opencode-vcc-compaction 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,3 +1,308 @@
1
- # Temporary Holding Version
1
+ # opencode-vcc-compaction — deterministic LLM-free compaction for OpenCode V2
2
2
 
3
- 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.
3
+ **Your long session gets summarized by a model. The summary is invented
4
+ text — and the model then reasons from it as if it were fact.**
5
+
6
+ This plugin removes the model from that step. On every `compaction` hook
7
+ it compiles history with a deterministic region compiler and sets
8
+ `event.result`, so the host takes its `fromHook` short-circuit: the
9
+ summary persists verbatim, the tail rebuilds from `keepID`, and **no
10
+ model call is billed** on the compaction path — proven live on host
11
+ v2.3.2 (see `../docs/research/vcc-plugin-live-verdict.md`).
12
+
13
+ Port of [`dsh-compaction-vcc`](https://github.com/tingfeng-droid/dsh-compaction-vcc)
14
+ (MIT, itself a fork of `TsFreddie/dsh-compaction-instant`), written
15
+ directly against `@opencode/plugin/effect` (canonical runtime), so no
16
+ convert-to-Effect task ever arises. The VCC reference engine is vendored
17
+ byte-identical from `../compiler/` into `./engine/` (sync-enforced).
18
+ Version: `opencode-vcc-compaction@0.1.0`.
19
+
20
+ ## How it works
21
+
22
+ The adapter (`adapter.mjs`, pure offline) maps the request messages to
23
+ compile nodes, runs the deterministic reference compiler, and sets:
24
+
25
+ ```js
26
+ event.result = { summary, metadata: { keepID } }
27
+ ```
28
+
29
+ `keepID` is the id of the first message the host must keep: the last
30
+ `keepMessages` request messages stay verbatim, everything older compiles
31
+ into the summary. When no message id exists at/after the keep cut, the
32
+ adapter abstains — `result` stays unset and the host falls back to model
33
+ compaction. Never a broken summary.
34
+
35
+ ## Example
36
+
37
+ Seven messages (user request, assistant text + two tool calls, results,
38
+ follow-ups) compile to this — verbatim, the real output:
39
+
40
+ ```text
41
+ This is an automatically generated checkpoint condensing an earlier span of the conversation to free up context. Treat the captured context as established background and build on it without restating it. Continue the task directly from the messages that follow, without acknowledging this checkpoint.
42
+
43
+ <compacted-checkpoint>
44
+
45
+ RECALL: append-only log — nothing is lost. `recall` restores original content: type "seq", id "3-7"; "result", id "3"; "checkpoint", id "1" (`[checkpoint N]` = dropped). `search` finds by keyword.
46
+
47
+ [opencode-vcc-compaction vcc-compiler-debug-2: 7 messages -> 8 entries]
48
+
49
+ [user]
50
+ please fix the login bug — sessions expire after 60 seconds
51
+
52
+ [assistant]
53
+ on it, checking the session middleware first
54
+
55
+ * read "src/auth/session.js" (seq 2 -> result 3)
56
+
57
+ [tool]
58
+ const TTL = 60; // seconds ...
59
+
60
+ [assistant]
61
+ * edit "src/auth/session.js" (seq 4 -> result 5)
62
+
63
+ [tool]
64
+ edited 1 file
65
+
66
+ [assistant]
67
+ fixed — TTL is now one hour. Want me to check the logout path too?
68
+
69
+ [user]
70
+ yes, and also verify refresh tokens still work
71
+
72
+ </compacted-checkpoint>
73
+ ```
74
+
75
+ Every tool call is one line — `* name "key argument" (seq N -> result M)`.
76
+ The `-> result M` pointer keeps each result one lookup away. Long text is
77
+ truncated to its budget with a `...(truncated from seq N)` marker naming
78
+ the event that still holds the full content.
79
+
80
+ ## Why keeping original tokens prevents hallucination
81
+
82
+ Ask a model to summarize history and it fills the details it cannot quite
83
+ recall with plausible-sounding wording — **and that filled-in material is
84
+ invented, not factual**. Worse, it reads fluently, and the model then treats
85
+ **its own summary as a factual premise**. A paraphrased number, a reworded
86
+ caveat, or a dropped precondition is enough to put a whole downstream chain
87
+ on a false footing.
88
+
89
+ This engine **only moves original text, never rewriting a single
90
+ character**: every elision carries a `(seq N)` pointer back to the original
91
+ event. So the model ever sees two things: **original tokens**, or **an
92
+ explicitly marked pointer saying content was elided here**. There is no
93
+ third kind. Pointer-based archiving costs a few bytes per elision,
94
+ essentially independent of history length — while a summary has to cover
95
+ more the longer the session gets, with more chances to rewrite and lose
96
+ information.
97
+
98
+ ## Key features
99
+
100
+ - **LLM-free** — compaction never invokes a model. No summarizer prompt, no
101
+ inference latency, no model token spend; the compile is deterministic
102
+ text processing.
103
+ - **Verbatim** — output contains only original tokens. Prior checkpoints
104
+ are copied word for word instead of being re-summarized.
105
+ - **Deterministic** — the same messages + config always compile to the
106
+ byte-identical summary (proven by double-run selftests).
107
+ - **Measured** — 4,998 mixed messages compile to a ~28k-character summary
108
+ in ~0.5 s on the dev machine, byte-identical across runs (see
109
+ Performance).
110
+ - **Fail-safe** — no keepID, no result: the host falls back to model
111
+ compaction rather than persisting a broken summary.
112
+
113
+ ## Performance
114
+
115
+ Single-threaded `node`, no model, no network. Measured on the dev machine
116
+ (Xeon W-2195, node v24.22.3) with synthetic mixed histories (user text +
117
+ assistant text + tool-call + tool-result, default config), best of 3 runs.
118
+ Input sizes are request-payload characters with ÷4 token estimates:
119
+
120
+ | History | Input | Summary | Time |
121
+ | --- | --- | --- | --- |
122
+ | 999 messages | ~0.58M chars (~150k tokens) | 28,130 chars | 80 ms |
123
+ | 4,998 messages | ~2.9M chars (~730k tokens) | 28,047 chars | 496 ms |
124
+ | 9,999 messages | ~5.9M chars (~1.5M tokens) | 28,047 chars | 934 ms |
125
+ | 24,999 messages | ~14.7M chars (~3.7M tokens) | 27,876 chars | 4.7 s |
126
+
127
+ Two things to read off this table:
128
+
129
+ - Compile time scales roughly linearly with history size — the pass is a
130
+ single deterministic walk, and every run above was byte-identical.
131
+ - Summary size stays flat because the default `maxTokens` cap (8192 entry
132
+ tokens) binds: bigger histories elide more rows, they don't emit more
133
+ text. Raise the cap if you want larger checkpoints, at the cost of more
134
+ context per compaction.
135
+
136
+ Caveats: synthetic repetitive text, one machine, one node version —
137
+ indicative, not a benchmark. Real sessions vary with text shape
138
+ (long tool outputs and base64 blobs cost more per message), but the
139
+ scaling shape (linear time, cap-flat output) follows from the algorithm,
140
+ not the input.
141
+
142
+ ## Install
143
+
144
+ Requires OpenCode `v2.x` (live-verified on `v2.3.2`).
145
+
146
+ ```bash
147
+ opencode plugin add opencode-vcc-compaction
148
+ ```
149
+
150
+ Or declare it in `opencode.json`:
151
+
152
+ ```json
153
+ {
154
+ "$schema": "https://opencode.ai/config.json",
155
+ "plugin": ["opencode-vcc-compaction"]
156
+ }
157
+ ```
158
+
159
+ With options (all optional; defaults in Configuration below):
160
+
161
+ ```jsonc
162
+ // opencode.jsonc
163
+ {
164
+ "plugins": [
165
+ {
166
+ "package": "opencode-vcc-compaction",
167
+ "options": { "maxTokens": 8192, "keepMessages": 6 },
168
+ },
169
+ ],
170
+ }
171
+ ```
172
+
173
+ The package is self-contained: the adapter imports the engine from
174
+ `./engine/` inside the package, so it installs from npm alone.
175
+
176
+ From source instead: clone
177
+ `https://github.com/jwitmann/opencode-vcc-compaction` and register the
178
+ local path (`"package": "/abs/path/to/opencode-vcc-compaction/vcc-plugin"`)
179
+ in the same object form.
180
+
181
+ Optional `opencode.jsonc` addition — auto-compaction threshold:
182
+
183
+ ```jsonc
184
+ {
185
+ // Fire auto-compaction once history passes (window − buffer).
186
+ // "99%" (fire at ~1% of window) is the demo-harness trigger for cheap
187
+ // live runs (see ../examples/opencode.jsonc); the override mechanism
188
+ // is threshold-independent, so leave the default in production.
189
+ "compaction": { "buffer": "99%" },
190
+ }
191
+ ```
192
+
193
+ ## Configuration
194
+
195
+ Options are the engine budgets plus behavior (all optional, upstream
196
+ defaults shown). Unknown keys are ignored; non-positive or non-finite
197
+ numbers fall back to defaults.
198
+
199
+ | Key | Default | Meaning |
200
+ | --- | ------- | ------- |
201
+ | `maxTokens` | 8192 | total cap on compiled entry tokens |
202
+ | `textTokens` | 8192 | per-block assistant text budget |
203
+ | `userTextTokens` | 16384 | per-block user text budget |
204
+ | `toolCallTokens` | 128 | tool one-liner budget |
205
+ | `toolResultExcerptTokens` | 256 | tool-result excerpt budget |
206
+ | `includeReasoning` | false | keep reasoning blocks (else elided) |
207
+ | `hideTools` | [] | tool names dropped entirely |
208
+ | `noisePatterns` | [] | extra strip regex sources (strings) |
209
+ | `keepMessages` | 6 | trailing messages kept verbatim |
210
+
211
+ `noisePatterns` entries must be valid regex sources — an invalid one
212
+ throws loudly at setup, never a silent no-strip.
213
+
214
+ How the budgets behave:
215
+
216
+ - Every budget is enforced twice — by token count **and** by a
217
+ `budget × 4` character ceiling (floor 32) — so pathological unbroken
218
+ runs (base64 blobs, minified files) cannot bypass them.
219
+ - Tool calls are **always one line**: they are never rescaled. Truncation
220
+ marks the cut with `...(truncated from seq N)`.
221
+ - Over-long tool results keep head and tail with an
222
+ `...(elided from seq N)` middle, since the end (listings, logs) usually
223
+ matters more than the middle.
224
+ - Under cap pressure the oldest **tool/result rows go first**
225
+ (`[N tool/result entries elided: seqs a-b]`), then the oldest remaining
226
+ entries — tool calls can never squeeze the dialogue out. The newest
227
+ content always survives, and a `[cap enforced at N entry tokens]`
228
+ footer says the cap bit.
229
+ - Dropped prior checkpoints never vanish silently: each leaves a
230
+ `[checkpoint N]` line (N = compaction ordinal, 1 = oldest).
231
+ - `keepMessages` counts request messages, not entries: the host rebuilds
232
+ the verbatim tail from `keepID`, the summary covers everything older.
233
+
234
+ ## Seq pointers and recall
235
+
236
+ `(seq N)` ordinals are 1-based positions over the compiled messages
237
+ (skipped messages consume no seq), not durable host ids — the hook only
238
+ sees the request window. Every checkpoint heads with a short RECALL guide
239
+ telling the model how to recover elided content; OpenCode-native recall
240
+ tools (resolving message/part IDs against the session log) are
241
+ follow-up work, recorded in [the plan](../archive/plans/vcc-plugin.md).
242
+ v0.1.0 ships the engine: deterministic summary + keep-tail, with every
243
+ cut marked and pointing at its source.
244
+
245
+ ## Message mapping
246
+
247
+ OpenCode parts map to compiler blocks as follows: text → text; reasoning
248
+ → reasoning (elided unless `includeReasoning`); tool-call → one-liner
249
+ (`arguments: JSON.stringify(input)`, unparseable input falls back to
250
+ name-only); tool-result → single text block via projection (json →
251
+ compact `JSON.stringify`, text → as-is, error → `[error] ...`, content →
252
+ `TextContent` joined / `[file name]` / `[type]`); media → image iff
253
+ `mediaType` starts with `image/`, else document; `compaction` part with
254
+ text → synthesized checkpoint node (prior summaries carry over verbatim);
255
+ `compaction` with null text, `effort` parts, and system-role messages →
256
+ skipped.
257
+
258
+ ## Tokenizer
259
+
260
+ Character-class heuristic, verbatim from upstream: ASCII letter runs and
261
+ digit runs count as one token each, punctuation is per-character,
262
+ whitespace is free, and CJK-density characters (CJK, kana, hangul, Thai,
263
+ Lao, Indic scripts) carry extra weight. Every cut lands on a code-point
264
+ boundary — emoji and astral characters always survive intact. ANSI escapes
265
+ and control bytes are stripped deterministically before counting.
266
+
267
+ ## Layout
268
+
269
+ - `index.ts` — thin Effect wiring only (`Plugin.define` + `Effect.fn` +
270
+ `session.hook`). No logic beyond config → `compileCompaction` → assign.
271
+ - `adapter.mjs` — pure mapping + compile (unit-tested, no host). See its
272
+ header for the vocabulary mapping (tool args, tool-result projection,
273
+ checkpoint synthesis, skip cases, tool-link seam).
274
+ - `engine/` — the VCC reference engine vendored byte-identical from
275
+ `../compiler/` (`tokenize`, `compile`, `recall`, `session-compat`,
276
+ `search`). Ships inside the npm tarball; fixes land in `../compiler/`
277
+ first and are re-vendored, never hand-edited (enforced by
278
+ `../scripts/check-engine-sync.mjs`).
279
+ - `selftest.mjs` — adapter unit vectors (`node vcc-plugin/selftest.mjs`).
280
+
281
+ ## Verify
282
+
283
+ ```sh
284
+ node --check vcc-plugin/index.ts
285
+ node vcc-plugin/selftest.mjs
286
+ node scripts/check-engine-sync.mjs
287
+ node compiler/selftest.mjs
288
+ ```
289
+
290
+ Live compaction runs only with explicit approval + explicit `--model`,
291
+ from a scratch project, never a real one.
292
+
293
+ ## Status and limits
294
+
295
+ - v0.1.0 ships the hook + verbatim summary only: no slash commands, no
296
+ recall tools. `(seq N)`
297
+ pointers are 1-based ordinals over the compiled messages (skipped
298
+ messages consume no seq); OpenCode-native
299
+ recall (message/part-ID resolution) is follow-up work.
300
+ - Multi-result tool messages link the first result id only
301
+ (`message.toolCallId` carries one id); the rest still compile as text.
302
+ - `effect` comes from the host instance — declared as peer
303
+ (`effect ^4.0.0`, `@opencode/plugin ^2.0.0`), never bundled.
304
+ - Engine source of truth is `../compiler/`; the `./engine/` copy is
305
+ byte-identical (also recorded: the object-form `package` registration
306
+ with `options:` in Install is how options reach the plugin).
307
+
308
+ MIT licensed — see `../LICENSE`.
package/adapter.mjs ADDED
@@ -0,0 +1,243 @@
1
+ /**
2
+ * Hook adapter: OpenCode `Message` values → VCC `CompileNode` values.
3
+ *
4
+ * Pure offline mapping plus compile (no Effect import, no dependencies
5
+ * beyond `./engine/*`, so it unit-tests with plain node). The thin
6
+ * Effect wiring lives in `index.ts`; everything decidable lives here.
7
+ *
8
+ * Vocabulary notes (verified against the v2.3.2 checkout):
9
+ * - `ToolCallPart.input` is already parsed (unknown) upstream, while the
10
+ * compiler wants a raw JSON string (`parseToolArguments`) — stringify
11
+ * here, unparseable input falls back to name-only one-liners there.
12
+ * - `ToolResultPart.result` is `{ type, value }`, not blocks — project to
13
+ * one text block per part (`projectResultValue`). The compiler's
14
+ * result-pointer pre-pass reads `message.toolCallId` (DSH shape), so the
15
+ * adapter copies the first tool-result part id onto the node message;
16
+ * OpenCode parts link by plain `id`. Multi-result messages link the
17
+ * first part only (documented limitation; the rest still compile).
18
+ * - `CompactionPart` (a prior summary) becomes a synthesized user node
19
+ * with `source: { kind: "compact-checkpoint" }` — the shape the
20
+ * compiler's checkpoint branch matches. Null-text compaction parts,
21
+ * effort parts, and system-role messages are skipped (transient or
22
+ * empty; documented).
23
+ * - Message `metadata` is NOT projected (read-only stored metadata, never
24
+ * DSH `source` shapes).
25
+ * - seqs are 1-based ordinals over the adapted nodes (contiguous:
26
+ * skipped messages consume no seq). The summary's
27
+ * `(seq N)` pointers are positional; OpenCode-native recall (message /
28
+ * part IDs) is follow-up work, not this adapter.
29
+ * - `keepID` must be a message id present in the request (the host splits
30
+ * history at `message.id === keepID`). When no id exists at/after the
31
+ * cut, `compileCompaction` returns undefined and the hook abstains —
32
+ * the host falls back to model compaction. Never a broken summary.
33
+ */
34
+ import {
35
+ COMPILER_REV,
36
+ compileNoisePatterns,
37
+ compileRegion,
38
+ frameCheckpoint,
39
+ } from "./engine/compile.mjs";
40
+
41
+ /** Upstream engine defaults (`src/index.js` in dsh-compaction-vcc@0.7.4). */
42
+ export const DEFAULT_PLUGIN_CONFIG = Object.freeze({
43
+ maxTokens: 8192,
44
+ textTokens: 8192,
45
+ userTextTokens: 16384,
46
+ toolCallTokens: 128,
47
+ toolResultExcerptTokens: 256,
48
+ includeReasoning: false,
49
+ hideTools: [],
50
+ noisePatterns: [],
51
+ keepMessages: 6,
52
+ });
53
+
54
+ /**
55
+ * Project one OpenCode tool-result value to plain text for a text block.
56
+ * @param result - `{ type, value }` tool-result value (may be absent).
57
+ * @returns projected text (possibly empty).
58
+ */
59
+ export function projectResultValue(result) {
60
+ if (result === null || result === undefined) return "";
61
+ if (typeof result !== "object") return String(result);
62
+ const value = result.value;
63
+ switch (result.type) {
64
+ case "text":
65
+ return typeof value === "string" ? value : String(value);
66
+ case "error":
67
+ return `[error] ${String(value)}`;
68
+ case "content": {
69
+ if (!Array.isArray(value)) return String(value);
70
+ return value
71
+ .map((block) => {
72
+ if (block === null || block === undefined) return "";
73
+ if (block.type === "text") return block.text ?? "";
74
+ if (block.type === "file") return `[file ${block.name ?? block.uri ?? "attachment"}]`;
75
+ return `[${String(block.type)}]`;
76
+ })
77
+ .filter((text) => text.length > 0)
78
+ .join("\n");
79
+ }
80
+ case "json":
81
+ default:
82
+ if (typeof value === "string") return value;
83
+ try {
84
+ return JSON.stringify(value) ?? String(value);
85
+ } catch {
86
+ return String(value);
87
+ }
88
+ }
89
+ }
90
+
91
+ /**
92
+ * Map one content part to a compiler block, or null to drop it.
93
+ * @param part - OpenCode content part.
94
+ * @returns compiler block or null.
95
+ */
96
+ function toBlock(part) {
97
+ if (part === null || part === undefined) return null;
98
+ switch (part.type) {
99
+ case "text":
100
+ return { type: "text", text: part.text ?? "" };
101
+ case "reasoning":
102
+ return { type: "reasoning", text: part.text ?? "" };
103
+ case "tool-call": {
104
+ let args;
105
+ try {
106
+ args = typeof part.input === "string" ? part.input : JSON.stringify(part.input) ?? "";
107
+ } catch {
108
+ args = "";
109
+ }
110
+ return { type: "tool-call", id: part.id ?? "", name: part.name ?? "unknown", arguments: args };
111
+ }
112
+ case "tool-result":
113
+ return { type: "text", text: projectResultValue(part.result) };
114
+ case "media": {
115
+ const mime = part.media?.mediaType ?? part.media?.mime ?? "";
116
+ return { type: typeof mime === "string" && mime.startsWith("image/") ? "image" : "document" };
117
+ }
118
+ case "compaction":
119
+ case "effort":
120
+ return null;
121
+ default:
122
+ return { type: String(part.type) };
123
+ }
124
+ }
125
+
126
+ /**
127
+ * Map one request message to a compiler node, or null to skip it.
128
+ * @param message - OpenCode request message (`{ id?, role, content }`).
129
+ * @param seq - 1-based ordinal for this message.
130
+ * @returns compile node or null.
131
+ */
132
+ export function toNode(message, seq) {
133
+ if (message === null || message === undefined) return null;
134
+ if (!Array.isArray(message.content)) return null;
135
+ if (message.role === "system") return null;
136
+ if (message.role === "assistant") {
137
+ const live = message.content.filter((block) => block !== null && block !== undefined);
138
+ if (live.length === 1 && live[0].type === "compaction") {
139
+ const text = live[0].text;
140
+ if (typeof text !== "string" || text.length === 0) return null;
141
+ return { seq, message: { role: "user", content: [{ type: "text", text }], source: { kind: "compact-checkpoint" } } };
142
+ }
143
+ }
144
+ const blocks = [];
145
+ for (const part of message.content) {
146
+ const block = toBlock(part);
147
+ if (block !== null) blocks.push(block);
148
+ }
149
+ if (message.role === "assistant") {
150
+ if (blocks.length === 0) return { seq, message: { role: "assistant", content: [] } };
151
+ return { seq, message: { role: "assistant", content: blocks } };
152
+ }
153
+ if (message.role === "tool") {
154
+ const first = message.content.find((part) => part !== null && part !== undefined && part.type === "tool-result");
155
+ const node = { seq, message: { role: "tool", content: blocks } };
156
+ if (first !== undefined && typeof first.id === "string" && first.id !== "") node.message.toolCallId = first.id;
157
+ return node;
158
+ }
159
+ if (message.role === "user") {
160
+ return { seq, message: { role: "user", content: blocks } };
161
+ }
162
+ return null;
163
+ }
164
+
165
+ /**
166
+ * Pick the keepID: id of the first tailed message (scan forward past
167
+ * id-less messages from the cut point).
168
+ * @param messages - request messages in order.
169
+ * @param keepMessages - how many trailing messages stay verbatim.
170
+ * @returns the keepID, or undefined when no id exists at/after the cut.
171
+ */
172
+ export function pickKeepID(messages, keepMessages) {
173
+ const list = Array.isArray(messages) ? messages : [];
174
+ const keep = Number.isFinite(keepMessages) ? Math.max(1, Math.floor(keepMessages)) : DEFAULT_PLUGIN_CONFIG.keepMessages;
175
+ const cut = Math.max(0, list.length - keep);
176
+ for (let index = cut; index < list.length; index += 1) {
177
+ const id = list[index]?.id;
178
+ if (typeof id === "string" && id !== "") return id;
179
+ }
180
+ return undefined;
181
+ }
182
+
183
+ /**
184
+ * Resolve user options (opencode.jsonc `{package, options}` object form)
185
+ * against the upstream engine defaults. Unknown keys are ignored;
186
+ * invalid values fall back to defaults. Invalid noise patterns throw
187
+ * (fail fast at setup, never a silent no-strip).
188
+ * @param options - `ctx.options` (possibly absent).
189
+ * @returns full compiler config.
190
+ */
191
+ export function buildConfig(options) {
192
+ const input = options !== null && typeof options === "object" ? options : {};
193
+ const num = (key) => {
194
+ const value = input[key];
195
+ return typeof value === "number" && Number.isFinite(value) && value > 0
196
+ ? value
197
+ : DEFAULT_PLUGIN_CONFIG[key];
198
+ };
199
+ const hideTools = Array.isArray(input.hideTools)
200
+ ? input.hideTools.filter((name) => typeof name === "string")
201
+ : [];
202
+ const noiseSources = Array.isArray(input.noisePatterns)
203
+ ? input.noisePatterns.filter((source) => typeof source === "string")
204
+ : [];
205
+ return {
206
+ maxTokens: num("maxTokens"),
207
+ textTokens: num("textTokens"),
208
+ userTextTokens: num("userTextTokens"),
209
+ toolCallTokens: num("toolCallTokens"),
210
+ toolResultExcerptTokens: num("toolResultExcerptTokens"),
211
+ includeReasoning: input.includeReasoning === true,
212
+ hideTools,
213
+ noisePatterns: compileNoisePatterns(noiseSources),
214
+ keepMessages: num("keepMessages"),
215
+ };
216
+ }
217
+
218
+ /**
219
+ * Compile one compaction request deterministically.
220
+ * @param messages - request messages in order.
221
+ * @param config - resolved config from `buildConfig`.
222
+ * @returns `{ summary, keepID, stats, capped }`, or undefined to abstain
223
+ * (no id at/after the cut — the hook must leave `result` unset).
224
+ */
225
+ export function compileCompaction(messages, config = buildConfig({})) {
226
+ const list = Array.isArray(messages) ? messages : [];
227
+ const nodes = [];
228
+ for (const message of list) {
229
+ const node = toNode(message, nodes.length + 1);
230
+ if (node !== null) nodes.push(node);
231
+ }
232
+ const keepID = pickKeepID(list, config.keepMessages);
233
+ if (keepID === undefined) return undefined;
234
+ const region = compileRegion(nodes, config);
235
+ const headerLine = `[opencode-vcc-compaction ${COMPILER_REV}: ${nodes.length} messages -> ${region.entries.length} entries]`;
236
+ const footerLine = region.capped === true
237
+ ? [`[cap enforced at ${config.maxTokens} entry tokens]`]
238
+ : undefined;
239
+ const summary = frameCheckpoint(region.entries, headerLine, undefined, footerLine)
240
+ .map((block) => block.text)
241
+ .join("\n\n");
242
+ return { summary, keepID, stats: region.stats, capped: region.capped };
243
+ }