@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/src/runtime.js ADDED
@@ -0,0 +1,868 @@
1
+ import { contextScopeLabel, placementSignature, resolveScope, scopeLabel, taskKey } from "./scope.js"
2
+ import { buildBootstrap } from "./bootstrap.js"
3
+ import { buildCheckpoint, checkpointFingerprint } from "./compaction.js"
4
+ import { unavailableReason } from "./credentials.js"
5
+ import { createControlClient } from "./spaces.js"
6
+ import { createSkillContexts } from "./skill-contexts.js"
7
+ import { createSpool } from "./spool.js"
8
+ import { errorMessage, oneLine, rememberBounded, shortHash } from "./util.js"
9
+
10
+ /** A session bind uses a shorter bound so prompt construction never waits long. */
11
+ const SKILL_BIND_TIMEOUT_MS = 1_500
12
+ /** Do not retry a failed bind refresh on every prompt. */
13
+ const SKILL_BIND_RETRY_MS = 60_000
14
+ /**
15
+ * The session context behind the pinned block is trusted for ten minutes, so a
16
+ * model call inside that window makes no control request. The block's bytes
17
+ * change only when the space or placement changes, or at a session,
18
+ * compaction, bind, or /mem-sync boundary.
19
+ */
20
+ const BOOTSTRAP_TTL_MS = 10 * 60_000
21
+ /** A block built with one of its two reads missing is rebuilt sooner. */
22
+ const BOOTSTRAP_PARTIAL_TTL_MS = 60_000
23
+ /** A slow or failed bootstrap is not retried on every model call. */
24
+ const BOOTSTRAP_FAILURE_TTL_MS = 15_000
25
+ /** Overall bound on resolving and building the pinned block for one model call. */
26
+ const BOOTSTRAP_DEADLINE_MS = 1_500
27
+ /** A compaction checkpoint is best effort and must never hold the host. */
28
+ const COMPACTION_TIMEOUT_MS = 2_000
29
+ /** Bound the in-memory duplicate guard; old sessions fall out in insertion order. */
30
+ const COMPACTION_DEDUPE_MAX = 200
31
+ /** Bound the per-session registries; old sessions fall out in insertion order. */
32
+ const SESSION_REGISTRY_MAX = 1_000
33
+ /** At most one background spool drain per minute. */
34
+ const SPOOL_DRAIN_INTERVAL_MS = 60_000
35
+ /** Declared tasks kept per process; old sessions fall out in insertion order. */
36
+ const SESSION_TASKS_MAX = 500
37
+
38
+ /**
39
+ * Shared plugin state: scope resolution, the pinned bootstrap cache, the skill
40
+ * source cache, and a durable spool for captures that could not reach the
41
+ * backend.
42
+ *
43
+ * `credentials` (see `src/credentials.js`) supplies the bearer and decides
44
+ * whether memory is available at all; without it the runtime uses
45
+ * `config.token` and never reports memory unavailable. `gateway` forces
46
+ * gateway mode when no `controlURL` is known yet (inside Jelly, before the
47
+ * identity accessor appears).
48
+ *
49
+ * @param {{ config: any, log: any, backend: any, control?: any, credentials?: any, gateway?: boolean, now?: () => number }} input
50
+ */
51
+ export function createRuntime(input) {
52
+ const { config, log, backend } = input
53
+ const credentials = input.credentials ?? null
54
+ /** Wall clock for cache expiry and spool scheduling; injectable for tests. Deadlines use real time. */
55
+ const now = typeof input.now === "function" ? input.now : Date.now
56
+ /** `${sessionID}::${agent}` -> the pinned block and its refresh state. */
57
+ const pins = new Map()
58
+ /** `${sessionID}::${agent}` -> { context, expires }: the session context, cached for the TTL. */
59
+ const sessionContexts = new Map()
60
+ /** sessionID -> the agent the context hook last asked for. */
61
+ const lastAgents = new Map()
62
+ /** sessionID -> invalidation count; a refresh from an older epoch is discarded. */
63
+ const epochs = new Map()
64
+ let globalEpoch = 0
65
+ const bootstrapMisses = { count: 0, last: null }
66
+ const inflight = new Map()
67
+ const compactionSeen = new Map()
68
+ /** sessionID -> parent session id, or null for a root session. */
69
+ const sessionParents = new Map()
70
+ /** sessionID -> the task the session declared (a validated header value). */
71
+ const sessionTasks = new Map()
72
+ const skillMirror = {
73
+ count: 0,
74
+ sourceSpaces: 0,
75
+ spaceIds: new Set(),
76
+ ids: new Set(),
77
+ placements: new Map(),
78
+ attempts: new Map(),
79
+ inflight: null,
80
+ }
81
+ let api = null
82
+ const gatewayMode = input.gateway ?? Boolean(config.controlURL)
83
+ const control =
84
+ input.control ??
85
+ (gatewayMode
86
+ ? createControlClient({ controlURL: () => config.controlURL, token: config.token, credentials, log })
87
+ : null)
88
+
89
+ /**
90
+ * One sentence saying why memory is unavailable, or "" when it is. Only a
91
+ * gateway deployment needs a credential and an address; local direct mode
92
+ * never reports itself unavailable here.
93
+ */
94
+ function unavailable() {
95
+ if (!control || !credentials) return ""
96
+ return unavailableReason({
97
+ source: credentials.source(),
98
+ controlURL: config.controlURL,
99
+ inJelly: credentials.inJelly(),
100
+ })
101
+ }
102
+
103
+ /**
104
+ * Build an upstream scope. A control-plane context is authoritative for the
105
+ * container, user, and agent; without one the fixed local scope applies.
106
+ */
107
+ function scopeFor(context, overrides = {}) {
108
+ return resolveScope(config, {
109
+ ...overrides,
110
+ spaceID: context?.space_id,
111
+ containerID: context?.container_id,
112
+ user: overrides.user || context?.user_id,
113
+ agent: overrides.agent || context?.agent,
114
+ })
115
+ }
116
+
117
+ function scope(overrides = {}) {
118
+ const { context, ...rest } = overrides ?? {}
119
+ return scopeFor(context, rest)
120
+ }
121
+
122
+ /** Shared-asset scope (skills, wiki). Agent is intentionally absent. */
123
+ function sharedScope(overrides = {}) {
124
+ const scoped = scope(overrides)
125
+ delete scoped.agent_id
126
+ return scoped
127
+ }
128
+
129
+ /**
130
+ * The task a session declared most recently through mem_recall, mem_remember,
131
+ * or mem_forget. Captured turns and the compaction checkpoint of that session
132
+ * carry it as `x-tdai-task-id`. Returns the stored key, or "" when the value
133
+ * clears the task or has no usable characters.
134
+ */
135
+ function setSessionTask(sessionID, task) {
136
+ if (!sessionID) return ""
137
+ const key = taskKey(task)
138
+ sessionTasks.delete(String(sessionID))
139
+ if (!key) return ""
140
+ sessionTasks.set(String(sessionID), key)
141
+ if (sessionTasks.size > SESSION_TASKS_MAX) sessionTasks.delete(sessionTasks.keys().next().value)
142
+ return key
143
+ }
144
+
145
+ function taskFor(sessionID) {
146
+ return sessionID ? sessionTasks.get(String(sessionID)) || undefined : undefined
147
+ }
148
+
149
+ /**
150
+ * Ask the control plane for the active context or one explicitly selected
151
+ * space. Returns null in local direct mode, where no control plane exists.
152
+ */
153
+ async function resolveContext(overrides = {}) {
154
+ if (!control) return null
155
+ const space = String(overrides.space ?? "").trim()
156
+ const agent = overrides.agent && overrides.agent !== "auto" ? String(overrides.agent) : undefined
157
+ const context = await control.resolveContext({
158
+ userId: overrides.userId || config.user,
159
+ spaceId: space || undefined,
160
+ sessionId: overrides.sessionID,
161
+ agent,
162
+ })
163
+ // An explicit space together with a session binds the session to that
164
+ // space. When that changes the session's space, the cached session context
165
+ // and the pinned block belong to the previous binding: the next model call
166
+ // starts a new epoch. Re-binding to the same space changes nothing.
167
+ if (space && overrides.sessionID && cachedSpaceOf(overrides.sessionID) !== context?.space_id) {
168
+ invalidate(overrides.sessionID)
169
+ }
170
+ return context
171
+ }
172
+
173
+ /**
174
+ * A shared context is authoritative for writes only when the control plane
175
+ * reports that this session is bound to it. A shared space returned as a
176
+ * global default is not a selection.
177
+ */
178
+ function isSessionBound(context) {
179
+ return Boolean(
180
+ context?.space_id && context?.session_space_id && context.session_space_id === context.space_id,
181
+ )
182
+ }
183
+
184
+ /**
185
+ * The context a session-scoped operation belongs to: personal, or a shared
186
+ * space explicitly bound to the session. In control mode a shared default
187
+ * falls back to the user's personal space rather than silently writing shared.
188
+ * Throws when no safe context can be established; callers must fail closed.
189
+ */
190
+ async function sessionContext(sessionID, agent) {
191
+ if (!control) return null
192
+ const epoch = epochOf(sessionID)
193
+ const context = await resolveSessionContext(sessionID, agent)
194
+ // Every fresh answer refreshes the bootstrap's cached copy, so a captured
195
+ // turn also keeps the pinned block's context current. Writes never read
196
+ // the cache: capture and the tools always resolve fresh.
197
+ if (sessionID && epochOf(sessionID) === epoch) {
198
+ rememberBounded(
199
+ sessionContexts,
200
+ pinKey(sessionID, agent),
201
+ { context, expires: now() + BOOTSTRAP_TTL_MS },
202
+ SESSION_REGISTRY_MAX,
203
+ )
204
+ }
205
+ return context
206
+ }
207
+
208
+ /** The space of any context cached for a session, whatever the agent. */
209
+ function cachedSpaceOf(sessionID) {
210
+ const prefix = `${sessionID}::`
211
+ for (const [key, cached] of sessionContexts) {
212
+ if (key.startsWith(prefix)) return cached.context?.space_id
213
+ }
214
+ return undefined
215
+ }
216
+
217
+ /** The session context cached by the last fresh resolution, if still within the TTL. */
218
+ function cachedSessionContext(sessionID, agent) {
219
+ if (!sessionID) return null
220
+ const cached = sessionContexts.get(pinKey(sessionID, agent))
221
+ return cached && cached.expires > now() ? cached.context : null
222
+ }
223
+
224
+ async function resolveSessionContext(sessionID, agent) {
225
+ const context = await resolveContext({ sessionID, agent })
226
+ if (!context) throw new Error("control plane returned no context")
227
+ // Only a personal space, or a context the control plane reports as bound to
228
+ // this session, is safe for a session-scoped write. An unknown kind is not
229
+ // proof of a personal container, so it follows the same binding rule.
230
+ if (context.space_kind === "personal" || isSessionBound(context)) return context
231
+
232
+ const personalID = context.personal_space_id
233
+ if (!personalID || personalID === context.space_id) {
234
+ throw new Error("the active shared space is not bound to this session")
235
+ }
236
+ // Do not send the session id here: resolving a second space must not
237
+ // rebind the session away from its active shared space.
238
+ const personal = await resolveContext({ space: personalID, agent })
239
+ if (!personal || personal.space_kind === "shared") {
240
+ throw new Error("control plane returned no personal space for this session")
241
+ }
242
+ return personal
243
+ }
244
+
245
+ /**
246
+ * Context for a session-scoped private or team write the plugin places
247
+ * itself: the compaction checkpoint and summary, and the tool helpers.
248
+ * Captured turns do not use it in control mode; the gateway places them
249
+ * (`captureTurn`). Private never follows a shared session binding; it
250
+ * resolves the caller's personal space without touching the binding. Team
251
+ * needs an explicitly bound shared space.
252
+ */
253
+ async function captureContext(sessionID, agent, visibility = config.captureVisibility) {
254
+ if (!control) return null
255
+ const context = await sessionContext(sessionID, agent)
256
+ if (!context) throw new Error("control plane returned no context")
257
+ if (visibility === "team" && context.space_kind === "shared") return context
258
+ if (context.space_kind === "personal") return context
259
+
260
+ const personalID = context.personal_space_id
261
+ if (!personalID || personalID === context.space_id) {
262
+ throw new Error("control plane returned no personal space for private capture")
263
+ }
264
+ const personal = await resolveContext({ space: personalID, agent })
265
+ if (!personal || personal.space_kind === "shared") {
266
+ throw new Error("control plane returned no personal space for private capture")
267
+ }
268
+ return personal
269
+ }
270
+
271
+ /** In control mode the gateway places captured turns (`/v1/capture`). */
272
+ const gatewayCapture = Boolean(control)
273
+ let captureRouteWarned = false
274
+
275
+ /**
276
+ * Control mode: send one completed turn to the gateway's capture route.
277
+ *
278
+ * The plugin sends the session, the agent, the visibility, and the task; the
279
+ * gateway resolves the space and the container, so the plugin makes no
280
+ * control call for a turn and never names a container. A team turn the
281
+ * gateway refuses because the session has no shared binding
282
+ * (`409 capture_not_bound`) is sent once more as private: private is always
283
+ * allowed, it is the narrower visibility, and it keeps the turn instead of
284
+ * quarantining it. A private turn is never re-sent as team.
285
+ *
286
+ * A 404 means the gateway predates the route. It is logged once per
287
+ * process and thrown, so the turn
288
+ * stays in the spool and drains once the gateway is upgraded. There is no
289
+ * fallback to the data plane: that would put the container choice back in
290
+ * the plugin.
291
+ *
292
+ * @param {{ sessionID: string, agent?: string, visibility?: string, task?: string, payload: object }} input
293
+ */
294
+ async function captureTurn({ sessionID, agent, visibility, task, payload }) {
295
+ const requested = visibility === "team" ? "team" : "private"
296
+ const hint = agent && agent !== "auto" ? String(agent) : undefined
297
+ const send = (as) => backend.captureTurn({ sessionID, agent: hint, visibility: as, task, payload })
298
+ try {
299
+ return await send(requested)
300
+ } catch (error) {
301
+ if (requested === "team" && error?.code === "capture_not_bound") {
302
+ log.info("team capture refused: the session is not bound to a shared space; captured as private", { sessionID })
303
+ return send("private")
304
+ }
305
+ if (Number(error?.status) === 404 && !captureRouteWarned) {
306
+ captureRouteWarned = true
307
+ log.warn(
308
+ "the gateway answered 404 for /v1/capture: it predates the capture route (or is 0.4.0, which forwarded to a cell route the deployed core lacks). Turns stay in the spool until it is upgraded; run npm run verify:edge",
309
+ { error: errorMessage(error) },
310
+ )
311
+ }
312
+ throw error
313
+ }
314
+ }
315
+
316
+ /**
317
+ * Record what the host reported about a session. Only the parent link is
318
+ * kept: it never changes for a session, while the active agent can.
319
+ */
320
+ function noteSession(sessionID, info = {}) {
321
+ if (!sessionID) return
322
+ const parentID = info?.parentID ? String(info.parentID) : null
323
+ rememberBounded(sessionParents, String(sessionID), parentID, SESSION_REGISTRY_MAX)
324
+ }
325
+
326
+ /** The recorded parent: a session id, null for a root, undefined when unknown. */
327
+ function parentOf(sessionID) {
328
+ if (!sessionID) return undefined
329
+ return sessionParents.get(String(sessionID))
330
+ }
331
+
332
+ /** A known subagent session that this configuration does not treat as first-class. */
333
+ function skipsSubagent(sessionID) {
334
+ return !config.captureSubagents && Boolean(parentOf(sessionID))
335
+ }
336
+
337
+ function normaliseAgent(agent) {
338
+ if (agent && agent !== "auto") return String(agent)
339
+ return config.agent === "auto" ? "opencode" : String(config.agent)
340
+ }
341
+
342
+ function cacheKey(sessionID, agent, context) {
343
+ const space = context?.space_id || "local"
344
+ return `${sessionID ?? "global"}::${normaliseAgent(agent)}::${space}::${placementSignature(context)}`
345
+ }
346
+
347
+ function pinKey(sessionID, agent) {
348
+ return `${sessionID ?? "global"}::${normaliseAgent(agent)}`
349
+ }
350
+
351
+ /**
352
+ * Build the pinned block. A read that fails is not the same as an empty
353
+ * space: when both reads fail the build fails, so a transient backend error
354
+ * is retried instead of pinning an empty block for the session. A block
355
+ * built with one read missing is marked partial and rebuilt sooner.
356
+ */
357
+ async function buildFor(sessionID, agent, context) {
358
+ const scoped = context ? scopeFor(context, { sessionID, agent }) : scope({ sessionID, agent })
359
+ const settle = (read) =>
360
+ Promise.resolve()
361
+ .then(read)
362
+ .then(
363
+ (value) => ({ value }),
364
+ (error) => ({ error }),
365
+ )
366
+ const [core, scenarios] = await Promise.all([
367
+ settle(() => backend.readCore({ scope: scoped })),
368
+ settle(() => backend.listScenarios({ scope: scoped })),
369
+ ])
370
+ if (core.error && scenarios.error) throw core.error
371
+ const block = buildBootstrap({
372
+ core: core.value ?? null,
373
+ scenarios: scenarios.value?.entries ?? [],
374
+ scope: scoped,
375
+ label: context ? contextScopeLabel(context, scoped) : undefined,
376
+ budgetChars: config.bootstrapChars,
377
+ })
378
+ return { block, partial: Boolean(core.error || scenarios.error) }
379
+ }
380
+
381
+ /** Fail rather than hang when the control plane is slow. */
382
+ async function bounded(promise, timeoutMs, label) {
383
+ if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) return promise
384
+ let timer
385
+ try {
386
+ return await Promise.race([
387
+ promise,
388
+ new Promise((_, reject) => {
389
+ timer = setTimeout(() => reject(new Error(`${label}: timeout after ${timeoutMs}ms`)), timeoutMs)
390
+ }),
391
+ ])
392
+ } finally {
393
+ clearTimeout(timer)
394
+ }
395
+ }
396
+
397
+ const skillSources = createSkillContexts({ config, log, control, scopeFor, sharedScope, bounded })
398
+ const skillContexts = skillSources.skillContexts
399
+
400
+ /** Forget failed bind-refresh attempts so mem-sync retries every space now. */
401
+ function resetSkillContexts() {
402
+ skillMirror.attempts.clear()
403
+ }
404
+
405
+ /** Record what the registry currently mirrors; failed refreshes never call this. */
406
+ function recordSkillMirror(result = {}) {
407
+ skillMirror.count = Number(result.count) || 0
408
+ skillMirror.sourceSpaces = Number(result.sourceSpaces) || 0
409
+ skillMirror.spaceIds = new Set((result.spaceIds ?? []).map(String).filter(Boolean))
410
+ skillMirror.ids = new Set((result.ids ?? []).map(String).filter(Boolean))
411
+ skillMirror.placements = new Map(Object.entries(result.placements ?? {}))
412
+ skillMirror.lastRefreshAt = Date.now()
413
+ for (const spaceID of skillMirror.spaceIds) skillMirror.attempts.delete(spaceID)
414
+ }
415
+
416
+ /** The ids mirrored by the last successful refresh, used to remove stale ones. */
417
+ function mirroredSkillIds() {
418
+ return Array.from(skillMirror.ids)
419
+ }
420
+
421
+ function skillStatus() {
422
+ return {
423
+ count: skillMirror.count,
424
+ sourceSpaces: skillMirror.sourceSpaces,
425
+ spaceIds: Array.from(skillMirror.spaceIds),
426
+ lastRefreshAt: skillMirror.lastRefreshAt ?? null,
427
+ }
428
+ }
429
+
430
+ /**
431
+ * A session bind can reveal a shared space that was not in the registry yet,
432
+ * or a space whose placement moved since the last refresh. Refresh in the
433
+ * background: prompt construction must not wait for skills, and a failed
434
+ * attempt is not retried on every prompt.
435
+ */
436
+ function refreshSkillsForSpace(context) {
437
+ if (!control || !config.skills) return
438
+ if (context?.space_kind !== "shared") return
439
+ const spaceID = String(context.space_id ?? "").trim()
440
+ if (!spaceID) return
441
+ const signature = placementSignature(context)
442
+ if (skillMirror.spaceIds.has(spaceID) && skillMirror.placements.get(spaceID) === signature) return
443
+ if (typeof api?.refreshSkills !== "function") return
444
+ const attempted = skillMirror.attempts.get(spaceID)
445
+ if (attempted && attempted.signature === signature && Date.now() - attempted.at < SKILL_BIND_RETRY_MS) return
446
+ if (skillMirror.inflight) return
447
+ skillMirror.attempts.set(spaceID, { signature, at: Date.now() })
448
+ queueMicrotask(() => {
449
+ if (skillMirror.inflight) return
450
+ skillMirror.inflight = Promise.resolve()
451
+ .then(() => api.refreshSkills({ reason: "session-bind", context, timeoutMs: SKILL_BIND_TIMEOUT_MS }))
452
+ .catch((error) => log.warn("skill refresh after space bind failed", error))
453
+ .finally(() => {
454
+ skillMirror.inflight = null
455
+ })
456
+ })
457
+ }
458
+
459
+ /**
460
+ * Record the agent the host reported for a session: the `prompt` and
461
+ * `context` hooks, every tool call, and the bootstrap. The host's session
462
+ * record has none (OpenCode 2.2 `session.get` has no agent field, verified
463
+ * 2026-11-04), so a captured turn is filed under this agent, the one its
464
+ * tools write and recall as. The latest report wins: a session can switch
465
+ * agents.
466
+ */
467
+ function noteAgent(sessionID, agent) {
468
+ if (!sessionID || agent === undefined || agent === null) return
469
+ const value = String(agent).trim()
470
+ if (!value || value === "auto") return
471
+ rememberBounded(lastAgents, String(sessionID), value, SESSION_REGISTRY_MAX)
472
+ }
473
+
474
+ /** The agent the host last reported for this session (see noteAgent). */
475
+ function lastAgent(sessionID) {
476
+ return sessionID ? lastAgents.get(String(sessionID)) : undefined
477
+ }
478
+
479
+ function epochOf(sessionID) {
480
+ return `${globalEpoch}:${epochs.get(String(sessionID ?? "global")) ?? 0}`
481
+ }
482
+
483
+ function setPin(key, sessionID, epoch, pin) {
484
+ // An invalidation (compaction, /mem-sync, a bind) during the refresh wins:
485
+ // the result belongs to the old epoch and is not stored.
486
+ if (epochOf(sessionID) !== epoch) return
487
+ rememberBounded(pins, key, pin, SESSION_REGISTRY_MAX)
488
+ }
489
+
490
+ /**
491
+ * Resolve and build one session's pinned block under a single deadline: the
492
+ * context resolution and the build share `timeoutMs` instead of each getting
493
+ * it in full.
494
+ */
495
+ async function refreshPin(key, sessionID, agent, timeoutMs) {
496
+ const deadline = Date.now() + timeoutMs
497
+ const remaining = () => Math.max(1, deadline - Date.now())
498
+ const epoch = epochOf(sessionID)
499
+ const previous = pins.get(key)
500
+ const base = { sessionID: sessionID ?? null, agent: normaliseAgent(agent) }
501
+ try {
502
+ let context = null
503
+ if (control) {
504
+ context =
505
+ cachedSessionContext(sessionID, agent) ??
506
+ (await bounded(sessionContext(sessionID, agent), remaining(), "bootstrap context"))
507
+ // Never await this: skills must not delay the pinned block.
508
+ refreshSkillsForSpace(context)
509
+ }
510
+ const blockKey = cacheKey(sessionID, agent, context)
511
+ if (previous?.blockKey === blockKey && !previous.partial) {
512
+ // Same space and placement: keep the pinned bytes, so the provider's
513
+ // prefix cache survives the refresh. Content is rebuilt only at a
514
+ // session, compaction, bind, or /mem-sync boundary.
515
+ setPin(key, sessionID, epoch, { ...previous, fresh: now() + BOOTSTRAP_TTL_MS, retryAt: 0, stale: false, miss: null })
516
+ return previous.block
517
+ }
518
+ const built = await bounded(buildFor(sessionID, agent, context), remaining(), "bootstrap")
519
+ setPin(key, sessionID, epoch, {
520
+ ...base,
521
+ block: built.block,
522
+ blockKey,
523
+ partial: built.partial,
524
+ fresh: now() + (built.partial ? BOOTSTRAP_PARTIAL_TTL_MS : BOOTSTRAP_TTL_MS),
525
+ retryAt: 0,
526
+ stale: false,
527
+ miss: null,
528
+ })
529
+ return built.block
530
+ } catch (error) {
531
+ const miss = { reason: oneLine(errorMessage(error), 200), at: new Date(now()).toISOString() }
532
+ bootstrapMisses.count += 1
533
+ bootstrapMisses.last = { ...miss, sessionID: sessionID ?? null }
534
+ log.warn("bootstrap failed", { sessionID, error: miss.reason })
535
+ // A denial means the space may no longer be readable: stop serving it.
536
+ // Anything else (timeout, outage) keeps the last good block, so a
537
+ // transient failure does not make the system prefix flicker.
538
+ const revoked = [401, 403, 404].includes(Number(error?.status))
539
+ const keep = !revoked && previous?.block ? previous.block : ""
540
+ setPin(key, sessionID, epoch, {
541
+ ...base,
542
+ block: keep,
543
+ blockKey: keep ? previous.blockKey : null,
544
+ partial: Boolean(keep && previous.partial),
545
+ fresh: 0,
546
+ retryAt: now() + BOOTSTRAP_FAILURE_TTL_MS,
547
+ stale: Boolean(keep),
548
+ miss,
549
+ })
550
+ return keep
551
+ }
552
+ }
553
+
554
+ /**
555
+ * Return the pinned block for a session. In control mode the block is built
556
+ * from the session's personal or bound shared space, and a context failure
557
+ * never falls back to a local-scope block.
558
+ *
559
+ * Within the context TTL (10 min) a model call makes no control or backend
560
+ * request at all. After it, the context is resolved once; if the space and
561
+ * placement are unchanged the same bytes are served. A failure is retried
562
+ * after 15 s and, unless access was denied, the last good block is served
563
+ * meanwhile. `timeoutMs` bounds the whole refresh.
564
+ */
565
+ async function bootstrapFor(sessionID, agent, options = {}) {
566
+ const timeoutMs =
567
+ Number.isFinite(options?.timeoutMs) && options.timeoutMs > 0
568
+ ? Math.floor(options.timeoutMs)
569
+ : BOOTSTRAP_DEADLINE_MS
570
+ noteAgent(sessionID, agent)
571
+ const key = pinKey(sessionID, agent)
572
+ const pin = pins.get(key)
573
+ const at = now()
574
+ if (pin?.blockKey && pin.fresh > at) return pin.block
575
+ if (pin && pin.retryAt > at) return pin.block
576
+ if (inflight.has(key)) return inflight.get(key)
577
+ const promise = refreshPin(key, sessionID, agent, timeoutMs).finally(() => {
578
+ if (inflight.get(key) === promise) inflight.delete(key)
579
+ })
580
+ inflight.set(key, promise)
581
+ return promise
582
+ }
583
+
584
+ /** Start fetching early, without awaiting, so dispatch does not pay for it. */
585
+ function prefetchBootstrap(sessionID, agent) {
586
+ if (!config.bootstrap) return
587
+ void bootstrapFor(sessionID, agent).catch(() => {})
588
+ }
589
+
590
+ /**
591
+ * What is pinned for a session, for /mem-why and mem_status. Uses the agent
592
+ * the context hook last pinned for, so it reports the block actually sent.
593
+ */
594
+ function pinFor(sessionID, agent) {
595
+ const pin = pins.get(pinKey(sessionID, agent ?? lastAgent(sessionID)))
596
+ if (!pin) return null
597
+ return {
598
+ block: pin.block,
599
+ agent: pin.agent,
600
+ stale: Boolean(pin.stale),
601
+ partial: Boolean(pin.partial),
602
+ miss: pin.miss ?? null,
603
+ }
604
+ }
605
+
606
+ function pinnedCount() {
607
+ let pinned = 0
608
+ for (const pin of pins.values()) if (pin.block) pinned += 1
609
+ return pinned
610
+ }
611
+
612
+ function bootstrapStatus(sessionID, agent) {
613
+ let stale = 0
614
+ for (const pin of pins.values()) if (pin.stale) stale += 1
615
+ return {
616
+ pinned: pinnedCount(),
617
+ stale,
618
+ misses: bootstrapMisses.count,
619
+ lastMiss: bootstrapMisses.last,
620
+ session: sessionID ? pinFor(sessionID, agent) : null,
621
+ }
622
+ }
623
+
624
+ /**
625
+ * Start a new context epoch: compaction, /mem-sync, and a session bind call
626
+ * this. The next model call resolves the context and rebuilds the block.
627
+ */
628
+ function invalidate(sessionID) {
629
+ if (!sessionID) {
630
+ globalEpoch += 1
631
+ pins.clear()
632
+ sessionContexts.clear()
633
+ inflight.clear()
634
+ return
635
+ }
636
+ const id = String(sessionID)
637
+ rememberBounded(epochs, id, (epochs.get(id) ?? 0) + 1, SESSION_REGISTRY_MAX)
638
+ for (const map of [pins, sessionContexts, inflight]) {
639
+ for (const key of Array.from(map.keys())) {
640
+ if (key.startsWith(`${id}::`)) map.delete(key)
641
+ }
642
+ }
643
+ }
644
+
645
+ /**
646
+ * Write a pre-compaction checkpoint to L0.
647
+ *
648
+ * The checkpoint is private by default. In control mode a private write resolves
649
+ * the caller's personal space; if that resolution fails the checkpoint is
650
+ * skipped, never redirected to a local container or the active shared space.
651
+ * The write is bounded, deduplicated, and always invalidates the pinned
652
+ * bootstrap so post-compaction context is fresh.
653
+ *
654
+ * @param {{ sessionID?: string, agent?: string, messages?: any[], timeoutMs?: number, model?: any, directory?: string }} input
655
+ * @returns {Promise<{ ok: boolean, chars: number, sessionID: string, reason?: string }>}
656
+ * `reason` says why nothing was written: no-session, disabled, unavailable, subagent,
657
+ * context-unresolved, no-context, empty, duplicate, or write-failed.
658
+ */
659
+ async function writeCompactionCheckpoint(input = {}) {
660
+ if (!input || typeof input !== "object") input = {}
661
+ const sessionID = input.sessionID ? String(input.sessionID) : ""
662
+ const skipped = (reason) => ({ ok: false, chars: 0, sessionID, reason })
663
+ if (!sessionID) return skipped("no-session")
664
+ if (config.compactionCheckpoint === false) return skipped("disabled")
665
+ if (unavailable()) return skipped("unavailable")
666
+ if (skipsSubagent(sessionID)) return skipped("subagent")
667
+
668
+ const timeoutMs =
669
+ Number.isFinite(input.timeoutMs) && input.timeoutMs > 0 ? Math.floor(input.timeoutMs) : COMPACTION_TIMEOUT_MS
670
+ const deadline = Date.now() + timeoutMs
671
+ const remaining = () => Math.max(1, deadline - Date.now())
672
+ const messages = Array.isArray(input.messages) ? input.messages : []
673
+
674
+ try {
675
+ let context = null
676
+ let scoped
677
+ if (control) {
678
+ try {
679
+ context = await bounded(captureContext(sessionID, input.agent, "private"), remaining(), "compaction context")
680
+ } catch (error) {
681
+ // Never fall back to a local container: a checkpoint that cannot be
682
+ // placed safely is skipped.
683
+ log.warn("compaction checkpoint skipped: control context unresolved", {
684
+ sessionID,
685
+ error: errorMessage(error),
686
+ })
687
+ return skipped("context-unresolved")
688
+ }
689
+ if (!context) {
690
+ log.warn("compaction checkpoint skipped: control returned no context", { sessionID })
691
+ return skipped("no-context")
692
+ }
693
+ scoped = scopeFor(context, { sessionID, agent: input.agent, task: taskFor(sessionID) })
694
+ } else {
695
+ scoped = scope({ sessionID, agent: input.agent, task: taskFor(sessionID) })
696
+ }
697
+
698
+ const label = context ? contextScopeLabel(context, scoped) : scopeLabel(scoped)
699
+ const checkpoint = buildCheckpoint({
700
+ sessionID,
701
+ agent: input.agent,
702
+ messages,
703
+ space: label,
704
+ now: new Date(),
705
+ directory: typeof input.directory === "string" ? input.directory : undefined,
706
+ })
707
+ if (!checkpoint) {
708
+ log.debug("compaction checkpoint skipped: nothing to checkpoint", { sessionID })
709
+ return skipped("empty")
710
+ }
711
+
712
+ // The timestamp changes on every fire; exclude it so a repeated compaction
713
+ // event for the same transcript is recognized as a duplicate.
714
+ const fingerprint = checkpointFingerprint(checkpoint.text)
715
+ const key = `${sessionID}::${checkpoint.messageID ?? "-"}::${checkpoint.messageCount}::${fingerprint}`
716
+ if (compactionSeen.has(key)) {
717
+ log.debug("duplicate compaction checkpoint suppressed", { sessionID })
718
+ return skipped("duplicate")
719
+ }
720
+
721
+ // The extraction profile is keyed by the write session. Two spaces must
722
+ // never share one, so the space is part of the synthetic session id.
723
+ const spaceKey = context?.space_id
724
+ ? `space-${shortHash(context.space_id, 8)}`
725
+ : `local-${shortHash(scopeLabel(scoped), 8)}`
726
+ const checkpointSessionID = `${spaceKey}-${sessionID}-checkpoint-${shortHash(fingerprint, 8)}`
727
+ const payload = {
728
+ sessionID: checkpointSessionID,
729
+ messages: [
730
+ { role: "user", content: checkpoint.text },
731
+ { role: "assistant", content: "Checkpoint recorded." },
732
+ ],
733
+ scope: { ...scoped, session_id: checkpointSessionID },
734
+ }
735
+
736
+ await bounded(backend.addConversation(payload), remaining(), "compaction checkpoint")
737
+ // Only a successful write is deduplicated. A failed write must remain
738
+ // eligible for the next compaction event or a retry.
739
+ rememberBounded(compactionSeen, key, Date.now(), COMPACTION_DEDUPE_MAX)
740
+ // The host summary of this compaction would be a second L0 write and a
741
+ // second extraction pass for the same state. Record, across processes,
742
+ // that this session's compaction is covered.
743
+ spool.markCheckpoint(sessionID)
744
+ log.info("compaction checkpoint written", {
745
+ sessionID,
746
+ chars: checkpoint.text.length,
747
+ messages: checkpoint.messageCount,
748
+ space: context?.space_id ?? null,
749
+ })
750
+ return { ok: true, chars: checkpoint.text.length, sessionID }
751
+ } catch (error) {
752
+ log.warn("compaction checkpoint failed", { sessionID, error: errorMessage(error) })
753
+ return skipped("write-failed")
754
+ } finally {
755
+ invalidate(sessionID)
756
+ }
757
+ }
758
+
759
+ const spool = createSpool({ config, log, backend, captureTurn: gatewayCapture ? captureTurn : null, now })
760
+ let lastDrain = 0
761
+
762
+ /**
763
+ * After a successful live capture the backend is reachable: drain what is
764
+ * queued in the background. Rate-limited so a busy session does not rescan
765
+ * the spool on every turn.
766
+ */
767
+ function drainSpool() {
768
+ if (!config.spool) return
769
+ const started = Date.now()
770
+ if (started - lastDrain < SPOOL_DRAIN_INTERVAL_MS) return
771
+ lastDrain = started
772
+ if (spool.spoolStats().pending === 0) return
773
+ void spool.flushSpool().catch((error) => log.warn("background spool flush failed", errorMessage(error)))
774
+ }
775
+
776
+ async function status(overrides = {}) {
777
+ const { context, ...rest } = overrides
778
+ const scoped = scope({ ...rest, context, visibility: rest.visibility ?? config.captureVisibility })
779
+ const shared = sharedScope({ context })
780
+ // Counts describe the whole scope, not the current session.
781
+ const wide = { ...scoped }
782
+ delete wide.session_id
783
+ const health = await backend.probe()
784
+ const [conversations, atoms, scenarios, core, skills, knowledge, wikis, graphs] = await Promise.all([
785
+ backend.countConversations({ scope: wide }).catch(() => null),
786
+ backend.countAtoms({ scope: wide }).catch(() => null),
787
+ backend.countScenarios({ scope: wide }).catch(() => null),
788
+ backend.readCore({ scope: wide }).catch(() => null),
789
+ backend.listSkills({ scope: shared }).catch(() => null),
790
+ backend.listKnowledge({ scope: shared }).catch(() => null),
791
+ backend.listWiki({ scope: shared }).catch(() => null),
792
+ backend.listCodeGraph({ scope: shared }).catch(() => null),
793
+ ])
794
+ return {
795
+ health: health.ok ? "ok" : `unavailable (${health.error})`,
796
+ scope: context ? contextScopeLabel(context, scoped) : scopeLabel(scoped),
797
+ space: context?.space_id ?? null,
798
+ spaceName: context?.space_name ?? null,
799
+ spaceKind: context?.space_kind ?? null,
800
+ collection: context?.collection_id ?? null,
801
+ capture: config.captureVisibility,
802
+ layers: {
803
+ l0: conversations?.total ?? null,
804
+ l1: atoms?.total ?? null,
805
+ l2: scenarios?.total ?? null,
806
+ l3: Boolean(core?.content),
807
+ skills: skills?.total ?? null,
808
+ knowledge: (knowledge?.total ?? 0) + (wikis?.total ?? 0) + (graphs?.total ?? 0),
809
+ },
810
+ sourceSpaces: skillMirror.sourceSpaces,
811
+ mirroredSkills: skillMirror.count,
812
+ pinned: pinnedCount(),
813
+ bootstrap: bootstrapStatus(rest.sessionID, rest.agent),
814
+ spool: spool.spoolStats(),
815
+ }
816
+ }
817
+
818
+ api = {
819
+ config,
820
+ log,
821
+ backend,
822
+ control,
823
+ credentials,
824
+ unavailable,
825
+ scope,
826
+ scopeFor,
827
+ sharedScope,
828
+ resolveContext,
829
+ isSessionBound,
830
+ sessionContext,
831
+ captureContext,
832
+ gatewayCapture,
833
+ captureTurn,
834
+ noteSession,
835
+ noteAgent,
836
+ agentFor: lastAgent,
837
+ parentOf,
838
+ skipsSubagent,
839
+ setSessionTask,
840
+ taskFor,
841
+ skillContexts,
842
+ resetSkillContexts,
843
+ recordSkillMirror,
844
+ mirroredSkillIds,
845
+ skillStatus,
846
+ bootstrapFor,
847
+ prefetchBootstrap,
848
+ pinFor,
849
+ lastAgent,
850
+ bootstrapStatus,
851
+ writeCompactionCheckpoint,
852
+ invalidate,
853
+ writeSpool: spool.writeSpool,
854
+ stageSpool: spool.stageSpool,
855
+ releaseSpool: spool.releaseSpool,
856
+ removeSpool: spool.removeSpool,
857
+ claimCapture: spool.claimCapture,
858
+ releaseCapture: spool.releaseCapture,
859
+ recentCheckpoint: spool.recentCheckpoint,
860
+ pruneClaims: spool.pruneClaims,
861
+ enqueueSpool: spool.enqueueSpool,
862
+ flushSpool: spool.flushSpool,
863
+ spoolStats: spool.spoolStats,
864
+ drainSpool,
865
+ status,
866
+ }
867
+ return api
868
+ }