sj,C
` d Z ddlZddlZddlZddlZddlZddlZddlZddlZddl m
Z
m Z m Z ej
e ZdZdZdZdZdZd Zd
Z ej d Zd Z ej Zd
a d Z efde de fdZ d.dZ de!fdZ"de#de#fdZ$de#de#dz fdZ%de#fdZ&de#de#fdZ'e
fde#d e de(e#e!f fd Z)de#de#fd Z*de#d e#de!fd Z+d!e#d"e!d#e d$e#de#f
d%Z, ej d&ej- Z.de#de#dz fd'Z/de dfde#d(e#de#d)e d*e e0z dz de#f d+Z1de fd,e2e3 d)e de2e3 fd-Z4dS )/u Tool result persistence -- preserves large outputs instead of truncating.
Defense against context-window overflow operates at three levels:
1. **Per-tool output cap** (inside each tool): Tools like search_files
pre-truncate their own output before returning. This is the first line
of defense and the only one the tool author controls.
2. **Per-result persistence** (maybe_persist_tool_result): After a tool
returns, if its output exceeds the tool's registered threshold
(registry.get_max_result_size), the full output is persisted and the
in-context content is replaced with a preview + file path reference.
The canonical home is ALWAYS host-side:
``$HERMES_HOME/cache/spillover/{tool_use_id}.txt`` — alongside the other
Hermes-owned caches (images, audio, documents, ...) instead of littering
the OS temp dir. This needs no sandbox environment, so it also works for
sessions that never ran a terminal command (MCP-only, cron, gateway) —
previously those hit the inline-truncate fallback because
``get_active_env()`` returned None until the first terminal call created
an environment.
What the model sees depends on the backend:
- **Local backend (or no active env):** the host path itself.
- **Remote backends (docker/ssh/modal/daytona):** ``cache/spillover`` is
in the auto-mounted/synced cache-dir list (tools/credential_files.py),
so the reference is the translated in-sandbox path (probed for
readability first). When the sandbox can't see it (e.g. a persistent
container created before spillover joined the mount list), fall back
to writing a copy into the sandbox temp dir via env.execute().
The spillover dir is pruned two ways: the gateway housekeeping loop
sweeps it hourly with the other media caches, and a once-per-process
best-effort prune runs on the first spill so CLI-only installs (which
never run gateway housekeeping) self-clean too.
3. **Per-turn aggregate budget** (enforce_turn_budget): After all tool
results in a single assistant turn are collected, if the total exceeds
MAX_TURN_BUDGET_CHARS (200K), the largest non-persisted results are
spilled to disk until the aggregate is under budget. This catches cases
where many medium-sized results combine to overflow context.
N)DEFAULT_PREVIEW_SIZE_CHARS BudgetConfigDEFAULT_BUDGETzzz/tmp/hermes-resultszcache/spillover HERMES_PERSIST_EOF__budget_enforcement__z[^A-Za-z0-9_.-]+x Fc 2 ddl m} | t z S )z H H H H H I I 8 8 8 137777777778s' ,,00+A' '
B1BBc Z | dS ddl m} t | | S # t $ r Y dS w xY w)u True when the spill file should be written by this process directly.
Covers ``env=None`` (no sandbox environment active — e.g. a session
that has not run a terminal command yet) and the local backend
(where env.execute() runs on this same host anyway). Remote backends
(docker/ssh/modal/daytona) return False: their read_file resolves
inside the sandbox, so the spill must be written there.
NTr )LocalEnvironmentF)tools.environments.localr,
isinstancer( )envr, s r _is_host_side_envr0 ~ sX {t======# /000 uus
**contentfilenamec , t }| dd ||z }| | dd n4# t $ r'}t d|| Y d}~dS d}~ww xY wt
t | S )zWrite content host-side to $HERMES_HOME/cache/spillover.
Returns the absolute path string on success, None on failure.
T)parentsexist_okutf-8replace)encodingerrorsz!Spillover write failed for %s: %sN)r mkdir
write_textr r& warningr* str)r1 r2 spill_dirpathr) s r _write_to_spilloverr@ s
%'' t4448# ')DDDD :HcJJJttttt t99s AA
A6 A11A6 host_pathc D ddl m} || }n3# t $ r&}t d| Y d}~dS d}~ww xY wt |dd }|J | d n2# t $ r%}t d| Y d}~nd}~ww xY w | d t j | d
}|
d d
dk r|S n2# t $ r%}t d| Y d}~nd}~ww xY wdS )u5 Return the path where a remote backend can read *host_path*, or None.
``cache/spillover`` is one of the auto-mounted/synced cache dirs
(tools/credential_files.py), so on docker it is bind-mounted and on
modal/ssh/daytona it is file-synced into the sandbox. Translate the
host path with the same helper the image tools use, force a sync for
synced backends, then PROBE readability — a persistent docker
container created before spillover joined the mount list won't have
the bind mount, and must fall back to the in-sandbox write.
r )to_agent_visible_cache_pathz%Spillover path translation failed: %sN
_sync_managerT)forcezSpillover sync failed: %sztest -r )timeout
returncoder z&Spillover readability probe failed: %s) tools.credential_filesrC r( r& r' getattrsyncexecuteshlexquoteget)rA r/ rC visibler) sync_managerresults r _sandbox_visible_spillover_pathrS s FFFFFF--i88 G(<(< > >KK ::lA & &! + +N , D D D =sCCCCCCCCD 4sC
A?AA2 2
B!<B B!%AC. .
D 8DD c | |t | dd }t | r\ | }|r | d pd}| dS n2# t $ r%}t d| Y d}~nd}~ww xY wt S )z=Return the best temp-backed storage dir for this environment.N get_temp_dir/z/hermes-resultsz"Could not resolve env temp dir: %s)rJ callablerstripr( r& r' STORAGE_DIR)r/ rU temp_dirr) s r _resolve_storage_dirr[ s
sND99 L ! ! 8
8'<>> 8 's 3 3 :sH &77778
H
H
H A3GGGGGGGG
H s
A
A<A77A< tool_use_idc t | pd }t d| d }||k }|sd}d}|st | t
k rlt
j | d dd }|dt
d pd}| d| }| dS ) z3Return a single safe filename for a tool result id. tool_result_z._-Tr6 N z.txt) r= _UNSAFE_RESULT_FILENAME_CHARSsubstriplen_MAX_RESULT_FILENAME_STEMhashlibsha256encode hexdigestrX )r\ raw_id safe_stemchangeddigests r _safe_result_filenamern s
-
.
.F-11#v>>DDUKKI6!G ! ,#i..#<<<
g 6 677AACCCRCH 8 8 89@@GGX= ++6++ r max_charsc t | |k r| dfS | d| }| d }||dz k r
|d|dz }|dfS )zGTruncate at last newline within max_chars. Returns (preview, has_more).FN
r T)rd rfind)r1 ro truncatedlast_nls r generate_previewrv sg
7||y ~
#Iood##Ga lw{l+ d?r c h t | vrt S dt j j dd S )z=Return a heredoc delimiter that doesn't collide with content.HERMES_PERSIST_N )HEREDOC_MARKERuuiduuid4hex)r1 s r _heredoc_markerr~ s3 W$$ 3TZ\\ -bqb 1 3 33r remote_pathc t j | }dt j | dt j | }| |d| }| dd dk S )u Write content into the sandbox via env.execute(). Returns True on success.
Pushes ``content`` through stdin rather than embedding it in the command
string. Linux's ``MAX_ARG_STRLEN`` caps any single argv element at 128 KB
(32 * PAGE_SIZE), so the previous heredoc-in-the-command-string approach
silently failed with ``OSError: [Errno 7] Argument list too long`` for any
tool result over ~128 KB — exactly the case persistence exists to handle.
Routing through stdin removes that ceiling on local + ssh (``_stdin_mode
== "pipe"``); remote backends with ``_stdin_mode == "heredoc"`` keep their
existing API-body sized limit, which is orders of magnitude larger than
the exec-arg ceiling.
z mkdir -p z
&& cat > )rG
stdin_datarH r r )osr? dirnamerM rN rL rO )r1 r r/ storage_dircmdrR s r _write_to_sandboxr sp '//+..K
Tek+..
T
T%+k:R:R
T
TC
[[bW[
=
=F ::lA & &! ++r previewhas_more
original_size file_pathc |dz }|dk r
|dz dd}n|dd}t d}|d|dd| d z
}|d
| dz
}|d z
}|d z
}|d
t | dz
}|| z
}|r|dz
}|dt z
}|S )z/Build the replacement block.i z.1fz MBz KBrq z This tool result was too large (,z
characters, z).
zFull output saved to: zYUse the read_file tool with offset and limit to access specific sections of this output.
u Recovery: page through the saved file with read_file (offset/limit) or process it with execute_code — do NOT re-request the same data from the remote API; the full result is already on disk.
zPreview (first z chars):
z
...)PERSISTED_OUTPUT_TAGrd PERSISTED_OUTPUT_CLOSING_TAG)r r r r size_kbsize_strmsgs r _build_persisted_messager s d"G$ n---- &&&&
!
%
%
%C Zm Z Z ZH Z Z ZZC 1I 1 1 11C ggC >C
5S\\ 5 5 55C7NC w ., . ..C Jr z ^Full output saved to: (.+)$c t | t r t | vrdS t | }|r'| d ndS )a' Return the file path from a replacement block.
Used by the result-reference stubbing guard (agent/tool_guardrails.py) so
a stub referencing a persisted first occurrence can carry the spillover
path instead of dangling. Returns None for non-persisted content.
Nr )r. r= r _PERSISTED_PATH_REsearchgrouprc )r1 matchs r extract_persisted_pathr - s_ gs # # ';7'J'Jt % %g . .E%* 45;;q>> ! ! !4r tool_nameconfig thresholdc @ ||n| | }|t d k r| S t | |k r| S t | }t | |j \ }} t
| | }
t | rN|
Jt d||t | |
t || t | |
S n||
]t |
| } | Kt d||t | | |
t || t | | S t | } | d| }
t | |
| rJt d||t | |
t || t | |
S n3# t $ r&}t d|| Y d}~nd}~ww xY wt d|t | | d t | d
d S ) a Layer 2: persist oversized result into the sandbox, return preview + path.
Writes via env.execute() so the file is accessible from any backend
(local, Docker, SSH, Modal, Daytona). Falls back to inline truncation
if write fails or no env is available.
Args:
content: Raw tool result string.
tool_name: Name of the tool (used for threshold lookup).
tool_use_id: Unique ID for this tool call (used as filename).
env: The active BaseEnvironment instance, or None.
config: BudgetConfig controlling thresholds and preview size.
threshold: Explicit override; takes precedence over config resolution.
Returns:
Original content if small, or replacement.
Ninf)ro z4Persisted large tool result: %s (%s, %d chars -> %s)z?Persisted large tool result: %s (%s, %d chars -> %s [host: %s])rV z Sandbox write failed for %s: %szDInline-truncating large tool result: %s (%d chars, no sandbox write)z
[Truncated: tool response was r z3 chars. Full output could not be saved to sandbox.])resolve_thresholdfloatrd rn rv preview_sizer@ r0 r& infor rS r[ r r( r< )r1 r r\ r/ r r effective_thresholdr2 r r rA rP r r r) s r maybe_persist_tool_resultr : sz 2 (1'<))&BZBZ[dBeBeeEll**
7||***$[11H(F||z }|t | z
}| | | d< t
d
|
| | S ) a" Layer 3: enforce aggregate budget across all tool results in a turn.
If total chars exceed budget, persist the largest non-persisted results
first (via sandbox write) until under budget. Already-persisted results
are skipped.
Mutates the list in-place and returns it.
r r1 c | d S )Nr )xs r z%enforce_turn_budget.. s
!A$ r T)keyreverse tool_call_idbudget_)r1 r r\ r/ r r z7Budget enforcement: persisted tool result %s (%d chars)) enumeraterO rd r append turn_budgetsortr _BUDGET_TOOL_NAMEr& r ) r r/ r
candidates
total_sizeir r1 sizeidxr\ replacements r enforce_turn_budgetr sx JJM** ) )3'')R((7||d
w . . q$i ( ( (V''' OOO555 T + + + EC i.ggnooo>> /'#
' ! ! $ J #k** *J,7M# y ) KKIT
r )r N)5__doc__rf loggingr rerM threadingr r{ tools.budget_configr r r getLogger__name__r& r r rY r SPILLOVER_MAX_AGE_HOURSrz r compilera re Lockr$ r% r intr" r* boolr0 r= r@ rS r[ rn tuplerv r~ r r MULTILINEr r r r r dictr r r r r s * *X
8 $ $+ 4 # $ %, *
+> ? ? & (( 0 0 0 2I 3 S 08 8 8 8(d & " s C$J F
s s $ 5O c c SXY\^bYbSc 4S 4S 4 4 4 4,s , ,d , , , ,&
< RZ ? NN
5C
5C$J
5
5
5
5"
)$(
R R
RR R
R U{T!
R R R R Rn
)3 3:3
3
$Z 3 3 3 3 3 3r