@qilin-agent/output-retention 0.0.0-stage → 3.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kkutysllb
+
+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,64 @@
+# 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/util/output-retention/README.md
+/:
+  en: 058416b280f64a3a
+  zh: 6dd741394b67bd30
+/qilin-output-retention:
+  en: 82dad0c2270dc0df
+  zh: de7c6f1334ed2692
+/qilin-output-retention/summary:
+  en: 3f0331a40f919223
+  zh: 9c670d911ceb4ff6
+/qilin-output-retention/table-of-contents:
+  en: d152484eb41ac6b4
+  zh: 09388d293f9be9cb
+/qilin-output-retention/use-this-package:
+  en: f62f2da3b880d972
+  zh: be8b8bea3bff9cb6
+/qilin-output-retention/use-this-package/bounding-a-list-of-items:
+  en: 4e33df2bffae04a9
+  zh: b79773e1936605bf
+/qilin-output-retention/use-this-package/bounding-a-text-stream:
+  en: c0002b8dd81f4732
+  zh: 4f8c0e9f03e4ecf9
+/qilin-output-retention/use-this-package/building-the-omission-footer:
+  en: 24a79057aea704e0
+  zh: ab6b91d0d1c3b8d7
+/qilin-output-retention/use-this-package/what-truncated-means:
+  en: d496be708ac637dc
+  zh: 739017ce47f08148
+/qilin-output-retention/use-this-package/how-the-current-tools-use-it:
+  en: ed4b3b343ad80143
+  zh: 65dd1f707c3ac747
+/qilin-output-retention/understand-the-implementation:
+  en: fd2a6c959bfe864e
+  zh: 25b11d28aced568c
+/qilin-output-retention/understand-the-implementation/source-map:
+  en: e2d87f9e71d8db62
+  zh: cf34dd787a069775
+/qilin-output-retention/understand-the-implementation/two-retainers-two-resource-models:
+  en: 6a5dd228d9f9808b
+  zh: 9bba82c5771ee705
+/qilin-output-retention/understand-the-implementation/how-the-budget-facts-stay-honest:
+  en: 101d99e1107d91c7
+  zh: ab64a35b62938db1
+/qilin-output-retention/understand-the-implementation/the-read-render-exclusion:
+  en: f76b67fa9e940705
+  zh: e7731bfd31cc9f5c
+/qilin-output-retention/further-exploration:
+  en: 7392047525d06599
+  zh: cc6e45cc72335359
+/qilin-output-retention/model-experience:
+  en: 247cdeeae9390244
+  zh: 0720d77e0a1d1c15
+/qilin-output-retention/model-experience/kv-cache-effect:
+  en: 4487c456cf996b48
+  zh: 2c25fe4a5a53f345
+/qilin-output-retention/known-limitations-and-deferred-work:
+  en: dabd5ca291570e70
+  zh: d1d98ece31eaa664
+/qilin-output-retention/known-limitations-and-deferred-work/dev-note:
+  en: e67f633dc6fe7773
+  zh: 3bb0c20c93f16f98

package/README.md

@@ -1,3 +1,163 @@
-# Temporary Holding Version
+---
+description: "Bounded model-facing output for tools that must cap how much context they return: item and text retainers plus a standardized omission footer."
+kind: "package-library"
+---
 
-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.
+# @qilin-agent/output-retention
+
+English | [中文](README.zh.md)
+
+## Summary
+
+Use `qilin-output-retention` to cap the items or text a tool returns to a model while reporting what was omitted. `ItemRetainer` keeps an ordered head window and can report an exact omitted-item count; `TextRetainer` keeps head, tail, or head-and-tail byte windows without returning invalid UTF-8 cuts. `formatRetentionNotice` adds a consistent omission clause while each tool supplies its own recovery guidance. Grouping, line numbering, spill files, and provider errors remain tool responsibilities; consumers import this library directly rather than loading it through `cordis.yml`.
+
+## 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
+
+Use a retainer wherever a tool must cap how much of its result reaches the model, and report honestly what was dropped. Choose `ItemRetainer` for ordered logical units and `TextRetainer` for byte-oriented streams.
+
+### Bounding a list of items
+
+```ts
+import { ItemRetainer } from '@qilin-agent/output-retention'
+
+declare const globMaxResults: number
+declare const candidates: AsyncIterable<{ path: string }>
+const retainer = new ItemRetainer<{ path: string }>({ kind: 'head', maxItems: globMaxResults })
+for await (const entry of candidates) {
+  retainer.push(entry)          // keep draining past the cap for an exact count
+}
+const { items, truncated, omitted } = retainer.finish()
+```
+
+`push()` reports per item whether it was kept, and `finish()` returns the retained items plus `omitted` — an exact count when the caller kept feeding every observed unit. A search tool can collect the full result set for a spill file while retaining only the first page for the model.
+
+### Bounding a text stream
+
+```text
+import { TextRetainer } from '@qilin-agent/output-retention'
+
+const out = new TextRetainer({ kind: 'headTail', headBytes: headCap, tailBytes: tailCap })
+child.stdout.on('data', (chunk: Buffer) => { out.push(chunk) })
+const { text, omittedBytes } = out.finish()
+```
+
+`head`, `tail`, and `headTail` count bytes, not characters or lines: a child's pipe and an HTTP body are byte streams. `finish()` trims a partial codepoint at each cut, so the returned text never carries a replacement character introduced by the cut, and a codepoint is never reconstructed across the omitted middle.
+
+### Building the omission footer
+
+```ts
+import { formatRetentionNotice } from '@qilin-agent/output-retention'
+
+declare const grepMaxMatches: number
+declare const items: { length: number }
+import type { Omitted } from '@qilin-agent/output-retention'
+
+declare const omitted: Omitted
+
+const footer = formatRetentionNotice(
+  { scope: 'grep', strategy: 'head', unit: 'items', limit: grepMaxMatches, kept: items.length, omitted },
+  ({ kept }) => `Results capped at ${kept}. Narrow the pattern, path, or include to see more.`,
+)
+```
+
+The library standardizes the omission clause (`Omitted 3 items.`) and joins it with the tool's own recovery guidance; only the tool knows the recovery action, so the tool supplies those words.
+
+### What `truncated` means
+
+`truncated` is a budget fact: the retainer omitted otherwise-available content because of a cap. It never means the upstream was incomplete — permission failures, skipped binary files, provider partial failures, and unreadable candidates stay in tool-domain fields, never folded into `truncated`.
+
+### How the current tools use it
+
+| Tool | Retainer | What the tool still owns |
+|---|---|---|
+| `glob` | `ItemRetainer`, `head` | Spill-file collection, path mapping, skipped candidates, `incomplete` |
+| `grep` | `ItemRetainer`, `head` | Spill-file collection, per-match preview truncation, grouping, sorting |
+| `bash` | `TextRetainer`, `tail` or `headTail` | Spill files, exit status, signal, timeout, background jobs |
+| `web_fetch` | `TextRetainer`, `head` or `headTail` | Provider and resource caps, error states |
+| `web_search` | `ItemRetainer`, `head` | The "sources capped" notice wording and provider facts |
+
+`read` stays outside this library: its line-window pagination (`offset`/`limit`, line numbers, `totalLines`) is a file-specific renderer that a single omission count cannot represent.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+The library is built on one separation: it owns the mechanical question of what was kept and what was omitted; tool packages own every business meaning.
+
+### Source map
+
+| File | Role |
+|---|---|
+| [`src/index.ts`](src/index.ts) | `ItemRetainer`, `TextRetainer`, `describeOmitted`, and `formatRetentionNotice` |
+
+### Two retainers, two resource models
+
+`ItemRetainer` bounds ordered logical units and keeps only the first `maxItems`; the caller keeps pushing every observed unit so the omission count is exact. `TextRetainer` bounds bytes with one shared prefix/suffix accumulator: `head` is prefix-only, `tail` is suffix-only, `headTail` is both, and the accumulator holds at most `headBytes + tailBytes + one chunk` in memory, so a large stream does not accumulate unbounded.
+
+### How the budget facts stay honest
+
+`push()` returns `kept` (this unit or chunk fully retained) and `truncated` (anything dropped yet). `finish()` reports omission against the bytes actually returned, so a UTF-8 boundary trim that drops partial-codepoint bytes is counted too — a notice built from the budget alone would overstate the retained text. `describeOmitted` prints a count only for `exact`; `unknown` prints no count because the caller provided none.
+
+### The read-render exclusion
+
+`read`'s `offset`/`limit` pagination is a line-window renderer with its own byte cap over the selected window; a single `Omitted` value cannot represent both sides of that window, so it stays out of this library.
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+Read these pages when you need the consumers or the boundary decision behind the library.
+
+- [Spill policy](../../spill/spill-policy/README.md) — composes `TextRetainer` for a bounded preview around a spill-file notice.
+- [Spill subsystem](../../../docs/subsystems/spill.md) — the spill vocabulary this library's preview mechanics serve.
+- [File search tool](../../fs/tool-fs-search/README.md) — an `ItemRetainer` consumer collecting full results for spill.
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+Indirectly, through the retention consumers that render retained content and omission metadata.
+
+#### KV Cache effect
+
+No direct invalidation; the retention consumers own any request-prefix changes.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+These limits define what the retainers deliberately do not cover. They are current package constraints, not a task backlog.
+
+- **Item retention supports `head` only** — tail, head/tail, pagination, grouping, and provider-completeness semantics remain tool-owned.
+- **Text retention is byte-oriented** — line and character windows such as `read` pagination require a separate renderer, and a cut may discard partial UTF-8 boundary bytes to keep the returned text valid.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>

package/README.zh.md

@@ -0,0 +1,163 @@
+---
+description: "为必须限制返回上下文量的工具提供有界的面向模型输出：项与文本 retainer，以及标准化的省略页脚。"
+kind: "package-library"
+---
+
+# @qilin-agent/output-retention
+
+[English](README.md) | 中文
+
+## 概述
+
+使用 `qilin-output-retention` 限制工具返回给模型的项或文本量，并报告省略了什么。`ItemRetainer` 保留有序的头部窗口，并可报告精确的省略项数；`TextRetainer` 保留 head、tail 或 head-and-tail 字节窗口，且不会返回因切割而无效的 UTF-8。`formatRetentionNotice` 添加一致的省略子句，各工具则提供自己的恢复指引。分组、行号、spill 文件与提供方错误仍归工具负责；消费方直接导入本库，而不通过 `cordis.yml` 加载。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+凡是工具必须限制其结果到达模型的数量、并如实报告丢弃内容的地方，都使用 retainer。有序逻辑单元选 `ItemRetainer`，面向字节的流选 `TextRetainer`。
+
+### 限制项列表
+
+```ts
+import { ItemRetainer } from '@qilin-agent/output-retention'
+
+declare const globMaxResults: number
+declare const candidates: AsyncIterable<{ path: string }>
+const retainer = new ItemRetainer<{ path: string }>({ kind: 'head', maxItems: globMaxResults })
+for await (const entry of candidates) {
+  retainer.push(entry)          // keep draining past the cap for an exact count
+}
+const { items, truncated, omitted } = retainer.finish()
+```
+
+`push()` 逐项报告该项是否被保留，`finish()` 返回保留的项与 `omitted`——当调用方持续送入每个已观察单元时，这是一个精确计数。搜索工具可以收集完整结果集用于 spill 文件，同时只为模型保留第一页。
+
+### 限制文本流
+
+```text
+import { TextRetainer } from '@qilin-agent/output-retention'
+
+const out = new TextRetainer({ kind: 'headTail', headBytes: headCap, tailBytes: tailCap })
+child.stdout.on('data', (chunk: Buffer) => { out.push(chunk) })
+const { text, omittedBytes } = out.finish()
+```
+
+`head`、`tail` 与 `headTail` 按字节而非字符或行计数：子进程管道与 HTTP 正文都是字节流。`finish()` 会在每个切割处修剪不完整的码点，因此返回的文本绝不会携带由切割引入的替换字符，码点也绝不会跨被省略的中间部分重建。
+
+### 构建省略页脚
+
+```ts
+import { formatRetentionNotice } from '@qilin-agent/output-retention'
+
+declare const grepMaxMatches: number
+declare const items: { length: number }
+import type { Omitted } from '@qilin-agent/output-retention'
+
+declare const omitted: Omitted
+
+const footer = formatRetentionNotice(
+  { scope: 'grep', strategy: 'head', unit: 'items', limit: grepMaxMatches, kept: items.length, omitted },
+  ({ kept }) => `Results capped at ${kept}. Narrow the pattern, path, or include to see more.`,
+)
+```
+
+库负责标准化省略子句（`Omitted 3 items.`）并把它与工具自有的恢复指引拼接；只有工具知道恢复动作，因此这些措辞由工具提供。
+
+### `truncated` 意味着什么
+
+`truncated` 是预算事实：retainer 因上限而省略了本可获得的内容。它绝不表示上游不完整——权限失败、跳过二进制文件、提供方部分失败与不可读候选项都留在工具领域字段中，绝不并入 `truncated`。
+
+### 当前工具如何使用它
+
+| 工具 | Retainer | 工具仍负责什么 |
+|---|---|---|
+| `glob` | `ItemRetainer`，`head` | spill 文件收集、路径映射、已跳过候选项、`incomplete` |
+| `grep` | `ItemRetainer`，`head` | spill 文件收集、逐匹配预览截断、分组、排序 |
+| `bash` | `TextRetainer`，`tail` 或 `headTail` | spill 文件、退出状态、信号、超时、后台任务 |
+| `web_fetch` | `TextRetainer`，`head` 或 `headTail` | 提供方与资源上限、错误状态 |
+| `web_search` | `ItemRetainer`，`head` | 「来源已达上限」通知措辞与提供方事实 |
+
+`read` 不属于本库：它的行窗口分页（`offset`/`limit`、行号、`totalLines`）是文件专属渲染器，单个省略计数无法表示该窗口的两侧。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现细节——点击展开</summary>
+
+本库建立在一个分离之上：它负责「保留了什么、省略了什么」这个机制问题；业务含义全部归工具包所有。
+
+### 源码地图
+
+| 文件 | 职责 |
+|---|---|
+| [`src/index.ts`](src/index.ts) | `ItemRetainer`、`TextRetainer`、`describeOmitted` 与 `formatRetentionNotice` |
+
+### 两个 retainer，两种资源模型
+
+`ItemRetainer` 限制有序逻辑单元，只保留前 `maxItems` 个；调用方持续送入每个已观察单元，因此省略计数是精确的。`TextRetainer` 用同一个前缀/后缀累加器限制字节：`head` 只留前缀，`tail` 只留后缀，`headTail` 两者都留；累加器在内存中至多持有 `headBytes + tailBytes + 一个分片`，因此大流不会无界累积。
+
+### 预算事实如何保持诚实
+
+`push()` 返回 `kept`（该单元或分片是否完整保留）与 `truncated`（是否已丢弃任何内容）。`finish()` 按实际返回的字节报告省略，因此丢弃部分码点字节的 UTF-8 边界修剪也会被计入——仅按预算推导的通知会高估保留文本。`describeOmitted` 只为 `exact` 打印计数；`unknown` 不打印计数，因为调用方没有提供。
+
+### read 渲染的排除
+
+`read` 的 `offset`/`limit` 分页是行窗口渲染器，对所选窗口有自己的字节上限；单个 `Omitted` 值无法表示该窗口两侧，因此它不属于本库。
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+当你需要消费方或库背后的边界决策时，阅读以下页面。
+
+- [spill 策略](../../spill/spill-policy/README.zh.md)——组合 `TextRetainer`，围绕 spill 文件通知构建有界预览。
+- [spill 子系统](../../../docs/subsystems/spill.zh.md)——本库预览机制所服务的 spill 词汇。
+- [文件搜索工具](../../fs/tool-fs-search/README.zh.md)——为 spill 收集完整结果的 `ItemRetainer` 消费方。
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+通过渲染保留内容与省略元数据的保留消费方间接影响模型。
+
+#### KV Cache 影响
+
+不会直接导致失效；请求前缀的任何变更由保留消费方负责。
+
+## 已知限制与延期工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+这些限制说明 retainer 刻意不覆盖什么。它们是当前包约束，不是任务积压。
+
+- **项保留只支持 `head`**——tail、head/tail、分页、分组与提供方完整性语义仍归工具所有。
+- **文本保留面向字节**——`read` 分页等行窗口与字符窗口需要单独的渲染器；切割可能丢弃部分 UTF-8 边界字节，以保持返回文本有效。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者的工作上下文——点击展开</summary>
+
+无。
+
+</details>

package/lib/index.js

@@ -0,0 +1,285 @@
+//#region lib/types/index.js
+/**
+* A dependency-light **retention** library: bounded model-facing output for
+* tools that must cap how much context they return. A caller feeds items or
+* text chunks into a bounded object, then gets the retained content plus exact
+* omission metadata ({@link RetainedItems} / {@link RetainedText}).
+*
+* The library owns ONLY the mechanical question "what did we keep, what did we
+* omit?". Tool-specific code still owns
+* business semantics: file grouping, line numbering, exit codes, provider error
+* states, per-line preview truncation, spill files, and the model-facing prose.
+* In particular {@link RetainedText.truncated}/{@link RetainedItems.truncated}
+* means "the retainer omitted otherwise-available content because of a budget" —
+* NOT "the upstream was incomplete". Permission failures, skipped binaries,
+* provider partial failures, and unreadable candidates stay in tool-domain
+* fields, never folded into `truncated`.
+*
+* This is deliberately a library, not a cordis service or plugin: it takes no
+* `ctx`, registers nothing, and emits no events. The two retainers are the only
+* stateful pieces and their state is per-instance (one accumulation), never
+* cross-call. Tool packages import it directly when they need bounded output.
+*
+* The two retainers differ in resource model, which is why they are two names
+* rather than one generic collector:
+* - {@link ItemRetainer} bounds ordered logical units (paths, grep matches,
+*   search sources). `head` retention only in v1.
+* - {@link TextRetainer} bounds byte-oriented text streams (bash stdout/stderr,
+*   web bodies). `head` / `tail` / `headTail`, preserving UTF-8 boundaries at
+*   {@link TextRetainer.finish}.
+*
+* @module @qilin-agent/output-retention
+*/
+/** Assert a budget field is a non-negative integer (the retainer request contract). */
+function assertBudget(value, name) {
+	if (!Number.isInteger(value) || value < 0) throw new Error(`${name} must be a non-negative integer`);
+}
+/**
+* Bounds an ordered stream of logical units, keeping the first `maxItems`
+* ({@link ItemRetentionStrategy} `head`). `push()` reports, per unit, whether it
+* was kept and whether the retained result is now truncated.
+*
+* Grouping, sorting, path mapping, per-unit preview truncation, and any
+* `incomplete` state stay OUTSIDE the retainer: it counts and keeps, nothing
+* more. The caller pushes prepared logical units and, after {@link finish},
+* groups/sorts the retained subset itself.
+*/
+var ItemRetainer = class {
+	maxItems;
+	items = [];
+	seen = 0;
+	omittedCount = 0;
+	/** @param strategy Head strategy: `maxItems` (non-negative integer). */
+	constructor(strategy) {
+		assertBudget(strategy.maxItems, "maxItems");
+		this.maxItems = strategy.maxItems;
+	}
+	/**
+	* Offer one unit. Kept when the retainer is below `maxItems`; otherwise dropped
+	* and counted as omitted. Callers keep pushing all observed units, so the final
+	* {@link Omitted} count is exact.
+	*
+	* @param item The prepared logical unit (path, flat match, source).
+	* @returns The per-push {@link PushDecision}.
+	*/
+	push(item) {
+		this.seen++;
+		if (this.items.length < this.maxItems) {
+			this.items.push(item);
+			return {
+				kept: true,
+				truncated: false
+			};
+		}
+		this.omittedCount++;
+		return {
+			kept: false,
+			truncated: true
+		};
+	}
+	/**
+	* Finalize and report what was kept and omitted.
+	*
+	* @returns The {@link RetainedItems} snapshot (safe to group/sort downstream).
+	*/
+	finish() {
+		const truncated = this.omittedCount > 0;
+		return {
+			items: this.items,
+			truncated,
+			seen: this.seen,
+			kept: this.items.length,
+			omitted: truncated ? {
+				kind: "exact",
+				count: this.omittedCount
+			} : { kind: "none" }
+		};
+	}
+};
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+/**
+* Drop a trailing incomplete UTF-8 sequence so a prefix cut never emits a
+* replacement char at the boundary. Walks back over continuation bytes
+* (`10xxxxxx`) to the lead byte; if fewer bytes follow it than the lead byte's
+* length declares, the sequence is incomplete and is trimmed. A complete tail,
+* or a run too long/short to be a valid lead, is returned untouched (any
+* genuinely malformed interior is left for the decoder to replace).
+*/
+function trimTrailingPartialUtf8(bytes) {
+	let i = bytes.length - 1;
+	while (i >= 0 && (bytes[i] & 192) === 128 && bytes.length - i <= 3) i--;
+	if (i < 0) return bytes;
+	const lead = bytes[i];
+	const expected = lead < 128 ? 1 : lead < 224 ? 2 : lead < 240 ? 3 : lead < 248 ? 4 : 0;
+	if (expected === 0) return bytes;
+	return bytes.length - i < expected ? bytes.subarray(0, i) : bytes;
+}
+/**
+* Drop leading continuation bytes (`10xxxxxx`) so a suffix cut starts on a
+* lead/ASCII byte instead of mid-codepoint.
+*/
+function trimLeadingContinuationUtf8(bytes) {
+	let i = 0;
+	while (i < bytes.length && (bytes[i] & 192) === 128) i++;
+	return bytes.subarray(i);
+}
+/**
+* Bounds a byte-oriented text stream, keeping a prefix, a suffix, or both
+* ({@link TextRetentionStrategy}). All three strategies share one prefix/suffix
+* accumulator: `head` is prefix-only, `tail` is suffix-only, `headTail` is both.
+*
+* Bytes, not characters: caps and `omittedBytes` are byte counts for process/
+* body safety. Chunks that straddle a codepoint are handled — {@link finish}
+* trims a partial codepoint at each cut so the returned text never introduces a
+* replacement char at the boundary. The retainer holds at most
+* `prefixCap + tailBytes + one chunk` in memory (old suffix chunks are dropped
+* as they slide out), so a large stream does not accumulate unbounded.
+*/
+var TextRetainer = class {
+	prefixCap;
+	suffixCap;
+	prefixChunks = [];
+	prefixHeld = 0;
+	suffixChunks = [];
+	suffixHeld = 0;
+	total = 0;
+	/** @param strategy One {@link TextRetentionStrategy} variant; byte budgets must be non-negative integers. */
+	constructor(strategy) {
+		switch (strategy.kind) {
+			case "head":
+				assertBudget(strategy.maxBytes, "maxBytes");
+				this.prefixCap = strategy.maxBytes;
+				this.suffixCap = 0;
+				break;
+			case "tail":
+				assertBudget(strategy.maxBytes, "maxBytes");
+				this.prefixCap = 0;
+				this.suffixCap = strategy.maxBytes;
+				break;
+			case "headTail":
+				assertBudget(strategy.headBytes, "headBytes");
+				assertBudget(strategy.tailBytes, "tailBytes");
+				this.prefixCap = strategy.headBytes;
+				this.suffixCap = strategy.tailBytes;
+				break;
+		}
+	}
+	/**
+	* Offer one chunk (a `Uint8Array`, or a `string` encoded as UTF-8). Prefix
+	* bytes fill up to the prefix cap then stop; suffix bytes roll so only the
+	* last `suffixCap` bytes are retained. `kept` is `true` only when no byte of
+	* this chunk was dropped.
+	*
+	* @param chunk The next bytes of the stream (`Uint8Array` or UTF-8 `string`).
+	* @returns The per-push {@link PushDecision}.
+	*/
+	push(chunk) {
+		const bytes = typeof chunk === "string" ? encoder.encode(chunk) : chunk;
+		const before = this.total;
+		this.total += bytes.length;
+		const room = this.prefixCap - this.prefixHeld;
+		const take = Math.max(0, Math.min(room, bytes.length));
+		if (take > 0) {
+			this.prefixChunks.push(bytes.subarray(0, take));
+			this.prefixHeld += take;
+		}
+		if (this.suffixCap > 0) {
+			this.suffixChunks.push(bytes);
+			this.suffixHeld += bytes.length;
+			let head = this.suffixChunks[0];
+			while (head !== void 0 && this.suffixHeld - head.length >= this.suffixCap) {
+				this.suffixChunks.shift();
+				this.suffixHeld -= head.length;
+				head = this.suffixChunks[0];
+			}
+			if (head !== void 0 && this.suffixHeld > this.suffixCap) {
+				const excess = this.suffixHeld - this.suffixCap;
+				this.suffixChunks[0] = head.subarray(excess);
+				this.suffixHeld -= excess;
+			}
+		}
+		return {
+			kept: !(this.omittedAt(this.total) > this.omittedAt(before)),
+			truncated: this.omittedAt(this.total) > 0
+		};
+	}
+	/** Bytes omitted once `total` bytes have been seen: `total − keptPrefix − keptSuffix`. */
+	omittedAt(total) {
+		const prefixLen = Math.min(total, this.prefixCap);
+		const suffixLen = Math.min(total - prefixLen, this.suffixCap);
+		return total - prefixLen - suffixLen;
+	}
+	/**
+	* Finalize: decode the retained prefix and suffix (each trimmed to a UTF-8
+	* boundary at its cut) and report the exact omitted byte count.
+	*
+	* @returns The {@link RetainedText} snapshot (safe to hand to a formatter).
+	*/
+	finish() {
+		const prefixLen = Math.min(this.total, this.prefixCap);
+		const suffixLen = Math.min(this.total - prefixLen, this.suffixCap);
+		const prefix = concat(this.prefixChunks);
+		const suffix = concat(this.suffixChunks).subarray(this.suffixHeld - suffixLen);
+		const budgetOmitted = this.omittedAt(this.total);
+		const [keptPrefix, keptSuffix] = budgetOmitted > 0 ? [trimTrailingPartialUtf8(prefix), trimLeadingContinuationUtf8(suffix)] : [prefix, suffix];
+		const text = budgetOmitted > 0 ? decoder.decode(keptPrefix) + decoder.decode(keptSuffix) : decoder.decode(concat([prefix, suffix]));
+		const omitted = this.total - keptPrefix.length - keptSuffix.length;
+		const truncated = omitted > 0;
+		return {
+			text,
+			truncated,
+			omittedBytes: truncated ? {
+				kind: "exact",
+				count: omitted
+			} : { kind: "none" }
+		};
+	}
+};
+/** Concatenate chunks into one contiguous buffer (their exact total length). */
+function concat(chunks) {
+	let length = 0;
+	for (const chunk of chunks) length += chunk.length;
+	const out = new Uint8Array(length);
+	let offset = 0;
+	for (const chunk of chunks) {
+		out.set(chunk, offset);
+		offset += chunk.length;
+	}
+	return out;
+}
+/**
+* Standardized, false-precision-safe wording for one {@link Omitted} value —
+* the "may standardize omission wording" half the library owns. `exact` prints
+* the count (`Omitted 3 items`); `unknown` prints NO count because the caller
+* did not provide one. `none` is the empty string.
+*
+* @param omitted The omission metadata from a retainer result.
+* @param unit The noun for the omitted quantity (`items`, `bytes`, `chars`, `lines`).
+* @returns A neutral clause (no trailing space), or `''` when nothing was omitted.
+*/
+function describeOmitted(omitted, unit) {
+	switch (omitted.kind) {
+		case "none": return "";
+		case "exact": return `Omitted ${omitted.count} ${unit}.`;
+		case "unknown": return `More ${unit} were omitted.`;
+	}
+}
+/**
+* Turn a {@link RetentionNotice} into a one-line footer: the library-owned
+* standardized omission clause ({@link describeOmitted}) followed by the tool's
+* own recovery guidance. The library never owns recovery words — only the tool
+* knows the action ("narrow the pattern", "fetch a more specific URL", "read the
+* spill file") — so `recovery` supplies them and receives the full notice to
+* phrase from (`kept`, `limit`, `omitted`, …). Either half may be empty; the two
+* are joined with a single space.
+*
+* @param notice The neutral retention outcome.
+* @param recovery Tool-supplied guidance builder; receives the notice, returns a sentence (or `''`).
+* @returns The combined footer line.
+*/
+function formatRetentionNotice(notice, recovery) {
+	return [describeOmitted(notice.omitted, notice.unit), recovery(notice)].filter((part) => part.length > 0).join(" ");
+}
+//#endregion
+export { ItemRetainer, TextRetainer, describeOmitted, formatRetentionNotice };

package/lib/types/index.d.ts

@@ -0,0 +1,225 @@
+/**
+ * A dependency-light **retention** library: bounded model-facing output for
+ * tools that must cap how much context they return. A caller feeds items or
+ * text chunks into a bounded object, then gets the retained content plus exact
+ * omission metadata ({@link RetainedItems} / {@link RetainedText}).
+ *
+ * The library owns ONLY the mechanical question "what did we keep, what did we
+ * omit?". Tool-specific code still owns
+ * business semantics: file grouping, line numbering, exit codes, provider error
+ * states, per-line preview truncation, spill files, and the model-facing prose.
+ * In particular {@link RetainedText.truncated}/{@link RetainedItems.truncated}
+ * means "the retainer omitted otherwise-available content because of a budget" —
+ * NOT "the upstream was incomplete". Permission failures, skipped binaries,
+ * provider partial failures, and unreadable candidates stay in tool-domain
+ * fields, never folded into `truncated`.
+ *
+ * This is deliberately a library, not a cordis service or plugin: it takes no
+ * `ctx`, registers nothing, and emits no events. The two retainers are the only
+ * stateful pieces and their state is per-instance (one accumulation), never
+ * cross-call. Tool packages import it directly when they need bounded output.
+ *
+ * The two retainers differ in resource model, which is why they are two names
+ * rather than one generic collector:
+ * - {@link ItemRetainer} bounds ordered logical units (paths, grep matches,
+ *   search sources). `head` retention only in v1.
+ * - {@link TextRetainer} bounds byte-oriented text streams (bash stdout/stderr,
+ *   web bodies). `head` / `tail` / `headTail`, preserving UTF-8 boundaries at
+ *   {@link TextRetainer.finish}.
+ *
+ * @module @qilin-agent/output-retention
+ */
+/**
+ * How much content the retainer omitted.
+ *
+ * `exact` is the normal retainer shape: every unit/byte was observed, so the
+ * omitted count is precise. `unknown` is reserved for a caller that omits
+ * without a count; the retainers themselves never return it.
+ */
+export type Omitted = {
+    kind: 'none';
+} | {
+    kind: 'exact';
+    count: number;
+} | {
+    kind: 'unknown';
+};
+/**
+ * The caller receives this after each `push()`.
+ */
+export interface PushDecision {
+    /** Was this whole unit / all of this chunk's bytes retained (nothing dropped)? */
+    kept: boolean;
+    /** Cumulative: has the retainer omitted anything due to the budget yet? */
+    truncated: boolean;
+}
+/**
+ * Final result for ordered logical units.
+ *
+ * `seen` means units OBSERVED by the retainer, not necessarily the total in the
+ * upstream source. `kept` is `items.length`, surfaced explicitly so a notice
+ * formatter need not re-count.
+ */
+export interface RetainedItems<T> {
+    items: T[];
+    truncated: boolean;
+    seen: number;
+    kept: number;
+    omitted: Omitted;
+}
+/**
+ * Final result for text streams.
+ *
+ * The returned `text` is safe to hand to a formatter: the retainer adds no
+ * tool-specific headers, exit markers, XML tags, or recovery instructions, and
+ * `omittedBytes` counts BYTES (not characters or lines) — text retention is
+ * byte-oriented for process/body safety. UTF-8 boundaries at each cut are
+ * preserved, so `text` never carries a replacement char introduced by the cut
+ * itself.
+ */
+export interface RetainedText {
+    text: string;
+    truncated: boolean;
+    omittedBytes: Omitted;
+}
+/** Item retention strategy. Only `head` in v1; windows/grouped budgets wait for a second consumer. */
+export type ItemRetentionStrategy = {
+    /** Keep the first `maxItems` units. Use for `glob`, `grep`, and web sources. */
+    kind: 'head';
+    maxItems: number;
+};
+/** Text retention strategy: keep a prefix, a suffix, or both, counted in bytes. */
+export type TextRetentionStrategy = {
+    /** Keep the first `maxBytes` bytes. */
+    kind: 'head';
+    maxBytes: number;
+} | {
+    /** Keep the final `maxBytes` bytes. Requires reading to the end. */
+    kind: 'tail';
+    maxBytes: number;
+} | {
+    /** Keep a stable prefix and suffix, omitting the middle. Requires reading to the end. */
+    kind: 'headTail';
+    headBytes: number;
+    tailBytes: number;
+};
+/**
+ * A neutral, tool-agnostic description of one retention outcome — the input to
+ * {@link formatRetentionNotice}. It carries the mechanical facts (strategy,
+ * unit, limit, kept count, {@link Omitted}); the tool supplies the recovery
+ * words, because only the tool knows the recovery action ("narrow the pattern",
+ * "fetch a more specific URL", "read the spill file").
+ */
+export interface RetentionNotice {
+    /** Tool/scope label, e.g. `grep`, `web_fetch`, `bash stdout`. */
+    scope: string;
+    strategy: 'head' | 'tail' | 'headTail';
+    unit: 'items' | 'bytes' | 'chars' | 'lines';
+    limit: number | {
+        head: number;
+        tail: number;
+    };
+    kept: number;
+    omitted: Omitted;
+}
+/**
+ * Bounds an ordered stream of logical units, keeping the first `maxItems`
+ * ({@link ItemRetentionStrategy} `head`). `push()` reports, per unit, whether it
+ * was kept and whether the retained result is now truncated.
+ *
+ * Grouping, sorting, path mapping, per-unit preview truncation, and any
+ * `incomplete` state stay OUTSIDE the retainer: it counts and keeps, nothing
+ * more. The caller pushes prepared logical units and, after {@link finish},
+ * groups/sorts the retained subset itself.
+ */
+export declare class ItemRetainer<T> {
+    private readonly maxItems;
+    private readonly items;
+    private seen;
+    private omittedCount;
+    /** @param strategy Head strategy: `maxItems` (non-negative integer). */
+    constructor(strategy: ItemRetentionStrategy);
+    /**
+     * Offer one unit. Kept when the retainer is below `maxItems`; otherwise dropped
+     * and counted as omitted. Callers keep pushing all observed units, so the final
+     * {@link Omitted} count is exact.
+     *
+     * @param item The prepared logical unit (path, flat match, source).
+     * @returns The per-push {@link PushDecision}.
+     */
+    push(item: T): PushDecision;
+    /**
+     * Finalize and report what was kept and omitted.
+     *
+     * @returns The {@link RetainedItems} snapshot (safe to group/sort downstream).
+     */
+    finish(): RetainedItems<T>;
+}
+/**
+ * Bounds a byte-oriented text stream, keeping a prefix, a suffix, or both
+ * ({@link TextRetentionStrategy}). All three strategies share one prefix/suffix
+ * accumulator: `head` is prefix-only, `tail` is suffix-only, `headTail` is both.
+ *
+ * Bytes, not characters: caps and `omittedBytes` are byte counts for process/
+ * body safety. Chunks that straddle a codepoint are handled — {@link finish}
+ * trims a partial codepoint at each cut so the returned text never introduces a
+ * replacement char at the boundary. The retainer holds at most
+ * `prefixCap + tailBytes + one chunk` in memory (old suffix chunks are dropped
+ * as they slide out), so a large stream does not accumulate unbounded.
+ */
+export declare class TextRetainer {
+    private readonly prefixCap;
+    private readonly suffixCap;
+    private readonly prefixChunks;
+    private prefixHeld;
+    private readonly suffixChunks;
+    private suffixHeld;
+    private total;
+    /** @param strategy One {@link TextRetentionStrategy} variant; byte budgets must be non-negative integers. */
+    constructor(strategy: TextRetentionStrategy);
+    /**
+     * Offer one chunk (a `Uint8Array`, or a `string` encoded as UTF-8). Prefix
+     * bytes fill up to the prefix cap then stop; suffix bytes roll so only the
+     * last `suffixCap` bytes are retained. `kept` is `true` only when no byte of
+     * this chunk was dropped.
+     *
+     * @param chunk The next bytes of the stream (`Uint8Array` or UTF-8 `string`).
+     * @returns The per-push {@link PushDecision}.
+     */
+    push(chunk: Uint8Array | string): PushDecision;
+    /** Bytes omitted once `total` bytes have been seen: `total − keptPrefix − keptSuffix`. */
+    private omittedAt;
+    /**
+     * Finalize: decode the retained prefix and suffix (each trimmed to a UTF-8
+     * boundary at its cut) and report the exact omitted byte count.
+     *
+     * @returns The {@link RetainedText} snapshot (safe to hand to a formatter).
+     */
+    finish(): RetainedText;
+}
+/**
+ * Standardized, false-precision-safe wording for one {@link Omitted} value —
+ * the "may standardize omission wording" half the library owns. `exact` prints
+ * the count (`Omitted 3 items`); `unknown` prints NO count because the caller
+ * did not provide one. `none` is the empty string.
+ *
+ * @param omitted The omission metadata from a retainer result.
+ * @param unit The noun for the omitted quantity (`items`, `bytes`, `chars`, `lines`).
+ * @returns A neutral clause (no trailing space), or `''` when nothing was omitted.
+ */
+export declare function describeOmitted(omitted: Omitted, unit: RetentionNotice['unit']): string;
+/**
+ * Turn a {@link RetentionNotice} into a one-line footer: the library-owned
+ * standardized omission clause ({@link describeOmitted}) followed by the tool's
+ * own recovery guidance. The library never owns recovery words — only the tool
+ * knows the action ("narrow the pattern", "fetch a more specific URL", "read the
+ * spill file") — so `recovery` supplies them and receives the full notice to
+ * phrase from (`kept`, `limit`, `omitted`, …). Either half may be empty; the two
+ * are joined with a single space.
+ *
+ * @param notice The neutral retention outcome.
+ * @param recovery Tool-supplied guidance builder; receives the notice, returns a sentence (or `''`).
+ * @returns The combined footer line.
+ */
+export declare function formatRetentionNotice(notice: RetentionNotice, recovery: (notice: RetentionNotice) => string): string;
+//# sourceMappingURL=index.d.ts.map

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "@qilin-agent/output-retention",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Zero-dependency bounded-retention primitive: ItemRetainer/TextRetainer + neutral notice helpers (what did we keep, what did we omit)",
+  "version": "3.1.3",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kkutysllb/QiLin.git",
+    "directory": "packages/util/output-retention"
+  },
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@qilin-agent/kylin": "~4.0.3"
+  },
+  "devDependencies": {
+    "@qilin-agent/kylin": "~4.0.3"
+  }
 }