@joe-broadhead/opencode-mem 0.9.14 → 0.11.3

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 (143) hide show
  1. package/CHANGELOG.md +1856 -0
  2. package/README.md +15 -7
  3. package/SECURITY.md +3 -1
  4. package/docs/agent-instructions.md +1 -1
  5. package/docs/agent-protocol.md +7 -7
  6. package/docs/permissions.md +16 -0
  7. package/package.json +8921 -1070
  8. package/shared/page-paths.js +44 -0
  9. package/skills/mem.pages/SKILL.md +3 -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 +623 -30
  20. package/src/config.js +88 -7
  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 +11 -6
  88. package/src/recall.js +92 -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 +389 -92
  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 +74 -23
  104. package/src/tools/held-write.js +46 -19
  105. package/src/tools/index.js +28 -0
  106. package/src/tools/ingest.js +38 -2
  107. package/src/tools/memory.js +56 -25
  108. package/src/tools/page.js +212 -95
  109. package/src/tools/recall.js +218 -4
  110. package/src/tools/share.js +42 -3
  111. package/src/tools/shared.js +84 -6
  112. package/src/tools/space-lifecycle.js +278 -0
  113. package/src/tools/spaces.js +381 -30
  114. package/src/tools/status.js +9 -2
  115. package/src/tools/wiki.js +231 -116
  116. package/src/util.js +110 -6
  117. package/src/vendor/source-contract/README.md +24 -0
  118. package/src/vendor/source-contract/THIRD-PARTY-NOTICES.md +35 -0
  119. package/src/vendor/source-contract/VENDOR.json +81 -0
  120. package/src/vendor/source-contract/chunks/chunk-3M5PAKSS.js +84 -0
  121. package/src/vendor/source-contract/chunks/chunk-6HDIB2SA.js +183 -0
  122. package/src/vendor/source-contract/chunks/chunk-HLVAKAYG.js +10 -0
  123. package/src/vendor/source-contract/chunks/chunk-I2RXJJJM.js +81 -0
  124. package/src/vendor/source-contract/chunks/chunk-KWEWSZ4V.js +505 -0
  125. package/src/vendor/source-contract/chunks/chunk-W5SHR7DQ.js +9477 -0
  126. package/src/vendor/source-contract/chunks/chunk-ZUKF7P6U.js +653 -0
  127. package/src/vendor/source-contract/cursor.js +26 -0
  128. package/src/vendor/source-contract/events.js +257 -0
  129. package/src/vendor/source-contract/registry.js +23 -0
  130. package/src/vendor/source-contract/tools-rpc.js +42 -0
  131. package/src/views/access-reads.js +256 -0
  132. package/src/views/communities.js +77 -0
  133. package/src/views/contracts.js +1082 -23
  134. package/src/views/inbox-bytes.js +103 -0
  135. package/src/views/profile.js +31 -0
  136. package/src/views/receipt.js +26 -1
  137. package/src/views/records-reads.js +520 -41
  138. package/src/views/rpc.js +153 -25
  139. package/src/views/shape.js +8 -5
  140. package/src/views/write-state.js +89 -0
  141. package/src/wiki-ingest.js +215 -0
  142. package/src/wiki-state.js +228 -0
  143. package/views/pages.html +2 -2
package/src/runtime.js CHANGED
@@ -5,11 +5,12 @@ import { dayIn, dueSection } from "./records.js"
5
5
  import { createRecordsStore } from "./records-store.js"
6
6
  import { createRecordsClient } from "./backend/records.js"
7
7
  import { buildCheckpoint, checkpointFingerprint } from "./compaction.js"
8
- import { UNLINKED_SENTENCE, asSession, credentialLine, unavailableReason } from "./credentials.js"
8
+ import { SOURCES, UNLINKED_SENTENCE, asSession, credentialLine, unavailableReason } from "./credentials.js"
9
9
  import { createControlClient } from "./spaces.js"
10
10
  import { createSkillContexts } from "./skill-contexts.js"
11
11
  import { createSpool } from "./spool.js"
12
12
  import { createForgetPurge } from "./forget-purge.js"
13
+ import { createForgetTurns } from "./forget-turn.js"
13
14
  import { createCapturePause } from "./capture-pause.js"
14
15
  import { createStatedText } from "./stated.js"
15
16
  import { errorMessage, oneLine, rememberBounded, shortHash } from "./util.js"
@@ -62,6 +63,12 @@ export function createRuntime(input) {
62
63
  const now = typeof input.now === "function" ? input.now : Date.now
63
64
  /** The per-session capture pause (/mem-pause, /mem-resume): no turn, summary or checkpoint while set. */
64
65
  const capturePause = createCapturePause({ stateDir: config.stateDir, log, now: () => new Date(now()) })
66
+ /**
67
+ * Session marks for a forget: the turn a successful forget ran in is not
68
+ * kept (src/forget-turn.js). Attached capture spends a mark, and mem_revise's
69
+ * forget sets one.
70
+ */
71
+ const forgetTurns = createForgetTurns()
65
72
  /** `${sessionID}::${agent}` -> the pinned block and its refresh state. */
66
73
  const pins = new Map()
67
74
  /** `${sessionID}::${agent}` -> { context, expires }: the session context, cached for the TTL. */
@@ -121,10 +128,16 @@ export function createRuntime(input) {
121
128
  */
122
129
  function unavailable() {
123
130
  if (!control || !credentials) return ""
131
+ // The source this address would actually use. A host with no `memory`
132
+ // resource keeps its own wording; a resource at another origin cannot
133
+ // speak for this address, so the plain wording is used there.
134
+ const source = credentials.source(config.controlURL)
135
+ const identityUnusable = Boolean(credentials.memoryResource()) && source !== SOURCES.identity
124
136
  const reason = unavailableReason({
125
- source: credentials.source(),
137
+ source,
126
138
  controlURL: config.controlURL,
127
- inJelly: credentials.inJelly(),
139
+ memoryResourceOffered: Boolean(credentials.memoryResource()) && !identityUnusable,
140
+ ownServiceNote: config.ownServiceNote ?? "",
128
141
  })
129
142
  if (reason) return reason
130
143
  return credentials.unlinked?.() ? UNLINKED_SENTENCE : ""
@@ -507,7 +520,9 @@ export function createRuntime(input) {
507
520
  ])
508
521
  if (core.error && index.error && records.error) throw core.error
509
522
  const day = today()
510
- const due = records.value ? dueSection(records.value.items, { today: day, zone: clock.zone }) : { text: "", withheld: 0 }
523
+ const due = records.value
524
+ ? dueSection(records.value.items, { today: day, zone: clock.zone, session: sessionID })
525
+ : { text: "", withheld: 0 }
511
526
  const block = buildBootstrap({
512
527
  index: index.value ?? null,
513
528
  core: core.value ?? null,
@@ -587,7 +602,10 @@ export function createRuntime(input) {
587
602
  */
588
603
  function refreshSkillsForSpace(context) {
589
604
  if (!control || !config.skills) return
590
- if (context?.space_kind !== "shared") return
605
+ // A personal space binds too: a fresh host's first session is usually a
606
+ // personal one, and its skills arrive the same way a shared space's do
607
+ // (jelly #80 review, R2-S1).
608
+ if (context?.space_kind !== "shared" && context?.space_kind !== "personal") return
591
609
  const spaceID = String(context.space_id ?? "").trim()
592
610
  if (!spaceID) return
593
611
  const signature = placementSignature(context)
@@ -602,7 +620,9 @@ export function createRuntime(input) {
602
620
  queueMicrotask(() => asSession("", () => {
603
621
  if (skillMirror.inflight) return
604
622
  skillMirror.inflight = Promise.resolve()
605
- .then(() => api.refreshSkills({ reason: "session-bind", context, timeoutMs: SKILL_BIND_TIMEOUT_MS }))
623
+ // One deadline for the whole refresh, as for setup's (jelly #80): a slow
624
+ // server costs the bind a refresh, never the session.
625
+ .then(() => api.refreshSkills({ reason: "session-bind", context, timeoutMs: SKILL_BIND_TIMEOUT_MS, deadlineMs: SKILL_BIND_TIMEOUT_MS }))
606
626
  .catch((error) => log.warn("skill refresh after space bind failed", error))
607
627
  .finally(() => {
608
628
  skillMirror.inflight = null
@@ -927,6 +947,25 @@ export function createRuntime(input) {
927
947
  }
928
948
  }
929
949
 
950
+ /**
951
+ * The account the current session's **verified** sign-in names, or "" when
952
+ * there is none: the person a source read answers for.
953
+ *
954
+ * A source read runs in `asVerifiedSession`, so the credential is that
955
+ * session's own Jelly token, minted for the person speaking in it
956
+ * (`src/credentials.js`). `check()` has the token, `subject()` reads the
957
+ * account it names (`acc_…`). A pasted memory key is not a person and answers
958
+ * "" — never `config.user`, which is the host's own user (`MEMORY_USER`, or
959
+ * the OS user) and names every member alike on a host with more than one.
960
+ *
961
+ * @returns {Promise<string>}
962
+ */
963
+ async function verifiedAccount() {
964
+ if (!credentials?.check || !credentials?.subject) return ""
965
+ await credentials.check()
966
+ return credentials.subject()
967
+ }
968
+
930
969
  const spool = createSpool({
931
970
  config,
932
971
  log,
@@ -976,6 +1015,44 @@ export function createRuntime(input) {
976
1015
  return spool.flushSpool(options)
977
1016
  }
978
1017
 
1018
+ /** How long the delete of a forgotten turn may take, and how often it retries a running write. */
1019
+ // Kept small: the delete is part of the forget's answer.
1020
+ const FORGET_DELETE_TIMEOUT_MS = 5_000
1021
+ const FORGET_DELETE_RETRY_MS = 400
1022
+
1023
+ /**
1024
+ * Erase a turn the person forgot that a capture may have delivered before
1025
+ * the forget ran (src/forget-turn.js): the gateway's `POST /v1/capture/delete`
1026
+ * records a tombstone for the turn's key prefix, so no later capture of it
1027
+ * lands, and removes what is stored.
1028
+ *
1029
+ * A write of the turn still running answers 425; the delete is retried for
1030
+ * up to `FORGET_DELETE_TIMEOUT_MS`, so a turn that lands meanwhile is
1031
+ * removed too. Answers how many turns it removed (0 when the call failed,
1032
+ * which the caller reports). Local direct mode has no such route: it
1033
+ * answers 0.
1034
+ *
1035
+ * @param {{ sessionID: string, visibility?: string, key?: string }} input
1036
+ * @returns {Promise<{ removed: number, failed: boolean, attempted: boolean }>}
1037
+ */
1038
+ async function deleteCaptureTurn({ sessionID, visibility = config.captureVisibility, key = "" } = {}) {
1039
+ if (!sessionID || !key || !gatewayCapture || typeof backend.deleteCapture !== "function") return { removed: 0, failed: false, attempted: false }
1040
+ const deadline = Date.now() + FORGET_DELETE_TIMEOUT_MS
1041
+ for (let attempt = 0; ; attempt += 1) {
1042
+ try {
1043
+ const answer = await backend.deleteCapture({ sessionID, visibility, key })
1044
+ return { removed: Number(answer?.deleted) || 0, failed: false, attempted: true }
1045
+ } catch (error) {
1046
+ const running = Number(error?.status) === 425
1047
+ if (!running || Date.now() + FORGET_DELETE_RETRY_MS >= deadline) {
1048
+ log.warn("a delivered capture of a forgotten turn could not be deleted", { sessionID, error: errorMessage(error) })
1049
+ return { removed: 0, failed: true, attempted: true }
1050
+ }
1051
+ await new Promise((resolve) => setTimeout(resolve, FORGET_DELETE_RETRY_MS))
1052
+ }
1053
+ }
1054
+ }
1055
+
979
1056
  /** A new user message in a session: its Jelly token is asked for again (src/credentials.js `userTurn`). */
980
1057
  function userTurn(sessionID, messageID) {
981
1058
  credentials?.userTurn?.(sessionID, messageID)
@@ -1067,7 +1144,7 @@ export function createRuntime(input) {
1067
1144
  return {
1068
1145
  health: health.ok ? "ok" : `unavailable (${health.error})`,
1069
1146
  // Read after the requests above, so a refusal they met is reported.
1070
- credential: credentials ? credentialLine(credentials.describe()) : config.token ? "option" : "none",
1147
+ credential: credentials ? credentialLine(credentials.describe(config.controlURL)) : config.token ? "option" : "none",
1071
1148
  scope: context ? contextScopeLabel(context, scoped) : scopeLabel(scoped),
1072
1149
  space: context?.space_id ?? null,
1073
1150
  spaceName: context?.space_name ?? null,
@@ -1101,6 +1178,7 @@ export function createRuntime(input) {
1101
1178
  recordsClient,
1102
1179
  today,
1103
1180
  credentials,
1181
+ verifiedAccount,
1104
1182
  unavailable,
1105
1183
  availability,
1106
1184
  userTurn,
@@ -1118,6 +1196,7 @@ export function createRuntime(input) {
1118
1196
  captureContext,
1119
1197
  gatewayCapture,
1120
1198
  captureTurn,
1199
+ deleteCaptureTurn,
1121
1200
  spaceHint,
1122
1201
  noteSession,
1123
1202
  noteAgent,
@@ -1158,6 +1237,9 @@ export function createRuntime(input) {
1158
1237
  purgeSpool: spool.purgeMatching,
1159
1238
  forgetPurge,
1160
1239
  maskForgotten: forgetPurge.mask,
1240
+ // A forget marks the turn it ran in, which capture then does not keep
1241
+ // (src/forget-turn.js); mem_revise's forget calls `noteForgetTurn`.
1242
+ forgetTurns,
1161
1243
  drainSpool,
1162
1244
  status,
1163
1245
  }
@@ -0,0 +1,68 @@
1
+ /**
2
+ * Memory's own setup time, phase by phase, for the host (jelly #80, D226).
3
+ *
4
+ * A host starts an engine and waits for every plugin's `setup`. Jelly's
5
+ * engine-start telemetry can name the slowest phase, but not which plugin
6
+ * spent it, so Memory times itself: one timer per engine start, on a monotonic
7
+ * clock (`performance.now()`, never the wall clock, so a clock adjustment
8
+ * mid-start cannot make a phase negative), read through the declared read
9
+ * `memory.setup` (`src/views/contracts.js`) as `{ ms, phases: [{ name, ms }], at }`.
10
+ *
11
+ * **The phases.** Each is the span between two marks, in the order `setup`
12
+ * (`src/index.js`) runs:
13
+ *
14
+ * | phase | the setup work it spans |
15
+ * |---|---|
16
+ * | `config` | `resolveConfig`: the options, the environment, Jelly's sheet |
17
+ * | `host` | the OpenCode version and capability checks |
18
+ * | `credentials` | the origin, `/connect`, the credential chain, `skipAsks` |
19
+ * | `backend` | the backend and the runtime, and the spooled captures pruned |
20
+ * | `connect` | Memory added to `/connect`, and the sign-in OpenCode holds read from its own store (the probe that confirms it runs after the start) |
21
+ * | `status` | the setup log line, the configuration warnings, availability |
22
+ * | `wiring` | the disposers, and the skill-refresh wiring |
23
+ * | `tools` | the `mem_*` tools and `/mem-collect` |
24
+ * | `rules` | the default permission rules |
25
+ * | `views` | the RPC Memory's views call in Jelly |
26
+ * | `sources` | the source provider's tools RPC |
27
+ * | `skills` | the skills mirrored from the control plane |
28
+ * | `builtinSkill` | Memory's own four skills |
29
+ * | `commands` | the `mem-status` command |
30
+ * | `hooks` | the session hooks |
31
+ * | `capture` | the event stream's capture |
32
+ * | `flush` | starting the spool flush and the backend probe (neither is awaited; with a stored sign-in, both wait for the background probe to confirm it) |
33
+ *
34
+ * The total is the sum of the phases, by construction, and `at` is when this
35
+ * start began (ISO 8601): it names the start the numbers belong to. Nothing is
36
+ * measured by reading it — the record is made once, as setup ends, and the read
37
+ * returns those numbers (`src/views/rpc.js`).
38
+ *
39
+ * **What is not counted.** The spool flush and the backend probe are started,
40
+ * not awaited (`src/index.js`), so their work happens after the engine is up.
41
+ */
42
+ export function createSetupTimer({ now = () => performance.now(), clock = () => Date.now() } = {}) {
43
+ const start = now()
44
+ const startedAt = clock()
45
+ let last = start
46
+ let total = 0
47
+ const phases = []
48
+ let record = null
49
+
50
+ return {
51
+ /** Close the current phase: its name, and the time since the previous mark (or the start). */
52
+ mark(name) {
53
+ if (record) return record
54
+ const at = now()
55
+ const ms = at - last
56
+ phases.push(Object.freeze({ name: String(name), ms }))
57
+ total += ms
58
+ last = at
59
+ return null
60
+ },
61
+ /** The record this start answers from now on: frozen, so a later mark cannot change it. */
62
+ finish() {
63
+ if (record) return record
64
+ record = Object.freeze({ ms: total, phases: Object.freeze(phases.slice()), at: new Date(startedAt).toISOString() })
65
+ return record
66
+ },
67
+ }
68
+ }
package/src/skills.js CHANGED
@@ -1,6 +1,7 @@
1
1
  import fs from "node:fs/promises"
2
2
  import path from "node:path"
3
3
  import { fileURLToPath } from "node:url"
4
+ import { gatewayOrigin } from "./connect.js"
4
5
  import { slug, oneLine, shortHash } from "./util.js"
5
6
 
6
7
  /**
@@ -13,6 +14,35 @@ import { slug, oneLine, shortHash } from "./util.js"
13
14
  export const BUILTIN_SKILLS = Object.freeze(["mem.usage", "mem.pages", "mem.sharing", "mem.sources"])
14
15
  const builtinPath = (id) => fileURLToPath(new URL(`../skills/${id}/SKILL.md`, import.meta.url))
15
16
  const MAX_SKILLS = 24
17
+ /**
18
+ * One background skill refresh's whole deadline, as the session bind already
19
+ * gives it (`SKILL_BIND_TIMEOUT_MS`, src/runtime.js): the mirror serves the
20
+ * session either way, so a slow server delays a refresh, never a start (jelly
21
+ * #80, D226).
22
+ */
23
+ export const SKILL_REFRESH_DEADLINE_MS = 1_500
24
+ /**
25
+ * How long after a start the first background refresh begins. Setup's own phases
26
+ * are the start's time; a refresh that ran beside them would add its work to
27
+ * them on the one event loop, which is not a wait but reads as one. The refresh
28
+ * is only warming the mirror for the next start (`registerMirroredSkills`), and
29
+ * the session bind covers the session that is starting, so a sixth of a second
30
+ * is free.
31
+ */
32
+ export const SKILL_REFRESH_START_MS = 60
33
+ /**
34
+ * The background refresh's own deadline, and how long a host waits before trying
35
+ * again when it fails. A start never waits for a refresh, so the refresh may
36
+ * take its time: three round trips (spaces, contexts, lists) at 600 ms each need
37
+ * 1.8 s, and a server slower than 1.5 s still delivers the first session's
38
+ * skills (jelly #80 review, R2-S1). Retries back off to two minutes, so a dead
39
+ * server costs occasional background requests and nothing else.
40
+ */
41
+ export const SKILL_REFRESH_BACKGROUND_MS = 10_000
42
+ export const SKILL_RETRY_DELAYS_MS = Object.freeze([5_000, 30_000, 120_000])
43
+ /** The mirror's own manifest beside each `SKILL.md`: what a registration needs, without the body. */
44
+ const MIRROR_MANIFEST = "skill.json"
45
+ const MIRROR_MANIFEST_V = 1
16
46
 
17
47
  /**
18
48
  * Register the plugin's own skills as native skills, so every agent that can
@@ -93,6 +123,153 @@ function failed(reason, error) {
93
123
  }
94
124
  }
95
125
 
126
+ /** The key a mirror is bound to: this server, and this account, and nothing else. */
127
+ function ownerKey(origin, subject) {
128
+ return shortHash(`${origin}\n${subject}`, 16)
129
+ }
130
+
131
+ /**
132
+ * Who the mirror on this disk belongs to (jelly #80 review, R2-B1): the server
133
+ * origin, and a hash of the account subject when this engine can name one (a
134
+ * Jelly sign-in's token `sub`, from the credential it already holds — no
135
+ * request). A host that cannot name its account has no owner (`owner: ""`), and
136
+ * its cache is never registered: another account's private skills could be in
137
+ * it. The hash is what goes on disk, never the account id.
138
+ *
139
+ * @param {any} runtime
140
+ * @returns {{ origin: string, owner: string }}
141
+ */
142
+ export function mirrorOwner(runtime) {
143
+ const origin = gatewayOrigin(runtime?.config?.controlURL ?? "") || gatewayOrigin(runtime?.credentials?.origin?.() ?? "")
144
+ let subject = ""
145
+ try {
146
+ subject = String(runtime?.credentials?.subject?.() ?? "")
147
+ } catch {
148
+ subject = ""
149
+ }
150
+ return { origin, owner: origin && subject ? ownerKey(origin, subject) : "" }
151
+ }
152
+
153
+ /**
154
+ * What a mirrored skill is, as the host is given it: `SKILL.md`'s own path and
155
+ * content (the host reads the file), and the few fields a registration needs,
156
+ * which the manifest beside it records (`skill.json`).
157
+ */
158
+ function mirrorDefinition(dir, name, content, manifest) {
159
+ const file = path.join(dir, name, "SKILL.md")
160
+ const id = String(manifest?.id ?? "").trim() || name
161
+ return {
162
+ id,
163
+ name: String(manifest?.name ?? "").trim() || frontMatterField(content, "name") || id,
164
+ description: String(manifest?.description ?? "").trim() || frontMatterDescription(content) || "",
165
+ path: file,
166
+ content,
167
+ // A manifest written before this field existed, or a mirror from an older
168
+ // version: never auto-invoke what the mirror does not say is the person's.
169
+ autoinvoke: manifest ? manifest.autoinvoke === true : false,
170
+ }
171
+ }
172
+
173
+ /**
174
+ * The skills this host already mirrors, read from the disk alone: every
175
+ * `stateDir/skills/<id>/SKILL.md`, with the `skill.json` beside it. No control
176
+ * plane, no backend, no request: what the last successful refresh left, so the
177
+ * first session of a start has its skills even when Memory cannot be reached
178
+ * (jelly #80, D226). A directory that cannot be read is left out and logged; an
179
+ * empty or absent mirror is an empty list.
180
+ *
181
+ * @param {any} config
182
+ * @param {{ log?: any }} [options]
183
+ */
184
+ export async function readMirrorSkills(config, { log, identity = null } = {}) {
185
+ const dir = path.join(config.stateDir, "skills")
186
+ let entries = []
187
+ try {
188
+ entries = await fs.readdir(dir, { withFileTypes: true })
189
+ } catch (error) {
190
+ if (error?.code !== "ENOENT") log?.warn?.("the skill mirror could not be read", { error: error?.message })
191
+ return []
192
+ }
193
+ const definitions = []
194
+ for (const entry of entries) {
195
+ if (!entry.isDirectory()) continue
196
+ const skillDir = path.join(dir, entry.name)
197
+ let content
198
+ try {
199
+ content = await fs.readFile(path.join(skillDir, "SKILL.md"), "utf8")
200
+ } catch (error) {
201
+ if (error?.code !== "ENOENT") log?.warn?.("a mirrored skill could not be read", { dir: entry.name, error: error?.message })
202
+ continue
203
+ }
204
+ let manifest = null
205
+ try {
206
+ const text = await fs.readFile(path.join(skillDir, MIRROR_MANIFEST), "utf8")
207
+ const parsed = JSON.parse(text)
208
+ manifest = parsed && typeof parsed === "object" ? parsed : null
209
+ } catch {
210
+ // No manifest (a mirror from an older version, or a half-written one): the
211
+ // body's front matter still names it, and the directory is its id.
212
+ }
213
+ if (!content.trim()) continue
214
+ // Bound to its owner: a manifest written for another account, another origin,
215
+ // or by a version that recorded neither, is ignored (jelly #80 review, R2-B1).
216
+ if (identity) {
217
+ if (manifest?.origin !== identity.origin || manifest?.owner !== identity.owner) continue
218
+ }
219
+ definitions.push(mirrorDefinition(dir, entry.name, content, manifest))
220
+ }
221
+ return definitions.sort((left, right) => left.id.localeCompare(right.id))
222
+ }
223
+
224
+ /**
225
+ * Register the mirrored skills at setup, from the disk alone, before anything
226
+ * asks the network: the first session of a start has the skills the last
227
+ * successful refresh left, and setup never waits for a mirror (jelly #80,
228
+ * F1). The next refresh disposes this registration and swaps its own in
229
+ * (`runtime.refreshSkills`, src/index.js).
230
+ *
231
+ * Returns `null` when there is nothing to register: no mirror, or a host whose
232
+ * skills are off. It registers even while memory is unavailable, because the
233
+ * files are already here.
234
+ */
235
+ export async function registerMirroredSkills(ctx, runtime) {
236
+ const { config, log } = runtime
237
+ if (!config.skills) return null
238
+ if (!ctx?.skill || typeof ctx.skill.transform !== "function") return null
239
+ // Who is signed in, asked of Jelly's own accessor only (in this process, and
240
+ // bounded: a host that does not answer costs the cache, not the start). No
241
+ // request is made here, whatever the sign-in is.
242
+ if (runtime.credentials?.source?.() === "jelly-identity" && typeof runtime.credentials.check === "function") {
243
+ try {
244
+ await (typeof runtime.bounded === "function" ? runtime.bounded(runtime.credentials.check(), 150, "skill cache owner") : runtime.credentials.check())
245
+ } catch {
246
+ // No account named: no owner, so nothing from the cache is registered.
247
+ }
248
+ }
249
+ // Only the account that mirrored these skills, on the server that holds them:
250
+ // signed out, or signed in as someone else, registers none of them.
251
+ const identity = mirrorOwner(runtime)
252
+ if (!identity.owner) return null
253
+ const definitions = await readMirrorSkills(config, { log, identity })
254
+ if (definitions.length === 0) return null
255
+ let registration
256
+ try {
257
+ registration = await ctx.skill.transform((editor) => {
258
+ for (const definition of definitions) editor.add(definition)
259
+ })
260
+ } catch (error) {
261
+ log.warn("mirrored skills could not be registered", error?.message)
262
+ return null
263
+ }
264
+ const ids = definitions.map((definition) => definition.id)
265
+ log.info("mirrored skills registered from disk", { count: ids.length })
266
+ // The spaces the mirror came from are not known here: the first session binds
267
+ // its own space and refreshes, which is how a skill published since the last
268
+ // run arrives (`refreshSkillsForSpace`, src/runtime.js).
269
+ runtime.recordSkillMirror?.({ count: ids.length, ids, spaceIds: [], sourceSpaces: 0 })
270
+ return { ok: true, cached: true, count: ids.length, ids, spaceIds: [], sourceSpaces: 0, registration }
271
+ }
272
+
96
273
  /**
97
274
  * Mirror space skills into OpenCode's native skill registry.
98
275
  *
@@ -123,9 +300,19 @@ export async function syncSkills(ctx, runtime, options = {}) {
123
300
  return { ok: true, disabled: true, count: 0, ids: [], spaceIds: [], sourceSpaces: 0, registration: null }
124
301
  }
125
302
 
303
+ // One deadline for the whole refresh (jelly #80, F1): a slow server costs a
304
+ // refresh, never a start or a session. Each request is bounded by what is
305
+ // left, and no read is retried: a refresh the deadline cut keeps the mirror.
306
+ const deadline = Number(options.deadlineMs) > 0 ? Date.now() + Number(options.deadlineMs) : 0
307
+ // A positive floor: a bound of 0 is no bound at all (`bounded`, src/runtime.js).
308
+ const remaining = () => (deadline ? Math.max(1, deadline - Date.now()) : 0)
309
+ const outOfTime = () => deadline > 0 && deadline - Date.now() <= 0
310
+ /** The per-call limits a deadline imposes: what is left to spend, and no retry. */
311
+ const spent = () => (deadline ? { timeoutMs: remaining(), retries: 0 } : {})
312
+
126
313
  let resolved
127
314
  try {
128
- resolved = await runtime.skillContexts(options)
315
+ resolved = await runtime.skillContexts(deadline ? { ...options, timeoutMs: remaining() } : options)
129
316
  } catch (error) {
130
317
  log.warn("skill context resolution failed; keeping the last good registry", error)
131
318
  return failed("context", error)
@@ -146,15 +333,27 @@ export async function syncSkills(ctx, runtime, options = {}) {
146
333
  // the host registry. Local direct mode has one source, so it is not capped.
147
334
  const limit = runtime.control ? MAX_SKILLS : Number.POSITIVE_INFINITY
148
335
 
149
- for (const target of resolved.targets ?? []) {
150
- if (candidates.length >= limit) break
151
- let items = []
336
+ // Every source's list is read at once: one round trip, not one per space
337
+ // (jelly #80, F1: eight spaces used to cost eight in a row).
338
+ const listed = await Promise.all((resolved.targets ?? []).map(async (target) => {
339
+ if (outOfTime()) return { target, error: new Error("deadline") }
152
340
  try {
153
- const listed = await backend.listSkills({ scope: target.scoped })
154
- items = Array.isArray(listed?.items) ? listed.items : []
341
+ const answer = await backend.listSkills({ scope: target.scoped, ...spent() })
342
+ return { target, items: Array.isArray(answer?.items) ? answer.items : [] }
155
343
  } catch (error) {
156
- listErrors.push({ space: target.context?.space_id, error: error?.message })
157
344
  log.warn("skill list failed", { space: target.context?.space_id, error: error?.message })
345
+ return { target, error }
346
+ }
347
+ }))
348
+ if (outOfTime()) {
349
+ log.warn("skill refresh stopped at its deadline; keeping the last good registry")
350
+ return failed("deadline", new Error("the skill refresh reached its deadline"))
351
+ }
352
+
353
+ for (const { target, items = [], error } of listed) {
354
+ if (candidates.length >= limit) break
355
+ if (error) {
356
+ listErrors.push({ space: target.context?.space_id, error: error?.message })
158
357
  continue
159
358
  }
160
359
 
@@ -175,8 +374,12 @@ export async function syncSkills(ctx, runtime, options = {}) {
175
374
 
176
375
  let content = String(item?.content ?? item?.body ?? item?.prompt ?? "").trim()
177
376
  if (!content) {
377
+ if (outOfTime()) {
378
+ log.warn("skill refresh stopped at its deadline; keeping the last good registry")
379
+ return failed("deadline", new Error("the skill refresh reached its deadline"))
380
+ }
178
381
  try {
179
- const detail = await backend.getSkill({ id: rawID, scope: target.scoped })
382
+ const detail = await backend.getSkill({ id: rawID, scope: target.scoped, ...spent() })
180
383
  content = String(detail?.content ?? detail?.body ?? detail?.prompt ?? "").trim()
181
384
  } catch (error) {
182
385
  log.debug("skill detail fetch failed", { id: rawID, error: error?.message })
@@ -206,6 +409,8 @@ export async function syncSkills(ctx, runtime, options = {}) {
206
409
  return failed("list", new Error(listErrors[0]?.error ?? "skill listing failed"))
207
410
  }
208
411
 
412
+ // The owner this mirror belongs to, stamped on every manifest it writes.
413
+ const mirror = mirrorOwner(runtime)
209
414
  const definitions = []
210
415
  for (const candidate of candidates) {
211
416
  try {
@@ -213,6 +418,23 @@ export async function syncSkills(ctx, runtime, options = {}) {
213
418
  await fs.mkdir(path.dirname(candidate.path), { recursive: true, mode: 0o700 })
214
419
  await fs.writeFile(candidate.path, candidate.content, { encoding: "utf8", mode: 0o600 })
215
420
  await fs.chmod(candidate.path, 0o600).catch(() => {})
421
+ // What a start needs without the body's front matter or the network: the
422
+ // manifest the next setup registers this skill from (jelly #80, F1).
423
+ await fs.writeFile(
424
+ path.join(path.dirname(candidate.path), MIRROR_MANIFEST),
425
+ JSON.stringify({
426
+ v: MIRROR_MANIFEST_V,
427
+ id: candidate.id,
428
+ name: candidate.name,
429
+ description: candidate.description,
430
+ autoinvoke: candidate.autoinvoke,
431
+ // Whose mirror this is: the server and the account, so a later start
432
+ // registers it only for the same ones (jelly #80 review, R2-B1).
433
+ origin: mirror.origin,
434
+ owner: mirror.owner,
435
+ }),
436
+ { encoding: "utf8", mode: 0o600 },
437
+ )
216
438
  definitions.push(candidate)
217
439
  } catch (error) {
218
440
  log.warn("skill materialisation failed", { id: candidate.id, error: error?.message })
@@ -0,0 +1,25 @@
1
+ /**
2
+ * The id a binding names: a built-in source's name, or a plugin-declared source's
3
+ * contract id (source-contract's `SOURCE_ID`) — `gws.gmail`, `gws.calendar.today`,
4
+ * lowercase, dotted, at most 64 characters.
5
+ *
6
+ * One copy, four users: the plugin (`src/collector.js`, `src/tools/spaces.js`), the
7
+ * records service, and the console. The package does not export its `SOURCE_ID`, so
8
+ * `test/source-ids.test.js` holds every copy to the contract's own `checkSources`.
9
+ */
10
+ export const BUILTIN_SOURCE_NAME = /^[a-z][a-z0-9_-]{0,31}$/
11
+ /** The contract's `SOURCE_ID`: `[a-z][a-z0-9-]*(.[a-z][a-z0-9-]*)+`. */
12
+ export const CONTRACT_SOURCE_ID = /^[a-z][a-z0-9-]*(?:\.[a-z][a-z0-9-]*)+$/
13
+ /** The contract's cap on a source id, in characters. */
14
+ export const SOURCE_ID_MAX = 64
15
+
16
+ /**
17
+ * True for a binding's source: a built-in name (Memory's own word rule), or a
18
+ * declared source's contract id at the contract's length.
19
+ *
20
+ * @param {unknown} value
21
+ * @returns {boolean}
22
+ */
23
+ export function isSourceName(value) {
24
+ return typeof value === "string" && (BUILTIN_SOURCE_NAME.test(value) || (value.length <= SOURCE_ID_MAX && CONTRACT_SOURCE_ID.test(value)))
25
+ }