@hasna-internal/kai-output-retention 0.1.1-rc.2

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,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/util/output-retention/README.md
+README.md: e1d2c828fd4c6526cc391e7f93d7fe20df26e268
+README.zh.md: 51055dd33e2cce3b82a1d15d6994f9d9f37a0579

package/README.md

@@ -0,0 +1,97 @@
+# dsh-output-retention
+
+English | [中文](README.zh.md)
+
+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.
+
+The library owns **only** the mechanical question *"what did we keep, and what did we omit?"*. Tool-specific code keeps its business semantics: file grouping, line numbering, exit codes, provider error states, per-line preview truncation, spill files, and the model-facing prose. This is the boundary the [Agent Note](../../../.agents/notes/implemented/architecture/2026-07-06-tool-result-retention-library.md) draws.
+
+It is a **library, not a service or plugin**: no `ctx`, registers nothing, emits no events. The only state is per-retainer (one accumulation), never cross-call. Tool packages import it directly.
+
+## API
+
+```ts
+import {
+  ItemRetainer, TextRetainer,
+  describeOmitted, formatRetentionNotice,
+} from '@hasna-internal/kai-output-retention'
+import type {
+  Omitted, PushDecision, RetainedItems, RetainedText,
+  ItemRetentionStrategy, TextRetentionStrategy, RetentionNotice,
+} from '@hasna-internal/kai-output-retention'
+```
+
+| Export | Role |
+|---|---|
+| `ItemRetainer<T>` | Bounds ordered logical units (paths, grep matches, sources). `head` only. `push()` → `PushDecision`; `finish()` → `RetainedItems<T>`. |
+| `TextRetainer` | Bounds a byte-oriented text stream. `head` / `tail` / `headTail`, UTF-8 boundaries preserved at `finish()`. `push()` → `PushDecision`; `finish()` → `RetainedText`. |
+| `describeOmitted(omitted, unit)` | Standardized omission clause (`exact` prints a count; `unknown` does not). |
+| `formatRetentionNotice(notice, recovery)` | Joins the standardized omission clause with the tool's own recovery guidance. |
+| `Omitted` | `none` / `exact` / `unknown` — how much was omitted. |
+| `PushDecision` | `{ kept, truncated }` — the per-push retention result. |
+
+## Resource Modes
+
+The two retainers are separate names, not one generic collector, because they differ in **resource model**.
+
+- **`ItemRetainer` bounds ordered logical units.** A search tool can collect a full result set for spill-file recovery while retaining only the first `maxItems` for the model-facing preview. The omission count is exact because the caller keeps feeding every observed item.
+- **`TextRetainer` bounds byte-oriented text.** `head`, `tail`, and `headTail` preserve UTF-8 boundaries at `finish()`; `headTail` is the shape `dsh-spill-policy` uses to build a bounded preview around a spill-file notice.
+
+## `truncated` is a budget fact, never "incomplete"
+
+`truncated` means *the retainer omitted otherwise-available content because of a budget*. It does **not** mean the upstream was incomplete. Permission failures, skipped binary files, provider partial failures, unreadable candidates, and invalid UTF-8 stay in tool-domain fields — never folded into `truncated`. Conflating the two is the bug this library's naming most invites; keep them separate.
+
+## Bytes, not characters
+
+Text caps and `omittedBytes` count **bytes**, for process/body safety (a child's pipe and an HTTP body are byte streams). A chunk that straddles a codepoint is handled: `finish()` trims a partial codepoint at each cut so the returned text never introduces a replacement char at the boundary, and the two sides are decoded separately so a codepoint is never reconstructed across the omitted middle. Character- or line-level preview budgets are a separate, tool-owned concern.
+
+## Tool mappings
+
+Current retention consumers use these mappings:
+
+| Tool | Retainer & strategy | Notes |
+|---|---|---|
+| `glob` | `ItemRetainer<FsGlobEntry>`, `head` | Collect the full sorted path list for a spill file while retaining the first page inline. Path mapping, skipped candidates, and `incomplete` stay outside. |
+| `grep` | `ItemRetainer<FlatGrepMatch>`, `head` | Collect matches for a spill file while retaining the first page inline. Per-match preview truncation, grouping, sorting, and `incomplete` stay outside. |
+| `bash` | `TextRetainer`, `tail` or `headTail` | Executor still owns spill files, exit status, signal, timeout, and background jobs. |
+| `web_fetch` | `TextRetainer`, `head` or `headTail` | Provider/resource caps stay provider facts; the retainer supplies only retained text and omission metadata. |
+| `web_search` | `ItemRetainer<WebSearchSource>`, `head` | Standardizes the "sources capped" notice when providers return more sources than the model-facing result should include. |
+
+`read` remains outside this generic library. Its `read-render` helper owns a file-specific pagination contract — `offset`/`limit`, line numbers, `totalLines`, offset-out-of-range errors, per-line preview truncation, and a byte cap over the selected window — which is a line-window renderer. A single `Omitted` count cannot represent both sides of that window.
+
+## Usage shape
+
+```ts ignore-check
+// glob: keep the first page inline while still collecting the full list for spill.
+const retainer = new ItemRetainer<FsGlobEntry>({ kind: 'head', maxItems: globMaxResults })
+const allEntries: FsGlobEntry[] = []
+for await (const entry of candidates) {
+  allEntries.push(entry)
+  retainer.push(entry)
+}
+const { items, truncated, omitted } = retainer.finish()
+
+// bash: keep a head + tail, read to process exit.
+const out = new TextRetainer({ kind: 'headTail', headBytes: headCap, tailBytes: tailCap })
+child.stdout.on('data', (chunk: Buffer) => { out.push(chunk) })
+const { text, omittedBytes } = out.finish()
+
+// A footer: the library standardizes the omission clause; the tool owns recovery words.
+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.`,
+)
+```
+
+## Model Experience
+
+Indirectly, through tool consumers that render retained content and omission metadata.
+
+#### KV Cache effect
+
+No direct invalidation; the named consumer owns any request-prefix changes.
+
+## Known Limitations and Deferred Work
+
+- **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 returned text valid.

package/README.zh.md

@@ -0,0 +1,97 @@
+# dsh-output-retention
+
+[English](README.md) | 中文
+
+一个轻依赖的**保留**库：为必须限制返回上下文量的工具提供有界的面向模型输出。调用方将项或文本分片送入有界对象，然后取回保留的内容和精确的省略元数据。
+
+该库**只**负责这个机制问题：*「我们保留了什么，又省略了什么？」*。工具专用代码保留其业务语义：文件分组、行号、退出码、提供方错误状态、每行预览截断、spill 文件以及面向模型的文案。这就是 [Agent Note](../../../.agents/notes/implemented/architecture/2026-07-06-tool-result-retention-library.zh.md) 划定的边界。
+
+它是**库，而非服务或插件**：没有 `ctx`，不注册任何内容，不发出任何事件。状态只存在于每个 retainer（一次累积）中，绝不跨调用。工具包直接导入它。
+
+## 对外接口
+
+```ts
+import {
+  ItemRetainer, TextRetainer,
+  describeOmitted, formatRetentionNotice,
+} from '@hasna-internal/kai-output-retention'
+import type {
+  Omitted, PushDecision, RetainedItems, RetainedText,
+  ItemRetentionStrategy, TextRetentionStrategy, RetentionNotice,
+} from '@hasna-internal/kai-output-retention'
+```
+
+| 导出项 | 职责 |
+|---|---|
+| `ItemRetainer<T>` | 限制有序逻辑单元（路径、grep 匹配项、来源）。只支持 `head`。`push()` → `PushDecision`；`finish()` → `RetainedItems<T>`。 |
+| `TextRetainer` | 限制面向字节的文本流。`head` / `tail` / `headTail`，并在 `finish()` 时保留 UTF-8 边界。`push()` → `PushDecision`；`finish()` → `RetainedText`。 |
+| `describeOmitted(omitted, unit)` | 标准化的省略子句（`exact` 输出数量；`unknown` 不输出）。 |
+| `formatRetentionNotice(notice, recovery)` | 将标准化的省略子句与工具自有的恢复指引连接起来。 |
+| `Omitted` | `none` / `exact` / `unknown`：省略了多少内容。 |
+| `PushDecision` | `{ kept, truncated }`：每次 push 的保留结果。 |
+
+## 资源模式
+
+两个 retainer 使用独立名称，而不是同一个通用收集器，因为它们的**资源模型**不同。
+
+- **`ItemRetainer` 限制有序逻辑单元**。搜索工具可收集完整结果集用于 spill 文件恢复，同时只为面向模型的预览保留前 `maxItems` 项。因为调用方会继续送入每个已观察到的项，所以省略数量是精确的。
+- **`TextRetainer` 限制面向字节的文本**。`head`、`tail` 和 `headTail` 在 `finish()` 时保留 UTF-8 边界；`headTail` 是 `dsh-spill-policy` 用于围绕 spill 文件通知构建有界预览的形态。
+
+## `truncated` 是预算事实，绝不表示「不完整」
+
+`truncated` 表示*因为预算限制，retainer 省略了本可获得的内容*。它**不**表示上游不完整。权限失败、跳过二进制文件、提供方部分失败、不可读候选项和无效 UTF-8 保留在工具领域字段中，绝不合并到 `truncated`。将两者混为一谈是该库命名最容易诱发的缺陷；务必保持分离。
+
+## 字节，而非字符
+
+文本上限和 `omittedBytes` 按**字节**计数，以保证进程/正文安全（子进程管道和 HTTP 正文都是字节流）。跨越码点的分片会被正确处理：`finish()` 会修剪每个切割位置的不完整码点，使返回文本绝不在边界引入替换字符；首尾两侧会分开解码，因此绝不会跨越被省略的中间部分重建码点。按字符或行限制的预览预算属于独立的工具职责。
+
+## 工具映射
+
+当前的保留机制消费方采用以下映射：
+
+| 工具 | Retainer 与策略 | 说明 |
+|---|---|---|
+| `glob` | `ItemRetainer<FsGlobEntry>`，`head` | 收集完整的已排序路径列表用于 spill 文件，同时在内联位置保留第一页。路径映射、已跳过候选项和 `incomplete` 保留在外部。 |
+| `grep` | `ItemRetainer<FlatGrepMatch>`，`head` | 收集匹配项用于 spill 文件，同时在内联位置保留第一页。每个匹配项的预览截断、分组、排序和 `incomplete` 保留在外部。 |
+| `bash` | `TextRetainer`，`tail` 或 `headTail` | 执行器仍负责 spill 文件、退出状态、信号、超时和后台任务。 |
+| `web_fetch` | `TextRetainer`，`head` 或 `headTail` | 提供方/资源上限保留为提供方事实；retainer 只提供保留文本和省略元数据。 |
+| `web_search` | `ItemRetainer<WebSearchSource>`，`head` | 当提供方返回的来源超过面向模型的结果应包含的数量时，标准化「来源已达上限」通知。 |
+
+`read` 仍不属于这个通用库。其 `read-render` 辅助工具负责文件专用的分页约定：`offset`/`limit`、行号、`totalLines`、偏移越界错误、每行预览截断，以及所选窗口的字节上限。该辅助工具是一个行窗口渲染器。单个 `Omitted` 数量无法表示该窗口两侧。
+
+## 使用形态
+
+```ts ignore-check
+// glob: keep the first page inline while still collecting the full list for spill.
+const retainer = new ItemRetainer<FsGlobEntry>({ kind: 'head', maxItems: globMaxResults })
+const allEntries: FsGlobEntry[] = []
+for await (const entry of candidates) {
+  allEntries.push(entry)
+  retainer.push(entry)
+}
+const { items, truncated, omitted } = retainer.finish()
+
+// bash: keep a head + tail, read to process exit.
+const out = new TextRetainer({ kind: 'headTail', headBytes: headCap, tailBytes: tailCap })
+child.stdout.on('data', (chunk: Buffer) => { out.push(chunk) })
+const { text, omittedBytes } = out.finish()
+
+// A footer: the library standardizes the omission clause; the tool owns recovery words.
+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.`,
+)
+```
+
+## 模型体验
+
+通过渲染保留内容和省略元数据的工具消费方间接影响模型。
+
+#### KV Cache 影响
+
+不会直接导致 KV Cache 失效；请求前缀变更由上述消费方负责。
+
+## 已知限制与暂缓事项
+
+- **项保留只支持 `head`**：tail、head/tail、分页、分组和提供方完整性语义仍由工具负责。
+- **文本保留面向字节**：`read` 分页等行窗口和字符窗口需要单独的渲染器；切割可能会丢弃部分 UTF-8 边界字节，以保持返回文本有效。

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 @hasna-internal/kai-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/invariant.js

@@ -0,0 +1,23 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@hasna-internal/kai-output-retention`.
+* @module @hasna-internal/kai-output-retention/invariant
+*/
+const PACKAGE_NAME = "@hasna-internal/kai-output-retention";
+/** Cordis companion plugin name. */
+const name = "output-retention-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: this pure utility owns no event stream or mutable runtime data; its value
+* algebra is enforced by unit tests.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

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 @hasna-internal/kai-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/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@hasna-internal/kai-output-retention`.
+ * @module @hasna-internal/kai-output-retention/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "output-retention-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@hasna-internal/kai-output-retention",
+  "description": "Zero-dependency bounded-retention primitive: ItemRetainer/TextRetainer + neutral notice helpers (what did we keep, what did we omit)",
+  "version": "0.1.1-rc.2",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-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"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@hasna-internal/kai-invariants": "^0.1.1-rc.2",
+    "@deepseek-ai/cordis": "^4.0.1"
+  },
+  "devDependencies": {
+    "@hasna-internal/kai-invariants": "^0.1.1-rc.2",
+    "@deepseek-ai/cordis": "^4.0.1"
+  }
+}