PmjedZddlmZddlZddlZddlZddlmZddlm Z m Z m Z ej e ZdZdZdZdZd$dZd$dZd%dZd&dZd'dZddddd(d"Zgd#ZdS))uiSpill oversized hook-injected context to disk with a preview placeholder. Ported from openai/codex PR #21069 (``Spill large hook outputs from context``). Background ---------- Both shell hooks (``agent/shell_hooks.py``) and Python plugins (``pre_llm_call`` hook in ``run_agent.py``) can return ``{"context": "..."}`` which gets concatenated into the current turn's user message on EVERY subsequent API call. If a hook emits a large blob (e.g. a debug dump, a full file, or a runaway prompt-engineering script), that blob inflates every turn of the session and blows out the prompt cache prefix the moment it's appended. This mirrors what Codex does for its ``PreToolUse``/``Stop``/feedback hooks: once the injected text exceeds a configured budget, write the full content to a per-session directory on disk and replace the in-prompt payload with a head/tail preview plus the saved path. The model can still inspect the full content via ``read_file`` or ``terminal`` if it needs to. Config (``config.yaml``):: hooks: output_spill: enabled: true # default: true; set false to disable spilling max_chars: 10000 # default; context above this is spilled preview_head: 500 # chars shown at the start of the preview preview_tail: 500 # chars shown at the end of the preview directory: null # default: /hook_outputs Design invariants ----------------- * Behaviour-preserving when ``enabled: false`` or when content is under the cap — return the input string unchanged. * Never raises. Any I/O error (disk full, permission denied, missing HERMES_HOME, etc.) falls back to a byte-length truncation with an in-prompt notice — the hook context still reaches the model, just bounded in size. * Spill files are grouped by session so a ``/new`` session doesn't grow them forever in one directory. ) annotationsN)Path)AnyDictOptionali'iTvaluerdefaultintreturncj t|}n#ttf$r|cYSwxYw|dkr|S|S)Nrr TypeError ValueErrorrr ivs =/home/thesage/.hermes/hermes-agent/tools/hook_output_spill.py_coerce_positive_intr<sP ZZ z " Qww I ((cj t|}n#ttf$r|cYSwxYw|dkr|S|S)z@Like ``_coerce_positive_int`` but allows zero (e.g. empty tail).rr rs r_coerce_non_negative_intrFsP ZZ z " Avv IrDict[str, Any]ci} ddlm}|pi}t|tr|dnd}t|tr,|d}t|tr|}n#t $ri}YnwxYw|dt }|t|nt }|d}|t|tsd}|t|dtt|d tt|d t|d S) z7Return resolved hook output-spill config. Never raises.r) load_confighooksN output_spillenabled directory max_chars preview_head preview_tail)rrrr r)hermes_cli.configr isinstancedictget ExceptionDEFAULT_ENABLEDboolstrrDEFAULT_MAX_CHARSrDEFAULT_PREVIEW_HEADDEFAULT_PREVIEW_TAIL)sectionrcfgrsub enabled_rawrrs rget_spill_configr0Qs| G 111111kmm!r$.sD$9$9C   t eT " " ))N++C#t$$  ++i99K#.#:d;G K((IZ 3%?%? )'++k*B*BDUVV0 KK ' ')=  1 KK ' ')=     sA?B BBdirectory_override Optional[str] session_idrc.|r-ttj|}n ddlm}t|dz }|pd}|dddddd}||z S) z=Return the directory where spill files for this session live.r)get_hermes_home hook_outputsz no-session/_\z..)rospath expanduserhermes_constantsr5replace)r1r3baser5session_segments r_resolve_spill_dirrAss8BG&&'9::;;444444OO%%&&7!0LO&--c377??cJJRRSWY\]]O / !!textr(headtail saved_pathsourcec|t|}|dkr |d|nd}|dkr||kr || dnd}d|d|dd|rd|d nd zg}|r*|d |||r*|d ||d |S)zDAssemble the in-prompt preview with head/tail and saved-path footer.rN[u output truncated — ,z chars; full content z saved to ]u#unavailable — spill write failed]z --- head ---z --- tail --- )lenappendjoin) rCrDrErFrGtotal head_chunk tail_chunkpartss r_build_previewrUs IIE $qetebJ!%edllteffJ IFHH%HHHH(2 ] $z $ $ $ $8] _ E! ^$$$ Z   ! ^$$$ Z   99U  rBhook)r3rGconfigrWOptional[Dict[str, Any]]c|dSt|ts" t|}n#t$rYdSwxYw||n t}|dds|St |dpt }t||kr|St |dpd}t |dpd}|d }d} t||} | dd tj j d } | | z } | |d r|n|d zd t| } n4#t$r'} td| d} Yd} ~ nd} ~ wwxYwt#|||| |S)aSpill ``text`` to disk if it exceeds the configured cap. Returns either ``text`` unchanged (when under the cap, disabled, or empty) or a preview string with a filesystem path pointing at the full content. Parameters ---------- text: The raw injected-context string from a hook. Non-string inputs are coerced with ``str()``. session_id: Used to group spill files by conversation. Falls back to ``"no-session"`` if missing. source: Human-readable label used in the preview header (``"hook"``, ``"plugin hook"``, ``"shell hook"``, etc.). Free-form. config: Optional override for tests; normally resolved from ``config.yaml``. NrIrTrrrr r)parentsexist_okz.txtrMzutf-8)encodingzhook output spill failed: %s)rG)r"r(r%r0r$r r)rNrAmkdiruuiduuid4hex write_textendswithloggerwarningrU)rCr3rGrWr-rrDrEr1rF spill_dirfilename spill_pathexcs rspill_if_oversizedris8 |r dC  t99DD   22 &&&,<,>,>C 779d # # CGGK((=,=>>I 4yyI sww~&&+! , ,D sww~&&+! , ,D--!%J &'9:FF t444jll&,,,)  dmmD&9&9Jddtd{U\]]]__ 5s;;;  $dJv F F FFs%+ 99BF F=F88F=)r)r*r+r&r0ri)rrr r r r )r r)r1r2r3r2r r) rCr(rDr rEr rFr2rGr(r r() rCr(r3r2rGr(rWrXr r()__doc__ __future__rloggingr:r^pathlibrtypingrrr getLogger__name__rcr)r*r+r&rrr0rArUri__all__rBrrssJ((T#""""" &&&&&&&&&&  8 $ $D""""":!%'+ @G@G@G@G@G@GF   rB