status_output.py 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278
  1. """User-facing status / warning / notice plumbing for ``AIAgent``.
  2. Safe printing, quiet-mode gating, deduped context-overflow warnings, and the buffered retry
  3. chatter that is shown only when every retry/fallback is exhausted.
  4. Extracted from ``run_agent.py``; every method resolves through ``AIAgent``'s MRO unchanged.
  5. """
  6. import logging
  7. import sys
  8. from agent.i18n import t
  9. from agent.session_activity import ActivityProvenance
  10. # Same logger name as the origin module so log records / caplog filters are unchanged.
  11. logger = logging.getLogger("run_agent")
  12. def deliver_kept_startup_notices(agent) -> None:
  13. """Hand *agent*'s turn the notices a migration kept for the home (a gateway start, a CLI resolution, an
  14. agent's own start, in any process) when someone sees them: the CLI's print sink or a driver's
  15. ``notice_callback``. A cron run, subagent, curator, kanban worker or background fork leaves them in the
  16. home for the next such turn: claiming them there would drop them."""
  17. from agent.side_question_lease import is_unattended_turn
  18. if getattr(agent, "suppress_status_output", False) or is_unattended_turn(agent):
  19. return
  20. if (getattr(agent, "platform", None) or "cli") != "cli" and not getattr(agent, "notice_callback", None):
  21. return
  22. from hermes_cli.left_core_migration import claim_kept_notices
  23. for message in claim_kept_notices():
  24. agent._emit_startup_warning(message)
  25. class StatusOutputMixin:
  26. """Status/warning/notice emission and retry-chatter buffering (see module docstring)."""
  27. def _safe_print(self, *args, diagnostic: bool = False, **kwargs):
  28. """Print that swallows broken pipes / closed stdout (headless stdout can vanish mid-session);
  29. routes through ``self._print_fn`` so the CLI can inject an ANSI-aware renderer."""
  30. if getattr(self, "_mute_notification_reply", False):
  31. return
  32. if diagnostic and not self._warning_presentation_enabled():
  33. return
  34. try:
  35. (self._print_fn or print)(*args, **kwargs)
  36. except (OSError, ValueError):
  37. pass
  38. def _vprint(self, *args, force: bool = False, diagnostic: bool = False, **kwargs):
  39. """Verbose print — suppressed while tokens are streaming (allowed during tool execution) and after
  40. the main response; ``force=True`` bypasses both. ``suppress_status_output`` (``hermes chat -q``) wins."""
  41. if getattr(self, "suppress_status_output", False):
  42. return
  43. if diagnostic and not self._warning_presentation_enabled():
  44. return
  45. if force or not (getattr(self, "_mute_post_response", False) or (self._has_stream_consumers() and not self._executing_tools)):
  46. self._safe_print(*args, **kwargs)
  47. def _should_start_quiet_spinner(self) -> bool:
  48. """True when quiet-mode spinner output has a safe sink (``_print_fn`` or a real TTY); a raw spinner
  49. on a non-TTY stdout can corrupt protocol streams (ACP JSON-RPC)."""
  50. if self._print_fn is not None:
  51. return True
  52. try:
  53. return bool(sys.stdout.isatty())
  54. except (AttributeError, ValueError, OSError):
  55. return False
  56. def _should_emit_quiet_tool_messages(self) -> bool:
  57. """True when quiet-mode tool summaries should print directly (CLI, no callback owns rendering);
  58. ``suppress_status_output`` always wins so ``[tool]``/``[done]`` never land in captured stdout.
  59. ``suppress_status_output`` (the strict machine-readable mode used by ``hermes chat -Q``) always
  60. wins: those flows neutralize the rendering callbacks, and without this gate the "no callback owns
  61. rendering" fallback would print ``[tool]``/``[done]`` spinner lines into the captured stdout it
  62. exists to keep clean (#93220).
  63. """
  64. if getattr(self, "suppress_status_output", False):
  65. return False
  66. return self.quiet_mode and not self.tool_progress_callback and getattr(self, "platform", "") == "cli"
  67. def _call_callback(self, name: str, *args, origin: str) -> None:
  68. """Invoke ``self.<name>(*args)`` if set, swallowing errors — a driver callback must never break the loop."""
  69. cb = getattr(self, name, None)
  70. if cb:
  71. try:
  72. cb(*args)
  73. except Exception:
  74. logger.debug("%s error in %s", name, origin, exc_info=True)
  75. def _emit_status_kind(self, kind: str, message: str, *, origin: str) -> None:
  76. """Print to the CLI (``_vprint(force=True)``) and forward to ``status_callback(kind, message)``. Never raises."""
  77. from gateway.warning_notifications import is_warning_status
  78. try:
  79. if not is_warning_status(kind, message) or self._warning_presentation_enabled():
  80. self._vprint(f"{self.log_prefix}{message}", force=True)
  81. except Exception:
  82. pass
  83. self._call_callback("status_callback", kind, message, origin=origin)
  84. def _warning_presentation_enabled(self) -> bool:
  85. from gateway.warning_notifications import warning_notifications_enabled
  86. try:
  87. return warning_notifications_enabled(
  88. getattr(self, "_notification_platform", getattr(self, "platform", "cli")),
  89. getattr(self, "_notification_config", None),
  90. )
  91. except Exception:
  92. # A presentation preference must never turn a recoverable notice into a failed turn.
  93. return True
  94. def _emit_diagnostic_status(self, message: str) -> None:
  95. """A diagnostic on the lifecycle rail, without changing legacy formatting."""
  96. from gateway.warning_notifications import DiagnosticText
  97. self._emit_status(DiagnosticText(message))
  98. def _emit_status(self, message: str) -> None:
  99. """Emit a lifecycle status message (CLI + gateway ``status_callback``)."""
  100. self._emit_status_kind("lifecycle", message, origin="_emit_status")
  101. def _emit_warning(self, message: str) -> None:
  102. """Emit a user-visible warning for degraded side paths where the turn continues but the user must know."""
  103. self._emit_status_kind("warn", message, origin="_emit_warning")
  104. def _emit_startup_warning(self, message: str) -> None:
  105. """A warning raised during ``__init__`` that the user must see (e.g. a memory provider that
  106. could not be recovered). The CLI prints it; a CLI session the gateway hosts (``hermes chat``) has
  107. no viewer sink until its first turn wires one, so the line waits for that turn. Other drivers get
  108. a sticky warn ``AgentNotice``: Desktop renders notices but no warn-kind ``status.update``, and the
  109. messaging gateway wires its callbacks per turn, after init, so a notice raised before then waits
  110. for :meth:`_replay_startup_warnings` on the first turn."""
  111. message = message.strip()
  112. if (getattr(self, "platform", None) or "cli") == "cli":
  113. if getattr(self, "_gateway_session_key", None):
  114. self._pending_startup_prints = [*getattr(self, "_pending_startup_prints", ()), message]
  115. return
  116. self._emit_warning(message)
  117. return
  118. import zlib
  119. from agent.credits_tracker import AgentNotice
  120. key = f"startup-warning.{zlib.crc32(message.encode()):08x}"
  121. level = "success" if message.startswith("✓") else "warn" # a recovered provider is good news
  122. notice = AgentNotice(text=message, level=level, kind="sticky", key=key, id=key)
  123. if getattr(self, "notice_callback", None):
  124. self._emit_notice(notice)
  125. else:
  126. self._pending_startup_notices = [*getattr(self, "_pending_startup_notices", ()), notice]
  127. def _replay_startup_warnings(self) -> None:
  128. prints = getattr(self, "_pending_startup_prints", None)
  129. if prints:
  130. self._pending_startup_prints = []
  131. for message in prints:
  132. self._emit_warning(message)
  133. pending = getattr(self, "_pending_startup_notices", None)
  134. if pending and getattr(self, "notice_callback", None):
  135. self._pending_startup_notices = []
  136. for notice in pending:
  137. self._emit_notice(notice)
  138. def _warn_context_overflow_blocked(self, reason: str, preflight_tokens: int, threshold_tokens: int) -> None:
  139. """Warn (deduped on the block *kind* — ``cooldown`` / ``ineffective`` — not the countdown string;
  140. cleared by ``_clear_context_overflow_warn``) when context is over the threshold but compression is blocked."""
  141. _warn_kind = (reason or "unknown").split(":", 1)[0]
  142. _warn_key = ("ctx_overflow_blocked", _warn_kind)
  143. if getattr(self, "_last_ctx_overflow_warn", None) == _warn_key:
  144. return
  145. self._last_ctx_overflow_warn = _warn_key
  146. from agent.conversation_compression import CONTEXT_OVERFLOW_BLOCKED_WARNING_TEMPLATE
  147. # cooldown + anti-thrash (ineffective) are both "compression blocked".
  148. if _warn_kind in ("cooldown", "ineffective"):
  149. self._touch_activity(f"compression blocked ({reason})", provenance=ActivityProvenance.AGENT_COMPRESSION_COOLDOWN)
  150. self._emit_warning(CONTEXT_OVERFLOW_BLOCKED_WARNING_TEMPLATE.format(
  151. tokens=preflight_tokens, threshold=threshold_tokens, reason=reason,
  152. ))
  153. def _warn_uncompressed_context_overflow(self, preflight_tokens: int, context_length: int) -> None:
  154. """Deduped warning when uncompressed context exceeds the model limit; points the user at /compact.
  155. When compression is explicitly disabled (compression.enabled: false), long sessions can grow past
  156. the model context window with no compression to shrink them (#89297). Surface an actionable warning
  157. so the user knows to run /compact or enable compression.
  158. """
  159. _warn_key = ("uncompressed_ctx_overflow", context_length)
  160. if getattr(self, "_last_ctx_overflow_warn", None) != _warn_key:
  161. self._last_ctx_overflow_warn = _warn_key
  162. self._emit_warning(t("display.notice.uncompressed_context_overflow",
  163. tokens=f"{preflight_tokens:,}", context_length=f"{context_length:,}"))
  164. def _clear_context_overflow_warn(self) -> None:
  165. """Reset the blocked-overflow warning dedup so it can re-fire on the next blocked turn."""
  166. self._last_ctx_overflow_warn = None
  167. def _emit_notice(self, notice) -> None:
  168. """Fire a structured ``AgentNotice`` to the active driver (TUI / CLI)."""
  169. self._call_callback("notice_callback", notice, origin="_emit_notice")
  170. def _emit_notice_clear(self, key: str) -> None:
  171. """Clear a previously-fired sticky notice by ``key`` (e.g. on recovery)."""
  172. self._call_callback("notice_clear_callback", key, origin="_emit_notice_clear")
  173. def _emit_wait_notice(self, text: str) -> None:
  174. """Rewrite the live status line (CLI spinner, TUI ``thinking.delta``, gateway activity)
  175. so long provider waits are not an anonymous spinner."""
  176. self._touch_activity(text)
  177. self._call_callback("thinking_callback", text, origin="_emit_wait_notice")
  178. def _emit_diagnostic_wait(self, text: str) -> None:
  179. from gateway.warning_notifications import DiagnosticText
  180. self._emit_wait_notice(DiagnosticText(text))
  181. # ── Buffered retry/fallback status: shown only when every retry/fallback is exhausted, dropped on
  182. # success. Backend logs are unaffected (every site still logs). ──
  183. def _buffer_retry_message(self, kind: str, message: str) -> None:
  184. """Buffer a retry/fallback line as ``(kind, text)`` until we know whether the turn recovered.
  185. ``kind`` is ``"status"`` (replays via ``_emit_status``), ``"vprint"`` (``_vprint(force=True)``) or
  186. ``"warn"`` (``_emit_warning``).
  187. """
  188. buf = getattr(self, "_retry_status_buffer", None)
  189. if buf is None:
  190. buf = self._retry_status_buffer = []
  191. buf.append((kind, message))
  192. def _buffer_status(self, message: str) -> None:
  193. self._buffer_retry_message("status", message)
  194. def _buffer_diagnostic_status(self, message: str) -> None:
  195. from gateway.warning_notifications import DiagnosticText
  196. self._buffer_status(DiagnosticText(message))
  197. def _buffer_vprint(self, message: str) -> None:
  198. self._buffer_retry_message("vprint", message)
  199. def _clear_status_buffer(self) -> None:
  200. """Drop buffered retry messages — call on successful recovery."""
  201. buf = getattr(self, "_retry_status_buffer", None)
  202. if buf:
  203. buf.clear()
  204. def _emit_pending_fallback_notice(self) -> None:
  205. """Surface the one-shot fallback-switch notice on successful recovery: a provider switch is durable
  206. state operators must see, unlike the retry chatter ``_clear_status_buffer`` drops. Emitted once, then
  207. cleared; on terminal failure the buffered switch line is flushed instead (``_flush_status_buffer``)."""
  208. notice = getattr(self, "_pending_fallback_notice", None)
  209. if not notice:
  210. return
  211. # Clear before emitting so a (swallowed) callback error can't leave a stale re-emit.
  212. self._pending_fallback_notice = None
  213. for item in notice if isinstance(notice, list) else [notice]:
  214. try:
  215. self._emit_diagnostic_status(item)
  216. except Exception:
  217. # One surface failure must not hide later switches from the same chain.
  218. continue
  219. def _flush_status_buffer(self) -> None:
  220. """Emit buffered retry messages — call on terminal failure so the user sees what was tried."""
  221. # The buffered trace already carries the switch line; drop the one-shot notice.
  222. self._pending_fallback_notice = None
  223. buf = getattr(self, "_retry_status_buffer", None)
  224. if not buf:
  225. return
  226. # Drain first so a callback exception doesn't double-emit.
  227. messages = list(buf)
  228. buf.clear()
  229. replay = {"status": self._emit_status, "warn": self._emit_warning}
  230. for kind, msg in messages:
  231. try:
  232. if kind in replay:
  233. replay[kind](msg)
  234. else:
  235. if self._warning_presentation_enabled():
  236. self._vprint(f"{self.log_prefix}{msg}", force=True)
  237. except Exception:
  238. pass