@joe-broadhead/opencode-mem 0.12.3 → 0.12.4

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 CHANGED
@@ -3,6 +3,50 @@
3
3
  The format follows Keep a Changelog 1.1.0: one `## [x.y.z] - date` section per
4
4
  release.
5
5
 
6
+ ## [0.12.4] - 2026-11-18
7
+
8
+ ### Fixed
9
+
10
+ - X is collected once a day. Its reads are billed, so the owner's cadence policy now outranks both the
11
+ registry's own cadence and a plugin's declared `cadence.providerMinMinutes`, for a legacy binding
12
+ and a declared source alike.
13
+ - A failed collection no longer uses up its binding's cadence: a binding that fails is due again after
14
+ the shorter of its cadence and an hour. A successful binding keeps its cadence. Live at 22:37Z on
15
+ 2026-11-17, X failed and the next timer run skipped it as not due, which a daily cadence would have
16
+ stretched to a day.
17
+ - Memory reads the plugin list OpenCode actually answers: `ctx.plugin.list()` gives
18
+ `{ location, data: [...] }` on 2.2.6, not an array. Discovery and re-verification read only an array,
19
+ so they saw no plugin, published no declaration, and every bind fell back to the previous contract.
20
+ An answer that is neither shape is read as no list, with a warning.
21
+ - A configuration reload that leaves two instances in one process no longer leaves the surviving one
22
+ without the collector lease until its next 30-minute tick: an instance that is not the holder takes
23
+ a lease that is free at its next heartbeat, and collects what is due, so a reload does not read a
24
+ billed source whose cadence is not up.
25
+ - A run whose collector service was asked to stop writes no source status and reports nothing, so an
26
+ instance being disposed cannot mark every binding failing with its own missing plugin RPCs. An
27
+ `RPC is unavailable` answer is transient: the binding keeps its last good state, and the run says
28
+ retry next run.
29
+ - A collection's failure reads as one line of text with its code (`Why: AUTH_REQUIRED: the Slack
30
+ plugin is not signed in`), never `Why: [object Object]`. The placeholder came from a failure that
31
+ arrived as an object and met `String()`: at the records service, which stored it, and at the
32
+ console, which rendered it. Both now read a failure for its `code` and `message`, and the
33
+ collector reports its own failures with the code the contract's table named.
34
+ - A collector on another machine no longer marks a binding failing. Every report names the machine
35
+ that made it, and a binding's failing state stands only when the collector that last succeeded
36
+ for it is the one that failed; another machine's failure is kept beside the binding, named and
37
+ timed, and said on Sources without calling it failing. A pause from that machine is not applied
38
+ either. A machine started from a snapshot with the person's Memory sign-in and none of the
39
+ source's can no longer stop the machine that reads the source.
40
+ - A source whose account names the machine that reads it (`history`) is never read or reported by
41
+ a collector on another machine, so a guest cannot turn it failing.
42
+
43
+ ### Deploy
44
+
45
+ The records service needs a deploy before these reports are read as here: `sources.collected` and
46
+ `plugins.pause` take a `host`, and `source_collections` gains `host`, `elsewhere_host`,
47
+ `elsewhere_at` and `elsewhere_error`. Additive, with no migration: an older service ignores the
48
+ fields, and an older collector sends none, which keeps the previous rule.
49
+
6
50
  ## [0.12.3] - 2026-11-17
7
51
 
8
52
  ### Fixed
package/README.md CHANGED
@@ -590,7 +590,7 @@ machine collects every 30 minutes (`collect`, `collectEveryMinutes`,
590
590
  console as the next step), outside the person's own personal space, and for
591
591
  any account their own collector did not report.
592
592
  - **Cadence and setup.** Each source has its own cadence in the registry (X,
593
- which is billed, every 120 minutes). A bind passes on the source's own setup
593
+ which is billed, once a day). A bind passes on the source's own setup
594
594
  step: Slack needs its `events.channels` option, and X should have
595
595
  `"events": {"maxCalls": 2}` (and `ownsXApp` only if the account owns the app).
596
596
  - **Without routines, collection only buffers.** The records service's
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@joe-broadhead/opencode-mem",
3
- "version": "0.12.3",
3
+ "version": "0.12.4",
4
4
  "type": "module",
5
5
  "description": "Durable private and shared-space memory for OpenCode agents",
6
6
  "license": "MIT",
@@ -57,7 +57,7 @@ await tools.mem.spaces({ action: "sources", unbind: { source: "gmail", account:
57
57
 
58
58
  Collection runs with no model: every 30 minutes while OpenCode runs (one process
59
59
  per machine), and on Jelly a declared routine also wakes it. A billed source
60
- runs less often (X every 120 minutes). `spaces` `health` shows the last run,
60
+ runs less often (X, which is billed, once a day). `spaces` `health` shows the last run,
61
61
  each source's counts and errors, and whether **routines** run, with the model.
62
62
 
63
63
  **Collection without routines only buffers.** When health says `routines: off`,
@@ -1,9 +1,10 @@
1
1
  import fs from "node:fs"
2
+ import os from "node:os"
2
3
  import path from "node:path"
3
4
  import { DEFAULT_ACCOUNT, cadenceMs, collectSessionId, collectSessionRules, collectableSources, createCollector, hostBrokerTransport, hostSourceLister, hostSourceProber, rulesHash } from "./collector.js"
4
5
  import { createLease } from "./collector-lock.js"
5
6
  import { knownSources, sourceEntry } from "./sources.js"
6
- import { errorMessage, isPlainObject, oneLine } from "./util.js"
7
+ import { errorMessage, failureText, isPlainObject, oneLine } from "./util.js"
7
8
  import { recordsOf } from "./tools/share.js"
8
9
  import { unboundOwner } from "./backend/records.js"
9
10
 
@@ -18,7 +19,9 @@ export const CATCH_UP_RUNS = 10
18
19
  export const STARTUP_JITTER_MS = Object.freeze([10_000, 60_000])
19
20
  /** A source is due this long before its cadence is up, so a 30-minute timer does not skip a 30-minute source by a few seconds. */
20
21
  export const DUE_SLACK_MS = 60_000
21
- /** Triggers a person started: they collect every bound source, whatever its cadence. */
22
+ /** A binding whose last attempt failed is due again after the shorter of its cadence and this (0.12.4). */
23
+ export const RETRY_MS = 60 * 60_000
24
+ /** Triggers a person started: they collect every bound source, whatever its cadence. A take-over is not one: it is a startup run, and collects what is due. */
22
25
  const ASKED = new Set(["tool", "command", "request"])
23
26
 
24
27
  const REAL_CLOCK = Object.freeze({
@@ -46,7 +49,8 @@ const REAL_CLOCK = Object.freeze({
46
49
  * request (`mem_collect`, `/mem-collect`). `collect: false` (or
47
50
  * `MEMORY_COLLECT=0`) turns the timer off; a request still runs. A timer
48
51
  * run collects a source only when its own cadence is up (the registry's
49
- * `everyMinutes`: X every 120 minutes); a request collects every source.
52
+ * `everyMinutes`: X, which is billed, once a day); a request collects every
53
+ * source.
50
54
  * - **Bind requests:** each run first answers the person's bind requests
51
55
  * (`sources.list` `requests`): only for those sources, it reads the
52
56
  * signed-in account and reports it (`sources.report`) for the person to
@@ -71,7 +75,7 @@ const REAL_CLOCK = Object.freeze({
71
75
  * lease?: ReturnType<typeof createLease>,
72
76
  * }} input
73
77
  */
74
- export function createCollectorService({ ctx, runtime, toolkit, clock = REAL_CLOCK, random = Math.random, waitMs = COLLECT_WAIT_MS, lease }) {
78
+ export function createCollectorService({ ctx, runtime, toolkit, clock = REAL_CLOCK, random = Math.random, waitMs = COLLECT_WAIT_MS, lease, host = os.hostname() }) {
75
79
  const config = runtime.config
76
80
  const log = runtime.log
77
81
  const stateDir = config.stateDir
@@ -246,6 +250,7 @@ export function createCollectorService({ ctx, runtime, toolkit, clock = REAL_CLO
246
250
  const brokerState = { timedOut: false, embedded: new Set() }
247
251
  const collector = createCollector({
248
252
  scheduler: null,
253
+ host,
249
254
  lister: hostSourceLister(ctx, { broker: hostBrokerTransport(ctx, { state: brokerState }), brokerState }),
250
255
  prober: hostSourceProber(ctx),
251
256
  log,
@@ -263,6 +268,8 @@ export function createCollectorService({ ctx, runtime, toolkit, clock = REAL_CLO
263
268
 
264
269
  /** A run's refusal once the lease is another process's: it must not read, write or report as a holder. */
265
270
  const LOST = "another OpenCode process holds the collector lease now; this run stopped before writing more"
271
+ /** A run's refusal once the service was asked to stop: a reload disposed this instance, so its run writes nothing more. */
272
+ const STOPPING = "this collector service was asked to stop; the run stopped before writing more"
266
273
 
267
274
  function writeStatus(status) {
268
275
  try {
@@ -326,7 +333,7 @@ export function createCollectorService({ ctx, runtime, toolkit, clock = REAL_CLO
326
333
  * Start one collection unless one is running here, memory is unavailable, or
327
334
  * another process holds the lease. Returns at once.
328
335
  *
329
- * @param {"startup" | "timer" | "catch-up" | "request" | "tool" | "command"} trigger
336
+ * @param {"startup" | "timer" | "catch-up" | "takeover" | "request" | "tool" | "command"} trigger
330
337
  * @returns {Promise<{ started: true } | { running: true, since: string } | { skipped: string }>}
331
338
  */
332
339
  async function begin(trigger, { only, sessionID } = {}) {
@@ -382,6 +389,7 @@ export function createCollectorService({ ctx, runtime, toolkit, clock = REAL_CLO
382
389
  * taker) never writes as a holder — not even the run's first status line.
383
390
  */
384
391
  function guard() {
392
+ if (stopped) throw new Error(STOPPING)
385
393
  if (stillHolder()) return
386
394
  throw new Error(LOST)
387
395
  }
@@ -424,6 +432,7 @@ export function createCollectorService({ ctx, runtime, toolkit, clock = REAL_CLO
424
432
  const rpc = (binding) => {
425
433
  // Read nothing as a holder that has lost the lease (a machine that woke
426
434
  // after another process took over): the binding is reported, not read.
435
+ if (stopped) throw new Error(STOPPING)
427
436
  if (!stillHolder()) throw new Error(LOST)
428
437
  return rpcSession(null, binding)
429
438
  }
@@ -449,7 +458,15 @@ export function createCollectorService({ ctx, runtime, toolkit, clock = REAL_CLO
449
458
  // The reason is the source's own failure text and the store keeps it for
450
459
  // every process and the console to read: redacted here, where it is
451
460
  // stored, not only where it is shown (0.10.4's gate; review F1).
452
- pause: (binding, reason, code) => call("plugins.pause", { source: binding.source, account: binding.account, reason: oneLine(errorMessage(reason), 200), code }, where),
461
+ // `host` says which machine asked: a pause from one that is not the
462
+ // binding's collector is not applied (0.12.3), as its collection report
463
+ // does not turn the binding failing.
464
+ pause: (binding, reason, code) => {
465
+ // A run whose service was asked to stop pauses nothing: the instance is
466
+ // being disposed, and the store is not told what its dead RPCs said.
467
+ if (stopped) return Promise.resolve()
468
+ return call("plugins.pause", { source: binding.source, account: binding.account, reason: oneLine(errorMessage(reason), 200), code, host }, where)
469
+ },
453
470
  ingest: async (input) => {
454
471
  // And write nothing as one: the page never lands, and the run leaves the
455
472
  // status to the holder that has the lease.
@@ -476,12 +493,22 @@ export function createCollectorService({ ctx, runtime, toolkit, clock = REAL_CLO
476
493
  * report never fails the collection.
477
494
  */
478
495
  async function reportCollections(call, where, results) {
496
+ // A service asked to stop reports nothing: its run is the instance being
497
+ // disposed, and its plugin RPCs are already gone (0.12.4, live at 22:19Z on
498
+ // 2026-11-17), so every binding would be reported failing for the host's
499
+ // state rather than its own.
500
+ if (stopped) return
479
501
  for (const result of results) {
480
- if (result.notDue || typeof result.source !== "string") continue
502
+ if (stopped) return
503
+ // Not due, and another machine's binding, are not this run's reports.
504
+ if (result.notDue || result.otherHost || result.transient || typeof result.source !== "string") continue
481
505
  // `more` travels with the report (review S5): the console's Sources row says
482
506
  // "catching up" from records, so it must know the run left pages behind.
483
- const body = { source: result.source, account: result.account ?? "default", ok: !result.error, accepted: Number.isInteger(result.accepted) ? result.accepted : undefined, more: result.more === true }
484
- if (result.error) body.error = oneLine(errorMessage(result.error), 300)
507
+ // `host` is this machine: the records service shows a binding's failing
508
+ // state only for the collector that last succeeded for it, so a machine
509
+ // with no sign-in to the source cannot turn it failing (0.12.3).
510
+ const body = { source: result.source, account: result.account ?? "default", ok: !result.error, accepted: Number.isInteger(result.accepted) ? result.accepted : undefined, more: result.more === true, host }
511
+ if (result.error) body.error = reasonText(result, 300)
485
512
  try {
486
513
  await call("sources.collected", body, where)
487
514
  } catch (error) {
@@ -492,9 +519,14 @@ export function createCollectorService({ ctx, runtime, toolkit, clock = REAL_CLO
492
519
 
493
520
  function finish(trigger, started, results, error, none = false, { probes = [], collected } = {}) {
494
521
  const ended = clock.now()
495
- // When each binding was last attempted, for its cadence: kept across runs and processes in collector.json.
522
+ // The point each binding's cadence counts from, kept across runs and
523
+ // processes in collector.json. A success counts from the run's start; a
524
+ // failed attempt counts from earlier, so the binding is due again after the
525
+ // shorter of its cadence and an hour (0.12.4). A failure must not use up a
526
+ // billed source's day: live at 22:37Z on 2026-11-17, X failed, and the
527
+ // 22:49Z run skipped it as not due.
496
528
  const at = { ...(collected ?? (isPlainObject(readStatus()?.collected) ? readStatus().collected : {})) }
497
- for (const result of results) if (!result.notDue) at[keyOf(result)] = new Date(started).toISOString()
529
+ for (const result of results) if (!result.notDue && !result.otherHost) at[keyOf(result)] = new Date(cadencePoint(result, started)).toISOString()
498
530
  last = {
499
531
  state: error ? "failed" : "done",
500
532
  trigger,
@@ -508,9 +540,12 @@ export function createCollectorService({ ctx, runtime, toolkit, clock = REAL_CLO
508
540
  collected: at,
509
541
  }
510
542
  // A run writes no status as a holder unless the lock still proves it is
511
- // one: the check is made now, not only when the run first noticed.
512
- if (!leaseLost) stillHolder()
513
- if (leaseLost) log?.info?.("collection run stopped: the lease is another process's", { trigger })
543
+ // one: the check is made now, not only when the run first noticed. A
544
+ // service asked to stop writes none either: its run is the instance being
545
+ // disposed, and its state is not the machine's (0.12.4).
546
+ if (!stopped && !leaseLost) stillHolder()
547
+ if (stopped) log?.info?.("collection run stopped with the service; it wrote no status", { trigger })
548
+ else if (leaseLost) log?.info?.("collection run stopped: the lease is another process's", { trigger })
514
549
  else writeStatus(last)
515
550
  const behind = results.some((result) => result.more && !result.error)
516
551
  if (behind && catchUps < CATCH_UP_RUNS && !stopped) {
@@ -541,11 +576,27 @@ export function createCollectorService({ ctx, runtime, toolkit, clock = REAL_CLO
541
576
  /* already taken */
542
577
  }
543
578
  }
579
+ // The holder may have gone without its lease going stale: a configuration
580
+ // reload disposes one of two instances and its stop() releases the lease,
581
+ // and the survivor that skipped its startup run must not wait for its next
582
+ // interval tick (0.12.4, live at 22:19Z on 2026-11-17). Take a lease that
583
+ // is free now and collect once; the one-holder rule is the same acquire.
584
+ if (!leader && !active && !stopped && freeLease()) safely("takeover")
544
585
  } catch (error) {
545
586
  log?.warn?.("collector heartbeat failed", { error: errorMessage(error) })
546
587
  }
547
588
  }
548
589
 
590
+ /** True when no process holds the lease, or the one it names stopped beating: the next beat may take it. */
591
+ function freeLease() {
592
+ try {
593
+ const current = lock.holder()
594
+ return !current || lock.isStale(current)
595
+ } catch {
596
+ return false
597
+ }
598
+ }
599
+
549
600
  /** Start the timers. Returns at once; the first run comes after a short random wait. */
550
601
  function start() {
551
602
  if (!config.collect) {
@@ -697,6 +748,31 @@ function keyOf(row) {
697
748
  return `${row?.source ?? ""}\u0000${row?.account || DEFAULT_ACCOUNT}`
698
749
  }
699
750
 
751
+ /**
752
+ * The point a binding's cadence counts from after a run: the run's start, or
753
+ * for a failed attempt earlier by the part of the cadence beyond an hour, so the
754
+ * binding is due again after the shorter of its cadence and an hour. A billed
755
+ * source that fails is retried no more often than that, and a transient failure
756
+ * costs at most that (0.12.4).
757
+ */
758
+ function cadencePoint(result, started) {
759
+ if (!result.error) return started
760
+ const cadence = cadenceMs(result.source)
761
+ return started - (cadence - Math.min(cadence, RETRY_MS))
762
+ }
763
+
764
+ /**
765
+ * A result's reason as one line: `CODE: message` when the run kept the
766
+ * contract's code (`AUTH_REQUIRED` is a sign-in), else the message alone. A
767
+ * failure that arrived as an object reads as its own words; `String(object)`,
768
+ * which is `[object Object]`, is never what a person sees (0.12.3).
769
+ */
770
+ function reasonText(result, max = 300) {
771
+ const raw = result?.error
772
+ if (typeof raw === "string") return failureText({ code: result?.code, message: raw }, max)
773
+ return failureText(raw ?? result?.reason, max)
774
+ }
775
+
700
776
  /**
701
777
  * What the status file keeps of one result. The file is read by every process
702
778
  * and by the console, and it holds text a source or a plugin wrote — a
@@ -706,7 +782,7 @@ function keyOf(row) {
706
782
  */
707
783
  export function storedResult(result) {
708
784
  const kept = { ...result }
709
- if (kept.error) kept.error = oneLine(errorMessage(kept.error), 300)
785
+ if (kept.error) kept.error = reasonText(kept, 300)
710
786
  if (kept.refused_reason) kept.refused_reason = oneLine(errorMessage(kept.refused_reason), 200)
711
787
  if (kept.setup) kept.setup = oneLine(errorMessage(kept.setup), 400)
712
788
  if (kept.held) kept.held = oneLine(errorMessage(kept.held), 100)
@@ -729,6 +805,12 @@ export function describeProbe(probe) {
729
805
  /** One source's line: its counts, what it refused, and why it stopped. */
730
806
  export function describeResult(result) {
731
807
  if (result.notDue) return `${oneLine(result.source ?? "?", 40)}:${oneLine(result.account ?? "?", 80)}: not due (collected every ${Number(result.everyMinutes) || 30} minutes)`
808
+ // Another machine's host-bound binding (0.12.3): said, and not a failure.
809
+ if (result.otherHost) return `${oneLine(result.source ?? "?", 40)}:${oneLine(result.account ?? "?", 80)}: only ${oneLine(result.otherHost, 80)} collects it, so this machine leaves it alone`
810
+ // The plugin's RPC is not registered yet, or no longer (a reload): the host's
811
+ // state, not the binding's failure, so it is not called stopped and it keeps
812
+ // the state it had (0.12.4).
813
+ if (result.transient) return `${oneLine(result.source ?? "?", 40)}:${oneLine(result.account ?? "?", 80)}: ${oneLine(errorMessage(result.error ?? "the plugin's RPC is not available"), 240)}; retry next run`
732
814
  const counts = `${Number(result.accepted) || 0} new, ${Number(result.duplicates) || 0} already had, ${Number(result.refused) || 0} refused, ${Number(result.pages) || 0} page(s)`
733
815
  // A refused event is a real loss — the contract's cursor moves past it — so
734
816
  // the line names the newest one and why, not only how many (DESIGN §2.3.1).
@@ -741,5 +823,5 @@ export function describeResult(result) {
741
823
  // object, and the 0.10.3 gate (A15) caught an answer repeating the placeholder.
742
824
  // The refusal trace is build/0.11’s (fix/source-kinds): a refused event is a
743
825
  // real loss, so the line names the newest one and why.
744
- return `${name}: ${result.error ? `stopped (${oneLine(errorMessage(result.error), 240)}); ` : ""}${counts}${refused}${result.more ? "; more waits for the next run" : ""}${result.setup ? `; the source says: ${oneLine(errorMessage(result.setup), 240)}` : ""}`
826
+ return `${name}: ${result.error ? `stopped (${reasonText(result, 240)}); ` : ""}${counts}${refused}${result.more ? "; more waits for the next run" : ""}${result.setup ? `; the source says: ${oneLine(errorMessage(result.setup), 240)}` : ""}`
745
827
  }
package/src/collector.js CHANGED
@@ -1,7 +1,7 @@
1
1
  import { errorMessage, isPlainObject, oneLine } from "./util.js"
2
2
  import { createHash } from "node:crypto"
3
3
  import { isSourceName } from "./source-ids.js"
4
- import { ACCOUNT_NAME, DEFAULT_EVERY_MINUTES, contractRefusal, resolveDeclaredSource, rpcDefinition, sourceAllowRules, sourceEntry } from "./sources.js"
4
+ import { ACCOUNT_NAME, DEFAULT_EVERY_MINUTES, contractRefusal, hostBoundSource, resolveDeclaredSource, rpcDefinition, sourceAllowRules, sourceEntry } from "./sources.js"
5
5
  import { acceptAnswer, probe, read } from "./plugins/source-contract/vendor/read.js"
6
6
  import { isBrokerAnswer, sourceReader } from "./plugins/source-contract/vendor/broker-client.js"
7
7
  import { probeResultProblems } from "./plugins/source-contract/vendor/events.js"
@@ -165,6 +165,47 @@ export function collectableSources(sources, { only } = {}) {
165
165
  return [...seen.values()].sort((a, b) => bindingKey(a).localeCompare(bindingKey(b)))
166
166
  }
167
167
 
168
+ /**
169
+ * The machine a host-bound binding belongs to, when it is not this one, or
170
+ * null. A host-bound source's account names the machine whose own files it
171
+ * reads (src/sources.js `hostBoundSource`): another machine's collector never
172
+ * reads it, and never reports on it, so it cannot turn the binding failing
173
+ * (0.12.3). Hostnames are case-insensitive.
174
+ *
175
+ * @param {{ source?: string, account?: string }} binding
176
+ * @param {string | null | undefined} host this collector's machine
177
+ * @returns {string | null} the machine the binding names
178
+ */
179
+ export function foreignHostSource(binding, host) {
180
+ if (!hostBoundSource(binding?.source)) return null
181
+ const named = String(binding?.account ?? "").trim()
182
+ const here = String(host ?? "").trim()
183
+ if (!named || !here || named.toLowerCase() === here.toLowerCase()) return null
184
+ return named
185
+ }
186
+
187
+ /** The host's tools RPC has no plugin registered under that id right now: the plugin is starting, reloading or unloaded. */
188
+ function rpcUnavailable(error) {
189
+ return error?.type === "rpc.unavailable" || /^RPC is unavailable\b/.test(String(error?.message ?? ""))
190
+ }
191
+
192
+ /**
193
+ * Mark a result whose failure is the host's RPC, not the binding's: it keeps
194
+ * its last good state in the store (nothing is reported for it), and the run
195
+ * says when it reads again (0.12.4, live at 22:19Z on 2026-11-17: a plugin
196
+ * being reloaded answered `RPC is unavailable`, and five bindings were reported
197
+ * failing).
198
+ */
199
+ function transient(result, error, failure) {
200
+ if (!rpcUnavailable(error)) return false
201
+ result.transient = true
202
+ result.retry = "next run"
203
+ result.error = failure.message
204
+ result.code = undefined
205
+ result.action = undefined
206
+ return true
207
+ }
208
+
168
209
  /** The input every `events_list` call to a binding sends: the page, its account, and the registry's input. */
169
210
  /**
170
211
  * The account an events_list call names: a named binding's, and for a source
@@ -811,7 +852,7 @@ function noteRefusal(result, refusal) {
811
852
  *
812
853
  * @param {{ scheduler?: { list(): Promise<any[]>, create(input: any): Promise<any>, remove(id: string): Promise<void> } | null, lister?: ReturnType<typeof hostSourceLister>, prober?: ReturnType<typeof hostSourceProber>, log?: any }} [input]
813
854
  */
814
- export function createCollector({ scheduler = null, lister = null, prober = null, log } = {}) {
855
+ export function createCollector({ scheduler = null, lister = null, prober = null, log, host = null } = {}) {
815
856
  const reported = new Map()
816
857
 
817
858
  function noteOwner(source, account, owner) {
@@ -879,6 +920,13 @@ export function createCollector({ scheduler = null, lister = null, prober = null
879
920
  // One broker deadline per tick (N7b): a broker that timed out this run does not cost each later binding.
880
921
  lister?.resetBrokerTick?.()
881
922
  for (const binding of collectableSources(sources, { only })) {
923
+ // Another machine's host-bound binding: not read, not reported, and so
924
+ // never turned failing here (0.12.3). The row says whose it is.
925
+ const elsewhere = foreignHostSource(binding, host)
926
+ if (elsewhere) {
927
+ results.push({ ...binding, pages: 0, accepted: 0, duplicates: 0, refused: 0, more: false, otherHost: elsewhere, done: true })
928
+ continue
929
+ }
882
930
  if (!due(binding)) {
883
931
  results.push({ ...binding, pages: 0, accepted: 0, duplicates: 0, refused: 0, more: false, notDue: true, everyMinutes: cadenceMs(binding.source) / 60_000, done: true })
884
932
  continue
@@ -1004,6 +1052,10 @@ export function createCollector({ scheduler = null, lister = null, prober = null
1004
1052
  // §8.3.4: a code is a pause, a hold or a reset. A reset reads once more
1005
1053
  // from the window; a pause pauses the binding through its callback.
1006
1054
  const failure = failureFromError(error)
1055
+ // A plugin whose RPC is not registered yet (or no longer) is the
1056
+ // host's state: the binding keeps the state it had, and this run
1057
+ // retries next run rather than failing the binding (0.12.4).
1058
+ if (transient(result, error, failure)) break
1007
1059
  // A PERMISSION_DENIED is decided by fact, never by its message: the broker's refusal is a changed
1008
1060
  // declaration only when the digest installed now differs from the one the person confirmed. Equal
1009
1061
  // digests mean the access itself was refused (a withdrawn grant, or the provider), which re-consenting
@@ -1059,6 +1111,9 @@ export function createCollector({ scheduler = null, lister = null, prober = null
1059
1111
  result.error = failure.message
1060
1112
  result.code = failure.code
1061
1113
  result.action = failureAction(failure.code).action
1114
+ // The same transient read outside the page loop (a session, a cursor):
1115
+ // the binding keeps its state, and the run retries next run (0.12.4).
1116
+ transient(result, error, failure)
1062
1117
  } finally {
1063
1118
  result.done = true
1064
1119
  }
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * Discovery of plugin-declared Memory (DESIGN-PLUGIN-MEMORY §2.3), read-only:
3
3
  *
4
- * 1. **List** `ctx.plugin.list()`: active `package` and `local` plugins, not
4
+ * 1. **List** `ctx.plugin.list()` (an array, or the host's `{ location, data }`): active `package` and `local` plugins, not
5
5
  * `builtin`, `sdk` or Memory itself.
6
6
  * 2. **Find** each one's installed package (src/plugins/locate.js).
7
7
  * 3. **Read** `name`, `version` and `memory` from that `package.json`. No
@@ -27,6 +27,7 @@
27
27
  * or the protocol.
28
28
  */
29
29
  import { LAYOUT_CHANGED, cacheRoot, locate } from "./locate.js"
30
+ import { pluginList } from "./list.js"
30
31
  import { canonicalJSON, validateManifest } from "./manifest.js"
31
32
  import { CONTRACT_LABELS, readDeclared } from "./descriptor.js"
32
33
  import { setDeclaredSources, setInstalledVersions, sourceEntriesOf } from "../sources.js"
@@ -245,7 +246,7 @@ export function createPluginDiscovery({ ctx, runtime, toolkit, clock = REAL_CLOC
245
246
  if (resolved.invalid || resolved.error) throw new Error(resolved.invalid || resolved.error)
246
247
  where = { space: resolved.context.space_id }
247
248
  }
248
- const result = await discover({ plugins: await ctx.plugin.list(), root: await root(), readRpc: reader, clock })
249
+ const result = await discover({ plugins: pluginList(await ctx.plugin.list(), log), root: await root(), readRpc: reader, clock })
249
250
  // A full report: every plugin this machine has; the records service marks the ones it no longer names as missing.
250
251
  await records.call("plugins.report", { layout: result.layout, full: true, plugins: result.plugins }, where)
251
252
  // The declarations the collector reads under are published **only after**
@@ -0,0 +1,18 @@
1
+ /**
2
+ * What `ctx.plugin.list()` answers, as its list of plugins.
3
+ *
4
+ * OpenCode 2.2.6 answers `{ location, data: [...] }`, not an array (live on the
5
+ * owner's machine at 19:10Z on 2026-11-17: 116 entries), while `/api/plugin`
6
+ * answers a bare array. Both are read here, and anything else is no list at
7
+ * all: a warning in the log, never a throw, and never a plugin.
8
+ *
9
+ * @param {unknown} answer what the host answered
10
+ * @param {{ warn?: (message: string, detail?: object) => void } | null} [log]
11
+ * @returns {any[]} the plugins the answer names, or none
12
+ */
13
+ export function pluginList(answer, log = null) {
14
+ if (Array.isArray(answer)) return answer
15
+ if (answer !== null && typeof answer === "object" && Array.isArray(answer.data)) return answer.data
16
+ log?.warn?.("plugin list is not a list", { shape: answer === null ? "null" : typeof answer })
17
+ return []
18
+ }
@@ -4,7 +4,8 @@
4
4
  * Memory's credential can report a plugin. So before a binding collects, the
5
5
  * collector itself:
6
6
  *
7
- * 1. finds the plugin in OpenCode's own list (`ctx.plugin.list()`), active,
7
+ * 1. finds the plugin in OpenCode's own list (`ctx.plugin.list()`: `{ location, data }` on
8
+ * 2.2.6, a bare array from `/api/plugin`), active,
8
9
  * with no failed twin of the same id;
9
10
  * 2. checks the pin: the same source kind and target or path, and the same
10
11
  * package name, as the person confirmed;
@@ -20,6 +21,7 @@
20
21
  * collector accept what is really on disk, intersected with the consent.
21
22
  */
22
23
  import { LAYOUT_CHANGED, locate } from "./locate.js"
24
+ import { pluginList } from "./list.js"
23
25
  import { validateManifest } from "./manifest.js"
24
26
  import { effectiveSource } from "./grants.js"
25
27
 
@@ -27,12 +29,12 @@ const stop = (kind, reason) => ({ ok: false, stop: kind, reason })
27
29
 
28
30
  /**
29
31
  * @param {{ plugin_id: string, source: string, package: string, pin: { kind: string, ref: string }, digest: string, live_digest?: string | null, snapshot: { source: any }, state: string }} consent
30
- * @param {{ plugins: any[], root: string }} where OpenCode's plugin list and the cache root
32
+ * @param {{ plugins: any[] | { data: any[] }, root: string, log?: { warn?: (message: string, detail?: object) => void } | null }} where OpenCode's plugin list (either shape) and the cache root
31
33
  * @returns {Promise<{ ok: true, effective: ReturnType<typeof effectiveSource>, live: any, digest: string } | { ok: false, stop: string, reason: string }>}
32
34
  */
33
- export async function verifyConsent(consent, { plugins, root }) {
35
+ export async function verifyConsent(consent, { plugins, root, log = null }) {
34
36
  if (consent.state !== "on") return stop("stopped", consent.reason ?? `the binding is ${consent.state}`)
35
- const all = Array.isArray(plugins) ? plugins : []
37
+ const all = pluginList(plugins, log)
36
38
  const info = all.find((entry) => entry?.id === consent.plugin_id && entry?.state?.status === "active")
37
39
  if (!info) return stop("missing", `${consent.plugin_id} is not running in this OpenCode`)
38
40
  if (all.some((entry) => entry?.id === consent.plugin_id && entry?.state?.status === "failed" && /^Duplicate plugin ID\b/.test(String(entry.state.error ?? "")))) {
package/src/sources.js CHANGED
@@ -31,9 +31,41 @@ import { maxBytesOf } from "./plugins/source-contract/vendor/descriptor.js"
31
31
  /** A binding's account name: no wildcard (`*`, `?`), separator (`:`, `/`) or space, and never empty. */
32
32
  export const ACCOUNT_NAME = /^[A-Za-z0-9][A-Za-z0-9_.@+-]{0,127}$/
33
33
 
34
+ /**
35
+ * The sources whose **account names the machine that reads them**: the
36
+ * sessions a history source indexes live in this machine's own files, so a
37
+ * binding of one is that machine's binding, and no other machine can read it
38
+ * (0.12.3). A collector on another machine leaves such a binding alone: it is
39
+ * not read, not reported, and so never turned failing.
40
+ *
41
+ * It is named here, beside the catalog, because the account is the only place
42
+ * a machine is named: the contract has no field for it. A declared
43
+ * `history.sessions` is the same source under its contract id.
44
+ */
45
+ const HOST_BOUND = new Set(["history", "history.sessions"])
46
+
47
+ /** True when only the machine its account names may collect this source (0.12.3). */
48
+ export function hostBoundSource(source) {
49
+ return HOST_BOUND.has(String(source ?? ""))
50
+ }
51
+
34
52
  /** The timer's default cadence per source, in minutes. */
35
53
  export const DEFAULT_EVERY_MINUTES = 30
36
54
 
55
+ /**
56
+ * The owner's cadence policy, by namespace (0.12.4): **X's reads are billed**, so
57
+ * a binding of one of its sources is read once a day, whatever the plugin's own
58
+ * declaration or cadence says. A plugin's `cadence.providerMinMinutes` is the
59
+ * floor the provider imposes, never the person's choice, so it cannot shorten
60
+ * this; it can only lengthen it.
61
+ */
62
+ const OWNER_CADENCE_MINUTES = Object.freeze({ x: 1440 })
63
+
64
+ /** The shortest cadence the owner allows this namespace, in minutes, or 0 where they set none. */
65
+ function ownerCadence(namespace) {
66
+ return OWNER_CADENCE_MINUTES[String(namespace ?? "")] ?? 0
67
+ }
68
+
37
69
  function freezePermission(permission) {
38
70
  return Object.freeze({
39
71
  ...permission,
@@ -89,7 +121,7 @@ export const PREVIOUS_CONTRACT_SOURCES = Object.freeze(
89
121
  namespace: "x",
90
122
  package: "@joe-broadhead/opencode-x",
91
123
  minVersion: "0.0.4",
92
- everyMinutes: 120,
124
+ // Once a day: its reads are billed, and the owner's cadence policy is below (`ownerCadence`).
93
125
  permission: { actions: ["x_get_users_me", "x_get_users_mentions", "x_get_users_bookmarks", "x_get_users_timeline"] },
94
126
  setupOptions:
95
127
  'X reads are billed. Set the x plugin\'s options "events": {"feeds": ["mentions", "bookmarks"], "maxCalls": 2}, and "ownsXApp": true only if the signed-in account owns the developer app (it lowers the price X charges); then restart OpenCode.',
@@ -145,7 +177,6 @@ export const PREVIOUS_CONTRACT_SOURCES = Object.freeze(
145
177
  tool: "events_list",
146
178
  input: {},
147
179
  minVersion: null,
148
- everyMinutes: DEFAULT_EVERY_MINUTES,
149
180
  ownerProbe: "limit1",
150
181
  setupOptions: null,
151
182
  namesAccount: false,
@@ -153,6 +184,9 @@ export const PREVIOUS_CONTRACT_SOURCES = Object.freeze(
153
184
  contractLabel: "events_list (previous)",
154
185
  kind: "events",
155
186
  ...entry,
187
+ // The owner's cadence outranks the registry's own: X is read once a day
188
+ // because its reads are billed (0.12.4).
189
+ everyMinutes: Math.max(DEFAULT_EVERY_MINUTES, Number(entry.everyMinutes) || 0, ownerCadence(entry.namespace)),
156
190
  input: Object.freeze({ ...(entry.input ?? {}) }),
157
191
  permission: freezePermission({
158
192
  events: `${entry.namespace}_events_list`,
@@ -432,13 +466,14 @@ function declaredEntry(plugin, item) {
432
466
  const named = item.accounts?.named === true
433
467
  const stated = Number(item.cadence?.providerMinMinutes)
434
468
  const floor = Number.isInteger(stated) && stated >= 1 ? stated : null
469
+ const namespace = String(item.id).split(".")[0]
435
470
  return Object.freeze({
436
471
  source: item.id,
437
472
  pluginId: plugin.id,
438
473
  package: plugin.package,
439
474
  version: plugin.version ?? null,
440
475
  rpc: `${plugin.id}.tools`,
441
- namespace: String(item.id).split(".")[0],
476
+ namespace,
442
477
  tool: item.tool,
443
478
  kind: item.kind,
444
479
  reads: item.reads ?? null,
@@ -450,7 +485,9 @@ function declaredEntry(plugin, item) {
450
485
  // rules and the plugin's account always agree.
451
486
  namesAccount: named,
452
487
  ownerProbe: "probe",
453
- everyMinutes: Math.max(DEFAULT_EVERY_MINUTES, floor ?? 0),
488
+ // A declared X source is read once a day too: the plugin's own cadence can
489
+ // only lengthen the owner's policy, never shorten it (0.12.4).
490
+ everyMinutes: Math.max(DEFAULT_EVERY_MINUTES, floor ?? 0, ownerCadence(namespace)),
454
491
  minVersion: null,
455
492
  setupOptions: null,
456
493
  contract: "sources",
@@ -495,7 +532,8 @@ function memoryEntries(plugin) {
495
532
  pageSource: pageSourceOf({ id: source.id, input: source.input }),
496
533
  namesAccount: source.accounts === "multi",
497
534
  ownerProbe: "limit0",
498
- everyMinutes: Math.max(DEFAULT_EVERY_MINUTES, Number(source.cadence?.everyMinutes) || 0),
535
+ // The owner's cadence applies to a previous-contract declaration too, by the source id's namespace.
536
+ everyMinutes: Math.max(DEFAULT_EVERY_MINUTES, Number(source.cadence?.everyMinutes) || 0, ownerCadence(String(source.id).split(".")[0])),
499
537
  minVersion: null,
500
538
  setupOptions: null,
501
539
  contract: "memory",
package/src/util.js CHANGED
@@ -174,6 +174,34 @@ export function errorMessage(error) {
174
174
  return NO_ERROR_MESSAGE
175
175
  }
176
176
 
177
+ /** A message that already names a code (`AUTH_REQUIRED: …`): a second one would be noise. */
178
+ const CODED_PREFIX = /^[A-Z][A-Z0-9_]+: /
179
+
180
+ /**
181
+ * A failure as one line of text a person reads: `CODE: what happened`, or the
182
+ * message alone when it names no code (or only the contract's own
183
+ * `UNAVAILABLE`, which says the read failed and no more). The code is kept
184
+ * because a provider's refusal is diagnosed by it (`AUTH_REQUIRED` is a
185
+ * sign-in, `RATE_LIMITED` is a wait), and the message alone has lost it by the
186
+ * time it is stored.
187
+ *
188
+ * It is built from `errorMessage`, so a failure that arrives as a plain object
189
+ * reads as its own words: never `String(object)`, which is `[object Object]`.
190
+ * A message that already names the code (`AUTH_REQUIRED: …`, which is how a
191
+ * coded error is written) is not prefixed twice.
192
+ *
193
+ * @param {unknown} error
194
+ * @param {number} [max]
195
+ */
196
+ export function failureText(error, max = 300) {
197
+ const text = oneLine(errorMessage(error), max)
198
+ const code = oneLine(codeOf(error), 60)
199
+ // `UNAVAILABLE` is the contract's word for "the read failed, retry": a
200
+ // failure that names nothing more specific reads as its own sentence.
201
+ if (!code || code === "UNAVAILABLE" || text === code || CODED_PREFIX.test(text)) return text
202
+ return oneLine(`${code}: ${text}`, max)
203
+ }
204
+
177
205
  /** The withheld phrase, naming the code so a failure is still diagnosable. */
178
206
  function withheld(code) {
179
207
  return code ? `${ERROR_WITHHELD} (code ${oneLine(code, 60)})` : ERROR_WITHHELD