code_execution_tool.py 50 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972
  1. #!/usr/bin/env python3
  2. """Code Execution Tool -- Programmatic Tool Calling (PTC).
  3. The LLM writes a Python script that calls Hermes tools via RPC, collapsing
  4. multi-step tool chains into one inference turn; only the script's stdout returns
  5. to the LLM. Local backend: a persistent per-conversation session kernel
  6. (tools/code_kernel.py) over a Unix socket (loopback TCP on Windows). Remote
  7. backends: a remote session kernel (tools/code_kernel_remote.py) falling open to a
  8. per-call script ship, tool calls as request files polled via env.execute()
  9. (needs Python 3 on the backend). Siblings: tools/code_execution_env.py (env
  10. scrubbing, interpreter/cwd), tools/code_execution_rpc.py (RPC servers).
  11. """
  12. import json
  13. import logging
  14. import os
  15. import re
  16. import secrets
  17. import shlex
  18. import subprocess
  19. import tempfile
  20. import threading
  21. import time
  22. import uuid
  23. from typing import Any, Dict, List, Optional, Tuple
  24. from tools.thread_context import propagate_context_to_thread
  25. from tools.registry import registry, tool_error
  26. from hermes_time import get_timezone_name
  27. from tools.code_execution_env import _resolve_child_cwd, _resolve_child_python
  28. from tools.code_execution_rpc import (
  29. _execute_checked, _private_dirs_cmd, _remote_write, _rpc_poll_loop, tool_errors_since,
  30. )
  31. from tools.tool_output_truncate import head_tail_split, truncation_notice
  32. logger = logging.getLogger(__name__)
  33. # Loopback TCP replaces AF_UNIX on Windows, so execute_code runs on every platform Hermes does.
  34. SANDBOX_AVAILABLE = True
  35. # Tools allowed inside the sandbox; ∩ the session's enabled tools decides which stubs are generated.
  36. SANDBOX_ALLOWED_TOOLS = frozenset([
  37. "web_search", "web_extract", "read_file", "write_file", "search_files", "patch", "terminal",
  38. ])
  39. # Resource limit defaults (overridable via config.yaml → code_execution.*)
  40. DEFAULT_TIMEOUT = 300 # 5 minutes
  41. DEFAULT_MAX_TOOL_CALLS = 50
  42. MAX_STDOUT_BYTES = 50_000 # 50 KB
  43. MAX_STDERR_BYTES = 10_000 # 10 KB
  44. # Hard ceiling on the spilled file (as web_tools' MAX_STORED_TEXT_CHARS): a runaway print loop must not fill the disk.
  45. MAX_SPILLED_STDOUT_BYTES = 5_000_000
  46. def _truncate_stdout_text(stdout_text: str) -> tuple[str, dict[str, Any]]:
  47. """Cap stdout by bytes (40% head / 60% tail) with explicit truncation metadata: byte counts
  48. ride alongside the textual marker because a client layer can miss or re-truncate it. The
  49. omitted middle is spilled to cache/exec and the result carries the path (recover-don't-rerun)."""
  50. stdout_bytes = stdout_text.encode("utf-8", errors="replace")
  51. total = len(stdout_bytes)
  52. captured = min(total, MAX_STDOUT_BYTES)
  53. metadata: dict[str, Any] = {"stdout_truncated": total > captured, "stdout_bytes_captured": captured,
  54. "stdout_bytes_total": total, "stdout_bytes_omitted": total - captured}
  55. if total <= MAX_STDOUT_BYTES:
  56. return stdout_bytes.decode("utf-8", errors="replace"), metadata
  57. head_bytes, tail_bytes = head_tail_split(MAX_STDOUT_BYTES)
  58. text = (stdout_bytes[:head_bytes].decode("utf-8", errors="replace")
  59. + truncation_notice(total - captured, total, unit="bytes")
  60. + stdout_bytes[-tail_bytes:].decode("utf-8", errors="replace"))
  61. metadata["warning"] = ("execute_code stdout was truncated; the script did run, but only "
  62. "the captured head/tail output is included. Re-run only with "
  63. "narrower output if the omitted data is required.")
  64. spill_path = _spill_full_stdout(stdout_text)
  65. if spill_path:
  66. metadata["stdout_spill_path"] = spill_path
  67. metadata["warning"] = ("execute_code stdout was truncated (head/tail shown); the "
  68. f"script did run. FULL output saved to {spill_path} — page it "
  69. f'with read_file(path="{spill_path}", offset=...) instead of re-running.')
  70. return text, metadata
  71. def _spill_full_stdout(stdout_text: str) -> Optional[str]:
  72. """Write full stdout to cache/exec; return its path (None on failure — best-effort,
  73. the truncated inline output is still returned). Keyed by content digest so identical
  74. reruns coalesce; the dir rides the cache/web remote bind-mount list (credential_files)."""
  75. try:
  76. import hashlib
  77. from hermes_constants import get_hermes_dir
  78. from tools.spill_safety import write_text_exclusive
  79. if len(stdout_text) > MAX_SPILLED_STDOUT_BYTES:
  80. stdout_text = (stdout_text[:MAX_SPILLED_STDOUT_BYTES]
  81. + f"\n\n[... spill capped at {MAX_SPILLED_STDOUT_BYTES:,} bytes ...]")
  82. cache_dir = get_hermes_dir("cache/exec", "exec_spill")
  83. cache_dir.mkdir(parents=True, exist_ok=True)
  84. digest = hashlib.sha256(stdout_text.encode("utf-8", errors="replace")).hexdigest()[:12]
  85. path = cache_dir / f"stdout-{digest}.txt"
  86. write_text_exclusive(path, stdout_text, private=False, overwrite=True)
  87. return str(path)
  88. except Exception as exc:
  89. logger.debug("Failed to spill execute_code stdout: %s", exc)
  90. return None
  91. def check_sandbox_requirements() -> bool:
  92. """check_fn: available unless the vercel_sandbox backend fails its own checks."""
  93. if not SANDBOX_AVAILABLE:
  94. return False
  95. try:
  96. from tools.terminal_tool import _get_env_config
  97. from tools.terminal_tool_backends import _check_vercel_sandbox_requirements
  98. config = _get_env_config()
  99. except Exception:
  100. logger.debug("Could not resolve terminal config for execute_code availability", exc_info=True)
  101. return False
  102. return config.get("env_type") != "vercel_sandbox" or _check_vercel_sandbox_requirements(config)
  103. # ---- hermes_tools.py code generator ----
  104. # Per-tool stub templates: (signature, docstring, args_dict_expr — the JSON payload sent over RPC).
  105. _TOOL_STUBS = {
  106. "web_search": ("query: str, limit: int = 5",
  107. '"""Search the web. Returns dict with data.web list of {url, title, description}."""',
  108. '{"query": query, "limit": limit}'),
  109. "web_extract": ("urls: list, char_limit: int = None",
  110. '"""Extract content from URLs (no LLM summarization). Returns dict with results list of {url, title, content, error}. Pages over char_limit (default 15000) are head+tail truncated with the full text stored on disk; the content footer gives the path. content is markdown."""',
  111. '{"urls": urls, "char_limit": char_limit}'),
  112. "read_file": ("path: str, offset: int = 1, limit: int = 2000",
  113. '"""Read a file (1-indexed lines). Returns dict with "content" and "total_lines"."""',
  114. '{"path": path, "offset": offset, "limit": limit}'),
  115. "write_file": ("path: str, content: str, cross_profile: bool = False",
  116. '"""Write content to a file (always overwrites). Returns dict with status."""',
  117. '{"path": path, "content": content, "cross_profile": cross_profile}'),
  118. "search_files": ('pattern: str, target: str = "content", path: str = ".", file_glob: str = None, limit: int = 50, offset: int = 0, output_mode: str = "content", context: int = 0, order: str = "discovery"',
  119. '"""Search file contents (target="content") or find files by name (target="files"). Returns dict with "matches"."""',
  120. '{"pattern": pattern, "target": target, "path": path, "file_glob": file_glob, "limit": limit, "offset": offset, "output_mode": output_mode, "context": context, "order": order}'),
  121. "patch": ('path: str = None, old_string: str = None, new_string: str = None, replace_all: bool = False, mode: str = "replace", patch: str = None, cross_profile: bool = False',
  122. '"""Targeted find-and-replace (mode="replace") or V4A multi-file patches (mode="patch"). Returns dict with status."""',
  123. '{"path": path, "old_string": old_string, "new_string": new_string, "replace_all": replace_all, "mode": mode, "patch": patch, "cross_profile": cross_profile}'),
  124. "terminal": ("command: str, timeout: int = None, workdir: str = None",
  125. '"""Run a shell command (foreground only). Returns dict with "output" and "exit_code"."""',
  126. '{"command": command, "timeout": timeout, "workdir": workdir}'),
  127. }
  128. def _missing_hermes_tools_import_hint(m, enabled_tools) -> str:
  129. missing = m.group(1)
  130. if missing in {"json_parse", "shell_quote", "retry"}:
  131. return (f"Import helpers with `from hermes_tools import {missing}`. "
  132. "If that import failed, the generated module may be stale or another "
  133. "hermes_tools may be first on sys.path. Check hermes_tools.__file__ "
  134. "and retry with reset=true.")
  135. available = sorted(SANDBOX_ALLOWED_TOOLS & set(enabled_tools or SANDBOX_ALLOWED_TOOLS))
  136. return (f"'{missing}' is not available inside the execute_code sandbox. "
  137. f"Importable tools here: {', '.join(available)}. For anything "
  138. "else, use the normal tool call instead of execute_code.")
  139. # (regex, formatter(match, enabled_tools)) — first match wins. Production mining (state.db) ranked
  140. # these as the top execute_code failure classes: hermes_tools import misuse, missing helper
  141. # imports, treating tool results as strings, importing third-party packages absent from the sandbox.
  142. _FAILURE_HINT_RULES = (
  143. (r"cannot import name '(\w+)' from 'hermes_tools'", _missing_hermes_tools_import_hint),
  144. (r"NameError: name '(json_parse|shell_quote|retry)' is not defined",
  145. lambda m, _: f"Import {m.group(1)} before calling it: "
  146. f"from hermes_tools import {m.group(1)}"),
  147. (r"ModuleNotFoundError: No module named '([\w.]+)'",
  148. lambda m, _: f"'{m.group(1)}' is not installed in the sandbox interpreter. "
  149. "Use Python stdlib inside execute_code, or run the code via "
  150. "terminal() with the project venv's python instead."),
  151. (r"TypeError: string indices must be integers|AttributeError: 'str' object has no attribute 'get'",
  152. lambda m, _: "Tool functions in the sandbox return DICTS (already parsed) — "
  153. "do not json.loads() them or index them like strings. Example: read_file(path)['content']."),
  154. )
  155. def _sandbox_failure_hint(stderr_text: str, enabled_tools=None) -> Optional[str]:
  156. """Map well-known sandbox script failures to one actionable recovery hint
  157. (bounded scan, first match wins, never raises)."""
  158. if not stderr_text:
  159. return None
  160. window = stderr_text[:4000]
  161. try:
  162. for pattern, fmt in _FAILURE_HINT_RULES:
  163. m = re.search(pattern, window)
  164. if m:
  165. return fmt(m, enabled_tools)
  166. except Exception:
  167. return None
  168. return None
  169. def generate_hermes_tools_module(enabled_tools: list[str],
  170. transport: str = "uds") -> str:
  171. """Source of the hermes_tools.py stub module for SANDBOX_ALLOWED_TOOLS ∩ *enabled_tools*.
  172. ``transport``: ``"uds"`` (local socket client) or ``"file"`` (file RPC, remote backends)."""
  173. header = _FILE_TRANSPORT_HEADER if transport == "file" else _UDS_TRANSPORT_HEADER
  174. return header + "\n".join(
  175. f"def {name}({sig}):\n {doc}\n return _call({name!r}, {args_expr})\n"
  176. for name, (sig, doc, args_expr) in sorted(_TOOL_STUBS.items()) if name in set(enabled_tools)
  177. )
  178. # ---- Shared helpers section (embedded in both transport headers) ----------
  179. _COMMON_HELPERS = '''\
  180. # ---------------------------------------------------------------------------
  181. # Convenience helpers (avoid common scripting pitfalls)
  182. # ---------------------------------------------------------------------------
  183. def json_parse(text: str):
  184. """Parse JSON tolerant of control characters and UTF-8 BOM (strict=False).
  185. Use this instead of json.loads() when parsing output from terminal()
  186. or web_extract() that may contain raw tabs/newlines in strings,
  187. or from tools/files that prepend a UTF-8 BOM (salvage #57870, credit @woxinwuhen713-bit)."""
  188. if isinstance(text, str) and text.startswith("\ufeff"):
  189. text = text[1:]
  190. return json.loads(text, strict=False)
  191. def shell_quote(s: str) -> str:
  192. """Shell-escape a string for safe interpolation into commands.
  193. Use this when inserting dynamic content into terminal() commands:
  194. terminal(f"echo {shell_quote(user_input)}")
  195. """
  196. return shlex.quote(s)
  197. def retry(fn, max_attempts=3, delay=2):
  198. """Retry a function up to max_attempts times with exponential backoff.
  199. Use for transient failures (network errors, API rate limits):
  200. result = retry(lambda: terminal("gh issue list ..."))
  201. """
  202. last_err = None
  203. for attempt in range(max_attempts):
  204. try:
  205. return fn()
  206. except Exception as e:
  207. last_err = e
  208. if attempt < max_attempts - 1:
  209. time.sleep(delay * (2 ** attempt))
  210. raise last_err
  211. '''
  212. # ---- UDS transport (local backend) ---------------------------------------
  213. _UDS_TRANSPORT_HEADER = '''\
  214. """Auto-generated Hermes tools RPC stubs."""
  215. import json, os, socket, shlex, threading, time
  216. _sock = None
  217. # The RPC server handles a single client connection serially and has no
  218. # request-id in the protocol, so concurrent _call() invocations from multiple
  219. # threads (e.g. ThreadPoolExecutor) would race on the shared socket and get
  220. # each other's responses. Serialize the entire send+recv round-trip.
  221. _call_lock = threading.Lock()
  222. ''' + _COMMON_HELPERS + '''\
  223. def _connect():
  224. """Connect to the parent's RPC server via the transport it picked.
  225. HERMES_RPC_SOCKET can be either:
  226. - a filesystem path (POSIX Unix domain socket — the default on
  227. Linux and macOS)
  228. - a string of the form ``tcp://127.0.0.1:<port>`` (Windows, where
  229. AF_UNIX is unreliable — the parent falls back to loopback TCP)
  230. """
  231. global _sock
  232. if _sock is None:
  233. endpoint = os.environ["HERMES_RPC_SOCKET"]
  234. if endpoint.startswith("tcp://"):
  235. # tcp://host:port (host is always 127.0.0.1 in practice — we
  236. # only bind loopback server-side)
  237. _host_port = endpoint[len("tcp://"):]
  238. _host, _, _port = _host_port.rpartition(":")
  239. _sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
  240. _sock.connect((_host or "127.0.0.1", int(_port)))
  241. else:
  242. _sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
  243. _sock.connect(endpoint)
  244. _sock.settimeout(300)
  245. return _sock
  246. def _call(tool_name, args):
  247. """Send a tool call to the parent process and return the parsed result."""
  248. request = json.dumps({
  249. "tool": tool_name,
  250. "args": args,
  251. "token": os.environ.get("HERMES_RPC_TOKEN", ""),
  252. }) + "\\n"
  253. # Session kernels outlive the RPC server's 300s idle window, so their
  254. # connection can be legitimately gone by the next cell. The server
  255. # re-accepts (HERMES_RPC_PERSISTENT=1); retry once on a fresh socket.
  256. _attempts = 2 if os.environ.get("HERMES_RPC_PERSISTENT") == "1" else 1
  257. with _call_lock:
  258. for _attempt in range(_attempts):
  259. try:
  260. conn = _connect()
  261. conn.sendall(request.encode())
  262. buf = b""
  263. while True:
  264. chunk = conn.recv(65536)
  265. if not chunk:
  266. raise RuntimeError("Agent process disconnected")
  267. buf += chunk
  268. if buf.endswith(b"\\n"):
  269. break
  270. break
  271. except (OSError, RuntimeError):
  272. global _sock
  273. try:
  274. if _sock is not None:
  275. _sock.close()
  276. except OSError:
  277. pass
  278. _sock = None
  279. if _attempt + 1 >= _attempts:
  280. raise
  281. raw = buf.decode().strip()
  282. result = json.loads(raw)
  283. if isinstance(result, str):
  284. try:
  285. return json.loads(result)
  286. except (json.JSONDecodeError, TypeError):
  287. return result
  288. return result
  289. '''
  290. # ---- File-based transport (remote backends) -------------------------------
  291. _FILE_TRANSPORT_HEADER = '''\
  292. """Auto-generated Hermes tools RPC stubs (file-based transport)."""
  293. import json, os, shlex, tempfile, threading, time
  294. _RPC_DIR = os.environ.get("HERMES_RPC_DIR") or os.path.join(tempfile.gettempdir(), "hermes_rpc")
  295. _seq = 0
  296. # `_seq += 1` is not atomic (read-modify-write), so concurrent _call()
  297. # invocations from multiple threads could allocate the same sequence number
  298. # and clobber each other's request files. Guard seq allocation with a lock.
  299. _seq_lock = threading.Lock()
  300. ''' + _COMMON_HELPERS + '''\
  301. def _call(tool_name, args):
  302. """Send a tool call request via file-based RPC and wait for response."""
  303. global _seq
  304. with _seq_lock:
  305. _seq += 1
  306. seq = _seq
  307. seq_str = f"{seq:06d}"
  308. req_file = os.path.join(_RPC_DIR, f"req_{seq_str}")
  309. res_file = os.path.join(_RPC_DIR, f"res_{seq_str}")
  310. # Write request atomically (write to .tmp, then rename).
  311. # encoding="utf-8" is critical: on Windows-hosted remote backends
  312. # (or any non-UTF-8 locale) the default open() mode would mangle
  313. # non-ASCII chars in tool args when encoding them as JSON.
  314. tmp = req_file + ".tmp"
  315. # The request carries the RPC token and tool args: owner-only even under a
  316. # permissive process umask.
  317. fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
  318. with os.fdopen(fd, "w", encoding="utf-8") as f:
  319. json.dump({
  320. "tool": tool_name,
  321. "args": args,
  322. "seq": seq,
  323. "token": os.environ.get("HERMES_RPC_TOKEN", ""),
  324. }, f)
  325. os.rename(tmp, req_file)
  326. # Wait for response with adaptive polling
  327. deadline = time.monotonic() + 300 # 5-minute timeout per tool call
  328. poll_interval = 0.05 # Start at 50ms
  329. while not os.path.exists(res_file):
  330. if time.monotonic() > deadline:
  331. raise RuntimeError(f"RPC timeout: no response for {tool_name} after 300s")
  332. time.sleep(poll_interval)
  333. poll_interval = min(poll_interval * 1.2, 0.25) # Back off to 250ms
  334. with open(res_file, encoding="utf-8") as f:
  335. raw = f.read()
  336. # Clean up response file
  337. try:
  338. os.unlink(res_file)
  339. except OSError:
  340. pass
  341. result = json.loads(raw)
  342. if isinstance(result, str):
  343. try:
  344. return json.loads(result)
  345. except (json.JSONDecodeError, TypeError):
  346. return result
  347. return result
  348. '''
  349. # ---- Remote execution support (file-based RPC via terminal backend) ----
  350. def _get_or_create_env(task_id: str):
  351. """``(env, env_type)`` — the environment the terminal/file tools share for *task_id*, created on
  352. first use (same double-checked per-task lock pattern as file_tools._get_file_ops)."""
  353. from tools.terminal_tool_backends import (_container_config_from_config, _create_environment,
  354. _local_config_from_config, _ssh_config_from_config)
  355. from tools.terminal_tool import (
  356. _active_environments, _env_lock, _get_env_config, _last_activity,
  357. _start_cleanup_thread, _creation_locks, _creation_locks_lock, _task_env_overrides,
  358. _resolve_container_task_id, _resolve_task_host_cwd, _is_container_backend, _select_image,
  359. )
  360. effective_task_id = _resolve_container_task_id(task_id)
  361. def _cached():
  362. with _env_lock:
  363. env = _active_environments.get(effective_task_id)
  364. if env is not None:
  365. _last_activity[effective_task_id] = time.time()
  366. return env
  367. env = _cached()
  368. if env is not None:
  369. return env, _get_env_config()["env_type"]
  370. with _creation_locks_lock:
  371. task_lock = _creation_locks.setdefault(effective_task_id, threading.Lock())
  372. with task_lock:
  373. env = _cached()
  374. if env is not None:
  375. return env, _get_env_config()["env_type"]
  376. config = _get_env_config()
  377. env_type = config["env_type"]
  378. overrides = _task_env_overrides.get(effective_task_id, {})
  379. container_config = None
  380. if _is_container_backend(env_type):
  381. # Shared shaper: execute_code's own key subset dropped docker_extra_args / docker_forward_env /
  382. # docker_env, so a sandbox created from this path lost the operator's configured settings.
  383. container_config = _container_config_from_config(config)
  384. logger.info("Creating new %s environment for execute_code task %s...",
  385. env_type, effective_task_id[:8])
  386. env = _create_environment(
  387. env_type=env_type, image=_select_image(env_type, overrides, config),
  388. cwd=overrides.get("cwd") or config["cwd"], timeout=config["timeout"],
  389. ssh_config=_ssh_config_from_config(config) if env_type == "ssh" else None,
  390. container_config=container_config,
  391. local_config=_local_config_from_config(config) if env_type == "local" else None,
  392. task_id=effective_task_id, host_cwd=_resolve_task_host_cwd(config, task_id),
  393. )
  394. with _env_lock:
  395. _active_environments[effective_task_id] = env
  396. _last_activity[effective_task_id] = time.time()
  397. _start_cleanup_thread()
  398. logger.info("%s environment ready for execute_code task %s",
  399. env_type, effective_task_id[:8])
  400. return env, env_type
  401. def _ship_file_to_remote(env, remote_path: str, content: str, *, atomic: bool = False) -> None:
  402. """Write *content* owner-only to *remote_path*; the payload rides
  403. ``stdin_data``, never an ``echo`` argv (see _remote_write). Raises on write
  404. failure: the caller ships secrets and code into dirs it believes are locked
  405. down, so a silent failure would run the next step against a missing or
  406. half-written file."""
  407. _remote_write(env, remote_path, content, atomic=atomic, check=True)
  408. def _ship_env_file_and_launch(env, remote_dir: str, env_name: str, launch: str, *,
  409. rpc_dir: str, rpc_token: str, **extra_env: str) -> str:
  410. """Ship the sandbox env (RPC dir + token, PYTHONDONTWRITEBYTECODE, the routed
  411. profile's TZ, plus *extra_env*) as KEY=value lines to ``remote_dir/env_name``
  412. and return the complete command that sources it inside a subshell and runs
  413. *launch* there.
  414. The subshell is load-bearing: every env.execute() runs inside the backend's
  415. session wrapper, which re-dumps ``export -p`` into the shared session
  416. snapshot after each command. A plain ``set -a; . file`` in the outer shell
  417. would export HERMES_RPC_TOKEN/PYTHONPATH/TZ into that snapshot and re-export
  418. them into every later command on the backend (the #71296 snapshot-leak
  419. class). The token also stays off the remote shell's argv, which co-tenant
  420. users can read via ps for the command's lifetime."""
  421. env_map = {"HERMES_RPC_DIR": rpc_dir, "HERMES_RPC_TOKEN": rpc_token,
  422. "PYTHONDONTWRITEBYTECODE": "1", **extra_env}
  423. tz = get_timezone_name() # routed profile's timezone, not the bridged default's
  424. if tz:
  425. env_map["TZ"] = tz
  426. lines = "".join(f"{k}={shlex.quote(v)}\n" for k, v in env_map.items())
  427. _ship_file_to_remote(env, f"{remote_dir}/{env_name}", lines)
  428. return (f"cd {shlex.quote(remote_dir)} && "
  429. f"( set -a && . ./{env_name} && set +a && {launch} )")
  430. def _env_temp_dir(env: Any) -> str:
  431. """Return a writable temp dir for env-backed execute_code sandboxes."""
  432. temp_dir = None
  433. get_temp_dir = getattr(env, "get_temp_dir", None)
  434. if callable(get_temp_dir):
  435. try:
  436. temp_dir = get_temp_dir()
  437. except Exception as exc:
  438. logger.debug("Could not resolve execute_code env temp dir: %s", exc)
  439. for candidate in (temp_dir, tempfile.gettempdir()):
  440. if isinstance(candidate, str) and candidate.startswith("/"):
  441. return candidate.rstrip("/") or "/"
  442. return tempfile.gettempdir()
  443. def _format_interrupted_output(stdout_text: str) -> str:
  444. """Append an interruption marker without guessing who caused it."""
  445. from tools.interrupt import get_interrupt_reason
  446. reason = get_interrupt_reason()
  447. marker = f"[execution interrupted — {reason}]" if reason else "[execution interrupted]"
  448. return f"{stdout_text}\n{marker}" if stdout_text else marker
  449. def _clean_output(stdout_text: str) -> tuple[str, dict[str, Any]]:
  450. """Shared output pipeline: byte-cap (with spill), ANSI strip, secret redaction. code_file=True:
  451. output often echoes source/config — skip ENV/JSON/f-string false positives, still mask credentials."""
  452. from tools.ansi_strip import strip_ansi
  453. from agent.redact import redact_sensitive_text
  454. stdout_text, metadata = _truncate_stdout_text(stdout_text)
  455. return redact_sensitive_text(strip_ansi(stdout_text), code_file=True), metadata
  456. def _with_timeout_notice(stdout_text: str, timeout_msg: str) -> str:
  457. """Timeout message goes in the output too — an empty result makes models answer as if
  458. nothing happened, and the gateway drops empty replies."""
  459. return stdout_text + f"\n\n⏰ {timeout_msg}" if stdout_text else f"⏰ {timeout_msg}"
  460. def _error_result(error: str, *, tool_calls_made: int = 0, duration: float = 0,
  461. user_summary: Optional[str] = None) -> str:
  462. body = {"status": "error", "error": error, "tool_calls_made": tool_calls_made, "duration_seconds": duration}
  463. if user_summary:
  464. body["user_summary"] = user_summary # one human sentence; surfaces show it before the model text
  465. return json.dumps(body, ensure_ascii=False)
  466. def _remote_failure(exc: BaseException, exec_start: float, tool_calls_made: int) -> str:
  467. duration = round(time.monotonic() - exec_start, 2)
  468. logger.error("execute_code remote failed after %ss with %d tool calls: %s: %s",
  469. duration, tool_calls_made, type(exc).__name__, exc, exc_info=True)
  470. return _error_result(str(exc), tool_calls_made=tool_calls_made, duration=duration)
  471. _REMOTE_EXIT_STATUS = {124: "timeout", 130: "interrupted"}
  472. def _remote_result(status: str, raw_stdout: str, exec_start: float, fields: dict[str, Any],
  473. kernel: Optional[dict[str, Any]] = None) -> dict[str, Any]:
  474. """Common remote reply shape: status, cleaned output, *fields*, duration, optional kernel
  475. info, then truncation metadata (key order is part of the result contract)."""
  476. stdout_text, stdout_metadata = _clean_output(raw_stdout)
  477. result: dict[str, Any] = {"status": status, "output": stdout_text, **fields,
  478. "duration_seconds": round(time.monotonic() - exec_start, 2)}
  479. if kernel is not None:
  480. result["kernel"] = kernel
  481. result.update(stdout_metadata)
  482. return result
  483. def _apply_timeout(result: dict[str, Any], timeout_msg: str) -> None:
  484. result["error"] = timeout_msg
  485. result["output"] = _with_timeout_notice(result["output"], timeout_msg)
  486. def _finish_remote_kernel_result(kernel_result: dict[str, Any], *,
  487. timeout: int, exec_start: float) -> str:
  488. """Post-process a remote-kernel cell result into the tool's JSON reply. Timeout messaging
  489. mirrors the local kernel contract (kernel killed, state lost, next call fresh)."""
  490. stdout_text = kernel_result.get("stdout", "") or ""
  491. stderr_text = kernel_result.get("stderr", "") or ""
  492. traceback_text = kernel_result.get("traceback", "") or ""
  493. if stderr_text or traceback_text:
  494. # Same joining shape as the local kernel: stderr and traceback ride in
  495. # the output under one marker so the model sees the failure inline.
  496. stdout_text = stdout_text + "\n--- stderr ---\n" + stderr_text + traceback_text
  497. result = _remote_result(kernel_result.get("status", "error"), stdout_text, exec_start,
  498. {"tool_calls_made": kernel_result.get("tool_calls_made", 0)},
  499. kernel=kernel_result.get("kernel", {"remote": True}))
  500. if kernel_result.get("tool_errors"):
  501. result["tool_errors"] = kernel_result["tool_errors"]
  502. if result["status"] == "timeout":
  503. _apply_timeout(result, f"Cell timed out after {timeout}s; the remote session kernel was "
  504. "killed and its state was lost. The next call starts fresh.")
  505. elif result["status"] == "error" and kernel_result.get("error"):
  506. result["error"] = kernel_result["error"]
  507. return json.dumps(result, ensure_ascii=False)
  508. def _sandbox_tools_for(enabled_tools: Optional[list[str]]) -> frozenset:
  509. """Enabled ∩ SANDBOX_ALLOWED_TOOLS, or every sandbox tool when the intersection is empty."""
  510. return frozenset(SANDBOX_ALLOWED_TOOLS & set(enabled_tools or ())) or SANDBOX_ALLOWED_TOOLS
  511. def _run_remote_per_call(env, env_type: str, code: str, effective_task_id: str,
  512. sandbox_tools: frozenset, *, timeout: int, max_tool_calls: int,
  513. exec_start: float) -> str:
  514. """Per-call script ship: stage hermes_tools.py + script.py in a fresh remote sandbox dir,
  515. serve file-RPC from a polling thread, run, clean up."""
  516. sandbox_dir = f"{_env_temp_dir(env)}/hermes_exec_{uuid.uuid4().hex[:12]}"
  517. quoted_sandbox_dir = shlex.quote(sandbox_dir)
  518. tool_call_counter, tool_call_log, stop_event, rpc_thread = [0], [], threading.Event(), None
  519. try:
  520. # Private dirs: the sandbox lives under a shared temp dir and carries the
  521. # RPC token (in req files) and tool results. Fail closed on setup
  522. # failure rather than ship secrets into a dir that stayed permissive.
  523. _execute_checked(env, _private_dirs_cmd(sandbox_dir, f"{sandbox_dir}/rpc"),
  524. "remote sandbox setup", timeout=10)
  525. rpc_token = secrets.token_urlsafe(32)
  526. _ship_file_to_remote(env, f"{sandbox_dir}/hermes_tools.py",
  527. generate_hermes_tools_module(list(sandbox_tools), transport="file"))
  528. _ship_file_to_remote(env, f"{sandbox_dir}/script.py", code)
  529. # Wrapped so the thread inherits the turn's approval context + callbacks
  530. # (tools.thread_context) — else sandbox RPC tool calls lose approval routing.
  531. # See #30882.
  532. rpc_thread = threading.Thread(
  533. target=propagate_context_to_thread(_rpc_poll_loop), daemon=True,
  534. args=(env, f"{sandbox_dir}/rpc", effective_task_id, tool_call_log, tool_call_counter,
  535. max_tool_calls, sandbox_tools, stop_event, rpc_token))
  536. rpc_thread.start()
  537. # The token travels in a sourced env file, never in argv. No umask on
  538. # the launch command: the 700 dirs + explicit 0600 writes cover Hermes'
  539. # files, and user code keeps the remote's default file modes.
  540. launch_cmd = _ship_env_file_and_launch(
  541. env, sandbox_dir, "sandbox.env", "exec python3 script.py",
  542. rpc_dir=f"{sandbox_dir}/rpc", rpc_token=rpc_token)
  543. logger.info("Executing code on %s backend (task %s)...", env_type, effective_task_id[:8])
  544. script_result = env.execute(launch_cmd, timeout=timeout)
  545. stdout_text = script_result.get("output", "") or ""
  546. exit_code = script_result.get("returncode", -1)
  547. # Backend exit codes: 124 = timeout wrapper, 130 = SIGINT.
  548. status = _REMOTE_EXIT_STATUS.get(exit_code, "success")
  549. except Exception as exc:
  550. return _remote_failure(exc, exec_start, tool_call_counter[0])
  551. finally:
  552. stop_event.set()
  553. if rpc_thread is not None:
  554. rpc_thread.join(timeout=5)
  555. try:
  556. env.execute(f"rm -rf {quoted_sandbox_dir}", cwd="/", timeout=15)
  557. except Exception:
  558. logger.debug("Failed to clean up remote sandbox %s", sandbox_dir)
  559. result = _remote_result(status, stdout_text, exec_start,
  560. {"exit_code": exit_code, "tool_calls_made": tool_call_counter[0]})
  561. tool_errors = tool_errors_since(tool_call_log)
  562. if tool_errors:
  563. result["tool_errors"] = tool_errors
  564. if status == "timeout":
  565. _apply_timeout(result, f"Script timed out after {timeout}s and was killed.")
  566. logger.warning("execute_code (remote) timed out after %ss (limit %ss) with %d tool calls",
  567. result["duration_seconds"], timeout, tool_call_counter[0])
  568. elif status == "interrupted":
  569. result["output"] = _format_interrupted_output(result["output"])
  570. elif exit_code != 0:
  571. result["status"] = "error"
  572. result["error"] = f"Script exited with code {exit_code}"
  573. return json.dumps(result, ensure_ascii=False)
  574. def _execute_remote(code: str, task_id: Optional[str], enabled_tools: Optional[list[str]],
  575. reset: bool = False) -> str:
  576. """Run code on the remote terminal backend: the owner's persistent remote session kernel
  577. (tools/code_kernel_remote.py) first, else the per-call script ship — the fail-open route when
  578. a kernel cannot be spawned and the only route for hosts that cannot sustain a background process."""
  579. from tools.terminal_tool import _resolve_container_task_id
  580. from tools.terminal_tool_lifecycle import _call_in_flight
  581. _cfg = _load_config()
  582. timeout, max_tool_calls = _cfg.get("timeout", DEFAULT_TIMEOUT), _cfg.get("max_tool_calls", DEFAULT_MAX_TOOL_CALLS)
  583. sandbox_tools, effective_task_id = _sandbox_tools_for(enabled_tools), task_id or "default"
  584. env, env_type = _get_or_create_env(effective_task_id)
  585. with _call_in_flight(_resolve_container_task_id(effective_task_id)):
  586. exec_start = time.monotonic()
  587. try:
  588. py_check = env.execute("command -v python3 >/dev/null 2>&1 && echo OK", cwd="/", timeout=15)
  589. if "OK" not in py_check.get("output", ""):
  590. return _error_result(f"Python 3 is not available in the {env_type} terminal "
  591. "environment. Install Python to use execute_code with remote backends.")
  592. # Session-kernel path: one persistent kernel per owner on the
  593. # run-to-completion transport. Spawn failure falls OPEN to the per-call
  594. # path below so a degraded remote host never blocks execution.
  595. try:
  596. # --- Session-kernel path (hermes-agent#96873) ------------------- Same always-on model as
  597. # local: one persistent kernel per owner, rebuilt on the run-to-completion transport (detached
  598. # runner + file cell protocol).
  599. from tools.code_kernel_remote import execute_in_remote_kernel
  600. kernel_result = execute_in_remote_kernel(
  601. code, env=env, env_type=env_type, task_env_id=effective_task_id,
  602. sandbox_tools=frozenset(sandbox_tools), timeout=timeout,
  603. max_tool_calls=max_tool_calls, reset=bool(reset),
  604. idle_exit=int(_cfg.get("kernel_idle_timeout", 1800)),
  605. )
  606. except Exception:
  607. logger.warning("remote session-kernel path failed; falling back to per-call", exc_info=True)
  608. kernel_result = None
  609. if kernel_result is not None:
  610. return _finish_remote_kernel_result(kernel_result, timeout=timeout, exec_start=exec_start)
  611. logger.info("remote session kernel unavailable on %s; using per-call path", env_type)
  612. except Exception as exc:
  613. return _remote_failure(exc, exec_start, 0)
  614. return _run_remote_per_call(env, env_type, code, effective_task_id, sandbox_tools,
  615. timeout=timeout, max_tool_calls=max_tool_calls, exec_start=exec_start)
  616. # ---- Main entry point ----
  617. def execute_code(
  618. code: str,
  619. task_id: Optional[str] = None,
  620. enabled_tools: Optional[list[str]] = None,
  621. reset: bool = False,
  622. ) -> str:
  623. """Run Python in the session's persistent kernel (local) or on the remote terminal backend,
  624. with RPC access to a subset of Hermes tools; returns the JSON result string. "Sandbox" means
  625. the security envelope (env scrubbing, tool whitelist + call budget, output redaction), not an
  626. isolation jail: default `project` mode runs in the session's cwd with the project venv.
  627. ``enabled_tools`` ∩ SANDBOX_ALLOWED_TOOLS; ``reset`` kills the existing kernel first."""
  628. if not SANDBOX_AVAILABLE:
  629. return tool_error("execute_code sandbox is unavailable in this environment. "
  630. "Use normal tool calls (terminal, read_file, write_file, ...) instead.")
  631. # Fail closed under a terminal-policy refusal scope: the routed profile's terminal
  632. # policy is unresolved, so refuse rather than inherit the launch process's ambient policy.
  633. try:
  634. # See #68559.
  635. from tools.terminal_scope import enforce_no_refusal
  636. enforce_no_refusal()
  637. except Exception as refusal:
  638. return tool_error(f"execute_code refused: {refusal} "
  639. "(profile terminal policy unresolved; fix the profile's config.yaml / .env and retry)")
  640. if not code or not code.strip():
  641. return tool_error("No code provided. execute_code requires a non-empty 'code' "
  642. "parameter containing Python source. To run shell commands, use terminal(command=...) instead.")
  643. # Hard-block gateway-lifecycle commands (mirrors the terminal_tool guard — otherwise
  644. # `os.system("launchctl bootout ...")` here bypasses it and SIGTERMs the gateway mid-task).
  645. # Gated on PID-file ownership, not the inherited env marker.
  646. # Hard-block gateway-lifecycle commands, mirroring the terminal_tool guard (#68289): without this,
  647. # execute_code is a straight bypass — the terminal() path refuses `launchctl bootout ai.hermes.gateway`,
  648. # but the identical command inside `os.system(...)` / `subprocess.run([...])` here sailed through and
  649. # SIGTERM'd the gateway mid-task.
  650. # The identity probe ends in a kernel process query that has wedged on macOS
  651. # (#111922); share the cell's own deadline and fail CLOSED when it renders no verdict.
  652. from agent.deadline import run_bounded_sync
  653. from tools.process_registry import _is_supervised_gateway_process
  654. from tools.terminal_tool import _PRE_EXEC_GUARD_MIN_TIMEOUT_S
  655. _probe_timeout = max(_load_config().get("timeout", DEFAULT_TIMEOUT), _PRE_EXEC_GUARD_MIN_TIMEOUT_S)
  656. _probe = run_bounded_sync(
  657. _is_supervised_gateway_process, _probe_timeout, label="execute_code.lifecycle-guard",
  658. )
  659. if _probe.timed_out:
  660. return tool_error(
  661. f"execute_code lifecycle guard did not finish within {_probe_timeout}s "
  662. "(process-identity probe wedged); the code was not run. Retry the call."
  663. )
  664. if _probe.value:
  665. from cron.lifecycle_guard import (
  666. HOST_INTERPRETER_KILL_REJECTION,
  667. contains_gateway_lifecycle_command,
  668. contains_host_interpreter_kill,
  669. )
  670. if contains_gateway_lifecycle_command(code):
  671. if contains_host_interpreter_kill(code):
  672. return tool_error(HOST_INTERPRETER_KILL_REJECTION)
  673. return tool_error(
  674. "Blocked: cannot restart or stop the gateway from inside the "
  675. "gateway process. The gateway would kill this script before "
  676. "it could complete (SIGTERM propagates to child processes). "
  677. "Run the lifecycle command from a shell outside the gateway."
  678. )
  679. from tools.terminal_tool import _get_env_config, _docker_has_host_access
  680. _env_config = _get_env_config()
  681. env_type = _env_config["env_type"]
  682. # Arbitrary Python never passes through terminal()/DANGEROUS_PATTERNS, so guard the whole
  683. # script before either dispatch path spawns it — in this (tool-executor) thread, which holds
  684. # the session context. A Docker sandbox with host bind mounts gets no container fast-path.
  685. # See #30882.
  686. from tools.approval import check_execute_code_guard
  687. _guard = check_execute_code_guard(code, env_type, has_host_access=_docker_has_host_access(_env_config))
  688. if not _guard.get("approved", False):
  689. return _error_result(_guard.get("message") or "execute_code blocked by approval guard.",
  690. user_summary=_guard.get("user_summary"))
  691. # Clear a stale interrupt bit that landed during the blocking approval-wait so it can't
  692. # kill the just-approved run on the first poll. A genuine post-clear interrupt re-sets it.
  693. if _guard.get("user_approved"):
  694. from tools.interrupt import clear_current_thread_interrupt
  695. clear_current_thread_interrupt()
  696. from hermes_cli.observability.shared_metrics_loop import record_execution_backend
  697. if env_type != "local":
  698. return record_execution_backend("code", "remote", _execute_remote(code, task_id, enabled_tools, reset=bool(reset)))
  699. from tools.interrupt import is_interrupted as _is_interrupted
  700. # Session kernels are always on locally (one interpreter per conversation); the guards above
  701. # already ran for this cell, and the kernel path shares env builder, RPC server and redaction.
  702. from tools.code_kernel import execute_in_session_kernel
  703. _cfg = _load_config()
  704. _mode = _get_execution_mode()
  705. return record_execution_backend("code", "local", execute_in_session_kernel(
  706. code, task_id=task_id or "", mode=_mode, child_python=_resolve_child_python(_mode),
  707. child_cwd=_resolve_child_cwd(_mode, "", task_id=task_id or ""),
  708. sandbox_tools=frozenset(_sandbox_tools_for(enabled_tools)),
  709. timeout=_cfg.get("timeout", DEFAULT_TIMEOUT),
  710. max_tool_calls=_cfg.get("max_tool_calls", DEFAULT_MAX_TOOL_CALLS),
  711. reset=bool(reset), is_interrupted=_is_interrupted,
  712. ))
  713. def _kill_process_group(proc, escalate: bool = False):
  714. """Kill the child and its whole process tree via agent.deadline.kill_process_tree: SIGTERM
  715. (killpg + psutil descendant sweep; ``taskkill /T /F`` on Windows, where sig is ignored); with
  716. ``escalate=True`` wait 5s then SIGKILL survivors. Never raises — falls back to ``proc.kill()``."""
  717. import signal as _signal
  718. def _tree_signal(sig) -> None:
  719. try:
  720. from agent.deadline import kill_process_tree
  721. kill_process_tree(proc.pid, sig=sig)
  722. except Exception as e:
  723. logger.debug("Could not terminate process tree: %s", e, exc_info=True)
  724. try:
  725. proc.kill()
  726. except Exception as e2:
  727. logger.debug("Could not kill process: %s", e2, exc_info=True)
  728. _tree_signal(getattr(_signal, "SIGTERM", None))
  729. if escalate:
  730. try:
  731. proc.wait(timeout=5)
  732. except subprocess.TimeoutExpired:
  733. _tree_signal(getattr(_signal, "SIGKILL", None))
  734. def _load_config() -> dict:
  735. """Effective ``code_execution`` section (defaults + user file + managed overlay) — runs while the
  736. module-level schema is built at tool discovery, so it must not import ``cli``."""
  737. try:
  738. from hermes_cli.config import load_config_readonly
  739. cfg = load_config_readonly().get("code_execution", {})
  740. return cfg if isinstance(cfg, dict) else {}
  741. except Exception:
  742. return {}
  743. # ---- Execution mode resolution (strict vs project) ----
  744. # Canonical code_execution.mode values (referenced by tests and the config layer). Session
  745. # kernels are the only local execution model; a leftover kernel_mode config key is ignored.
  746. EXECUTION_MODES = ("project", "strict")
  747. DEFAULT_EXECUTION_MODE = "project"
  748. def _get_execution_mode() -> str:
  749. """``code_execution.mode`` (invalid → default with a warning). ``project``: session cwd + active
  750. venv python; ``strict``: isolated temp dir + ``sys.executable``. Scrubbing/whitelist apply to both."""
  751. cfg_value = str(_load_config().get("mode", DEFAULT_EXECUTION_MODE)).strip().lower()
  752. if cfg_value in EXECUTION_MODES:
  753. return cfg_value
  754. logger.warning(
  755. "Ignoring code_execution.mode=%r (expected one of %s), falling back to %r",
  756. cfg_value, EXECUTION_MODES, DEFAULT_EXECUTION_MODE,
  757. )
  758. return DEFAULT_EXECUTION_MODE
  759. # ---- OpenAI Function-Calling Schema ----
  760. # Per-tool documentation lines for the execute_code description, in canonical display order.
  761. _TOOL_DOC_LINES = [
  762. ("web_search", " web_search(query: str, limit: int = 5) -> dict\n"
  763. " Returns {\"data\": {\"web\": [{\"url\", \"title\", \"description\"}, ...]}}"),
  764. ("web_extract", " web_extract(urls: list[str], char_limit: int = None) -> dict\n"
  765. " Returns {\"results\": [{\"url\", \"title\", \"content\", \"error\"}, ...]} where content is markdown.\n"
  766. " No LLM summarization. Pages over char_limit (default 15000) are head+tail truncated; full text stored on disk (path in the content footer)."),
  767. ("read_file", " read_file(path: str, offset: int = 1, limit: int = 2000) -> dict\n"
  768. " Lines are 1-indexed. Returns {\"content\": \"...\", \"total_lines\": N}"),
  769. ("write_file", " write_file(path: str, content: str) -> dict\n Always overwrites the entire file; an existing file must be read_file'd first or the write is refused."),
  770. ("search_files", " search_files(pattern: str, target=\"content\", path=\".\", file_glob=None, limit=50, order=\"discovery\") -> dict\n"
  771. " target: \"content\" (search inside files) or \"files\" (find files by name). Returns {\"matches\": [...]}"),
  772. ("patch", " patch(path: str, old_string: str, new_string: str, replace_all: bool = False) -> dict\n"
  773. " Replaces old_string with new_string in the file."),
  774. ("terminal", " terminal(command: str, timeout=None, workdir=None) -> dict\n"
  775. " Foreground only (no background/pty). Returns {\"output\": \"...\", \"exit_code\": N}"),
  776. ]
  777. def build_execute_code_schema(enabled_sandbox_tools: set | None = None,
  778. mode: str | None = None) -> dict:
  779. """execute_code schema listing only *enabled_sandbox_tools* — a disabled tool (e.g. web off)
  780. must not appear or the model keeps trying it. ``mode`` (None → config) picks the cwd sentence."""
  781. if enabled_sandbox_tools is None:
  782. enabled_sandbox_tools = SANDBOX_ALLOWED_TOOLS
  783. if mode is None:
  784. mode = _get_execution_mode()
  785. tool_lines = "\n".join(doc for name, doc in _TOOL_DOC_LINES if name in enabled_sandbox_tools)
  786. import_examples = [n for n in ("web_search", "terminal") if n in enabled_sandbox_tools]
  787. import_examples = import_examples or sorted(enabled_sandbox_tools)[:2]
  788. import_str = ", ".join(import_examples) + ", ..." if import_examples else "..."
  789. if mode == "strict":
  790. cwd_note = (
  791. "Scripts run in their own temp dir, not the session's CWD — pass "
  792. "absolute paths for any file that lives outside the session's "
  793. "working directory, or use terminal()/read_file() to reach it."
  794. )
  795. else:
  796. cwd_note = (
  797. "Scripts run in the session's working directory. Interpreter: "
  798. "the project's activated venv/conda python when one is active "
  799. "(VIRTUAL_ENV/CONDA_PREFIX — matches terminal()); otherwise "
  800. "Hermes's own python (the common case — stdlib plus Hermes's "
  801. "deps; check `import x` before relying on project packages)."
  802. )
  803. # Remote hosts that fail open to per-call are not worth schema words; the result's
  804. # `kernel` field tells the truth per call.
  805. # Session kernels are always on (kernel_mode retired in #96787): persistence is part of the tool's one
  806. # description, not a bolt-on paragraph behind a dead conditional.
  807. description = (
  808. "Run Python that calls Hermes tools programmatically. Use when you "
  809. "need 3+ tool calls with logic between them: filtering/reducing "
  810. "large outputs before they enter context, branching, or loops "
  811. "(N pages/files, retry on failure). Use normal tool calls for "
  812. "single calls, results you must reason over in full, or anything needing user interaction.\n\n"
  813. "Calls run in a persistent session kernel: variables, imports, and "
  814. "loaded data survive across execute_code calls, so build on earlier "
  815. "work instead of re-loading it. A timed-out or interrupted call loses that state.\n\n"
  816. f"Available via `from hermes_tools import ...`:\n\n"
  817. f"{tool_lines}\n\n"
  818. "Limits: 5-minute timeout, max 50 tool calls per call. Stdout over "
  819. "50KB shows head/tail inline; the FULL text is auto-saved to a file whose path rides in the result.\n\n"
  820. f"{cwd_note}\n\n"
  821. "Helpers require imports: `from hermes_tools import json_parse, shell_quote, retry`. "
  822. "json_parse(text) — tolerant "
  823. "json.loads for terminal() output; shell_quote(s) — shlex.quote for "
  824. "dynamic shell args; retry(fn, max_attempts=3, delay=2) — exponential backoff."
  825. )
  826. return {
  827. "name": "execute_code",
  828. "description": description,
  829. "parameters": {
  830. "type": "object",
  831. "properties": {
  832. "code": {"type": "string", "description": (
  833. "Python code to execute. Import tools with "
  834. f"`from hermes_tools import {import_str}` "
  835. "and print your final result to stdout.")},
  836. "reset": {"type": "boolean", "description": (
  837. "Discard the kernel's persistent state and start fresh before running this code.")},
  838. },
  839. "required": ["code"],
  840. },
  841. }
  842. # Registration-time schema (all sandbox tools, configured mode); model_tools.py rebuilds per-session.
  843. EXECUTE_CODE_SCHEMA = build_execute_code_schema()
  844. def _execute_code_handler(args: dict, **kwargs) -> str:
  845. """Redirect misdirected calls (terminal's ``command`` arg, non-string ``code``) with an
  846. actionable error before dispatching to ``execute_code``."""
  847. if "code" not in args and "command" in args:
  848. logger.warning("execute_code received 'command' instead of the required 'code' argument")
  849. return tool_error("execute_code received a 'command' parameter, but it requires "
  850. "Python source in 'code'. Use terminal(command=...) for shell "
  851. "commands; for Python, retry as execute_code(code=...).")
  852. code = args.get("code", "")
  853. if code is not None and not isinstance(code, str):
  854. return tool_error(f"execute_code received a {type(code).__name__} in 'code', but it "
  855. "requires Python source as a string. Retry as execute_code(code=\"...\").")
  856. return execute_code(code=code or "", task_id=kwargs.get("task_id"),
  857. enabled_tools=kwargs.get("enabled_tools"), reset=bool(args.get("reset", False)))
  858. registry.register(
  859. name="execute_code", toolset="code_execution", schema=EXECUTE_CODE_SCHEMA,
  860. handler=_execute_code_handler, check_fn=check_sandbox_requirements, emoji="🐍",
  861. max_result_size_chars=100_000,
  862. )