{"_id":"@buckeyestudio/toh-spill-local","name":"@buckeyestudio/toh-spill-local","dist-tags":{"next":"0.1.1-rc.2","latest":"0.1.1-rc.2"},"versions":{"0.1.1-rc.2":{"name":"@buckeyestudio/toh-spill-local","description":"Local-filesystem implementation of the TheOpen Harness spill storage seam (private session-scoped files)","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-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"},"license":"MIT","author":{"name":"buckeyestudio"},"peerDependencies":{"@buckeyestudio/toh-invariants":"^0.1.1-rc.2","@buckeyestudio/toh-spill":"^0.1.1-rc.2","@buckeyestudio/cordis":"^4.0.1"},"dependencies":{"@buckeyestudio/schemastery":"^3.18.1"},"devDependencies":{"@buckeyestudio/toh-invariants":"^0.1.1-rc.2","@buckeyestudio/toh-brand":"^0.1.1-rc.2","@buckeyestudio/toh-session":"^0.1.1-rc.2","@buckeyestudio/toh-spill":"^0.1.1-rc.2","@buckeyestudio/toh-llm":"^0.1.1-rc.2","@buckeyestudio/cordis":"^4.0.1"},"_id":"@buckeyestudio/toh-spill-local@0.1.1-rc.2","bugs":{"url":"https://github.com/dustinwloring1988/theopen-harness/issues"},"homepage":"https://github.com/dustinwloring1988/theopen-harness#readme","_integrity":"sha512-YDkHdBLQWQavXAsQ8NOOGj3cMoClQJCDiCRMuz95cbX6bgjf0pwbRLYRym6SpyjtkWGkShYwNkZTezlmYfE2Aw==","_resolved":"/home/runner/work/theopen-harness/theopen-harness/dist/npm/buckeyestudio-toh-spill-local-0.1.1-rc.2.tgz","_from":"file:/home/runner/work/theopen-harness/theopen-harness/dist/npm/buckeyestudio-toh-spill-local-0.1.1-rc.2.tgz","_nodeVersion":"24.19.0","_npmVersion":"11.17.0","dist":{"integrity":"sha512-YDkHdBLQWQavXAsQ8NOOGj3cMoClQJCDiCRMuz95cbX6bgjf0pwbRLYRym6SpyjtkWGkShYwNkZTezlmYfE2Aw==","shasum":"e5b3a4b53f08cf15fd353b109a67406efce50c89","tarball":"https://registry.npmjs.org/@buckeyestudio/toh-spill-local/-/toh-spill-local-0.1.1-rc.2.tgz","fileCount":10,"unpackedSize":20045,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQD/rgzMgyOp5dBrLZja0Rd90vUpHx2UnuV0NEqBSKFfAgIgXuLSvfcBMctrBLOt1WfEHenNaArjmqcP8maDg8P+gG0="}]},"_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-local_0.1.1-rc.2_1787489335062_0.9032384600838719"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-23T12:48:54.774Z","0.1.1-rc.2":"2026-08-23T12:48:55.201Z","modified":"2026-08-23T12:48:55.441Z"},"maintainers":[{"name":"buckeyestudio","email":"dustinwloring1988@gmail.com"}],"description":"Local-filesystem implementation of the TheOpen Harness spill storage seam (private session-scoped files)","homepage":"https://github.com/dustinwloring1988/theopen-harness#readme","repository":{"type":"git","url":"git+https://github.com/dustinwloring1988/theopen-harness.git","directory":"packages/spill/spill-local"},"author":{"name":"buckeyestudio"},"bugs":{"url":"https://github.com/dustinwloring1988/theopen-harness/issues"},"license":"MIT","readme":"# @buckeyestudio/toh-spill-local\n\n[English](README.md) | 中文\n\n[`@buckeyestudio/toh-spill`](../spill) 存储 seam 的**本地文件系统**实现。它注册为 `ctx.spillStore`，将工具产生的过大文本持久化到私有的会话级文件；定位信息是文件路径，取回指引会告诉模型对该路径使用 `read` 或 `grep`。\n\n## 存储布局\n\n文件存放在 `<root>/session-<hash>/​<random>-<safeName>`：\n\n- **`root`**：使用配置中的 `root`（解析为绝对路径）；如果省略，则在操作系统临时目录下延迟创建每进程私有（0700）目录。可预测且任何用户均可读取的根目录会让其他本地用户读取 spill 工具输出，或在其中预置符号链接。\n- **`session-<hash>`**：截短的 `sha256(sessionId)` 前缀，用于将同一会话的 spill 文件归在一起，以便未来的清理操作可按会话删除。\n- **`<random>-<safeName>`**：不可预测的十六进制前缀（防止在共享根目录中预置符号链接），加上经过清理的调用方 `suggestedName`，使其成为单个安全路径段（防路径遍历；与 JSONL 持久化后端的 `encodeSegment` 一致）。写入操作采用排他方式，且权限仅限所有者（`open(path, 'wx', 0o600)`）：如果路径已经存在，无论是否为符号链接，操作都会失败，因此预置的目标无法重定向写入。\n\n## 配置\n\n| 键 | 默认值 | 含义 |\n|---|---|---|\n| `root` | 私有 0700 临时目录 | spill 文件的根目录。设置后可将这些文件保存在已知位置。 |\n\n`saveText` 在发生真实存储故障（权限、ENOSPC）时返回拒绝；spill 策略会按尽力而为原则处理该拒绝，并保留内联结果。词汇见 seam README，设计见[工具输出 spill Agent Note](../../../.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.zh.md)。\n\n## 模型体验\n\n通过渲染本地路径以及 `read`/`grep` 取回指引的 spill 消费方间接影响模型。\n\n#### KV Cache 影响\n\n不会直接导致 KV Cache 失效；请求前缀变更由上述消费方负责。\n\n## 已知限制与暂缓事项\n\n- **本地 spill 文件会持续存在，直到外部清理为止**：该后端不提供会话生命周期删除或按时间保留的策略，因为已持久化、已恢复和 fork 后的会话可能仍在引用某个路径。\n- **定位信息需要与其位于同一文件系统的消费方**：远程或虚拟部署需要另一个 `SpillStore` 后端，其定位信息和取回指引在该环境中有明确含义。\n","readmeFilename":"README.zh.md","_rev":"1-4b20e5d48cb3b5a82fd398134cfed05e"}