| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290 |
- """One backend-owned connection operation per ``manage_connections`` call. Pure data; its only
- I/O is one local log line per state change and per settle."""
- from __future__ import annotations
- import logging
- import threading
- import time
- import uuid
- from dataclasses import dataclass, field
- from typing import Any, Callable, ClassVar, Dict, List, Optional
- from tools.connectors.contract import Actor, SettleReason, TargetState, allowed, resolves
- logger = logging.getLogger(__name__)
- # Not a config key: a user-tunable wait with clamp rails was a foot-gun (PR1 shipped one, unmerged).
- # As long as a connect link lives (10 minutes), so a slow authorization settles connected, not failed.
- OPERATION_DEADLINE_SECONDS = 600.0
- class IllegalTransition(ValueError):
- pass
- @dataclass
- class Target:
- name: str
- kind: str
- action: str
- state: TargetState = TargetState.pending
- detail: str = ""
- instructions: str = ""
- connect_url: Optional[str] = None
- # The vendor account a managed mint created or observed. Not the desktop transport's connection id.
- connection_id: Optional[str] = None
- # Opaque per-attempt handle when the gateway mints one (absent today; the status route adds it).
- attempt: Optional[str] = None
- # Earliest the watcher may read this target's account again; set from a 429's Retry-After so a
- # rate-limited route is not hammered once per second.
- next_read_at: float = 0.0
- # The credentials an MCP install still needs ({name, prompt, required}); the card draws a
- # field per entry and holds its verb until every required one has text.
- required_env: list[dict[str, Any]] = field(default_factory=list)
- # Fields a transition passes through to the model (``tools`` on a connected MCP target).
- extra: dict[str, Any] = field(default_factory=dict)
- # The install step an ``initiated`` catalog row is in (an ``InstallPhase`` id); drawn only then.
- phase: Optional[str] = None
- # The name of the one hosted account this target connects or repairs; absent for the connector's default account.
- alias: Optional[str] = None
- # The existing account a reconnect repairs, by id: an unnamed account, which no alias can address.
- repair_id: Optional[str] = None
- # What an MCP row will run or contact ({kind, target, env?, cwd?}), scrubbed; the card shows it before consent.
- launch: Optional[dict[str, Any]] = None
- @property
- def resolved(self) -> bool:
- return resolves(self.kind, self.state)
- def snapshot(self, *, with_url: bool = True) -> dict[str, Any]:
- out: dict[str, Any] = {"name": self.name, "kind": self.kind, "action": self.action, "state": self.state.value,
- "resolved": self.resolved}
- if self.alias:
- out["alias"] = self.alias
- if self.phase and self.state == TargetState.initiated:
- out["phase"] = self.phase
- if self.detail:
- out["detail"] = self.detail
- if self.instructions:
- out["instructions"] = self.instructions
- if with_url and self.connect_url:
- out["connect_url"] = self.connect_url
- if self.connection_id:
- out["connection_id"] = self.connection_id
- if self.attempt:
- out["attempt"] = self.attempt
- if self.required_env:
- out["required_env"] = self.required_env
- if self.launch:
- out["launch"] = self.launch
- out.update(self.extra)
- return out
- @dataclass
- class ConnectionOperation:
- # The gateway installs its ``connection.update`` emitter here once; pure data otherwise.
- on_change: ClassVar[
- Optional[Callable[[ConnectionOperation, Optional[dict[str, Any]], dict[str, Any]], None]]
- ] = None
- targets: list[Target]
- session_key: str = ""
- # Stamped by ``live.open``: the profile home the operation was opened under.
- profile_key: str = ""
- # The model's id for the call that opened the operation; the card binds to that tool row only.
- tool_call_id: Optional[str] = None
- # The opening call's ids (a ``CallRef``) for the requests a Try again makes; unset for account ops.
- call: Optional[Any] = None
- op_id: str = field(default_factory=lambda: uuid.uuid4().hex[:12])
- created_at: float = field(default_factory=time.time)
- deadline_at: float = 0.0
- settled_at: Optional[float] = None
- settled_by: Optional[SettleReason] = None
- # Monotonic write counter. Every frame carries the seq of the snapshot it was built from, so a
- # renderer that keeps the highest seq per op can drop a frame that arrives after a newer one.
- seq: int = 0
- # Set on every transition and on settle; the waiting loop sleeps on it.
- wake: threading.Event = field(default_factory=threading.Event, repr=False)
- _settled_snapshot: Optional[dict[str, Any]] = field(default=None, repr=False)
- _lock: threading.Lock = field(default_factory=threading.Lock, repr=False)
- def __post_init__(self) -> None:
- if not self.deadline_at:
- self.deadline_at = self.created_at + OPERATION_DEADLINE_SECONDS
- def target(self, name: str) -> Optional[Target]:
- return next((t for t in self.targets if t.name == name), None)
- def transition(
- self, name: str, to: TargetState, actor: Actor, *, detail: Optional[str] = None,
- connect_url: Optional[str] = None, connection_id: Optional[str] = None, attempt: Optional[str] = None,
- **extra: Any,
- ) -> Optional[dict[str, Any]]:
- """Move one target; the contract decides whether ``actor`` may. Returns the change, or None
- when the target is already in ``to``. Allowed after settlement: the frozen result stays."""
- target = self.target(name)
- if target is None:
- raise IllegalTransition(f"unknown target {name!r}")
- with self._lock:
- if target.state == to:
- return None
- if allowed(target.kind, target.state, to) != actor:
- raise IllegalTransition(f"{target.kind} {name}: {target.state.value} -> {to.value} by {actor.value}")
- change = {"target": name, "from": target.state.value, "to": to.value, "actor": actor.value}
- target.state = to
- if detail is not None:
- target.detail = detail
- change["detail"] = target.detail
- if connect_url is not None:
- target.connect_url = connect_url
- if connection_id is not None:
- target.connection_id = connection_id
- if attempt is not None:
- target.attempt = attempt
- if extra:
- target.extra = dict(extra)
- snapshot = self._bump_locked()
- logger.info("connection op %s: %s %s -> %s by %s", self.op_id, name, change["from"], to.value, actor.value)
- self.wake.set()
- self._changed(change, snapshot)
- return change
- def refresh(self, name: str, *, connect_url: Optional[str], detail: str, actor: Actor = Actor.user,
- phase: Optional[str] = None) -> None:
- """Replace a target's link, detail and install phase without a state change (a repeated
- failure, or the next step of an install).
- ``actor`` says who produced the new text: a second failure of a backend attempt is the
- backend's report, not the user's move, and the frame must not claim otherwise."""
- target = self.target(name)
- if target is None:
- raise IllegalTransition(f"unknown target {name!r}")
- with self._lock:
- target.connect_url = connect_url
- target.detail = detail
- target.phase = phase
- change = {"target": name, "from": target.state.value, "to": target.state.value, "actor": actor.value,
- "detail": detail}
- snapshot = self._bump_locked()
- self.wake.set()
- self._changed(change, snapshot)
- def _bump_locked(self) -> dict[str, Any]:
- """Advance the write counter and take the snapshot that frame carries. Both happen under
- ``_lock`` so a second writer cannot backdate this frame with its own state.
- After settlement the frozen snapshot is the frame, seq included: a later write changes
- nothing the renderer can see, so it must not leave the operation naming a seq no frame
- carried (the resume snapshot would wait for a frame that never comes)."""
- if self._settled_snapshot is None:
- self.seq += 1
- return self._result_locked()
- def _changed(self, change: Optional[dict[str, Any]], snapshot: dict[str, Any]) -> None:
- hook = type(self).on_change
- if hook is not None:
- hook(self, change, snapshot)
- @property
- def all_resolved(self) -> bool:
- return bool(self.targets) and all(t.resolved for t in self.targets)
- @property
- def settled(self) -> bool:
- return self.settled_at is not None
- def remaining_seconds(self, now: Optional[float] = None) -> float:
- return max(0.0, self.deadline_at - (time.time() if now is None else now))
- def settle(self, by: SettleReason, now: Optional[float] = None) -> bool:
- """Compare-and-set: the first caller freezes the result."""
- with self._lock:
- if self.settled_at is not None:
- return False
- self.settled_at = time.time() if now is None else now
- self.settled_by = by
- for target in self.targets:
- if not target.resolved:
- target.state = TargetState.not_connected
- self._settled_snapshot = self._bump_locked()
- outcomes = ", ".join(f"{t.name}={t.state.value}" for t in self.targets)
- logger.info("connection op %s settled by %s: %s", self.op_id, by.value, outcomes)
- self.wake.set()
- self._changed(None, self._settled_snapshot)
- return True
- def settle_if_all_resolved(self) -> bool:
- return self.all_resolved and self.settle(SettleReason.all_resolved)
- def _snapshot_locked(self, *, with_urls: bool = True) -> dict[str, Any]:
- return {
- "op_id": self.op_id,
- "seq": self.seq,
- "deadline_at": self.deadline_at,
- "settled_at": self.settled_at,
- "settled_by": self.settled_by.value if self.settled_by else None,
- "targets": [t.snapshot(with_url=with_urls) for t in self.targets],
- }
- def _result_locked(self, *, with_urls: bool = True) -> dict[str, Any]:
- if self._settled_snapshot is not None:
- targets = [dict(t) for t in self._settled_snapshot["targets"]]
- if not with_urls:
- for t in targets:
- t.pop("connect_url", None)
- return dict(self._settled_snapshot, targets=targets)
- return self._snapshot_locked(with_urls=with_urls)
- def snapshot(self, *, with_urls: bool = True) -> dict[str, Any]:
- with self._lock:
- return self._result_locked(with_urls=with_urls)
- def result(self, *, with_urls: bool = True) -> dict[str, Any]:
- with self._lock:
- result = self._result_locked(with_urls=with_urls)
- for target in result["targets"]:
- target.pop("connection_id", None)
- target.pop("resolved", None) # the card's flag; the model reads state
- target.pop("launch", None) # the card's consent line; the model named the server itself
- if result.get("settled_at") is None:
- return result
- from tools.registry import registry
- from tools.tool_search_catalog import build_catalog_listing_with_form
- for target in result["targets"]:
- # Setup instructions are the card's text for the user. A catalog entry's notes can be
- # older than this flow ("restart your session to load the tools"), and the model would
- # repeat them after a result that says the tools are callable now.
- target.pop("instructions", None)
- names = target.get("tools") if target.get("kind") == "mcp" else None
- if not names:
- continue
- definitions = registry.get_definitions(set(names), quiet=True)
- listing, _form = build_catalog_listing_with_form(definitions, max_tokens=1500)
- if listing:
- target["tools_listing"] = listing
- return result
- def request_payload(self) -> dict[str, Any]:
- """The ``connection.request`` payload and the resume snapshot: identity, live target snapshots
- (links included, the panel owns them), server-owned deadline."""
- with self._lock:
- targets = [t.snapshot() for t in self.targets]
- seq = self.seq
- payload: dict[str, Any] = {
- "op_id": self.op_id,
- "seq": seq,
- "deadline_at": self.deadline_at,
- "timeout_seconds": OPERATION_DEADLINE_SECONDS,
- "targets": targets,
- }
- if self.tool_call_id:
- payload["tool_call_id"] = self.tool_call_id
- return payload
- class DetachedOperation(ConnectionOperation):
- on_change = None
|