DSH plugin spill store: locators, hints, and save contracts
After a tool result spills, the model holds a locator — not a path and not an access-control credential. DSH plugin's spill store is an optional capability seam: it persists text verbatim and hands back a model-facing handle. Who decides to spill, and who owns the preview, lives elsewhere.
spill is optional and outside the loop
Storage and decision are deliberately separated: storage preserves, the consumer decides.(source)
Three facts frame the layer:
- The service definition is
dsh-spill, surfaced asctx.spillStore; the local service provider isdsh-spill-local. - The consumers are the tool-result policy and session references, not the agent loop itself.
- Preview and spill decisions belong to consumers; the store persists the provided text verbatim.
So do not expect "save it and it gets smart." Whether to spill, which excerpt the model sees, and how much to truncate are all consumer policy. The store's only job is to persist the full content and return a usable locator plus retrieval hint.
Three fields with three boundaries
owner handles archiving, source handles provenance, and suggestedName is only a naming hint — none are access control.(source)
SaveTextSpill has four parts: owner, source, suggestedName, and content.
owner— the storage namespace for the save, withsessionIdas its only field. It lets the backend archive artifacts under the producing session, but the real model-facing handle is the returnedSpillLocator.source— descriptive producer provenance, never access control. Tool sources are{ kind: 'tool', toolName, callId, label }; session-reference sources are{ kind: 'session-reference', sessionId, label }.suggestedName— a caller-suggested base name such asweb_fetch.txt. The backend sanitizes it into a single safe path segment; it is a hint and never a path.
content is the complete UTF-8 text. Note "complete": concatenation, truncation, and summarization must not happen before the save, or the model retrieves an amputated payload through the locator.
Fork semantics are defined here too: a forked session inherits locators already present in the seed log, and those artifacts are neither copied nor reassigned; spills produced after the fork use the child session id. If you touch fork logic, do not try to migrate old artifacts.
The result is a locator plus a hint, not a path
SpillRef has three fields, but locator is opaque and consumers must not parse it.(source)
interface SpillRef {
locator: SpillLocator
bytes: number
retrievalHint: string
}
locator is a branded, model-facing handle. A local backend renders it as a filesystem path; a remote or database backend may render a URI, a key, or a command token. The reference requires consumers to treat it as opaque and render it with retrievalHint, rather than assuming read is always the right retrieval mechanism.
bytes is exact, suitable for display or budget hints — do not reverse it into a character count. retrievalHint is the answer to "how do I fetch this": the local backend suggests read or grep on that path.
One easily missed boundary: retention cleanup can invalidate old locators along with other stale session artifacts, and the spill seam defines no per-session cleanup policy. Long-lived locator validity is not part of the contract; content that must persist belongs somewhere else.
One method, and failure must reject
The abstract service exposes only saveText, rejects on failure, and leaves degradation to the caller.(source)
SpillStore lives in packages/spill/spill/src/index.ts with a single operation: saveText(input) → Promise<SpillRef>. It rejects when actual storage fails — insufficient permissions, ENOSPC, backend unavailable.
That rejection semantics matters: the seam neither swallows errors nor invents a fallback for you. Policy consumers read a rejection as a best-effort signal — keep the original inline result instead of turning a previously successful tool call into isError.
Be equally clear about what it does not own: retention policy, tool-result replacement, and retrieval or search APIs are outside this seam. Adding "periodic per-session cleanup" or "a locator index" is another capability; do not stuff it into saveText.
There is also an implementation constraint: only one implementation may exist per context, and loading a second one throws per Cordis's standard duplicate-service behavior. To replace a backend, replace the plugin rather than loading both.
What the local backend writes
The backend builds the path itself; safety comes from directory permissions and exclusive writes.(source)
dsh-spill-local writes to <root>/session-<hash>/<random>-<safeName>:
- Root — a configured or lazily created private directory with mode
0700; - Session subdirectory —
sha256(sessionId), so special characters in the id never reach the path; - Filename — a random prefix plus the sanitized safe name, guaranteeing no collisions;
- Write mode — exclusive and owner-only, i.e.
open(path, 'wx', 0o600), so a pre-planted symlink cannot redirect the write elsewhere.
This explains two behaviors: identical suggested names never overwrite each other (random prefix), and you cannot reconstruct the real path from the suggestion (sanitization plus randomness). Its locator is a local path, and its retrievalHint tells the model to use read or grep there.
Consumer duties: preview and policy stay outside
Spill policy is a separate plugin's business; the store only supplies an address.(source)
The policy consumer dsh-spill-policy replaces image and text results above maxInlineTokens with the leading and trailing content kept in order plus a spill address. The process is best effort: if the save fails, the original inline result survives and a successful call never becomes an error.
For plugin authors, that draws a clean responsibility line:
- your plugin decides when to spill, which head and tail to keep, and how much the model sees;
- the store only guarantees the full text is saved and returns a locator with a hint;
- the model's retrieval action follows
retrievalHint, not your hard-codedread.
If you build a custom tool, first decide whether "what the model sees" and "what storage holds" are the same payload. Under spilling they should not be: the model gets a summary while storage keeps the full text.
Verification: save text and fetch it back
The point is not "the file exists" but "bytes match, the hint works, failure degrades."(source)
- Build
contentcontaining CJK characters and emoji, callsaveText, and record the returnedbytes. - Retrieve the content the way
retrievalHintsuggests and assert a byte-for-byte match. - Pass a
suggestedNamecontaining../and assert the written filename collapses to one safe segment. - Save identical content under two different
sessionIdvalues and assert separate session subdirectories with no overwrite. - Simulate an unavailable store (a read-only root) and assert
saveTextrejects while the caller keeps its inline result.
If step 1's bytes surprises you, you counted characters. CJK text and emoji occupy several bytes in UTF-8, and bytes promises only bytes.
To connect spilling with context pressure, read token metering and context pressure; for the concrete shape of truncated references, see session reference truncation.
One line to close: spill stores and never decides, owner archives while source attributes and suggestedName merely hints, locators stay opaque with retrieval driven by retrievalHint, and a failed save leaves degradation to the caller.
FAQ
No. DSH plugin's spill layer only saves. The reference assigns preview and spill decisions to consumers; the store persists the exact text it is given and returns a locator.
No. DSH plugin treats it as a naming hint only. The backend sanitizes it into a single safe path segment, so the produced name derives from it but never equals it.
No. DSH plugin's policy consumer treats saving as best effort. On failure it keeps the original inline result rather than turning a successful call into isError.
No. DSH plugin defines the locator as opaque. A local backend may render a filesystem path while remote backends may use URIs or keys, so render retrievalHint instead of parsing.
Related Terms
- SaveTextSpill
- SaveTextSpill is the save request: owner, source, suggestedName, and the full content to persist verbatim.— packages/spill/spill/src/types.ts
- SpillRef
- SpillRef is the result of one save: an opaque locator, an exact byte count, and a backend retrieval hint for the model.— packages/spill/spill/src/types.ts
- SpillOwner
- SpillOwner is the storage namespace for a save, carrying only sessionId so backends archive artifacts under the producing session.— packages/spill/spill/src/types.ts
- retrievalHint
- retrievalHint is the backend's model-facing retrieval guidance; consumers render the locator with it rather than assuming read is always the mechanism.— packages/spill/spill/src/types.ts
Sources
- DeepSeek Harness reference - Spill store· deepseek-ai
- packages/spill/spill/src/types.ts· deepseek-ai