+ lHj_$aR8tB0tRt^RIt^RIt^RIt^RIt^RIt^RIt^RIt^RI t ^RI t ^RI t ^RI t ^RI HtHtHt]P"!]4tRtRt]P,P/] P0!4R4tRt^tRt]!0R9m4tRtR t ]PB!R 4t"^xt#] PH!4t%]&!4t']^kR t(R R lt)]PB!R4t*Rt+]PB!R4t,RRlt-RRlt.RRlt/R:RRllt0RRlt1RRlt2RRlt3RR lt4R!R"lt5R#R$lt6]3R%R&llt7R'R(lt8R)R*lt9R+R,lt:]PB!R-]Pv4tR2R3lt?R4R5lt@R]3R6R7lltAR#);uTool result persistence -- preserves large outputs instead of truncating. Layers against context overflow: (1) per-tool caps inside each tool; (2) ``maybe_persist_tool_result`` — output over the tool's threshold is persisted and replaced by a preview + path; canonical home is ALWAYS host-side ``$HERMES_HOME/cache/spillover/{id}.txt`` (works for sessions that never ran a terminal), remote backends get the translated in-sandbox path (probed for readability) else a copy in the sandbox temp dir; (3) ``enforce_turn_budget``.N)DEFAULT_PREVIEW_SIZE_CHARS BudgetConfigDEFAULT_BUDGETzzzhermes-resultszcache/spillover__budget_enforcement__zzz[^A-Za-z0-9_.-]+c2^RIHpV!4\, #)z/home/ubuntu/.hermes/hermes-agent/tools/tool_result_storage.pyget_spillover_dirr +s0  / //c$V^8dQhR\/#returnint)formats"r __annotate__r1s88C8r c6^RIHp\V!4PR4;'g/PR^Z44p\P !V4'g\ #\\ \T^,44# \d \ u#i;i)aJDefault spillover age = the session retention window (``sessions.retention_days``). Spill files are archives the durable transcript points at, not a cache: a session resumed days later must still find what the ```` pointer promises (#126351). Falls back to the legacy 24h cache age when the config is unreadable.)load_config_readonlysessionsretention_days) hermes_cli.configrfloatgetmathisfiniteSPILLOVER_MAX_AGE_HOURS Exceptionmaxr)rdayss r _spillover_retention_hoursr#1s ':*,00<BBGGHXZ\]^}}T""* *# &D2I 77 '&&'s'B2BBBBz#spillover(?:/|\\+)([A-Za-z0-9_.-]+)zH(instr(content, 'spillover') > 0 OR instr(api_content, 'spillover') > 0)z4(?:^|[/\\])(?:spillover|hermes-results)[/\\][^/\\]+$c0V^8dQhR\R\/#)rpathr)strdict)rs"r rrPs / / / /r ct\V\4'd\PV4'g/#RRRR/#)zExtra read_file not-found fields for a persisted-tool-result path: the archive was pruned, so the model gets "expired" instead of a generic miss it might take for a typo (#126351).expiredThintuThis was a persisted tool result archive and it has expired (pruned with its session or by the cache sweep); the full output is no longer recoverable. Inspect the current state before re-running the original tool — the call that produced it may already have taken effect.) isinstancer&_ARCHIVE_PATH_REsearch)r%s&r expired_archive_fieldsr.Ps= dC (8(?(?(E(E tV - //r c$V^8dQhR\/#rset)rs"r rr\ssr c\4pVFHp\V\4'gKRV9gK$VP\P V44KJ V#)zVSpillover archive basenames referenced by transcript message text (empty set on none). spillover)r1r+r&update_SPILLOVER_NAME_REfindall)textsnamestexts* r spillover_names_in_textr:\sFE dC [D%8 LL+33D9 : Lr c2V^8dQhR\R,/#rrNr0)rs"r rresS4Zr c&VPPR, pVP4'g \4#\P!VP 4 R2RRR7pVP R\ R24P4pVP4\T4R 8dR#\4pTFwrVT\YV4,pK T# TP4i;i \P\3dR#i;i) ueBasenames under *spill_dir* still referenced by any message in the home's ``state.db``. ``set()`` when no database exists (no sessions → nothing references anything), ``None`` when the reference set is UNKNOWN (unreadable / truncated query) so callers fail closed and keep the files; a plain read-only connection is enough, the write path owns the locks.zstate.dbz?mode=roTg@)uritimeoutz0SELECT content, api_content FROM messages WHERE z LIMIT 20001Ni N)parentexistsr1sqlite3connectas_uriexecuteSPILLOVER_SQL_FILTERfetchallcloseErrorOSErrorlenr:) spill_dirdb_pathconnrowsr8content api_contents& r referenced_spillover_namesrRes %% 2G >>  u  '.."2!38<$PST <<BCWBXXdehj  JJL 4y5E $ (>>!% L JJL MM7 #s)*C1*'CC1C..C11DDc>V^8dQhR\R,R\/#)r max_age_hoursNrr)rs"r rrs""3:""r czVf \4MTp\P!4VR,, p.p\\4P 44pTFNpTP 4'd5TP4PT8dTPT4KLKNKP T'g^#\\44p^pTF4pTeTPT9dKTP4T^, pK6 T# \ d^#i;i \ dKi;i \ dKli;i)uDelete spillover files older than *max_age_hours*; returns count removed (same contract as the ``cleanup_*_cache`` helpers the gateway housekeeping loop runs hourly). A ``None`` age means the session retention window, not a cache TTL — an explicit ``max_age_hours`` (tests, legacy callers) still wins. An expired file is deleted only when no message in the home's state.db references it: the transcript's ```` promise outlives the archive's mtime exactly as long as the owning session does (#126351) — referenced archives leave with their session, via the unlink SessionDB delete/prune performs, not with the age sweep.i) r#timelistr iterdirrJis_filestatst_mtimeappendrRnameunlink)rT age_hourscutoffr)entriesf referencedremoveds& r cleanup_spillover_cacheres1>0E*,=I YY[I, -FG(*2245 yy{{qvvx0069q! :{ +,=,?@JG   :!5   HHJ qLG  N)        s6!DAD(D+ DD D('D(+ D:9D:cV^8dQhRR/#r<)rs"r rrs88t8r c~^RIHpV!4p\;_uu_4V\9d RRR4R#\P V4RRR4\ 4;p'd\ PRV4R#R# +'giL=;i \d"p\ PRT4Rp?R#Rp?ii;i)zBest-effort prune, at most once per process PER PROFILE HOME (CLI-only installs never run housekeeping; a multiplexed gateway must sweep every profile's ``cache/spillover``, not just the first one that spilled).)hermes_home_keyNz#Pruned %d expired spillover file(s)zSpillover prune failed: %s) r ri_spillover_prune_lock_spillover_pruned_homesaddreloggerdebugr )rihome_keyrdexcs r _prune_spillover_oncerqs1 H   . .    ##H- 8-/ /7 / LL> H 0   8 13778s( A=A=(B= B  B<B77B<c$V^8dQhR\/#r)bool)rs"r rrs  d r cVVfR#^RIHp\W4# \dR#i;i)zTrue when this process should write the spill file directly: ``env=None`` (no sandbox yet) or the local backend. Remote backends resolve ``read_file`` inside the sandbox.T)LocalEnvironmentF)tools.environments.localrur+r )envrus& r _is_host_side_envrxs1 {=#00 s  ((c0V^8dQhR\R\/#)rrPfilenamer&)rs"r rrsr cVPRRR7p\4pVPRRR7W1, pVPV4\P !V4P pT\T48wd4\PRY\T44TP4R#\4\T4# \d"p\PRY4Rp?R#Rp?ii;i \dR#i;i) a6Write host-side to $HERMES_HOME/cache/spillover; returns path str or None. The write is size-verified before the caller tells the model "Full output saved": a partially-flushed file (quota, ENOSPC race) fails closed to the bounded inline truncation instead of referencing an archive that silently lost bytes. utf-8replaceerrorsT)parentsexist_okz!Spillover write failed for %s: %sNu]Spillover write for %s is not lossless (%d bytes on disk, expected %d) — discarding archive)encoder mkdir write_bytesosrZst_sizerJrmwarningrKr^rqr&)rPrzdatarLr%persisted_sizerps&& r _write_to_spilloverrs >>')> 4D%' t4# ..T" 2 c$i   KKM t9 :HJ   s*ACC2 C/C**C/2 DDc>V^8dQhR\R\R,/#)r host_pathrNr{)rs"r rrssC$Jr c ^RIHpV!V4p\ TRR4;peTP RR7TPR\P!T4 2^R 7PR ^4^8XdT#R# \d"p\P RT4Rp?R#Rp?ii;i \d!p\P RT4Rp?LRp?ii;i \d"p\P R T4Rp?R#Rp?ii;i) u(Path where a remote backend can read *host_path*, or None. Translates via the image tools' helper, forces a sync for synced backends, then PROBES readability — a persistent container created before spillover joined the mount list lacks the bind mount and must fall back to the in-sandbox write.)to_agent_visible_cache_pathz%Spillover path translation failed: %sN _sync_managerT)forcezSpillover sync failed: %sztest -r r? returncodez&Spillover readability probe failed: %s) tools.credential_filesrr rmrngetattrsyncrEshlexquoter)rrwrvisiblerp sync_managers&& r _sandbox_visible_spillover_pathrs F-i87#C$? ?L L   D  )D ;;%++g"6!78"; E I I,XY Z^_ _N `   DDUKI!G**]I#i.#<< g 67AACCH889@@GXX=  k6(+ [ r c^V^8dQhR\R\R\\\3,/#)rrP max_charsr)r&rtuplers)rs"r rrs3RRcRcRSXY\^bYbScRr c\V4V8:dVR3#VPR^V4pTRW!^,8d V^,R3#TR3#)zGTruncate at last newline within max_chars. Returns (preview, has_more).F NT)rKrfind)rPrlast_nls&& r generate_previewrsW 7|y ~mmD!Y/G J7!^#;GaK KT QQ KT QQr c0V^8dQhR\R\/#)rrPrr{)rs"r rrs&a&aC&aC&ar cB\P!V4p\ T\ 4'dT'd\ T4\8:gT#TPR4p\ T\4'd T'gT#TP4UUu/uFwr4TR8wgKY4bK pppT'gT#\P!TR^R\R7pT R\ RT R\ R2# \\3dTu#i;iuuppi \\3dTu#i;i)uRewrite an MCP handler result envelope into the text it wraps, else return *content*. ``tools/mcp_tool_handlers.py::_render_call_tool_result`` hands the model a JSON string (``{"result": , ...}``) so structured metadata survives inline delivery. Persisting that string verbatim put a multi-hundred-KB document on ONE line with escaped newlines, so the ``read_file`` offset/limit pagination the ```` block recommends could not be used at all (#90426). Recognized by SHAPE, not by tool name: the envelope is the only JSON object in the codebase whose keys are a subset of ``{"result", "structuredContent", "_meta"}`` with a non-empty string ``result``. That keeps opaque JSON from any other tool verbatim, and it also covers the aggregate path (``enforce_turn_budget`` persists under ``_BUDGET_TOOL_NAME``, so a ``mcp__``-prefix test would miss exactly the results it has to fix). Sibling members are appended after the text in a delimited metadata block instead of being dropped: they are the structured payloads ``_render_call_tool_result`` deliberately keeps for the model (#115430), and the spill file is the only copy left once the envelope is replaced by the preview. Anything unrecognized — unparseable JSON, a non-object, an unknown key, a missing/empty/non-string ``result`` (e.g. a structuredContent-only result, which has no pageable text) — is persisted verbatim, exactly as before. resultFT) ensure_asciiindent sort_keysdefaultz r)jsonloads TypeError ValueErrorr+r'r1_MCP_ENVELOPE_KEYSrr&itemsdumps_ENVELOPE_METADATA_TAG_ENVELOPE_METADATA_CLOSING_TAG)rPpayloadr9keyvalueextrasmetadatas& r _pageable_textrs,**W% gt $ $G3w\=]]_ `` z "O z " s/C) D D4D)C?>C?DDc<V^8dQhR\R\R\/#)rrP remote_pathr)r&rs)rs"r rrEs!&&s&&d&r c\PPV4p^RIHpV!V4 R\ P !V4 2pVPV^VR7PR^4^8wdR#\VPRRR74pVPR \ P !V4 2^R 7pTPR^4^8wdR #\TPRR4;'gR4P4P!4p T 'dT R,P#4'gR #\%T R,4p Y8XdR #\P'RYT4TPR\ P !T4 2^R 7R# \d"p\PR Y4R p?R #R p?ii;i \dR#i;i)atWrite content into the sandbox via env.execute(); True on success. Content goes through stdin, not the command string: Linux ``MAX_ARG_STRLEN`` caps one argv element at 128 KB, so a heredoc-in-command silently failed for exactly the oversized results this handles. The write is round-trip verified with ``wc -c`` (one extra exec RTT per oversized result): a zero exit from ``cat`` does not prove the bytes landed (quota/ENOSPC races, API-body truncation on payload backends). A measured mismatch removes the archive and fails closed; an unprobeable backend (no ``wc``, exec error, unparseable output) stays best-effort success.)_private_dirs_cmdz && cat > )r? stdin_datarFr}r~rzwc -c < rz$Sandbox size probe failed for %s: %sNToutputu^Sandbox spill for %s is not lossless (%d bytes in sandbox, expected %d) — discarding archivezrm -f )rr%dirnametools.code_execution_rpcrrrrErrKrr rmrnr&rsplitisdigitrr) rPrrw storage_dirrcmdexpectedproberprawrs &&& r _write_to_sandboxrEs''//+.K; , -.{{;/0 2C {{3w{7;;L!LPQQ7>>')><=H hu{{;'?&@A2 N yyq!Q& eii"%++ , 2 2 4 : : replacement block.iz.1fz MBz KBz! This tool result was too large (,z characters, z). Full output saved to: u Use the read_file tool with offset and limit to access specific sections of this output. 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 archive is kept while this session's transcript references it. If it is missing, inspect the current state before retrying — the call that produced it may already have taken effect. Preview (first z chars): z ...rr)PERSISTED_OUTPUT_TAGrKPERSISTED_OUTPUT_CLOSING_TAG)rrrrsize_kbsize_strs&&&& r _build_persisted_messagernsd"G-4_'D.%S)WSMQTBUH  !++8*;= S!!* ,g,z 3  !)Wb 2 +, - . /r z^Full output saved to: (.+)$c>V^8dQhR\R\R,/#)rrPrNr{)rs"r rrs55C5C$J5r c\V\4'd!\V9d\P V4MRpV'd VP ^4P 4#R#)zFile path from a block, or None (lets the result-reference stubbing guard in agent/tool_guardrails.py carry the spillover path instead of leaving it dangling).N)r+r&r_PERSISTED_PATH_REr-groupr)rPmatchs& r extract_persisted_pathrsO7C((-AW-L & &w /RV %*5;;q>   !44r c nV^8dQhR\R\R\R\R\R,R\/#)rrP tool_namerconfig thresholdNr)r&rr)rs"r rrs=););s);s););&2);).);AD);r caaa aaVfVPS4pV\R48Xg\V4V8:dV#\V4o\ S4p\ SVP R7woo RRV VVVV3Rlllp\SV4p\V4p V 'd Ve V!V4#V 'gSV'd \W4MRp V eV!V RV R24#\V4 RV 2p \SW4'd V!V 4#\PR S\V44S R \V4R R 2# \d"p \PR ST 4Rp ? LYRp ? ii;i)zLayer 2: persist an oversized result, return preview + path. ``threshold`` overrides ``config.resolve_threshold(tool_name)``; falls back to inline truncation when no write location succeeds.Ninf)rc<V^8dQhR\R\R\/#)rr% host_suffixrr{)rs"r r/maybe_persist_tool_result..__annotate__s&YYY3YYr cv<\PRSS\S4W4\SS\S4V4#)z6Persisted large tool result: %s (%s, %d chars -> %s%s))rminforKr)r%rrpersisted_contentrrrs&&r _persisted-maybe_persist_tool_result.._persisteds: L{C0A,BD W'3?P;QSWXXr z [host: ]rzSandbox write failed for %s: %szDInline-truncating large tool result: %s (%d chars, no sandbox write)z [Truncated: tool response was rz3 chars. Full output could not be saved to sandbox.])r)resolve_thresholdrrKrrr preview_sizerrxrrrr rmrr)rPrrrwrrrzrr host_siderrrprrrs&ff&&& @@@r maybe_persist_tool_resultr sq ,,Y7 E%L CLI$='w/$[1H():fFYFYZGXYY $$5x@I!#&IY*)$$ FO1)ATX  g)A'>? ?-c231XJ?  P !2KEE!+..F KKV3w<)i9#g,q9IJ: :;  P NNEEc$V^8dQhR\/#rr)rs"r rrs3r c|\V\4'd\RV44#\T;'gR4#)zCharacters of TEXT a tool message carries: a string's length, or the summed text parts of a multimodal part list (image parts are governed by the vision embed budget, and a list's ``len`` counts parts).c3"TFYp\V\4'gKVPR4R8XgK3\VPR4;'gR4xK[ R#5i)typer9rN)r+r'rrK).0ps& r %_content_text_size..sLpW 1d@S+XYX]X]^dXeioXo+3quuV}**++WsA#A#A#A#r)r+rWsumrK)rPs&r _content_text_sizers3'4  pWppp w}}" r c jV^8dQhR\R\R\R\\\3,/#)rpartsrrr)rWr&rrr)rs"r rrs; o oD os o oZ_`dfi`iZj or c $\V4UUu.uFzwrE\V\4'gKVPR4R8XgK5\VPR4\4'gK\\ VR,9gKpWER,3NK| pppV'gV^3#\ VRR7wrx\V\V RV 2W#^R7p W8XdV^3#.VRVO/W,CRV /CNW^,RO\V4\V 4, 3#uuppi)z_Persist the largest non-persisted text part of a multimodal list; ``(new parts, chars saved)``.rr9c&\V^,4#)rK)ts&r *_spill_largest_text_part..s QqTr )r_partrPrrrwrrN) enumerater+r'rr&rr!r _BUDGET_TOOL_NAMErK) rrrwrirr7idxr9 replacements &&&& r _spill_largest_text_partr&s(1%(8 [(8Jq$.sadr T)rreverse tool_call_idbudget_zFBudget enforcement: persisted a text part of tool result %s (%d chars)r z7Budget enforcement: persisted tool result %s (%d chars))rrrr!r+rWr turn_budgetsortedr&rmrr r"rK)r(rwrmsgsizes total_sizer#size candidatesr$rPrrsavedr%s&&& r enforce_turn_budgetr8s DQ Q=C  2 6 7=E QUJ+4U+;V+; 0 4 4Y ?FF)1A1E1EiQS1TT1)+;JV'''JNDI  ++ + $ # $Y/#(,,^wse_M gt $ $3G#VLE# 05c"9- dfqy /'8ka1   ! #k*T1 1J,7# y ) KKQ# +%J( 7 RVs$F9AF>F>c@V^8dQh/^\9d \;R&#)rrk)__conditional_annotations__r1)rs"r rrs#EEN%$$OEr >_metarstructuredContent)N)Cr:__doc__rrloggingrrrerrBtempfile threadingrVtools.budget_configrrr getLogger__name__rmrrr%join gettempdirrr rr" frozensetrrrcompilerrLockrjr1rkr r#r5rFr,r.r:rRrerqrxrrrrrrrr MULTILINErrr rr&r8r)r:s@r rKsE   XX   8 $+4ggll8..02BC $,GH0!9 " +> ?!("u$0 8.ZZ FGa::UV /8"J8" @0 X 5OR&aR&R/(ZZ ?N5SW5C8<);X o8