@joe-broadhead/opencode-mem 0.0.0-stage → 0.6.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/LICENSE +21 -0
- package/README.md +323 -2
- package/SECURITY.md +131 -0
- package/docs/agent-protocol.md +190 -0
- package/index.js +4 -0
- package/package.json +174 -4
- package/skills/mem-usage/SKILL.md +427 -0
- package/src/backend/v3.js +562 -0
- package/src/bootstrap.js +85 -0
- package/src/capture.js +143 -0
- package/src/commands.js +151 -0
- package/src/compaction.js +402 -0
- package/src/config.js +193 -0
- package/src/copies.js +322 -0
- package/src/credentials.js +294 -0
- package/src/curation.js +240 -0
- package/src/erase.js +36 -0
- package/src/events.js +394 -0
- package/src/hooks.js +182 -0
- package/src/index.js +189 -0
- package/src/limits.js +90 -0
- package/src/log.js +161 -0
- package/src/protocol.js +48 -0
- package/src/recall.js +368 -0
- package/src/runtime.js +868 -0
- package/src/scope.js +127 -0
- package/src/sessions.js +62 -0
- package/src/skill-contexts.js +168 -0
- package/src/skills.js +252 -0
- package/src/spaces.js +478 -0
- package/src/spool.js +520 -0
- package/src/tools/index.js +51 -0
- package/src/tools/knowledge.js +90 -0
- package/src/tools/memory.js +1239 -0
- package/src/tools/recall.js +273 -0
- package/src/tools/shared.js +339 -0
- package/src/tools/spaces.js +179 -0
- package/src/tools/status.js +64 -0
- package/src/tools/wiki.js +412 -0
- package/src/util.js +176 -0
package/src/events.js
ADDED
|
@@ -0,0 +1,394 @@
|
|
|
1
|
+
import { buildSessionPayload, extractCompactionSummary, newTurn } from "./capture.js"
|
|
2
|
+
import { CAPTURE_MESSAGE_CHARS, MAX_MESSAGES, splitContent } from "./limits.js"
|
|
3
|
+
import { parentIDOf, readSession } from "./sessions.js"
|
|
4
|
+
import { errorMessage, redactSecrets, rememberBounded, shortHash } from "./util.js"
|
|
5
|
+
|
|
6
|
+
/** Bounds on the per-process maps; old sessions fall out in insertion order. */
|
|
7
|
+
const COMPACTED_MAX = 200
|
|
8
|
+
const MODELS_MAX = 500
|
|
9
|
+
const SEEN_EVENTS_MAX = 1_000
|
|
10
|
+
/** Turns admitted but never finished (an abandoned session). The oldest is flushed. */
|
|
11
|
+
const OPEN_TURNS_MAX = 200
|
|
12
|
+
|
|
13
|
+
/** Room left in each part for the continuation header. */
|
|
14
|
+
const SUMMARY_PART_CHARS = CAPTURE_MESSAGE_CHARS - 80
|
|
15
|
+
|
|
16
|
+
/**
|
|
17
|
+
* A host compaction summary as L0 user messages. A summary longer than the
|
|
18
|
+
* upstream per-message limit is split, not truncated: it is the one record of
|
|
19
|
+
* the compacted context, and about a quarter of summaries used to be rejected
|
|
20
|
+
* whole. Credential-shaped values are redacted first.
|
|
21
|
+
*
|
|
22
|
+
* @param {string} text
|
|
23
|
+
*/
|
|
24
|
+
export function summaryMessages(text) {
|
|
25
|
+
const parts = splitContent(redactSecrets(text), SUMMARY_PART_CHARS).slice(0, MAX_MESSAGES - 1)
|
|
26
|
+
return parts.map((part, index) => ({
|
|
27
|
+
role: "user",
|
|
28
|
+
content:
|
|
29
|
+
index === 0
|
|
30
|
+
? `Session checkpoint summary${parts.length > 1 ? ` (part 1/${parts.length})` : ""}:\n${part}`
|
|
31
|
+
: `Session checkpoint summary (part ${index + 1}/${parts.length}):\n${part}`,
|
|
32
|
+
}))
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
/**
|
|
36
|
+
* Capture completed turns into the memory backend.
|
|
37
|
+
*
|
|
38
|
+
* Turn boundaries are the only sane write points: per-token capture multiplies
|
|
39
|
+
* extraction cost, and per-session capture loses the user query that gives the
|
|
40
|
+
* turn its meaning.
|
|
41
|
+
*
|
|
42
|
+
* Two event vocabularies are supported because the host renamed them between
|
|
43
|
+
* releases: the shipped 2.0.x stream uses `session.inbox.*` and
|
|
44
|
+
* `session.execution.*`, while the documented V2 API uses `session.next.*`.
|
|
45
|
+
*
|
|
46
|
+
* @param {any} ctx
|
|
47
|
+
* @param {ReturnType<import("./runtime.js").createRuntime>} runtime
|
|
48
|
+
*/
|
|
49
|
+
export function attachCapture(ctx, runtime) {
|
|
50
|
+
if (!runtime.config.capture) return () => {}
|
|
51
|
+
if (!ctx?.event || typeof ctx.event.subscribe !== "function") {
|
|
52
|
+
runtime.log.warn("host has no event.subscribe; capture disabled")
|
|
53
|
+
return () => {}
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
const controller = new AbortController()
|
|
57
|
+
const turns = new Map()
|
|
58
|
+
const models = new Map()
|
|
59
|
+
const seenTypes = new Set()
|
|
60
|
+
const seenEvents = new Set()
|
|
61
|
+
const compacted = new Set()
|
|
62
|
+
let unavailableLogged = false
|
|
63
|
+
|
|
64
|
+
/**
|
|
65
|
+
* Memory is unavailable (a gateway or Jelly install with no credential):
|
|
66
|
+
* nothing is captured, and nothing is spooled for later. Logged once.
|
|
67
|
+
*/
|
|
68
|
+
function skipUnavailable(what) {
|
|
69
|
+
const reason = runtime.unavailable?.() ?? ""
|
|
70
|
+
if (!reason) return false
|
|
71
|
+
if (!unavailableLogged) {
|
|
72
|
+
unavailableLogged = true
|
|
73
|
+
runtime.log.info(`${what} not captured: memory is unavailable`, { reason })
|
|
74
|
+
}
|
|
75
|
+
return true
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
function payloadOf(event) {
|
|
79
|
+
return event?.data ?? event?.properties ?? {}
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
/**
|
|
83
|
+
* The session's active agent and parent link. The agent scopes the captured
|
|
84
|
+
* turn: the one the hooks and tool calls reported for the session (the
|
|
85
|
+
* agent its tools write and recall as), else the host's session record,
|
|
86
|
+
* which OpenCode 2.2 leaves without one. Without either, the configured
|
|
87
|
+
* agent applies. The parent link marks a subagent session.
|
|
88
|
+
*/
|
|
89
|
+
async function sessionFacts(sessionID, turn) {
|
|
90
|
+
const info = await readSession(ctx, runtime, sessionID)
|
|
91
|
+
return { agent: turn.agent ?? runtime.agentFor?.(sessionID) ?? info.agent, parentID: info.parentID }
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
function skipSubagent(sessionID, what) {
|
|
95
|
+
if (!runtime.skipsSubagent?.(sessionID)) return false
|
|
96
|
+
runtime.log.debug(`subagent ${what} not captured`, { sessionID, parent: runtime.parentOf?.(sessionID) })
|
|
97
|
+
return true
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
/**
|
|
101
|
+
* Open a turn. A session that is admitted but never goes idle would keep its
|
|
102
|
+
* turn for the life of the host; past the bound the oldest open turn is
|
|
103
|
+
* flushed (captured as it stands) rather than dropped.
|
|
104
|
+
*/
|
|
105
|
+
async function openTurn(sessionID, turn) {
|
|
106
|
+
turns.set(sessionID, turn)
|
|
107
|
+
while (turns.size > OPEN_TURNS_MAX) {
|
|
108
|
+
const oldest = turns.keys().next().value
|
|
109
|
+
if (oldest === undefined || oldest === sessionID) break
|
|
110
|
+
await flush(oldest, "evicted")
|
|
111
|
+
}
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
async function flush(sessionID, reason = "idle") {
|
|
115
|
+
const turn = turns.get(sessionID)
|
|
116
|
+
if (!turn) return
|
|
117
|
+
turns.delete(sessionID)
|
|
118
|
+
if (skipUnavailable("turn")) return
|
|
119
|
+
if (skipSubagent(sessionID, "turn")) return
|
|
120
|
+
if (turn.model === "unknown" && models.has(sessionID)) turn.model = models.get(sessionID)
|
|
121
|
+
const facts = await sessionFacts(sessionID, turn)
|
|
122
|
+
turn.agent = facts.agent
|
|
123
|
+
// A child session's first user message is the parent's brief. Stop before
|
|
124
|
+
// the claim, the spool, or any control call.
|
|
125
|
+
if (skipSubagent(sessionID, "turn")) return
|
|
126
|
+
|
|
127
|
+
let messages = []
|
|
128
|
+
try {
|
|
129
|
+
messages = await ctx.session.context({ sessionID })
|
|
130
|
+
} catch (error) {
|
|
131
|
+
runtime.log.warn("session context read failed", error)
|
|
132
|
+
}
|
|
133
|
+
|
|
134
|
+
const payload = buildSessionPayload({ turn, messages })
|
|
135
|
+
if (!payload) return
|
|
136
|
+
|
|
137
|
+
if (turn.messageID && !runtime.claimCapture(`${sessionID}:${turn.messageID}`)) {
|
|
138
|
+
runtime.log.debug("duplicate capture suppressed", { sessionID })
|
|
139
|
+
return
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
const visibility = runtime.config.captureVisibility
|
|
143
|
+
// The task the session declared when the turn ended. It travels with a
|
|
144
|
+
// spooled entry so a replay files the turn under the same task.
|
|
145
|
+
const task = runtime.taskFor?.(sessionID)
|
|
146
|
+
// What a replay needs to send the turn again. In control mode that is all
|
|
147
|
+
// the gateway needs to place it; no container is recorded.
|
|
148
|
+
const meta = { sessionID, agent: turn.agent, visibility, ...(task ? { task } : {}) }
|
|
149
|
+
// Control mode: the gateway's capture route places the turn. Local direct
|
|
150
|
+
// mode: the fixed local scope.
|
|
151
|
+
const scoped = runtime.gatewayCapture ? null : runtime.scope({ sessionID, agent: turn.agent, visibility, task })
|
|
152
|
+
// Spool before sending: a one-shot `opencode run` can exit before the HTTP
|
|
153
|
+
// round trip completes, and losing the last turn is the worst failure mode.
|
|
154
|
+
// The entry is written already claimed, so a concurrent flush in another
|
|
155
|
+
// process cannot send it a second time.
|
|
156
|
+
const staged = (runtime.stageSpool ?? runtime.writeSpool)("session", payload, scoped, meta)
|
|
157
|
+
try {
|
|
158
|
+
const placed = runtime.gatewayCapture
|
|
159
|
+
? await runtime.captureTurn({ ...meta, payload })
|
|
160
|
+
: await runtime.backend.addSessionTurn({ payload, scope: scoped })
|
|
161
|
+
runtime.removeSpool(staged)
|
|
162
|
+
runtime.log.info("turn captured", {
|
|
163
|
+
sessionID,
|
|
164
|
+
reason,
|
|
165
|
+
messages: payload.messages.length,
|
|
166
|
+
visibility: placed?.space_kind ?? visibility,
|
|
167
|
+
space: placed?.space_id ?? null,
|
|
168
|
+
})
|
|
169
|
+
runtime.drainSpool?.()
|
|
170
|
+
} catch (error) {
|
|
171
|
+
// A gateway or control failure leaves the turn in the spool with its
|
|
172
|
+
// visibility; the replay asks the gateway to place it again.
|
|
173
|
+
const outcome = runtime.releaseSpool?.(staged, error)
|
|
174
|
+
runtime.log.warn("turn capture failed", { outcome: outcome ?? "kept", error: errorMessage(error) })
|
|
175
|
+
}
|
|
176
|
+
}
|
|
177
|
+
|
|
178
|
+
async function captureCompaction(sessionID) {
|
|
179
|
+
if (!runtime.config.captureScenarios) return
|
|
180
|
+
try {
|
|
181
|
+
if (skipUnavailable("compaction summary")) return
|
|
182
|
+
if (skipSubagent(sessionID, "compaction")) return
|
|
183
|
+
const facts = await sessionFacts(sessionID, {})
|
|
184
|
+
if (skipSubagent(sessionID, "compaction")) return
|
|
185
|
+
const messages = await ctx.session.context({ sessionID })
|
|
186
|
+
const summary = extractCompactionSummary(messages)
|
|
187
|
+
if (!summary) return
|
|
188
|
+
// The host may emit both `session.compacted` and
|
|
189
|
+
// `session.compaction.ended` for one compaction. The summary identity is
|
|
190
|
+
// stable, so the second event is not a second capture.
|
|
191
|
+
const key = `${sessionID}:${summary.messageID ?? shortHash(summary.text, 12)}`
|
|
192
|
+
if (compacted.has(key)) {
|
|
193
|
+
runtime.log.debug("duplicate compaction capture suppressed", { sessionID })
|
|
194
|
+
return
|
|
195
|
+
}
|
|
196
|
+
// One L0 write per compaction: the pre-compaction checkpoint written by
|
|
197
|
+
// the compaction hook (in any process) already records this state, and
|
|
198
|
+
// it is the record recall reserves room for. The host summary is the
|
|
199
|
+
// fallback when no checkpoint was written.
|
|
200
|
+
if (runtime.recentCheckpoint?.(sessionID)) {
|
|
201
|
+
runtime.log.debug("compaction summary not captured: the checkpoint covers it", { sessionID })
|
|
202
|
+
rememberBounded(compacted, key, undefined, COMPACTED_MAX)
|
|
203
|
+
return
|
|
204
|
+
}
|
|
205
|
+
// Every plugin instance sees the same event; only one writes it.
|
|
206
|
+
const claimKey = `compaction:${key}`
|
|
207
|
+
if (runtime.claimCapture && !runtime.claimCapture(claimKey)) {
|
|
208
|
+
runtime.log.debug("duplicate compaction capture suppressed", { sessionID })
|
|
209
|
+
return
|
|
210
|
+
}
|
|
211
|
+
const agent = facts.agent
|
|
212
|
+
// Compaction summaries follow the same visibility policy as ordinary
|
|
213
|
+
// turn capture. A shared session binding must not silently move a
|
|
214
|
+
// private summary into the shared container. Only an explicit
|
|
215
|
+
// captureVisibility=team writes the summary shared.
|
|
216
|
+
const visibility = runtime.config.captureVisibility
|
|
217
|
+
let context = null
|
|
218
|
+
try {
|
|
219
|
+
context = await runtime.captureContext(sessionID, agent, visibility)
|
|
220
|
+
} catch (error) {
|
|
221
|
+
runtime.releaseCapture?.(claimKey)
|
|
222
|
+
runtime.log.warn("compaction summary skipped: capture context unresolved", { sessionID, error: errorMessage(error) })
|
|
223
|
+
return
|
|
224
|
+
}
|
|
225
|
+
const scoped = context
|
|
226
|
+
? runtime.scopeFor(context, { sessionID, agent, task: runtime.taskFor?.(sessionID) })
|
|
227
|
+
: runtime.scope({ sessionID, visibility, task: runtime.taskFor?.(sessionID) })
|
|
228
|
+
// The backend's scenario endpoint is update-only, so L2 cannot be written
|
|
229
|
+
// directly. Feed the checkpoint back into L0 and let the pipeline distill
|
|
230
|
+
// it, which also keeps derivation and visibility rules server-side.
|
|
231
|
+
const prefix = context ? `space-${shortHash(context.space_id, 8)}` : visibility === "private" ? "priv" : "team"
|
|
232
|
+
const checkpointSession = `${prefix}-${sessionID}-checkpoint-${shortHash(summary.text, 8)}`
|
|
233
|
+
try {
|
|
234
|
+
await runtime.backend.addConversation({
|
|
235
|
+
sessionID: checkpointSession,
|
|
236
|
+
messages: [...summaryMessages(summary.text), { role: "assistant", content: "Checkpoint noted." }],
|
|
237
|
+
scope: { ...scoped, session_id: checkpointSession },
|
|
238
|
+
})
|
|
239
|
+
} catch (error) {
|
|
240
|
+
// A failed write stays eligible for the duplicate event or a retry.
|
|
241
|
+
runtime.releaseCapture?.(claimKey)
|
|
242
|
+
throw error
|
|
243
|
+
}
|
|
244
|
+
rememberBounded(compacted, key, undefined, COMPACTED_MAX)
|
|
245
|
+
runtime.log.info("compaction fed back to L0", {
|
|
246
|
+
sessionID,
|
|
247
|
+
visibility,
|
|
248
|
+
space: context?.space_id ?? null,
|
|
249
|
+
chars: summary.text.length,
|
|
250
|
+
})
|
|
251
|
+
} catch (error) {
|
|
252
|
+
runtime.log.warn("compaction summary capture failed", { sessionID, error: errorMessage(error) })
|
|
253
|
+
}
|
|
254
|
+
}
|
|
255
|
+
|
|
256
|
+
async function handle(event) {
|
|
257
|
+
if (!event?.type) return
|
|
258
|
+
if (event.id) {
|
|
259
|
+
if (seenEvents.has(event.id)) return
|
|
260
|
+
// Evict the oldest ids, never the whole set: clearing it would let a
|
|
261
|
+
// replayed event in again.
|
|
262
|
+
rememberBounded(seenEvents, event.id, undefined, SEEN_EVENTS_MAX)
|
|
263
|
+
}
|
|
264
|
+
|
|
265
|
+
const data = payloadOf(event)
|
|
266
|
+
if (!seenTypes.has(event.type)) {
|
|
267
|
+
seenTypes.add(event.type)
|
|
268
|
+
runtime.log.debug("event type observed", event.type)
|
|
269
|
+
}
|
|
270
|
+
|
|
271
|
+
switch (event.type) {
|
|
272
|
+
// --- turn start --------------------------------------------------------
|
|
273
|
+
case "session.inbox.enqueued": {
|
|
274
|
+
const sessionID = data.sessionID
|
|
275
|
+
const item = data.item
|
|
276
|
+
if (!sessionID || item?.type !== "user") return
|
|
277
|
+
if (skipSubagent(sessionID, "prompt")) return
|
|
278
|
+
const messageID = data.inboxID
|
|
279
|
+
const existing = turns.get(sessionID)
|
|
280
|
+
// The same admission can be delivered more than once.
|
|
281
|
+
if (existing && existing.messageID === messageID) return
|
|
282
|
+
if (existing) await flush(sessionID, "superseded")
|
|
283
|
+
await openTurn(
|
|
284
|
+
sessionID,
|
|
285
|
+
newTurn({
|
|
286
|
+
sessionID,
|
|
287
|
+
messageID,
|
|
288
|
+
promptText: item?.payload?.text ?? "",
|
|
289
|
+
model: models.get(sessionID) ?? "unknown",
|
|
290
|
+
}),
|
|
291
|
+
)
|
|
292
|
+
return
|
|
293
|
+
}
|
|
294
|
+
case "session.next.prompt.admitted": {
|
|
295
|
+
const sessionID = data.sessionID
|
|
296
|
+
if (!sessionID) return
|
|
297
|
+
if (skipSubagent(sessionID, "prompt")) return
|
|
298
|
+
const messageID = data.messageID
|
|
299
|
+
const existing = turns.get(sessionID)
|
|
300
|
+
if (existing && existing.messageID === messageID) return
|
|
301
|
+
if (existing) await flush(sessionID, "superseded")
|
|
302
|
+
await openTurn(
|
|
303
|
+
sessionID,
|
|
304
|
+
newTurn({
|
|
305
|
+
sessionID,
|
|
306
|
+
messageID,
|
|
307
|
+
promptText: data.prompt?.text ?? "",
|
|
308
|
+
model: models.get(sessionID) ?? "unknown",
|
|
309
|
+
}),
|
|
310
|
+
)
|
|
311
|
+
return
|
|
312
|
+
}
|
|
313
|
+
|
|
314
|
+
// --- turn end ----------------------------------------------------------
|
|
315
|
+
case "session.execution.succeeded":
|
|
316
|
+
case "session.execution.failed":
|
|
317
|
+
case "session.idle": {
|
|
318
|
+
if (data.sessionID) await flush(data.sessionID, event.type)
|
|
319
|
+
return
|
|
320
|
+
}
|
|
321
|
+
|
|
322
|
+
// --- identity ----------------------------------------------------------
|
|
323
|
+
case "session.created": {
|
|
324
|
+
const sessionID = data.sessionID ?? data.info?.id ?? data.session?.id
|
|
325
|
+
// Belt and braces: a child created by the task tool is known before
|
|
326
|
+
// its brief is admitted, so no turn is ever opened for it. Only a
|
|
327
|
+
// reported parent is recorded; an absent field is not proof of a root.
|
|
328
|
+
const parentID = parentIDOf(data)
|
|
329
|
+
if (sessionID && parentID) runtime.noteSession?.(sessionID, { parentID })
|
|
330
|
+
if (sessionID && data.model?.providerID && data.model?.id) {
|
|
331
|
+
rememberBounded(models, sessionID, `${data.model.providerID}/${data.model.id}`, MODELS_MAX)
|
|
332
|
+
}
|
|
333
|
+
return
|
|
334
|
+
}
|
|
335
|
+
case "session.next.model.switched": {
|
|
336
|
+
const model = data.model ?? data
|
|
337
|
+
if (data.sessionID && model?.providerID && model?.id) {
|
|
338
|
+
rememberBounded(models, data.sessionID, `${model.providerID}/${model.id}`, MODELS_MAX)
|
|
339
|
+
}
|
|
340
|
+
return
|
|
341
|
+
}
|
|
342
|
+
|
|
343
|
+
// --- compaction --------------------------------------------------------
|
|
344
|
+
case "session.compacted":
|
|
345
|
+
case "session.compaction.ended": {
|
|
346
|
+
if (!data.sessionID) return
|
|
347
|
+
try {
|
|
348
|
+
await captureCompaction(data.sessionID)
|
|
349
|
+
} finally {
|
|
350
|
+
// Compaction always starts a new context epoch, even when capture is
|
|
351
|
+
// disabled or the summary write failed.
|
|
352
|
+
runtime.invalidate(data.sessionID)
|
|
353
|
+
}
|
|
354
|
+
return
|
|
355
|
+
}
|
|
356
|
+
|
|
357
|
+
// --- lifecycle ---------------------------------------------------------
|
|
358
|
+
case "session.deleted": {
|
|
359
|
+
if (data.sessionID) {
|
|
360
|
+
turns.delete(data.sessionID)
|
|
361
|
+
models.delete(data.sessionID)
|
|
362
|
+
runtime.invalidate?.(data.sessionID)
|
|
363
|
+
}
|
|
364
|
+
return
|
|
365
|
+
}
|
|
366
|
+
default:
|
|
367
|
+
return
|
|
368
|
+
}
|
|
369
|
+
}
|
|
370
|
+
|
|
371
|
+
void (async () => {
|
|
372
|
+
try {
|
|
373
|
+
for await (const event of ctx.event.subscribe({ signal: controller.signal })) {
|
|
374
|
+
try {
|
|
375
|
+
await handle(event)
|
|
376
|
+
} catch (error) {
|
|
377
|
+
runtime.log.warn("event handling failed", { type: event?.type, error: errorMessage(error) })
|
|
378
|
+
}
|
|
379
|
+
}
|
|
380
|
+
} catch (error) {
|
|
381
|
+
if (!controller.signal.aborted) runtime.log.warn("event stream ended", errorMessage(error))
|
|
382
|
+
}
|
|
383
|
+
})()
|
|
384
|
+
|
|
385
|
+
async function dispose() {
|
|
386
|
+
controller.abort()
|
|
387
|
+
for (const sessionID of Array.from(turns.keys())) {
|
|
388
|
+
await flush(sessionID, "shutdown").catch(() => {})
|
|
389
|
+
}
|
|
390
|
+
}
|
|
391
|
+
/** Sizes of the per-process maps, for tests and diagnostics. */
|
|
392
|
+
dispose.stats = () => ({ turns: turns.size, models: models.size, seenEvents: seenEvents.size, compacted: compacted.size })
|
|
393
|
+
return dispose
|
|
394
|
+
}
|
package/src/hooks.js
ADDED
|
@@ -0,0 +1,182 @@
|
|
|
1
|
+
import { buildCompactionInstruction } from "./compaction.js"
|
|
2
|
+
import { hasProtocol, protocolBlock } from "./protocol.js"
|
|
3
|
+
import { isChildSession } from "./sessions.js"
|
|
4
|
+
import { errorMessage } from "./util.js"
|
|
5
|
+
|
|
6
|
+
/** A model call must not wait long for memory. */
|
|
7
|
+
const DEFAULT_DEADLINE_MS = 1_500
|
|
8
|
+
/** A compaction may wait a little longer for its checkpoint, but not block. */
|
|
9
|
+
const DEFAULT_COMPACTION_TIMEOUT_MS = 2_000
|
|
10
|
+
|
|
11
|
+
function positive(value, fallback) {
|
|
12
|
+
return Number.isFinite(value) && value > 0 ? Math.floor(value) : fallback
|
|
13
|
+
}
|
|
14
|
+
|
|
15
|
+
/**
|
|
16
|
+
* Attach the memory session hooks.
|
|
17
|
+
*
|
|
18
|
+
* `prompt` runs once at admission, so it starts the bootstrap fetch early.
|
|
19
|
+
* `context` runs before every model call: it injects the pinned bootstrap
|
|
20
|
+
* (bounded by a deadline) and the always-on memory protocol when the host or a
|
|
21
|
+
* loaded skill does not already provide it. `compaction` tells the summarizer
|
|
22
|
+
* what must survive and writes a checkpoint to L0 before the transcript is
|
|
23
|
+
* replaced.
|
|
24
|
+
*
|
|
25
|
+
* Every hook is best effort. A memory, control-plane, or backend failure must
|
|
26
|
+
* never block a model call or a compaction.
|
|
27
|
+
*
|
|
28
|
+
* @param {any} ctx
|
|
29
|
+
* @param {any} runtime
|
|
30
|
+
* @param {{ deadlineMs?: number, compactionTimeoutMs?: number }} [options]
|
|
31
|
+
*/
|
|
32
|
+
export async function attachMemoryHooks(ctx, runtime, options = {}) {
|
|
33
|
+
const disposers = []
|
|
34
|
+
const opts = options ?? {}
|
|
35
|
+
const log = runtime.log ?? { debug() {}, info() {}, warn() {}, error() {} }
|
|
36
|
+
const deadlineMs = positive(opts.deadlineMs, DEFAULT_DEADLINE_MS)
|
|
37
|
+
const compactionTimeoutMs = positive(opts.compactionTimeoutMs, DEFAULT_COMPACTION_TIMEOUT_MS)
|
|
38
|
+
if (!ctx?.session || typeof ctx.session.hook !== "function") {
|
|
39
|
+
log.warn("host has no session.hook; memory hooks disabled")
|
|
40
|
+
return { dispose: async () => {} }
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
const config = runtime.config ?? {}
|
|
44
|
+
|
|
45
|
+
/**
|
|
46
|
+
* A subagent session gets the protocol and the tools but not the pinned
|
|
47
|
+
* block, unless subagents are first-class (`captureSubagents: true`). Its
|
|
48
|
+
* brief already carries the parent's context, it can still pull memory with
|
|
49
|
+
* mem_recall, and skipping saves a control round trip and up to
|
|
50
|
+
* `bootstrapChars` of prefix on every subagent model call. An unknown or
|
|
51
|
+
* slow answer counts as a root session.
|
|
52
|
+
*/
|
|
53
|
+
async function isSubagent(sessionID) {
|
|
54
|
+
if (config.captureSubagents || !sessionID) return false
|
|
55
|
+
let timer
|
|
56
|
+
try {
|
|
57
|
+
return await Promise.race([
|
|
58
|
+
isChildSession(ctx, runtime, sessionID),
|
|
59
|
+
new Promise((resolve) => {
|
|
60
|
+
timer = setTimeout(() => resolve(false), deadlineMs)
|
|
61
|
+
}),
|
|
62
|
+
])
|
|
63
|
+
} catch {
|
|
64
|
+
return false
|
|
65
|
+
} finally {
|
|
66
|
+
clearTimeout(timer)
|
|
67
|
+
}
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
if (config.bootstrap) {
|
|
71
|
+
const promptRegistration = await ctx.session.hook("prompt", (event) => {
|
|
72
|
+
try {
|
|
73
|
+
runtime.noteAgent?.(event?.sessionID, event?.agent)
|
|
74
|
+
if (runtime.unavailable?.()) return
|
|
75
|
+
if (runtime.skipsSubagent?.(event.sessionID)) return
|
|
76
|
+
runtime.prefetchBootstrap?.(event.sessionID, event.agent)
|
|
77
|
+
} catch (error) {
|
|
78
|
+
log.warn("bootstrap prefetch failed", errorMessage(error))
|
|
79
|
+
}
|
|
80
|
+
})
|
|
81
|
+
disposers.push(promptRegistration)
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
// The protocol is independent of the bootstrap setting: an agent with no
|
|
85
|
+
// global instruction file still needs the memory rules.
|
|
86
|
+
const contextRegistration = await ctx.session.hook("context", async (event) => {
|
|
87
|
+
try {
|
|
88
|
+
// The agent of every model call, for turn capture (see runtime.noteAgent).
|
|
89
|
+
runtime.noteAgent?.(event?.sessionID, event?.agent)
|
|
90
|
+
if (!Array.isArray(event?.system)) return
|
|
91
|
+
// Memory is unavailable (no credential): no pinned block, and no
|
|
92
|
+
// protocol teaching the agent to use tools that can only say so.
|
|
93
|
+
if (runtime.unavailable?.()) return
|
|
94
|
+
const alreadyTaught = hasProtocol(event.system)
|
|
95
|
+
|
|
96
|
+
if (config.bootstrap) {
|
|
97
|
+
try {
|
|
98
|
+
// One deadline covers the subagent check and the bootstrap.
|
|
99
|
+
const started = Date.now()
|
|
100
|
+
const child = await isSubagent(event.sessionID)
|
|
101
|
+
const timeoutMs = Math.max(1, deadlineMs - (Date.now() - started))
|
|
102
|
+
const block = child
|
|
103
|
+
? ""
|
|
104
|
+
: await runtime.bootstrapFor?.(event.sessionID, event.agent, { timeoutMs })
|
|
105
|
+
if (block) {
|
|
106
|
+
event.system.push({ type: "text", text: block })
|
|
107
|
+
log.debug("bootstrap injected", { sessionID: event.sessionID, chars: block.length })
|
|
108
|
+
}
|
|
109
|
+
} catch (error) {
|
|
110
|
+
// Keep going: the protocol is still worth injecting when memory is
|
|
111
|
+
// unreachable.
|
|
112
|
+
log.warn("bootstrap injection failed", error)
|
|
113
|
+
}
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
if (!alreadyTaught) {
|
|
117
|
+
const block = protocolBlock()
|
|
118
|
+
event.system.push({ type: "text", text: block })
|
|
119
|
+
log.debug("memory protocol injected", { sessionID: event.sessionID, chars: block.length })
|
|
120
|
+
}
|
|
121
|
+
} catch (error) {
|
|
122
|
+
log.warn("context hook failed", errorMessage(error))
|
|
123
|
+
}
|
|
124
|
+
})
|
|
125
|
+
disposers.push(contextRegistration)
|
|
126
|
+
|
|
127
|
+
const compactionRegistration = await ctx.session.hook("compaction", async (event) => {
|
|
128
|
+
try {
|
|
129
|
+
const alreadyInstructed = event?.system?.some?.((part) => String(part?.text ?? "").includes("<mem_compaction"))
|
|
130
|
+
if (Array.isArray(event?.system) && !alreadyInstructed && !runtime.unavailable?.()) {
|
|
131
|
+
const spaceLabel = runtime.control ? undefined : config.space
|
|
132
|
+
event.system.push({ type: "text", text: buildCompactionInstruction({ spaceLabel }) })
|
|
133
|
+
}
|
|
134
|
+
} catch (error) {
|
|
135
|
+
log.warn("compaction instruction injection failed", errorMessage(error))
|
|
136
|
+
}
|
|
137
|
+
|
|
138
|
+
try {
|
|
139
|
+
if (config.compactionCheckpoint !== false && typeof runtime.writeCompactionCheckpoint === "function") {
|
|
140
|
+
const result = await runtime.writeCompactionCheckpoint({
|
|
141
|
+
sessionID: event?.sessionID,
|
|
142
|
+
agent: event?.agent,
|
|
143
|
+
messages: event?.messages,
|
|
144
|
+
model: event?.model,
|
|
145
|
+
timeoutMs: compactionTimeoutMs,
|
|
146
|
+
// Paths under the project are stored relative to it.
|
|
147
|
+
directory: event?.directory ?? ctx?.location?.directory,
|
|
148
|
+
})
|
|
149
|
+
if (!result?.ok) {
|
|
150
|
+
log.debug("compaction checkpoint not written", {
|
|
151
|
+
sessionID: event?.sessionID,
|
|
152
|
+
reason: result?.reason ?? "unavailable",
|
|
153
|
+
})
|
|
154
|
+
}
|
|
155
|
+
}
|
|
156
|
+
} catch (error) {
|
|
157
|
+
log.warn("compaction checkpoint failed", errorMessage(error))
|
|
158
|
+
} finally {
|
|
159
|
+
// The checkpoint is a new memory, and compaction always starts a new
|
|
160
|
+
// context epoch. Even a failed write must not serve the pre-compaction
|
|
161
|
+
// pinned block to the next model call.
|
|
162
|
+
try {
|
|
163
|
+
if (event?.sessionID) runtime.invalidate?.(event.sessionID)
|
|
164
|
+
} catch (error) {
|
|
165
|
+
log.warn("bootstrap invalidation failed", errorMessage(error))
|
|
166
|
+
}
|
|
167
|
+
}
|
|
168
|
+
})
|
|
169
|
+
disposers.push(compactionRegistration)
|
|
170
|
+
|
|
171
|
+
return {
|
|
172
|
+
async dispose() {
|
|
173
|
+
for (const registration of disposers) {
|
|
174
|
+
try {
|
|
175
|
+
await registration?.dispose?.()
|
|
176
|
+
} catch {
|
|
177
|
+
/* ignore */
|
|
178
|
+
}
|
|
179
|
+
}
|
|
180
|
+
},
|
|
181
|
+
}
|
|
182
|
+
}
|