@joe-broadhead/opencode-mem 0.8.5 → 0.9.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (58) hide show
  1. package/CHANGELOG.md +512 -0
  2. package/README.md +127 -61
  3. package/docs/agent-protocol.md +67 -177
  4. package/package.json +1453 -100
  5. package/skills/mem.pages/SKILL.md +146 -0
  6. package/skills/mem.sharing/SKILL.md +91 -0
  7. package/skills/mem.sources/SKILL.md +94 -0
  8. package/skills/mem.usage/SKILL.md +129 -492
  9. package/src/backend/records.js +285 -0
  10. package/src/backend/v3.js +3 -0
  11. package/src/bootstrap.js +49 -45
  12. package/src/call-shapes.js +41 -10
  13. package/src/collector-lock.js +162 -0
  14. package/src/collector-service.js +441 -0
  15. package/src/collector.js +381 -0
  16. package/src/commands.js +3 -3
  17. package/src/config.js +15 -1
  18. package/src/credentials.js +26 -1
  19. package/src/curation.js +1 -1
  20. package/src/permissions.js +87 -10
  21. package/src/protocol.js +29 -20
  22. package/src/recall.js +104 -27
  23. package/src/records-store.js +267 -121
  24. package/src/records.js +63 -11
  25. package/src/runtime.js +23 -14
  26. package/src/skills.js +44 -18
  27. package/src/sources.js +58 -0
  28. package/src/spaces.js +93 -10
  29. package/src/tools/aliases.js +164 -0
  30. package/src/tools/commitments.js +12 -9
  31. package/src/tools/held-write.js +82 -0
  32. package/src/tools/index.js +100 -23
  33. package/src/tools/ingest.js +277 -0
  34. package/src/tools/knowledge.js +6 -1
  35. package/src/tools/memory.js +722 -229
  36. package/src/tools/page.js +423 -0
  37. package/src/tools/recall.js +371 -113
  38. package/src/tools/records-kit.js +142 -0
  39. package/src/tools/share.js +1042 -0
  40. package/src/tools/shared.js +16 -2
  41. package/src/tools/spaces.js +431 -143
  42. package/src/tools/status.js +87 -58
  43. package/src/tools/wiki.js +8 -4
  44. package/src/views/contracts.js +293 -3
  45. package/src/views/inbox-decision.js +59 -0
  46. package/src/views/recall-result.js +12 -0
  47. package/src/views/records-reads.js +675 -0
  48. package/src/views/rpc.js +58 -99
  49. package/src/views/shape.js +61 -0
  50. package/views/commitments.html +4 -0
  51. package/views/graph.html +753 -0
  52. package/views/home.html +11 -5
  53. package/views/journal.html +621 -0
  54. package/views/memory.html +7 -1
  55. package/views/pages.html +636 -0
  56. package/views/recall.html +123 -0
  57. package/views/review.html +406 -0
  58. package/views/today.html +309 -0
package/src/views/rpc.js CHANGED
@@ -1,19 +1,21 @@
1
1
  import { UNLINKED_SENTENCE, asView, inView, isUnlinked, originOf, PACKAGE_NAME, SOURCES } from "../credentials.js"
2
2
  import { dayIn, dueDay, filterItems, formatDay, formatDue } from "../records.js"
3
3
  import { isRecordsWikiName } from "../tools/knowledge.js"
4
- import { oneLine } from "../util.js"
5
4
  import {
6
5
  COMMITMENTS_MAX,
7
- ID_PATTERN,
8
6
  LIST_MAX,
9
- MEMORY_TEXT_CHARS,
10
7
  PAGE_TEXT_CHARS,
11
- RECENT_MAX_OFFSET,
12
- RECENT_PAGE,
13
8
  SPEAKER_FIELD,
14
9
  VIEW_ERROR,
15
10
  VIEW_METHODS,
16
11
  } from "./contracts.js"
12
+ import { createRecordsReads, recordsFailureWords } from "./records-reads.js"
13
+ import { SPACE_KINDS, ViewRefusal, clip, clipText, idOf, refuse, spaceOf } from "./shape.js"
14
+ import { createHeldInboxDecision } from "./inbox-decision.js"
15
+
16
+ // Jelly has no Inbox action route, signed-grant verifier, or ask bridge yet (#33).
17
+ // Never enable in production until all three are available and independently verified.
18
+ export const INBOX_ACTION_RPC_ENABLED = false
17
19
 
18
20
  /**
19
21
  * The RPC behind Memory's views in Jelly (`views/*.html`).
@@ -53,56 +55,15 @@ export const VIEW_UNLINKED_SENTENCE = "Memory is unavailable: you have not linke
53
55
  const MAX_AGENTS = 4
54
56
  /** The engine's agent list is read again after this long. */
55
57
  const AGENT_TTL_MS = 60_000
56
- /** Upstream answers at most this many rows per query. */
57
- const QUERY_MAX = 100
58
58
  /** A page's text is held well under Jelly's 64 KB answer cap. */
59
59
  const PAGE_TEXT_BYTES = 56_000
60
- const ID = new RegExp(ID_PATTERN)
61
-
62
- /** A refusal in the plugin's own words, which the page shows. */
63
- class ViewRefusal extends Error {}
64
60
 
65
- const refuse = (words) => {
66
- throw new ViewRefusal(words)
67
- }
68
-
69
- /** One line, at most `max` characters, never ending in half a surrogate pair. */
70
- function clip(value, max) {
71
- const text = oneLine(value, max)
72
- return /[\uD800-\uDBFF]…$/.test(text) ? `${text.slice(0, -2)}…` : text
73
- }
74
-
75
- /** Multi-line text, at most `chars` characters and `bytes` UTF-8 bytes. */
76
- function clipText(value, chars, bytes) {
77
- let text = String(value ?? "")
78
- let clipped = false
79
- if (text.length > chars) {
80
- text = text.slice(0, chars)
81
- clipped = true
82
- }
83
- while (Buffer.byteLength(text) > bytes) {
84
- text = text.slice(0, Math.floor(text.length * 0.9))
85
- clipped = true
86
- }
87
- if (clipped && /[\uD800-\uDBFF]$/.test(text)) text = text.slice(0, -1)
88
- return { text, clipped }
89
- }
90
-
91
- /** An id the schema accepts, or "". */
92
- function idOf(value) {
93
- const text = String(value ?? "").trim()
94
- return ID.test(text) ? text : ""
95
- }
96
-
97
- const SPACE_KINDS = new Set(["personal", "shared"])
98
-
99
- function spaceOf(context) {
100
- if (!context) return { id: "local", name: "Local memory", kind: "personal" }
101
- return {
102
- id: idOf(context.space_id) || "unknown",
103
- name: clip(context.space_name || context.space_id || "Your memory", 200),
104
- kind: SPACE_KINDS.has(context.space_kind) ? context.space_kind : "unknown",
105
- }
61
+ function inboxTime(value) {
62
+ const match = /^(\d{4})-(\d\d)-(\d\d)T(\d\d):(\d\d):(\d\d)(?:\.\d+)?(?:Z|([+-])(\d\d):(\d\d))$/.exec(value)
63
+ if (!match) return false
64
+ const [, year, month, day, hour, minute, second, , offsetHour, offsetMinute] = match
65
+ const date = new Date(Date.UTC(Number(year), Number(month) - 1, Number(day)))
66
+ return date.getUTCFullYear() === Number(year) && date.getUTCMonth() + 1 === Number(month) && date.getUTCDate() === Number(day) && Number(hour) < 24 && Number(minute) < 60 && Number(second) < 60 && Number(offsetHour ?? 0) < 24 && Number(offsetMinute ?? 0) < 60
106
67
  }
107
68
 
108
69
  const CREDENTIALS = Object.freeze({
@@ -190,11 +151,14 @@ export function createViewReads({ runtime, agents = async () => [] }) {
190
151
  }
191
152
  }
192
153
 
154
+ const recordsReads = createRecordsReads({ runtime, personalScopes, available })
155
+
193
156
  async function overview() {
194
157
  const address = originOf(String(config.controlURL ?? "")) || originOf(String(config.baseURL ?? "").replace(/\/core$/, ""))
195
158
  const base = {
196
159
  capture: config.capture !== false,
197
160
  health: "unknown",
161
+ extraction: "unknown",
198
162
  ...(address ? { address: clip(address, 300) } : {}),
199
163
  }
200
164
  const reason = await unavailableNow()
@@ -212,13 +176,18 @@ export function createViewReads({ runtime, agents = async () => [] }) {
212
176
  ...base,
213
177
  }
214
178
  }
179
+ // Memories are records from 0.9 (the space's count); conversations,
180
+ // summaries and the profile are still the core's, per agent.
215
181
  const count = (read) => read.then((data) => Number(data?.total) || 0).catch(() => 0)
216
- const [health, perAgent] = await Promise.all([
182
+ const [health, kept, perAgent, extraction] = await Promise.all([
217
183
  backend.probe().catch(() => ({ ok: false })),
184
+ recordsReads.memoryCount(scopes[0]).catch((error) => {
185
+ runtime.log?.warn?.("view overview: records count failed", error)
186
+ return { memories: 0 }
187
+ }),
218
188
  Promise.all(
219
189
  scopes.map(({ scope }) =>
220
190
  Promise.all([
221
- count(backend.countAtoms({ scope })),
222
191
  count(backend.countConversations({ scope })),
223
192
  count(backend.countScenarios({ scope })),
224
193
  backend
@@ -228,10 +197,10 @@ export function createViewReads({ runtime, agents = async () => [] }) {
228
197
  ]),
229
198
  ),
230
199
  ),
200
+ runtime.control && typeof backend.extractionHealth === "function" ? backend.extractionHealth().catch(() => null) : null,
231
201
  ])
232
- const counts = { memories: 0, conversations: 0, summaries: 0, profile: false }
233
- for (const [memories, conversations, summaries, profile] of perAgent) {
234
- counts.memories += memories
202
+ const counts = { memories: kept.memories, conversations: 0, summaries: 0, profile: false }
203
+ for (const [conversations, summaries, profile] of perAgent) {
235
204
  counts.conversations += conversations
236
205
  counts.summaries += summaries
237
206
  counts.profile ||= profile
@@ -241,6 +210,9 @@ export function createViewReads({ runtime, agents = async () => [] }) {
241
210
  ...credentialState(),
242
211
  ...base,
243
212
  health: health?.ok ? "ok" : "unreachable",
213
+ extraction: ["healthy", "failing", "unknown"].includes(extraction?.state) ? extraction.state : "unknown",
214
+ ...(extraction?.state === "failing" && typeof extraction.failing_since === "string" && /^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d\.\d{3}Z$/.test(extraction.failing_since) ? { failing_since: extraction.failing_since } : {}),
215
+ ...(kept.records ? { records: kept.records } : {}),
244
216
  space: spaceOf(scopes[0]?.context),
245
217
  counts,
246
218
  }
@@ -263,45 +235,6 @@ export function createViewReads({ runtime, agents = async () => [] }) {
263
235
  }
264
236
  }
265
237
 
266
- /**
267
- * The newest memories (L1 atoms) of the personal space, newest first, across
268
- * the agents a view reads under. Each agent's newest `offset + page + 1` are
269
- * merged, so a page is exact: upstream answers at most 100 rows a query,
270
- * which is as deep as the screen goes (two pages, `RECENT_MAX_OFFSET`).
271
- */
272
- async function recent(input) {
273
- await available()
274
- const offset = input?.offset ?? 0
275
- if (typeof offset !== "number" || !Number.isInteger(offset) || offset < 0 || offset > RECENT_MAX_OFFSET || offset % RECENT_PAGE !== 0) {
276
- refuse(`offset is a multiple of ${RECENT_PAGE} from 0 to ${RECENT_MAX_OFFSET}`)
277
- }
278
- const scopes = await personalScopes()
279
- const want = Math.min(QUERY_MAX, offset + RECENT_PAGE + 1)
280
- const pages = await Promise.all(
281
- scopes.map(({ scope }) =>
282
- backend.queryAtoms({ scope, limit: want, offset: 0 }).then((data) =>
283
- (data?.items ?? []).map((item) => ({ item })),
284
- ),
285
- ),
286
- )
287
- const when = ({ item }) => String(item?.updated_at ?? item?.created_at ?? "")
288
- const rows = pages
289
- .flat()
290
- .filter(({ item }) => idOf(item?.id))
291
- .sort((a, b) => when(b).localeCompare(when(a)))
292
- const page = rows.slice(offset, offset + RECENT_PAGE)
293
- return {
294
- space: spaceOf(scopes[0]?.context),
295
- items: page.map(({ item }) => ({
296
- id: idOf(item.id),
297
- text: clip(item.content, MEMORY_TEXT_CHARS),
298
- type: clip(item.type ?? "memory", 40),
299
- at: clip(item.updated_at ?? item.created_at ?? "", 40),
300
- })),
301
- more: offset + RECENT_PAGE <= RECENT_MAX_OFFSET && rows.length > offset + RECENT_PAGE,
302
- }
303
- }
304
-
305
238
  /** The knowledge scope: wikis belong to the space, not to an agent. */
306
239
  async function knowledgeScope() {
307
240
  const [first] = await personalScopes()
@@ -402,14 +335,25 @@ export function createViewReads({ runtime, agents = async () => [] }) {
402
335
  }
403
336
  }
404
337
 
338
+ async function inboxList() {
339
+ const review = await recordsReads.methods["review.list"]({})
340
+ return { items: review.items.flatMap((item) => {
341
+ if (!/^rec_[0-9A-Za-z]{1,64}$/.test(item.id)) return []
342
+ if (!inboxTime(item.created)) return []
343
+ const title = String(item.title).replace(/[\p{Cc}\p{Cf}<>]/gu, " ").replace(/\s+/g, " ").trim().slice(0, 120)
344
+ return [{ key: `proposal:${item.id}`, category: "request", label: "Proposal", name: "Memory", line: title || "A proposal is waiting for review", at: item.created }]
345
+ }) }
346
+ }
347
+
405
348
  return {
406
349
  "commitments.list": commitmentsList,
350
+ "inbox.list": inboxList,
407
351
  "memory.overview": overview,
408
352
  "spaces.list": spacesList,
409
- "memories.recent": recent,
410
353
  "wiki.list": wikiList,
411
354
  "wiki.pages": wikiPages,
412
355
  "wiki.read": wikiRead,
356
+ ...recordsReads.methods,
413
357
  }
414
358
  }
415
359
 
@@ -425,7 +369,8 @@ function viewWords(reason) {
425
369
 
426
370
  /** A failed read in words; a view call's unlinked speaker in the view's words. */
427
371
  function viewFailureWords(error) {
428
- return isUnlinked(error) && inView() ? VIEW_UNLINKED_SENTENCE : failureWords(error)
372
+ if (isUnlinked(error) && inView()) return VIEW_UNLINKED_SENTENCE
373
+ return recordsFailureWords(error) || failureWords(error)
429
374
  }
430
375
 
431
376
  /**
@@ -494,7 +439,7 @@ export function splitSpeaker(input) {
494
439
  * @param {any} ctx
495
440
  * @param {any} runtime
496
441
  */
497
- export async function registerViewRpc(ctx, runtime) {
442
+ export async function registerViewRpc(ctx, runtime, { enableInboxActions = INBOX_ACTION_RPC_ENABLED, verifyInboxAction } = {}) {
498
443
  if (typeof ctx?.rpc?.register !== "function") return null
499
444
  const reads = createViewReads({ runtime, agents: engineAgents(ctx) })
500
445
  const methods = {}
@@ -515,5 +460,19 @@ export async function registerViewRpc(ctx, runtime) {
515
460
  return typeof speaker === "string" ? asView(speaker, read) : read()
516
461
  }
517
462
  }
463
+ if (enableInboxActions) {
464
+ if (typeof verifyInboxAction !== "function") throw new Error("Inbox actions require a grant verifier and ask bridge")
465
+ const decide = createHeldInboxDecision(runtime)
466
+ methods["act.inbox.decide"] = {
467
+ input: { type: "object", additionalProperties: false, required: ["key", "decision"], properties: { key: { type: "string" }, decision: { type: "string", enum: ["accept", "private", "decline"] } } },
468
+ output: { type: "object" },
469
+ }
470
+ handlers["act.inbox.decide"] = async (input, call) => {
471
+ // The verifier must validate the signed, input-bound grant and enforce the
472
+ // separate memory.revise ask; page-provided identity is never accepted.
473
+ const speaker = await verifyInboxAction({ input, call })
474
+ return decide({ key: input?.key, decision: input?.decision, caller: { runtime, speaker } })
475
+ }
476
+ }
518
477
  return ctx.rpc.register({ id: PACKAGE_NAME, events: {}, methods }, handlers)
519
478
  }
@@ -0,0 +1,61 @@
1
+ import { oneLine } from "../util.js"
2
+ import { ID_PATTERN } from "./contracts.js"
3
+
4
+ /**
5
+ * Small helpers every view read shares: refusals in the plugin's own words,
6
+ * and the clipping that holds each answer to its declared schema and under
7
+ * Jelly's 64 KB answer cap.
8
+ */
9
+
10
+ /** A refusal in the plugin's own words, which the page shows. */
11
+ export class ViewRefusal extends Error {}
12
+
13
+ /** @returns {never} */
14
+ export const refuse = (words) => {
15
+ throw new ViewRefusal(words)
16
+ }
17
+
18
+ /** One line, at most `max` characters, never ending in half a surrogate pair. */
19
+ export function clip(value, max) {
20
+ const text = oneLine(value, max)
21
+ return /[\uD800-\uDBFF]…$/.test(text) ? `${text.slice(0, -2)}…` : text
22
+ }
23
+
24
+ /** Multi-line text, at most `chars` characters and `bytes` UTF-8 bytes. */
25
+ export function clipText(value, chars, bytes) {
26
+ let text = String(value ?? "")
27
+ let clipped = false
28
+ if (text.length > chars) {
29
+ text = text.slice(0, chars)
30
+ clipped = true
31
+ }
32
+ while (Buffer.byteLength(text) > bytes) {
33
+ text = text.slice(0, Math.floor(text.length * 0.9))
34
+ clipped = true
35
+ }
36
+ if (clipped && /[\uD800-\uDBFF]$/.test(text)) text = text.slice(0, -1)
37
+ return { text, clipped }
38
+ }
39
+
40
+ const ID = new RegExp(ID_PATTERN)
41
+
42
+ /** An id the schema accepts, or "". */
43
+ export function idOf(value) {
44
+ const text = String(value ?? "").trim()
45
+ return ID.test(text) ? text : ""
46
+ }
47
+
48
+ export const SPACE_KINDS = new Set(["personal", "shared"])
49
+
50
+ /** The space an answer names, from a control context; local direct mode has one. */
51
+ export function spaceOf(context) {
52
+ if (!context) return { id: "local", name: "Local memory", kind: "personal" }
53
+ return {
54
+ id: idOf(context.space_id) || "unknown",
55
+ name: clip(context.space_name || context.space_id || "Your memory", 200),
56
+ kind: SPACE_KINDS.has(context.space_kind) ? context.space_kind : "unknown",
57
+ }
58
+ }
59
+
60
+ /** UTF-8 bytes of a value as JSON. */
61
+ export const jsonBytes = (value) => Buffer.byteLength(JSON.stringify(value))
@@ -2,6 +2,7 @@
2
2
  <html lang="en-GB">
3
3
  <head>
4
4
  <meta charset="utf-8">
5
+ <meta http-equiv="Content-Security-Policy" content="default-src 'none'; script-src 'sha256-5dtPKkjegOPG8bawdSzGBjixnIaSCLYcZOUAwbRWFAc=' 'sha256-ok3CmSN9UFtjvZkYSjfg8g06g5+3ayhEW8txJ9m7sXw='; style-src 'unsafe-inline'; base-uri 'none'; form-action 'none'">
5
6
  <title>Commitments</title>
6
7
  <style>
7
8
  :root {
@@ -131,6 +132,8 @@ const card = document.getElementById("card");
131
132
  const SHOWN = 8;
132
133
  let view = null;
133
134
 
135
+ // What every view says when the server has no records service (src/views/contracts.js).
136
+ const RECORDS_OFF = "This Memory server has no records service yet, so memories, journals, pages and review can't be shown. Ask whoever runs it to turn it on.";
134
137
  function el(tag, className, text) {
135
138
  const node = document.createElement(tag);
136
139
  if (className) node.className = className;
@@ -192,6 +195,7 @@ async function draw() {
192
195
  try {
193
196
  answer = await view.call("commitments.list", { state: "open" });
194
197
  } catch (error) {
198
+ if (error.message === RECORDS_OFF) return show(el("p", "muted", RECORDS_OFF));
195
199
  const retry = el("button", "button", "Try again");
196
200
  retry.type = "button";
197
201
  retry.addEventListener("click", draw);