{"_id":"@buckeyestudio/toh-spill","name":"@buckeyestudio/toh-spill","dist-tags":{"next":"0.1.1-rc.2","latest":"0.1.1-rc.2"},"versions":{"0.1.1-rc.2":{"name":"@buckeyestudio/toh-spill","description":"Abstract spill storage seam (ctx.spillStore) for the TheOpen Harness — save oversized tool text and return a retrieval locator","version":"0.1.1-rc.2","publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/dustinwloring1988/theopen-harness.git","directory":"packages/spill/spill"},"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"},"license":"MIT","author":{"name":"buckeyestudio"},"peerDependencies":{"@buckeyestudio/toh-brand":"^0.1.1-rc.2","@buckeyestudio/toh-invariants":"^0.1.1-rc.2","@buckeyestudio/toh-llm":"^0.1.1-rc.2","@buckeyestudio/toh-session":"^0.1.1-rc.2","@buckeyestudio/cordis":"^4.0.1"},"devDependencies":{"@buckeyestudio/toh-brand":"^0.1.1-rc.2","@buckeyestudio/toh-llm":"^0.1.1-rc.2","@buckeyestudio/toh-invariants":"^0.1.1-rc.2","@buckeyestudio/cordis":"^4.0.1","@buckeyestudio/toh-session":"^0.1.1-rc.2"},"_id":"@buckeyestudio/toh-spill@0.1.1-rc.2","bugs":{"url":"https://github.com/dustinwloring1988/theopen-harness/issues"},"homepage":"https://github.com/dustinwloring1988/theopen-harness#readme","_integrity":"sha512-mpTNttIWKAP3wh2NzVN9HbUn/IlqnLb+IJnMYJ+Cm+ec60sHmvr5o/DQZaxKNvNTRE22n/GvqPpZhqo68vH3tw==","_resolved":"/home/runner/work/theopen-harness/theopen-harness/dist/npm/buckeyestudio-toh-spill-0.1.1-rc.2.tgz","_from":"file:/home/runner/work/theopen-harness/theopen-harness/dist/npm/buckeyestudio-toh-spill-0.1.1-rc.2.tgz","_nodeVersion":"24.19.0","_npmVersion":"11.17.0","dist":{"integrity":"sha512-mpTNttIWKAP3wh2NzVN9HbUn/IlqnLb+IJnMYJ+Cm+ec60sHmvr5o/DQZaxKNvNTRE22n/GvqPpZhqo68vH3tw==","shasum":"2d6c46c65bddf2eca891873d88fd50c3e2f5e10d","tarball":"https://registry.npmjs.org/@buckeyestudio/toh-spill/-/toh-spill-0.1.1-rc.2.tgz","fileCount":10,"unpackedSize":18879,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCJb9C5LyVvWihn9BGZ2kiFEGi+fV/qg3EloN5zmSLWxgIgQywC6Fa5GeKkr8joRw2EaGuqBV186hLGmkqIFVdDBrk="}]},"_npmUser":{"name":"buckeyestudio","email":"dustinwloring1988@gmail.com"},"directories":{},"maintainers":[{"name":"buckeyestudio","email":"dustinwloring1988@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/toh-spill_0.1.1-rc.2_1787489330792_0.18435357848749256"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-23T12:48:50.658Z","0.1.1-rc.2":"2026-08-23T12:48:50.923Z","modified":"2026-08-23T12:48:51.105Z"},"maintainers":[{"name":"buckeyestudio","email":"dustinwloring1988@gmail.com"}],"description":"Abstract spill storage seam (ctx.spillStore) for the TheOpen Harness — save oversized tool text and return a retrieval locator","homepage":"https://github.com/dustinwloring1988/theopen-harness#readme","repository":{"type":"git","url":"git+https://github.com/dustinwloring1988/theopen-harness.git","directory":"packages/spill/spill"},"author":{"name":"buckeyestudio"},"bugs":{"url":"https://github.com/dustinwloring1988/theopen-harness/issues"},"license":"MIT","readme":"# @buckeyestudio/toh-spill\n\n[English](README.md) | 中文\n\n**`SpillStore`**（`ctx.spillStore`）定义 spill 后端做什么，即持久化某个工具过大的文本，并返回面向模型的定位信息与取回指引；它不规定如何实现。\n\n该包是 spill 能力的三个组成部分之一。拆分后，各项关注点可独立演进和替换：\n\n| 包 | 职责 |\n|---|---|\n| `@buckeyestudio/toh-spill`（本包） | Service Definition：抽象服务与词汇类型 |\n| `@buckeyestudio/toh-spill-local` | Service Provider：位于宿主文件系统中的私有会话级文件 |\n| `@buckeyestudio/toh-spill-policy` | Consumer：对过大最终结果执行 spill 的工具结果策略 |\n\n这种拆分方式与 shell/fs seam 相同。未来的远程或虚拟后端（例如 `spill://…` URI、数据库键或后端专用取回工具）可实现此 Service Definition，无需修改策略插件。\n\n## 服务 API（`ctx.spillStore`）\n\n| 成员 | 语义 |\n|---|---|\n| `saveText(input)` | 逐字保存 `input.content`；成功时返回 `SpillRef`（不透明定位信息、写入的精确字节数和取回指引）。**发生真实存储故障时，调用会以拒绝状态结束**（权限、ENOSPC、后端不可用）；由调用方决定如何降级。 |\n\n存储操作以请求的 `owner` 会话作为保存时命名空间进行分组；后端自行选择私有表示，并可以从调用方的 `suggestedName` 派生名称，但绝不能将其当作可信路径。该 seam 只负责存储：不提供保留策略（由 [`@buckeyestudio/toh-output-retention`](../../util/output-retention) 负责），不替换工具结果（由 `@buckeyestudio/toh-spill-policy` 负责），也不提供取回/搜索 API（后端的 `retrievalHint` 会告诉模型如何使用定位信息）。\n\n## 词汇\n\n`SaveTextSpill`（owner、source、suggestedName、content）是请求；`SpillRef`（locator、bytes、retrievalHint）是结果。`SpillLocator` 是[带品牌类型](../../util/brand)的值，并以不透明字符串的形式呈现给模型；对 `toh-spill-local` 而言它是本地路径，但未来的后端可以返回 URI、键或命令 token，无需修改策略／工具消费方。`SpillOwner.sessionId` 是保存时存储命名空间：fork 后的会话会从种子日志继承现有定位信息，无需复制或更改其归属；fork 后新产生的 spill 使用子会话 id。`SpillSource` 记录产生该 spill 的 `toolName`、`callId` 和 `label`，供后端命名和检查使用，不用于访问控制。完整约定见 `src/types.ts`。\n\n设计原理见[工具输出 spill Agent Note](../../../.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.zh.md)，其中说明了为什么创建操作应由运行时 spill seam 而非面向模型的 `write` 工具承担。\n\n## 模型体验\n\n通过渲染后端定位信息和取回指引的 spill 消费方间接影响模型。\n\n#### KV Cache 影响\n\n不会直接导致 KV Cache 失效；请求前缀变更由上述消费方负责。\n\n## 已知限制与暂缓事项\n\n- **该 seam 没有取回或删除 API**：消费方只能渲染后端的定位信息与指引；生命周期和访问语义仍由后端自行决定。\n- **存储不等于访问控制**：`SpillOwner` 会区分写入命名空间，但不会授予通过定位信息读取内容的权限；每个后端和取回消费方都必须自行强制执行访问边界。\n","readmeFilename":"README.zh.md","_rev":"1-e52975429fdfc43398c09c4c1215bcee"}