turn_explainers.py 13 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275
  1. """File-mutation verification footers and turn-completion explanations for ``AIAgent``.
  2. The footer tells the model (and user) when a claimed file mutation did not land; the explainer
  3. summarises why a turn ended without a final answer. Every method resolves through ``AIAgent``'s MRO.
  4. """
  5. import os
  6. import re
  7. from contextlib import suppress
  8. from typing import Any, Dict, Optional
  9. from agent.i18n import t
  10. from agent.tool_dispatch_helpers import (
  11. _extract_error_preview, _extract_file_mutation_targets, _extract_landed_file_mutation_paths
  12. )
  13. from agent.tool_result_classification import (
  14. FILE_MUTATING_TOOL_NAMES as _FILE_MUTATING_TOOLS, file_mutation_result_landed
  15. )
  16. # One text for "the model produced nothing after retries" on every surface (CLI explainer,
  17. # gateway ``(empty)`` rewrite, desktop). English source kept as a constant for importers; surfaces
  18. # rendering to a human use ``empty_response_explanation`` (``explainer.empty_response``).
  19. EMPTY_RESPONSE_EXPLANATION = (
  20. "{model} didn't produce a reply this time, even after retries. "
  21. "Send `continue` to try again, or switch models with /model."
  22. )
  23. def empty_response_explanation(model: str = "") -> str:
  24. """Localized ``EMPTY_RESPONSE_EXPLANATION`` with the model name (or "The model") filled in."""
  25. return t("explainer.empty_response", model=model or t("explainer.shared.the_model"))
  26. # Exact ``turn_exit_reason`` → catalog key of the explanation body (prefixed with the no-reply marker).
  27. _EXIT_REASON_EXPLANATIONS: dict[str, str] = {
  28. "empty_response_exhausted": "explainer.empty_response",
  29. "all_retries_exhausted_no_response": "explainer.exit.all_retries_exhausted_no_response",
  30. "partial_stream_recovery": "explainer.exit.partial_stream_recovery",
  31. "fallback_prior_turn_content": "explainer.exit.fallback_prior_turn_content",
  32. "redirect_restart_limit_exceeded": "explainer.exit.redirect_restart_limit_exceeded",
  33. "rebuilt_restart_limit_exceeded": "explainer.exit.rebuilt_restart_limit_exceeded",
  34. "budget_exhausted": "explainer.exit.budget_exhausted",
  35. "ollama_runtime_context_too_small": "explainer.exit.ollama_runtime_context_too_small",
  36. "pending_tool_result": "explainer.exit.pending_tool_result",
  37. }
  38. # Parameterised reasons (``max_iterations_reached(3/3)`` …) matched by prefix.
  39. # ``interrupted_during_api_call(<issuer>)`` names a system watchdog (#112647).
  40. _EXIT_REASON_PREFIX_EXPLANATIONS = tuple(
  41. (prefix, f"explainer.exit.{prefix}") for prefix in ("interrupted_during_api_call", "max_iterations_reached", "error_near_max_iterations", "repeated_outer_errors")
  42. )
  43. # ``session_persistence_failed`` refined by the classified cause (lock contention ≠ disk full).
  44. _PERSISTENCE_CAUSES = frozenset({"compression", "compression_closed", "turn_lease", "session_row_missing", "locked", "replaced", "deleted_wal", "corrupt", "fts_index", "disk"})
  45. def _persistence_explanation_key(cause: Optional[str]) -> str:
  46. return f"explainer.persistence.{cause}" if cause in _PERSISTENCE_CAUSES else "explainer.persistence.default"
  47. def _file_mutation_identity(path: str, task_id: Optional[str]) -> str:
  48. """One key per on-disk target: the file tools' task-resolved absolute path, case-folded
  49. on case-insensitive hosts. A failure recorded as ``notes.md`` and the write that later
  50. lands as ``/repo/notes.md`` (or ``Notes.md`` on Windows) must meet on the same key."""
  51. try:
  52. from tools.file_tools_paths import _resolve_path_for_task
  53. resolved = str(_resolve_path_for_task(path, task_id or "default"))
  54. except Exception:
  55. resolved = os.path.abspath(os.path.expanduser(path))
  56. return os.path.normcase(os.path.normpath(resolved))
  57. def _file_stat_signature(identity: str) -> Optional[tuple]:
  58. """``(mtime_ns, size)`` of the target, ``None`` when it does not exist (or cannot be read)."""
  59. try:
  60. st = os.stat(identity)
  61. except OSError:
  62. return None
  63. return (st.st_mtime_ns, st.st_size)
  64. def _display_flag_enabled(agent, *, env_var: str, config_key: str, cache_attr: str) -> bool:
  65. """``display.<config_key>`` (default True), cached per agent on ``cache_attr``.
  66. ``env_var`` overrides on every call and is never cached. Reads the persisted config.yaml
  67. so gateway and CLI share the setting; ``load_config`` is imported lazily (startup cycle,
  68. and tests patch it at ``hermes_cli.config``). Any failure → True (safe default: on)."""
  69. try:
  70. env = os.environ.get(env_var)
  71. if env is not None:
  72. return env.strip().lower() not in {"0", "false", "no", "off"}
  73. cached = getattr(agent, cache_attr, None)
  74. if cached is not None:
  75. return cached
  76. try:
  77. from hermes_cli.config import load_config as _load_config
  78. _cfg = _load_config() or {}
  79. except Exception:
  80. _cfg = {}
  81. _display = _cfg.get("display") if isinstance(_cfg, dict) else None
  82. if isinstance(_display, dict) and config_key in _display:
  83. enabled = bool(_display.get(config_key))
  84. else:
  85. enabled = True
  86. setattr(agent, cache_attr, enabled)
  87. return enabled
  88. except Exception:
  89. return True
  90. class TurnExplainersMixin:
  91. """File-mutation failure footer + turn-completion explainer (see module docstring)."""
  92. def _record_file_mutation_result(
  93. self, tool_name: str, args: dict[str, Any], result: Any, is_error: bool,
  94. *, task_id: Optional[str] = None,
  95. ) -> None:
  96. """Record a ``write_file`` / ``patch`` outcome for the turn-end verifier.
  97. Failures store ``{path: {error_preview, tool, identity, stat}}`` keyed by the model's
  98. spelling; ``identity`` is the resolved on-disk target and ``stat`` its signature at
  99. failure time. A later success on the same identity (any spelling) removes the entry.
  100. No-op when the per-turn state dict is not initialised (tool dispatched outside ``run_conversation``).
  101. """
  102. if tool_name not in _FILE_MUTATING_TOOLS:
  103. return
  104. state = getattr(self, "_turn_failed_file_mutations", None)
  105. if state is None:
  106. return
  107. targets = _extract_file_mutation_targets(tool_name, args)
  108. if not targets:
  109. return
  110. landed = file_mutation_result_landed(tool_name, result)
  111. if landed:
  112. landed_paths = _extract_landed_file_mutation_paths(tool_name, args, result)
  113. changed = getattr(self, "_turn_file_mutation_paths", None)
  114. if changed is not None:
  115. changed.update(landed_paths)
  116. # Feed the checkpoint agent-write ledger so /rollback's safe mode can tell
  117. # Hermes-authored content from later user hand-edits.
  118. mgr = getattr(self, "_checkpoint_mgr", None)
  119. if mgr is not None and getattr(mgr, "enabled", False):
  120. from tools.file_tools_paths import container_backend_for_task
  121. if container_backend_for_task(task_id or "default") is None: # container paths carry no host ledger entry
  122. for _p in landed_paths:
  123. with suppress(Exception):
  124. mgr.record_agent_write(_p)
  125. if is_error and not landed:
  126. # Keep the FIRST error per path unless a later success replaces it.
  127. preview = _extract_error_preview(result)
  128. for path in targets:
  129. identity = _file_mutation_identity(path, task_id)
  130. state.setdefault(path, {
  131. "tool": tool_name, "error_preview": preview,
  132. "identity": identity, "stat": _file_stat_signature(identity),
  133. })
  134. else:
  135. cleared = {
  136. _file_mutation_identity(p, task_id)
  137. for p in (landed_paths if landed else targets)
  138. }
  139. for path, info in list(state.items()):
  140. if info.get("identity", _file_mutation_identity(path, task_id)) in cleared:
  141. state.pop(path, None)
  142. @staticmethod
  143. def _file_mutations_still_failed(failed: dict[str, dict[str, Any]]) -> dict[str, dict[str, Any]]:
  144. """Drop entries whose target changed on disk since the failed call.
  145. The recorder only sees write_file/patch receipts; a terminal redirect or an
  146. execute_code write leaves none. Re-checking the stat signature at turn end keeps
  147. the footer from listing a file that was in fact modified later this turn. Entries
  148. without a snapshot (hand-built dicts) are kept as-is.
  149. """
  150. return {
  151. path: info for path, info in failed.items()
  152. if "stat" not in info or _file_stat_signature(info["identity"]) == info["stat"]
  153. }
  154. def _file_mutation_verifier_enabled(self) -> bool:
  155. """``display.file_mutation_verifier`` / ``HERMES_FILE_MUTATION_VERIFIER`` (a patchable seam)."""
  156. return _display_flag_enabled(
  157. self, env_var="HERMES_FILE_MUTATION_VERIFIER", config_key="file_mutation_verifier",
  158. cache_attr="_file_mutation_verifier_enabled_cache",
  159. )
  160. def _turn_completion_explainer_enabled(self) -> bool:
  161. """``display.turn_completion_explainer`` / ``HERMES_TURN_COMPLETION_EXPLAINER``."""
  162. return _display_flag_enabled(
  163. self, env_var="HERMES_TURN_COMPLETION_EXPLAINER", config_key="turn_completion_explainer",
  164. cache_attr="_turn_completion_explainer_enabled_cache",
  165. )
  166. # Bare absolute / home / Windows-drive paths in a footer line. Mirrors the gateway's
  167. # extract_local_files detector so anything it WOULD auto-attach is backticked first (#35584).
  168. _FOOTER_PATH_RE = re.compile(
  169. r"(?<![/:\w.`])(?:~/|/|[A-Za-z]:[/\\])(?:[\w.\-]+[/\\])*[\w.\-]+\.[\w]+",
  170. )
  171. @classmethod
  172. def _neutralize_footer_paths(cls, text: str) -> str:
  173. """Backtick bare file paths so the gateway's ``extract_local_files`` never auto-attaches them.
  174. The extractor skips inline-code spans; already-backticked paths are left alone (no double-wrap).
  175. """
  176. if not text:
  177. return text
  178. return cls._FOOTER_PATH_RE.sub(lambda m: f"`{m.group(0)}`", text)
  179. @classmethod
  180. def _format_file_mutation_failure_footer(cls, failed: dict[str, dict[str, Any]]) -> str:
  181. """Render the per-turn failed-mutation dict as a user-facing footer.
  182. Up to 10 paths with their first error preview, then an overflow count; "" when nothing failed.
  183. Every path is backtick-wrapped via ``_neutralize_footer_paths`` so protected files cannot be
  184. auto-delivered.
  185. """
  186. if not failed:
  187. return ""
  188. lines = [t("explainer.file_mutation.header", count=len(failed))]
  189. shown = list(failed.items())[:10]
  190. for path, info in shown:
  191. preview = (info.get("error_preview") or "").strip()
  192. tool = info.get("tool") or "patch"
  193. lines.append(t("explainer.file_mutation.entry", path=path, tool=tool,
  194. preview=preview or t("explainer.file_mutation.failed")))
  195. remaining = len(failed) - len(shown)
  196. if remaining > 0:
  197. lines.append(t("explainer.shared.and_more", count=remaining))
  198. # Neutralize paths the preview echoed; the lookbehind prevents double-wrapping the bullet path.
  199. return cls._neutralize_footer_paths("\n".join(lines))
  200. @staticmethod
  201. def _format_turn_completion_explanation(
  202. turn_exit_reason: str, persistence_cause: Optional[str] = None, db_path=None, model: str = "",
  203. ) -> str:
  204. """User-facing explanation for an abnormal turn ending, or "" for normal / unknown reasons.
  205. ``text_response(...)`` is the healthy terminal; unknown/diagnostic-only reasons (e.g.
  206. ``guardrail_halt``, which surfaces its own message) are not second-guessed.
  207. """
  208. if not turn_exit_reason:
  209. return ""
  210. reason = str(turn_exit_reason)
  211. if reason.startswith("text_response"):
  212. return ""
  213. key = _EXIT_REASON_EXPLANATIONS.get(reason)
  214. if key is None:
  215. for prefix, prefix_key in _EXIT_REASON_PREFIX_EXPLANATIONS:
  216. if reason.startswith(prefix):
  217. key = prefix_key
  218. break
  219. if key is not None:
  220. body = t(key, model=model or t("explainer.shared.the_model"))
  221. elif reason == "session_persistence_failed":
  222. from hermes_constants import display_hermes_home, profile_cli_selector
  223. from hermes_state_errors import STORAGE_RECOVERY_DOCS_URL
  224. # Copy-pasteable, so pin every `hermes` command to the profile whose store failed:
  225. # a multi-profile backend (Desktop serve) hosts sessions whose state.db is NOT the
  226. # process default, and a bare `hermes` follows active_profile (#105887).
  227. fill: dict[str, str] = {
  228. "home": display_hermes_home(), "profile_arg": profile_cli_selector(),
  229. "recovery_docs": STORAGE_RECOVERY_DOCS_URL, "db_path": "", "backups_dir": "",
  230. }
  231. if persistence_cause in ("corrupt", "fts_index"):
  232. from hermes_constants import get_default_hermes_root
  233. from hermes_state import _default_db_path
  234. fill["db_path"] = str(db_path or _default_db_path())
  235. fill["backups_dir"] = str(get_default_hermes_root() / "backups")
  236. body = t(_persistence_explanation_key(persistence_cause), **fill)
  237. else:
  238. body = None
  239. return t("explainer.no_reply_prefix") + body if body else ""