Overview
dsh-spill-local
@deepseek-ai/dsh-spill storage seam. Registers as ctx.spillStore and persists a tool's oversized text to a private, session-scoped file; its locator is the file path and its retrieval hint tells the model to use read or grep on that path.This is an atomic module already shipped with Harness, not a standalone profile layer.
Capabilities
What it contributes
README / EN
Package documentation
@deepseek-ai/dsh-spill-local
English | 中文
The local-filesystem implementation of the @deepseek-ai/dsh-spill storage seam. Registers as ctx.spillStore and persists a tool's oversized text to a private, session-scoped file; its locator is the file path and its retrieval hint tells the model to use read or grep on that path.
Storage layout
Files land at <root>/session-<hash>/<random>-<safeName>:
root— the configroot(resolved to absolute), or a lazily-created private (0700) per-process directory under the OS temp dir when omitted. A predictable, world-readable root would let other local users read spilled tool output or plant symlinks.session-<hash>— a shortsha256(sessionId)prefix, so a session's spill files group together and a future cleanup can drop them per session.<random>-<safeName>— an unpredictable hex prefix (defeats symlink planting in a shared root) plus the caller'ssuggestedNamesanitized to one safe path segment (traversal-proof; mirrors the JSONL persistence backend'sencodeSegment). The write is exclusive + owner-only (open(path, 'wx', 0o600)): it fails on any pre-existing path, symlink or not, so a planted target cannot redirect it.
Config
| Key | Default | Meaning |
|---|---|---|
root |
private 0700 temp dir | Root directory for spill files. Set to keep them under a known location. |
saveText rejects on a real storage failure (permissions, ENOSPC); the spill policy treats a rejection as best-effort and keeps the inline result. See the seam README for the vocabulary and the tool output spill Agent Note for the design.
Model Experience
Indirectly, through spill consumers that render the local path and read/grep retrieval guidance.
KV Cache effect
No direct invalidation; the named consumer owns any request-prefix changes.
Known Limitations and Deferred Work
- Local spill files persist until external cleanup — the backend has no session-lifecycle deletion or age-based retention policy, because persisted, resumed, and forked sessions may still reference a path.
- Locators require a co-located filesystem consumer — a remote or virtual deployment needs another
SpillStorebackend whose locator and retrieval hint are meaningful there.
LIMITATIONS
Known limitations
- **Local spill files persist until external cleanup** — the backend has no session-lifecycle deletion or age-based retention policy, because persisted, resumed, and forked sessions may still reference a path. - **Locators require a co-located filesystem consumer** — a remote or virtual deployment needs another `SpillStore` backend whose locator and retrieval hint are meaningful there.