terminal_tool_result.py 15 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278
  1. """Foreground result post-processing for the terminal tool (cwd dual-write,
  2. sudo handling, transform hook, truncation, ANSI strip, redaction, exit-code
  3. notes/hints, spill redaction, verification evidence) + exit-code tables. Lazy
  4. ``tools.terminal_tool`` lookups keep the origin's monkeypatch points authoritative.
  5. """
  6. import json
  7. import logging
  8. import os
  9. import re
  10. import signal
  11. from contextlib import contextmanager
  12. from pathlib import Path
  13. from typing import Any, Optional
  14. logger = logging.getLogger("tools.terminal_tool")
  15. @contextmanager
  16. def _quiet(label: str):
  17. """Best-effort block: swallow any exception, logging it at DEBUG."""
  18. try:
  19. yield
  20. except Exception:
  21. logger.debug("%s failed", label, exc_info=True)
  22. # Signal-death notes keyed by signum, used for both ``-signum`` (subprocess)
  23. # and ``128+signum`` (shell) encodings. Curated, not exhaustive, so a
  24. # legitimate application exit code is never mislabeled; 130/SIGINT is owned
  25. # by the executor's interrupt-marker path and excluded.
  26. _SIGNAL_EXIT_NOTES: dict[int, str] = {
  27. 3: "SIGQUIT (quit from keyboard)",
  28. 4: "SIGILL (illegal instruction — corrupt binary or wrong architecture)",
  29. 6: "SIGABRT (abort — assertion failure, fatal runtime error, or glibc abort)",
  30. 7: "SIGBUS (bus error — misaligned or unmapped memory access)",
  31. 8: "SIGFPE (fatal arithmetic error, e.g. integer division by zero)",
  32. 9: "SIGKILL — often the kernel OOM killer on memory exhaustion, or an explicit kill -9",
  33. 11: "SIGSEGV (segmentation fault — the program crashed)",
  34. 13: "SIGPIPE (wrote to a closed pipe — e.g. output piped to a reader that exited)",
  35. 15: "SIGTERM (terminated — kill/timeout or shutdown requested it to stop)",
  36. 24: "SIGXCPU (CPU time limit exceeded)",
  37. 25: "SIGXFSZ (file size limit exceeded)",
  38. }
  39. def _interpret_signal_exit(exit_code: int) -> str | None:
  40. """Note for a signal-termination exit code, or None. Negative codes are
  41. definite (subprocess semantics); 128+signum is the shell convention and a
  42. program *can* exit 139 itself, so those notes hedge with "usually"."""
  43. if exit_code < 0:
  44. signum = -exit_code
  45. if signum == 2: # SIGINT — executor's interrupt-marker path owns it
  46. return None
  47. if note := _SIGNAL_EXIT_NOTES.get(signum):
  48. return f"Command terminated by signal {signum}: {note}"
  49. try:
  50. name = signal.Signals(signum).name
  51. except ValueError:
  52. name = f"signal {signum}"
  53. return f"Command terminated by {name} (signal {signum})"
  54. if exit_code > 128 and (note := _SIGNAL_EXIT_NOTES.get(exit_code - 128)):
  55. return (f"Exit code {exit_code} usually means the command was "
  56. f"terminated by signal {exit_code - 128}: {note}")
  57. return None
  58. # Informational non-zero exit codes per base command.
  59. _EXIT_CODE_SEMANTICS: dict[str, dict[int, str]] = {
  60. **{key: {1: "No matches found (not an error)"} for key in ("grep", "egrep", "fgrep", "rg", "ag", "ack")},
  61. **{key: {1: "Files differ (expected, not an error)"} for key in ("diff", "colordiff")},
  62. **{key: {1: "Condition evaluated to false (expected, not an error)"} for key in ("test", "[")},
  63. "find": {1: "Some directories were inaccessible (partial results may still be valid)"},
  64. "curl": {6: "Could not resolve host", 7: "Failed to connect to host",
  65. 22: "HTTP response code indicated error (e.g. 404, 500)", 28: "Operation timed out"},
  66. "git": {1: "Non-zero exit (often normal — e.g. 'git diff' returns 1 when files differ)"},
  67. }
  68. # Model-facing warning attached when the backend replaced its container/sandbox
  69. # mid-command (out-of-band removal, terminal sandbox state). Persistent-filesystem
  70. # state was restored, but background processes and anything outside the synced
  71. # paths are gone (ported from lobehub/lobehub#19329).
  72. _ENV_RECREATED_NOTE = (
  73. "The execution environment was recreated while running this command "
  74. "(the previous container/sandbox was gone). Persistent files were restored "
  75. "where the backend supports it, but background processes and any files "
  76. "outside persisted paths from earlier commands may be lost — verify state "
  77. "before relying on prior work."
  78. )
  79. def _interpret_exit_code(command: str, exit_code: int) -> str | None:
  80. """Note for a non-zero exit code that is informational rather than an
  81. error (grep=1 "no matches", diff=1 "files differ", signal deaths), so the
  82. model doesn't burn turns investigating it. None when 0 or a real error."""
  83. if exit_code == 0:
  84. return None
  85. if (signal_note := _interpret_signal_exit(exit_code)) is not None:
  86. # Signal terminations (ported from Kilo-Org/kilocode#12698, adapted to Python semantics). Two shapes
  87. # reach the model: * negative codes — subprocess.Popen reports a signal-killed process as
  88. # ``-signum`` (definite signal death), and * 128+signum — the conventional shell encoding when bash
  89. # reports a signal-killed child (heuristic: a program *can* ``exit 139``, so these notes say
  90. # "usually"). Without a note the model sees a bare ``exit_code=-9`` or ``137`` and burns turns
  91. # re-running or mis-diagnosing (137 = OOM kill is the big one). 130/SIGINT is deliberately absent:
  92. # the executor has bespoke interrupt-marker handling for rc=130.
  93. return signal_note
  94. # The last command of a pipeline/chain determines the exit code; base
  95. # command = its first word that isn't a VAR=val assignment, basename'd.
  96. segments = re.split(r'\s*(?:\|\||&&|[|;])\s*', command)
  97. last_segment = (segments[-1] if segments else command).strip()
  98. base_cmd = next((w.split("/")[-1] for w in last_segment.split()
  99. if "=" not in w or w.startswith("-")), "")
  100. return _EXIT_CODE_SEMANTICS.get(base_cmd, {}).get(exit_code)
  101. def _sudo_annotations(command: str, output: str, env_type: str) -> tuple[str, bool, bool]:
  102. """Sudo failure handling -> (output, auth_failed, cache_cleared)."""
  103. import tools.terminal_tool as tt
  104. from tools.terminal_tool_sudo import (
  105. _handle_sudo_failure, _invalidate_cached_sudo_on_auth_failure, _no_sudo_user,
  106. _sudo_wrong_password_failure,
  107. )
  108. from utils import env_var_enabled
  109. output = _handle_sudo_failure(output, env_type)
  110. auth_failed = _sudo_wrong_password_failure(output)
  111. cache_cleared = _invalidate_cached_sudo_on_auth_failure(command, output)
  112. can_reprompt = cache_cleared and (
  113. tt._get_sudo_password_callback() is not None or env_var_enabled("HERMES_INTERACTIVE")
  114. ) and not _no_sudo_user()
  115. if can_reprompt:
  116. output += ("\n\n⚠️ Sudo authentication failed — cached password "
  117. "cleared. You will be prompted again on the next sudo command.")
  118. return output, auth_failed, cache_cleared
  119. def _apply_output_transform_hook(command, output, returncode, task_id, env_type) -> str:
  120. """Plugin output-transform seam (fail-open; first string result wins).
  121. Replacements are still subject to the output limit applied afterwards."""
  122. with _quiet("transform_terminal_output hook"):
  123. from hermes_cli.lifecycle import invoke_hook
  124. from tools.approval_context import _approval_tool_call_id
  125. # Concurrent terminal calls in one turn must gate per call, not collapse into one;
  126. # an empty id is treated as "no identity" by the hook gate.
  127. results = invoke_hook("transform_terminal_output", command=command, output=output,
  128. returncode=returncode, task_id=task_id or "", env_type=env_type,
  129. tool_call_id=_approval_tool_call_id.get())
  130. output = next((r for r in results if isinstance(r, str)), output)
  131. return output
  132. def _truncate_head_tail(output: str) -> str:
  133. from tools.tool_output_limits import get_max_bytes
  134. from tools.tool_output_truncate import truncate_head_tail
  135. return truncate_head_tail(output, get_max_bytes())
  136. def _failure_hint(command: str, returncode: int, output: str, exit_note) -> Optional[str]:
  137. """Recovery hints for well-known failure shapes (tools/terminal_hints.py);
  138. on rc=0, warn when a pipeline tail / `|| echo` may mask an upstream
  139. failure and the output carries strong failure indicators (advisory only)."""
  140. with _quiet("failure hint"):
  141. from tools import terminal_hints
  142. if returncode == 0:
  143. return terminal_hints.annotate_masked_success(command, output)
  144. if not exit_note:
  145. return terminal_hints.annotate_failure(command, returncode, output)
  146. return None
  147. def _redact_spill_file(path, total_chars, command) -> list[tuple[str, Any]]:
  148. """Spill handle so the model can read the omitted middle instead of
  149. re-running. The collector wrote it raw; redact it with the same pass so no
  150. secret persists unmasked on disk. On failure drop the handle (and file)."""
  151. if not path:
  152. return []
  153. try:
  154. from agent.redact import redact_terminal_output
  155. from tools.ansi_strip import strip_ansi
  156. from tools.spill_safety import write_text_exclusive
  157. raw_spill = Path(path).read_text(encoding="utf-8-sig", errors="replace")
  158. # lstat-checked unlink + exclusive create: the redacted copy can't
  159. # be diverted through a symlink planted since the collector's write.
  160. write_text_exclusive(Path(path), redact_terminal_output(strip_ansi(raw_spill), command),
  161. private=True, overwrite=True, errors="replace")
  162. except Exception:
  163. logger.debug("spill redaction failed; dropping spill handle", exc_info=True)
  164. with _quiet("spill unlink"):
  165. Path(path).unlink()
  166. return []
  167. note = ("Output exceeded the capture window (head+tail shown). "
  168. f"Full output ({total_chars:,} chars) saved to {path} — search it with "
  169. "search_files or page it with read_file instead of re-running the command.")
  170. return [("output_total_chars", total_chars), ("full_output_path", path), ("truncation_note", note)]
  171. def _verification_evidence(command, cwd, session_id, returncode, output, pipeline_status=None) -> Optional[dict]:
  172. with _quiet("verification evidence recording"):
  173. from agent.verification_evidence import record_terminal_result
  174. evidence = record_terminal_result(command=command, cwd=cwd, session_id=session_id,
  175. exit_code=returncode, output=output,
  176. pipeline_status=pipeline_status)
  177. if evidence:
  178. return {k: evidence.get(k) for k in ("status", "kind", "scope", "canonical_command")}
  179. return None
  180. def finalize_foreground_result(
  181. *, command: str, result: dict, env: Any, env_type: str, effective_task_id: str,
  182. task_id: Optional[str], session_id: Optional[str], session_key: str,
  183. workdir: Optional[str], command_cwd: Optional[str], approval_note: Optional[str],
  184. ) -> str:
  185. """Turn a raw ``env.execute`` result into the tool's JSON result string."""
  186. from tools.terminal_tool import record_session_cwd
  187. # Record the cwd this command finished in as THIS session's durable cwd —
  188. # only when the command actually reported it (an interrupted/killed command
  189. # emits no marker, and env.cwd then holds another session's directory), and
  190. # never for a transient per-command ``workdir`` (would hijack the session cwd
  191. # for every later command). Prefer the result's own cwd; env.cwd is shared
  192. # mutable compat state kept as fallback for third-party providers.
  193. observed_cwd = None
  194. if (result or {}).get("cwd_observed"):
  195. observed_cwd = (result or {}).get("cwd") or getattr(env, "cwd", None)
  196. if not workdir and observed_cwd:
  197. record_session_cwd(session_key, observed_cwd)
  198. output = result.get("output", "")
  199. returncode = result.get("returncode", 0)
  200. output, sudo_auth_failed, sudo_cache_cleared = _sudo_annotations(command, output, env_type)
  201. output = _apply_output_transform_hook(command, output, returncode, effective_task_id, env_type)
  202. output = _truncate_head_tail(output)
  203. # Strip ANSI so the model never copies escapes into file writes, then
  204. # redact secrets; redact_terminal_output is command-aware (env-dump
  205. # commands get the KEY=value pass, source/config dumps skip it).
  206. from agent.redact import redact_terminal_output
  207. from tools.ansi_strip import strip_ansi
  208. output = strip_ansi(output)
  209. # For source/config dumps (MAX_TOKENS=100, "apiKey": "x" fixtures, postgresql:// f-string templates) the
  210. # ENV/JSON/template passes are skipped to avoid false positives (code_file=True). But for env-dump
  211. # commands (env/printenv/set/export/declare) the output IS a KEY=value credential dump, so
  212. # redact_terminal_output runs the ENV pass (code_file=False) to mask opaque tokens with no vendor
  213. # prefix. Real prefixes, auth headers, JWTs, private keys are masked in both modes. See issue #43025.
  214. output = redact_terminal_output(output.strip(), command) if output else ""
  215. exit_note = _interpret_exit_code(command, returncode)
  216. failure_hint = _failure_hint(command, returncode, output, exit_note)
  217. # cwd echo when the command changed directory (gated on the observation
  218. # flag so an interrupted command can't echo another session's cwd).
  219. changed_cwd = None
  220. with _quiet("cwd comparison"):
  221. if observed_cwd and command_cwd and os.path.realpath(str(observed_cwd)) != os.path.realpath(str(command_cwd)):
  222. changed_cwd = str(observed_cwd)
  223. # rc=130 is an interrupt only with the executor's marker — a command can
  224. # legitimately `exit 130` itself. An interrupted approved run keeps the
  225. # audit note but must never imply success.
  226. if approval_note and returncode == 130 and "[Command interrupted]" in output:
  227. approval_note = approval_note.rstrip(".") + ", then interrupted."
  228. result_dict = {"output": output, "exit_code": returncode, "error": None}
  229. # Optional fields in observable JSON key order; None means "omit". Spill
  230. # metadata is present only when output overflowed the capture window.
  231. optional_fields: list[tuple[str, Any]] = [
  232. ("cwd", changed_cwd),
  233. ("environment_recreated", _ENV_RECREATED_NOTE if result.get("environment_recreated") else None),
  234. *_redact_spill_file(result.get("full_output_path"), result.get("output_total_chars"), command),
  235. ("verification_evidence", _verification_evidence(
  236. command, command_cwd, session_id or task_id or effective_task_id or "default",
  237. returncode, output, result.get("pipeline_status"))),
  238. ("approval", approval_note or None),
  239. ("exit_code_meaning", exit_note or None),
  240. ("hint", failure_hint or None),
  241. ("sudo_auth_failed", True if sudo_auth_failed else None),
  242. ("sudo_cache_cleared", True if sudo_cache_cleared else None),
  243. ]
  244. for key, value in optional_fields:
  245. if value is not None:
  246. result_dict[key] = value
  247. return json.dumps(result_dict, ensure_ascii=False)