@crazx/dsh-compaction-basic 0.1.5-alpha.1.zw.2 → 0.1.5-rc.1.zw.1

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # 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/compaction/compaction-basic/README.md
-README.md: d70bc758c5bba4a9791a1f5017beb80783b1017e
-README.zh.md: 086dc4a49d423daa661a0521e50be51db8db7872
+README.md: 03fe2811a94ea128fffbd3a6b4678b6d944fc1d9
+README.zh.md: 2a5f9562d5ff30c97129e5a880d25bedc45bcd82

package/README.md

@@ -9,7 +9,7 @@ English | [中文](README.zh.md)
 
 ## Summary
 
-This package keeps long agent conversations working near the model's context limit. As token pressure builds, it condenses the oldest history into a summary while preserving recent messages; after a context-overflow error, it condenses and retries. You can also request condensation with `/compact` and optionally trim oversized tool outputs first. Fitting input uses one extra model request; oversized input uses bounded hierarchical map-reduce calls, and only the final summary text is retained. It cannot reduce the system prompt, tools, or session prefix, or split one indivisible unit such as a single huge tool call.
+This package keeps long agent conversations working near the model's context limit. As token pressure builds, it condenses the oldest history into a summary while preserving recent messages; after a context-overflow error, it condenses and retries. You can also request condensation with `/compact` and optionally trim oversized tool outputs first. Condensation uses one extra model request and retains only its summary text. It cannot reduce the system prompt, tools, or session prefix, or split one indivisible unit such as a single huge tool call.
 
 ## Table of Contents
 
@@ -109,7 +109,7 @@ The backend is built on four commitments:
 
 - **One measurement service prices every decision.** The singleton `ctx.tokenMeter` measures the latest canonical logged envelope and current surface at one consumed-log revision. When the routed adapter declares request-image pricing, the meter applies it to image history. Pressure, recent-tail retention, range selection, and shrink validation use the same route-priced node figures; logged replacement shadow prices stay on the route-independent heuristic so pure projection folds remain consistent.
 - **The log-recorded bracket is the transaction.** All entry points share one bracket-first region transaction: validate the range and live lock, append `compaction/start` synchronously, prepare and await the summary, revalidate, append `compaction/summary` plus the replacement, and make exactly one closing attempt. Automatic and explicit-region calls require a numeric open-turn owner and whole-surface stability; `compactNow()` reserves idle admission, uses `turn: null`, accepts append-only context outside its selected span, flushes every closed attempt, and releases admission in `finally`.
-- **Summarization preserves the cache-reusing fast path and bounds oversized work.** A fitting one-shot replays the system prompt held by the `system/message` at surface node 0, the last routed request's tools, and the shadowed-region messages byte-for-byte. Hierarchical calls replay that same fixed system head exactly once while bounding chronological map spans and recursive reductions.
+- **Summarization reuses the provider's warm prefix.** Replaying the system prompt held by the `system/message` at surface node 0, the last routed request's tools, and the shadowed-region messages byte-for-byte makes the auxiliary call a genuine prefix of the conversation, so only the trailing instruction and the summary output are uncached.
 - **`summarize()` is the sole subclass hook.** A template- or remote-summarizer subclass can override it while pressure, retention, cited source events, shrink validation, and shadowed-token accounting stay on the token meter.
 
 ### Automatic triggers and overflow recovery
@@ -120,7 +120,7 @@ Pressure policy resolves capacity from the adapter that owns the durable route.
 
 ### Summarization mechanics
 
-A direct `ctx.llm.stream()` call uses the configured provider/model pair and cap, falling back to the latest logged request target and then the `AgentOptions` pair, without running the loop-only `agent/request` extension point. When the complete request fits, the call replays the derived `system/message` at surface node 0 as the leading entry of `messages`, followed by the shadowed-region messages (including a shadowed in-history `system/message` in its surface position), carries the header's tools verbatim, and appends the compaction instruction as the final user message. Oversized or Provider-rejected input is grouped into tool-balanced chronological map spans and recursively reduced; every map and reduce request replays the current non-empty system head exactly once as its first message, while later dynamic `system/message` entries remain ordinary chronological map input and are never promoted or deleted. The fixed-head, optional-tool, and instruction cost is included in every stage budget. Tool schemas accompany hierarchy calls only when `replayTools: true`. An empty-content system head contributes no message but remains outside the compacted range. Every call sets `GenerateOptions.purpose` to `compaction`; only returned text enters the checkpoint, excluding reasoning and tool calls. Image output fails with `UNSUPPORTED_CONTENT` rather than disappearing. The replacement user message frames the summary with `<compacted-summary>` tags; the raw final summary remains on the `compaction/summary` event.
+A direct `ctx.llm.stream()` call uses the configured provider/model pair and cap, falling back to the latest logged request target and then the `AgentOptions` pair, without running the loop-only `agent/request` extension point. The call replays the derived `system/message` at surface node 0 as the leading entry of `messages`, followed by the shadowed-region messages (including a shadowed in-history `system/message` in its surface position), and carries the header's tools verbatim — including image references, which the selected adapter must resolve or explicitly reject — and appends the compaction instruction as the final user message, so it reuses the provider's warm prefix cache instead of invalidating it. An empty-content system head contributes no message but remains outside the compacted range. The call sets `GenerateOptions.purpose` to `compaction`; only returned text enters the checkpoint, excluding reasoning and tool calls. Image output fails with `UNSUPPORTED_CONTENT` rather than disappearing. The replacement user message frames the summary with `<compacted-summary>` tags; the raw summary remains on the `compaction/summary` event.
 
 ### The region transaction
 
@@ -136,13 +136,10 @@ The transaction validates the surface span and the durable lock, appends `compac
 |---|---|
 | [`src/index.ts`](src/index.ts) | Plugin entry: `BasicCompactionEngine`, automatic listeners, entry-point dispatch |
 | [`src/region.ts`](src/region.ts) | Retention selection and the shared bracket-first compaction transaction |
-| [`src/summarizer.ts`](src/summarizer.ts) | Default `ctx.llm.stream()` one-shot summarization, checkpoint framing, safe-summary projection |
-| [`src/hierarchical.ts`](src/hierarchical.ts) | Bounded map-reduce fallback, adaptive splitting, stage usage aggregation |
-| [`src/hierarchical-planner.ts`](src/hierarchical-planner.ts) | Tool-balanced units and greedy token-budget planning |
-| [`src/hierarchical-prompts.ts`](src/hierarchical-prompts.ts) | Structured map/reduce prompts and output validation |
+| [`src/summarizer.ts`](src/summarizer.ts) | Default `ctx.llm.stream()` summarization, checkpoint framing, safe-summary projection |
 | [`src/config.ts`](src/config.ts) | Load-time validation and routed-model policy resolution |
 | [`src/types.ts`](src/types.ts) | `BasicCompactionConfig` and resolved policy vocabulary |
-| — | No runtime invariant companion is published; this package exposes no independent event sequence or mutable data relation beyond contracts enforced at its owning seam. |
+| — | No runtime invariant companion is published; this package exposes no independent event sequence or mutable data relation beyond contracts enforced at its owning seam. The durable bracket remains observable in the session log. |
 
 </details>
 
@@ -189,7 +186,7 @@ Replacing rather than append-only. Each checkpoint invalidates reuse from the fi
 
 #### What the model sees
 
-When the complete request fits, the summarization model receives the conversation replayed verbatim — the same system head, tool schemas, and messages the last routed request sent for the shadowed region — followed by one final user message: the compaction instruction below. For hierarchy, each map request receives the same system head exactly once, an ordered tool-balanced source span, and a structured map instruction; reduce requests receive that same head exactly once, ordered `<partial-summary>` frames, and a structured reduce instruction. Later system updates remain in their original map chronology instead of becoming a second fixed head. Tool schemas accompany hierarchy calls only when `replayTools: true`. The conversation model never sees these private requests or their reasoning; only the final text is stored.
+When the complete request fits, the summarization model receives the conversation replayed verbatim — the same system prompt, tool schemas, and messages the last routed request sent for the shadowed region — followed by one final user message: the compaction instruction below. For hierarchy, each map request receives the same system prompt, an ordered tool-balanced source span, and a structured map instruction; reduce requests receive ordered `<partial-summary>` frames and a structured reduce instruction. Tool schemas accompany hierarchy calls only when `replayTools: true`. The conversation model never sees these private requests or their reasoning; only the final text is stored.
 
 ##### Compaction instruction (final user message)
 
@@ -236,7 +233,7 @@ A fitting input costs one separate model call: the replayed conversation prefix
 
 #### KV Cache effect
 
-The fitting one-shot preserves the complete warm prefix through the shadowed region. Hierarchical calls preserve prefix reuse for the fixed system head and, when enabled, tool schemas; map payloads and reduction frames diverge after that shared prefix. Routing the summarizer to a different provider/model forgoes the conversation route's cache reuse.
+The fitting one-shot request matches the conversation's replayed system prompt, tools, and shadowed-region messages byte-for-byte, so the provider's warm prefix cache is reused up to the trailing instruction. Routing to another model or compacting a non-head range forgoes that reuse. Hierarchy intentionally bounds each call and therefore cannot preserve one full warm prefix: map calls may reuse their leading system/message prefix where the Provider permits, while reduce calls operate on newly generated partials. `replayTools: false` also omits the tool-schema prefix to leave more room for source messages.
 
 ## Known Limitations and Deferred Work
 
@@ -247,9 +244,9 @@ These limits define when automatic condensation is a poor fit or needs special c
 
 - **Meter accuracy follows the fixed heuristic** — missing reusable provider usage falls back to character count plus structural overhead rather than exact tokenization; image occurrences carry provider-exact visual tokens only on routes whose adapter declares request-image pricing.
 - **Overflow classification is adapter-maintained** — provider wording can change; both DeepSeek adapters normalize recognized context-limit failures to `CONTEXT_WINDOW_EXCEEDED`.
+- **Bounded recovery requires summary-model capacity metadata** — an adapter that omits `contextWindow` keeps the legacy one-shot path. If that request succeeds, behavior is unchanged; if it overflows, hierarchy cannot derive safe chunk budgets and fails with an actionable capacity error.
+- **Hierarchy output is a strict checkpoint protocol** — every map and reduce stage must return all required headings. Truncation, visual output, malformed structure, exhausted `maxDepth`, or an indivisible source/partial that still overflows fails the complete compaction transaction without installing a partial checkpoint.
 - **Some indivisible-unit and envelope-only overflow remains outside surface compaction** — recovery cannot shrink system/tools/prefix, split an indivisible non-tool node, or repair a tool unit whose non-prunable remainder still exceeds the window. The optional pruner can shrink text-bearing tool-result bulk inside an otherwise indivisible pair.
-- **Hierarchy requires declared summary-model capacity** — without a positive integer `contextWindow`, fitting input still uses one-shot summarization, but a confirmed one-shot overflow fails clearly because bounded chunk planning has no trustworthy window.
-- **Hierarchy is intentionally bounded** — a Provider-rejected indivisible tool-balanced span, fixed system/tools/instruction overhead that exhausts the stage budget, a reduction round that does not reduce partial count, or reaching `maxDepth` fails instead of looping.
 - **`compactRegion` requires an open turn** — a manual call on a fully-closed session throws ("no open turn") rather than compacting.
 - **Summarization failure preserves the latest durable surface** — before any replacement, the auto path logs a warning and proceeds with full over-budget history. If pruning already landed, a later summarization failure proceeds from that durable pruned surface. Summarization truncation at `maxTokens`, which hidden reasoning tokens can consume, follows the same rule.
 
@@ -262,7 +259,7 @@ These limits define when automatic condensation is a poor fit or needs special c
 This Dev Note is working context for maintainers and is explicitly non-authoritative; shipped behavior lives in the sections above, the package code, and the linked Agent Notes.
 
 - **Default ratios, undecided** — `thresholdRatio: 0.8` and `retainRatio: 0.16` are fixed defaults; per-model tuning via `modelPolicies` exists, but no corpus-backed guidance on ideal values is recorded.
-- **Tokenizer-accurate measurement, deferred** — the token meter's four-characters-per-token heuristic underprices CJK text and JSON schemas; exact tokenization remains an open direction for the measurement service.
+- **Tokenizer-accurate measurement, deferred** — the token meter's four-characters-per-token heuristic underprices CJK text and JSON Schema documents; exact tokenization remains an open direction for the measurement service.
 - **Overflow recovery beyond canonical errors, undecided** — recovery triggers on `CONTEXT_WINDOW_EXCEEDED` only; other provider-side context failures are not classified.
 
 </details>

package/README.zh.md

@@ -1,5 +1,5 @@
 ---
-description: "面向部署方的自动会话压缩：选择、调优或排查随 token 压力上升如何把较早历史摘要为总结。"
+description: "面向部署场景的自动会话压缩（compaction）：用于选择、调优或排查随 token 压力上升对较早历史进行摘要的方式。"
 kind: "package-reference"
 ---
 
@@ -9,7 +9,7 @@ kind: "package-reference"
 
 ## 概述
 
-本包让长时 agent 会话在接近模型上下文上限时仍能正常工作。token 压力上升时，它会把最旧的历史压缩为摘要并保留近期消息；上下文溢出错误发生后，它会压缩并重试。你也可以通过 `/compact` 按需压缩，并选择先修剪超大工具输出。能容纳的输入使用一次额外模型请求；超大输入使用有界层次 map-reduce 调用，并且只保留最终摘要文本。它无法缩减系统提示词、工具或会话前缀，也无法拆分单个不可分单元（例如一次超大工具调用）。
+本包让长时 agent（智能体）会话在接近模型上下文上限时仍能正常工作。token 压力上升时，它会把最旧的历史压缩为摘要并保留近期消息；上下文溢出错误发生后，它会压缩并重试。你也可以通过 `/compact` 按需压缩，并选择先修剪超大工具输出。压缩使用一次额外的模型请求，并且只保留该请求返回的摘要文本。它无法缩减系统提示词、工具或会话前缀，也无法拆分单个不可分单元（例如一次超大工具调用）。
 
 ## 目录
 
@@ -17,7 +17,7 @@ kind: "package-reference"
 - [理解实现](#understand-the-implementation)
 - [进一步探索](#further-exploration)
 - [模型体验](#model-experience)
-- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [已知限制与暂缓事项](#known-limitations-and-deferred-work)
 - [开发备注](#dev-note)
 
 -----
@@ -29,7 +29,7 @@ kind: "package-reference"
 
 ### 你会得到什么
 
-默认设置下你会获得四种行为：会话向模型上下文上限增长时自动压缩；提供方确认上下文溢出错误后的恢复（先压缩再重试该请求）；通过 `/compact` 命令按需压缩；以及——挂载修剪器时——压缩前对超大工具输出的修剪。能放入摘要模型窗口的输入保留复用 cache 的 one-shot 路径；超大输入或提供方拒绝的输入回退到有界时序 map-reduce。
+默认设置下你会获得四种行为：会话向模型上下文上限增长时自动压缩；提供方确认上下文溢出错误后的恢复（先压缩再重试该请求）；通过 `/compact` 命令按需压缩；以及——挂载修剪器时——压缩前对超大工具输出的修剪。
 
 ### 最小可用组合
 
@@ -71,11 +71,11 @@ kind: "package-reference"
 | `maxTokens` | `8192` | 摘要请求的输出上限；可包含推理 token。 |
 | `compactionRetries` | `1` | 压力仍高于阈值时，在首次压缩后进行的额外尝试次数。 |
 | `maxOverflowRetries` | `1` | 已确认上下文窗口溢出后的最大重试次数；`0` 只禁用恢复。 |
-| `chunkInputRatio` | `0.6` | 每个层次阶段输入可使用的摘要模型窗口比例；有效范围为 `[0.1, 0.9]`。 |
+| `chunkInputRatio` | `0.6` | 每个层次阶段输入可用的摘要模型窗口比例；有效范围 `[0.1, 0.9]`。 |
 | `mapMaxTokens` | `4096` | 单次层次 map 调用的提供方生成上限。 |
 | `reduceMaxTokens` | `8192` | 单次层次 reduce 调用的提供方生成上限。 |
-| `maxDepth` | `4` | 最大递归 reduce 轮数；有效范围为 `1..8`。 |
-| `replayTools` | `false` | 在层次阶段重放工具 schema。严格提供方可能需要启用它，但它会占用分块输入并降低前缀复用。 |
+| `maxDepth` | `4` | 递归 reduce 轮次上限；有效范围 `1..8`。 |
+| `replayTools` | `false` | 在层次阶段回放工具 schema。严格提供方可能需要打开此项，但会占用 chunk 输入并降低前缀复用。 |
 | `modelPolicies` | `[]` | 针对个别模型路由的精确 `{ provider, model, ...partialPolicy }` 覆盖。 |
 | `auto` | `true` | 启用自动压缩与溢出恢复；设为 `false` 则仅手动执行。 |
 
@@ -109,18 +109,18 @@ kind: "package-reference"
 
 - **一个测量服务为每个决策定价。** 单例 `ctx.tokenMeter` 会在同一个已消费日志 revision 上测量最新规范已记录 envelope 与当前表层。路由适配器声明请求图片定价时，meter 会将其应用于图片历史。压力、近期尾部保留、范围选择与缩减验证使用同一套路由定价的节点数值；已记录的替换影子价仍使用与路由无关的启发式规则，使纯投影 fold 保持一致。
 - **日志记录的标记对就是事务。** 所有入口点共享一个先记录标记的区域事务：验证范围与活动锁，同步追加 `compaction/start`，准备并等待摘要，重新验证，再追加 `compaction/summary` 与替换，最后恰好进行一次闭合尝试。自动调用与显式范围调用要求数字标识的开放轮次归属与整个表层稳定；`compactNow()` 会预留空闲接纳，使用 `turn: null`，允许所选 span 之外追加仅追加上下文，flush 每次已闭合尝试，并在 `finally` 中释放接纳预留。
-- **摘要保留复用 cache 的快速路径，并约束超大工作。** 能容纳的 one-shot 会逐字回放 surface 节点 0 处 `system/message` 所承载的系统提示词、上次已路由请求的工具与已遮蔽区域消息。层次调用会恰好一次重放同一个固定 system head，同时约束时序 map span 与递归 reduce。
+- **摘要复用提供方的热前缀。** 逐字回放 surface 节点 0 处 `system/message` 所承载的系统提示词、上次已路由请求的工具与已遮蔽区域消息，使辅助调用成为会话的真正前缀，因此只有尾随指令与摘要输出未缓存。
 - **`summarize()` 是唯一的子类钩子。** 基于模板或远程摘要器的子类可以覆盖它，同时压力、保留、被引用的源事件、缩减验证与已遮蔽 token 计量仍由 token meter 负责。
 
 ### 自动触发与溢出恢复
 
-当 `auto: true` 时，串行 `agent/pre-step` listener 会在请求派生前检查压力：它通过 `ctx.tokenMeter` 为最新持久路由请求 envelope 定价，当压力越过路由模型的阈值时，先剪枝，再在保留已定价近期尾部的同时摘要最旧的平衡范围。每个选定范围都从第一个不是 `system/message` 的 surface 节点开始，因此位于 surface 节点 0 的系统提示词永不会被遮蔽；由历史内提示词更新追加的后续 `system/message` 是普通历史，范围可以遮蔽它，agent loop 的投影随后会在二者文本不同时用当前提示词替换节点 0（[决策规则](../../core/agent-loop/README.zh.md#understand-the-implementation)）。`agent/request-error` listener 响应提供方确认的 `CONTEXT_WINDOW_EXCEEDED`：它绕过常规阈值与保留策略，尝试一次最大平衡头部缩减，并且只在表层替换 generation 前进后才授权重试。取消全程保持最终决定权。
+当 `auto: true` 时，串行 `agent/pre-step` listener 会在请求派生前检查压力：它通过 `ctx.tokenMeter` 为最新持久路由请求 envelope 定价，当压力越过路由模型的阈值时，先剪枝，再在保留已定价近期尾部的同时摘要最旧的平衡范围。每个选定范围都从第一个不是 `system/message` 的 surface 节点开始，因此位于 surface 节点 0 的系统提示词永不会被遮蔽；由历史内提示词更新追加的后续 `system/message` 是普通历史，范围可以遮蔽它，agent loop（智能体循环）的投影随后会在二者文本不同时用当前提示词替换节点 0（[决策规则](../../core/agent-loop/README.zh.md#understand-the-implementation)）。`agent/request-error` listener 响应提供方确认的 `CONTEXT_WINDOW_EXCEEDED`：它绕过常规阈值与保留策略，尝试一次最大平衡头部缩减，并且只在表层替换 generation 前进后才授权重试。取消全程保持最终决定权。
 
 压力策略从拥有持久路由的适配器解析容量。适配器无法为有效动态路由返回容量时，手动压力路径会抛出目标特定配置错误；自动 listener 会对该精确目标警告一次，并携带完整历史继续。
 
 ### 摘要机制
 
-直接 `ctx.llm.stream()` 调用使用已配置的提供方／模型对与上限，回退到最新已记录请求目标，然后再回退到 `AgentOptions` 对，而不运行仅用于 agent loop 的 `agent/request` 扩展点。完整请求能容纳时，该调用将 surface 节点 0 处派生的 `system/message` 作为 `messages` 的首项回放，后接已遮蔽区域消息（包括位于其 surface 位置的被遮蔽历史内 `system/message`），逐字携带 header 的工具，并将压缩指令作为最后一条 user 消息追加。超大输入或提供方拒绝的输入会被组合成工具配对平衡的时序 map span，再递归 reduce；每个 map 与 reduce 请求都把当前非空 system head 恰好一次作为首条消息重放，后续动态 `system/message` 仍是普通时序 map 输入，绝不会被提升或删除。每阶段预算都包含固定 head、可选工具与指令成本。只有 `replayTools: true` 时，工具 schema 才随层次调用发送。空内容系统头节点不贡献消息，但仍处于压缩范围之外。每次调用都将 `GenerateOptions.purpose` 设为 `compaction`；只有返回文本进入检查点，推理与工具调用都会被排除。图片输出会以 `UNSUPPORTED_CONTENT` 失败，而不是消失。替换 user 消息用 `<compacted-summary>` 标签框定摘要；最终原始摘要保留在 `compaction/summary` 事件上。
+直接 `ctx.llm.stream()` 调用使用已配置的提供方／模型对与上限，回退到最新已记录请求目标，然后再回退到 `AgentOptions` 对，而不运行仅用于 agent loop 的 `agent/request` 扩展点。该调用将 surface 节点 0 处派生的 `system/message` 作为 `messages` 的首项回放，后接已遮蔽区域消息（包括位于其 surface 位置的被遮蔽历史内 `system/message`），并逐字携带 header 的工具——包括所选适配器必须解析或明确拒绝的图片引用——并将压缩指令作为最后一条 user 消息追加，从而复用提供方的热前缀 cache，而非使它失效。空内容系统头节点不贡献消息，但仍处于压缩范围之外。调用将 `GenerateOptions.purpose` 设为 `compaction`；只有返回文本进入检查点，推理与工具调用都会被排除。图片输出会以 `UNSUPPORTED_CONTENT` 失败，而不是消失。替换 user 消息用 `<compacted-summary>` 标签框定摘要；原始摘要保留在 `compaction/summary` 事件上。
 
 ### 区域事务
 
@@ -136,13 +136,10 @@ kind: "package-reference"
 |---|---|
 | [`src/index.ts`](src/index.ts) | 插件入口：`BasicCompactionEngine`、自动 listener、入口点分发 |
 | [`src/region.ts`](src/region.ts) | 保留选择与共享的先记录标记压缩事务 |
-| [`src/summarizer.ts`](src/summarizer.ts) | 默认 `ctx.llm.stream()` one-shot 摘要、检查点框定、安全摘要投影 |
-| [`src/hierarchical.ts`](src/hierarchical.ts) | 有界 map-reduce 回退、自适应拆分与阶段用量聚合 |
-| [`src/hierarchical-planner.ts`](src/hierarchical-planner.ts) | 工具配对平衡单元与贪心 token 预算规划 |
-| [`src/hierarchical-prompts.ts`](src/hierarchical-prompts.ts) | 结构化 map/reduce 提示词与输出验证 |
+| [`src/summarizer.ts`](src/summarizer.ts) | 默认 `ctx.llm.stream()` 摘要、检查点框定、安全摘要投影 |
 | [`src/config.ts`](src/config.ts) | 加载时验证与路由模型策略解析 |
 | [`src/types.ts`](src/types.ts) | `BasicCompactionConfig` 与已解析策略词汇 |
-| — | 不发布运行时不变式伴生入口；持久标记对可在会话日志中观察。 |
+| — | 不发布运行时不变式配套条目；除所属 seam 强制执行的约定外，本包不公开独立事件序列或可变数据关系。持久标记对仍可在会话日志中观察。 |
 
 </details>
 
@@ -189,7 +186,7 @@ This is an automatically generated checkpoint condensing an earlier span of the
 
 #### 模型看到的内容
 
-完整请求能容纳时，摘要模型会接收逐字回放的会话：与上次已路由请求为已遮蔽区域发送的相同 system head、工具 schema 与消息，后面跟随一条最终 user 消息，即下方压缩指令。层次模式下，每个 map 请求接收恰好一次相同 system head、一个有序且工具配对平衡的源 span，以及结构化 map 指令；reduce 请求接收恰好一次相同 head、有序 `<partial-summary>` frame 和结构化 reduce 指令。后续 system 更新保留在原始 map 时序中，不会成为第二个固定 head。只有 `replayTools: true` 时，工具 schema 才随层次调用发送。会话模型绝不会看到这些私有请求或其推理；只有最终返回文本会被存储。
+摘要模型会接收逐字回放的会话：与上次已路由请求为已遮蔽区域发送的相同系统提示词、工具 schema 与消息，后面跟随一条最终 user 消息，即下方压缩指令。会话模型绝不会看到该私有请求或其推理；只有返回文本会被存储。
 
 ##### 压缩指令（最终 user 消息）
 
@@ -232,13 +229,13 @@ Rules:
 
 #### Token 影响
 
-能容纳的输入会产生一次独立模型调用：输入是已回放会话前缀加固定指令，输出受 `maxTokens` 限制。层次模式每个 map span 调用一次模型，再进行一次或多次 reduce，分别受 `mapMaxTokens` 与 `reduceMaxTokens` 限制；提供方确认的 overflow 可能在本地二分前增加失败尝试。收敛重试可能多次支付任一种成本。
+这是一次独立模型调用：输入是已回放会话前缀加固定指令，输出受 `maxTokens` 限制。收敛重试可能多次支付这项成本。
 
 #### KV Cache 影响
 
-能容纳的 one-shot 会保留穿过已遮蔽区域的完整热前缀。层次调用会保留固定 system head，以及启用时工具 schema 的前缀复用；map payload 与 reduce frame 会在该共享前缀之后分叉。将摘要器路由到不同提供方／模型会放弃会话路由的 cache 复用。
+已回放系统提示词、工具与已遮蔽区域消息与会话最后一个已路由请求逐字匹配，因此提供方的热前缀 cache 可复用至尾随指令之前；只有该指令与摘要输出未缓存。将摘要器路由到不同提供方／模型，或压缩非头部范围，都会放弃该复用。
 
-## 已知限制与延期工作
+## 已知限制与暂缓事项
 
 <a id="known-limitations-and-deferred-work"></a>
 
@@ -247,9 +244,9 @@ Rules:
 
 - **计量准确度取决于固定启发式规则**——可复用提供方用量缺失时，会回退到字符数加结构开销，而非精确的 token 化；只有在适配器声明了请求图片定价的路由上，图片出现处才携带提供方精确的视觉 token。
 - **溢出分类由适配器维护**——提供方措辞可能改变；两个 DeepSeek 适配器将可识别的上下文限制失败规范化为 `CONTEXT_WINDOW_EXCEEDED`。
+- **有界恢复需要摘要模型的容量元数据**——省略 `contextWindow` 的适配器继续走旧的一次性路径。该请求成功则行为不变；若溢出，层次无法推导安全 chunk 预算，并以可操作的容量错误失败。
+- **层次输出是严格的检查点协议**——每个 map 与 reduce 阶段必须返回全部必需标题。截断、视觉输出、结构畸形、耗尽 `maxDepth`，或仍溢出的不可分源／部分摘要，都会让整次压缩事务失败，不安装部分检查点。
 - **部分不可分单元与仅 envelope 溢出仍不在表层压缩范围内**——恢复无法缩减系统／工具／前缀、拆分不可分的非工具节点，或修复不可剪枝剩余部分仍超出窗口的工具单元。可选 pruner 可以缩减原本不可分工具对内的文本型工具结果主体。
-- **层次模式要求声明摘要模型容量**——没有正整数 `contextWindow` 时，能容纳的输入仍可 one-shot 摘要；但 one-shot 被确认 overflow 后会清晰失败，因为有界分块规划没有可信窗口。
-- **层次模式刻意有界**——提供方拒绝不可分的工具配对平衡 span、固定 system／tools／instruction 开销耗尽阶段预算、reduce 轮次未减少 partial 数量，或达到 `maxDepth` 时都会失败，而不会循环。
 - **`compactRegion` 要求存在未结束的轮次**——在完全关闭的会话上手动调用会抛出异常（「no open turn」），而不是执行压缩。
 - **摘要失败会保留最新持久表层**——任何替换前，自动路径会记录警告，并携带完整超预算历史继续。如果剪枝已落地，后续摘要失败会从该持久剪枝表层继续。因达到 `maxTokens` 而发生的摘要截断（隐藏推理 token 可能会耗尽该额度）遵循同一规则。
 
@@ -262,7 +259,7 @@ Rules:
 本开发备注是维护者的工作上下文，明确不具权威性；已交付行为以上文、包代码与所链接的 Agent Note 为准。
 
 - **默认比例，尚未决定**——`thresholdRatio: 0.8` 与 `retainRatio: 0.16` 是固定默认值；存在通过 `modelPolicies` 进行的按模型调优，但没有基于语料的理想值指引记录。
-- **tokenizer 精确测量，暂缓**——token meter 每 token 四字符的启发式对 CJK 文本与 JSON schema 定价偏低；精确 token 化仍是测量服务的开放方向。
+- **tokenizer 精确测量，暂缓**——token meter 每 token 四字符的启发式对 CJK 文本与 JSON Schema 定价偏低；精确 token 化仍是测量服务的开放方向。
 - **规范错误之外的溢出恢复，尚未决定**——恢复仅针对 `CONTEXT_WINDOW_EXCEEDED` 触发；其他提供方侧上下文失败不参与分类。
 
 </details>

package/lib/index.js

@@ -344,7 +344,7 @@ async function summarizeWithLlm(ctx, config, input, agent, signal) {
 		...signal === void 0 ? {} : { signal }
 	};
 	for await (const chunk of ctx.llm.stream(options)) assembler.push(chunk);
-	const error = finishError(assembler.finish);
+	const error = finishError$1(assembler.finish);
 	if (error !== void 0) throw error;
 	const rawOutput = assembler.blocks();
 	const summary = summaryText(rawOutput);
@@ -377,12 +377,8 @@ function frameSummary(summary) {
 		}
 	];
 }
-/**
-* Map a terminal summarization finish to its fail-closed error.
-* @param finish - terminal stream finish emitted by the summary request.
-* @returns the corresponding error, or `undefined` for a complete stop.
-*/
-function finishError(finish) {
+/** Map a terminal summarization finish to its fail-closed error. */
+function finishError$1(finish) {
 	switch (finish.kind) {
 		case "error":
 		case "aborted": {
@@ -398,11 +394,7 @@ function finishError(finish) {
 		default: return;
 	}
 }
-/**
-* Reject visual output and keep only text before synthesizing a user message.
-* @param blocks - raw content blocks emitted by the summary request.
-* @returns the text-only blocks safe to persist as a compaction checkpoint.
-*/
+/** Reject visual output and keep only text before synthesizing a user message. */
 function summaryText(blocks) {
 	if (contentHasImage(blocks)) throw new LlmError("compaction summary cannot contain image output", "UNSUPPORTED_CONTENT");
 	return blocks.filter((block) => block.type === "text");
@@ -1002,8 +994,7 @@ var HierarchicalSummarizer = class {
 		/* v8 ignore next -- LlmRuntime validates defined capacity before returning model info. */
 		if (!Number.isSafeInteger(contextWindow) || contextWindow < 1) throw new Error(`hierarchical compaction: no positive integer context capacity for summary target ${target.provider}/${target.model}`);
 		const estimate = (message) => this.ctx.tokenMeter.estimateMessage(message);
-		const replay = hierarchyReplay(input.messages);
-		const oneShotTokens = this.estimateCallInput(input, replay, COMPACTION_INSTRUCTION, true, estimate);
+		const oneShotTokens = this.estimateCallInput(input, COMPACTION_INSTRUCTION, true, estimate);
 		let hadFailedLlmAttempt = false;
 		if (oneShotTokens + target.oneShotMaxTokens <= contextWindow) try {
 			return await oneShot();
@@ -1013,10 +1004,11 @@ var HierarchicalSummarizer = class {
 		}
 		const inputBudget = Math.floor(contextWindow * this.hierarchy.chunkInputRatio);
 		this.assertStageOutputReserve(contextWindow, inputBudget, this.hierarchy.mapMaxTokens, "map");
-		const totalUnits = toolBalancedUnits(replay.sourceMessages).length;
-		const mapReserve = this.estimateFixedInput(input, replay.systemHead, mapInstruction(totalUnits, totalUnits, totalUnits), this.hierarchy.replayTools, estimate);
-		const mapMessageBudget = this.messageBudget(inputBudget, mapReserve, "map");
-		const chunks = planMessageChunks(replay.sourceMessages, mapMessageBudget, estimate);
+		const systemMessage = input.messages[0]?.role === "system" ? input.messages[0] : void 0;
+		const sourceMessages = systemMessage === void 0 ? input.messages : input.messages.slice(1);
+		const totalUnits = toolBalancedUnits(sourceMessages).length;
+		const mapReserve = this.estimateFixedInput(input, mapInstruction(totalUnits, totalUnits, totalUnits), this.hierarchy.replayTools, estimate);
+		const chunks = planMessageChunks(sourceMessages, this.messageBudget(inputBudget, mapReserve, "map"), estimate);
 		/* v8 ignore next -- stock range selection never submits an empty shadowed region. */
 		if (chunks.length === 0) throw new Error("hierarchical compaction: oversized input produced no map chunks");
 		const calls = [];
@@ -1028,7 +1020,10 @@ var HierarchicalSummarizer = class {
 			/* v8 ignore next -- the loop condition proves shift has an entry. */
 			if (span === void 0) break;
 			try {
-				const result = await this.runStage(input, span.messages, replay.systemHead, mapInstruction(span.start, span.end, totalUnits), target, this.hierarchy.mapMaxTokens, agent, signal);
+				const result = await this.runStage({
+					...input,
+					messages: systemMessage === void 0 ? span.messages : [systemMessage, ...span.messages]
+				}, mapInstruction(span.start, span.end, totalUnits), target, this.hierarchy.mapMaxTokens, agent, signal);
 				calls.push(result);
 				partials.push(this.partial(result, span.start, span.end, `map source units ${span.start}-${span.end}`));
 			} catch (error) {
@@ -1045,7 +1040,7 @@ var HierarchicalSummarizer = class {
 		let usedReduce = false;
 		for (let round = 1; partials.length > 1; round += 1) {
 			if (round > this.hierarchy.maxDepth) throw new Error(`hierarchical compaction: reduction did not converge within ${this.hierarchy.maxDepth} round(s)`);
-			const reduceReserve = this.estimateFixedInput(input, replay.systemHead, reduceInstruction(round, totalUnits, totalUnits, totalUnits), this.hierarchy.replayTools, estimate);
+			const reduceReserve = this.estimateFixedInput(input, reduceInstruction(round, totalUnits, totalUnits, totalUnits), this.hierarchy.replayTools, estimate);
 			const reduceMessageBudget = this.messageBudget(inputBudget, reduceReserve, `reduce round ${round}`);
 			let groups;
 			try {
@@ -1066,7 +1061,10 @@ var HierarchicalSummarizer = class {
 				/* v8 ignore next -- the loop condition proves shift has an entry. */
 				if (span === void 0) break;
 				try {
-					const result = await this.runStage(input, span.messages, replay.systemHead, reduceInstruction(round, span.start, span.end, totalUnits), target, this.hierarchy.reduceMaxTokens, agent, signal);
+					const result = await this.runStage({
+						...input,
+						messages: systemMessage === void 0 ? span.messages : [systemMessage, ...span.messages]
+					}, reduceInstruction(round, span.start, span.end, totalUnits), target, this.hierarchy.reduceMaxTokens, agent, signal);
 					calls.push(result);
 					next.push(this.partial(result, span.start, span.end, `reduce round ${round} source units ${span.start}-${span.end}`));
 				} catch (error) {
@@ -1190,12 +1188,13 @@ var HierarchicalSummarizer = class {
 		if (inputBudget + outputTokens > contextWindow) throw new Error(`hierarchical compaction: ${stage} input budget ${inputBudget} plus output reserve ${outputTokens} exceeds summary context ${contextWindow}`);
 	}
 	/** Price a complete auxiliary call input. */
-	estimateCallInput(input, replay, instruction, includeTools, estimate) {
-		return this.estimateFixedInput(input, replay.systemHead, instruction, includeTools, estimate) + estimateMessages(replay.sourceMessages, estimate);
+	estimateCallInput(input, instruction, includeTools, estimate) {
+		const sourceMessages = input.messages[0]?.role === "system" ? input.messages.slice(1) : input.messages;
+		return this.estimateFixedInput(input, instruction, includeTools, estimate) + estimateMessages(sourceMessages, estimate);
 	}
-	/** Price the repeated system head, optional tools, and final stage instruction. */
-	estimateFixedInput(input, systemHead, instruction, includeTools, estimate) {
-		return (systemHead === void 0 ? 0 : estimate(systemHead)) + (!includeTools || input.tools === void 0 || input.tools.length === 0 ? 0 : Math.ceil(JSON.stringify(input.tools).length / CHARS_PER_TOKEN) + ENVELOPE_OVERHEAD) + estimate(this.instructionMessage(instruction));
+	/** Price the repeated header and final instruction for one stage. */
+	estimateFixedInput(input, instruction, includeTools, estimate) {
+		return (input.messages[0]?.role === "system" ? estimate(input.messages[0]) : 0) + (!includeTools || input.tools === void 0 || input.tools.length === 0 ? 0 : Math.ceil(JSON.stringify(input.tools).length / CHARS_PER_TOKEN) + ENVELOPE_OVERHEAD) + estimate(this.instructionMessage(instruction));
 	}
 	/** Derive positive room for stage messages after fixed input. */
 	messageBudget(inputBudget, fixedTokens, stage) {
@@ -1204,17 +1203,13 @@ var HierarchicalSummarizer = class {
 		return budget;
 	}
 	/** Run one private map or reduce model call and require structured text. */
-	async runStage(input, messages, systemHead, instruction, target, maxTokens, agent, signal) {
+	async runStage(input, instruction, target, maxTokens, agent, signal) {
 		signal?.throwIfAborted();
 		const assembler = new BlockAssembler();
 		const options = {
 			provider: target.provider,
 			model: target.model,
-			messages: [
-				...systemHead === void 0 ? [] : [systemHead],
-				...messages,
-				this.instructionMessage(instruction)
-			],
+			messages: [...input.messages, this.instructionMessage(instruction)],
 			...this.hierarchy.replayTools && input.tools !== void 0 ? { tools: [...input.tools] } : {},
 			maxTokens,
 			sessionId: agent.session.id,
@@ -1225,7 +1220,8 @@ var HierarchicalSummarizer = class {
 		const finishFailure = finishError(assembler.finish);
 		if (finishFailure !== void 0) throw finishFailure;
 		const rawOutput = assembler.blocks();
-		const summary = summaryText(rawOutput);
+		if (contentHasImage(rawOutput)) throw new LlmError("hierarchical compaction summary cannot contain image output", "UNSUPPORTED_CONTENT");
+		const summary = rawOutput.filter((block) => block.type === "text");
 		validateStructuredSummary(summary, "hierarchical compaction stage");
 		return {
 			summary,
@@ -1265,15 +1261,6 @@ var HierarchicalSummarizer = class {
 		});
 	}
 };
-/** Separate the fixed surface system head from chronological source history. */
-function hierarchyReplay(messages) {
-	const [first, ...rest] = messages;
-	if (first?.role === "system") return {
-		systemHead: first,
-		sourceMessages: rest
-	};
-	return { sourceMessages: messages };
-}
 /** Build the terminal diagnostic for a provider-rejected atomic span. */
 function indivisibleOverflow(stage, cause) {
 	const error = new OversizedCompactionUnitError(`hierarchical compaction: ${stage} still exceeds the provider context window and is indivisible`, { cause });
@@ -1284,6 +1271,23 @@ function indivisibleOverflow(stage, cause) {
 function hasErrorCode(error, code) {
 	return typeof error === "object" && error !== null && "code" in error && error.code === code;
 }
+/** Map a terminal stage finish to a fail-closed error. */
+function finishError(finish) {
+	switch (finish.kind) {
+		case "error":
+		case "aborted": {
+			const error = new Error(finish.failure.message);
+			error.code = finish.failure.code;
+			return error;
+		}
+		case "max-tokens": {
+			const error = /* @__PURE__ */ new Error("hierarchical compaction stage truncated at the token cap");
+			error.code = "MAX_TOKENS";
+			return error;
+		}
+		default: return;
+	}
+}
 /**
 * Sum disjoint provider usage across every successful map and reduce call.
 * @param usages - stage usage values in call order.

package/lib/types/summarizer.d.ts

@@ -4,7 +4,7 @@
  * @module @deepseek-ai/dsh-compaction-basic/summarizer
  */
 import type { Context } from '@deepseek-ai/cordis';
-import type { ContentBlock, FinishReason, Message, TokenUsage, ToolSchema } from '@deepseek-ai/dsh-llm';
+import type { ContentBlock, Message, TokenUsage, ToolSchema } from '@deepseek-ai/dsh-llm';
 import type { Agent } from '@deepseek-ai/dsh-agent';
 interface SummaryConfig {
     readonly summarizationProvider: string;
@@ -68,19 +68,5 @@ export declare function summarizeWithLlm(ctx: Context, config: SummaryConfig, in
  * @returns content for the synthesized replacement user message.
  */
 export declare function frameSummary(summary: readonly ContentBlock[]): ContentBlock[];
-/**
- * Map a terminal summarization finish to its fail-closed error.
- * @param finish - terminal stream finish emitted by the summary request.
- * @returns the corresponding error, or `undefined` for a complete stop.
- */
-export declare function finishError(finish: FinishReason): Error | undefined;
-/**
- * Reject visual output and keep only text before synthesizing a user message.
- * @param blocks - raw content blocks emitted by the summary request.
- * @returns the text-only blocks safe to persist as a compaction checkpoint.
- */
-export declare function summaryText(blocks: readonly ContentBlock[]): Array<Extract<ContentBlock, {
-    type: 'text';
-}>>;
 export {};
 //# sourceMappingURL=summarizer.d.ts.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@crazx/dsh-compaction-basic",
   "description": "Token-meter-driven compaction policy and LLM summarization backend for the DeepSeek Harness",
-  "version": "0.1.5-alpha.1.zw.2",
+  "version": "0.1.5-rc.1.zw.1",
   "publishConfig": {
     "access": "public"
   },
@@ -28,13 +28,13 @@
   "license": "MIT",
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-agent": "^0.1.5-alpha.1",
-    "@deepseek-ai/dsh-commands": "^0.1.5-alpha.1",
-    "@deepseek-ai/dsh-compaction": "^0.1.5-alpha.1",
-    "@deepseek-ai/dsh-compaction-tool-result-pruner": "^0.1.5-alpha.1",
-    "@deepseek-ai/dsh-llm": "^0.1.5-alpha.1",
-    "@deepseek-ai/dsh-session": "^0.1.5-alpha.1",
-    "@deepseek-ai/dsh-token-meter": "^0.1.5-alpha.1"
+    "@deepseek-ai/dsh-agent": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-commands": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-compaction": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-compaction-tool-result-pruner": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-session": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-token-meter": "^0.1.5-rc.1"
   },
   "peerDependenciesMeta": {
     "@deepseek-ai/dsh-compaction-tool-result-pruner": {
@@ -42,25 +42,25 @@
     }
   },
   "dependencies": {
-    "@deepseek-ai/dsh-util-values": "^0.1.5-alpha.1",
+    "@deepseek-ai/dsh-util-values": "^0.1.5-rc.1",
     "@deepseek-ai/schemastery": "^3.18.2"
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "^4.0.2",
     "@deepseek-ai/cordis-plugin-include": "^1.0.7",
     "@deepseek-ai/cordis-plugin-loader": "^1.0.3",
-    "@deepseek-ai/dsh-agent": "^0.1.5-alpha.1",
-    "@deepseek-ai/dsh-agent-loop": "^0.1.5-alpha.1",
-    "@deepseek-ai/dsh-agent-loop-testkit": "^0.1.5-alpha.1",
-    "@deepseek-ai/dsh-commands": "^0.1.5-alpha.1",
-    "@deepseek-ai/dsh-compaction": "^0.1.5-alpha.1",
-    "@deepseek-ai/dsh-compaction-tool-result-pruner": "^0.1.5-alpha.1",
-    "@deepseek-ai/dsh-invariants": "^0.1.5-alpha.1",
-    "@deepseek-ai/dsh-llm": "^0.1.5-alpha.1",
-    "@deepseek-ai/dsh-llm-retry": "^0.1.5-alpha.1",
-    "@deepseek-ai/dsh-session": "^0.1.5-alpha.1",
-    "@deepseek-ai/dsh-session-projection": "^0.1.5-alpha.1",
-    "@deepseek-ai/dsh-token-meter": "^0.1.5-alpha.1",
-    "@deepseek-ai/dsh-tools": "^0.1.5-alpha.1"
+    "@deepseek-ai/dsh-agent": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-agent-loop": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-agent-loop-testkit": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-commands": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-compaction": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-compaction-tool-result-pruner": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-llm-retry": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-session": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-session-projection": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-token-meter": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-tools": "^0.1.5-rc.1"
   }
 }