@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
@@ -1,48 +1,273 @@
1
1
  /**
2
- * Reading and writing a space's records wiki ("Memory records",
3
- * `commitments.json`). The pure rules live in `records.js`.
2
+ * A space's commitments as records (kind `commitment`) in the records service
3
+ * (docs/design/memory-v1-contracts.md §4.1), and the one-time migration of the
4
+ * hub's reserved "Memory records" wiki (`commitments.json`) into them.
4
5
  *
5
- * Two of one person's agents can write the file at once, and the wiki raw
6
- * route has no conditional write yet (GAPS S2). So a write is a
7
- * read-modify-write that detects a change since its read:
6
+ * The interface is the one the hub-file store had, so `mem_commitments`, the
7
+ * Due list and the views keep their shape: `read(scope)` answers
8
+ * `{ records: { items } }` in the item shape of `records.js`, and
9
+ * `change(scope, spaceContext, change, context)` applies one add, update or
10
+ * delete. The pure rules (validation, the duplicate check, the Due list) stay
11
+ * in `records.js`.
8
12
  *
9
- * 1. Read the file and apply the change.
10
- * 2. Re-read just before writing. If the file changed, apply the same change
11
- * (it names its target by id) to the newer copy and start again.
12
- * 3. Write, then read back. If another writer replaced the file in between,
13
- * and the change is not in what is stored now, apply it to that copy and
14
- * write again.
13
+ * Concurrency: an update sends the record's `base_version`; a
14
+ * `version_conflict` (another writer got there first) re-reads and applies the
15
+ * same change to the newer copy, at most three rounds, then reports a conflict
16
+ * instead of overwriting.
15
17
  *
16
- * Every write is built from the newest copy read, so a record another writer
17
- * added is kept: a change touches only its own id. After three rounds without
18
- * a stable read, the write reports a conflict instead of overwriting.
18
+ * Migration, on the first read or write in a space (per process): the hub
19
+ * file's items are put as commitment records carrying their old id as
20
+ * `fields.legacy_id`, using the records service's atomic legacy ledger. An
21
+ * unstamped file is checked on each use: the hub has no conditional write, so
22
+ * stamping it could overwrite a concurrent legacy edit. Old `cmt_` ids still
23
+ * address the migrated records. Previously stamped files are left alone.
19
24
  */
20
25
  import {
26
+ CLOSED_RETENTION_DAYS,
21
27
  RECORDS_FILE,
22
28
  RECORDS_WIKI,
23
29
  applyChange,
30
+ commitmentFields,
24
31
  dayIn,
25
- emptyRecords,
32
+ itemOfRecord,
26
33
  parseRecords,
27
- serializeRecords,
34
+ prune,
28
35
  } from "./records.js"
36
+ import { isRecordsCode } from "./backend/records.js"
29
37
  import { errorMessage } from "./util.js"
30
38
 
31
39
  export const MAX_ROUNDS = 3
40
+ /** Commitment records read per list page, and pages read at most. */
41
+ const PAGE = 200
42
+ const MAX_PAGES = 10
32
43
 
33
- /** True when a stored copy already reflects a change (nothing left to write). */
34
- function reflects(records, change, item) {
35
- const stored = records.items.find((entry) => entry.id === change.id)
36
- if (change.action === "delete") return !stored
37
- if (!stored || !item) return false
38
- return JSON.stringify(stored) === JSON.stringify(item)
44
+ /**
45
+ * @param {{ backend: any, control?: any, log?: any, client?: { call: Function } | null }} deps
46
+ */
47
+ export function createRecordsStore({ backend, control, log, client }) {
48
+ const hub = createHubFile({ backend, control, log })
49
+ /** Spaces whose hub file is migrated (or absent), and migrations running now. */
50
+ const migrated = new Set()
51
+ const migrating = new Map()
52
+
53
+ function need() {
54
+ if (!client) throw new Error("the records service is not configured")
55
+ return client
56
+ }
57
+
58
+ /** One records call in the space a scope names. Reads never send the session, so they never bind it. */
59
+ function call(method, body, scope, { session } = {}) {
60
+ return need().call(method, body, { scope, space: scope?.space_id, ...(session ? { sessionID: session } : {}) })
61
+ }
62
+
63
+ const spaceKey = (scope) => String(scope?.space_id || scope?.team_id || "local")
64
+
65
+ /** Every commitment record in the space, any status, newest first. */
66
+ async function listRecords(scope) {
67
+ const records = []
68
+ let cursor
69
+ for (let page = 0; page < MAX_PAGES; page += 1) {
70
+ const data = await call("records.list", { kind: "commitment", status: "all", limit: PAGE, full: true, ...(cursor ? { cursor } : {}) }, scope)
71
+ records.push(...(data?.records ?? []))
72
+ cursor = data?.cursor
73
+ if (!cursor) break
74
+ }
75
+ return records
76
+ }
77
+
78
+ /**
79
+ * Migrate the hub file once per space. A failure is logged and retried on the
80
+ * next use; it never fails the read or write that triggered it.
81
+ *
82
+ * @returns {Promise<{ migrated: number, skipped: number, marked: boolean, reason?: string }>}
83
+ */
84
+ async function migrate(scope) {
85
+ const key = spaceKey(scope)
86
+ if (migrated.has(key)) return { migrated: 0, skipped: 0, marked: false, reason: "done" }
87
+ if (migrating.has(key)) return migrating.get(key)
88
+ const run = (async () => {
89
+ try {
90
+ const result = await migrateOnce(scope)
91
+ if (result.reason === "already migrated") migrated.add(key)
92
+ if (result.migrated > 0) log?.info?.("commitments migrated into records", { migrated: result.migrated, skipped: result.skipped })
93
+ return result
94
+ } catch (error) {
95
+ log?.warn?.("commitments migration failed; it is retried on the next use", { error: errorMessage(error) })
96
+ return { migrated: 0, skipped: 0, marked: false, reason: `failed: ${errorMessage(error)}` }
97
+ } finally {
98
+ migrating.delete(key)
99
+ }
100
+ })()
101
+ migrating.set(key, run)
102
+ return run
103
+ }
104
+
105
+ async function migrateOnce(scope) {
106
+ const file = await hub.read(scope)
107
+ if (!file) return { migrated: 0, skipped: 0, marked: false, reason: "no hub file" }
108
+ if (file.parsed.migrated) return { migrated: 0, skipped: 0, marked: false, reason: "already migrated" }
109
+ let count = 0
110
+ let skipped = 0
111
+ for (const item of file.parsed.items) {
112
+ const result = await call("records.put", { record: migratedRecord(item), migrate_legacy: true }, scope)
113
+ if (result?.legacy_migration !== true) throw new Error("the records service did not confirm atomic legacy migration; upgrade it before retrying")
114
+ if (result.created === false) skipped += 1
115
+ else count += 1
116
+ }
117
+ return { migrated: count, skipped, marked: false, reason: "hub has no conditional write; file left unstamped" }
118
+ }
119
+
120
+ /**
121
+ * The space's commitments, in the item shape of `records.js`.
122
+ *
123
+ * @returns {Promise<{ records: { items: any[] }, raw: any[] }>}
124
+ */
125
+ async function read(scope) {
126
+ await migrate(scope)
127
+ const raw = await listRecords(scope)
128
+ return { records: { items: raw.map(itemOfRecord) }, raw }
129
+ }
130
+
131
+ /** The record a commitment id names: its `rec_` id, or the `cmt_` id it had before the migration. */
132
+ function find(raw, id) {
133
+ return raw.find((record) => record.id === id) ?? raw.find((record) => record.fields?.legacy_id === id) ?? null
134
+ }
135
+
136
+ /**
137
+ * Apply one change, with the version check described above.
138
+ *
139
+ * @param {any} scope
140
+ * @param {any} _spaceContext
141
+ * @param {{ action: "add" | "update" | "delete", id?: string, fields?: Record<string, any> }} change
142
+ * @param {{ now: number, zone: string, session?: string }} context
143
+ * @returns {Promise<{ item?: any, records?: { items: any[] }, rounds?: number, unchanged?: boolean, error?: string, conflict?: boolean }>}
144
+ */
145
+ async function change(scope, _spaceContext, change, context) {
146
+ const today = dayIn(context.now, context.zone)
147
+ for (let round = 1; round <= MAX_ROUNDS; round += 1) {
148
+ const { records, raw } = await read(scope)
149
+ if (change.action === "add") {
150
+ const applied = applyChange(records, { ...change, id: "new" }, { today, session: context.session })
151
+ if (applied.error) return { error: applied.error }
152
+ if (applied.unchanged) return { item: applied.item, records, rounds: round, unchanged: true }
153
+ const data = await call("records.put", { record: commitmentRecord(applied.item, { session: context.session }) }, scope, { session: context.session })
154
+ const item = itemOfRecord(data.record)
155
+ const items = [...records.items, item]
156
+ await pruneClosed(scope, raw, today)
157
+ return { item, records: { items }, rounds: round }
158
+ }
159
+ const target = find(raw, String(change.id ?? ""))
160
+ if (!target) return { error: `no commitment ${String(change.id ?? "").slice(0, 40)} in this space` }
161
+ const current = itemOfRecord(target)
162
+ if (change.action === "delete") {
163
+ const data = await call("records.delete", { ids: [target.id] }, scope, { session: context.session })
164
+ if (!(data?.deleted ?? []).includes(target.id)) return { error: `the records service did not delete ${target.id}` }
165
+ return { item: current, records: { items: records.items.filter((item) => item.id !== current.id) }, rounds: round }
166
+ }
167
+ const applied = applyChange({ items: [current] }, { ...change, id: current.id }, { today, session: context.session })
168
+ if (applied.error) return { error: applied.error }
169
+ try {
170
+ const data = await call(
171
+ "records.put",
172
+ { record: { id: target.id, ...commitmentRecord(applied.item, { session: context.session, keep: target }), base_version: target.version } },
173
+ scope,
174
+ { session: context.session },
175
+ )
176
+ const item = itemOfRecord(data.record)
177
+ await pruneClosed(scope, raw, today)
178
+ return { item, records: { items: records.items.map((entry) => (entry.id === item.id ? item : entry)) }, rounds: round }
179
+ } catch (error) {
180
+ if (!isRecordsCode(error, "version_conflict")) throw error
181
+ log?.debug?.("commitment changed since read; applying again", { round })
182
+ }
183
+ }
184
+ return { conflict: true, error: "another agent kept changing this commitment; nothing was overwritten. Try again in a moment." }
185
+ }
186
+
187
+ /** Closed commitments past the retention window are deleted on a write, best effort. */
188
+ async function pruneClosed(scope, raw, today) {
189
+ const items = raw.map(itemOfRecord)
190
+ const keep = new Set(prune(items, today).map((item) => item.id))
191
+ const old = raw.filter((record) => !keep.has(record.id)).map((record) => record.id)
192
+ if (old.length === 0) return
193
+ try {
194
+ await call("records.delete", { ids: old }, scope)
195
+ } catch (error) {
196
+ log?.debug?.(`closed commitments older than ${CLOSED_RETENTION_DAYS} days were not pruned`, { error: errorMessage(error) })
197
+ }
198
+ }
199
+
200
+ /**
201
+ * The session-start dashboard: the space's `index` page, or null when it has
202
+ * none. A failed read throws, so the pinned block counts it as a miss.
203
+ */
204
+ async function readIndex(scope) {
205
+ const data = await call("records.get", { paths: ["index"] }, scope)
206
+ return (data?.records ?? []).find((record) => record.path === "index") ?? null
207
+ }
208
+
209
+ return {
210
+ read,
211
+ change,
212
+ migrate,
213
+ readIndex,
214
+ locate: hub.locate,
215
+ isRecordsWiki: hub.isRecordsWiki,
216
+ noteRecordsWiki: hub.noteRecordsWiki,
217
+ remember: hub.remember,
218
+ }
219
+ }
220
+
221
+ /** A hub item as the commitment record it becomes, carrying its old id. */
222
+ function migratedRecord(item) {
223
+ const record = commitmentRecord(item, { session: item.session })
224
+ record.fields.legacy_id = item.id
225
+ if (item.created) record.fields.created_day = item.created
226
+ // Provenance is a field: a record's source names only a session, turn, event, url, routine or record (§2.3).
227
+ record.fields.migrated_from = "hub"
228
+ return record
229
+ }
230
+
231
+ /** The commitment fields this module writes whole; the item is their only source. */
232
+ const OWNED_FIELDS = Object.freeze(["what", "owner", "due", "trigger", "state", "project", "link", "closed_at", "links"])
233
+
234
+ /** A commitment item as the record the service stores (kind and type `commitment`). */
235
+ export function commitmentRecord(item, { session, keep } = {}) {
236
+ // The service merges fields on update and removes a key sent as null
237
+ // (§2.3), so a field this module owns that the item no longer has (a cleared
238
+ // due, the closed_at of a reopened commitment) is sent as null; any other
239
+ // field is kept.
240
+ const fields = { ...commitmentFields(item) }
241
+ if (keep) {
242
+ for (const key of OWNED_FIELDS) if (keep.fields?.[key] !== undefined && fields[key] === undefined) fields[key] = null
243
+ }
244
+ const record = {
245
+ kind: "commitment",
246
+ type: "commitment",
247
+ title: item.what,
248
+ body: commitmentBody(item),
249
+ fields,
250
+ ...(keep ? {} : { stated_by: "agent" }),
251
+ }
252
+ if (!keep && session) record.source = { session: String(session) }
253
+ return record
254
+ }
255
+
256
+ /** The searchable text: what, and when. The project is a link. */
257
+ function commitmentBody(item) {
258
+ const lines = [String(item.what ?? "")]
259
+ if (item.due) lines.push(`Due: ${item.due}`)
260
+ if (item.trigger) lines.push(`When: ${item.trigger}`)
261
+ if (item.project) lines.push(`Project: [[projects/${item.project}]]`)
262
+ return lines.join("\n")
39
263
  }
40
264
 
41
265
  /**
42
- * @param {{ backend: any, control?: any, log?: any }} deps
266
+ * The hub's reserved records wiki: found to migrate it, and kept out of
267
+ * mem_wiki (`isRecordsWiki`). Nothing new is written to it except the
268
+ * migration stamp.
43
269
  */
44
- export function createRecordsStore({ backend, control, log }) {
45
- /** Records wiki id per container: one lookup per space and process. */
270
+ function createHubFile({ backend, control, log }) {
46
271
  const wikiIds = new Map()
47
272
  const known = new Set()
48
273
 
@@ -51,24 +276,23 @@ export function createRecordsStore({ backend, control, log }) {
51
276
  known.add(wikiID)
52
277
  }
53
278
 
54
- /** True for a wiki id this process knows is a records wiki. */
55
279
  function isRecordsWiki(wikiID) {
56
280
  return known.has(String(wikiID ?? ""))
57
281
  }
58
282
 
283
+ function noteRecordsWiki(wikiID) {
284
+ if (wikiID) known.add(String(wikiID))
285
+ }
286
+
59
287
  /**
60
- * Find the space's records wiki. A wiki listing that fails is an error, not
61
- * an empty space: a write must never create a second records wiki because a
62
- * read timed out.
288
+ * Find the space's records wiki in the wiki list or the asset catalogue (each
289
+ * can miss one the other has). Only both failing is an error.
63
290
  */
64
291
  async function locate(scope) {
65
292
  const key = String(scope.team_id ?? "")
66
293
  if (wikiIds.has(key)) return wikiIds.get(key)
67
- // The wiki list and the asset catalogue can each miss a wiki the other
68
- // has (knowledge.js discoverKnowledge merges them for the same reason), so
69
- // both are read; only both failing is an error.
70
294
  const [wikis, assets] = await Promise.allSettled([
71
- backend.listWiki({ scope }),
295
+ typeof backend.listWiki === "function" ? backend.listWiki({ scope }) : Promise.reject(new Error("no wiki listing")),
72
296
  typeof backend.listAccessibleAssets === "function"
73
297
  ? backend.listAccessibleAssets({ scope, assetType: "llm_wiki" })
74
298
  : Promise.reject(new Error("no asset listing")),
@@ -84,35 +308,15 @@ export function createRecordsStore({ backend, control, log }) {
84
308
  return String(found)
85
309
  }
86
310
 
87
- /** Create the records wiki and, where a control plane owns the catalogue, register it. */
88
- async function create(scope, spaceContext) {
89
- const wiki = await backend.createWiki({ scope, name: RECORDS_WIKI })
90
- const wikiID = String(wiki?.wiki_id ?? "")
91
- if (!wikiID) throw new Error("wiki/create returned no wiki_id")
92
- const registered = typeof wiki?.resource_id === "string" && wiki.resource_id.trim()
93
- if (!registered && control && spaceContext?.space_id) {
94
- const userId = spaceContext.user_id
95
- if (userId) {
96
- await control.createResource({
97
- userId,
98
- spaceId: spaceContext.space_id,
99
- resource: { kind: "wiki", upstream_id: wikiID, name: RECORDS_WIKI },
100
- })
101
- }
102
- }
103
- remember(String(scope.team_id ?? ""), wikiID)
104
- return wikiID
105
- }
106
-
107
311
  async function readText(scope, wikiID) {
108
312
  let data
109
313
  try {
110
314
  data = await backend.readWikiRaw({ scope, wikiID, filenames: [RECORDS_FILE] })
111
315
  } catch (error) {
112
- // The cached id may belong to a wiki that was deleted since.
113
316
  if (Number(error?.status) === 404) {
114
317
  for (const [key, value] of wikiIds) if (value === wikiID) wikiIds.delete(key)
115
318
  known.delete(wikiID)
319
+ return ""
116
320
  }
117
321
  throw error
118
322
  }
@@ -120,80 +324,22 @@ export function createRecordsStore({ backend, control, log }) {
120
324
  return typeof item?.content === "string" ? item.content : ""
121
325
  }
122
326
 
123
- /**
124
- * The space's commitments. No records wiki yet is an empty set.
125
- *
126
- * @returns {Promise<{ wikiID: string, records: ReturnType<typeof emptyRecords>, text: string }>}
127
- */
327
+ /** The file, parsed, or null when the space has none (or it holds nothing). */
128
328
  async function read(scope) {
129
329
  const wikiID = await locate(scope)
130
- if (!wikiID) return { wikiID: "", records: emptyRecords(), text: "" }
330
+ if (!wikiID) return null
131
331
  const text = await readText(scope, wikiID)
332
+ if (!text.trim()) return null
132
333
  const parsed = parseRecords(text)
133
- if (parsed.error) throw new Error(parsed.error)
134
- return { wikiID, records: parsed.records, text }
135
- }
136
-
137
- /**
138
- * Apply one change with the concurrency check described above.
139
- *
140
- * @param {any} scope
141
- * @param {any} spaceContext
142
- * @param {{ action: "add" | "update" | "delete", id: string, fields?: Record<string, any> }} change
143
- * @param {{ now: number, zone: string, session?: string }} context
144
- * @returns {Promise<{ item?: any, records?: any, rounds?: number, unchanged?: boolean, error?: string, conflict?: boolean }>}
145
- */
146
- async function change(scope, spaceContext, change, context) {
147
- const today = dayIn(context.now, context.zone)
148
- let wikiID = await locate(scope)
149
- if (!wikiID && change.action !== "add") return { error: `no commitment ${change.id} in this space: it has no commitments yet` }
150
- if (!wikiID) wikiID = await create(scope, spaceContext)
151
-
152
- let text = await readText(scope, wikiID)
153
- for (let round = 1; round <= MAX_ROUNDS; round += 1) {
154
- const parsed = parseRecords(text)
155
- if (parsed.error) return { error: `${parsed.error}; nothing was written` }
156
- const applied = applyChange(parsed.records, change, { today, session: context.session })
157
- if (applied.error) return { error: applied.error }
158
- if (applied.unchanged) return { item: applied.item, records: parsed.records, rounds: round, unchanged: true }
159
- const next = { ...parsed.records, version: parsed.records.version + 1, items: applied.items }
160
- const body = serializeRecords(next)
161
-
162
- // Re-read just before writing: a write since our read means our copy is
163
- // old, so the change is applied again to the newer one.
164
- const latest = await readText(scope, wikiID)
165
- if (latest !== text) {
166
- log?.debug?.("records changed since read; merging", { round })
167
- text = latest
168
- continue
169
- }
170
-
171
- await backend.writeWikiRaw({ scope, wikiID, files: [{ filename: RECORDS_FILE, content: body }] })
172
-
173
- // Read back: a writer that raced us between the re-read and the write
174
- // shows here. If our change is in what is stored, we are done;
175
- // otherwise apply it to the stored copy and write again.
176
- const stored = await readText(scope, wikiID)
177
- if (stored === body) return { item: applied.item, records: next, rounds: round }
178
- const storedParsed = parseRecords(stored)
179
- if (!storedParsed.error && reflects(storedParsed.records, change, applied.item)) {
180
- return { item: applied.item, records: storedParsed.records, rounds: round }
181
- }
182
- log?.debug?.("records replaced after write; merging", { round })
183
- text = stored
334
+ if (parsed.error) {
335
+ log?.warn?.("the hub's commitments file is unreadable; it is not migrated", { error: parsed.error })
336
+ return null
184
337
  }
185
- return {
186
- conflict: true,
187
- error: `another agent kept changing this space's commitments; nothing was overwritten. Try again in a moment.`,
188
- }
189
- }
190
-
191
- /** Note a records wiki seen in a listing, so mem_wiki refuses it by id too. */
192
- function noteRecordsWiki(wikiID) {
193
- if (wikiID) known.add(String(wikiID))
338
+ return { wikiID, text, parsed: parsed.records }
194
339
  }
195
340
 
196
- return { read, change, locate, isRecordsWiki, noteRecordsWiki, remember }
341
+ void control
342
+ return { locate, readText, read, isRecordsWiki, noteRecordsWiki, remember }
197
343
  }
198
344
 
199
345
  /** A records read for the pinned block: never throws; a failure is `null`. */
package/src/records.js CHANGED
@@ -2,16 +2,19 @@
2
2
  * Commitments: things someone will do, with a time or a trigger, kept as a
3
3
  * structured record with a state (docs/design/memory-value-design.md §7).
4
4
  *
5
- * Atoms cannot hold this: they cannot be updated, upstream assigns their type,
6
- * and `work_task` atoms are withheld from recall by design. So each space
7
- * keeps one reserved, never-ingested wiki, "Memory records", holding one file,
8
- * `commitments.json`:
5
+ * From 0.9.0 each commitment is a record of kind `commitment` in the records
6
+ * service (docs/design/memory-v1-contracts.md §2.3), with its state in
7
+ * `fields`. Before that, each space kept one reserved, never-ingested wiki,
8
+ * "Memory records", holding one file, `commitments.json`:
9
9
  *
10
10
  * { "marker": "opencode-mem:records v1", "version": 7, "items": [ … ] }
11
11
  *
12
- * This module is pure: parse, validate, apply a change, merge a change into a
13
- * newer copy, and render the Due list and the list answer. The I/O and the
14
- * concurrency check live in `records-store.js`.
12
+ * `records-store.js` migrates that file into records once and stamps it
13
+ * `migrated`; the parser here still reads it for that.
14
+ *
15
+ * This module is pure: parse, validate, apply a change, map an item to and
16
+ * from its record, and render the Due list and the list answer. The I/O and
17
+ * the concurrency check live in `records-store.js`.
15
18
  */
16
19
  import { isInstructionShaped } from "./curation.js"
17
20
  import { neutralizeFenceClosers, oneLine } from "./util.js"
@@ -69,12 +72,61 @@ export function parseRecords(text) {
69
72
  const items = (Array.isArray(parsed.items) ? parsed.items : []).filter(
70
73
  (item) => item && typeof item === "object" && typeof item.id === "string" && typeof item.what === "string",
71
74
  )
72
- return { records: { marker: RECORDS_MARKER, version, items } }
75
+ const migrated = parsed.migrated && typeof parsed.migrated === "object" ? { migrated: parsed.migrated } : {}
76
+ return { records: { marker: RECORDS_MARKER, version, ...migrated, items } }
73
77
  }
74
78
 
75
79
  /** The file's text; the marker is the first key, as a share's marker is its first line. */
76
80
  export function serializeRecords(records) {
77
- return `${JSON.stringify({ marker: RECORDS_MARKER, version: records.version, items: records.items }, null, 2)}\n`
81
+ const migrated = records.migrated ? { migrated: records.migrated } : {}
82
+ return `${JSON.stringify({ marker: RECORDS_MARKER, version: records.version, ...migrated, items: records.items }, null, 2)}\n`
83
+ }
84
+
85
+ /** The calendar day of an ISO time, or the value itself when it is already a day. */
86
+ function dayOf(value) {
87
+ const text = String(value ?? "")
88
+ return DATE.test(text) ? text : text.slice(0, 10)
89
+ }
90
+
91
+ /**
92
+ * A commitment record (kind `commitment`) as the item every answer and the Due
93
+ * list read: `{ id, what, owner, due?, trigger?, state, project?, link?,
94
+ * created, updated, closed?, session?, legacy_id? }`. The id is the record's
95
+ * `rec_` id; a commitment migrated from the hub file keeps its old `cmt_` id
96
+ * as `legacy_id`.
97
+ */
98
+ export function itemOfRecord(record) {
99
+ const fields = record?.fields ?? {}
100
+ return compact({
101
+ id: String(record?.id ?? ""),
102
+ what: String(fields.what ?? record?.title ?? ""),
103
+ owner: fields.owner ?? "user",
104
+ due: fields.due,
105
+ trigger: fields.trigger,
106
+ state: STATES.includes(fields.state) ? fields.state : "open",
107
+ project: fields.project,
108
+ link: fields.link,
109
+ created: fields.created_day ?? dayOf(record?.created),
110
+ updated: dayOf(record?.updated),
111
+ closed: fields.closed_at ? dayOf(fields.closed_at) : undefined,
112
+ session: record?.source?.session,
113
+ legacy_id: fields.legacy_id,
114
+ })
115
+ }
116
+
117
+ /** An item's state as a commitment record's `fields` (contract §2.3): `what` is also the title. */
118
+ export function commitmentFields(item) {
119
+ return compact({
120
+ what: item.what,
121
+ owner: item.owner ?? "user",
122
+ due: item.due,
123
+ trigger: item.trigger,
124
+ state: item.state ?? "open",
125
+ project: item.project,
126
+ link: item.link,
127
+ closed_at: item.state && item.state !== "open" ? item.closed : undefined,
128
+ links: item.project ? [`projects/${item.project}`] : undefined,
129
+ })
78
130
  }
79
131
 
80
132
  /** True when a file's text is a records file (used to keep it out of mem_wiki). */
@@ -396,7 +448,7 @@ export function dueSection(items, { today, zone, workingDays = DUE_WORKING_DAYS
396
448
  if (due.length === 0) return { text: "", withheld }
397
449
  const lines = due
398
450
  .slice(0, DUE_MAX_LINES)
399
- .map((item) => `- ${dueLabel(item, today, zone)}: ${shown(item.what, 160)} (${shown(ownerLabel(item.owner), 60)}) [${shown(item.id, 20)}]`)
451
+ .map((item) => `- ${dueLabel(item, today, zone)}: ${shown(item.what, 160)} (${shown(ownerLabel(item.owner), 60)}) [${shown(item.id, 40)}]`)
400
452
  const more = open.length - withheld - lines.length
401
453
  if (more > 0) lines.push(`(${more} more open: mem_commitments list)`)
402
454
  return { text: `## Due (${formatDay(today)})\n${lines.join("\n")}`, withheld }
@@ -428,7 +480,7 @@ export function filterItems(items, filter, zone) {
428
480
 
429
481
  /** One line of a list answer. */
430
482
  export function itemLine(item, today, zone) {
431
- const parts = [`${shown(item.id, 20)}`, shown(item.what, MAX_WHAT_CHARS)]
483
+ const parts = [`${shown(item.id, 40)}`, shown(item.what, MAX_WHAT_CHARS)]
432
484
  const when = item.state === "open" ? dueLabel(item, today, zone) : item.due ? formatDue(item.due, zone) : ""
433
485
  if (when) parts.push(item.state === "open" ? when : `due ${when}`)
434
486
  if (item.trigger) parts.push(`when: ${shown(item.trigger, MAX_TRIGGER_CHARS)}`)
package/src/runtime.js CHANGED
@@ -3,6 +3,7 @@ import { buildBootstrap } from "./bootstrap.js"
3
3
  import { createClock } from "./config.js"
4
4
  import { dayIn, dueSection } from "./records.js"
5
5
  import { createRecordsStore } from "./records-store.js"
6
+ import { createRecordsClient } from "./backend/records.js"
6
7
  import { buildCheckpoint, checkpointFingerprint } from "./compaction.js"
7
8
  import { UNLINKED_SENTENCE, asSession, credentialLine, unavailableReason } from "./credentials.js"
8
9
  import { createControlClient } from "./spaces.js"
@@ -93,8 +94,13 @@ export function createRuntime(input) {
93
94
  ? createControlClient({ controlURL: () => config.controlURL, token: config.token, credentials, log })
94
95
  : null)
95
96
 
96
- /** The personal space's commitments (the reserved records wiki). */
97
- const records = createRecordsStore({ backend, control, log })
97
+ /** The records service (memory-v1-contracts.md §2): memories, pages, commitments. */
98
+ // `recordsClient: null` stands for a build with no records client (tests of the legacy paths).
99
+ const recordsClient = input.recordsClient === null ? null : (input.recordsClient ?? createRecordsClient(config, { log, credentials }))
100
+ /** The personal space's commitments, as records; the hub file is migrated once. */
101
+ const records = createRecordsStore({ backend, control, log, client: recordsClient })
102
+ /** The same store, for `buildFor`, whose read results are named `records`. */
103
+ const records_ = records
98
104
 
99
105
  /**
100
106
  * One sentence saying why memory is unavailable, or "" when it is. Only a
@@ -285,14 +291,13 @@ export function createRuntime(input) {
285
291
  const context = await sessionContext(sessionID, agent)
286
292
  if (!context) throw new Error("control plane returned no context")
287
293
  if (visibility === "team" && context.space_kind === "shared") return context
288
- if (context.space_kind === "personal") return context
289
-
290
294
  const personalID = context.personal_space_id
295
+ if (context.space_kind === "personal" && personalID && context.space_id === personalID) return context
291
296
  if (!personalID || personalID === context.space_id) {
292
297
  throw new Error("control plane returned no personal space for private capture")
293
298
  }
294
299
  const personal = await resolveContext({ space: personalID, agent })
295
- if (!personal || personal.space_kind === "shared") {
300
+ if (!personal || personal.space_kind !== "personal" || personal.space_id !== personalID) {
296
301
  throw new Error("control plane returned no personal space for private capture")
297
302
  }
298
303
  return personal
@@ -384,10 +389,13 @@ export function createRuntime(input) {
384
389
  }
385
390
 
386
391
  /**
387
- * Build the pinned block. A read that fails is not the same as an empty
388
- * space: when both reads fail the build fails, so a transient backend error
389
- * is retried instead of pinning an empty block for the session. A block
390
- * built with one read missing is marked partial and rebuilt sooner.
392
+ * Build the pinned block (contract §4.3): the space's `index` page, the Due
393
+ * list, then the persona. A read that fails is not the same as an empty
394
+ * space: when every read fails the build fails, so a transient error is
395
+ * retried instead of pinning an empty block for the session. A block built
396
+ * without the persona is marked partial and rebuilt sooner; the index and
397
+ * the Due list come from the records service and, as the Due list always
398
+ * did, a failed read leaves them out without failing the block.
391
399
  */
392
400
  async function buildFor(sessionID, agent, context) {
393
401
  const scoped = context ? scopeFor(context, { sessionID, agent }) : scope({ sessionID, agent })
@@ -398,26 +406,26 @@ export function createRuntime(input) {
398
406
  (value) => ({ value }),
399
407
  (error) => ({ error }),
400
408
  )
401
- const [core, scenarios, records] = await Promise.all([
409
+ const [core, index, records] = await Promise.all([
402
410
  settle(() => backend.readCore({ scope: scoped })),
403
- settle(() => backend.listScenarios({ scope: scoped })),
411
+ settle(() => (config.tools ? records_.readIndex(scoped) : null)),
404
412
  // The person's commitments live in their personal space, also when the
405
413
  // session is bound to a shared one. A failed read leaves the Due list
406
414
  // out; it never fails the block.
407
415
  settle(() => personalRecords(sessionID, agent, context, scoped)),
408
416
  ])
409
- if (core.error && scenarios.error) throw core.error
417
+ if (core.error && index.error && records.error) throw core.error
410
418
  const day = today()
411
419
  const due = records.value ? dueSection(records.value.items, { today: day, zone: clock.zone }) : { text: "", withheld: 0 }
412
420
  const block = buildBootstrap({
421
+ index: index.value ?? null,
413
422
  core: core.value ?? null,
414
- scenarios: scenarios.value?.entries ?? [],
415
423
  due,
416
424
  scope: scoped,
417
425
  label: context ? contextScopeLabel(context, scoped) : undefined,
418
426
  budgetChars: config.bootstrapChars,
419
427
  })
420
- return { block, partial: Boolean(core.error || scenarios.error) }
428
+ return { block, partial: Boolean(core.error) }
421
429
  }
422
430
 
423
431
  /** The personal space's records for the Due list, or null when there are none. */
@@ -913,6 +921,7 @@ export function createRuntime(input) {
913
921
  control,
914
922
  clock,
915
923
  records,
924
+ recordsClient,
916
925
  today,
917
926
  credentials,
918
927
  unavailable,