@deepseek-ai/dsh-spill-policy 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-policy/README.md
+README.md: 7638f62c0426964d83d7a635ebf73d0f117abd78
+README.zh.md: f3bb66d7a65edb6f4d2f2a0e86d0d83bb1a262ab

package/README.md

@@ -0,0 +1,58 @@
+# @deepseek-ai/dsh-spill-policy
+
+English | [中文](README.zh.md)
+
+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.spillStore`. It only decides WHEN to spill and composes the notice.
+
+## Config
+
+| Key | Default | Meaning |
+|---|---|---|
+| `maxInlineBytes` | *(omitted)* | Model-facing context cap for a plain-text result, in UTF-8 bytes (a non-negative integer; validated at load). **Omitted disables the policy entirely** (the plugin registers nothing). When set, a larger result is spilled and replaced with a preview derived from the same budget (head/tail split). |
+
+## Behavior
+
+1. Let the tool run (delegates via `next()`, so it bounds whatever a downstream hook accepted).
+2. Skip nested executions (`exec.parent` is present — their DURABLE copy is bounded by the dispatch-log arm below), accepted value replacements (the registry must revalidate and rerender them), `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:
+
+   ```text
+   <retained head/tail preview>
+
+   (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 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.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. A successful replacement changes only `content`; the canonical programmatic value is preserved.
+
+**The dispatch-log arm:** a second listener on `tools/code-dispatch-log` applies the same cap, replacement pipeline, and best-effort fallbacks to the DURABLE copy of each `run_code` sub-call result (artifact label `dispatch`, keyed by the sub-call id). The program's value is untouched — it already crossed the worker boundary whole — and `read` sub-calls are bounded too: a log copy is not model context, so the read-again loop cannot occur, and `read` is precisely the tool that produces huge logs ([rationale](../../../.agents/notes/implemented/feature/2026-07-26-code-dispatch-log-spill.md)).
+
+## Scope
+
+The policy sees only the FINAL formatted surface result—not a tool's internal resource or canonical value. 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. `glob`/`grep` own item-level surface spill because their complete acquired values still exist before rendering; bash streams own acquisition-time spill. The generic policy prepends its waterfall listener, then delegates, so ordinary tool-owned asynchronous projections complete before generic byte bounding regardless of plugin load order. See the [tool output spill Agent Note](../../../.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md).
+
+## Model Experience
+
+### Oversized plain-text result
+
+#### What the model sees
+
+Results at or below `maxInlineBytes`, nested results, `read` results, blocked decisions, and results containing non-text blocks are unchanged. An oversized plain-text surface result becomes a bounded head/tail preview followed by `(Omitted <bytes> bytes. Full formatted result stored at: <locator>. <retrievalHint>)`; storage or ownership failures leave the original result visible.
+
+#### Token effect
+
+A successful replacement is at most `maxInlineBytes` UTF-8 bytes and remains in history until compaction; the full spill text is not resent to the model.
+
+#### KV Cache effect
+
+Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.
+
+## Known Limitations and Deferred Work
+
+- **Only final plain-text results are spillable** — mixed-content results, blocked feedback, and `read` pass through; provider truncation or tool-owned retention that happened earlier cannot be recovered here.
+- **A notice that cannot fit disables replacement for that call** — a tiny cap or long locator leaves the oversized original inline after the backend has already saved an unreferenced spill.

package/README.zh.md

@@ -0,0 +1,58 @@
+# @deepseek-ai/dsh-spill-policy
+
+[English](README.md) | 中文
+
+**工具结果 spill 策略**：一个 `tools/post-execute` 转换器，用于防止过大的纯文本工具结果进入模型上下文。当最终结果超过 `maxInlineBytes` 时，它会通过 [`ctx.spillStore`](../spill) 保存完整文本，并将面向模型的结果替换为有界的首尾预览、后端定位信息与取回指引。
+
+该插件**不注册任何服务**，也不负责存储或预览机制：预览由 [`@deepseek-ai/dsh-retention`](../../util/retention)（`TextRetainer`）负责，存储由 `ctx.spillStore` 负责。它只决定何时 spill，并组合通知。
+
+## 配置
+
+| 键 | 默认值 | 含义 |
+|---|---|---|
+| `maxInlineBytes` | *（省略）* | 面向模型的纯文本结果上下文上限，以 UTF-8 字节数计（在加载时验证为非负整数）。**省略时完全禁用该策略**（插件不注册任何内容）。设置后，超过该上限的结果会被 spill，并替换为从同一预算派生的预览（首尾拆分）。 |
+
+## 行为
+
+1. 允许工具运行（通过 `next()` 委托，因此可以限制任何下游钩子接受的结果）。
+2. 跳过嵌套执行（存在 `exec.parent`——其持久化副本由下方的 dispatch-log 分支设界）、已接受的值替换（注册表必须重新验证并重新渲染它们）、`read`（避免 `read → spill → read again` 循环）以及任何非 `accept` 决策（`block` 的纠正反馈会原样通过）。
+3. 仅在已接受的内容为**纯文本**（全部都是 `text` 块）时才将其展平；包含任何非文本块的结果都保持不变。
+4. 如果 UTF-8 大小为 `≤ maxInlineBytes`，则保持不变。
+5. 否则，保存完整文本，并将结果替换为预览和以下通知。系统会调整大小，使整个替换内容（预览、空行和通知）不超过 `maxInlineBytes`：先从预算中保留通知所需字节，再缩小预览以适配剩余空间，因此面向模型的结果绝不会超过上限：
+
+   ```text
+   <retained head/tail preview>
+
+   (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.)
+   ```
+
+   当通知本身已占满预算时（上限极小或定位信息很长），预览为空，只返回通知。如果仅通知的替换内容仍会超过 `maxInlineBytes`，策略将保留内联结果；它绝不会发出超过上限的替换内容（而且上限内的替换内容总比原结果更小，因此这也意味着 spill 绝不会增加字节数）。
+
+**尽力而为**：没有会话所有者、没有 `ctx.spillStore` 后端，或 `saveText` 返回拒绝 ⇒ 策略记录警告并返回原始结果。spill 失败绝不会将成功调用变为 `isError`，也不会隐藏内联结果。成功替换时只会更改 `content`；规范的程序化值保持不变。
+
+**dispatch-log 分支：**注册在 `tools/code-dispatch-log` 上的第二个监听器，把同一套上限、替换流水线与尽力而为的回退应用到每个 `run_code` 子调用结果的持久化副本上（产物标签为 `dispatch`，按子调用 id 归档）。程序的值不受影响，因为它早已完整跨过 worker 边界；`read` 子调用同样设界：日志副本不是模型上下文，因此不会发生 read-again 循环，而 `read` 恰恰是最容易产生巨型日志的工具（[原理](../../../.agents/notes/implemented/feature/2026-07-26-code-dispatch-log-spill.md)）。
+
+## 范围
+
+该策略只能看到最终格式化的呈现结果，看不到工具的内部资源或规范值。如果提供方已经截断内容（例如 `web-fetch-local.maxBodyChars`），spill 产物保存的是工具返回的完整格式化结果，而非完整原始源。提供方／资源上限仍然是必需的，并且与该策略相互独立。`glob`/`grep` 负责对项级呈现结果执行 spill，因为渲染前仍然存在完整的已获取值；bash 流负责在获取时 spill。通用策略预先注册自己的 waterfall（瀑布式事件）监听器，然后再委托，因此无论插件加载顺序如何，普通工具自身的异步投影都会在通用字节限制之前完成。详见[工具输出 spill Agent Note](../../../.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md)。
+
+## 模型体验
+
+### 过大的纯文本结果
+
+#### 模型看到的内容
+
+大小不超过 `maxInlineBytes` 的结果、嵌套结果、`read` 结果、被阻止的决策和包含非文本块的结果都保持不变。过大的纯文本呈现结果会变为有界的首尾预览，后面附加 `(Omitted <bytes> bytes. Full formatted result stored at: <locator>. <retrievalHint>)`；存储失败或没有会话所有者时，原始结果仍然可见。
+
+#### Token 影响
+
+成功替换后的内容最多为 `maxInlineBytes` 个 UTF-8 字节，并会保留在历史中直到压缩（compaction）；完整 spill 文本不会重新发送给模型。
+
+#### KV Cache 影响
+
+仅追加；新可见内容位于可重用请求前缀之后，不会使现有 KV Cache 条目失效。
+
+## 已知限制与暂缓事项
+
+- **只能对最终纯文本结果执行 spill**：混合内容结果、阻止反馈和 `read` 会原样通过；无法在此恢复先前已经发生的提供方截断或工具自身执行的保留处理。
+- **通知无法容纳时，该次调用的替换功能会禁用**：当上限极小或定位信息很长时，后端已经保存了无引用的 spill，但过大的原始结果仍会保留在内联位置。

package/lib/index.js

@@ -0,0 +1,169 @@
+import z from "@deepseek-ai/schemastery";
+import { TextRetainer, describeOmitted } from "@deepseek-ai/dsh-retention";
+//#region lib/types/index.js
+/**
+* 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 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.spillStore`.
+* The policy only decides WHEN to spill and composes the notice.
+*
+* A second arm applies the SAME cap to the durable log: the
+* `tools/code-dispatch-log` waterfall bounds the `tool/code-dispatch` event's
+* copy of an oversized `run_code` sub-call result (the program's value is
+* untouched; UIs and replay read the full text through the spill artifact).
+*
+* ## Deliberately narrow
+*
+* - Omitted `maxInlineBytes` ⇒ the plugin registers nothing (a true no-op).
+* - 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).
+* - Nested composite calls skip the MODEL-facing arm; their durable log copy
+*   is bounded by the dispatch-log arm instead.
+* - Accepted value replacements pass through for registry revalidation and
+*   rendering; this presentation policy cannot also replace content in the
+*   same mutually exclusive decision.
+* - `read` is skipped by the model-facing arm to avoid a
+*   `read → spill → read again` loop; the dispatch-log arm bounds `read`
+*   sub-calls too (a log copy is not model context, and `read` is precisely
+*   the tool that produces huge logs).
+* - 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.
+*
+* It COMPOSES with other post-execute listeners: its prepended listener
+* delegates via `next()` and bounds the resulting content projection, so
+* tool-owned asynchronous projection runs before generic bounding, a hook that
+* replaced content still has its replacement bounded, and value replacements
+* and `block` decisions pass through unchanged.
+*
+* @module @deepseek-ai/dsh-spill-policy
+*/
+/** Cordis plugin name used by loader diagnostics. */
+const name = "spill-policy";
+/** Require the tool registry (its `tools/post-execute` waterfall is the extension point we transform). */
+const inject = ["tools"];
+const Config = z.object({ maxInlineBytes: z.number() });
+/** All-text content flattened to one UTF-8 string, or `undefined` if any block is non-text. */
+function flattenPlainText(content) {
+	let text = "";
+	for (const block of content) {
+		if (block.type !== "text") return void 0;
+		text += block.text;
+	}
+	return text;
+}
+/** The owning session id, or `undefined` for a call with no agent (a direct/test call). */
+function ownerSessionId(exec) {
+	return exec.agent?.session.header.id;
+}
+/** Build the bounded head/tail preview for `text`, splitting `budget` bytes across the two ends. */
+function preview(text, budget) {
+	const retainer = new TextRetainer({
+		kind: "headTail",
+		headBytes: Math.ceil(budget / 2),
+		tailBytes: Math.floor(budget / 2)
+	});
+	retainer.push(text);
+	const kept = retainer.finish();
+	return {
+		text: kept.text,
+		omitted: kept.omittedBytes
+	};
+}
+/** The spill-notice line for a given omission + saved reference (no preview, no leading blank line). */
+function spillNotice(omitted, ref) {
+	return `(${describeOmitted(omitted, "bytes")} Full formatted result stored at: ${ref.locator}. ${ref.retrievalHint})`;
+}
+function apply(ctx, config) {
+	const maxInlineBytes = config.maxInlineBytes;
+	if (maxInlineBytes === void 0) return;
+	if (!Number.isInteger(maxInlineBytes) || maxInlineBytes < 0) throw new Error(`spill-policy: maxInlineBytes must be a non-negative integer (got ${maxInlineBytes})`);
+	const cap = maxInlineBytes;
+	/**
+	* Spill `text` and build the bounded replacement (preview + notice), or
+	* return `undefined` when the policy must keep the original (no session
+	* owner, no backend, storage failure, or no within-cap replacement).
+	* Shared verbatim by the model-facing post-execute arm and the durable
+	* dispatch-log arm so both produce byte-identical projections.
+	*/
+	async function spillReplacement(text, totalBytes, sessionId, toolName, callId, label) {
+		if (sessionId === void 0) {
+			ctx.logger.warn(`spill-policy: no session owner for ${toolName} ${label}; keeping the inline content`);
+			return;
+		}
+		const spillStore = ctx.get("spillStore");
+		if (!spillStore) {
+			ctx.logger.warn("spill-policy: no ctx.spillStore backend loaded; keeping the inline content");
+			return;
+		}
+		const save = {
+			owner: { sessionId },
+			source: {
+				toolName,
+				callId,
+				label
+			},
+			suggestedName: `${toolName}.txt`,
+			content: text
+		};
+		let ref;
+		try {
+			ref = await spillStore.saveText(save);
+		} catch (error) {
+			ctx.logger.warn(`spill-policy: saveText failed for ${toolName}: ${String(error)}; keeping the inline content`);
+			return;
+		}
+		const reserve = Buffer.byteLength(spillNotice({
+			kind: "exact",
+			count: totalBytes
+		}, ref), "utf8") + 2;
+		const { text: previewText, omitted } = preview(text, Math.max(0, cap - reserve));
+		const notice = spillNotice(omitted, ref);
+		const replacedText = previewText.length > 0 ? `${previewText}\n\n${notice}` : notice;
+		if (Buffer.byteLength(replacedText, "utf8") > cap) {
+			ctx.logger.warn(`spill-policy: spill notice for ${toolName} exceeds maxInlineBytes; keeping the inline content`);
+			return;
+		}
+		return replacedText;
+	}
+	ctx.on("tools/post-execute", async (exec, result, next) => {
+		const decision = await next();
+		if (decision.kind !== "accept" || Object.hasOwn(decision, "value") || exec.parent !== void 0 || exec.name === "read") return decision;
+		const text = flattenPlainText(decision.content ?? result.content);
+		if (text === void 0) return decision;
+		const totalBytes = Buffer.byteLength(text, "utf8");
+		if (totalBytes <= maxInlineBytes) return decision;
+		const replacedText = await spillReplacement(text, totalBytes, ownerSessionId(exec), exec.name, exec.callId, "result");
+		if (replacedText === void 0) return decision;
+		return {
+			kind: "accept",
+			content: [{
+				type: "text",
+				text: replacedText
+			}],
+			...decision.additionalContexts ? { additionalContexts: decision.additionalContexts } : {}
+		};
+	}, { prepend: true });
+	ctx.on("tools/code-dispatch-log", async (dispatch, next) => {
+		const content = await next();
+		const text = flattenPlainText(content);
+		if (text === void 0) return content;
+		const totalBytes = Buffer.byteLength(text, "utf8");
+		if (totalBytes <= maxInlineBytes) return content;
+		const replacedText = await spillReplacement(text, totalBytes, ownerSessionId(dispatch.exec), dispatch.name, dispatch.subCallId, "dispatch");
+		if (replacedText === void 0) return content;
+		return [{
+			type: "text",
+			text: replacedText
+		}];
+	}, { prepend: true });
+}
+//#endregion
+export { Config, apply, inject, name };

package/lib/invariant.js

@@ -0,0 +1,23 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@deepseek-ai/dsh-spill-policy`.
+* @module @deepseek-ai/dsh-spill-policy/invariant
+*/
+const PACKAGE_NAME = "@deepseek-ai/dsh-spill-policy";
+/** Cordis companion plugin name. */
+const name = "spill-policy-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,63 @@
+/**
+ * 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 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.spillStore`.
+ * The policy only decides WHEN to spill and composes the notice.
+ *
+ * A second arm applies the SAME cap to the durable log: the
+ * `tools/code-dispatch-log` waterfall bounds the `tool/code-dispatch` event's
+ * copy of an oversized `run_code` sub-call result (the program's value is
+ * untouched; UIs and replay read the full text through the spill artifact).
+ *
+ * ## Deliberately narrow
+ *
+ * - Omitted `maxInlineBytes` ⇒ the plugin registers nothing (a true no-op).
+ * - 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).
+ * - Nested composite calls skip the MODEL-facing arm; their durable log copy
+ *   is bounded by the dispatch-log arm instead.
+ * - Accepted value replacements pass through for registry revalidation and
+ *   rendering; this presentation policy cannot also replace content in the
+ *   same mutually exclusive decision.
+ * - `read` is skipped by the model-facing arm to avoid a
+ *   `read → spill → read again` loop; the dispatch-log arm bounds `read`
+ *   sub-calls too (a log copy is not model context, and `read` is precisely
+ *   the tool that produces huge logs).
+ * - 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.
+ *
+ * It COMPOSES with other post-execute listeners: its prepended listener
+ * delegates via `next()` and bounds the resulting content projection, so
+ * tool-owned asynchronous projection runs before generic bounding, a hook that
+ * replaced content still has its replacement bounded, and value replacements
+ * and `block` decisions pass through unchanged.
+ *
+ * @module @deepseek-ai/dsh-spill-policy
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+export type { SpillPolicyExec } from './types.ts';
+/** Plugin config. */
+export interface Config {
+    /**
+     * The model-facing context cap for a plain-text tool result, in UTF-8 bytes.
+     * Omitted disables the policy entirely (no-op). When set, a result larger than
+     * this is spilled and replaced with a preview derived from this same budget.
+     */
+    maxInlineBytes?: number;
+}
+/** Cordis plugin name used by loader diagnostics. */
+export declare const name = "spill-policy";
+/** Require the tool registry (its `tools/post-execute` waterfall is the extension point we transform). */
+export declare const inject: string[];
+export declare const Config: z<Config>;
+export declare function apply(ctx: Context, config: Config): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-spill-policy`.
+ * @module @deepseek-ai/dsh-spill-policy/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "spill-policy-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/types.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 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 artifact.
+ *
+ * `@deepseek-ai/dsh-tools`' `ToolExecution` satisfies this shape, so the policy
+ * reads `exec` straight through without importing `dsh-tools` or `dsh-agent`.
+ * Only the session HEADER id is read — the same identity every other subsystem
+ * keys off (see `dsh-tool-bash`'s owner derivation).
+ *
+ * @module @deepseek-ai/dsh-spill-policy/types
+ */
+import type { SessionId } from '@deepseek-ai/dsh-session';
+/** Minimal structural view of a tool execution: the owning session's header id, when present. */
+export interface SpillPolicyExec {
+    /** The agent on whose behalf the call runs, when there is one. */
+    agent?: {
+        session: {
+            header: {
+                /** The canonical session identity — the spill owner. */
+                id: SessionId;
+            };
+        };
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@deepseek-ai/dsh-spill-policy",
+  "description": "Tool-result spill policy for the DeepSeek Harness — replaces oversized plain-text tool results with a retained preview plus a spill-file path (no service surface)",
+  "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-policy"
+  },
+  "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-llm": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-retention": "^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/dsh-tools": "^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-agent": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-code-runtime-worker": "^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-retention": "^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/dsh-tools": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+  }
+}