@joe-broadhead/opencode-mem 0.9.5 → 0.9.14

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 (63) hide show
  1. package/CHANGELOG.md +1408 -0
  2. package/README.md +120 -41
  3. package/docs/agent-instructions.md +17 -0
  4. package/docs/agent-protocol.md +28 -27
  5. package/docs/permissions.md +150 -0
  6. package/package.json +386 -17
  7. package/skills/mem.pages/SKILL.md +40 -16
  8. package/skills/mem.sharing/SKILL.md +39 -6
  9. package/skills/mem.sources/SKILL.md +41 -10
  10. package/skills/mem.usage/SKILL.md +37 -16
  11. package/src/backend/records.js +8 -0
  12. package/src/backend/v3.js +15 -10
  13. package/src/call-shapes.js +18 -25
  14. package/src/capture-pause.js +136 -0
  15. package/src/capture.js +7 -5
  16. package/src/collector-service.js +212 -35
  17. package/src/collector.js +187 -47
  18. package/src/commands.js +37 -0
  19. package/src/compaction.js +4 -2
  20. package/src/config.js +151 -1
  21. package/src/curation.js +6 -10
  22. package/src/events.js +144 -36
  23. package/src/forget-purge.js +377 -0
  24. package/src/forgotten.js +152 -0
  25. package/src/hooks.js +9 -4
  26. package/src/index.js +5 -3
  27. package/src/permissions.js +116 -38
  28. package/src/protocol.js +32 -11
  29. package/src/recall.js +13 -1
  30. package/src/records.js +4 -1
  31. package/src/runtime.js +202 -15
  32. package/src/shapes.js +63 -0
  33. package/src/sources.js +205 -12
  34. package/src/spaces.js +58 -1
  35. package/src/spool.js +442 -64
  36. package/src/stated.js +334 -0
  37. package/src/storable.js +477 -0
  38. package/src/tools/aliases.js +36 -147
  39. package/src/tools/commitments.js +79 -13
  40. package/src/tools/held-write.js +5 -1
  41. package/src/tools/index.js +25 -43
  42. package/src/tools/ingest.js +33 -128
  43. package/src/tools/memory.js +525 -911
  44. package/src/tools/page-sections.js +147 -0
  45. package/src/tools/page.js +314 -82
  46. package/src/tools/recall-browse.js +173 -0
  47. package/src/tools/recall.js +36 -8
  48. package/src/tools/records-kit.js +2 -1
  49. package/src/tools/share.js +494 -131
  50. package/src/tools/shared.js +97 -19
  51. package/src/tools/spaces.js +194 -101
  52. package/src/tools/status.js +31 -3
  53. package/src/tools/wiki.js +5 -13
  54. package/src/util.js +10 -59
  55. package/src/views/contracts.js +258 -20
  56. package/src/views/overdue.js +1 -1
  57. package/src/views/profile.js +2 -3
  58. package/src/views/receipt.js +81 -0
  59. package/src/views/records-reads.js +545 -25
  60. package/src/views/rpc.js +41 -3
  61. package/views/memory.html +16 -3
  62. package/views/remembered.html +130 -0
  63. package/src/erase.js +0 -36
package/src/collector.js CHANGED
@@ -1,5 +1,6 @@
1
1
  import { errorMessage, isPlainObject, oneLine } from "./util.js"
2
- import { contractRefusal, rpcDefinition, sourceEntry } from "./sources.js"
2
+ import { createHash } from "node:crypto"
3
+ import { ACCOUNT_NAME, DEFAULT_EVERY_MINUTES, SOURCE_REGISTRY, contractRefusal, rpcDefinition, sourceAllowRules, sourceEntry } from "./sources.js"
3
4
 
4
5
  /**
5
6
  * The memory collector (docs/design/memory-v1-contracts.md §4.4, §4.5).
@@ -17,9 +18,16 @@ import { contractRefusal, rpcDefinition, sourceEntry } from "./sources.js"
17
18
  * OpenCode 2.2.5 gives plugins no schedule API (a plugin's `Context` has no
18
19
  * schedule domain; `experimental.schedule.*` is on the host's SDK client
19
20
  * only), so this is how plain OpenCode collects, and Jelly while awake.
20
- * - **A host schedule** (`collectCheckCode`): the Code Mode check a host that
21
- * offers a schedule writes, calling `tools.<namespace>.events_list`. Jelly
22
- * instead declares a routine that calls `tools.mem.collect` (`jelly.routines`).
21
+ * - **Jelly** declares a routine that calls `tools.mem.collect`
22
+ * (`jelly.routines`), which runs the same in-plugin collection.
23
+ *
24
+ * 0.9.7 (audit runtime #8): the host-schedule path is gone. It ran every
25
+ * source, on any account, in one broad session (`ses_mem_collect`), which
26
+ * would undo the per-binding sessions. No OpenCode release up to 2.2.6 gives a
27
+ * plugin `ctx.experimental.schedule` (its `experimental` holds `terminal`,
28
+ * `generate` and `artifact`), so nothing reached it; it is removed so a host
29
+ * that adds the API does not reach it either. `collectCheckCode` and
30
+ * `createCollector({scheduler})` stay as pure units; nothing wires a scheduler.
23
31
  *
24
32
  * Every `events_list` answer must carry `source` and `account` (§4.5); one
25
33
  * without them is refused with the release its plugin needs, and the binding
@@ -35,7 +43,7 @@ export const PAGES_PER_SOURCE = 5
35
43
  export const PAGE_LIMIT = 200
36
44
  /** The account a binding without one uses. */
37
45
  export const DEFAULT_ACCOUNT = "default"
38
- /** The reserved session the collector's RPC calls and a host schedule run in. */
46
+ /** The prefix of the collector's reserved sessions: each binding's is `ses_mem_collect_<source>_<hash>`. */
39
47
  export const COLLECT_SESSION = "ses_mem_collect"
40
48
  /**
41
49
  * The engine sends a schedule's prompt only after its check fails three times
@@ -43,22 +51,65 @@ export const COLLECT_SESSION = "ses_mem_collect"
43
51
  */
44
52
  export const COLLECT_FAILURE_PROMPT =
45
53
  "The memory-collect schedule's check failed repeatedly, so the engine paused it. Reply with the single word: paused."
54
+ const BASE_RULES = [
55
+ { action: "*", resource: "*", effect: "deny" },
56
+ { action: "execute", resource: "*", effect: "allow" },
57
+ ]
58
+
59
+ const freezeRules = (rules) => Object.freeze(rules.map((rule) => Object.freeze({ ...rule })))
60
+
46
61
  /**
47
- * The collector session's own rules: only Code Mode and the sources'
48
- * `events_list`, so neither an RPC call nor a failure prompt's turn can do
49
- * anything else there.
62
+ * The collector sessions' rules: deny everything, then allow Code Mode and
63
+ * exactly what the registry says each source's `events_list` asserts
64
+ * (`sourceAllowRules`), never a generic `<ns>.read`.
65
+ *
66
+ * `collectSessionRules({source, account})`: one binding's session, which the
67
+ * in-plugin collector and a bind's probe both use. It allows the source's
68
+ * events action, the exact inner reads its events_list asserts (OpenCode
69
+ * checks each against this session: S0, 0.9.11), for gws the Gmail operations
70
+ * of its EVENT_READS on the binding's own account, and for github the four
71
+ * `github_api` GETs its events_list makes. There is no session for every
72
+ * source at once (0.9.7).
50
73
  */
51
- export const COLLECT_SESSION_RULES = Object.freeze([
52
- Object.freeze({ action: "*", resource: "*", effect: "deny" }),
53
- Object.freeze({ action: "execute", resource: "*", effect: "allow" }),
54
- Object.freeze({ action: "mem_cursor", resource: "*", effect: "allow" }),
55
- Object.freeze({ action: "mem_ingest", resource: "*", effect: "allow" }),
56
- Object.freeze({ action: "*_events_list", resource: "*", effect: "allow" }),
57
- ])
74
+ export function collectSessionRules({ source, account }) {
75
+ const entry = sourceEntry(source)
76
+ return freezeRules([...BASE_RULES, ...(entry ? sourceAllowRules(entry, account || DEFAULT_ACCOUNT) : [])])
77
+ }
78
+
79
+ /**
80
+ * The reserved session of one binding. Its id comes from the binding (source
81
+ * and account), not from its rules: when the registry changes the rules, the
82
+ * same session is updated to them (`rulesHash` in its metadata).
83
+ */
84
+ export function collectSessionId({ source, account }) {
85
+ const hash = createHash("sha256").update(`${source}\u0000${account || DEFAULT_ACCOUNT}`).digest("hex").slice(0, 12)
86
+ return `${COLLECT_SESSION}_${source}_${hash}`
87
+ }
88
+
89
+ /** A short hash of a session's rules, kept in its metadata so a stale session is noticed and updated. */
90
+ export function rulesHash(rules) {
91
+ const canonical = JSON.stringify(rules.map(({ action, resource, effect }) => [action, resource, effect]))
92
+ return createHash("sha256").update(canonical).digest("hex").slice(0, 16)
93
+ }
94
+
95
+ /** Match OpenCode's whole-value * and ? permission wildcards. */
96
+ function wildcard(pattern, value) {
97
+ const expression = String(pattern).replace(/[.+^${}()|[\]\\]/g, "\\$&").replaceAll("*", ".*").replaceAll("?", ".")
98
+ return new RegExp(`^${expression}$`).test(String(value))
99
+ }
100
+
101
+ /**
102
+ * The effect a session's rules give an action on a resource: the last
103
+ * matching rule wins, as in OpenCode's permission evaluation.
104
+ */
105
+ export function sessionEffect(action, resource = "*", rules = []) {
106
+ if (Array.isArray(resource)) return sessionEffect(action, "*", resource)
107
+ if (!Array.isArray(rules) || rules.length === 0) return "deny"
108
+ return rules.findLast((rule) => wildcard(rule.action, action) && wildcard(rule.resource, resource))?.effect ?? "ask"
109
+ }
58
110
 
59
111
  /** A source name is a lowercase identifier; only registered sources are collected. */
60
112
  const SOURCE_NAME = /^[a-z][a-z0-9_-]{0,63}$/
61
- const ACCOUNT_NAME = /^[A-Za-z0-9][A-Za-z0-9_.@+-]{0,127}$/
62
113
  const IDENTIFIER = /^[a-zA-Z][a-zA-Z0-9_]*$/
63
114
 
64
115
  export function isSourceName(value) {
@@ -99,12 +150,22 @@ export function collectableSources(sources, { only } = {}) {
99
150
  }
100
151
 
101
152
  /** The input every `events_list` call to a binding sends: the page, its account, and the registry's input. */
153
+ /**
154
+ * The account an events_list call names: a named binding's, and for a source
155
+ * whose reads are scoped by account (`namesAccount`, gws) "default" too, so
156
+ * the plugin reads exactly the account the session's rules allow.
157
+ */
158
+ function accountInput(entry, account) {
159
+ const named = account || DEFAULT_ACCOUNT
160
+ return named !== DEFAULT_ACCOUNT || entry?.namesAccount ? { account: named } : {}
161
+ }
162
+
102
163
  export function listInput(binding, cursor) {
103
164
  const entry = sourceEntry(binding.source)
104
165
  return {
105
166
  ...(cursor ? { cursor } : {}),
106
167
  limit: PAGE_LIMIT,
107
- ...(binding.account && binding.account !== DEFAULT_ACCOUNT ? { account: binding.account } : {}),
168
+ ...accountInput(entry, binding.account),
108
169
  ...(entry?.input ?? {}),
109
170
  }
110
171
  }
@@ -160,33 +221,6 @@ export function collectCheckCode(sources) {
160
221
  ].join("\n")
161
222
  }
162
223
 
163
- /**
164
- * The host's schedule API as the collector uses it, or null when a plugin
165
- * cannot reach one. OpenCode 2.2.5 gives plugins none, so this returns null
166
- * there. A host that hands plugins the SDK client's shape
167
- * (`experimental.schedule.{list,create,delete}`) is used as is, in the
168
- * reserved collector session.
169
- */
170
- export function hostScheduler(ctx, ensureSession) {
171
- const api = ctx?.experimental?.schedule
172
- if (!api || typeof api.create !== "function" || typeof api.list !== "function" || typeof api.delete !== "function") return null
173
- if (typeof ensureSession !== "function") return null
174
- return {
175
- async list() {
176
- const sessionID = await ensureSession()
177
- const rows = await api.list({ sessionID })
178
- return Array.isArray(rows) ? rows : []
179
- },
180
- async create({ name, cron, code, prompt }) {
181
- const sessionID = await ensureSession()
182
- return api.create({ sessionID, name, when: { cron }, if: { code }, prompt })
183
- },
184
- async remove(id) {
185
- await api.delete({ scheduleID: id })
186
- },
187
- }
188
- }
189
-
190
224
  function codeOf(row) {
191
225
  return typeof row?.if?.code === "string" ? row.if.code : typeof row?.check?.code === "string" ? row.check.code : ""
192
226
  }
@@ -212,6 +246,8 @@ export class SourceContractError extends Error {
212
246
  */
213
247
  export function readEventsAnswer(value, entry) {
214
248
  let answer = value
249
+ // A wrapper's text beside its output: a source's own words, such as Slack's "No Slack channel is enabled".
250
+ const said = isPlainObject(answer) && isPlainObject(answer.output) && typeof (answer.content ?? answer.text) === "string" ? String(answer.content ?? answer.text) : ""
215
251
  if (isPlainObject(answer) && !Array.isArray(answer.events) && isPlainObject(answer.output)) answer = answer.output
216
252
  if (isPlainObject(answer) && !Array.isArray(answer.events) && typeof (answer.content ?? answer.text) === "string") answer = answer.content ?? answer.text
217
253
  if (typeof answer === "string") {
@@ -234,7 +270,55 @@ export function readEventsAnswer(value, entry) {
234
270
  events: answer.events,
235
271
  cursor: typeof answer.cursor === "string" ? answer.cursor : "",
236
272
  more: answer.more === true,
273
+ setup: setupNote(answer, said),
274
+ }
275
+ }
276
+
277
+ const SETUP_WORDS = /\b(?:is|are) (?:not )?(?:enabled|configured|set)\b|\bset the plugin option\b|\bsign in\b|\bnot configured\b/i
278
+
279
+ /**
280
+ * The source's own sentence for setup it still needs, or null: the contract's
281
+ * `setup` field (§4.5), else a wrapper's text when nothing came back and it
282
+ * reads as a setup step (Slack 0.0.8 says "No Slack channel is enabled for
283
+ * events_list: set the plugin option events.channels …" only in its text).
284
+ */
285
+ export function setupNote(answer, said = "") {
286
+ const own = typeof answer?.setup === "string" ? answer.setup.trim() : ""
287
+ if (own) return oneLine(own, 400)
288
+ if (said && Array.isArray(answer?.events) && answer.events.length === 0 && SETUP_WORDS.test(said)) return oneLine(said.split(/(?<=\.)\s/)[0], 400)
289
+ return null
290
+ }
291
+
292
+ /** The input of the owner-only call a bind request makes (§4.5): `limit: 0` where the plugin keeps it, else `limit: 1`. */
293
+ export function probeInput(entry, account) {
294
+ return { limit: entry.ownerProbe === "limit0" ? 0 : 1, ...accountInput(entry, account) }
295
+ }
296
+
297
+ /** How often the timer collects a source, in milliseconds. */
298
+ export function cadenceMs(source) {
299
+ return Math.max(5, Number(sourceEntry(source)?.everyMinutes) || DEFAULT_EVERY_MINUTES) * 60_000
300
+ }
301
+
302
+ /**
303
+ * Bind requests the collector answers this run: asked for by the person
304
+ * (state `requested`, or `failed` once its `retry_at` has passed), of a
305
+ * registered source. A request that needs attention (3 failures) is not
306
+ * asked again until the person presses Bind… again. Nothing else is ever probed.
307
+ */
308
+ export function requestedSources(requests, { only, now = Date.now() } = {}) {
309
+ const out = []
310
+ for (const entry of Array.isArray(requests) ? requests : []) {
311
+ if (!isPlainObject(entry)) continue
312
+ if (entry.state !== "requested" && entry.state !== "failed") continue
313
+ // A failed request waits out its back-off (1 h, then 6 h); "attention" (3 failures) waits for Bind… again.
314
+ if (entry.state === "failed" && entry.retry_at && Date.parse(entry.retry_at) > now) continue
315
+ const source = String(entry.source ?? "")
316
+ const account = String(entry.account ?? "") || DEFAULT_ACCOUNT
317
+ if (!sourceEntry(source) || !isAccountName(account)) continue
318
+ if (only && source !== only) continue
319
+ out.push({ source, account })
237
320
  }
321
+ return out
238
322
  }
239
323
 
240
324
  /**
@@ -259,7 +343,7 @@ export function hostSourceLister(ctx) {
259
343
  * The collector's core: schedule upkeep, one collection, and the owners a
260
344
  * refused ingest reported.
261
345
  *
262
- * @param {{ scheduler?: ReturnType<typeof hostScheduler>, lister?: ReturnType<typeof hostSourceLister>, log?: any }} [input]
346
+ * @param {{ scheduler?: { list(): Promise<any[]>, create(input: any): Promise<any>, remove(id: string): Promise<void> } | null, lister?: ReturnType<typeof hostSourceLister>, log?: any }} [input]
263
347
  */
264
348
  export function createCollector({ scheduler = null, lister = null, log } = {}) {
265
349
  const reported = new Map()
@@ -322,10 +406,15 @@ export function createCollector({ scheduler = null, lister = null, log } = {}) {
322
406
  * ingest: (input: { source: string, account: string, owner: any, events: unknown[], cursor: string }) => Promise<{ accepted?: number, duplicates?: number, refused?: number, cursor_saved?: boolean }>,
323
407
  * sessionID?: string,
324
408
  * results?: object[],
409
+ * due?: (binding: { source: string, account: string }) => boolean,
325
410
  * }} input
326
411
  */
327
- async function runOnce({ sources, only, cursor, ingest, sessionID, results = [] }) {
412
+ async function runOnce({ sources, only, cursor, ingest, sessionID, results = [], due = () => true }) {
328
413
  for (const binding of collectableSources(sources, { only })) {
414
+ if (!due(binding)) {
415
+ results.push({ ...binding, pages: 0, accepted: 0, duplicates: 0, refused: 0, more: false, notDue: true, everyMinutes: cadenceMs(binding.source) / 60_000, done: true })
416
+ continue
417
+ }
329
418
  const result = { ...binding, pages: 0, accepted: 0, duplicates: 0, refused: 0, more: false, done: false }
330
419
  results.push(result)
331
420
  try {
@@ -333,6 +422,7 @@ export function createCollector({ scheduler = null, lister = null, log } = {}) {
333
422
  result.error = "this host gives plugins no way to call another plugin's events_list"
334
423
  continue
335
424
  }
425
+ const session = typeof sessionID === "function" ? await sessionID(binding) : sessionID
336
426
  const state = await cursor(binding)
337
427
  if (!state || state.enabled === false || (state.status && state.status !== "confirmed")) {
338
428
  result.error = `the binding is ${state?.enabled === false ? "disabled" : state?.status || "unknown"}`
@@ -340,12 +430,13 @@ export function createCollector({ scheduler = null, lister = null, log } = {}) {
340
430
  }
341
431
  let at = typeof state.cursor === "string" && state.cursor ? state.cursor : undefined
342
432
  for (let page = 0; page < PAGES_PER_SOURCE; page += 1) {
343
- const answer = await lister(binding.source, listInput(binding, at), sessionID)
433
+ const answer = await lister(binding.source, listInput(binding, at), session)
344
434
  if (!answer || !answer.cursor) {
345
435
  result.error = "the source's events_list gave no events and cursor"
346
436
  break
347
437
  }
348
438
  // The answer's own source and account (§4.5): the binding they name decides.
439
+ if (answer.setup) result.setup = answer.setup
349
440
  const saved = await ingest({ source: answer.source, account: answer.account, owner: answer.owner, events: answer.events, cursor: answer.cursor })
350
441
  result.pages += 1
351
442
  result.accepted += Number(saved?.accepted) || 0
@@ -368,6 +459,54 @@ export function createCollector({ scheduler = null, lister = null, log } = {}) {
368
459
  return results
369
460
  }
370
461
 
462
+ /**
463
+ * Answer the person's bind requests: for each requested source only, ask
464
+ * its `events_list` for the signed-in account (`probeInput`; any event it
465
+ * returns is dropped, never stored) and report it, or the source's own
466
+ * reason it could not, with `report`. Nothing is bound here: the person
467
+ * confirms the reported account.
468
+ *
469
+ * @param {{ requests: unknown, only?: string, sessionID?: string, report: (input: object) => Promise<unknown>, probes?: object[] }} input
470
+ */
471
+ async function probeRequests({ requests, only, now = Date.now(), sessionID, report, probes = [] }) {
472
+ for (const asked of requestedSources(requests, { only, now })) {
473
+ const probe = { ...asked, reported: false }
474
+ probes.push(probe)
475
+ const entry = sourceEntry(asked.source)
476
+ // The binding's own session first: when it cannot be made, nothing is read and
477
+ // nothing is reported (it is not the source's failure, so no back-off either).
478
+ let session
479
+ try {
480
+ session = typeof sessionID === "function" ? await sessionID(asked) : sessionID
481
+ } catch (error) {
482
+ probe.error = oneLine(errorMessage(error), 300)
483
+ continue
484
+ }
485
+ let body
486
+ try {
487
+ if (!lister) throw new Error("this host gives plugins no way to call another plugin's events_list")
488
+ const answer = await lister(asked.source, probeInput(entry, asked.account), session)
489
+ if (answer?.owner?.id) {
490
+ const owner = { id: oneLine(answer.owner.id, 300), label: oneLine(answer.owner.label ?? answer.owner.email ?? answer.owner.id, 300) }
491
+ body = { source: asked.source, account: asked.account, owner, reported_account: answer.account, ...(answer.setup || entry.setupOptions ? { note: answer.setup || entry.setupOptions } : {}) }
492
+ probe.owner = owner
493
+ } else {
494
+ body = { source: asked.source, account: asked.account, note: answer?.setup || `${entry.package}'s events_list named no signed-in account; sign in to it in its own plugin.` }
495
+ }
496
+ } catch (error) {
497
+ body = { source: asked.source, account: asked.account, note: oneLine(errorMessage(error), 400) }
498
+ }
499
+ probe.note = body.note ?? null
500
+ try {
501
+ await report(body)
502
+ probe.reported = true
503
+ } catch (error) {
504
+ probe.error = oneLine(errorMessage(error), 300)
505
+ }
506
+ }
507
+ return probes
508
+ }
509
+
371
510
  return {
372
511
  get scheduled() {
373
512
  return Boolean(scheduler)
@@ -377,5 +516,6 @@ export function createCollector({ scheduler = null, lister = null, log } = {}) {
377
516
  ownerFor,
378
517
  sync,
379
518
  runOnce,
519
+ probeRequests,
380
520
  }
381
521
  }
package/src/commands.js CHANGED
@@ -95,6 +95,7 @@ export async function registerCommands(ctx, runtime) {
95
95
  }
96
96
  if (status.collection) lines.push(`- collection: ${oneLine(status.collection, 120)}`)
97
97
  lines.push(
98
+ `- capture: ${status.capture ?? "?"}`,
98
99
  `- credential: ${status.credential}`,
99
100
  `- L0 conversations: ${status.layers?.l0 ?? "?"}`,
100
101
  `- L1 atoms: ${status.layers?.l1 ?? "?"}`,
@@ -144,6 +145,42 @@ export async function registerCommands(ctx, runtime) {
144
145
  },
145
146
  })
146
147
 
148
+ // Pause and resume touch only this machine's state, so they work even
149
+ // while memory is unavailable: nothing is sent.
150
+ target.add({
151
+ name: "mem-pause",
152
+ description: "Pause memory capture for this session: no turn, compaction summary or checkpoint is kept until /mem-resume",
153
+ execute: async ({ sessionID } = {}) => {
154
+ if (!sessionID) return
155
+ if (!runtime.config.capture) {
156
+ await reply(sessionID, "capture is already off for this install (capture: false); nothing from this session is kept automatically.")
157
+ return
158
+ }
159
+ const since = runtime.pauseCapture(sessionID)
160
+ await reply(
161
+ sessionID,
162
+ `memory capture paused for this session since ${since}: no turn, compaction summary or checkpoint is kept. mem_remember and mem_page still store what you ask for. /mem-resume captures new turns again; this session gets no checkpoint or compaction summary, because they cover the whole transcript.`,
163
+ )
164
+ },
165
+ })
166
+
167
+ target.add({
168
+ name: "mem-resume",
169
+ description: "Resume memory capture for this session after /mem-pause",
170
+ execute: async ({ sessionID } = {}) => {
171
+ if (!sessionID) return
172
+ const resumed = runtime.resumeCapture(sessionID)
173
+ await reply(
174
+ sessionID,
175
+ resumed === "unreadable"
176
+ ? "memory capture stays paused: the pause state file (capture-paused.json in the state directory) is unreadable, so every session counts as paused. Fix or remove it, then /mem-resume."
177
+ : resumed
178
+ ? "memory capture resumed for this session: new turns are captured again. Turns from the pause are never captured, and this session gets no checkpoint or compaction summary."
179
+ : "memory capture was not paused for this session; nothing changed.",
180
+ )
181
+ },
182
+ })
183
+
147
184
  editor.add({
148
185
  name: "mem-why",
149
186
  description: "Show the exact memory block pinned into this session (dashboard, Due list, persona)",
package/src/compaction.js CHANGED
@@ -1,4 +1,5 @@
1
1
  import os from "node:os"
2
+ import { storable } from "./storable.js"
2
3
  import { FENCE_TAGS, clampText, neutralizeFenceClosers, nowIso, oneLine, redactSecrets, shortHash } from "./util.js"
3
4
 
4
5
  /**
@@ -32,12 +33,13 @@ const DECISION_PATTERN =
32
33
  const OPEN_PATTERN =
33
34
  /\b(next|todos?|open questions?|pending|blocked|follow[- ]?ups?|remaining|still need|unresolved|awaiting)\b/i
34
35
 
35
- // The redaction patterns live in util.js so capture and the logger share them.
36
+ // Kept for callers that import it from here; the checkpoint itself uses storable.
36
37
  export { redactSecrets }
37
38
 
39
+ /** As every automatic write (src/storable.js): secret lines withheld, emails and paths masked. */
38
40
  function sanitize(value, max) {
39
41
  if (typeof value !== "string" && typeof value !== "number") return ""
40
- return clampText(neutralizeFenceClosers(redactSecrets(value), FENCE_TAGS), max).trim()
42
+ return clampText(neutralizeFenceClosers(storable(String(value), "checkpoint").text, FENCE_TAGS), max).trim()
41
43
  }
42
44
 
43
45
  function field(value, max) {
package/src/config.js CHANGED
@@ -1,6 +1,8 @@
1
+ import fs from "node:fs"
1
2
  import os from "node:os"
2
3
  import path from "node:path"
3
4
  import { isPlainObject, toPositiveInt } from "./util.js"
5
+ import { ASK_ACTIONS } from "./permissions.js"
4
6
 
5
7
  /** The bundled simulator: the core URL of local direct mode. */
6
8
  export const LOCAL_BASE_URL = "http://127.0.0.1:8420"
@@ -45,6 +47,16 @@ const DEFAULTS = Object.freeze({
45
47
  tools: true,
46
48
  /** Opt-in only for hosts that expose the held-write Inbox decisions. */
47
49
  heldTeamWrites: false,
50
+ /**
51
+ * Default asks the person turned off: approval action names (ASK_ACTIONS in
52
+ * src/permissions.js), as a list or one comma-separated string, such as
53
+ * "memory.forget, page.delete". Each one then runs without an assertion. In
54
+ * plain OpenCode a `permission` rule does the same; in Jelly a person's
55
+ * Allow cannot lift a declared ask (D77), so this is the way to loosen one.
56
+ * A held team write still waits in the Inbox. Unknown names are ignored,
57
+ * with a warning.
58
+ */
59
+ skipAsks: [],
48
60
  skills: true,
49
61
  commands: true,
50
62
  spool: true,
@@ -62,6 +74,12 @@ const DEFAULTS = Object.freeze({
62
74
  recallChars: 6000,
63
75
  timeoutMs: 2000,
64
76
  recordsWriteTimeoutMs: 10000,
77
+ /**
78
+ * Timeout of one turn capture on the gateway's `/v1/capture`. Longer than a
79
+ * read's: a capture that times out is sent again, and only the gateway's
80
+ * receipt keeps the retry from storing it twice (docs/capture-delivery.md).
81
+ */
82
+ captureTimeoutMs: 10000,
65
83
  /**
66
84
  * Retries of one keyed records write after an unknown outcome, 0 to 5
67
85
  * (docs/design/records-idempotency.md). Sent only to a records service that
@@ -101,6 +119,7 @@ const ENV_MAP = {
101
119
  timeZone: "MEMORY_TIME_ZONE",
102
120
  collect: "MEMORY_COLLECT",
103
121
  recordsWriteTimeoutMs: "MEMORY_RECORDS_WRITE_TIMEOUT_MS",
122
+ captureTimeoutMs: "MEMORY_CAPTURE_TIMEOUT_MS",
104
123
  recordsWriteRetries: "MEMORY_RECORDS_WRITE_RETRIES",
105
124
  }
106
125
 
@@ -119,7 +138,7 @@ const BOOLEAN_KEYS = [
119
138
  "debug",
120
139
  ]
121
140
 
122
- const NUMBER_KEYS = ["bootstrapChars", "recallLimit", "recallChars", "timeoutMs", "recordsWriteTimeoutMs", "retries", "collectEveryMinutes"]
141
+ const NUMBER_KEYS = ["bootstrapChars", "recallLimit", "recallChars", "timeoutMs", "recordsWriteTimeoutMs", "captureTimeoutMs", "retries", "collectEveryMinutes"]
123
142
 
124
143
  /** An IANA zone this runtime knows, or "". */
125
144
  function validTimeZone(value) {
@@ -155,6 +174,125 @@ export function createClock(config, started = Date.now()) {
155
174
  * @param {Record<string, unknown>} [options]
156
175
  * @param {Record<string, string | undefined>} [env]
157
176
  */
177
+ /** `skipAsks` as given: a list, or one string separated by commas or spaces. */
178
+ function parseAskList(value) {
179
+ const items = Array.isArray(value) ? value : typeof value === "string" ? value.split(/[\s,]+/) : []
180
+ return [...new Set(items.map((item) => String(item ?? "").trim()).filter(Boolean))]
181
+ }
182
+
183
+ /** The known action names of a `skipAsks` value, and the others. */
184
+ function splitAsks(value) {
185
+ const named = parseAskList(value)
186
+ return { names: Object.freeze(named.filter((name) => ASK_ACTIONS.includes(name))), unknown: Object.freeze(named.filter((name) => !ASK_ACTIONS.includes(name))) }
187
+ }
188
+
189
+ /** JSON with comments and trailing commas (opencode.jsonc), parsed; strings keep their slashes. */
190
+ function parseJsonc(text) {
191
+ let out = ""
192
+ let inString = false
193
+ for (let i = 0; i < text.length; i += 1) {
194
+ const char = text[i]
195
+ if (inString) {
196
+ out += char
197
+ if (char === "\\") {
198
+ out += text[i + 1] ?? ""
199
+ i += 1
200
+ } else if (char === '"') inString = false
201
+ continue
202
+ }
203
+ if (char === '"') {
204
+ inString = true
205
+ out += char
206
+ } else if (char === "/" && text[i + 1] === "/") {
207
+ while (i < text.length && text[i] !== "\n") i += 1
208
+ out += "\n"
209
+ } else if (char === "/" && text[i + 1] === "*") {
210
+ i += 2
211
+ while (i < text.length && !(text[i] === "*" && text[i + 1] === "/")) i += 1
212
+ i += 1
213
+ } else out += char
214
+ }
215
+ return JSON.parse(out.replace(/,(\s*[}\]])/g, "$1"))
216
+ }
217
+
218
+ /** True when a config's plugin spec names this package: its name, a version or tag of it, or a directory holding it. */
219
+ function namesThisPlugin(spec, configDir, packageName) {
220
+ const value = String(spec ?? "").trim()
221
+ if (!value) return false
222
+ if (value === packageName || value.startsWith(`${packageName}@`)) return true
223
+ if (/^(?:github:)?joe-broadhead\/opencode-mem(?:#.*)?$/.test(value)) return true
224
+ if (!/^(?:\/|\.|~)/.test(value)) return false
225
+ try {
226
+ const dir = path.resolve(configDir, value.replace(/^~(?=\/)/, os.homedir()))
227
+ return JSON.parse(fs.readFileSync(path.join(dir, "package.json"), "utf8"))?.name === packageName
228
+ } catch {
229
+ return false
230
+ }
231
+ }
232
+
233
+ /**
234
+ * `skipAsks` from the user-level OpenCode config only:
235
+ * `$XDG_CONFIG_HOME/opencode/opencode.json(c)`, else `~/.config/opencode/`.
236
+ * OpenCode merges a repository's own opencode.json over it and adds its
237
+ * plugin entries, so a project file could otherwise turn asks off for anyone
238
+ * who opens the repository. Neither the environment nor OPENCODE_CONFIG is read.
239
+ */
240
+ export function userLevelSkipAsks(where = {}) {
241
+ const names = []
242
+ for (const options of userLevelOptions(where)) if (options.skipAsks !== undefined) names.push(...parseAskList(options.skipAsks))
243
+ return splitAsks(names)
244
+ }
245
+
246
+ /** The options of every entry naming this plugin in the user-level OpenCode config. */
247
+ function userLevelOptions({ env = process.env, home = os.homedir(), packageName = "@joe-broadhead/opencode-mem" } = {}) {
248
+ const dir = path.join(env.XDG_CONFIG_HOME || path.join(home, ".config"), "opencode")
249
+ const found = []
250
+ for (const file of ["opencode.json", "opencode.jsonc"]) {
251
+ let document
252
+ try {
253
+ document = parseJsonc(fs.readFileSync(path.join(dir, file), "utf8"))
254
+ } catch {
255
+ continue
256
+ }
257
+ const entries = [...(Array.isArray(document?.plugins) ? document.plugins : []), ...(Array.isArray(document?.plugin) ? document.plugin : [])]
258
+ for (const entry of entries) {
259
+ const spec = Array.isArray(entry) ? entry[0] : isPlainObject(entry) ? entry.package ?? entry.name : entry
260
+ const options = Array.isArray(entry) ? entry[1] : isPlainObject(entry) ? entry.options : undefined
261
+ if (isPlainObject(options) && namesThisPlugin(spec, dir, packageName)) found.push(options)
262
+ }
263
+ }
264
+ return found
265
+ }
266
+
267
+ /**
268
+ * Where `skipAsks` comes from (REVIEW-SMOOTH): inside Jelly, the person's
269
+ * "Run without asking" setting, which reaches the plugin as an option; else
270
+ * the user-level OpenCode config only. Read on every use, because Jelly's
271
+ * accessors may appear after setup.
272
+ *
273
+ * @param {any} config resolveConfig's answer
274
+ * @param {{ inJelly: () => boolean, user?: { names: readonly string[], unknown: readonly string[] } }} source
275
+ */
276
+ export function applySkipAsksSource(config, { inJelly, user = userLevelSkipAsks() }) {
277
+ const fromOptions = config.optionSkipAsks ?? Object.freeze([])
278
+ const optionUnknown = config.unknownSkipAsks ?? Object.freeze([])
279
+ const jelly = () => {
280
+ try {
281
+ return Boolean(inJelly?.())
282
+ } catch {
283
+ return false
284
+ }
285
+ }
286
+ Object.defineProperty(config, "skipAsks", { get: () => (jelly() ? fromOptions : user.names), enumerable: true, configurable: true })
287
+ Object.defineProperty(config, "unknownSkipAsks", { get: () => (jelly() ? optionUnknown : user.unknown), enumerable: false, configurable: true })
288
+ Object.defineProperty(config, "ignoredSkipAsks", {
289
+ get: () => (jelly() ? Object.freeze([]) : Object.freeze(fromOptions.filter((name) => !user.names.includes(name)))),
290
+ enumerable: false,
291
+ configurable: true,
292
+ })
293
+ return config
294
+ }
295
+
158
296
  export function resolveConfig(options = {}, env = process.env) {
159
297
  const input = isPlainObject(options) ? options : {}
160
298
  const backend = isPlainObject(input.backend) ? input.backend : {}
@@ -191,6 +329,15 @@ export function resolveConfig(options = {}, env = process.env) {
191
329
  merged.recordsWriteRetries = Number.isInteger(value) && value >= 0 ? Math.min(value, 5) : DEFAULTS.recordsWriteRetries
192
330
  }
193
331
  merged.collectEveryMinutes = Math.min(Math.max(merged.collectEveryMinutes, 5), 1440)
332
+ {
333
+ // What the plugin options say. Outside Jelly the plugin uses the
334
+ // user-level config's value instead (applySkipAsksSource), because a
335
+ // repository's own opencode.json can set plugin options too.
336
+ const split = splitAsks(merged.skipAsks)
337
+ merged.skipAsks = split.names
338
+ Object.defineProperty(merged, "optionSkipAsks", { value: split.names, enumerable: false, writable: true, configurable: true })
339
+ Object.defineProperty(merged, "unknownSkipAsks", { value: split.unknown, enumerable: false, writable: true, configurable: true })
340
+ }
194
341
 
195
342
  for (const key of ["baseURL", "controlURL", "knowledgeURL"]) {
196
343
  if (!merged[key]) continue
@@ -255,5 +402,8 @@ export function configWarnings(config, { credentialSource = config.token ? "opti
255
402
  warnings.push("compactionCheckpoint=false; no pre-compaction checkpoint is written to memory")
256
403
  if (config.captureSubagents)
257
404
  warnings.push("captureSubagents=true; subagent sessions are captured and pinned like primary sessions")
405
+ if (config.skipAsks?.length) warnings.push(`skipAsks=${config.skipAsks.join(",")}; these run without asking (a held team write still waits in the Inbox)`)
406
+ if (config.ignoredSkipAsks?.length) warnings.push(`skipAsks ${config.ignoredSkipAsks.join(", ")} ignored: outside Jelly it is read only from the user-level config (~/.config/opencode/opencode.json), never from a project's`)
407
+ if (config.unknownSkipAsks?.length) warnings.push(`skipAsks ignores ${config.unknownSkipAsks.join(", ")}: not one of ${ASK_ACTIONS.join(", ")}`)
258
408
  return warnings
259
409
  }
package/src/curation.js CHANGED
@@ -1,3 +1,5 @@
1
+ import { storable } from "./storable.js"
2
+
1
3
  /**
2
4
  * Curation guards.
3
5
  *
@@ -71,9 +73,6 @@ const INSTRUCTION = [
71
73
  /\b(?:when|if|once|after) you (?:read|see|recall|retrieve|load) (?:this|these)\b/i,
72
74
  ]
73
75
 
74
- const EMAIL = /[\w.+-]+@[\w-]+\.[\w.]{2,}/
75
- const LOCAL_PATH = /(?:^|\s)\/(?:Users|home|private\/var)\/[A-Za-z0-9._-]+\//
76
-
77
76
  /**
78
77
  * Upstream L1 types that are task descriptions rather than durable memory.
79
78
  * `work_task` atoms are what an imperative brief or a status turn extracts to:
@@ -87,7 +86,8 @@ const WITHHELD_TYPES = new Set(["work_task"])
87
86
  * Why a write must be refused, or "" when it may be stored.
88
87
  *
89
88
  * The order matters: status first because it is the largest bad class, then
90
- * instructions, then two shapes that are repo state rather than durable facts.
89
+ * instructions, then what `storable` refuses on a memory (owner decisions D3
90
+ * and D3': a secret, a person's email address or role address, a home path).
91
91
  *
92
92
  * @param {string} text
93
93
  * @returns {string}
@@ -101,12 +101,8 @@ export function writeRefusal(text) {
101
101
  if (isInstructionShaped(value)) {
102
102
  return "not stored: the content contains an instruction. Memory is a data channel and never carries commands."
103
103
  }
104
- if (EMAIL.test(value)) {
105
- return "not stored: an email address is personal data, not a durable fact. Keep the decision, not the address."
106
- }
107
- if (LOCAL_PATH.test(value)) {
108
- return "not stored: an absolute local path is repo state, not a fact. It is wrong on every other machine."
109
- }
104
+ const verdict = storable(value, "remember")
105
+ if (verdict.outcome === "refuse") return verdict.message
110
106
  return ""
111
107
  }
112
108