@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.
- package/CHANGELOG.md +512 -0
- package/README.md +127 -61
- package/docs/agent-protocol.md +67 -177
- package/package.json +1453 -100
- package/skills/mem.pages/SKILL.md +146 -0
- package/skills/mem.sharing/SKILL.md +91 -0
- package/skills/mem.sources/SKILL.md +94 -0
- package/skills/mem.usage/SKILL.md +129 -492
- package/src/backend/records.js +285 -0
- package/src/backend/v3.js +3 -0
- package/src/bootstrap.js +49 -45
- package/src/call-shapes.js +41 -10
- package/src/collector-lock.js +162 -0
- package/src/collector-service.js +441 -0
- package/src/collector.js +381 -0
- package/src/commands.js +3 -3
- package/src/config.js +15 -1
- package/src/credentials.js +26 -1
- package/src/curation.js +1 -1
- package/src/permissions.js +87 -10
- package/src/protocol.js +29 -20
- package/src/recall.js +104 -27
- package/src/records-store.js +267 -121
- package/src/records.js +63 -11
- package/src/runtime.js +23 -14
- package/src/skills.js +44 -18
- package/src/sources.js +58 -0
- package/src/spaces.js +93 -10
- package/src/tools/aliases.js +164 -0
- package/src/tools/commitments.js +12 -9
- package/src/tools/held-write.js +82 -0
- package/src/tools/index.js +100 -23
- package/src/tools/ingest.js +277 -0
- package/src/tools/knowledge.js +6 -1
- package/src/tools/memory.js +722 -229
- package/src/tools/page.js +423 -0
- package/src/tools/recall.js +371 -113
- package/src/tools/records-kit.js +142 -0
- package/src/tools/share.js +1042 -0
- package/src/tools/shared.js +16 -2
- package/src/tools/spaces.js +431 -143
- package/src/tools/status.js +87 -58
- package/src/tools/wiki.js +8 -4
- package/src/views/contracts.js +293 -3
- package/src/views/inbox-decision.js +59 -0
- package/src/views/recall-result.js +12 -0
- package/src/views/records-reads.js +675 -0
- package/src/views/rpc.js +58 -99
- package/src/views/shape.js +61 -0
- package/views/commitments.html +4 -0
- package/views/graph.html +753 -0
- package/views/home.html +11 -5
- package/views/journal.html +621 -0
- package/views/memory.html +7 -1
- package/views/pages.html +636 -0
- package/views/recall.html +123 -0
- package/views/review.html +406 -0
- package/views/today.html +309 -0
package/src/records-store.js
CHANGED
|
@@ -1,48 +1,273 @@
|
|
|
1
1
|
/**
|
|
2
|
-
*
|
|
3
|
-
*
|
|
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
|
-
*
|
|
6
|
-
*
|
|
7
|
-
*
|
|
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
|
-
*
|
|
10
|
-
*
|
|
11
|
-
*
|
|
12
|
-
*
|
|
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
|
-
*
|
|
17
|
-
*
|
|
18
|
-
*
|
|
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
|
-
|
|
32
|
+
itemOfRecord,
|
|
26
33
|
parseRecords,
|
|
27
|
-
|
|
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
|
-
/**
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
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
|
-
*
|
|
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
|
-
|
|
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
|
|
61
|
-
*
|
|
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
|
|
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)
|
|
134
|
-
|
|
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
|
-
|
|
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
|
-
*
|
|
6
|
-
*
|
|
7
|
-
*
|
|
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
|
-
*
|
|
13
|
-
*
|
|
14
|
-
*
|
|
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
|
-
|
|
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
|
-
|
|
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,
|
|
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,
|
|
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
|
|
97
|
-
|
|
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
|
|
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
|
|
388
|
-
*
|
|
389
|
-
*
|
|
390
|
-
*
|
|
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,
|
|
409
|
+
const [core, index, records] = await Promise.all([
|
|
402
410
|
settle(() => backend.readCore({ scope: scoped })),
|
|
403
|
-
settle(() =>
|
|
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 &&
|
|
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
|
|
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,
|