delegate_tool_registry.py 15 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310
  1. """Live-subagent registry + model-facing control plane (list/steer/stop) for delegate_task."""
  2. from __future__ import annotations
  3. import logging
  4. import json
  5. import threading
  6. import time
  7. from typing import Any, Dict, List, Optional
  8. from agent.interrupt_compat import request_hard_interrupt
  9. from tools.registry import tool_error
  10. logger = logging.getLogger("tools.delegate_tool") # log-record parity with the origin module
  11. _spawn_pause_lock = threading.Lock()
  12. _spawn_paused: bool = False
  13. _active_subagents_lock = threading.Lock()
  14. # subagent_id -> mutable record tracking the live child agent. Stays only
  15. # for the lifetime of the run; _run_single_child is the owner.
  16. _active_subagents: dict[str, dict[str, Any]] = {}
  17. # subagent_id -> {goal, delegation_id, owner_agent_session_id} retained AFTER the child finishes (bounded FIFO).
  18. # Child-started background processes routinely outlive the child (its npm ci with notify_on_complete=true finishes
  19. # after the summary was delivered); their completion notifications reach the parent via the shared completion_queue
  20. # and need delegation attribution even though the live registry entry is gone.
  21. _RECENT_SUBAGENTS_CAP = 200
  22. _recent_subagents: dict[str, dict[str, Any]] = {}
  23. def get_subagent_attribution(task_id: Optional[str]) -> Optional[dict[str, Any]]:
  24. """``{subagent_id, goal, delegation_id}`` for a process task_id that belongs to a live or recently-finished child
  25. (children run their terminal sessions under ``task_id == subagent_id``), else None."""
  26. if not task_id or not isinstance(task_id, str):
  27. return None
  28. with _active_subagents_lock:
  29. record = _active_subagents.get(task_id) or _recent_subagents.get(task_id)
  30. if record is None:
  31. return None
  32. return {"subagent_id": task_id, "goal": record.get("goal"), "delegation_id": record.get("delegation_id")}
  33. def set_spawn_paused(paused: bool) -> bool:
  34. """Globally block/unblock NEW delegate_task spawns (active children keep running). Returns the new state."""
  35. global _spawn_paused
  36. with _spawn_pause_lock:
  37. _spawn_paused = bool(paused)
  38. return _spawn_paused
  39. def is_spawn_paused() -> bool:
  40. with _spawn_pause_lock:
  41. return _spawn_paused
  42. def _register_subagent(record: dict[str, Any]) -> None:
  43. sid = record.get("subagent_id")
  44. if not sid:
  45. return
  46. record.setdefault("accepting_steer", True)
  47. with _active_subagents_lock:
  48. _active_subagents[sid] = record
  49. def _unregister_subagent(subagent_id: str, *, agent: Any = None) -> None:
  50. """Drop the live record (exact agent identity when given) and keep a bounded attribution stub."""
  51. with _active_subagents_lock:
  52. record = _active_subagents.get(subagent_id)
  53. if record is None or not (agent is None or record.get("agent") is agent):
  54. return
  55. _active_subagents.pop(subagent_id, None)
  56. sid = record.get("subagent_id")
  57. if not sid:
  58. return
  59. _recent_subagents[sid] = {k: record.get(k) for k in ("goal", "delegation_id", "owner_agent_session_id")}
  60. while len(_recent_subagents) > _RECENT_SUBAGENTS_CAP:
  61. _recent_subagents.pop(next(iter(_recent_subagents)), None)
  62. def _close_subagent_steering(subagent_id: str, agent: Any) -> Optional[str]:
  63. """Atomically close steer acceptance and drain its final durable artifact. ``steer_subagent`` holds the same
  64. registry lock through ``agent.steer``, so either acceptance wins and this drain sees its exact text, or closure
  65. wins and the caller is rejected. Exact agent identity prevents a finishing child with a recycled public id from
  66. closing its replacement."""
  67. with _active_subagents_lock:
  68. record = _active_subagents.get(subagent_id)
  69. if record is None or record.get("agent") is not agent:
  70. return None
  71. record["accepting_steer"] = False
  72. drain = getattr(agent, "_drain_pending_steer", None)
  73. if not callable(drain):
  74. return None
  75. try:
  76. pending = drain()
  77. except Exception as exc:
  78. logger.debug("final steer drain for %s failed: %s", subagent_id, exc)
  79. return None
  80. return pending if isinstance(pending, str) and pending.strip() else None
  81. def interrupt_subagent(subagent_id: str) -> bool:
  82. """Request that one running subagent stop at its next iteration boundary
  83. (cooperative: the flag propagates to in-flight tools and recurses into
  84. grandchildren via AIAgent.interrupt()). True iff a matching subagent was found."""
  85. with _active_subagents_lock:
  86. record = _active_subagents.get(subagent_id)
  87. agent = record.get("agent") if record else None
  88. if agent is None:
  89. return False
  90. try:
  91. return bool(request_hard_interrupt(agent, f"Interrupted via TUI ({subagent_id})"))
  92. except Exception as exc:
  93. logger.debug("interrupt_subagent(%s) failed: %s", subagent_id, exc)
  94. return False
  95. def _subagent_transport_matches(record, transport) -> bool:
  96. """Authority follows the owning session's LIVE transport slot, read at check time.
  97. ``owner_transport`` on the record is only the capture-time marker that a gateway session
  98. commissioned the child (``None`` = no RPC authority ever). The slot is authoritative because
  99. every reattach path (prompt.submit, queued drain, resume, activate, viewer failover) already
  100. mutates it; a per-record copy needed a matching registry sync at each of those sites and two
  101. were missed (#106663). Records whose owner is not a session dict keep the exact-object rule."""
  102. from tui_gateway.transport import FanoutTransport
  103. if record.get("owner_transport") is None:
  104. return False
  105. owner = record.get("owner_session_record")
  106. bound = owner.get("transport") if isinstance(owner, dict) else record.get("owner_transport")
  107. return bound is transport or (isinstance(bound, FanoutTransport) and bound.contains(transport))
  108. def steer_subagent(
  109. subagent_id: str, text: str, *, owner_session_id: Optional[str] = None, owner_transport: Any = None,
  110. owner_session_record: Any = None,
  111. ) -> bool:
  112. """Queue steering text into a running subagent without stopping it.
  113. AIAgent.steer() appends the text to the child's last tool result at its next iteration boundary — the current tool
  114. call is never cut. True iff the text was QUEUED while the child still accepted work; False for unknown/closed id,
  115. ownership mismatch, no live agent, or empty text. ``owner_session_id=None`` keeps the in-process helper contract;
  116. gateway callers must pass exact authority. Acceptance and completion are linearized by the registry lock: if
  117. acceptance wins but no delivery boundary remains, the text lands in the entry as ``missed_steer``.
  118. """
  119. if not text or not text.strip():
  120. return False
  121. with _active_subagents_lock:
  122. record = _active_subagents.get(subagent_id)
  123. if not record or not record.get("accepting_steer", False):
  124. return False
  125. if owner_session_id is not None and (
  126. record.get("owner_session_id") != owner_session_id
  127. or owner_transport is None
  128. or not _subagent_transport_matches(record, owner_transport)
  129. or owner_session_record is None
  130. or record.get("owner_session_record") is not owner_session_record
  131. ):
  132. return False
  133. agent = record.get("agent")
  134. if agent is None:
  135. return False
  136. try:
  137. return bool(agent.steer(text))
  138. except Exception as exc:
  139. logger.debug("steer_subagent(%s) failed: %s", subagent_id, exc)
  140. return False
  141. def _capture_gateway_steer_authority(owner_session_id: Optional[str]) -> tuple[Any, Any]:
  142. """Exact request transport + live session generation, if any — an in-process
  143. bridge, not a serializable capability. Non-gateway hosts get ``(None, None)``."""
  144. if not owner_session_id:
  145. return None, None
  146. try:
  147. from tui_gateway.server import _current_session_steer_authority
  148. return _current_session_steer_authority(owner_session_id)
  149. except Exception:
  150. return None, None
  151. # Registry record fields never exposed to the TUI/RPC snapshot.
  152. _PRIVATE_RECORD_KEYS = frozenset({"agent", "owner_session_id", "owner_transport", "owner_session_record", "accepting_steer"})
  153. def list_active_subagents() -> list[dict[str, Any]]:
  154. """Copy of the running subagent tree ({subagent_id, parent_id, depth, goal, model,
  155. started_at, tool_count, status, ...}); safe from any thread."""
  156. with _active_subagents_lock:
  157. return [{k: v for k, v in r.items() if k not in _PRIVATE_RECORD_KEYS} for r in _active_subagents.values()]
  158. def _is_descendant_of(child_agent: Any, parent_agent: Any, max_hops: int = 8) -> bool:
  159. """True when *child_agent* sits below *parent_agent* in the spawn tree (walks the ``_delegate_parent_ref`` weakref
  160. chain stamped at build time). Identity only — a parent may steer/stop its own children and grandchildren, never
  161. a sibling tree owned by another conversation."""
  162. if child_agent is None or parent_agent is None:
  163. return False
  164. cur = child_agent
  165. for _ in range(max_hops):
  166. ref = getattr(cur, "_delegate_parent_ref", None)
  167. ancestor = ref() if callable(ref) else None
  168. if ancestor is None:
  169. return False
  170. if ancestor is parent_agent:
  171. return True
  172. cur = ancestor
  173. return False
  174. # Model-facing control actions accepted by delegate_task(action=...).
  175. # "spawn" (or omitted) keeps the historical spawn semantics.
  176. _CONTROL_ACTIONS = frozenset({"list", "steer", "stop"})
  177. def _resolve_session_lineage(session_id: Optional[str], parent_agent: Any) -> str:
  178. """Tip of a session id's compression lineage via the parent's live SessionDB (best-effort; input unchanged when
  179. unavailable) so a delegation dispatched before a compression rotation still matches the rotated parent."""
  180. sid = str(session_id or "")
  181. db = getattr(parent_agent, "_session_db", None)
  182. if not sid or db is None:
  183. return sid
  184. try:
  185. resolved = db.resolve_resume_session_id(sid)
  186. return str(resolved) if resolved else sid
  187. except Exception:
  188. return sid
  189. def _owns_subagent_record(record: dict[str, Any], parent_agent: Any) -> bool:
  190. """True when *parent_agent*'s conversation owns this live-child record.
  191. Tier 1: identity — the ``_delegate_parent_ref`` weakref chain reaches
  192. *parent_agent* (fast path while the parent AIAgent survives the run). Tier 2:
  193. durable lineage — the record's ``owner_agent_session_id`` matches the caller's
  194. ``session_id`` after resolving compression-rotation lineage on both sides.
  195. Tier 2 exists because the identity chain is BRITTLE across parent rebuilds:
  196. the CLI sets ``self.agent = None`` mid-session (route change, credential
  197. refresh, /model, MoA one-shots) and builds a NEW AIAgent while the child keeps
  198. a weakref to the old one. Delivery routes by durable session id; control must
  199. use the same spine or running children go invisible/unsteerable.
  200. """
  201. if _is_descendant_of(record.get("agent"), parent_agent):
  202. return True
  203. owner_sid = str(record.get("owner_agent_session_id") or "")
  204. parent_sid = str(getattr(parent_agent, "session_id", "") or "")
  205. if not owner_sid or not parent_sid:
  206. return False
  207. if owner_sid == parent_sid:
  208. return True
  209. # Compression rotation on either side: compare lineage tips.
  210. return _resolve_session_lineage(owner_sid, parent_agent) in {parent_sid, _resolve_session_lineage(parent_sid, parent_agent)}
  211. def _list_payload(parent_agent: Any) -> dict[str, Any]:
  212. with _active_subagents_lock:
  213. records = list(_active_subagents.values())
  214. entries = []
  215. for r in records:
  216. if not _owns_subagent_record(r, parent_agent):
  217. continue
  218. started = r.get("started_at")
  219. entries.append({
  220. "subagent_id": r.get("subagent_id"),
  221. "parent_id": r.get("parent_id"),
  222. "goal": r.get("goal"),
  223. "model": r.get("model"),
  224. "status": r.get("status"),
  225. "running_seconds": round(time.time() - started, 1) if isinstance(started, (int, float)) else None,
  226. "accepting_steer": bool(r.get("accepting_steer", False)),
  227. "live_transcript": getattr(r.get("agent"), "_live_transcript_path", None),
  228. })
  229. payload: dict[str, Any] = {"action": "list", "count": len(entries), "subagents": entries}
  230. if not entries:
  231. payload["note"] = (
  232. "No live subagents right now. Children that already finished "
  233. "have delivered (or will deliver) their results as normal "
  234. "completion messages — there is nothing to steer or stop."
  235. )
  236. return payload
  237. def _handle_control_action(action: str, subagent_id: Optional[str], message: Optional[str], parent_agent: Any) -> str:
  238. """Synchronous control plane for delegate_task: list/steer/stop. Runs in-turn (never backgrounded) over the same
  239. registry the TUI overlay drives, scoped so a conversation can only control its own spawn tree."""
  240. if action == "list":
  241. return json.dumps(_list_payload(parent_agent), ensure_ascii=False)
  242. # steer / stop need a resolvable, owned target.
  243. sid = (subagent_id or "").strip()
  244. if not sid:
  245. return tool_error(f"action='{action}' requires subagent_id (from the spawn dispatch response or action='list').")
  246. with _active_subagents_lock:
  247. record = _active_subagents.get(sid)
  248. if record is None or not _owns_subagent_record(record, parent_agent):
  249. return tool_error(
  250. f"No live subagent '{sid}' in this conversation's spawn tree. It "
  251. "may have already finished (its result arrives as a normal "
  252. "completion message). Use action='list' to see live children."
  253. )
  254. if action == "steer" and not (message or "").strip():
  255. return tool_error("action='steer' requires a non-empty 'message' describing the course correction.")
  256. outcome = _CONTROL_OUTCOMES.get(action)
  257. if outcome is None:
  258. return tool_error(f"Unknown action '{action}'. Use spawn, list, steer, or stop.")
  259. status, note, failure = outcome
  260. ok = interrupt_subagent(sid) if action == "stop" else steer_subagent(sid, message.strip())
  261. if ok:
  262. return json.dumps({"action": action, "subagent_id": sid, "status": status, "note": note}, ensure_ascii=False)
  263. return tool_error(failure.format(sid=sid))
  264. # action -> (success status, success note, failure error template)
  265. _CONTROL_OUTCOMES = {
  266. "stop": (
  267. "interrupt_requested",
  268. "The subagent stops at its next iteration boundary (in-flight tool calls are asked to cancel). Its "
  269. "partial result still re-enters the conversation as a completion message — do not wait or poll.",
  270. "Could not interrupt '{sid}' — it likely finished in the last "
  271. "moment. Its result arrives as a normal completion message.",
  272. ),
  273. "steer": (
  274. "queued",
  275. "Steering text queued. The subagent sees it appended to its next tool result — the current tool call is "
  276. "never cut. If the child finishes before a delivery boundary remains, the text is reported back as "
  277. "missed_steer in its completion entry.", "Subagent '{sid}' is no longer accepting steering (finishing or "
  278. "already finished). Its result arrives as a normal completion "
  279. "message; re-delegate a follow-up task if more work is needed.",
  280. ),
  281. }