subagent_lifecycle.py 21 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472
  1. """Public, plugin-safe lifecycle API for delegated Hermes subagents: immutable contracts, not ``AIAgent``
  2. objects. Plugins obtain it via ``PluginContext.subagent_lifecycle``."""
  3. from __future__ import annotations
  4. import contextvars
  5. import dataclasses
  6. import enum
  7. import hashlib
  8. import hmac
  9. import json
  10. import math
  11. import secrets
  12. import threading
  13. import time
  14. import contextlib
  15. import weakref
  16. from contextlib import contextmanager
  17. from concurrent.futures import Future, TimeoutError
  18. from typing import Any, Callable, Mapping, Optional
  19. from agent.interrupt_compat import request_hard_interrupt
  20. PUBLIC_CONTRACT_VERSION = 1
  21. _MAX_GOAL_CHARS = 16_000
  22. _MAX_CONTEXT_CHARS = 32_000
  23. _MAX_METADATA_BYTES = 8_192
  24. _MAX_RESULT_CHARS = 32_000
  25. _TERMINAL_RETENTION_SECONDS = 3_600
  26. class SubagentLifecycleError(ValueError):
  27. """A request cannot be safely accepted by the public lifecycle API."""
  28. class SubagentState(str, enum.Enum):
  29. PENDING = "PENDING"
  30. STARTING = "STARTING"
  31. RUNNING = "RUNNING"
  32. SUCCEEDED = "SUCCEEDED"
  33. FAILED = "FAILED"
  34. INTERRUPTED = "INTERRUPTED"
  35. CANCEL_REQUESTED = "CANCEL_REQUESTED"
  36. CANCELLED = "CANCELLED"
  37. UNKNOWN = "UNKNOWN"
  38. @dataclasses.dataclass(frozen=True)
  39. class SubagentLaunchRequest:
  40. goal: str
  41. context: Optional[str] = None
  42. role: str = "leaf"
  43. model: Optional[str] = None
  44. provider: Optional[str] = None
  45. allowed_toolsets: Optional[tuple[str, ...]] = None
  46. blocked_tools: tuple[str, ...] = ()
  47. working_directory: Optional[str] = None
  48. parent_session_id: Optional[str] = None
  49. correlation_id: Optional[str] = None
  50. metadata: Mapping[str, Any] = dataclasses.field(default_factory=dict)
  51. timeout_seconds: Optional[float] = None
  52. @dataclasses.dataclass(frozen=True)
  53. class SubagentHandle:
  54. contract_version: int
  55. subagent_id: str
  56. parent_session_id: Optional[str]
  57. correlation_id: Optional[str]
  58. created_at: float
  59. provider: Optional[str]
  60. model: Optional[str]
  61. role: str
  62. depth: int
  63. capability: str
  64. def to_dict(self) -> dict[str, Any]:
  65. return dataclasses.asdict(self)
  66. @classmethod
  67. def from_dict(cls, value: Mapping[str, Any]) -> SubagentHandle:
  68. try:
  69. return cls(**dict(value))
  70. except (TypeError, ValueError) as exc:
  71. raise SubagentLifecycleError("Malformed subagent handle.") from exc
  72. @dataclasses.dataclass(frozen=True)
  73. class SubagentStatus:
  74. handle: SubagentHandle
  75. state: SubagentState
  76. updated_at: float
  77. diagnostic: Optional[str] = None
  78. @dataclasses.dataclass(frozen=True)
  79. class SubagentTerminalState:
  80. handle: SubagentHandle
  81. state: SubagentState
  82. completed: bool
  83. timed_out: bool = False
  84. diagnostic: Optional[str] = None
  85. @dataclasses.dataclass(frozen=True)
  86. class SubagentCancelResult:
  87. accepted: bool
  88. already_terminal: bool = False
  89. unknown_handle: bool = False
  90. unsupported: bool = False
  91. state: SubagentState = SubagentState.UNKNOWN
  92. @dataclasses.dataclass(frozen=True)
  93. class SubagentResult:
  94. handle: SubagentHandle
  95. terminal_state: SubagentState
  96. ready: bool
  97. summary: Optional[str] = None
  98. structured_payload: Optional[Mapping[str, Any]] = None
  99. started_at: Optional[float] = None
  100. completed_at: Optional[float] = None
  101. error_classification: Optional[str] = None
  102. error_message: Optional[str] = None
  103. usage_metadata: Mapping[str, Any] = dataclasses.field(default_factory=dict)
  104. tool_execution_summary: Mapping[str, Any] = dataclasses.field(default_factory=dict)
  105. result_hash: Optional[str] = None
  106. @dataclasses.dataclass(frozen=True)
  107. class SubagentReconnectResult:
  108. connected: bool
  109. state: SubagentState
  110. diagnostic: Optional[str] = None
  111. @dataclasses.dataclass
  112. class _Record:
  113. handle: SubagentHandle
  114. state: SubagentState
  115. updated_at: float
  116. agent: Any = None
  117. future: Optional[Future] = None
  118. started_at: Optional[float] = None
  119. completed_at: Optional[float] = None
  120. result: Optional[SubagentResult] = None
  121. @dataclasses.dataclass
  122. class _Registry:
  123. """Thread-safe terminal-retention registry; never returns live records."""
  124. lock: threading.RLock = dataclasses.field(default_factory=threading.RLock)
  125. records: dict[str, _Record] = dataclasses.field(default_factory=dict)
  126. correlations: dict[tuple[Optional[str], str], str] = dataclasses.field(default_factory=dict)
  127. _REGISTRY = _Registry()
  128. from tools.daemon_pool import DaemonThreadPoolExecutor as _DaemonExecutor # daemon: a wedged child never blocks exit
  129. _EXECUTOR = _DaemonExecutor(max_workers=8, thread_name_prefix="hermes-lifecycle")
  130. _SECRET = secrets.token_bytes(32)
  131. _ACTIVE_PARENT_AGENT: contextvars.ContextVar[Any] = contextvars.ContextVar("hermes_subagent_lifecycle_parent", default=None)
  132. @contextmanager
  133. def bind_subagent_parent(parent_agent: Any):
  134. """Bind the host-owned parent for the current agent turn.
  135. Stored as a weakref: every asyncio Handle/Future scheduled from the turn
  136. (LSP reader loops, kernel pipes, ...) snapshots the Context, and those
  137. snapshots outlive the turn. A strong ref there pinned finished delegate
  138. children — each of which binds itself here for its own turn — in the
  139. parent process heap for the life of the background loop.
  140. """
  141. try:
  142. ref = weakref.ref(parent_agent)
  143. except TypeError:
  144. ref = lambda: parent_agent
  145. token = _ACTIVE_PARENT_AGENT.set(ref)
  146. try:
  147. yield
  148. finally:
  149. _ACTIVE_PARENT_AGENT.reset(token)
  150. def get_active_subagent_parent() -> Any:
  151. """Return the parent bound to this execution context, if any."""
  152. ref = _ACTIVE_PARENT_AGENT.get()
  153. return ref() if ref is not None else None
  154. def _opt_str(value: Any) -> bool:
  155. return value is None or isinstance(value, str)
  156. def _session_id_of(agent: Any) -> Optional[str]:
  157. return str(getattr(agent, "session_id", "") or "") or None
  158. def _clip(value: Any) -> Optional[str]:
  159. return str(value)[:_MAX_RESULT_CHARS] if value is not None else None
  160. # Per-field shape check applied to a (possibly deserialized) handle before trusting it.
  161. _HANDLE_FIELD_CHECKS: tuple[tuple[str, Callable[[Any], bool]], ...] = (
  162. ("contract_version", lambda v: type(v) is int and v == PUBLIC_CONTRACT_VERSION),
  163. ("subagent_id", lambda v: isinstance(v, str) and bool(v)),
  164. ("parent_session_id", _opt_str),
  165. ("correlation_id", _opt_str),
  166. ("created_at", lambda v: not isinstance(v, bool) and isinstance(v, (int, float)) and math.isfinite(v)),
  167. ("provider", _opt_str),
  168. ("model", _opt_str),
  169. ("role", lambda v: isinstance(v, str)),
  170. ("depth", lambda v: type(v) is int),
  171. ("capability", lambda v: isinstance(v, str)),
  172. )
  173. # Launch-request rejections in check order: (predicate, error). The type check leads so later predicates may
  174. # dereference request fields.
  175. _REQUEST_REJECTIONS: tuple[tuple[Callable[[Any], bool], str], ...] = (
  176. (lambda r: not isinstance(r, SubagentLaunchRequest) or not isinstance(r.goal, str) or not r.goal.strip() or len(r.goal) > _MAX_GOAL_CHARS,
  177. "goal must be a non-empty string of at most 16000 characters."),
  178. (lambda r: r.context is not None and (not isinstance(r.context, str) or len(r.context) > _MAX_CONTEXT_CHARS),
  179. "context must be a string of at most 32000 characters."),
  180. (lambda r: r.role not in {"leaf", "orchestrator"}, "role must be 'leaf' or 'orchestrator'."),
  181. (lambda r: r.provider is not None and (not isinstance(r.provider, str) or not r.provider.strip() or len(r.provider) > 64),
  182. "provider must be a non-empty string of at most 64 characters."),
  183. (lambda r: r.timeout_seconds is not None, "Per-launch timeout is not supported; configure delegation timeout explicitly."),
  184. (lambda r: r.working_directory is not None,
  185. "working_directory is not supported because Hermes delegates use isolated task environments."),
  186. (lambda r: bool(r.blocked_tools),
  187. "Per-tool blocking is not supported; use allowed_toolsets. Hermes always blocks unsafe child tools."),
  188. )
  189. def _handle_is_well_formed(handle: Any) -> bool:
  190. return isinstance(handle, SubagentHandle) and all(check(getattr(handle, field)) for field, check in _HANDLE_FIELD_CHECKS)
  191. def _coerce_request(request: Any) -> SubagentLaunchRequest:
  192. if isinstance(request, SubagentLaunchRequest):
  193. return request
  194. if not isinstance(request, Mapping):
  195. raise SubagentLifecycleError("request must be a SubagentLaunchRequest or a mapping of its fields.")
  196. values = dict(request)
  197. unknown = set(values) - {field.name for field in dataclasses.fields(SubagentLaunchRequest)}
  198. if unknown:
  199. raise SubagentLifecycleError(f"Unknown request fields: {', '.join(sorted(map(str, unknown)))}.")
  200. for name in ("allowed_toolsets", "blocked_tools"):
  201. if isinstance(values.get(name), list):
  202. values[name] = tuple(values[name])
  203. try:
  204. return SubagentLaunchRequest(**values)
  205. except TypeError as exc:
  206. raise SubagentLifecycleError(f"Malformed subagent launch request: {exc}") from exc
  207. def _coerce_handle(handle: Any) -> Optional[SubagentHandle]:
  208. if isinstance(handle, SubagentHandle):
  209. return handle
  210. if isinstance(handle, Mapping):
  211. try:
  212. return SubagentHandle.from_dict(handle)
  213. except SubagentLifecycleError:
  214. return None
  215. return None
  216. class SubagentLifecycleService:
  217. """Stable public service behind :attr:`PluginContext.subagent_lifecycle`. Children run in-process only;
  218. completed results stay until process exit; ``reconnect`` reports that a serialized handle cannot
  219. reconnect after a restart instead of launching work again."""
  220. def __init__(self, parent_agent_resolver: Callable[[], Any]) -> None:
  221. self._parent_agent_resolver = parent_agent_resolver
  222. def launch(self, request: SubagentLaunchRequest | Mapping[str, Any]) -> SubagentHandle:
  223. parent = self._parent_agent_resolver()
  224. if parent is None:
  225. raise SubagentLifecycleError("No active Hermes parent session is available.")
  226. request = _coerce_request(request)
  227. self._validate_request(request, parent)
  228. parent_session_id = _session_id_of(parent)
  229. if request.parent_session_id and request.parent_session_id != parent_session_id:
  230. raise SubagentLifecycleError("parent_session_id does not match the active session.")
  231. correlation_key = (parent_session_id, request.correlation_id or "")
  232. with _REGISTRY.lock:
  233. self._cleanup_locked()
  234. if request.correlation_id and correlation_key in _REGISTRY.correlations:
  235. raise SubagentLifecycleError("Duplicate correlation_id for this parent session.")
  236. # Lazy: delegate construction stays internal, plugins never import private delegation helpers.
  237. from tools.delegate_tool import (
  238. _build_child_preserving_parent_tools, _credential_overrides, _load_config, _resolve_delegation_credentials,
  239. DEFAULT_MAX_ITERATIONS,
  240. )
  241. # Routing precedence: request.provider > delegation config > parent.
  242. routing_cfg = {"provider": request.provider, "model": request.model or ""} if request.provider is not None else _load_config()
  243. try:
  244. creds = _resolve_delegation_credentials(routing_cfg, parent)
  245. except ValueError as exc:
  246. raise SubagentLifecycleError(str(exc)) from exc
  247. child = _build_child_preserving_parent_tools(
  248. task_index=0, goal=request.goal, context=request.context,
  249. toolsets=list(request.allowed_toolsets) if request.allowed_toolsets else None,
  250. model=request.model or creds["model"], max_iterations=DEFAULT_MAX_ITERATIONS,
  251. task_count=1, parent_agent=parent, role=request.role, **_credential_overrides(creds, routing_cfg),
  252. )
  253. subagent_id = str(getattr(child, "_subagent_id", "") or "")
  254. if not subagent_id:
  255. raise SubagentLifecycleError("Hermes failed to assign a child identity.")
  256. created = time.time()
  257. handle = SubagentHandle(
  258. PUBLIC_CONTRACT_VERSION, subagent_id, parent_session_id, request.correlation_id, created,
  259. getattr(child, "provider", None), getattr(child, "model", None), getattr(child, "_delegate_role", request.role),
  260. int(getattr(child, "_delegate_depth", 1) or 1), self._capability(subagent_id, parent_session_id, created),
  261. )
  262. record = _Record(handle, SubagentState.PENDING, created, agent=child)
  263. with _REGISTRY.lock:
  264. _REGISTRY.records[subagent_id] = record
  265. if request.correlation_id:
  266. _REGISTRY.correlations[correlation_key] = subagent_id
  267. record.future = _EXECUTOR.submit(self._run, record, request.goal, parent)
  268. return handle
  269. def status(self, handle: SubagentHandle | Mapping[str, Any]) -> SubagentStatus:
  270. record = self._record(handle)
  271. if record is None:
  272. return SubagentStatus(handle, SubagentState.UNKNOWN, time.time(), "UNKNOWN_HANDLE")
  273. with _REGISTRY.lock:
  274. return SubagentStatus(record.handle, record.state, record.updated_at)
  275. def wait(self, handle: SubagentHandle | Mapping[str, Any], *, timeout_seconds: Optional[float] = None) -> SubagentTerminalState:
  276. record = self._record(handle)
  277. if record is None:
  278. return SubagentTerminalState(handle, SubagentState.UNKNOWN, True, diagnostic="UNKNOWN_HANDLE")
  279. try:
  280. if record.future is not None:
  281. record.future.result(timeout=timeout_seconds)
  282. except TimeoutError:
  283. return SubagentTerminalState(record.handle, record.state, False, True)
  284. except Exception:
  285. pass
  286. with _REGISTRY.lock:
  287. return SubagentTerminalState(record.handle, record.state, record.result is not None)
  288. def cancel(self, handle: SubagentHandle | Mapping[str, Any], *, reason: str) -> SubagentCancelResult:
  289. record = self._record(handle)
  290. if record is None:
  291. return SubagentCancelResult(False, unknown_handle=True)
  292. with _REGISTRY.lock:
  293. if record.result is not None:
  294. return SubagentCancelResult(False, already_terminal=True, state=record.state)
  295. agent = record.agent
  296. record.state = SubagentState.CANCEL_REQUESTED
  297. record.updated_at = time.time()
  298. accepted = False
  299. if agent is not None:
  300. with contextlib.suppress(Exception):
  301. accepted = request_hard_interrupt(
  302. agent, f"Lifecycle cancellation requested: {reason[:500]}", tool_reason="subagent cancellation requested",
  303. )
  304. return SubagentCancelResult(bool(accepted), unsupported=not accepted, state=SubagentState.CANCEL_REQUESTED)
  305. def result(self, handle: SubagentHandle | Mapping[str, Any]) -> SubagentResult:
  306. record = self._record(handle)
  307. if record is None:
  308. return SubagentResult(handle, SubagentState.UNKNOWN, False, error_classification="UNKNOWN_HANDLE")
  309. with _REGISTRY.lock:
  310. return record.result or SubagentResult(record.handle, record.state, False, error_classification="NOT_READY")
  311. def reconnect(self, handle: SubagentHandle | Mapping[str, Any]) -> SubagentReconnectResult:
  312. record = self._record(handle)
  313. if record is None:
  314. return SubagentReconnectResult(False, SubagentState.UNKNOWN, "RECONNECT_UNAVAILABLE")
  315. with _REGISTRY.lock:
  316. return SubagentReconnectResult(True, record.state)
  317. def steer(self, handle: SubagentHandle | Mapping[str, Any], text: str) -> bool:
  318. """Queue text for the child's next iteration boundary while it accepts steering."""
  319. record = self._record(handle)
  320. if record is None or not isinstance(text, str) or not text.strip():
  321. return False
  322. with _REGISTRY.lock:
  323. if record.result is not None:
  324. return False
  325. from tools.delegate_tool_registry import steer_subagent
  326. return steer_subagent(record.handle.subagent_id, text.strip())
  327. def _record(self, handle: SubagentHandle | Mapping[str, Any]) -> Optional[_Record]:
  328. """Registry record for a well-formed, capability-verified handle owned by the active parent."""
  329. handle = _coerce_handle(handle)
  330. if not _handle_is_well_formed(handle):
  331. return None
  332. expected = self._capability(handle.subagent_id, handle.parent_session_id, handle.created_at)
  333. if not hmac.compare_digest(handle.capability, expected):
  334. return None
  335. if _session_id_of(self._parent_agent_resolver()) != handle.parent_session_id:
  336. return None
  337. with _REGISTRY.lock:
  338. return _REGISTRY.records.get(handle.subagent_id)
  339. @staticmethod
  340. def _cleanup_locked() -> None:
  341. """Retain terminal snapshots for a bounded period, never live work."""
  342. cutoff = time.time() - _TERMINAL_RETENTION_SECONDS
  343. expired = [
  344. sid for sid, record in _REGISTRY.records.items()
  345. if record.result is not None and record.completed_at is not None and record.completed_at < cutoff
  346. ]
  347. for subagent_id in expired:
  348. handle = _REGISTRY.records.pop(subagent_id).handle
  349. if handle.correlation_id:
  350. _REGISTRY.correlations.pop((handle.parent_session_id, handle.correlation_id), None)
  351. def _run(self, record: _Record, goal: str, parent: Any) -> None:
  352. with _REGISTRY.lock:
  353. if record.state is not SubagentState.CANCEL_REQUESTED:
  354. record.state = SubagentState.RUNNING
  355. record.started_at = record.updated_at = time.time()
  356. try:
  357. from tools.delegate_tool import _run_child_lifecycle
  358. raw = _run_child_lifecycle(0, goal, record.agent, parent)
  359. is_dict = isinstance(raw, dict)
  360. raw = raw if is_dict else {}
  361. status = str(raw.get("status", "error"))
  362. if status == "interrupted":
  363. state = SubagentState.CANCELLED if record.state == SubagentState.CANCEL_REQUESTED else SubagentState.INTERRUPTED
  364. else:
  365. state = SubagentState.SUCCEEDED if status == "completed" else SubagentState.FAILED
  366. fields: dict[str, Any] = dict(
  367. summary=_clip(raw.get("summary")), error_message=_clip(raw.get("error") or None),
  368. error_classification=None if state == SubagentState.SUCCEEDED else status.upper(),
  369. usage_metadata={"api_calls": raw.get("api_calls", 0)} if is_dict else {},
  370. tool_execution_summary={"duration_seconds": raw.get("duration_seconds", 0)} if is_dict else {},
  371. )
  372. except Exception as exc:
  373. state = SubagentState.FAILED
  374. fields = dict(error_classification=type(exc).__name__, error_message=_clip(exc))
  375. result = SubagentResult(record.handle, state, True, started_at=record.started_at, completed_at=time.time(), **fields)
  376. payload = dataclasses.asdict(result)
  377. payload.pop("result_hash", None)
  378. result = dataclasses.replace(result, result_hash=hashlib.sha256(json.dumps(payload, sort_keys=True, default=str).encode()).hexdigest())
  379. with _REGISTRY.lock:
  380. record.agent, record.result, record.state = None, result, result.terminal_state
  381. record.completed_at = record.updated_at = result.completed_at
  382. @staticmethod
  383. def _capability(subagent_id: str, parent_session_id: Optional[str], created_at: float) -> str:
  384. value = f"{subagent_id}|{parent_session_id or ''}|{created_at:.6f}".encode()
  385. return hmac.new(_SECRET, value, hashlib.sha256).hexdigest()
  386. @staticmethod
  387. def _validate_request(request: SubagentLaunchRequest, parent: Any) -> None:
  388. for rejected, message in _REQUEST_REJECTIONS:
  389. if rejected(request):
  390. raise SubagentLifecycleError(message)
  391. try:
  392. metadata_bytes = len(json.dumps(dict(request.metadata), sort_keys=True).encode())
  393. except (TypeError, ValueError) as exc:
  394. raise SubagentLifecycleError("metadata must be JSON-serializable.") from exc
  395. if metadata_bytes > _MAX_METADATA_BYTES:
  396. raise SubagentLifecycleError("metadata exceeds 8192 bytes.")
  397. if not request.allowed_toolsets:
  398. return
  399. # Plugin and registry-alias toolsets count as known, as they do for delegate_task.
  400. from toolsets import validate_toolset
  401. unknown = {name for name in request.allowed_toolsets if not validate_toolset(name)}
  402. if unknown:
  403. raise SubagentLifecycleError(f"Unknown toolsets: {', '.join(sorted(unknown))}.")
  404. enabled = getattr(parent, "enabled_toolsets", None)
  405. if enabled is not None and not set(request.allowed_toolsets).issubset(set(enabled)):
  406. raise SubagentLifecycleError("Requested toolsets would broaden parent permissions.")