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

docs(spill): clarify forked spill namespace

Browse Source
This commit is contained in:
Dudu-0223
2026-07-14 10:40:53 +08:00
parent 3fba88e873
commit 6c57e6036d
4 changed files with 12 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -18,10 +18,10 @@ The split mirrors the bash/fs seams. A future remote or virtual backend (e.g. a
|---|---|
| `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 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).
Storage is grouped by the request's `owner` session as a save-time namespace; 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` (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.
`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.sessionId` is the save-time storage namespace: forked sessions inherit existing locators from the seeded log without copying or re-owning them, and new spills after the fork use the child session id. `SpillSource` (toolName, callId, label) is descriptive provenance for backend naming and inspection, 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.

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

@@ -28,10 +28,11 @@ export function SpillLocator(locator: string): SpillLocator {
}
/**
* Who a spilled file belongs to: the session whose tool call produced it. The
* backend scopes storage per session (its directory layout, its cleanup unit),
* so the owner is the session id, not a decoupled token — spill is inherently
* session-scoped, unlike the bash executor's cross-session `OwnerToken`.
* Save-time storage namespace for a spilled artifact. The session id lets a
* backend group storage under the producing session, but the returned
* {@link SpillLocator} is the model-facing handle. Forked sessions inherit
* locators already present in the seeded log; those artifacts are not copied or
* re-owned, and spills produced after the fork use the child session id.
*/
export interface SpillOwner {
sessionId: SessionId
@@ -39,8 +40,8 @@ export interface SpillOwner {
/**
* Provenance of one spilled artifact — recorded by the backend for a readable
* filename and future cleanup/inspection. Not interpreted for access control
* (the {@link SpillOwner} scopes storage); purely descriptive.
* filename and inspection. Not interpreted for access control; purely
* descriptive.
*/
export interface SpillSource {
/** The tool whose result was spilled (e.g. `web_fetch`). */