run_turn_progress.py 56 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034
  1. """Extracted gateway run_turn_progress responsibility; consumed by TurnRunner."""
  2. from __future__ import annotations
  3. import asyncio
  4. import dataclasses
  5. import logging
  6. import queue
  7. import re
  8. import threading
  9. import time
  10. from contextlib import suppress
  11. from datetime import datetime
  12. from typing import TYPE_CHECKING, Any, Dict, List, Optional
  13. from agent.i18n import t
  14. from agent.interrupt_compat import _accepts_keyword
  15. from agent.replay_cleanup import strip_stale_dangerous_confirmations
  16. from gateway.config import Platform
  17. from gateway.media_repair import repair_explicit_computer_use_media_paths
  18. from gateway.platforms.base import BasePlatformAdapter
  19. from gateway.platforms.helpers import typing_metadata_for_turn
  20. from gateway.turn_context import TurnContext
  21. from hermes_cli.config import cfg_get
  22. from utils import is_truthy_value
  23. if TYPE_CHECKING: # string annotations only; never imported at runtime (cycle)
  24. from gateway.run import GatewayRunner
  25. from gateway.run_turn_runner import TurnRunner
  26. # Log-record parity with the origin module.
  27. logger = logging.getLogger("gateway.run")
  28. def _append_progress_repeat_count(message: str, occurrences: int) -> str:
  29. """Put a repeat counter after a closing code fence on its own line: ```` ``` (×N) ```` is not a
  30. valid closing fence, so Telegram/Markdown renderers would leave the block open."""
  31. suffix = f"(×{occurrences})"
  32. body = message.rstrip("\r\n")
  33. if re.search(r"(?:^|\n)[ \t]*```[ \t]*\r?\Z", body):
  34. line_end = "\r\n" if message.endswith("\r\n") else "\n"
  35. return f"{body}{line_end}{suffix}"
  36. return f"{message} {suffix}"
  37. def _tool_lifecycle_payload(call_id, tool_name, args) -> dict:
  38. """The ``ToolStartPayload`` contract every client reads (``tool_id``/``name``/``context``),
  39. plus the ``tool_call_id``/``tool_name`` the gateway's own consumers were built on."""
  40. from agent.display import build_tool_preview, tool_labels_for_call
  41. name = str(tool_name or "tool")
  42. args = args if isinstance(args, dict) else {}
  43. from gateway.session_tool_events import bounded_args
  44. payload = {"tool_id": str(call_id or ""), "name": name, "context": build_tool_preview(name, args, max_len=80) or "",
  45. "tool_call_id": str(call_id or ""), "tool_name": name, "args": bounded_args(args)}
  46. if labels := [label.as_payload() for label in tool_labels_for_call(name, args)]:
  47. payload["labels"] = labels
  48. return payload
  49. def _tool_complete_payload(call_id, tool_name, args, result, *, is_error=None, verbose=False) -> dict:
  50. """``tool.complete`` as every viewer reads it: the start contract plus the executor's verdict and
  51. the result (ACP renders paths/output and failure from it), and ``result_text`` under /verbose."""
  52. from gateway.session_tool_events import bounded_result
  53. if is_error is None:
  54. from agent.display import _detect_tool_failure
  55. is_error = _detect_tool_failure(tool_name, result)[0]
  56. payload = {**_tool_lifecycle_payload(call_id, tool_name, args), "is_error": bool(is_error),
  57. "result": bounded_result(result, is_error)}
  58. if verbose:
  59. from tui_gateway.tool_progress import _tool_result_text
  60. payload["result_text"] = _tool_result_text(result)
  61. return payload
  62. def publish_worker_tool_event(authority, session_id, generation, frame) -> bool:
  63. """A managed worker's tool frame, published exactly as an in-process turn publishes its own
  64. (the shared viewer stream and this admission's API observers). False for any other frame."""
  65. kind = frame.get("type")
  66. fields = {"type", "tool_call_id", "name", "args"} | ({"result", "is_error"} if kind == "tool.complete" else set())
  67. if (kind not in ("tool.start", "tool.complete") or set(frame) != fields
  68. or not isinstance(frame["tool_call_id"], str) or not isinstance(frame["name"], str)
  69. or not isinstance(frame["args"], dict)
  70. or (kind == "tool.complete" and (not isinstance(frame["result"], str) or type(frame["is_error"]) is not bool))):
  71. return False
  72. call_id, name, args, result = frame["tool_call_id"], frame["name"], frame["args"], frame.get("result")
  73. if kind == "tool.start":
  74. payload = _tool_lifecycle_payload(call_id, name, args)
  75. else:
  76. verbose = getattr(authority.sessions[session_id], "tool_progress_mode", None) == "verbose"
  77. payload = _tool_complete_payload(call_id, name, args, result, is_error=frame["is_error"], verbose=verbose)
  78. authority.publish_execution(session_id, generation, kind, payload)
  79. from gateway.session_api_turn import publish_api_tool_event, publish_api_tool_progress
  80. publish_api_tool_event(authority, session_id, generation, kind, call_id, name, args, result)
  81. # A worker sends no progress events: progress-only observers get the executor's preview of its
  82. # args and the frame's own verdict, taken before the result was bounded.
  83. if kind == "tool.start":
  84. from agent.display import build_tool_preview
  85. publish_api_tool_progress(authority, session_id, generation, "tool.started", name,
  86. build_tool_preview(name, args), args)
  87. else:
  88. publish_api_tool_progress(authority, session_id, generation, "tool.completed", name, None, None,
  89. is_error=frame["is_error"], result=result)
  90. return True
  91. class GatewayTurnProgressMixin:
  92. # ── shared thread→loop plumbing ─────────────────────────────────────────────────────────
  93. def _schedule(self, coro, log_message: str, loop=None):
  94. """Hop a coroutine from the agent's sync worker thread onto the gateway loop."""
  95. from gateway.run import safe_schedule_threadsafe
  96. return safe_schedule_threadsafe(
  97. coro, self._ctx._loop_for_step if loop is None else loop, logger=logger, log_message=log_message,
  98. )
  99. def _agent_interrupted(self) -> bool:
  100. """True once the user sent `stop` (agent_holder[0] is the shared agent handle)."""
  101. try:
  102. agent = self._ctx.agent_holder[0] if self._ctx.agent_holder else None
  103. return bool(agent is not None and getattr(agent, "is_interrupted", False))
  104. except Exception:
  105. return False
  106. def _stream_consumer(self):
  107. holder = self._ctx.stream_consumer_holder
  108. return holder[0] if holder else None
  109. def _drain_progress_queue(self) -> None:
  110. q = self._ctx.progress_queue
  111. with suppress(Exception):
  112. while not q.empty():
  113. q.get_nowait()
  114. def _track_progress_result(self, result) -> None:
  115. """Remember a delivered progress/status message id for end-of-turn cleanup."""
  116. ctx = self._ctx
  117. if ctx._cleanup_progress and getattr(result, "success", False) and getattr(result, "message_id", None):
  118. ctx._cleanup_msg_ids.append(str(result.message_id))
  119. def _track_future_cleanup_id(self, fut) -> None:
  120. try:
  121. res = fut.result()
  122. except Exception:
  123. return
  124. self._track_progress_result(res)
  125. # ── progress_callback (agent thread → progress queue) ───────────────────────────────────
  126. def progress_callback(self, event_type: str, tool_name: str | None = None, preview: str | None = None, args: dict | None = None, **kwargs):
  127. """Callback invoked by agent on tool lifecycle events."""
  128. ctx = self._ctx
  129. if local_viewer_turn(self):
  130. try:
  131. from gateway import local_viewer_events
  132. local_viewer_events.publish_progress(self, event_type, tool_name, preview, kwargs)
  133. except Exception:
  134. # Best-effort: a viewer frame never blocks the failure notice below, but a lost one is logged.
  135. logger.debug("Local viewer progress publish failed for %s", event_type, exc_info=True)
  136. # Failed subagent → one clean user-facing notice, handled FIRST, before every progress-queue
  137. # gate: platforms with tool_progress off must still hear about a dead delegation.
  138. if event_type == "subagent.complete":
  139. self._progress_subagent_notice(preview, kwargs)
  140. return
  141. self._progress_live_status(event_type, tool_name, args)
  142. # "log" mode: append tool.started lines to the log queue, silent in chat. Handled before
  143. # the progress_queue guard because log mode runs without a chat progress queue.
  144. if ctx.log_queue is not None and event_type == "tool.started" and tool_name and tool_name != "_thinking":
  145. ts = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
  146. preview_str = f' "{preview}"' if preview else ""
  147. ctx.log_queue.put(f"{ts} {tool_name}:{preview_str}".rstrip())
  148. if not ctx.progress_queue or not ctx._run_still_current():
  149. return
  150. if event_type == "tool.completed" and not ctx.long_tool_hint_fired[0]:
  151. self._progress_onboarding_hint(kwargs)
  152. return
  153. # "_thinking" is assistant scratch text between tool calls, never ordinary tool progress:
  154. # only relayed when the platform explicitly opted into thinking_progress.
  155. if event_type == "_thinking" or tool_name == "_thinking":
  156. thinking_text = (preview if tool_name == "_thinking" else tool_name) if ctx._thinking_enabled else None
  157. if thinking_text:
  158. ctx.progress_queue.put(t("gateway.progress.thinking_prefix", text=thinking_text))
  159. return
  160. # Native task cards consume the ID-bearing tool_start/tool_complete callbacks instead;
  161. # name-correlated text events would duplicate cards and mispair concurrent same-tool calls.
  162. if ctx._native_slack_task_cards and event_type in {"tool.started", "tool.completed"}:
  163. return
  164. # tool_progress off → only _thinking passes (above). Only tool.started renders. clarify:
  165. # send_clarify IS the user-facing rendering (a bubble would duplicate it, and verbose mode
  166. # would dump the raw args JSON right under the prompt). Post-`stop`: N parallel tool calls
  167. # fire N tool.started events before the interrupt check, so a late stop must not render them.
  168. if (
  169. not ctx.tool_progress_enabled
  170. or event_type != "tool.started"
  171. # The adapter's send_clarify IS the user-facing rendering (interactive buttons or the
  172. # numbered-text fallback), so a progress bubble is pure duplication — and in verbose mode it
  173. # dumps the raw tool-call args JSON into the chat. Because
  174. # the progress queue drains on a background task, that raw JSON typically lands right underneath
  175. # the rendered prompt (#52374).
  176. or tool_name == "clarify"
  177. or self._agent_interrupted()
  178. ):
  179. return
  180. # "new" mode: only report when tool changes
  181. if ctx.progress_mode == "new" and tool_name == ctx.last_tool[0]:
  182. return
  183. ctx.last_tool[0] = tool_name
  184. msg = self._progress_build_message(tool_name, preview, args)
  185. if msg is not None:
  186. self._progress_emit(msg)
  187. def _progress_subagent_notice(self, preview, kwargs: dict) -> None:
  188. """Only terminal failure statuses render (same notice rail as credit warnings)."""
  189. ctx = self._ctx
  190. from gateway.warning_notifications import render_notification
  191. status = kwargs.get("status")
  192. try:
  193. from tools.delegate_tool import SUBAGENT_FAILURE_STATUSES, format_subagent_failure_line
  194. if status in SUBAGENT_FAILURE_STATUSES and ctx._run_still_current():
  195. line = format_subagent_failure_line(
  196. kwargs.get("goal"), status, error=kwargs.get("summary") or preview,
  197. duration_seconds=kwargs.get("duration_seconds"), failure_reason=kwargs.get("failure_reason"),
  198. )
  199. render_notification(
  200. lambda: self._schedule(self._runner._deliver_platform_notice(ctx.source, line), "subagent failure notice scheduling error"),
  201. platform=ctx.source.platform, user_config=ctx.user_config)
  202. except Exception:
  203. logger.debug("subagent failure notice failed", exc_info=True)
  204. def _progress_live_status(self, event_type: str, tool_name, args) -> None:
  205. """Live status line (Slack assistant status): stash the tool phrase on the adapter; the
  206. _keep_typing refresh renders it. Plain dict write, safe from the sync worker thread."""
  207. ctx = self._ctx
  208. adapter = ctx._live_status_adapter
  209. if adapter is None or ctx._live_status_mode == "off" or tool_name == "_thinking":
  210. return
  211. try:
  212. if event_type == "tool.started" and tool_name and ctx._run_still_current():
  213. from agent.display import build_status_phrase
  214. adapter.set_status_text(ctx.source.chat_id, build_status_phrase(tool_name, args if ctx._live_status_mode == "full" else None))
  215. elif event_type == "tool.completed":
  216. # Between tools the model is genuinely "thinking" again — revert to the static default.
  217. adapter.set_status_text(ctx.source.chat_id, None)
  218. except Exception as err:
  219. logger.debug("live status update failed: %s", err)
  220. def _progress_onboarding_hint(self, kwargs: dict) -> None:
  221. """First-touch onboarding: the first time a tool exceeds _LONG_TOOL_THRESHOLD_S while
  222. streaming every tool (progress_mode == "all"), append a one-time /verbose hint."""
  223. from gateway.run import _hermes_home, _load_gateway_config
  224. ctx = self._ctx
  225. try:
  226. if (kwargs.get("duration") or 0) >= ctx._LONG_TOOL_THRESHOLD_S and ctx.progress_mode == "all":
  227. from agent.onboarding import TOOL_PROGRESS_FLAG, is_seen, mark_seen, tool_progress_hint_gateway
  228. cfg = _load_gateway_config()
  229. gate_on = is_truthy_value(cfg_get(cfg, "display", "tool_progress_command"), default=False)
  230. if gate_on and not is_seen(cfg, TOOL_PROGRESS_FLAG):
  231. ctx.long_tool_hint_fired[0] = True
  232. ctx.progress_queue.put(tool_progress_hint_gateway())
  233. mark_seen(_hermes_home / "config.yaml", TOOL_PROGRESS_FLAG)
  234. except Exception as err:
  235. logger.debug("tool-progress onboarding hint failed: %s", err)
  236. @staticmethod
  237. def _preview_cap() -> int:
  238. """tool_preview_length (default 40): the one-line preview budget for "all"/"new" modes."""
  239. from agent.display import get_tool_preview_max_len
  240. pl = get_tool_preview_max_len()
  241. return pl if pl > 0 else 40
  242. def _progress_terminal_blocks(self, adapter, tool_name, args, emoji):
  243. """(full, short) fenced blocks for a terminal command on markdown platforms, else (None, None).
  244. No language tag: Slack mrkdwn renders it as a literal first code line. Verbose shows the FULL
  245. command; "all"/"new" truncate to one line capped at ``tool_preview_length``. Consecutive
  246. terminal calls drop the repeated header so back-to-back commands render as adjacent blocks.
  247. """
  248. if not (
  249. getattr(adapter, "supports_code_blocks", False) and tool_name == "terminal" and isinstance(args, dict)
  250. and isinstance(args.get("command"), str) and args["command"].strip()
  251. ):
  252. return None, None
  253. cmd_full = args["command"].rstrip()
  254. header = "" if self._ctx.last_was_terminal_block[0] else t("gateway.progress.tool_head", emoji=emoji, tool=tool_name) + "\n"
  255. cap = self._preview_cap()
  256. lines = cmd_full.splitlines()
  257. cmd_short = lines[0] if lines else cmd_full
  258. if len(cmd_short) > cap:
  259. cmd_short = cmd_short[:cap - 3] + "..."
  260. elif len(lines) > 1:
  261. cmd_short += " ..."
  262. return f"{header}```\n{cmd_full}\n```", f"{header}```\n{cmd_short}\n```"
  263. def _progress_build_message(self, tool_name, preview, args) -> Optional[str]:
  264. """Render the progress line. Verbose mode queues directly (no dedup) and returns None."""
  265. ctx = self._ctx
  266. from agent.display import get_tool_emoji
  267. emoji = get_tool_emoji(tool_name, default="⚙️")
  268. try:
  269. adapter = self._runner._delivery_adapter_for(ctx.source)
  270. except Exception:
  271. adapter = None
  272. code_full, code_short = self._progress_terminal_blocks(adapter, tool_name, args, emoji)
  273. verbose = ctx.progress_mode == "verbose"
  274. code = code_full if verbose else code_short
  275. ctx.last_was_terminal_block[0] = code is not None
  276. if verbose:
  277. if code is None and args:
  278. from agent.display import get_tool_preview_max_len, verbose_tool_args_text
  279. # tool_preview_length 0 (default) = no truncation in verbose mode; the user asked
  280. # for full detail and platform message-length limits handle the rest.
  281. args_str = verbose_tool_args_text(args, get_tool_preview_max_len(),
  282. getattr(adapter, "supports_code_blocks", False))
  283. code = t("gateway.progress.tool_verbose", emoji=emoji, tool=tool_name, keys=list(args.keys()), args=args_str)
  284. elif code is None:
  285. code = (t("gateway.progress.tool_preview", emoji=emoji, tool=tool_name, preview=preview) if preview
  286. else t("gateway.progress.tool_pending", emoji=emoji, tool=tool_name))
  287. ctx.progress_queue.put(code)
  288. return None
  289. if code is not None:
  290. return code
  291. if not preview:
  292. return t("gateway.progress.tool_pending", emoji=emoji, tool=tool_name)
  293. from agent.display import get_tool_verb, prepare_tool_preview, tool_verb_connector, verb_drops_preview
  294. prepared = prepare_tool_preview(tool_name, args, fallback=preview, max_len=self._preview_cap())
  295. preview = adapter.format_tool_preview(prepared) if adapter is not None else prepared.text
  296. # Friendly labels: human-phrased line for built-in tools ("🔍 Searching the web for ...")
  297. # by prefixing the verb onto the computed preview, so the command/url/query is kept.
  298. verb = get_tool_verb(tool_name)
  299. if not verb:
  300. return t("gateway.progress.tool_preview", emoji=emoji, tool=tool_name, preview=preview)
  301. return f"{emoji} {verb}" if verb_drops_preview(tool_name) else f"{emoji} {verb}{tool_verb_connector(tool_name)}{preview}"
  302. def _progress_emit(self, msg: str) -> None:
  303. """Dedup consecutive identical lines (execute_code boilerplate), then route to the native
  304. stream bubble when the consumer accepts tool progress, else the progress queue."""
  305. ctx = self._ctx
  306. sc = self._stream_consumer()
  307. native = sc is not None and getattr(sc, "accepts_tool_progress", False)
  308. if msg == ctx.last_progress_msg[0]:
  309. ctx.repeat_count[0] += 1
  310. if native:
  311. sc.on_tool_progress(_append_progress_repeat_count(msg, ctx.repeat_count[0] + 1))
  312. else:
  313. ctx.progress_queue.put(("__dedup__", msg, ctx.repeat_count[0]))
  314. return
  315. ctx.last_progress_msg[0], ctx.repeat_count[0] = msg, 0
  316. if native:
  317. sc.on_tool_progress(msg)
  318. else:
  319. ctx.progress_queue.put(msg)
  320. # ── Slack-native task cards (progress-queue drain) ──────────────────────────────────────
  321. @dataclasses.dataclass
  322. class _TaskCardState:
  323. """Task-card rail state for ``_send_native_task_card_progress``."""
  324. adapter: Any
  325. tasks: dict[str, dict[str, str]] = dataclasses.field(default_factory=dict)
  326. task_order: list[str] = dataclasses.field(default_factory=list)
  327. fallback_msg_id: Optional[str] = None
  328. native_failed: bool = False
  329. # TERMINAL for the turn, distinct from native_failed: no later publication
  330. # in this turn may deliver task text through the native lane OR the text
  331. # fallback. Two causes, both properties of the destination rather than of
  332. # one attempt: the connector's egress guard refused the chat, or the chat
  333. # cannot host a card (no thread anchor). Declared rather than set
  334. # dynamically so the state is visible where it lives.
  335. publication_suppressed: bool = False
  336. anonymous_seq: int = 0
  337. @staticmethod
  338. def _compact(value: Any, limit: int = 120) -> str:
  339. text = re.sub(r"\s+", " ", str(value or "")).strip()
  340. return text if len(text) <= limit else text[: limit - 3].rstrip() + "..."
  341. def visible_tasks(self) -> list[dict[str, str]]:
  342. return [self.tasks[task_id] for task_id in self.task_order[-8:]]
  343. def fallback_text(self) -> str:
  344. labels = {"in_progress": t("gateway.progress.task_status_running"),
  345. "complete": t("gateway.progress.task_status_complete"),
  346. "error": t("gateway.progress.task_status_error")}
  347. lines = [t("gateway.progress.task_line", title=task["title"], status=labels.get(task["status"], task["status"]))
  348. for task in self.visible_tasks()]
  349. return t("gateway.progress.task_card_title") + "\n" + "\n".join(lines)
  350. def _upsert(self, call_id: str, title: str) -> dict[str, str]:
  351. if call_id not in self.tasks:
  352. self.task_order.append(call_id)
  353. self.tasks[call_id] = {"id": call_id, "title": self._compact(title), "status": "in_progress"}
  354. return self.tasks[call_id]
  355. def apply_event(self, raw: Any) -> bool:
  356. event_type = raw.get("type") if isinstance(raw, dict) else None
  357. if event_type not in {"tool.started", "tool.completed"}:
  358. return False
  359. call_id = str(raw.get("tool_call_id") or "")
  360. if not call_id:
  361. self.anonymous_seq += 1
  362. call_id = f"anonymous_{self.anonymous_seq}"
  363. tool_name = str(raw.get("tool_name") or "tool")
  364. if event_type == "tool.started":
  365. preview = self._compact(raw.get("preview"), 64)
  366. self._upsert(call_id, f"{tool_name} - {preview}" if preview else tool_name)
  367. return True
  368. # Completion-only events are rare but valid on some runtimes; keep their real ID instead
  369. # of guessing a same-name pending call.
  370. task = self.tasks.get(call_id) or self._upsert(call_id, tool_name)
  371. task["status"] = "error" if raw.get("is_error") else "complete"
  372. return True
  373. async def _task_card_send_or_edit_fallback(self, st) -> None:
  374. ctx = self._ctx
  375. text = st.fallback_text()
  376. from gateway.relay.egress import declined_send
  377. if st.publication_suppressed:
  378. return
  379. if st.fallback_msg_id:
  380. result = await st.adapter.edit_message(
  381. chat_id=ctx.source.chat_id, message_id=st.fallback_msg_id, content=text, metadata=ctx._progress_metadata,
  382. )
  383. if getattr(result, "success", False):
  384. return
  385. # P5(b): R5-4 made a declined native CARD terminal but left this
  386. # editable-text fallback: a declined edit fell through to
  387. # _send_progress_text and re-sent the same task text to the refused
  388. # chat. The decline must set the terminal state here too.
  389. if declined_send(result):
  390. logger.warning(
  391. "Task-card fallback edit DECLINED by the connector's egress "
  392. "guard; suppressing progress delivery for the rest of this "
  393. "turn (the destination is not approved)"
  394. )
  395. st.publication_suppressed = True
  396. return
  397. result = await self._send_progress_text(st, text)
  398. if getattr(result, "success", False) and getattr(result, "message_id", None):
  399. st.fallback_msg_id = str(result.message_id)
  400. async def _task_card_publish(self, st) -> None:
  401. ctx = self._ctx
  402. if not st.tasks:
  403. return
  404. if st.publication_suppressed:
  405. # Publication was suppressed earlier in the turn (egress refusal or a chat
  406. # that cannot host a card); every later publication would re-deliver the
  407. # same task text there.
  408. return
  409. # Resolve eligibility in the owning adapter BEFORE transport I/O: a first
  410. # timeout/disconnect must not turn an un-cardable chat into text fallback.
  411. # Optional for older adapters; only an explicit False refuses publication.
  412. destination_supported = getattr(st.adapter, "native_task_card_destination_supported", None)
  413. if callable(destination_supported) and destination_supported(
  414. ctx.source.chat_id, reply_to=ctx._progress_reply_to, metadata=ctx._progress_metadata,
  415. ) is False:
  416. self._task_card_uncardable_destination(st)
  417. if st.publication_suppressed:
  418. return
  419. if not st.native_failed:
  420. result = await st.adapter.send_native_task_card_progress(
  421. chat_id=ctx.source.chat_id, tasks=st.visible_tasks(), title=t("gateway.progress.task_card_title"),
  422. reply_to=ctx._progress_reply_to, metadata=ctx._progress_metadata, fallback_text=st.fallback_text(),
  423. )
  424. if getattr(result, "success", False):
  425. return
  426. # P5(b): an AUTHORIZATION decline is not a broken card lane. The
  427. # fallback below sends the same task text to the same chat, which
  428. # turns a refused card into delivered plain text. Stop the lane
  429. # without re-delivering; the refusal is already logged.
  430. from gateway.relay.egress import declined_send
  431. if declined_send(result):
  432. # TERMINAL, and stored SEPARATELY from native_failed. Reusing
  433. # native_failed suppressed exactly ONE update: the next progress
  434. # event skipped this branch (the lane is already "failed") and
  435. # went straight to the text fallback. A refusal does not expire
  436. # after one tick.
  437. st.publication_suppressed = True
  438. st.native_failed = True
  439. logger.warning(
  440. "Slack native task-card progress DECLINED by the connector's "
  441. "egress guard — suppressing the text fallback for the rest "
  442. "of this turn (the destination is not approved)"
  443. )
  444. return
  445. st.native_failed = True
  446. from gateway.run_turn_runner import _CARD_DESTINATION_REFUSALS
  447. if getattr(result, "error", None) in _CARD_DESTINATION_REFUSALS:
  448. self._task_card_uncardable_destination(st, getattr(result, "error", "unknown error"))
  449. if st.publication_suppressed:
  450. return
  451. else:
  452. logger.warning(
  453. "Slack native task-card progress failed; falling back "
  454. "to an editable text update: %s", getattr(result, "error", "unknown error"),
  455. )
  456. # Once the native rail fails, every later lifecycle event edits the same fallback message.
  457. await self._task_card_send_or_edit_fallback(st)
  458. def _task_card_uncardable_destination(self, st, reason: str = "no thread anchor") -> None:
  459. """The chat cannot host a card (flat DM: no thread anchor) — a property of the destination,
  460. not a transient outage. The text fallback exists to keep a WORKING card lane live through a
  461. transient failure, not to invent text bubbles the operator never asked for: with Slack's tier
  462. default (``tool_progress: off``) the lane goes silent for the turn. An operator who WROTE
  463. ``new``/``all`` asked for text progress, so the editable fallback carries it instead."""
  464. if self._ctx.tool_progress_enabled:
  465. st.native_failed = True
  466. logger.info(
  467. "Slack native task cards are unsupported for this destination (%s); "
  468. "tool progress continues as an editable text update", reason,
  469. )
  470. return
  471. st.publication_suppressed = True
  472. logger.info(
  473. "Slack native task cards are unsupported for this destination (%s); "
  474. "tool progress stays off for this turn", reason,
  475. )
  476. def _task_card_drain(self, st) -> bool:
  477. changed = False
  478. try:
  479. while True:
  480. changed = st.apply_event(self._ctx.progress_queue.get_nowait()) or changed
  481. except queue.Empty:
  482. pass
  483. except Exception:
  484. logger.debug("Slack native progress queue drain failed", exc_info=True)
  485. return changed
  486. async def _send_native_task_card_progress(self, adapter) -> None:
  487. """Drain progress into native cards; supported destinations retain editable fallback.
  488. Unsupported destinations and egress refusals suppress publication, never finalization.
  489. See #29483.
  490. """
  491. ctx = self._ctx
  492. st = self._TaskCardState(adapter)
  493. try:
  494. while ctx._run_still_current():
  495. try:
  496. raw = ctx.progress_queue.get_nowait()
  497. except queue.Empty:
  498. await asyncio.sleep(0.1)
  499. continue
  500. if not self._agent_interrupted() and st.apply_event(raw):
  501. await self._task_card_publish(st)
  502. except asyncio.CancelledError:
  503. if self._task_card_drain(st) and ctx._run_still_current() and not self._agent_interrupted():
  504. await self._task_card_publish(st)
  505. finally:
  506. if hasattr(adapter, "stop_native_task_card_progress"):
  507. # Best-effort on the turn-cleanup path: an escaping transport exception would skip
  508. # final-delivery logic (cleanup awaits catch only CancelledError).
  509. try:
  510. await adapter.stop_native_task_card_progress(
  511. ctx.source.chat_id, reply_to=ctx._progress_reply_to, metadata=ctx._progress_metadata,
  512. )
  513. except asyncio.CancelledError:
  514. raise
  515. except Exception:
  516. logger.debug("task-card stop failed during turn cleanup", exc_info=True)
  517. # ── editable progress bubbles (progress-queue drain) ────────────────────────────────────
  518. @dataclasses.dataclass
  519. class _ProgressEditState:
  520. """Mutable editable-bubble state shared by ``send_progress_messages`` and its helpers."""
  521. adapter: Any
  522. progress_lines: list
  523. progress_msg_id: Any
  524. can_edit: bool
  525. _progress_len_fn: Any
  526. _PROGRESS_TEXT_LIMIT: int
  527. _edit_accepts_metadata: bool
  528. def _progress_edit_state(self, adapter) -> TurnRunner._ProgressEditState:
  529. ctx = self._ctx
  530. len_fn = adapter.message_len_fn if isinstance(adapter, BasePlatformAdapter) else len
  531. try:
  532. raw_limit = int(getattr(adapter, "MAX_MESSAGE_LENGTH", 4000) or 4000)
  533. except Exception: # health: allow BLE001 -- moved unchanged from run_turn_runner.py (main has the same handler): a plugin adapter's odd MAX_MESSAGE_LENGTH falls back to 4000
  534. raw_limit = 4000
  535. # Per-chat resolution (relay adapter fronting N platforms): cap and length unit follow the
  536. # chat's underlying platform; native adapters return their scalar/property unchanged.
  537. if isinstance(adapter, BasePlatformAdapter):
  538. with suppress(Exception):
  539. raw_limit = int(adapter.max_message_length_for_chat(ctx.source.chat_id) or 4000)
  540. len_fn = adapter.message_len_fn_for_chat(ctx.source.chat_id)
  541. return self._ProgressEditState(
  542. adapter=adapter, progress_lines=[], progress_msg_id=None,
  543. # "separate" = one message per tool (pre-v0.9 behavior)
  544. can_edit=ctx.progress_grouping != "separate",
  545. _progress_len_fn=len_fn,
  546. # Leave room for platform quirks / formatting; tiny test adapters keep a usable limit.
  547. _PROGRESS_TEXT_LIMIT=max(1, raw_limit - (64 if raw_limit > 128 else 0)),
  548. # Overflow edits pass metadata (Telegram topic/thread routing) only when edit_message takes it.
  549. _edit_accepts_metadata=bool(ctx._progress_metadata) and _accepts_keyword(adapter.edit_message, "metadata"),
  550. )
  551. async def _edit_progress_message(self, st, message_id: str, content: str):
  552. ctx = self._ctx
  553. kwargs = {"chat_id": ctx.source.chat_id, "message_id": message_id, "content": content}
  554. if getattr(st.adapter, "REQUIRES_EDIT_FINALIZE", False):
  555. kwargs["finalize"] = True
  556. if st._edit_accepts_metadata:
  557. kwargs["metadata"] = ctx._progress_metadata
  558. return await st.adapter.edit_message(**kwargs)
  559. @staticmethod
  560. def _progress_text(lines: list) -> str:
  561. return "\n".join(str(line) for line in lines)
  562. def _split_progress_groups(self, st, lines: list) -> list[list]:
  563. """Partition progress lines into platform-sized editable bubbles."""
  564. groups: list[list] = []
  565. current: list = []
  566. for line in lines:
  567. candidate = current + [line]
  568. if current and st._progress_len_fn(self._progress_text(candidate)) > st._PROGRESS_TEXT_LIMIT:
  569. groups.append(current)
  570. candidate = [line]
  571. current = candidate
  572. return groups + ([current] if current else [])
  573. async def _send_progress_text(self, st, text: str):
  574. ctx = self._ctx
  575. result = await st.adapter.send(
  576. chat_id=ctx.source.chat_id, content=text, reply_to=ctx._progress_reply_to, metadata=ctx._progress_metadata,
  577. )
  578. self._track_progress_result(result)
  579. return result
  580. async def _roll_progress_overflow_if_needed(self, st) -> bool:
  581. """Start fresh editable progress bubbles before a bubble exceeds limit.
  582. Returns True when it delivered/split the buffer or a transient edit failure left it
  583. intact for retry — either way the caller skips the normal send/edit path this tick.
  584. """
  585. if not st.progress_lines or not st.can_edit:
  586. return False
  587. groups = self._split_progress_groups(st, st.progress_lines)
  588. if len(groups) <= 1:
  589. return False
  590. if st.progress_msg_id is not None:
  591. result = await self._edit_progress_message(st, st.progress_msg_id, self._progress_text(groups[0]))
  592. if not result.success:
  593. if getattr(result, "retryable", False):
  594. logger.debug("[%s] Transient overflow edit failure — keeping can_edit=True", st.adapter.name)
  595. return True
  596. st.can_edit = False
  597. # Fall back to the existing non-edit behavior.
  598. return False
  599. groups = groups[1:]
  600. for group in groups:
  601. result = await self._send_progress_text(st, self._progress_text(group))
  602. if result.success and result.message_id:
  603. st.progress_msg_id = result.message_id
  604. # The newest continuation is the only mutable bubble: keep just its lines so later
  605. # edits update it instead of replaying the full transcript into new messages.
  606. st.progress_lines = groups[-1]
  607. return True
  608. @staticmethod
  609. def _is_reset_marker(raw) -> bool:
  610. return isinstance(raw, tuple) and len(raw) >= 1 and raw[0] == "__reset__"
  611. def _reset_progress_bubble(self, st) -> None:
  612. """Content bubble landed — close the tool-progress bubble so the next tool starts fresh
  613. below it; else tool edits hit the ORIGINAL message above (out of order)."""
  614. st.progress_msg_id, st.progress_lines = None, []
  615. self._ctx.last_progress_msg[0], self._ctx.repeat_count[0] = None, 0
  616. def _progress_absorb(self, st, raw) -> Any:
  617. """Fold a queue item into the bubble buffer; returns the line to render this tick."""
  618. if isinstance(raw, tuple) and len(raw) == 3 and raw[0] == "__dedup__":
  619. _, base_msg, count = raw
  620. if not st.progress_lines:
  621. return base_msg
  622. st.progress_lines[-1] = _append_progress_repeat_count(base_msg, count + 1)
  623. return st.progress_lines[-1]
  624. st.progress_lines.append(raw)
  625. return raw
  626. async def _flush_progress_edit(self, st) -> None:
  627. if st.can_edit and st.progress_lines and st.progress_msg_id:
  628. with suppress(Exception):
  629. await self._edit_progress_message(st, st.progress_msg_id, self._progress_text(st.progress_lines))
  630. async def _drain_progress_on_cancel(self, st) -> None:
  631. ctx = self._ctx
  632. with suppress(Exception):
  633. while not ctx.progress_queue.empty():
  634. raw = ctx.progress_queue.get_nowait()
  635. if self._is_reset_marker(raw):
  636. # Content-bubble marker during drain: close the current progress bubble
  637. # and start a fresh one for tool lines that arrived after.
  638. await self._roll_progress_overflow_if_needed(st)
  639. await self._flush_progress_edit(st)
  640. self._reset_progress_bubble(st)
  641. else:
  642. self._progress_absorb(st, raw)
  643. await self._roll_progress_overflow_if_needed(st)
  644. # Final edit with all remaining tools (only if editing works)
  645. if st.can_edit and st.progress_lines and st.progress_msg_id:
  646. await self._roll_progress_overflow_if_needed(st)
  647. await self._flush_progress_edit(st)
  648. async def _progress_restore_typing(self, st) -> None:
  649. ctx = self._ctx
  650. await asyncio.sleep(0.3)
  651. if ctx._run_still_current():
  652. # On this turn's own message, as its refresh: the chat's latest may be a newer one.
  653. await st.adapter.send_typing(ctx.source.chat_id, metadata=typing_metadata_for_turn(
  654. st.adapter, ctx.source.chat_id, ctx.event_message_id, ctx._progress_metadata))
  655. async def _progress_send_or_edit(self, st, msg) -> bool:
  656. """Deliver this tick's bubble. Returns False on a transient edit failure (retry next tick).
  657. Transient network errors (ConnectError, timeouts) must not disable editing; only permanent
  658. failures (not found, permissions) set can_edit=False. Flood control backs off but keeps editing.
  659. """
  660. if st.can_edit and st.progress_msg_id is not None:
  661. result = await self._edit_progress_message(st, st.progress_msg_id, "\n".join(st.progress_lines))
  662. if result.success:
  663. return True
  664. if getattr(result, "retryable", False):
  665. logger.debug("[%s] Transient edit failure — keeping can_edit=True", st.adapter.name)
  666. return False
  667. if any(w in (getattr(result, "error", "") or "").lower() for w in ("flood", "retry after")):
  668. logger.info("[%s] Progress edit flood control, backing off", st.adapter.name)
  669. else:
  670. st.can_edit = False
  671. await self._send_progress_text(st, msg)
  672. return True
  673. # First tool: send all accumulated text as a new message; editing unsupported: just this line.
  674. result = await self._send_progress_text(st, "\n".join(st.progress_lines) if st.can_edit else msg)
  675. if result.success and result.message_id:
  676. st.progress_msg_id = result.message_id
  677. return True
  678. async def send_progress_messages(self):
  679. ctx = self._ctx
  680. adapter = self._runner._delivery_adapter_for(ctx.source) if ctx.progress_queue else None
  681. if not adapter:
  682. return
  683. if ctx._native_slack_task_cards and hasattr(adapter, "send_native_task_card_progress"):
  684. await self._send_native_task_card_progress(adapter)
  685. return
  686. # Skip tool progress for platforms that can't edit messages (e.g. iMessage/BlueBubbles):
  687. # each update would be a separate bubble. getattr, not attribute access: duck-typed
  688. # adapters (test fakes, minimal plugins) may lack edit_message — treated as "can't edit".
  689. adapter_edit = getattr(type(adapter), "edit_message", None)
  690. if adapter_edit is None or adapter_edit is BasePlatformAdapter.edit_message:
  691. self._drain_progress_queue()
  692. return
  693. st = self._progress_edit_state(adapter)
  694. last_edit_ts = 0.0
  695. EDIT_INTERVAL = 1.5 # Minimum seconds between edits (Telegram flood control)
  696. while True:
  697. try:
  698. if not ctx._run_still_current():
  699. self._drain_progress_queue()
  700. return
  701. raw = ctx.progress_queue.get_nowait()
  702. # Drain silently when interrupted: events queued in the window between tool parse
  703. # and interrupt processing should not render as bubbles.
  704. if self._agent_interrupted():
  705. await asyncio.sleep(0)
  706. continue
  707. if self._is_reset_marker(raw):
  708. self._reset_progress_bubble(st)
  709. continue
  710. msg = self._progress_absorb(st, raw)
  711. if not await self._roll_progress_overflow_if_needed(st):
  712. # Throttle edits: batch rapid tool updates into fewer API calls (grammY pattern:
  713. # proactively rate-limit rather than react to 429s). Loop back to drain further
  714. # queued messages before sending a single batched edit.
  715. remaining = EDIT_INTERVAL - (time.monotonic() - last_edit_ts)
  716. if remaining > 0:
  717. await asyncio.sleep(remaining)
  718. continue
  719. if not ctx._run_still_current():
  720. return
  721. if not await self._progress_send_or_edit(st, msg):
  722. continue
  723. last_edit_ts = time.monotonic()
  724. await self._progress_restore_typing(st)
  725. except queue.Empty:
  726. await asyncio.sleep(0.3)
  727. except asyncio.CancelledError:
  728. await self._drain_progress_on_cancel(st)
  729. return
  730. except Exception as e:
  731. logger.error("Progress message error: %s", e)
  732. await asyncio.sleep(1)
  733. # ── ID-bearing lifecycle callbacks (agent thread) ───────────────────────────────────────
  734. def voice_ack_callback(self, call_id, tool_name, args):
  735. """tool_start_callback: speak a one-time ack in the voice channel."""
  736. ctx = self._ctx
  737. if ctx._voice_ack_fired[0] or ctx._voice_ack_guild[0] is None or not ctx._run_still_current():
  738. return
  739. ctx._voice_ack_fired[0] = True
  740. # The bot whose call the guild was resolved on (#139345), not the default profile's.
  741. adapter = self._runner._delivery_adapter_for(ctx.source)
  742. if adapter is None or not hasattr(adapter, "play_ack_in_voice"):
  743. return
  744. try:
  745. self._schedule(
  746. adapter.play_ack_in_voice(ctx._voice_ack_guild[0]), "voice ack scheduling error", loop=ctx._voice_ack_loop,
  747. )
  748. except Exception as err:
  749. logger.debug("voice ack schedule failed: %s", err)
  750. # Slack-native task cards ride agent.tool_start_callback / tool_complete_callback so start and
  751. # completion correlate by the REAL tool-call id; name-correlated progress_callback text events
  752. # would duplicate cards and mispair concurrent calls.
  753. def _native_card_gate(self) -> bool:
  754. ctx = self._ctx
  755. return bool(ctx.progress_queue) and ctx._run_still_current() and not self._agent_interrupted()
  756. # ── Slack-native task cards: ID-bearing lifecycle callbacks (#29483) ── These ride
  757. # agent.tool_start_callback / agent.tool_complete_callback so start/completion events correlate by the
  758. # REAL tool-call id — the name-correlated text events in progress_callback would duplicate cards and
  759. # mispair concurrent calls to the same tool.
  760. def native_tool_start_callback(self, call_id, tool_name, args):
  761. """Queue an ID-correlated native progress start from the agent thread."""
  762. if not self._native_card_gate():
  763. return
  764. from agent.display import build_tool_preview
  765. name = str(tool_name or "tool")
  766. self._ctx.progress_queue.put({
  767. "type": "tool.started", "tool_call_id": str(call_id or ""), "tool_name": name,
  768. "preview": build_tool_preview(name, args or {}, max_len=64) or "",
  769. })
  770. def native_tool_complete_callback(self, call_id, tool_name, args, result):
  771. """Queue the matching native completion using the real tool-call ID."""
  772. if not self._native_card_gate():
  773. return
  774. from agent.display import _detect_tool_failure
  775. name = str(tool_name or "tool")
  776. is_error, _ = _detect_tool_failure(name, result)
  777. self._ctx.progress_queue.put({
  778. "type": "tool.completed", "tool_call_id": str(call_id or ""), "tool_name": name, "is_error": bool(is_error),
  779. })
  780. def combined_tool_start_callback(self, call_id, tool_name, args):
  781. """Compose the voice ack + native task-card start consumers."""
  782. if local_viewer_turn(self):
  783. from gateway import local_viewer_events
  784. local_viewer_events.note_tool_start(self, call_id, tool_name, args)
  785. self._publish_execution("tool.start", _tool_lifecycle_payload(call_id, tool_name, args))
  786. self._publish_api_tool("tool.start", call_id, tool_name, args)
  787. if self._ctx._voice_ack_guild[0] is not None:
  788. self.voice_ack_callback(call_id, tool_name, args)
  789. if self._ctx._native_slack_task_cards:
  790. self.native_tool_start_callback(call_id, tool_name, args)
  791. def combined_tool_complete_callback(self, call_id, tool_name, args, result):
  792. from agent.display import _detect_tool_failure
  793. is_error, _ = _detect_tool_failure(tool_name, result)
  794. owner = self._approval_owner
  795. live = owner[0].sessions.get(owner[1]) if owner is not None else None
  796. # A session's /verbose (gateway/session_busy_controls.py) ships the Result block text.
  797. verbose = live is not None and (getattr(live, "tool_progress_mode", None) or self._ctx.progress_mode) == "verbose"
  798. payload = _tool_complete_payload(call_id, tool_name, args, result, is_error=is_error, verbose=verbose)
  799. if local_viewer_turn(self):
  800. from gateway import local_viewer_events
  801. payload.update(local_viewer_events.complete_fields(self, call_id, tool_name, args, result, is_error=is_error))
  802. self._publish_execution("tool.complete", payload)
  803. if local_viewer_turn(self) and isinstance(payload.get("todos"), list):
  804. # Task state is application data, not tool chrome: the full snapshot, as the TUI gateway emits it.
  805. self._publish_execution("todo.updated", {"todos": payload["todos"], "revision": payload.get("revision", 0)})
  806. self._publish_api_tool("tool.complete", call_id, tool_name, args, result)
  807. if local_viewer_turn(self):
  808. from gateway import local_viewer_events
  809. local_viewer_events.publish_control_if_changed(self)
  810. if self._ctx._native_slack_task_cards:
  811. self.native_tool_complete_callback(call_id, tool_name, args, result)
  812. # ── hook / status bridges (agent thread → gateway loop) ────────────────────────────────
  813. def _step_callback_sync(self, iteration: int, prev_tools: list) -> None:
  814. ctx = self._ctx
  815. if not ctx._run_still_current():
  816. return
  817. self._publish_execution("agent.step", {"iteration": iteration})
  818. if iteration > 1 and local_viewer_turn(self):
  819. # Each step after the first follows a finished API call: main's CLI repainted its status
  820. # bar from the agent's counters right then (the last call is covered at turn end).
  821. from gateway.session_usage import publish_usage
  822. publish_usage(self, ctx.agent_holder[0])
  823. if not ctx._hooks_ref.loaded_hooks:
  824. return
  825. # prev_tools may be list[str] or list[dict] with "name"/"result" keys. Normalise so
  826. # "tool_names" stays backward-compatible for user hooks that do ', '.join(tool_names).
  827. names = [(t.get("name") or "") if isinstance(t, dict) else str(t) for t in (prev_tools or [])]
  828. self._schedule(
  829. ctx._hooks_ref.emit("agent:step", {
  830. "platform": ctx.source.platform.value if ctx.source.platform else "",
  831. "user_id": ctx.source.user_id, "session_id": ctx.session_id,
  832. "iteration": iteration, "tool_names": names, "tools": prev_tools,
  833. }),
  834. "agent:step hook scheduling error",
  835. )
  836. def _event_callback_sync(self, event_type: str, context: dict) -> None:
  837. ctx = self._ctx
  838. try:
  839. asyncio.run_coroutine_threadsafe(ctx._hooks_ref.emit(event_type, context), ctx._loop_for_step)
  840. except Exception as e:
  841. logger.debug("event_callback hook error: %s", e)
  842. def _local_notice_callback_sync(self, notice) -> None:
  843. """``AgentNotice`` -> ``notification.show`` for local viewers (the TUI's payload)."""
  844. from gateway.warning_notifications import is_diagnostic_notice, render_notification
  845. ctx = self._ctx
  846. if ctx.mute_notification_reply or not self._status_live() or not str(notice.text or "").strip():
  847. return
  848. render_notification(lambda: self._publish_execution("notification.show", {
  849. "text": str(notice.text).strip(), "level": notice.level, "kind": notice.kind,
  850. "ttl_ms": notice.ttl_ms, "key": notice.key, "id": notice.id}),
  851. platform=ctx.source.platform, user_config=ctx.user_config, diagnostic=is_diagnostic_notice(notice))
  852. def _local_notice_clear_callback_sync(self, key) -> None:
  853. """Recovery -> ``notification.clear`` for local viewers (main's TUI payload)."""
  854. if key and self._status_live():
  855. self._publish_execution("notification.clear", {"key": str(key)})
  856. def _status_live(self) -> bool:
  857. """Status adapter present and this run is still the current generation."""
  858. return bool(self._ctx._status_adapter) and self._ctx._run_still_current()
  859. def _send_status_text(self, text: str, metadata, log_message: str) -> None:
  860. from gateway.bot_peer_notices import automatic_notices_allowed
  861. ctx = self._ctx
  862. if not automatic_notices_allowed(ctx.source):
  863. return
  864. self._schedule(ctx._status_adapter.send(ctx._status_chat_id, text, metadata=metadata), log_message)
  865. def _attach_session_title_callback(self, agent, ctx) -> None:
  866. """Wire the platform thread-rename lane onto the agent as `_on_session_title`.
  867. The titler runs in the turn prologue, so attach before the run, not after it.
  868. """
  869. try:
  870. # Gateway auto-title failures are not user-actionable, so never surface them as messages;
  871. # overriding the failure sink keeps CLI on _emit_auxiliary_failure while gateway logs debug.
  872. agent._title_failure_callback = lambda task, exc: logger.debug(
  873. "Gateway auto-title failure suppressed (not user-visible): %s: %s", task, exc,
  874. )
  875. session_id = getattr(agent, "session_id", None)
  876. if local_viewer_turn(self):
  877. # Main's CLI repainted its status-bar title when the auto-title landed.
  878. authority, canonical_id, _generation = self._approval_owner
  879. def republish(title, title_source):
  880. from gateway.session_contract import SessionRef
  881. from gateway.session_local import local_session_info
  882. ref = SessionRef(getattr(authority, "profile_id", ""), canonical_id)
  883. authority.sessions[canonical_id].event_stream.publish(
  884. canonical_id, local_session_info(authority, ref), event_type="session.info")
  885. agent._on_session_title = republish
  886. return
  887. runner = self._runner
  888. source = runner._recover_discord_auto_thread_source(ctx.source, ctx.session_key)
  889. # Both lanes spend a rate-limited platform call per title, so they use the model's title
  890. # only (TitleCallback); renaming twice burns Discord's 2-per-10-min budget on a throwaway.
  891. # Relay Discord predicate is shape-only: whether the connector auto-threaded our reply is
  892. # only knowable AFTER delivery, so register eagerly and let the rename lane look up the
  893. # cache at fire time — gating registration on the cache read meant it never registered.
  894. if runner._is_telegram_topic_lane(source):
  895. lane = "_schedule_telegram_topic_title_rename"
  896. elif runner._is_discord_auto_thread_lane(source) or runner._is_relay_discord_channel_lane(source):
  897. lane = "_schedule_discord_semantic_thread_rename"
  898. else:
  899. return
  900. agent._on_session_title = lambda title, title_source: (
  901. title_source == "llm" and getattr(runner, lane)(source, session_id, title)
  902. )
  903. except Exception:
  904. logger.debug("Failed to attach session title callback", exc_info=True)
  905. def _status_callback_sync(self, event_type: str, message: str) -> None:
  906. from gateway.run import _prepare_gateway_status_message, _redact_gateway_user_facing_secrets, _send_or_update_status_coro
  907. from gateway.warning_notifications import is_warning_status, render_notification
  908. ctx = self._ctx
  909. if ctx.mute_notification_reply or not self._status_live():
  910. return
  911. # Lifecycle diagnostics (including provider fallback notices) are UI affordances for a
  912. # human caller. Sending them to a known bot peer can create a new inbound turn and a loop.
  913. from gateway.bot_peer_notices import automatic_notices_allowed
  914. if not automatic_notices_allowed(ctx.source):
  915. logger.debug("status_callback suppressed for bot-authored message: %s", event_type)
  916. return
  917. prepared = _prepare_gateway_status_message(ctx.source.platform, event_type, message)
  918. if prepared is None:
  919. logger.debug(
  920. "status_callback suppressed for %s/%s: %s",
  921. ctx.source.platform.value if ctx.source.platform else "unknown", event_type,
  922. _redact_gateway_user_facing_secrets(str(message or ""))[:160],
  923. )
  924. return
  925. def present():
  926. if local_viewer_turn(self):
  927. self._publish_execution("status.update", {"kind": _viewer_status_kind(event_type, prepared),
  928. "text": prepared})
  929. return
  930. fut = self._schedule(
  931. _send_or_update_status_coro(ctx._status_adapter, ctx._status_chat_id, event_type, prepared, ctx._status_thread_metadata),
  932. f"status_callback ({event_type}) scheduling error",
  933. )
  934. if fut is not None and ctx._cleanup_progress:
  935. fut.add_done_callback(self._track_future_cleanup_id)
  936. render_notification(present, platform=ctx.source.platform, user_config=ctx.user_config,
  937. diagnostic=is_warning_status(event_type, message))
  938. def local_viewer_turn(runner) -> bool:
  939. """A local route's viewers read the canonical event stream; ``LocalSessionAdapter.send``
  940. publishes nothing, so status and notices go to that stream instead. So does a conversation its
  941. chat moved past (gateway/session_detached.py): it delivers through that same adapter."""
  942. source = getattr(runner._ctx, "source", None) if getattr(runner, "_approval_owner", None) is not None else None
  943. from gateway.session_detached import detached_route_of
  944. return getattr(source, "platform", None) == Platform.LOCAL or detached_route_of(source) is not None
  945. def _viewer_status_kind(kind, text):
  946. """The TUI's ``status.update`` kind: auto-compaction progress is re-tagged ``compacting``."""
  947. from agent.conversation_compression import is_compaction_progress_status
  948. return "compacting" if kind == "lifecycle" and is_compaction_progress_status(text) else str(kind)