@deepseek-ai/dsh-spill-local 0.0.1-rc.1

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, DeepSeek
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/spill/spill-local/README.md
+README.md: 2270a65d9270e1549a9e48d6a36b821e48c29070
+README.zh.md: 907a2b5c98f3ee07e0b896b8827e6a00fa1827df

package/README.md

@@ -0,0 +1,34 @@
+# @deepseek-ai/dsh-spill-local
+
+English | [中文](README.zh.md)
+
+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
+
+Files land at `<root>/session-<hash>/​<random>-<safeName>`:
+
+- **`root`** — the config `root` (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 short `sha256(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's `suggestedName` sanitized to one safe path segment (traversal-proof; mirrors the JSONL persistence backend's `encodeSegment`). 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](../../../.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md) 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 `SpillStore` backend whose locator and retrieval hint are meaningful there.

package/README.zh.md

@@ -0,0 +1,34 @@
+# @deepseek-ai/dsh-spill-local
+
+[English](README.md) | 中文
+
+[`@deepseek-ai/dsh-spill`](../spill) 存储 seam 的**本地文件系统**实现。它注册为 `ctx.spillStore`，将工具产生的过大文本持久化到私有的会话级文件；定位信息是文件路径，取回指引会告诉模型对该路径使用 `read` 或 `grep`。
+
+## 存储布局
+
+文件存放在 `<root>/session-<hash>/​<random>-<safeName>`：
+
+- **`root`**：使用配置中的 `root`（解析为绝对路径）；如果省略，则在操作系统临时目录下延迟创建每进程私有（0700）目录。可预测且任何用户均可读取的根目录会让其他本地用户读取 spill 工具输出，或在其中预置符号链接。
+- **`session-<hash>`**：截短的 `sha256(sessionId)` 前缀，用于将同一会话的 spill 文件归在一起，以便未来的清理操作可按会话删除。
+- **`<random>-<safeName>`**：不可预测的十六进制前缀（防止在共享根目录中预置符号链接），加上经过清理的调用方 `suggestedName`，使其成为单个安全路径段（防路径遍历；与 JSONL 持久化后端的 `encodeSegment` 一致）。写入操作采用排他方式，且权限仅限所有者（`open(path, 'wx', 0o600)`）：如果路径已经存在，无论是否为符号链接，操作都会失败，因此预置的目标无法重定向写入。
+
+## 配置
+
+| 键 | 默认值 | 含义 |
+|---|---|---|
+| `root` | 私有 0700 临时目录 | spill 文件的根目录。设置后可将这些文件保存在已知位置。 |
+
+`saveText` 在发生真实存储故障（权限、ENOSPC）时返回拒绝；spill 策略会按尽力而为原则处理该拒绝，并保留内联结果。词汇见 seam README，设计见[工具输出 spill Agent Note](../../../.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md)。
+
+## 模型体验
+
+通过渲染本地路径以及 `read`/`grep` 取回指引的 spill 消费方间接影响模型。
+
+#### KV Cache 影响
+
+不会直接导致 KV Cache 失效；请求前缀变更由上述消费方负责。
+
+## 已知限制与暂缓事项
+
+- **本地 spill 文件会持续存在，直到外部清理为止**：该后端不提供会话生命周期删除或按时间保留的策略，因为已持久化、已恢复和 fork 后的会话可能仍在引用某个路径。
+- **定位信息需要与其位于同一文件系统的消费方**：远程或虚拟部署需要另一个 `SpillStore` 后端，其定位信息和取回指引在该环境中有明确含义。

package/lib/index.js

@@ -0,0 +1,138 @@
+import { join, resolve } from "node:path";
+import z from "@deepseek-ai/schemastery";
+import { SpillLocator, SpillStore } from "@deepseek-ai/dsh-spill";
+import { createHash, randomBytes } from "node:crypto";
+import { mkdtempSync } from "node:fs";
+import { mkdir, open } from "node:fs/promises";
+import { tmpdir } from "node:os";
+//#region lib/types/store.js
+/**
+* Cordis-free storage mechanics for the local spill backend: private
+* session-scoped directory selection, safe-name derivation, path-traversal
+* protection, and the exclusive owner-only write. Kept out of the service class
+* (like `dsh-bash-local`'s `run.ts`) so the filesystem behavior is unit-testable
+* without a `ctx` and without the OS temp dir.
+*
+* @module @deepseek-ai/dsh-spill-local/store
+*/
+let defaultRoot;
+/**
+* The default spill root: a private (0700) per-process directory under the OS
+* tmpdir, created lazily. Predictable world-readable paths would let other
+* local users read spilled tool output or pre-create symlinks; `mkdtemp` gives
+* an unpredictable suffix and 0700 semantics.
+*
+* @returns The lazily-created private spill root.
+*/
+function privateRoot() {
+	defaultRoot ??= mkdtempSync(join(tmpdir(), "dsh-spill-"));
+	return defaultRoot;
+}
+/**
+* Encode an arbitrary string as one safe path segment, injectively over ALL JS
+* (UTF-16) strings. A session id / suggested name is untrusted input, so this
+* neutralizes `../`, absolute paths, NUL, and separators before any filesystem
+* use. Each code unit is kept literal (`[A-Za-z0-9._-]`, minus `~`) or escaped
+* as `~XXXX`; `~` is itself escaped, so the mapping is reversible and distinct
+* inputs never collide. The whole-segment tokens `.`/`..` are escaped so they
+* can never traverse. An empty string encodes to `~` (never an empty segment).
+* (Mirrors the JSONL persistence backend's `encodeSegment`.)
+*
+* @param raw The untrusted string to encode as one safe path segment.
+* @returns An injective, filesystem-safe single path segment.
+*/
+function encodeSegment(raw) {
+	if (raw.length === 0) return "~";
+	if (raw === ".") return "~002E";
+	if (raw === "..") return "~002E~002E";
+	let out = "";
+	for (let i = 0; i < raw.length; i++) {
+		const code = raw.charCodeAt(i);
+		const ch = String.fromCharCode(code);
+		if (ch !== "~" && /^[A-Za-z0-9._-]$/.test(ch)) out += ch;
+		else out += "~" + code.toString(16).toUpperCase().padStart(4, "0");
+	}
+	return out;
+}
+/**
+* The session-scoped directory: `<root>/session-<hash(sessionId)>`, a short stable hash.
+*
+* @param root The spill root directory.
+* @param sessionId The owning session id to hash into a stable directory name.
+* @returns The absolute session-scoped spill directory path.
+*/
+function sessionDir(root, sessionId) {
+	return join(root, `session-${createHash("sha256").update(sessionId).digest("hex").slice(0, 12)}`);
+}
+/**
+* Write `content` to a fresh file under the session-scoped directory and return
+* its path + byte length. The filename is a random hex prefix plus the
+* sanitized `suggestedName`, so it is unpredictable (defeats symlink planting in
+* a shared root) AND stays readable. The open is exclusive + owner-only
+* (`'wx', 0o600`): it fails on any existing path — symlink or not — so a
+* pre-planted target cannot redirect the write.
+*
+* @param options The resolved root and request fields required to save the file.
+* @returns The written file path and UTF-8 byte length.
+*/
+async function saveTextFile(options) {
+	const dir = sessionDir(options.root, options.sessionId);
+	await mkdir(dir, {
+		recursive: true,
+		mode: 448
+	});
+	const safeName = encodeSegment(options.suggestedName);
+	const path = join(dir, `${randomBytes(6).toString("hex")}-${safeName}`);
+	const bytes = Buffer.byteLength(options.content, "utf8");
+	const handle = await open(path, "wx", 384);
+	try {
+		await handle.writeFile(options.content);
+	} finally {
+		await handle.close();
+	}
+	return {
+		path,
+		bytes
+	};
+}
+//#endregion
+//#region lib/types/index.js
+/**
+* `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 locator plus local
+* read/grep retrieval guidance.
+*
+* @module @deepseek-ai/dsh-spill-local
+*/
+/**
+* Local-filesystem spill backend. Files land under `<root>/session-<hash>/…`
+* with unpredictable names, an exclusive owner-only (0600) write, and a private
+* (0700) root — a spilled tool result must not be readable by other local users
+* or redirectable via a planted symlink.
+*/
+var LocalSpillStore = class extends SpillStore {
+	static Config = z.object({ root: z.string() });
+	/** Resolved absolute spill root (config `root`, else the private default), fixed at construction. */
+	root;
+	constructor(ctx, config) {
+		super(ctx);
+		this.root = config.root !== void 0 ? resolve(config.root) : privateRoot();
+	}
+	async saveText(input) {
+		const saved = await saveTextFile({
+			root: this.root,
+			sessionId: input.owner.sessionId,
+			suggestedName: input.suggestedName,
+			content: input.content
+		});
+		return {
+			locator: SpillLocator(saved.path),
+			bytes: saved.bytes,
+			retrievalHint: "Use read with offset/limit, or grep this path to search within it."
+		};
+	}
+};
+//#endregion
+export { LocalSpillStore, LocalSpillStore as default, encodeSegment, privateRoot, saveTextFile, sessionDir };

package/lib/invariant.js

@@ -0,0 +1,23 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@deepseek-ai/dsh-spill-local`.
+* @module @deepseek-ai/dsh-spill-local/invariant
+*/
+const PACKAGE_NAME = "@deepseek-ai/dsh-spill-local";
+/** Cordis companion plugin name. */
+const name = "spill-local-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: this package exposes no independent event sequence or mutable data relation
+* beyond contracts enforced at its owning seam.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,39 @@
+/**
+ * `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 locator plus local
+ * read/grep retrieval guidance.
+ *
+ * @module @deepseek-ai/dsh-spill-local
+ */
+import { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import { SpillStore } from '@deepseek-ai/dsh-spill';
+import type { SaveTextSpill, SpillRef } from '@deepseek-ai/dsh-spill';
+export { encodeSegment, privateRoot, saveTextFile, sessionDir } from './store.ts';
+export type { SavedText, SaveTextOptions } from './store.ts';
+/** Plugin config (all optional — `static Config` supplies the defaults). */
+export interface Config {
+    /**
+     * Root directory for spill files. Omitted uses a lazily-created private
+     * (0700) per-process directory under the OS temp dir — the safe default for
+     * a local deployment. Set it to keep spill files under a known location.
+     */
+    root?: string;
+}
+/**
+ * Local-filesystem spill backend. Files land under `<root>/session-<hash>/…`
+ * with unpredictable names, an exclusive owner-only (0600) write, and a private
+ * (0700) root — a spilled tool result must not be readable by other local users
+ * or redirectable via a planted symlink.
+ */
+export declare class LocalSpillStore extends SpillStore {
+    static Config: z<Config>;
+    /** Resolved absolute spill root (config `root`, else the private default), fixed at construction. */
+    readonly root: string;
+    constructor(ctx: Context, config: Config);
+    saveText(input: SaveTextSpill): Promise<SpillRef>;
+}
+export default LocalSpillStore;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-spill-local`.
+ * @module @deepseek-ai/dsh-spill-local/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "spill-local-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/store.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Cordis-free storage mechanics for the local spill backend: private
+ * session-scoped directory selection, safe-name derivation, path-traversal
+ * protection, and the exclusive owner-only write. Kept out of the service class
+ * (like `dsh-bash-local`'s `run.ts`) so the filesystem behavior is unit-testable
+ * without a `ctx` and without the OS temp dir.
+ *
+ * @module @deepseek-ai/dsh-spill-local/store
+ */
+/**
+ * The default spill root: a private (0700) per-process directory under the OS
+ * tmpdir, created lazily. Predictable world-readable paths would let other
+ * local users read spilled tool output or pre-create symlinks; `mkdtemp` gives
+ * an unpredictable suffix and 0700 semantics.
+ *
+ * @returns The lazily-created private spill root.
+ */
+export declare function privateRoot(): string;
+/**
+ * Encode an arbitrary string as one safe path segment, injectively over ALL JS
+ * (UTF-16) strings. A session id / suggested name is untrusted input, so this
+ * neutralizes `../`, absolute paths, NUL, and separators before any filesystem
+ * use. Each code unit is kept literal (`[A-Za-z0-9._-]`, minus `~`) or escaped
+ * as `~XXXX`; `~` is itself escaped, so the mapping is reversible and distinct
+ * inputs never collide. The whole-segment tokens `.`/`..` are escaped so they
+ * can never traverse. An empty string encodes to `~` (never an empty segment).
+ * (Mirrors the JSONL persistence backend's `encodeSegment`.)
+ *
+ * @param raw The untrusted string to encode as one safe path segment.
+ * @returns An injective, filesystem-safe single path segment.
+ */
+export declare function encodeSegment(raw: string): string;
+/**
+ * The session-scoped directory: `<root>/session-<hash(sessionId)>`, a short stable hash.
+ *
+ * @param root The spill root directory.
+ * @param sessionId The owning session id to hash into a stable directory name.
+ * @returns The absolute session-scoped spill directory path.
+ */
+export declare function sessionDir(root: string, sessionId: string): string;
+/** Options for {@link saveTextFile} — the resolved root and the request fields the store needs. */
+export interface SaveTextOptions {
+    /** The spill root directory (configured or the lazy private default). */
+    root: string;
+    /** The owning session id (scopes the directory). */
+    sessionId: string;
+    /** Caller-suggested base name; sanitized to one safe segment before use. */
+    suggestedName: string;
+    /** The full text to persist. */
+    content: string;
+}
+/** A written spill file. */
+export interface SavedText {
+    path: string;
+    bytes: number;
+}
+/**
+ * Write `content` to a fresh file under the session-scoped directory and return
+ * its path + byte length. The filename is a random hex prefix plus the
+ * sanitized `suggestedName`, so it is unpredictable (defeats symlink planting in
+ * a shared root) AND stays readable. The open is exclusive + owner-only
+ * (`'wx', 0o600`): it fails on any existing path — symlink or not — so a
+ * pre-planted target cannot redirect the write.
+ *
+ * @param options The resolved root and request fields required to save the file.
+ * @returns The written file path and UTF-8 byte length.
+ */
+export declare function saveTextFile(options: SaveTextOptions): Promise<SavedText>;
+//# sourceMappingURL=store.d.ts.map

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@deepseek-ai/dsh-spill-local",
+  "description": "Local-filesystem implementation of the DeepSeek Harness spill storage seam (private session-scoped files)",
+  "version": "0.0.1-rc.1",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/spill/spill-local"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-spill": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.1-rc.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-brand": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-session": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-spill": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+  }
+}