opencode-vcc-compaction 0.1.0 → 0.2.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
@@ -15,7 +15,7 @@ Port of [`dsh-compaction-vcc`](https://github.com/tingfeng-droid/dsh-compaction-
15
15
  directly against `@opencode/plugin/effect` (canonical runtime), so no
16
16
  convert-to-Effect task ever arises. The VCC reference engine is vendored
17
17
  byte-identical from `../compiler/` into `./engine/` (sync-enforced).
18
- Version: `opencode-vcc-compaction@0.1.0`.
18
+ Version: `opencode-vcc-compaction@0.2.0`.
19
19
 
20
20
  ## How it works
21
21
 
@@ -231,16 +231,38 @@ How the budgets behave:
231
231
  - `keepMessages` counts request messages, not entries: the host rebuilds
232
232
  the verbatim tail from `keepID`, the summary covers everything older.
233
233
 
234
- ## Seq pointers and recall
234
+ ## Seq pointers, recall, and search
235
235
 
236
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.
237
+ (skipped messages consume no seq), not durable host ids. Every checkpoint
238
+ heads with a short RECALL guide telling the model how to recover elided
239
+ content; the `/vcc-recall` and `/vcc-search` commands below resolve those
240
+ pointers against the per-session snapshot.
241
+
242
+ ## Commands
243
+
244
+ Server-only slash commands (no `./tui`): `/vcc-recall`, `/vcc-search`,
245
+ `/vcc-status`. Command invocations cannot read history directly, so the
246
+ `context` hook (with `compaction` as backup) persists a cleaned snapshot
247
+ of the session's messages to `ctx.storage` (`vcc-snapshot/<sessionID>`,
248
+ growth-guarded by version/count/lastID); the commands read that
249
+ snapshot. A snapshot written on every context event is fresh enough for
250
+ recall/search; `/vcc-status` reports its age.
251
+
252
+ - `/vcc-recall <seq selection> | result <ref> | checkpoint <ref>` —
253
+ restore exact original content, e.g. `/vcc-recall 3-7`,
254
+ `/vcc-recall result 3`, `/vcc-recall checkpoint 1`. Replies with the
255
+ recalled text plus an event/token count header.
256
+ - `/vcc-search <keyword-or-regex>` — e.g. `/vcc-search login`.
257
+ Replies with `(seq N)` hits plus a recall call-to-action.
258
+ - `/vcc-status` — engine revision, resolved config
259
+ (`maxTokens`/`keepMessages`/reasoning/hide/noise counts), and snapshot
260
+ freshness (version, message count, lastID, age).
261
+
262
+ Results feed back through `session.prompt`, so the agent presents them.
263
+ A nothing-to-do stays silent (log line only, never an empty agent turn);
264
+ a storage read failure replies explicitly ("snapshot read failed, try
265
+ again in a moment"), never a misleading "none yet".
244
266
 
245
267
  ## Message mapping
246
268
 
@@ -267,10 +289,16 @@ and control bytes are stripped deterministically before counting.
267
289
  ## Layout
268
290
 
269
291
  - `index.ts` — thin Effect wiring only (`Plugin.define` + `Effect.fn` +
270
- `session.hook`). No logic beyond config → `compileCompaction` → assign.
292
+ `session.hook` + `command.transform`). No logic beyond config →
293
+ `compileCompaction` → assign, snapshot remember, and the three
294
+ `/vcc-*` command registrations.
271
295
  - `adapter.mjs` — pure mapping + compile (unit-tested, no host). See its
272
296
  header for the vocabulary mapping (tool args, tool-result projection,
273
297
  checkpoint synthesis, skip cases, tool-link seam).
298
+ - `snapshot.mjs` — snapshot store + command policy (clean/build,
299
+ growth-guarded write check, recall/search arg parsing, selection
300
+ resolution, reply formatters, status text). Unit-tested; the only
301
+ module `index.ts` imports command-side.
274
302
  - `engine/` — the VCC reference engine vendored byte-identical from
275
303
  `../compiler/` (`tokenize`, `compile`, `recall`, `session-compat`,
276
304
  `search`). Ships inside the npm tarball; fixes land in `../compiler/`
@@ -292,11 +320,11 @@ from a scratch project, never a real one.
292
320
 
293
321
  ## Status and limits
294
322
 
295
- - v0.1.0 ships the hook + verbatim summary only: no slash commands, no
296
- recall tools. `(seq N)`
323
+ - v0.2.0 ships the hook + three server-only slash commands
324
+ (`/vcc-recall`, `/vcc-search`, `/vcc-status`; no `./tui`). `(seq N)`
297
325
  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.
326
+ messages consume no seq); recall/search resolve them against the
327
+ per-session snapshot.
300
328
  - Multi-result tool messages link the first result id only
301
329
  (`message.toolCallId` carries one id); the rest still compile as text.
302
330
  - `effect` comes from the host instance — declared as peer
package/adapter.mjs CHANGED
@@ -88,6 +88,33 @@ export function projectResultValue(result) {
88
88
  }
89
89
  }
90
90
 
91
+ /**
92
+ * Stringify a tool-call input the same way everywhere (adapter + snapshot).
93
+ * Absent input yields "" (never the literal "null").
94
+ * @param input - raw tool-call input (string, JSON value, or absent).
95
+ * @returns stringified arguments.
96
+ */
97
+ export function stringifyToolInput(input) {
98
+ if (input === undefined || input === null) return "";
99
+ try {
100
+ return typeof input === "string" ? input : JSON.stringify(input) ?? "";
101
+ } catch {
102
+ return "";
103
+ }
104
+ }
105
+
106
+ /**
107
+ * Classify a media part as image/document label (bytes never stored).
108
+ * Accepts OpenCode parts (`part.media.*`) and cleaned snapshot parts
109
+ * (`part.mediaType`).
110
+ * @param part - media-ish part.
111
+ * @returns "image" or "document".
112
+ */
113
+ export function mediaLabel(part) {
114
+ const mime = part?.media?.mediaType ?? part?.media?.mime ?? part?.mediaType ?? "";
115
+ return typeof mime === "string" && mime.startsWith("image/") ? "image" : "document";
116
+ }
117
+
91
118
  /**
92
119
  * Map one content part to a compiler block, or null to drop it.
93
120
  * @param part - OpenCode content part.
@@ -95,25 +122,19 @@ export function projectResultValue(result) {
95
122
  */
96
123
  function toBlock(part) {
97
124
  if (part === null || part === undefined) return null;
125
+ if (typeof part.type !== "string") return null;
98
126
  switch (part.type) {
99
127
  case "text":
100
128
  return { type: "text", text: part.text ?? "" };
101
129
  case "reasoning":
102
130
  return { type: "reasoning", text: part.text ?? "" };
103
131
  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 };
132
+ return { type: "tool-call", id: part.id ?? "", name: part.name ?? "unknown", arguments: stringifyToolInput(part.input) };
111
133
  }
112
134
  case "tool-result":
113
135
  return { type: "text", text: projectResultValue(part.result) };
114
136
  case "media": {
115
- const mime = part.media?.mediaType ?? part.media?.mime ?? "";
116
- return { type: typeof mime === "string" && mime.startsWith("image/") ? "image" : "document" };
137
+ return { type: mediaLabel(part) };
117
138
  }
118
139
  case "compaction":
119
140
  case "effort":
package/index.ts CHANGED
@@ -1,14 +1,33 @@
1
1
  import { Plugin } from "@opencode/plugin/effect"
2
2
  import { Effect } from "effect"
3
3
  import { buildConfig, compileCompaction } from "./adapter.mjs"
4
+ import {
5
+ COMPILER_REV,
6
+ SNAPSHOT_KEY_PREFIX,
7
+ buildSnapshot,
8
+ classifySnapshotStore,
9
+ formatRecallReply,
10
+ formatSearchReply,
11
+ formatStatusText,
12
+ parseRecallArgs,
13
+ parseSearchArgs,
14
+ recallFromSnapshot,
15
+ resolveRecallSelections,
16
+ searchSnapshot,
17
+ snapshotNeedsWrite,
18
+ } from "./snapshot.mjs"
4
19
 
5
20
  // opencode-vcc-compaction: deterministic LLM-free compaction summaries.
6
21
  //
7
- // The hook adapts the request messages through adapter.mjs (pure offline
8
- // mapping + the VCC reference compiler) and sets event.result so the host
9
- // takes its fromHook short-circuit: no model call, tail rebuilt from
22
+ // The compaction hook adapts the request messages through adapter.mjs (pure
23
+ // offline mapping + the VCC reference compiler) and sets event.result so the
24
+ // host takes its fromHook short-circuit: no model call, tail rebuilt from
10
25
  // metadata.keepID. When the adapter abstains (no message id at/after the
11
26
  // keep cut), result stays unset and the host falls back to model compaction.
27
+ // Alongside, context + compaction hooks snapshot cleaned raw messages
28
+ // (snapshot.mjs, growth-guarded by version/count/lastID, warn-and-continue)
29
+ // so the vcc- commands can recall/search history the command ctx cannot
30
+ // read directly.
12
31
  //
13
32
  // Effect-direct by owner decision: written against @opencode/plugin/effect
14
33
  // from the start, so no convert-to-Effect task ever arises.
@@ -17,22 +36,251 @@ export default Plugin.define({
17
36
  id: "opencode-vcc-compaction",
18
37
  effect: Effect.fn(function* (ctx) {
19
38
  const config = buildConfig(ctx.options)
39
+ const seen = new Map<string, { version: number; count: number; lastID: string | undefined }>()
40
+
41
+ const remember = (sessionID: unknown, messages: unknown) =>
42
+ Effect.catch(
43
+ Effect.flatMap(
44
+ Effect.sync(() => {
45
+ if (typeof sessionID !== "string" || sessionID === "") {
46
+ console.warn("[opencode-vcc-compaction] snapshot skipped: missing sessionID")
47
+ return null
48
+ }
49
+ return buildSnapshot(messages as never)
50
+ }),
51
+ (snap) => {
52
+ if (snap === null) return Effect.void
53
+ const prev = seen.get(sessionID as string)
54
+ if (!snapshotNeedsWrite(prev, snap)) return Effect.void
55
+ return Effect.catch(
56
+ Effect.flatMap(
57
+ ctx.storage.set(`${SNAPSHOT_KEY_PREFIX}${sessionID}`, {
58
+ version: snap.version,
59
+ messages: snap.messages,
60
+ count: snap.count,
61
+ ...(snap.lastID === undefined ? {} : { lastID: snap.lastID }),
62
+ writtenAt: Date.now(),
63
+ }),
64
+ () =>
65
+ Effect.sync(() => {
66
+ seen.set(sessionID as string, {
67
+ version: snap.version,
68
+ count: snap.count,
69
+ lastID: snap.lastID,
70
+ })
71
+ }),
72
+ ),
73
+ (error) =>
74
+ Effect.sync(() => {
75
+ console.warn("[opencode-vcc-compaction] snapshot write failed:", error)
76
+ }),
77
+ )
78
+ },
79
+ ),
80
+ (error) =>
81
+ Effect.sync(() => {
82
+ console.warn("[opencode-vcc-compaction] snapshot build failed:", error)
83
+ }),
84
+ )
85
+
86
+ try {
87
+ yield* ctx.session.hook("context", (event) =>
88
+ remember((event as { sessionID: string }).sessionID, (event as { messages: unknown }).messages),
89
+ )
90
+ } catch (error) {
91
+ console.warn("[opencode-vcc-compaction] context hook unavailable; snapshots via compaction only:", error)
92
+ }
20
93
 
21
94
  yield* ctx.session.hook("compaction", (event) =>
22
- Effect.sync(() => {
23
- let outcome
24
- try {
25
- outcome = compileCompaction(event.messages, config)
26
- } catch (error) {
27
- console.warn("[opencode-vcc-compaction] adapter failed; leaving result unset:", error)
28
- return
29
- }
30
- if (outcome === undefined) return
31
- event.result = {
32
- summary: outcome.summary,
33
- metadata: { keepID: outcome.keepID },
34
- }
35
- }),
95
+ Effect.flatMap(
96
+ remember((event as { sessionID: string }).sessionID, (event as { messages: unknown }).messages),
97
+ () =>
98
+ Effect.sync(() => {
99
+ let outcome
100
+ try {
101
+ outcome = compileCompaction(event.messages, config)
102
+ } catch (error) {
103
+ console.warn("[opencode-vcc-compaction] adapter failed; leaving result unset:", error)
104
+ return
105
+ }
106
+ if (outcome === undefined) return
107
+ event.result = {
108
+ summary: outcome.summary,
109
+ metadata: { keepID: outcome.keepID },
110
+ }
111
+ }),
112
+ ),
36
113
  )
114
+
115
+ try {
116
+ yield* ctx.command.transform((editor) => {
117
+ editor.add({
118
+ name: "vcc-recall",
119
+ description: "Restore exact original content from this session by (seq N), result, or checkpoint reference.",
120
+ execute: (input) =>
121
+ Effect.catchCause(
122
+ Effect.flatMap(
123
+ Effect.sync(() => parseRecallArgs((input.prompt as { text?: unknown })?.text ?? "")),
124
+ (parsed) => {
125
+ if ("error" in parsed) {
126
+ return ctx.session.prompt({
127
+ sessionID: input.sessionID,
128
+ text: `**/vcc-recall** — ${parsed.error}`,
129
+ delivery: input.delivery,
130
+ })
131
+ }
132
+ return Effect.flatMap(
133
+ Effect.catch(
134
+ ctx.storage.get(`${SNAPSHOT_KEY_PREFIX}${input.sessionID}`),
135
+ (error) =>
136
+ Effect.sync(() => {
137
+ console.warn("[opencode-vcc-compaction] vcc-recall: snapshot read failed:", error)
138
+ return { __vccReadFailed: true as const }
139
+ }),
140
+ ),
141
+ (stored) => {
142
+ const classified = classifySnapshotStore(stored as never)
143
+ if (classified.status === "failed") {
144
+ return ctx.session.prompt({
145
+ sessionID: input.sessionID,
146
+ text: "**/vcc-recall** — snapshot read failed, try again in a moment",
147
+ delivery: input.delivery,
148
+ })
149
+ }
150
+ if (classified.status === "empty") {
151
+ console.log("[opencode-vcc-compaction] vcc-recall: no snapshot yet for this session")
152
+ return Effect.void
153
+ }
154
+ const resolved = resolveRecallSelections(classified.messages as never, parsed.type, parsed.id)
155
+ if (resolved.errors.length > 0 || resolved.selections.length === 0) {
156
+ return ctx.session.prompt({
157
+ sessionID: input.sessionID,
158
+ text: `**/vcc-recall** — ${resolved.errors.join("; ") || "nothing to recall"}`,
159
+ delivery: input.delivery,
160
+ })
161
+ }
162
+ const recalled = recallFromSnapshot(classified.messages as never, resolved.selections)
163
+ return ctx.session.prompt({
164
+ sessionID: input.sessionID,
165
+ text: formatRecallReply(parsed.type, parsed.id, recalled as never),
166
+ delivery: input.delivery,
167
+ })
168
+ },
169
+ )
170
+ },
171
+ ),
172
+ (cause) =>
173
+ Effect.sync(() => {
174
+ console.warn("[opencode-vcc-compaction] vcc-recall failed:", cause)
175
+ }),
176
+ ),
177
+ })
178
+ editor.add({
179
+ name: "vcc-search",
180
+ description: "Search this session's history by keyword or regex; returns (seq N) hits for /vcc-recall.",
181
+ execute: (input) =>
182
+ Effect.catchCause(
183
+ Effect.flatMap(
184
+ Effect.sync(() => parseSearchArgs((input.prompt as { text?: unknown })?.text ?? "")),
185
+ (parsed) => {
186
+ if ("error" in parsed) {
187
+ return ctx.session.prompt({
188
+ sessionID: input.sessionID,
189
+ text: `**/vcc-search** — ${parsed.error}`,
190
+ delivery: input.delivery,
191
+ })
192
+ }
193
+ return Effect.flatMap(
194
+ Effect.catch(
195
+ ctx.storage.get(`${SNAPSHOT_KEY_PREFIX}${input.sessionID}`),
196
+ (error) =>
197
+ Effect.sync(() => {
198
+ console.warn("[opencode-vcc-compaction] vcc-search: snapshot read failed:", error)
199
+ return { __vccReadFailed: true as const }
200
+ }),
201
+ ),
202
+ (stored) => {
203
+ const classified = classifySnapshotStore(stored as never)
204
+ if (classified.status === "failed") {
205
+ return ctx.session.prompt({
206
+ sessionID: input.sessionID,
207
+ text: "**/vcc-search** — snapshot read failed, try again in a moment",
208
+ delivery: input.delivery,
209
+ })
210
+ }
211
+ if (classified.status === "empty") {
212
+ console.log("[opencode-vcc-compaction] vcc-search: no snapshot yet for this session")
213
+ return Effect.void
214
+ }
215
+ let found
216
+ try {
217
+ found = searchSnapshot(classified.messages as never, parsed.pattern)
218
+ } catch (error) {
219
+ return ctx.session.prompt({
220
+ sessionID: input.sessionID,
221
+ text: `**/vcc-search** — ${error instanceof Error ? error.message : String(error)}`,
222
+ delivery: input.delivery,
223
+ })
224
+ }
225
+ return ctx.session.prompt({
226
+ sessionID: input.sessionID,
227
+ text: formatSearchReply(parsed.pattern, found as never),
228
+ delivery: input.delivery,
229
+ })
230
+ },
231
+ )
232
+ },
233
+ ),
234
+ (cause) =>
235
+ Effect.sync(() => {
236
+ console.warn("[opencode-vcc-compaction] vcc-search failed:", cause)
237
+ }),
238
+ ),
239
+ })
240
+ editor.add({
241
+ name: "vcc-status",
242
+ description: "Show opencode-vcc-compaction engine revision, config, and snapshot freshness.",
243
+ execute: (input) =>
244
+ Effect.catchCause(
245
+ Effect.flatMap(
246
+ Effect.catch(
247
+ ctx.storage.get(`${SNAPSHOT_KEY_PREFIX}${input.sessionID}`),
248
+ (error) =>
249
+ Effect.sync(() => {
250
+ console.warn("[opencode-vcc-compaction] vcc-status: snapshot read failed:", error)
251
+ return { __vccReadFailed: true as const }
252
+ }),
253
+ ),
254
+ (stored) => {
255
+ const classified = classifySnapshotStore(stored as never)
256
+ if (classified.status === "failed") {
257
+ return ctx.session.prompt({
258
+ sessionID: input.sessionID,
259
+ text: "**/vcc-status** — snapshot read failed, try again in a moment",
260
+ delivery: input.delivery,
261
+ })
262
+ }
263
+ return ctx.session.prompt({
264
+ sessionID: input.sessionID,
265
+ text: formatStatusText(
266
+ classified.status === "ready" ? classified.stored as never : undefined,
267
+ config as never,
268
+ COMPILER_REV as string,
269
+ Date.now(),
270
+ ),
271
+ delivery: input.delivery,
272
+ })
273
+ },
274
+ ),
275
+ (cause) =>
276
+ Effect.sync(() => {
277
+ console.warn("[opencode-vcc-compaction] vcc-status failed:", cause)
278
+ }),
279
+ ),
280
+ })
281
+ })
282
+ } catch (error) {
283
+ console.warn("[opencode-vcc-compaction] command API unavailable; /vcc-* commands not registered:", error)
284
+ }
37
285
  }),
38
286
  })
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "opencode-vcc-compaction",
3
- "version": "0.1.0",
3
+ "version": "0.2.0",
4
4
  "description": "Deterministic LLM-free compaction summaries for OpenCode V2 (VCC reference engine, Effect-direct hook).",
5
5
  "license": "MIT",
6
6
  "author": "jwitmann <jerome_witmann@witmanco.net>",
@@ -24,7 +24,7 @@
24
24
  ],
25
25
  "type": "module",
26
26
  "main": "./index.ts",
27
- "files": ["index.ts", "adapter.mjs", "engine/", "README.md"],
27
+ "files": ["index.ts", "adapter.mjs", "snapshot.mjs", "engine/", "README.md"],
28
28
  "engines": {
29
29
  "node": ">=18"
30
30
  },
package/snapshot.mjs ADDED
@@ -0,0 +1,515 @@
1
+ /**
2
+ * Snapshot store for vcc- commands: cleaned raw messages + session view.
3
+ *
4
+ * Why cleaned raw (not projected nodes): `toNode` bakes in config
5
+ * (`includeReasoning`, `hideTools`) and elides for compile budgets. Recall
6
+ * is the lossless counterpart, so the snapshot keeps full text, reasoning,
7
+ * raw tool-call input, and full tool-result values for the known part
8
+ * vocabulary — stripping only transport bloat (`cache`, `metadata`,
9
+ * `providerMetadata`) and media bytes (recall renders media as labels
10
+ * anyway, via the shared `mediaLabel` helper); unknown future part types
11
+ * are label-only. Readers re-project through `toNode` for seq assignment, so
12
+ * recall/search seqs are by construction identical to checkpoint
13
+ * `(seq N)` pointers. `cleanPart` intentionally mirrors `toBlock`
14
+ * (adapter.mjs): lossless store vs lossy compile projection — do not
15
+ * "unify" them; shared tables (`stringifyToolInput`, `mediaLabel`,
16
+ * `projectResultValue`) are imported, the keep/drop rules differ on purpose.
17
+ *
18
+ * System messages are dropped at write time (transient preamble, never
19
+ * compiled, never sequenced). Effort parts are dropped (transient effort
20
+ * updates; compile keeps the message shell with empty content so seqs
21
+ * still align).
22
+ *
23
+ * Event shape: `{ seq, type, data: { message, source? } }` where `seq` is
24
+ * the 1-based ordinal over `toNode`-kept messages (skipped messages consume
25
+ * no seq — same rule as the checkpoint header). Types: user messages get
26
+ * `user/message`, assistant `assistant/message`, tool `tool/result` (so
27
+ * `result N` refs resolve), and synthesized checkpoints `user/message`
28
+ * with `source: { kind: "compact-checkpoint" }` (so `findCheckpointSeqs`
29
+ * and `checkpoint N` refs work).
30
+ *
31
+ * Search deviation (documented): upstream `search.mjs` scans positionally
32
+ * (`events[seq]` with `event.seq === seq`, 0-based) over the array the
33
+ * session yields, which can never match 1-based seqs. `searchSnapshot`
34
+ * pads a dummy seq-0 entry so the verbatim `searchSession` contract holds,
35
+ * then delegates — no forked search loop to hand-sync. Same hits, honest
36
+ * seqs.
37
+ *
38
+ * The session log is append-only: `snapshotNeedsWrite` is a growth guard
39
+ * (version/count/lastID). In-place edits to middle messages are not
40
+ * detected by design. Imports come from the vendored `./engine/` (ships in
41
+ * the tarball), never `../compiler/`.
42
+ */
43
+
44
+ import { mediaLabel, projectResultValue, stringifyToolInput, toNode } from "./adapter.mjs";
45
+ import {
46
+ DEFAULT_MAX_RECALL_TOKENS,
47
+ recallSession,
48
+ resolveRecallReference,
49
+ } from "./engine/recall.mjs";
50
+ import {
51
+ DEFAULT_MAX_SEARCH_HITS,
52
+ searchSession,
53
+ } from "./engine/search.mjs";
54
+
55
+ /** Re-exported so command wiring imports only `snapshot.mjs`, never `./engine/` directly. */
56
+ export { COMPILER_REV } from "./engine/compile.mjs";
57
+
58
+ export const SNAPSHOT_VERSION = 1;
59
+
60
+ /** Storage key prefix; full key is `${SNAPSHOT_KEY_PREFIX}${sessionID}`. */
61
+ export const SNAPSHOT_KEY_PREFIX = "vcc-snapshot/";
62
+
63
+ /**
64
+ * Strip one content part to its storable core.
65
+ * @param part - OpenCode content part.
66
+ * @returns cleaned part, or null to drop.
67
+ */
68
+ export function cleanPart(part) {
69
+ if (part === null || part === undefined) return null;
70
+ if (typeof part.type !== "string") return null;
71
+ switch (part.type) {
72
+ case "text":
73
+ return { type: "text", text: part.text ?? "" };
74
+ case "reasoning":
75
+ return { type: "reasoning", text: part.text ?? "" };
76
+ case "tool-call":
77
+ return {
78
+ type: "tool-call",
79
+ id: typeof part.id === "string" ? part.id : "",
80
+ name: typeof part.name === "string" ? part.name : "unknown",
81
+ ...(part.input === undefined ? {} : { input: part.input }),
82
+ };
83
+ case "tool-result":
84
+ return {
85
+ type: "tool-result",
86
+ id: typeof part.id === "string" ? part.id : "",
87
+ name: typeof part.name === "string" ? part.name : "unknown",
88
+ result: part.result ?? null,
89
+ };
90
+ case "media": {
91
+ const mime = part.media?.mediaType ?? part.media?.mime ?? "";
92
+ return {
93
+ type: "media",
94
+ mediaType: typeof mime === "string" ? mime : "",
95
+ };
96
+ }
97
+ case "compaction":
98
+ return typeof part.text === "string" && part.text.length > 0
99
+ ? { type: "compaction", text: part.text }
100
+ : null;
101
+ case "effort":
102
+ return null;
103
+ default:
104
+ return { type: String(part.type) };
105
+ }
106
+ }
107
+
108
+ /**
109
+ * Strip one request message to its storable core. System role and
110
+ * empty/invalid content are dropped (never compiled, never sequenced).
111
+ * @param message - OpenCode request message.
112
+ * @returns cleaned message, or null to drop.
113
+ */
114
+ export function cleanMessage(message) {
115
+ if (message === null || message === undefined) return null;
116
+ if (!Array.isArray(message.content)) return null;
117
+ if (message.role === "system") return null;
118
+ const id = typeof message.id === "string" && message.id !== "" ? message.id : undefined;
119
+ if (message.role === "assistant") {
120
+ const live = message.content.filter(
121
+ (block) => block !== null && block !== undefined,
122
+ );
123
+ if (live.length === 1 && live[0]?.type === "compaction") {
124
+ const text = live[0].text;
125
+ if (typeof text !== "string" || text.length === 0) return null;
126
+ return {
127
+ ...(id === undefined ? {} : { id }),
128
+ role: "assistant",
129
+ content: [{ type: "compaction", text }],
130
+ };
131
+ }
132
+ const content = [];
133
+ for (const part of message.content) {
134
+ const cleaned = cleanPart(part);
135
+ if (cleaned !== null) content.push(cleaned);
136
+ }
137
+ return {
138
+ ...(id === undefined ? {} : { id }),
139
+ role: "assistant",
140
+ content,
141
+ };
142
+ }
143
+ const content = [];
144
+ for (const part of message.content) {
145
+ const cleaned = cleanPart(part);
146
+ if (cleaned !== null) content.push(cleaned);
147
+ }
148
+ // Mirror toNode: user/tool shells are kept even when empty (they consume a
149
+ // seq on the compile side); only system/empty-invalid messages are dropped.
150
+ return {
151
+ ...(id === undefined ? {} : { id }),
152
+ role: message.role,
153
+ content,
154
+ };
155
+ }
156
+
157
+ /**
158
+ * Build a snapshot from request messages.
159
+ * @param messages - request messages in order.
160
+ * @returns `{ version, messages, count, lastID }`.
161
+ */
162
+ export function buildSnapshot(messages) {
163
+ const list = Array.isArray(messages) ? messages : [];
164
+ const cleaned = [];
165
+ for (const message of list) {
166
+ const kept = cleanMessage(message);
167
+ if (kept !== null) cleaned.push(kept);
168
+ }
169
+ let lastID;
170
+ for (let index = cleaned.length - 1; index >= 0; index -= 1) {
171
+ if (typeof cleaned[index].id === "string" && cleaned[index].id !== "") {
172
+ lastID = cleaned[index].id;
173
+ break;
174
+ }
175
+ }
176
+ return {
177
+ version: SNAPSHOT_VERSION,
178
+ messages: cleaned,
179
+ count: cleaned.length,
180
+ lastID,
181
+ };
182
+ }
183
+
184
+ /**
185
+ * Parse a `/vcc-recall` invocation into a typed recall reference.
186
+ * Strips a leading `/vcc-recall` command prefix when present.
187
+ * @param text - raw invocation prompt text.
188
+ * @returns `{ type, id }`, or `{ error }` with usage text.
189
+ */
190
+ export function parseRecallArgs(text) {
191
+ const raw = String(text ?? "").replace(/^\s*\/vcc-recall\b/iu, "").trim();
192
+ if (raw.length === 0) return { error: "usage: /vcc-recall <seq selection> | result <ref> | checkpoint <ref> (e.g. `/vcc-recall 3-7`, `/vcc-recall result 3`, `/vcc-recall checkpoint 1`)" };
193
+ const lowered = raw.toLowerCase();
194
+ if (lowered === "result" || lowered.startsWith("result ")) {
195
+ const id = raw.slice(6).trim();
196
+ if (id.length === 0) return { error: "usage: /vcc-recall result <seq> (e.g. `/vcc-recall result 3`)" };
197
+ return { type: "result", id };
198
+ }
199
+ if (lowered === "checkpoint" || lowered.startsWith("checkpoint ")) {
200
+ const id = raw.slice(10).trim();
201
+ if (id.length === 0) return { error: "usage: /vcc-recall checkpoint <ordinal|seq> (e.g. `/vcc-recall checkpoint 1`)" };
202
+ return { type: "checkpoint", id };
203
+ }
204
+ return { type: "seq", id: raw };
205
+ }
206
+
207
+ /**
208
+ * Resolve a parsed recall reference against snapshot messages.
209
+ * Thin wrapper over engine `resolveRecallReference` (via
210
+ * `makeSnapshotSession`) so command wiring imports only `snapshot.mjs`.
211
+ * @param cleanedMessages - snapshot `messages`.
212
+ * @param type - reference type: `seq`, `result`, or `checkpoint`.
213
+ * @param id - type-dependent reference text.
214
+ * @returns `{ selections, errors }`.
215
+ */
216
+ export function resolveRecallSelections(cleanedMessages, type, id) {
217
+ return resolveRecallReference(makeSnapshotSession(cleanedMessages), type, id);
218
+ }
219
+
220
+ /**
221
+ * Strip a `/vcc-search` command prefix, returning the raw pattern.
222
+ * @param text - raw invocation prompt text.
223
+ * @returns `{ pattern }`, or `{ error }` with usage text.
224
+ */
225
+ export function parseSearchArgs(text) {
226
+ const pattern = String(text ?? "").replace(/^\s*\/vcc-search\b/iu, "").trim();
227
+ if (pattern.length === 0) return { error: "usage: /vcc-search <keyword-or-regex> (e.g. `/vcc-search login`)" };
228
+ return { pattern };
229
+ }
230
+
231
+ /**
232
+ * Format a `/vcc-status` reply from the stored snapshot and live config.
233
+ * Pure (caller supplies `now`); never throws on malformed snapshots.
234
+ * @param stored - storage value (`{ version, messages, count, lastID, writtenAt }` or undefined).
235
+ * @param config - resolved plugin config from `buildConfig`.
236
+ * @param rev - engine revision string.
237
+ * @param now - current epoch ms (for age computation).
238
+ * @returns status text.
239
+ */
240
+ export function formatStatusText(stored, config, rev, now) {
241
+ const lines = [`**/vcc-status** — opencode-vcc-compaction (engine ${rev})`];
242
+ const cfg = config !== null && typeof config === "object" ? config : {};
243
+ const maxTokens = typeof cfg.maxTokens === "number" ? cfg.maxTokens : "?";
244
+ const keepMessages = typeof cfg.keepMessages === "number" ? cfg.keepMessages : "?";
245
+ const reasoning = cfg.includeReasoning === true ? "on" : "off";
246
+ const hide = Array.isArray(cfg.hideTools) ? cfg.hideTools.length : 0;
247
+ const noise = Array.isArray(cfg.noisePatterns) ? cfg.noisePatterns.length : "?";
248
+ lines.push(`config: maxTokens=${maxTokens} keepMessages=${keepMessages} reasoning=${reasoning} hideTools=${hide} noisePatterns=${noise}`);
249
+ const snap = stored !== null && typeof stored === "object" ? stored : undefined;
250
+ const messages = Array.isArray(snap?.messages) ? snap.messages : undefined;
251
+ if (messages === undefined) {
252
+ lines.push("snapshot: none yet (recall/search will stay silent until the first context event lands)");
253
+ return lines.join("\n");
254
+ }
255
+ const count = typeof snap.count === "number" ? snap.count : messages.length;
256
+ const version = typeof snap.version === "number" ? snap.version : "?";
257
+ const lastID = typeof snap.lastID === "string" && snap.lastID !== "" ? snap.lastID : "(none)";
258
+ let age = "(unknown age)";
259
+ if (typeof snap.writtenAt === "number" && Number.isFinite(snap.writtenAt) && typeof now === "number" && Number.isFinite(now)) {
260
+ const seconds = Math.max(0, Math.floor((now - snap.writtenAt) / 1000));
261
+ age = seconds < 60 ? `${seconds}s ago` : `${Math.floor(seconds / 60)}m ago`;
262
+ }
263
+ lines.push(`snapshot: v${version}, ${count} message(s), lastID=${lastID}, written ${age}`);
264
+ return lines.join("\n");
265
+ }
266
+
267
+ /**
268
+ * Classify a storage read for command wiring: one shared outcome for all
269
+ * vcc- commands so read-failure vs empty vs ready never diverge per command.
270
+ * @param stored - raw `ctx.storage.get` value (or the read-failure sentinel).
271
+ * @returns `{ status: "failed" }`, `{ status: "empty" }`, or `{ status: "ready", messages }`.
272
+ */
273
+ export function classifySnapshotStore(stored) {
274
+ if (stored !== undefined && stored !== null && stored.__vccReadFailed === true) return { status: "failed" };
275
+ const envelope = stored !== null && typeof stored === "object" ? stored : undefined;
276
+ const messages = envelope?.messages;
277
+ if (!Array.isArray(messages) || messages.length === 0) return { status: "empty" };
278
+ return { status: "ready", messages, stored: envelope };
279
+ }
280
+
281
+ /**
282
+ * Format a `/vcc-recall` agent reply (header + recalled text).
283
+ * @param type - reference type (`seq`, `result`, `checkpoint`).
284
+ * @param id - reference text.
285
+ * @param recalled - `recallSession` output.
286
+ * @returns reply text.
287
+ */
288
+ export function formatRecallReply(type, id, recalled) {
289
+ const label = `**/vcc-recall ${type} ${id}** (${recalled.seqs.length} event(s), ${recalled.tokens} tokens${recalled.missing > 0 ? `, ${recalled.missing} missing` : ""}${recalled.truncated ? ", budget-truncated" : ""})`;
290
+ return `${label}\n\n${recalled.text}`;
291
+ }
292
+
293
+ /**
294
+ * Format a `/vcc-search` agent reply (header + search text).
295
+ * @param pattern - raw search pattern.
296
+ * @param found - `searchSession` output.
297
+ * @returns reply text.
298
+ */
299
+ export function formatSearchReply(pattern, found) {
300
+ return `**/vcc-search ${pattern}** (${found.totalMatches} matching event(s))\n\n${found.text}`;
301
+ }
302
+
303
+ /**
304
+ * Decide whether a snapshot write is needed (growth guard).
305
+ * @param previous - `{ version, count, lastID }` from the last write (or undefined).
306
+ * @param next - candidate snapshot meta.
307
+ * @returns true when first-write, version-bumped, or grown.
308
+ */
309
+ export function snapshotNeedsWrite(previous, next) {
310
+ if (previous === null || previous === undefined) return true;
311
+ if ((previous.version ?? SNAPSHOT_VERSION) !== next.version) return true;
312
+ if (next.count !== previous.count) return true;
313
+ return next.lastID !== previous.lastID;
314
+ }
315
+
316
+ /**
317
+ * Map one cleaned part to a recall block.
318
+ * @param part - cleaned part.
319
+ * @returns recall block, or null to drop.
320
+ */
321
+ function recallBlock(part) {
322
+ switch (part.type) {
323
+ case "text":
324
+ return { type: "text", text: part.text ?? "" };
325
+ case "reasoning":
326
+ return { type: "reasoning", text: part.text ?? "" };
327
+ case "tool-call": {
328
+ return { type: "tool-call", name: part.name ?? "unknown", arguments: stringifyToolInput(part.input) };
329
+ }
330
+ case "tool-result": {
331
+ const result = part.result;
332
+ if (result !== null && typeof result === "object" && result.type === "content" && Array.isArray(result.value)) {
333
+ const content = [];
334
+ for (const block of result.value) {
335
+ if (block === null || block === undefined) continue;
336
+ if (block.type === "text") content.push({ type: "text", text: block.text ?? "" });
337
+ else if (block.type === "file") {
338
+ content.push({
339
+ type: "text",
340
+ text: `[file ${block.name ?? block.uri ?? "attachment"}]`,
341
+ });
342
+ } else content.push({ type: String(block.type) });
343
+ }
344
+ return { type: "tool-result", content };
345
+ }
346
+ return { type: "tool-result", content: [{ type: "text", text: projectResultValue(result) }] };
347
+ }
348
+ case "media": {
349
+ return { type: mediaLabel(part) };
350
+ }
351
+ case "compaction":
352
+ return { type: "text", text: part.text ?? "" };
353
+ default:
354
+ return { type: String(part.type) };
355
+ }
356
+ }
357
+
358
+ /**
359
+ * Project one cleaned message to a recall message (`deriveEventMessage`
360
+ * output): `{ role, content }` with recall blocks.
361
+ * @param cleaned - cleaned message.
362
+ * @returns recall message.
363
+ */
364
+ export function snapshotMessageToRecall(cleaned) {
365
+ const content = Array.isArray(cleaned?.content) ? cleaned.content : [];
366
+ if (cleaned?.role === "assistant" && content.length === 1 && content[0]?.type === "compaction") {
367
+ return { role: "user", content: [{ type: "text", text: content[0].text ?? "" }] };
368
+ }
369
+ const blocks = [];
370
+ for (const part of content) {
371
+ if (part === null || part === undefined || typeof part.type !== "string") continue;
372
+ const block = recallBlock(part);
373
+ if (block !== null) blocks.push(block);
374
+ }
375
+ return { role: cleaned?.role ?? "user", content: blocks };
376
+ }
377
+
378
+ /**
379
+ * Build the session-shaped event list from cleaned messages. Seq assignment
380
+ * goes through `toNode` directly on the cleaned messages (same filter +
381
+ * 1-based ordinals as checkpoints); payloads stay lossless cleaned raw.
382
+ * @param cleanedMessages - snapshot `messages`.
383
+ * @returns event array with `seq`, `type`, `data`.
384
+ */
385
+ export function toSnapshotEvents(cleanedMessages) {
386
+ const list = Array.isArray(cleanedMessages) ? cleanedMessages : [];
387
+ const events = [];
388
+ for (const cleaned of list) {
389
+ if (cleaned === null || cleaned === undefined || !Array.isArray(cleaned.content)) continue;
390
+ const node = toNode(cleaned, events.length + 1);
391
+ if (node === null) continue;
392
+ const isCheckpoint =
393
+ node.message?.role === "user" &&
394
+ node.message?.source?.kind === "compact-checkpoint";
395
+ const type = isCheckpoint
396
+ ? "user/message"
397
+ : cleaned.role === "user"
398
+ ? "user/message"
399
+ : cleaned.role === "tool"
400
+ ? "tool/result"
401
+ : "assistant/message";
402
+ events.push({
403
+ seq: node.seq,
404
+ type,
405
+ data: {
406
+ message: cleaned,
407
+ ...(isCheckpoint ? { source: { kind: "compact-checkpoint" } } : {}),
408
+ },
409
+ });
410
+ }
411
+ return events;
412
+ }
413
+
414
+ /**
415
+ * Make the session-shaped value `recall.mjs` / `search.mjs` read through
416
+ * `session-compat` (`snapshotEvents` + `eventAt` + `deriveEventMessage`).
417
+ * @param cleanedMessages - snapshot `messages`.
418
+ * @returns session-shaped value.
419
+ */
420
+ export function makeSnapshotSession(cleanedMessages) {
421
+ const events = toSnapshotEvents(cleanedMessages);
422
+ const frozen = Object.freeze(events.slice());
423
+ const bySeq = new Map(frozen.map((event) => [event.seq, event]));
424
+ return {
425
+ snapshotEvents() {
426
+ return frozen;
427
+ },
428
+ eventAt(seq) {
429
+ return bySeq.get(seq) ?? undefined;
430
+ },
431
+ get events() {
432
+ return frozen;
433
+ },
434
+ deriveEventMessage(event) {
435
+ const cleaned = event?.data?.message;
436
+ if (cleaned === null || cleaned === undefined) return null;
437
+ return snapshotMessageToRecall(cleaned);
438
+ },
439
+ };
440
+ }
441
+
442
+ /**
443
+ * Recall full original content for parsed selections from a snapshot.
444
+ * Thin wrapper over `recallSession` so commands need no DSH imports.
445
+ * @param cleanedMessages - snapshot `messages`.
446
+ * @param selections - parsed inclusive ranges.
447
+ * @param maxRecallTokens - total budget (defaults to engine default).
448
+ * @returns `recallSession` output.
449
+ */
450
+ export function recallFromSnapshot(cleanedMessages, selections, maxRecallTokens = DEFAULT_MAX_RECALL_TOKENS) {
451
+ const budget = typeof maxRecallTokens === "number" && Number.isFinite(maxRecallTokens) && maxRecallTokens > 0
452
+ ? maxRecallTokens
453
+ : DEFAULT_MAX_RECALL_TOKENS;
454
+ return recallSession(makeSnapshotSession(cleanedMessages), selections, { maxRecallTokens: budget });
455
+ }
456
+
457
+ /**
458
+ * Search a snapshot for a pattern by delegating to the verbatim
459
+ * `searchSession`: pad a dummy seq-0 entry so the positional
460
+ * `events[seq]` + `seq === seq` contract holds for 1-based seqs.
461
+ * @param cleanedMessages - snapshot `messages`.
462
+ * @param patternSource - raw regex/keyword.
463
+ * @param config - `{ maxSearchHits, maxRecallTokens }` (defaults to engine defaults).
464
+ * @returns `searchSession` output.
465
+ */
466
+ export function searchSnapshot(cleanedMessages, patternSource, config = {}) {
467
+ const input = config !== null && typeof config === "object" ? config : {};
468
+ const maxSearchHits = typeof input.maxSearchHits === "number" && Number.isFinite(input.maxSearchHits) && input.maxSearchHits > 0
469
+ ? Math.floor(input.maxSearchHits)
470
+ : DEFAULT_MAX_SEARCH_HITS;
471
+ const maxRecallTokens = typeof input.maxRecallTokens === "number" && Number.isFinite(input.maxRecallTokens) && input.maxRecallTokens > 0
472
+ ? input.maxRecallTokens
473
+ : DEFAULT_MAX_RECALL_TOKENS;
474
+ const inner = makeSnapshotSession(cleanedMessages);
475
+ const live = inner.snapshotEvents();
476
+ const padded = [{ seq: 0, type: "session.created", data: {} }, ...live];
477
+ const paddedSession = {
478
+ snapshotEvents() {
479
+ return padded;
480
+ },
481
+ eventAt(seq) {
482
+ if (seq === 0) return padded[0];
483
+ return inner.eventAt(seq);
484
+ },
485
+ get events() {
486
+ return padded;
487
+ },
488
+ deriveEventMessage(event) {
489
+ if (event?.seq === 0) return null;
490
+ return inner.deriveEventMessage(event);
491
+ },
492
+ };
493
+ const out = searchSession(paddedSession, patternSource, { maxSearchHits, maxRecallTokens });
494
+ // The seq-0 pad satisfies the verbatim positional scan but must never
495
+ // surface: seq 0 is unrecallable (`parseSeqSpec` rejects it), so drop any
496
+ // phantom hit and rebuild the summary around the live hits.
497
+ const hits = out.hits.filter((hit) => hit.seq !== 0);
498
+ const dropped = out.hits.length - hits.length;
499
+ const totalMatches = out.totalMatches - dropped;
500
+ const omitted = Math.max(0, totalMatches - hits.length);
501
+ const lines = [
502
+ `[search "${out.pattern}": ${totalMatches} matching event(s)]`,
503
+ ...hits.map((hit) => hit.text),
504
+ ...(omitted > 0 ? [`[${omitted} more matching event(s) omitted — narrow the pattern or use recall]`] : []),
505
+ ...(out.truncated ? ["[search budget exhausted; some hits were cut]"] : []),
506
+ ];
507
+ if (hits.length > 0) lines.push("[use recall with a (seq N) pointer to restore any hit's full original content]");
508
+ return {
509
+ ...out,
510
+ totalMatches,
511
+ hits,
512
+ omitted,
513
+ text: lines.join("\n\n"),
514
+ };
515
+ }