@qlzt/dsh-spill-policy 0.0.0-stage → 0.2.1-alpha.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.i18n.yaml

@@ -0,0 +1,82 @@
+# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/spill/spill-policy/README.md
+/:
+  en: 07748986630e8da3
+  zh: 4ff004a12b883fdf
+/deepseek-ai-dsh-spill-policy:
+  en: e3d75c128bb2f4b9
+  zh: 15daa9f8f3efaabd
+/deepseek-ai-dsh-spill-policy/summary:
+  en: 225c013f0f230c37
+  zh: 30634801496c205f
+/deepseek-ai-dsh-spill-policy/table-of-contents:
+  en: d152484eb41ac6b4
+  zh: 09388d293f9be9cb
+/deepseek-ai-dsh-spill-policy/use-this-package:
+  en: 52e3b36ee5b98e7f
+  zh: 98380821aa7cde9d
+/deepseek-ai-dsh-spill-policy/use-this-package/minimal-configuration:
+  en: a5d85ae7f7962b9e
+  zh: 73c44a9413c3c8cf
+/deepseek-ai-dsh-spill-policy/use-this-package/what-the-model-sees:
+  en: 7cb5bba705975712
+  zh: 26adbdee1252d2bb
+/deepseek-ai-dsh-spill-policy/use-this-package/which-results-are-affected:
+  en: c419117e6b5f84f8
+  zh: 1a43afb623346603
+/deepseek-ai-dsh-spill-policy/use-this-package/best-effort-failure-behavior:
+  en: b4d94d99a8a9e52f
+  zh: d5cec6295cbf5ef6
+/deepseek-ai-dsh-spill-policy/use-this-package/the-durable-log-copy:
+  en: b72e6e88ada5a957
+  zh: 5c6167651618738a
+/deepseek-ai-dsh-spill-policy/understand-the-implementation:
+  en: bb7cedc768113c0e
+  zh: ca05828dfe63b233
+/deepseek-ai-dsh-spill-policy/understand-the-implementation/design-philosophy:
+  en: a8e0d6d0651401c0
+  zh: 0e159fc19caf9300
+/deepseek-ai-dsh-spill-policy/understand-the-implementation/the-two-arms:
+  en: a9233181feb1afb4
+  zh: e54f1498a0dea843
+/deepseek-ai-dsh-spill-policy/understand-the-implementation/shared-notice-ownership:
+  en: 916aa902ea376c42
+  zh: 51fbf25c1f1560d7
+/deepseek-ai-dsh-spill-policy/understand-the-implementation/source-map:
+  en: 355ca3b01de5233e
+  zh: 19a7c28a57171573
+/deepseek-ai-dsh-spill-policy/understand-the-implementation/failure-modes:
+  en: 5640d59fdf0e064f
+  zh: 7f92c52a1bdf5bff
+/deepseek-ai-dsh-spill-policy/further-exploration:
+  en: 2b5860d2cc9a6523
+  zh: 006157ad7bc92891
+/deepseek-ai-dsh-spill-policy/model-experience:
+  en: 215e7ba838619b7b
+  zh: a311da3843709f90
+/deepseek-ai-dsh-spill-policy/model-experience/oversized-text-and-image-results:
+  en: 99c96010474af9cf
+  zh: 9a25fa709f21a494
+/deepseek-ai-dsh-spill-policy/model-experience/oversized-text-and-image-results/what-the-model-sees:
+  en: a701c098db84aff5
+  zh: 2b04abc792def1a2
+/deepseek-ai-dsh-spill-policy/model-experience/oversized-text-and-image-results/token-effect:
+  en: 02ec4218006ecb65
+  zh: 62f1d481ebf0c665
+/deepseek-ai-dsh-spill-policy/model-experience/oversized-text-and-image-results/kv-cache-effect:
+  en: f5d5f97a153f7c70
+  zh: bee82b41983a66a0
+/deepseek-ai-dsh-spill-policy/known-limitations-and-deferred-work:
+  en: bd38d2abae4cb4e6
+  zh: 29acb530988ee2bd
+/deepseek-ai-dsh-spill-policy/known-limitations-and-deferred-work/dev-note:
+  en: a63e51f03bdb279f
+  zh: 191a48d3bfc4a792
+/deepseek-ai-dsh-spill-policy/known-limitations-and-deferred-work/dev-note/future-per-tool-configuration:
+  en: 7e6c4300e87f3f07
+  zh: 7b97be5218905ecc
+/deepseek-ai-dsh-spill-policy/known-limitations-and-deferred-work/dev-note/future-earlier-spill:
+  en: dbb9f9fe93996893
+  zh: d9d3c1a46ea67595

package/README.md

@@ -1,3 +1,166 @@
-# Temporary Holding Version
+---
+description: "Tool-result retention with a shared text/image token budget and readable recovery files."
+kind: "package-reference"
+---
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @deepseek-ai/dsh-spill-policy
+
+English | [中文](README.zh.md)
+
+## Summary
+
+Keep oversized text and image results within a shared estimated token budget. The model receives ordered head/tail content and a path to the complete result. Images remain in attachment storage; the result file records their readable paths. Omitting `maxInlineTokens` disables retention, and recovery failures leave the original content visible.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+Mount the policy alongside a spill backend. Text and images share the configured budget after post-execute policy accepts the result.
+
+### Minimal configuration
+
+Load a spill backend and set `maxInlineTokens` in estimated tokens:
+
+```yaml
+- name: '@deepseek-ai/dsh-spill-local'
+- name: '@deepseek-ai/dsh-spill-policy'
+  config:
+    maxInlineTokens: 12500
+```
+
+| Field | Default | Meaning |
+|---|---|---|
+| `maxInlineTokens` | omitted | Estimated token cap for retained text, images, image descriptions, and notices; omission disables retention |
+
+The generated [configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-spill-policy) is the exhaustive source for every accepted field. A negative or fractional cap fails plugin load rather than corrupting per-call behavior.
+
+### What the model sees
+
+Oversized results keep their original order. Each end receives half the budget remaining after omission notices; text may be split, while each image is retained or omitted whole. Images inside the omitted interval are omitted too. A successful replacement stays within the configured token estimate:
+
+```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.)
+```
+
+The notice also reports omitted image counts. A notice-only result is allowed when no preview fits; if the notice itself exceeds the cap, the original content stays visible. The full result file keeps all accepted text and an attachment path at each image position, so the model can use `read` and then `read_image`. Attachment bytes are not copied into this file. Local attachment objects persist independently of spill cleanup.
+
+### Which results are affected
+
+The policy accepts text/image sequences. Results within budget, `read`, blocked decisions, value replacements, and other block types pass through. Text-only nested results are bounded only in their log copies. Provider or tool limits applied before this policy cannot be recovered here.
+
+### Best-effort failure behavior
+
+A missing owner or spill backend, failed storage, missing route image pricing, or unavailable execution-world image path logs a warning and keeps the original content. The policy never substitutes an unreadable path for an image.
+
+### The durable log copy
+
+PTC programs receive complete canonical values. Image-bearing sub-results are bounded before forwarding to the model; when every image is omitted, the model still receives the retained text and recovery notice. The dispatch log uses the same retained content. Text-only sub-call logs, including `read`, are bounded asynchronously without delaying program values.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+This section explains the design decisions behind the policy; the observable behavior is fully covered in [Use this package](#use-this-package).
+
+### Design philosophy
+
+The pure retention function selects ordered content by cost; the plugin owns policy, recovery text, and storage calls. Text uses the existing token-meter estimate. Images use the active route's `imageRequestPricing`, including descriptor text. DeepSeek routes reuse the provider's image-dimension calculator. The budget is an estimate, not an exact tokenizer guarantee.
+
+### The two arms
+
+The prepended `tools/post-execute` listener delegates before bounding accepted content. `tools/ptc-dispatch-log` shares the same helper. MCP's `projectContent` installs real image blocks before these policies; later content replacement, value replacement, or blocking remains authoritative.
+
+<a id="shared-notice-ownership"></a>
+### Shared notice ownership
+
+The browser-safe `./notice` entry owns `formatSpillNotice(omitted, ref, images)` and `hasSpillNotice(text)`. It recognizes both historical byte-only notices and notices with whole-image counts without changing recorded text.
+
+### Source map
+
+| File | Role |
+|---|---|
+| [`src/index.ts`](src/index.ts) | Plugin entry: `Config` validation, the two waterfall listeners, the shared replacement helper |
+| [`src/notice.ts`](src/notice.ts) | Browser-safe notice formatting and recognition, published as `./notice` |
+| [`src/retention.ts`](src/retention.ts) | Pure ordered text/image head-tail retention |
+
+### Failure modes
+
+Recovery or pricing failures preserve the input and log the reason. Negative, fractional, or unsafe-integer budgets fail at plugin load. Results containing unsupported block types remain unchanged.
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+Read these pages when the package-level contract is not enough.
+
+- [Spill storage service](../spill/README.md) — the `saveText` contract behind the policy's replacement.
+- [dsh-spill-local](../spill-local/README.md) — the local backend that stores the spilled text.
+- [Token meter](../../llm/token-meter/README.md) — shared text estimates and route image accounting.
+- [Tool output spill decision](../../../.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md) — the capability boundary and design rationale.
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+### Oversized text and image results
+
+#### What the model sees
+
+The retained prefix and suffix keep image order, with `[...]` at the omitted interval. The final notice names omitted text bytes, optional whole-image counts, and the complete-result path. Reading that file reveals the omitted text and image addresses.
+
+#### Token effect
+
+A successful replacement fits `maxInlineTokens` under the shared text estimate and active route's image calculator, including notices and image descriptor text. Provider-reported usage remains authoritative.
+
+#### 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
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+These limits define when the policy cannot help. They are current package constraints.
+
+- **Text recognition cannot authenticate output** — a tool can print the same notice text; `hasSpillNotice` identifies a text convention, not proof that the policy saved a result.
+- **Unavailable recovery or pricing** — images require a route calculator and execution-readable attachment paths; otherwise the original content stays visible. Unsupported blocks, blocked feedback, and `read` also pass through.
+- **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.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+This Dev Note is working context for maintainers: open directions. It is explicitly non-authoritative.
+
+#### Future: per-tool configuration
+
+Per-tool opt-out or per-tool policy declarations remain deferred; the built-in `read` skip covers the known loop, and a second real tool need would justify configuration.
+
+#### Future: earlier spill
+
+The policy only sees final accepted content. Earlier provider truncation and tool-owned output limits remain outside its scope.
+
+</details>

package/README.zh.md

@@ -0,0 +1,166 @@
+---
+description: "工具结果保留：文字和图片共享 token 预算，并通过完整结果文件恢复省略内容。"
+kind: "package-reference"
+---
+
+# @deepseek-ai/dsh-spill-policy
+
+[English](README.md) | 中文
+
+## 概述
+
+将过大的文字和图片结果限制在共享的估算 token 预算内。模型收到按原顺序保留的首尾内容，以及完整结果文件的路径。图片保存在附件存储中，结果文件记录其可读取路径。省略 `maxInlineTokens` 会禁用策略，无法保存可恢复内容时保留原结果。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+将策略与 spill 后端一起挂载。执行后策略接受结果之后，文字和图片共享配置的预算。
+
+### 最小配置
+
+挂载 spill 后端，并以估算 token 数设置 `maxInlineTokens`：
+
+```yaml
+- name: '@deepseek-ai/dsh-spill-local'
+- name: '@deepseek-ai/dsh-spill-policy'
+  config:
+    maxInlineTokens: 12500
+```
+
+| 字段 | 默认值 | 含义 |
+|---|---|---|
+| `maxInlineTokens` | 省略 | 保留的文字、图片、图片说明和提示的估算 token 上限；省略时禁用策略 |
+
+生成的[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-spill-policy)是每个受支持字段的穷尽式真源。负数或小数上限会让插件加载失败，而不是破坏每次调用的行为。
+
+### 模型看到什么
+
+过大的结果保持原始顺序。扣除省略提示后，两端各使用剩余预算的一半；文字可以切分，图片整张保留或省略。省略区间中的图片也会被省略。成功替换的内容不超过配置的 token 估算预算：
+
+```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.)
+```
+
+提示也会报告省略的图片数量。预算容不下预览时允许只返回提示；连提示也超出上限时保留原内容。完整结果文件保存全部已接受文字，并在每张图片的位置记录附件路径，模型可先用 `read` 读取，再用 `read_image` 查看。图片字节不复制到这个文件中。本地附件对象的持久保存独立于 spill 文件清理。
+
+### 哪些结果会受影响
+
+策略接受文字和图片序列。预算内结果、`read`、被阻止的决策、值替换以及其他内容块类型会原样通过。纯文本嵌套结果只限制日志副本。提供方或工具在此前应用的限制无法在这里恢复。
+
+### 尽力而为的故障行为
+
+缺少归属或 spill 后端、存储失败、缺少模型图片计量或图片路径无法在执行环境读取时，策略记录警告并保留原内容。策略不会用无法读取的路径替换图片。
+
+### 持久日志副本
+
+PTC 程序收到完整的规范值。含图片的子结果在转发给模型前设定上限；全部图片被省略时，模型仍会收到保留的文字和读取提示。分发日志使用相同的保留内容。纯文本子调用的日志，包括 `read`，异步设定上限，不延迟程序获取返回值。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现细节——点击展开</summary>
+
+本节解释该策略背后的设计决策；可观察行为已在[使用本包](#use-this-package)中完整说明。
+
+### 设计理念
+
+纯保留函数按成本选择有序内容，插件负责策略、读取提示和存储调用。文字使用现有 token-meter 估算。图片使用当前模型的 `imageRequestPricing`，并计入说明文字。DeepSeek 模型复用提供方的图片尺寸计算器。预算是估算值，不保证与实际分词结果完全一致。
+
+### 两条分支
+
+以 prepend 注册的 `tools/post-execute` 监听器先委托，再限制已接受的内容。`tools/ptc-dispatch-log` 共用同一辅助函数。MCP 的 `projectContent` 在这些策略之前安装真实图片块；后续内容替换、值替换或阻止仍然生效。
+
+<a id="shared-notice-ownership"></a>
+### 共享通知的所有权
+
+浏览器安全入口 `./notice` 负责 `formatSpillNotice(omitted, ref, images)` 和 `hasSpillNotice(text)`。它识别历史的仅字节提示和包含整张图片数量的提示，不改写已有记录。
+
+### 源码地图
+
+| 文件 | 职责 |
+|---|---|
+| [`src/index.ts`](src/index.ts) | 插件入口：`Config` 校验、两个 waterfall 监听器、共享替换辅助函数 |
+| [`src/notice.ts`](src/notice.ts) | 浏览器安全的通知格式化与识别，以 `./notice` 发布 |
+| [`src/retention.ts`](src/retention.ts) | 有序图文首尾保留的纯函数 |
+
+### 故障模式
+
+无法恢复内容或计量失败时保留输入，并记录原因。负数、小数或非安全整数预算会使插件加载失败。包含不支持的内容块类型的结果保持原样。
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+当包级约定不够用时阅读以下页面。
+
+- [spill 存储服务](../spill/README.zh.md)——策略替换背后的 `saveText` 约定。
+- [dsh-spill-local](../spill-local/README.zh.md)——保存 spill 文本的本地后端。
+- [Token meter](../../llm/token-meter/README.zh.md) — 共享文字估算和模型图片计量。
+- [工具输出 spill 决策](../../../.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.zh.md)——能力边界与设计依据。
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+### 过大的文字和图片结果
+
+#### 模型看到什么
+
+保留的前缀和后缀维持图片顺序，并在省略区间显示 `[...]`。末尾提示说明省略的文字字节数、整张图片数量及完整结果路径。读取该文件可以找到省略的文字和图片地址。
+
+#### Token 影响
+
+成功替换的结果在共享文字估算和当前模型图片计算器下不超过 `maxInlineTokens`，包括提示和图片说明文字。实际用量以提供方报告为准。
+
+#### KV Cache 影响
+
+仅追加；新可见内容位于可重用请求前缀之后，不会使现有 KV Cache 条目失效。
+
+## 已知限制与延期工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+这些限制说明策略在哪些情况下无法提供帮助。它们是当前的包约束。
+
+- **文本识别无法认证输出来源**——工具也能打印相同的通知文本；`hasSpillNotice` 识别的是文本约定，不能证明策略保存过结果。
+- **无法恢复或计量**：图片要求模型计算器和执行环境可读取的附件路径，否则保留原内容。不支持的内容块、被阻止的反馈和 `read` 也会原样通过。
+- **通知无法容纳时会禁用该次调用的替换**——上限极小或定位信息很长时，后端已经保存了无引用的 spill，但过大的原始结果仍留在内联位置。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者的工作上下文——点击展开</summary>
+
+本开发备注是维护者的工作上下文：开放方向。它明确不具权威性。
+
+#### 未来：逐工具配置
+
+逐工具选择退出或逐工具策略声明仍然延期；内置的 `read` 跳过已覆盖已知循环，第二个真实工具需求才能证明配置的合理性。
+
+#### 未来：更早的 spill
+
+策略只处理最终已接受的内容。此前的提供方截断和工具自身的输出限制仍由各自负责。
+
+</details>

package/lib/index.js

@@ -0,0 +1,262 @@
+import z from "@deepseek-ai/schemastery";
+import { createUserMessage, resolveImageAttachmentAccess } from "@qlzt/dsh-llm";
+import { estimateContent } from "@qlzt/dsh-token-meter/estimate";
+import { describeOmitted } from "@qlzt/dsh-output-retention";
+//#region lib/types/notice.js
+/** Browser-safe formatting and recognition of persisted spill-policy notices. */
+const OPEN = "(";
+const CLOSE = ")";
+const LOCATION = " Full formatted result stored at: ";
+const GUIDANCE_SEPARATOR = ". ";
+const EXACT_OMISSION = describeOmitted({
+	kind: "exact",
+	count: 0
+}, "bytes");
+const COUNT_OFFSET = EXACT_OMISSION.indexOf("0");
+EXACT_OMISSION.slice(COUNT_OFFSET + 1);
+/**
+* Format the notice appended to a retained preview, preserving its persisted spelling.
+* @param omitted - bytes omitted by the retention policy.
+* @param ref - saved text locator and retrieval guidance.
+* @param images - number of whole images omitted alongside text.
+* @returns the complete notice without a leading preview separator.
+*/
+function formatSpillNotice(omitted, ref, images = 0) {
+	const imageNotice = images > 0 ? ` Omitted ${images} images.` : "";
+	return `${OPEN}${describeOmitted(omitted, "bytes")}${imageNotice}${LOCATION}${ref.locator}${GUIDANCE_SEPARATOR}${ref.retrievalHint}${CLOSE}`;
+}
+//#endregion
+//#region lib/types/retention.js
+/** Preserve a UTF-16 code point when a text budget cuts between its surrogates. */
+function textSlice(text, length, tail) {
+	let cut = tail ? text.length - length : length;
+	const previous = text.charCodeAt(cut - 1);
+	const current = text.charCodeAt(cut);
+	if (previous >= 55296 && previous <= 56319 && current >= 56320 && current <= 57343) cut += tail ? 1 : -1;
+	return tail ? text.slice(cut) : text.slice(0, cut);
+}
+/** Largest contiguous text end fitting a monotonic token estimate. */
+function fitText(text, budget, tail, price) {
+	let low = 0;
+	let high = text.length;
+	while (low < high) {
+		const middle = Math.ceil((low + high) / 2);
+		const candidate = textSlice(text, middle, tail);
+		if (candidate.length === 0 || price({
+			type: "text",
+			text: candidate
+		}) <= budget) low = middle;
+		else high = middle - 1;
+	}
+	return textSlice(text, low, tail);
+}
+/**
+* Retain contiguous ends without moving or partially retaining an image.
+* Each end receives half the content budget; unused space at an indivisible
+* image stays unused. Text pricing must be monotonic in retained length.
+* @param content - ordered text and image blocks whose total price exceeds budget.
+* @param budget - non-negative integer token budget after reserving notices.
+* @param price - model-route cost of one retained block, including its framing.
+* @returns retained ends and omitted UTF-8 text bytes and whole images.
+*/
+function retainContent(content, budget, price) {
+	const head = [];
+	const tail = [];
+	let first = 0;
+	let last = content.length - 1;
+	let headCharacters = 0;
+	let remaining = Math.ceil(budget / 2);
+	while (first <= last) {
+		const block = content[first];
+		const cost = price(block);
+		if (cost <= remaining) {
+			head.push(block);
+			remaining -= cost;
+			first++;
+			continue;
+		}
+		if (block.type === "text") {
+			const text = fitText(block.text, remaining, false, price);
+			headCharacters = text.length;
+			if (text.length > 0) head.push({
+				type: "text",
+				text
+			});
+		}
+		break;
+	}
+	remaining = Math.floor(budget / 2);
+	while (last >= first) {
+		const original = content[last];
+		const block = last === first && original.type === "text" ? {
+			type: "text",
+			text: original.text.slice(headCharacters)
+		} : original;
+		const cost = price(block);
+		if (cost <= remaining) {
+			tail.push(block);
+			remaining -= cost;
+			last--;
+			continue;
+		}
+		if (block.type === "text") {
+			const text = fitText(block.text, remaining, true, price);
+			if (text.length > 0) tail.push({
+				type: "text",
+				text
+			});
+		}
+		break;
+	}
+	tail.reverse();
+	const bytes = (blocks) => blocks.reduce((total, block) => total + (block.type === "text" ? Buffer.byteLength(block.text, "utf8") : 0), 0);
+	const images = (blocks) => blocks.filter((block) => block.type === "image").length;
+	return {
+		head,
+		tail,
+		omittedBytes: bytes(content) - bytes(head) - bytes(tail),
+		omittedImages: images(content) - images(head) - images(tail)
+	};
+}
+//#endregion
+//#region lib/types/index.js
+/** Cordis plugin identity. */
+const name = "spill-policy";
+/** Tools own both model-facing results and PTC dispatch logs. */
+const inject = ["tools"];
+const Config = z.object({ maxInlineTokens: z.number() });
+/** Narrow the model's ordered content without rewriting unsupported blocks. */
+function retainable(content) {
+	return content.every((block) => block.type === "text" || block.type === "image");
+}
+const GAP = {
+	type: "text",
+	text: "\n\n[...]\n\n"
+};
+/**
+* Mount token retention for accepted tool results and PTC log copies.
+* @param ctx - tool registry and optional pricing, filesystem, attachment, and spill services.
+* @param config - maximum estimated result tokens; omission disables the plugin.
+*/
+function apply(ctx, config) {
+	const cap = config.maxInlineTokens;
+	if (cap === void 0) return;
+	if (!Number.isSafeInteger(cap) || cap < 0) throw new Error(`spill-policy: maxInlineTokens must be a non-negative integer (got ${cap})`);
+	const maxTokens = cap;
+	/** Price actual request images and their accompanying descriptor text. */
+	function pricing(exec, images) {
+		const costs = /* @__PURE__ */ new Map();
+		if (images.length > 0) {
+			const routed = exec.agent?.session.requestHeader()?.config;
+			const provider = routed?.provider ?? exec.agent?.options.provider;
+			const model = routed?.model ?? exec.agent?.options.model;
+			const calculator = provider === void 0 || model === void 0 ? void 0 : ctx.get("llm")?.imageRequestPricing(provider, model);
+			if (calculator === void 0) throw new Error("the current model has no image token calculator");
+			const prices = calculator.priceImages(images);
+			if (prices.length !== images.length) throw new Error("image token calculator returned an inconsistent occurrence count");
+			for (const [index, image] of images.entries()) {
+				const cost = prices[index];
+				costs.set(image, cost.visualTokens + estimateContent([{
+					type: "text",
+					text: cost.text
+				}]));
+			}
+		}
+		return (block) => block.type === "image" ? costs.get(block) : estimateContent([block]);
+	}
+	/** Full ordered text with an execution-readable attachment path at each image position. */
+	function fullText(content) {
+		return content.map((block) => {
+			if (block.type === "text") return block.text;
+			const attachments = ctx.get("attachments");
+			const fs = ctx.get("fs");
+			const access = attachments === void 0 || fs === void 0 ? void 0 : resolveImageAttachmentAccess(attachments, (path) => fs.processPathFromHostPath(path), block.attachment);
+			if (access === void 0) throw new Error(`image ${block.attachment.attachmentId} has no readable attachment path`);
+			return `\n[Image: ${JSON.stringify(access.readonlyPath)}; ${block.attachment.mediaType}; ${block.attachment.width}x${block.attachment.height}. Use read_image to view it.]\n`;
+		}).join("");
+	}
+	/** Recoverably bound one display copy; failures leave successful tool content visible. */
+	async function bound(exec, content, toolName, callId, label) {
+		if (!retainable(content)) return void 0;
+		try {
+			const images = content.filter((block) => block.type === "image");
+			const price = pricing(exec, images);
+			if (content.reduce((total, block) => total + price(block), 0) <= maxTokens) return void 0;
+			const owner = exec.agent?.session.header.id;
+			if (owner === void 0) throw new Error(`no session owner for ${toolName} ${label}`);
+			const spillStore = ctx.get("spillStore");
+			if (spillStore === void 0) throw new Error("no ctx.spillStore backend loaded");
+			const ref = await spillStore.saveText({
+				owner: { sessionId: owner },
+				source: {
+					kind: "tool",
+					toolName,
+					callId,
+					label
+				},
+				suggestedName: `${toolName}.txt`,
+				content: fullText(content)
+			});
+			const totalBytes = content.reduce((total, block) => total + (block.type === "text" ? Buffer.byteLength(block.text, "utf8") : 0), 0);
+			const notice = (bytes, count) => ({
+				type: "text",
+				text: formatSpillNotice({
+					kind: "exact",
+					count: bytes
+				}, ref, count)
+			});
+			const worstNotice = notice(totalBytes, images.length);
+			const reserved = price(GAP) + price({
+				type: "text",
+				text: `\n\n${worstNotice.text}`
+			});
+			if (price(worstNotice) > maxTokens) throw new Error(`spill notice for ${toolName} exceeds maxInlineTokens`);
+			const retained = retainContent(content, Math.max(0, maxTokens - reserved), price);
+			const footer = notice(retained.omittedBytes, retained.omittedImages);
+			const result = retained.head.length + retained.tail.length === 0 ? [footer] : [
+				...retained.head,
+				GAP,
+				...retained.tail,
+				{
+					type: "text",
+					text: `\n\n${footer.text}`
+				}
+			];
+			const merged = [];
+			for (const block of result) {
+				const previous = merged.at(-1);
+				if (block.type === "text" && previous?.type === "text") previous.text += block.text;
+				else merged.push(block.type === "text" ? { ...block } : block);
+			}
+			return merged;
+		} catch (error) {
+			ctx.logger.warn(`spill-policy: ${String(error)}; keeping the inline content`);
+			return;
+		}
+	}
+	ctx.on("tools/post-execute", async (exec, result, next) => {
+		const decision = await next();
+		if (decision.kind !== "accept" || Object.hasOwn(decision, "value") || exec.name === "read") return decision;
+		const content = decision.content ?? result.content;
+		const hasImages = content.some((block) => block.type === "image");
+		if (exec.parent !== void 0 && !hasImages) return decision;
+		const retained = await bound(exec, content, exec.name, exec.callId, exec.parent === void 0 ? "result" : "dispatch");
+		if (retained === void 0) return decision;
+		const additionalContexts = [...decision.additionalContexts ?? []];
+		if (exec.parent !== void 0 && !result.isError && hasImages && !retained.some((block) => block.type === "image")) additionalContexts.push(createUserMessage({
+			content: retained,
+			source: { kind: "ptc-mode" }
+		}));
+		return {
+			kind: "accept",
+			content: retained,
+			...additionalContexts.length > 0 ? { additionalContexts } : {}
+		};
+	}, { prepend: true });
+	ctx.on("tools/ptc-dispatch-log", async (dispatch, next) => {
+		const content = await next();
+		return await bound(dispatch.exec, content, dispatch.name, dispatch.subCallId, "dispatch") ?? content;
+	}, { prepend: true });
+}
+//#endregion
+export { Config, apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Token-budgeted tool content with recoverable text and image addresses.
+ * Post-execute policies settle before retention; canonical program values
+ * remain intact. Missing recovery storage or image pricing keeps the original
+ * content and reports the reason through the logger.
+ * @module @qlzt/dsh-spill-policy
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+export type { SpillPolicyExec } from './types.ts';
+/** Optional result-retention budget. */
+export interface Config {
+    /** Maximum estimated tokens in a retained result, including image descriptors and omission notices. Omitted disables retention. */
+    maxInlineTokens?: number;
+}
+/** Cordis plugin identity. */
+export declare const name = "spill-policy";
+/** Tools own both model-facing results and PTC dispatch logs. */
+export declare const inject: string[];
+export declare const Config: z<Config>;
+/**
+ * Mount token retention for accepted tool results and PTC log copies.
+ * @param ctx - tool registry and optional pricing, filesystem, attachment, and spill services.
+ * @param config - maximum estimated result tokens; omission disables the plugin.
+ */
+export declare function apply(ctx: Context, config: Config): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/index.js

@@ -0,0 +1,138 @@
+import z from '@deepseek-ai/schemastery';
+import { createUserMessage, resolveImageAttachmentAccess } from '@qlzt/dsh-llm';
+import { estimateContent } from '@qlzt/dsh-token-meter/estimate';
+import { formatSpillNotice } from "./notice.js";
+import { retainContent } from "./retention.js";
+/** Cordis plugin identity. */
+export const name = 'spill-policy';
+/** Tools own both model-facing results and PTC dispatch logs. */
+export const inject = ['tools'];
+export const Config = z.object({ maxInlineTokens: z.number() });
+/** Narrow the model's ordered content without rewriting unsupported blocks. */
+function retainable(content) {
+    return content.every(block => block.type === 'text' || block.type === 'image');
+}
+const GAP = { type: 'text', text: '\n\n[...]\n\n' };
+/**
+ * Mount token retention for accepted tool results and PTC log copies.
+ * @param ctx - tool registry and optional pricing, filesystem, attachment, and spill services.
+ * @param config - maximum estimated result tokens; omission disables the plugin.
+ */
+export function apply(ctx, config) {
+    const cap = config.maxInlineTokens;
+    if (cap === undefined)
+        return;
+    if (!Number.isSafeInteger(cap) || cap < 0) {
+        throw new Error(`spill-policy: maxInlineTokens must be a non-negative integer (got ${cap})`);
+    }
+    const maxTokens = cap;
+    /** Price actual request images and their accompanying descriptor text. */
+    function pricing(exec, images) {
+        const costs = new Map();
+        if (images.length > 0) {
+            const routed = exec.agent?.session.requestHeader()?.config;
+            const provider = routed?.provider ?? exec.agent?.options.provider;
+            const model = routed?.model ?? exec.agent?.options.model;
+            const calculator = provider === undefined || model === undefined
+                ? undefined
+                : ctx.get('llm')?.imageRequestPricing(provider, model);
+            if (calculator === undefined)
+                throw new Error('the current model has no image token calculator');
+            const prices = calculator.priceImages(images);
+            if (prices.length !== images.length)
+                throw new Error('image token calculator returned an inconsistent occurrence count');
+            for (const [index, image] of images.entries()) {
+                const cost = prices[index];
+                costs.set(image, cost.visualTokens + estimateContent([{ type: 'text', text: cost.text }]));
+            }
+        }
+        return block => block.type === 'image' ? costs.get(block) : estimateContent([block]);
+    }
+    /** Full ordered text with an execution-readable attachment path at each image position. */
+    function fullText(content) {
+        return content.map((block) => {
+            if (block.type === 'text')
+                return block.text;
+            const attachments = ctx.get('attachments');
+            const fs = ctx.get('fs');
+            const access = attachments === undefined || fs === undefined ? undefined : resolveImageAttachmentAccess(attachments, path => fs.processPathFromHostPath(path), block.attachment);
+            if (access === undefined)
+                throw new Error(`image ${block.attachment.attachmentId} has no readable attachment path`);
+            return `\n[Image: ${JSON.stringify(access.readonlyPath)}; ${block.attachment.mediaType}; ${block.attachment.width}x${block.attachment.height}. Use read_image to view it.]\n`;
+        }).join('');
+    }
+    /** Recoverably bound one display copy; failures leave successful tool content visible. */
+    async function bound(exec, content, toolName, callId, label) {
+        if (!retainable(content))
+            return undefined;
+        try {
+            const images = content.filter((block) => block.type === 'image');
+            const price = pricing(exec, images);
+            if (content.reduce((total, block) => total + price(block), 0) <= maxTokens)
+                return undefined;
+            const owner = exec.agent?.session.header.id;
+            if (owner === undefined)
+                throw new Error(`no session owner for ${toolName} ${label}`);
+            const spillStore = ctx.get('spillStore');
+            if (spillStore === undefined)
+                throw new Error('no ctx.spillStore backend loaded');
+            const ref = await spillStore.saveText({
+                owner: { sessionId: owner }, source: { kind: 'tool', toolName, callId, label },
+                suggestedName: `${toolName}.txt`, content: fullText(content),
+            });
+            const totalBytes = content.reduce((total, block) => total + (block.type === 'text' ? Buffer.byteLength(block.text, 'utf8') : 0), 0);
+            const notice = (bytes, count) => ({
+                type: 'text', text: formatSpillNotice({ kind: 'exact', count: bytes }, ref, count),
+            });
+            const worstNotice = notice(totalBytes, images.length);
+            const reserved = price(GAP) + price({ type: 'text', text: `\n\n${worstNotice.text}` });
+            if (price(worstNotice) > maxTokens)
+                throw new Error(`spill notice for ${toolName} exceeds maxInlineTokens`);
+            const retained = retainContent(content, Math.max(0, maxTokens - reserved), price);
+            const footer = notice(retained.omittedBytes, retained.omittedImages);
+            const result = retained.head.length + retained.tail.length === 0
+                ? [footer]
+                : [...retained.head, GAP, ...retained.tail, { type: 'text', text: `\n\n${footer.text}` }];
+            // Adjacent text has one framing cost on the wire and in the spill preview.
+            const merged = [];
+            for (const block of result) {
+                const previous = merged.at(-1);
+                if (block.type === 'text' && previous?.type === 'text')
+                    previous.text += block.text;
+                else
+                    merged.push(block.type === 'text' ? { ...block } : block);
+            }
+            return merged;
+        }
+        catch (error) {
+            ctx.logger.warn(`spill-policy: ${String(error)}; keeping the inline content`);
+            return undefined;
+        }
+    }
+    ctx.on('tools/post-execute', async (exec, result, next) => {
+        const decision = await next();
+        if (decision.kind !== 'accept' || Object.hasOwn(decision, 'value') || exec.name === 'read')
+            return decision;
+        const content = decision.content ?? result.content;
+        const hasImages = content.some(block => block.type === 'image');
+        // Text-only PTC bindings retain their asynchronous log-only spill path.
+        if (exec.parent !== undefined && !hasImages)
+            return decision;
+        const retained = await bound(exec, content, exec.name, exec.callId, exec.parent === undefined ? 'result' : 'dispatch');
+        if (retained === undefined)
+            return decision;
+        const additionalContexts = [...decision.additionalContexts ?? []];
+        if (exec.parent !== undefined && !result.isError && hasImages && !retained.some(block => block.type === 'image')) {
+            additionalContexts.push(createUserMessage({ content: retained, source: { kind: 'ptc-mode' } }));
+        }
+        return {
+            kind: 'accept', content: retained,
+            ...additionalContexts.length > 0 ? { additionalContexts } : {},
+        };
+    }, { prepend: true });
+    ctx.on('tools/ptc-dispatch-log', async (dispatch, next) => {
+        const content = await next();
+        return await bound(dispatch.exec, content, dispatch.name, dispatch.subCallId, 'dispatch') ?? content;
+    }, { prepend: true });
+}
+//# sourceMappingURL=index.js.map

package/lib/types/notice.d.ts

@@ -0,0 +1,19 @@
+/** Browser-safe formatting and recognition of persisted spill-policy notices. */
+import { type Omitted } from '@qlzt/dsh-output-retention';
+import type { SpillRef } from '@qlzt/dsh-spill';
+/**
+ * Format the notice appended to a retained preview, preserving its persisted spelling.
+ * @param omitted - bytes omitted by the retention policy.
+ * @param ref - saved text locator and retrieval guidance.
+ * @param images - number of whole images omitted alongside text.
+ * @returns the complete notice without a leading preview separator.
+ */
+export declare function formatSpillNotice(omitted: Omitted, ref: Pick<SpillRef, 'locator' | 'retrievalHint'>, images?: number): string;
+/**
+ * Recognize a final spill-policy notice in persisted text, including notice-only output.
+ * This identifies the text convention, not authenticated tool-output origin.
+ * @param text - complete recorded text result.
+ * @returns whether a complete notice occupies the end of the result.
+ */
+export declare function hasSpillNotice(text: string): boolean;
+//# sourceMappingURL=notice.d.ts.map

package/lib/types/notice.js

@@ -0,0 +1,59 @@
+/** Browser-safe formatting and recognition of persisted spill-policy notices. */
+import { describeOmitted } from '@qlzt/dsh-output-retention';
+const OPEN = '(';
+const CLOSE = ')';
+const LOCATION = ' Full formatted result stored at: ';
+const GUIDANCE_SEPARATOR = '. ';
+const SEPARATOR = '\n\n';
+const EXACT_OMISSION = describeOmitted({ kind: 'exact', count: 0 }, 'bytes');
+const COUNT_OFFSET = EXACT_OMISSION.indexOf('0');
+const COUNT_SUFFIX = EXACT_OMISSION.slice(COUNT_OFFSET + 1);
+/**
+ * Format the notice appended to a retained preview, preserving its persisted spelling.
+ * @param omitted - bytes omitted by the retention policy.
+ * @param ref - saved text locator and retrieval guidance.
+ * @param images - number of whole images omitted alongside text.
+ * @returns the complete notice without a leading preview separator.
+ */
+export function formatSpillNotice(omitted, ref, images = 0) {
+    const imageNotice = images > 0 ? ` Omitted ${images} images.` : '';
+    return `${OPEN}${describeOmitted(omitted, 'bytes')}${imageNotice}${LOCATION}${ref.locator}${GUIDANCE_SEPARATOR}${ref.retrievalHint}${CLOSE}`;
+}
+function isOmission(text) {
+    const imageNotice = / Omitted ([1-9][0-9]*) images\.$/.exec(text);
+    if (imageNotice !== null) {
+        if (!Number.isSafeInteger(Number(imageNotice[1])))
+            return false;
+        text = text.slice(0, imageNotice.index);
+    }
+    if (text === describeOmitted({ kind: 'none' }, 'bytes')
+        || text === describeOmitted({ kind: 'unknown' }, 'bytes'))
+        return true;
+    const count = Number(text.slice(COUNT_OFFSET, text.length - COUNT_SUFFIX.length));
+    return Number.isSafeInteger(count) && count >= 0
+        && text === describeOmitted({ kind: 'exact', count }, 'bytes');
+}
+/**
+ * Recognize a final spill-policy notice in persisted text, including notice-only output.
+ * This identifies the text convention, not authenticated tool-output origin.
+ * @param text - complete recorded text result.
+ * @returns whether a complete notice occupies the end of the result.
+ */
+export function hasSpillNotice(text) {
+    if (!text.endsWith(CLOSE))
+        return false;
+    let start = 0;
+    while (true) {
+        const next = text.indexOf(`${SEPARATOR}${OPEN}`, start);
+        const candidate = text.slice(start, next < 0 ? -CLOSE.length : next);
+        const location = candidate.indexOf(LOCATION, OPEN.length);
+        if (candidate.startsWith(OPEN) && location >= 0
+            && isOmission(candidate.slice(OPEN.length, location))) {
+            return text.indexOf(GUIDANCE_SEPARATOR, start + location + LOCATION.length) >= 0;
+        }
+        if (next < 0)
+            return false;
+        start = next + SEPARATOR.length;
+    }
+}
+//# sourceMappingURL=notice.js.map

package/lib/types/retention.d.ts

@@ -0,0 +1,24 @@
+/** Ordered head/tail retention of text and indivisible images. @module @qlzt/dsh-spill-policy/retention */
+import type { ContentBlock } from '@qlzt/dsh-llm';
+/** Content whose text can be split and whose images must remain whole. */
+export type RetainableBlock = Extract<ContentBlock, {
+    type: 'text' | 'image';
+}>;
+/** Retained ends and exact quantities excluded from their original sequence. */
+export interface RetainedContent {
+    head: RetainableBlock[];
+    tail: RetainableBlock[];
+    omittedBytes: number;
+    omittedImages: number;
+}
+/**
+ * Retain contiguous ends without moving or partially retaining an image.
+ * Each end receives half the content budget; unused space at an indivisible
+ * image stays unused. Text pricing must be monotonic in retained length.
+ * @param content - ordered text and image blocks whose total price exceeds budget.
+ * @param budget - non-negative integer token budget after reserving notices.
+ * @param price - model-route cost of one retained block, including its framing.
+ * @returns retained ends and omitted UTF-8 text bytes and whole images.
+ */
+export declare function retainContent(content: readonly RetainableBlock[], budget: number, price: (block: RetainableBlock) => number): RetainedContent;
+//# sourceMappingURL=retention.d.ts.map

package/lib/types/retention.js

@@ -0,0 +1,88 @@
+/** Preserve a UTF-16 code point when a text budget cuts between its surrogates. */
+function textSlice(text, length, tail) {
+    let cut = tail ? text.length - length : length;
+    const previous = text.charCodeAt(cut - 1);
+    const current = text.charCodeAt(cut);
+    if (previous >= 0xd800 && previous <= 0xdbff && current >= 0xdc00 && current <= 0xdfff) {
+        cut += tail ? 1 : -1;
+    }
+    return tail ? text.slice(cut) : text.slice(0, cut);
+}
+/** Largest contiguous text end fitting a monotonic token estimate. */
+function fitText(text, budget, tail, price) {
+    let low = 0;
+    let high = text.length;
+    while (low < high) {
+        const middle = Math.ceil((low + high) / 2);
+        const candidate = textSlice(text, middle, tail);
+        if (candidate.length === 0 || price({ type: 'text', text: candidate }) <= budget)
+            low = middle;
+        else
+            high = middle - 1;
+    }
+    return textSlice(text, low, tail);
+}
+/**
+ * Retain contiguous ends without moving or partially retaining an image.
+ * Each end receives half the content budget; unused space at an indivisible
+ * image stays unused. Text pricing must be monotonic in retained length.
+ * @param content - ordered text and image blocks whose total price exceeds budget.
+ * @param budget - non-negative integer token budget after reserving notices.
+ * @param price - model-route cost of one retained block, including its framing.
+ * @returns retained ends and omitted UTF-8 text bytes and whole images.
+ */
+export function retainContent(content, budget, price) {
+    const head = [];
+    const tail = [];
+    let first = 0;
+    let last = content.length - 1;
+    let headCharacters = 0;
+    let remaining = Math.ceil(budget / 2);
+    while (first <= last) {
+        const block = content[first];
+        const cost = price(block);
+        if (cost <= remaining) {
+            head.push(block);
+            remaining -= cost;
+            first++;
+            continue;
+        }
+        if (block.type === 'text') {
+            const text = fitText(block.text, remaining, false, price);
+            headCharacters = text.length;
+            if (text.length > 0)
+                head.push({ type: 'text', text });
+        }
+        break;
+    }
+    remaining = Math.floor(budget / 2);
+    while (last >= first) {
+        const original = content[last];
+        const block = last === first && original.type === 'text'
+            ? { type: 'text', text: original.text.slice(headCharacters) }
+            : original;
+        const cost = price(block);
+        if (cost <= remaining) {
+            tail.push(block);
+            remaining -= cost;
+            last--;
+            continue;
+        }
+        if (block.type === 'text') {
+            const text = fitText(block.text, remaining, true, price);
+            if (text.length > 0)
+                tail.push({ type: 'text', text });
+        }
+        break;
+    }
+    tail.reverse();
+    const bytes = (blocks) => blocks.reduce((total, block) => total + (block.type === 'text' ? Buffer.byteLength(block.text, 'utf8') : 0), 0);
+    const images = (blocks) => blocks.filter(block => block.type === 'image').length;
+    return {
+        head,
+        tail,
+        omittedBytes: bytes(content) - bytes(head) - bytes(tail),
+        omittedImages: images(content) - images(head) - images(tail),
+    };
+}
+//# sourceMappingURL=retention.js.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.
+ *
+ * `@qlzt/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 @qlzt/dsh-spill-policy/types
+ */
+import type { SessionId } from '@qlzt/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/lib/types/types.js

@@ -0,0 +1,13 @@
+/**
+ * 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.
+ *
+ * `@qlzt/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 @qlzt/dsh-spill-policy/types
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/package.json

@@ -1,6 +1,75 @@
 {
   "name": "@qlzt/dsh-spill-policy",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "description": "Token-budgeted tool-result retention with recoverable text and image paths",
+  "version": "0.2.1-alpha.3",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://gitee.com/zsping1989/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"
+    },
+    "./notice": {
+      "types": "./lib/types/notice.d.ts",
+      "default": "./lib/types/notice.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@qlzt/dsh-llm": "0.2.1-alpha.3",
+    "@qlzt/dsh-output-retention": "0.2.1-alpha.3",
+    "@qlzt/dsh-session": "0.2.1-alpha.3",
+    "@qlzt/dsh-spill": "0.2.1-alpha.3",
+    "@qlzt/dsh-tools": "0.2.1-alpha.3",
+    "@deepseek-ai/cordis": "~4.0.5-alpha.1",
+    "@qlzt/dsh-attachment": "0.2.1-alpha.3",
+    "@qlzt/dsh-fs": "0.2.1-alpha.3",
+    "@qlzt/dsh-token-meter": "0.2.1-alpha.3"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "~3.18.5-alpha.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-agent": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-ptc-runtime-node": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-llm": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-output-retention": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-session": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-spill": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-tools": "0.2.1-alpha.3",
+    "@deepseek-ai/cordis": "~4.0.5-alpha.1",
+    "@deepseek-ai/dsh-fs-local": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-subprocess-local": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-sandbox-local": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-sandbox-policy": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-session-projection": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-attachment": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-fs": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-token-meter": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-mcp-client": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-spill-local": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-llm-deepseek": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-ptc-runtime": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-attachment-local": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-tool-fs": "0.2.1-alpha.3",
+    "sharp": "^0.35.5",
+    "@deepseek-ai/dsh-agent-loop-testkit": "0.2.1-alpha.3"
+  },
+  "dsh": {}
+}