2026-02-19 23:23:43 -08:00
#!/usr/bin/env python3
2026-09-02 22:33:03 -07:00
""" Code Execution Tool -- Programmatic Tool Calling (PTC).
The LLM writes a Python script that calls Hermes tools via RPC , collapsing
multi - step tool chains into one inference turn ; only the script ' s stdout returns
to the LLM . Local backend : a persistent per - conversation session kernel
( tools / code_kernel . py ) over a Unix socket ( loopback TCP on Windows ) . Remote
backends : a remote session kernel ( tools / code_kernel_remote . py ) falling open to a
per - call script ship , tool calls as request files polled via env . execute ( )
( needs Python 3 on the backend ) . Siblings : tools / code_execution_env . py ( env
scrubbing , interpreter / cwd ) , tools / code_execution_rpc . py ( RPC servers ) .
2026-02-19 23:23:43 -08:00
"""
2026-04-04 12:57:49 -07:00
import base64
2026-02-19 23:23:43 -08:00
import json
import logging
import os
2026-08-02 14:39:42 -07:00
import re
2026-07-01 02:52:04 -07:00
import secrets
2026-04-09 13:46:08 +02:00
import shlex
2026-02-19 23:23:43 -08:00
import subprocess
import tempfile
import threading
import time
import uuid
2026-05-31 21:59:24 +03:30
from typing import Any , Dict , List , Optional , Tuple
2026-02-19 23:23:43 -08:00
2026-05-28 17:47:09 -04:00
from tools . thread_context import propagate_context_to_thread
2026-09-02 12:11:59 -07:00
from tools . registry import registry , tool_error
2026-05-28 17:47:09 -04:00
2026-09-03 13:24:04 -07:00
from tools . code_execution_env import _resolve_child_cwd , _resolve_child_python
from tools . code_execution_rpc import _rpc_poll_loop
2026-05-28 17:47:09 -04:00
2026-02-21 03:32:11 -08:00
logger = logging . getLogger ( __name__ )
2026-09-02 22:33:03 -07:00
# Loopback TCP replaces AF_UNIX on Windows, so execute_code runs on every platform Hermes does.
2026-05-07 18:17:31 -07:00
SANDBOX_AVAILABLE = True
2026-02-19 23:23:43 -08:00
2026-09-02 22:33:03 -07:00
# Tools allowed inside the sandbox; ∩ the session's enabled tools decides which stubs are generated.
2026-02-19 23:23:43 -08:00
SANDBOX_ALLOWED_TOOLS = frozenset ( [
2026-09-02 22:10:19 -07:00
" web_search " , " web_extract " , " read_file " , " write_file " , " search_files " , " patch " , " terminal " ,
2026-02-19 23:23:43 -08:00
] )
# Resource limit defaults (overridable via config.yaml → code_execution.*)
2026-02-20 01:29:53 -08:00
DEFAULT_TIMEOUT = 300 # 5 minutes
2026-02-19 23:23:43 -08:00
DEFAULT_MAX_TOOL_CALLS = 50
MAX_STDOUT_BYTES = 50_000 # 50 KB
MAX_STDERR_BYTES = 10_000 # 10 KB
2026-09-02 23:00:08 -07:00
# Hard ceiling on the spilled file (as web_tools' MAX_STORED_TEXT_CHARS): a runaway print loop must not fill the disk.
2026-09-02 22:10:19 -07:00
MAX_SPILLED_STDOUT_BYTES = 5_000_000
2026-05-31 21:59:24 +03:30
def _truncate_stdout_text ( stdout_text : str ) - > Tuple [ str , Dict [ str , Any ] ] :
2026-09-02 23:00:08 -07:00
""" Cap stdout by bytes (40 % he ad / 60 % tail) with explicit truncation metadata: byte counts
ride alongside the textual marker because a client layer can miss or re - truncate it . The
omitted middle is spilled to cache / exec and the result carries the path ( recover - don ' t-rerun). " " "
2026-05-31 21:59:24 +03:30
stdout_bytes = stdout_text . encode ( " utf-8 " , errors = " replace " )
2026-09-02 22:10:19 -07:00
total = len ( stdout_bytes )
2026-09-02 22:52:47 -07:00
captured = min ( total , MAX_STDOUT_BYTES )
metadata : Dict [ str , Any ] = { " stdout_truncated " : total > captured , " stdout_bytes_captured " : captured ,
" stdout_bytes_total " : total , " stdout_bytes_omitted " : total - captured }
2026-09-02 22:10:19 -07:00
if total < = MAX_STDOUT_BYTES :
2026-09-02 22:52:47 -07:00
return stdout_bytes . decode ( " utf-8 " , errors = " replace " ) , metadata
2026-05-31 21:59:24 +03:30
head_bytes = int ( MAX_STDOUT_BYTES * 0.4 )
2026-09-02 22:52:47 -07:00
text = ( stdout_bytes [ : head_bytes ] . decode ( " utf-8 " , errors = " replace " )
+ f " \n \n ... [OUTPUT TRUNCATED - { total - captured : , } bytes omitted out of { total : , } total] ... \n \n "
+ stdout_bytes [ head_bytes - MAX_STDOUT_BYTES : ] . decode ( " utf-8 " , errors = " replace " ) )
metadata [ " warning " ] = ( " execute_code stdout was truncated; the script did run, but only "
" the captured head/tail output is included. Re-run only with "
" narrower output if the omitted data is required. " )
2026-08-28 03:05:03 -07:00
spill_path = _spill_full_stdout ( stdout_text )
if spill_path :
metadata [ " stdout_spill_path " ] = spill_path
2026-09-02 22:45:21 -07:00
metadata [ " warning " ] = ( " execute_code stdout was truncated (head/tail shown); the "
f " script did run. FULL output saved to { spill_path } — page it "
f ' with read_file(path= " { spill_path } " , offset=...) instead of re-running. ' )
2026-08-28 03:05:03 -07:00
return text , metadata
def _spill_full_stdout ( stdout_text : str ) - > Optional [ str ] :
2026-09-02 22:33:03 -07:00
""" Write full stdout to cache/exec; return its path (None on failure — best-effort,
the truncated inline output is still returned ) . Keyed by content digest so identical
reruns coalesce ; the dir rides the cache / web remote bind - mount list ( credential_files ) . """
2026-08-28 03:05:03 -07:00
try :
import hashlib
from hermes_constants import get_hermes_dir
2026-09-02 22:10:19 -07:00
from tools . spill_safety import write_text_exclusive
2026-08-28 03:05:03 -07:00
if len ( stdout_text ) > MAX_SPILLED_STDOUT_BYTES :
2026-09-02 22:10:19 -07:00
stdout_text = ( stdout_text [ : MAX_SPILLED_STDOUT_BYTES ]
+ f " \n \n [... spill capped at { MAX_SPILLED_STDOUT_BYTES : , } bytes ...] " )
2026-08-28 03:05:03 -07:00
cache_dir = get_hermes_dir ( " cache/exec " , " exec_spill " )
cache_dir . mkdir ( parents = True , exist_ok = True )
2026-09-02 22:10:19 -07:00
digest = hashlib . sha256 ( stdout_text . encode ( " utf-8 " , errors = " replace " ) ) . hexdigest ( ) [ : 12 ]
2026-08-28 03:05:03 -07:00
path = cache_dir / f " stdout- { digest } .txt "
write_text_exclusive ( path , stdout_text , private = False , overwrite = True )
return str ( path )
except Exception as exc : # noqa: BLE001
logger . debug ( " Failed to spill execute_code stdout: %s " , exc )
return None
2026-05-31 21:59:24 +03:30
2026-02-19 23:23:43 -08:00
def check_sandbox_requirements ( ) - > bool :
2026-09-02 12:11:59 -07:00
""" check_fn: available unless the vercel_sandbox backend fails its own checks. """
2026-04-29 18:20:53 +05:30
if not SANDBOX_AVAILABLE :
return False
2026-07-29 18:16:17 -07:00
try :
2026-09-03 13:24:04 -07:00
from tools . terminal_tool import _get_env_config
from tools . terminal_tool_backends import _check_vercel_sandbox_requirements
2026-07-29 18:16:17 -07:00
config = _get_env_config ( )
except Exception :
logger . debug ( " Could not resolve terminal config for execute_code availability " , exc_info = True )
return False
2026-09-02 22:52:47 -07:00
return config . get ( " env_type " ) != " vercel_sandbox " or _check_vercel_sandbox_requirements ( config )
2026-07-29 18:16:17 -07:00
2026-09-02 23:00:08 -07:00
# ---- hermes_tools.py code generator ----
2026-02-19 23:23:43 -08:00
2026-09-02 22:33:03 -07:00
# Per-tool stub templates: (signature, docstring, args_dict_expr — the JSON payload sent over RPC).
2026-02-19 23:23:43 -08:00
_TOOL_STUBS = {
2026-09-02 22:52:47 -07:00
" web_search " : ( " query: str, limit: int = 5 " ,
2026-02-19 23:30:01 -08:00
' " " " Search the web. Returns dict with data.web list of { url, title, description}. " " " ' ,
2026-09-02 22:52:47 -07:00
' { " query " : query, " limit " : limit} ' ) ,
" web_extract " : ( " urls: list, char_limit: int = None " ,
2026-06-29 10:00:49 -07:00
' " " " 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. " " " ' ,
2026-09-02 22:52:47 -07:00
' { " urls " : urls, " char_limit " : char_limit} ' ) ,
" read_file " : ( " path: str, offset: int = 1, limit: int = 2000 " ,
2026-02-19 23:23:43 -08:00
' " " " Read a file (1-indexed lines). Returns dict with " content " and " total_lines " . " " " ' ,
2026-09-02 22:52:47 -07:00
' { " path " : path, " offset " : offset, " limit " : limit} ' ) ,
" write_file " : ( " path: str, content: str, cross_profile: bool = False " ,
2026-08-28 06:36:22 -07:00
' " " " Write content to a file (always overwrites). Returns dict with status. " " " ' ,
2026-09-02 22:52:47 -07:00
' { " path " : path, " content " : content, " cross_profile " : cross_profile} ' ) ,
2026-09-03 03:31:03 -07:00
" 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 " ' ,
2026-03-06 03:40:06 -08:00
' " " " Search file contents (target= " content " ) or find files by name (target= " files " ). Returns dict with " matches " . " " " ' ,
2026-09-03 03:31:03 -07:00
' { " pattern " : pattern, " target " : target, " path " : path, " file_glob " : file_glob, " limit " : limit, " offset " : offset, " output_mode " : output_mode, " context " : context, " order " : order} ' ) ,
2026-09-02 22:52:47 -07:00
" 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 ' ,
2026-08-28 06:36:22 -07:00
' " " " Targeted find-and-replace (mode= " replace " ) or V4A multi-file patches (mode= " patch " ). Returns dict with status. " " " ' ,
2026-09-02 22:52:47 -07:00
' { " path " : path, " old_string " : old_string, " new_string " : new_string, " replace_all " : replace_all, " mode " : mode, " patch " : patch, " cross_profile " : cross_profile} ' ) ,
" terminal " : ( " command: str, timeout: int = None, workdir: str = None " ,
2026-02-19 23:23:43 -08:00
' " " " Run a shell command (foreground only). Returns dict with " output " and " exit_code " . " " " ' ,
2026-09-02 22:52:47 -07:00
' { " command " : command, " timeout " : timeout, " workdir " : workdir} ' ) ,
2026-02-19 23:23:43 -08:00
}
2026-09-02 22:10:19 -07:00
def _missing_hermes_tools_import_hint ( m , enabled_tools ) - > str :
missing = m . group ( 1 )
if missing in { " json_parse " , " shell_quote " , " retry " } :
2026-09-07 03:33:05 -07:00
return ( f " Import helpers with `from hermes_tools import { missing } `. "
" If that import failed, the generated module may be stale or another "
" hermes_tools may be first on sys.path. Check hermes_tools.__file__ "
" and retry with reset=true. " )
2026-09-02 22:10:19 -07:00
available = sorted ( SANDBOX_ALLOWED_TOOLS & set ( enabled_tools or SANDBOX_ALLOWED_TOOLS ) )
return ( f " ' { missing } ' is not available inside the execute_code sandbox. "
f " Importable tools here: { ' , ' . join ( available ) } . For anything "
" else, use the normal tool call instead of execute_code. " )
2026-09-02 22:33:03 -07:00
# (regex, formatter(match, enabled_tools)) — first match wins. Production mining (state.db) ranked
2026-09-07 03:33:05 -07:00
# these as the top execute_code failure classes: hermes_tools import misuse, missing helper
# imports, treating tool results as strings, importing third-party packages absent from the sandbox.
2026-09-02 22:10:19 -07:00
_FAILURE_HINT_RULES = (
( r " cannot import name ' ( \ w+) ' from ' hermes_tools ' " , _missing_hermes_tools_import_hint ) ,
( r " NameError: name ' (json_parse|shell_quote|retry) ' is not defined " ,
2026-09-07 03:33:05 -07:00
lambda m , _ : f " Import { m . group ( 1 ) } before calling it: "
f " from hermes_tools import { m . group ( 1 ) } " ) ,
2026-09-02 22:10:19 -07:00
( r " ModuleNotFoundError: No module named ' ([ \ w.]+) ' " ,
lambda m , _ : f " ' { m . group ( 1 ) } ' is not installed in the sandbox interpreter. "
" Use Python stdlib inside execute_code, or run the code via "
" terminal() with the project venv ' s python instead. " ) ,
( r " TypeError: string indices must be integers|AttributeError: ' str ' object has no attribute ' get ' " ,
lambda m , _ : " Tool functions in the sandbox return DICTS (already parsed) — "
2026-09-02 22:33:03 -07:00
" do not json.loads() them or index them like strings. Example: read_file(path)[ ' content ' ]. " ) ,
2026-09-02 22:10:19 -07:00
)
2026-08-02 14:39:42 -07:00
def _sandbox_failure_hint ( stderr_text : str , enabled_tools = None ) - > Optional [ str ] :
2026-09-02 22:10:19 -07:00
""" Map well-known sandbox script failures to one actionable recovery hint
( bounded scan , first match wins , never raises ) . """
2026-08-02 14:39:42 -07:00
if not stderr_text :
return None
window = stderr_text [ : 4000 ]
try :
2026-09-02 22:10:19 -07:00
for pattern , fmt in _FAILURE_HINT_RULES :
m = re . search ( pattern , window )
if m :
return fmt ( m , enabled_tools )
2026-08-02 14:39:42 -07:00
except Exception :
return None
return None
2026-04-04 12:57:49 -07:00
def generate_hermes_tools_module ( enabled_tools : List [ str ] ,
transport : str = " uds " ) - > str :
2026-09-02 22:33:03 -07:00
""" Source of the hermes_tools.py stub module for SANDBOX_ALLOWED_TOOLS ∩ *enabled_tools*.
` ` transport ` ` : ` ` " uds " ` ` ( local socket client ) or ` ` " file " ` ` ( file RPC , remote backends ) . """
2026-09-02 12:11:59 -07:00
header = _FILE_TRANSPORT_HEADER if transport == " file " else _UDS_TRANSPORT_HEADER
2026-09-02 22:33:03 -07:00
return header + " \n " . join (
f " def { name } ( { sig } ): \n { doc } \n return _call( { name !r} , { args_expr } ) \n "
for name , ( sig , doc , args_expr ) in sorted ( _TOOL_STUBS . items ( ) ) if name in set ( enabled_tools )
)
2026-02-19 23:23:43 -08:00
2026-03-06 01:52:46 -08:00
2026-04-04 12:57:49 -07:00
# ---- Shared helpers section (embedded in both transport headers) ----------
_COMMON_HELPERS = ''' \
2026-03-06 01:52:46 -08:00
# ---------------------------------------------------------------------------
# Convenience helpers (avoid common scripting pitfalls)
# ---------------------------------------------------------------------------
def json_parse ( text : str ) :
2026-07-05 01:55:34 +08:00
""" Parse JSON tolerant of control characters and UTF-8 BOM (strict=False).
2026-03-06 01:52:46 -08:00
Use this instead of json . loads ( ) when parsing output from terminal ( )
2026-07-05 01:55:34 +08:00
or web_extract ( ) that may contain raw tabs / newlines in strings ,
or from tools / files that prepend a UTF - 8 BOM ( salvage #57870, credit @woxinwuhen713-bit)."""
2026-09-02 22:10:19 -07:00
if isinstance ( text , str ) and text . startswith ( " \ufeff " ) :
2026-07-05 01:55:34 +08:00
text = text [ 1 : ]
2026-03-06 01:52:46 -08:00
return json . loads ( text , strict = False )
def shell_quote ( s : str ) - > str :
""" Shell-escape a string for safe interpolation into commands.
Use this when inserting dynamic content into terminal ( ) commands :
terminal ( f " echo { shell_quote ( user_input ) } " )
"""
return shlex . quote ( s )
def retry ( fn , max_attempts = 3 , delay = 2 ) :
""" Retry a function up to max_attempts times with exponential backoff.
Use for transient failures ( network errors , API rate limits ) :
result = retry ( lambda : terminal ( " gh issue list ... " ) )
"""
last_err = None
for attempt in range ( max_attempts ) :
try :
return fn ( )
except Exception as e :
last_err = e
if attempt < max_attempts - 1 :
time . sleep ( delay * ( 2 * * attempt ) )
raise last_err
2026-04-04 12:57:49 -07:00
'''
# ---- UDS transport (local backend) ---------------------------------------
_UDS_TRANSPORT_HEADER = ''' \
""" Auto-generated Hermes tools RPC stubs. """
2026-04-30 13:20:05 +08:00
import json , os , socket , shlex , threading , time
2026-04-04 12:57:49 -07:00
_sock = None
2026-04-30 13:20:05 +08:00
# The RPC server handles a single client connection serially and has no
# request-id in the protocol, so concurrent _call() invocations from multiple
# threads (e.g. ThreadPoolExecutor) would race on the shared socket and get
# each other's responses. Serialize the entire send+recv round-trip.
_call_lock = threading . Lock ( )
2026-04-04 12:57:49 -07:00
''' + _COMMON_HELPERS + ''' \
2026-02-19 23:23:43 -08:00
def _connect ( ) :
feat(windows): close remaining POSIX-only landmines — TUI crash, kanban waitpid, AF_UNIX sandbox, /bin/bash, npm .cmd shims, cwd tracking, detach flags
Second pass on native Windows support, driven by a systematic audit across
five areas: POSIX-only primitives (signal.SIGKILL/SIGHUP/SIGPIPE, os.WNOHANG,
os.setsid), path translation bugs (/c/Users → C:\Users), subprocess patterns
(npm.cmd batch shims, start_new_session no-op on Windows), subsystem health
(cron, gateway daemon, update flow), and module-level import guards.
Every change is platform-gated — POSIX (Linux/macOS) behaviour is preserved
bit-identical. Explicit "do no harm" test: test_posix_path_preserved_on_linux,
test_posix_noop, test_windows_detach_popen_kwargs_is_posix_equivalent_on_posix.
## New module
- hermes_cli/_subprocess_compat.py — shared helpers (resolve_node_command,
windows_detach_flags, windows_hide_flags, windows_detach_popen_kwargs).
All no-ops on non-Windows.
## CRITICAL fixes (would crash or silently break on Windows)
- tui_gateway/entry.py: SIGPIPE/SIGHUP referenced at module top level would
AttributeError on import on Windows, breaking `hermes --tui` entirely (it
spawns this module as a subprocess). Guard each signal.signal() call with
hasattr() and add SIGBREAK as Windows' SIGHUP equivalent.
- hermes_cli/kanban_db.py: os.waitpid(-1, os.WNOHANG) in dispatcher tick was
unguarded. os.WNOHANG doesn't exist on Windows. Gate the whole reap loop
behind `os.name != "nt"` — Windows has no zombies anyway.
- tools/code_execution_tool.py: AF_UNIX socket for execute_code RPC fails on
most Windows builds. Fall back to loopback TCP (AF_INET on 127.0.0.1:0
ephemeral port) when _IS_WINDOWS. HERMES_RPC_SOCKET env var now accepts
either a filesystem path (POSIX) or `tcp://127.0.0.1:<port>` (Windows).
Generated sandbox client parses both.
- cron/scheduler.py: `argv = ["/bin/bash", str(path)]` hardcoded. Use
shutil.which("bash") so Windows (Git Bash via MinGit) works, with a
readable error when bash is genuinely absent.
- 6 bare npm/npx spawn sites: tools_config.py x2, doctor.py, whatsapp.py
(npm install + node version probe), browser_tool.py x2. On Windows npm
is npm.cmd / npx is npx.cmd (batch shims); subprocess.Popen(["npm", ...])
fails with WinError 193. shutil.which(...) returns the absolute .cmd
path which CreateProcessW accepts because the extension routes through
cmd.exe /c. POSIX behaviour unchanged (shutil.which still returns the
same path subprocess would resolve itself).
## HIGH fixes (silent misbehaviour on Windows)
- tools/environments/local.py get_temp_dir: hardcoded /tmp returned on
Windows meant `_cwd_file = "/tmp/hermes-cwd-*.txt"`, which bash wrote
via MSYS2's virtual /tmp but native Python couldn't open. Result: cwd
tracking silently broken — `cd` in terminal tool did nothing. Windows
branch now returns `%HERMES_HOME%/cache/terminal` with forward slashes
(works in both bash and Python, guaranteed no spaces).
- tools/environments/local.py _make_run_env PATH injection: `/usr/bin not
in split(":")` heuristic mangles Windows PATH (";" separator). Gate
the injection behind `not _IS_WINDOWS`.
- hermes_cli/gateway.py launch_detached_profile_gateway_restart: outer
Popen + watcher-script Popen both used start_new_session=True, which
Windows silently ignores. Watcher stayed attached to CLI's console,
died when user closed terminal after `hermes update`, left gateway
stale. Now branches through windows_detach_popen_kwargs() helper
(CREATE_NEW_PROCESS_GROUP | DETACHED_PROCESS | CREATE_NO_WINDOW on
Windows, start_new_session=True on POSIX — identical to main).
## MEDIUM fixes
- gateway/run.py /restart and /update handlers: hardcoded bash/setsid
chain crashes on Windows when user triggers /update in-gateway. Now
has sys.platform=="win32" branch using sys.executable + a tiny
Python watcher with proper detach flags. POSIX path is unchanged.
- cli.py _git_repo_root: Git on Windows sometimes returns /c/Users/...
style paths that break subprocess.Popen(cwd=...) and Path().resolve().
Added _normalize_git_bash_path() helper that translates /c/Users,
/cygdrive/c, /mnt/c variants to native C:\Users form. POSIX no-op.
_git_repo_root() now routes every result through it.
- cli.py worktree .worktreeinclude: os.symlink on directories failed
hard on Windows (requires admin or Developer Mode). Falls back to
shutil.copytree with a warning log.
## Tests
- 29 new tests in tests/tools/test_windows_native_support.py covering:
subprocess_compat helpers, TUI entry signal guards, kanban waitpid
guard, code_execution TCP fallback source-level invariants, cron bash
resolution, npm/npx bare-spawn lint per-file, local env Windows temp
dir, PATH injection gating, git bash path normalization, symlink
fallback, gateway detached watcher flags.
- One existing test assertion adjusted in test_browser_homebrew_paths:
it compared captured Popen argv to the BARE `"npx"` literal; after the
shutil.which() change argv[0] is the absolute path. New assertion
checks the shape (two items, second is `agent-browser`) rather than
the exact first-item string. Behaviour unchanged; test was too strict.
All 56 tests pass on Linux (30 from previous commits + 26 new).
267 tests from the affected files/dirs (browser, code_exec, local_env,
process_registry, kanban_db, windows_compat) all pass — zero regressions.
tests/hermes_cli/ (3909 pass) and tests/gateway/ (5021 pass) unchanged;
all pre-existing test failures confirmed unrelated via `git stash` re-run.
## What's still deferred (LOW priority)
- Visible cmd-window flashes on short-lived console apps (~14 sites) —
cosmetic, needs a follow-up pass once we have user reports.
- agent/file_safety.py POSIX-only security deny patterns — separate
hardening task.
- tools/process_registry.py returning "/tmp" as fallback — theoretical;
reachable only when all env-var candidates fail.
2026-05-07 17:29:31 -07:00
""" Connect to the parent ' s RPC server via the transport it picked.
HERMES_RPC_SOCKET can be either :
- a filesystem path ( POSIX Unix domain socket — the default on
Linux and macOS )
- a string of the form ` ` tcp : / / 127.0 .0 .1 : < port > ` ` ( Windows , where
AF_UNIX is unreliable — the parent falls back to loopback TCP )
"""
2026-02-19 23:23:43 -08:00
global _sock
if _sock is None :
feat(windows): close remaining POSIX-only landmines — TUI crash, kanban waitpid, AF_UNIX sandbox, /bin/bash, npm .cmd shims, cwd tracking, detach flags
Second pass on native Windows support, driven by a systematic audit across
five areas: POSIX-only primitives (signal.SIGKILL/SIGHUP/SIGPIPE, os.WNOHANG,
os.setsid), path translation bugs (/c/Users → C:\Users), subprocess patterns
(npm.cmd batch shims, start_new_session no-op on Windows), subsystem health
(cron, gateway daemon, update flow), and module-level import guards.
Every change is platform-gated — POSIX (Linux/macOS) behaviour is preserved
bit-identical. Explicit "do no harm" test: test_posix_path_preserved_on_linux,
test_posix_noop, test_windows_detach_popen_kwargs_is_posix_equivalent_on_posix.
## New module
- hermes_cli/_subprocess_compat.py — shared helpers (resolve_node_command,
windows_detach_flags, windows_hide_flags, windows_detach_popen_kwargs).
All no-ops on non-Windows.
## CRITICAL fixes (would crash or silently break on Windows)
- tui_gateway/entry.py: SIGPIPE/SIGHUP referenced at module top level would
AttributeError on import on Windows, breaking `hermes --tui` entirely (it
spawns this module as a subprocess). Guard each signal.signal() call with
hasattr() and add SIGBREAK as Windows' SIGHUP equivalent.
- hermes_cli/kanban_db.py: os.waitpid(-1, os.WNOHANG) in dispatcher tick was
unguarded. os.WNOHANG doesn't exist on Windows. Gate the whole reap loop
behind `os.name != "nt"` — Windows has no zombies anyway.
- tools/code_execution_tool.py: AF_UNIX socket for execute_code RPC fails on
most Windows builds. Fall back to loopback TCP (AF_INET on 127.0.0.1:0
ephemeral port) when _IS_WINDOWS. HERMES_RPC_SOCKET env var now accepts
either a filesystem path (POSIX) or `tcp://127.0.0.1:<port>` (Windows).
Generated sandbox client parses both.
- cron/scheduler.py: `argv = ["/bin/bash", str(path)]` hardcoded. Use
shutil.which("bash") so Windows (Git Bash via MinGit) works, with a
readable error when bash is genuinely absent.
- 6 bare npm/npx spawn sites: tools_config.py x2, doctor.py, whatsapp.py
(npm install + node version probe), browser_tool.py x2. On Windows npm
is npm.cmd / npx is npx.cmd (batch shims); subprocess.Popen(["npm", ...])
fails with WinError 193. shutil.which(...) returns the absolute .cmd
path which CreateProcessW accepts because the extension routes through
cmd.exe /c. POSIX behaviour unchanged (shutil.which still returns the
same path subprocess would resolve itself).
## HIGH fixes (silent misbehaviour on Windows)
- tools/environments/local.py get_temp_dir: hardcoded /tmp returned on
Windows meant `_cwd_file = "/tmp/hermes-cwd-*.txt"`, which bash wrote
via MSYS2's virtual /tmp but native Python couldn't open. Result: cwd
tracking silently broken — `cd` in terminal tool did nothing. Windows
branch now returns `%HERMES_HOME%/cache/terminal` with forward slashes
(works in both bash and Python, guaranteed no spaces).
- tools/environments/local.py _make_run_env PATH injection: `/usr/bin not
in split(":")` heuristic mangles Windows PATH (";" separator). Gate
the injection behind `not _IS_WINDOWS`.
- hermes_cli/gateway.py launch_detached_profile_gateway_restart: outer
Popen + watcher-script Popen both used start_new_session=True, which
Windows silently ignores. Watcher stayed attached to CLI's console,
died when user closed terminal after `hermes update`, left gateway
stale. Now branches through windows_detach_popen_kwargs() helper
(CREATE_NEW_PROCESS_GROUP | DETACHED_PROCESS | CREATE_NO_WINDOW on
Windows, start_new_session=True on POSIX — identical to main).
## MEDIUM fixes
- gateway/run.py /restart and /update handlers: hardcoded bash/setsid
chain crashes on Windows when user triggers /update in-gateway. Now
has sys.platform=="win32" branch using sys.executable + a tiny
Python watcher with proper detach flags. POSIX path is unchanged.
- cli.py _git_repo_root: Git on Windows sometimes returns /c/Users/...
style paths that break subprocess.Popen(cwd=...) and Path().resolve().
Added _normalize_git_bash_path() helper that translates /c/Users,
/cygdrive/c, /mnt/c variants to native C:\Users form. POSIX no-op.
_git_repo_root() now routes every result through it.
- cli.py worktree .worktreeinclude: os.symlink on directories failed
hard on Windows (requires admin or Developer Mode). Falls back to
shutil.copytree with a warning log.
## Tests
- 29 new tests in tests/tools/test_windows_native_support.py covering:
subprocess_compat helpers, TUI entry signal guards, kanban waitpid
guard, code_execution TCP fallback source-level invariants, cron bash
resolution, npm/npx bare-spawn lint per-file, local env Windows temp
dir, PATH injection gating, git bash path normalization, symlink
fallback, gateway detached watcher flags.
- One existing test assertion adjusted in test_browser_homebrew_paths:
it compared captured Popen argv to the BARE `"npx"` literal; after the
shutil.which() change argv[0] is the absolute path. New assertion
checks the shape (two items, second is `agent-browser`) rather than
the exact first-item string. Behaviour unchanged; test was too strict.
All 56 tests pass on Linux (30 from previous commits + 26 new).
267 tests from the affected files/dirs (browser, code_exec, local_env,
process_registry, kanban_db, windows_compat) all pass — zero regressions.
tests/hermes_cli/ (3909 pass) and tests/gateway/ (5021 pass) unchanged;
all pre-existing test failures confirmed unrelated via `git stash` re-run.
## What's still deferred (LOW priority)
- Visible cmd-window flashes on short-lived console apps (~14 sites) —
cosmetic, needs a follow-up pass once we have user reports.
- agent/file_safety.py POSIX-only security deny patterns — separate
hardening task.
- tools/process_registry.py returning "/tmp" as fallback — theoretical;
reachable only when all env-var candidates fail.
2026-05-07 17:29:31 -07:00
endpoint = os . environ [ " HERMES_RPC_SOCKET " ]
if endpoint . startswith ( " tcp:// " ) :
# tcp://host:port (host is always 127.0.0.1 in practice — we
# only bind loopback server-side)
_host_port = endpoint [ len ( " tcp:// " ) : ]
_host , _ , _port = _host_port . rpartition ( " : " )
_sock = socket . socket ( socket . AF_INET , socket . SOCK_STREAM )
_sock . connect ( ( _host or " 127.0.0.1 " , int ( _port ) ) )
else :
_sock = socket . socket ( socket . AF_UNIX , socket . SOCK_STREAM )
_sock . connect ( endpoint )
2026-02-19 23:23:43 -08:00
_sock . settimeout ( 300 )
return _sock
def _call ( tool_name , args ) :
""" Send a tool call to the parent process and return the parsed result. """
2026-07-01 02:52:04 -07:00
request = json . dumps ( {
" tool " : tool_name ,
" args " : args ,
" token " : os . environ . get ( " HERMES_RPC_TOKEN " , " " ) ,
} ) + " \\ n "
feat(tools): session-persistent kernels for execute_code (kernel_mode: session) (#94647)
* feat(tools): session-persistent kernels for execute_code (kernel_mode: session)
execute_code spawns a fresh Python process per call, so every multi-step
data task re-loads its inputs: a CSV parsed in call one is gone by call
two, and scripts route state through temp files to survive. Hermes
already rewards programmatic tool calling (execute_code-only turns
refund the iteration budget), which makes the missing half — state that
survives between calls — the bottleneck.
Add opt-in `code_execution.kernel_mode: session`: one persistent kernel
per (task, mode, interpreter, cwd, tool-set). Variables, imports, and
loaded data persist across calls; `reset=true` discards state on demand.
The default `per-call` keeps today's behavior byte-for-byte.
Safety posture is unchanged by design: the child env comes from the same
builder as the per-call path (extracted, not duplicated, so the secret
scrubbing / PYTHONPATH hygiene cannot drift), the RPC server is the same
`_rpc_server_loop` with the same token and a per-cell tool budget, and
output passes the same ANSI strip + secret redaction. A timed-out or
interrupted cell kills the whole kernel tree and the next call respawns
— a wedged kernel can never hang the agent. The kernel env is frozen at
spawn; the schema and config comment say so.
Wire protocol: NDJSON requests on the kernel's stdin; responses framed
on stdout behind a per-kernel random sentinel, with unframed bytes
(fd-level output from user-spawned subprocesses) attributed to the
serialized current cell. The generated RPC client reconnects once when
HERMES_RPC_PERSISTENT=1, because a kernel legitimately outlives the RPC
server's 300s idle window between cells.
Tested on macOS 15 (Apple Silicon), Python 3.11: 13 new tests in
tests/tools/test_code_kernel.py (persistence, reset, error-keeps-kernel,
timeout-kills-kernel, sys.exit ends kernel, subprocess fd passthrough,
schema surface, mode fallback) plus the existing
test_code_execution.py / test_code_execution_modes.py suites (81 passed).
* fix(tools): session kernels get a stable owner, bounded lifetime, and per-cell RPC authority
Addresses the blocking review on the session-kernel design: two
authority/lifecycle boundaries were wrong.
1. Ownership and bounded lifetime. The kernel key's first component is
now the conversation's approval session key (_resolve_owner), not the
per-turn task id run_agent mints per top-level invocation — so state
genuinely survives across user turns of one conversation, and delegated
subagent sessions isolate naturally under their own keys (the task id
remains only the last-resort owner for embeds/tests with no session
context). Lifetime is bounded on four edges: kernels are disposed at the
same session boundary that clears the owner's approval/yolo state
(tools.approval.clear_session -> shutdown_kernels_for_owner), reaped
after code_execution.kernel_idle_timeout seconds idle (default 1800,
swept on every entry), capped process-wide at
code_execution.max_session_kernels live children (default 4, LRU
evicted), and still torn down by reset/death/atexit as before. The
ownership + disposal + idle-reap + cap shape deliberately carries
forward the lifecycle invariants of the earlier session-persistent
implementation in #88637 by @z80dev.
2. Per-cell RPC authority. The serving thread no longer freezes the
spawning cell's context/callbacks for the kernel's life. Each cell
installs a CellAuthority — captured on the calling thread exactly as
propagate_context_to_thread would for a per-call RPC thread — before its
request is written, and retires it on every settle path; _rpc_server_loop
gains a dispatch hook the kernel uses to route each tool call through
the CURRENT cell's context, callbacks, and task id. A call arriving with
no active cell is refused. Interpreter state persists; RPC authority
does not.
Composition with the per-script static guard (see the config note): a
persistent namespace lets cell N+1 invoke objects cell N created, which
a single-cell static scan cannot see — the runtime RPC boundary
(allow-list by name, per-cell budget, per-cell authority) is the
operative cross-cell enforcement in this mode, and the adversarial
alias test pins exactly that.
Tests (9 new): state survives across turns of one conversation;
sessions isolate; clear_session disposes the owner's kernels (and the
next turn starts fresh); the live-kernel cap LRU-evicts with evicted
children proven dead; idle kernels are reaped; a later cell's RPC runs
under that cell's approval callback; a cross-cell alias dispatches under
the CURRENT cell's authority; a settled cell's authority refuses
dispatch; each cell installs a fresh authority. 22/22 kernel tests, 81
code-execution tests, ruff clean. The 7 test-order failures in the
tools/-k-approval selection reproduce identically on the clean branch
base (pre-existing pollution, not this change).
* fix(code-kernel): delegated children get their own kernels — child contexts inherit the parent approval key, so qualify the owner with the delegation session id (live-verified leak, both directions)
---------
Co-authored-by: Teknium <127238744+teknium1@users.noreply.github.com>
2026-08-28 04:26:31 +09:00
# Session kernels outlive the RPC server's 300s idle window, so their
# connection can be legitimately gone by the next cell. The server
# re-accepts (HERMES_RPC_PERSISTENT=1); retry once on a fresh socket.
_attempts = 2 if os . environ . get ( " HERMES_RPC_PERSISTENT " ) == " 1 " else 1
2026-04-30 13:20:05 +08:00
with _call_lock :
feat(tools): session-persistent kernels for execute_code (kernel_mode: session) (#94647)
* feat(tools): session-persistent kernels for execute_code (kernel_mode: session)
execute_code spawns a fresh Python process per call, so every multi-step
data task re-loads its inputs: a CSV parsed in call one is gone by call
two, and scripts route state through temp files to survive. Hermes
already rewards programmatic tool calling (execute_code-only turns
refund the iteration budget), which makes the missing half — state that
survives between calls — the bottleneck.
Add opt-in `code_execution.kernel_mode: session`: one persistent kernel
per (task, mode, interpreter, cwd, tool-set). Variables, imports, and
loaded data persist across calls; `reset=true` discards state on demand.
The default `per-call` keeps today's behavior byte-for-byte.
Safety posture is unchanged by design: the child env comes from the same
builder as the per-call path (extracted, not duplicated, so the secret
scrubbing / PYTHONPATH hygiene cannot drift), the RPC server is the same
`_rpc_server_loop` with the same token and a per-cell tool budget, and
output passes the same ANSI strip + secret redaction. A timed-out or
interrupted cell kills the whole kernel tree and the next call respawns
— a wedged kernel can never hang the agent. The kernel env is frozen at
spawn; the schema and config comment say so.
Wire protocol: NDJSON requests on the kernel's stdin; responses framed
on stdout behind a per-kernel random sentinel, with unframed bytes
(fd-level output from user-spawned subprocesses) attributed to the
serialized current cell. The generated RPC client reconnects once when
HERMES_RPC_PERSISTENT=1, because a kernel legitimately outlives the RPC
server's 300s idle window between cells.
Tested on macOS 15 (Apple Silicon), Python 3.11: 13 new tests in
tests/tools/test_code_kernel.py (persistence, reset, error-keeps-kernel,
timeout-kills-kernel, sys.exit ends kernel, subprocess fd passthrough,
schema surface, mode fallback) plus the existing
test_code_execution.py / test_code_execution_modes.py suites (81 passed).
* fix(tools): session kernels get a stable owner, bounded lifetime, and per-cell RPC authority
Addresses the blocking review on the session-kernel design: two
authority/lifecycle boundaries were wrong.
1. Ownership and bounded lifetime. The kernel key's first component is
now the conversation's approval session key (_resolve_owner), not the
per-turn task id run_agent mints per top-level invocation — so state
genuinely survives across user turns of one conversation, and delegated
subagent sessions isolate naturally under their own keys (the task id
remains only the last-resort owner for embeds/tests with no session
context). Lifetime is bounded on four edges: kernels are disposed at the
same session boundary that clears the owner's approval/yolo state
(tools.approval.clear_session -> shutdown_kernels_for_owner), reaped
after code_execution.kernel_idle_timeout seconds idle (default 1800,
swept on every entry), capped process-wide at
code_execution.max_session_kernels live children (default 4, LRU
evicted), and still torn down by reset/death/atexit as before. The
ownership + disposal + idle-reap + cap shape deliberately carries
forward the lifecycle invariants of the earlier session-persistent
implementation in #88637 by @z80dev.
2. Per-cell RPC authority. The serving thread no longer freezes the
spawning cell's context/callbacks for the kernel's life. Each cell
installs a CellAuthority — captured on the calling thread exactly as
propagate_context_to_thread would for a per-call RPC thread — before its
request is written, and retires it on every settle path; _rpc_server_loop
gains a dispatch hook the kernel uses to route each tool call through
the CURRENT cell's context, callbacks, and task id. A call arriving with
no active cell is refused. Interpreter state persists; RPC authority
does not.
Composition with the per-script static guard (see the config note): a
persistent namespace lets cell N+1 invoke objects cell N created, which
a single-cell static scan cannot see — the runtime RPC boundary
(allow-list by name, per-cell budget, per-cell authority) is the
operative cross-cell enforcement in this mode, and the adversarial
alias test pins exactly that.
Tests (9 new): state survives across turns of one conversation;
sessions isolate; clear_session disposes the owner's kernels (and the
next turn starts fresh); the live-kernel cap LRU-evicts with evicted
children proven dead; idle kernels are reaped; a later cell's RPC runs
under that cell's approval callback; a cross-cell alias dispatches under
the CURRENT cell's authority; a settled cell's authority refuses
dispatch; each cell installs a fresh authority. 22/22 kernel tests, 81
code-execution tests, ruff clean. The 7 test-order failures in the
tools/-k-approval selection reproduce identically on the clean branch
base (pre-existing pollution, not this change).
* fix(code-kernel): delegated children get their own kernels — child contexts inherit the parent approval key, so qualify the owner with the delegation session id (live-verified leak, both directions)
---------
Co-authored-by: Teknium <127238744+teknium1@users.noreply.github.com>
2026-08-28 04:26:31 +09:00
for _attempt in range ( _attempts ) :
try :
conn = _connect ( )
conn . sendall ( request . encode ( ) )
buf = b " "
while True :
chunk = conn . recv ( 65536 )
if not chunk :
raise RuntimeError ( " Agent process disconnected " )
buf + = chunk
if buf . endswith ( b " \\ n " ) :
break
2026-04-30 13:20:05 +08:00
break
feat(tools): session-persistent kernels for execute_code (kernel_mode: session) (#94647)
* feat(tools): session-persistent kernels for execute_code (kernel_mode: session)
execute_code spawns a fresh Python process per call, so every multi-step
data task re-loads its inputs: a CSV parsed in call one is gone by call
two, and scripts route state through temp files to survive. Hermes
already rewards programmatic tool calling (execute_code-only turns
refund the iteration budget), which makes the missing half — state that
survives between calls — the bottleneck.
Add opt-in `code_execution.kernel_mode: session`: one persistent kernel
per (task, mode, interpreter, cwd, tool-set). Variables, imports, and
loaded data persist across calls; `reset=true` discards state on demand.
The default `per-call` keeps today's behavior byte-for-byte.
Safety posture is unchanged by design: the child env comes from the same
builder as the per-call path (extracted, not duplicated, so the secret
scrubbing / PYTHONPATH hygiene cannot drift), the RPC server is the same
`_rpc_server_loop` with the same token and a per-cell tool budget, and
output passes the same ANSI strip + secret redaction. A timed-out or
interrupted cell kills the whole kernel tree and the next call respawns
— a wedged kernel can never hang the agent. The kernel env is frozen at
spawn; the schema and config comment say so.
Wire protocol: NDJSON requests on the kernel's stdin; responses framed
on stdout behind a per-kernel random sentinel, with unframed bytes
(fd-level output from user-spawned subprocesses) attributed to the
serialized current cell. The generated RPC client reconnects once when
HERMES_RPC_PERSISTENT=1, because a kernel legitimately outlives the RPC
server's 300s idle window between cells.
Tested on macOS 15 (Apple Silicon), Python 3.11: 13 new tests in
tests/tools/test_code_kernel.py (persistence, reset, error-keeps-kernel,
timeout-kills-kernel, sys.exit ends kernel, subprocess fd passthrough,
schema surface, mode fallback) plus the existing
test_code_execution.py / test_code_execution_modes.py suites (81 passed).
* fix(tools): session kernels get a stable owner, bounded lifetime, and per-cell RPC authority
Addresses the blocking review on the session-kernel design: two
authority/lifecycle boundaries were wrong.
1. Ownership and bounded lifetime. The kernel key's first component is
now the conversation's approval session key (_resolve_owner), not the
per-turn task id run_agent mints per top-level invocation — so state
genuinely survives across user turns of one conversation, and delegated
subagent sessions isolate naturally under their own keys (the task id
remains only the last-resort owner for embeds/tests with no session
context). Lifetime is bounded on four edges: kernels are disposed at the
same session boundary that clears the owner's approval/yolo state
(tools.approval.clear_session -> shutdown_kernels_for_owner), reaped
after code_execution.kernel_idle_timeout seconds idle (default 1800,
swept on every entry), capped process-wide at
code_execution.max_session_kernels live children (default 4, LRU
evicted), and still torn down by reset/death/atexit as before. The
ownership + disposal + idle-reap + cap shape deliberately carries
forward the lifecycle invariants of the earlier session-persistent
implementation in #88637 by @z80dev.
2. Per-cell RPC authority. The serving thread no longer freezes the
spawning cell's context/callbacks for the kernel's life. Each cell
installs a CellAuthority — captured on the calling thread exactly as
propagate_context_to_thread would for a per-call RPC thread — before its
request is written, and retires it on every settle path; _rpc_server_loop
gains a dispatch hook the kernel uses to route each tool call through
the CURRENT cell's context, callbacks, and task id. A call arriving with
no active cell is refused. Interpreter state persists; RPC authority
does not.
Composition with the per-script static guard (see the config note): a
persistent namespace lets cell N+1 invoke objects cell N created, which
a single-cell static scan cannot see — the runtime RPC boundary
(allow-list by name, per-cell budget, per-cell authority) is the
operative cross-cell enforcement in this mode, and the adversarial
alias test pins exactly that.
Tests (9 new): state survives across turns of one conversation;
sessions isolate; clear_session disposes the owner's kernels (and the
next turn starts fresh); the live-kernel cap LRU-evicts with evicted
children proven dead; idle kernels are reaped; a later cell's RPC runs
under that cell's approval callback; a cross-cell alias dispatches under
the CURRENT cell's authority; a settled cell's authority refuses
dispatch; each cell installs a fresh authority. 22/22 kernel tests, 81
code-execution tests, ruff clean. The 7 test-order failures in the
tools/-k-approval selection reproduce identically on the clean branch
base (pre-existing pollution, not this change).
* fix(code-kernel): delegated children get their own kernels — child contexts inherit the parent approval key, so qualify the owner with the delegation session id (live-verified leak, both directions)
---------
Co-authored-by: Teknium <127238744+teknium1@users.noreply.github.com>
2026-08-28 04:26:31 +09:00
except ( OSError , RuntimeError ) :
global _sock
try :
if _sock is not None :
_sock . close ( )
except OSError :
pass
_sock = None
if _attempt + 1 > = _attempts :
raise
2026-02-19 23:23:43 -08:00
raw = buf . decode ( ) . strip ( )
result = json . loads ( raw )
if isinstance ( result , str ) :
try :
return json . loads ( result )
except ( json . JSONDecodeError , TypeError ) :
return result
return result
'''
2026-04-04 12:57:49 -07:00
# ---- File-based transport (remote backends) -------------------------------
_FILE_TRANSPORT_HEADER = ''' \
""" Auto-generated Hermes tools RPC stubs (file-based transport). """
2026-04-30 13:20:05 +08:00
import json , os , shlex , tempfile , threading , time
2026-04-04 12:57:49 -07:00
2026-04-09 13:46:08 +02:00
_RPC_DIR = os . environ . get ( " HERMES_RPC_DIR " ) or os . path . join ( tempfile . gettempdir ( ) , " hermes_rpc " )
2026-04-04 12:57:49 -07:00
_seq = 0
2026-04-30 13:20:05 +08:00
# `_seq += 1` is not atomic (read-modify-write), so concurrent _call()
# invocations from multiple threads could allocate the same sequence number
# and clobber each other's request files. Guard seq allocation with a lock.
_seq_lock = threading . Lock ( )
2026-04-04 12:57:49 -07:00
''' + _COMMON_HELPERS + ''' \
def _call ( tool_name , args ) :
""" Send a tool call request via file-based RPC and wait for response. """
global _seq
2026-04-30 13:20:05 +08:00
with _seq_lock :
_seq + = 1
seq = _seq
seq_str = f " { seq : 06d } "
2026-04-04 12:57:49 -07:00
req_file = os . path . join ( _RPC_DIR , f " req_ { seq_str } " )
res_file = os . path . join ( _RPC_DIR , f " res_ { seq_str } " )
2026-05-07 18:52:59 -07:00
# Write request atomically (write to .tmp, then rename).
# encoding="utf-8" is critical: on Windows-hosted remote backends
# (or any non-UTF-8 locale) the default open() mode would mangle
# non-ASCII chars in tool args when encoding them as JSON.
2026-04-04 12:57:49 -07:00
tmp = req_file + " .tmp "
2026-05-07 18:52:59 -07:00
with open ( tmp , " w " , encoding = " utf-8 " ) as f :
2026-07-01 02:52:04 -07:00
json . dump ( {
" tool " : tool_name ,
" args " : args ,
" seq " : seq ,
" token " : os . environ . get ( " HERMES_RPC_TOKEN " , " " ) ,
} , f )
2026-04-04 12:57:49 -07:00
os . rename ( tmp , req_file )
# Wait for response with adaptive polling
deadline = time . monotonic ( ) + 300 # 5-minute timeout per tool call
poll_interval = 0.05 # Start at 50ms
while not os . path . exists ( res_file ) :
if time . monotonic ( ) > deadline :
raise RuntimeError ( f " RPC timeout: no response for { tool_name } after 300s " )
time . sleep ( poll_interval )
poll_interval = min ( poll_interval * 1.2 , 0.25 ) # Back off to 250ms
2026-05-07 18:52:59 -07:00
with open ( res_file , encoding = " utf-8 " ) as f :
2026-04-04 12:57:49 -07:00
raw = f . read ( )
# Clean up response file
try :
os . unlink ( res_file )
except OSError :
pass
result = json . loads ( raw )
if isinstance ( result , str ) :
try :
return json . loads ( result )
except ( json . JSONDecodeError , TypeError ) :
return result
return result
'''
2026-02-19 23:23:43 -08:00
2026-09-02 23:00:08 -07:00
# ---- Remote execution support (file-based RPC via terminal backend) ----
2026-02-19 23:23:43 -08:00
2026-04-04 12:57:49 -07:00
def _get_or_create_env ( task_id : str ) :
2026-09-02 22:33:03 -07:00
""" ``(env, env_type)`` — the environment the terminal/file tools share for *task_id*, created on
first use ( same double - checked per - task lock pattern as file_tools . _get_file_ops ) . """
2026-09-05 18:25:05 +05:30
from tools . terminal_tool_backends import _container_config_from_config , _create_environment , _ssh_config_from_config
2026-04-04 12:57:49 -07:00
from tools . terminal_tool import (
2026-09-03 13:24:04 -07:00
_active_environments , _env_lock , _get_env_config , _last_activity ,
2026-09-02 22:10:19 -07:00
_start_cleanup_thread , _creation_locks , _creation_locks_lock , _task_env_overrides ,
_resolve_container_task_id , _resolve_task_host_cwd , _is_container_backend , _select_image ,
2026-04-04 12:57:49 -07:00
)
feat(terminal): collapse subagent task_ids to shared container (#16177)
Before: delegate_task children each allocated their own terminal
sandbox keyed by child task_id. Starting extra containers (or Modal
sandboxes / Daytona workspaces) is expensive, and the subagent's work
is invisible to the parent — files written by the child in its
container don't exist in the parent's when the subagent returns.
After: a single `_resolve_container_task_id` helper maps any
tool-call task_id to "default" UNLESS an env override is registered
for it. The parent agent and all delegate_task children therefore
share one long-lived sandbox — installed packages, cwd, /workspace
files, and /tmp scratch carry over freely between them.
RL and benchmark environments (TerminalBench2, HermesSweEnv, ...)
opt in to isolation via `register_task_env_overrides(task_id, {...})`;
those task_ids survive the collapse and get their own sandbox,
preserving the per-task Docker image behavior these benchmarks rely on.
file_state / active-subagents registry / TUI events still key off the
original child task_id, so the 'subagent wrote a file the parent read'
warning and UI per-subagent panels keep working.
Tradeoff: parallel delegate_task children (tasks=[...]) now share one
bash/container. Concurrent cd, env-var mutations, and writes to the
same path will collide. If that bites a specific workflow, the
subagent can opt back into isolation via register_task_env_overrides.
Applied at four lookup sites:
- tools/terminal_tool.py terminal_tool() and get_active_env()
- tools/file_tools.py _get_file_ops() and _get_live_tracking_cwd()
- tools/code_execution_tool.py _get_or_create_environment()
Docs: website/docs/user-guide/configuration.md updated to reflect the
shared-container reality and document the RL/benchmark carve-out.
Tests: tests/tools/test_shared_container_task_id.py (9 cases).
2026-04-26 11:55:02 -07:00
effective_task_id = _resolve_container_task_id ( task_id )
2026-09-02 22:10:19 -07:00
def _cached ( ) :
2026-04-04 12:57:49 -07:00
with _env_lock :
2026-09-02 22:10:19 -07:00
env = _active_environments . get ( effective_task_id )
if env is not None :
2026-04-04 12:57:49 -07:00
_last_activity [ effective_task_id ] = time . time ( )
2026-09-02 22:10:19 -07:00
return env
env = _cached ( )
if env is not None :
return env , _get_env_config ( ) [ " env_type " ]
2026-04-04 12:57:49 -07:00
with _creation_locks_lock :
2026-09-02 22:10:19 -07:00
task_lock = _creation_locks . setdefault ( effective_task_id , threading . Lock ( ) )
2026-04-04 12:57:49 -07:00
with task_lock :
2026-09-02 22:10:19 -07:00
env = _cached ( )
if env is not None :
return env , _get_env_config ( ) [ " env_type " ]
2026-04-04 12:57:49 -07:00
config = _get_env_config ( )
env_type = config [ " env_type " ]
overrides = _task_env_overrides . get ( effective_task_id , { } )
container_config = None
2026-09-02 22:10:19 -07:00
if _is_container_backend ( env_type ) :
2026-09-05 18:25:05 +05:30
# Shared shaper: execute_code's own key subset dropped docker_extra_args / docker_forward_env /
# docker_env, so a sandbox created from this path lost the operator's configured settings.
container_config = _container_config_from_config ( config )
2026-04-04 12:57:49 -07:00
logger . info ( " Creating new %s environment for execute_code task %s ... " ,
env_type , effective_task_id [ : 8 ] )
env = _create_environment (
2026-09-02 22:33:03 -07:00
env_type = env_type , image = _select_image ( env_type , overrides , config ) ,
cwd = overrides . get ( " cwd " ) or config [ " cwd " ] , timeout = config [ " timeout " ] ,
2026-09-02 22:10:19 -07:00
ssh_config = _ssh_config_from_config ( config ) if env_type == " ssh " else None ,
2026-04-04 12:57:49 -07:00
container_config = container_config ,
2026-09-02 22:10:19 -07:00
local_config = { " persistent " : config . get ( " local_persistent " , False ) } if env_type == " local " else None ,
2026-09-02 22:33:03 -07:00
task_id = effective_task_id , host_cwd = _resolve_task_host_cwd ( config , task_id ) ,
2026-04-04 12:57:49 -07:00
)
with _env_lock :
_active_environments [ effective_task_id ] = env
_last_activity [ effective_task_id ] = time . time ( )
_start_cleanup_thread ( )
logger . info ( " %s environment ready for execute_code task %s " ,
env_type , effective_task_id [ : 8 ] )
return env , env_type
def _ship_file_to_remote ( env , remote_path : str , content : str ) - > None :
2026-09-02 22:33:03 -07:00
""" Write *content* to *remote_path* via ``echo … | base64 -d`` — some backends (Modal) don ' t
reliably deliver stdin_data to chained commands ; base64 is shell - safe inside single quotes . """
2026-04-04 12:57:49 -07:00
encoded = base64 . b64encode ( content . encode ( " utf-8 " ) ) . decode ( " ascii " )
2026-09-02 22:10:19 -07:00
env . execute ( f " echo ' { encoded } ' | base64 -d > { shlex . quote ( remote_path ) } " , cwd = " / " , timeout = 30 )
2026-04-04 12:57:49 -07:00
2026-04-09 13:46:08 +02:00
def _env_temp_dir ( env : Any ) - > str :
""" Return a writable temp dir for env-backed execute_code sandboxes. """
2026-09-02 22:10:19 -07:00
temp_dir = None
2026-04-09 13:46:08 +02:00
get_temp_dir = getattr ( env , " get_temp_dir " , None )
if callable ( get_temp_dir ) :
try :
temp_dir = get_temp_dir ( )
except Exception as exc :
logger . debug ( " Could not resolve execute_code env temp dir: %s " , exc )
2026-09-02 22:10:19 -07:00
for candidate in ( temp_dir , tempfile . gettempdir ( ) ) :
if isinstance ( candidate , str ) and candidate . startswith ( " / " ) :
return candidate . rstrip ( " / " ) or " / "
2026-04-09 13:46:08 +02:00
return " /tmp "
2026-08-24 01:38:06 +08:00
def _format_interrupted_output ( stdout_text : str ) - > str :
""" Append an interruption marker without guessing who caused it. """
from tools . interrupt import get_interrupt_reason
reason = get_interrupt_reason ( )
2026-09-02 22:10:19 -07:00
marker = f " [execution interrupted — { reason } ] " if reason else " [execution interrupted] "
2026-08-24 01:38:06 +08:00
return f " { stdout_text } \n { marker } " if stdout_text else marker
2026-09-02 12:11:59 -07:00
def _clean_output ( stdout_text : str ) - > Tuple [ str , Dict [ str , Any ] ] :
2026-09-02 22:33:03 -07:00
""" Shared output pipeline: byte-cap (with spill), ANSI strip, secret redaction. code_file=True:
output often echoes source / config — skip ENV / JSON / f - string false positives , still mask credentials . """
2026-08-28 01:39:33 -07:00
from tools . ansi_strip import strip_ansi
from agent . redact import redact_sensitive_text
2026-09-02 12:11:59 -07:00
stdout_text , metadata = _truncate_stdout_text ( stdout_text )
return redact_sensitive_text ( strip_ansi ( stdout_text ) , code_file = True ) , metadata
2026-08-28 01:39:33 -07:00
2026-09-02 12:11:59 -07:00
def _with_timeout_notice ( stdout_text : str , timeout_msg : str ) - > str :
2026-09-02 22:33:03 -07:00
""" Timeout message goes in the output too — an empty result makes models answer as if
nothing happened , and the gateway drops empty replies . """
2026-09-02 12:11:59 -07:00
return stdout_text + f " \n \n ⏰ { timeout_msg } " if stdout_text else f " ⏰ { timeout_msg } "
2026-08-28 01:39:33 -07:00
2026-09-02 12:11:59 -07:00
def _error_result ( error : str , * , tool_calls_made : int = 0 , duration : float = 0 ) - > str :
2026-09-02 22:33:03 -07:00
return json . dumps ( { " status " : " error " , " error " : error , " tool_calls_made " : tool_calls_made ,
" duration_seconds " : duration } , ensure_ascii = False )
2026-08-28 01:39:33 -07:00
2026-09-02 22:10:19 -07:00
def _remote_failure ( exc : BaseException , exec_start : float , tool_calls_made : int ) - > str :
duration = round ( time . monotonic ( ) - exec_start , 2 )
logger . error ( " execute_code remote failed after %s s with %d tool calls: %s : %s " ,
duration , tool_calls_made , type ( exc ) . __name__ , exc , exc_info = True )
return _error_result ( str ( exc ) , tool_calls_made = tool_calls_made , duration = duration )
2026-08-28 01:39:33 -07:00
2026-04-04 12:57:49 -07:00
2026-09-02 12:11:59 -07:00
_REMOTE_EXIT_STATUS = { 124 : " timeout " , 130 : " interrupted " }
2026-04-04 12:57:49 -07:00
2026-09-02 22:33:03 -07:00
def _remote_result ( status : str , raw_stdout : str , exec_start : float , fields : Dict [ str , Any ] ,
kernel : Optional [ Dict [ str , Any ] ] = None ) - > Dict [ str , Any ] :
""" Common remote reply shape: status, cleaned output, *fields*, duration, optional kernel
info , then truncation metadata ( key order is part of the result contract ) . """
stdout_text , stdout_metadata = _clean_output ( raw_stdout )
result : Dict [ str , Any ] = { " status " : status , " output " : stdout_text , * * fields ,
" duration_seconds " : round ( time . monotonic ( ) - exec_start , 2 ) }
if kernel is not None :
result [ " kernel " ] = kernel
result . update ( stdout_metadata )
return result
2026-04-04 12:57:49 -07:00
2026-09-02 22:33:03 -07:00
def _apply_timeout ( result : Dict [ str , Any ] , timeout_msg : str ) - > None :
result [ " error " ] = timeout_msg
result [ " output " ] = _with_timeout_notice ( result [ " output " ] , timeout_msg )
2026-04-04 12:57:49 -07:00
2026-09-02 12:11:59 -07:00
def _finish_remote_kernel_result ( kernel_result : Dict [ str , Any ] , * ,
timeout : int , exec_start : float ) - > str :
2026-09-02 22:33:03 -07:00
""" Post-process a remote-kernel cell result into the tool ' s JSON reply. Timeout messaging
mirrors the local kernel contract ( kernel killed , state lost , next call fresh ) . """
2026-08-28 01:39:33 -07:00
stdout_text = kernel_result . get ( " stdout " , " " ) or " "
stderr_text = kernel_result . get ( " stderr " , " " ) or " "
traceback_text = kernel_result . get ( " traceback " , " " ) or " "
if stderr_text or traceback_text :
2026-09-02 12:11:59 -07:00
# Same joining shape as the local kernel: stderr and traceback ride in
# the output under one marker so the model sees the failure inline.
2026-09-02 22:10:19 -07:00
stdout_text = stdout_text + " \n --- stderr --- \n " + stderr_text + traceback_text
2026-09-02 22:33:03 -07:00
result = _remote_result ( kernel_result . get ( " status " , " error " ) , stdout_text , exec_start ,
{ " tool_calls_made " : kernel_result . get ( " tool_calls_made " , 0 ) } ,
kernel = kernel_result . get ( " kernel " , { " remote " : True } ) )
2026-08-28 01:39:33 -07:00
if result [ " status " ] == " timeout " :
2026-09-02 22:33:03 -07:00
_apply_timeout ( result , f " Cell timed out after { timeout } s; the remote session kernel was "
" killed and its state was lost. The next call starts fresh. " )
2026-08-28 01:39:33 -07:00
elif result [ " status " ] == " error " and kernel_result . get ( " error " ) :
result [ " error " ] = kernel_result [ " error " ]
return json . dumps ( result , ensure_ascii = False )
2026-09-02 12:11:59 -07:00
def _sandbox_tools_for ( enabled_tools : Optional [ List [ str ] ] ) - > frozenset :
2026-09-02 22:33:03 -07:00
""" Enabled ∩ SANDBOX_ALLOWED_TOOLS, or every sandbox tool when the intersection is empty. """
2026-09-02 12:11:59 -07:00
return frozenset ( SANDBOX_ALLOWED_TOOLS & set ( enabled_tools or ( ) ) ) or SANDBOX_ALLOWED_TOOLS
2026-08-28 01:39:33 -07:00
2026-04-04 12:57:49 -07:00
2026-09-02 22:10:19 -07:00
def _run_remote_per_call ( env , env_type : str , code : str , effective_task_id : str ,
sandbox_tools : frozenset , * , timeout : int , max_tool_calls : int ,
exec_start : float ) - > str :
2026-09-02 22:33:03 -07:00
""" Per-call script ship: stage hermes_tools.py + script.py in a fresh remote sandbox dir,
serve file - RPC from a polling thread , run , clean up . """
2026-09-02 12:11:59 -07:00
sandbox_dir = f " { _env_temp_dir ( env ) } /hermes_exec_ { uuid . uuid4 ( ) . hex [ : 12 ] } "
2026-04-09 13:46:08 +02:00
quoted_sandbox_dir = shlex . quote ( sandbox_dir )
quoted_rpc_dir = shlex . quote ( f " { sandbox_dir } /rpc " )
2026-09-02 23:00:08 -07:00
tool_call_counter , stop_event , rpc_thread = [ 0 ] , threading . Event ( ) , None
2026-04-04 12:57:49 -07:00
try :
2026-09-02 12:11:59 -07:00
env . execute ( f " mkdir -p { quoted_rpc_dir } " , cwd = " / " , timeout = 10 )
2026-07-01 02:52:04 -07:00
rpc_token = secrets . token_urlsafe ( 32 )
2026-09-02 22:10:19 -07:00
_ship_file_to_remote ( env , f " { sandbox_dir } /hermes_tools.py " ,
generate_hermes_tools_module ( list ( sandbox_tools ) , transport = " file " ) )
2026-04-04 12:57:49 -07:00
_ship_file_to_remote ( env , f " { sandbox_dir } /script.py " , code )
2026-05-28 17:47:09 -04:00
# Wrapped so the thread inherits the turn's approval context + callbacks
2026-09-02 12:11:59 -07:00
# (tools.thread_context) — else sandbox RPC tool calls lose approval routing.
2026-09-03 09:44:26 -07:00
# See #30882.
2026-04-04 12:57:49 -07:00
rpc_thread = threading . Thread (
2026-09-02 23:00:08 -07:00
target = propagate_context_to_thread ( _rpc_poll_loop ) , daemon = True ,
args = ( env , f " { sandbox_dir } /rpc " , effective_task_id , [ ] , tool_call_counter ,
max_tool_calls , sandbox_tools , stop_event , rpc_token ) )
2026-04-04 12:57:49 -07:00
rpc_thread . start ( )
2026-09-02 23:00:08 -07:00
env_prefix = ( f " HERMES_RPC_DIR= { quoted_rpc_dir } HERMES_RPC_TOKEN= { shlex . quote ( rpc_token ) } "
" PYTHONDONTWRITEBYTECODE=1 " )
2026-04-04 12:57:49 -07:00
tz = os . getenv ( " HERMES_TIMEZONE " , " " ) . strip ( )
if tz :
2026-04-12 03:06:53 +03:00
env_prefix + = f " TZ= { shlex . quote ( tz ) } "
2026-09-02 22:10:19 -07:00
logger . info ( " Executing code on %s backend (task %s )... " , env_type , effective_task_id [ : 8 ] )
script_result = env . execute ( f " cd { quoted_sandbox_dir } && { env_prefix } python3 script.py " ,
timeout = timeout )
2026-05-31 21:59:24 +03:30
stdout_text = script_result . get ( " output " , " " ) or " "
2026-04-04 12:57:49 -07:00
exit_code = script_result . get ( " returncode " , - 1 )
2026-09-02 12:11:59 -07:00
# Backend exit codes: 124 = timeout wrapper, 130 = SIGINT.
status = _REMOTE_EXIT_STATUS . get ( exit_code , " success " )
2026-04-04 12:57:49 -07:00
except Exception as exc :
2026-09-02 22:10:19 -07:00
return _remote_failure ( exc , exec_start , tool_call_counter [ 0 ] )
2026-04-04 12:57:49 -07:00
finally :
stop_event . set ( )
if rpc_thread is not None :
rpc_thread . join ( timeout = 5 )
try :
2026-09-02 12:11:59 -07:00
env . execute ( f " rm -rf { quoted_sandbox_dir } " , cwd = " / " , timeout = 15 )
2026-04-04 12:57:49 -07:00
except Exception :
logger . debug ( " Failed to clean up remote sandbox %s " , sandbox_dir )
2026-09-02 22:33:03 -07:00
result = _remote_result ( status , stdout_text , exec_start ,
{ " exit_code " : exit_code , " tool_calls_made " : tool_call_counter [ 0 ] } )
2026-04-04 12:57:49 -07:00
if status == " timeout " :
2026-09-02 22:33:03 -07:00
_apply_timeout ( result , f " Script timed out after { timeout } s and was killed. " )
2026-09-02 22:10:19 -07:00
logger . warning ( " execute_code (remote) timed out after %s s (limit %s s) with %d tool calls " ,
2026-09-02 22:33:03 -07:00
result [ " duration_seconds " ] , timeout , tool_call_counter [ 0 ] )
2026-04-04 12:57:49 -07:00
elif status == " interrupted " :
2026-09-02 22:33:03 -07:00
result [ " output " ] = _format_interrupted_output ( result [ " output " ] )
2026-04-04 12:57:49 -07:00
elif exit_code != 0 :
result [ " status " ] = " error "
result [ " error " ] = f " Script exited with code { exit_code } "
return json . dumps ( result , ensure_ascii = False )
2026-09-02 22:10:19 -07:00
def _execute_remote ( code : str , task_id : Optional [ str ] , enabled_tools : Optional [ List [ str ] ] ,
reset : bool = False ) - > str :
2026-09-02 22:33:03 -07:00
""" Run code on the remote terminal backend: the owner ' s persistent remote session kernel
( tools / code_kernel_remote . py ) first , else the per - call script ship — the fail - open route when
a kernel cannot be spawned and the only route for hosts that cannot sustain a background process . """
2026-09-02 22:10:19 -07:00
_cfg = _load_config ( )
2026-09-02 23:00:08 -07:00
timeout , max_tool_calls = _cfg . get ( " timeout " , DEFAULT_TIMEOUT ) , _cfg . get ( " max_tool_calls " , DEFAULT_MAX_TOOL_CALLS )
sandbox_tools , effective_task_id = _sandbox_tools_for ( enabled_tools ) , task_id or " default "
2026-09-02 22:10:19 -07:00
env , env_type = _get_or_create_env ( effective_task_id )
exec_start = time . monotonic ( )
try :
py_check = env . execute ( " command -v python3 >/dev/null 2>&1 && echo OK " , cwd = " / " , timeout = 15 )
if " OK " not in py_check . get ( " output " , " " ) :
2026-09-02 22:45:21 -07:00
return _error_result ( f " Python 3 is not available in the { env_type } terminal "
" environment. Install Python to use execute_code with remote backends. " )
2026-09-02 22:10:19 -07:00
# Session-kernel path: one persistent kernel per owner on the
# run-to-completion transport. Spawn failure falls OPEN to the per-call
# path below so a degraded remote host never blocks execution.
try :
2026-09-03 09:44:26 -07:00
# --- Session-kernel path (hermes-agent#96873) ------------------- Same always-on model as
# local: one persistent kernel per owner, rebuilt on the run-to-completion transport (detached
# runner + file cell protocol).
2026-09-02 22:10:19 -07:00
from tools . code_kernel_remote import execute_in_remote_kernel
kernel_result = execute_in_remote_kernel (
code , env = env , env_type = env_type , task_env_id = effective_task_id ,
sandbox_tools = frozenset ( sandbox_tools ) , timeout = timeout ,
max_tool_calls = max_tool_calls , reset = bool ( reset ) ,
idle_exit = int ( _cfg . get ( " kernel_idle_timeout " , 1800 ) ) ,
)
except Exception :
logger . warning ( " remote session-kernel path failed; falling back to per-call " , exc_info = True )
kernel_result = None
if kernel_result is not None :
return _finish_remote_kernel_result ( kernel_result , timeout = timeout , exec_start = exec_start )
logger . info ( " remote session kernel unavailable on %s ; using per-call path " , env_type )
except Exception as exc :
return _remote_failure ( exc , exec_start , 0 )
return _run_remote_per_call ( env , env_type , code , effective_task_id , sandbox_tools ,
timeout = timeout , max_tool_calls = max_tool_calls , exec_start = exec_start )
2026-02-19 23:23:43 -08:00
feat(tools): session-persistent kernels for execute_code (kernel_mode: session) (#94647)
* feat(tools): session-persistent kernels for execute_code (kernel_mode: session)
execute_code spawns a fresh Python process per call, so every multi-step
data task re-loads its inputs: a CSV parsed in call one is gone by call
two, and scripts route state through temp files to survive. Hermes
already rewards programmatic tool calling (execute_code-only turns
refund the iteration budget), which makes the missing half — state that
survives between calls — the bottleneck.
Add opt-in `code_execution.kernel_mode: session`: one persistent kernel
per (task, mode, interpreter, cwd, tool-set). Variables, imports, and
loaded data persist across calls; `reset=true` discards state on demand.
The default `per-call` keeps today's behavior byte-for-byte.
Safety posture is unchanged by design: the child env comes from the same
builder as the per-call path (extracted, not duplicated, so the secret
scrubbing / PYTHONPATH hygiene cannot drift), the RPC server is the same
`_rpc_server_loop` with the same token and a per-cell tool budget, and
output passes the same ANSI strip + secret redaction. A timed-out or
interrupted cell kills the whole kernel tree and the next call respawns
— a wedged kernel can never hang the agent. The kernel env is frozen at
spawn; the schema and config comment say so.
Wire protocol: NDJSON requests on the kernel's stdin; responses framed
on stdout behind a per-kernel random sentinel, with unframed bytes
(fd-level output from user-spawned subprocesses) attributed to the
serialized current cell. The generated RPC client reconnects once when
HERMES_RPC_PERSISTENT=1, because a kernel legitimately outlives the RPC
server's 300s idle window between cells.
Tested on macOS 15 (Apple Silicon), Python 3.11: 13 new tests in
tests/tools/test_code_kernel.py (persistence, reset, error-keeps-kernel,
timeout-kills-kernel, sys.exit ends kernel, subprocess fd passthrough,
schema surface, mode fallback) plus the existing
test_code_execution.py / test_code_execution_modes.py suites (81 passed).
* fix(tools): session kernels get a stable owner, bounded lifetime, and per-cell RPC authority
Addresses the blocking review on the session-kernel design: two
authority/lifecycle boundaries were wrong.
1. Ownership and bounded lifetime. The kernel key's first component is
now the conversation's approval session key (_resolve_owner), not the
per-turn task id run_agent mints per top-level invocation — so state
genuinely survives across user turns of one conversation, and delegated
subagent sessions isolate naturally under their own keys (the task id
remains only the last-resort owner for embeds/tests with no session
context). Lifetime is bounded on four edges: kernels are disposed at the
same session boundary that clears the owner's approval/yolo state
(tools.approval.clear_session -> shutdown_kernels_for_owner), reaped
after code_execution.kernel_idle_timeout seconds idle (default 1800,
swept on every entry), capped process-wide at
code_execution.max_session_kernels live children (default 4, LRU
evicted), and still torn down by reset/death/atexit as before. The
ownership + disposal + idle-reap + cap shape deliberately carries
forward the lifecycle invariants of the earlier session-persistent
implementation in #88637 by @z80dev.
2. Per-cell RPC authority. The serving thread no longer freezes the
spawning cell's context/callbacks for the kernel's life. Each cell
installs a CellAuthority — captured on the calling thread exactly as
propagate_context_to_thread would for a per-call RPC thread — before its
request is written, and retires it on every settle path; _rpc_server_loop
gains a dispatch hook the kernel uses to route each tool call through
the CURRENT cell's context, callbacks, and task id. A call arriving with
no active cell is refused. Interpreter state persists; RPC authority
does not.
Composition with the per-script static guard (see the config note): a
persistent namespace lets cell N+1 invoke objects cell N created, which
a single-cell static scan cannot see — the runtime RPC boundary
(allow-list by name, per-cell budget, per-cell authority) is the
operative cross-cell enforcement in this mode, and the adversarial
alias test pins exactly that.
Tests (9 new): state survives across turns of one conversation;
sessions isolate; clear_session disposes the owner's kernels (and the
next turn starts fresh); the live-kernel cap LRU-evicts with evicted
children proven dead; idle kernels are reaped; a later cell's RPC runs
under that cell's approval callback; a cross-cell alias dispatches under
the CURRENT cell's authority; a settled cell's authority refuses
dispatch; each cell installs a fresh authority. 22/22 kernel tests, 81
code-execution tests, ruff clean. The 7 test-order failures in the
tools/-k-approval selection reproduce identically on the clean branch
base (pre-existing pollution, not this change).
* fix(code-kernel): delegated children get their own kernels — child contexts inherit the parent approval key, so qualify the owner with the delegation session id (live-verified leak, both directions)
---------
Co-authored-by: Teknium <127238744+teknium1@users.noreply.github.com>
2026-08-28 04:26:31 +09:00
2026-09-02 23:00:08 -07:00
# ---- Main entry point ----
feat(tools): session-persistent kernels for execute_code (kernel_mode: session) (#94647)
* feat(tools): session-persistent kernels for execute_code (kernel_mode: session)
execute_code spawns a fresh Python process per call, so every multi-step
data task re-loads its inputs: a CSV parsed in call one is gone by call
two, and scripts route state through temp files to survive. Hermes
already rewards programmatic tool calling (execute_code-only turns
refund the iteration budget), which makes the missing half — state that
survives between calls — the bottleneck.
Add opt-in `code_execution.kernel_mode: session`: one persistent kernel
per (task, mode, interpreter, cwd, tool-set). Variables, imports, and
loaded data persist across calls; `reset=true` discards state on demand.
The default `per-call` keeps today's behavior byte-for-byte.
Safety posture is unchanged by design: the child env comes from the same
builder as the per-call path (extracted, not duplicated, so the secret
scrubbing / PYTHONPATH hygiene cannot drift), the RPC server is the same
`_rpc_server_loop` with the same token and a per-cell tool budget, and
output passes the same ANSI strip + secret redaction. A timed-out or
interrupted cell kills the whole kernel tree and the next call respawns
— a wedged kernel can never hang the agent. The kernel env is frozen at
spawn; the schema and config comment say so.
Wire protocol: NDJSON requests on the kernel's stdin; responses framed
on stdout behind a per-kernel random sentinel, with unframed bytes
(fd-level output from user-spawned subprocesses) attributed to the
serialized current cell. The generated RPC client reconnects once when
HERMES_RPC_PERSISTENT=1, because a kernel legitimately outlives the RPC
server's 300s idle window between cells.
Tested on macOS 15 (Apple Silicon), Python 3.11: 13 new tests in
tests/tools/test_code_kernel.py (persistence, reset, error-keeps-kernel,
timeout-kills-kernel, sys.exit ends kernel, subprocess fd passthrough,
schema surface, mode fallback) plus the existing
test_code_execution.py / test_code_execution_modes.py suites (81 passed).
* fix(tools): session kernels get a stable owner, bounded lifetime, and per-cell RPC authority
Addresses the blocking review on the session-kernel design: two
authority/lifecycle boundaries were wrong.
1. Ownership and bounded lifetime. The kernel key's first component is
now the conversation's approval session key (_resolve_owner), not the
per-turn task id run_agent mints per top-level invocation — so state
genuinely survives across user turns of one conversation, and delegated
subagent sessions isolate naturally under their own keys (the task id
remains only the last-resort owner for embeds/tests with no session
context). Lifetime is bounded on four edges: kernels are disposed at the
same session boundary that clears the owner's approval/yolo state
(tools.approval.clear_session -> shutdown_kernels_for_owner), reaped
after code_execution.kernel_idle_timeout seconds idle (default 1800,
swept on every entry), capped process-wide at
code_execution.max_session_kernels live children (default 4, LRU
evicted), and still torn down by reset/death/atexit as before. The
ownership + disposal + idle-reap + cap shape deliberately carries
forward the lifecycle invariants of the earlier session-persistent
implementation in #88637 by @z80dev.
2. Per-cell RPC authority. The serving thread no longer freezes the
spawning cell's context/callbacks for the kernel's life. Each cell
installs a CellAuthority — captured on the calling thread exactly as
propagate_context_to_thread would for a per-call RPC thread — before its
request is written, and retires it on every settle path; _rpc_server_loop
gains a dispatch hook the kernel uses to route each tool call through
the CURRENT cell's context, callbacks, and task id. A call arriving with
no active cell is refused. Interpreter state persists; RPC authority
does not.
Composition with the per-script static guard (see the config note): a
persistent namespace lets cell N+1 invoke objects cell N created, which
a single-cell static scan cannot see — the runtime RPC boundary
(allow-list by name, per-cell budget, per-cell authority) is the
operative cross-cell enforcement in this mode, and the adversarial
alias test pins exactly that.
Tests (9 new): state survives across turns of one conversation;
sessions isolate; clear_session disposes the owner's kernels (and the
next turn starts fresh); the live-kernel cap LRU-evicts with evicted
children proven dead; idle kernels are reaped; a later cell's RPC runs
under that cell's approval callback; a cross-cell alias dispatches under
the CURRENT cell's authority; a settled cell's authority refuses
dispatch; each cell installs a fresh authority. 22/22 kernel tests, 81
code-execution tests, ruff clean. The 7 test-order failures in the
tools/-k-approval selection reproduce identically on the clean branch
base (pre-existing pollution, not this change).
* fix(code-kernel): delegated children get their own kernels — child contexts inherit the parent approval key, so qualify the owner with the delegation session id (live-verified leak, both directions)
---------
Co-authored-by: Teknium <127238744+teknium1@users.noreply.github.com>
2026-08-28 04:26:31 +09:00
2026-02-19 23:23:43 -08:00
def execute_code (
code : str ,
task_id : Optional [ str ] = None ,
enabled_tools : Optional [ List [ str ] ] = None ,
feat(tools): session-persistent kernels for execute_code (kernel_mode: session) (#94647)
* feat(tools): session-persistent kernels for execute_code (kernel_mode: session)
execute_code spawns a fresh Python process per call, so every multi-step
data task re-loads its inputs: a CSV parsed in call one is gone by call
two, and scripts route state through temp files to survive. Hermes
already rewards programmatic tool calling (execute_code-only turns
refund the iteration budget), which makes the missing half — state that
survives between calls — the bottleneck.
Add opt-in `code_execution.kernel_mode: session`: one persistent kernel
per (task, mode, interpreter, cwd, tool-set). Variables, imports, and
loaded data persist across calls; `reset=true` discards state on demand.
The default `per-call` keeps today's behavior byte-for-byte.
Safety posture is unchanged by design: the child env comes from the same
builder as the per-call path (extracted, not duplicated, so the secret
scrubbing / PYTHONPATH hygiene cannot drift), the RPC server is the same
`_rpc_server_loop` with the same token and a per-cell tool budget, and
output passes the same ANSI strip + secret redaction. A timed-out or
interrupted cell kills the whole kernel tree and the next call respawns
— a wedged kernel can never hang the agent. The kernel env is frozen at
spawn; the schema and config comment say so.
Wire protocol: NDJSON requests on the kernel's stdin; responses framed
on stdout behind a per-kernel random sentinel, with unframed bytes
(fd-level output from user-spawned subprocesses) attributed to the
serialized current cell. The generated RPC client reconnects once when
HERMES_RPC_PERSISTENT=1, because a kernel legitimately outlives the RPC
server's 300s idle window between cells.
Tested on macOS 15 (Apple Silicon), Python 3.11: 13 new tests in
tests/tools/test_code_kernel.py (persistence, reset, error-keeps-kernel,
timeout-kills-kernel, sys.exit ends kernel, subprocess fd passthrough,
schema surface, mode fallback) plus the existing
test_code_execution.py / test_code_execution_modes.py suites (81 passed).
* fix(tools): session kernels get a stable owner, bounded lifetime, and per-cell RPC authority
Addresses the blocking review on the session-kernel design: two
authority/lifecycle boundaries were wrong.
1. Ownership and bounded lifetime. The kernel key's first component is
now the conversation's approval session key (_resolve_owner), not the
per-turn task id run_agent mints per top-level invocation — so state
genuinely survives across user turns of one conversation, and delegated
subagent sessions isolate naturally under their own keys (the task id
remains only the last-resort owner for embeds/tests with no session
context). Lifetime is bounded on four edges: kernels are disposed at the
same session boundary that clears the owner's approval/yolo state
(tools.approval.clear_session -> shutdown_kernels_for_owner), reaped
after code_execution.kernel_idle_timeout seconds idle (default 1800,
swept on every entry), capped process-wide at
code_execution.max_session_kernels live children (default 4, LRU
evicted), and still torn down by reset/death/atexit as before. The
ownership + disposal + idle-reap + cap shape deliberately carries
forward the lifecycle invariants of the earlier session-persistent
implementation in #88637 by @z80dev.
2. Per-cell RPC authority. The serving thread no longer freezes the
spawning cell's context/callbacks for the kernel's life. Each cell
installs a CellAuthority — captured on the calling thread exactly as
propagate_context_to_thread would for a per-call RPC thread — before its
request is written, and retires it on every settle path; _rpc_server_loop
gains a dispatch hook the kernel uses to route each tool call through
the CURRENT cell's context, callbacks, and task id. A call arriving with
no active cell is refused. Interpreter state persists; RPC authority
does not.
Composition with the per-script static guard (see the config note): a
persistent namespace lets cell N+1 invoke objects cell N created, which
a single-cell static scan cannot see — the runtime RPC boundary
(allow-list by name, per-cell budget, per-cell authority) is the
operative cross-cell enforcement in this mode, and the adversarial
alias test pins exactly that.
Tests (9 new): state survives across turns of one conversation;
sessions isolate; clear_session disposes the owner's kernels (and the
next turn starts fresh); the live-kernel cap LRU-evicts with evicted
children proven dead; idle kernels are reaped; a later cell's RPC runs
under that cell's approval callback; a cross-cell alias dispatches under
the CURRENT cell's authority; a settled cell's authority refuses
dispatch; each cell installs a fresh authority. 22/22 kernel tests, 81
code-execution tests, ruff clean. The 7 test-order failures in the
tools/-k-approval selection reproduce identically on the clean branch
base (pre-existing pollution, not this change).
* fix(code-kernel): delegated children get their own kernels — child contexts inherit the parent approval key, so qualify the owner with the delegation session id (live-verified leak, both directions)
---------
Co-authored-by: Teknium <127238744+teknium1@users.noreply.github.com>
2026-08-28 04:26:31 +09:00
reset : bool = False ,
2026-02-19 23:23:43 -08:00
) - > str :
2026-09-02 22:33:03 -07:00
""" Run Python in the session ' s persistent kernel (local) or on the remote terminal backend,
2026-09-02 23:00:08 -07:00
with RPC access to a subset of Hermes tools ; returns the JSON result string . " Sandbox " means
the security envelope ( env scrubbing , tool whitelist + call budget , output redaction ) , not an
isolation jail : default ` project ` mode runs in the session ' s cwd with the project venv.
` ` enabled_tools ` ` ∩ SANDBOX_ALLOWED_TOOLS ; ` ` reset ` ` kills the existing kernel first . """
2026-02-19 23:23:43 -08:00
if not SANDBOX_AVAILABLE :
2026-09-02 22:45:21 -07:00
return tool_error ( " execute_code sandbox is unavailable in this environment. "
" Use normal tool calls (terminal, read_file, write_file, ...) instead. " )
2026-09-02 22:33:03 -07:00
# Fail closed under a terminal-policy refusal scope: the routed profile's terminal
# policy is unresolved, so refuse rather than inherit the launch process's ambient policy.
fix(terminal): scope terminal config per turn under profile multiplexing
A multiplexed Hermes process (gateway.multiplex_profiles, unified
dashboard/TUI, or cron) serves several profiles at once, but terminal.*
resolved through process-global TERMINAL_* env vars bridged ONCE at
startup from the launch profile (gateway/run.py ~2700-2760) plus the
one-shot _ensure_terminal_env_bridged() guard. Every routed profile
therefore inherited the launch profile's backend, cwd, docker volumes,
SSH target and shared-container key: a local profile ran inside another
profile's docker sandbox (or a docker profile escaped to the host), and a
container labeled profile A carried profile B's RW bind mounts.
Fix: an authoritative per-profile terminal policy seam, mirroring
agent/secret_scope.py:
- tools/terminal_scope.py: ContextVar holding the routed profile's
COMPLETE effective TERMINAL_* policy (defined defaults <- profile .env
TERMINAL_* <- config.yaml terminal:). While bound, terminal_env()
resolves ONLY from it - an omitted key yields the defined default,
never os.environ. Unreadable/malformed policy installs a refusal
scope; terminal_tool / execute_code refuse instead of running under
ambient launch-process policy (fail closed).
- Installed at every in-process profile boundary: gateway
_profile_runtime_scope, tui_gateway session/build/turn scopes, cron
per-job fire. The unscoped single-process path is byte-identical.
- Every terminal.* consumer reads through the scope: terminal_tool
(_get_env_config, _resolve_container_task_id shared key, orphan
reaper lifetime, degraded mode), gateway/platforms/base.py docker
media translation (volumes, shared key, persistence), runtime_cwd /
agent_init / skill_utils / code_execution_tool / file_tools cwd
anchors, prompt_builder / browser_tool / env_probe backend checks,
gateway footer, @-refs and slash-command cwd. env_probe resolves the
backend in the caller's context, since the probe worker thread does
not inherit the ContextVar.
Salvage of #99225 onto current main: adds the three ambient reads the PR
missed (tools/file_tools.py TERMINAL_CWD, tools/browser_tool.py and
tools/env_probe.py TERMINAL_ENV; shape from #79117) and trims the test
module to the leak matrix driven through the real gateway boundary,
omitted-key defaults, refusal, and boundary reset.
Fixes #68559
Fixes #94200
Fixes #101132
Fixes #95470
Co-authored-by: x7peeps <9640837+x7peeps@users.noreply.github.com>
Co-authored-by: Eva <239388517+100yenadmin@users.noreply.github.com>
Co-authored-by: ExitMaster <292490062+ExitMaster@users.noreply.github.com>
2026-08-31 10:53:22 +07:00
try :
2026-09-03 09:44:26 -07:00
# See #68559.
fix(terminal): scope terminal config per turn under profile multiplexing
A multiplexed Hermes process (gateway.multiplex_profiles, unified
dashboard/TUI, or cron) serves several profiles at once, but terminal.*
resolved through process-global TERMINAL_* env vars bridged ONCE at
startup from the launch profile (gateway/run.py ~2700-2760) plus the
one-shot _ensure_terminal_env_bridged() guard. Every routed profile
therefore inherited the launch profile's backend, cwd, docker volumes,
SSH target and shared-container key: a local profile ran inside another
profile's docker sandbox (or a docker profile escaped to the host), and a
container labeled profile A carried profile B's RW bind mounts.
Fix: an authoritative per-profile terminal policy seam, mirroring
agent/secret_scope.py:
- tools/terminal_scope.py: ContextVar holding the routed profile's
COMPLETE effective TERMINAL_* policy (defined defaults <- profile .env
TERMINAL_* <- config.yaml terminal:). While bound, terminal_env()
resolves ONLY from it - an omitted key yields the defined default,
never os.environ. Unreadable/malformed policy installs a refusal
scope; terminal_tool / execute_code refuse instead of running under
ambient launch-process policy (fail closed).
- Installed at every in-process profile boundary: gateway
_profile_runtime_scope, tui_gateway session/build/turn scopes, cron
per-job fire. The unscoped single-process path is byte-identical.
- Every terminal.* consumer reads through the scope: terminal_tool
(_get_env_config, _resolve_container_task_id shared key, orphan
reaper lifetime, degraded mode), gateway/platforms/base.py docker
media translation (volumes, shared key, persistence), runtime_cwd /
agent_init / skill_utils / code_execution_tool / file_tools cwd
anchors, prompt_builder / browser_tool / env_probe backend checks,
gateway footer, @-refs and slash-command cwd. env_probe resolves the
backend in the caller's context, since the probe worker thread does
not inherit the ContextVar.
Salvage of #99225 onto current main: adds the three ambient reads the PR
missed (tools/file_tools.py TERMINAL_CWD, tools/browser_tool.py and
tools/env_probe.py TERMINAL_ENV; shape from #79117) and trims the test
module to the leak matrix driven through the real gateway boundary,
omitted-key defaults, refusal, and boundary reset.
Fixes #68559
Fixes #94200
Fixes #101132
Fixes #95470
Co-authored-by: x7peeps <9640837+x7peeps@users.noreply.github.com>
Co-authored-by: Eva <239388517+100yenadmin@users.noreply.github.com>
Co-authored-by: ExitMaster <292490062+ExitMaster@users.noreply.github.com>
2026-08-31 10:53:22 +07:00
from tools . terminal_scope import enforce_no_refusal
enforce_no_refusal ( )
except Exception as refusal :
2026-09-02 22:45:21 -07:00
return tool_error ( f " execute_code refused: { refusal } "
" (profile terminal policy unresolved; fix the profile ' s config.yaml / .env and retry) " )
2026-02-19 23:23:43 -08:00
if not code or not code . strip ( ) :
2026-09-02 22:45:21 -07:00
return tool_error ( " No code provided. execute_code requires a non-empty ' code ' "
" parameter containing Python source. To run shell commands, use terminal(command=...) instead. " )
2026-09-02 22:33:03 -07:00
# Hard-block gateway-lifecycle commands (mirrors the terminal_tool guard — otherwise
# `os.system("launchctl bootout ...")` here bypasses it and SIGTERMs the gateway mid-task).
# Gated on PID-file ownership, not the inherited env marker.
2026-09-03 09:44:26 -07:00
# Hard-block gateway-lifecycle commands, mirroring the terminal_tool guard (#68289): without this,
# execute_code is a straight bypass — the terminal() path refuses `launchctl bootout ai.hermes.gateway`,
# but the identical command inside `os.system(...)` / `subprocess.run([...])` here sailed through and
# SIGTERM'd the gateway mid-task.
2026-08-23 16:55:50 -07:00
from tools . process_registry import _is_supervised_gateway_process
if _is_supervised_gateway_process ( ) :
from cron . lifecycle_guard import contains_gateway_lifecycle_command
if contains_gateway_lifecycle_command ( code ) :
return tool_error (
" Blocked: cannot restart or stop the gateway from inside the "
" gateway process. The gateway would kill this script before "
" it could complete (SIGTERM propagates to child processes). "
" Run the lifecycle command from a shell outside the gateway. "
)
2026-06-28 18:35:41 -07:00
from tools . terminal_tool import _get_env_config , _docker_has_host_access
_env_config = _get_env_config ( )
env_type = _env_config [ " env_type " ]
2026-09-02 22:33:03 -07:00
# Arbitrary Python never passes through terminal()/DANGEROUS_PATTERNS, so guard the whole
# script before either dispatch path spawns it — in this (tool-executor) thread, which holds
# the session context. A Docker sandbox with host bind mounts gets no container fast-path.
2026-09-03 09:44:26 -07:00
# See #30882.
2026-05-28 17:47:09 -04:00
from tools . approval import check_execute_code_guard
2026-09-02 22:10:19 -07:00
_guard = check_execute_code_guard ( code , env_type , has_host_access = _docker_has_host_access ( _env_config ) )
2026-05-28 17:47:09 -04:00
if not _guard . get ( " approved " , False ) :
2026-09-02 12:11:59 -07:00
return _error_result ( _guard . get ( " message " ) or " execute_code blocked by approval guard. " )
2026-09-02 22:33:03 -07:00
# Clear a stale interrupt bit that landed during the blocking approval-wait so it can't
# kill the just-approved run on the first poll. A genuine post-clear interrupt re-sets it.
2026-06-19 14:41:58 +02:00
if _guard . get ( " user_approved " ) :
from tools . interrupt import clear_current_thread_interrupt
clear_current_thread_interrupt ( )
2026-04-04 12:57:49 -07:00
if env_type != " local " :
2026-08-28 01:39:33 -07:00
return _execute_remote ( code , task_id , enabled_tools , reset = bool ( reset ) )
2026-04-11 14:02:58 -07:00
from tools . interrupt import is_interrupted as _is_interrupted
2026-09-02 22:33:03 -07:00
# Session kernels are always on locally (one interpreter per conversation); the guards above
# already ran for this cell, and the kernel path shares env builder, RPC server and redaction.
2026-09-02 12:11:59 -07:00
from tools . code_kernel import execute_in_session_kernel
2026-02-19 23:23:43 -08:00
_cfg = _load_config ( )
2026-09-02 12:11:59 -07:00
_mode = _get_execution_mode ( )
return execute_in_session_kernel (
2026-09-02 22:33:03 -07:00
code , task_id = task_id or " " , mode = _mode , child_python = _resolve_child_python ( _mode ) ,
2026-09-02 12:11:59 -07:00
child_cwd = _resolve_child_cwd ( _mode , " " , task_id = task_id or " " ) ,
2026-09-02 22:10:19 -07:00
sandbox_tools = frozenset ( _sandbox_tools_for ( enabled_tools ) ) ,
timeout = _cfg . get ( " timeout " , DEFAULT_TIMEOUT ) ,
max_tool_calls = _cfg . get ( " max_tool_calls " , DEFAULT_MAX_TOOL_CALLS ) ,
2026-09-02 22:33:03 -07:00
reset = bool ( reset ) , is_interrupted = _is_interrupted ,
fix(pm): integrate audited runtime and lifecycle repairs
Prepare dependency generations before selecting them. Keep shipped tool
bytes separate from writable additions, and store facts beside their entries.
Validate proposed plugin sets before config publication. Restore the previous
config if the facts write fails.
Consolidate duplicate updater, backup, setup, and voice helpers. Repair
launcher selection, dependency consumers, download ownership, update feeds,
and native Windows process and file handling.
Verification: 206 changed/prior-failing Python files reported 4630 passed,
one failed, and 330 skipped. Fix the remaining Hindsight fixture boundary.
The final targeted rerun reported 234 passed and two skipped. The store
review regression batch reported 83 passed and one skipped. Desktop
TypeScript checks, 56 selected Electron tests, 24 release tests, and the
removed-import/compatibility guards passed.
This is an integration checkpoint, not full audit acceptance. The complete
Python suite has not run on this fixed tree. Crash-atomic plugin publication,
generation cleanup, receipt correlation, and packaged lifecycle acceptance
remain open in docs/pm-audit-status.md.
2026-09-05 22:36:48 -04:00
)
def _kill_process_group ( proc , escalate : bool = False ) :
""" Kill the child and its whole process tree via agent.deadline.kill_process_tree: SIGTERM
( killpg + psutil descendant sweep ; ` ` taskkill / T / F ` ` on Windows , where sig is ignored ) ; with
` ` escalate = True ` ` wait 5 s then SIGKILL survivors . Never raises — falls back to ` ` proc . kill ( ) ` ` . """
import signal as _signal
def _tree_signal ( sig ) - > None :
try :
from agent . deadline import kill_process_tree
kill_process_tree ( proc . pid , sig = sig )
except Exception as e :
logger . debug ( " Could not terminate process tree: %s " , e , exc_info = True )
try :
proc . kill ( )
except Exception as e2 :
logger . debug ( " Could not kill process: %s " , e2 , exc_info = True )
_tree_signal ( getattr ( _signal , " SIGTERM " , None ) )
if escalate :
try :
proc . wait ( timeout = 5 )
except subprocess . TimeoutExpired :
_tree_signal ( getattr ( _signal , " SIGKILL " , None ) )
def _load_config ( ) - > dict :
""" ``code_execution`` config section via the lightweight raw reader — runs while the
module - level schema is built at tool discovery , so it must not import ` ` cli ` ` . """
try :
from hermes_cli . config import read_raw_config
cfg = read_raw_config ( ) . get ( " code_execution " , { } )
return cfg if isinstance ( cfg , dict ) else { }
except Exception :
return { }
# ---- Execution mode resolution (strict vs project) ----
# Canonical code_execution.mode values (referenced by tests and the config layer). Session
# kernels are the only local execution model; a leftover kernel_mode config key is ignored.
EXECUTION_MODES = ( " project " , " strict " )
DEFAULT_EXECUTION_MODE = " project "
def _get_execution_mode ( ) - > str :
""" ``code_execution.mode`` (invalid → default with a warning). ``project``: session cwd + active
venv python ; ` ` strict ` ` : isolated temp dir + ` ` sys . executable ` ` . Scrubbing / whitelist apply to both . """
cfg_value = str ( _load_config ( ) . get ( " mode " , DEFAULT_EXECUTION_MODE ) ) . strip ( ) . lower ( )
if cfg_value in EXECUTION_MODES :
return cfg_value
logger . warning (
" Ignoring code_execution.mode= %r (expected one of %s ), falling back to %r " ,
cfg_value , EXECUTION_MODES , DEFAULT_EXECUTION_MODE ,
)
return DEFAULT_EXECUTION_MODE
# ---- OpenAI Function-Calling Schema ----
# Per-tool documentation lines for the execute_code description, in canonical display order.
_TOOL_DOC_LINES = [
( " web_search " , " web_search(query: str, limit: int = 5) -> dict \n "
" Returns { \" data \" : { \" web \" : [ { \" url \" , \" title \" , \" description \" }, ...]}} " ) ,
( " web_extract " , " web_extract(urls: list[str], char_limit: int = None) -> dict \n "
" Returns { \" results \" : [ { \" url \" , \" title \" , \" content \" , \" error \" }, ...]} where content is markdown. \n "
" No LLM summarization. Pages over char_limit (default 15000) are head+tail truncated; full text stored on disk (path in the content footer). " ) ,
( " read_file " , " read_file(path: str, offset: int = 1, limit: int = 2000) -> dict \n "
" Lines are 1-indexed. Returns { \" content \" : \" ... \" , \" total_lines \" : N} " ) ,
( " write_file " , " write_file(path: str, content: str) -> dict \n Always overwrites the entire file. " ) ,
( " search_files " , " search_files(pattern: str, target= \" content \" , path= \" . \" , file_glob=None, limit=50, order= \" discovery \" ) -> dict \n "
" target: \" content \" (search inside files) or \" files \" (find files by name). Returns { \" matches \" : [...]} " ) ,
( " patch " , " patch(path: str, old_string: str, new_string: str, replace_all: bool = False) -> dict \n "
" Replaces old_string with new_string in the file. " ) ,
( " terminal " , " terminal(command: str, timeout=None, workdir=None) -> dict \n "
" Foreground only (no background/pty). Returns { \" output \" : \" ... \" , \" exit_code \" : N} " ) ,
]
def build_execute_code_schema ( enabled_sandbox_tools : set = None ,
mode : str = None ) - > dict :
""" execute_code schema listing only *enabled_sandbox_tools* — a disabled tool (e.g. web off)
must not appear or the model keeps trying it . ` ` mode ` ` ( None → config ) picks the cwd sentence . """
if enabled_sandbox_tools is None :
enabled_sandbox_tools = SANDBOX_ALLOWED_TOOLS
if mode is None :
mode = _get_execution_mode ( )
tool_lines = " \n " . join ( doc for name , doc in _TOOL_DOC_LINES if name in enabled_sandbox_tools )
import_examples = [ n for n in ( " web_search " , " terminal " ) if n in enabled_sandbox_tools ]
import_examples = import_examples or sorted ( enabled_sandbox_tools ) [ : 2 ]
import_str = " , " . join ( import_examples ) + " , ... " if import_examples else " ... "
if mode == " strict " :
cwd_note = (
" Scripts run in their own temp dir, not the session ' s CWD — pass "
" absolute paths for any file that lives outside the session ' s "
" working directory, or use terminal()/read_file() to reach it. "
)
else :
cwd_note = (
" Scripts run in the session ' s working directory. Interpreter: "
" the project ' s activated venv/conda python when one is active "
" (VIRTUAL_ENV/CONDA_PREFIX — matches terminal()); otherwise "
" Hermes ' s own python (the common case — stdlib plus Hermes ' s "
" deps; check `import x` before relying on project packages). "
)
# Remote hosts that fail open to per-call are not worth schema words; the result's
# `kernel` field tells the truth per call.
# Session kernels are always on (kernel_mode retired in #96787): persistence is part of the tool's one
# description, not a bolt-on paragraph behind a dead conditional.
description = (
" Run Python that calls Hermes tools programmatically. Use when you "
" need 3+ tool calls with logic between them: filtering/reducing "
" large outputs before they enter context, branching, or loops "
" (N pages/files, retry on failure). Use normal tool calls for "
" single calls, results you must reason over in full, or anything needing user interaction. \n \n "
" Calls run in a persistent session kernel: variables, imports, and "
" loaded data survive across execute_code calls, so build on earlier "
" work instead of re-loading it. A timed-out or interrupted call loses that state. \n \n "
f " Available via `from hermes_tools import ...`: \n \n "
f " { tool_lines } \n \n "
" Limits: 5-minute timeout, max 50 tool calls per call. Stdout over "
" 50KB shows head/tail inline; the FULL text is auto-saved to a file whose path rides in the result. \n \n "
f " { cwd_note } \n \n "
2026-09-07 03:33:05 -07:00
" Helpers require imports: `from hermes_tools import json_parse, shell_quote, retry`. "
" json_parse(text) — tolerant "
fix(pm): integrate audited runtime and lifecycle repairs
Prepare dependency generations before selecting them. Keep shipped tool
bytes separate from writable additions, and store facts beside their entries.
Validate proposed plugin sets before config publication. Restore the previous
config if the facts write fails.
Consolidate duplicate updater, backup, setup, and voice helpers. Repair
launcher selection, dependency consumers, download ownership, update feeds,
and native Windows process and file handling.
Verification: 206 changed/prior-failing Python files reported 4630 passed,
one failed, and 330 skipped. Fix the remaining Hindsight fixture boundary.
The final targeted rerun reported 234 passed and two skipped. The store
review regression batch reported 83 passed and one skipped. Desktop
TypeScript checks, 56 selected Electron tests, 24 release tests, and the
removed-import/compatibility guards passed.
This is an integration checkpoint, not full audit acceptance. The complete
Python suite has not run on this fixed tree. Crash-atomic plugin publication,
generation cleanup, receipt correlation, and packaged lifecycle acceptance
remain open in docs/pm-audit-status.md.
2026-09-05 22:36:48 -04:00
" json.loads for terminal() output; shell_quote(s) — shlex.quote for "
" dynamic shell args; retry(fn, max_attempts=3, delay=2) — exponential backoff. "
)
return {
" name " : " execute_code " ,
" description " : description ,
" parameters " : {
" type " : " object " ,
" properties " : {
" code " : { " type " : " string " , " description " : (
" Python code to execute. Import tools with "
f " `from hermes_tools import { import_str } ` "
" and print your final result to stdout. " ) } ,
" reset " : { " type " : " boolean " , " description " : (
" Discard the kernel ' s persistent state and start fresh before running this code. " ) } ,
} ,
" required " : [ " code " ] ,
} ,
}
# Registration-time schema (all sandbox tools, configured mode); model_tools.py rebuilds per-session.
EXECUTE_CODE_SCHEMA = build_execute_code_schema ( )
def _execute_code_handler ( args : dict , * * kwargs ) - > str :
""" Redirect misdirected calls (terminal ' s ``command`` arg, non-string ``code``) with an
actionable error before dispatching to ` ` execute_code ` ` . """
if " code " not in args and " command " in args :
logger . warning ( " execute_code received ' command ' instead of the required ' code ' argument " )
return tool_error ( " execute_code received a ' command ' parameter, but it requires "
" Python source in ' code ' . Use terminal(command=...) for shell "
" commands; for Python, retry as execute_code(code=...). " )
code = args . get ( " code " , " " )
if code is not None and not isinstance ( code , str ) :
return tool_error ( f " execute_code received a { type ( code ) . __name__ } in ' code ' , but it "
" requires Python source as a string. Retry as execute_code(code= \" ... \" ). " )
return execute_code ( code = code or " " , task_id = kwargs . get ( " task_id " ) ,
enabled_tools = kwargs . get ( " enabled_tools " ) , reset = bool ( args . get ( " reset " , False ) ) )
registry . register (
name = " execute_code " , toolset = " code_execution " , schema = EXECUTE_CODE_SCHEMA ,
handler = _execute_code_handler , check_fn = check_sandbox_requirements , emoji = " 🐍 " ,
max_result_size_chars = 100_000 ,
)