@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
package/src/events.js CHANGED
@@ -1,8 +1,9 @@
1
1
  import { buildSessionPayload, extractCompactionSummary, newTurn } from "./capture.js"
2
2
  import { UNLINKED_SENTENCE, asSession } from "./credentials.js"
3
+ import { purgeForgottenTurn } from "./forget-turn.js"
3
4
  import { CAPTURE_MESSAGE_CHARS, MAX_MESSAGES, splitContent } from "./limits.js"
4
5
  import { parentIDOf, readSession } from "./sessions.js"
5
- import { turnKey } from "./spool.js"
6
+ import { turnKey, turnKeyPrefix } from "./spool.js"
6
7
  import { storable } from "./storable.js"
7
8
  import { errorMessage, rememberBounded, shortHash } from "./util.js"
8
9
 
@@ -12,6 +13,17 @@ const MODELS_MAX = 500
12
13
  const SEEN_EVENTS_MAX = 1_000
13
14
  /** Turns admitted but never finished (an abandoned session). The oldest is flushed. */
14
15
  const OPEN_TURNS_MAX = 200
16
+ /** How far a forget follows the session's parent chain to the root. */
17
+ const PARENT_CHAIN_MAX = 8
18
+ /**
19
+ * Flush reasons whose turn holds the exchange's final answer. `session.idle`
20
+ * is the one an ordinary turn ends on (it is the event type); a turn that
21
+ * leaves the flush early (`superseded`, `evicted`) is only part of the
22
+ * exchange that is still running, and is never deleted by a forget.
23
+ */
24
+ const COMPLETED_REASONS = new Set(["idle", "session.idle", "session.execution.succeeded", "session.execution.failed", "shutdown"])
25
+ /** How long a steered turn is offered for removal after it was flushed. */
26
+ const PARTIAL_TURN_TTL_MS = 60 * 60_000
15
27
 
16
28
  /** Room left in each part for the continuation header. */
17
29
  const SUMMARY_PART_CHARS = CAPTURE_MESSAGE_CHARS - 80
@@ -81,6 +93,20 @@ export function attachCapture(ctx, runtime, options = {}) {
81
93
  const controller = new AbortController()
82
94
  const turns = new Map()
83
95
  const models = new Map()
96
+ /**
97
+ * sessionID -> the last turn flushed because the person steered or it was
98
+ * evicted: it is part of the exchange still running and may hold the text.
99
+ * A forget never deletes it (it cannot be tied to the forget); its result
100
+ * tells the agent it exists, to offer removing it (src/forget-turn.js).
101
+ */
102
+ const partialTurn = new Map()
103
+ /**
104
+ * child session -> the message of its parent's turn that was open when the
105
+ * host created it. Only that turn carries the child's request and result;
106
+ * a parent that has moved on to another turn is not marked by the child's
107
+ * forget (a background subagent).
108
+ */
109
+ const spawnTurn = new Map()
84
110
  const seenTypes = new Set()
85
111
  const seenEvents = new Set()
86
112
  const compacted = new Set()
@@ -144,6 +170,38 @@ export function attachCapture(ctx, runtime, options = {}) {
144
170
  return true
145
171
  }
146
172
 
173
+ /**
174
+ * The session and its ancestors, nearest first, to the root: a forget in a
175
+ * subagent's session also protects the turn of the parent (or root) session
176
+ * that carries the person's request and the task's result.
177
+ */
178
+ function sessionChain(sessionID) {
179
+ const ids = []
180
+ let id = sessionID ? String(sessionID) : ""
181
+ for (let depth = 0; depth < PARENT_CHAIN_MAX && id && !ids.includes(id); depth += 1) {
182
+ ids.push(id)
183
+ const parent = runtime.parentOf?.(id)
184
+ id = typeof parent === "string" ? parent : ""
185
+ }
186
+ return ids
187
+ }
188
+
189
+ /** End the session's exchange: its next turn is a new one. */
190
+ function endExchange(sessionID) {
191
+ partialTurn.delete(sessionID)
192
+ }
193
+
194
+ /** The turn of `sessionID` flushed as superseded or evicted, if it is recent. */
195
+ function partialOf(sessionID) {
196
+ const mark = partialTurn.get(sessionID)
197
+ if (!mark) return null
198
+ if (Date.now() - mark.at >= PARTIAL_TURN_TTL_MS) {
199
+ partialTurn.delete(sessionID)
200
+ return null
201
+ }
202
+ return mark
203
+ }
204
+
147
205
  /**
148
206
  * Open a turn. A session that is admitted but never goes idle would keep its
149
207
  * turn for the life of the host; past the bound the oldest open turn is
@@ -174,6 +232,21 @@ export function attachCapture(ctx, runtime, options = {}) {
174
232
  const turn = turns.get(sessionID)
175
233
  if (!turn) return
176
234
  turns.delete(sessionID)
235
+ // Every way this turn ends counts: a completed turn ends the exchange even
236
+ // when the flush leaves early below (another instance won the claim, the
237
+ // session is paused, or a subagent is skipped). Only a turn that stops
238
+ // because the person steered, or that was evicted, leaves the exchange
239
+ // running (src/forget-turn.js).
240
+ if (COMPLETED_REASONS.has(reason)) endExchange(sessionID)
241
+ // The turn a forget ran in is not kept at all: its prompt, its answer and
242
+ // any tool result restate the forgotten text, and masking misses a
243
+ // paraphrase. The mark was set while this turn was open and is spent here,
244
+ // so the turn after it is captured as usual, and the log keeps the marker
245
+ // in the turn's place, never the text (src/forget-turn.js).
246
+ if (runtime.forgetTurns?.take(sessionID, turn.startedAt) === true) {
247
+ runtime.log.info("turn not captured: a memory was forgotten in this turn, so the turn isn't kept", { sessionID, skip: "forgotten", reason })
248
+ return
249
+ }
177
250
  if (skipPaused(sessionID, "turn", turn)) return
178
251
  if (await skipUnavailable("turn", sessionID)) return
179
252
  if (skipSubagent(sessionID, "turn")) return
@@ -218,6 +291,11 @@ export function attachCapture(ctx, runtime, options = {}) {
218
291
  // space's turns only (src/forget-purge.js). Not used to place it.
219
292
  const space = runtime.spaceHint?.(sessionID, visibility) ?? ""
220
293
  const meta = { sessionID, agent: turn.agent, visibility, key, ...(task ? { task } : {}), ...(space ? { space } : {}) }
294
+ // A turn that stopped because the person steered, or was evicted, is part
295
+ // of the exchange that is still running. A forget never deletes it (it
296
+ // cannot be tied to the forget): the forget's result names it, so the
297
+ // agent can offer to remove it with the person's consent.
298
+ if (!COMPLETED_REASONS.has(reason)) rememberBounded(partialTurn, sessionID, { messageID: turn.messageID, key, at: Date.now() }, MODELS_MAX)
221
299
  // Control mode: the gateway's capture route places the turn. Local direct
222
300
  // mode: the fixed local scope.
223
301
  const scoped = runtime.gatewayCapture ? null : runtime.scope({ sessionID, agent: turn.agent, visibility, task })
@@ -374,6 +452,9 @@ export function attachCapture(ctx, runtime, options = {}) {
374
452
  turns.delete(sessionID)
375
453
  models.delete(sessionID)
376
454
  unlinkedLogged.delete(sessionID)
455
+ partialTurn.delete(sessionID)
456
+ spawnTurn.delete(sessionID)
457
+ runtime.forgetTurns?.drop(sessionID)
377
458
  if (runtime.forgetSession) runtime.forgetSession(sessionID)
378
459
  else runtime.invalidate?.(sessionID)
379
460
  }
@@ -389,12 +470,26 @@ export function attachCapture(ctx, runtime, options = {}) {
389
470
  runtime.userTurn?.(data.sessionID, data.messageID)
390
471
  runtime.notePrompt?.(data.sessionID, data.prompt?.text)
391
472
  }
473
+ // A plugin was added or the config changed (no payload; plugin.updated
474
+ // fires twice per install): re-read the plugins' declarations, debounced.
475
+ if (event.type === "plugin.updated" || event.type === "config.updated") {
476
+ runtime.onPluginsChanged?.(event.type)
477
+ return
478
+ }
392
479
  // A child's parent, also with capture off: a subagent's brief is checked
393
480
  // against its root session's messages, not as the person's (src/stated.js).
394
481
  if (event.type === "session.created") {
395
482
  const sessionID = data.sessionID ?? data.info?.id ?? data.session?.id
396
483
  const parentID = parentIDOf(data)
397
- if (sessionID && parentID) runtime.noteSession?.(sessionID, { parentID })
484
+ if (sessionID && parentID) {
485
+ runtime.noteSession?.(sessionID, { parentID })
486
+ // Which of the parent's turns was open when this child was created:
487
+ // the foreground task's turn, which carries the child's request and
488
+ // result. A background child outlives it, and a forget in the child
489
+ // must not drop the parent's later, unrelated turn (src/forget-turn.js).
490
+ const parentMessage = turns.get(String(parentID))?.messageID ?? ""
491
+ rememberBounded(spawnTurn, String(sessionID), String(parentMessage), MODELS_MAX)
492
+ }
398
493
  }
399
494
  if (!capturing) return
400
495
  if (!seenTypes.has(event.type)) {
@@ -507,6 +602,82 @@ export function attachCapture(ctx, runtime, options = {}) {
507
602
  }
508
603
  })()
509
604
 
605
+ /**
606
+ * A forget succeeded in `sessionID` (mem_revise's forget, src/forget-turn.js).
607
+ * The turn it ran in is not kept, and neither is the turn of a parent (or
608
+ * root) session that is awaiting it:
609
+ *
610
+ * - The session's own open turn, if capture has one (captureSubagents on).
611
+ * - A parent's open turn, but only when it is the turn that was open when
612
+ * the host created the child: a foreground subagent's task turn, which
613
+ * carries the person's request and the child's result. A background child
614
+ * that outlives it never marks a later, unrelated parent turn.
615
+ *
616
+ * Nothing else is touched: a finished turn of the session is never deleted
617
+ * or dropped, whatever it holds; the forget's result names a steered turn
618
+ * so the agent can offer removing it (the person's decision).
619
+ *
620
+ * Each marked turn's capture claim is taken here, while the turn is open, so
621
+ * every other plugin instance observing the same events finds the claim at
622
+ * its flush and captures nothing (src/spool.js `claimCapture`).
623
+ *
624
+ * A capture of a marked turn that another instance already delivered is
625
+ * erased through the gateway (a tombstone, so a later capture of it is
626
+ * refused too), and the answer says whether that was confirmed.
627
+ *
628
+ * @param {string} sessionID
629
+ * @returns {Promise<{ marked: number, failed: number }>}
630
+ */
631
+ async function noteForgetTurn(sessionID) {
632
+ if (!sessionID || !capturing) return { marked: 0, failed: 0 }
633
+ let marked = 0
634
+ let failed = 0
635
+ let child = String(sessionID)
636
+ for (const id of sessionChain(sessionID)) {
637
+ if (id !== String(sessionID)) {
638
+ // Only the parent's turn that was open at this child's creation ties
639
+ // the child's forget to it.
640
+ const expected = spawnTurn.get(child)
641
+ const openParent = turns.get(id)?.messageID ?? null
642
+ if (!expected || !openParent || expected !== openParent) break
643
+ }
644
+ const open = turns.get(id)
645
+ if (open) {
646
+ try {
647
+ runtime.claimCapture?.(`${id}:${open.messageID}`)
648
+ } catch (error) {
649
+ runtime.log.warn("the capture claim of a forgotten turn could not be taken; another instance may keep it", { sessionID: id, error: errorMessage(error) })
650
+ }
651
+ if (runtime.forgetTurns?.note(id) === true) marked += 1
652
+ }
653
+ // A spooled copy of a marked turn is deleted by its own key, whatever
654
+ // text it holds. One another instance already delivered is erased
655
+ // through the gateway, which also tombstones the turn so a later
656
+ // capture cannot land (src/forget-turn.js). Both are awaited: the
657
+ // forget's answer reports a removal it could not confirm.
658
+ if (open) {
659
+ try {
660
+ const purged = purgeForgottenTurn(runtime.purgeSpool, { sessionID: id, messageID: open.messageID })
661
+ if (purged > 0) runtime.log.info("spooled capture of a forgotten turn deleted", { sessionID: id, entries: purged })
662
+ } catch (error) {
663
+ runtime.log.warn("the capture of a forgotten turn could not be deleted; a later purge may catch it", { sessionID: id, error: errorMessage(error) })
664
+ }
665
+ const outcome = await runtime.deleteCaptureTurn?.({
666
+ sessionID: id,
667
+ visibility: runtime.config.captureVisibility,
668
+ key: turnKeyPrefix(id, open.messageID),
669
+ })
670
+ if (outcome?.removed > 0) runtime.log.info("delivered capture of a forgotten turn deleted", { sessionID: id, entries: outcome.removed })
671
+ if (outcome?.failed) failed += 1
672
+ }
673
+ child = id
674
+ }
675
+ return { marked, failed }
676
+ }
677
+ runtime.noteForgetTurn = noteForgetTurn
678
+ /** The turn this session last had flushed as superseded or evicted, if recent. */
679
+ runtime.partialTurnOf = (sessionID) => partialOf(sessionID ? String(sessionID) : "")
680
+
510
681
  /**
511
682
  * Stop capturing. Open turns are flushed and sends still running are
512
683
  * awaited, together for at most `shutdownMs`. A send that has not finished by
@@ -540,6 +711,6 @@ export function attachCapture(ctx, runtime, options = {}) {
540
711
  runtime.log.warn("capture shutdown deadline reached; unsent turns stay in the spool", { left, afterMs: shutdownMs })
541
712
  }
542
713
  /** Sizes of the per-process maps, for tests and diagnostics. */
543
- dispose.stats = () => ({ turns: turns.size, models: models.size, seenEvents: seenEvents.size, compacted: compacted.size })
714
+ dispose.stats = () => ({ turns: turns.size, models: models.size, seenEvents: seenEvents.size, compacted: compacted.size, partialTurn: partialTurn.size, spawnTurn: spawnTurn.size })
544
715
  return dispose
545
716
  }
@@ -0,0 +1,141 @@
1
+ import { turnKeyPrefix } from "./spool.js"
2
+ import { rememberBounded } from "./util.js"
3
+
4
+ /**
5
+ * A turn with a forget is not kept (0.9.14 gate, `tool-revise-forget#2`).
6
+ *
7
+ * A forget erases a memory's text on the server. The turn that asked for it
8
+ * restates that text: the person's request quotes it, the agent's answer often
9
+ * does, and the forget's own result can too. Capture kept that turn as L0, so
10
+ * the text survived in Memory's own transcript.
11
+ *
12
+ * Exact-text redaction cannot close this: a paraphrase of the forgotten text
13
+ * carries no run of its words, so masking (src/forget-purge.js) passes it
14
+ * through. Instead the whole turn is dropped, and the log keeps a one-line
15
+ * marker where the turn would have been. A declined forget, or one that
16
+ * deleted nothing, leaves capture as it was.
17
+ *
18
+ * Two pieces:
19
+ *
20
+ * - **The mark.** A successful forget marks its session while its turn is
21
+ * open: that turn is the one it ran in, and `take` spends the mark when the
22
+ * turn flushes, so the turn after it is captured as usual. Every session on
23
+ * the forget's parent chain is marked too: a subagent has no turn of its own
24
+ * without `captureSubagents`, and the parent's turn is the one that carries
25
+ * the request and the task's result. A forget made with no turn open (a
26
+ * command, or a script calling the tool) has no turn to protect and marks
27
+ * nothing. The mark lives in one process, so the caller also takes the
28
+ * turn's capture claim (`claimCapture`), which every other instance sees at
29
+ * its flush.
30
+ *
31
+ * A mark's life is its turn's: the flush spends it and `session.deleted`
32
+ * drops it. `ttlMs` is only a safe upper bound for a mark whose turn never
33
+ * ends (a host that stops emitting events), far longer than any turn.
34
+ * - **A capture already spooled.** A turn evicted mid-flight (a host may open
35
+ * many sessions) or one whose send failed has its capture in the spool
36
+ * before the forget succeeds. `purgeForgottenTurn` deletes it through the
37
+ * spool's own `purgeMatching`, by the turn's idempotency key, whatever text
38
+ * it holds; an entry being sent is deleted too and its sender does not
39
+ * re-queue it.
40
+ *
41
+ * What this does not reach: a capture the backend already accepted. The
42
+ * plugin has no per-turn delete, so that copy stays in L0 until the person
43
+ * erases it; recall withholds it (the forgotten-copy fingerprint), and the
44
+ * purge entries mask it from later captures (docs/capture-delivery.md).
45
+ *
46
+ * The mark is an in-memory map, one entry per session: a restart forgets it,
47
+ * and a turn whose capture crossed the restart is again covered by the spool
48
+ * purge only. No text is kept here, and nothing is written to a log.
49
+ */
50
+
51
+ /**
52
+ * A mark older than this no longer names a live turn. It is a safety net for a
53
+ * turn that never ends, not the mark's life: the flush spends the mark and a
54
+ * deleted session drops it, and a turn can run for hours.
55
+ */
56
+ export const FORGET_TURN_TTL_MS = 24 * 3_600_000
57
+ /** Sessions marked at most; the oldest go first. */
58
+ const MAX_MARKS = 200
59
+
60
+ /** A Date, a ms number, or anything else (no boundary: every mark counts). */
61
+ function millis(value) {
62
+ if (value instanceof Date) return value.getTime()
63
+ const number = Number(value)
64
+ return Number.isFinite(number) ? number : Number.NaN
65
+ }
66
+
67
+ /**
68
+ * `now` is the wall clock, never the person's configured or pinned clock: a
69
+ * mark is compared with a turn's own start (`new Date()`, src/capture.js), and
70
+ * a pinned clock in an eval run would put the two on different days.
71
+ *
72
+ * @param {{ now?: () => number, ttlMs?: number, max?: number }} [options]
73
+ */
74
+ export function createForgetTurns({ now = Date.now, ttlMs = FORGET_TURN_TTL_MS, max = MAX_MARKS } = {}) {
75
+ /** @type {Map<string, number>} session id → when its forget succeeded, in ms */
76
+ const marks = new Map()
77
+
78
+ return {
79
+ /**
80
+ * A forget succeeded in `sessionID`: the turn it ran in is not kept.
81
+ *
82
+ * @returns {boolean} whether the session is marked (false without an id)
83
+ */
84
+ note(sessionID) {
85
+ if (!sessionID) return false
86
+ rememberBounded(marks, String(sessionID), now(), max)
87
+ return true
88
+ },
89
+ /**
90
+ * Whether a forget happened in the turn that started at `startedAt`, and
91
+ * spend the mark. The mark is set only while a turn is open, so this is the
92
+ * flush of that turn; the comparison keeps a stale mark from spending
93
+ * itself on a later turn. A mark older than `ttlMs` is spent and answers
94
+ * false, so the turn is captured as usual.
95
+ *
96
+ * @param {string} sessionID
97
+ * @param {Date | number | undefined} startedAt
98
+ */
99
+ take(sessionID, startedAt) {
100
+ if (!sessionID) return false
101
+ const id = String(sessionID)
102
+ const at = marks.get(id)
103
+ if (at === undefined) return false
104
+ marks.delete(id)
105
+ if (now() - at >= ttlMs) return false
106
+ const started = millis(startedAt)
107
+ return !Number.isFinite(started) || started <= 0 || at >= started
108
+ },
109
+ /** When the session was marked, in ms, or undefined. */
110
+ peek(sessionID) {
111
+ return sessionID ? marks.get(String(sessionID)) : undefined
112
+ },
113
+ /** Drop a session's mark (a session the host deleted). */
114
+ drop(sessionID) {
115
+ if (sessionID) marks.delete(String(sessionID))
116
+ },
117
+ /** Sessions marked now, for diagnostics. */
118
+ size() {
119
+ return marks.size
120
+ },
121
+ }
122
+ }
123
+
124
+ /**
125
+ * Delete the spooled capture of one turn, whatever text it holds: its pending
126
+ * entry, an in-flight claim, a quarantined `.failed` entry, and the state
127
+ * files. The turn is named by the same idempotency key it was captured with
128
+ * (`turnKey` in src/spool.js), so another turn of the same session is never
129
+ * touched. The log names the file, never the content.
130
+ *
131
+ * @param {(predicate: (entry: any, info: { state: string, file: string, raw: string }) => boolean) => { purged?: number } | undefined} purgeSpool
132
+ * the spool's `purgeMatching`
133
+ * @param {{ sessionID?: string, messageID?: string }} turn
134
+ * @returns {number} entries deleted
135
+ */
136
+ export function purgeForgottenTurn(purgeSpool, { sessionID, messageID } = {}) {
137
+ if (typeof purgeSpool !== "function" || !sessionID || !messageID) return 0
138
+ const prefix = turnKeyPrefix(sessionID, messageID)
139
+ const result = purgeSpool((entry) => typeof entry?.key === "string" && entry.key.startsWith(prefix))
140
+ return Number(result?.purged) || 0
141
+ }
@@ -0,0 +1,78 @@
1
+ /**
2
+ * The OpenCode versions Memory supports, and what a host outside them is told.
3
+ *
4
+ * The range is `>= 2.1.4 < 2.4.0`: 2.3 is tested (jelly moves its engine to
5
+ * 2.3), nothing above it is, and the floor is the newest host whose plugin
6
+ * surface Memory needs. A host outside the range gets **one tool and nothing
7
+ * else**: no hooks, no protocol block, no request. OpenCode discards a plugin's
8
+ * `console.error`, so a bare message would leave a person with memory tools that
9
+ * simply vanished (review F1); the tool's description and its answer carry the
10
+ * reason, so the agent can tell the person why, and the same sentence goes to
11
+ * Memory's own debug log.
12
+ */
13
+ import { versionAtLeast, versionBelow, versionParts } from "./util.js"
14
+
15
+ /** The oldest host Memory supports: 2.1.4. */
16
+ export const HOST_FLOOR = Object.freeze({ major: 2, minor: 1, patch: 4 })
17
+ /** The first host Memory does not support: 2.4.0. */
18
+ export const HOST_CEILING = Object.freeze({ major: 2, minor: 4, patch: 0 })
19
+
20
+ /**
21
+ * The one tool a refused host registers. Its id is `mem_off` (the host prefixes
22
+ * the plugin id). Free on `build/0.11`, live or retired: `mem_status` is a 0.8
23
+ * shim (`src/tools/aliases.js`), so that name could not be used.
24
+ */
25
+ export const REFUSAL_TOOL_NAME = "off"
26
+
27
+ /** A refusal tool's whole input: it reads nothing. */
28
+ const EMPTY_INPUT = Object.freeze({ type: "object", properties: {}, additionalProperties: false })
29
+
30
+ /**
31
+ * Whether `version` is outside the range, and the one or two sentences that say
32
+ * so. The sentences carry no contractions and name what to do next.
33
+ *
34
+ * @param {unknown} version the host's `ctx.app.version`
35
+ * @returns {{ kind: "floor" | "ceiling", sentence: string } | null}
36
+ */
37
+ export function hostRefusal(version) {
38
+ const stated = String(version ?? "").trim()
39
+ if (!versionAtLeast(version, HOST_FLOOR.major, HOST_FLOOR.minor, HOST_FLOOR.patch)) {
40
+ // A version that cannot be read is refused at the floor without pretending
41
+ // to know which release it is ("dev", "", "test").
42
+ const sentence =
43
+ versionParts(version) === null
44
+ ? "Memory is off: this OpenCode reports no version Memory can read. Update OpenCode to 2.1.4 or newer."
45
+ : `Memory is off: this OpenCode (${stated}) is older than Memory supports. Update OpenCode to 2.1.4 or newer.`
46
+ return { kind: "floor", sentence }
47
+ }
48
+ if (!versionBelow(version, HOST_CEILING.major, HOST_CEILING.minor, HOST_CEILING.patch)) {
49
+ return {
50
+ kind: "ceiling",
51
+ sentence: `Memory is off: this OpenCode (${stated}) is newer than Memory supports. Update Memory, or use OpenCode below 2.4.0.`,
52
+ }
53
+ }
54
+ return null
55
+ }
56
+
57
+ /**
58
+ * Register the one tool a refused host gets: its description is the sentence,
59
+ * and calling it answers the sentence. Nothing else is touched, and a throw here
60
+ * is not caught — the host's own log is where a registration failure must land.
61
+ *
62
+ * @param {any} ctx the plugin context
63
+ * @param {string} sentence what is wrong with the host
64
+ */
65
+ export async function registerRefusal(ctx, sentence) {
66
+ return ctx.tool.transform((editor) => {
67
+ editor.add({
68
+ name: REFUSAL_TOOL_NAME,
69
+ description: sentence,
70
+ input: EMPTY_INPUT,
71
+ // The namespace is what gives the tool its `mem_` id, as every other
72
+ // Memory tool has one; the namespace itself is not declared, so this is
73
+ // still exactly one registration.
74
+ options: { namespace: "mem" },
75
+ execute: async () => ({ content: sentence }),
76
+ })
77
+ })
78
+ }