Spill Storage

Spill Storage

Edge adaptation of the upstream tool-output overflow storage.

Upstream reference: Spill Storage documentation

What Upstream Provides

Spill storage is an optional capability seam that persists large tool outputs and returns model-facing locators with retrieval guidance. It comprises three packages:

• dsh-spill — service definition: SpillStore abstract class with a single saveText() method.
• dsh-spill-local — upstream provider: saves to local filesystem.
• dsh-spill-policy — consumer: replaces inline tool results exceeding maxInlineBytes with preview excerpts and spill references.

When a tool produces output larger than the policy threshold, SpillPolicy calls ctx.spillStore.saveText(), stores the full content, and replaces it with a truncated preview + a retrievalHint telling the model how to read the spilled file.

What Edge Changed

Replacement SpillStore → VFS

EdgeVfsSpillStore extends the upstream SpillStore abstract class. Instead of writing to the local filesystem (dsh-spill-local), it writes to the Cloudflare Computer VFS at /workspace/.spill/{name}_{callId}.txt. The VFS writer is bound per-turn and unbound after the turn completes.

Direct Reuse SpillPolicy

SpillPolicy is installed as-is with maxInlineBytes: 32_768. The policy consumer, retrieval hint generation, and preview truncation are entirely upstream code.

What Edge Did NOT Change

• SpillStore interface (saveText contract)
• SpillPolicy threshold and preview behavior
• SpillRef/SpillLocator structure
• Model-facing retrieval hints

Performance Characteristics

Write path

saveText() performs two VFS operations: mkdir('/workspace/.spill', { recursive: true }) and writeFile(path, content). Both delegate to the Computer VFS backend. The mkdir is idempotent after the first call per session.

Spill size

Spill triggers when tool output exceeds 32 KB. Typical spilled outputs are bash command results (large directory listings, build logs, test output). The full content is written to VFS; only a truncated preview enters the event log.

Architecture Summary

| Component | Category | Edge Code |

|---|---|---|

| EdgeVfsSpillStore | Replace | ~30 lines (extends SpillStore, writes to VFS) |

| SpillPolicy | Reuse | One ctx.plugin() call |

Key observation: Spill storage is a textbook minimal replacement — the upstream abstract class defines the contract, Edge provides a 30-line VFS implementation, and the upstream policy consumer works unchanged.