`gj^dZddlmZddlZddlZddlZddlmZddlm Z m Z m Z eje ZdZdZdZdZdd Zdd Zdd Zdd Z dd Zdddd ddZgdZy)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'iTcZ t|}|dkr|S|S#ttf$r|cYSwxYw)Nrint TypeError ValueErrorvaluedefaultivs J/root/.hermes/venv/lib/python3.12/site-packages/tools/hook_output_spill.py_coerce_positive_intr<s> Z Qw I z " **cZ t|}|dkr|S|S#ttf$r|cYSwxYw)z@Like ``_coerce_positive_int`` but allows zero (e.g. empty tail).rr r s r_coerce_non_negative_intrFs> Z Av I z "rcRi} ddlm}|xsi}t|tr|j dnd}t|tr#|j d}t|tr|}|j dt }| t|nt }|j d}|t|tsd}|t|j dtt|j d tt|j d t|d S#t $ri}YwxYw) z7Return resolved hook output-spill config. Never raises.r) load_confighooksN output_spillenabled directory max_chars preview_head preview_tail)rrrrr)hermes_cli.configr isinstancedictget ExceptionDEFAULT_ENABLEDboolstrrDEFAULT_MAX_CHARSrDEFAULT_PREVIEW_HEADDEFAULT_PREVIEW_TAIL)sectionrcfgrsub enabled_rawrrs rget_spill_configr.Qs G 1m!r$.sD$9 t eT "))N+C#t$++i9K#.#:d;G K(IZ 3%? )'++k*BDUV0 KK ')= 1 KK ')=    sA'D D&%D&c|r)ttjj|}n ddlm}t|dz }|xsd}|jddjd djd d}||z S#t $rQtjjdxstjjd}t|dz }YwxYw) z=Return the directory where spill files for this session live.r)get_hermes_home hook_outputs HERMES_HOMEz ~/.hermesz no-session/_\z..) rospath expanduserhermes_constantsr0r#environr"replace)directory_override session_idbaser0homesession_segments r_resolve_spill_dirrAssBGG&&'9:; / 8)*^;D!0LO&--c37??cJRRSWY\]O / !! /::>>-0SBGG4F4F{4SD:.D /sBACCc2t|}|dkDr|d|nd}|dkDr ||kDr|| dnd}d|d|dd|rd|d nd zg}|r"|jd |j||r"|jd |j|d j|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) textheadtail saved_pathsourcetotal head_chunk tail_chunkpartss r_build_previewrTs IE $qetbJ!%edltefJ F8)%2GH(2Yzl! $8] _ E ^$ Z  ^$ Z 99U hook)r=rOconfigc|yt|ts t|}||n t}|j dds|St |j dxst }t||kr|St |j dxsd}t |j dxsd}|j d }d} t||} | jdd tjjd } | | z } | j|jd r|n|d zd t| } t#|||| |S#t$rYywxYw#t$r"} tj!d| d} Yd} ~ Ed} ~ wwxYw)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``. NrCrTrrrrr)parentsexist_okz.txtrGzutf-8)encodingzhook output spill failed: %s)rO)r r&r#r.r"r r'rHrAmkdiruuiduuid4hex write_textendswithloggerwarningrT)rKr=rOrWr+rrLrMr<rN spill_dirfilename spill_pathexcs rspill_if_oversizedrhs|8 | dC  t9D&&,<,>C 779d # CGGK(=,=>I 4yI sww~&+! ,D sww~&+! ,D-!%J &'9:F t4jjl&&'t,)  dmmD&9dtd{U\]_ $dJv FF?  6 5s; s* E A9E EE F%FF)r'r(r)r$r.rh)rrrr returnr )rizDict[str, Any])r< Optional[str]r=rjrir) rKr&rLr rMr rNrjrOr&rir&) rKr&r=rjrOr&rWzOptional[Dict[str, Any]]rir&)__doc__ __future__rloggingr6r]pathlibrtypingrrr getLogger__name__rbr'r(r)r$rrr.rArTrh__all__rUrrts(T# &&   8 $D"*       :!%'+ @G @G@G  @G % @G  @GF rU