acp-kernel 0.0.1 → 0.0.2

package/DESIGN.md

@@ -0,0 +1,220 @@
+# acp-kernel Design
+
+Framework-agnostic, model-driven context-compression engine. This document is the authoritative contract for the pure core.
+
+---
+
+## 1. Mental Model
+
+ACP-style compression is **not** like zip in one essential way: **the model writes the summaries; this library orchestrates everything around them.**
+
+- **zip**: computes the compressed output itself (`bytes → bytes`).
+- **acp-kernel**: the *summary text* is produced externally (by an LLM) and passed in as an argument. The core decides *when* to compress, *what range* to compress, tracks *state*, applies a compress *decision*, prunes ranges, and supports decompress/search. **It never calls a model.**
+
+This is precisely why the core can be a pure library: the one external dependency (the summarizer) is reduced to a string input.
+
+---
+
+## 2. Module Boundary
+
+```
+┌───────────────────────────────────────────────────────┐
+│  CORE (pure TS, zero host dependency, MIT)             │
+│  stateless w.r.t. storage: state passed in and out      │
+│                                                        │
+│  processTurn / applyCompression / resolveBoundaries    │
+│  decompress / search / status / decideNudge            │
+│  (node pipeline: assign-refs → sync → merge → prune →  │
+│   filter → hide → nudge → emergency-truncate → render) │
+└──────────────────────┬────────────────────────────────┘
+                       │ pure function calls
+┌──────────────────────┴────────────────────────────────┐
+│  ADAPTER (thin, host-specific) — one per host           │
+│  OpenCode adapter | Pi adapter | custom                 │
+│  - pass messages into the core each turn                │
+│  - own + persist the state object                       │
+│  - render NudgeDecision into host message format        │
+│  - register tools / commands / lifecycle hooks          │
+└───────────────────────────────────────────────────────┘
+```
+
+**The core holds no state and performs no I/O.** State is an explicit input and output of every call. The host decides how to persist it (filesystem, memory, whatever). This is the zip model: `zip(data) → data`.
+
+---
+
+## 3. Domain Types
+
+Portable, host-agnostic. Adapters translate host-native messages into `CoreMessage[]` before calling the core, and apply the core's output back.
+
+```ts
+type CoreMessage = {
+    id: string;
+    role: "user" | "assistant" | "system" | "tool";
+    contentType: "text" | "tool-call" | "tool-result" | "reasoning";
+    text?: string;
+    toolName?: string;      // for protected-tool filtering
+    toolCallId?: string;    // links tool-call ↔ tool-result
+};
+
+type CompressionBlock = {
+    blockId: string;                    // "b0", "b1", ...
+    runId: string;
+    tier: 1 | 2 | 3;
+    topic?: string;
+    summary: string;                    // produced by the model
+    directMessageIds: string[];
+    effectiveMessageIds: string[];
+    directBlockIds: string[];           // nested blocks consumed
+    createdAt: number;
+    survivedCount: number;
+    generation: "young" | "old";
+    active: boolean;
+};
+
+type CompressionState = {
+    blocks: CompressionBlock[];
+    messageRefs: { byRaw: Record<string, string>; byRef: Record<string, string> }; // raw ↔ mNNNNN
+    nudge: {
+        lastPerMessageNudgeTokens: number;
+        lastNudgeShownTokens: number;
+        baselineTokens: number;
+        anchors: Record<string, unknown>;
+    };
+    stats: { tokensCompressed: number; compressionCount: number };
+    nextBlockId: number;
+    nextRunId: number;
+};
+
+type Config = {
+    tiers: { enabled: boolean; tier2Trigger: number; tier3Trigger: number };
+    nudge: {
+        maxContextLimitPct: number;   // e.g. 0.55 (currently advisory; threshold gate uses minContextLimitPct)
+        minContextLimitPct: number;   // e.g. 0.45 — nudge threshold gate
+        frequency: number;            // advisory (reserved for future turn-frequency gating)
+        iterationThreshold: number;   // advisory (reserved for future iteration gating)
+        force: "soft" | "strong";
+    };
+    // young→old promotion after N survivals (drives the merge-blocks node).
+    // NOTE: there is no GC — no age-based deactivation, no summary truncation.
+    promotionThreshold: number;
+    truncate: { threshold: number };          // emergency tool-output truncation node (LAST safety valve); 1.0 = 100%
+    merge: { maxSummaryLength: number; minOldGenBlocks: number }; // batch-merge old-gen blocks into one summary
+    protectedTools: string[];
+    preserveRecentMessages: number;
+    modelContextLimit: number;
+};
+```
+
+---
+
+## 4. Core Operations
+
+```ts
+interface CompressionCore {
+    // Per-turn node pipeline (replaces the message-transform hook's algorithm part).
+    // Runs every turn (canonical order): assign-refs → sync-blocks → merge-blocks →
+    // prune → filter → hide-compress-calls → nudge-inject → emergency-truncate →
+    // render-refs. Survives/promotes blocks via advanceSurvival (no age-based
+    // deactivation). Returns transformed messages + updated state + nudge decision.
+    processTurn(input: {
+        messages: CoreMessage[];
+        state: CompressionState;
+        config: Config;
+        tokenCount: number;
+    }): {
+        messages: CoreMessage[];
+        state: CompressionState;
+        nudge?: NudgeDecision;
+    };
+
+    // When the model calls compress. `ranges[].summary` is model-produced text.
+    // Allocates block(s), deactivates consumed blocks, updates indices, resets the
+    // nudge growth baseline on success (§5.7 feedback-loop fix).
+    applyCompression(input: {
+        ranges: { startRef: string; endRef: string; summary: string; topic?: string }[];
+        messages: CoreMessage[];
+        state: CompressionState;
+        config: Config;
+    }): {
+        state: CompressionState;
+        result: { blocksCreated: number; tokensCompressed: number; errors: string[] };
+    };
+
+    resolveBoundaries(input: {
+        startRef: string;
+        endRef: string;
+        messages: CoreMessage[];
+        state: CompressionState;
+    }): { startIndex: number; endIndex: number; protectedGaps: number[] };
+    // protectedGaps is reserved (currently always []); protected-tool hard-exclusion
+    // is intentionally NOT implemented in the core — see README "Known limitation".
+
+    decompress(blockId: string, state: CompressionState): CompressionBlock | undefined;
+
+    search(query: string, state: CompressionState): CompressionBlock[];
+
+    status(state: CompressionState, tokenCount: number, config: Config): StatusReport;
+
+    // No gc(): age-based deactivation was removed (it caused memory-loss upstream).
+    // Block promotion (young→old) still happens via advanceSurvival in sync-blocks,
+    // and old-gen blocks are batch-merged by the merge-blocks node — not dropped.
+}
+
+type CompressCall = {
+    mode: "range" | "message";
+    ranges: { startRef: string; endRef: string; summary: string; topic?: string }[];
+};
+
+type NudgeDecision = {
+    shouldInject: boolean;
+    reason: string;
+    compressibleRanges: { startRef: string; endRef: string; tokens: number }[];
+    contextUsage: number;       // 0..1
+    tier: 1 | 2 | 3 | null;     // multi-tier trigger, if any
+    breakdown: Record<string, number>;
+};
+```
+
+---
+
+## 5. Port Surface (host implements)
+
+The core needs two capabilities from the host, both injected (the core never imports a host SDK):
+
+```ts
+interface Ports {
+    countTokens(text: string): number;   // default impl ships in core
+    // messages are PASSED IN to each call (never fetched) → no MessageStore port
+    // state persistence is the host's job (state is plain data) → no storage port
+}
+```
+
+A default `countTokens` ships with the core (word-level + unicode CJK tokenizer, the same MIT `cc-alg` tokenizer). Hosts may override with a model-specific tokenizer.
+
+---
+
+## 6. Concept Mapping (nothing is lost)
+
+| ACP concept | Destination in acp-kernel |
+|---|---|
+| message-id ↔ ref mapping | **core** `processTurn` (pure) |
+| prune (range → summary block) | **core** `processTurn` (pure) |
+| boundary resolution / search | **core** `resolveBoundaries` (pure) |
+| block allocation / state mutation / tiers | **core** `applyCompression` (pure) |
+| young→old promotion / batch merge | **core** `sync-blocks` node (`advanceSurvival`) + `merge-blocks` node (pure) |
+| emergency truncation (context near full) | **core** `emergency-truncate` node — the LAST safety valve; no age-based GC |
+| protected-tools filtering logic | **core** (pure: message + config → bool) |
+| `inject` **decision** (shouldNudge / growth / threshold) | **core** `decideNudge` (pure) |
+| `inject` **text rendering** (nudge → message string) | **adapter** (host message format) |
+| prompts (system / nudge text templates) | rules as **structured data** in core; text rendering in **adapter** |
+| compress/decompress/search/status **tool registration** | **adapter** (calls core pure fns) |
+| `/acp` commands | **adapter** |
+| opencode hooks | **OpenCode adapter** |
+| config three-layer merge | **adapter** (core only consumes its own `Config`) |
+| logger / auth / persistence / update | **adapter** (core does zero I/O) |
+
+---
+
+## 7. Why the algorithm, but not the DCP-derived code, comes here
+
+Copyright protects *expression*, not ideas, methods, or algorithms (17 USC §102(b)). The compression *methods* (3-tier, growth cadence, protected filtering) are the author's. This core reimplements them in **fresh expression** — it is not a copy or refactor of DCP-derived files. See [PROVENANCE.md](./PROVENANCE.md) for the per-module origin classification (original-bring / DCP-derived-reimplement / adapter-only).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ranxianglei
+
+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/PROVENANCE.md

@@ -0,0 +1,92 @@
+# acp-kernel Provenance Audit
+
+This document classifies **every** source file in `opencode-acp/lib/` (the donor) into one of three buckets, to determine what can be carried into the MIT `acp-kernel` and what must be reimplemented in fresh expression.
+
+**Method**: exact path comparison of `opencode-acp` (the ACP fork, 82 `lib/*.ts` files) against the upstream DCP repository (66 `lib/*.ts` files). A file that has **no DCP equivalent** is original work (bucket A). A file with a **DCP equivalent at the same path** is a DCP derivative — its *expression* is AGPL-bound regardless of how much it was later changed (derivation is judged by whether a file was created by transforming the original, not by % changed; per copyright law expression is protected, not ideas/methods/algorithms).
+
+---
+
+## Legend
+
+| Bucket | Meaning | Action in acp-kernel |
+|---|---|---|
+| **A** | No DCP equivalent → original work of ranxianglei | **Bring verbatim** (the author's own code, MIT-safe). License header rewritten to MIT. |
+| **B** | DCP-derived file (same path exists upstream) → derivative expression is AGPL | **Reimplement in fresh expression** using the author's algorithm; do NOT copy/refactor the file's code. |
+| **N/A** | Adapter-only (framework-specific: opencode hooks, I/O, auth, commands, UI) | **Excluded** from the pure core. Stays in host adapters. Origin irrelevant. |
+
+---
+
+## Bucket A — Original work (bring verbatim) — 30 files
+
+Quality gate intentionally omitted from acp-kernel (may be added later if needed).
+
+### `compress/`
+| File | Notes |
+|---|---|
+| `compress/decompress.ts` | ACP-original (v1.11+); DCP has no decompress |
+| `compress/decompress-logic.ts` | ACP-original |
+| `compress/hide-consumed.ts` | ACP-original (v1.14+) |
+| `compress/hide-failed.ts` | ACP-original |
+| `compress/keep-markers.ts` | ACP-original (v1.12+) |
+| `compress/parts.ts` | ACP-original |
+| `compress/recap.ts` | ACP-original (v1.12.1) |
+| `compress/status.ts` | ACP-original (v1.11+) |
+
+### other
+| File | Notes |
+|---|---|
+| `config-validation.ts` | ACP-extracted for testability; no DCP equivalent |
+| `gc/merge.ts` | ACP-original (DCP has no `gc/` dir) |
+| `messages/truncate-tools.ts` | ACP-original (v1.14.5, replaced DCP's `gc/truncate.ts`) |
+| `messages/filter/*` (9 files) | ACP-original filtering subsystem |
+| `messages/inject/policy/*` (3 files) | ACP-original (v1.13.1) — inject **policy** logic, not rendering |
+| `state/rebuild.ts` | ACP-original (v1.11+) |
+
+---
+
+## Bucket B — DCP-derived (reimplement in fresh expression) — 40 files
+
+Only the **algorithmic** subset is reimplemented into the pure core; the rest are adapter-only (persistence, config-merge, prompts-rendering) and excluded from the core. Listed by what they become.
+
+### Reimplemented into acp-kernel (fresh expression, ~9 substantial files)
+| DCP-derived file | Becomes | What to reimplement |
+|---|---|---|
+| `compress/range.ts` | `core/applyCompression` (range mode) | block allocation, nested-block handling, boundary resolution |
+| `compress/search.ts` | `core/resolveBoundaries` | ref→index mapping, reversed-boundary swap, protected-gap detection |
+| `compress/state.ts` | `core/state` (mutation) | block id/run allocation, deactivation, byMessageId index |
+| `compress/pipeline.ts` | `core/processTurn` prep/finalize | permission (host-side), fetch (host-side), state wrap |
+| `messages/prune.ts` | `core/prune` | replace compressed ranges with summary blocks |
+| `messages/sync.ts` | `core/sync` | deactivate orphaned blocks when messages deleted |
+| `message-ids.ts` | `core/refs` | raw↔mNNNNN bidirectional map |
+| `messages/inject/inject.ts` + `inject/utils.ts` | `core/decideNudge` | **decision only** — shouldNudge, growth baseline, threshold, compressible ranges |
+| `config.ts` (core subset) | `core/Config` defaults | defaults + validation (use A-class `config-validation.ts`) |
+
+### Supporting types/barrels (trivial, write fresh)
+`compress/{index,types,timing,range-utils}.ts`, `messages/{index,priority,query,reasoning-strip,shape,utils}.ts`, `state/{index,types,utils}.ts`, `token-utils.ts` (wrap `cc-alg` tokenizer), `protected-patterns.ts`, `compress/protected-content.ts`.
+
+### Excluded from core (adapter-only despite B lineage)
+`state/persistence.ts` (filesystem I/O), `prompts/*` (text rendering → adapter), `compress-permission.ts` (permission = host concern).
+
+---
+
+## Bucket N/A — Adapter-only (excluded from core) — 12 files
+
+All framework-specific; irrelevant to the pure core. Stay in the OpenCode adapter (and a future Pi adapter).
+
+`auth.ts`, `hooks.ts`, `host-permissions.ts`, `logger.ts`, `update.ts`, `ui/notification.ts`, `ui/utils.ts`, `commands/{compression-targets,context,index,stats}.ts`, `compress-permission.ts`.
+
+---
+
+## Summary
+
+| Bucket | Files | Disposition |
+|---|---|---|
+| **B** DCP-derived | 40 | ~9 substantial algorithms reimplemented fresh + ~12 types/barrels rewritten fresh; rest excluded (adapter) |
+| **N/A** adapter | 12 | excluded from core |
+
+
+---
+
+## Compliance note
+
+This audit exists to ensure acp-kernel is **genuinely MIT**, not "MIT-labeled but AGPL-tainted." The rule applied throughout: an idea/algorithm is free regardless of source; a *file's code expression* is bound to the license of the file it descends from. A-class files descend from no DCP file. B-class files' code is NOT carried — the algorithms are reimplemented in new expression. Should any contributor question a classification, the comparison data above (and the upstream DCP tree) allow independent verification.

package/README.md

@@ -1,5 +1,99 @@
 # acp-kernel
 
-Active Context Pruning — platform-agnostic compression kernel for AI coding agents.
+Framework-agnostic, model-driven context-compression engine. Pure TypeScript core with **zero host dependency** — like a zip library, it does not assume any agent, server, or UI exists.
 
-Placeholder package. Full release coming soon.
+## What this is
+
+`acp-kernel` is a **host-agnostic, model-driven context-compression engine**: 3-tier LSM-tree context compression, growth-based nudge policy, protected-content filtering. Its compression algorithms and pipeline architecture (`PipelineNode` / `processTurn` / `CompressionCore`) are **original work by the ACP authors** — an independent reimplementation, not a port of any existing codebase.
+
+The key design principle: **the model writes the summaries; this library orchestrates everything around them.** The core decides *when* to compress, *what range* to compress, tracks *state* (blocks, message-id mapping, tiers), applies a compress *decision*, prunes compressed ranges, and supports decompress/search. It never calls a model.
+
+## Why a separate library
+
+- **Decoupling**: the original plugin is tightly coupled to OpenCode's hook system, making the algorithm hard to test and reuse.
+- **Multi-host**: one core, multiple thin adapters (OpenCode, Pi, or any agent).
+- **License clarity**: an independent reimplementation that shares **no source code** with its inspiration, opencode-dynamic-context-pruning (DCP, AGPL-3.0). Released under the permissive MIT license. See the [License](#license) section for the full provenance statement.
+
+## Mental model
+
+```
+processTurn({ messages, state }) → { messages, state, nudge? }    // like zip(data)→data, but stateful state passed in/out
+applyCompression({ call, state }) → { state, result }             // call.summary is produced externally by the model
+```
+
+The core is **stateless with respect to storage**: state is an explicit input and output of every call. The host persists state between turns however it likes.
+
+See [DESIGN.md](./DESIGN.md) for the full contract and [PROVENANCE.md](./PROVENANCE.md) for the per-module origin audit (which modules are original work vs. reimplemented from scratch).
+
+## API
+
+### Core engine (`createCore`)
+
+```ts
+import { createCore, createInitialState, defaultConfig } from "acp-kernel";
+
+const core = createCore();          // optional: { countTokens }
+const state = createInitialState();
+const config = defaultConfig(200000); // modelContextLimit (positional); optional overrides as 2nd arg
+
+// processTurn runs the canonical node pipeline every turn:
+// assign-refs → sync-blocks → merge-blocks → prune → filter →
+// hide-compress-calls → nudge-inject → emergency-truncate → render-refs
+const { messages, state: nextState, nudge } = core.processTurn({
+  messages, state, config, tokenCount,
+});
+
+// When the model emits a compress decision (summary written by the model):
+const { state: compressed, result } = core.applyCompression({
+  ranges: [{ startRef: "m00005", endRef: "m00020", summary: "..." }],
+  messages, state: nextState, config,
+});
+
+core.decompress("b3", compressed);            // look up a block
+core.search("auth token", compressed);        // relevance-ranked block search
+core.status(compressed, tokenCount, config);  // context-usage report
+```
+
+### Standalone modules
+
+| Module | Purpose |
+|--------|---------|
+| `truncateLargeToolOutputs` | Emergency context-threshold-gated truncation of large visible tool outputs (last-resort safety valve; summaries are never touched) |
+| `hideConsumedCompressCalls` | Hide historical compress tool-calls whose block is inactive |
+| `resolveKeepMarkers` | Expand `[[KEEP:mNNNNN]]` / rewrite `[[REF:mNNNNN\|desc]]` |
+| `buildStatusReport` / `buildRecap` | Context-usage report + block recap |
+| `mergeMarkedBlocks` / `collectOldGenBlocks` | Batch merge old-gen blocks into one summary |
+| `rebuildCompressionState` | Fork-recovery: replay historical compress calls |
+| `applyMessageFilters` | Pluggable message-filter framework |
+
+### Nudge system
+
+The nudge system tells the model *when* to compress. It implements:
+
+- **Threshold gate**: fires when context usage ≥ `nudge.minContextLimitPct`.
+- **Growth-gating**: a repeat nudge requires positive growth since the baseline (prevents re-firing every turn). `"strong"` force relaxes this.
+- **Tier-distillation triggers**: when active tier-1 blocks pile up past `tiers.tier2Trigger`, emit a tier-2 distillation nudge; tier-3 analogously.
+- **Compressible-range computation**: reports the actual compressible ranges (excluding covered + preserved-recent messages) so the model knows what to target.
+- **Baseline reset on compress**: `applyCompression` clears the growth baseline on success, preventing the feedback-loop bug where the nudge re-fires post-compress.
+
+## Status
+
+✅ **Engine complete** — 23 source modules, 167 tests, typecheck + build clean. 3-tier compression, growth-gated nudges, emergency truncation,, fork-recovery, batch merge, composable node pipeline. Ready for adapter authoring.
+
+> **Known limitation:** protected tool messages are excluded from *ref assignment* (marked `BLOCKED`) but, unlike opencode-acp's Bug 39, are **not** hard-excluded from an explicitly-referenced compress range. A model that names a range covering a `BLOCKED` message will compress it. This is an intentional simplification for the pure core; adapters that need hard-exclusion should pre-split ranges before calling `applyCompression`.
+
+## License
+
+MIT © ranxianglei
+
+### Provenance
+
+`acp-kernel` is an **independent reimplementation** of the ACP compression engine. Its compression algorithms and pipeline architecture (`PipelineNode` / `runPipeline` / `processTurn` / `CompressionCore`, the `CompressionBlock` data model, the `messageRefs` mapping, `assign-refs`, `NudgeDecision`, etc.) are **original work by the ACP authors**.
+
+It is **inspired by, but not derived from**, [opencode-dynamic-context-pruning](https://github.com/Tarquinen/opencode-dynamic-context-pruning) (DCP, AGPL-3.0, by Tarquinen). The two projects:
+
+- share **no source code** (different tokenizers — chars/4 vs. tiktoken; different strategies; different data models);
+- were written from scratch independently;
+- use unrelated host integration models.
+
+Because acp-kernel is an independent work rather than a derivative of DCP, the ACP authors — as sole copyright holders of this codebase — release it under the permissive MIT license. This is independent of DCP's AGPL-3.0 terms, which govern only DCP and its derivatives (such as [opencode-acp](https://github.com/ranxianglei/opencode-acp)).

package/dist/boundaries.d.ts

@@ -0,0 +1,25 @@
+import type { CompressionState, CoreMessage, ResolvedBoundary } from "./types.js";
+export type BoundaryKind = "message" | "block";
+export interface ParsedBoundary {
+    kind: BoundaryKind;
+    numericId: number;
+    raw: string;
+}
+export declare function parseBoundary(ref: string): ParsedBoundary | null;
+export interface ResolveBoundariesInput {
+    startRef: string;
+    endRef: string;
+    messages: CoreMessage[];
+    state: CompressionState;
+}
+export interface ResolvedRange {
+    startIndex: number;
+    endIndex: number;
+    messageIds: string[];
+    nestedBlockIds: string[];
+    boundaryKind: BoundaryKind;
+    protectedGaps: number[];
+}
+export declare function resolveBoundaries(input: ResolveBoundariesInput): ResolvedRange;
+export declare function toResolvedBoundary(range: ResolvedRange): ResolvedBoundary;
+//# sourceMappingURL=boundaries.d.ts.map

package/dist/boundaries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"boundaries.d.ts","sourceRoot":"","sources":["../src/boundaries.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,gBAAgB,EAChB,WAAW,EACX,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAEpB,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,OAAO,CAAC;AAE/C,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,YAAY,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;CACb;AAKD,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CAehE;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB,KAAK,EAAE,gBAAgB,CAAC;CACzB;AAED,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,YAAY,EAAE,YAAY,CAAC;IAC3B,aAAa,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,sBAAsB,GAC5B,aAAa,CA2Df;AAuCD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,aAAa,GAAG,gBAAgB,CAMzE"}

package/dist/compress.d.ts

@@ -0,0 +1,37 @@
+import { createInitialState } from "./state.js";
+import { type PipelineNode } from "./pipeline.js";
+import type { ApplyCompressionResult, CompressionBlock, CompressionState, Config, CoreMessage, ProcessTurnResult, StatusReport } from "./types.js";
+export interface Ports {
+    countTokens?: (text: string) => number;
+}
+export interface CompressionCore {
+    processTurn(input: ProcessTurnInput): ProcessTurnResult;
+    applyCompression(input: ApplyCompressionInput): ApplyCompressionResult;
+    defaultNodes(): PipelineNode[];
+    decompress(blockId: string, state: CompressionState): CompressionBlock | undefined;
+    search(query: string, state: CompressionState): CompressionBlock[];
+    status(state: CompressionState, tokenCount: number, config: Config): StatusReport;
+}
+export interface ProcessTurnInput {
+    messages: CoreMessage[];
+    state: CompressionState;
+    config: Config;
+    tokenCount: number;
+}
+export interface ApplyCompressionInput {
+    ranges: {
+        startRef: string;
+        endRef: string;
+        summary: string;
+        topic?: string;
+        compressCallId?: string;
+        summaryMaxChars?: number;
+    }[];
+    messages: CoreMessage[];
+    state: CompressionState;
+    config: Config;
+    protectedMessageIds?: Set<string>;
+}
+export declare function createCore(ports?: Ports): CompressionCore;
+export { createInitialState };
+//# sourceMappingURL=compress.d.ts.map

package/dist/compress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compress.d.ts","sourceRoot":"","sources":["../src/compress.ts"],"names":[],"mappings":"AAIA,OAAO,EAGL,kBAAkB,EACnB,MAAM,YAAY,CAAC;AAcpB,OAAO,EAGL,KAAK,YAAY,EAElB,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EACV,sBAAsB,EACtB,gBAAgB,EAChB,gBAAgB,EAEhB,MAAM,EAEN,WAAW,EAGX,iBAAiB,EAEjB,YAAY,EACb,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,KAAK;IACpB,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;CACxC;AAED,MAAM,WAAW,eAAe;IAC9B,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,iBAAiB,CAAC;IACxD,gBAAgB,CAAC,KAAK,EAAE,qBAAqB,GAAG,sBAAsB,CAAC;IACvE,YAAY,IAAI,YAAY,EAAE,CAAC;IAC/B,UAAU,CACR,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,gBAAgB,GACtB,gBAAgB,GAAG,SAAS,CAAC;IAChC,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,gBAAgB,GAAG,gBAAgB,EAAE,CAAC;IACnE,MAAM,CACJ,KAAK,EAAE,gBAAgB,EACvB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,GACb,YAAY,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB,KAAK,EAAE,gBAAgB,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE;QACN,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,MAAM,CAAC;QACf,OAAO,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,eAAe,CAAC,EAAE,MAAM,CAAC;KAC1B,EAAE,CAAC;IACJ,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB,KAAK,EAAE,gBAAgB,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,mBAAmB,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CACnC;AAED,wBAAgB,UAAU,CAAC,KAAK,GAAE,KAAU,GAAG,eAAe,CA0M7D;AAijBD,OAAO,EAAE,kBAAkB,EAAE,CAAC"}

package/dist/compression-rules.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Compression rule texts — VERBATIM copy from context-compress-algorithms (MIT, ours).
+ * These were tuned over months of production use.
+ *
+ * DO NOT modify the wording — it is the result of extensive tuning.
+ */
+export declare const COMPRESS_PHILOSOPHY = "Compression Philosophy:\n- All compression serves the primary task, but be frugal.\n- Context capacity is precious. Save context by compressing consumed outputs, not by avoiding tools.\n- Compress by need, not by percentage.\n- Work from summaries, not raw tool outputs. All listed ranges (user prompts, tool outputs, code, logs, exploration, intermediate steps) should be compressed to summary format \u2014 the ONLY exceptions are protected content, content the current step is actively using, or critical content you cannot reconstruct.\n- Curate summaries like a well-structured document. User prompts, compressed tool outputs, code, logs, or skill-call intermediate results that are critically important should be preserved \u2014 not by exempting them from compression, but by embedding them in the summary via [[KEEP:mNNNNN]] (auto-expanded verbatim) and [[REF:mNNNNN|description]] (compact link).";
+export declare const HOW_TO_COMPRESS_RULES = "HOW TO COMPRESS\n\nWhen you call `compress`, the summary you write becomes the only record of the replaced conversation. Make it self-contained and complete: every user request, experiment purpose, and work task in the range must be accurately captured. A later reader (or you, after decompressing) should be able to continue the task WITHOUT needing the original.\n\nKEEP VERBATIM \u2014 never paraphrase or abbreviate these:\n- Full file paths with line numbers, directory prefix on every mention (`lib/hooks.ts:347`, `src/index.ts:12-18`, `gatenet_v3/model.py:45`). Never abbreviate to a bare filename (`hooks.ts`, `model.py`) \u2014 they are ambiguous and cannot be grepped or decompressed-to later.\n- Function, class, and type signatures (exact names, params, return types) AND critical code lines that encode logic \u2014 the line that IS the finding, not just the function name (e.g. `kv_keys += define_gate * a_key[i](emb)` is more useful than \"see model_kvnet.py\").\n- Error messages and stack traces (exact text \u2014 you need the literal string to grep for it later).\n- Key details from reports and analyses \u2014 not just the conclusion. Keep the comparison numbers and the mechanism, not \"X is worse\" alone (write \"1.76\u00D7 PPL gap because KV store is static\", not \"KVNet underperforms\").\n- Decisions and their rationale (\"chose X over Y because Z\" \u2014 the \"because\" is load-bearing; without it the decision looks arbitrary).\n- Constraints discovered (\"must support Node 22\", \"no new dependencies\", \"AGENTS.md forbids `as any`\").\n- Exact values: versions, config keys, thresholds, magic numbers.\n- User intent \u2014 quote short user messages verbatim. When the message is too long to quote, preserve intent with extra care: do not change scope, constraints, priorities, acceptance criteria, or requested outcomes. Mark them clearly as past quotes (e.g., \"User said: ...\"), not as current directives. Losing these changes the task itself.\n- The user's overall goal and any changes to it \u2014 the big-picture objective plus how it evolved during the compressed range. Each summary must reflect the goal as it stood at the end of the range, including pivots (e.g., \"initially: fix bug X \u2192 pivoted to: refactor module Y after discovering root cause\"). Losing the goal or its evolution makes all subsequent work appear unmotivated.\n- Purpose behind each significant action \u2014 preserve not just what was done but why: the hypothesis behind each experiment, the question behind each exploration, the task goal behind each work action. Without purpose, the summary reads as disconnected technical steps with no through-line.\n- Open questions and unresolved TODOs \u2014 losing these changes what work appears to remain.\n- Message refs of key anchors (`m00420`, `m00510\u2013m00520`) \u2014 they let you or a later reader jump back via decompress to the exact original.\n\nDROP \u2014 extract the signal, discard the vessel:\n- Verbose logs (build/test/`npm` output) once you have captured the error line or the result.\n- Duplicate file reads once the needed content is recorded.\n- Consumed exploration \u2014 search hits, agent return values, successful tool outputs \u2014 once you have extracted the facts you need (same rule as dead-ends, but nothing went wrong; the content is simply spent).\n- Dead-end exploration \u2014 but PRESERVE the lesson in one line: \"tried X, failed because Y\".\n- Back-and-forth discussion and self-corrections once the final position is captured (keep the outcome, drop the journey to it).\n- Repeated status checks (`git status`, `ls`) once state is known.\n\nFor each significant item you DROP (scripts, reports, large analyses, long tool outputs), add a one-line CONTENT description of what it covers \u2014 not where it lives. Bad: \"probe script at /path/probe_kvnet.py\". Good: \"probe_kvnet.py: tests n-gram baseline, generation quality, long-range dependency, position sensitivity, op pipeline, QUERY attention.\" This lets a later decompress target the right block by relevance, not by guessing locations.\n\nKEEP MARKERS: `[[KEEP:mNNNNN]]` expands original message content into the summary (truncated to a max length). Do NOT use KEEP for verbose command output, diagnostic scripts, log dumps, or any content whose value is in the conclusion rather than the raw output \u2014 summarize these or use `[[REF:mNNNNN|desc]` instead.\n\nPRIORITY \u2014 when the summary must be compact, preserve in this order:\n1. User's overall goal, goal evolution, intent, and hard constraints (losing these changes the task).\n2. Decisions and rationale.\n3. Exact technical artifacts: paths, signatures, errors, values.\n4. Conclusions and key findings.\n5. Lessons learned: what failed and why.\n\nWrite dense, scannable bullets \u2014 not narrative prose. If the range spans distinct concerns (request \u2192 findings \u2192 decision), group bullets under short thematic headers so a reader can scan to the part they need. Every line must earn its place. Do not mimic the style of existing summaries in context; follow these rules.";
+export declare const TIER2_DISTILL_RULES = "TIER 2 COMPRESSION \u2014 DISTILLATION\n\nYou are compressing historical summaries (not raw conversation). These summaries have already captured the details. Your job is to DISTILL them: extract only what matters for future work, discard the process.\n\nKEEP \u2014 these are the only things that survive distillation:\n- Decisions and their rationale (\"chose X over Y because Z\" \u2014 the \"because\" is load-bearing).\n- Final outcomes: version numbers shipped, PR numbers merged/closed, bugs fixed or deferred.\n- Key lessons: what failed and why (\"tried X, failed because Y\"). These prevent repeating mistakes.\n- Critical constraints discovered (\"must support Node 22\", \"AGENTS.md forbids as any\").\n- Design decisions with architectural impact (\"chose compress-as-anchor over synthetic messages because prefix cache\").\n- Whether content is OBSOLETE or SUPERSEDED \u2014 mark with one line: \"[SUPERSEDED by PR #NNN]\" or \"[OBSOLETE: deleted in vX.Y.Z]\". Do NOT keep the obsolete content's details \u2014 just the marker and reason.\n- Function/class/type names and module paths that are the SUBJECT of the work \u2014 e.g., \"fixed filterCompressedRanges in prune.ts\", \"added SessionStateRegistry in state.ts\". Not exact line numbers or full signatures \u2014 just enough to LOCATE the code without searching.\n- Exploration findings: if a block was exploratory with no decision, keep the CONCLUSION in one line (\"explored X, not viable because Y\"). Do not keep the exploration process.\n\nDROP \u2014 these were useful during the work but are no longer needed:\n- Exact line numbers, diffs, verbose function signatures, full code listings.\n- Build/deploy process details, test execution steps.\n- Review process details (who reviewed, what rounds, test counts).\n- Verbose logs, command output, intermediate debugging steps.\n\nFORMAT:\n- Start each distilled block with a source header line:\n  `Source: bN+bM+... (XK\u2192YK tok, Zx). [original topic]`\n  Example: `Source: b5+b7 (56K+44K\u2192268 tok, 375x). [Tool-result recap + publish]`\n- 3-5 bullet points per source block, each a self-contained fact.\n- Dense, scannable \u2014 no narrative prose.\n- Start with the outcome, not the process: \"v1.13.0 shipped (7 PRs bundled)\" not \"implemented 7 PRs then reviewed then merged\".\n- Cross-block synthesis: if multiple source blocks cover the same topic (same PR, same feature, same bug), MERGE them into a single group of bullets. Do not repeat the same fact from different blocks \u2014 keep it once under the most relevant source header.\n\nSIZE TARGET: 50-150 tokens per source block (excluding the header). If you can't fit it in 150 tokens, you're keeping too much process. If a block has nothing worth keeping (pure noise), output just the header followed by \"[no actionable content].\"";
+export declare const TIER3_CONDENSE_RULES = "TIER 3 COMPRESSION \u2014 ULTRA-CONDENSATION\n\nYou are compressing distilled summaries (Tier 2) into ultra-condensed facts (Tier 3). The distilled summaries already contain only decisions and outcomes. Your job is to reduce them to bare factual references.\n\nPRIORITY \u2014 when a source block has more facts than the size target allows, keep in this order:\n1. Shipped outcomes (versions released, PRs merged) \u2014 these are permanent record.\n2. Open work (PRs/issues still pending) \u2014 these may need follow-up.\n3. Key decisions with architectural impact (\"chose X over Y because Z\").\n4. Critical constraints (\"must support Node 22\").\nDrop everything else. Tier 3 is a lookup index, not a knowledge base.\n\nFORMAT:\n- Start with a source header line:\n  `Source: bN+bM+... (XK\u2192YK tok, Zx). [original topic]`\n- Output 1-3 facts per source block. Each fact is a single line: subject + outcome.\n- No explanations, no rationale, no process \u2014 just the fact.\n- Format: \"[PR/Issue/Version] \u2014 [outcome in \u22648 words]\"\n- Merge related facts from different source blocks if they concern the same topic.\n\nEXAMPLES:\n- \"v1.13.0 shipped \u2014 quality gate + GC fix (7 PRs)\"\n- \"PR #196 merged \u2014 preserve-first-user (supersedes #169)\"\n- \"Bug 1214 fixed \u2014 compress consumed all user messages\"\n- \"Chose compress-as-anchor \u2014 prefix cache benefit over synthetic injection\"\n- \"Constraint: AGENTS.md forbids as any \u2014 never suppress types\"\n\nDROP:\n- Multi-sentence context. If a fact needs >1 sentence, it's too detailed for Tier 3.\n- Lessons learned (\"tried X, failed because Y\") \u2014 drop UNLESS the failure is likely to recur and the block is <30 days old.\n- Design rationale details \u2014 keep the decision, drop the \"because\" unless it's a critical constraint.\n- Anything marked [OBSOLETE] or [SUPERSEDED] \u2014 drop entirely, note \"[N blocks obsolete]\" in the summary.\n\nSIZE TARGET: 30-60 tokens per source block (including header). For a batch of N source blocks, total output \u2248 N \u00D7 40 tokens. If a source block has only one trivial fact, output just the header + one line.";
+//# sourceMappingURL=compression-rules.d.ts.map

package/dist/compression-rules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compression-rules.d.ts","sourceRoot":"","sources":["../src/compression-rules.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAO,MAAM,mBAAmB,64BAKuU,CAAC;AAExW,eAAO,MAAM,qBAAqB,qgKAqC8R,CAAC;AAEjU,eAAO,MAAM,mBAAmB,mxFA6ByN,CAAC;AAE1P,eAAO,MAAM,oBAAoB,0nEAgC4K,CAAC"}

package/dist/config.d.ts

@@ -0,0 +1,4 @@
+import type { Config } from "./types.js";
+export declare function defaultConfig(modelContextLimit: number, overrides?: Partial<Config>): Config;
+export declare function validateConfig(config: Config): string[];
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEzC,wBAAgB,aAAa,CAC3B,iBAAiB,EAAE,MAAM,EACzB,SAAS,GAAE,OAAO,CAAC,MAAM,CAAM,GAC9B,MAAM,CAsCR;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAgCvD"}

package/dist/decompress.d.ts

@@ -0,0 +1,14 @@
+import type { CompressionBlock, CompressionState, CoreMessage } from "./types.js";
+export declare function parseBlockIdArg(arg: string): string | null;
+export declare function findBlocksOverlappingMessages(state: CompressionState, messageIds: Set<string>): CompressionBlock[];
+export declare function findActiveAncestor(state: CompressionState, blockId: string): string | null;
+export interface DeactivateOptions {
+    deep?: boolean;
+}
+export declare function deactivateBlock(state: CompressionState, blockIds: string[], options?: DeactivateOptions): CompressionState;
+export interface RestoredPreviewResult {
+    preview: string;
+    restoredCount: number;
+}
+export declare function buildRestoredContentPreview(messages: CoreMessage[], beforeActiveMessageIds: Set<string>, state: CompressionState): RestoredPreviewResult;
+//# sourceMappingURL=decompress.d.ts.map

package/dist/decompress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decompress.d.ts","sourceRoot":"","sources":["../src/decompress.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAElF,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAO1D;AAED,wBAAgB,6BAA6B,CACzC,KAAK,EAAE,gBAAgB,EACvB,UAAU,EAAE,GAAG,CAAC,MAAM,CAAC,GACxB,gBAAgB,EAAE,CAUpB;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAiB1F;AAED,MAAM,WAAW,iBAAiB;IAC9B,IAAI,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,wBAAgB,eAAe,CAC3B,KAAK,EAAE,gBAAgB,EACvB,QAAQ,EAAE,MAAM,EAAE,EAClB,OAAO,GAAE,iBAAsB,GAChC,gBAAgB,CAkClB;AAED,MAAM,WAAW,qBAAqB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;CACzB;AAED,wBAAgB,2BAA2B,CACvC,QAAQ,EAAE,WAAW,EAAE,EACvB,sBAAsB,EAAE,GAAG,CAAC,MAAM,CAAC,EACnC,KAAK,EAAE,gBAAgB,GACxB,qBAAqB,CA8BvB"}

package/dist/filter/apply.d.ts

@@ -0,0 +1,10 @@
+import type { CoreMessage } from "../types.js";
+import type { MessageFiltersConfig } from "./types.js";
+export interface ApplyResult {
+    messages: CoreMessage[];
+    partsFiltered: number;
+    partsDropped: number;
+    partsModified: number;
+}
+export declare function applyMessageFilters(messages: CoreMessage[], config: MessageFiltersConfig | undefined): ApplyResult;
+//# sourceMappingURL=apply.d.ts.map

package/dist/filter/apply.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply.d.ts","sourceRoot":"","sources":["../../src/filter/apply.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,KAAK,EAAsC,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAE3F,MAAM,WAAW,WAAW;IACxB,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;CACzB;AAED,wBAAgB,mBAAmB,CAC/B,QAAQ,EAAE,WAAW,EAAE,EACvB,MAAM,EAAE,oBAAoB,GAAG,SAAS,GACzC,WAAW,CAuFb"}

package/dist/filter/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./types.js";
+export { registerMessageFilter, getMessageFilter, listMessageFilters, clearMessageFilters } from "./registry.js";
+export { applyMessageFilters } from "./apply.js";
+export type { ApplyResult } from "./apply.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/filter/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/filter/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACjH,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACjD,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC"}

package/dist/filter/registry.d.ts

@@ -0,0 +1,6 @@
+import type { MessageFilter } from "./types.js";
+export declare function registerMessageFilter(filter: MessageFilter): void;
+export declare function getMessageFilter(name: string): MessageFilter | undefined;
+export declare function listMessageFilters(): MessageFilter[];
+export declare function clearMessageFilters(): void;
+//# sourceMappingURL=registry.d.ts.map

package/dist/filter/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/filter/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAIhD,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI,CAQjE;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAExE;AAED,wBAAgB,kBAAkB,IAAI,aAAa,EAAE,CAEpD;AAED,wBAAgB,mBAAmB,IAAI,IAAI,CAE1C"}