Module tool_spill 

Tool-output spill files: where they live and how they go away.

A tool result bigger than tool_output_spill_bytes is stored whole in <base>/spill/<session>/<tool_use_id>.txt, and model history carries a short head + tail preview that points at the file (the engine’s runtime::tool_spill). <session> is the persisted conversation id for a foreground session and the runtime trace session id for a worker.

Spill files are a cache of output the model already saw a preview of, so they are disposable. They go away two ways:

• with their session: retention (crate::retention) removes <base>/spill/<id>/ when it deletes or forgets session <id>;
• by age: sweep_stale_spill runs at startup, like the trace content-capture sweep, and removes session dirs nothing has written to for SPILL_MAX_AGE. Worker dirs have no session file, so this is what removes them.

Every directory is 0700 and every file 0600 (spec §5.4).

Structs

SpillRemoval

What a removal freed: spill-root entries (session dirs, strays), the regular files inside them, and their bytes.

Constants

SPILL_DIR_NAME

Name of the spill root under the Synaps base dir.

SPILL_MAX_AGE

A session spill dir nothing has written to for this long is removed by sweep_stale_spill. A week covers a session resumed after a weekend; past that the preview in history is what remains (the pointer goes dead, and a read of it says so).

Functions

default_spill_root

<base>/spill, resolved through the base-dir helper (crate::config::base_dir, which honours SYNAPS_BASE_DIR). Callers bind this ONCE at construction, like the capture dir.

remove_session_spill

Remove session session_id’s spill dir under root. Idempotent: a missing dir is Ok with nothing freed. An id that is not a safe path component is a no-op (nothing could have been written for it). A symlink planted at the dir’s path is removed as a link, never followed.

session_component

id when it is safe as ONE path component: 1-128 bytes of [A-Za-z0-9._-], and not . or ... Session ids (20261029-143000-ab12) and runtime trace ids (session-<pid>-<ms>-<seq>) both qualify; anything else is refused rather than rewritten, so two different ids can never share a directory.

spill_root

<base>/spill for an explicit base dir.

sweep_stale_spill

Startup sweep: remove every session dir under root whose last write (dir mtime: creating a spill file updates it) is older than max_age at now, plus anything that is not a directory (nothing else lives here). Bounded, fail-soft and confined to root’s own entries. A missing root is a no-op.