process_registry_notifications.py 25 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507
  1. """Human-readable rendering of ``ProcessRegistry.completion_queue`` events (completion,
  2. watch_match, watch_disabled, watch_overflow_*, async_delegation) into the
  3. ``[IMPORTANT: ...]`` / ``[ASYNC DELEGATION ...]`` text the CLI drain loop, gateway and
  4. TUI inject into the agent conversation."""
  5. import time
  6. from dataclasses import dataclass
  7. from contextlib import suppress
  8. _DONE = ("completed", "success")
  9. _REASON_STATUS = {"lost": "marked lost because the process backend disappeared", "failed_start": "failed to start"}
  10. @dataclass(frozen=True, slots=True)
  11. class ProcessNotificationBatch:
  12. """Keep completion identity until the owning surface starts its turn."""
  13. notifications: tuple[tuple[dict, str], ...]
  14. def _live(self, registry) -> list:
  15. return [(event, text) for event, text in self.notifications
  16. if not registry.is_completion_consumed(event.get("session_id", ""))]
  17. def render(self, registry) -> str | None:
  18. messages = [text for _event, text in self._live(registry)]
  19. if not messages:
  20. return None
  21. if len(messages) == 1:
  22. return messages[0]
  23. header = (f"[IMPORTANT: {len(messages)} background processes completed. "
  24. "Treat these results as one batch and give one consolidated response; "
  25. "preserve failures and actionable results.]")
  26. return "\n\n".join((header, *messages))
  27. def display_text(self, registry) -> str:
  28. return process_completion_display_text([event for event, _text in self._live(registry)])
  29. def group_process_notifications(notifications):
  30. """Group consecutive completions only; watches and delegations are barriers."""
  31. batch = []
  32. for event, text in notifications:
  33. if event.get("type", "completion") == "completion":
  34. batch.append((event, text))
  35. else:
  36. if batch:
  37. yield tuple(batch)
  38. batch = []
  39. yield ((event, text),)
  40. if batch:
  41. yield tuple(batch)
  42. def is_child_process_notification(evt: dict) -> bool:
  43. """Raw child process noise, not a delegation or work-closeout deliverable."""
  44. if evt.get("type") in {"async_delegation", "async_delegation_work_closeout"}:
  45. return False
  46. return str(evt.get("owner_task_id") or evt.get("task_id") or "").startswith("sa-")
  47. def should_surface_notification(evt: dict, *, surface_child: bool | None = None) -> bool:
  48. """Shared policy; callers must first enter the event's owning profile scope."""
  49. if not is_child_process_notification(evt):
  50. return True
  51. if surface_child is None:
  52. from tools.process_registry import ProcessRegistry
  53. surface_child = ProcessRegistry._surface_child_process_notifications()
  54. return surface_child
  55. def _format_age(seconds: float) -> str:
  56. """Human-friendly elapsed string ('18m', '2h3m', '45s')."""
  57. try:
  58. s = int(max(0, seconds))
  59. except (TypeError, ValueError):
  60. return "?"
  61. if s < 60:
  62. return f"{s}s"
  63. m, s = divmod(s, 60)
  64. if m < 60:
  65. return f"{m}m" + (f"{s}s" if s else "")
  66. h, m = divmod(m, 60)
  67. return f"{h}h" + (f"{m}m" if m else "")
  68. def _model_not_found_patterns() -> list[str]:
  69. """Model-not-found phrases from ``agent.error_classifier`` (the failover path's
  70. own list, so nothing drifts); a minimal built-in set if the import fails.
  71. Imported from ``agent.error_classifier`` so the batch renderer applies the SAME classification the
  72. failover path consumes — no hand-copied pattern list to drift. Fails open to a minimal built-in set so a
  73. classifier import problem never hides the per-task blocks. See #97667.
  74. """
  75. try:
  76. from agent.error_classifier import _MODEL_NOT_FOUND_PATTERNS
  77. return list(_MODEL_NOT_FOUND_PATTERNS)
  78. except Exception:
  79. return ["is not a valid model", "model not found", "model_not_found"]
  80. def _delegation_config() -> dict:
  81. """Active delegation config; ``{}`` on any error. Lazy: delegate_tool is heavy."""
  82. try:
  83. from tools.delegate_tool import _load_config as _cfg
  84. return _cfg() or {}
  85. except Exception:
  86. return {}
  87. def _delegation_model_not_found(results, config) -> bool:
  88. """True when a result reflects a config-level model_not_found rejection: needs a
  89. model-not-found phrase AND the currently-configured model name in the same text,
  90. so a stale task failing on a removed model is not mis-attributed to the config."""
  91. model = str((config or {}).get("model") or "").lower()
  92. if not model:
  93. return False
  94. patterns = _model_not_found_patterns()
  95. texts = (" ".join(str(x) for x in (r.get("error"), r.get("summary")) if x).lower() for r in results or [])
  96. return any(model in text and any(p in text for p in patterns) for text in texts)
  97. def _delegation_model_not_found_notice(results) -> list[str] | None:
  98. """Config-level model_not_found notice lines, or None (fail-open) — once per batch."""
  99. config = _delegation_config()
  100. if not _delegation_model_not_found(results, config):
  101. return None
  102. model = config.get("model") or "?"
  103. provider = config.get("provider") or "configured provider"
  104. lines = [
  105. "⚠ SUBAGENT MODEL REJECTED: the configured Subagent Model "
  106. f'"{model}" was rejected by provider "{provider}" '
  107. "(HTTP 400: not a valid model ID).",
  108. "Every task in this batch failed for this reason before doing any work.",
  109. "Check Settings → Advanced → Subagent Model (or: hermes config get delegation.model)."]
  110. with suppress(Exception):
  111. from hermes_cli.fallback_config import get_fallback_chain
  112. if not get_fallback_chain(config):
  113. lines.append("No fallback chain is configured, so no failover was attempted.")
  114. return lines
  115. _TRUNCATED_SUMMARY_NOTE = (
  116. "[TRUNCATED — subagent hit its iteration cap; the summary below "
  117. "may be incomplete. Verify before relying on it, or re-dispatch "
  118. "the unfinished part.]")
  119. def _is_truncated(entry: dict) -> bool:
  120. return bool(entry.get("truncated") or entry.get("exit_reason") == "max_iterations")
  121. def _notice_lines(results) -> list[str]:
  122. """Blank + model_not_found notice block, or [] when the notice does not apply."""
  123. notice = _delegation_model_not_found_notice(results)
  124. return ["", *notice] if notice else []
  125. def _preamble(evt: dict, title: str, intro: str, completed_at: float, *, with_goal: bool) -> list[str]:
  126. """Shared preamble: title, intro, blank, dispatch time, [goal], context/toolsets, role+model."""
  127. lines = [title, intro, ""]
  128. dispatched_at = evt.get("dispatched_at")
  129. if isinstance(dispatched_at, (int, float)):
  130. ts = time.strftime("%Y-%m-%d %H:%M:%S", time.localtime(dispatched_at))
  131. lines.append(f"Dispatched: {ts} ({_format_age(completed_at - dispatched_at)} ago)")
  132. if with_goal:
  133. lines.append(f"Original goal: {evt.get('goal', '') or ''}")
  134. if evt.get("context"):
  135. lines.append(f"Context you provided: {evt['context']}")
  136. if evt.get("toolsets"):
  137. lines.append(f"Toolsets: {', '.join(evt['toolsets'])}")
  138. lines.append(f"Role: {evt.get('role') or 'leaf'}" + (f" Model: {evt['model']}" if evt.get("model") else ""))
  139. return lines
  140. def _format_task_failure_notice(evt: dict, deleg_id: str) -> str:
  141. """One child of a still-running fan-out failed: say which, why, and that the batch goes on."""
  142. (r,) = (evt.get("results") or [{}])[:1] or [{}]
  143. goals, idx, n = evt.get("goals") or [], r.get("task_index", 0), evt.get("n_tasks") or len(evt.get("goals") or [])
  144. goal = goals[idx] if idx < len(goals) else r.get("goal", "")
  145. err = str(r.get("error") or "").strip().replace("\n", " ")[:400]
  146. lines = [
  147. f"[ASYNC DELEGATION TASK FAILED — {deleg_id}, task {idx + 1}/{n}]",
  148. "One subagent in a background fan-out you dispatched has failed while its siblings are still running. "
  149. "The batch's consolidated results will still arrive when the last sibling finishes; this is an early "
  150. "warning so you can re-dispatch or investigate now instead of then.",
  151. f"Task: {goal}" if goal else "",
  152. f"Status: {r.get('status', '?')} Duration: {r.get('duration_seconds', '?')}s" + (f"\nError: {err}" if err else ""),
  153. ]
  154. if r.get("live_transcript"):
  155. lines.append(f"Live transcript: {r['live_transcript']}")
  156. return "\n".join(line for line in lines if line)
  157. def _recovery_lines(evt: dict) -> list[str]:
  158. """Owner-died recovery diagnostics (``recover_abandoned_delegations``): last persisted
  159. status, per-task transcript paths, their verbatim tails and the owner's git state."""
  160. if not evt.get("last_known_status"):
  161. return []
  162. lines = [f"Last persisted unit status: {evt['last_known_status']} (before owner exit; not current liveness). "
  163. "Unrecorded outcomes remain unknown; inspect evidence before retrying side effects."]
  164. tails = evt.get("transcript_tails") or {}
  165. for index, path in (evt.get("task_transcripts") or {}).items():
  166. lines.append(f"Task index {index} transcript (may be incomplete): {path}")
  167. if tails.get(index):
  168. lines += [f"--- last lines of task {index} transcript ---", tails[index], "--- end ---"]
  169. if evt.get("git_state_hint"):
  170. lines.append(f"Owner working tree at recovery: {evt['git_state_hint']}")
  171. return lines
  172. def _format_batch_delegation(evt: dict, deleg_id: str, completed_at: float) -> str:
  173. """Consolidated block for a delegate_task fan-out that finished as one unit."""
  174. results, goals = evt.get("results") or [], evt.get("goals") or []
  175. # ``goals`` is the whole delegate_task call (task_index indexes it); ``results`` is this unit's subset.
  176. n, n_unit = len(goals) or len(results), len(results) or len(goals)
  177. group = evt.get("group")
  178. unit = f"group '{group}' ({n_unit} subagent(s))" if group is not None else f"{n_unit} subagent(s)"
  179. lines = _preamble(
  180. evt,
  181. f"[ASYNC DELEGATION BATCH COMPLETE — {deleg_id}]",
  182. f"A background fan-out unit you dispatched earlier — {unit} — has finished; its consolidated results are "
  183. "below. Any other units from the same delegate_task call report separately as they finish. You may have "
  184. "moved on since dispatching — act on these or re-dispatch if things have changed. If you are still waiting "
  185. "on siblings, end your turn after acting on this one.",
  186. completed_at, with_goal=False)
  187. lines[-1] += f" Total duration: {evt.get('total_duration_seconds', evt.get('duration_seconds', '?'))}s"
  188. lines += _recovery_lines(evt)
  189. if evt.get("error") and not results:
  190. lines += ["--- ERROR ---", f"The batch did not complete successfully: {evt['error']}"]
  191. return "\n".join(lines)
  192. # Config-level rejection notice BEFORE the per-task wall — a rejected
  193. # delegation model fails every task identically and must not stay buried.
  194. lines += _notice_lines(results)
  195. for r in sorted(results, key=lambda x: x.get("task_index", 0)):
  196. idx, r_truncated = r.get("task_index", 0), _is_truncated(r)
  197. r_status, r_summary, r_error = r.get("status", "?"), r.get("summary"), r.get("error")
  198. r_goal = goals[idx] if idx < len(goals) else r.get("goal", "")
  199. icon = "⚠" if r_truncated else ("✓" if r_status in _DONE else "✗")
  200. header = (f"--- {icon} TASK {idx + 1}/{n}" + (f": {r_goal}" if r_goal else "") + f" (status={r_status}"
  201. + (f", api_calls={r['api_calls']}" if r.get("api_calls") else "")
  202. + (f", {r['duration_seconds']}s" if r.get("duration_seconds") is not None else "")
  203. + (", TRUNCATED: hit max_iterations — work may be incomplete" if r_truncated else ""))
  204. lines += ["", header + ") ---"]
  205. if r_status in _DONE and r_summary:
  206. if r_truncated:
  207. lines.append(_TRUNCATED_SUMMARY_NOTE)
  208. lines.append(r_summary)
  209. elif r_summary:
  210. if r_error:
  211. lines.append(f"({r_status}: {r_error})")
  212. lines += ["Partial output:", r_summary]
  213. else:
  214. lines.append(f"(no summary — status={r_status}" + (f": {r_error}" if r_error else "") + ")")
  215. if r.get("live_transcript"):
  216. lines.append(f"Full live transcript (complete tool/assistant trace): {r['live_transcript']}")
  217. lines += _process_accounting_lines(r)
  218. return "\n".join(lines)
  219. def _process_accounting_lines(r: dict) -> list:
  220. """Runtime-truth lines about a child's background processes: what it handed to you (you own it now, its
  221. completion lands here) and what it left running (terminated at teardown — never trust a child's "watcher running")."""
  222. lines = []
  223. for h in r.get("handed_off_processes") or []:
  224. lines.append(f"Handed off to you: {h.get('session_id')} ({h.get('command', '')[:120]}) — {h.get('note', '')}. "
  225. "You own it now; its completion notice will arrive here.")
  226. orphans = r.get("orphaned_processes") or []
  227. if orphans:
  228. lines.append(f"Child left {len(orphans)} background process(es) running that were TERMINATED with it "
  229. "(subagent process notices never reach you): "
  230. + "; ".join(f"{o.get('session_id')} `{o.get('command', '')[:100]}` ({o.get('runtime_seconds')}s)" for o in orphans)
  231. + ". Re-launch in this session anything you still need.")
  232. for u in r.get("unread_completions") or []:
  233. lines.append(f"Child's process {u.get('session_id')} `{u.get('command', '')[:100]}` finished (exit code "
  234. f"{u.get('exit_code')}) but the child never read its result; output tail:\n{u.get('output_tail', '')}")
  235. return lines
  236. def _format_async_delegation(evt: dict) -> str:
  237. """Self-contained re-injection for an async-delegation completion: the FULL
  238. original task source (goal, context, toolsets, role, model), dispatch time, status
  239. and result, so an agent deep in unrelated context can act on it or re-dispatch."""
  240. deleg_id = evt.get("delegation_id", "unknown")
  241. completed_at = evt.get("completed_at") or time.time()
  242. if evt.get("task_failure_notice"):
  243. return _format_task_failure_notice(evt, deleg_id)
  244. if evt.get("is_batch") or isinstance(evt.get("results"), list):
  245. return _format_batch_delegation(evt, deleg_id, completed_at)
  246. status, summary, error = evt.get("status") or "completed", evt.get("summary"), evt.get("error")
  247. truncated = _is_truncated(evt)
  248. lines = _preamble(
  249. evt,
  250. f"[ASYNC DELEGATION COMPLETE — {deleg_id}]",
  251. "A background subagent you dispatched earlier has finished. You may "
  252. "have moved on since dispatching it; the full task source is below so "
  253. "you can act on the result or re-dispatch if things have changed.",
  254. completed_at, with_goal=True)
  255. lines += _notice_lines([evt]) + [
  256. f"Status: {status}" + (f" API calls: {evt['api_calls']}" if evt.get("api_calls") is not None else "")
  257. + f" Duration: {evt.get('duration_seconds', '?')}s"
  258. + (" [TRUNCATED: hit max_iterations — work may be incomplete]" if truncated else ""),
  259. "--- RESULT ---"]
  260. if status in _DONE and summary:
  261. if truncated:
  262. lines.append(_TRUNCATED_SUMMARY_NOTE)
  263. lines.append(summary)
  264. else:
  265. if status == "interrupted":
  266. lines.append("The subagent was interrupted before completing" + (f": {error}" if error else "."))
  267. else: # error / timeout / failed / unknown (owner died)
  268. lines.append(
  269. f"The subagent did not complete successfully (status={status})." + (f"\n{error}" if error else ""))
  270. lines += _recovery_lines(evt)
  271. if summary:
  272. lines += ["Partial output:", summary]
  273. return "\n".join(lines)
  274. def async_delegation_display_text(evt: dict) -> str:
  275. """Compact UI title; the separate model notification retains all task evidence."""
  276. raw_results = evt.get("results")
  277. results = [r for r in raw_results if isinstance(r, dict)] if isinstance(raw_results, list) else []
  278. results = results or [evt]
  279. goals = evt.get("goals") or []
  280. labels, titles = [], []
  281. status_labels = {"failed": "Failed", "error": "Failed", "cancelled": "Cancelled",
  282. "interrupted": "Interrupted", "timeout": "Timed Out", "stalled": "Stalled",
  283. "unknown": "Unknown", "rejected": "Failed"}
  284. for result in results:
  285. status = result.get("status") or ("failed" if result.get("error") else "completed")
  286. label = ("Incomplete" if _is_truncated(result) else "Completed") if status in _DONE else (
  287. status_labels.get(status, "Incomplete"))
  288. labels.append(label)
  289. index = result.get("task_index", 0)
  290. goal = goals[index] if 0 <= index < len(goals) else result.get("goal", "")
  291. titles.append(" ".join(str(goal or "Background task").split()))
  292. if len(results) == 1:
  293. return f"Subagent Task {labels[0]}: {_short_title(titles[0])}"
  294. outcome = labels[0] if len(set(labels)) == 1 else "Finished with Issues"
  295. title = " ".join(str(evt.get("group") or "").split()) or "; ".join(titles)
  296. return f"Subagent Tasks {outcome}: {_short_title(title)} ({len(results)} tasks)"
  297. def _short_title(title: str) -> str:
  298. # A goal is free text: the card's title stays one line (and within an admission's display limit).
  299. return title[:197] + "..." if len(title) > 200 else title
  300. PROCESS_COMPLETE_DISPLAY_KIND = "process_complete"
  301. def _short_command(command) -> str:
  302. cmd = " ".join(str(command or "").split())
  303. return cmd[:77] + "..." if len(cmd) > 80 else cmd
  304. def process_completion_display_text(events: list) -> str:
  305. """Compact UI title for one or more process completions; the model text keeps the full output."""
  306. if len(events) != 1:
  307. return f"{len(events)} Background Processes Finished"
  308. evt = events[0]
  309. reason, exit_code = evt.get("completion_reason") or "exited", evt.get("exit_code", "?")
  310. if reason == "killed":
  311. outcome = "Terminated"
  312. elif reason in _REASON_STATUS:
  313. outcome = "Lost" if reason == "lost" else "Failed to Start"
  314. else:
  315. outcome = "Finished" if exit_code == 0 else "Failed"
  316. cmd = _short_command(evt.get("command"))
  317. detail = f" (exit {exit_code})" if reason not in ("killed", *_REASON_STATUS) and exit_code != 0 else ""
  318. return f"Background Process {outcome}{detail}: {cmd}" if cmd else f"Background Process {outcome}{detail}"
  319. HEARTBEAT_DISPLAY_KIND = "hidden" # a wake, not a message: no surface paints the row
  320. HEARTBEAT_OUTPUT_CHARS = 2000
  321. def heartbeat_output_tail(output: str, omitted: int = 0) -> tuple[str, int]:
  322. """A tick's output capped to its newest characters (a long job's latest lines are what matter),
  323. and the count of characters cut before it. ``omitted`` counts characters already cut before
  324. ``output``. The count rides the tick as its own field (``omitted``): text a job printed is never
  325. read back as a cut marker."""
  326. if len(output) > HEARTBEAT_OUTPUT_CHARS:
  327. omitted += len(output) - HEARTBEAT_OUTPUT_CHARS
  328. output = output[-HEARTBEAT_OUTPUT_CHARS:]
  329. return output, omitted
  330. def join_heartbeat_outputs(earlier: dict, later: dict) -> dict:
  331. """Two consecutive ticks' ``output``/``omitted`` as one tick's, capped the same way, counting
  332. every character either cut. A later tick that was itself cut leaves none of the earlier output."""
  333. earlier_cut, earlier_text = int(earlier.get("omitted") or 0), str(earlier.get("output") or "")
  334. later_cut, later_text = int(later.get("omitted") or 0), str(later.get("output") or "")
  335. if later_cut:
  336. output, omitted = heartbeat_output_tail(later_text, earlier_cut + len(earlier_text) + later_cut)
  337. else:
  338. output, omitted = heartbeat_output_tail(earlier_text + later_text, earlier_cut)
  339. return {"output": output, "omitted": omitted}
  340. def heartbeat_output_text(evt: dict) -> str:
  341. """A tick's output as the agent reads it: the cut marker, rendered here only, then the tail."""
  342. omitted, output = int(evt.get("omitted") or 0), str(evt.get("output") or "")
  343. return f"...({omitted} earlier characters omitted)\n{output}" if omitted else output
  344. def heartbeat_display_text(evt: dict) -> str:
  345. """One-line CLI receipt for a heartbeat wake; the row itself is hidden (``HEARTBEAT_DISPLAY_KIND``)."""
  346. cmd = _short_command(evt.get("command"))
  347. age = _format_age(float(evt.get("elapsed") or 0))
  348. return f"Background Process Output after {age}: {cmd}" if cmd else f"Background Process Output after {age}"
  349. class TimelineNotification(str):
  350. """Queued model text that stays string-compatible, plus the display kind and compact human
  351. title the surface paints instead of the raw notification wall."""
  352. display_text: str
  353. display_kind: str
  354. notification_category: str
  355. def __new__(cls, text: str, display_text: str, display_kind: str, notification_category: str = "result"):
  356. instance = super().__new__(cls, text)
  357. instance.display_text = display_text
  358. instance.display_kind = display_kind
  359. instance.notification_category = notification_category
  360. return instance
  361. @classmethod
  362. def for_delegation(cls, text: str, event: dict) -> "TimelineNotification":
  363. from agent.notification_presentation import diagnostic_process_event
  364. return cls(text, async_delegation_display_text(event), "async_delegation_complete",
  365. "diagnostic" if diagnostic_process_event(event) else "result")
  366. def _delegation_attribution_line(evt: dict) -> str | None:
  367. """One-line provenance for a subagent-owned process event, else None. Such a process
  368. outlives the child and lands in the PARENT conversation, which would otherwise see an
  369. anonymous output wall. Keyed on ``owner_task_id`` — ``task_id`` may be the session key."""
  370. task_id = str(evt.get("owner_task_id") or evt.get("task_id") or "")
  371. if not task_id.startswith("sa-"):
  372. return None
  373. info = None
  374. with suppress(Exception):
  375. from tools.delegate_tool import get_subagent_attribution
  376. info = get_subagent_attribution(task_id)
  377. if not info:
  378. # Registry entry aged out — still attribute generically, not anonymously.
  379. return f"Started by subagent {task_id} (delegate_task)."
  380. goal, deleg = str(info.get("goal") or "").strip(), info.get("delegation_id")
  381. goal = goal[:117] + "..." if len(goal) > 120 else goal
  382. return (f"Started by subagent {task_id}" + (f" of delegation {deleg}" if deleg else "") + "."
  383. + (f' Task: "{goal}"' if goal else ""))
  384. def _completion_status(evt: dict) -> str:
  385. reason = evt.get("completion_reason") or "exited"
  386. if reason == "killed":
  387. return f"terminated by {evt.get('termination_source') or 'Hermes'}"
  388. return _REASON_STATUS.get(reason) or ("completed normally" if evt.get("exit_code", "?") == 0 else "exited")
  389. def format_process_notification(evt: dict) -> str | None:
  390. """Format a completion_queue event into an ``[IMPORTANT: ...]`` message."""
  391. evt_type = evt.get("type", "completion")
  392. # watch_disabled and overflow events carry their own human-readable `message`;
  393. # otherwise overflow events would fall through to the completion formatter as a
  394. # phantom "process exited (exit code ?)".
  395. if evt_type in ("watch_disabled", "watch_overflow_tripped", "watch_overflow_released"):
  396. return f"[IMPORTANT: {evt.get('message', '')}]"
  397. if evt_type == "async_delegation":
  398. return _format_async_delegation(evt)
  399. _sid, _cmd = evt.get("session_id", "unknown"), evt.get("command", "unknown")
  400. _attribution = _delegation_attribution_line(evt)
  401. if evt.get("handoff_note"):
  402. _attribution = f"Handed off to you by a subagent before it finished. Purpose: {evt['handoff_note']}"
  403. attribution = f"{_attribution}\n" if _attribution else ""
  404. if evt_type == "heartbeat":
  405. return (
  406. f"[Background process {_sid} heartbeat #{evt.get('seq', '?')} — still running after "
  407. f"{_format_age(float(evt.get('elapsed') or 0))} (next in {evt.get('interval', '?')}s when there "
  408. f"is new output; you will also be told when it exits).\n"
  409. f"{attribution}Command: {_cmd}\nOutput since last heartbeat:\n{heartbeat_output_text(evt)}]")
  410. if evt_type == "watch_match":
  411. _sup = evt.get("suppressed", 0)
  412. return (
  413. f"[IMPORTANT: Background process {_sid} matched watch pattern \"{evt.get('pattern', '?')}\".\n"
  414. f"{attribution}Command: {_cmd}\nMatched output:\n{evt.get('output', '')}"
  415. + (f"\n({_sup} earlier matches were suppressed by rate limit)" if _sup else "") + "]")
  416. _exit = evt.get("exit_code", "?")
  417. _out = evt.get("output", "")
  418. _signal = ", SIGTERM" if _exit in {-15, 143, "-15", "143"} else ""
  419. # A subagent-owned process's full output belongs in the child's transcript, not as
  420. # a raw wall in the parent — trim hard but keep enough tail to recognise failures.
  421. if _attribution and isinstance(_out, str) and len(_out) > 600:
  422. _out = (
  423. "...(output trimmed — subagent-owned process; see the "
  424. "delegation's live transcript for full output)\n"
  425. + _out[-600:])
  426. elif evt.get("output_cut"):
  427. # Say so where the output is the payload (a teammate's reply): a silent tail reads as whole.
  428. _out = (f"...(first {evt['output_cut']} characters cut — process(action=\"log\", "
  429. f"session_id=\"{_sid}\") has the full output)\n{_out}")
  430. return (
  431. f"[IMPORTANT: Background process {_sid} {_completion_status(evt)} (exit code {_exit}{_signal}).\n"
  432. f"{attribution}Command: {_cmd}\nOutput:\n{_out}]")