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 +42 -14
- package/adapter.mjs +30 -9
- package/index.ts +265 -17
- package/package.json +2 -2
- package/snapshot.mjs +515 -0
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.
|
|
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
|
|
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
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
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 →
|
|
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.
|
|
296
|
-
recall
|
|
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);
|
|
299
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
8
|
-
// mapping + the VCC reference compiler) and sets event.result so the
|
|
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.
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
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.
|
|
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
|
+
}
|