Coder/deepseek-harness
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix(review): generalize spill storage locators

Browse Source
This commit is contained in:
Dudu-0223
2026-07-13 11:07:27 +08:00
parent 43535aab42
commit 5ac03dde3f
37 changed files with 274 additions and 260 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
packages/spill/README.md
View File

@@ -4,9 +4,9 @@ The tool-output spill capability seam: an abstract storage interface, a local fi
| Package | Role | ctx key |
|---|---|---|
| `spill/` | Abstract spill storage seam (`saveText` — persist oversized tool text to a session-scoped path) | `ctx.spillFiles` |
| `spill-local/` | Local-filesystem backend: private, session-scoped files with traversal-safe names | (registers on `ctx.spillFiles`) |
| `spill-policy/` | `tools/post-execute` policy: replaces oversized plain-text results with a preview + spill path | (no service surface) |
| `spill/` | Abstract spill storage seam (`saveText` — persist oversized tool text and return a locator + retrieval hint) | `ctx.spillStore` |
| `spill-local/` | Local-filesystem backend: private, session-scoped files with traversal-safe names | (registers on `ctx.spillStore`) |
| `spill-policy/` | `tools/post-execute` policy: replaces oversized plain-text results with a preview + spill locator | (no service surface) |
The interface lives at `spill/spill/`. The split mirrors bash/fs: the seam owns storage only, `spill-local` owns the filesystem mechanics, and `spill-policy` owns WHEN to spill and the model-facing notice. Preview mechanics stay in [`util/retention`](../util/README.md) — the policy composes the two without either owning the other's job.

2
packages/spill/spill-local/README.md
View File

@@ -1,6 +1,6 @@
# @deepseek-ai/dsh-spill-local
The **local-filesystem** implementation of the [`@deepseek-ai/dsh-spill`](../spill) storage seam. Registers as `ctx.spillFiles` and persists a tool's oversized text to a private, session-scoped file the model's `read` tool can open.
The **local-filesystem** implementation of the [`@deepseek-ai/dsh-spill`](../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

18
packages/spill/spill-local/src/index.ts
View File

@@ -1,9 +1,9 @@
/**
* `LocalSpillFiles`: the host-filesystem implementation of the
* `LocalSpillStore`: the host-filesystem implementation of the
* `@deepseek-ai/dsh-spill` storage seam. Persists a tool's oversized text to a
* private, session-scoped file (see `./store.ts` for the traversal-safe naming
* and exclusive owner-only write) and returns a path the local `read` tool can
* open.
* and exclusive owner-only write) and returns a path locator plus local
* read/grep retrieval guidance.
*
* @module @deepseek-ai/dsh-spill-local
*/
@@ -11,7 +11,7 @@
import { Context } from 'cordis'
import { resolve } from 'node:path'
import z from 'schemastery'
import { SpillFiles, SpillPath } from '@deepseek-ai/dsh-spill'
import { SpillLocator, SpillStore } from '@deepseek-ai/dsh-spill'
import type { SaveTextSpill, SpillRef } from '@deepseek-ai/dsh-spill'
import { privateRoot, saveTextFile } from './store.ts'
@@ -34,7 +34,7 @@ export interface Config {
* (0700) root — a spilled tool result must not be readable by other local users
* or redirectable via a planted symlink.
*/
export class LocalSpillFiles extends SpillFiles {
export class LocalSpillStore extends SpillStore {
static Config: z<Config> = z.object({
root: z.string(),
})
@@ -54,8 +54,12 @@ export class LocalSpillFiles extends SpillFiles {
suggestedName: input.suggestedName,
content: input.content,
})
return { path: SpillPath(saved.path), bytes: saved.bytes }
return {
locator: SpillLocator(saved.path),
bytes: saved.bytes,
retrievalHint: 'Use read with offset/limit, or grep this path to search within it.',
}
}
}
export default LocalSpillFiles
export default LocalSpillStore

35
packages/spill/spill-local/tests/spill-local.spec.ts
View File

@@ -1,9 +1,9 @@
/**
* Tests for the LOCAL spill backend: `saveText` writes a session-scoped file and
* returns its path + byte length, filename sanitization neutralizes traversal,
* the configured `root` is honored (and the private default when omitted), and a
* storage failure rejects. The Cordis-free `store.ts` helpers are exercised
* directly for the naming/encoding edge cases.
* returns a locator + byte length + retrieval hint, filename sanitization
* neutralizes traversal, the configured `root` is honored (and the private
* default when omitted), and a storage failure rejects. The Cordis-free
* `store.ts` helpers are exercised directly for the naming/encoding edge cases.
*/
import { describe, expect, it, beforeEach, afterEach } from 'vitest'
@@ -14,7 +14,7 @@ import { dirname, isAbsolute, join } from 'node:path'
import { CallId } from '@deepseek-ai/dsh-llm'
import { SessionId } from '@deepseek-ai/dsh-session'
import type { SaveTextSpill } from '@deepseek-ai/dsh-spill'
import LocalSpillFiles, { encodeSegment, privateRoot, saveTextFile, sessionDir } from '@deepseek-ai/dsh-spill-local'
import LocalSpillStore, { encodeSegment, privateRoot, saveTextFile, sessionDir } from '@deepseek-ai/dsh-spill-local'
let root: string
@@ -106,33 +106,34 @@ describe('privateRoot', () => {
})
})
describe('LocalSpillFiles service', () => {
it('registers as ctx.spillFiles and saves under the configured root', async () => {
describe('LocalSpillStore service', () => {
it('registers as ctx.spillStore and saves under the configured root', async () => {
const ctx = new Context()
await ctx.plugin(LocalSpillFiles, { root })
const ref = await ctx.spillFiles.saveText(request())
expect(dirname(ref.path)).toBe(sessionDir(root, 'sess-1'))
expect(readFileSync(ref.path, 'utf8')).toBe('the full body')
await ctx.plugin(LocalSpillStore, { root })
const ref = await ctx.spillStore.saveText(request())
expect(dirname(ref.locator)).toBe(sessionDir(root, 'sess-1'))
expect(readFileSync(ref.locator, 'utf8')).toBe('the full body')
expect(ref.bytes).toBe(Buffer.byteLength('the full body', 'utf8'))
expect(ref.retrievalHint).toBe('Use read with offset/limit, or grep this path to search within it.')
})
it('resolves a relative configured root to absolute', async () => {
const ctx = new Context()
await ctx.plugin(LocalSpillFiles, { root: '.' })
expect(isAbsolute((ctx.spillFiles as LocalSpillFiles).root)).toBe(true)
await ctx.plugin(LocalSpillStore, { root: '.' })
expect(isAbsolute((ctx.spillStore as LocalSpillStore).root)).toBe(true)
})
it('falls back to the private root when none is configured', async () => {
const ctx = new Context()
await ctx.plugin(LocalSpillFiles, {})
expect((ctx.spillFiles as LocalSpillFiles).root).toBe(privateRoot())
await ctx.plugin(LocalSpillStore, {})
expect((ctx.spillStore as LocalSpillStore).root).toBe(privateRoot())
})
it('rejects when the root is not writable (missing parent, exclusive open)', async () => {
const ctx = new Context()
// A file (not a dir) as the root makes mkdir under it fail — a real storage error.
const filePath = (await saveTextFile({ root, sessionId: 's', suggestedName: 'f', content: 'x' })).path
await ctx.plugin(LocalSpillFiles, { root: filePath })
await expect(ctx.spillFiles.saveText(request())).rejects.toThrow()
await ctx.plugin(LocalSpillStore, { root: filePath })
await expect(ctx.spillStore.saveText(request())).rejects.toThrow()
})
})

14
packages/spill/spill-policy/README.md
View File

@@ -1,8 +1,8 @@
# @deepseek-ai/dsh-spill-policy
The **tool-result spill policy**: a `tools/post-execute` transformer that keeps oversized plain-text tool results out of the model's context. When a final result exceeds `maxInlineBytes`, it saves the FULL text to a session-scoped spill file via [`ctx.spillFiles`](../spill) and replaces the model-facing result with a bounded head/tail preview plus the spill path — the model reads the complete result later with the existing `read` tool.
The **tool-result spill policy**: a `tools/post-execute` transformer that keeps oversized plain-text tool results out of the model's context. When a final result exceeds `maxInlineBytes`, it saves the FULL text through [`ctx.spillStore`](../spill) and replaces the model-facing result with a bounded head/tail preview plus the backend's locator and retrieval hint.
This plugin registers **no service** and owns no storage or preview mechanics: preview is [`@deepseek-ai/dsh-retention`](../../util/retention) (`TextRetainer`), storage is `ctx.spillFiles`. It only decides WHEN to spill and composes the notice.
This plugin registers **no service** and owns no storage or preview mechanics: preview is [`@deepseek-ai/dsh-retention`](../../util/retention) (`TextRetainer`), storage is `ctx.spillStore`. It only decides WHEN to spill and composes the notice.
## Config
@@ -13,7 +13,7 @@ This plugin registers **no service** and owns no storage or preview mechanics: p
## Behavior
1. Let the tool run (delegates via `next()`, so it bounds whatever a downstream hook accepted).
2. Skip `read` (avoids a `read → spill file → read again` loop) and any non-`accept` decision (a `block`'s corrective feedback passes through).
2. Skip `read` (avoids a `read → spill → read again` loop) and any non-`accept` decision (a `block`'s corrective feedback passes through).
3. Flatten the accepted content only when it is **plain text** (all `text` blocks); a result with any non-text block is left untouched.
4. If its UTF-8 size is `≤ maxInlineBytes`, leave it unchanged.
5. Otherwise save the full text and replace the result with a preview + this notice, sized so the whole replacement (preview + blank line + notice) stays within `maxInlineBytes` — the notice's byte cost is reserved out of the budget, so the preview shrinks to fit and the model-facing result never exceeds the cap:
@@ -21,13 +21,13 @@ This plugin registers **no service** and owns no storage or preview mechanics: p
```text
<retained head/tail preview>
(Omitted N bytes. Full formatted result saved to: /…/session-…/…-web_fetch.txt. Use read with offset/limit to inspect it.)
(Omitted N bytes. Full formatted result stored at: /…/session-…/…-web_fetch.txt. Use read with offset/limit, or grep this path to search within it.)
```
When the notice alone fills the budget (a tiny cap or a long path) the preview is empty and only the notice is returned. If even that notice-only replacement would exceed `maxInlineBytes`, the policy keeps the inline result — it never emits a replacement over the cap (and a within-cap replacement is always smaller than the original, so this also means spilling never adds bytes).
When the notice alone fills the budget (a tiny cap or a long locator) the preview is empty and only the notice is returned. If even that notice-only replacement would exceed `maxInlineBytes`, the policy keeps the inline result — it never emits a replacement over the cap (and a within-cap replacement is always smaller than the original, so this also means spilling never adds bytes).
**Best-effort:** no session owner, no `ctx.spillFiles` backend, or a `saveText` rejection ⇒ the policy logs a warning and returns the original result. A spill failure never turns a successful call into an `isError` or hides the inline result.
**Best-effort:** no session owner, no `ctx.spillStore` backend, or a `saveText` rejection ⇒ the policy logs a warning and returns the original result. A spill failure never turns a successful call into an `isError` or hides the inline result.
## Scope
The policy sees only the FINAL formatted tool result — not a tool's internal resource. If a provider already truncated (e.g. `web-fetch-local.maxBodyChars`), the spill file holds the full formatted result the tool returned, not the full original source. Provider/resource caps stay mandatory and separate. Tool-owned early spill (bash streams, subagent rollouts) is future work — see the [tool output spill RFC](../../../docs/rfc/implemented/architecture/2026-07-08-tool-output-spill-files.md).
The policy sees only the FINAL formatted tool result — not a tool's internal resource. If a provider already truncated (e.g. `web-fetch-local.maxBodyChars`), the spill artifact holds the full formatted result the tool returned, not the full original source. Provider/resource caps stay mandatory and separate. Tool-owned early spill (bash streams, subagent rollouts) is future work — see the [tool output spill RFC](../../../docs/rfc/implemented/architecture/2026-07-08-tool-output-spill-files.md).

36
packages/spill/spill-policy/src/index.ts
View File

@@ -2,12 +2,12 @@
* The spill-policy PLUGIN: a `tools/post-execute` result transformer that keeps
* oversized plain-text tool results out of the model's context. When a final
* result's UTF-8 size exceeds `maxInlineBytes`, it saves the FULL text to a
* session-scoped spill file (`ctx.spillFiles`) and replaces the model-facing
* result with a bounded head/tail preview plus the spill path — the model reads
* the complete result later with the existing `read` tool.
* session-scoped spill artifact (`ctx.spillStore`) and replaces the
* model-facing result with a bounded head/tail preview plus the backend's
* locator and retrieval guidance.
*
* It registers NO service and owns NO storage or preview mechanics: preview is
* `@deepseek-ai/dsh-retention` (`TextRetainer`), storage is `ctx.spillFiles`.
* `@deepseek-ai/dsh-retention` (`TextRetainer`), storage is `ctx.spillStore`.
* The policy only decides WHEN to spill and composes the notice.
*
* ## Deliberately narrow
@@ -16,8 +16,8 @@
* - Plain-text results only: a result carrying any non-text block is left
* untouched (the policy knows only the final formatted text, not tool
* internals).
* - `read` is skipped to avoid a `read → spill file → read again` loop.
* - Best-effort: no session owner, no `ctx.spillFiles` backend, or a save
* - `read` is skipped to avoid a `read → spill → read again` loop.
* - Best-effort: no session owner, no `ctx.spillStore` backend, or a save
* failure ⇒ log and return the original result. A spill failure must NEVER
* turn a successful tool call into an `isError` or hide the inline result.
*
@@ -34,7 +34,7 @@ import z from 'schemastery'
import type { ContentBlock } from '@deepseek-ai/dsh-llm'
import { TextRetainer, describeOmitted } from '@deepseek-ai/dsh-retention'
import type { Omitted } from '@deepseek-ai/dsh-retention'
import type { SaveTextSpill } from '@deepseek-ai/dsh-spill'
import type { SaveTextSpill, SpillRef } from '@deepseek-ai/dsh-spill'
import type { SessionId } from '@deepseek-ai/dsh-session'
import type { PostToolDecision, ToolExecution } from '@deepseek-ai/dsh-tools'
import type { SpillPolicyExec } from './types.ts'
@@ -86,10 +86,10 @@ function preview(text: string, budget: number): { text: string; omitted: Omitted
return { text: kept.text, omitted: kept.omittedBytes }
}
/** The spill-notice line for a given omission + path (no preview, no leading blank line). */
function spillNotice(omitted: Omitted, spillPath: string): string {
/** The spill-notice line for a given omission + saved reference (no preview, no leading blank line). */
function spillNotice(omitted: Omitted, ref: SpillRef): string {
const omission = describeOmitted(omitted, 'bytes')
return `(${omission} Full formatted result saved to: ${spillPath}. Use read with offset/limit to inspect it.)`
return `(${omission} Full formatted result stored at: ${ref.locator}. ${ref.retrievalHint})`
}
export function apply(ctx: Context, config: Config): void {
@@ -108,7 +108,7 @@ export function apply(ctx: Context, config: Config): void {
// we bound whatever it accepted. A block passes through — spill only shapes
// accepted plain-text results, never corrective feedback.
const decision = await next()
// Skip `read` to avoid a read → spill file → read again loop.
// Skip `read` to avoid a read → spill → read again loop.
if (decision.kind !== 'accept' || exec.name === 'read') return decision
const content = decision.content ?? result.content
@@ -122,9 +122,9 @@ export function apply(ctx: Context, config: Config): void {
ctx.logger.warn(`spill-policy: no session owner for ${exec.name} result; keeping the inline result`)
return decision
}
const spillFiles = ctx.get('spillFiles')
if (!spillFiles) {
ctx.logger.warn('spill-policy: no ctx.spillFiles backend loaded; keeping the inline result')
const spillStore = ctx.get('spillStore')
if (!spillStore) {
ctx.logger.warn('spill-policy: no ctx.spillStore backend loaded; keeping the inline result')
return decision
}
@@ -134,9 +134,9 @@ export function apply(ctx: Context, config: Config): void {
suggestedName: `${exec.name}.txt`,
content: text,
}
let path: string
let ref: SpillRef
try {
({ path } = await spillFiles.saveText(save))
ref = await spillStore.saveText(save)
} catch (error: unknown) {
// Best-effort: a storage failure (permissions, ENOSPC, backend down) must
// never fail the call or hide the result — keep the original inline.
@@ -152,10 +152,10 @@ export function apply(ctx: Context, config: Config): void {
// count (the full byte total): its digit count bounds the real count's, so
// the reserved size is a safe upper bound and the final notice is never
// longer than what we reserved. `\n\n` is the 2-byte join.
const reserve = Buffer.byteLength(spillNotice({ kind: 'exact', count: totalBytes }, path), 'utf8') + 2
const reserve = Buffer.byteLength(spillNotice({ kind: 'exact', count: totalBytes }, ref), 'utf8') + 2
const previewBudget = Math.max(0, maxInlineBytes - reserve)
const { text: previewText, omitted } = preview(text, previewBudget)
const notice = spillNotice(omitted, path)
const notice = spillNotice(omitted, ref)
const replacedText = previewText.length > 0 ? `${previewText}\n\n${notice}` : notice
// Invariant: the policy NEVER emits a replacement larger than the cap. When
// the notice alone exceeds maxInlineBytes (a tiny cap or a long spill root),

2
packages/spill/spill-policy/src/types.ts
View File

@@ -1,6 +1,6 @@
/**
* Vocabulary for the spill-policy plugin: the minimal structural view of a tool
* execution the policy needs to derive the owning session for a spill file.
* execution the policy needs to derive the owning session for a spill artifact.
*
* `@deepseek-ai/dsh-tools`' `ToolExecution` satisfies this shape, so the policy
* reads `exec` straight through without importing `dsh-tools` or `dsh-agent`.

32
packages/spill/spill-policy/tests/spill-policy.spec.ts
View File

@@ -2,7 +2,7 @@
* Tests for the spill-policy PLUGIN. It registers no service, only the
* `tools/post-execute` transformer. We drive real tools through
* `ctx.tools.execute(...)` and assert: disabled mode is a true no-op, an
* oversized plain-text result is spilled and replaced with a preview + path,
* oversized plain-text result is spilled and replaced with a preview + locator,
* a small result and a non-text result pass through, `read` is skipped, and a
* `saveText` failure / missing backend / missing owner all preserve the original
* result without an `isError`.
@@ -17,19 +17,23 @@ import { SessionId } from '@deepseek-ai/dsh-session'
import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
import ToolRegistry, { defineTool } from '@deepseek-ai/dsh-tools'
import type { ToolExecution } from '@deepseek-ai/dsh-tools'
import { SpillFiles, SpillPath } from '@deepseek-ai/dsh-spill'
import { SpillLocator, SpillStore } from '@deepseek-ai/dsh-spill'
import type { SaveTextSpill, SpillRef } from '@deepseek-ai/dsh-spill'
import * as SpillPolicy from '@deepseek-ai/dsh-spill-policy'
/** A stub spill backend recording its saves; `fail` exercises the best-effort fallback. */
class StubSpill extends SpillFiles {
class StubStore extends SpillStore {
saves: SaveTextSpill[] = []
fail = false
async saveText(input: SaveTextSpill): Promise<SpillRef> {
if (this.fail) throw new Error('disk full')
this.saves.push(input)
return { path: SpillPath(`/spill/${input.suggestedName}`), bytes: Buffer.byteLength(input.content, 'utf8') }
return {
locator: SpillLocator(`/spill/${input.suggestedName}`),
bytes: Buffer.byteLength(input.content, 'utf8'),
retrievalHint: 'Use the stub retrieval path.',
}
}
}
@@ -54,14 +58,14 @@ function exec(name: string, session = 's1'): ToolExecution {
* Build a context with tools + the policy, and optionally a spill backend.
* Returns the context and the backend handle (undefined when `withSpill` false).
*/
async function setup(config: SpillPolicy.Config, withSpill = true): Promise<{ ctx: Context; spill?: StubSpill; fiber: Awaited<ReturnType<Context['plugin']>> }> {
async function setup(config: SpillPolicy.Config, withSpill = true): Promise<{ ctx: Context; spill?: StubStore; fiber: Awaited<ReturnType<Context['plugin']>> }> {
const ctx = new Context()
await ctx.plugin(SystemPrompt)
await ctx.plugin(ToolRegistry)
let spill: StubSpill | undefined
let spill: StubStore | undefined
if (withSpill) {
await ctx.plugin(StubSpill)
spill = ctx.spillFiles as StubSpill
await ctx.plugin(StubStore)
spill = ctx.spillStore as StubStore
}
const fiber = await ctx.plugin(SpillPolicy, config)
return { ctx, fiber, ...spill ? { spill } : {} }
@@ -108,7 +112,7 @@ describe('config validation', () => {
})
describe('oversized plain-text replacement', () => {
it('spills the full text and replaces the result with a preview + path within the cap', async () => {
it('spills the full text and replaces the result with a preview + locator within the cap', async () => {
const { ctx, spill } = await setup({ maxInlineBytes: 200 })
const body = 'HEAD'.repeat(200) + 'TAIL'.repeat(200) // 1600 bytes > 200
ctx.tools.register(textTool('big', body))
@@ -124,8 +128,8 @@ describe('oversized plain-text replacement', () => {
const text = textOf(result.content)
expect(text).not.toBe(body)
expect(text.startsWith('HEAD')).toBe(true)
expect(text).toContain('Full formatted result saved to: /spill/big.txt')
expect(text).toContain('Use read with offset/limit')
expect(text).toContain('Full formatted result stored at: /spill/big.txt')
expect(text).toContain('Use the stub retrieval path.')
expect(text).toContain('Omitted')
// The replacement (preview + blank line + notice) stays within the cap and
// is smaller than the original — the whole point of spilling.
@@ -221,7 +225,7 @@ describe('composition', () => {
ctx.tools.register(textTool('small', 'tiny'))
const result = await ctx.tools.execute(exec('small'))
expect(spill?.saves[0]?.content).toBe('z'.repeat(500))
expect(textOf(result.content)).toContain('Full formatted result saved to')
expect(textOf(result.content)).toContain('Full formatted result stored at')
})
it('preserves a downstream accept decision additionalContext when spilling', async () => {
@@ -231,7 +235,7 @@ describe('composition', () => {
({ kind: 'accept', additionalContext: context }))
ctx.tools.register(textTool('big', 'x'.repeat(1000)))
const result = await ctx.tools.execute(exec('big'))
expect(textOf(result.content)).toContain('Full formatted result saved to')
expect(textOf(result.content)).toContain('Full formatted result stored at')
expect(result.additionalContext).toEqual(context)
})
})
@@ -259,7 +263,7 @@ describe('disposal (HMR safety)', () => {
// Live: the listener spills and replaces.
const before = await ctx.tools.execute(exec('big'))
expect(textOf(before.content)).toContain('Full formatted result saved to')
expect(textOf(before.content)).toContain('Full formatted result stored at')
expect(spill?.saves).toHaveLength(1)
// After disposal the listener is gone — the result passes through untouched

12
packages/spill/spill/README.md
View File

@@ -1,6 +1,6 @@
# @deepseek-ai/dsh-spill
The **spill storage seam**: an abstract `SpillFiles` service (`ctx.spillFiles`) defining WHAT a spill backend does — persist a tool's oversized text to a session-scoped path the model can later `read` — without saying HOW.
The **spill storage seam**: an abstract `SpillStore` service (`ctx.spillStore`) defining WHAT a spill backend does — persist a tool's oversized text and return a model-facing locator plus retrieval guidance — without saying HOW.
This package is one third of the spill capability, split so each concern evolves (and swaps) independently:
@@ -10,18 +10,18 @@ This package is one third of the spill capability, split so each concern evolves
| `@deepseek-ai/dsh-spill-local` | an implementation: private session-scoped files on the host filesystem |
| `@deepseek-ai/dsh-spill-policy` | the tool-result policy that spills oversized final results |
The split mirrors the bash/fs seams. A future remote or virtual backend (e.g. a `spill://…` URI plus a read-only bridge for ACP or remote environments) implements this interface without touching the policy plugin.
The split mirrors the bash/fs seams. A future remote or virtual backend (e.g. a `spill://…` URI, a database key, or a backend-specific retrieval tool) implements this interface without touching the policy plugin.
## Service API (`ctx.spillFiles`)
## Service API (`ctx.spillStore`)
| Member | Semantics |
|---|---|
| `saveText(input)` | Persist `input.content` verbatim to a session-scoped file; resolves with a `SpillRef` (path readable by the local `read` tool + exact bytes written). **Rejects on a real storage failure** (permissions, ENOSPC, backend unavailable) — the caller decides how to degrade. |
| `saveText(input)` | Persist `input.content` verbatim; resolves with a `SpillRef` (opaque locator, exact bytes written, and retrieval hint). **Rejects on a real storage failure** (permissions, ENOSPC, backend unavailable) — the caller decides how to degrade. |
Storage is scoped by the request's `owner` session; the backend chooses a private (not world-readable) location and a collision-free name derived from — never equal to — the caller's `suggestedName`. The seam owns storage only: NO retention policy (that is [`@deepseek-ai/dsh-retention`](../../util/retention)), NO tool-result replacement (that is `@deepseek-ai/dsh-spill-policy`), NO file inspection (the model uses the existing `read` tool on the returned path).
Storage is scoped by the request's `owner` session; the backend chooses its own private representation and may derive names from — never trust as a path — the caller's `suggestedName`. The seam owns storage only: NO retention policy (that is [`@deepseek-ai/dsh-retention`](../../util/retention)), NO tool-result replacement (that is `@deepseek-ai/dsh-spill-policy`), NO retrieval/search API (the backend's `retrievalHint` tells the model what to do with the locator).
## Vocabulary
`SaveTextSpill` (owner, source, suggestedName, content) is the request; `SpillRef` (path, bytes) is the result. `SpillPath` is [branded](../../util/brand) and rendered to the model as an ordinary path string in v1 — the brand records provenance (a runtime artifact, not a workspace file) so a future virtual backend can swap the path shape without a consumer change. `SpillOwner` scopes storage to a `SessionId`; unlike the bash executor's decoupled `OwnerToken`, spill is inherently session-scoped, so the seam imports `dsh-session`'s `SessionId` directly. `SpillSource` (toolName, callId, label) is descriptive provenance for the filename and future cleanup, not access control. See `src/types.ts` for the full contracts.
`SaveTextSpill` (owner, source, suggestedName, content) is the request; `SpillRef` (locator, bytes, retrievalHint) is the result. `SpillLocator` is [branded](../../util/brand) and rendered to the model as an opaque string — a local path for `dsh-spill-local`, but a future backend may return a URI, key, or command token without changing policy/tool consumers. `SpillOwner` scopes storage to a `SessionId`; unlike the bash executor's decoupled `OwnerToken`, spill is inherently session-scoped, so the seam imports `dsh-session`'s `SessionId` directly. `SpillSource` (toolName, callId, label) is descriptive provenance for backend naming and future cleanup, not access control. See `src/types.ts` for the full contracts.
See the [tool output spill RFC](../../../docs/rfc/implemented/architecture/2026-07-08-tool-output-spill-files.md) for the design rationale, including why creation belongs to the runtime spill seam rather than the model-facing `write` tool.

2
packages/spill/spill/package.json
View File

@@ -1,6 +1,6 @@
{
"name": "@deepseek-ai/dsh-spill",
"description": "Abstract spill storage seam (ctx.spillFiles) for the DeepSeek Harness — save oversized tool text to a session-scoped path",
"description": "Abstract spill storage seam (ctx.spillStore) for the DeepSeek Harness — save oversized tool text and return a retrieval locator",
"version": "0.0.1",
"private": true,
"type": "module",

36
packages/spill/spill/src/index.ts
View File

@@ -1,16 +1,15 @@
/**
* The spill storage seam (`ctx.spillFiles`): an abstract service defining WHAT a
* spill backend does — persist a tool's oversized text to a session-scoped path
* the model can later `read` — without saying HOW. Implementations subclass
* {@link SpillFiles} and register as the `spillFiles` service;
* The spill storage seam (`ctx.spillStore`): an abstract service defining WHAT a
* spill backend does — persist a tool's oversized text and return a model-facing
* locator plus retrieval guidance — without saying HOW. Implementations
* subclass {@link SpillStore} and register as the `spillStore` service;
* `@deepseek-ai/dsh-spill-local` (host filesystem) is the first.
*
* The seam is deliberately minimal: `saveText` and nothing else. It owns NO
* retention policy (that is `@deepseek-ai/dsh-retention`), NO tool-result
* replacement (that is `@deepseek-ai/dsh-spill-policy`), and NO file inspection
* (the model uses the existing `read` tool on the returned path). A future
* remote/virtual backend may return a `spill://…` URI plus a read-only bridge;
* v1 keeps the path filesystem-shaped until such a backend exists.
* replacement (that is `@deepseek-ai/dsh-spill-policy`), and NO retrieval or
* search API. The backend supplies the locator and retrieval hint appropriate
* for its storage substrate.
*
* @module @deepseek-ai/dsh-spill
*/
@@ -18,24 +17,24 @@
import { Context, Service } from 'cordis'
import type { SaveTextSpill, SpillRef } from './types.ts'
export { SpillPath } from './types.ts'
export { SpillLocator } from './types.ts'
export type { SaveTextSpill, SpillOwner, SpillRef, SpillSource } from './types.ts'
declare module 'cordis' {
interface Context {
spillFiles: SpillFiles
spillStore: SpillStore
}
}
/**
* Abstract spill storage service. Subclass, implement {@link saveText}, and load
* the subclass as a plugin — it registers as `ctx.spillFiles` (one
* the subclass as a plugin — it registers as `ctx.spillStore` (one
* implementation per context; loading a second throws, cordis' standard
* duplicate-service behavior).
*
* Semantics every implementation must honor:
* - {@link saveText} persists the FULL `content` verbatim and returns a path
* the local `read` tool can open, plus the exact byte length written.
* - {@link saveText} persists the FULL `content` verbatim and returns an opaque
* locator, exact byte length, and model-facing retrieval guidance.
* - Storage is scoped by the request's {@link SaveTextSpill.owner} session; the
* backend chooses a private (not world-readable) location and a collision-free
* name derived from — never equal to — the caller's `suggestedName`.
@@ -43,18 +42,17 @@ declare module 'cordis' {
* unavailable); the caller decides how to degrade (the spill policy treats a
* rejection as best-effort and keeps the inline result).
*/
export abstract class SpillFiles extends Service {
export abstract class SpillStore extends Service {
constructor(ctx: Context) {
super(ctx, 'spillFiles')
super(ctx, 'spillStore')
}
/**
* Persist `input.content` to a session-scoped spill file.
* Persist `input.content` to a session-scoped spill artifact.
* @param input - the owner, provenance, suggested name, and full text to save.
* @returns the saved file's {@link SpillRef} (path + bytes written); rejects on
* a storage failure.
* @returns the saved artifact's {@link SpillRef}; rejects on a storage failure.
*/
abstract saveText(input: SaveTextSpill): Promise<SpillRef>
}
export default SpillFiles
export default SpillStore

27
packages/spill/spill/src/types.ts
View File

@@ -11,22 +11,20 @@ import type { CallId } from '@deepseek-ai/dsh-llm'
import type { SessionId } from '@deepseek-ai/dsh-session'
/**
* A local filesystem path produced by the spill seam, intended for the model's
* `read` tool. The brand records that the path came from {@link SpillFiles.saveText}
* (a runtime artifact, not a workspace file); it is still rendered to the model
* as an ordinary path string in v1. A future remote/virtual backend may replace
* this with a `spill://…` URI, so consumers treat it as opaque.
* Opaque model-facing handle for one spilled artifact. A local backend may use a
* filesystem path; a remote or database backend may use a URI or key. Consumers
* render it with {@link SpillRef.retrievalHint}, but do not parse it.
*/
export type SpillPath = Branded<'SpillPath'>
export type SpillLocator = Branded<'SpillLocator'>
/**
* Brand a string as a {@link SpillPath}.
* Brand a string as a {@link SpillLocator}.
*
* @param path The backend-produced path string to brand.
* @returns The branded spill path.
* @param locator The backend-produced locator string to brand.
* @returns The branded spill locator.
*/
export function SpillPath(path: string): SpillPath {
return path as SpillPath
export function SpillLocator(locator: string): SpillLocator {
return locator as SpillLocator
}
/**
@@ -53,7 +51,7 @@ export interface SpillSource {
label: string
}
/** One request to persist text to a spill file. */
/** One request to persist text to a spill artifact. */
export interface SaveTextSpill {
owner: SpillOwner
source: SpillSource
@@ -66,8 +64,9 @@ export interface SaveTextSpill {
content: string
}
/** A saved spill file: its path plus the byte length written. */
/** A saved spill artifact: its locator, byte length, and backend-specific retrieval guidance. */
export interface SpillRef {
path: SpillPath
locator: SpillLocator
bytes: number
retrievalHint: string
}

32
packages/spill/spill/tests/service.spec.ts
View File

@@ -1,6 +1,6 @@
/**
* Tests for the spill seam INTERFACE: a minimal concrete subclass registers as
* `ctx.spillFiles`, a second load throws (duplicate service), and disposal
* `ctx.spillStore`, a second load throws (duplicate service), and disposal
* releases the service. The storage behavior is the implementation's concern
* (`@deepseek-ai/dsh-spill-local`); here we only pin the seam contract.
*/
@@ -9,16 +9,20 @@ import { describe, expect, it } from 'vitest'
import { Context } from 'cordis'
import { CallId } from '@deepseek-ai/dsh-llm'
import { SessionId } from '@deepseek-ai/dsh-session'
import { SpillFiles, SpillPath } from '@deepseek-ai/dsh-spill'
import { SpillLocator, SpillStore } from '@deepseek-ai/dsh-spill'
import type { SaveTextSpill, SpillRef } from '@deepseek-ai/dsh-spill'
/** Minimal concrete backend: records the last request, returns a fixed ref. */
class StubSpill extends SpillFiles {
class StubStore extends SpillStore {
last: SaveTextSpill | undefined
async saveText(input: SaveTextSpill): Promise<SpillRef> {
this.last = input
return { path: SpillPath(`/stub/${input.suggestedName}`), bytes: Buffer.byteLength(input.content, 'utf8') }
return {
locator: SpillLocator(`/stub/${input.suggestedName}`),
bytes: Buffer.byteLength(input.content, 'utf8'),
retrievalHint: 'Use the stub reader.',
}
}
}
@@ -32,25 +36,25 @@ function request(content: string): SaveTextSpill {
}
describe('spill seam', () => {
it('registers as ctx.spillFiles and saves text', async () => {
it('registers as ctx.spillStore and saves text', async () => {
const ctx = new Context()
await ctx.plugin(StubSpill)
const ref = await ctx.spillFiles.saveText(request('hello'))
expect(ref).toEqual({ path: '/stub/web_fetch.txt', bytes: 5 })
expect((ctx.spillFiles as StubSpill).last?.content).toBe('hello')
await ctx.plugin(StubStore)
const ref = await ctx.spillStore.saveText(request('hello'))
expect(ref).toEqual({ locator: '/stub/web_fetch.txt', bytes: 5, retrievalHint: 'Use the stub reader.' })
expect((ctx.spillStore as StubStore).last?.content).toBe('hello')
})
it('rejects a second implementation (one per context)', async () => {
const ctx = new Context()
await ctx.plugin(StubSpill)
await expect(ctx.plugin(StubSpill)).rejects.toThrow()
await ctx.plugin(StubStore)
await expect(ctx.plugin(StubStore)).rejects.toThrow()
})
it('releases the service on disposal', async () => {
const ctx = new Context()
const fiber = await ctx.plugin(StubSpill)
expect(ctx.spillFiles).toBeInstanceOf(StubSpill)
const fiber = await ctx.plugin(StubStore)
expect(ctx.spillStore).toBeInstanceOf(StubStore)
await fiber.dispose()
expect((ctx as Context & { spillFiles?: unknown }).spillFiles).toBeUndefined()
expect((ctx as Context & { spillStore?: unknown }).spillStore).toBeUndefined()
})
})