@joe-broadhead/opencode-mem 0.9.2 → 0.9.12

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 (64) hide show
  1. package/CHANGELOG.md +1605 -0
  2. package/README.md +135 -43
  3. package/docs/agent-protocol.md +29 -28
  4. package/docs/permissions.md +148 -0
  5. package/package.json +277 -16
  6. package/skills/mem.pages/SKILL.md +35 -16
  7. package/skills/mem.sharing/SKILL.md +39 -6
  8. package/skills/mem.sources/SKILL.md +41 -10
  9. package/skills/mem.usage/SKILL.md +47 -16
  10. package/src/backend/records.js +413 -50
  11. package/src/backend/v3.js +15 -10
  12. package/src/call-shapes.js +18 -25
  13. package/src/capture-pause.js +136 -0
  14. package/src/capture.js +7 -4
  15. package/src/collector-service.js +212 -35
  16. package/src/collector.js +186 -47
  17. package/src/commands.js +37 -0
  18. package/src/compaction.js +4 -2
  19. package/src/config.js +162 -1
  20. package/src/connect.js +353 -0
  21. package/src/copies.js +28 -3
  22. package/src/credentials.js +35 -7
  23. package/src/curation.js +33 -14
  24. package/src/events.js +144 -36
  25. package/src/forget-purge.js +377 -0
  26. package/src/forgotten.js +356 -0
  27. package/src/hooks.js +9 -4
  28. package/src/index.js +25 -6
  29. package/src/permissions.js +116 -38
  30. package/src/protocol.js +21 -11
  31. package/src/records.js +4 -1
  32. package/src/runtime.js +207 -16
  33. package/src/shapes.js +63 -0
  34. package/src/sources.js +183 -12
  35. package/src/spaces.js +58 -1
  36. package/src/spool.js +442 -64
  37. package/src/stated.js +334 -0
  38. package/src/storable.js +477 -0
  39. package/src/tools/aliases.js +36 -147
  40. package/src/tools/commitments.js +69 -12
  41. package/src/tools/held-write.js +9 -1
  42. package/src/tools/index.js +29 -44
  43. package/src/tools/ingest.js +33 -128
  44. package/src/tools/memory.js +594 -901
  45. package/src/tools/page-sections.js +147 -0
  46. package/src/tools/page.js +314 -82
  47. package/src/tools/recall-browse.js +173 -0
  48. package/src/tools/recall.js +79 -19
  49. package/src/tools/share.js +494 -131
  50. package/src/tools/shared.js +97 -19
  51. package/src/tools/spaces.js +215 -104
  52. package/src/tools/status.js +31 -3
  53. package/src/tools/wiki.js +5 -13
  54. package/src/util.js +10 -20
  55. package/src/views/contracts.js +137 -6
  56. package/src/views/overdue.js +125 -0
  57. package/src/views/profile.js +154 -0
  58. package/src/views/records-reads.js +132 -33
  59. package/src/views/rpc.js +63 -12
  60. package/src/views/shape.js +49 -0
  61. package/views/commitments.html +31 -4
  62. package/views/home.html +22 -3
  63. package/views/memory.html +126 -24
  64. package/src/erase.js +0 -36
@@ -1,7 +1,9 @@
1
1
  import { contextScopeLabel, scopeLabel, taskKey } from "../scope.js"
2
2
  import { errorMessage, oneLine } from "../util.js"
3
3
  import { isCoded } from "../errors.js"
4
- import { hasSharedWritePolicy } from "../permissions.js"
4
+ import { assertUnlessSkipped, hasSharedWritePolicy, skipsAsk } from "../permissions.js"
5
+ import { asVerifiedSession } from "../credentials.js"
6
+ import { holdTeamWrite } from "./held-write.js"
5
7
 
6
8
  /**
7
9
  * Roles that may write to a shared space. The plugin reads this from the
@@ -16,9 +18,39 @@ export const WHOLE_SPACE = "*"
16
18
  export const TASK_INPUT = Object.freeze({
17
19
  type: "string",
18
20
  description:
19
- 'Optional context, never a substitute for the required arguments: one line naming the work, not the topic ("fix the migration ordering"). Kept for the session: later calls and captured turns use it. "*" means the whole space for this call',
21
+ "Optional: one line naming the work, not the topic; kept for the session. \"*\": the whole space, this call only",
20
22
  })
21
23
 
24
+ /**
25
+ * The pages of the pinned block: the dashboard `index`, placed in the system
26
+ * prompt of every later session (src/bootstrap.js, src/records-store.js). The
27
+ * persona is the core's (L3) and no tool writes it.
28
+ */
29
+ export const PINNED_PAGES = Object.freeze(["index"])
30
+
31
+ /** True when a page path is placed in the pinned block. */
32
+ export function isPinnedPage(path) {
33
+ return PINNED_PAGES.includes(String(path ?? "").trim())
34
+ }
35
+
36
+ /**
37
+ * Who stated a write, as the host decides it (FABLE tools 1 and 6; slice 7
38
+ * review P1). The agent's `stated_by` argument is a claim. It is kept only on
39
+ * a held write, and the records store keeps it only when the person accepts
40
+ * that exact content in Memory's console, a browser session; an accept in the
41
+ * Jelly Inbox view (src/tools/held-write.js `decideProposal`) is a bearer and
42
+ * stores `agent` (records/src/model.js `mayStatePerson`). An ask that passed is not consent: a configured
43
+ * allow passes it with no prompt (`assertTeamWrite`). Everything else is the
44
+ * agent's.
45
+ *
46
+ * @param {unknown} claimed the caller's stated_by argument
47
+ * @param {{ held?: string } | null | undefined} gate gateWrite's answer
48
+ * @returns {"person" | "agent"}
49
+ */
50
+ export function hostProvenance(claimed, gate) {
51
+ return claimed === "person" && typeof gate?.held === "string" ? "person" : "agent"
52
+ }
53
+
22
54
  /** True when a control-plane role may write to a shared space. */
23
55
  export function canWriteShared(role) {
24
56
  return SHARED_WRITE_ROLES.includes(String(role ?? "").trim().toLowerCase())
@@ -48,7 +80,7 @@ export function createToolkit(ctx, runtime) {
48
80
  * means the active context. In local direct mode an explicit space is an error
49
81
  * rather than a silent no-op, because there is nothing that could resolve it.
50
82
  */
51
- async function resolveSpace(input, context, { bind = false } = {}) {
83
+ async function resolveSpace(input, context) {
52
84
  const requested = String(input?.space ?? "").trim()
53
85
  if (!control) {
54
86
  if (requested) return { error: "control plane not configured; set MEMORY_CONTROL_URL to select a space" }
@@ -57,10 +89,9 @@ export function createToolkit(ctx, runtime) {
57
89
  try {
58
90
  const resolved = await runtime.resolveContext({
59
91
  space: requested || undefined,
60
- // A read with an explicit space must not rebind the session. A read
61
- // without a space follows the session's existing binding. Only an
62
- // explicit write binds the session to the requested space.
63
- sessionID: requested ? (bind ? context?.sessionID : undefined) : context?.sessionID,
92
+ // An explicit space targets this call and never rebinds the session.
93
+ // Without one the call follows the session's binding.
94
+ sessionID: requested ? undefined : context?.sessionID,
64
95
  agent: context?.agent,
65
96
  })
66
97
  if (!resolved) return { error: "the control plane returned no space context" }
@@ -162,11 +193,8 @@ export function createToolkit(ctx, runtime) {
162
193
  let spaceContext
163
194
  try {
164
195
  if (requested) {
165
- spaceContext = await runtime.resolveContext({
166
- space: requested,
167
- sessionID: context?.sessionID,
168
- agent: context?.agent,
169
- })
196
+ // The write goes to the space it names; the session keeps its binding.
197
+ spaceContext = await runtime.resolveContext({ space: requested, agent: context?.agent })
170
198
  } else {
171
199
  // A shared default is not a selection. captureContext only returns a
172
200
  // shared space when the control plane reports a session binding.
@@ -220,9 +248,18 @@ export function createToolkit(ctx, runtime) {
220
248
  return { key, declared: true }
221
249
  }
222
250
 
251
+ /**
252
+ * The host's permission assertion. An action the person's `skipAsks` names
253
+ * runs without it only where the host's rules would ask; a deny still
254
+ * stands (src/permissions.js assertUnlessSkipped).
255
+ */
256
+ async function assert(request) {
257
+ await assertUnlessSkipped(ctx, config, request)
258
+ }
259
+
223
260
  /** An assertion enforces host policy, but does not prove a prompt appeared. */
224
261
  async function assertTeamWrite(context, action, resources, metadata) {
225
- await ctx.permission.assert({
262
+ await assertUnlessSkipped(ctx, config, {
226
263
  sessionID: context?.sessionID,
227
264
  agent: context?.agent,
228
265
  source: { type: "tool", messageID: context?.messageID, id: context?.id },
@@ -233,16 +270,55 @@ export function createToolkit(ctx, runtime) {
233
270
  })
234
271
  // On older hosts a default * allow may pass with no action policy. Require
235
272
  // a visible action-specific rule there; never infer that a prompt appeared.
236
- if (["memory.remember", "memory.revise", "page.write", "wiki.write"].includes(action) &&
273
+ // The person's own skipAsks setting is that explicit opt-in.
274
+ if (["memory.revise", "page.write", "wiki.write"].includes(action) && !skipsAsk(config, action) &&
237
275
  !(await hasSharedWritePolicy(ctx, context, action, resources))) {
238
276
  throw new Error(`no explicit permission rule for ${action} is visible on this host; no write was made. Add an allow or ask rule for ${action} (or memory.* for memory actions), or update OpenCode`)
239
277
  }
240
278
  }
241
279
 
280
+ /**
281
+ * The one gate for a write others or later sessions see (FABLE tools 1 and
282
+ * 2; slice 7). Every tool sends such a write here and nowhere else:
283
+ * - `shared` (a shared space, or another person's space through a grant):
284
+ * with `heldTeamWrites` and `records` it can express, the write is held in
285
+ * the speaker's own Inbox under the verified session, and the person
286
+ * approves it there; otherwise it asks `action`.
287
+ * - `pinned` (the `index` page, in any space, Personal included): it asks
288
+ * `action`, because it changes what every later session is told.
289
+ * - neither: no gate.
290
+ * A denial is an answer, `{ denied }`; a held write's failure throws, as
291
+ * holdTeamWrite does. `{ asked }` says an assertion passed, which is not
292
+ * proof that a prompt appeared, so `hostProvenance` never takes it as consent.
293
+ *
294
+ * @param {any} context the tool call's context
295
+ * @param {{ action: string, spaceContext?: any, shared?: boolean, pinned?: boolean, resources?: string[], metadata?: object, records?: object[] }} write
296
+ * @returns {Promise<{ asked: boolean, held?: string, denied?: string }>}
297
+ */
298
+ async function gateWrite(context, { action, spaceContext, shared = false, pinned = false, resources = [], metadata = {}, records } = {}) {
299
+ if (!shared && !pinned) return { asked: false }
300
+ if (shared && config.heldTeamWrites && Array.isArray(records) && records.length > 0) {
301
+ const held = await asVerifiedSession(context?.sessionID, () => holdTeamWrite(toolkit, context, spaceContext, records))
302
+ return { asked: false, held }
303
+ }
304
+ try {
305
+ await assertTeamWrite(context, action, [spaceContext?.space_id ?? (shared ? "team" : "local"), ...resources], {
306
+ ...metadata,
307
+ visibility: shared ? "team" : "private",
308
+ ...(pinned ? { pinned: "This page is placed in the system prompt of every later session." } : {}),
309
+ ...(spaceContext?.space_id ? { space_id: spaceContext.space_id } : {}),
310
+ ...(spaceContext?.space_name ? { space_name: oneLine(spaceContext.space_name, 200) } : {}),
311
+ })
312
+ } catch (error) {
313
+ return { asked: false, denied: errorMessage(error) }
314
+ }
315
+ return { asked: true }
316
+ }
317
+
242
318
  /**
243
319
  * Where each record id the agent has seen was written: its layer, agent, and
244
320
  * (for L0) session. Upstream deletes match a row only under the agent and
245
- * session it was written with, and mem_forget is used with ids that
321
+ * session it was written with, and revise forget is used with ids that
246
322
  * mem_recall or mem_remember just showed. Bounded and per process; keyed by
247
323
  * space so an id never resolves against another space's placement.
248
324
  */
@@ -255,7 +331,7 @@ export function createToolkit(ctx, runtime) {
255
331
 
256
332
  /**
257
333
  * Read a row's write coordinates, tolerating upstream field-name variants.
258
- * The text is kept, capped, so mem_forget can look for other copies of a
334
+ * The text is kept, capped, so revise forget can look for other copies of a
259
335
  * record it deletes even when the record is older than its scan window.
260
336
  */
261
337
  function rowLocation(layer, row, fallback = {}) {
@@ -275,7 +351,7 @@ export function createToolkit(ctx, runtime) {
275
351
  const location = rowLocation(layer, row, fallback)
276
352
  // Upstream L0 search hits carry no session. An L0 delete needs the row's
277
353
  // own session, so such a hit is not a usable location: leave it out and
278
- // let mem_forget look the id up with conversation/query.
354
+ // let revise forget look the id up with conversation/query.
279
355
  if (layer === "l0" && !location.session_id) continue
280
356
  const key = locationKey(spaceContext, id)
281
357
  locations.delete(key)
@@ -321,7 +397,7 @@ export function createToolkit(ctx, runtime) {
321
397
  return spaceContext.collection_name ? `${id} ${oneLine(spaceContext.collection_name, 120)}` : id
322
398
  }
323
399
 
324
- return {
400
+ const toolkit = {
325
401
  backend,
326
402
  config,
327
403
  log,
@@ -333,7 +409,7 @@ export function createToolkit(ctx, runtime) {
333
409
  scopeFor: runtime.scopeFor,
334
410
  resolveContext: runtime.resolveContext,
335
411
  isSessionBound: runtime.isSessionBound,
336
- assert: ctx.permission.assert,
412
+ assert,
337
413
  text,
338
414
  fail,
339
415
  sharedScope,
@@ -342,6 +418,7 @@ export function createToolkit(ctx, runtime) {
342
418
  resolvePrivateSpace,
343
419
  resolveWriteSpace,
344
420
  assertTeamWrite,
421
+ gateWrite,
345
422
  taskFor,
346
423
  rowLocation,
347
424
  noteLocations,
@@ -352,4 +429,5 @@ export function createToolkit(ctx, runtime) {
352
429
  describeSpace,
353
430
  describeCollection,
354
431
  }
432
+ return toolkit
355
433
  }