operation.py 13 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290
  1. """One backend-owned connection operation per ``manage_connections`` call. Pure data; its only
  2. I/O is one local log line per state change and per settle."""
  3. from __future__ import annotations
  4. import logging
  5. import threading
  6. import time
  7. import uuid
  8. from dataclasses import dataclass, field
  9. from typing import Any, Callable, ClassVar, Dict, List, Optional
  10. from tools.connectors.contract import Actor, SettleReason, TargetState, allowed, resolves
  11. logger = logging.getLogger(__name__)
  12. # Not a config key: a user-tunable wait with clamp rails was a foot-gun (PR1 shipped one, unmerged).
  13. # As long as a connect link lives (10 minutes), so a slow authorization settles connected, not failed.
  14. OPERATION_DEADLINE_SECONDS = 600.0
  15. class IllegalTransition(ValueError):
  16. pass
  17. @dataclass
  18. class Target:
  19. name: str
  20. kind: str
  21. action: str
  22. state: TargetState = TargetState.pending
  23. detail: str = ""
  24. instructions: str = ""
  25. connect_url: Optional[str] = None
  26. # The vendor account a managed mint created or observed. Not the desktop transport's connection id.
  27. connection_id: Optional[str] = None
  28. # Opaque per-attempt handle when the gateway mints one (absent today; the status route adds it).
  29. attempt: Optional[str] = None
  30. # Earliest the watcher may read this target's account again; set from a 429's Retry-After so a
  31. # rate-limited route is not hammered once per second.
  32. next_read_at: float = 0.0
  33. # The credentials an MCP install still needs ({name, prompt, required}); the card draws a
  34. # field per entry and holds its verb until every required one has text.
  35. required_env: list[dict[str, Any]] = field(default_factory=list)
  36. # Fields a transition passes through to the model (``tools`` on a connected MCP target).
  37. extra: dict[str, Any] = field(default_factory=dict)
  38. # The install step an ``initiated`` catalog row is in (an ``InstallPhase`` id); drawn only then.
  39. phase: Optional[str] = None
  40. # The name of the one hosted account this target connects or repairs; absent for the connector's default account.
  41. alias: Optional[str] = None
  42. # The existing account a reconnect repairs, by id: an unnamed account, which no alias can address.
  43. repair_id: Optional[str] = None
  44. # What an MCP row will run or contact ({kind, target, env?, cwd?}), scrubbed; the card shows it before consent.
  45. launch: Optional[dict[str, Any]] = None
  46. @property
  47. def resolved(self) -> bool:
  48. return resolves(self.kind, self.state)
  49. def snapshot(self, *, with_url: bool = True) -> dict[str, Any]:
  50. out: dict[str, Any] = {"name": self.name, "kind": self.kind, "action": self.action, "state": self.state.value,
  51. "resolved": self.resolved}
  52. if self.alias:
  53. out["alias"] = self.alias
  54. if self.phase and self.state == TargetState.initiated:
  55. out["phase"] = self.phase
  56. if self.detail:
  57. out["detail"] = self.detail
  58. if self.instructions:
  59. out["instructions"] = self.instructions
  60. if with_url and self.connect_url:
  61. out["connect_url"] = self.connect_url
  62. if self.connection_id:
  63. out["connection_id"] = self.connection_id
  64. if self.attempt:
  65. out["attempt"] = self.attempt
  66. if self.required_env:
  67. out["required_env"] = self.required_env
  68. if self.launch:
  69. out["launch"] = self.launch
  70. out.update(self.extra)
  71. return out
  72. @dataclass
  73. class ConnectionOperation:
  74. # The gateway installs its ``connection.update`` emitter here once; pure data otherwise.
  75. on_change: ClassVar[
  76. Optional[Callable[[ConnectionOperation, Optional[dict[str, Any]], dict[str, Any]], None]]
  77. ] = None
  78. targets: list[Target]
  79. session_key: str = ""
  80. # Stamped by ``live.open``: the profile home the operation was opened under.
  81. profile_key: str = ""
  82. # The model's id for the call that opened the operation; the card binds to that tool row only.
  83. tool_call_id: Optional[str] = None
  84. # The opening call's ids (a ``CallRef``) for the requests a Try again makes; unset for account ops.
  85. call: Optional[Any] = None
  86. op_id: str = field(default_factory=lambda: uuid.uuid4().hex[:12])
  87. created_at: float = field(default_factory=time.time)
  88. deadline_at: float = 0.0
  89. settled_at: Optional[float] = None
  90. settled_by: Optional[SettleReason] = None
  91. # Monotonic write counter. Every frame carries the seq of the snapshot it was built from, so a
  92. # renderer that keeps the highest seq per op can drop a frame that arrives after a newer one.
  93. seq: int = 0
  94. # Set on every transition and on settle; the waiting loop sleeps on it.
  95. wake: threading.Event = field(default_factory=threading.Event, repr=False)
  96. _settled_snapshot: Optional[dict[str, Any]] = field(default=None, repr=False)
  97. _lock: threading.Lock = field(default_factory=threading.Lock, repr=False)
  98. def __post_init__(self) -> None:
  99. if not self.deadline_at:
  100. self.deadline_at = self.created_at + OPERATION_DEADLINE_SECONDS
  101. def target(self, name: str) -> Optional[Target]:
  102. return next((t for t in self.targets if t.name == name), None)
  103. def transition(
  104. self, name: str, to: TargetState, actor: Actor, *, detail: Optional[str] = None,
  105. connect_url: Optional[str] = None, connection_id: Optional[str] = None, attempt: Optional[str] = None,
  106. **extra: Any,
  107. ) -> Optional[dict[str, Any]]:
  108. """Move one target; the contract decides whether ``actor`` may. Returns the change, or None
  109. when the target is already in ``to``. Allowed after settlement: the frozen result stays."""
  110. target = self.target(name)
  111. if target is None:
  112. raise IllegalTransition(f"unknown target {name!r}")
  113. with self._lock:
  114. if target.state == to:
  115. return None
  116. if allowed(target.kind, target.state, to) != actor:
  117. raise IllegalTransition(f"{target.kind} {name}: {target.state.value} -> {to.value} by {actor.value}")
  118. change = {"target": name, "from": target.state.value, "to": to.value, "actor": actor.value}
  119. target.state = to
  120. if detail is not None:
  121. target.detail = detail
  122. change["detail"] = target.detail
  123. if connect_url is not None:
  124. target.connect_url = connect_url
  125. if connection_id is not None:
  126. target.connection_id = connection_id
  127. if attempt is not None:
  128. target.attempt = attempt
  129. if extra:
  130. target.extra = dict(extra)
  131. snapshot = self._bump_locked()
  132. logger.info("connection op %s: %s %s -> %s by %s", self.op_id, name, change["from"], to.value, actor.value)
  133. self.wake.set()
  134. self._changed(change, snapshot)
  135. return change
  136. def refresh(self, name: str, *, connect_url: Optional[str], detail: str, actor: Actor = Actor.user,
  137. phase: Optional[str] = None) -> None:
  138. """Replace a target's link, detail and install phase without a state change (a repeated
  139. failure, or the next step of an install).
  140. ``actor`` says who produced the new text: a second failure of a backend attempt is the
  141. backend's report, not the user's move, and the frame must not claim otherwise."""
  142. target = self.target(name)
  143. if target is None:
  144. raise IllegalTransition(f"unknown target {name!r}")
  145. with self._lock:
  146. target.connect_url = connect_url
  147. target.detail = detail
  148. target.phase = phase
  149. change = {"target": name, "from": target.state.value, "to": target.state.value, "actor": actor.value,
  150. "detail": detail}
  151. snapshot = self._bump_locked()
  152. self.wake.set()
  153. self._changed(change, snapshot)
  154. def _bump_locked(self) -> dict[str, Any]:
  155. """Advance the write counter and take the snapshot that frame carries. Both happen under
  156. ``_lock`` so a second writer cannot backdate this frame with its own state.
  157. After settlement the frozen snapshot is the frame, seq included: a later write changes
  158. nothing the renderer can see, so it must not leave the operation naming a seq no frame
  159. carried (the resume snapshot would wait for a frame that never comes)."""
  160. if self._settled_snapshot is None:
  161. self.seq += 1
  162. return self._result_locked()
  163. def _changed(self, change: Optional[dict[str, Any]], snapshot: dict[str, Any]) -> None:
  164. hook = type(self).on_change
  165. if hook is not None:
  166. hook(self, change, snapshot)
  167. @property
  168. def all_resolved(self) -> bool:
  169. return bool(self.targets) and all(t.resolved for t in self.targets)
  170. @property
  171. def settled(self) -> bool:
  172. return self.settled_at is not None
  173. def remaining_seconds(self, now: Optional[float] = None) -> float:
  174. return max(0.0, self.deadline_at - (time.time() if now is None else now))
  175. def settle(self, by: SettleReason, now: Optional[float] = None) -> bool:
  176. """Compare-and-set: the first caller freezes the result."""
  177. with self._lock:
  178. if self.settled_at is not None:
  179. return False
  180. self.settled_at = time.time() if now is None else now
  181. self.settled_by = by
  182. for target in self.targets:
  183. if not target.resolved:
  184. target.state = TargetState.not_connected
  185. self._settled_snapshot = self._bump_locked()
  186. outcomes = ", ".join(f"{t.name}={t.state.value}" for t in self.targets)
  187. logger.info("connection op %s settled by %s: %s", self.op_id, by.value, outcomes)
  188. self.wake.set()
  189. self._changed(None, self._settled_snapshot)
  190. return True
  191. def settle_if_all_resolved(self) -> bool:
  192. return self.all_resolved and self.settle(SettleReason.all_resolved)
  193. def _snapshot_locked(self, *, with_urls: bool = True) -> dict[str, Any]:
  194. return {
  195. "op_id": self.op_id,
  196. "seq": self.seq,
  197. "deadline_at": self.deadline_at,
  198. "settled_at": self.settled_at,
  199. "settled_by": self.settled_by.value if self.settled_by else None,
  200. "targets": [t.snapshot(with_url=with_urls) for t in self.targets],
  201. }
  202. def _result_locked(self, *, with_urls: bool = True) -> dict[str, Any]:
  203. if self._settled_snapshot is not None:
  204. targets = [dict(t) for t in self._settled_snapshot["targets"]]
  205. if not with_urls:
  206. for t in targets:
  207. t.pop("connect_url", None)
  208. return dict(self._settled_snapshot, targets=targets)
  209. return self._snapshot_locked(with_urls=with_urls)
  210. def snapshot(self, *, with_urls: bool = True) -> dict[str, Any]:
  211. with self._lock:
  212. return self._result_locked(with_urls=with_urls)
  213. def result(self, *, with_urls: bool = True) -> dict[str, Any]:
  214. with self._lock:
  215. result = self._result_locked(with_urls=with_urls)
  216. for target in result["targets"]:
  217. target.pop("connection_id", None)
  218. target.pop("resolved", None) # the card's flag; the model reads state
  219. target.pop("launch", None) # the card's consent line; the model named the server itself
  220. if result.get("settled_at") is None:
  221. return result
  222. from tools.registry import registry
  223. from tools.tool_search_catalog import build_catalog_listing_with_form
  224. for target in result["targets"]:
  225. # Setup instructions are the card's text for the user. A catalog entry's notes can be
  226. # older than this flow ("restart your session to load the tools"), and the model would
  227. # repeat them after a result that says the tools are callable now.
  228. target.pop("instructions", None)
  229. names = target.get("tools") if target.get("kind") == "mcp" else None
  230. if not names:
  231. continue
  232. definitions = registry.get_definitions(set(names), quiet=True)
  233. listing, _form = build_catalog_listing_with_form(definitions, max_tokens=1500)
  234. if listing:
  235. target["tools_listing"] = listing
  236. return result
  237. def request_payload(self) -> dict[str, Any]:
  238. """The ``connection.request`` payload and the resume snapshot: identity, live target snapshots
  239. (links included, the panel owns them), server-owned deadline."""
  240. with self._lock:
  241. targets = [t.snapshot() for t in self.targets]
  242. seq = self.seq
  243. payload: dict[str, Any] = {
  244. "op_id": self.op_id,
  245. "seq": seq,
  246. "deadline_at": self.deadline_at,
  247. "timeout_seconds": OPERATION_DEADLINE_SECONDS,
  248. "targets": targets,
  249. }
  250. if self.tool_call_id:
  251. payload["tool_call_id"] = self.tool_call_id
  252. return payload
  253. class DetachedOperation(ConnectionOperation):
  254. on_change = None