@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
package/src/sources.js CHANGED
@@ -7,25 +7,165 @@
7
7
  * bind call `events_list` through it (`ctx.rpc`).
8
8
  * - `namespace` and `tool`: the Code Mode path a host schedule's check calls,
9
9
  * `tools.<namespace>.<tool>`.
10
+ * - `permission`: exactly what the source plugin asserts when Memory calls its
11
+ * `events_list`, so the collector's session allows that and nothing more
12
+ * (`collectSessionRules` in src/collector.js). OpenCode checks each inner
13
+ * action against that session (S0, 0.9.11), so a missing one is an outage.
14
+ * - `events`: its events action, allowed on `"*"`: the plugin's tools RPC
15
+ * checks it on `"*"` before it runs (gws included).
16
+ * - `actions`: the exact inner actions it then asserts, on `"*"`: the MCP
17
+ * tools it reads through OpenCode's executors, `<server>_<tool>`. When
18
+ * `accountServer` is set (Plaud), a named account's tools are on their own
19
+ * server, so `<server>_` becomes that server's name.
20
+ * - `reads` with `readAction`: the operations it asserts `readAction` on,
21
+ * named `<account>:<operation>` (gws: `work:gmail.users.messages.get`),
22
+ * always on the binding's own account, never `*:`. Such a source sets
23
+ * `namesAccount`, so Memory always sends that account in `events_list`,
24
+ * "default" included (gws's own default alias). A confirmed binding's
25
+ * account is the alias its bind probe reported, so its session is pinned
26
+ * to the account the person confirmed.
27
+ * No source gets a generic `<ns>_*`, `.read` or any write.
10
28
  * - `input`: what every `events_list` call to this source adds; a plugin that
11
29
  * serves several sources (gws: gmail, later calendar and drive) is told which.
30
+ * - `everyMinutes`: how often the timer collects this source (default 30). A
31
+ * billed source (X) runs less often; "collect now" ignores it.
32
+ * - `ownerProbe`: how a bind request learns the signed-in account. `"limit0"`
33
+ * is the contract's owner-only call (`limit: 0`, §4.5): no events. `"limit1"`
34
+ * is the fallback for releases that refuse 0: one event is read and dropped,
35
+ * never stored, as the plugin's own bind does.
36
+ * - `setupOptions`: the plugin options this source needs or should have before
37
+ * it is bound, said in the bind answer and the docs. Memory never sets them:
38
+ * they are the source plugin's.
12
39
  * - `package` and `minVersion`: who to update when the plugin's `events_list`
13
40
  * does not keep the source contract (§4.5). `minVersion` is the first release
14
- * whose `events_list` answers `source` and `account`; null until lane SRC
15
- * publishes it, and the error then names the contract instead.
41
+ * whose `events_list` answers `source`, `account` and `owner`.
16
42
  */
43
+ /** A binding's account name: no wildcard (`*`, `?`), separator (`:`, `/`) or space, and never empty. */
44
+ export const ACCOUNT_NAME = /^[A-Za-z0-9][A-Za-z0-9_.@+-]{0,127}$/
45
+
46
+ function freezePermission(permission) {
47
+ return Object.freeze({ ...permission, actions: Object.freeze([...permission.actions]), reads: Object.freeze([...permission.reads]) })
48
+ }
49
+
50
+ /** The timer's default cadence per source, in minutes. */
51
+ export const DEFAULT_EVERY_MINUTES = 30
52
+
17
53
  export const SOURCE_REGISTRY = Object.freeze(
18
54
  [
19
- { source: "history", rpc: "history.sessions.tools", namespace: "history", package: "@joe-broadhead/opencode-history" },
20
- { source: "gmail", rpc: "google-workspace.gws.tools", namespace: "gws", input: { source: "gmail" }, package: "@joe-broadhead/opencode-gws" },
21
- { source: "slack", rpc: "slack.workspace.tools", namespace: "slack", package: "@joe-broadhead/opencode-slack" },
22
- { source: "x", rpc: "x.posts.tools", namespace: "x", package: "@joe-broadhead/opencode-x" },
23
- { source: "granola", rpc: "granola.meetings.tools", namespace: "granola", package: "@joe-broadhead/opencode-granola" },
24
- { source: "plaud", rpc: "plaud.recordings.tools", namespace: "plaud", package: "@joe-broadhead/opencode-plaud" },
25
- { source: "wisprflow", rpc: "wisprflow.meetings.tools", namespace: "wisprflow", package: "@joe-broadhead/opencode-wisprflow" },
26
- { source: "github", rpc: "github.platform.tools", namespace: "github", package: "@joe-broadhead/opencode-github" },
27
- { source: "linear", rpc: "linear.workspace.tools", namespace: "linear", package: "@joe-broadhead/opencode-linear" },
28
- ].map((entry) => Object.freeze({ tool: "events_list", input: {}, minVersion: null, ...entry, input: Object.freeze({ ...(entry.input ?? {}) }) })),
55
+ // history reads its own local index: no inner action.
56
+ { source: "history", rpc: "history.sessions.tools", namespace: "history", package: "@joe-broadhead/opencode-history", minVersion: "0.0.6" },
57
+ {
58
+ source: "gmail",
59
+ rpc: "google-workspace.gws.tools",
60
+ namespace: "gws",
61
+ input: { source: "gmail" },
62
+ package: "@joe-broadhead/opencode-gws",
63
+ minVersion: "0.0.10",
64
+ // gws (dist src/host/tools-rpc.ts) first checks gws.events_list with the rules whose resource
65
+ // matches "*", so it must be allowed on "*"; then events_list asserts gws.events_list on
66
+ // <account>:gmail.users.history.list and gws.read ("Run a read-only operation") on
67
+ // <account>:<operation> for each of its EVENT_READS, all Gmail list and get calls.
68
+ permission: {
69
+ events: "gws.events_list",
70
+ readAction: "gws.read",
71
+ reads: ["gmail.users.getProfile", "gmail.users.history.list", "gmail.users.messages.list", "gmail.users.messages.get"],
72
+ },
73
+ // gws scopes the reads by account, so the account is always named: "default" too.
74
+ namesAccount: true,
75
+ },
76
+ {
77
+ source: "slack",
78
+ rpc: "slack.workspace.tools",
79
+ namespace: "slack",
80
+ package: "@joe-broadhead/opencode-slack",
81
+ minVersion: "0.0.8",
82
+ // events_list reads the owner, then each enabled channel, through the MCP executors of the server
83
+ // "slack", whose tools are named slack_*: both are "read" in its class table (S0 Q1.4 proved this pair).
84
+ permission: { actions: ["slack_slack_read_user_profile", "slack_slack_read_channel"] },
85
+ setupOptions: 'Slack collects only the channels and direct messages listed in the slack plugin\'s option "events": {"channels": ["C…", "D…"]} (at most 16); set it, then restart OpenCode.',
86
+ },
87
+ {
88
+ source: "x",
89
+ rpc: "x.posts.tools",
90
+ namespace: "x",
91
+ package: "@joe-broadhead/opencode-x",
92
+ minVersion: "0.0.1",
93
+ // Every X read is billed to the developer account that owns the app.
94
+ everyMinutes: 120,
95
+ // The owner, then each feed in the plugin's events.feeds (mentions, bookmarks, and the home
96
+ // timeline only when named), all in its READ_TOOLS.
97
+ permission: { actions: ["x_get_users_me", "x_get_users_mentions", "x_get_users_bookmarks", "x_get_users_timeline"] },
98
+ setupOptions:
99
+ 'X reads are billed. Set the x plugin\'s options "events": {"feeds": ["mentions", "bookmarks"], "maxCalls": 2}, and "ownsXApp": true only if the signed-in account owns the developer app (it lowers the price X charges); then restart OpenCode.',
100
+ },
101
+ {
102
+ source: "granola",
103
+ rpc: "granola.meetings.tools",
104
+ namespace: "granola",
105
+ package: "@joe-broadhead/opencode-granola",
106
+ minVersion: "0.0.9",
107
+ // The owner, the week windows, then each meeting's details: all in its READ_TOOLS.
108
+ permission: { actions: ["granola_get_account_info", "granola_search_meetings", "granola_get_meetings"] },
109
+ },
110
+ {
111
+ source: "plaud",
112
+ rpc: "plaud.recordings.tools",
113
+ namespace: "plaud",
114
+ package: "@joe-broadhead/opencode-plaud",
115
+ minVersion: "0.0.8",
116
+ // The owner, then the recordings, both in its KNOWN_READS, on the account's server:
117
+ // "plaud" for the default account, "plaud-<account>" for another.
118
+ permission: { actions: ["plaud_list_files", "plaud_get_current_user"], accountServer: "plaud-{account}" },
119
+ },
120
+ {
121
+ source: "wisprflow",
122
+ rpc: "wisprflow.meetings.tools",
123
+ namespace: "wisprflow",
124
+ package: "@joe-broadhead/opencode-wisprflow",
125
+ minVersion: "0.0.3",
126
+ // The owner comes from the sign-in itself; the meetings from search_meetings, in its READ_TOOLS.
127
+ permission: { actions: ["wisprflow_search_meetings"] },
128
+ },
129
+ {
130
+ source: "github",
131
+ rpc: "github.platform.tools",
132
+ namespace: "github",
133
+ package: "@joe-broadhead/opencode-github",
134
+ minVersion: "0.0.9",
135
+ // The owner from get_me (the context toolset's read); the rest are REST GETs, which assert nothing.
136
+ permission: { actions: ["github_get_me"] },
137
+ },
138
+ {
139
+ source: "linear",
140
+ rpc: "linear.workspace.tools",
141
+ namespace: "linear",
142
+ package: "@joe-broadhead/opencode-linear",
143
+ minVersion: "0.0.9",
144
+ // Assigned issues, the inbox, then the workspace and the owner: all in its READ_TOOLS.
145
+ permission: { actions: ["linear_list_issues", "linear_get_notifications", "linear_get_workspace", "linear_get_user"] },
146
+ },
147
+ ].map((entry) =>
148
+ Object.freeze({
149
+ tool: "events_list",
150
+ input: {},
151
+ minVersion: null,
152
+ everyMinutes: DEFAULT_EVERY_MINUTES,
153
+ ownerProbe: "limit1",
154
+ setupOptions: null,
155
+ namesAccount: false,
156
+ ...entry,
157
+ input: Object.freeze({ ...(entry.input ?? {}) }),
158
+ // The plugins' convention: <namespace>_events_list; each source lists its own inner actions.
159
+ permission: freezePermission({
160
+ events: `${entry.namespace}_events_list`,
161
+ actions: [],
162
+ accountServer: null,
163
+ readAction: null,
164
+ reads: [],
165
+ ...(entry.permission ?? {}),
166
+ }),
167
+ }),
168
+ ),
29
169
  )
30
170
 
31
171
  const BY_SOURCE = new Map(SOURCE_REGISTRY.map((entry) => [entry.source, entry]))
@@ -40,6 +180,37 @@ export function knownSources() {
40
180
  return SOURCE_REGISTRY.map((entry) => entry.source)
41
181
  }
42
182
 
183
+ /** The account a binding without one names. */
184
+ const DEFAULT_ACCOUNT = "default"
185
+
186
+ /**
187
+ * The allow rules a source's `events_list` needs in one binding's collector
188
+ * session: its events action, its exact inner actions, and its exact read
189
+ * operations, always on the binding's account. Never a generic `<ns>_*` or
190
+ * `.read`, and never a write. An account that is not an account name (a
191
+ * wildcard, a separator, empty) is refused: it would widen the rules.
192
+ *
193
+ * @param {string | null} [account] the binding's account; null for the default binding, "default"
194
+ * @returns {{ action: string, resource: string, effect: "allow" }[]}
195
+ */
196
+ export function sourceAllowRules(entry, account = null) {
197
+ const permission = entry.permission
198
+ if (account !== null && account !== undefined && (typeof account !== "string" || !ACCOUNT_NAME.test(account))) {
199
+ throw new TypeError(`sourceAllowRules: "${String(account).slice(0, 60)}" is not an account name`)
200
+ }
201
+ const bound = account ?? DEFAULT_ACCOUNT
202
+ const named = bound !== DEFAULT_ACCOUNT ? bound : null
203
+ const allow = (action, resource = "*") => ({ action, resource, effect: "allow" })
204
+ // A named account's MCP tools on its own server (Plaud): "<namespace>_<tool>" becomes "<server>_<tool>".
205
+ const server = named && permission.accountServer ? permission.accountServer.replace("{account}", named) : null
206
+ const inner = (action) => (server && action.startsWith(`${entry.namespace}_`) ? `${server}${action.slice(entry.namespace.length)}` : action)
207
+ return [
208
+ allow(permission.events),
209
+ ...permission.actions.map((action) => allow(inner(action))),
210
+ ...permission.reads.map((operation) => allow(permission.readAction, `${bound}:${operation}`)),
211
+ ]
212
+ }
213
+
43
214
  /** The source contract version a plugin's `events_list` must keep. */
44
215
  export const SOURCE_CONTRACT = "the memory source contract v1 (events_list answers source and account)"
45
216
 
package/src/spaces.js CHANGED
@@ -184,14 +184,18 @@ export function createControlClient(input) {
184
184
  * spaceId?: string,
185
185
  * sessionId?: string,
186
186
  * agent?: string,
187
+ * bind?: boolean,
187
188
  * }} input
189
+ * `bind: true` (with a session) is the one request that changes the
190
+ * session's binding: to `spaceId`, or to the personal space without one.
188
191
  */
189
- async function resolveContext({ userId, spaceId, sessionId, agent } = {}) {
192
+ async function resolveContext({ userId, spaceId, sessionId, agent, bind } = {}) {
190
193
  if (!userId) throw missing("context", "user_id")
191
194
  const body = { user_id: String(userId) }
192
195
  if (spaceId) body.space_id = String(spaceId)
193
196
  if (sessionId) body.session_id = String(sessionId)
194
197
  if (agent) body.agent = String(agent)
198
+ if (bind === true && sessionId) body.bind = true
195
199
 
196
200
  const payload = await request("context", "POST", "/v1/context", { body })
197
201
  const context = normalizeContext(payload, { userId: body.user_id, spaceId })
@@ -367,10 +371,63 @@ export function createControlClient(input) {
367
371
  return extractMemberList(payload).map(normalizeMember).filter((member) => member.user_id)
368
372
  }
369
373
 
374
+ /**
375
+ * One colleague by exact email (mem_share grant and transfer, after the
376
+ * co-member search): `GET /v1/users/lookup?email=`. Answers `{ user_id,
377
+ * name }` for the one active user of the caller's organisation with that
378
+ * address, or null. Control limits each caller (429 lookup_rate_limited);
379
+ * there is no listing (docs/design/adr-user-lookup.md).
380
+ *
381
+ * @param {{ userId: string, email: string }} input
382
+ * @returns {Promise<{ user_id: string, name: string } | null>}
383
+ */
384
+ async function lookupUser({ userId, email } = {}) {
385
+ if (!userId) throw missing("lookup", "user_id")
386
+ if (!email) throw missing("lookup", "email")
387
+ const payload = await request("lookup", "GET", "/v1/users/lookup", { query: { email: String(email) } })
388
+ const user = isPlainObject(payload?.user) ? payload.user : null
389
+ const id = text(user?.user_id)
390
+ return id ? { user_id: id, name: text(user.name) } : null
391
+ }
392
+
393
+ /**
394
+ * The records pages and folders others shared with the caller, in every
395
+ * space (mem_share list with "to": "me"): `GET /v1/shared-with-me`. Only
396
+ * display fields are kept.
397
+ *
398
+ * @param {{ userId: string }} input
399
+ */
400
+ async function sharedWithMe({ userId } = {}) {
401
+ if (!userId) throw missing("shared", "user_id")
402
+ const payload = await request("shared", "GET", "/v1/shared-with-me")
403
+ const rows = Array.isArray(payload?.shares) ? payload.shares : []
404
+ const person = (value) => (isPlainObject(value) && text(value.user_id) ? { user_id: text(value.user_id), name: text(value.name), email: text(value.email) } : null)
405
+ return {
406
+ shares: rows
407
+ .filter((row) => isPlainObject(row) && /^[a-z0-9][a-z0-9/-]{0,300}$/.test(text(row.path)) && text(row.space?.id))
408
+ .map((row) => ({
409
+ path: text(row.path),
410
+ kind: text(row.kind) === "folder" ? "folder" : "page",
411
+ name: text(row.name),
412
+ space_id: text(row.space.id),
413
+ space_name: text(row.space.name),
414
+ space_kind: text(row.space.kind),
415
+ owner: person(row.owner),
416
+ role: text(row.role) === "editor" ? "editor" : "viewer",
417
+ via: text(row.via),
418
+ expires_at: text(row.expires_at),
419
+ grant_id: text(row.grant_id),
420
+ })),
421
+ more: Number.isInteger(payload?.more) ? payload.more : 0,
422
+ }
423
+ }
424
+
370
425
  return {
371
426
  get controlURL() {
372
427
  return controlURLOf()
373
428
  },
429
+ lookupUser,
430
+ sharedWithMe,
374
431
  listSpaces,
375
432
  resolveContext,
376
433
  effectiveAccess,