@joe-broadhead/opencode-mem 0.9.12 → 0.11.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (144) hide show
  1. package/CHANGELOG.md +1934 -2
  2. package/README.md +29 -17
  3. package/SECURITY.md +3 -1
  4. package/docs/agent-instructions.md +17 -0
  5. package/docs/agent-protocol.md +8 -8
  6. package/docs/permissions.md +22 -4
  7. package/package.json +7923 -217
  8. package/shared/page-paths.js +44 -0
  9. package/skills/mem.pages/SKILL.md +8 -1
  10. package/skills/mem.usage/SKILL.md +15 -15
  11. package/src/action-grant-keys.js +159 -0
  12. package/src/action-grant.js +439 -0
  13. package/src/actions.js +1690 -0
  14. package/src/backend/records.js +25 -2
  15. package/src/backend/v3.js +76 -22
  16. package/src/call-shapes.js +17 -16
  17. package/src/collector-lock.js +533 -62
  18. package/src/collector-service.js +153 -26
  19. package/src/collector.js +627 -33
  20. package/src/config.js +79 -6
  21. package/src/connect.js +106 -8
  22. package/src/credentials.js +123 -25
  23. package/src/events.js +174 -3
  24. package/src/forget-turn.js +141 -0
  25. package/src/host-refusal.js +78 -0
  26. package/src/index.js +209 -22
  27. package/src/jobs/host.js +557 -0
  28. package/src/ops/codes.js +110 -0
  29. package/src/ops/copy-lineage.js +42 -0
  30. package/src/ops/index.js +28 -0
  31. package/src/ops/space-ops.js +1936 -0
  32. package/src/outlinks.js +103 -0
  33. package/src/p2-reservation.js +151 -0
  34. package/src/permissions.js +30 -0
  35. package/src/plugins/descriptor.js +62 -0
  36. package/src/plugins/discovery.js +318 -0
  37. package/src/plugins/grants.js +178 -0
  38. package/src/plugins/locate.js +319 -0
  39. package/src/plugins/manifest.js +1162 -0
  40. package/src/plugins/source-contract/index.js +34 -0
  41. package/src/plugins/source-contract/policy.js +102 -0
  42. package/src/plugins/source-contract/vendor/PROVENANCE.json +17 -0
  43. package/src/plugins/source-contract/vendor/RELEASE-SHA256SUMS +3 -0
  44. package/src/plugins/source-contract/vendor/RELEASE.json +17 -0
  45. package/src/plugins/source-contract/vendor/SHA256SUMS +41 -0
  46. package/src/plugins/source-contract/vendor/THIRD-PARTY-NOTICES.md +35 -0
  47. package/src/plugins/source-contract/vendor/broker-client.js +93 -0
  48. package/src/plugins/source-contract/vendor/chunks/chunk-3M5PAKSS.js +84 -0
  49. package/src/plugins/source-contract/vendor/chunks/chunk-4ERCA4TK.js +185 -0
  50. package/src/plugins/source-contract/vendor/chunks/chunk-6HDIB2SA.js +183 -0
  51. package/src/plugins/source-contract/vendor/chunks/chunk-ELPJD3ND.js +10 -0
  52. package/src/plugins/source-contract/vendor/chunks/chunk-HLVAKAYG.js +10 -0
  53. package/src/plugins/source-contract/vendor/chunks/chunk-I2RXJJJM.js +81 -0
  54. package/src/plugins/source-contract/vendor/chunks/chunk-KWEWSZ4V.js +505 -0
  55. package/src/plugins/source-contract/vendor/chunks/chunk-KYWBTAF4.js +182 -0
  56. package/src/plugins/source-contract/vendor/chunks/chunk-Q3RQA5J2.js +249 -0
  57. package/src/plugins/source-contract/vendor/chunks/chunk-RRUAIQ4I.js +156 -0
  58. package/src/plugins/source-contract/vendor/chunks/chunk-RYNKNCPP.js +165 -0
  59. package/src/plugins/source-contract/vendor/chunks/chunk-W5SHR7DQ.js +9477 -0
  60. package/src/plugins/source-contract/vendor/chunks/chunk-ZUKF7P6U.js +653 -0
  61. package/src/plugins/source-contract/vendor/cursor.js +26 -0
  62. package/src/plugins/source-contract/vendor/descriptor.js +34 -0
  63. package/src/plugins/source-contract/vendor/events.js +257 -0
  64. package/src/plugins/source-contract/vendor/index.js +10 -0
  65. package/src/plugins/source-contract/vendor/params.js +22 -0
  66. package/src/plugins/source-contract/vendor/permission.js +28 -0
  67. package/src/plugins/source-contract/vendor/pick.js +22 -0
  68. package/src/plugins/source-contract/vendor/read.js +29 -0
  69. package/src/plugins/source-contract/vendor/registry.js +23 -0
  70. package/src/plugins/source-contract/vendor/schema.js +17 -0
  71. package/src/plugins/source-contract/vendor/schemas/output.agenda.json +96 -0
  72. package/src/plugins/source-contract/vendor/schemas/output.countdown.json +28 -0
  73. package/src/plugins/source-contract/vendor/schemas/output.image.json +28 -0
  74. package/src/plugins/source-contract/vendor/schemas/output.inbox.json +84 -0
  75. package/src/plugins/source-contract/vendor/schemas/output.links.json +46 -0
  76. package/src/plugins/source-contract/vendor/schemas/output.list.json +57 -0
  77. package/src/plugins/source-contract/vendor/schemas/output.metric.json +61 -0
  78. package/src/plugins/source-contract/vendor/schemas/output.note.json +14 -0
  79. package/src/plugins/source-contract/vendor/schemas/output.progress.json +50 -0
  80. package/src/plugins/source-contract/vendor/schemas/output.record.json +38 -0
  81. package/src/plugins/source-contract/vendor/schemas/output.table.json +61 -0
  82. package/src/plugins/source-contract/vendor/schemas/output.thread.json +62 -0
  83. package/src/plugins/source-contract/vendor/schemas/sources.json +819 -0
  84. package/src/plugins/source-contract/vendor/schemas.js +19 -0
  85. package/src/plugins/source-contract/vendor/tools-rpc.js +42 -0
  86. package/src/plugins/verify.js +56 -0
  87. package/src/protocol.js +21 -5
  88. package/src/recall.js +104 -5
  89. package/src/records.js +61 -2
  90. package/src/requests.js +216 -0
  91. package/src/runtime.js +89 -7
  92. package/src/setup-time.js +68 -0
  93. package/src/skills.js +230 -8
  94. package/src/source-ids.js +25 -0
  95. package/src/sources/declaration.js +365 -0
  96. package/src/sources/reads.js +772 -0
  97. package/src/sources/rpc.js +151 -0
  98. package/src/sources.js +409 -90
  99. package/src/spaces.js +283 -11
  100. package/src/spool.js +61 -4
  101. package/src/stated.js +10 -5
  102. package/src/storable.js +139 -0
  103. package/src/tools/commitments.js +47 -5
  104. package/src/tools/held-write.js +36 -13
  105. package/src/tools/index.js +27 -0
  106. package/src/tools/ingest.js +27 -2
  107. package/src/tools/memory.js +52 -14
  108. package/src/tools/page.js +95 -9
  109. package/src/tools/recall.js +208 -4
  110. package/src/tools/records-kit.js +2 -1
  111. package/src/tools/share.js +42 -3
  112. package/src/tools/shared.js +44 -4
  113. package/src/tools/space-lifecycle.js +278 -0
  114. package/src/tools/spaces.js +373 -29
  115. package/src/tools/status.js +9 -2
  116. package/src/tools/wiki.js +34 -4
  117. package/src/util.js +110 -6
  118. package/src/vendor/source-contract/README.md +24 -0
  119. package/src/vendor/source-contract/THIRD-PARTY-NOTICES.md +35 -0
  120. package/src/vendor/source-contract/VENDOR.json +81 -0
  121. package/src/vendor/source-contract/chunks/chunk-3M5PAKSS.js +84 -0
  122. package/src/vendor/source-contract/chunks/chunk-6HDIB2SA.js +183 -0
  123. package/src/vendor/source-contract/chunks/chunk-HLVAKAYG.js +10 -0
  124. package/src/vendor/source-contract/chunks/chunk-I2RXJJJM.js +81 -0
  125. package/src/vendor/source-contract/chunks/chunk-KWEWSZ4V.js +505 -0
  126. package/src/vendor/source-contract/chunks/chunk-W5SHR7DQ.js +9477 -0
  127. package/src/vendor/source-contract/chunks/chunk-ZUKF7P6U.js +653 -0
  128. package/src/vendor/source-contract/cursor.js +26 -0
  129. package/src/vendor/source-contract/events.js +257 -0
  130. package/src/vendor/source-contract/registry.js +23 -0
  131. package/src/vendor/source-contract/tools-rpc.js +42 -0
  132. package/src/views/access-reads.js +256 -0
  133. package/src/views/communities.js +77 -0
  134. package/src/views/contracts.js +1183 -36
  135. package/src/views/inbox-bytes.js +103 -0
  136. package/src/views/overdue.js +1 -1
  137. package/src/views/profile.js +31 -0
  138. package/src/views/receipt.js +81 -0
  139. package/src/views/records-reads.js +869 -37
  140. package/src/views/rpc.js +159 -11
  141. package/src/views/shape.js +8 -5
  142. package/views/memory.html +16 -3
  143. package/views/pages.html +2 -2
  144. package/views/remembered.html +130 -0
@@ -0,0 +1,557 @@
1
+ /**
2
+ * Memory Jobs, slice J0: the **job host** (DESIGN-MEMORY-JOBS §3.2, §5.3).
3
+ *
4
+ * The host is the extract stage, and it runs in the person's own OpenCode,
5
+ * beside the connector plugins and their sign-ins:
6
+ *
7
+ * 1. it says it is alive (`jobs.host`);
8
+ * 2. it claims one run (`jobs.claim`), which carries the lease and its epoch;
9
+ * 3. it makes the **job session** `ses_mem_job_<job>`: rules `deny *`, then
10
+ * exactly the job's grants, and **no `execute`** (§5.3). The session is
11
+ * remade when its rules hash changes;
12
+ * 4. it calls `events_list` over the tools RPC with that session id in the
13
+ * envelope, and checks the answer against the binding before storing a
14
+ * single event: `source`, `account` and `owner` must be the job's, and every
15
+ * event's kind and scope must be what the person confirmed. **That is the
16
+ * per-run account check** (§5.3, §8.2): a plugin that answers for another
17
+ * account stops the run, and nothing is stored;
18
+ * 5. it checkpoints each page with `cursor_before` / `cursor_after`, then
19
+ * finishes with the outcome.
20
+ *
21
+ * The host never writes a page, never writes a Memory record, and never holds
22
+ * the model: every write is the records service's curate stage (§3.1). A failed
23
+ * run is reported, not retried here: the server's tick schedules the retry.
24
+ */
25
+ import { acceptAnswer, jobSessionRules, rulesKey } from "../plugins/grants.js"
26
+ import { recordsOf } from "../tools/share.js"
27
+ import { errorMessage, isPlainObject, oneLine } from "../util.js"
28
+
29
+ /** The heartbeat, and how often a host looks for a run (DESIGN §3.2). */
30
+ export const HEARTBEAT_MS = 60_000
31
+ /** A host still reads a page at a time: the template's budget caps it. */
32
+ export const MAX_PAGES = 5
33
+ export const PAGE_LIMIT = 200
34
+ /** The most events one read's answer may contribute: the same cap a page has. */
35
+ export const MAX_PAGE_ITEMS = 500
36
+
37
+ const REAL_CLOCK = Object.freeze({
38
+ now: () => Date.now(),
39
+ setInterval: (fn, ms) => {
40
+ const handle = setInterval(fn, ms)
41
+ handle?.unref?.()
42
+ return handle
43
+ },
44
+ clearInterval: (handle) => clearInterval(handle),
45
+ })
46
+
47
+ /**
48
+ * The inputs a declared read is called with (§9.1 C): a binding-key input takes
49
+ * the one id the person confirmed, and a per-unit input takes its value from the
50
+ * event's own structured fields — never from its text. A unit whose id is
51
+ * outside the bind's confirmed scope is refused here, **before** the call, so a
52
+ * thread in a channel the person did not confirm is never read.
53
+ *
54
+ * @param {Record<string, string | {perUnit: string, bind: string}>} inputs
55
+ * @param {{scope: object, thread: string|null, externalId: string}} unit
56
+ * @returns {Record<string, string> | null}
57
+ */
58
+ export function perUnitInputs(inputs, { scope, thread, externalId }) {
59
+ const confirmed = isPlainObject(scope) ? scope : {}
60
+ const parts = threadParts(thread)
61
+ const out = {}
62
+ for (const [field, spec] of Object.entries(inputs ?? {})) {
63
+ if (typeof spec === "string") {
64
+ const ids = Array.isArray(confirmed[spec]) ? confirmed[spec] : []
65
+ // One confirmed id is what a binding-key input narrows to. More than one
66
+ // is the person's whole scope, and a read that pins only one of them would
67
+ // be a guess: it is refused rather than picking one.
68
+ if (ids.length !== 1) return null
69
+ out[field] = String(ids[0])
70
+ continue
71
+ }
72
+ if (!isPlainObject(spec) || typeof spec.perUnit !== "string") return null
73
+ const value = spec.perUnit === "external_id" ? externalId : parts?.[spec.perUnit === "thread_channel" ? "channel" : "ts"] ?? null
74
+ if (typeof value !== "string" || value === "") return null
75
+ // The bind is the confirmed scope the id must stay inside.
76
+ const allowed = Array.isArray(confirmed[spec.bind]) ? confirmed[spec.bind] : []
77
+ if (spec.perUnit === "thread_channel" && !allowed.includes(value)) return null
78
+ out[field] = value
79
+ }
80
+ return out
81
+ }
82
+
83
+ /**
84
+ * The events a declared read answered with.
85
+ *
86
+ * A read is a tool, so its answer is the tool's own shape, not the event shape
87
+ * contract 2 fixes for `events_list`. Two shapes are understood, and nothing is
88
+ * guessed: an answer that already holds `events` (a plugin's own listing), and
89
+ * Slack's thread answer, `{ messages: [{ ts, user, text, thread_ts }] }`, which
90
+ * becomes one message event per reply — the reply that was never broadcast
91
+ * included, which is the whole reason a thread is read. Anything else yields no
92
+ * events, and the run stores nothing from it.
93
+ */
94
+ export function eventsOfRead(answer, { thread, source, account, pinnedChannel }) {
95
+ const out = readOutput(answer)
96
+ if (!out) return []
97
+ if (Array.isArray(out.events)) return out.events.slice(0, MAX_PAGE_ITEMS).map((event) => ({ ...event, source: event?.source ?? source, account: event?.account ?? account }))
98
+ if (Array.isArray(out.messages)) return threadEvents(out.messages, { thread, source, account, pinnedChannel })
99
+ return []
100
+ }
101
+
102
+ /** The tool's payload: its `output`, its structured content, or the JSON in a text content block. */
103
+ function readOutput(answer) {
104
+ if (!isPlainObject(answer)) return null
105
+ if (isPlainObject(answer.output)) return answer.output
106
+ if (isPlainObject(answer.structuredContent)) return answer.structuredContent
107
+ const text = Array.isArray(answer.content) ? answer.content.find((block) => block?.type === "text" && typeof block.text === "string")?.text : null
108
+ if (typeof text === "string") {
109
+ try {
110
+ const parsed = JSON.parse(text)
111
+ return isPlainObject(parsed) ? parsed : null
112
+ } catch {
113
+ return null
114
+ }
115
+ }
116
+ return null
117
+ }
118
+
119
+ /** Slack's thread answer as message events: the channel and the thread come from the unit, not from the text. */
120
+ function threadEvents(messages, { thread, source, account, pinnedChannel }) {
121
+ const parts = threadParts(thread)
122
+ if (!parts) return []
123
+ const events = []
124
+ for (const message of messages.slice(0, MAX_PAGE_ITEMS)) {
125
+ if (!isPlainObject(message)) continue
126
+ const ts = typeof message.ts === "string" ? message.ts : null
127
+ if (!ts || !/^\d{1,16}\.\d{1,8}$/.test(ts)) continue
128
+ // A reply from another thread is not this thread's.
129
+ if (typeof message.thread_ts === "string" && message.thread_ts !== parts.ts) continue
130
+ // The channel is the one the **answer** names, else the one the call was
131
+ // pinned to. A message that names none of them is not this thread's.
132
+ const channel = typeof message.channel === "string" && message.channel ? message.channel : typeof message.channel_id === "string" && message.channel_id ? message.channel_id : pinnedChannel
133
+ if (typeof channel !== "string" || channel === "") continue
134
+ const at = Number(ts.split(".")[0])
135
+ if (!Number.isSafeInteger(at)) continue
136
+ const user = typeof message.user === "string" && message.user ? message.user.slice(0, 100) : null
137
+ const said = typeof message.text === "string" ? message.text.slice(0, 4096) : ""
138
+ events.push({
139
+ source,
140
+ account,
141
+ kind: "message",
142
+ external_id: `${channel}:${ts}`,
143
+ occurred_at: new Date(at * 1000).toISOString(),
144
+ thread,
145
+ actors: user ? [{ role: "author", id: `slack:${user}` }] : [],
146
+ title: said.split("\n")[0].slice(0, 300) || "(no text)",
147
+ text: said,
148
+ url: null,
149
+ labels: ["channel", `channel:${channel}`, ts === parts.ts ? "thread-parent" : "thread-reply"],
150
+ })
151
+ }
152
+ return events
153
+ }
154
+
155
+ /**
156
+ * True when the service would admit this event: its kind is one the job collects,
157
+ * and every channel it names is one the person confirmed. The same rule the
158
+ * checkpoint applies, read here so no unit is taken from a page it will refuse.
159
+ */
160
+ export function inScope(event, job) {
161
+ const kinds = Array.isArray(job?.kinds) ? job.kinds : []
162
+ if (kinds.length > 0 && !kinds.includes(event?.kind)) return false
163
+ const confirmed = isPlainObject(job?.scope) ? job.scope : {}
164
+ const allowed = Array.isArray(confirmed.channels) ? confirmed.channels : []
165
+ if (allowed.length === 0) return true
166
+ const labels = Array.isArray(event?.labels) ? event.labels : []
167
+ const channels = labels.filter((label) => typeof label === "string" && label.startsWith("channel:")).map((label) => label.slice("channel:".length))
168
+ if (channels.length === 0) return false
169
+ return channels.every((channel) => allowed.includes(channel))
170
+ }
171
+
172
+ /** `<scheme>-thread:<channel id>:<thread ts>`, or null. */
173
+ function threadParts(thread) {
174
+ if (typeof thread !== "string") return null
175
+ const match = /^[a-z0-9]+-thread:([^:]+):(.+)$/.exec(thread)
176
+ return match ? { channel: match[1], ts: match[2] } : null
177
+ }
178
+
179
+ /** The reserved session a job's reads run in: one per job, so its rules are its own. */
180
+ export function jobSessionId(job) {
181
+ return `ses_mem_job_${String(job.id).replace(/^job_/, "")}`
182
+ }
183
+
184
+ /**
185
+ * The RPC definition a connector's `tools` namespace answers on: `<plugin id>.tools`,
186
+ * with `events_list` and every method the job's steps name. A method the
187
+ * definition omits cannot be called at all, so a `call` step without its method
188
+ * here is a step that silently does nothing.
189
+ */
190
+ export function jobRpcDefinition(job) {
191
+ const io = { input: { type: "object" }, output: { type: "object" } }
192
+ const methods = { events_list: io }
193
+ for (const step of Array.isArray(job?.extract) ? job.extract : []) {
194
+ if (typeof step?.call === "string" && /^[A-Za-z][A-Za-z0-9_]{0,80}$/.test(step.call)) methods[step.call] = io
195
+ }
196
+ return { id: `${job.connector}.tools`, events: {}, methods }
197
+ }
198
+
199
+ /**
200
+ * @param {{ctx: any, runtime: any, toolkit: any, clock?: typeof REAL_CLOCK, hostId?: string}} input
201
+ */
202
+ export function createJobHost({ ctx, runtime, toolkit, clock = REAL_CLOCK, hostId }) {
203
+ const log = runtime?.log
204
+ const id = hostId ?? `host_${process.pid}_${Math.random().toString(36).slice(2, 8)}`
205
+ const sessions = new Map()
206
+ let timer = null
207
+ let active = null
208
+ let last = null
209
+
210
+ async function pickupAgent() {
211
+ const wanted = runtime?.config?.agent
212
+ if (wanted && wanted !== "auto") return wanted
213
+ try {
214
+ const listed = await ctx?.agent?.list?.()
215
+ const agents = (Array.isArray(listed?.data) ? listed.data : Array.isArray(listed) ? listed : []).map((agent) => String(agent?.id ?? agent?.name ?? "")).filter(Boolean)
216
+ return agents.includes("build") ? "build" : agents[0] || "build"
217
+ } catch {
218
+ return "build"
219
+ }
220
+ }
221
+
222
+ /**
223
+ * The job's session, with exactly its grants and no `execute`. An existing
224
+ * session is reused only while its rules hash matches; otherwise it is
225
+ * updated, or removed and made again. **Fail closed:** a session that cannot
226
+ * be made stops the run before anything is read.
227
+ */
228
+ async function ensureSession(job) {
229
+ const sid = jobSessionId(job)
230
+ const permissions = jobSessionRules(job.grants, job.account).map((rule) => ({ ...rule }))
231
+ const hash = rulesKey(permissions)
232
+ const cached = sessions.get(sid)
233
+ if (cached?.hash === hash) return cached.promise
234
+ const promise = (async () => {
235
+ if (typeof ctx?.session?.create !== "function") throw new Error("this host cannot make the job's session")
236
+ const metadata = { memory: { role: "job", job: job.id, rules: hash } }
237
+ const make = async () =>
238
+ ctx.session.create({
239
+ id: sid,
240
+ title: `Memory job: ${oneLine(String(job.name ?? job.id), 80)}`,
241
+ agent: await pickupAgent(),
242
+ ...(ctx?.location?.directory ? { location: { directory: ctx.location.directory } } : {}),
243
+ metadata,
244
+ permissions,
245
+ })
246
+ try {
247
+ await make()
248
+ return sid
249
+ } catch (error) {
250
+ if (!/exist/i.test(errorMessage(error))) throw error
251
+ }
252
+ let current = null
253
+ try {
254
+ const answer = await ctx.session.get?.({ sessionID: sid })
255
+ current = answer?.data ?? answer
256
+ } catch {
257
+ current = null
258
+ }
259
+ if (current?.metadata?.memory?.rules === hash) return sid
260
+ if (typeof ctx.session.update === "function") {
261
+ await ctx.session.update({ sessionID: sid, metadata, permissions })
262
+ return sid
263
+ }
264
+ if (typeof ctx.session.remove === "function") {
265
+ await ctx.session.remove({ sessionID: sid })
266
+ await make()
267
+ return sid
268
+ }
269
+ throw new Error("its rules are out of date, and this host can neither update nor remove it")
270
+ })()
271
+ sessions.set(sid, { hash, promise })
272
+ promise.catch(() => {
273
+ if (sessions.get(sid)?.promise === promise) sessions.delete(sid)
274
+ })
275
+ return promise
276
+ }
277
+
278
+ /** The space the job's space lives in, and the records client, or a refusal. */
279
+ async function place(records, sessionID) {
280
+ if (!toolkit?.control) return { where: { sessionID } }
281
+ const resolved = await toolkit.resolvePrivateSpace({}, { sessionID, agent: runtime?.agentFor?.(sessionID) })
282
+ if (resolved?.invalid || resolved?.error) throw new Error(resolved.invalid ?? resolved.error)
283
+ return { where: { space: resolved.context.space_id, sessionID } }
284
+ }
285
+
286
+ /**
287
+ * One run: read its pages and checkpoint them, then finish. A run that stops
288
+ * early is finished `failed` with the reason; its pages stay stored, and the
289
+ * next run continues from the cursor the job holds.
290
+ */
291
+ async function runJob(records, where, run) {
292
+ let pages = 0
293
+ let accepted = 0
294
+ let duplicates = 0
295
+ let skippedUnits = 0
296
+ try {
297
+ const view = await records.call("jobs.get", { job_id: run.job_id }, where)
298
+ const job = view?.job
299
+ if (!job) throw new Error(`the service knows no job ${run.job_id}`)
300
+ // The source's own identity (§9.2): its owner-only call names the source,
301
+ // and the page's own limit is what a read sends.
302
+ const identity = isPlainObject(view.identity) && isPlainObject(view.identity.input) ? view.identity.input : {}
303
+ const reads = Array.isArray(view.reads) ? view.reads : []
304
+ const sessionID = await ensureSession(job)
305
+ if (typeof ctx?.rpc !== "function") throw new Error("this host gives plugins no tools RPC, so a job cannot read its connector")
306
+ const client = ctx.rpc(jobRpcDefinition(job))
307
+ if (typeof client?.events_list !== "function") throw new Error(`the host has no RPC method ${job.connector}.tools/events_list`)
308
+ const budget = isPlainObject(job.budgets) ? job.budgets : {}
309
+ const maxPages = Math.min(MAX_PAGES, Math.max(1, Number(budget.pagesPerRun) || MAX_PAGES))
310
+ const limit = Math.min(500, Math.max(1, Number(budget.pageLimit) || PAGE_LIMIT))
311
+ let cursor = job.cursor ?? ""
312
+ let more = true
313
+ const seen = []
314
+ let gap = null
315
+ while (more && pages < maxPages) {
316
+ // The page is read from the job's own cursor, with the identity's own
317
+ // input, and the account is always named.
318
+ // The job's confirmed scope travels with the call: contract 2's `scope`
319
+ // narrows and never widens the plugin's own option, so the source reads
320
+ // what the person confirmed and nothing else (§5.3).
321
+ const narrowing = isPlainObject(job.scope) && Object.keys(job.scope).length ? { scope: job.scope } : {}
322
+ const answer = await client.events_list({ sessionID, input: { ...identity, ...narrowing, limit, account: job.account, ...(cursor ? { cursor } : {}) } })
323
+ // A contract-2 answer echoes the scope it read; a contract-1 answer (Slack
324
+ // today) does not, and the scope is then checked item by item on the service,
325
+ // from each event's `channel:<id>` label. Either way the check happens.
326
+ const echoes = isPlainObject(answer?.scope) || isPlainObject(answer?.output?.scope) || (isPlainObject(answer?.scope) && typeof answer.content === "string")
327
+ // The per-run account check: source, account, owner, kinds and scope (§5.3).
328
+ const page = acceptAnswer(answer, {
329
+ source: job.source,
330
+ account: job.account,
331
+ owner: job.owner,
332
+ scope: echoes && isPlainObject(job.scope) ? job.scope : {},
333
+ kinds: Array.isArray(job.kinds) && job.kinds.length ? job.kinds : [""],
334
+ })
335
+ // The scope the page was read for. A contract-2 answer echoes it; a
336
+ // contract-1 answer (Slack today) does not, so the job's own confirmed
337
+ // scope is sent — what was asked for, never what the plugin claims. The
338
+ // service checks each event's channel against it.
339
+ const asked = page.scope ?? (isPlainObject(job.scope) ? job.scope : undefined)
340
+ // §9.3: the source may say it restarted its window. The service judges
341
+ // that, records the one resync a day, and answers where to continue.
342
+ const raw = isPlainObject(answer?.output) ? answer.output : answer
343
+ if (isPlainObject(answer?.gap) || isPlainObject(answer?.output?.gap)) gap = answer?.gap ?? answer.output.gap
344
+ // §8.3.4: `refused[]` is final and does not hold the cursor; `failed[]`
345
+ // is retryable and does, so the page is read again next cadence.
346
+ const refused = Array.isArray(raw?.refused) ? raw.refused : []
347
+ const failed = Array.isArray(raw?.failed) ? raw.failed : []
348
+ const saved = await records.call(
349
+ "jobs.checkpoint",
350
+ {
351
+ run_id: run.id,
352
+ epoch: run.lease_epoch,
353
+ cursor_before: cursor,
354
+ cursor_after: failed.length ? null : page.cursor,
355
+ scope: asked,
356
+ owner: page.owner,
357
+ items: page.events,
358
+ ...(gap ? { gap } : {}),
359
+ ...(refused.length ? { refused } : {}),
360
+ ...(failed.length ? { failed } : {}),
361
+ },
362
+ where,
363
+ )
364
+ accepted += Number(saved?.accepted) || 0
365
+ duplicates += Number(saved?.duplicates) || 0
366
+ pages += 1
367
+ cursor = page.cursor || cursor
368
+ // A held page (failed[]) is read again next cadence; a gap ends the run's
369
+ // reading of this window.
370
+ more = page.more === true && !gap && saved?.held !== "failed"
371
+ seen.push(...page.events)
372
+ }
373
+ // The declared reads, per unit (§9.1 C): the events a template's `call`
374
+ // step asks for, with the unit's own ids filled and pinned to the scope.
375
+ const perUnit = await readUnits(client, { job, reads, sessionID, seen, records, where, run, cursor })
376
+ accepted += perUnit.accepted
377
+ duplicates += perUnit.duplicates
378
+ skippedUnits += perUnit.skipped
379
+ const done = await records.call("jobs.finish", { run_id: run.id, epoch: run.lease_epoch, outcome: "ok", counts: { accepted, duplicates, pages } }, where)
380
+ return { run: run.id, host: id, pages, accepted, duplicates, skipped_units: skippedUnits, outcome: "ok", curate: done?.curate ?? null }
381
+ } catch (error) {
382
+ const why = oneLine(errorMessage(error), 300)
383
+ log?.warn?.("a job run stopped", { run: run.id, error: why })
384
+ try {
385
+ await records.call("jobs.finish", { run_id: run.id, epoch: run.lease_epoch, outcome: "failed", error: why, counts: { accepted, duplicates, pages } }, where)
386
+ } catch (failure) {
387
+ log?.warn?.("the job run could not be finished", { run: run.id, error: oneLine(errorMessage(failure), 200) })
388
+ }
389
+ return { run: run.id, host: id, pages, accepted, duplicates, skipped_units: skippedUnits, outcome: "failed", error: why }
390
+ }
391
+ }
392
+
393
+ /**
394
+ * The job's `call` steps, once per unit: each thread the page listed, read
395
+ * with the unit's own channel and ts, and each answer stored as the events it
396
+ * holds. A unit outside the confirmed scope is counted and skipped, never
397
+ * called (§9.1 C).
398
+ */
399
+ async function readUnits(client, { job, reads, sessionID, seen, records, where, run, cursor }) {
400
+ const steps = (Array.isArray(job.extract) ? job.extract : []).filter((step) => typeof step?.call === "string")
401
+ const out = { accepted: 0, duplicates: 0, skipped: 0 }
402
+ if (steps.length === 0) return out
403
+ const budget = isPlainObject(job.budgets) ? job.budgets : {}
404
+ const maxUnits = Math.max(1, Math.min(200, Number(budget.maxUnits) || 40))
405
+ // §9.1 C: a unit comes from the page **Memory admitted** — the job's confirmed
406
+ // channels and kinds — never from the raw answer. An event the service will
407
+ // refuse must not make a read happen first.
408
+ const units = new Map()
409
+ let outOfScope = 0
410
+ for (const event of seen) {
411
+ if (typeof event?.thread !== "string" || !event.thread) continue
412
+ if (!inScope(event, job)) {
413
+ outOfScope += 1
414
+ continue
415
+ }
416
+ units.set(event.thread, event)
417
+ }
418
+ out.skipped += outOfScope
419
+ for (const step of steps) {
420
+ const read = reads.find((entry) => entry?.method === step.call)
421
+ const call = client?.[step.call]
422
+ // A step whose read the declaration does not list, or the host cannot
423
+ // call, contributes nothing: the grants for it were never in the job.
424
+ if (!read || typeof call !== "function") continue
425
+ let done = 0
426
+ for (const [thread, event] of units) {
427
+ if (done >= maxUnits) break
428
+ const inputs = perUnitInputs(read.scopeInputs, { scope: isPlainObject(job.scope) ? job.scope : {}, thread, externalId: String(event.external_id ?? "") })
429
+ if (inputs === null) {
430
+ out.skipped += 1
431
+ continue
432
+ }
433
+ done += 1
434
+ // §9.1 C: the pinned inputs come **last**, so a template's `with` cannot
435
+ // replace one — the validator refuses such a key, and this is the
436
+ // second line of that defence.
437
+ const answer = await call({ sessionID, input: { ...(isPlainObject(step.with) ? step.with : {}), ...inputs } })
438
+ // The channel the answer speaks for: the pinned one, from the input Memory
439
+ // filled — never the unit's label, which came from the page.
440
+ const pinned = Object.entries(read.scopeInputs ?? {}).find(([, spec]) => isPlainObject(spec) && spec.perUnit === "thread_channel")?.[0]
441
+ const pinnedChannel = pinned ? inputs[pinned] : undefined
442
+ const events = eventsOfRead(answer, { thread, source: job.source, account: job.account, pinnedChannel })
443
+ if (events.length === 0) continue
444
+ const saved = await records.call("jobs.checkpoint", { run_id: run.id, epoch: run.lease_epoch, cursor_before: cursor, cursor_after: cursor, scope: job.scope ?? {}, items: events }, where)
445
+ out.accepted += Number(saved?.accepted) || 0
446
+ out.duplicates += Number(saved?.duplicates) || 0
447
+ }
448
+ }
449
+ return out
450
+ }
451
+
452
+ /** One heartbeat: report, claim at most one run, run it. Nothing else. */
453
+ async function tick({ sessionID } = {}) {
454
+ if (active) return { running: true, since: new Date(active.started).toISOString() }
455
+ const records = recordsOf(toolkit)
456
+ if (!records) return { skipped: "this plugin build has no records client" }
457
+ const started = clock.now()
458
+ active = { started, promise: null }
459
+ active.promise = (async () => {
460
+ try {
461
+ const { where } = await place(records, sessionID)
462
+ try {
463
+ await records.call("jobs.host", { host_id: id, kind: "personal", user: runtime?.config?.user ?? null, plugins: [], bindings: [] }, where)
464
+ } catch (error) {
465
+ log?.debug?.("the host report was not recorded", { error: oneLine(errorMessage(error), 160) })
466
+ }
467
+ // The bind-like consent flow (§5.2, §5.6): the person asked to confirm
468
+ // a job version, so their own host reads which account the connector is
469
+ // signed in as, and reports it for them to confirm. Nothing is stored
470
+ // from it: the console confirms, not this host.
471
+ const probed = await probePending(records, where).catch((error) => {
472
+ log?.warn?.("the job host could not report a requested account", { error: oneLine(errorMessage(error), 200) })
473
+ return []
474
+ })
475
+ const claimed = await records.call("jobs.claim", { host_id: id }, where)
476
+ if (!claimed?.run) {
477
+ last = { at: new Date(started).toISOString(), claimed: null, probed, why: claimed?.why ?? "nothing_due" }
478
+ return last
479
+ }
480
+ last = { at: new Date(started).toISOString(), probed, ...(await runJob(records, where, claimed.run)) }
481
+ return last
482
+ } catch (error) {
483
+ last = { at: new Date(started).toISOString(), error: oneLine(errorMessage(error), 300) }
484
+ log?.warn?.("the job host could not take a run", { error: last.error })
485
+ return last
486
+ } finally {
487
+ active = null
488
+ }
489
+ })()
490
+ return active.promise
491
+ }
492
+
493
+ /** The `{account, source, owner}` a connector's answer names, without judging it (a probe has no owner to judge against yet). */
494
+ function accountOf(answer) {
495
+ const out = isPlainObject(answer?.output) ? answer.output : isPlainObject(answer?.data) ? answer.data : answer
496
+ const owner = isPlainObject(out?.owner) && typeof out.owner.id === "string" && out.owner.id ? { id: out.owner.id.slice(0, 300), label: String(out.owner.label ?? out.owner.id).slice(0, 300) } : null
497
+ return { account: typeof out?.account === "string" ? out.account : null, source: typeof out?.source === "string" ? out.source : null, owner }
498
+ }
499
+
500
+ /**
501
+ * For each job whose version the person asked to confirm (`jobs.request`),
502
+ * read one page in that version's own session and report the account. The
503
+ * service refuses an answer from anyone but the person who asked, so this
504
+ * only ever confirms the person's own request.
505
+ */
506
+ async function probePending(records, where) {
507
+ let listed
508
+ try {
509
+ listed = await records.call("jobs.list", {}, where)
510
+ } catch {
511
+ return []
512
+ }
513
+ const pending = (Array.isArray(listed?.jobs) ? listed.jobs : []).filter((job) => job?.request?.state === "requested" && job.draft)
514
+ const done = []
515
+ for (const job of pending) {
516
+ const version = job.draft
517
+ const doc = isPlainObject(version.doc) ? version.doc : {}
518
+ const spec = { ...job, ...doc, id: job.id, account: doc.account ?? job.account, grants: doc.grants ?? job.grants }
519
+ try {
520
+ if (typeof ctx?.rpc !== "function") continue
521
+ const sessionID = await ensureSession(spec)
522
+ const client = ctx.rpc(jobRpcDefinition(spec))
523
+ if (typeof client?.events_list !== "function" || !spec.account) continue
524
+ // **No events are read**: a probe asks for none, because all it needs is
525
+ // the account and owner the connector answers with (DESIGN §9.3).
526
+ const answer = await client.events_list({ sessionID, input: { limit: 0, account: spec.account } })
527
+ const read = accountOf(answer)
528
+ if (!read.owner) continue
529
+ await records.call("jobs.probe", { job_id: job.id, version: version.version, digest: version.digest, account: read.account ?? spec.account, owner: read.owner }, where)
530
+ done.push({ job: job.id, version: version.version })
531
+ } catch (error) {
532
+ log?.debug?.("a job's account could not be read", { job: job.id, error: oneLine(errorMessage(error), 160) })
533
+ }
534
+ }
535
+ return done
536
+ }
537
+
538
+ /**
539
+ * The heartbeat timer. It starts from plugin setup, behind the existing
540
+ * switch: a host turned off is a host that claims nothing, and the leases of
541
+ * J0 are unchanged (a run is claimed once, by one host, at one epoch).
542
+ */
543
+ function start() {
544
+ if (timer) return false
545
+ timer = clock.setInterval(() => {
546
+ tick().catch((error) => log?.warn?.("the job host tick failed", { error: oneLine(errorMessage(error), 200) }))
547
+ }, HEARTBEAT_MS)
548
+ return true
549
+ }
550
+
551
+ function stop() {
552
+ if (timer) clock.clearInterval(timer)
553
+ timer = null
554
+ }
555
+
556
+ return { id, tick, start, stop, started: () => Boolean(timer), status: () => last, ensureSession, jobSessionId }
557
+ }
@@ -0,0 +1,110 @@
1
+ /**
2
+ * #58's operation errors, in the words the issue uses: an action answers
3
+ * `{ok: true, …}` or fails with one of these codes, and every failure says what
4
+ * happened and what to do next (`CODE: what. Next step: …`, Memory's family).
5
+ *
6
+ * These are the codes Jelly binds a control to, so they are fixed here rather
7
+ * than derived from a service's own vocabulary: a control-plane `forbidden` on
8
+ * a page is `NOT_OWNER` to the person, a records `space_read_only` is
9
+ * `SPACE_READ_ONLY`, and so on (`fromService`, below).
10
+ */
11
+ export const CODES = Object.freeze({
12
+ NOT_FOUND: "NOT_FOUND",
13
+ VERSION_CONFLICT: "VERSION_CONFLICT",
14
+ SPACE_READ_ONLY: "SPACE_READ_ONLY",
15
+ NOT_OWNER: "NOT_OWNER",
16
+ NEEDS_APPROVAL: "NEEDS_APPROVAL",
17
+ ALREADY_MEMBER: "ALREADY_MEMBER",
18
+ REQUEST_PENDING: "REQUEST_PENDING",
19
+ SCOPE_MISSING: "SCOPE_MISSING",
20
+ P2_UNAVAILABLE: "P2_UNAVAILABLE",
21
+ INVALID: "INVALID",
22
+ })
23
+
24
+ export class OperationError extends Error {
25
+ /**
26
+ * @param {keyof CODES} code
27
+ * @param {string} what what happened, in one sentence
28
+ * @param {string} next what to do about it
29
+ * @param {{ cause?: unknown, extra?: Record<string, unknown> }} [options]
30
+ */
31
+ constructor(code, what, next, options = {}) {
32
+ super(`${code}: ${what} Next step: ${next}`)
33
+ this.name = "OperationError"
34
+ this.code = CODES[code] ? code : "INVALID"
35
+ this.what = what
36
+ this.next = next
37
+ if (options.cause !== undefined) this.cause = options.cause
38
+ if (options.extra) Object.assign(this, options.extra)
39
+ }
40
+ }
41
+
42
+ /** The service's own code, wherever a service put it. */
43
+ function serviceCode(error) {
44
+ return String(error?.errorCode ?? error?.code ?? error?.error?.code ?? "")
45
+ }
46
+
47
+ /**
48
+ * Map a service failure onto #58's words. The service's code is kept in
49
+ * `serviceCode`, so a caller can log exactly what the server said without
50
+ * replaying it as the person's answer.
51
+ */
52
+ export function fromService(error, fallback = "INVALID") {
53
+ if (error instanceof OperationError) return error
54
+ const code = serviceCode(error)
55
+ const message = String(error?.what ?? error?.message ?? error ?? "").replace(/^[A-Z0-9_]+:\s*/, "")
56
+ const next = String(error?.next ?? "")
57
+ const mapped = (() => {
58
+ switch (code) {
59
+ case "not_found":
60
+ case "space_missing":
61
+ return "NOT_FOUND"
62
+ case "version_conflict":
63
+ case "revision_conflict":
64
+ return "VERSION_CONFLICT"
65
+ case "space_read_only":
66
+ case "read_only":
67
+ return "SPACE_READ_ONLY"
68
+ case "page_lines_kept":
69
+ case "team_delete_console_only":
70
+ case "grant_reshare_forbidden":
71
+ case "resource_transfer_forbidden":
72
+ case "not_a_member":
73
+ return "NOT_OWNER"
74
+ case "already_member":
75
+ case "member_exists":
76
+ return "ALREADY_MEMBER"
77
+ case "request_pending":
78
+ return "REQUEST_PENDING"
79
+ case "no_space":
80
+ case "space_required":
81
+ return "SCOPE_MISSING"
82
+ case "session_required":
83
+ // A person's act (a handover) is a console session or a host grant; a
84
+ // key cannot stand in for the person.
85
+ return "NEEDS_APPROVAL"
86
+ case "digest_required":
87
+ case "preview_required":
88
+ case "pinned_confirmation_required":
89
+ return "NEEDS_APPROVAL"
90
+ case "p2_unavailable":
91
+ // The one place the missing secret is named: a control-plane act
92
+ // cannot be carried without a reservation (docs/design/p2-control.md).
93
+ return "P2_UNAVAILABLE"
94
+ default:
95
+ // Only a conflict the service names a version for is VERSION_CONFLICT;
96
+ // any other 409 (a name taken, a cap reached) is the caller's input.
97
+ return String(error?.status) === "404" ? "NOT_FOUND" : fallback
98
+ }
99
+ })()
100
+ const defaultNext =
101
+ mapped === "P2_UNAVAILABLE"
102
+ ? "Set the same P2_RESERVATION_KEY (32 bytes or longer) in records, the gateway and control, then press again; until then, make this change in Memory's console."
103
+ : "Read the record again and retry, or ask the person."
104
+ const failure = new OperationError(mapped, message || "the server refused it", next || defaultNext, { cause: error })
105
+ if (code) failure.serviceCode = code
106
+ // The HTTP status rides along: an operation that needs it (a page op, where
107
+ // a 403 is the person's own page rule) reads it rather than re-deriving it.
108
+ failure.status = Number(error?.status) || null
109
+ return failure
110
+ }