packages/compact/README.md

# compact/ — compaction capability family

English | [中文](README.zh.md)

A compaction capability family (see [capability seams](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)): an abstract interface, a summarizing backend, a model-free tool-result pruning companion, and a deferred model-facing consumer. All **product** packages.

| Package | Role | ctx key |
|---|---|---|
| `compact/` | Abstract compaction seam (interface + `compact/*` events + `CompactionResult`) | `ctx.compact` |
| `compact-basic/` | A backend: `ctx.tokenMeter` pressure + token-budget retention + `llm.stream()` summarization | (registers `ctx.compact`) |
| `compact-tool-result-prune/` | Optional model-free head/middle/tail rewriting before summary compaction | `ctx.toolResultPrune` |
| `tool-compact/` (deferred) | Model-facing `/compact` tool over `ctx.compact` | (registers on `ctx.tools`) |

The interface lives at `compact/compact/`, the backend at `compact/compact-basic/`, and deterministic pruning at `compact/compact-tool-result-prune/`. Unlike the bash seam, the interface depends on `dsh-session` and `dsh-llm` because its verbs are defined over a `Session` and its output uses `ContentBlock`. That deviation is recorded in the [compaction capability-seam Agent Note](../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md). Token measurement remains a reusable LLM-family service; a template- or model-backed compactor can replace `compact-basic` without changing the meter, pruner, or callers.
docs(compact): add the compact group/service to package and architecture docs 2026-06-23 16:40:24 +08:00			`# compact/ — compaction capability family`

docs: translate remaining READMEs 2026-07-26 05:03:53 +08:00			`English \| [中文](README.zh.md)`

Merge master into compact-tool-result-prune 2026-07-20 16:41:59 +08:00			`A compaction capability family (see [capability seams](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)): an abstract interface, a summarizing backend, a model-free tool-result pruning companion, and a deferred model-facing consumer. All product packages.`
docs(compact): add the compact group/service to package and architecture docs 2026-06-23 16:40:24 +08:00
			`\| Package \| Role \| ctx key \|`
			`\|---\|---\|---\|`
			\| `compact/` \| Abstract compaction seam (interface + `compact/*` events + `CompactionResult`) \| `ctx.compact` \|
feat(llm): add replay token metering (PR2 round 1) 2026-07-15 14:47:29 +08:00			\| `compact-basic/` \| A backend: `ctx.tokenMeter` pressure + token-budget retention + `llm.stream()` summarization \| (registers `ctx.compact`) \|
refactor(compact): align pruning contracts (round 3) 2026-07-16 18:51:26 +08:00			\| `compact-tool-result-prune/` \| Optional model-free head/middle/tail rewriting before summary compaction \| `ctx.toolResultPrune` \|
docs(compact): add the compact group/service to package and architecture docs 2026-06-23 16:40:24 +08:00			\| `tool-compact/` (deferred) \| Model-facing `/compact` tool over `ctx.compact` \| (registers on `ctx.tools`) \|

Merge master into compact-tool-result-prune 2026-07-20 16:41:59 +08:00			The interface lives at `compact/compact/`, the backend at `compact/compact-basic/`, and deterministic pruning at `compact/compact-tool-result-prune/`. Unlike the bash seam, the interface depends on `dsh-session` and `dsh-llm` because its verbs are defined over a `Session` and its output uses `ContentBlock`. That deviation is recorded in the [compaction capability-seam Agent Note](../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md). Token measurement remains a reusable LLM-family service; a template- or model-backed compactor can replace `compact-basic` without changing the meter, pruner, or callers.