@joe-broadhead/opencode-mem 0.8.5 → 0.9.0

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 (52) hide show
  1. package/CHANGELOG.md +429 -0
  2. package/README.md +114 -61
  3. package/docs/agent-protocol.md +67 -177
  4. package/package.json +1351 -98
  5. package/skills/mem.pages/SKILL.md +143 -0
  6. package/skills/mem.sharing/SKILL.md +82 -0
  7. package/skills/mem.sources/SKILL.md +93 -0
  8. package/skills/mem.usage/SKILL.md +118 -492
  9. package/src/backend/records.js +285 -0
  10. package/src/bootstrap.js +49 -45
  11. package/src/call-shapes.js +41 -10
  12. package/src/collector-lock.js +162 -0
  13. package/src/collector-service.js +441 -0
  14. package/src/collector.js +381 -0
  15. package/src/commands.js +3 -3
  16. package/src/config.js +12 -1
  17. package/src/curation.js +1 -1
  18. package/src/permissions.js +18 -2
  19. package/src/protocol.js +29 -20
  20. package/src/recall.js +104 -27
  21. package/src/records-store.js +280 -120
  22. package/src/records.js +63 -11
  23. package/src/runtime.js +23 -14
  24. package/src/skills.js +44 -18
  25. package/src/sources.js +58 -0
  26. package/src/spaces.js +93 -10
  27. package/src/tools/aliases.js +163 -0
  28. package/src/tools/commitments.js +12 -9
  29. package/src/tools/index.js +88 -19
  30. package/src/tools/ingest.js +277 -0
  31. package/src/tools/knowledge.js +6 -1
  32. package/src/tools/memory.js +640 -210
  33. package/src/tools/page.js +411 -0
  34. package/src/tools/recall.js +363 -112
  35. package/src/tools/records-kit.js +142 -0
  36. package/src/tools/share.js +1012 -0
  37. package/src/tools/shared.js +8 -1
  38. package/src/tools/spaces.js +431 -143
  39. package/src/tools/status.js +87 -58
  40. package/src/tools/wiki.js +2 -2
  41. package/src/views/contracts.js +273 -3
  42. package/src/views/records-reads.js +675 -0
  43. package/src/views/rpc.js +17 -100
  44. package/src/views/shape.js +61 -0
  45. package/views/commitments.html +4 -0
  46. package/views/graph.html +753 -0
  47. package/views/home.html +11 -5
  48. package/views/journal.html +621 -0
  49. package/views/memory.html +7 -1
  50. package/views/pages.html +636 -0
  51. package/views/review.html +406 -0
  52. package/views/today.html +309 -0
@@ -0,0 +1,675 @@
1
+ import { isRecordsUnavailable } from "../backend/records.js"
2
+ import {
3
+ EVIDENCE_MAX,
4
+ FIELDS_MAX,
5
+ FOLDERS_MAX,
6
+ GRAPH_EDGES_MAX,
7
+ GRAPH_NODES_MAX,
8
+ HISTORY_MAX,
9
+ JOURNAL_MAX,
10
+ JOURNAL_SOURCES_MAX,
11
+ LINEAGE_MAX,
12
+ LINKS_MAX,
13
+ MEMORY_TEXT_CHARS,
14
+ PAGES_MAX,
15
+ RECENT_MAX_OFFSET,
16
+ RECENT_PAGE,
17
+ RECORDS_OFF,
18
+ RECORD_BODY_CHARS,
19
+ REVIEW_MAX,
20
+ SUMMARY_CHARS,
21
+ } from "./contracts.js"
22
+ import { SPACE_KINDS, clip, clipText, idOf, jsonBytes, refuse, spaceOf } from "./shape.js"
23
+
24
+ /**
25
+ * The views' reads of the records service (docs/design/memory-v1-contracts.md
26
+ * §2.4): the newest memories (records of kind `memory`) and the overview's
27
+ * count of them, and the 0.9 views (Journal, Review, Pages, Graph and the Today
28
+ * tile). Every one goes through the runtime's records client
29
+ * (`runtime.recordsClient`, `src/backend/records.js`): the gateway's
30
+ * `/records/v1/<method>` with the credential chain's bearer, which inside a
31
+ * view call (`asView`) is the token of the person who opened the view. Only
32
+ * the reads in `VIEW_RECORDS_METHODS` are ever sent.
33
+ *
34
+ * A server without the records service (503 `records_unavailable`) gets one
35
+ * plain sentence, `RECORDS_OFF`, which every page shows as it is.
36
+ *
37
+ * The space is the person's personal space, or one they chose from
38
+ * `spaces.list`: a space id a view sends is checked against the spaces control
39
+ * lists for the person before anything is read, so a view names only what it
40
+ * was shown. The gateway and the records service decide access again.
41
+ *
42
+ * Every answer is held to its schema and under Jelly's 64 KB answer cap: a long
43
+ * body is clipped and says so, and a list stops early and says there is more.
44
+ * Text from the store is returned as text; the pages set it with `textContent`
45
+ * only, so nothing in a record or an event ever runs.
46
+ */
47
+
48
+ /** The records methods a view may read through; any other is refused before a request. */
49
+ export const VIEW_RECORDS_METHODS = Object.freeze([
50
+ "records.get",
51
+ "records.list",
52
+ "records.links",
53
+ "records.backlinks",
54
+ "records.history",
55
+ "review.list",
56
+ "space.stats",
57
+ ])
58
+
59
+ /** Each answer is held under this many bytes of JSON, below Jelly's 64 KB cap. */
60
+ const ANSWER_BYTES = 56_000
61
+ /** A journal's body is at most this many bytes, so its sources fit beside it. */
62
+ const JOURNAL_BODY_BYTES = 36_000
63
+ /** The newest pages the Pages view's top level counts folders from: three reads of 200. */
64
+ const FOLDER_SCAN_PAGES = 3
65
+ /** The folders the routines keep, shown first (memory-tools-v1.md §6). */
66
+ const KNOWN_FOLDERS = Object.freeze(["people", "projects", "teams", "topics", "runbooks", "decisions", "journal"])
67
+
68
+ const JOURNAL_PATH = /^journal\/(\d{4}-\d{2}-\d{2}|\d{4}-w\d{2}|\d{4}-\d{2})$/
69
+ const PAGE_PATH = /^[a-z0-9][a-z0-9-]{0,63}(\/[a-z0-9][a-z0-9-]{0,63}){0,3}$/
70
+ const FOLDER = /^[a-z0-9][a-z0-9-]{0,63}$/
71
+ const RECORD_ID = /^rec_[0-9A-Za-z]{1,64}$/
72
+ const RECORD_TYPE = /^[a-z_]{1,40}$/
73
+ const ISO_DAY = /^\d{4}-\d{2}-\d{2}$/
74
+ const URL_TEXT = /^https?:\/\/[^\s<>"']{1,290}$/
75
+ const STATED_BY = new Set(["person", "agent", "inferred", "external"])
76
+ const EDGE_TYPES = new Set(["link", "supersedes", "source"])
77
+ /** Fields that are the routine's bookkeeping, or shown elsewhere (links). */
78
+ const HIDDEN_FIELDS = new Set(["routine_key", "links", "run", "payload", "evidence"])
79
+
80
+ /** A records failure in words a person can act on, or "" when the status says enough. */
81
+ export function recordsFailureWords(error) {
82
+ const code = String(error?.code ?? "")
83
+ const status = Number(error?.status) || 0
84
+ if (isRecordsUnavailable(error) || code === "records_unavailable") return RECORDS_OFF
85
+ if (code === "not_found" || (status === 404 && code)) return "That isn't in this memory any more."
86
+ if (code === "space_access_denied" || code === "forbidden") return "Memory refused this read: you can't see that space."
87
+ return ""
88
+ }
89
+
90
+ /** The period of a journal path. */
91
+ function periodOf(stem) {
92
+ if (ISO_DAY.test(stem)) return "day"
93
+ return stem.includes("w") ? "week" : "month"
94
+ }
95
+
96
+ /** The Monday of ISO week `week` of `year`, as YYYY-MM-DD. */
97
+ function isoWeekMonday(year, week) {
98
+ const jan4 = new Date(Date.UTC(year, 0, 4))
99
+ const monday = new Date(jan4)
100
+ monday.setUTCDate(jan4.getUTCDate() - ((jan4.getUTCDay() + 6) % 7) + (week - 1) * 7)
101
+ return monday.toISOString().slice(0, 10)
102
+ }
103
+
104
+ /** The day a journal path covers when its fields name none. */
105
+ function dateOfStem(stem, period) {
106
+ if (period === "day") return stem
107
+ if (period === "month") return `${stem}-01`
108
+ const [year, week] = stem.split("-w").map(Number)
109
+ return isoWeekMonday(year, week)
110
+ }
111
+
112
+ /**
113
+ * Markdown to one plain line: citations dropped, `[[target|label]]` as its
114
+ * label (or the target's last part), emphasis and code marks dropped.
115
+ */
116
+ export function plainLine(text) {
117
+ return String(text ?? "")
118
+ .replace(/\[(?:turn|event) [^\]\s]+\]/g, "")
119
+ .replace(/\[\[([^\]|]+)\|([^\]]+)\]\]/g, "$2")
120
+ .replace(/\[\[([^\]]+)\]\]/g, (_, target) => target.split("/").pop())
121
+ .replace(/\[([^\]]+)\]\([^)]*\)/g, "$1")
122
+ .replace(/<(https?:\/\/[^>\s]+)>/g, "$1")
123
+ .replace(/[*_`]+/g, "")
124
+ .replace(/\s+/g, " ")
125
+ .replace(/ ([.,;:!?])/g, "$1")
126
+ .trim()
127
+ }
128
+
129
+ /** A journal's summary: the first paragraph under `## Summary`, else the first line of text. */
130
+ export function summaryOf(body) {
131
+ const lines = String(body ?? "").split("\n")
132
+ const at = lines.findIndex((line) => /^##\s+Summary\s*$/i.test(line.trim()))
133
+ const from = at >= 0 ? at + 1 : 0
134
+ for (const line of lines.slice(from)) {
135
+ const text = line.trim()
136
+ if (!text) continue
137
+ if (/^#{1,6}\s/.test(text)) {
138
+ if (at >= 0) break
139
+ continue
140
+ }
141
+ if (/^(?:[-*]\s|---|<)/.test(text)) continue
142
+ return plainLine(text)
143
+ }
144
+ return ""
145
+ }
146
+
147
+ /**
148
+ * A journal body split into what the page renders as Markdown, the cited
149
+ * sources listed under `## Sources` (each `- source · title · <url> [event
150
+ * evt_…]`), and the footer line after the last `---`.
151
+ */
152
+ export function splitJournal(body) {
153
+ const lines = String(body ?? "").split("\n")
154
+ let footer = ""
155
+ const rule = lines.findLastIndex((line) => line.trim() === "---")
156
+ if (rule >= 0) {
157
+ const after = lines.slice(rule + 1).map((line) => line.trim()).filter(Boolean)
158
+ if (after.length === 1 && /^_.*_$/.test(after[0])) {
159
+ footer = after[0].slice(1, -1).trim()
160
+ lines.length = rule
161
+ }
162
+ }
163
+ const sources = []
164
+ const start = lines.findIndex((line) => /^##\s+Sources\s*$/i.test(line.trim()))
165
+ if (start >= 0) {
166
+ let end = lines.findIndex((line, index) => index > start && /^##\s/.test(line.trim()))
167
+ if (end < 0) end = lines.length
168
+ for (const line of lines.slice(start + 1, end)) {
169
+ const match = /^\s*[-*]\s+(.*?)\s*\[(event|turn) ([^\]\s]+)\]\s*$/.exec(line)
170
+ if (!match) continue
171
+ const ref = idOf(match[3])
172
+ if (!ref) continue
173
+ const parts = match[1].split(" · ").map((part) => part.trim())
174
+ const entry = { ref, kind: match[2], source: clip(parts.shift() ?? "", 40), title: "", url: "" }
175
+ for (const part of parts) {
176
+ const address = /^<(.+)>$/.exec(part)?.[1]
177
+ if (address && URL_TEXT.test(address)) entry.url = address
178
+ else if (!entry.title) entry.title = clip(part, 160)
179
+ }
180
+ sources.push(entry)
181
+ }
182
+ lines.splice(start, end - start)
183
+ }
184
+ while (lines.length > 0 && !lines.at(-1).trim()) lines.pop()
185
+ return { body: lines.join("\n"), sources, footer }
186
+ }
187
+
188
+ /** A record's fields as name and value lines, for the page's field list. */
189
+ export function fieldLines(fields) {
190
+ const out = []
191
+ const value = (inner) => {
192
+ if (inner === null || inner === undefined || inner === "") return ""
193
+ if (typeof inner === "boolean") return inner ? "yes" : "no"
194
+ if (Array.isArray(inner)) return inner.map(value).filter(Boolean).join(", ")
195
+ if (typeof inner === "object") {
196
+ return Object.entries(inner)
197
+ .map(([key, item]) => (value(item) ? `${key}: ${value(item)}` : ""))
198
+ .filter(Boolean)
199
+ .join(", ")
200
+ }
201
+ return String(inner)
202
+ }
203
+ for (const [name, inner] of Object.entries(fields && typeof fields === "object" ? fields : {})) {
204
+ if (HIDDEN_FIELDS.has(name)) continue
205
+ const text = value(inner)
206
+ if (text) out.push({ name: clip(name.replaceAll("_", " "), 40), value: clip(text, 300) })
207
+ if (out.length >= FIELDS_MAX) break
208
+ }
209
+ return out
210
+ }
211
+
212
+ /** The text accepting a proposal would apply. */
213
+ function proposedText(proposal) {
214
+ const payload = proposal?.fields?.payload
215
+ if (typeof payload === "string") return payload
216
+ if (payload && typeof payload === "object") {
217
+ const parts = [payload.title, payload.fields?.what, payload.body].filter((part) => typeof part === "string" && part.trim())
218
+ if (parts.length > 0) return [...new Set(parts)].join("\n\n")
219
+ }
220
+ return String(proposal?.title ?? "")
221
+ }
222
+
223
+ /** Keep adding items while the whole answer stays under the byte cap; whether any were left out. */
224
+ function fitList(answer, key, items) {
225
+ let fitted = false
226
+ for (const item of items) {
227
+ answer[key].push(item)
228
+ if (jsonBytes(answer) > ANSWER_BYTES) {
229
+ answer[key].pop()
230
+ fitted = true
231
+ break
232
+ }
233
+ }
234
+ return fitted
235
+ }
236
+
237
+ /** The fact a memory record states: its body before "Why:", else its title (as `mem_recall` reads it). */
238
+ function factOf(record) {
239
+ const body = String(record?.body ?? "").split(/\n\s*\nWhy:/)[0].trim()
240
+ return body || String(record?.title ?? "").trim()
241
+ }
242
+
243
+ /**
244
+ * The memories `space.stats` counts: current and contested, the ones a default
245
+ * read shows. The records service answers `records.by_kind.memory` by status;
246
+ * the stub's fake answers `by_kind.memory` as one number.
247
+ */
248
+ export function memoriesIn(stats) {
249
+ const byKind = stats?.records?.by_kind ?? stats?.by_kind ?? {}
250
+ const memory = byKind?.memory
251
+ if (typeof memory === "number") return Math.max(0, Math.floor(memory))
252
+ if (memory && typeof memory === "object") return ["current", "contested"].reduce((sum, status) => sum + Math.max(0, Math.floor(Number(memory[status]) || 0)), 0)
253
+ return 0
254
+ }
255
+
256
+ /**
257
+ * @param {{ runtime: any, personalScopes: () => Promise<Array<{ context: any }>>, available: () => Promise<void> }} input
258
+ */
259
+ export function createRecordsReads({ runtime, personalScopes, available }) {
260
+ /** A records call's options for one of `personalScopes()`'s entries. */
261
+ const whereOf = (entry) => ({
262
+ ...(entry?.scope ? { scope: entry.scope } : {}),
263
+ ...(entry?.context?.space_id ? { space: entry.context.space_id } : {}),
264
+ })
265
+
266
+ /** One records read, through the runtime's records client; a build without one has no records. */
267
+ function records(method, body, where) {
268
+ if (!VIEW_RECORDS_METHODS.includes(method)) refuse("A view only reads.")
269
+ if (typeof runtime.recordsClient?.call !== "function") refuse(RECORDS_OFF)
270
+ return runtime.recordsClient.call(method, body, where)
271
+ }
272
+
273
+ /**
274
+ * Where a read goes: the personal space, or a space of the person's that the
275
+ * view names. Each read carries the person's scope, without its session, as
276
+ * the tools' reads do (`callRecords`): in local direct mode the scope is what
277
+ * names the store, and through the gateway it is only a hint.
278
+ */
279
+ async function target(input) {
280
+ const [first] = await personalScopes()
281
+ const scope = first?.scope
282
+ if (input?.space !== undefined) {
283
+ const spaceId = idOf(input.space)
284
+ if (!spaceId) refuse("That is not a space id.")
285
+ if (!runtime.control) refuse("This memory has one space, your own.")
286
+ const spaces = await runtime.control.listSpaces({ userId: runtime.config?.user })
287
+ const found = (spaces ?? []).find((space) => space?.space_id === spaceId)
288
+ if (!found) refuse("That space isn't one of yours.")
289
+ return {
290
+ where: { ...(scope ? { scope } : {}), space: spaceId },
291
+ space: { id: spaceId, name: clip(found.name || spaceId, 200), kind: SPACE_KINDS.has(found.kind) ? found.kind : "unknown" },
292
+ }
293
+ }
294
+ return { where: whereOf(first), space: spaceOf(first?.context ?? null) }
295
+ }
296
+
297
+ /** `{ path }` or `{ id }` from a view's input; one of them, checked. */
298
+ function recordRef(input) {
299
+ const path = input?.path === undefined ? "" : String(input.path).trim()
300
+ const id = input?.id === undefined ? "" : String(input.id).trim()
301
+ if (path && id) refuse("Name a page or a record, not both.")
302
+ if (path) {
303
+ if (!PAGE_PATH.test(path)) refuse("That is not a page path.")
304
+ return { path }
305
+ }
306
+ if (id) {
307
+ if (!RECORD_ID.test(id)) refuse("That is not a record id.")
308
+ return { id }
309
+ }
310
+ return refuse("Name a page or a record.")
311
+ }
312
+
313
+ /**
314
+ * The newest memories of the personal space, newest first: records of kind
315
+ * `memory` (current and contested), 50 a page, two pages deep, as 0.8's list
316
+ * of atoms was. A memory's text is the fact it states, without its "Why:".
317
+ */
318
+ async function memoriesRecent(input) {
319
+ await available()
320
+ const offset = input?.offset ?? 0
321
+ if (typeof offset !== "number" || !Number.isInteger(offset) || offset < 0 || offset > RECENT_MAX_OFFSET || offset % RECENT_PAGE !== 0) {
322
+ refuse(`offset is a multiple of ${RECENT_PAGE} from 0 to ${RECENT_MAX_OFFSET}`)
323
+ }
324
+ const where = await target({})
325
+ const answer = await records("records.list", { kind: "memory", limit: offset + RECENT_PAGE + 1 }, where.where)
326
+ const rows = (answer?.records ?? []).filter((record) => idOf(record?.id))
327
+ return {
328
+ space: where.space,
329
+ items: rows.slice(offset, offset + RECENT_PAGE).map((record) => ({
330
+ id: idOf(record.id),
331
+ text: clip(factOf(record), MEMORY_TEXT_CHARS),
332
+ type: clip(record.type ?? "memory", 40),
333
+ at: clip(record.updated ?? record.created ?? "", 40),
334
+ })),
335
+ more: offset + RECENT_PAGE <= RECENT_MAX_OFFSET && rows.length > offset + RECENT_PAGE,
336
+ }
337
+ }
338
+
339
+ /**
340
+ * How many memories the personal space keeps (`entry` is the first of
341
+ * `personalScopes()`), for the overview: `{ memories,
342
+ * records: "ok" }`, or `records: "unavailable"` (and no count) on a server
343
+ * without the records service. Any other failure is thrown.
344
+ */
345
+ async function memoryCount(entry) {
346
+ try {
347
+ return { memories: memoriesIn(await records("space.stats", {}, whereOf(entry))), records: "ok" }
348
+ } catch (error) {
349
+ if (isRecordsUnavailable(error) || error?.code === "records_unavailable" || error?.message === RECORDS_OFF) return { memories: 0, records: "unavailable" }
350
+ throw error
351
+ }
352
+ }
353
+
354
+ function journalEntry(record) {
355
+ const path = String(record?.path ?? "")
356
+ const match = JOURNAL_PATH.exec(path)
357
+ if (!match) return null
358
+ const period = periodOf(match[1])
359
+ const named = String(record.fields?.date ?? "")
360
+ return {
361
+ path,
362
+ title: clip(record.title || path, 200),
363
+ period,
364
+ date: ISO_DAY.test(named) ? named : dateOfStem(match[1], period),
365
+ edited: record.fields?.edited === true,
366
+ summary: clip(summaryOf(record.body), SUMMARY_CHARS),
367
+ updated: clip(record.updated ?? "", 40),
368
+ }
369
+ }
370
+
371
+ async function journalList(input) {
372
+ await available()
373
+ const wanted = input?.period
374
+ if (wanted !== undefined && !["day", "week", "month"].includes(wanted)) refuse("period is day, week or month.")
375
+ const where = await target(input)
376
+ const answer = await records("records.list", { kind: "page", type: "journal", path_prefix: "journal/", limit: 200 }, where.where)
377
+ const order = { day: 0, week: 1, month: 2 }
378
+ const entries = (answer?.records ?? [])
379
+ .map(journalEntry)
380
+ .filter((entry) => entry && (!wanted || entry.period === wanted))
381
+ .sort((a, b) => b.date.localeCompare(a.date) || order[a.period] - order[b.period] || b.path.localeCompare(a.path))
382
+ const out = { space: where.space, items: [], more: false }
383
+ const fitted = fitList(out, "items", entries.slice(0, JOURNAL_MAX))
384
+ out.more = fitted || entries.length > JOURNAL_MAX || Boolean(answer?.cursor)
385
+ return out
386
+ }
387
+
388
+ async function journalRead(input) {
389
+ await available()
390
+ const path = String(input?.path ?? "").trim()
391
+ if (!JOURNAL_PATH.test(path)) refuse("That is not a journal page.")
392
+ const where = await target(input)
393
+ const answer = await records("records.get", { paths: [path] }, where.where)
394
+ const record = (answer?.records ?? []).find((entry) => entry?.path === path)
395
+ if (!record) refuse("That journal page isn't in this memory.")
396
+ const entry = journalEntry(record)
397
+ const split = splitJournal(record.body)
398
+ const { text, clipped } = clipText(split.body, RECORD_BODY_CHARS, JOURNAL_BODY_BYTES)
399
+ const tokens = /([\d,]+) of ([\d,]+) tokens/.exec(split.footer)
400
+ const number = (value) => Math.max(0, Number.parseInt(String(value).replaceAll(",", ""), 10) || 0)
401
+ const counts = Object.entries(record.fields?.sources && typeof record.fields.sources === "object" ? record.fields.sources : {})
402
+ .map(([source, count]) => ({ source: clip(source, 40), count: number(count) }))
403
+ .slice(0, 20)
404
+ const out = {
405
+ space: where.space,
406
+ path,
407
+ title: entry.title,
408
+ period: entry.period,
409
+ date: entry.date,
410
+ edited: entry.edited,
411
+ updated: entry.updated,
412
+ body: text,
413
+ clipped,
414
+ sources: [],
415
+ footer: {
416
+ routine: clip(record.fields?.routine ?? "", 40),
417
+ counts,
418
+ ...(tokens ? { tokens: number(tokens[1]), budget: number(tokens[2]) } : {}),
419
+ line: clip(split.footer, 600),
420
+ },
421
+ }
422
+ fitList(out, "sources", split.sources.slice(0, JOURNAL_SOURCES_MAX))
423
+ return out
424
+ }
425
+
426
+ function proposalItem(proposal) {
427
+ const fields = proposal?.fields && typeof proposal.fields === "object" ? proposal.fields : {}
428
+ const stated = STATED_BY.has(proposal?.stated_by) ? proposal.stated_by : "unknown"
429
+ const evidence = (Array.isArray(fields.evidence) ? fields.evidence : [])
430
+ .map((item) => {
431
+ const kind = ["event", "turn", "record"].find((name) => typeof item?.[name] === "string")
432
+ const ref = kind ? idOf(item[kind]) : ""
433
+ return kind && ref ? { kind, ref, quote: clip(item.quote ?? "", 300) } : null
434
+ })
435
+ .filter(Boolean)
436
+ .slice(0, EVIDENCE_MAX)
437
+ return {
438
+ id: idOf(proposal.id),
439
+ action: clip(fields.action || proposal.type || "", 40),
440
+ title: clip(proposal.title ?? "", 200),
441
+ target: clip(fields.target_path || fields.target_id || "", 200),
442
+ reason: clip(fields.reason ?? "", 300),
443
+ stated_by: stated,
444
+ external: stated === "external",
445
+ evidence,
446
+ proposed: clipText(proposedText(proposal), 600, 1800).text,
447
+ expires: clip(fields.expires ?? "", 40),
448
+ created: clip(proposal.created ?? "", 40),
449
+ }
450
+ }
451
+
452
+ async function reviewList(input) {
453
+ await available()
454
+ const where = await target(input)
455
+ const answer = await records("review.list", { limit: REVIEW_MAX + 1 }, where.where)
456
+ const proposals = (answer?.proposals ?? []).filter((proposal) => idOf(proposal?.id))
457
+ const out = { space: where.space, items: [], more: false }
458
+ const fitted = fitList(out, "items", proposals.slice(0, REVIEW_MAX).map(proposalItem))
459
+ out.more = fitted || proposals.length > REVIEW_MAX
460
+ return out
461
+ }
462
+
463
+ const pageRow = (record) => ({
464
+ path: idOf(record.path),
465
+ title: clip(record.title || record.path, 200),
466
+ type: clip(record.type ?? "", 40),
467
+ updated: clip(record.updated ?? "", 40),
468
+ })
469
+
470
+ async function pagesList(input) {
471
+ await available()
472
+ let folder = ""
473
+ if (input?.folder !== undefined && input.folder !== "") {
474
+ folder = String(input.folder).trim().replace(/\/$/, "")
475
+ if (!FOLDER.test(folder)) refuse("That is not a folder.")
476
+ }
477
+ const where = await target(input)
478
+ if (folder) {
479
+ const answer = await records("records.list", { kind: "page", path_prefix: `${folder}/`, limit: 200 }, where.where)
480
+ const rows = (answer?.records ?? []).filter((record) => idOf(record?.path)).map(pageRow)
481
+ rows.sort((a, b) => a.title.localeCompare(b.title, "en-GB"))
482
+ const out = { space: where.space, folder, folders: [], pages: [], more: false }
483
+ const fitted = fitList(out, "pages", rows.slice(0, PAGES_MAX))
484
+ out.more = fitted || rows.length > PAGES_MAX || Boolean(answer?.cursor)
485
+ return out
486
+ }
487
+ // The top: the folders the newest pages are in, and the pages in none (`index`).
488
+ const all = []
489
+ let cursor
490
+ for (let read = 0; read < FOLDER_SCAN_PAGES; read += 1) {
491
+ const answer = await records("records.list", { kind: "page", limit: 200, ...(cursor ? { cursor } : {}) }, where.where)
492
+ all.push(...(answer?.records ?? []))
493
+ cursor = answer?.cursor
494
+ if (!cursor) break
495
+ }
496
+ const counts = new Map()
497
+ const top = []
498
+ for (const record of all) {
499
+ const path = idOf(record?.path)
500
+ if (!path) continue
501
+ if (path.includes("/")) {
502
+ const name = path.split("/")[0]
503
+ counts.set(name, (counts.get(name) ?? 0) + 1)
504
+ } else top.push(pageRow(record))
505
+ }
506
+ const rank = (name) => (KNOWN_FOLDERS.includes(name) ? KNOWN_FOLDERS.indexOf(name) : KNOWN_FOLDERS.length)
507
+ const folders = [...counts.entries()]
508
+ .sort(([a], [b]) => rank(a) - rank(b) || a.localeCompare(b))
509
+ .slice(0, FOLDERS_MAX)
510
+ .map(([name, count]) => ({ name: clip(name, 64), count }))
511
+ top.sort((a, b) => (a.path === "index" ? -1 : b.path === "index" ? 1 : a.title.localeCompare(b.title, "en-GB")))
512
+ const out = { space: where.space, folder: "", folders, pages: [], more: false }
513
+ const fitted = fitList(out, "pages", top.slice(0, PAGES_MAX))
514
+ out.more = fitted || Boolean(cursor) || top.length > PAGES_MAX
515
+ return out
516
+ }
517
+
518
+ async function pagesRead(input) {
519
+ await available()
520
+ const ref = recordRef(input)
521
+ const where = await target(input)
522
+ const answer = await records("records.get", ref.path ? { paths: [ref.path] } : { ids: [ref.id] }, where.where)
523
+ const record = (answer?.records ?? [])[0]
524
+ if (!record || !idOf(record.id)) refuse(ref.path ? "That page isn't in this memory." : "That record isn't in this memory.")
525
+ const targets = [...new Set((Array.isArray(record.links) ? record.links : []).map((link) => String(link ?? "").trim()).filter(Boolean))].slice(0, LINKS_MAX)
526
+ const linkIds = targets.filter((target) => RECORD_ID.test(target))
527
+ const linkPaths = targets.filter((target) => !RECORD_ID.test(target) && PAGE_PATH.test(target))
528
+ const [linked, back] = await Promise.all([
529
+ targets.length > 0
530
+ ? records("records.get", { ...(linkIds.length ? { ids: linkIds } : {}), ...(linkPaths.length ? { paths: linkPaths } : {}) }, where.where).catch(() => ({ records: [] }))
531
+ : { records: [] },
532
+ record.path ? records("records.backlinks", { path: record.path }, where.where).catch(() => ({ records: [] })) : { records: [] },
533
+ ])
534
+ const known = new Map()
535
+ for (const found of linked?.records ?? []) {
536
+ if (found?.id) known.set(found.id, found)
537
+ if (found?.path) known.set(found.path, found)
538
+ }
539
+ const backlinks = (back?.records ?? []).filter((found) => idOf(found?.id) && found.id !== record.id)
540
+ const out = {
541
+ space: where.space,
542
+ id: idOf(record.id),
543
+ path: clip(record.path ?? "", 200),
544
+ kind: clip(record.kind ?? "", 20),
545
+ type: clip(record.type ?? "", 40),
546
+ title: clip(record.title || record.path || record.id, 200),
547
+ status: clip(record.status ?? "", 20),
548
+ stated_by: clip(record.stated_by ?? "", 20),
549
+ updated: clip(record.updated ?? "", 40),
550
+ version: Math.max(0, Math.floor(Number(record.version) || 0)),
551
+ fields: fieldLines(record.fields),
552
+ body: "",
553
+ clipped: false,
554
+ outlinks: targets.map((target) => {
555
+ const found = known.get(target)
556
+ return { target: clip(target, 200), title: clip(found?.title || "", 200), exists: Boolean(found) }
557
+ }),
558
+ backlinks: backlinks.slice(0, LINKS_MAX).map((found) => ({
559
+ id: idOf(found.id),
560
+ path: clip(found.path ?? "", 200),
561
+ title: clip(found.title || found.path || found.id, 200),
562
+ type: clip(found.type ?? "", 40),
563
+ })),
564
+ backlinksMore: backlinks.length > LINKS_MAX || back?.truncated === true,
565
+ }
566
+ const room = Math.max(4_000, ANSWER_BYTES - jsonBytes(out))
567
+ const { text, clipped } = clipText(record.body ?? "", RECORD_BODY_CHARS, room)
568
+ out.body = text
569
+ out.clipped = clipped
570
+ return out
571
+ }
572
+
573
+ async function pagesHistory(input) {
574
+ await available()
575
+ const id = String(input?.id ?? "").trim()
576
+ if (!RECORD_ID.test(id)) refuse("That is not a record id.")
577
+ const where = await target(input)
578
+ const answer = await records("records.history", { id }, where.where)
579
+ const changeWords = (change) => {
580
+ if (!change || typeof change !== "object") return ""
581
+ const by = change.by?.agent ? ` by ${change.by.agent}` : ""
582
+ const why = change.reason ? `: ${change.reason}` : change.section ? `: ${change.section}` : ""
583
+ return `${change.action ?? "changed"}${by}${why}`
584
+ }
585
+ const lineage = (items) =>
586
+ (Array.isArray(items) ? items : [])
587
+ .filter((item) => idOf(item?.id))
588
+ .slice(0, LINEAGE_MAX)
589
+ .map((item) => ({ id: idOf(item.id), title: clip(item.missing ? "(deleted)" : item.title || item.id, 200), status: clip(item.status ?? "", 20) }))
590
+ return {
591
+ id,
592
+ versions: (Array.isArray(answer?.versions) ? answer.versions : []).slice(0, HISTORY_MAX).map((version) => ({
593
+ version: Math.max(0, Math.floor(Number(version?.version) || 0)),
594
+ updated: clip(version?.updated ?? "", 40),
595
+ title: clip(version?.title ?? "", 200),
596
+ status: clip(version?.status ?? "", 20),
597
+ change: clip(changeWords(version?.change), 200),
598
+ })),
599
+ supersedes: lineage(answer?.lineage?.supersedes),
600
+ supersededBy: lineage(answer?.lineage?.superseded_by),
601
+ }
602
+ }
603
+
604
+ async function graphLinks(input) {
605
+ await available()
606
+ const ref = recordRef(input)
607
+ const depth = input?.depth ?? 1
608
+ if (depth !== 1 && depth !== 2) refuse("depth is 1 or 2.")
609
+ const max = input?.max ?? 80
610
+ if (!Number.isInteger(max) || max < 10 || max > GRAPH_NODES_MAX) refuse(`max is a whole number from 10 to ${GRAPH_NODES_MAX}.`)
611
+ const types = input?.types ?? []
612
+ if (!Array.isArray(types) || types.length > 20 || types.some((type) => typeof type !== "string" || !RECORD_TYPE.test(type))) refuse("types are record types such as person or decision.")
613
+ const where = await target(input)
614
+ const answer = await records(
615
+ "records.links",
616
+ { ...(ref.path ? { path: ref.path } : { id: ref.id }), depth, max_nodes: max, ...(types.length ? { types } : {}) },
617
+ where.where,
618
+ )
619
+ const nodes = []
620
+ const index = new Map()
621
+ for (const node of Array.isArray(answer?.nodes) ? answer.nodes : []) {
622
+ const key = String(node?.id ?? node?.path ?? "")
623
+ if (!key || index.has(key) || nodes.length >= GRAPH_NODES_MAX) continue
624
+ const record = RECORD_ID.test(String(node.id ?? ""))
625
+ index.set(key, nodes.length)
626
+ if (node.path) index.set(String(node.path), nodes.length)
627
+ nodes.push({
628
+ id: record ? idOf(node.id) : "",
629
+ path: clip(node.path ?? "", 200),
630
+ title: clip(node.title || node.path || node.id || "", 80),
631
+ kind: clip(node.kind ?? "", 20),
632
+ type: clip(node.type ?? "", 40),
633
+ dangling: node.dangling === true,
634
+ })
635
+ }
636
+ const startKey = ref.path ?? ref.id
637
+ const start = index.get(startKey) ?? 0
638
+ // Long paths and titles could pass the cap at 200 nodes: the farthest go first.
639
+ let cut = false
640
+ while (nodes.length > start + 1 && jsonBytes(nodes) > ANSWER_BYTES - 12_000) {
641
+ nodes.pop()
642
+ cut = true
643
+ }
644
+ for (const [key, at] of index) if (at >= nodes.length) index.delete(key)
645
+ const edges = []
646
+ const seen = new Set()
647
+ for (const edge of Array.isArray(answer?.edges) ? answer.edges : []) {
648
+ const from = index.get(String(edge?.from ?? ""))
649
+ const to = index.get(String(edge?.to ?? ""))
650
+ const type = EDGE_TYPES.has(edge?.type) ? edge.type : "link"
651
+ const key = `${from}>${to}>${type}`
652
+ if (from === undefined || to === undefined || from === to || seen.has(key)) continue
653
+ seen.add(key)
654
+ edges.push({ from, to, type })
655
+ if (edges.length >= GRAPH_EDGES_MAX) break
656
+ }
657
+ const out = { space: where.space, start, nodes, edges: [], truncated: answer?.truncated === true || cut }
658
+ if (fitList(out, "edges", edges)) out.truncated = true
659
+ return out
660
+ }
661
+
662
+ return {
663
+ memoryCount,
664
+ methods: {
665
+ "memories.recent": memoriesRecent,
666
+ "journal.list": journalList,
667
+ "journal.read": journalRead,
668
+ "review.list": reviewList,
669
+ "pages.list": pagesList,
670
+ "pages.read": pagesRead,
671
+ "pages.history": pagesHistory,
672
+ "graph.links": graphLinks,
673
+ },
674
+ }
675
+ }