opencode-vcc-compaction 0.1.0 → 0.3.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,58 @@ 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 slash commands (plus the `./tui` companion below):
245
+ `/vcc-recall`, `/vcc-search`,
246
+ `/vcc-status`. Command invocations cannot read history directly, so the
247
+ `context` hook (with `compaction` as backup) persists a cleaned snapshot
248
+ of the session's messages to `ctx.storage` (`vcc-snapshot/<sessionID>`,
249
+ growth-guarded by version/count/lastID); the commands read that
250
+ snapshot. A snapshot written on every context event is fresh enough for
251
+ recall/search; `/vcc-status` reports its age.
252
+
253
+ - `/vcc-recall <seq selection> | result <ref> | checkpoint <ref>` —
254
+ restore exact original content, e.g. `/vcc-recall 3-7`,
255
+ `/vcc-recall result 3`, `/vcc-recall checkpoint 1`. Replies with the
256
+ recalled text plus an event/token count header.
257
+ - `/vcc-search <keyword-or-regex>` — e.g. `/vcc-search login`.
258
+ Replies with `(seq N)` hits plus a recall call-to-action.
259
+ - `/vcc-status` — engine revision, resolved config
260
+ (`maxTokens`/`keepMessages`/reasoning/hide/noise counts), and snapshot
261
+ freshness (version, message count, lastID, age).
262
+
263
+ Results travel as an RPC event the TUI companion renders: each command
264
+ emits `rpc.opencode-vcc-compaction.replied` and returns void with no
265
+ prompt call, so there is no model turn and no chatter — the TUI toasts
266
+ short replies and dialogs long ones (see `./tui` below). This requires
267
+ the companion: add the package to `cli.json` `plugins`. Without a
268
+ connected TUI the emit goes nowhere and the reply is silent — by
269
+ design (no wake), so non-interactive use stays quiet. Only when RPC
270
+ itself is unavailable (or an emit fails) do replies fall back to
271
+ `session.prompt`, where the agent presents them.
272
+ A nothing-to-do stays silent (log line only, never an empty agent turn);
273
+ a storage read failure replies explicitly ("snapshot read failed, try
274
+ again in a moment"), never a misleading "none yet". Unexpected command
275
+ errors attempt a visible "command failed, try again" prompt reply before
276
+ giving up to the log.
277
+
278
+ ## TUI companion (`./tui` export)
279
+
280
+ `tui.tsx` listens for the reply event and renders it immediately: short
281
+ replies as toasts, long ones as large centered dialogs. No keymap
282
+ commands — none are needed, since the event carries its session. Add
283
+ the package to `cli.json` `plugins` (TUI-only surface, also works
284
+ against a remote server). The server commands stay as the transcript
285
+ record; the companion is the quiet visible channel.
244
286
 
245
287
  ## Message mapping
246
288
 
@@ -267,10 +309,16 @@ and control bytes are stripped deterministically before counting.
267
309
  ## Layout
268
310
 
269
311
  - `index.ts` — thin Effect wiring only (`Plugin.define` + `Effect.fn` +
270
- `session.hook`). No logic beyond config → `compileCompaction` → assign.
312
+ `session.hook` + `command.transform`). No logic beyond config →
313
+ `compileCompaction` → assign, snapshot remember, and the three
314
+ `/vcc-*` command registrations.
271
315
  - `adapter.mjs` — pure mapping + compile (unit-tested, no host). See its
272
316
  header for the vocabulary mapping (tool args, tool-result projection,
273
317
  checkpoint synthesis, skip cases, tool-link seam).
318
+ - `snapshot.mjs` — snapshot store + command policy (clean/build,
319
+ growth-guarded write check, recall/search arg parsing, selection
320
+ resolution, reply formatters, status text). Unit-tested; the only
321
+ module `index.ts` imports command-side.
274
322
  - `engine/` — the VCC reference engine vendored byte-identical from
275
323
  `../compiler/` (`tokenize`, `compile`, `recall`, `session-compat`,
276
324
  `search`). Ships inside the npm tarball; fixes land in `../compiler/`
@@ -281,22 +329,26 @@ and control bytes are stripped deterministically before counting.
281
329
  ## Verify
282
330
 
283
331
  ```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
332
+ npm run typecheck # node --check index.ts + tsc -p tsconfig.tui.json
333
+ npm run test # both selftests + engine-sync
334
+ npm run lint:md # markdown lint over the tree
288
335
  ```
289
336
 
337
+ Run from the repo root (workspace scripts; toolchain installs with `npm ci`).
338
+
290
339
  Live compaction runs only with explicit approval + explicit `--model`,
291
340
  from a scratch project, never a real one.
292
341
 
293
342
  ## Status and limits
294
343
 
295
- - v0.1.0 ships the hook + verbatim summary only: no slash commands, no
296
- recall tools. `(seq N)`
344
+ - v0.3.0 (in tree, unreleased — package.json still reads 0.2.0
345
+ until `scripts/release.sh minor` runs) ships the hook + three
346
+ server slash commands
347
+ (`/vcc-recall`, `/vcc-search`, `/vcc-status`) plus the `./tui`
348
+ companion that renders their replies quietly. `(seq N)`
297
349
  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.
350
+ messages consume no seq); recall/search resolve them against the
351
+ per-session snapshot.
300
352
  - Multi-result tool messages link the first result id only
301
353
  (`message.toolCallId` carries one id); the rest still compile as text.
302
354
  - `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/events.mjs ADDED
@@ -0,0 +1,55 @@
1
+ // Event contract for the vcc TUI companion (dependency-free).
2
+ //
3
+ // The server cannot emit visible output without waking the agent, so
4
+ // /vcc-* replies travel as an RPC event the TUI toasts: the server
5
+ // emits `rpc.opencode-vcc-compaction.replied` with the reply payload
6
+ // and returns void with no prompt call (no wake, no chatter, no inbox
7
+ // row). The TUI filters `ctx.data.listen` by `replyEventType()` and
8
+ // renders it.
9
+ //
10
+ // Both `index.ts` (server, Rpc.define + emit) and `tui.tsx` (TUI,
11
+ // listen + dialog) import this module so the type string and payload
12
+ // shape have a single source of truth. No external imports so
13
+ // `selftest.mjs` runs it without node_modules.
14
+
15
+ export const VCC_RPC_ID = "opencode-vcc-compaction";
16
+
17
+ export const VCC_REPLY_EVENT = "replied";
18
+
19
+ export function replyEventType() {
20
+ return `rpc.${VCC_RPC_ID}.${VCC_REPLY_EVENT}`;
21
+ }
22
+
23
+ // The bus carries the whole reply; cap pathological payloads (a huge
24
+ // recall range) so one event cannot flood it. Truncation is explicit.
25
+ export const MAX_REPLY_TEXT = 30000;
26
+
27
+ // Payload the server emits per command reply. `command` is the slash
28
+ // name without arguments ("/vcc-status"); `text` the rendered reply.
29
+ // Non-string text is coerced so a future caller passing unvalidated
30
+ // data gets a payload (which `isReplyPayload` still accepts) instead
31
+ // of an exception on `.length`.
32
+ export function buildReplyPayload(sessionID, command, text) {
33
+ const body = typeof text === "string" ? text : String(text);
34
+ return {
35
+ sessionID,
36
+ command,
37
+ text:
38
+ body.length > MAX_REPLY_TEXT
39
+ ? `${body.slice(0, MAX_REPLY_TEXT)}\n\n[truncated: reply exceeds ${MAX_REPLY_TEXT} chars — narrow the selection and retry]`
40
+ : body,
41
+ };
42
+ }
43
+
44
+ // Short replies toast; longer ones need a large centered dialog.
45
+ export const MAX_TOAST_TEXT = 300;
46
+
47
+ export function isReplyPayload(value) {
48
+ return (
49
+ typeof value === "object" &&
50
+ value !== null &&
51
+ typeof value.sessionID === "string" &&
52
+ typeof value.command === "string" &&
53
+ typeof value.text === "string"
54
+ );
55
+ }
package/index.ts CHANGED
@@ -1,38 +1,384 @@
1
- import { Plugin } from "@opencode/plugin/effect"
2
- import { Effect } from "effect"
1
+ import { Plugin, Rpc } from "@opencode/plugin/effect"
2
+ import type { SessionInbox } from "@opencode/schema/session-inbox"
3
+ import { Effect, Schema } from "effect"
3
4
  import { buildConfig, compileCompaction } from "./adapter.mjs"
5
+ import { VCC_REPLY_EVENT, VCC_RPC_ID, buildReplyPayload } from "./events.mjs"
6
+ import {
7
+ COMPILER_REV,
8
+ SNAPSHOT_KEY_PREFIX,
9
+ buildSnapshot,
10
+ classifySnapshotStore,
11
+ formatRecallReply,
12
+ formatSearchReply,
13
+ formatStatusText,
14
+ parseRecallArgs,
15
+ parseSearchArgs,
16
+ recallFromSnapshot,
17
+ resolveRecallSelections,
18
+ searchSnapshot,
19
+ snapshotNeedsWrite,
20
+ } from "./snapshot.mjs"
4
21
 
5
22
  // opencode-vcc-compaction: deterministic LLM-free compaction summaries.
6
23
  //
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
24
+ // The compaction hook adapts the request messages through adapter.mjs (pure
25
+ // offline mapping + the VCC reference compiler) and sets event.result so the
26
+ // host takes its fromHook short-circuit: no model call, tail rebuilt from
10
27
  // metadata.keepID. When the adapter abstains (no message id at/after the
11
28
  // keep cut), result stays unset and the host falls back to model compaction.
29
+ // Alongside, context + compaction hooks snapshot cleaned raw messages
30
+ // (snapshot.mjs, growth-guarded by version/count/lastID, warn-and-continue)
31
+ // so the vcc- commands can recall/search history the command ctx cannot
32
+ // read directly.
12
33
  //
13
34
  // Effect-direct by owner decision: written against @opencode/plugin/effect
14
35
  // from the start, so no convert-to-Effect task ever arises.
36
+ //
37
+ // Command replies travel as an RPC event the TUI companion toasts:
38
+ // the server emits `rpc.opencode-vcc-compaction.replied` and returns
39
+ // void with no prompt call (no wake, no chatter, no inbox row) — the
40
+ // goal-plugin pattern (`get` + event). Without the companion the
41
+ // event goes nowhere, and without RPC itself replies fall back to
42
+ // `session.prompt` (visible + wakes), so output is never lost.
43
+ // Payload shape shared with events.mjs (runtime single source of truth
44
+ // lives there for the dependency-free selftest; this alias only types
45
+ // the emit call site).
46
+ type ReplyPayload = { sessionID: string; command: string; text: string }
47
+
48
+ const VccRpc = Rpc.define({ id: VCC_RPC_ID,
49
+ methods: {
50
+ get: {
51
+ input: Schema.toStandardSchemaV1(Schema.Struct({ sessionID: Schema.String })),
52
+ output: Schema.toStandardSchemaV1(
53
+ Schema.NullOr(
54
+ Schema.Struct({
55
+ version: Schema.Number,
56
+ messages: Schema.Array(Schema.Unknown),
57
+ count: Schema.Number,
58
+ lastID: Schema.optional(Schema.String),
59
+ writtenAt: Schema.Number,
60
+ }),
61
+ ),
62
+ ),
63
+ },
64
+ },
65
+ events: {
66
+ [VCC_REPLY_EVENT]: {
67
+ schema: Schema.toStandardSchemaV1(
68
+ Schema.Struct({ sessionID: Schema.String, command: Schema.String, text: Schema.String }),
69
+ ),
70
+ },
71
+ },
72
+ })
15
73
 
16
74
  export default Plugin.define({
17
75
  id: "opencode-vcc-compaction",
18
76
  effect: Effect.fn(function* (ctx) {
19
77
  const config = buildConfig(ctx.options)
78
+ const seen = new Map<string, { version: number; count: number; lastID: string | undefined }>()
20
79
 
21
- 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
- }
80
+ const readStored = (sessionID: string, label: string) =>
81
+ Effect.catch(
82
+ ctx.storage.get(`${SNAPSHOT_KEY_PREFIX}${sessionID}`),
83
+ (error) =>
84
+ Effect.sync(() => {
85
+ console.warn(`[opencode-vcc-compaction] ${label}: snapshot read failed:`, error)
86
+ return { __vccReadFailed: true as const }
87
+ }),
88
+ )
89
+
90
+ // RPC registration must never break init: a JS try/catch around
91
+ // yield* cannot intercept Effect failures, so catch the cause
92
+ // channel explicitly and degrade to prompt replies.
93
+ const rpc = yield* Effect.catchCause(
94
+ ctx.rpc.register(VccRpc, {
95
+ get: (input) =>
96
+ Effect.flatMap(readStored(input.sessionID, "rpc.get"), (stored) => {
97
+ const classified = classifySnapshotStore(stored as never)
98
+ if (classified.status !== "ready") return Effect.succeed(null)
99
+ const candidate = classified.stored as Partial<
100
+ Record<"version" | "messages" | "count" | "lastID" | "writtenAt", unknown>
101
+ >
102
+ // The store only guarantees a non-empty messages array; project
103
+ // the five schema fields (or null) instead of trusting the
104
+ // envelope, so hand-written or older shapes fail soft.
105
+ return Effect.succeed(
106
+ typeof candidate.version === "number" &&
107
+ Array.isArray(candidate.messages) &&
108
+ typeof candidate.count === "number" &&
109
+ typeof candidate.writtenAt === "number"
110
+ ? {
111
+ version: candidate.version,
112
+ messages: candidate.messages,
113
+ count: candidate.count,
114
+ ...(typeof candidate.lastID === "string" ? { lastID: candidate.lastID } : {}),
115
+ writtenAt: candidate.writtenAt,
116
+ }
117
+ : null,
118
+ )
119
+ }),
35
120
  }),
121
+ (cause) =>
122
+ Effect.flatMap(
123
+ Effect.sync(() => {
124
+ console.warn("[opencode-vcc-compaction] rpc unavailable; /vcc-* replies fall back to prompt:", cause)
125
+ }),
126
+ () => Effect.succeed(null),
127
+ ),
36
128
  )
129
+ const emitReply: ((payload: ReplyPayload) => Effect.Effect<void, unknown>) | null =
130
+ rpc === null ? null : (payload) => rpc.events.emit(VCC_REPLY_EVENT, payload)
131
+
132
+ // Primary path emits the reply event for the TUI companion (silent,
133
+ // no wake). Fallbacks keep output visible: emit failure or missing
134
+ // RPC revert to session.prompt (visible + wakes, 0.2.0 behavior).
135
+ // The host passes `input.prompt` as `{ text }`; normalize a plain
136
+ // string too so a host-shape change degrades to working, not to a
137
+ // permanent usage error.
138
+ const promptText = (input: { prompt: unknown }) =>
139
+ typeof input.prompt === "string" ? input.prompt : ((input.prompt as { text?: unknown })?.text ?? "")
140
+
141
+ const reply = (input: { sessionID: string; delivery?: SessionInbox.Delivery }, command: string, text: string) =>
142
+ emitReply === null
143
+ ? ctx.session.prompt({
144
+ sessionID: input.sessionID,
145
+ text,
146
+ delivery: input.delivery,
147
+ })
148
+ : Effect.catch(
149
+ emitReply(buildReplyPayload(input.sessionID, command, text)),
150
+ (error) =>
151
+ Effect.flatMap(
152
+ Effect.sync(() => {
153
+ console.warn("[opencode-vcc-compaction] reply emit failed; falling back to prompt:", error)
154
+ }),
155
+ () =>
156
+ ctx.session.prompt({
157
+ sessionID: input.sessionID,
158
+ text,
159
+ delivery: input.delivery,
160
+ }),
161
+ ),
162
+ )
163
+
164
+ const remember = (sessionID: unknown, messages: unknown) =>
165
+ Effect.catch(
166
+ Effect.flatMap(
167
+ Effect.sync(() => {
168
+ if (typeof sessionID !== "string" || sessionID === "") {
169
+ console.warn("[opencode-vcc-compaction] snapshot skipped: missing sessionID")
170
+ return null
171
+ }
172
+ return buildSnapshot(messages as never)
173
+ }),
174
+ (snap) => {
175
+ if (snap === null) return Effect.void
176
+ const prev = seen.get(sessionID as string)
177
+ if (!snapshotNeedsWrite(prev, snap)) return Effect.void
178
+ return Effect.catch(
179
+ Effect.flatMap(
180
+ ctx.storage.set(`${SNAPSHOT_KEY_PREFIX}${sessionID}`, {
181
+ version: snap.version,
182
+ messages: snap.messages,
183
+ count: snap.count,
184
+ ...(snap.lastID === undefined ? {} : { lastID: snap.lastID }),
185
+ writtenAt: Date.now(),
186
+ }),
187
+ () =>
188
+ Effect.sync(() => {
189
+ seen.set(sessionID as string, {
190
+ version: snap.version,
191
+ count: snap.count,
192
+ lastID: snap.lastID,
193
+ })
194
+ }),
195
+ ),
196
+ (error) =>
197
+ Effect.sync(() => {
198
+ console.warn("[opencode-vcc-compaction] snapshot write failed:", error)
199
+ }),
200
+ )
201
+ },
202
+ ),
203
+ (error) =>
204
+ Effect.sync(() => {
205
+ console.warn("[opencode-vcc-compaction] snapshot build failed:", error)
206
+ }),
207
+ )
208
+
209
+ try {
210
+ yield* ctx.session.hook("context", (event) =>
211
+ remember((event as { sessionID: string }).sessionID, (event as { messages: unknown }).messages),
212
+ )
213
+ } catch (error) {
214
+ console.warn("[opencode-vcc-compaction] context hook unavailable; snapshots via compaction only:", error)
215
+ }
216
+
217
+ yield* ctx.session.hook("compaction", (event) =>
218
+ Effect.flatMap(
219
+ remember((event as { sessionID: string }).sessionID, (event as { messages: unknown }).messages),
220
+ () =>
221
+ Effect.sync(() => {
222
+ let outcome
223
+ try {
224
+ outcome = compileCompaction(event.messages, config)
225
+ } catch (error) {
226
+ console.warn("[opencode-vcc-compaction] adapter failed; leaving result unset:", error)
227
+ return
228
+ }
229
+ if (outcome === undefined) return
230
+ event.result = {
231
+ summary: outcome.summary,
232
+ metadata: { keepID: outcome.keepID },
233
+ }
234
+ }),
235
+ ),
236
+ )
237
+
238
+ try {
239
+ yield* ctx.command.transform((editor) => {
240
+ editor.add({
241
+ name: "vcc-recall",
242
+ description: "Restore exact original content from this session by (seq N), result, or checkpoint reference.",
243
+ execute: (input) =>
244
+ Effect.catchCause(
245
+ Effect.flatMap(
246
+ Effect.sync(() => parseRecallArgs(promptText(input))),
247
+ (parsed) => {
248
+ if ("error" in parsed) {
249
+ return reply(input, "/vcc-recall", `**/vcc-recall** — ${parsed.error}`)
250
+ }
251
+ return Effect.flatMap(
252
+ readStored(input.sessionID, "vcc-recall"),
253
+ (stored) => {
254
+ const classified = classifySnapshotStore(stored as never)
255
+ if (classified.status === "failed") {
256
+ return reply(input, "/vcc-recall", "**/vcc-recall** — snapshot read failed, try again in a moment")
257
+ }
258
+ if (classified.status === "empty") {
259
+ console.log("[opencode-vcc-compaction] vcc-recall: no snapshot yet for this session")
260
+ return Effect.void
261
+ }
262
+ const resolved = resolveRecallSelections(classified.messages as never, parsed.type, parsed.id)
263
+ if (resolved.errors.length > 0 || resolved.selections.length === 0) {
264
+ return reply(
265
+ input,
266
+ "/vcc-recall",
267
+ `**/vcc-recall** — ${resolved.errors.join("; ") || "nothing to recall"}`,
268
+ )
269
+ }
270
+ const recalled = recallFromSnapshot(classified.messages as never, resolved.selections)
271
+ return reply(input, "/vcc-recall", formatRecallReply(parsed.type, parsed.id, recalled as never))
272
+ },
273
+ )
274
+ },
275
+ ),
276
+ (cause) =>
277
+ Effect.catchCause(
278
+ ctx.session.prompt({
279
+ sessionID: input.sessionID,
280
+ text: "**/vcc-recall** — command failed, try again in a moment",
281
+ delivery: input.delivery,
282
+ }),
283
+ () =>
284
+ Effect.sync(() => {
285
+ console.warn("[opencode-vcc-compaction] vcc-recall failed:", cause)
286
+ }),
287
+ ),
288
+ ),
289
+ })
290
+ editor.add({
291
+ name: "vcc-search",
292
+ description: "Search this session's history by keyword or regex; returns (seq N) hits for /vcc-recall.",
293
+ execute: (input) =>
294
+ Effect.catchCause(
295
+ Effect.flatMap(
296
+ Effect.sync(() => parseSearchArgs(promptText(input))),
297
+ (parsed) => {
298
+ if ("error" in parsed) {
299
+ return reply(input, "/vcc-search", `**/vcc-search** — ${parsed.error}`)
300
+ }
301
+ return Effect.flatMap(
302
+ readStored(input.sessionID, "vcc-search"),
303
+ (stored) => {
304
+ const classified = classifySnapshotStore(stored as never)
305
+ if (classified.status === "failed") {
306
+ return reply(input, "/vcc-search", "**/vcc-search** — snapshot read failed, try again in a moment")
307
+ }
308
+ if (classified.status === "empty") {
309
+ console.log("[opencode-vcc-compaction] vcc-search: no snapshot yet for this session")
310
+ return Effect.void
311
+ }
312
+ let found
313
+ try {
314
+ found = searchSnapshot(classified.messages as never, parsed.pattern)
315
+ } catch (error) {
316
+ return reply(
317
+ input,
318
+ "/vcc-search",
319
+ `**/vcc-search** — ${error instanceof Error ? error.message : String(error)}`,
320
+ )
321
+ }
322
+ return reply(input, "/vcc-search", formatSearchReply(parsed.pattern, found as never))
323
+ },
324
+ )
325
+ },
326
+ ),
327
+ (cause) =>
328
+ Effect.catchCause(
329
+ ctx.session.prompt({
330
+ sessionID: input.sessionID,
331
+ text: "**/vcc-search** — command failed, try again in a moment",
332
+ delivery: input.delivery,
333
+ }),
334
+ () =>
335
+ Effect.sync(() => {
336
+ console.warn("[opencode-vcc-compaction] vcc-search failed:", cause)
337
+ }),
338
+ ),
339
+ ),
340
+ })
341
+ editor.add({
342
+ name: "vcc-status",
343
+ description: "Show opencode-vcc-compaction engine revision, config, and snapshot freshness.",
344
+ execute: (input) =>
345
+ Effect.catchCause(
346
+ Effect.flatMap(
347
+ readStored(input.sessionID, "vcc-status"),
348
+ (stored) => {
349
+ const classified = classifySnapshotStore(stored as never)
350
+ if (classified.status === "failed") {
351
+ return reply(input, "/vcc-status", "**/vcc-status** — snapshot read failed, try again in a moment")
352
+ }
353
+ return reply(
354
+ input,
355
+ "/vcc-status",
356
+ formatStatusText(
357
+ classified.status === "ready" ? classified.stored as never : undefined,
358
+ config as never,
359
+ COMPILER_REV as string,
360
+ Date.now(),
361
+ ),
362
+ )
363
+ },
364
+ ),
365
+ (cause) =>
366
+ Effect.catchCause(
367
+ ctx.session.prompt({
368
+ sessionID: input.sessionID,
369
+ text: "**/vcc-status** — command failed, try again in a moment",
370
+ delivery: input.delivery,
371
+ }),
372
+ () =>
373
+ Effect.sync(() => {
374
+ console.warn("[opencode-vcc-compaction] vcc-status failed:", cause)
375
+ }),
376
+ ),
377
+ ),
378
+ })
379
+ })
380
+ } catch (error) {
381
+ console.warn("[opencode-vcc-compaction] command API unavailable; /vcc-* commands not registered:", error)
382
+ }
37
383
  }),
38
384
  })
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "opencode-vcc-compaction",
3
- "version": "0.1.0",
3
+ "version": "0.3.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,12 +24,22 @@
24
24
  ],
25
25
  "type": "module",
26
26
  "main": "./index.ts",
27
- "files": ["index.ts", "adapter.mjs", "engine/", "README.md"],
27
+ "exports": {
28
+ ".": "./index.ts",
29
+ "./tui": "./tui.tsx",
30
+ "./package.json": "./package.json"
31
+ },
32
+ "files": ["index.ts", "adapter.mjs", "snapshot.mjs", "events.mjs", "tui.tsx", "engine/", "README.md"],
28
33
  "engines": {
29
34
  "node": ">=18"
30
35
  },
31
36
  "peerDependencies": {
32
37
  "@opencode/plugin": "^2.0.0",
33
38
  "effect": "^4.0.0"
39
+ },
40
+ "devDependencies": {
41
+ "@opentui/solid": "^0.5.17",
42
+ "solid-js": "^1.9.12",
43
+ "typescript": "^5.9.2"
34
44
  }
35
45
  }
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
+ }
package/tui.tsx ADDED
@@ -0,0 +1,44 @@
1
+ /** @jsxImportSource @opentui/solid */
2
+
3
+ import { Plugin } from "@opencode/plugin/tui"
4
+ import { isReplyPayload, MAX_TOAST_TEXT, replyEventType } from "./events.mjs"
5
+
6
+ // opencode-vcc-compaction TUI companion: quiet visible output for the
7
+ // server /vcc-* commands. The server emits
8
+ // `rpc.opencode-vcc-compaction.replied` and returns void (no wake, no
9
+ // chatter); this listener toasts/dialogs the reply. No keymap commands:
10
+ // slash lookup has no session context, and none is needed — the event
11
+ // carries its session. (ODF tui.tsx pattern: dialog.alert large +
12
+ // centered for long content.)
13
+
14
+ const replyType = replyEventType()
15
+
16
+ export default Plugin.define({
17
+ id: "opencode-vcc-compaction",
18
+ setup(ctx) {
19
+ ctx.data.listen((event) => {
20
+ try {
21
+ const details = (event as { details?: unknown }).details as
22
+ | { type?: unknown; data?: unknown }
23
+ | undefined
24
+ if (details?.type !== replyType) return
25
+ const payload = (details as { data?: unknown }).data
26
+ // Runtime shape already validated; the guard lives in untyped
27
+ // .mjs (no node_modules for real types), so narrow by cast.
28
+ if (!isReplyPayload(payload)) return
29
+ const reply = payload as { sessionID: string; command: string; text: string }
30
+ const title = `vcc ${reply.command}`
31
+ if (reply.text.length < MAX_TOAST_TEXT) {
32
+ void ctx.ui.toast.show({ title, message: reply.text, variant: "info" })
33
+ return
34
+ }
35
+ // ODF dialog pattern: alert, then presentation, then drop the handle.
36
+ const shown = ctx.ui.dialog.alert({ title, message: reply.text })
37
+ ctx.ui.dialog.set({ size: "large", centered: true })
38
+ void shown
39
+ } catch (error) {
40
+ console.warn("[opencode-vcc-compaction] reply render failed:", error)
41
+ }
42
+ })
43
+ },
44
+ })