{"_id":"@buddhilive/dsh-output-retention","name":"@buddhilive/dsh-output-retention","dist-tags":{"alpha":"0.1.2-alpha.3","latest":"0.1.2-alpha.3"},"versions":{"0.1.2-alpha.3":{"name":"@buddhilive/dsh-output-retention","description":"Zero-dependency bounded-retention primitive: ItemRetainer/TextRetainer + neutral notice helpers (what did we keep, what did we omit)","version":"0.1.2-alpha.3","publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/Buddhilive/buddhi-ai-harness.git","directory":"packages/util/output-retention"},"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","peerDependencies":{"@buddhilive/dsh-invariants":"^0.1.2-alpha.3","@deepseek-ai/cordis":"^4.0.2"},"devDependencies":{"@buddhilive/dsh-invariants":"^0.1.2-alpha.3","@deepseek-ai/cordis":"^4.0.2"},"_id":"@buddhilive/dsh-output-retention@0.1.2-alpha.3","bugs":{"url":"https://github.com/Buddhilive/buddhi-ai-harness/issues"},"homepage":"https://github.com/Buddhilive/buddhi-ai-harness#readme","_integrity":"sha512-M/KcWDhKv/2Z3HWU7/d4gnYJygxC4BpexnFhJN405jsg8dygX2hRHE4QfKBej6G7Cs4KGqqv70vrYeMNlnA+Ow==","_resolved":"C:\\DevDojo\\Buddhi\\buddhi-ai-harness\\dist\\npm\\buddhilive-dsh-output-retention-0.1.2-alpha.3.tgz","_from":"file:C:/DevDojo/Buddhi/buddhi-ai-harness/dist/npm/buddhilive-dsh-output-retention-0.1.2-alpha.3.tgz","_nodeVersion":"24.13.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-M/KcWDhKv/2Z3HWU7/d4gnYJygxC4BpexnFhJN405jsg8dygX2hRHE4QfKBej6G7Cs4KGqqv70vrYeMNlnA+Ow==","shasum":"f5bf009194067bff3e201fd56b3f49a7d7e44fd6","tarball":"https://registry.npmjs.org/@buddhilive/dsh-output-retention/-/dsh-output-retention-0.1.2-alpha.3.tgz","fileCount":9,"unpackedSize":41490,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQC5lrNRRYmgXpjfkF4qfvwD1lUkMOykeMEXR4s2DuuORQIgUpgL3Ze6MLK1lpZy351YYupBfyb39D+yji/GYAfPU6o="}]},"_npmUser":{"name":"buddhilive","email":"visitbudkavin@gmail.com"},"directories":{},"maintainers":[{"name":"buddhilive","email":"visitbudkavin@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/dsh-output-retention_0.1.2-alpha.3_1788165297194_0.18130979849843842"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-31T08:34:57.057Z","0.1.2-alpha.3":"2026-08-31T08:34:57.326Z","modified":"2026-08-31T08:34:57.508Z"},"maintainers":[{"name":"buddhilive","email":"visitbudkavin@gmail.com"}],"description":"Zero-dependency bounded-retention primitive: ItemRetainer/TextRetainer + neutral notice helpers (what did we keep, what did we omit)","homepage":"https://github.com/Buddhilive/buddhi-ai-harness#readme","repository":{"type":"git","url":"git+https://github.com/Buddhilive/buddhi-ai-harness.git","directory":"packages/util/output-retention"},"bugs":{"url":"https://github.com/Buddhilive/buddhi-ai-harness/issues"},"license":"MIT","readme":"---\ndescription: \"为必须限制返回上下文量的工具提供有界的面向模型输出：项与文本 retainer，以及标准化的省略页脚。\"\nkind: \"package-library\"\n---\n\n# @buddhilive/dsh-output-retention\n\n[English](README.md) | 中文\n\n## 概述\n\n`dsh-output-retention` 限制工具返回给模型的上下文量：调用方把项或文本分片送入 retainer，然后取回保留的内容与精确的省略元数据。`ItemRetainer` 以头部预算限制有序逻辑单元列表（路径、匹配项、来源）；`TextRetainer` 以 head、tail 或 head+tail 窗口限制面向字节的文本流，并在每个切割处保持 UTF-8 边界有效。标准化的省略子句与通知格式化器让工具获得一致的「结果已达上限」页脚，而恢复指引由工具自己提供。该库只回答「保留了什么、省略了什么」这个机制问题——分组、行号、spill 文件与提供方错误状态都留在工具侧。它是轻依赖库，由工具包直接导入；`cordis.yml` 无法加载它。\n\n## 目录\n\n- [使用本包](#use-this-package)\n- [理解实现](#understand-the-implementation)\n- [进一步探索](#further-exploration)\n- [模型体验](#model-experience)\n- [已知限制与延期工作](#known-limitations-and-deferred-work)\n- [开发备注](#dev-note)\n\n-----\n\n<a id=\"use-this-package\"></a>\n## 使用本包\n\n凡是工具必须限制其结果到达模型的数量、并如实报告丢弃内容的地方，都使用 retainer。有序逻辑单元选 `ItemRetainer`，面向字节的流选 `TextRetainer`。\n\n### 限制项列表\n\n```ts\nimport { ItemRetainer } from '@buddhilive/dsh-output-retention'\n\ndeclare const globMaxResults: number\ndeclare const candidates: AsyncIterable<{ path: string }>\nconst retainer = new ItemRetainer<{ path: string }>({ kind: 'head', maxItems: globMaxResults })\nfor await (const entry of candidates) {\n  retainer.push(entry)          // keep draining past the cap for an exact count\n}\nconst { items, truncated, omitted } = retainer.finish()\n```\n\n`push()` 逐项报告该项是否被保留，`finish()` 返回保留的项与 `omitted`——当调用方持续送入每个已观察单元时，这是一个精确计数。搜索工具可以收集完整结果集用于 spill 文件，同时只为模型保留第一页。\n\n### 限制文本流\n\n```text\nimport { TextRetainer } from '@buddhilive/dsh-output-retention'\n\nconst out = new TextRetainer({ kind: 'headTail', headBytes: headCap, tailBytes: tailCap })\nchild.stdout.on('data', (chunk: Buffer) => { out.push(chunk) })\nconst { text, omittedBytes } = out.finish()\n```\n\n`head`、`tail` 与 `headTail` 按字节而非字符或行计数：子进程管道与 HTTP 正文都是字节流。`finish()` 会在每个切割处修剪不完整的码点，因此返回的文本绝不会携带由切割引入的替换字符，码点也绝不会跨被省略的中间部分重建。\n\n### 构建省略页脚\n\n```ts\nimport { formatRetentionNotice } from '@buddhilive/dsh-output-retention'\n\ndeclare const grepMaxMatches: number\ndeclare const items: { length: number }\nimport type { Omitted } from '@buddhilive/dsh-output-retention'\n\ndeclare const omitted: Omitted\n\nconst footer = formatRetentionNotice(\n  { scope: 'grep', strategy: 'head', unit: 'items', limit: grepMaxMatches, kept: items.length, omitted },\n  ({ kept }) => `Results capped at ${kept}. Narrow the pattern, path, or include to see more.`,\n)\n```\n\n库负责标准化省略子句（`Omitted 3 items.`）并把它与工具自有的恢复指引拼接；只有工具知道恢复动作，因此这些措辞由工具提供。\n\n### `truncated` 意味着什么\n\n`truncated` 是预算事实：retainer 因上限而省略了本可获得的内容。它绝不表示上游不完整——权限失败、跳过二进制文件、提供方部分失败与不可读候选项都留在工具领域字段中，绝不并入 `truncated`。\n\n### 当前工具如何使用它\n\n| 工具 | Retainer | 工具仍负责什么 |\n|---|---|---|\n| `glob` | `ItemRetainer`，`head` | spill 文件收集、路径映射、已跳过候选项、`incomplete` |\n| `grep` | `ItemRetainer`，`head` | spill 文件收集、逐匹配预览截断、分组、排序 |\n| `bash` | `TextRetainer`，`tail` 或 `headTail` | spill 文件、退出状态、信号、超时、后台任务 |\n| `web_fetch` | `TextRetainer`，`head` 或 `headTail` | 提供方与资源上限、错误状态 |\n| `web_search` | `ItemRetainer`，`head` | 「来源已达上限」通知措辞与提供方事实 |\n\n`read` 不属于本库：它的行窗口分页（`offset`/`limit`、行号、`totalLines`）是文件专属渲染器，单个省略计数无法表示该窗口的两侧。\n\n-----\n\n<a id=\"understand-the-implementation\"></a>\n## 理解实现\n\n<details>\n<summary>实现细节——点击展开</summary>\n\n本库建立在一个分离之上：它负责「保留了什么、省略了什么」这个机制问题；业务含义全部归工具包所有。\n\n### 源码地图\n\n| 文件 | 职责 |\n|---|---|\n| [`src/index.ts`](src/index.ts) | `ItemRetainer`、`TextRetainer`、`describeOmitted` 与 `formatRetentionNotice` |\n| [`src/invariant.ts`](src/invariant.ts) | 不变式伴生插件（无运行时不变式；保留运算由单元测试覆盖） |\n\n### 两个 retainer，两种资源模型\n\n`ItemRetainer` 限制有序逻辑单元，只保留前 `maxItems` 个；调用方持续送入每个已观察单元，因此省略计数是精确的。`TextRetainer` 用同一个前缀/后缀累加器限制字节：`head` 只留前缀，`tail` 只留后缀，`headTail` 两者都留；累加器在内存中至多持有 `headBytes + tailBytes + 一个分片`，因此大流不会无界累积。\n\n### 预算事实如何保持诚实\n\n`push()` 返回 `kept`（该单元或分片是否完整保留）与 `truncated`（是否已丢弃任何内容）。`finish()` 按实际返回的字节报告省略，因此丢弃部分码点字节的 UTF-8 边界修剪也会被计入——仅按预算推导的通知会高估保留文本。`describeOmitted` 只为 `exact` 打印计数；`unknown` 不打印计数，因为调用方没有提供。\n\n### read 渲染的排除\n\n`read` 的 `offset`/`limit` 分页是行窗口渲染器，对所选窗口有自己的字节上限；单个 `Omitted` 值无法表示该窗口两侧，因此它不属于本库。\n\n</details>\n\n-----\n\n<a id=\"further-exploration\"></a>\n## 进一步探索\n\n当你需要消费方或库背后的边界决策时，阅读以下页面。\n\n- [工具结果保留库 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-06-tool-result-retention-library.zh.md)——库围绕工具语义划定的边界。\n- [spill 策略](../../spill/spill-policy/README.zh.md)——组合 `TextRetainer`，围绕 spill 文件通知构建有界预览。\n- [spill 子系统](../../../docs/subsystems/spill.zh.md)——本库预览机制所服务的 spill 词汇。\n- [文件搜索工具](../../fs/tool-fs-search/README.zh.md)——为 spill 收集完整结果的 `ItemRetainer` 消费方。\n\n-----\n\n<a id=\"model-experience\"></a>\n## 模型体验\n\n通过渲染保留内容与省略元数据的保留消费方间接影响模型。\n\n#### KV Cache 影响\n\n不会直接导致失效；请求前缀的任何变更由保留消费方负责。\n\n## 已知限制与延期工作\n\n<a id=\"known-limitations-and-deferred-work\"></a>\n\n\n这些限制说明 retainer 刻意不覆盖什么。它们是当前包约束，不是任务积压。\n\n- **项保留只支持 `head`**——tail、head/tail、分页、分组与提供方完整性语义仍归工具所有。\n- **文本保留面向字节**——`read` 分页等行窗口与字符窗口需要单独的渲染器；切割可能丢弃部分 UTF-8 边界字节，以保持返回文本有效。\n\n<a id=\"dev-note\"></a>\n### 开发备注\n\n<details>\n<summary>维护者的工作上下文——点击展开</summary>\n\n无。\n\n</details>\n","readmeFilename":"README.zh.md","_rev":"1-6b8f07c36cbac850b49ae44090105f10"}