@joe-broadhead/opencode-mem 0.8.5 → 0.9.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.
Files changed (58) hide show
  1. package/CHANGELOG.md +512 -0
  2. package/README.md +127 -61
  3. package/docs/agent-protocol.md +67 -177
  4. package/package.json +1453 -100
  5. package/skills/mem.pages/SKILL.md +146 -0
  6. package/skills/mem.sharing/SKILL.md +91 -0
  7. package/skills/mem.sources/SKILL.md +94 -0
  8. package/skills/mem.usage/SKILL.md +129 -492
  9. package/src/backend/records.js +285 -0
  10. package/src/backend/v3.js +3 -0
  11. package/src/bootstrap.js +49 -45
  12. package/src/call-shapes.js +41 -10
  13. package/src/collector-lock.js +162 -0
  14. package/src/collector-service.js +441 -0
  15. package/src/collector.js +381 -0
  16. package/src/commands.js +3 -3
  17. package/src/config.js +15 -1
  18. package/src/credentials.js +26 -1
  19. package/src/curation.js +1 -1
  20. package/src/permissions.js +87 -10
  21. package/src/protocol.js +29 -20
  22. package/src/recall.js +104 -27
  23. package/src/records-store.js +267 -121
  24. package/src/records.js +63 -11
  25. package/src/runtime.js +23 -14
  26. package/src/skills.js +44 -18
  27. package/src/sources.js +58 -0
  28. package/src/spaces.js +93 -10
  29. package/src/tools/aliases.js +164 -0
  30. package/src/tools/commitments.js +12 -9
  31. package/src/tools/held-write.js +82 -0
  32. package/src/tools/index.js +100 -23
  33. package/src/tools/ingest.js +277 -0
  34. package/src/tools/knowledge.js +6 -1
  35. package/src/tools/memory.js +722 -229
  36. package/src/tools/page.js +423 -0
  37. package/src/tools/recall.js +371 -113
  38. package/src/tools/records-kit.js +142 -0
  39. package/src/tools/share.js +1042 -0
  40. package/src/tools/shared.js +16 -2
  41. package/src/tools/spaces.js +431 -143
  42. package/src/tools/status.js +87 -58
  43. package/src/tools/wiki.js +8 -4
  44. package/src/views/contracts.js +293 -3
  45. package/src/views/inbox-decision.js +59 -0
  46. package/src/views/recall-result.js +12 -0
  47. package/src/views/records-reads.js +675 -0
  48. package/src/views/rpc.js +58 -99
  49. package/src/views/shape.js +61 -0
  50. package/views/commitments.html +4 -0
  51. package/views/graph.html +753 -0
  52. package/views/home.html +11 -5
  53. package/views/journal.html +621 -0
  54. package/views/memory.html +7 -1
  55. package/views/pages.html +636 -0
  56. package/views/recall.html +123 -0
  57. package/views/review.html +406 -0
  58. package/views/today.html +309 -0
@@ -0,0 +1,162 @@
1
+ import fs from "node:fs"
2
+ import os from "node:os"
3
+ import path from "node:path"
4
+ import { randomUUID } from "node:crypto"
5
+
6
+ /** A lease whose heartbeat is older than this belongs to a process that stopped. */
7
+ export const LEASE_STALE_MS = 10 * 60_000
8
+
9
+ /**
10
+ * One collector per machine (docs/design/memory-v1-contracts.md §4.4): a lease
11
+ * on `collector.lock` beside the spool, held by one OpenCode process and kept
12
+ * alive by a heartbeat (the file's modification time). Every other process
13
+ * sees a fresh lease and skips; a lease whose heartbeat is older than ten
14
+ * minutes is taken over.
15
+ *
16
+ * Built on the same file primitives as the spool's cross-process claims
17
+ * (src/spool.js): no-clobber creation and atomic rename. The spool's own
18
+ * helpers are one-shot claims with no heartbeat, so the lease is its own:
19
+ *
20
+ * - **create** writes the record to a private temp file and hard-links it to
21
+ * `collector.lock`; `link` fails when the name exists, so exactly one of
22
+ * several racing processes creates it, and nobody ever reads a half-written
23
+ * lock;
24
+ * - **take over** renames the stale lock to a name of the taker's own (one
25
+ * rename wins), checks that what it moved is the stale lease it judged
26
+ * (same holder and heartbeat) and puts it back if not, then creates;
27
+ * - **heartbeat** sets the file's times, only while the record is still this
28
+ * holder's;
29
+ * - **release** removes the file, only while it is still this holder's.
30
+ *
31
+ * `onStale` (tests only) runs between judging a lease stale and moving it, the
32
+ * window in which another process may beat or take it.
33
+ *
34
+ * @param {{ file: string, staleMs?: number, now?: () => number, id?: string, pid?: number, log?: any, onStale?: (lease: object) => void }} input
35
+ */
36
+ export function createLease({ file, staleMs = LEASE_STALE_MS, now = Date.now, id = randomUUID(), pid = process.pid, log, onStale }) {
37
+ const dir = path.dirname(file)
38
+
39
+ function readAt(target) {
40
+ let stat
41
+ try {
42
+ stat = fs.statSync(target)
43
+ } catch (error) {
44
+ if (error?.code === "ENOENT") return null
45
+ throw error
46
+ }
47
+ let record = {}
48
+ try {
49
+ record = JSON.parse(fs.readFileSync(target, "utf8"))
50
+ } catch {
51
+ record = {}
52
+ }
53
+ return {
54
+ id: typeof record.id === "string" ? record.id : "",
55
+ pid: Number(record.pid) || 0,
56
+ host: typeof record.host === "string" ? record.host : "",
57
+ since: typeof record.since === "string" ? record.since : "",
58
+ heartbeat: stat.mtimeMs,
59
+ }
60
+ }
61
+
62
+ /** The lease as it stands: its holder and heartbeat, or null when nobody holds it. */
63
+ function holder() {
64
+ return readAt(file)
65
+ }
66
+
67
+ const isStale = (lease) => now() - lease.heartbeat >= staleMs
68
+
69
+ function touch(target) {
70
+ const seconds = now() / 1000
71
+ fs.utimesSync(target, seconds, seconds)
72
+ }
73
+
74
+ function unlinkQuiet(target) {
75
+ try {
76
+ fs.unlinkSync(target)
77
+ } catch {
78
+ /* already gone */
79
+ }
80
+ }
81
+
82
+ /** Create the lock without clobbering one that exists; true when this holder made it. */
83
+ function create() {
84
+ const temp = `${file}.${id}.tmp`
85
+ fs.writeFileSync(temp, JSON.stringify({ id, pid, host: os.hostname(), since: new Date(now()).toISOString() }), { mode: 0o600 })
86
+ try {
87
+ touch(temp)
88
+ fs.linkSync(temp, file)
89
+ return true
90
+ } catch (error) {
91
+ if (error?.code === "EEXIST") return false
92
+ throw error
93
+ } finally {
94
+ unlinkQuiet(temp)
95
+ }
96
+ }
97
+
98
+ /**
99
+ * Hold the lease: keep it (refreshing the heartbeat) when this holder has it,
100
+ * create it when nobody does, take it over when its heartbeat is stale.
101
+ *
102
+ * @returns {{ owned: true, took?: "free" | "stale" } | { owned: false, holder: ReturnType<typeof holder> }}
103
+ */
104
+ function acquire() {
105
+ fs.mkdirSync(dir, { recursive: true, mode: 0o700 })
106
+ const current = holder()
107
+ if (current && current.id === id) {
108
+ touch(file)
109
+ return { owned: true }
110
+ }
111
+ if (current && !isStale(current)) return { owned: false, holder: current }
112
+ if (current) {
113
+ onStale?.(current)
114
+ const aside = `${file}.stale-${id}`
115
+ try {
116
+ fs.renameSync(file, aside)
117
+ } catch (error) {
118
+ if (error?.code !== "ENOENT") throw error
119
+ }
120
+ const moved = readAt(aside)
121
+ if (moved && (moved.id !== current.id || moved.heartbeat !== current.heartbeat)) {
122
+ // Someone took the stale lease, or its holder beat, between the read
123
+ // and the rename: give it back unless the name is already taken again.
124
+ try {
125
+ fs.linkSync(aside, file)
126
+ } catch {
127
+ /* the name was taken again; that holder stands */
128
+ }
129
+ unlinkQuiet(aside)
130
+ return { owned: false, holder: holder() ?? moved }
131
+ }
132
+ unlinkQuiet(aside)
133
+ if (moved) log?.info?.("collector lease taken over from a stopped process", { pid: moved.pid })
134
+ }
135
+ if (create()) return { owned: true, took: current ? "stale" : "free" }
136
+ return { owned: false, holder: holder() }
137
+ }
138
+
139
+ /** Refresh the heartbeat; false when the lease is no longer this holder's. */
140
+ function heartbeat() {
141
+ try {
142
+ const current = holder()
143
+ if (!current || current.id !== id) return false
144
+ touch(file)
145
+ return true
146
+ } catch {
147
+ return false
148
+ }
149
+ }
150
+
151
+ /** Give the lease up, if this holder still has it. */
152
+ function release() {
153
+ try {
154
+ const current = holder()
155
+ if (current && current.id === id) fs.unlinkSync(file)
156
+ } catch {
157
+ /* nothing to release */
158
+ }
159
+ }
160
+
161
+ return { id, file, acquire, heartbeat, release, holder, isStale }
162
+ }
@@ -0,0 +1,441 @@
1
+ import fs from "node:fs"
2
+ import path from "node:path"
3
+ import { COLLECT_SESSION, COLLECT_SESSION_RULES, collectableSources, createCollector, hostScheduler, hostSourceLister } from "./collector.js"
4
+ import { createLease } from "./collector-lock.js"
5
+ import { knownSources, sourceEntry } from "./sources.js"
6
+ import { errorMessage, isPlainObject, oneLine } from "./util.js"
7
+ import { recordsOf } from "./tools/share.js"
8
+ import { unboundOwner } from "./backend/records.js"
9
+
10
+ /** How long `collect` with `wait: true` and `/mem-collect` wait before reporting progress. */
11
+ export const COLLECT_WAIT_MS = 25_000
12
+ /** The lease's heartbeat, and how often the holder looks for a forwarded request. */
13
+ export const HEARTBEAT_MS = 60_000
14
+ /** After a run that left pages behind, the next run comes this soon, up to CATCH_UP_RUNS times. */
15
+ export const CATCH_UP_MS = 60_000
16
+ export const CATCH_UP_RUNS = 10
17
+ /** The first run after startup comes after a random wait in this range, so processes that start together spread out. */
18
+ export const STARTUP_JITTER_MS = Object.freeze([10_000, 60_000])
19
+
20
+ const REAL_CLOCK = Object.freeze({
21
+ now: () => Date.now(),
22
+ setTimeout: (fn, ms) => {
23
+ const handle = setTimeout(fn, ms)
24
+ handle?.unref?.()
25
+ return handle
26
+ },
27
+ clearTimeout: (handle) => clearTimeout(handle),
28
+ setInterval: (fn, ms) => {
29
+ const handle = setInterval(fn, ms)
30
+ handle?.unref?.()
31
+ return handle
32
+ },
33
+ clearInterval: (handle) => clearInterval(handle),
34
+ })
35
+
36
+ /**
37
+ * The in-plugin collector (docs/design/memory-v1-contracts.md §4.4).
38
+ *
39
+ * - **When:** a timer every `collectEveryMinutes` (default 30) while OpenCode
40
+ * runs, a first run shortly after startup (which catches up from the
41
+ * cursors), follow-up runs while a source still has pages waiting, and on
42
+ * request (`mem_collect`, `/mem-collect`). `collect: false` (or
43
+ * `MEMORY_COLLECT=0`) turns the timer off; a request still runs.
44
+ * - **Who:** one OpenCode process per machine, the holder of `collector.lock`
45
+ * beside the spool (src/collector-lock.js). Another process that is asked
46
+ * to collect leaves a request the holder picks up at its next heartbeat.
47
+ * - **How:** each source's `events_list` through the host's tools RPC, in the
48
+ * reserved session `ses_mem_collect`, whose own rules allow only the
49
+ * sources' `events_list`; then `events.ingest` and `events.cursor` on the
50
+ * records service, in the personal space.
51
+ * - **Safety:** nothing here blocks the host or throws into it: every timer
52
+ * callback is caught and logged. With no credential (`runtime.availability`)
53
+ * or no records client a run is skipped before it touches a file.
54
+ * - **Health:** each run's outcome, per source, is written to
55
+ * `collector.json` beside the lock, so `mem_spaces` health reads it in any
56
+ * process.
57
+ *
58
+ * @param {{
59
+ * ctx: any, runtime: any, toolkit: any,
60
+ * clock?: typeof REAL_CLOCK, random?: () => number, waitMs?: number,
61
+ * lease?: ReturnType<typeof createLease>,
62
+ * }} input
63
+ */
64
+ export function createCollectorService({ ctx, runtime, toolkit, clock = REAL_CLOCK, random = Math.random, waitMs = COLLECT_WAIT_MS, lease }) {
65
+ const config = runtime.config
66
+ const log = runtime.log
67
+ const stateDir = config.stateDir
68
+ const statusFile = path.join(stateDir, "collector.json")
69
+ const requestFile = path.join(stateDir, "collector.request")
70
+ const lock = lease ?? createLease({ file: path.join(stateDir, "collector.lock"), now: clock.now, log })
71
+ const everyMs = Math.max(5, Number(config.collectEveryMinutes) || 30) * 60_000
72
+
73
+ let sessionReady = null
74
+ /** The reserved session the RPC calls run in; `fallback` (the caller's session) when the host cannot make one. */
75
+ async function rpcSession(fallback) {
76
+ if (typeof ctx?.session?.create !== "function") {
77
+ if (fallback) return fallback
78
+ throw new Error("this host cannot make the collector's session")
79
+ }
80
+ sessionReady ??= (async () => {
81
+ const agent = await pickAgent()
82
+ await ctx.session.create({
83
+ id: COLLECT_SESSION,
84
+ title: "Memory collection",
85
+ agent,
86
+ ...(ctx?.location?.directory ? { location: { directory: ctx.location.directory } } : {}),
87
+ metadata: { memory: { role: "collector" } },
88
+ permissions: COLLECT_SESSION_RULES.map((rule) => ({ ...rule })),
89
+ })
90
+ return COLLECT_SESSION
91
+ })().catch((error) => {
92
+ sessionReady = null
93
+ // Creation by id is idempotent; a host that says the session exists is fine.
94
+ if (/exist/i.test(errorMessage(error))) return COLLECT_SESSION
95
+ throw error
96
+ })
97
+ try {
98
+ return await sessionReady
99
+ } catch (error) {
100
+ if (fallback) return fallback
101
+ throw new Error(`the collector's session could not be made (${oneLine(errorMessage(error), 200)})`)
102
+ }
103
+ }
104
+
105
+ async function pickAgent() {
106
+ if (config.agent && config.agent !== "auto") return config.agent
107
+ try {
108
+ const listed = await ctx?.agent?.list?.()
109
+ const agents = (Array.isArray(listed?.data) ? listed.data : Array.isArray(listed) ? listed : []).map((agent) => String(agent?.id ?? agent?.name ?? "")).filter(Boolean)
110
+ return agents.includes("build") ? "build" : agents[0] || "build"
111
+ } catch {
112
+ return "build"
113
+ }
114
+ }
115
+
116
+ const collector = createCollector({ scheduler: hostScheduler(ctx, () => rpcSession()), lister: hostSourceLister(ctx), log })
117
+
118
+ const timers = { startup: null, interval: null, heartbeat: null, catchUp: null }
119
+ let active = null
120
+ let leader = false
121
+ let catchUps = 0
122
+ let last = null
123
+ let stopped = false
124
+ let lastStartedAt = 0
125
+
126
+ function writeStatus(status) {
127
+ try {
128
+ fs.mkdirSync(stateDir, { recursive: true, mode: 0o700 })
129
+ const temp = `${statusFile}.${lock.id}.tmp`
130
+ fs.writeFileSync(temp, JSON.stringify(status, null, 2), { mode: 0o600 })
131
+ fs.renameSync(temp, statusFile)
132
+ } catch (error) {
133
+ log?.warn?.("collector status could not be written", { error: errorMessage(error) })
134
+ }
135
+ }
136
+
137
+ function readStatus() {
138
+ try {
139
+ const value = JSON.parse(fs.readFileSync(statusFile, "utf8"))
140
+ return isPlainObject(value) ? value : null
141
+ } catch {
142
+ return null
143
+ }
144
+ }
145
+
146
+ function requestRun() {
147
+ try {
148
+ fs.mkdirSync(stateDir, { recursive: true, mode: 0o700 })
149
+ fs.writeFileSync(requestFile, JSON.stringify({ pid: process.pid, at: new Date(clock.now()).toISOString() }), { mode: 0o600 })
150
+ const seconds = clock.now() / 1000
151
+ fs.utimesSync(requestFile, seconds, seconds)
152
+ return true
153
+ } catch {
154
+ return false
155
+ }
156
+ }
157
+
158
+ function pendingRequest() {
159
+ try {
160
+ // A request written in the same millisecond a run started runs again: never lost, and a repeat is harmless.
161
+ return fs.statSync(requestFile).mtimeMs >= lastStartedAt
162
+ } catch {
163
+ return false
164
+ }
165
+ }
166
+
167
+ const unavailable = async () => {
168
+ try {
169
+ return (runtime.availability ? await runtime.availability() : runtime.unavailable?.()) ?? ""
170
+ } catch (error) {
171
+ return errorMessage(error)
172
+ }
173
+ }
174
+
175
+ const holderText = (holder) => `another OpenCode process on this machine${holder?.pid ? ` (pid ${holder.pid})` : ""} collects`
176
+
177
+ /**
178
+ * Start one collection unless one is running here, memory is unavailable, or
179
+ * another process holds the lease. Returns at once.
180
+ *
181
+ * @param {"startup" | "timer" | "catch-up" | "request" | "tool" | "command"} trigger
182
+ * @returns {Promise<{ started: true } | { running: true, since: string } | { skipped: string }>}
183
+ */
184
+ async function begin(trigger, { only, sessionID } = {}) {
185
+ if (active) return { running: true, since: new Date(active.started).toISOString() }
186
+ const reason = await unavailable()
187
+ if (reason) return remember(trigger, { skipped: reason })
188
+ if (!recordsOf(toolkit)) return remember(trigger, { skipped: "this plugin build has no records client" })
189
+ if (!collector.lister) return remember(trigger, { skipped: "this host gives plugins no tools RPC, so Memory cannot reach the sources' events_list" })
190
+ if (active) return { running: true, since: new Date(active.started).toISOString() }
191
+ let elected
192
+ try {
193
+ elected = lock.acquire()
194
+ } catch (error) {
195
+ return remember(trigger, { skipped: `the collector lock could not be read (${oneLine(errorMessage(error), 160)})` })
196
+ }
197
+ leader = elected.owned
198
+ if (!elected.owned) {
199
+ if (trigger === "tool" || trigger === "command") {
200
+ const asked = requestRun()
201
+ return { skipped: `${holderText(elected.holder)}; ${asked ? "it was asked to run now, and its counts appear in mem_spaces health" : "its counts appear in mem_spaces health"}`, forwarded: asked, holder: elected.holder?.pid ?? 0 }
202
+ }
203
+ return { skipped: holderText(elected.holder) }
204
+ }
205
+ const started = clock.now()
206
+ lastStartedAt = started
207
+ const results = []
208
+ active = { started, trigger, only, results, promise: null }
209
+ active.promise = collect(trigger, { only, sessionID, results, started })
210
+ .catch((error) => {
211
+ log?.warn?.("collection failed", { error: errorMessage(error) })
212
+ return finish(trigger, started, results, errorMessage(error))
213
+ })
214
+ .finally(() => {
215
+ active = null
216
+ })
217
+ return { started: true }
218
+ }
219
+
220
+ function remember(trigger, outcome) {
221
+ last = { trigger, at: new Date(clock.now()).toISOString(), state: "skipped", reason: outcome.skipped, sources: [] }
222
+ log?.debug?.("collection skipped", { trigger, reason: outcome.skipped })
223
+ return outcome
224
+ }
225
+
226
+ async function collect(trigger, { only, sessionID, results, started }) {
227
+ writeStatus({ state: "running", trigger, pid: process.pid, started: new Date(started).toISOString(), sources: [] })
228
+ const records = recordsOf(toolkit)
229
+ let where = { sessionID }
230
+ if (toolkit.control) {
231
+ const resolved = await toolkit.resolvePrivateSpace({}, { sessionID, agent: runtime.agentFor?.(sessionID) })
232
+ if (resolved.invalid || resolved.error) throw new Error(resolved.invalid || resolved.error)
233
+ where = { space: resolved.context.space_id }
234
+ }
235
+ const sources = (await records.call("sources.list", {}, where))?.sources ?? []
236
+ await collector.sync(sources)
237
+ const rpc = await rpcSession(sessionID)
238
+ await collector.runOnce({
239
+ sources,
240
+ only,
241
+ sessionID: rpc,
242
+ results,
243
+ cursor: (binding) => records.call("events.cursor", binding, where),
244
+ ingest: async (input) => {
245
+ try {
246
+ return await records.call("events.ingest", input, where)
247
+ } catch (error) {
248
+ if (String(error?.code ?? error?.error?.code ?? "") === "source_unbound") {
249
+ collector.noteOwner(input.source, input.account, unboundOwner(error) ?? input.owner)
250
+ return { cursor_saved: false, error: `${input.source}:${input.account} is not bound to the account signed in; the person confirms it with mem_spaces sources bind` }
251
+ }
252
+ throw error
253
+ }
254
+ },
255
+ })
256
+ return finish(trigger, started, results, "", collectableSources(sources, { only }).length === 0)
257
+ }
258
+
259
+ function finish(trigger, started, results, error, none = false) {
260
+ const ended = clock.now()
261
+ last = {
262
+ state: error ? "failed" : "done",
263
+ trigger,
264
+ pid: process.pid,
265
+ started: new Date(started).toISOString(),
266
+ ended: new Date(ended).toISOString(),
267
+ ...(error ? { error: oneLine(error, 300) } : {}),
268
+ ...(none ? { none: true } : {}),
269
+ sources: results.map(({ done: _done, ...result }) => ({ ...result, ...(result.error ? { error: oneLine(result.error, 300) } : {}) })),
270
+ }
271
+ writeStatus(last)
272
+ const behind = results.some((result) => result.more && !result.error)
273
+ if (behind && catchUps < CATCH_UP_RUNS && !stopped) {
274
+ catchUps += 1
275
+ clock.clearTimeout(timers.catchUp)
276
+ timers.catchUp = clock.setTimeout(() => safely("catch-up"), CATCH_UP_MS)
277
+ } else if (!behind) catchUps = 0
278
+ log?.info?.("collection", { trigger, sources: results.length, failed: Boolean(error) })
279
+ return last
280
+ }
281
+
282
+ /** A timer's callback: never throws into the host. */
283
+ function safely(trigger) {
284
+ begin(trigger).catch((error) => log?.warn?.("collector timer failed", { error: errorMessage(error) }))
285
+ }
286
+
287
+ function beat() {
288
+ try {
289
+ if (leader && !lock.heartbeat()) {
290
+ leader = false
291
+ log?.info?.("collector lease lost to another process")
292
+ }
293
+ if (leader && !active && pendingRequest()) {
294
+ safely("request")
295
+ try {
296
+ fs.unlinkSync(requestFile)
297
+ } catch {
298
+ /* already taken */
299
+ }
300
+ }
301
+ } catch (error) {
302
+ log?.warn?.("collector heartbeat failed", { error: errorMessage(error) })
303
+ }
304
+ }
305
+
306
+ /** Start the timers. Returns at once; the first run comes after a short random wait. */
307
+ function start() {
308
+ if (!config.collect) {
309
+ log?.info?.("collection timer off (collect: false)")
310
+ return false
311
+ }
312
+ const [low, high] = STARTUP_JITTER_MS
313
+ timers.startup = clock.setTimeout(() => safely("startup"), Math.round(low + random() * (high - low)))
314
+ timers.interval = clock.setInterval(() => safely("timer"), everyMs)
315
+ timers.heartbeat = clock.setInterval(beat, HEARTBEAT_MS)
316
+ return true
317
+ }
318
+
319
+ async function stop() {
320
+ stopped = true
321
+ clock.clearTimeout(timers.startup)
322
+ clock.clearTimeout(timers.catchUp)
323
+ clock.clearInterval(timers.interval)
324
+ clock.clearInterval(timers.heartbeat)
325
+ if (leader) lock.release()
326
+ leader = false
327
+ }
328
+
329
+ /** Wait for a promise up to `ms`; resolves `{ timedOut }` or `{ value }`. */
330
+ function within(promise, ms) {
331
+ return new Promise((resolve) => {
332
+ const timer = clock.setTimeout(() => resolve({ timedOut: true }), ms)
333
+ promise.then(
334
+ (value) => {
335
+ clock.clearTimeout(timer)
336
+ resolve({ value })
337
+ },
338
+ () => {
339
+ clock.clearTimeout(timer)
340
+ resolve({ value: null })
341
+ },
342
+ )
343
+ })
344
+ }
345
+
346
+ /**
347
+ * A request to collect now (`mem_collect`, `/mem-collect`): starts a run in
348
+ * the background and answers at once; with `wait`, waits up to 25 seconds
349
+ * and reports the counts, or the progress so far.
350
+ */
351
+ async function trigger({ source, wait = false, sessionID, from = "tool" } = {}) {
352
+ const only = String(source ?? "").trim()
353
+ if (only && !sourceEntry(only)) return { skipped: `${oneLine(only, 40)} is not a source Memory knows: ${knownSources().join(", ")}` }
354
+ const outcome = await begin(from, { only: only || undefined, sessionID })
355
+ if (!wait) return outcome
356
+ if (outcome.started || outcome.running) {
357
+ const run = active
358
+ if (!run) return { ...outcome, done: true, run: last }
359
+ const waited = await within(run.promise, waitMs)
360
+ if (waited.timedOut) return { ...outcome, waited: true, done: false, progress: run.results.map(({ done, ...result }) => ({ ...result, finished: done })) }
361
+ return { ...outcome, done: true, run: waited.value ?? last }
362
+ }
363
+ if (outcome.forwarded) {
364
+ const asked = clock.now()
365
+ const deadline = asked + waitMs
366
+ while (clock.now() < deadline) {
367
+ await new Promise((resolve) => clock.setTimeout(resolve, 1_000))
368
+ const status = readStatus()
369
+ if (status?.ended && Date.parse(status.started) >= asked - 1_000) return { ...outcome, done: true, run: status }
370
+ }
371
+ return { ...outcome, waited: true, done: false }
372
+ }
373
+ return outcome
374
+ }
375
+
376
+ /** Lines for `mem_spaces` health: who collects, the last run, and each source's counts and errors. */
377
+ function describe() {
378
+ const lines = []
379
+ let holder = null
380
+ try {
381
+ holder = lock.holder()
382
+ } catch {
383
+ holder = null
384
+ }
385
+ const mode = config.collect ? `on, every ${everyMs / 60_000} minutes while OpenCode runs` : "timer off (collect: false); mem_collect and /mem-collect still collect on request"
386
+ const who = !holder || lock.isStale(holder) ? "no process holds collector.lock now" : holder.id === lock.id ? "this process collects (it holds collector.lock)" : holderText(holder)
387
+ lines.push(`collector: ${mode}; ${who}`)
388
+ if (collector.scheduled) lines.push("collector: the host also runs the memory-collect schedule")
389
+ if (last?.state === "skipped") lines.push(`collector: last attempt ${oneLine(last.at ?? "", 40)} (${oneLine(last.trigger ?? "?", 20)}) skipped: ${oneLine(last.reason ?? "", 200)}`)
390
+ const status = active ? { state: "running", trigger: active.trigger, started: new Date(active.started).toISOString(), sources: active.results } : (readStatus() ?? (last?.state === "skipped" ? null : last))
391
+ if (!status) {
392
+ if (last?.state !== "skipped") lines.push("collector: no run yet")
393
+ return lines.join("\n")
394
+ }
395
+ const when = status.state === "running" ? `running since ${oneLine(status.started ?? "", 40)}` : `last run ${oneLine(status.ended ?? status.started ?? "", 40)}`
396
+ lines.push(`collector: ${when} (${oneLine(status.trigger ?? "?", 20)}${status.pid ? `, pid ${status.pid}` : ""})${status.state === "failed" ? ` failed: ${oneLine(status.error ?? "", 200)}` : ""}${status.none ? ": no source is enabled and confirmed" : ""}`)
397
+ for (const result of Array.isArray(status.sources) ? status.sources : []) lines.push(`- ${describeResult(result)}`)
398
+ return lines.join("\n")
399
+ }
400
+
401
+ return {
402
+ // The core's surface, which mem_spaces and mem_ingest use.
403
+ get scheduled() {
404
+ return collector.scheduled
405
+ },
406
+ get lister() {
407
+ return collector.lister
408
+ },
409
+ noteOwner: collector.noteOwner,
410
+ ownerFor: collector.ownerFor,
411
+ sync: collector.sync,
412
+ runOnce: collector.runOnce,
413
+ // The service's.
414
+ rpcSession,
415
+ start,
416
+ stop,
417
+ begin,
418
+ trigger,
419
+ describe,
420
+ get leader() {
421
+ return leader
422
+ },
423
+ get running() {
424
+ return Boolean(active)
425
+ },
426
+ get active() {
427
+ return active
428
+ },
429
+ get last() {
430
+ return last
431
+ },
432
+ lease: lock,
433
+ }
434
+ }
435
+
436
+ /** One source's line: its counts, and why it stopped. */
437
+ export function describeResult(result) {
438
+ const counts = `${Number(result.accepted) || 0} new, ${Number(result.duplicates) || 0} already had, ${Number(result.refused) || 0} refused, ${Number(result.pages) || 0} page(s)`
439
+ const name = `${oneLine(result.source ?? "?", 40)}:${oneLine(result.account ?? "?", 80)}`
440
+ return `${name}: ${result.error ? `stopped (${oneLine(result.error, 240)}); ` : ""}${counts}${result.more ? "; more waits for the next run" : ""}`
441
+ }