bot_mode_dm.py 56 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049
  1. """Bot Mode agent-to-agent DM tool — ``message_agent``.
  2. Lets a Bot Mode agent message a teammate (a profile on this install, an agent on
  3. a registered peer gateway, or one on another Desktop-connected machine): the
  4. target is validated against the live roster, the attribution prefix is applied
  5. server-side, and the reply arrives later via the background-process completion
  6. notification (fire-and-forget). Containment: the schema is injected ONLY into a
  7. bot's canonical "Bot Chat" session on a Bot-Mode-managed install (same gate as
  8. ``tools/bot_mode_probe.py``; never in the registry or any toolset), and dispatch
  9. re-checks that gate so a forged call returns a structured error. Transports:
  10. local → ``hermes -p <name> chat --in ~ -c "Bot Chat" --create-if-missing -Q
  11. --query-file <tmp>``; peer → ``hermes peer dm <peer>[/<name>] < <tmp>``; both via
  12. ``terminal_tool(background=True, notify_on_complete=True)``.
  13. """
  14. from __future__ import annotations
  15. import contextlib
  16. import hashlib
  17. import json
  18. import logging
  19. import os
  20. import re
  21. import shlex
  22. import stat
  23. import subprocess
  24. import sys
  25. import tempfile
  26. import threading
  27. import time
  28. from dataclasses import dataclass, field
  29. from pathlib import Path
  30. from typing import Any, Optional
  31. # Top-level imports stay stdlib-only: this module also runs directly as the background
  32. # delivery runner (``python bot_mode_dm.py --run-delivery …``); Hermes helpers import lazily.
  33. logger = logging.getLogger(__name__)
  34. MESSAGE_AGENT_TOOL_NAME = "message_agent"
  35. # Message body cap — generous for real work, small enough that a runaway paste can't
  36. # turn one DM into a context bomb on the recipient.
  37. MESSAGE_MAX_CHARS = 16000
  38. # The delivery process's completion notification IS the reply: size it like a message, plus the
  39. # runner's header and failure prose, instead of the 2000-char tail a build log gets.
  40. REPLY_COMPLETION_CHARS = MESSAGE_MAX_CHARS + 2000
  41. # A runner owns and removes each DM file; this bounds residual plaintext lifetime if
  42. # the machine dies between spawn ack and the runner's finally.
  43. _DM_DIR_NAME = "hermes-dm"
  44. _DM_STALE_SECONDS = 24 * 60 * 60
  45. _LIVE_WAIT_SECONDS = 300
  46. # A live owner may run a turn past one wait window, but each waiting runner holds ~46 MB and the
  47. # sender's notify slot: past this the runner reports pending (do not resend) and exits.
  48. _LIVE_WAIT_MAX_SECONDS = 30 * 60
  49. # '<peer>/<agent>' — peer names are lowercase (``hermes peer`` normalizes them).
  50. _PEER_TARGET_RE = re.compile(r"^([a-z0-9][a-z0-9_-]{0,63})/([a-zA-Z0-9][a-zA-Z0-9_-]{0,63})$")
  51. # Same shape as ``tools.bot_relay._HANDLE_RE`` (kept local: see import note above).
  52. _LOCAL_TARGET_RE = re.compile(r"^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$")
  53. # Fan-out bound: one combined runner holds one sub-runner per target.
  54. FAN_OUT_MAX = 8
  55. def _default_home() -> str:
  56. from hermes_constants import get_process_hermes_home
  57. return str(get_process_hermes_home())
  58. def message_agent_tool_schema() -> dict:
  59. """OpenAI-format schema for ``message_agent`` (injected, not registered)."""
  60. return {
  61. "type": "function",
  62. "function": {
  63. "name": MESSAGE_AGENT_TOOL_NAME,
  64. "description": (
  65. "Send a message to ANOTHER agent (teammate) on this install, a registered peer gateway, or "
  66. "another connected machine. FIRE-AND-FORGET: it validates the target against the live roster, "
  67. "delivers into that agent's Bot Chat with your attribution prefixed, and returns a dispatch "
  68. "ack at once (status queued + delivery_id: a hand-off, not a receipt). It never returns the "
  69. "reply: finish your turn; the completion notification wakes you with the outcome (its "
  70. "`outcome` line says who answered or why not) — unless the ack says reply_delivery=\"poll\": "
  71. "then follow its process(action=\"wait\") instruction first. COMPOSE the message yourself "
  72. "(lead with the point and the concrete ask); never paste the user's words verbatim or share "
  73. "private 1:1 content. Targets: a roster name ('researcher'), '<peer>/<agent>' or '<peer>' for "
  74. "a peer gateway, '<handle>@<connection>' when a handle exists on several machines."
  75. ),
  76. "parameters": {
  77. "type": "object",
  78. "properties": {
  79. "target": {
  80. "type": "string",
  81. "description": (f"Who to message ('hermes' is the default agent). Up to {FAN_OUT_MAX} "
  82. "comma-separated names fan out: one combined reply."),
  83. },
  84. "message": {
  85. "type": "string",
  86. "description": (
  87. "The message YOU composed for that agent (max "
  88. f"{MESSAGE_MAX_CHARS} chars). Do not include the "
  89. "'Message from …' prefix — it is added automatically."
  90. ),
  91. },
  92. "constraints": {
  93. "type": "string",
  94. "description": "Limits their answer must respect (scope, length, format).",
  95. },
  96. "expecting": {
  97. "type": "string",
  98. "description": "What you need back from them; shown to them as the reply they owe you.",
  99. },
  100. "expects_reply": {
  101. "type": "boolean",
  102. "description": "false: notify only — no reply comes back and nothing wakes you.",
  103. },
  104. "cancel": {
  105. "type": "string",
  106. "description": "A delivery_id from your own ack: withdraw that queued request or stop the turn it started.",
  107. },
  108. },
  109. "required": ["target"],
  110. },
  111. },
  112. }
  113. def message_agent_authorized(agent: Any) -> bool:
  114. """The ``message_agent`` gate: a protocol-enabled agent whose session is a managed
  115. Bot-Mode canonical Bot Chat. Session-stable, so it is prompt-cache safe to re-evaluate
  116. on every tool-snapshot rebuild. Never raises."""
  117. try:
  118. if not getattr(agent, "_bot_mode_protocol", True):
  119. return False
  120. from tools.bot_mode_probe import BOT_CHAT_TITLE, is_bot_mode_managed
  121. # Managed-install check, NOT section non-emptiness: a SOUL.md carrying the
  122. # legacy protocol text gets an empty section but must still get the tool.
  123. return _session_title(agent) == BOT_CHAT_TITLE and is_bot_mode_managed(_agent_home(agent))
  124. except Exception: # pragma: no cover — must never break a turn
  125. logger.debug("message_agent_authorized failed", exc_info=True)
  126. return False
  127. def ensure_message_agent_tool(agent: Any) -> bool:
  128. """Inject the ``message_agent`` schema into a Bot Chat agent's tool list (once per turn).
  129. Idempotent and deterministic for the session's life (the gate is stable from the
  130. first turn), so the tool list is byte-identical across turns — prompt-cache safe. Never raises."""
  131. try:
  132. if not getattr(agent, "_bot_mode_protocol", True):
  133. return False
  134. tools = getattr(agent, "tools", None)
  135. present = bool(tools) and any(
  136. isinstance(t, dict) and t.get("function", {}).get("name") == MESSAGE_AGENT_TOOL_NAME
  137. for t in tools
  138. )
  139. if not present:
  140. if not message_agent_authorized(agent):
  141. return False
  142. if agent.tools is None:
  143. agent.tools = []
  144. agent.tools.append(message_agent_tool_schema())
  145. # Success means BOTH halves hold: a tool-surface rebuild (compaction, MCP refresh)
  146. # can keep the schema while valid_tool_names is republished without it, and an
  147. # advertised-but-nondispatchable tool sends the model hunting for shellouts (#96105).
  148. valid = getattr(agent, "valid_tool_names", None)
  149. if isinstance(valid, set):
  150. valid.add(MESSAGE_AGENT_TOOL_NAME)
  151. return True
  152. except Exception: # pragma: no cover — must never break a turn
  153. logger.debug("ensure_message_agent_tool failed", exc_info=True)
  154. return False
  155. def _resolve_local_name(target: str, roster: list[str], root: Path | None = None) -> Optional[str]:
  156. """Map a target to a local profile FOLDER id: 'hermes' → 'default' unless a real 'hermes'
  157. profile holds that handle (``_profile_for_handle``); an exact folder id
  158. (case-insensitive); else — when ``root`` is given — a friendly name or its Desktop @-slug
  159. (profile.yaml ``display_name`` / Bot Mode title: 'Scribe', '@scribe', 'Dr. Foo' → 'foo').
  160. Ambiguous friendly names resolve to None so a DM never lands on the wrong bot (#100671)."""
  161. want = target.strip().lower()
  162. if not want:
  163. return None
  164. from tools.bot_mode_probe import _profile_for_handle
  165. want = _profile_for_handle(want, roster)
  166. exact = next((name for name in roster if name.lower() == want), None)
  167. if exact is not None or root is None:
  168. return exact
  169. from tools.bot_mode_probe import alias_forms, local_alias_map
  170. aliases = local_alias_map(root)
  171. hits = set().union(*(aliases.get(form, set()) for form in alias_forms(want) | {want}))
  172. return next(iter(hits)) if len(hits) == 1 else None
  173. def _err(message: str, *, roster: list[str] | None = None, peers: list[str] | None = None) -> str:
  174. from tools.bot_failure_reasons import classify_agent_error
  175. payload: dict[str, Any] = {"error": message, "reason": classify_agent_error(message)}
  176. if roster is not None:
  177. payload["teammates"] = roster
  178. if peers is not None:
  179. payload["peers"] = peers
  180. return json.dumps(payload)
  181. @dataclass(frozen=True)
  182. class Sender:
  183. """The calling bot and its live roster, resolved once per ``message_agent`` call."""
  184. home: str
  185. root: Path
  186. me: str
  187. roster_homes: dict
  188. peers: list
  189. teammates: list
  190. task_id: Optional[str]
  191. agent: Any
  192. # The chain gate's author-envelope fields for this call (``tools/bot_mode_dm_chain.py``).
  193. chain: dict = field(default_factory=dict)
  194. def roster_err(self, msg: str) -> str:
  195. return _err(msg, roster=self.teammates, peers=self.peers)
  196. def _envelope(message: Any, constraints: Any, expecting: Any) -> str:
  197. """The request as the teammate reads it: the message, then its typed constraints and the reply
  198. the sender needs back, each on its own labelled line."""
  199. typed = [f"{label}: {str(value).strip()}" for label, value in (("Constraints", constraints),
  200. ("Reply needed", expecting)) if str(value or "").strip()]
  201. return "\n\n".join([str(message or "").strip(), *(["\n".join(typed)] if typed else [])])
  202. def _wants_reply(value: Any) -> bool:
  203. """``expects_reply`` as models send it: a bool, or its string spelling."""
  204. return str(value).strip().lower() not in ("false", "0", "no")
  205. def message_agent_tool(target: str = "", message: str = "", task_id: Optional[str] = None, agent: Any = None,
  206. expects_reply: Any = True, cancel: str = "", constraints: str = "", expecting: str = "") -> str:
  207. """Deliver ``message`` to ``target``'s Bot Chat (several comma-separated targets fan out),
  208. or withdraw the caller's own request ``cancel``. Returns a JSON ack/error.
  209. ``agent`` is the calling AIAgent — used for the Bot Chat gate and sender identity."""
  210. home = _agent_home(agent)
  211. try:
  212. from tools.bot_mode_probe import (
  213. BOT_CHAT_TITLE, NO_REPLY_MARKER, _display_name, _handle, _hermes_root, _peers,
  214. _profile_name as _self_profile_name, _roster, is_bot_mode_managed,
  215. )
  216. if _session_title(agent) != BOT_CHAT_TITLE:
  217. return _err("message_agent is only available in a Bot Mode 'Bot Chat' session. "
  218. "This session is not one; do not retry.")
  219. if not is_bot_mode_managed(home):
  220. return _err("This install is not Bot-Mode-managed (no bot roster); "
  221. "message_agent is unavailable. Do not retry.")
  222. except Exception as exc: # pragma: no cover — defensive
  223. return _err(f"Bot Mode gate check failed: {exc}")
  224. from hermes_cli.observability.shared_metrics_signals import record_feature_used
  225. record_feature_used("bot_mode", hermes_home=home)
  226. root, me = _hermes_root(Path(home)), _self_profile_name(Path(home))
  227. roster_homes = dict(_roster(root))
  228. peers = _peers(root)
  229. sender = Sender(home=home, root=root, me=me, roster_homes=roster_homes, peers=peers,
  230. teammates=[_handle(n, list(roster_homes)) for n in roster_homes if n != me], task_id=task_id, agent=agent)
  231. if str(cancel or "").strip():
  232. from tools.bot_mode_dm_coordination import cancel_own_delivery
  233. return cancel_own_delivery(str(cancel).strip(), str(target or ""), sender)
  234. if not str(message or "").strip():
  235. return _err("message is required — compose what you want to say to that agent.")
  236. body = _envelope(message, constraints, expecting)
  237. if len(body) > MESSAGE_MAX_CHARS:
  238. return _err(f"message too long ({len(body)} chars > {MESSAGE_MAX_CHARS}). "
  239. "Send the essentials; share large content as a file path instead.")
  240. from tools.bot_mode_dm_coordination import split_targets
  241. targets = split_targets(target, sender)
  242. if not targets:
  243. return sender.roster_err("target is required.")
  244. if len(targets) > FAN_OUT_MAX:
  245. return _err(f"Too many targets ({len(targets)} > {FAN_OUT_MAX}); message the ones the task needs.")
  246. reply = _wants_reply(expects_reply)
  247. # Sender signature: the friendly name when the bot has one (#89720); the @handle stays the routing alias.
  248. signature = f"Message from 🤖 {_display_name(me, roster_homes.get(me, Path(home)), list(roster_homes))} (@{_handle(me, list(roster_homes))}): "
  249. from tools.bot_mode_dm_chain import send_gated
  250. # The runtime's chain rules run before any transport (hop cap, repeated ask, reply to a bot: #137027).
  251. return send_gated(targets, reply, body, lambda wants: signature + ("" if wants else f"{NO_REPLY_MARKER} ") + body,
  252. sender)
  253. def _dispatch(raw_target: str, content: str, sender: Sender, *, wake: Any) -> str:
  254. """Resolve one target and hand ``content`` to its transport. ``wake`` is how the reply comes
  255. back: ``"notify"`` (a tracked runner whose completion wakes the sender), ``"none"`` (notify-only:
  256. nothing waits), or a list collecting the runner commands one fan-out runner joins."""
  257. from tools.bot_mode_probe import _handle, _profile_name as _self_profile_name
  258. from tools.bot_relay import _hermes_cli
  259. root, me, roster_homes, peers = sender.root, sender.me, sender.roster_homes, sender.peers
  260. roster = list(roster_homes)
  261. delivery = dict(task_id=sender.task_id, agent=sender.agent, wake=wake)
  262. # Attribution for the recipient's memory hooks; the text prefix stays the human-facing signature.
  263. author = {"id": f"bot:{me}", "name": _handle(me, roster), "is_bot": True, **sender.chain}
  264. # Peer target: '<peer>/<agent>' or a bare registered peer name.
  265. peer_match = _PEER_TARGET_RE.match(raw_target)
  266. if peer_match or raw_target.lower() in peers:
  267. peer_name, peer_profile = peer_match.groups() if peer_match else (raw_target.lower(), None)
  268. if peer_name not in peers:
  269. return sender.roster_err(f"No registered peer named '{peer_name}'.")
  270. dm_target = f"{peer_name}/{peer_profile}" if peer_profile else peer_name
  271. # A peer dm crosses installs: qualify the id with this host so the peer's own '<me>' stays distinct.
  272. from agent.turn_author import bot_author_id, local_origin
  273. peer_author = {**author, "id": bot_author_id(me, local_origin())}
  274. # Pin the registry-owning profile: `hermes peer` resolves bot_peers via the profile-scoped
  275. # load_config(), while the roster above reads the machine-root config — the CLI must run
  276. # in that same profile or a secondary-profile bot sees an empty registry.
  277. # The delivery runs in a background service context whose PATH lacks the gateway's
  278. # venv bin dir, so a bare "hermes" resolves to a system install and dies on import
  279. # under the wrong interpreter (#108628). _hermes_cli pins the entrypoint beside
  280. # this interpreter; _local_delivery_home matches argv[0] by basename,
  281. # so the absolute path stays compatible.
  282. return _start_delivery([_hermes_cli(), "-p", _self_profile_name(root), "peer", "dm", dm_target], content,
  283. f"@{peer_profile or peer_name} on peer '{peer_name}'", stdin_file=True,
  284. author=peer_author, **delivery)
  285. # A connection-qualified target ('hermes@mini') names a relay row outright; it is the form the relay itself
  286. # hands out for a colliding row, and stamps on replies. Resolved locally first, a local bot whose friendly
  287. # name slugs to 'hermes-mini' captured it. An '@' name no connection answers to still resolves locally.
  288. if "@" in raw_target.strip().lstrip("@"):
  289. # The sender's own relay folder, as below: the default's would relay a named bot's DM as the default.
  290. relayed = _try_relay_delivery(Path(sender.home), raw_target, content, me, **delivery)
  291. if relayed is not None:
  292. return relayed
  293. # Local teammate — folder id, or a friendly name / Desktop @-slug ('Scribe', 'Dr. Foo').
  294. resolved = _resolve_local_name(raw_target, roster, root)
  295. is_local_shape = bool(_LOCAL_TARGET_RE.match(raw_target))
  296. if resolved is None and not is_local_shape and "@" not in raw_target:
  297. return sender.roster_err(f"Invalid target: {raw_target!r}.")
  298. if resolved is None or resolved == me:
  299. # Unknown locally, or same-name target on ANOTHER connection (this gateway's 'default'
  300. # messaging the cloud 'default'): every Desktop-connected gateway is reachable via the
  301. # relay roster, so try that before reporting a resolution failure / self-message.
  302. relayed = _try_relay_delivery(Path(sender.home), raw_target, content, me, **delivery)
  303. if relayed is not None:
  304. return relayed
  305. if resolved == me:
  306. return _err("You can't message yourself. Pick a teammate from the roster.")
  307. return sender.roster_err(f"No teammate named '{raw_target}' on this install, on a connected "
  308. "machine, or on a registered peer. Pick a name from the roster "
  309. "(roles are listed in your system prompt).")
  310. if (getattr(sender.agent, "_turn_author", None) or {}).get("id") == f"bot:{resolved}":
  311. # One reply path (#95074): this turn answers @resolved's delivery, whose runner carries the
  312. # final response back. A second DM races it and lands in their chat as a separate turn.
  313. return _err(f"@{_handle(resolved, roster)} messaged you this turn and your final response already goes back "
  314. "to them: put your reply in it instead of messaging them. Do not retry.")
  315. # Local teammates are admitted through the profile authority; the argv only names the
  316. # profile for the runner's home lookup and is never executed.
  317. return _start_delivery([_hermes_cli(), "-p", resolved], content, f"@{_handle(resolved, roster)}",
  318. stdin_file=False, profile_home=roster_homes[resolved], author=author, **delivery)
  319. def _try_relay_delivery(root: Path, raw_target: str, content: str, me: str, *,
  320. task_id: Optional[str], agent: Any, wake: Any = "notify") -> Optional[str]:
  321. """Cross-connection delivery via the Desktop relay; None when the target doesn't
  322. resolve against the relay roster. The envelope is queued on disk for the Desktop
  323. to drain; a background waiter is spawned immediately so the relayed reply wakes
  324. the sender through the standard completion-notification path."""
  325. try:
  326. from tools.bot_mode_probe import _handle, _hermes_root, _roster, local_taken_forms
  327. from tools.bot_relay import (
  328. EnvelopeRefusedError, _target_aliases, enqueue_envelope, read_remote_roster, remote_target_forms,
  329. resolve_remote_target, waiter_command,
  330. )
  331. roster = read_remote_roster(root)
  332. match = resolve_remote_target(raw_target, roster) if roster else None
  333. if match is None:
  334. return None
  335. if match == "ambiguous":
  336. want = raw_target.strip().lstrip("@").partition("@")[0].lower()
  337. forms = ", ".join(form for r, form in zip(roster, remote_target_forms(roster, local_taken_forms(root)))
  338. if want in _target_aliases(r))
  339. return _err(f"'{raw_target}' exists on several connected machines — disambiguate with one of: {forms}.")
  340. try:
  341. envelope = enqueue_envelope(root, target=match, message=content, sender_profile=me,
  342. sender_handle=_handle(me, [n for n, _d in _roster(_hermes_root(root))]))
  343. except EnvelopeRefusedError as exc:
  344. # Fail fast: target definitively offline — nothing was queued.
  345. # Structured refusal so the agent can distinguish it from a resolution error ('runtime_offline'
  346. # per the #93091 reason enum).
  347. return json.dumps({"error": str(exc), "reason": exc.reason})
  348. label = f"@{match['handle']} on {match['connection_label'] or match['connection_id']}"
  349. if wake == "none":
  350. # The relay delivers the queued envelope on its own; only a reply needs the waiter.
  351. return json.dumps({"status": "queued", "delivery_id": envelope["id"], "to": label,
  352. "expects_reply": False, "detail": _NOTIFY_ONLY_DETAIL})
  353. raw = _spawn_delivery(waiter_command(root, envelope), label, delivery_id=envelope["id"], task_id=task_id,
  354. agent=agent, wake=wake)
  355. waiter_error = json.loads(raw).get("error")
  356. if not waiter_error:
  357. return raw
  358. # The envelope is already queued and the Desktop drains it on its own, so a waiter that
  359. # failed to start loses only the reply wake-up. Reporting a hard failure here makes the
  360. # sender resend and deliver the message twice. Same shape as the live-owner branch of
  361. # _start_delivery: queued + notification_error.
  362. return json.dumps({
  363. "status": "queued", "delivery_id": envelope["id"], "to": label, "notification_error": waiter_error,
  364. "detail": (f"Message queued for {label}; the relay delivers it on its own, but the reply "
  365. "waiter did not start, so the reply will NOT wake you. Do NOT resend."),
  366. })
  367. except Exception:
  368. logger.debug("relay delivery attempt failed", exc_info=True)
  369. return None
  370. def _dm_dir() -> Path:
  371. uid_getter = getattr(os, "getuid", None)
  372. uid = uid_getter() if callable(uid_getter) else None
  373. path = Path(tempfile.gettempdir()) / (f"{_DM_DIR_NAME}-{uid}" if uid is not None else _DM_DIR_NAME)
  374. path.mkdir(mode=0o700, exist_ok=True)
  375. # Shared POSIX temp roots need a per-user directory. Fail closed if an
  376. # attacker pre-created the expected path or replaced it with a symlink.
  377. info = path.lstat()
  378. if not stat.S_ISDIR(info.st_mode):
  379. raise PermissionError(f"DM temp path is not a directory: {path}")
  380. if uid is not None and info.st_uid != uid:
  381. raise PermissionError(f"DM temp directory is owned by another user: {path}")
  382. if stat.S_IMODE(info.st_mode) != 0o700:
  383. path.chmod(0o700)
  384. return path
  385. def cleanup_bot_dm_cache(max_age_hours: float = _DM_STALE_SECONDS / 3600, *, now: float | None = None) -> int:
  386. """Delete orphaned DM payload files older than *max_age_hours*; returns count.
  387. Same contract as the other ``cleanup_*_cache`` helpers (hourly gateway housekeeping);
  388. legacy temp-root locations from versions predating the dedicated directory are swept too."""
  389. temp_root = Path(tempfile.gettempdir())
  390. locations = [(temp_root, "hermes-dm-*.txt"), (temp_root, "hermes-relay-dm-*.txt")]
  391. with contextlib.suppress(OSError):
  392. dm_dir = _dm_dir()
  393. locations.append((dm_dir, "*.txt"))
  394. # Live-delivery intents (``<dm file>.live.json``, message plaintext included) outlive
  395. # their runner on purpose — a retry replays the same delivery id from them — so the
  396. # orphans of runners that never settled are swept here too.
  397. locations.append((dm_dir, "*.live.json"))
  398. locations.append((dm_dir, "fanout-*.json"))
  399. from utils import unlink_files_older_than
  400. return sum(unlink_files_older_than(d, pattern, max_age_hours * 3600, now=now) for d, pattern in locations)
  401. def _unlink_dm_file(path: str) -> None:
  402. with contextlib.suppress(OSError):
  403. os.unlink(path)
  404. def _write_dm_file(content: str) -> str:
  405. """The message rides a temp file — never inline shell text."""
  406. cleanup_bot_dm_cache()
  407. fd, path = tempfile.mkstemp(prefix="dm-", suffix=".txt", dir=_dm_dir(), text=True)
  408. try:
  409. with os.fdopen(fd, "w", encoding="utf-8") as f:
  410. f.write(content)
  411. except BaseException:
  412. # If fdopen itself failed the raw descriptor is still ours; closing twice is harmless.
  413. with contextlib.suppress(OSError):
  414. os.close(fd)
  415. _unlink_dm_file(path)
  416. raise
  417. return path
  418. def _live_intent_file(dm_file: str | os.PathLike) -> str:
  419. """The pinned live-delivery intent beside a DM file (the cache sweep globs ``*.live.json``)."""
  420. return f"{os.fspath(dm_file)}.live.json"
  421. def _dm_delivery_id(dm_file: str | os.PathLike) -> str:
  422. """One delivery id per DM file: the dispatch ack, the live-owner intent and every retry
  423. of the runner derive it the same way, so the sender can correlate all of them."""
  424. return hashlib.sha256(str(Path(dm_file).resolve()).encode()).hexdigest()
  425. class LiveTargetUnavailableError(RuntimeError):
  426. """The canonical Bot Chat owner could not be reached with anything admitted — before the
  427. intent was pinned, or on a dial that died before the deliver RPC went out: nothing was
  428. sent, so this is a definite no-send the sender may retry, not the ambiguous
  429. post-admission state."""
  430. reason = "runtime_unavailable"
  431. resend = "once the target is up"
  432. class LiveTargetHeldError(LiveTargetUnavailableError):
  433. """The owner refused because another session writer holds the Bot Chat, and settled this
  434. delivery id as never sent (``bot_relay.settle``): every later attempt under the id gets that
  435. disposition, so this is a definite no-send too. A refusal without that settlement stays the
  436. ambiguous outcome."""
  437. resend = "after that session closes"
  438. @property
  439. def reason(self) -> str:
  440. from tools.bot_failure_reasons import HELD_NOT_SENT
  441. return HELD_NOT_SENT
  442. def _unavailable_payload(dm_file: str, exc: LiveTargetUnavailableError) -> str:
  443. return json.dumps({"reason": exc.reason, "delivery_id": _dm_delivery_id(dm_file),
  444. "error": f"{exc} — the message was NOT sent; it is safe to resend {exc.resend}."})
  445. def _settled_no_send(dm_file: str, exc: LiveTargetUnavailableError) -> str:
  446. """The answer to a definite no-send, for both the tool and its runner: first the payload and
  447. any pinned intent go, so nothing local can rebuild or replay the delivery. A file that is still
  448. there is not settlement: the answer is then the unknown outcome, never "safe to resend"."""
  449. left = []
  450. for path in (_live_intent_file(dm_file), dm_file):
  451. _unlink_dm_file(path)
  452. if os.path.lexists(path):
  453. left.append(path)
  454. if left:
  455. return _live_outcome_unknown(dm_file, f"could not remove {left[0]}")
  456. return _unavailable_payload(dm_file, exc)
  457. def _held_disposition(record: dict | None) -> bool:
  458. """The owner's terminal not-sent receipt for a delivery refused while another writer held the
  459. chat (``gateway/session_bot.py:_not_sent_record``)."""
  460. from tools.bot_failure_reasons import HELD_NOT_SENT
  461. return bool(record) and record.get("refused") is True and record.get("reason") == HELD_NOT_SENT
  462. def _admit_live_dm(profile_home: Path | None, dm_file: str, author: Optional[dict] = None) -> dict | None:
  463. """Pin intent before admission; retries may inspect, never change transport."""
  464. from tools.bot_live_delivery import (PreDialError, deliver_to_live_owner, find_canonical_live_owner,
  465. read_delivery_result)
  466. from utils import fsync_directory
  467. intent: dict[str, Any]
  468. intent_path = Path(_live_intent_file(dm_file))
  469. pinned_now = False
  470. if intent_path.exists():
  471. intent = json.loads(intent_path.read_text(encoding="utf-8-sig"))
  472. else:
  473. assert profile_home is not None
  474. try:
  475. owner = find_canonical_live_owner(profile_home)
  476. except Exception as exc:
  477. # Discovery runs before the intent exists and never admits: definite, not ambiguous.
  478. raise LiveTargetUnavailableError(f"canonical Bot Chat target is unavailable ({exc})") from exc
  479. if owner is None:
  480. raise LiveTargetUnavailableError("canonical Bot Chat target is unavailable")
  481. intent = dict(owner=owner, message=Path(dm_file).read_text(encoding="utf-8-sig"),
  482. delivery_id=_dm_delivery_id(dm_file),
  483. **({"author": author} if author else {}))
  484. try:
  485. fd = os.open(intent_path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600)
  486. except FileExistsError:
  487. intent = json.loads(intent_path.read_text(encoding="utf-8-sig"))
  488. else:
  489. with os.fdopen(fd, "w", encoding="utf-8") as stream:
  490. json.dump(intent, stream)
  491. stream.flush()
  492. os.fsync(stream.fileno())
  493. fsync_directory(intent_path.parent)
  494. pinned_now = True
  495. home = intent["owner"]["profile_home"]
  496. record = read_delivery_result(home, intent["delivery_id"])
  497. if record is None or intent["owner"].get("canonical"):
  498. from hermes_cli.gateway_client import GatewayRPCError
  499. from tools.bot_failure_reasons import HELD_NOT_SENT
  500. from tools.bot_live_delivery import settle_held_delivery
  501. identity = dict(delivery_id=intent["delivery_id"], author=intent.get("author"))
  502. try:
  503. record = deliver_to_live_owner(home, intent["owner"], intent["message"], **identity)
  504. except GatewayRPCError as exc:
  505. if str(exc) != HELD_NOT_SENT or exc.data.get("admitted") is not False:
  506. raise
  507. # Nothing was admitted while that refusal held the owner's lock, but a same-id attempt
  508. # may have admitted since: only the owner's settle decides, under that same lock.
  509. record = settle_held_delivery(home, intent["owner"], intent["message"], **identity)
  510. except PreDialError as exc:
  511. if not pinned_now:
  512. raise # an earlier attempt under this intent may have admitted: outcome unknown
  513. # This call pinned the intent and its first dial died before the RPC went out: nothing
  514. # was admitted anywhere, so it is a definite no-send the sender may retry (#139303).
  515. _unlink_dm_file(_live_intent_file(dm_file))
  516. raise LiveTargetUnavailableError(f"live authority dial failed before admission ({exc})") from exc
  517. if _held_disposition(record):
  518. # The callers remove the intent and payload (``_settled_no_send``).
  519. raise LiveTargetHeldError("Bot Chat is held by another session writer")
  520. return record
  521. def _wait_live_dm(home: str, delivery_id: str, *, dm_file: str | os.PathLike | None = None) -> int:
  522. from tools.bot_failure_reasons import RUNTIME_OFFLINE
  523. from tools.bot_live_delivery import await_delivery, cancel_queued_delivery, owner_holds_delivery
  524. deadline = time.monotonic() + _LIVE_WAIT_MAX_SECONDS
  525. missed, unreachable = 0, False
  526. while True:
  527. record = await_delivery(home, delivery_id, max(0.0, min(_LIVE_WAIT_SECONDS, deadline - time.monotonic())))
  528. if record is None or record["status"] not in ("queued", "claimed") or time.monotonic() >= deadline:
  529. break
  530. try:
  531. held = owner_holds_delivery(home, record)
  532. except Exception:
  533. logger.debug("Could not check live DM owner", exc_info=True)
  534. held = None
  535. unreachable = held is None
  536. if held:
  537. missed = 0
  538. continue
  539. if held is False and record["status"] == "queued":
  540. # Under the same mailbox lock as claim, either cancellation wins or
  541. # the claim wins and we must keep waiting for its outcome.
  542. record = cancel_queued_delivery(
  543. home, delivery_id, error="Live Bot Chat owner is no longer available",
  544. reason=RUNTIME_OFFLINE)
  545. if record is None or record["status"] != "claimed":
  546. break
  547. missed = 0
  548. continue
  549. # A vanished consumer may leave a permanent claim, and an owner we cannot look up
  550. # may be gone: allow one more window for an in-flight turn, then release the runner.
  551. missed += 1
  552. if missed > 1:
  553. break
  554. status = record["status"] if record else "ambiguous"
  555. payload = {key: record[key] for key in ("reply", "error", "reason") if record and record.get(key)}
  556. payload.update(status=status, delivery_id=delivery_id)
  557. if status in ("queued", "claimed", "ambiguous"):
  558. payload["detail"] = "Delivery remains pending or its outcome is unknown. Do not resend; receipt is retained."
  559. state = _live_target_state(dm_file) or ("unreachable" if unreachable else None)
  560. if state:
  561. # A bound that lapses on a teammate parked on its own user is that, never a silent timeout.
  562. payload["target_state"] = state
  563. elif status == "settled" and dm_file is not None:
  564. # The intent carries the message plaintext so a retry can replay the SAME delivery id;
  565. # once the owner settled it nothing retries, so it goes along with the dm file (same
  566. # plaintext) — the live branch returns before _run_delivery's own unlink.
  567. _unlink_dm_file(_live_intent_file(dm_file))
  568. _unlink_dm_file(str(dm_file))
  569. from tools.bot_mode_dm_outcome import outcome_line
  570. who = f"@{Path(home).name}" if Path(home).parent.name == "profiles" else "Your teammate"
  571. print(json.dumps({"outcome": outcome_line(who, payload), **payload}))
  572. return 0 if status in ("settled", "queued", "claimed") else 1
  573. def _live_target_state(dm_file: str | os.PathLike | None) -> Optional[str]:
  574. """The target Bot Chat's live state for a wait ending pending, from a same-id replay of the
  575. pinned intent (the owner answers it with the existing receipt). None when nothing answers:
  576. the state is a hint, and its absence must never change the delivery outcome."""
  577. if dm_file is None or not os.path.exists(_live_intent_file(dm_file)):
  578. return None
  579. try:
  580. return (_admit_live_dm(None, os.fspath(dm_file)) or {}).get("target_state")
  581. except Exception:
  582. logger.debug("Could not read the live DM target's state", exc_info=True)
  583. return None
  584. def _local_delivery_home(argv: list[str]) -> Path | None:
  585. cli = (argv[0] if argv else "").rsplit("\\", 1)[-1].rsplit("/", 1)[-1]
  586. if len(argv) < 3 or cli not in ("hermes", "hermes.exe") or argv[1] != "-p":
  587. return None
  588. from tools.bot_mode_probe import _hermes_root, _roster
  589. return dict(_roster(_hermes_root(Path(_default_home())))).get(argv[2])
  590. def _live_outcome_unknown(dm_file: str, cause: object) -> str:
  591. """The runner's stdout when a live admission may have happened but its outcome is unknown."""
  592. return json.dumps({"status": "ambiguous", "delivery_id": _dm_delivery_id(dm_file),
  593. "error": f"Live admission outcome unknown: {cause}. Do not resend.",
  594. "evidence_file": dm_file})
  595. def _runner_argv(args: list[str]) -> tuple[Optional[str], str, str, list[str]] | None:
  596. """Split ``--run-delivery [--author <json>] <mode> <dm_file> <argv…>`` into
  597. ``(author_json, mode, dm_file, argv)``; None when malformed. Stdlib only: the boot-failure
  598. report runs it when no Hermes import is available."""
  599. if args[:1] != ["--run-delivery"]:
  600. return None
  601. rest, author = args[1:], None
  602. if rest[:1] == ["--author"]:
  603. if len(rest) < 2:
  604. return None
  605. author, rest = rest[1], rest[2:]
  606. if len(rest) < 2 or rest[0] not in ("stdin", "query-file"):
  607. return None
  608. return author, rest[0], rest[1], rest[2:]
  609. def _run_delivery(argv: list[str], dm_file: str, *, stdin_file: bool,
  610. profile_home: Path | None = None, author: Optional[dict] = None) -> int:
  611. """Admit local DMs only through the profile authority; retain uncertain intent.
  612. The optional peer stdin transport remains an explicit remote route, never a
  613. fallback after local admission. Background processes wait for delivery only.
  614. """
  615. # The live consumer owns turn admission; never compete for its CLI lease.
  616. if not stdin_file:
  617. home = profile_home or _local_delivery_home(argv)
  618. if home is not None or os.path.exists(_live_intent_file(dm_file)):
  619. try:
  620. record = _admit_live_dm(home, dm_file, author)
  621. except LiveTargetHeldError as exc:
  622. print(_settled_no_send(dm_file, exc)) # the owner settled the id: drop the payload too
  623. return 1
  624. except LiveTargetUnavailableError as exc:
  625. print(_unavailable_payload(dm_file, exc))
  626. return 1
  627. except Exception as exc:
  628. print(_live_outcome_unknown(dm_file, exc))
  629. return 1
  630. if record is not None:
  631. return _wait_live_dm(record["profile_home"], record["delivery_id"], dm_file=dm_file)
  632. if not stdin_file:
  633. print(json.dumps({"reason": "runtime_unavailable", "error": "No canonical Bot Chat authority; payload retained."}))
  634. return 1
  635. try:
  636. from tools.bot_relay import delivery_env
  637. env = delivery_env(author, profile_home if not stdin_file else None)
  638. # Keep the file open until the transport exits; cleanup occurs
  639. # after subprocess.run returns, not merely after stdin reaches EOF.
  640. with open(dm_file, "r", encoding="utf-8-sig") as stream:
  641. # Passing the file descriptor as stdin bypasses the BOM-aware decoder.
  642. return subprocess.run(argv, input=stream.read().encode("utf-8"), check=False, env=env).returncode
  643. finally:
  644. _unlink_dm_file(dm_file)
  645. def _delivery_command(argv: list[str], dm_file: str, *, stdin_file: bool,
  646. profile_home: Path | None = None, author: Optional[dict] = None) -> str:
  647. """Build an argv-safe command for the cleanup-owning background runner:
  648. ``--run-delivery [--author <json>] <mode> <dm_file> [--profile-home <path>] <argv...>``."""
  649. runner_argv = [sys.executable, str(Path(__file__).resolve()), "--run-delivery",
  650. "stdin" if stdin_file else "query-file", dm_file]
  651. if profile_home is not None:
  652. runner_argv.extend(["--profile-home", str(Path(profile_home).resolve())])
  653. runner_argv.extend(argv)
  654. if sys.platform == "win32":
  655. # The tracked local backend uses Git Bash on native Windows: forward slashes keep drive
  656. # paths executable there; backslash paths are parsed as command names (exit 127).
  657. runner_argv = [part.replace("\\", "/") for part in runner_argv]
  658. if author:
  659. # Inserted after the slash rewrite: JSON escapes are backslashes too.
  660. runner_argv[3:3] = ["--author", json.dumps(author, separators=(",", ":"))]
  661. return shlex.join(runner_argv)
  662. def _start_delivery(argv: list[str], content: str, label: str, *, stdin_file: bool,
  663. task_id: Optional[str], agent: Any, profile_home: Path | None = None,
  664. author: Optional[dict] = None, wake: Any = "notify") -> str:
  665. """Create a DM file and transfer its cleanup ownership to the runner."""
  666. dm_file = _write_dm_file(content)
  667. if profile_home is not None:
  668. try:
  669. record = _admit_live_dm(profile_home, dm_file, author)
  670. except LiveTargetUnavailableError as exc:
  671. return _settled_no_send(dm_file, exc)
  672. except Exception as exc:
  673. return json.dumps({"status": "ambiguous", "delivery_id": _dm_delivery_id(dm_file),
  674. "error": f"Live delivery admission could not be confirmed: {exc}. Do not resend.",
  675. "evidence_file": dm_file})
  676. if record is not None:
  677. if wake == "none":
  678. # The admission is durable at the owner and nothing waits for its reply: the intent and
  679. # payload exist only for a waiting runner's same-id replays.
  680. _unlink_dm_file(_live_intent_file(dm_file))
  681. _unlink_dm_file(dm_file)
  682. return json.dumps(_with_target_state(dict(
  683. status=record["status"], delivery_id=record["delivery_id"], to=label, expects_reply=False,
  684. detail=_NOTIFY_ONLY_DETAIL), record, label))
  685. command = _delivery_command(argv, dm_file, stdin_file=False, profile_home=profile_home, author=author)
  686. notification = json.loads(_spawn_delivery(command, label, delivery_id=record["delivery_id"],
  687. task_id=task_id, agent=agent, wake=wake))
  688. result = dict(status=record["status"], delivery_id=record["delivery_id"], to=label,
  689. detail="Durably queued for the live Bot Chat owner. Do NOT wait or resend; finish your turn.")
  690. if notification.get("error"):
  691. result["notification_error"] = notification["error"]
  692. elif notification.get("process_id"):
  693. result["process_id"] = notification["process_id"]
  694. result["reply_delivery"] = notification.get("reply_delivery", "notification")
  695. if result["reply_delivery"] == "poll":
  696. # Same runner, same stdout-borne reply (#101142): a non-push sender must get
  697. # the poll instruction here too, not 'finish your turn'.
  698. result["detail"] = f"Durably queued for the live Bot Chat owner. Do NOT resend. {notification['detail']}"
  699. return json.dumps(_with_target_state(result, record, label))
  700. try:
  701. command = _delivery_command(argv, dm_file, stdin_file=stdin_file, profile_home=profile_home, author=author)
  702. except BaseException:
  703. _unlink_dm_file(dm_file)
  704. raise
  705. return _spawn_delivery(command, label, dm_file=dm_file, task_id=task_id, agent=agent, wake=wake)
  706. _NOTIFY_ONLY_DETAIL = "Sent as notify-only: no reply comes back and nothing will wake you. Do not resend."
  707. # What a sender should tell its user when the teammate's turn is parked on that teammate's own user.
  708. _BLOCKED_DETAIL = {
  709. "waiting_approval": "is waiting for its user to approve a command in its own Bot Chat",
  710. "waiting_clarify": "is waiting for its user to answer a question in its own Bot Chat",
  711. "paused": "is not starting new turns right now (its gateway is restarting or updating)",
  712. }
  713. def _with_target_state(result: dict, record: dict, label: str) -> dict:
  714. """Carry the owner's live ``target_state`` into an ack; a blocked teammate is said so plainly."""
  715. state = record.get("target_state")
  716. if state:
  717. result["target_state"] = state
  718. if state in _BLOCKED_DETAIL:
  719. result["detail"] += (f" {label} {_BLOCKED_DETAIL[state]}, so its reply comes only after that: "
  720. "tell your user now.")
  721. return result
  722. def _spawn_delivery(command: str, label: str, *, dm_file: Optional[str] = None, delivery_id: Optional[str] = None,
  723. task_id: Optional[str], agent: Any, wake: Any = "notify",
  724. completion_chars: int = REPLY_COMPLETION_CHARS) -> str:
  725. """Launch the cleanup-owning runner and transfer file ownership on ack. ``dm_file``
  726. is None for relay deliveries (the waiter watches a reply file; envelope artifacts
  727. are owned/swept by ``tools/bot_relay.py``), which pass the envelope id as ``delivery_id``
  728. instead. The ack is ``queued`` + ``delivery_id`` like the live-owner branch: hand-off
  729. to a background process, never a delivery receipt. A list ``wake`` collects the runner for
  730. one fan-out process to join (it owns ``dm_file`` from here); ``"none"`` runs it unwatched."""
  731. if isinstance(wake, list):
  732. delivery_id = delivery_id or (_dm_delivery_id(dm_file) if dm_file else "")
  733. wake.append(dict(command=command, label=label, dm_file=dm_file, delivery_id=delivery_id))
  734. return json.dumps({"status": "queued", "delivery_id": delivery_id, "to": label})
  735. transferred = False
  736. try:
  737. from tools.terminal_tool import terminal_tool
  738. raw = terminal_tool(command, background=True, notify_on_complete=wake != "none", task_id=task_id,
  739. workdir=str(Path(__file__).resolve().parent.parent), _host_local=True,
  740. _completion_output_chars=completion_chars)
  741. try:
  742. parsed = json.loads(raw)
  743. except (ValueError, TypeError):
  744. parsed = {}
  745. proc_id = parsed.get("session_id") or ""
  746. if parsed.get("error"):
  747. return _err(f"Delivery to {label} failed to start: {parsed['error']}")
  748. if parsed.get("status") == "pending_approval":
  749. # terminal_tool's approval gate answers with an EMPTY error and no session_id: the runner
  750. # never launched because nobody in this turn could approve its command.
  751. return _err(f"Delivery to {label} failed to start: its command needs terminal approval that nobody "
  752. "in this turn can grant" + (", so nothing was sent. Approve it (or add it to "
  753. "command_allowlist) and send again." if dm_file else "."))
  754. if not proc_id:
  755. return _err(f"Delivery to {label} failed to start: no process id returned")
  756. # From here the background runner owns the file (removed after the consumer finishes).
  757. transferred = True
  758. if wake == "none":
  759. return json.dumps({"status": "queued", "delivery_id": delivery_id or (_dm_delivery_id(dm_file) if dm_file
  760. else ""), "to": label, "expects_reply": False, "detail": _NOTIFY_ONLY_DETAIL})
  761. if parsed.get("notify_on_complete") is False:
  762. # terminal_tool refused the completion promise: this session (api_server, one-shot
  763. # runner) cannot receive an async completion, so the recipient's reply would never
  764. # be injected here (#101142). Say so and name the return path the surface supports.
  765. detail = (f"Message handed to a background delivery process for {label}, but THIS session "
  766. "cannot receive completion notifications, so the reply will NOT arrive on its own. "
  767. f"Before ending your turn, retrieve the outcome with process(action='wait', "
  768. f"session_id='{proc_id}') — its output is the reply (relay it, attributed to that "
  769. "agent) or the delivery failure (report it; the message was NOT delivered); "
  770. "if wait returns status=timeout, call wait again until the process exits.")
  771. if _persist_reply_when_done(proc_id, agent):
  772. detail += (" Its outcome is also saved into this session's transcript as a delivery row "
  773. "when the process exits, so it survives even if the turn ends first.")
  774. else:
  775. detail = (f"Message queued for {label}: this acknowledges the hand-off to a "
  776. "background delivery process, not a delivery receipt — do NOT wait or poll. "
  777. "Finish your turn now; that process's completion notification carries the "
  778. "delivery outcome — the reply (relay it then, attributed to that agent) or "
  779. "the delivery failure (report it; the message was NOT delivered).")
  780. return json.dumps({
  781. "status": "queued",
  782. "delivery_id": delivery_id or (_dm_delivery_id(dm_file) if dm_file else ""),
  783. "to": label,
  784. "reply_delivery": "poll" if parsed.get("notify_on_complete") is False else "notification",
  785. "detail": detail,
  786. "process_id": proc_id,
  787. "queued_at": int(time.time()),
  788. })
  789. except Exception as exc:
  790. logger.error("message_agent delivery spawn failed: %s", exc, exc_info=True)
  791. return _err(f"Delivery to {label} could not be started: {exc}")
  792. finally:
  793. if dm_file and not transferred:
  794. _unlink_dm_file(dm_file)
  795. def _persist_reply_when_done(proc_id: str, agent: Any) -> bool:
  796. """#101142 durable leg. A non-push sender (api_server, one-shot runner) gets no completion
  797. notification, so once the tracked runner exits its stdout — the recipient's reply or the
  798. delivery failure — is appended to the sender's session transcript as a DELIVERY row
  799. (``display_kind="process_complete"``, the shape push surfaces persist for the same
  800. completion; mirrors gateway.wake.persist_delegation_delivery). A sender that already read
  801. the outcome via process(action='wait'/'log') is not told twice. Returns False (nothing
  802. armed) when the sender has no session transcript or the process is not tracked here."""
  803. from tools.process_registry import process_registry
  804. db, session_id = getattr(agent, "_session_db", None), getattr(agent, "session_id", None)
  805. proc = process_registry.get(proc_id)
  806. if proc is None or not session_id or not callable(getattr(db, "append_message", None)):
  807. return False
  808. def _run() -> None:
  809. from tools.process_registry_notifications import (
  810. format_process_notification, process_completion_display_text,
  811. )
  812. proc._completion_event.wait()
  813. if process_registry.is_completion_consumed(proc_id):
  814. return
  815. evt = {"type": "completion", "session_id": proc_id, **process_registry._exit_snapshot(proc, "exited")}
  816. try:
  817. db.append_message(session_id, "user", content=format_process_notification(evt),
  818. display_kind="process_complete",
  819. display_metadata={"display_text": process_completion_display_text([evt])})
  820. except Exception as exc:
  821. logger.warning("message_agent: could not persist the reply of %s into session %s: %s",
  822. proc_id, session_id, exc)
  823. threading.Thread(target=_run, name=f"message-agent-reply-{proc_id}", daemon=True).start()
  824. return True
  825. def _wait_reply_main(reply_path: str, label: str, budget_seconds: str) -> int:
  826. """The relay reply waiter (``tools/bot_relay.waiter_command``): block until the sender-side
  827. reply file exists, print it as the completion notification the sender wakes on, exit 1 on a
  828. delivery error or when the budget runs out. Stdlib only: this runs as a background process
  829. from any bot turn, and the sender's completion notification is exactly its stdout."""
  830. try:
  831. deadline = time.time() + float(budget_seconds)
  832. except ValueError:
  833. return 2
  834. while time.time() < deadline:
  835. if os.path.exists(reply_path):
  836. with open(reply_path, encoding="utf-8-sig") as fh:
  837. d = json.load(fh)
  838. if d.get("error"):
  839. # Typed reason code rides ahead of the free text so the sender can branch on it
  840. # without parsing provider prose. See #93091.
  841. code = str(d.get("reason") or "").strip()
  842. tag = f" [reason: {code}]" if code else ""
  843. print(f"Delivery to {label} failed{tag}: {d['error']}")
  844. return 1
  845. print(f"Reply from {label}:")
  846. print(d.get("reply") or "(empty reply)")
  847. return 0
  848. # 250ms cadence: stat is cheap and a longer sleep is pure dead air.
  849. time.sleep(0.25)
  850. print(f"No reply from {label} within {budget_seconds}s. The message may still be delivered when "
  851. "the Desktop reconnects; do not resend blindly.")
  852. return 1
  853. def _delivery_main(args: list[str]) -> int:
  854. """Runner entry for the argv ``_delivery_command`` and ``bot_relay.waiter_command`` build.
  855. Malformed argv exits 2 without touching the DM file."""
  856. if args[:1] == ["--wait-reply"]:
  857. return _wait_reply_main(*args[1:]) if len(args) == 4 else 2
  858. if args[:1] == ["--fan-out"]:
  859. from tools.bot_mode_dm_coordination import run_fan_out
  860. return run_fan_out(args[1]) if len(args) == 2 else 2
  861. parsed = _runner_argv(args)
  862. if parsed is None:
  863. return 2
  864. author_json, mode, dm_file, argv = parsed
  865. author = None
  866. if author_json is not None:
  867. from agent.turn_author import parse_turn_author
  868. author = parse_turn_author(author_json)
  869. if author is None:
  870. return 2
  871. try:
  872. profile_home = None
  873. if len(argv) >= 2 and argv[0] == "--profile-home":
  874. profile_home, argv = Path(argv[1]), argv[2:]
  875. return _run_delivery(argv, dm_file, stdin_file=mode == "stdin", profile_home=profile_home, author=author)
  876. except Exception as exc:
  877. # Every refusal ships a typed reason on stdout so the completion notification carries it
  878. # back to the sender (#93091), with the same vocabulary-guarded classification the relay
  879. # lane applies.
  880. from tools.bot_failure_reasons import delivery_failure_reason
  881. print(json.dumps({"error": str(exc), "reason": delivery_failure_reason(exc)}))
  882. return 1
  883. # agent-context helpers (mirror system_prompt.py's resolution)
  884. def _agent_home(agent: Any) -> str:
  885. """The calling agent's OWN home (session-db derived), not ambient env."""
  886. with contextlib.suppress(Exception):
  887. db_path = getattr(getattr(agent, "_session_db", None), "db_path", None)
  888. if db_path:
  889. return str(Path(db_path).parent)
  890. return _default_home()
  891. def _session_title(agent: Any) -> str:
  892. title = str(getattr(agent, "_session_title_hint", "") or "").strip()
  893. if title:
  894. return title
  895. with contextlib.suppress(Exception):
  896. sdb, sid = getattr(agent, "_session_db", None), getattr(agent, "session_id", None)
  897. if sdb and sid:
  898. return str(sdb.get_session_title(sid) or "").strip()
  899. return ""
  900. if __name__ == "__main__": # pragma: no cover - exercised as a background process
  901. # Spawned as a script with the sender's sys.executable, which under PM is the bare store
  902. # interpreter (dependencies are activated in-process, never inherited), so boot like every
  903. # entry point before the lazy Hermes imports. Run as a path, sys.path[0] is tools/.
  904. sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
  905. # Only the delivery lane boots: the reply waiter is stdlib only and its stdout is the
  906. # sender's wake-up, and any other argv exits 2 before a Hermes import.
  907. if sys.argv[1:2] == ["--run-delivery"]:
  908. try:
  909. import hermes_bootstrap
  910. except (Exception, SystemExit) as exc:
  911. # A pinned live intent means the sender may already have admitted this DM and was
  912. # told not to resend; a bare repair hint would read as "NOT delivered". Without an
  913. # intent nothing was handed over, so the plain failure is the truth. A relaunched
  914. # child (Windows) already printed its own outcome.
  915. booted = getattr(exc, "relaunched", False) or (isinstance(exc, SystemExit) and not exc.code)
  916. parsed = _runner_argv(sys.argv[1:])
  917. if not booted and parsed and os.path.exists(_live_intent_file(parsed[2])):
  918. print(_live_outcome_unknown(parsed[2], "the delivery runner could not activate "
  919. "Hermes dependencies (see stderr)"))
  920. raise
  921. raise SystemExit(_delivery_main(sys.argv[1:]))