@qilin-agent/compaction 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,85 @@
+# 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/compaction/compaction/README.md
+/:
+  en: 5c47c9629036f119
+  zh: 7730d7468a38b38d
+/qilin-compaction:
+  en: c840d0ca2fbd48b5
+  zh: 7f56057c5118fe46
+/qilin-compaction/summary:
+  en: 45df7ffaa893ddba
+  zh: bc09330e487a0822
+/qilin-compaction/table-of-contents:
+  en: d152484eb41ac6b4
+  zh: 09388d293f9be9cb
+/qilin-compaction/use-this-package:
+  en: 7d1dad97626dbd2e
+  zh: 075fef4e1844ad12
+/qilin-compaction/use-this-package/when-to-choose-it:
+  en: 5a17090293b8cfb0
+  zh: 6707423be7039a60
+/qilin-compaction/use-this-package/what-condensation-looks-like:
+  en: 0abbee3a3b929a90
+  zh: 334736dffe93488d
+/qilin-compaction/use-this-package/turning-condensation-on:
+  en: e551048815373de2
+  zh: bc08e4a0946a8d80
+/qilin-compaction/use-this-package/implementing-a-backend:
+  en: 8f4465774226630c
+  zh: cb5351816428e083
+/qilin-compaction/use-this-package/recognizing-condensed-history:
+  en: 6b698c775b41d3e5
+  zh: 333d2b86cc1d6eb0
+/qilin-compaction/understand-the-implementation:
+  en: 321c3dc665ea03ff
+  zh: f0fa408cde7b0454
+/qilin-compaction/understand-the-implementation/design-philosophy:
+  en: fc76a3dfe6dfb68a
+  zh: cee531777137932b
+/qilin-compaction/understand-the-implementation/service-api:
+  en: 0b9edbbf144e6973
+  zh: 6de6e6d920e70e96
+/qilin-compaction/understand-the-implementation/manual-failure-taxonomy:
+  en: f139df949cf288ea
+  zh: 51ab9f127578cf75
+/qilin-compaction/understand-the-implementation/tool-pairing-boundaries:
+  en: 15dad68a04d6c86b
+  zh: 3b95acf1b7e503bf
+/qilin-compaction/understand-the-implementation/the-surface-contract:
+  en: 8606610465cf1d5e
+  zh: 5dad56458947e548
+/qilin-compaction/understand-the-implementation/source-map:
+  en: ca0a8b4b73e2556f
+  zh: 1b671f96fb217d5e
+/qilin-compaction/understand-the-implementation/locking-and-serialization:
+  en: 68caa51bed28bada
+  zh: 3f8261f9dcba95ed
+/qilin-compaction/understand-the-implementation/events:
+  en: c972fe7e246ac3e0
+  zh: 69c7b92eaf8d0e44
+/qilin-compaction/further-exploration:
+  en: 30ce8988a71dceec
+  zh: 03b615969099762d
+/qilin-compaction/model-experience:
+  en: 215e7ba838619b7b
+  zh: a311da3843709f90
+/qilin-compaction/model-experience/conversation-history-when-a-backend-is-invoked:
+  en: 94de97ed1e85db85
+  zh: c8e37d8050609e63
+/qilin-compaction/model-experience/conversation-history-when-a-backend-is-invoked/what-the-model-sees:
+  en: 3c4875a13da17814
+  zh: 9b257950a9e2c7c1
+/qilin-compaction/model-experience/conversation-history-when-a-backend-is-invoked/token-effect:
+  en: be91f4a4bbb9338b
+  zh: 2b5de31d4d7caff1
+/qilin-compaction/model-experience/conversation-history-when-a-backend-is-invoked/kv-cache-effect:
+  en: 40ba838a2309c44a
+  zh: c609fc1587a0d666
+/qilin-compaction/known-limitations-and-deferred-work:
+  en: fee9ba06d3e5f35c
+  zh: 2bb5241e2447d15d
+/qilin-compaction/known-limitations-and-deferred-work/dev-note:
+  en: 270e23ae6414aff0
+  zh: c6d219b8a547dbca

package/README.md

@@ -1,3 +1,175 @@
-# Temporary Holding Version
+---
+description: "Shared compaction contract for backend implementers and deployers: what conversation condensation does, when to use it, and how to build a backend."
+kind: "package-reference"
+---
 
-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/compaction
+
+English | [中文](README.zh.md)
+
+## Summary
+
+`qilin-compaction` lets a long session condense its older history into a single summary message, keep the recent conversation intact, and continue as if the summary had always been there — with a backend such as `qilin-compaction-basic` and the optional `/compact` command. The shadowed content stays in the session log, so replaying the session deterministically reproduces the same condensed conversation. Reach for this package when you implement a condensation backend, build something that triggers condensation, or need to recognize condensed messages — it performs no condensation itself. Choose the shipped backend when you want the feature working out of the box.
+
+## 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
+
+Decide first what you need. The shipped backend plus the `/compact` command give you automatic and on-demand condensation with no code; this package only matters when you extend or reimplement the feature. The sections below describe what condensation does, how to turn it on, and how to write a backend.
+
+### When to choose it
+
+Choose `qilin-compaction-basic` when a model-written summary fits your needs: you get condensation automatically as the conversation grows, and on demand through `qilin-command-compact`. Choose this package when you write a backend with a different summarizer — a fixed template or a remote service — or when you build something that triggers condensation programmatically. Do not mount it alone: without a backend nothing condenses.
+
+### What condensation looks like
+
+When condensation runs, the selected older span of the conversation is replaced by one summary message; recent history is untouched and the conversation continues from the summary. Condensation can be triggered automatically as token pressure builds, on demand, or over an explicit span; the result reports which history was condensed and the estimated tokens freed.
+
+### Turning condensation on
+
+Mount the shipped backend to register the condensation service, and add `qilin-command-compact` for the on-demand command:
+
+```yaml
+- name: '@qilin-agent/compaction-basic'
+- name: '@qilin-agent/command-compact'
+```
+
+With these two rows the feature is on: the conversation condenses automatically as it grows, and `/compact` condenses immediately on request and reports how many history items were replaced. If no backend is mounted, nothing condenses and `/compact` fails; the full dependency chain for the shipped backend is in its own README.
+
+### Implementing a backend
+
+Extend the provided base class and implement three operations: one that decides and performs condensation for an automatic trigger, one that condenses on demand, and one that condenses an explicit range of the conversation. Load your class as a plugin and it becomes the condensation service for the composition. The exact signatures, the failure rules, and the checkpoint marker every backend must produce are in the implementation section below and in the [compaction subsystem reference](../../../docs/subsystems/compaction.md).
+
+### Recognizing condensed history
+
+Messages a backend wrote as summaries carry a stable marker, so any consumer can recognize condensed history after persistence or cloning without knowing which backend produced it. The marker is exported from the package root and from a Kylin-free subpath that client and wire programs can import.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+This section explains the contract in API terms and the design decisions behind it; the feature-level behavior is covered in [Use this package](#use-this-package).
+
+### Design philosophy
+
+The seam is built on one split and three commitments:
+
+- **Abstract contract, concrete backends.** The interface states what condensation does; providers own policy, retention, and summarization so each role evolves and swaps independently.
+- **Session and LLM vocabulary are part of the contract.** The operations act on a `Session` and the summary uses `ContentBlock`, so the Service Definition depends on `qilin-session` and `qilin-llm` despite the general Kylin-only guidance — a deliberate deviation recorded in the [compaction capability-seam Agent Note](../../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md).
+- **The log-recorded bracket is the lock.** `compaction/start` is appended before summarization yields and `compaction/end` releases; every failure makes exactly one close attempt, and a failed close leaves the unmatched start as the intentional busy signal.
+- **The surface is mutated exactly once.** The summary rides on a `user/message` replacement inside the bracket; all `compaction/*` events stay log-only.
+
+### Service API
+
+The contract is three abstract operations a backend implements: `compactIfNeeded` for automatic `pressure` or `context-overflow` triggers, `compactNow` for one explicit on-demand reduction, and `compactRegion` for a caller-selected surface range. Reusable request measurement is a separate service, `ctx.tokenMeter`. The exhaustive per-operation semantics live in the [compaction subsystem reference](../../../docs/subsystems/compaction.md); the exact signatures are in [`src/index.ts`](src/index.ts).
+
+A backend that summarizes through `ctx.llm.stream()` must forward the abort signal into the call's `GenerateOptions.signal`, so an abort or fiber dispose tears down the in-flight summarization. Automatic and explicit-region brackets recover their numeric owner from the open turn; manual brackets require no open turn and stamp `turn: null`.
+
+### Manual failure taxonomy
+
+The synchronous `compaction/summary-error` waterfall lets a backend request durable input recovery for a failed summary and an explicit selection. A listener returns true only after recording progress, or calls `next()` to delegate. The backend checks cancellation and selection stability before dispatch, then re-derives and re-prices input before retrying. The event declaration documents its payload; image policy belongs to `qilin-compaction-image-offload`.
+
+Expected manual failures throw `ManualCompactionError` with a stable `code` from a small closed set; only failures after the `compaction/start` marker are recorded — as a `compaction/end` carrying the error — while a `busy` rejection or pre-start cancellation leaves no record. The per-code semantics live in the [compaction subsystem reference](../../../docs/subsystems/compaction.md).
+
+<a id="tool-pairing-boundaries"></a>
+### Tool-pairing boundaries
+
+The Service Definition exports `toolPairingBalancedBefore(session, seq)` and `toolPairingBalancedAfter(session, seq)` for snapping and validating compaction edges. A safe edge has no unanswered assistant tool call crossing it. Each helper validates that the event sequence is in the current surface and answers from balances cached per cut in surface order, so repeated checks read no events; a replace generation rebuilds the cache, and missing seqs or an orphan `tool/result` reject as corrupt surface state.
+
+### The surface contract
+
+`SurfaceEventType` is a closed union — `user/message`, `assistant/message`, and `tool/result` require `surfaceOp`, and other events forbid it, so a `compaction/*` event cannot appear on the surface. A successful backend run instead brackets the operation in the log: it appends `compaction/start` (log-only) to acquire the lock, summarizes the range, appends the log-only `compaction/summary` record, replaces the selected span with one `user/message` carrying the summary — the only surface mutation — and appends `compaction/end` (log-only) to release the lock.
+
+The replacement sits inside the lock bracket, so a crash between `compaction/start` and `compaction/end` leaves a detectable orphaned lock rather than a `compaction/end` that falsely claims success. `deriveMessages()` renders the summary as a user-role message followed by the retained nodes; the shadowed events stay in the raw log, so replay is deterministic. The per-event payloads are enumerated in the [compaction subsystem reference](../../../docs/subsystems/compaction.md).
+
+### Source map
+
+| File | Role |
+|---|---|
+| [`src/index.ts`](src/index.ts) | Plugin entry: abstract `CompactionEngine`, `CompactionTrigger`, `ManualCompactionError`, `ctx.compaction` merge |
+| [`src/types.ts`](src/types.ts) | `CompactionResult` and the declaration-merged `compaction/*` session events |
+| [`src/tool-pairing.ts`](src/tool-pairing.ts) | Per-session cut-balance cache behind the two boundary helpers |
+| [`src/checkpoint.ts`](src/checkpoint.ts) | Kylin-free checkpoint source constructor and predicate (`./checkpoint` leaf) |
+| [`src/brand.ts`](src/brand.ts) | `CompactionId` branded identity |
+
+### Locking and serialization
+
+One log-recorded lock is shared by all entry points. Tail inspection finds the latest unmatched `compaction/start` and the newest `session/end-seed`; an unmatched start after that boundary is live and reports `busy`, while an older one is stale evidence from a prior process lifecycle. A live bracket cannot cross a `turn/start` or `turn/end`. The markers are lock time points, not an exclusive container: an idle `inject()` may append unrelated context between a manual start and end, so the manual path revalidates its selected span rather than demanding whole-surface equality.
+
+### Events
+
+The `compaction/*` events extend `SessionEventMap` (merge-extensible) via declaration merging — session events, not Kylin `Events`, and all log-only. The generated [persistence log event catalog](../../../docs/persistence-catalog.md) owns the per-event payloads; `compaction/prune` documents the shadow-price protocol shared with the tool-result pruner.
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+Read these pages when the package-level contract is not enough; they move from the shared vocabulary to the shipped backend and the decision evidence.
+
+- [Compaction subsystem reference](../../../docs/subsystems/compaction.md) — the condensation vocabulary, results, and generated service API.
+- [Compaction basic backend](../compaction-basic/README.md) — the shipped backend that condenses automatically and on demand.
+- [Tool-result pruner](../compaction-tool-result-pruner/README.md) — the optional companion that trims oversized tool outputs first.
+- [Human /compact command](../command-compact/README.md) — the on-demand trigger for condensation.
+- [Token meter](../../llm/token-meter/README.md) — the measurement service that decides when to condense.
+- [Compaction capability-seam Agent Note](../../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md) — the split and the session/llm dependency rationale.
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+### Conversation history, when a backend is invoked
+
+#### What the model sees
+
+A successful backend replaces an older surface range with one user-role summary checkpoint — a `user/message` carrying `surfaceOp: { op: 'replace', startSeq, endSeq }`. The raw events stay logged but stop appearing in derived model messages; the seam itself performs no rewrite.
+
+#### Token effect
+
+Zero direct tokens from this Service Definition. A backend trades many retained history tokens for one summary and leaves the recent tail unchanged.
+
+#### KV Cache effect
+
+A successful backend replacement invalidates reuse from the first shadowed history token; the seam itself does not alter a request.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+These limits describe what condensation cannot do, regardless of which backend is loaded; they are the current package constraints.
+
+- **Human command, not a model tool** — condensation is triggered by the `/compact` command and by automatic pressure; no model-facing compaction tool is registered.
+- **Some single-unit overflow is out of contract** — balanced summary compaction cannot split one indivisible unit. The optional pruning companion can still repair a closed tool pair when text-bearing tool-result bulk is removable; a large non-tool node or a tool unit whose non-prunable remainder is oversized cannot be compacted.
+- **An envelope that alone approaches the window is not surface-compaction work** — compaction shrinks derived history, never the system prompt, tools, or session prefix.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+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.
+
+- **Model-facing tool, undecided** — compaction is human-command only. A model-facing compaction tool remains an open question; it would need its own schema and interaction with the existing command path.
+- **Template and remote backends, undecided** — the `SummaryResult` contract already carries an unmarked `rawOutput` variant for summarizers that do not identify a call through `ctx.llm.stream()`, but no such backend ships.
+- **Range arguments for `/compact`, undecided** — the argument-free form keeps behavior stable across command adapters; explicit ranges stay the programmatic `compactRegion()` path.
+
+</details>

package/README.zh.md

@@ -0,0 +1,175 @@
+---
+description: "面向后端实现者与部署方的共享压缩约定：会话压缩做什么、何时使用，以及如何实现后端。"
+kind: "package-reference"
+---
+
+# @qilin-agent/compaction
+
+[English](README.md) | 中文
+
+## 概述
+
+`qilin-compaction` 让长时会话把较早历史压缩（compaction）成一条摘要消息、保持近期对话不变，并像摘要一直存在那样继续下去——配合 `qilin-compaction-basic` 之类的后端与可选的 `/compact` 命令即可实现。被遮蔽的内容仍保留在会话日志中，因此回放会话时能确定性地重现同一份压缩后的对话。当你实现压缩后端、构建触发压缩的组件，或需要识别压缩后的消息时，才需要本包——它本身不执行任何压缩。想开箱即用地获得该功能时，请选择随附后端。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+先确定你需要什么。随附后端加 `/compact` 命令即可零代码获得自动与按需压缩；只有在你扩展或重实现该功能时才需要本包。以下各节说明压缩做什么、如何启用，以及如何编写后端。
+
+### 何时选择
+
+当模型撰写的摘要符合需求时，选择 `qilin-compaction-basic`：会话增长时自动压缩，并可通过 `qilin-command-compact` 按需压缩。当你需要不同的摘要方式——固定模板或远程服务——或构建以编程方式触发压缩的组件时，选择本包。不要单独挂载它：没有后端就什么都不会压缩。
+
+### 压缩后会发生什么
+
+压缩运行时，所选较早范围的对话会被替换为一条摘要消息；近期历史不受影响，对话从摘要继续。压缩可以由 token 压力自动触发、按需触发，或针对显式范围触发；结果会报告压缩了哪些历史以及估算释放的 token 数。
+
+### 启用压缩
+
+挂载随附后端以注册压缩服务，并添加 `qilin-command-compact` 获得按需命令：
+
+```yaml
+- name: '@qilin-agent/compaction-basic'
+- name: '@qilin-agent/command-compact'
+```
+
+有了这两行配置，功能即已开启：会话增长时自动压缩，`/compact` 收到请求后立即压缩并报告替换了多少历史项。如果未挂载后端，什么都不会压缩，`/compact` 也会失败；随附后端的完整依赖链见其自身 README。
+
+### 实现后端
+
+继承提供的基类并实现三个操作：一个针对自动触发决定并执行压缩，一个按需压缩，一个压缩对话的显式范围。把你的类作为插件加载，它就会成为该组合的压缩服务。精确签名、失败规则以及每个后端必须生成的检查点标记，见下方实现章节与[压缩子系统参考](../../../docs/subsystems/compaction.zh.md)。
+
+### 识别压缩后的历史
+
+后端写入的摘要消息带有稳定标记，因此任何消费方都能在持久化或克隆后识别压缩历史，而无需知道是哪个后端生成的。该标记从包根导出，也从一个无 Cordis 依赖的子路径导出，客户端与 wire 程序均可导入。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现细节——点击展开</summary>
+
+本节以 API 术语解释约定及其背后的设计决策；功能层面行为见[使用本包](#use-this-package)。
+
+### 设计理念
+
+该 seam 建立在一个拆分与三项承诺之上：
+
+- **抽象约定，具体后端。** 接口规定压缩做什么；提供方拥有策略、保留与摘要，因此各角色可独立演进、独立替换。
+- **会话与 LLM（大语言模型）词汇是约定的一部分。** 操作作用于 `Session`，摘要使用 `ContentBlock`，因此尽管有通用的 Cordis-only 指引，Service Definition 仍依赖 `qilin-session` 与 `qilin-llm`——这是一项有意的偏离，记录在[压缩能力 seam Agent Note](../../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.zh.md) 中。
+- **日志记录的标记对就是锁。** `compaction/start` 在摘要让出控制权之前追加，`compaction/end` 释放；每次失败都恰好进行一次闭合尝试，闭合失败会留下未匹配 start 作为有意的 busy 信号。
+- **表层只变更一次。** 摘要承载在标记对内的一条 `user/message` 替换上；所有 `compaction/*` 事件仅写入日志。
+
+### 服务 API
+
+该约定是后端实现的三个抽象操作：`compactIfNeeded` 针对自动 `pressure` 或 `context-overflow` 触发，`compactNow` 进行一次显式按需缩减，`compactRegion` 针对调用方选择的表层范围。可复用的请求测量是独立服务 `ctx.tokenMeter`。穷尽式逐操作语义见[压缩子系统参考](../../../docs/subsystems/compaction.zh.md)；精确签名见 [`src/index.ts`](src/index.ts)。
+
+通过 `ctx.llm.stream()` 摘要的后端必须将 signal 转发到调用的 `GenerateOptions.signal`，因此 abort 或 fiber dispose（资源释放）会停止进行中的摘要。自动和显式范围标记对会从打开的轮次恢复其数字形式归属；手动标记对不要求存在打开的轮次，并标记 `turn: null`。
+
+### 手动失败分类
+
+同步的 `compaction/summary-error` waterfall 让后端为失败的摘要及明确选区请求持久输入恢复。监听器只有在记录实际进展后才返回 true，否则调用 `next()` 委派后续处理。后端在触发事件前检查取消和选区稳定性，重试前重新派生输入并计价。事件声明说明其载荷；图片策略由 `qilin-compaction-image-offload` 负责。
+
+预期手动失败会抛出 `ManualCompactionError`，携带来自小型封闭集合的稳定 `code`；只有 `compaction/start` 标记之后发生的失败才会被记录——以携带错误的 `compaction/end` 形式——而 `busy` 拒绝或 start 之前的取消不会留下记录。每个错误码的语义见[压缩子系统参考](../../../docs/subsystems/compaction.zh.md)。
+
+<a id="tool-pairing-boundaries"></a>
+### 工具配对边界
+
+该 Service Definition 导出 `toolPairingBalancedBefore(session, seq)` 与 `toolPairingBalancedAfter(session, seq)`，用于对齐和验证压缩边界。安全边界不会被尚未回答的 assistant 工具调用跨越。每个 helper 都会验证给定事件 seq 位于当前表层，并根据按表层顺序缓存的各切分点配对状态返回结果，因此重复检查不读取事件；replace generation 会重建缓存，缺失 seq 或孤立的 `tool/result` 会被视为表层状态损坏并遭拒绝。
+
+### 表层约定
+
+`SurfaceEventType` 是封闭联合——`user/message`、`assistant/message` 与 `tool/result` 必须携带 `surfaceOp`，其他事件禁止携带该字段，因此 `compaction/*` 事件不能出现在表层上。成功的后端运行改为在日志中包围整个操作：先追加 `compaction/start`（仅日志）获取锁，摘要该范围，追加仅日志的 `compaction/summary` 记录，用一条承载摘要的 `user/message` 替换所选范围——这是唯一的表层变更——最后追加 `compaction/end`（仅日志）释放锁。
+
+替换位于锁的起止范围**内**，因此 `compaction/start` 与 `compaction/end` 之间崩溃会留下可检测的遗留锁，而不是虚假声称成功的 `compaction/end`。`deriveMessages()` 将摘要渲染为 user 角色消息，后面跟随已保留节点；已遮蔽事件仍保留在原始日志中，因此回放具有确定性。每个事件的具体 payload 见[压缩子系统参考](../../../docs/subsystems/compaction.zh.md)。
+
+### 源码地图
+
+| 文件 | 职责 |
+|---|---|
+| [`src/index.ts`](src/index.ts) | 插件入口：抽象 `CompactionEngine`、`CompactionTrigger`、`ManualCompactionError`、`ctx.compaction` 合并 |
+| [`src/types.ts`](src/types.ts) | `CompactionResult` 与声明合并的 `compaction/*` 会话事件 |
+| [`src/tool-pairing.ts`](src/tool-pairing.ts) | 两个边界 helper 背后的每会话切分点平衡缓存 |
+| [`src/checkpoint.ts`](src/checkpoint.ts) | 无 Cordis 依赖的检查点来源构造函数与谓词（`./checkpoint` 叶子） |
+| [`src/brand.ts`](src/brand.ts) | `CompactionId` 品牌化标识 |
+
+### 锁与串行化
+
+所有入口点共享一个日志记录的锁。尾部检查会分别查找最新的未匹配 `compaction/start` 与最新的 `session/end-seed`；位于该边界之后的未匹配 start 是活动锁并报告 `busy`，更早的则是先前进程生命周期留下的陈旧证据。活动标记对不能跨越 `turn/start` 或 `turn/end`。标记是锁的时间点，而非排他容器：空闲的 `inject()` 可以在手动 start 与 end 之间追加不相关的上下文，因此手动路径重新验证其选中范围，而不要求整个表层相等。
+
+### 事件
+
+`compaction/*` 事件通过 declaration merging 扩展 `SessionEventMap`（可合并扩展）——它们是会话事件，不是 Cordis `Events`，且都仅写入日志。生成的[持久化日志事件目录](../../../docs/persistence-catalog.zh.md)拥有每个事件的 payload；`compaction/prune` 记录了与工具结果修剪器共享的影子价格协议。
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+当包级约定不够用时阅读以下页面；它们从共享词汇逐步进入随附后端与决策证据。
+
+- [压缩子系统参考](../../../docs/subsystems/compaction.zh.md)——压缩词汇、结果与生成的 API。
+- [压缩基础后端](../compaction-basic/README.zh.md)——自动与按需压缩的随附后端。
+- [工具结果修剪器](../compaction-tool-result-pruner/README.zh.md)——先修剪超大工具输出的可选配套工具。
+- [面向用户的 /compact 命令](../command-compact/README.zh.md)——按需触发压缩的入口。
+- [Token meter](../../llm/token-meter/README.zh.md)——决定何时压缩的测量服务。
+- [压缩能力 seam Agent Note](../../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.zh.md)——拆分及 session/llm 依赖的依据。
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+### 调用后端时的会话历史
+
+#### 模型看到的内容
+
+成功的后端会用一条 user 角色摘要检查点替换较早表层范围——一条携带 `surfaceOp: { op: 'replace', startSeq, endSeq }` 的 `user/message`。原始事件仍会记录，但不再出现在派生模型消息中；seam 本身不执行改写。
+
+#### Token 影响
+
+该 Service Definition 不会直接产生 token。后端用一份摘要换取多个原本保留的历史 token，并保持近期尾部不变。
+
+#### KV Cache 影响
+
+成功的后端替换会使从第一个被遮蔽的历史 token 起的复用失效；seam 本身不会改变请求。
+
+## 已知限制与延期工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+这些限制说明无论加载哪个后端，压缩都无法做到的事；它们是当前包约束。
+
+- **面向用户的命令，而非模型工具**——压缩由 `/compact` 命令与自动压力触发；不会注册面向模型的压缩工具。
+- **部分单元溢出不在约定内**——平衡摘要压缩无法拆分一个不可分单元。当闭合工具对中可移除的主要部分是承载文本的工具结果时，可选剪枝配套服务仍可修复该工具对；无法压缩大型非工具节点，或不可剪枝剩余部分过大的工具单元。
+- **单独接近窗口大小的 envelope 不属于表层压缩工作**——压缩缩减派生历史，绝不缩减系统提示词、工具或会话前缀。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者的工作上下文——点击展开</summary>
+
+本开发备注是维护者的工作上下文，明确不具权威性；已交付行为以上文、包代码与所链接的 Agent Note 为准。
+
+- **面向模型的工具，尚未决定**——压缩目前仅限用户命令。面向模型的压缩工具仍是开放问题；它需要自己的 schema，并与现有命令路径协调。
+- **模板与远程后端，尚未决定**——`SummaryResult` 约定已带有未标记的 `rawOutput` 变体，供不通过 `ctx.llm.stream()` 识别调用的摘要器使用，但此类后端尚未随附。
+- **`/compact` 的范围参数，尚未决定**——无参数形式使各命令适配器的行为保持稳定；显式范围仍由编程接口 `compactRegion()` 处理。
+
+</details>

package/lib/index.js

@@ -0,0 +1,175 @@
+import { Service } from "@qilin-agent/kylin";
+//#region lib/types/brand.js
+/**
+* Brand an implementation-minted compaction identity.
+* @param id - opaque transaction identity.
+* @returns the same string, branded; no validation is performed.
+*/
+function CompactionId(id) {
+	return id;
+}
+//#endregion
+//#region lib/types/tool-pairing.js
+/**
+* Tool-pairing balance over a session surface. Compaction changes surface
+* positions, so safe cuts are derived from tool-call/result content in current
+* surface order rather than step markers.
+* @module @qilin-agent/compaction/tool-pairing
+*/
+const balanceCacheBySession = /* @__PURE__ */ new WeakMap();
+/** Return how one surface event changes the in-progress tool-call count. */
+function eventDelta(event) {
+	switch (event.type) {
+		case "assistant/message": return event.data.message.content.filter((block) => block.type === "tool-call").length;
+		case "tool/result": return -1;
+		default: return 0;
+	}
+}
+/** Fold surface sequences not yet in the cache into its balance state. */
+function extendCache(session, cache, seqs) {
+	const processed = cache.cutBalanced.length - 1;
+	const tail = seqs.slice(processed);
+	const pendingCuts = [];
+	let inProgressToolCalls = cache.inProgressToolCalls;
+	for (const seq of tail) {
+		const event = session.eventAt(seq);
+		if (event === void 0 || event.seq !== seq) throw new Error(`tool-pairing balance: surface seq ${seq} has no matching session event (corrupt surface)`);
+		inProgressToolCalls += eventDelta(event);
+		if (inProgressToolCalls < 0) throw new Error(`tool-pairing balance: tool/result at surface seq ${seq} has no matching tool-call (corrupt surface)`);
+		pendingCuts.push(inProgressToolCalls === 0);
+	}
+	tail.forEach((seq, offset) => cache.indexBySeq.set(seq, processed + offset));
+	cache.cutBalanced = cache.cutBalanced.concat(pendingCuts);
+	cache.inProgressToolCalls = inProgressToolCalls;
+	return cache;
+}
+/** Return balance state synchronized with the current session surface. */
+function balanceCache(session) {
+	const surface = session.surface;
+	const seqs = surface.nodes;
+	const generation = surface.replaceGeneration;
+	const cached = balanceCacheBySession.get(session);
+	if (cached === void 0 || cached.generation !== generation || cached.cutBalanced.length - 1 > seqs.length) {
+		const rebuilt = extendCache(session, {
+			generation,
+			cutBalanced: [true],
+			indexBySeq: /* @__PURE__ */ new Map(),
+			inProgressToolCalls: 0
+		}, seqs);
+		balanceCacheBySession.set(session, rebuilt);
+		return rebuilt;
+	}
+	if (cached.cutBalanced.length - 1 < seqs.length) return extendCache(session, cached, seqs);
+	return cached;
+}
+/** Balance of the cut at a sequence's position plus offset, rejecting seqs outside current membership. */
+function cutBalance(cache, seq, offset) {
+	const index = cache.indexBySeq.get(seq);
+	const balanced = index === void 0 ? void 0 : cache.cutBalanced[index + offset];
+	if (balanced === void 0) throw new Error(`tool-pairing balance: surface seq ${seq} not found`);
+	return balanced;
+}
+/**
+* Whether the cut immediately before a current surface sequence is tool-pairing balanced.
+* @param session - session whose surface is checked.
+* @param seq - event sequence whose leading cut is checked.
+* @returns true when no unanswered tool call crosses the cut.
+* @throws when the seq is absent from the current surface, a surface sequence has no
+* matching log event, or a tool result has no preceding open call.
+*/
+function toolPairingBalancedBefore(session, seq) {
+	return cutBalance(balanceCache(session), seq, 0);
+}
+/**
+* Whether the cut immediately after a current surface sequence is tool-pairing balanced.
+* @param session - session whose surface is checked.
+* @param seq - event sequence whose trailing cut is checked.
+* @returns true when no unanswered tool call crosses the cut.
+* @throws when the seq is absent from the current surface, a surface sequence has no
+* matching log event, or a tool result has no preceding open call.
+*/
+function toolPairingBalancedAfter(session, seq) {
+	return cutBalance(balanceCache(session), seq, 1);
+}
+//#endregion
+//#region lib/types/checkpoint.js
+/**
+* Compaction checkpoint source: the correlated constructor and type
+* every backend uses for its replacement user message, plus the predicate that
+* recognizes persisted checkpoints.
+*
+* The seam itself lives in `@qilin-agent/compaction`, which re-exports these
+* contracts; this module is a pure type/value/predicate outlet (no cordis
+* imports, no module augmentation) so client and wire programs can name the
+* checkpoint source without loading the host plugin's Context merges — the
+* `qilin-commands/brand` shape.
+*
+* @module @qilin-agent/compaction/checkpoint
+*/
+const COMPACT_CHECKPOINT_MARKER = Object.freeze({ kind: "compact-checkpoint" });
+/**
+* Create a checkpoint source correlated with one compaction transaction.
+* @param compactionId - owning compaction identity.
+* @param sourceCommandId - initiating manual command, when present.
+* @returns immutable checkpoint source.
+*/
+function compactCheckpointSource(compactionId, sourceCommandId) {
+	return Object.freeze({
+		...COMPACT_CHECKPOINT_MARKER,
+		compactionId,
+		...sourceCommandId === void 0 ? {} : { sourceCommandId }
+	});
+}
+/**
+* Test whether a persisted message source identifies a compaction checkpoint.
+* @param source - source restored from a surface user message.
+* @returns whether the source carries the backend-independent checkpoint marker.
+*/
+function isCompactCheckpointSource(source) {
+	return source.kind === "compact-checkpoint";
+}
+//#endregion
+//#region lib/types/index.js
+/**
+* Compaction Service Definition (`ctx.compaction`): providers decide when to
+* compact and replace a history range with one summary node by subclassing
+* {@link CompactionEngine}. This interface necessarily depends on session and LLM
+* vocabulary; the rationale is in the
+* [compaction Agent Note](../../../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md).
+* @module @qilin-agent/compaction
+*/
+/**
+* Expected manual-compaction failure suitable for a direct human-command result.
+* Shared durable-lock entry assertions may also throw the `busy` subtype from
+* automatic compaction paths.
+*/
+var ManualCompactionError = class extends Error {
+	code;
+	name = "ManualCompactionError";
+	/**
+	* Create one classified compaction failure.
+	* @param code - stable failure class; `busy` may originate from any compaction entry path.
+	* @param message - backend diagnostic retained as the Error message.
+	* @param options - optional original failure.
+	*/
+	constructor(code, message, options) {
+		super(message, options);
+		this.code = code;
+	}
+};
+/**
+* Abstract compaction service. Implementations own trigger policy, retention,
+* and summarization, and may consume a separate measurement service. A
+* successful run replaces the selected surface span with one summary node and
+* prevents concurrent compaction of the same session. The replacement user
+* message uses {@link compactCheckpointSource} with the transaction identity
+* so consumers recognize and correlate it independently of the backend. Load
+* one implementation per context as `ctx.compaction`.
+*/
+var CompactionEngine = class extends Service {
+	constructor(ctx) {
+		super(ctx, "compaction");
+	}
+};
+//#endregion
+export { CompactionEngine, CompactionEngine as default, CompactionId, ManualCompactionError, compactCheckpointSource, isCompactCheckpointSource, toolPairingBalancedAfter, toolPairingBalancedBefore };

package/lib/types/brand.d.ts

@@ -0,0 +1,10 @@
+import type { Branded } from '@qilin-agent/brand';
+/** Stable identity shared by one compact start/summary/checkpoint/end transaction. */
+export type CompactionId = Branded<'CompactionId'>;
+/**
+ * Brand an implementation-minted compaction identity.
+ * @param id - opaque transaction identity.
+ * @returns the same string, branded; no validation is performed.
+ */
+export declare function CompactionId(id: string): CompactionId;
+//# sourceMappingURL=brand.d.ts.map

package/lib/types/brand.js

@@ -0,0 +1,9 @@
+/**
+ * Brand an implementation-minted compaction identity.
+ * @param id - opaque transaction identity.
+ * @returns the same string, branded; no validation is performed.
+ */
+export function CompactionId(id) {
+    return id;
+}
+//# sourceMappingURL=brand.js.map

package/lib/types/checkpoint.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Compaction checkpoint source: the correlated constructor and type
+ * every backend uses for its replacement user message, plus the predicate that
+ * recognizes persisted checkpoints.
+ *
+ * The seam itself lives in `@qilin-agent/compaction`, which re-exports these
+ * contracts; this module is a pure type/value/predicate outlet (no cordis
+ * imports, no module augmentation) so client and wire programs can name the
+ * checkpoint source without loading the host plugin's Context merges — the
+ * `qilin-commands/brand` shape.
+ *
+ * @module @qilin-agent/compaction/checkpoint
+ */
+import type { MessageSource } from '@qilin-agent/llm/message';
+import type { CommandId } from '@qilin-agent/commands/brand';
+import type { CompactionId } from './brand.ts';
+declare const COMPACT_CHECKPOINT_MARKER: Readonly<{
+    readonly kind: "compact-checkpoint";
+}>;
+/** Message source carried by a concrete compaction checkpoint. */
+export type CompactionCheckpointSource = typeof COMPACT_CHECKPOINT_MARKER & {
+    readonly compactionId: CompactionId;
+    readonly sourceCommandId?: CommandId;
+};
+/**
+ * Create a checkpoint source correlated with one compaction transaction.
+ * @param compactionId - owning compaction identity.
+ * @param sourceCommandId - initiating manual command, when present.
+ * @returns immutable checkpoint source.
+ */
+export declare function compactCheckpointSource(compactionId: CompactionId, sourceCommandId?: CommandId): CompactionCheckpointSource;
+/**
+ * Test whether a persisted message source identifies a compaction checkpoint.
+ * @param source - source restored from a surface user message.
+ * @returns whether the source carries the backend-independent checkpoint marker.
+ */
+export declare function isCompactCheckpointSource(source: MessageSource): source is CompactionCheckpointSource;
+export {};
+//# sourceMappingURL=checkpoint.d.ts.map

package/lib/types/checkpoint.js

@@ -0,0 +1,36 @@
+/**
+ * Compaction checkpoint source: the correlated constructor and type
+ * every backend uses for its replacement user message, plus the predicate that
+ * recognizes persisted checkpoints.
+ *
+ * The seam itself lives in `@qilin-agent/compaction`, which re-exports these
+ * contracts; this module is a pure type/value/predicate outlet (no cordis
+ * imports, no module augmentation) so client and wire programs can name the
+ * checkpoint source without loading the host plugin's Context merges — the
+ * `qilin-commands/brand` shape.
+ *
+ * @module @qilin-agent/compaction/checkpoint
+ */
+const COMPACT_CHECKPOINT_MARKER = Object.freeze({ kind: 'compact-checkpoint' });
+/**
+ * Create a checkpoint source correlated with one compaction transaction.
+ * @param compactionId - owning compaction identity.
+ * @param sourceCommandId - initiating manual command, when present.
+ * @returns immutable checkpoint source.
+ */
+export function compactCheckpointSource(compactionId, sourceCommandId) {
+    return Object.freeze({
+        ...COMPACT_CHECKPOINT_MARKER,
+        compactionId,
+        ...sourceCommandId === undefined ? {} : { sourceCommandId },
+    });
+}
+/**
+ * Test whether a persisted message source identifies a compaction checkpoint.
+ * @param source - source restored from a surface user message.
+ * @returns whether the source carries the backend-independent checkpoint marker.
+ */
+export function isCompactCheckpointSource(source) {
+    return source.kind === 'compact-checkpoint';
+}
+//# sourceMappingURL=checkpoint.js.map

package/lib/types/index.d.ts

@@ -0,0 +1,160 @@
+/**
+ * Compaction Service Definition (`ctx.compaction`): providers decide when to
+ * compact and replace a history range with one summary node by subclassing
+ * {@link CompactionEngine}. This interface necessarily depends on session and LLM
+ * vocabulary; the rationale is in the
+ * [compaction Agent Note](../../../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md).
+ * @module @qilin-agent/compaction
+ */
+import { Context, Service } from '@qilin-agent/kylin';
+import type { Session, SessionSeq } from '@qilin-agent/session';
+import type { CommandId } from '@qilin-agent/commands/brand';
+import type { CompactionResult } from './types.ts';
+import type { CompactionCheckpointSource } from './checkpoint.ts';
+export type { CompactionResult } from './types.ts';
+export { CompactionId } from './brand.ts';
+export { toolPairingBalancedAfter, toolPairingBalancedBefore } from './tool-pairing.ts';
+export { compactCheckpointSource, isCompactCheckpointSource } from './checkpoint.ts';
+export type { CompactionCheckpointSource } from './checkpoint.ts';
+declare module '@qilin-agent/llm' {
+    interface MessageSourceMap {
+        'compact-checkpoint': CompactionCheckpointSource;
+    }
+}
+/** Why automatic policy is asking a backend to consider compaction. */
+export type CompactionTrigger = 'pressure' | 'context-overflow';
+/** Expected failure classes for an explicit idle-session compaction request. */
+export type ManualCompactionErrorCode = 'busy' | 'cancelled' | 'changed' | 'summary' | 'commit' | 'persistence';
+/**
+ * Expected manual-compaction failure suitable for a direct human-command result.
+ * Shared durable-lock entry assertions may also throw the `busy` subtype from
+ * automatic compaction paths.
+ */
+export declare class ManualCompactionError extends Error {
+    readonly code: ManualCompactionErrorCode;
+    readonly name = "ManualCompactionError";
+    /**
+     * Create one classified compaction failure.
+     * @param code - stable failure class; `busy` may originate from any compaction entry path.
+     * @param message - backend diagnostic retained as the Error message.
+     * @param options - optional original failure.
+     */
+    constructor(code: ManualCompactionErrorCode, message: string, options?: ErrorOptions);
+}
+/** Minimal agent context compaction needs without depending on the agent package. */
+export interface CompactionAgentContext {
+    session: Session;
+    options: {
+        provider?: string;
+        model?: string;
+    };
+}
+/**
+ * Agent capability required to serialize an explicit idle-session compaction
+ * against driver turns. The durable `compaction/start` marker separately excludes
+ * other compaction transactions.
+ */
+export interface ManualCompactAgentContext extends CompactionAgentContext {
+    /**
+     * Run a non-turn maintenance operation only while the agent is idle, withholding later
+     * waking input until it settles.
+     * @param task - operation whose fulfillment or rejection is preserved, with an agent-owned cancellation signal.
+     * @throws synchronously when the agent is already active.
+     * @returns the task promise.
+     */
+    runMaintenance<T>(task: (signal: AbortSignal) => Promise<T>): Promise<T>;
+}
+declare module '@qilin-agent/kylin' {
+    interface Context {
+        compaction: CompactionEngine;
+    }
+    interface Events {
+        /**
+         * Recover a failed summary request by synchronously recording a durable
+         * change to its selected input. Return true only after making progress;
+         * the provider re-derives and re-prices the selection before retrying.
+         * Call next() when the failure cannot be recovered. Decisions survive a
+         * later summary failure or cancellation.
+         * @param payload.session - session containing the selected input.
+         * @param payload.sourceEventSeqs - selected message events in request order.
+         * @param payload.error - failure thrown by the summarizer.
+         * @param payload.signal - optional compaction cancellation signal.
+         * @param next - delegate to the next recovery listener.
+         * @mode waterfall
+         */
+        'compaction/summary-error'(payload: {
+            session: Session;
+            sourceEventSeqs: readonly SessionSeq[];
+            error: unknown;
+            signal?: AbortSignal;
+        }, next: () => boolean): boolean;
+    }
+}
+/**
+ * Abstract compaction service. Implementations own trigger policy, retention,
+ * and summarization, and may consume a separate measurement service. A
+ * successful run replaces the selected surface span with one summary node and
+ * prevents concurrent compaction of the same session. The replacement user
+ * message uses {@link compactCheckpointSource} with the transaction identity
+ * so consumers recognize and correlate it independently of the backend. Load
+ * one implementation per context as `ctx.compaction`.
+ */
+export declare abstract class CompactionEngine extends Service {
+    constructor(ctx: Context);
+    /**
+     * Consider automatic compaction for one explicit trigger. Pressure policy
+     * uses the latest durable routed request, while context-overflow policy may
+     * force a useful balanced reduction even below the normal threshold. Return
+     * `null` when no safe range can be compacted. A single oversized retained
+     * unit or request envelope cannot be repaired through surface compaction.
+     *
+     * @param agent - agent context owning the session surface and routing options.
+     * @param trigger - normal pressure or provider-confirmed context overflow.
+     * @param signal - cancellation signal; model-backed implementations must forward it.
+     * @returns the compaction result, or `null` if no compaction was needed.
+     */
+    abstract compactIfNeeded(agent: CompactionAgentContext, trigger: CompactionTrigger, signal: AbortSignal): Promise<CompactionResult | null>;
+    /**
+     * Explicitly compact useful history even below automatic pressure thresholds.
+     * Implementations synchronously start an idle task before any asynchronous
+     * work, select a useful range without writing on a no-op, then
+     * append a standalone `compaction/start` before summarization. That durable
+     * marker is the compaction lock until one `compaction/end` attempt. Later waking
+     * prompts remain accepted in FIFO order and start only after the optional
+     * durability checkpoint and idle-task settlement. Context injected while the
+     * summary runs may sit between the marker pair; only the selected span must
+     * remain stable.
+     *
+     * @param agent - idle agent whose durable history should be compacted.
+     * @param signal - cancellation scoped to this compaction request.
+     * @param sourceCommandId - initiating command identity for a manual compaction.
+     * @returns the compaction result, or `null` when no safe useful range exists.
+     * @throws {@link ManualCompactionError} for expected busy, agent-cancellation,
+     * changed-span, summarization/shrink, commit-stage, or persistence failures;
+     * an aborted request preserves its exact abort reason. Failed attempts remain
+     * visible in the log.
+     */
+    abstract compactNow(agent: ManualCompactAgentContext, signal: AbortSignal, sourceCommandId?: CommandId): Promise<CompactionResult | null>;
+    /**
+     * Forcibly compact a range of surface nodes into a single summary node.
+     * `start` and `end` name an inclusive span by surface position, not numeric seq
+     * order; replacements can make visible seqs non-monotonic. Both edges must be
+     * balanced so assistant tool calls remain paired with their results. A model-
+     * backed implementation forwards cancellation and rejects active, missing,
+     * reversed, or unbalanced ranges. The target session is `agent.session`.
+     * Its replacement user message must use {@link compactCheckpointSource} with
+     * the transaction's `CompactionId`.
+     * Use {@link toolPairingBalancedBefore} and {@link toolPairingBalancedAfter}
+     * for the edge checks.
+     *
+     * @param start - first surface seq, inclusive.
+     * @param end - last surface seq, inclusive.
+     * @param agent - context whose session is mutated and whose routing options guide summarization.
+     * @param signal - optional cancellation; model-backed implementations must forward it.
+     * @throws when compaction is active or the range is missing, reversed, or unbalanced.
+     * @returns the appended event seqs, summary, replaced range, and token accounting.
+     */
+    abstract compactRegion(start: SessionSeq, end: SessionSeq, agent: CompactionAgentContext, signal?: AbortSignal): Promise<CompactionResult>;
+}
+export default CompactionEngine;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/index.js

@@ -0,0 +1,50 @@
+/**
+ * Compaction Service Definition (`ctx.compaction`): providers decide when to
+ * compact and replace a history range with one summary node by subclassing
+ * {@link CompactionEngine}. This interface necessarily depends on session and LLM
+ * vocabulary; the rationale is in the
+ * [compaction Agent Note](../../../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md).
+ * @module @qilin-agent/compaction
+ */
+import { Service } from '@qilin-agent/kylin';
+export { CompactionId } from "./brand.js";
+export { toolPairingBalancedAfter, toolPairingBalancedBefore } from "./tool-pairing.js";
+// The checkpoint source constructor and predicate are declared on the cordis-free
+// `./checkpoint` leaf so client and wire programs can name them without this
+// root's Context merge; the root stays the host-side entry point for both.
+export { compactCheckpointSource, isCompactCheckpointSource } from "./checkpoint.js";
+/**
+ * Expected manual-compaction failure suitable for a direct human-command result.
+ * Shared durable-lock entry assertions may also throw the `busy` subtype from
+ * automatic compaction paths.
+ */
+export class ManualCompactionError extends Error {
+    code;
+    name = 'ManualCompactionError';
+    /**
+     * Create one classified compaction failure.
+     * @param code - stable failure class; `busy` may originate from any compaction entry path.
+     * @param message - backend diagnostic retained as the Error message.
+     * @param options - optional original failure.
+     */
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+    }
+}
+/**
+ * Abstract compaction service. Implementations own trigger policy, retention,
+ * and summarization, and may consume a separate measurement service. A
+ * successful run replaces the selected surface span with one summary node and
+ * prevents concurrent compaction of the same session. The replacement user
+ * message uses {@link compactCheckpointSource} with the transaction identity
+ * so consumers recognize and correlate it independently of the backend. Load
+ * one implementation per context as `ctx.compaction`.
+ */
+export class CompactionEngine extends Service {
+    constructor(ctx) {
+        super(ctx, 'compaction');
+    }
+}
+export default CompactionEngine;
+//# sourceMappingURL=index.js.map

package/lib/types/tool-pairing.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Tool-pairing balance over a session surface. Compaction changes surface
+ * positions, so safe cuts are derived from tool-call/result content in current
+ * surface order rather than step markers.
+ * @module @qilin-agent/compaction/tool-pairing
+ */
+import type { Session, SessionSeq } from '@qilin-agent/session';
+/**
+ * Whether the cut immediately before a current surface sequence is tool-pairing balanced.
+ * @param session - session whose surface is checked.
+ * @param seq - event sequence whose leading cut is checked.
+ * @returns true when no unanswered tool call crosses the cut.
+ * @throws when the seq is absent from the current surface, a surface sequence has no
+ * matching log event, or a tool result has no preceding open call.
+ */
+export declare function toolPairingBalancedBefore(session: Session, seq: SessionSeq): boolean;
+/**
+ * Whether the cut immediately after a current surface sequence is tool-pairing balanced.
+ * @param session - session whose surface is checked.
+ * @param seq - event sequence whose trailing cut is checked.
+ * @returns true when no unanswered tool call crosses the cut.
+ * @throws when the seq is absent from the current surface, a surface sequence has no
+ * matching log event, or a tool result has no preceding open call.
+ */
+export declare function toolPairingBalancedAfter(session: Session, seq: SessionSeq): boolean;
+//# sourceMappingURL=tool-pairing.d.ts.map

package/lib/types/tool-pairing.js

@@ -0,0 +1,97 @@
+/**
+ * Tool-pairing balance over a session surface. Compaction changes surface
+ * positions, so safe cuts are derived from tool-call/result content in current
+ * surface order rather than step markers.
+ * @module @qilin-agent/compaction/tool-pairing
+ */
+const balanceCacheBySession = new WeakMap();
+/** Return how one surface event changes the in-progress tool-call count. */
+function eventDelta(event) {
+    switch (event.type) {
+        case 'assistant/message':
+            return event.data.message.content.filter(block => block.type === 'tool-call').length;
+        case 'tool/result':
+            return -1;
+        default:
+            return 0;
+    }
+}
+/** Fold surface sequences not yet in the cache into its balance state. */
+function extendCache(session, cache, seqs) {
+    const processed = cache.cutBalanced.length - 1;
+    const tail = seqs.slice(processed);
+    // Validate the unseen tail before mutating the live cache, so a corrupt
+    // append cannot leave a partially advanced state behind.
+    const pendingCuts = [];
+    let inProgressToolCalls = cache.inProgressToolCalls;
+    for (const seq of tail) {
+        // oxlint-disable-next-line typescript/no-deprecated -- Existing Session history read; migration deferred.
+        const event = session.eventAt(seq);
+        if (event === undefined || event.seq !== seq) {
+            throw new Error(`tool-pairing balance: surface seq ${seq} has no matching session event (corrupt surface)`);
+        }
+        inProgressToolCalls += eventDelta(event);
+        if (inProgressToolCalls < 0) {
+            throw new Error(`tool-pairing balance: tool/result at surface seq ${seq} has no matching tool-call (corrupt surface)`);
+        }
+        pendingCuts.push(inProgressToolCalls === 0);
+    }
+    tail.forEach((seq, offset) => cache.indexBySeq.set(seq, processed + offset));
+    cache.cutBalanced = cache.cutBalanced.concat(pendingCuts);
+    cache.inProgressToolCalls = inProgressToolCalls;
+    return cache;
+}
+/** Return balance state synchronized with the current session surface. */
+function balanceCache(session) {
+    const surface = session.surface;
+    const seqs = surface.nodes;
+    const generation = surface.replaceGeneration;
+    const cached = balanceCacheBySession.get(session);
+    if (cached === undefined || cached.generation !== generation || cached.cutBalanced.length - 1 > seqs.length) {
+        // A rebuild is the same fold started from the empty-surface state, whose
+        // single leading cut is trivially balanced.
+        const rebuilt = extendCache(session, {
+            generation,
+            cutBalanced: [true],
+            indexBySeq: new Map(),
+            inProgressToolCalls: 0,
+        }, seqs);
+        balanceCacheBySession.set(session, rebuilt);
+        return rebuilt;
+    }
+    if (cached.cutBalanced.length - 1 < seqs.length)
+        return extendCache(session, cached, seqs);
+    return cached;
+}
+/** Balance of the cut at a sequence's position plus offset, rejecting seqs outside current membership. */
+function cutBalance(cache, seq, offset) {
+    const index = cache.indexBySeq.get(seq);
+    const balanced = index === undefined ? undefined : cache.cutBalanced[index + offset];
+    if (balanced === undefined) {
+        throw new Error(`tool-pairing balance: surface seq ${seq} not found`);
+    }
+    return balanced;
+}
+/**
+ * Whether the cut immediately before a current surface sequence is tool-pairing balanced.
+ * @param session - session whose surface is checked.
+ * @param seq - event sequence whose leading cut is checked.
+ * @returns true when no unanswered tool call crosses the cut.
+ * @throws when the seq is absent from the current surface, a surface sequence has no
+ * matching log event, or a tool result has no preceding open call.
+ */
+export function toolPairingBalancedBefore(session, seq) {
+    return cutBalance(balanceCache(session), seq, 0);
+}
+/**
+ * Whether the cut immediately after a current surface sequence is tool-pairing balanced.
+ * @param session - session whose surface is checked.
+ * @param seq - event sequence whose trailing cut is checked.
+ * @returns true when no unanswered tool call crosses the cut.
+ * @throws when the seq is absent from the current surface, a surface sequence has no
+ * matching log event, or a tool result has no preceding open call.
+ */
+export function toolPairingBalancedAfter(session, seq) {
+    return cutBalance(balanceCache(session), seq, 1);
+}
+//# sourceMappingURL=tool-pairing.js.map

package/lib/types/types.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Compaction vocabulary: the result type and the `compaction/*` session events.
+ * Those declaration-merged events record the lock and summary inputs without entering the surface, so they are not
+ * surface events; a separate replacement `user/message` carries the summary.
+ * Backend packages own configuration and retention policy; see
+ * `.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md`.
+ * @module @qilin-agent/compaction/types
+ */
+import type { ContentBlock, TokenUsage } from '@qilin-agent/llm';
+import type { CommandId } from '@qilin-agent/commands/brand';
+import type { SessionSeq } from '@qilin-agent/session/types';
+import type { CompactionId } from './brand.ts';
+export type { CompactionId };
+declare module '@qilin-agent/session/types' {
+    interface SessionEventMap {
+        /**
+         * Marks the start of a compaction — log-only, holds the lock until
+         * `compaction/end`. A numbered owner is strictly enclosed by that open turn;
+         * `null` identifies a standalone manual transaction between turns.
+         */
+        'compaction/start': {
+            compactionId: CompactionId;
+            sourceCommandId?: CommandId;
+            turn: number | null;
+        };
+        /**
+         * Completed summary, its inputs, and its model call facts — log-only, no surfaceOp.
+         * The summary content is in `data.summary`; the actual surface replacement
+         * is performed by the immediately following `user/message` event that
+         * shadows the compacted range. That adjacency is contractual — the
+         * shadowed pricing fields are the replacement's shadow price, so a
+         * consumer may pair a replacement with the metering event directly
+         * before it (`compaction/prune` documents the shared protocol).
+         */
+        'compaction/summary': {
+            compactionId: CompactionId;
+            sourceCommandId?: CommandId;
+            summary: ContentBlock[];
+            shadowedRange: {
+                start: SessionSeq;
+                end: SessionSeq;
+            };
+            shadowedSeqs: SessionSeq[];
+            shadowedTokenCount: number;
+            /** The provider route that wrote the summary. */
+            provider: string;
+            /**
+             * The model that wrote the summary — the summarize call's envelope,
+             * reported by the backend that made the call, logged so the one-shot
+             * request is reconstructable from log + code and "which model wrote
+             * this summary" has a durable answer (the reconstructability Agent Note).
+             */
+            model: string;
+            /** The generation cap the summarize call sent, when one applied. */
+            maxTokens?: number;
+            /** Provider-reported token usage for the summarization request, when emitted. */
+            usage?: TokenUsage;
+        } & ({
+            /** Complete provider output before the backend's safe summary projection. */
+            rawOutput: ContentBlock[];
+            /** Identifies exactly one call through this context's `ctx.llm.stream()`. */
+            llmStreamCall: true;
+        } | {
+            /** Optional complete output from an unmarked template, remote, or other summarizer. */
+            rawOutput?: ContentBlock[];
+            /** An unmarked summary does not identify a call through this context's LLM seam. */
+            llmStreamCall?: never;
+        });
+        /**
+         * Marks the end of a compaction — log-only, releases the lock. Its owner
+         * matches `compaction/start`; `error` records an unsuccessful attempt.
+         */
+        'compaction/end': {
+            compactionId: CompactionId;
+            sourceCommandId?: CommandId;
+            turn: number | null;
+            error?: string;
+        };
+        /**
+         * Shadow price of one model-free prune replacement — log-only, no
+         * surfaceOp. The shared shadow-price protocol: a surface `replace` event
+         * is priced by the metering event immediately before it (`compaction/summary`
+         * for a summarizing compaction, this event for a prune), which states the
+         * heuristic token price of the exact replaced range so a pure consumer
+         * can subtract it without retaining per-node prices. The replacement MUST
+         * be appended synchronously right after this event.
+         */
+        'compaction/prune': {
+            /** The replaced range's first and last surface-node seqs (a surface-position span, like {@link CompactionResult.shadowedRange}). */
+            shadowedRange: {
+                start: SessionSeq;
+                end: SessionSeq;
+            };
+            /** The seqs of all shadowed surface nodes, in surface order. */
+            shadowedSeqs: SessionSeq[];
+            /** Heuristic price of the shadowed content under the token-meter's fixed estimator. */
+            shadowedTokenCount: number;
+        };
+    }
+}
+/** Result of a successful compaction operation. */
+export interface CompactionResult {
+    /** Stable identity shared by this compaction's complete durable lifecycle. */
+    compactionId: CompactionId;
+    /** Human command that initiated this compaction, when it was manual. */
+    sourceCommandId?: CommandId;
+    /** The seq of the appended `compaction/start` event. */
+    startSeq: SessionSeq;
+    /** The seq of the appended `compaction/summary` event. */
+    summarySeq: SessionSeq;
+    /** The seq of the appended `compaction/end` event. */
+    endSeq: SessionSeq;
+    /** The summary content blocks produced by the backend. */
+    summary: ContentBlock[];
+    /**
+     * The surface-boundary pair that was shadowed: the seqs of the first
+     * (`start`) and last (`end`) surface nodes of the replaced range. A
+     * surface-POSITION span, not a numeric seq interval — after a prior replace
+     * lands a fresh high-seq summary node at an older range's position, `start`
+     * can be GREATER than `end`. {@link CompactionResult.shadowedSeqs} is the
+     * authoritative set of shadowed nodes, in surface order.
+     */
+    shadowedRange: {
+        start: SessionSeq;
+        end: SessionSeq;
+    };
+    /** The seqs of all shadowed surface nodes, in surface order. */
+    shadowedSeqs: SessionSeq[];
+    /** Estimated token count of the shadowed content. */
+    shadowedTokenCount: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/types/types.js

@@ -0,0 +1,10 @@
+/**
+ * Compaction vocabulary: the result type and the `compaction/*` session events.
+ * Those declaration-merged events record the lock and summary inputs without entering the surface, so they are not
+ * surface events; a separate replacement `user/message` carries the summary.
+ * Backend packages own configuration and retention policy; see
+ * `.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md`.
+ * @module @qilin-agent/compaction/types
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/package.json

@@ -1,6 +1,55 @@
 {
   "name": "@qilin-agent/compaction",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Abstract compaction service seam (ctx.compaction) for the QiLin",
+  "version": "3.1.3",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kkutysllb/QiLin.git",
+    "directory": "packages/compaction/compaction"
+  },
+  "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"
+    },
+    "./types": {
+      "types": "./lib/types/types.d.ts",
+      "default": "./lib/types/types.js"
+    },
+    "./checkpoint": {
+      "types": "./lib/types/checkpoint.d.ts",
+      "default": "./lib/types/checkpoint.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@qilin-agent/brand": "3.1.3",
+    "@qilin-agent/llm": "3.1.3",
+    "@qilin-agent/session": "3.1.3",
+    "@qilin-agent/kylin": "~4.0.3",
+    "@qilin-agent/commands": "3.1.3"
+  },
+  "devDependencies": {
+    "@qilin-agent/brand": "3.1.3",
+    "@qilin-agent/commands": "3.1.3",
+    "@qilin-agent/llm": "3.1.3",
+    "@qilin-agent/session": "3.1.3",
+    "@qilin-agent/kylin": "~4.0.3"
+  }
 }