Module tool_spill 

Tool output virtualisation.

Once a tool result is in model history it rides every later request. A text result bigger than tool_output_spill_bytes is therefore stored whole in a private spill file (<base>/spill/<session>/<tool_use_id>.txt, layout and retention in agent_core::core::tool_spill), and history gets a short preview instead: the first tool_output_spill_head_bytes and the last tool_output_spill_tail_bytes of the result, cut at line boundaries where possible, and a note naming the file and the omitted line range so the model can read it with offset/limit or grep it. The legacy cut (max_tool_output, head only) loses the tail, which is usually where the errors are; this loses nothing.

Rules:

• Off is legacy. A 0 threshold (ToolSpillPolicy::OFF) makes ToolSpill::virtualise return None before touching anything, so every caller falls through to the unchanged legacy path.
• Deterministic. The preview is a pure function of the result, the two budgets and the file path (session dir + tool_use_id): no timestamps, no random ids. History bytes, and the prompt cache over them, stay stable.
• Fail-soft. A spill that cannot be written (unwritable base dir, session cap reached) returns None: the caller uses the legacy cut, never a pointer to a file that does not exist.
• read is never copied. The model can already read that file by range, so its preview points back at the file itself with the offset/limit of the omitted lines. A read with an explicit limit is a deliberate range request and is left alone.
• Rich results are untouched. Callers only pass plain-text content (no image/document blocks).

Structs

ToolSpill

One session’s virtualiser: policy, spill dir, shared counters. Cheap to clone; built per stream from the runtime’s bound spill root.

ToolSpillPolicy

Thresholds from tool_output_spill_*.

ToolSpillStats

Session-cumulative counters, shared by a runtime and its clones. Metadata only.

ToolSpillTotals

Point-in-time copy of ToolSpillStats.

Virtualised

A virtualised result: what history carries instead of the full text.

Enums

SpillTarget

How one call’s result may be virtualised, decided from the tool and its (post-before_tool_call) input before it runs.

Constants

SPILL_FILE_CAP_BYTES

A spill file keeps at most this many bytes of a result (then a note).

SPILL_SESSION_CAP_BYTES

One session (runtime) writes at most this many spill bytes; past it, results fall back to the legacy cut. A safety net against a loop that re-runs a huge command, not a budget anyone should meet.