"""The one lifecycle every ``manage_connections`` operation follows, whatever the target kind. ``run_operation`` mints the op, registers it in ``live``, lets the kind prepare its targets (a managed mint, an MCP catalog check), emits the card through the session callback, then loops: sleep on ``op.wake`` for at most one tick, run the kind's ``observe`` hook, settle when every target is resolved or the deadline passes. ``connection.respond`` reaches the loop by transitioning the op through ``live`` and setting ``wake``; ``/stop`` sets the thread interrupt flag.""" from __future__ import annotations import json import time from dataclasses import dataclass from typing import Any, Callable, Dict, List, Optional, Sequence from tools.connectors import live from tools.connectors.contract import SettleReason from tools.connectors.operation import ConnectionOperation, Target UNKNOWN_TARGET = "unknown_target" MIXED_KINDS = "mixed_kinds" LINK_STILL_VALID = "link_still_valid" SETTLED = "settled" NOT_ALLOWED = "not_allowed" REFUSED = "refused" WATCH_INTERVAL_SECONDS = 5.0 # The interrupt flag has no wake hook, so the tick sleep is sliced and the flag read each slice. _WAKE_SLICE_SECONDS = 0.25 Callback = Callable[[dict[str, Any]], Optional[str]] @dataclass class Kind: """Per-kind hooks. ``prepare`` runs once before the card; ``observe`` runs every tick and may transition targets; ``note`` is the model-facing guidance appended to the settled result.""" prepare: Callable[[ConnectionOperation], None] observe: Callable[[ConnectionOperation], None] note: str # Replaces the per-target result for an operation the model reads differently (the display card). result: Optional[Callable[[ConnectionOperation], dict[str, Any]]] = None def reissue(operation: ConnectionOperation, names: Sequence[str], *, initiator: Optional[str] = None) -> Optional[str]: from tools.connectors.contract import Actor, TargetState, allowed targets = [operation.target(name) for name in names] if any(target is None for target in targets): return UNKNOWN_TARGET if len({target.kind for target in targets}) != 1: return MIXED_KINDS stale = [target.name for target in targets if target.state in (TargetState.failed, TargetState.expired)] if len(stale) != len(targets): return LINK_STILL_VALID if operation.settled: return SETTLED if any(allowed(target.kind, target.state, TargetState.initiated) is None for target in targets): return NOT_ALLOWED if targets[0].kind == "connector": from tools.connectors.managed import CARD_RETRY, managed_client, mint client = managed_client(creates_guest=True, initiator=initiator or CARD_RETRY, call=operation.call) mint(client, operation, stale, reinitiate=True, actor=Actor.user) return None from tools.connectors import catalog from tools.connectors.mcp import retry rerun = catalog.retry if catalog.owns(operation.op_id) else retry return REFUSED if rerun(operation, stale) else None def apply_answer(operation: ConnectionOperation, raw: str) -> None: """Hand the card's answer to the module running this operation (a catalog install or an MCP one); a managed operation's card only skips and continues, which the MCP fold also covers.""" from tools.connectors import catalog, display, mcp if isinstance(operation, display.DisplayOperation): display.apply_answer(operation, raw) return (catalog.apply_answer if catalog.owns(operation.op_id) else mcp.apply_answer)(operation, raw) def respond(operation: ConnectionOperation, raw: str) -> bool: """The card's answer: apply it, settle once every target is resolved, close a settled operation. Returns whether it settled; raises ``IllegalTransition`` for an answer the operation refuses.""" apply_answer(operation, raw) if not operation.settled and operation.all_resolved: operation.settle(SettleReason.all_resolved) if operation.settled: live.close(operation) return operation.settled def run_operation( targets: list[Target], kind: Kind, *, session_key: str, tool_call_id: Optional[str], connection_callback: Optional[Callback], tick_seconds: Optional[float] = None, with_urls_in_result: bool, call: Optional[Any] = None, ) -> str: """Block the tool thread until the operation settles; return the tool's JSON string.""" return open_and_drive( ConnectionOperation(targets, session_key=session_key, tool_call_id=tool_call_id, call=call), kind, connection_callback=connection_callback, tick_seconds=tick_seconds, with_urls_in_result=with_urls_in_result, ) def open_and_drive( operation: ConnectionOperation, kind: Kind, *, connection_callback: Optional[Callback], tick_seconds: Optional[float] = None, with_urls_in_result: bool, ) -> str: """Register ``operation`` as the session's open one and drive it; one open per session.""" try: live.open(operation) except live.OperationAlreadyOpen as exc: from tools.registry import tool_error return tool_error( f"a connection operation is already open in this session ({exc.existing.op_id}); it settles " "when the user finishes with the card, on Continue, or at its deadline. Do not start another." ) return drive_operation( operation, kind, connection_callback=connection_callback, tick_seconds=tick_seconds, with_urls_in_result=with_urls_in_result, ) def drive_operation( operation: ConnectionOperation, kind: Kind, *, connection_callback: Optional[Callback], tick_seconds: Optional[float] = None, with_urls_in_result: bool, ) -> str: try: kind.prepare(operation) operation.settle_if_all_resolved() if connection_callback is not None and not operation.settled: connection_callback(operation.request_payload()) _watch(operation, kind, tick_seconds) finally: live.close(operation) if kind.result is not None: return json.dumps(kind.result(operation), ensure_ascii=False) payload = operation.result(with_urls=with_urls_in_result) payload["status"] = "settled" payload["note"] = kind.note return json.dumps(payload, ensure_ascii=False) def _watch(operation: ConnectionOperation, kind: Kind, tick_seconds: Optional[float]) -> None: from tools.interrupt import is_interrupted tick = WATCH_INTERVAL_SECONDS if tick_seconds is None else tick_seconds while not operation.settled: if is_interrupted(): operation.settle(SettleReason.interrupt) return if time.time() >= operation.deadline_at: operation.settle(SettleReason.deadline) return kind.observe(operation) # The card or the clock may have settled the op during the read; its result is frozen. if operation.settled or operation.settle_if_all_resolved(): return _sleep_until_wake(operation, tick) def _sleep_until_wake(operation: ConnectionOperation, tick: float) -> None: """Sleep up to one tick, leaving early on ``wake``, the deadline, or the interrupt flag.""" from tools.interrupt import is_interrupted until = min(time.time() + tick, operation.deadline_at) while not operation.settled and not is_interrupted(): remaining = until - time.time() if remaining <= 0: break if operation.wake.wait(min(_WAKE_SLICE_SECONDS, remaining)): break operation.wake.clear()