@deepseek-ai/dsh-output-retention 0.1.7-alpha.2 → 0.1.7-rc.2

package/README.i18n.yaml

@@ -1,6 +1,67 @@
-# 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:
+# 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
-README.md: bb0902b959f298f9f7b0a64de23d48e29bfd75ad
-README.zh.md: 7d96ba4da33a98b24eba53f9dd5a2f2c98b79f39
+/:
+  en: 058416b280f64a3a
+  zh: 6dd741394b67bd30
+/deepseek-ai-dsh-output-retention:
+  en: 909b14f93584c835
+  zh: da2b6de301df901a
+/deepseek-ai-dsh-output-retention/summary:
+  en: 22e523125ade3619
+  zh: 2cf48b1a6658056f
+/deepseek-ai-dsh-output-retention/table-of-contents:
+  en: d152484eb41ac6b4
+  zh: 09388d293f9be9cb
+/deepseek-ai-dsh-output-retention/use-this-package:
+  en: f62f2da3b880d972
+  zh: be8b8bea3bff9cb6
+/deepseek-ai-dsh-output-retention/use-this-package/bounding-a-list-of-items:
+  en: 4e33df2bffae04a9
+  zh: b79773e1936605bf
+/deepseek-ai-dsh-output-retention/use-this-package/bounding-a-text-stream:
+  en: c0002b8dd81f4732
+  zh: 4f8c0e9f03e4ecf9
+/deepseek-ai-dsh-output-retention/use-this-package/building-the-omission-footer:
+  en: 24a79057aea704e0
+  zh: ab6b91d0d1c3b8d7
+/deepseek-ai-dsh-output-retention/use-this-package/capping-a-character-budget-preview:
+  en: ca55f16ac7f494d4
+  zh: 181c19d0d5f0128b
+/deepseek-ai-dsh-output-retention/use-this-package/what-truncated-means:
+  en: d496be708ac637dc
+  zh: 739017ce47f08148
+/deepseek-ai-dsh-output-retention/use-this-package/how-the-current-tools-use-it:
+  en: ed4b3b343ad80143
+  zh: 65dd1f707c3ac747
+/deepseek-ai-dsh-output-retention/understand-the-implementation:
+  en: fd2a6c959bfe864e
+  zh: 25b11d28aced568c
+/deepseek-ai-dsh-output-retention/understand-the-implementation/source-map:
+  en: cb49af8772b97f13
+  zh: 23810afb65f350ee
+/deepseek-ai-dsh-output-retention/understand-the-implementation/two-retainers-two-resource-models:
+  en: 6a5dd228d9f9808b
+  zh: 9bba82c5771ee705
+/deepseek-ai-dsh-output-retention/understand-the-implementation/how-the-budget-facts-stay-honest:
+  en: 101d99e1107d91c7
+  zh: ab64a35b62938db1
+/deepseek-ai-dsh-output-retention/understand-the-implementation/the-read-render-exclusion:
+  en: f76b67fa9e940705
+  zh: e7731bfd31cc9f5c
+/deepseek-ai-dsh-output-retention/further-exploration:
+  en: 32497c10ffb10c75
+  zh: 1176c882cbed93c0
+/deepseek-ai-dsh-output-retention/model-experience:
+  en: 247cdeeae9390244
+  zh: 0720d77e0a1d1c15
+/deepseek-ai-dsh-output-retention/model-experience/kv-cache-effect:
+  en: 4487c456cf996b48
+  zh: 2c25fe4a5a53f345
+/deepseek-ai-dsh-output-retention/known-limitations-and-deferred-work:
+  en: 34e646397df5e681
+  zh: 344609df5eb0c4fa
+/deepseek-ai-dsh-output-retention/known-limitations-and-deferred-work/dev-note:
+  en: e67f633dc6fe7773
+  zh: 3bb0c20c93f16f98

package/README.md

@@ -9,7 +9,7 @@ English | [中文](README.zh.md)
 
 ## Summary
 
-Use `dsh-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`.
+Use `dsh-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. `truncateWithoutSplittingSurrogatePair` caps a character-budget preview without leaving a lone high surrogate at the cut. 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
 
@@ -74,6 +74,10 @@ const footer = formatRetentionNotice(
 
 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.
 
+### Capping a character-budget preview
+
+`truncateWithoutSplittingSurrogatePair` caps a preview measured in UTF-16 code units. A cut that lands inside a surrogate pair drops the unpaired half instead of returning a lone high surrogate, so the kept text stays a prefix. The persistent `bash` and `pwsh` shells and `str_replace_editor` use it for their character-budget previews; each still owns its truncation notice and its `incomplete` prefix.
+
 ### 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`.
@@ -104,7 +108,7 @@ The library is built on one separation: it owns the mechanical question of what
 
 | File | Role |
 |---|---|
-| [`src/index.ts`](src/index.ts) | `ItemRetainer`, `TextRetainer`, `describeOmitted`, and `formatRetentionNotice` |
+| [`src/index.ts`](src/index.ts) | `ItemRetainer`, `TextRetainer`, `describeOmitted`, `formatRetentionNotice`, and `truncateWithoutSplittingSurrogatePair` |
 | — | No runtime invariant companion is published; this pure utility owns no event stream or mutable runtime data; its value algebra is enforced by unit tests. |
 
 ### Two retainers, two resource models
@@ -151,7 +155,7 @@ No direct invalidation; the retention consumers own any request-prefix changes.
 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.
+- **Text retention is byte-oriented** — `TextRetainer` counts bytes; character-budget head caps go through `truncateWithoutSplittingSurrogatePair`, and line windows such as `read` pagination still require a separate renderer. A cut may discard partial UTF-8 boundary bytes to keep the returned text valid.
 
 <a id="dev-note"></a>
 ### Dev Note

package/README.zh.md

@@ -9,7 +9,7 @@ kind: "package-library"
 
 ## 概述
 
-使用 `dsh-output-retention` 限制工具返回给模型的项或文本量，并报告省略了什么。`ItemRetainer` 保留有序的头部窗口，并可报告精确的省略项数；`TextRetainer` 保留 head、tail 或 head-and-tail 字节窗口，且不会返回因切割而无效的 UTF-8。`formatRetentionNotice` 添加一致的省略子句，各工具则提供自己的恢复指引。分组、行号、spill 文件与提供方错误仍归工具负责；消费方直接导入本库，而不通过 `cordis.yml` 加载。
+使用 `dsh-output-retention` 限制工具返回给模型的项或文本量，并报告省略了什么。`ItemRetainer` 保留有序的头部窗口，并可报告精确的省略项数；`TextRetainer` 保留 head、tail 或 head-and-tail 字节窗口，且不会返回因切割而无效的 UTF-8。`formatRetentionNotice` 添加一致的省略子句，各工具则提供自己的恢复指引。`truncateWithoutSplittingSurrogatePair` 按字符预算截断预览时，不会在切口留下孤立的高位代理项。分组、行号、spill 文件与提供方错误仍归工具负责；消费方直接导入本库，而不通过 `cordis.yml` 加载。
 
 ## 目录
 
@@ -74,6 +74,10 @@ const footer = formatRetentionNotice(
 
 库负责标准化省略子句（`Omitted 3 items.`）并把它与工具自有的恢复指引拼接；只有工具知道恢复动作，因此这些措辞由工具提供。
 
+### 按字符预算截断预览
+
+`truncateWithoutSplittingSurrogatePair` 按 UTF-16 码元限制预览文本。切口落在代理对内部时丢弃不成对的半个码元，而不是返回孤立高位代理项，因此保留文本仍是前缀。持久 `bash`、`pwsh` 与 `str_replace_editor` 用它处理各自的字符预算预览；截断提示与 `incomplete` 前缀仍由各工具自行负责。
+
 ### `truncated` 意味着什么
 
 `truncated` 是预算事实：retainer 因上限而省略了本可获得的内容。它绝不表示上游不完整——权限失败、跳过二进制文件、提供方部分失败与不可读候选项都留在工具领域字段中，绝不并入 `truncated`。
@@ -104,7 +108,7 @@ const footer = formatRetentionNotice(
 
 | 文件 | 职责 |
 |---|---|
-| [`src/index.ts`](src/index.ts) | `ItemRetainer`、`TextRetainer`、`describeOmitted` 与 `formatRetentionNotice` |
+| [`src/index.ts`](src/index.ts) | `ItemRetainer`、`TextRetainer`、`describeOmitted`、`formatRetentionNotice` 与 `truncateWithoutSplittingSurrogatePair` |
 | — | 不发布运行时不变式伴生入口；这个纯工具不拥有事件流或可变运行时数据；其值代数由单元测试保证。 |
 
 ### 两个 retainer，两种资源模型
@@ -151,7 +155,7 @@ const footer = formatRetentionNotice(
 这些限制说明 retainer 刻意不覆盖什么。它们是当前包约束，不是任务积压。
 
 - **项保留只支持 `head`**——tail、head/tail、分页、分组与提供方完整性语义仍归工具所有。
-- **文本保留面向字节**——`read` 分页等行窗口与字符窗口需要单独的渲染器；切割可能丢弃部分 UTF-8 边界字节，以保持返回文本有效。
+- **文本保留面向字节**——`TextRetainer` 以字节计数；字符预算的头部截断走 `truncateWithoutSplittingSurrogatePair`，`read` 分页等行窗口仍需独立渲染器；切割可能丢弃部分 UTF-8 边界字节，以保持返回文本有效。
 
 <a id="dev-note"></a>
 ### 开发备注

package/lib/index.js

@@ -281,5 +281,21 @@ function describeOmitted(omitted, unit) {
 function formatRetentionNotice(notice, recovery) {
 	return [describeOmitted(notice.omitted, notice.unit), recovery(notice)].filter((part) => part.length > 0).join(" ");
 }
+/**
+* Cap `text` at `maxChars` UTF-16 code units without introducing a lone high
+* surrogate: a cut that lands inside a surrogate pair drops the unpaired half,
+* so the result is one code unit shorter than the cap. An unpaired surrogate is
+* not well-formed text — a strict JSON reader rejects a durable Session log that
+* carries one. An unpaired surrogate `text` already carries is not repaired here.
+*
+* @param text The text to cap.
+* @param maxChars The maximum number of UTF-16 code units to retain.
+* @returns A prefix of `text` no longer than `maxChars`; the cut never introduces a lone high surrogate.
+*/
+function truncateWithoutSplittingSurrogatePair(text, maxChars) {
+	if (text.length <= maxChars) return text;
+	const capped = text.slice(0, maxChars);
+	return /[\uD800-\uDBFF]$/.test(capped) ? capped.slice(0, -1) : capped;
+}
 //#endregion
-export { ItemRetainer, TextRetainer, describeOmitted, formatRetentionNotice };
+export { ItemRetainer, TextRetainer, describeOmitted, formatRetentionNotice, truncateWithoutSplittingSurrogatePair };

package/lib/types/index.d.ts

@@ -222,4 +222,16 @@ export declare function describeOmitted(omitted: Omitted, unit: RetentionNotice[
  * @returns The combined footer line.
  */
 export declare function formatRetentionNotice(notice: RetentionNotice, recovery: (notice: RetentionNotice) => string): string;
+/**
+ * Cap `text` at `maxChars` UTF-16 code units without introducing a lone high
+ * surrogate: a cut that lands inside a surrogate pair drops the unpaired half,
+ * so the result is one code unit shorter than the cap. An unpaired surrogate is
+ * not well-formed text — a strict JSON reader rejects a durable Session log that
+ * carries one. An unpaired surrogate `text` already carries is not repaired here.
+ *
+ * @param text The text to cap.
+ * @param maxChars The maximum number of UTF-16 code units to retain.
+ * @returns A prefix of `text` no longer than `maxChars`; the cut never introduces a lone high surrogate.
+ */
+export declare function truncateWithoutSplittingSurrogatePair(text: string, maxChars: number): string;
 //# sourceMappingURL=index.d.ts.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/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.7-alpha.2",
+  "version": "0.1.7-rc.2",
   "publishConfig": {
     "access": "public"
   },