| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196 |
- """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()
|