@joe-broadhead/opencode-mem 0.9.14 → 0.11.2

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 (139) hide show
  1. package/CHANGELOG.md +1805 -0
  2. package/README.md +14 -7
  3. package/SECURITY.md +3 -1
  4. package/docs/agent-instructions.md +1 -1
  5. package/docs/agent-protocol.md +7 -7
  6. package/docs/permissions.md +16 -0
  7. package/package.json +7688 -339
  8. package/shared/page-paths.js +44 -0
  9. package/skills/mem.pages/SKILL.md +3 -1
  10. package/skills/mem.usage/SKILL.md +15 -15
  11. package/src/action-grant-keys.js +159 -0
  12. package/src/action-grant.js +439 -0
  13. package/src/actions.js +1690 -0
  14. package/src/backend/records.js +25 -2
  15. package/src/backend/v3.js +76 -22
  16. package/src/call-shapes.js +17 -16
  17. package/src/collector-lock.js +533 -62
  18. package/src/collector-service.js +153 -26
  19. package/src/collector.js +623 -30
  20. package/src/config.js +79 -6
  21. package/src/connect.js +106 -8
  22. package/src/credentials.js +123 -25
  23. package/src/events.js +174 -3
  24. package/src/forget-turn.js +141 -0
  25. package/src/host-refusal.js +78 -0
  26. package/src/index.js +209 -22
  27. package/src/jobs/host.js +557 -0
  28. package/src/ops/codes.js +110 -0
  29. package/src/ops/copy-lineage.js +42 -0
  30. package/src/ops/index.js +28 -0
  31. package/src/ops/space-ops.js +1936 -0
  32. package/src/outlinks.js +103 -0
  33. package/src/p2-reservation.js +151 -0
  34. package/src/permissions.js +30 -0
  35. package/src/plugins/descriptor.js +62 -0
  36. package/src/plugins/discovery.js +318 -0
  37. package/src/plugins/grants.js +178 -0
  38. package/src/plugins/locate.js +319 -0
  39. package/src/plugins/manifest.js +1162 -0
  40. package/src/plugins/source-contract/index.js +34 -0
  41. package/src/plugins/source-contract/policy.js +102 -0
  42. package/src/plugins/source-contract/vendor/PROVENANCE.json +17 -0
  43. package/src/plugins/source-contract/vendor/RELEASE-SHA256SUMS +3 -0
  44. package/src/plugins/source-contract/vendor/RELEASE.json +17 -0
  45. package/src/plugins/source-contract/vendor/SHA256SUMS +41 -0
  46. package/src/plugins/source-contract/vendor/THIRD-PARTY-NOTICES.md +35 -0
  47. package/src/plugins/source-contract/vendor/broker-client.js +93 -0
  48. package/src/plugins/source-contract/vendor/chunks/chunk-3M5PAKSS.js +84 -0
  49. package/src/plugins/source-contract/vendor/chunks/chunk-4ERCA4TK.js +185 -0
  50. package/src/plugins/source-contract/vendor/chunks/chunk-6HDIB2SA.js +183 -0
  51. package/src/plugins/source-contract/vendor/chunks/chunk-ELPJD3ND.js +10 -0
  52. package/src/plugins/source-contract/vendor/chunks/chunk-HLVAKAYG.js +10 -0
  53. package/src/plugins/source-contract/vendor/chunks/chunk-I2RXJJJM.js +81 -0
  54. package/src/plugins/source-contract/vendor/chunks/chunk-KWEWSZ4V.js +505 -0
  55. package/src/plugins/source-contract/vendor/chunks/chunk-KYWBTAF4.js +182 -0
  56. package/src/plugins/source-contract/vendor/chunks/chunk-Q3RQA5J2.js +249 -0
  57. package/src/plugins/source-contract/vendor/chunks/chunk-RRUAIQ4I.js +156 -0
  58. package/src/plugins/source-contract/vendor/chunks/chunk-RYNKNCPP.js +165 -0
  59. package/src/plugins/source-contract/vendor/chunks/chunk-W5SHR7DQ.js +9477 -0
  60. package/src/plugins/source-contract/vendor/chunks/chunk-ZUKF7P6U.js +653 -0
  61. package/src/plugins/source-contract/vendor/cursor.js +26 -0
  62. package/src/plugins/source-contract/vendor/descriptor.js +34 -0
  63. package/src/plugins/source-contract/vendor/events.js +257 -0
  64. package/src/plugins/source-contract/vendor/index.js +10 -0
  65. package/src/plugins/source-contract/vendor/params.js +22 -0
  66. package/src/plugins/source-contract/vendor/permission.js +28 -0
  67. package/src/plugins/source-contract/vendor/pick.js +22 -0
  68. package/src/plugins/source-contract/vendor/read.js +29 -0
  69. package/src/plugins/source-contract/vendor/registry.js +23 -0
  70. package/src/plugins/source-contract/vendor/schema.js +17 -0
  71. package/src/plugins/source-contract/vendor/schemas/output.agenda.json +96 -0
  72. package/src/plugins/source-contract/vendor/schemas/output.countdown.json +28 -0
  73. package/src/plugins/source-contract/vendor/schemas/output.image.json +28 -0
  74. package/src/plugins/source-contract/vendor/schemas/output.inbox.json +84 -0
  75. package/src/plugins/source-contract/vendor/schemas/output.links.json +46 -0
  76. package/src/plugins/source-contract/vendor/schemas/output.list.json +57 -0
  77. package/src/plugins/source-contract/vendor/schemas/output.metric.json +61 -0
  78. package/src/plugins/source-contract/vendor/schemas/output.note.json +14 -0
  79. package/src/plugins/source-contract/vendor/schemas/output.progress.json +50 -0
  80. package/src/plugins/source-contract/vendor/schemas/output.record.json +38 -0
  81. package/src/plugins/source-contract/vendor/schemas/output.table.json +61 -0
  82. package/src/plugins/source-contract/vendor/schemas/output.thread.json +62 -0
  83. package/src/plugins/source-contract/vendor/schemas/sources.json +819 -0
  84. package/src/plugins/source-contract/vendor/schemas.js +19 -0
  85. package/src/plugins/source-contract/vendor/tools-rpc.js +42 -0
  86. package/src/plugins/verify.js +56 -0
  87. package/src/protocol.js +11 -6
  88. package/src/recall.js +92 -5
  89. package/src/records.js +61 -2
  90. package/src/requests.js +216 -0
  91. package/src/runtime.js +89 -7
  92. package/src/setup-time.js +68 -0
  93. package/src/skills.js +230 -8
  94. package/src/source-ids.js +25 -0
  95. package/src/sources/declaration.js +365 -0
  96. package/src/sources/reads.js +772 -0
  97. package/src/sources/rpc.js +151 -0
  98. package/src/sources.js +389 -92
  99. package/src/spaces.js +283 -11
  100. package/src/spool.js +61 -4
  101. package/src/stated.js +10 -5
  102. package/src/storable.js +139 -0
  103. package/src/tools/commitments.js +37 -4
  104. package/src/tools/held-write.js +31 -12
  105. package/src/tools/index.js +27 -0
  106. package/src/tools/ingest.js +27 -2
  107. package/src/tools/memory.js +30 -7
  108. package/src/tools/page.js +95 -9
  109. package/src/tools/recall.js +208 -4
  110. package/src/tools/share.js +42 -3
  111. package/src/tools/shared.js +44 -4
  112. package/src/tools/space-lifecycle.js +278 -0
  113. package/src/tools/spaces.js +373 -29
  114. package/src/tools/status.js +9 -2
  115. package/src/tools/wiki.js +34 -4
  116. package/src/util.js +110 -6
  117. package/src/vendor/source-contract/README.md +24 -0
  118. package/src/vendor/source-contract/THIRD-PARTY-NOTICES.md +35 -0
  119. package/src/vendor/source-contract/VENDOR.json +81 -0
  120. package/src/vendor/source-contract/chunks/chunk-3M5PAKSS.js +84 -0
  121. package/src/vendor/source-contract/chunks/chunk-6HDIB2SA.js +183 -0
  122. package/src/vendor/source-contract/chunks/chunk-HLVAKAYG.js +10 -0
  123. package/src/vendor/source-contract/chunks/chunk-I2RXJJJM.js +81 -0
  124. package/src/vendor/source-contract/chunks/chunk-KWEWSZ4V.js +505 -0
  125. package/src/vendor/source-contract/chunks/chunk-W5SHR7DQ.js +9477 -0
  126. package/src/vendor/source-contract/chunks/chunk-ZUKF7P6U.js +653 -0
  127. package/src/vendor/source-contract/cursor.js +26 -0
  128. package/src/vendor/source-contract/events.js +257 -0
  129. package/src/vendor/source-contract/registry.js +23 -0
  130. package/src/vendor/source-contract/tools-rpc.js +42 -0
  131. package/src/views/access-reads.js +256 -0
  132. package/src/views/communities.js +77 -0
  133. package/src/views/contracts.js +930 -21
  134. package/src/views/inbox-bytes.js +103 -0
  135. package/src/views/profile.js +31 -0
  136. package/src/views/records-reads.js +355 -38
  137. package/src/views/rpc.js +118 -8
  138. package/src/views/shape.js +8 -5
  139. package/views/pages.html +2 -2
@@ -0,0 +1,365 @@
1
+ /**
2
+ * Memory's sources, as the shared source contract declares them
3
+ * (`package.json#sources`, contract version 1; app#2346 §2.2).
4
+ *
5
+ * Memory is a **provider** here, not only a consumer: the reads another project
6
+ * may need are declared once, in `package.json` (read from the installed package
7
+ * on disk, never over RPC), and served over `mem.tools`
8
+ * (`src/sources/rpc.js`). Each read is a plugin method whose action and
9
+ * operations are exactly what it does at Memory's own records and control
10
+ * services, so a grant and a person's off switch key on them.
11
+ *
12
+ * This module is the one place the declaration is written; the test
13
+ * `test/sources-declaration.test.js` holds `package.json` to it byte for byte,
14
+ * so the shipped key cannot drift from the code that serves it.
15
+ *
16
+ * **Outputs.** `mem.names` and `mem.pages-search` answer the registry's `list`,
17
+ * which is what opencode-mem#58 names for them. The rest carry #58's own shapes,
18
+ * which no registry name holds: an `x-mem/<name>` output states its schema
19
+ * inline (`outputSchema`), and the conformance kit holds each answer's `data` to
20
+ * it. A source's `x-` name is in the source id's own namespace, `mem`.
21
+ *
22
+ * Not a source: `mem.suggestions`' `suggestion.dismiss` action. An action is not
23
+ * a read, and it belongs to the actions lane (opencode-mem#58 §A, #49).
24
+ */
25
+
26
+ /** The contract version this declaration is written to. */
27
+ export const CONTRACT_VERSION = 1
28
+
29
+ /** The probe's own action: the identity read every source's grant carries as the bare operation `probe`. */
30
+ export const PROBE_ACTION = "mem_probe"
31
+
32
+ /** Memory's OpenCode plugin id (`opencode plugin list`): the contract's tools-RPC ids are
33
+ * `<plugin id>.tools`, and v0.1.0 accepts only lowercase dotted words, never a scoped npm name. */
34
+ export const RPC_PLUGIN = "mem"
35
+
36
+ /** A space a record lives in: the id its page names, and its display name. */
37
+ const SPACE = Object.freeze({
38
+ type: "object",
39
+ additionalProperties: false,
40
+ required: ["id", "name"],
41
+ properties: { id: { type: "string", maxLength: 200 }, name: { type: "string", maxLength: 200 } },
42
+ })
43
+
44
+ /** The roles a space's people hold, in the contract's words. */
45
+ const ROLE = Object.freeze(["owner", "admin", "writer", "reader"])
46
+
47
+ /** A record one turn saved (#58 S1). */
48
+ const RECEIPT = Object.freeze({
49
+ type: "object",
50
+ additionalProperties: false,
51
+ required: ["session", "turn", "at", "saved", "more"],
52
+ properties: {
53
+ session: { type: "string", maxLength: 200 },
54
+ turn: { type: ["string", "null"], maxLength: 200 },
55
+ at: { type: "string", maxLength: 40 },
56
+ // True when the answer was capped: a list's most, or the source's byte cap.
57
+ more: { type: "boolean" },
58
+ saved: {
59
+ type: "array",
60
+ maxItems: 500,
61
+ items: Object.freeze({
62
+ type: "object",
63
+ additionalProperties: false,
64
+ required: ["id", "kind", "text", "space"],
65
+ properties: {
66
+ id: { type: "string", maxLength: 200 },
67
+ kind: { type: "string", maxLength: 40 },
68
+ text: { type: "string", maxLength: 300 },
69
+ space: SPACE,
70
+ },
71
+ }),
72
+ },
73
+ },
74
+ })
75
+
76
+ /** Who is in one space (#58 S3a). */
77
+ const MEMBERS = Object.freeze({
78
+ type: "object",
79
+ additionalProperties: false,
80
+ required: ["space", "members", "more"],
81
+ properties: {
82
+ space: SPACE,
83
+ more: { type: "boolean" },
84
+ members: {
85
+ type: "array",
86
+ maxItems: 500,
87
+ items: Object.freeze({
88
+ type: "object",
89
+ additionalProperties: false,
90
+ required: ["person", "label", "role"],
91
+ properties: {
92
+ person: { type: "string", maxLength: 200 },
93
+ label: { type: "string", maxLength: 200 },
94
+ role: { type: "string", enum: ROLE },
95
+ },
96
+ }),
97
+ },
98
+ },
99
+ })
100
+
101
+ /** Who a space, wiki, folder or page is shared with (#58 S3b). */
102
+ const GRANTS = Object.freeze({
103
+ type: "object",
104
+ additionalProperties: false,
105
+ required: ["space", "scope", "grants", "more"],
106
+ properties: {
107
+ space: SPACE,
108
+ // Which grants were asked for: the one named target's, the space's (an
109
+ // admin's read), or (control refusing a member the space's) the caller's own.
110
+ scope: { type: "string", enum: ["target", "space", "mine"] },
111
+ more: { type: "boolean" },
112
+ grants: {
113
+ type: "array",
114
+ maxItems: 500,
115
+ items: Object.freeze({
116
+ type: "object",
117
+ additionalProperties: false,
118
+ required: ["subject", "access", "via"],
119
+ properties: {
120
+ subject: Object.freeze({
121
+ type: "object",
122
+ additionalProperties: false,
123
+ minProperties: 1,
124
+ maxProperties: 1,
125
+ properties: { person: { type: "string", maxLength: 200 }, team: { type: "string", maxLength: 200 } },
126
+ }),
127
+ access: { type: "string", enum: ROLE },
128
+ via: { type: "string", enum: ["space", "wiki", "folder", "page"] },
129
+ // When the grant started. #58 names no field for its expiry, so the
130
+ // answer carries none: a date that is not a start is worse than none.
131
+ since: { type: "string", maxLength: 40 },
132
+ },
133
+ }),
134
+ },
135
+ },
136
+ })
137
+
138
+ /** The shared spaces the person may ask to join (#58 S4). */
139
+ const SPACES = Object.freeze({
140
+ type: "object",
141
+ additionalProperties: false,
142
+ required: ["spaces", "more"],
143
+ properties: {
144
+ more: { type: "boolean" },
145
+ spaces: {
146
+ type: "array",
147
+ maxItems: 200,
148
+ items: Object.freeze({
149
+ type: "object",
150
+ additionalProperties: false,
151
+ required: ["space", "name", "kind", "join"],
152
+ properties: {
153
+ space: { type: "string", maxLength: 200 },
154
+ name: { type: "string", maxLength: 200 },
155
+ kind: { type: "string", enum: ["team", "topic"] },
156
+ about: { type: "string", maxLength: 300 },
157
+ members: { type: "integer", minimum: 0 },
158
+ join: { type: "string", enum: ["open", "request"] },
159
+ yourRequest: { type: "string", enum: ["pending"] },
160
+ },
161
+ }),
162
+ },
163
+ },
164
+ })
165
+
166
+ /** What one meeting produced (#58 S5), with the states Memory can prove. */
167
+ const MEETING_RECORDS = Object.freeze({
168
+ type: "object",
169
+ additionalProperties: false,
170
+ required: ["meeting", "records", "more"],
171
+ properties: {
172
+ meeting: { type: "string", maxLength: 200 },
173
+ records: {
174
+ type: "array",
175
+ maxItems: 500,
176
+ items: Object.freeze({
177
+ type: "object",
178
+ additionalProperties: false,
179
+ required: ["id", "text", "state", "space"],
180
+ properties: {
181
+ id: { type: "string", maxLength: 200 },
182
+ text: { type: "string", maxLength: 300 },
183
+ // `forgotten` is not knowable: a forgotten record is purged, and only a
184
+ // salted fingerprint stays. Memory answers the two states it can prove.
185
+ state: { type: "string", enum: ["waiting", "kept"] },
186
+ space: SPACE,
187
+ },
188
+ }),
189
+ },
190
+ more: { type: "boolean" },
191
+ },
192
+ })
193
+
194
+ /**
195
+ * The `sources` key's items. Every `tool` is one of the plugin methods
196
+ * `src/sources/rpc.js` registers, and every action is the method's own action.
197
+ *
198
+ * `private: false` on every source: each reads the person's own memory through
199
+ * their credential, and the memory it reads may hold shared spaces (a name, a
200
+ * page, a receipt for a turn that wrote to a team space), so none of them is
201
+ * "everything it reads is personal".
202
+ */
203
+ export function sourcesDeclaration() {
204
+ return {
205
+ contractVersion: CONTRACT_VERSION,
206
+ // Memory's OpenCode plugin id, not its scoped npm name: contract v0.1.0 accepts only lowercase dotted
207
+ // words, and declaring it keeps a host from having to map the package to an id it cannot derive.
208
+ rpc: `${RPC_PLUGIN}.tools`,
209
+ // The one probe tool, and the action `src/sources/rpc.js` asserts for it (contract v0.1.0's `sources.probe`).
210
+ probe: { action: PROBE_ACTION },
211
+ items: [
212
+ {
213
+ // S1: what Memory saved because of one turn, so "Ledger remembered 2
214
+ // things" is Memory's fact and not the host's count.
215
+ id: "mem.turn-receipts",
216
+ kind: "snapshot",
217
+ tool: "receipts_read",
218
+ input: { source: "turn-receipts" },
219
+ output: "x-mem/receipt",
220
+ outputSchema: RECEIPT,
221
+ params: { session: {}, turn: {}, space: {} },
222
+ accounts: { named: false },
223
+ permission: { tool: "mem.receipts_read", operations: ["records.list", "probe"] },
224
+ private: false,
225
+ cost: { class: "free" },
226
+ maxAgeSec: 30,
227
+ maxBytes: 65536,
228
+ },
229
+ {
230
+ // S2: the people and names Memory knows, for dictation's word list.
231
+ id: "mem.names",
232
+ kind: "snapshot",
233
+ tool: "names_list",
234
+ input: { source: "names" },
235
+ output: "list",
236
+ params: { space: {}, max: {} },
237
+ accounts: { named: false },
238
+ permission: { tool: "mem.names_list", operations: ["records.list", "probe"] },
239
+ private: false,
240
+ cost: { class: "free" },
241
+ maxAgeSec: 300,
242
+ maxBytes: 131072,
243
+ },
244
+ {
245
+ // S3a: who is in a space, as the space's own access rules let the
246
+ // caller see it.
247
+ id: "mem.members",
248
+ kind: "snapshot",
249
+ tool: "members_read",
250
+ input: { source: "members" },
251
+ output: "x-mem/members",
252
+ outputSchema: MEMBERS,
253
+ params: { space: {} },
254
+ accounts: { named: false },
255
+ permission: { tool: "mem.members_read", operations: ["control.spaces.members.list", "probe"] },
256
+ private: false,
257
+ cost: { class: "free" },
258
+ maxAgeSec: 60,
259
+ maxBytes: 131072,
260
+ },
261
+ {
262
+ // S3b: who a space, wiki, folder or page is shared with.
263
+ id: "mem.grants",
264
+ kind: "snapshot",
265
+ tool: "grants_read",
266
+ input: { source: "grants" },
267
+ output: "x-mem/grants",
268
+ outputSchema: GRANTS,
269
+ params: { space: {}, target: {} },
270
+ accounts: { named: false },
271
+ permission: { tool: "mem.grants_read", operations: ["control.spaces.grants.list", "probe"] },
272
+ private: false,
273
+ cost: { class: "free" },
274
+ maxAgeSec: 60,
275
+ maxBytes: 131072,
276
+ },
277
+ {
278
+ // S4: the shared spaces the person may ask to join.
279
+ id: "mem.spaces-to-join",
280
+ kind: "snapshot",
281
+ tool: "spaces_joinable_read",
282
+ input: { source: "spaces-to-join" },
283
+ output: "x-mem/spaces",
284
+ outputSchema: SPACES,
285
+ params: {},
286
+ accounts: { named: false },
287
+ permission: { tool: "mem.spaces_joinable_read", operations: ["control.spaces.list", "probe"] },
288
+ private: false,
289
+ cost: { class: "free" },
290
+ maxAgeSec: 300,
291
+ maxBytes: 65536,
292
+ },
293
+ {
294
+ // S5: what one meeting produced, with each end state Memory can prove.
295
+ id: "mem.meeting-records",
296
+ kind: "snapshot",
297
+ tool: "meeting_records_read",
298
+ input: { source: "meeting-records" },
299
+ output: "x-mem/meeting-records",
300
+ outputSchema: MEETING_RECORDS,
301
+ params: { meeting: {}, space: {} },
302
+ accounts: { named: false },
303
+ permission: { tool: "mem.meeting_records_read", operations: ["records.list", "probe"] },
304
+ private: false,
305
+ cost: { class: "free" },
306
+ maxAgeSec: 30,
307
+ maxBytes: 65536,
308
+ },
309
+ {
310
+ // S6: a turn's record worth sharing, as events of Memory's own kind.
311
+ // `suggestion.dismiss` is an action (#58 §A) and is not declared here.
312
+ id: "mem.suggestions",
313
+ kind: "events",
314
+ reads: "x-mem/suggestion",
315
+ tool: "events_list",
316
+ input: { source: "suggestions" },
317
+ accounts: { named: false },
318
+ permission: { events: "mem.events_list", operations: ["records.list", "probe"] },
319
+ private: false,
320
+ cost: { class: "free" },
321
+ retentionDays: 30,
322
+ maxBytes: 65536,
323
+ },
324
+ {
325
+ // S7: page titles, so Find can offer a page it has not listed.
326
+ id: "mem.pages-search",
327
+ kind: "snapshot",
328
+ tool: "pages_search",
329
+ input: { source: "pages-search" },
330
+ output: "list",
331
+ params: { space: {}, q: {}, limit: {} },
332
+ accounts: { named: false },
333
+ permission: { tool: "mem.pages_search", operations: ["records.search", "probe"] },
334
+ private: false,
335
+ cost: { class: "free" },
336
+ maxAgeSec: 60,
337
+ maxBytes: 65536,
338
+ },
339
+ ],
340
+ }
341
+ }
342
+
343
+ /**
344
+ * The method action each source's read asserts, and the operation it performs
345
+ * (the resource its rule is resolved on). `registerToolsRpc` resolves the rule
346
+ * on `<account>:<operation>` before dispatch, so a grant for the source is
347
+ * exactly these two rules.
348
+ */
349
+ export function sourceReads() {
350
+ return sourcesDeclaration().items.map((item) => ({
351
+ source: item.id,
352
+ kind: item.kind,
353
+ tool: item.tool,
354
+ action: item.kind === "events" ? item.permission.events : item.permission.tool,
355
+ operation: item.permission.operations.find((operation) => operation !== "probe") ?? "",
356
+ }))
357
+ }
358
+
359
+ export const SOURCE_READS = sourceReads()
360
+
361
+ /** Every declared item, by id. */
362
+ export const SOURCE_BY_ID = new Map(sourcesDeclaration().items.map((item) => [item.id, item]))
363
+
364
+ /** The bare operation a source declares for its probe, asserted as `mem_probe` on `*`. */
365
+ export const PROBE_OPERATION = "probe"