opencode-vcc-compaction 0.3.0 → 0.3.1

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.2.0`.
18
+ Version: `opencode-vcc-compaction@0.3.1`.
19
19
 
20
20
  ## How it works
21
21
 
@@ -341,9 +341,7 @@ from a scratch project, never a real one.
341
341
 
342
342
  ## Status and limits
343
343
 
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
344
+ - v0.3.0 ships the hook + three server slash commands
347
345
  (`/vcc-recall`, `/vcc-search`, `/vcc-status`) plus the `./tui`
348
346
  companion that renders their replies quietly. `(seq N)`
349
347
  pointers are 1-based ordinals over the compiled messages (skipped
package/index.ts CHANGED
@@ -5,7 +5,9 @@ import { buildConfig, compileCompaction } from "./adapter.mjs"
5
5
  import { VCC_REPLY_EVENT, VCC_RPC_ID, buildReplyPayload } from "./events.mjs"
6
6
  import {
7
7
  COMPILER_REV,
8
+ MAX_SNAPSHOT_WRITE_BYTES,
8
9
  SNAPSHOT_KEY_PREFIX,
10
+ WATCH_STATS_KEY_PREFIX,
9
11
  buildSnapshot,
10
12
  classifySnapshotStore,
11
13
  formatRecallReply,
@@ -17,6 +19,8 @@ import {
17
19
  resolveRecallSelections,
18
20
  searchSnapshot,
19
21
  snapshotNeedsWrite,
22
+ snapshotWriteBytes,
23
+ updateWatchStats,
20
24
  } from "./snapshot.mjs"
21
25
 
22
26
  // opencode-vcc-compaction: deterministic LLM-free compaction summaries.
@@ -27,9 +31,10 @@ import {
27
31
  // metadata.keepID. When the adapter abstains (no message id at/after the
28
32
  // keep cut), result stays unset and the host falls back to model compaction.
29
33
  // 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.
34
+ // (snapshot.mjs: growth-guarded by version/count/lastID, >1MB single-write
35
+ // warn tripwire + queryable per-session watch stats (`vcc-stats/` key:
36
+ // maxWriteBytes, tripCount), every failure path warn-and-continue) so the vcc-
37
+ // commands can recall/search history the command ctx cannot read directly.
33
38
  //
34
39
  // Effect-direct by owner decision: written against @opencode/plugin/effect
35
40
  // from the start, so no convert-to-Effect task ever arises.
@@ -75,7 +80,7 @@ export default Plugin.define({
75
80
  id: "opencode-vcc-compaction",
76
81
  effect: Effect.fn(function* (ctx) {
77
82
  const config = buildConfig(ctx.options)
78
- const seen = new Map<string, { version: number; count: number; lastID: string | undefined }>()
83
+ const seen = new Map<string, { version: number; count: number; lastID: string | undefined; stats: unknown; statsLoaded: boolean }>()
79
84
 
80
85
  const readStored = (sessionID: string, label: string) =>
81
86
  Effect.catch(
@@ -173,26 +178,70 @@ export default Plugin.define({
173
178
  }),
174
179
  (snap) => {
175
180
  if (snap === null) return Effect.void
176
- const prev = seen.get(sessionID as string)
181
+ const key = sessionID as string
182
+ const prev = seen.get(key)
177
183
  if (!snapshotNeedsWrite(prev, snap)) return Effect.void
184
+ const at = Date.now()
185
+ const envelope = {
186
+ version: snap.version,
187
+ messages: snap.messages,
188
+ count: snap.count,
189
+ ...(snap.lastID === undefined ? {} : { lastID: snap.lastID }),
190
+ writtenAt: at,
191
+ }
192
+ const writeBytes = snapshotWriteBytes(envelope)
193
+ // Watch stats live in their own kv key (not the envelope, so
194
+ // recall/search/RPC readers never change shape): lazy-load once
195
+ // per session, fold purely, persist only on new max or trip.
196
+ const loadStats =
197
+ prev?.statsLoaded === true
198
+ ? Effect.succeed(prev.stats)
199
+ : Effect.catch(
200
+ ctx.storage.get(`${WATCH_STATS_KEY_PREFIX}${key}`),
201
+ (error) =>
202
+ Effect.sync(() => {
203
+ console.warn("[opencode-vcc-compaction] watch stats read failed; folding from zero:", error)
204
+ return undefined
205
+ }),
206
+ )
178
207
  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
- ),
208
+ Effect.flatMap(loadStats, (storedStats) => {
209
+ const fold = updateWatchStats(storedStats, writeBytes, at)
210
+ const recordStats = fold.changed
211
+ ? Effect.catch(
212
+ ctx.storage.set(`${WATCH_STATS_KEY_PREFIX}${key}`, fold.stats),
213
+ (error) =>
214
+ Effect.sync(() => {
215
+ console.warn("[opencode-vcc-compaction] watch stats write failed:", error)
216
+ }),
217
+ )
218
+ : Effect.void
219
+ return Effect.flatMap(
220
+ writeBytes > MAX_SNAPSHOT_WRITE_BYTES
221
+ ? Effect.sync(() => {
222
+ console.warn(
223
+ `[opencode-vcc-compaction] snapshot write large: session ${sessionID} count=${snap.count} ~${writeBytes} bytes (O(n²) watch: full envelope rewritten per turn)`,
224
+ )
225
+ })
226
+ : Effect.void,
227
+ () =>
228
+ Effect.flatMap(
229
+ ctx.storage.set(`${SNAPSHOT_KEY_PREFIX}${key}`, envelope),
230
+ () =>
231
+ Effect.flatMap(recordStats, () =>
232
+ Effect.sync(() => {
233
+ seen.set(key, {
234
+ version: snap.version,
235
+ count: snap.count,
236
+ lastID: snap.lastID,
237
+ stats: fold.stats,
238
+ statsLoaded: true,
239
+ })
240
+ }),
241
+ ),
242
+ ),
243
+ )
244
+ }),
196
245
  (error) =>
197
246
  Effect.sync(() => {
198
247
  console.warn("[opencode-vcc-compaction] snapshot write failed:", error)
@@ -206,19 +255,42 @@ export default Plugin.define({
206
255
  }),
207
256
  )
208
257
 
258
+ // True when the context hook below registered: snapshots are then
259
+ // maintained on every turn and the compaction hook can skip its own
260
+ // rebuild. When false (host without a context hook), every
261
+ // compaction must rebuild — `seen` presence alone would go stale
262
+ // after the first compaction-time write.
263
+ let snapshotsViaContext = false
209
264
  try {
210
265
  yield* ctx.session.hook("context", (event) =>
211
266
  remember((event as { sessionID: string }).sessionID, (event as { messages: unknown }).messages),
212
267
  )
268
+ snapshotsViaContext = true
213
269
  } catch (error) {
214
270
  console.warn("[opencode-vcc-compaction] context hook unavailable; snapshots via compaction only:", error)
215
271
  }
216
272
 
217
273
  yield* ctx.session.hook("compaction", (event) =>
218
274
  Effect.flatMap(
219
- remember((event as { sessionID: string }).sessionID, (event as { messages: unknown }).messages),
220
- () =>
221
- Effect.sync(() => {
275
+ // Snapshots land via the context hook on every turn; rebuilding
276
+ // the same append-only log here would duplicate that work once
277
+ // per compaction. Skip only when the context path is proven
278
+ // live (registered above AND this session already seen) —
279
+ // otherwise rebuild, exactly as before.
280
+ Effect.sync(
281
+ () =>
282
+ snapshotsViaContext && seen.has((event as { sessionID: string }).sessionID),
283
+ ),
284
+ (ready) =>
285
+ Effect.flatMap(
286
+ ready
287
+ ? Effect.void
288
+ : remember(
289
+ (event as { sessionID: string }).sessionID,
290
+ (event as { messages: unknown }).messages,
291
+ ),
292
+ () =>
293
+ Effect.sync(() => {
222
294
  let outcome
223
295
  try {
224
296
  outcome = compileCompaction(event.messages, config)
@@ -232,6 +304,7 @@ export default Plugin.define({
232
304
  metadata: { keepID: outcome.keepID },
233
305
  }
234
306
  }),
307
+ ),
235
308
  ),
236
309
  )
237
310
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "opencode-vcc-compaction",
3
- "version": "0.3.0",
3
+ "version": "0.3.1",
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>",
package/snapshot.mjs CHANGED
@@ -31,9 +31,10 @@
31
31
  * Search deviation (documented): upstream `search.mjs` scans positionally
32
32
  * (`events[seq]` with `event.seq === seq`, 0-based) over the array the
33
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.
34
+ * leaves index 0 empty (a hole the engine skips via its own
35
+ * `event === undefined` guard) so the verbatim `searchSession` contract
36
+ * holds, then delegates — no forked search loop to hand-sync, no phantom
37
+ * hit, no stolen hit-slot or budget. Same hits, honest seqs.
37
38
  *
38
39
  * The session log is append-only: `snapshotNeedsWrite` is a growth guard
39
40
  * (version/count/lastID). In-place edits to middle messages are not
@@ -313,6 +314,65 @@ export function snapshotNeedsWrite(previous, next) {
313
314
  return next.lastID !== previous.lastID;
314
315
  }
315
316
 
317
+ // Tripwire for the O(n²) write-amplification watch: one full-envelope
318
+ // rewrite per turn, so warn when a single write exceeds ~1MB. Real
319
+ // sessions run ~5KB/message (tool-result JSON + reasoning), far above
320
+ // the 160B/message synthetic fillers the original thresholds assumed.
321
+ export const MAX_SNAPSHOT_WRITE_BYTES = 1000000;
322
+
323
+ /**
324
+ * Estimate the serialized size of a snapshot envelope.
325
+ * Unserializable input measures 0 (never trips; the write path
326
+ * warn-and-continues exactly like every other snapshot failure).
327
+ * @param envelope - the snapshot value about to be written.
328
+ * @returns JSON length in chars, or 0 when unserializable.
329
+ */
330
+ export function snapshotWriteBytes(envelope) {
331
+ try {
332
+ const text = JSON.stringify(envelope);
333
+ return typeof text === "string" ? text.length : 0;
334
+ } catch {
335
+ return 0;
336
+ }
337
+ }
338
+
339
+ export const WATCH_STATS_VERSION = 1;
340
+
341
+ /** Storage key prefix; full key is `${WATCH_STATS_KEY_PREFIX}${sessionID}`. */
342
+ export const WATCH_STATS_KEY_PREFIX = "vcc-stats/";
343
+
344
+ /**
345
+ * Fold one snapshot write into the O(n²) watch stats.
346
+ * Pure; malformed previous stats fold from zero (fail-soft, like every
347
+ * snapshot read path). Kept in a separate kv key so the snapshot envelope
348
+ * (and its recall/search/RPC readers) never changes shape.
349
+ * @param previous - stored stats value (or undefined on first write).
350
+ * @param writeBytes - serialized bytes of the write being recorded.
351
+ * @param now - current epoch ms.
352
+ * @returns `{ stats, changed }`: changed when a new max landed or the
353
+ * tripwire fired — the only cases the caller persists.
354
+ */
355
+ export function updateWatchStats(previous, writeBytes, now) {
356
+ const prev = previous !== null && typeof previous === "object" ? previous : {};
357
+ const prevMax = typeof prev.maxWriteBytes === "number" && prev.maxWriteBytes > 0 ? prev.maxWriteBytes : 0;
358
+ const prevTrips = typeof prev.tripCount === "number" && prev.tripCount > 0 ? Math.floor(prev.tripCount) : 0;
359
+ const prevTripAt = typeof prev.lastTripwireAt === "number" ? prev.lastTripwireAt : null;
360
+ const prevMaxAt = typeof prev.maxAt === "number" ? prev.maxAt : null;
361
+ const bytes = typeof writeBytes === "number" && writeBytes > 0 ? writeBytes : 0;
362
+ const tripped = bytes > MAX_SNAPSHOT_WRITE_BYTES;
363
+ const newMax = bytes > prevMax;
364
+ return {
365
+ stats: {
366
+ version: WATCH_STATS_VERSION,
367
+ maxWriteBytes: newMax ? bytes : prevMax,
368
+ maxAt: newMax ? now : prevMaxAt,
369
+ tripCount: prevTrips + (tripped ? 1 : 0),
370
+ lastTripwireAt: tripped ? now : prevTripAt,
371
+ },
372
+ changed: newMax || tripped,
373
+ };
374
+ }
375
+
316
376
  /**
317
377
  * Map one cleaned part to a recall block.
318
378
  * @param part - cleaned part.
@@ -456,8 +516,13 @@ export function recallFromSnapshot(cleanedMessages, selections, maxRecallTokens
456
516
 
457
517
  /**
458
518
  * 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.
519
+ * `searchSession`: leave index 0 empty (a hole, not a dummy event) so the
520
+ * positional `events[seq]` + `seq === seq` contract holds for 1-based seqs
521
+ * while the hole itself is skipped by the engine's own
522
+ * `event === undefined` guard — it can never match, never consume a
523
+ * maxSearchHits slot, and never burn search budget. A defensive
524
+ * seq-0 filter stays on the output in case the vendored engine ever
525
+ * changes shape.
461
526
  * @param cleanedMessages - snapshot `messages`.
462
527
  * @param patternSource - raw regex/keyword.
463
528
  * @param config - `{ maxSearchHits, maxRecallTokens }` (defaults to engine defaults).
@@ -473,27 +538,28 @@ export function searchSnapshot(cleanedMessages, patternSource, config = {}) {
473
538
  : DEFAULT_MAX_RECALL_TOKENS;
474
539
  const inner = makeSnapshotSession(cleanedMessages);
475
540
  const live = inner.snapshotEvents();
476
- const padded = [{ seq: 0, type: "session.created", data: {} }, ...live];
477
- const paddedSession = {
541
+ const aligned = [undefined, ...live];
542
+ const alignedSession = {
478
543
  snapshotEvents() {
479
- return padded;
544
+ return aligned;
480
545
  },
481
546
  eventAt(seq) {
482
- if (seq === 0) return padded[0];
547
+ if (seq === 0) return undefined;
483
548
  return inner.eventAt(seq);
484
549
  },
485
550
  get events() {
486
- return padded;
551
+ return aligned;
487
552
  },
488
553
  deriveEventMessage(event) {
489
- if (event?.seq === 0) return null;
554
+ if (event === undefined || event === null) return null;
490
555
  return inner.deriveEventMessage(event);
491
556
  },
492
557
  };
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.
558
+ const out = searchSession(alignedSession, patternSource, { maxSearchHits, maxRecallTokens });
559
+ // Defense in depth: the index-0 hole can never surface as a hit (the
560
+ // engine skips it before matching), but seq 0 is unrecallable
561
+ // (`parseSeqSpec` rejects it), so drop any phantom hit and rebuild the
562
+ // summary around the live hits.
497
563
  const hits = out.hits.filter((hit) => hit.seq !== 0);
498
564
  const dropped = out.hits.length - hits.length;
499
565
  const totalMatches = out.totalMatches - dropped;
package/tui.tsx CHANGED
@@ -29,10 +29,18 @@ export default Plugin.define({
29
29
  const reply = payload as { sessionID: string; command: string; text: string }
30
30
  const title = `vcc ${reply.command}`
31
31
  if (reply.text.length < MAX_TOAST_TEXT) {
32
- void ctx.ui.toast.show({ title, message: reply.text, variant: "info" })
32
+ // Host-native attribution: the toast ties itself to the
33
+ // reply's session (session title + open offer when its family
34
+ // is not open). Dialogs have no such option (see below).
35
+ void ctx.ui.toast.show({ title, message: reply.text, variant: "info", sessionID: reply.sessionID })
33
36
  return
34
37
  }
35
38
  // ODF dialog pattern: alert, then presentation, then drop the handle.
39
+ // Broadcast by design: DialogAlertOptions carries no sessionID, so a
40
+ // long reply dialogs in whatever session is viewed. Suppression was
41
+ // considered (via ctx.ui.router.current()) and rejected — a user who
42
+ // fires /vcc-recall and switches sessions mid-flight should still
43
+ // see the answer, and the title names the command.
36
44
  const shown = ctx.ui.dialog.alert({ title, message: reply.text })
37
45
  ctx.ui.dialog.set({ size: "large", centered: true })
38
46
  void shown