typeclaw 0.48.12 → 0.49.0

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 (213) hide show
  1. package/package.json +6 -3
  2. package/scripts/dump-system-prompt.ts +52 -110
  3. package/src/agent/attention-escalation.ts +8 -5
  4. package/src/agent/auth-reloadable.ts +2 -3
  5. package/src/agent/auth.ts +59 -79
  6. package/src/agent/compaction.ts +2 -2
  7. package/src/agent/index.ts +173 -85
  8. package/src/agent/live-sessions.ts +2 -2
  9. package/src/agent/live-subagents.ts +1 -0
  10. package/src/agent/llm-replay-sanitizer.ts +1 -1
  11. package/src/agent/model-overrides.ts +1 -1
  12. package/src/agent/multimodal/look-at.ts +3 -3
  13. package/src/agent/multimodal/read-redirect.ts +1 -1
  14. package/src/agent/plugin-tools.ts +76 -39
  15. package/src/agent/prompt-cache-key.ts +42 -0
  16. package/src/agent/provider-error.ts +179 -10
  17. package/src/agent/reload-tool.ts +1 -1
  18. package/src/agent/restart-handoff/index.ts +7 -14
  19. package/src/agent/reviewer-activity.ts +68 -0
  20. package/src/agent/session-origin.ts +33 -0
  21. package/src/agent/subagents.ts +14 -2
  22. package/src/agent/system-prompt.ts +68 -202
  23. package/src/agent/todo/continuation-policy.ts +12 -4
  24. package/src/agent/tool-error-remediation.ts +1 -1
  25. package/src/agent/tool-file-safety.ts +113 -14
  26. package/src/agent/tool-not-found-nudge.ts +1 -1
  27. package/src/agent/tool-result-budget.ts +2 -2
  28. package/src/agent/tools/channel-disengage.ts +2 -2
  29. package/src/agent/tools/channel-edit.ts +2 -2
  30. package/src/agent/tools/channel-fetch-attachment.ts +2 -2
  31. package/src/agent/tools/channel-history-render.ts +2 -1
  32. package/src/agent/tools/channel-history.ts +2 -2
  33. package/src/agent/tools/channel-react.ts +2 -2
  34. package/src/agent/tools/channel-read.ts +2 -2
  35. package/src/agent/tools/channel-reply.ts +25 -7
  36. package/src/agent/tools/channel-send.ts +51 -9
  37. package/src/agent/tools/curl-impersonate.ts +11 -2
  38. package/src/agent/tools/grant-role.ts +2 -2
  39. package/src/agent/tools/post-github-review.ts +79 -17
  40. package/src/agent/tools/restart.ts +2 -2
  41. package/src/agent/tools/skip-response.ts +4 -4
  42. package/src/agent/tools/spawn-subagent.ts +165 -14
  43. package/src/agent/tools/stream-snapshot.ts +2 -2
  44. package/src/agent/tools/subagent-cancel.ts +2 -2
  45. package/src/agent/tools/subagent-output.ts +10 -2
  46. package/src/agent/tools/todo/index.ts +2 -2
  47. package/src/agent/tools/webfetch/tool.ts +2 -2
  48. package/src/agent/tools/websearch.ts +2 -2
  49. package/src/bundled-plugins/backup/README.md +10 -9
  50. package/src/bundled-plugins/backup/runner.ts +140 -58
  51. package/src/bundled-plugins/backup/subagents.ts +58 -26
  52. package/src/bundled-plugins/github-cli-auth/gh-command.ts +34 -2
  53. package/src/bundled-plugins/github-cli-auth/granted-push.ts +135 -0
  54. package/src/bundled-plugins/github-cli-auth/index.ts +83 -11
  55. package/src/bundled-plugins/github-cli-auth/review-account.ts +23 -0
  56. package/src/bundled-plugins/github-cli-auth/review-checkout.ts +9 -2
  57. package/src/bundled-plugins/github-cli-auth/review-recorder.ts +45 -7
  58. package/src/bundled-plugins/operator/operator.ts +15 -4
  59. package/src/bundled-plugins/reviewer/skills/code-review.ts +1 -1
  60. package/src/bundled-plugins/security/index.ts +50 -2
  61. package/src/bundled-plugins/security/policies/git-exfil.ts +24 -12
  62. package/src/channels/adapters/discord-bot-reactions.ts +18 -0
  63. package/src/channels/adapters/discord-bot.ts +122 -67
  64. package/src/channels/adapters/discord-reactions.ts +18 -0
  65. package/src/channels/adapters/discord.ts +114 -8
  66. package/src/channels/adapters/github/inbound.ts +103 -8
  67. package/src/channels/adapters/github/index.ts +251 -19
  68. package/src/channels/adapters/github/last-alive.ts +27 -0
  69. package/src/channels/adapters/github/outbound.ts +54 -18
  70. package/src/channels/adapters/github/pending-review-store.ts +141 -0
  71. package/src/channels/adapters/github/permission-guidance.ts +1 -0
  72. package/src/channels/adapters/github/reactions.ts +100 -0
  73. package/src/channels/adapters/github/reconcile-cooldown-store.ts +197 -67
  74. package/src/channels/adapters/github/reconcile-open-prs.ts +418 -33
  75. package/src/channels/adapters/github/recovery.ts +106 -0
  76. package/src/channels/adapters/github/review-check.ts +510 -0
  77. package/src/channels/adapters/github/review-submitter.ts +34 -2
  78. package/src/channels/adapters/instagram.ts +32 -14
  79. package/src/channels/adapters/kakaotalk.ts +22 -7
  80. package/src/channels/adapters/line.ts +18 -3
  81. package/src/channels/adapters/outbound-account.ts +20 -0
  82. package/src/channels/adapters/own-reactions.ts +66 -0
  83. package/src/channels/adapters/recovery-correlation.ts +214 -0
  84. package/src/channels/adapters/slack-bot-classify.ts +18 -11
  85. package/src/channels/adapters/slack-bot-dedupe.ts +111 -28
  86. package/src/channels/adapters/slack-bot-reactions.ts +18 -0
  87. package/src/channels/adapters/slack-bot.ts +125 -57
  88. package/src/channels/adapters/slack-classify.ts +25 -4
  89. package/src/channels/adapters/slack-inbound-revision.ts +96 -0
  90. package/src/channels/adapters/slack-reactions.ts +18 -0
  91. package/src/channels/adapters/slack-thread-ts.ts +6 -0
  92. package/src/channels/adapters/slack.ts +48 -3
  93. package/src/channels/adapters/teams.ts +14 -4
  94. package/src/channels/adapters/telegram-bot.ts +56 -10
  95. package/src/channels/adapters/webex-bot.ts +12 -2
  96. package/src/channels/adapters/webex.ts +12 -2
  97. package/src/channels/background-handoff.ts +434 -0
  98. package/src/channels/background-obligations.ts +893 -0
  99. package/src/channels/continuity-types.ts +271 -0
  100. package/src/channels/github-review-check.ts +598 -0
  101. package/src/channels/github-review-turn-ledger.ts +102 -28
  102. package/src/channels/github-review-verdict-coordinator.ts +96 -13
  103. package/src/channels/github-token-bridge.ts +11 -5
  104. package/src/channels/inbound-journal.ts +1738 -0
  105. package/src/channels/index.ts +6 -1
  106. package/src/channels/manager.ts +17 -7
  107. package/src/channels/recovery-dispatcher.ts +264 -0
  108. package/src/channels/recovery-notice.ts +94 -0
  109. package/src/channels/recovery-outbox.ts +459 -0
  110. package/src/channels/router.ts +2582 -633
  111. package/src/channels/schema.ts +8 -1
  112. package/src/channels/subagent-completion-bridge.ts +17 -14
  113. package/src/channels/types.ts +121 -16
  114. package/src/channels/waiting-reactions.ts +664 -0
  115. package/src/cli/compose.ts +7 -4
  116. package/src/cli/hostd.ts +49 -3
  117. package/src/cli/inspect.ts +11 -14
  118. package/src/cli/model.ts +7 -5
  119. package/src/cli/oauth-callbacks.ts +38 -23
  120. package/src/coding-agent/broker-body.ts +38 -0
  121. package/src/coding-agent/broker.ts +290 -0
  122. package/src/coding-agent/claude.ts +95 -0
  123. package/src/coding-agent/codex.ts +104 -0
  124. package/src/coding-agent/index.ts +506 -0
  125. package/src/coding-agent/omo-state.ts +69 -0
  126. package/src/coding-agent/omo-stream.ts +98 -0
  127. package/src/coding-agent/omo.ts +192 -0
  128. package/src/coding-agent/runner.ts +263 -0
  129. package/src/coding-agent/tool.ts +62 -0
  130. package/src/coding-agent/worktree.ts +355 -0
  131. package/src/compose/restart.ts +10 -3
  132. package/src/compose/start.ts +20 -3
  133. package/src/config/config.ts +70 -26
  134. package/src/config/providers.ts +278 -50
  135. package/src/container/exit-reason.ts +44 -0
  136. package/src/container/index.ts +5 -0
  137. package/src/container/log-archive.ts +51 -13
  138. package/src/container/memory-limit.ts +1 -1
  139. package/src/container/memory-oversubscription.ts +36 -6
  140. package/src/container/oom-events.ts +86 -0
  141. package/src/container/restart.ts +2 -0
  142. package/src/container/shared.ts +8 -1
  143. package/src/container/start.ts +25 -13
  144. package/src/container/stop.ts +6 -2
  145. package/src/container/tool-oom-priority.ts +32 -0
  146. package/src/cron/consumer.ts +10 -4
  147. package/src/cron/reloadable.ts +23 -2
  148. package/src/doctor/checks.ts +14 -2
  149. package/src/hostd/daemon.ts +20 -10
  150. package/src/hostd/spawn.ts +106 -5
  151. package/src/hostd/version.ts +20 -0
  152. package/src/hostd/watchdog.ts +241 -0
  153. package/src/init/dockerfile.ts +57 -592
  154. package/src/init/index.ts +6 -7
  155. package/src/init/oauth-login.ts +57 -17
  156. package/src/inspect/transcript-view.ts +6 -3
  157. package/src/mcp/client.ts +3 -1
  158. package/src/operations/classify-tool-outcome.ts +45 -1
  159. package/src/operations/incidents.ts +10 -5
  160. package/src/plugin/core-tool-names.ts +1 -1
  161. package/src/plugin/define.ts +1 -0
  162. package/src/plugin/index.ts +1 -0
  163. package/src/plugin/types.ts +6 -1
  164. package/src/run/background-handoff-boot.ts +86 -0
  165. package/src/run/channel-session-factory.ts +5 -4
  166. package/src/run/index.ts +93 -93
  167. package/src/run/resource-sample.ts +19 -0
  168. package/src/sandbox/build.ts +4 -0
  169. package/src/sandbox/coding-agent.ts +214 -0
  170. package/src/sandbox/policy.ts +1 -0
  171. package/src/sandbox/runtime-private.ts +4 -1
  172. package/src/secrets/coding-agent-auth.ts +97 -0
  173. package/src/secrets/index.ts +0 -16
  174. package/src/secrets/refresh-provider-oauth.ts +30 -76
  175. package/src/secrets/schema.ts +3 -4
  176. package/src/secrets/storage.ts +133 -234
  177. package/src/server/command-runner.ts +6 -2
  178. package/src/server/index.ts +102 -41
  179. package/src/sessions/index.ts +1 -1
  180. package/src/skills/typeclaw-channel-github/SKILL.md +7 -5
  181. package/src/skills/typeclaw-claude-code/SKILL.md +25 -260
  182. package/src/skills/typeclaw-claude-code/references/auth-flow.md +7 -23
  183. package/src/skills/typeclaw-claude-code/references/headless-sessions.md +11 -0
  184. package/src/skills/typeclaw-claude-code/references/results-and-worktrees.md +13 -0
  185. package/src/skills/typeclaw-codex-cli/SKILL.md +35 -270
  186. package/src/skills/typeclaw-codex-cli/references/auth-flow.md +13 -20
  187. package/src/skills/typeclaw-codex-cli/references/headless-sessions.md +26 -0
  188. package/src/skills/typeclaw-codex-cli/references/results-and-worktrees.md +28 -0
  189. package/src/skills/typeclaw-config/SKILL.md +24 -24
  190. package/src/skills/typeclaw-config/references/dockerfile.md +14 -13
  191. package/src/skills/typeclaw-cron/SKILL.md +1 -1
  192. package/src/skills/typeclaw-github-contributing/SKILL.md +2 -2
  193. package/src/skills/typeclaw-memory/SKILL.md +3 -3
  194. package/src/skills/typeclaw-omo-cli/SKILL.md +52 -0
  195. package/src/skills/typeclaw-omo-cli/references/auth-flow.md +11 -0
  196. package/src/skills/typeclaw-omo-cli/references/headless-sessions.md +11 -0
  197. package/src/skills/typeclaw-omo-cli/references/results-and-worktrees.md +23 -0
  198. package/src/skills/typeclaw-plugins/SKILL.md +20 -20
  199. package/src/skills/typeclaw-skills/SKILL.md +19 -2
  200. package/src/skills/typeclaw-troubleshooting/SKILL.md +15 -2
  201. package/src/tui/index.ts +5 -3
  202. package/src/tui/theme.ts +1 -1
  203. package/typeclaw.schema.json +44 -2
  204. package/src/agent/adaptive-thinking-compat.ts +0 -79
  205. package/src/secrets/claude-credentials-json.ts +0 -129
  206. package/src/secrets/codex-auth-json.ts +0 -102
  207. package/src/secrets/export-claude-credentials-file.ts +0 -270
  208. package/src/secrets/export-codex-auth-file.ts +0 -250
  209. package/src/secrets/oauth-xai.ts +0 -348
  210. package/src/skills/typeclaw-claude-code/references/stop-hook.md +0 -101
  211. package/src/skills/typeclaw-claude-code/references/tmux-driving.md +0 -243
  212. package/src/skills/typeclaw-codex-cli/references/stop-hook.md +0 -92
  213. package/src/skills/typeclaw-codex-cli/references/tmux-driving.md +0 -239
@@ -20,7 +20,12 @@ export {
20
20
  type PrVerdictActivityBridge,
21
21
  type PrVerdictActivityBridgeOptions,
22
22
  } from './pr-verdict-activity-bridge'
23
- export { setReviewObserver, setReviewOutputObserver, type ReviewOutputState } from './github-review-turn-ledger'
23
+ export {
24
+ setReviewObserver,
25
+ setReviewOutputObserver,
26
+ setReviewCoverageCapture,
27
+ type ReviewOutputState,
28
+ } from './github-review-turn-ledger'
24
29
  export {
25
30
  createSubagentCompletionBridge,
26
31
  type SubagentCompletionBridge,
@@ -26,8 +26,11 @@ import { createTeamsAdapter, type TeamsAdapter } from './adapters/teams'
26
26
  import { createTelegramBotAdapter, type TelegramBotAdapter } from './adapters/telegram-bot'
27
27
  import { createWebexAdapter, type WebexAdapter } from './adapters/webex'
28
28
  import { createWebexBotAdapter, type WebexBotAdapter } from './adapters/webex-bot'
29
+ import type { BackgroundObligationStore } from './background-obligations'
29
30
  import { describeError } from './describe-error'
30
31
  import type { GithubTokenBridge } from './github-token-bridge'
32
+ import type { InboundJournal } from './inbound-journal'
33
+ import type { RecoveryOutbox } from './recovery-outbox'
31
34
  import {
32
35
  createChannelRouter,
33
36
  type ChannelRouter,
@@ -58,6 +61,7 @@ const consoleLogger: ChannelManagerLogger = {
58
61
  export type ChannelManagerOptions = {
59
62
  agentDir: string
60
63
  channelsConfigRef: () => ChannelsConfig
64
+ onRecoveryReady?: () => void
61
65
  // Plain-text names the agent answers to in channel engagement (the
62
66
  // `alias` field in `typeclaw.json`), forwarded to the router as
63
67
  // `configuredAliases`. Read live on every inbound so an `applied`-class
@@ -97,6 +101,9 @@ export type ChannelManagerOptions = {
97
101
  createTelegramAdapter?: typeof createTelegramBotAdapter
98
102
  createWebexAdapter?: typeof createWebexAdapter
99
103
  createWebexBotAdapter?: typeof createWebexBotAdapter
104
+ backgroundObligations?: BackgroundObligationStore
105
+ inboundJournal?: InboundJournal
106
+ recoveryOutbox?: RecoveryOutbox
100
107
  // Wake-up gate: forwarded to the router, which calls
101
108
  // `permissions.has(origin, 'channel.respond')` BEFORE creating a
102
109
  // session for any inbound. Optional here to keep direct manager-level
@@ -135,10 +142,6 @@ export type ChannelManagerOptions = {
135
142
  // otherwise spawn a duplicate child). Production wiring (src/run/index.ts)
136
143
  // supplies it from the LiveSubagentRegistry; tests omit it.
137
144
  newestRunningChildSubagentStartedAt?: (sessionId: string) => number | null
138
- // Forwarded to the router so the graceful-restart handoff can name the
139
- // background subagents a session was still awaiting. Same wiring shape as
140
- // newestRunningChildSubagentStartedAt; tests omit it.
141
- listRunningBackgroundSubagentNames?: (sessionId: string) => string[]
142
145
  // Forwarded to the router so an adapter-triggered work invalidation can stop
143
146
  // independent background sessions that a parent AgentSession abort cannot reach.
144
147
  cancelRunningSubagentsByWorkKey?: (
@@ -249,6 +252,9 @@ export function createChannelManager(options: ChannelManagerOptions): ChannelMan
249
252
  const env = options.env ?? process.env
250
253
  const router = createChannelRouter({
251
254
  agentDir: options.agentDir,
255
+ ...(options.backgroundObligations ? { backgroundObligations: options.backgroundObligations } : {}),
256
+ ...(options.inboundJournal ? { inboundJournal: options.inboundJournal } : {}),
257
+ ...(options.recoveryOutbox ? { recoveryOutbox: options.recoveryOutbox } : {}),
252
258
  configForAdapter: (adapter) => options.channelsConfigRef()[adapter],
253
259
  logger,
254
260
  ...(options.aliasesRef ? { configuredAliases: options.aliasesRef } : {}),
@@ -261,9 +267,6 @@ export function createChannelManager(options: ChannelManagerOptions): ChannelMan
261
267
  ...(options.newestRunningChildSubagentStartedAt
262
268
  ? { newestRunningChildSubagentStartedAt: options.newestRunningChildSubagentStartedAt }
263
269
  : {}),
264
- ...(options.listRunningBackgroundSubagentNames
265
- ? { listRunningBackgroundSubagentNames: options.listRunningBackgroundSubagentNames }
266
- : {}),
267
270
  ...(options.cancelRunningSubagentsByWorkKey
268
271
  ? { cancelRunningSubagentsByWorkKey: options.cancelRunningSubagentsByWorkKey }
269
272
  : {}),
@@ -528,6 +531,7 @@ export function createChannelManager(options: ChannelManagerOptions): ChannelMan
528
531
  recoveryRestartAttempts: 0,
529
532
  recoveryRestartQueued: false,
530
533
  })
534
+ options.onRecoveryReady?.()
531
535
  return { status: 'started' }
532
536
  } catch (err) {
533
537
  await cleanupPartialStart(adapter)
@@ -735,6 +739,11 @@ export function createChannelManager(options: ChannelManagerOptions): ChannelMan
735
739
  const now = recoveryNow()
736
740
  for (const [name, entry] of live) {
737
741
  if (entry.adapter.isConnected()) {
742
+ void router
743
+ .recoverWaitingReactions(name)
744
+ .catch((err) =>
745
+ logger.warn(`[channels] waiting reaction cleanup failed adapter="${name}": ${describeError(err)}`),
746
+ )
738
747
  entry.disconnectedSinceMs = null
739
748
  entry.nextRecoveryRestartAtMs = null
740
749
  entry.recoveryRestartAttempts = 0
@@ -1028,6 +1037,7 @@ export function createChannelManager(options: ChannelManagerOptions): ChannelMan
1028
1037
  }
1029
1038
  }
1030
1039
 
1040
+ options.onRecoveryReady?.()
1031
1041
  return { started, stopped, restarted, restartRequired, ...(credentialApply ? { credentialApply } : {}) }
1032
1042
  },
1033
1043
  }
@@ -0,0 +1,264 @@
1
+ import type { BackgroundObligationStore } from './background-obligations'
2
+ import type { RecoveryRecord } from './continuity-types'
3
+ import type { InboundJournal } from './inbound-journal'
4
+ import type { RecoveryOutbox } from './recovery-outbox'
5
+ import type { ChannelRouter } from './router'
6
+ import { channelKeyId, type ChannelKey, type RecoveryRedelivery } from './types'
7
+
8
+ // Bounds how long a restart notice waits for an adapter still deciding whether it re-admitted the
9
+ // interrupted work (GitHub's boot reconcile pass), so a stuck pass delays the notice, never loses it.
10
+ const REDELIVERY_WAIT_MS = 5 * 60_000
11
+
12
+ /** Transport-only recovery; each destination progresses independently. */
13
+ export class RecoveryDispatcher {
14
+ private readonly lanes = new Map<string, Promise<void>>()
15
+ private timer: NodeJS.Timeout | undefined
16
+ private stopped = false
17
+ /** Set by the first (boot) wake; imports never dispatch before adapters are ready. */
18
+ private woken = false
19
+ private readonly unsubscribe: () => void
20
+ /** Destinations whose due work was skipped while an earlier pass still held their lane. */
21
+ private readonly deferred = new Set<string>()
22
+
23
+ constructor(
24
+ private readonly outbox: RecoveryOutbox,
25
+ private readonly router: ChannelRouter,
26
+ private readonly options: {
27
+ now?: () => number
28
+ consistencyDelayMs?: number
29
+ onError?: (error: unknown) => void
30
+ backgroundObligations?: BackgroundObligationStore
31
+ inboundJournal?: InboundJournal
32
+ } = {},
33
+ ) {
34
+ router.setRecoveryStopHandler((target, parent) => this.suppressParent(target, parent))
35
+ // A transfer made durable after boot (a live turn that ended unanswered) dispatches now
36
+ // instead of at the next poll; multiple imports in one tick coalesce into one wake.
37
+ this.unsubscribe = outbox.subscribe(() => {
38
+ if (!this.woken || this.stopped) return
39
+ clearTimeout(this.timer)
40
+ this.timer = undefined
41
+ this.schedule(0)
42
+ })
43
+ }
44
+
45
+ private async validateCoverageInLane(record: RecoveryRecord): Promise<'open' | 'resolved'> {
46
+ if (record.covers.some((cover) => cover.store === 'inbound')) {
47
+ if (!this.options.inboundJournal) throw new Error('Inbound recovery requires journal authority')
48
+ return this.options.inboundJournal.validateNotice(record)
49
+ }
50
+ if (record.covers.some((cover) => cover.store === 'background')) {
51
+ this.options.inboundJournal?.assertAvailable()
52
+ if (!this.options.backgroundObligations) throw new Error('Background recovery requires source authority')
53
+ this.options.backgroundObligations.assertAvailable()
54
+ }
55
+ return this.options.backgroundObligations?.validateNotice(record) ?? 'open'
56
+ }
57
+
58
+ private async acknowledge(record: RecoveryRecord): Promise<void> {
59
+ if (record.covers.some((cover) => cover.store === 'inbound')) {
60
+ const journal = this.options.inboundJournal
61
+ if (!journal) throw new Error('Inbound recovery requires journal authority')
62
+ if (this.options.backgroundObligations)
63
+ await this.options.backgroundObligations.withTargetLane(record.target, () => journal.acknowledgeNotice(record))
64
+ else await journal.acknowledgeNotice(record)
65
+ return
66
+ }
67
+ const source = this.options.backgroundObligations
68
+ if (!source) return
69
+ if (record.covers.some((cover) => cover.store === 'background')) {
70
+ await source.withTargetLane(record.target, () => source.acknowledgeNotice(record))
71
+ } else {
72
+ // Legacy upgrade receipts have immutable inventory-only provenance.
73
+ await source.acknowledgeNotice(record)
74
+ }
75
+ }
76
+
77
+ /**
78
+ * Source acknowledgment, then retirement of the terminal outbox record. Retirement requires the
79
+ * source to validate the delivery as resolved in its lane, so no open or re-importable coverage
80
+ * can still point at it; the outbox keeps an immutable fence for any later identical import.
81
+ */
82
+ private async finish(record: RecoveryRecord, retire: boolean): Promise<void> {
83
+ await this.acknowledge(record)
84
+ if (!retire) return
85
+ const source = this.options.backgroundObligations
86
+ const coverage =
87
+ source && record.covers.some((cover) => cover.store !== 'inventory')
88
+ ? await source.withTargetLane(record.target, () => this.validateCoverageInLane(record))
89
+ : await this.validateCoverageInLane(record)
90
+ if (coverage === 'resolved') await this.outbox.retire(record.deliveryId, record.generation)
91
+ }
92
+
93
+ async wake(): Promise<void> {
94
+ if (this.stopped) return
95
+ this.woken = true
96
+ clearTimeout(this.timer)
97
+ this.timer = undefined
98
+ const now = this.options.now?.() ?? Date.now()
99
+ let next = now + 30_000
100
+ const started = new Set<string>()
101
+ for (const record of await this.outbox.list()) {
102
+ const key = channelKeyId(record.target)
103
+ if (record.state === 'delivered' || record.state === 'suppressed') {
104
+ // A lane from an earlier pass may still hold this record's in-flight send (a /stop raced
105
+ // it), so it is retired on a later pass. A lane started by this pass skips terminal records.
106
+ await this.finish(record, !this.lanes.has(key) || started.has(key)).catch((error) =>
107
+ this.options.onError?.(error),
108
+ )
109
+ continue
110
+ }
111
+ const due = record.nextAttemptAt ?? 0
112
+ if (due > now) {
113
+ next = Math.min(next, due)
114
+ continue
115
+ }
116
+ if (this.lanes.has(key)) {
117
+ // That lane listed the outbox before this record was due or existed; run again after it.
118
+ if (!started.has(key)) this.deferred.add(key)
119
+ continue
120
+ }
121
+ started.add(key)
122
+ const lane = this.dispatchTarget(key)
123
+ .catch((error) => this.options.onError?.(error))
124
+ .finally(() => {
125
+ this.lanes.delete(key)
126
+ if (this.deferred.delete(key)) {
127
+ clearTimeout(this.timer)
128
+ this.timer = undefined
129
+ this.schedule(0)
130
+ } else this.schedule(30_000)
131
+ })
132
+ this.lanes.set(key, lane)
133
+ }
134
+ this.schedule(Math.max(10, next - now))
135
+ }
136
+
137
+ private schedule(delay: number): void {
138
+ if (this.stopped || this.timer) return
139
+ this.timer = setTimeout(() => {
140
+ this.timer = undefined
141
+ void this.wake().catch((error) => this.options.onError?.(error))
142
+ }, delay)
143
+ this.timer.unref?.()
144
+ }
145
+ private async acquire(record: RecoveryRecord) {
146
+ const claim = async () => {
147
+ if ((await this.validateCoverageInLane(record)) === 'resolved') return undefined
148
+ if (record.lease?.epoch === this.outbox.epoch) {
149
+ return (await this.outbox.repairLease(record.deliveryId, record.lease)) ? record.lease : undefined
150
+ }
151
+ return this.outbox.lease(record.deliveryId, record.generation)
152
+ }
153
+ try {
154
+ const source = this.options.backgroundObligations
155
+ return source && record.covers.some((cover) => cover.store !== 'inventory')
156
+ ? await source.withTargetLane(record.target, claim)
157
+ : await claim()
158
+ } catch (error) {
159
+ this.options.onError?.(error)
160
+ return undefined
161
+ }
162
+ }
163
+
164
+ private async dispatchTarget(key: string): Promise<void> {
165
+ // One pass per wake avoids a blocked destination starving another record.
166
+ for (const snapshot of await this.outbox.list()) {
167
+ if (channelKeyId(snapshot.target) !== key || this.stopped) continue
168
+ const record = await this.outbox.get(snapshot.deliveryId)
169
+ const now = this.options.now?.() ?? Date.now()
170
+ if (!record || record.state === 'delivered' || record.state === 'suppressed' || (record.nextAttemptAt ?? 0) > now)
171
+ continue
172
+ try {
173
+ const source = this.options.backgroundObligations
174
+ const coverage =
175
+ source && record.covers.some((cover) => cover.store !== 'inventory')
176
+ ? await source.withTargetLane(record.target, () => this.validateCoverageInLane(record!))
177
+ : await this.validateCoverageInLane(record)
178
+ if (coverage === 'resolved') {
179
+ await this.outbox.suppress(record.deliveryId, 'coverage-resolved', crypto.randomUUID())
180
+ continue
181
+ }
182
+ const redelivery = this.redelivery(record, now)
183
+ if (redelivery === 'pending') continue
184
+ if (redelivery === 'redelivered' && this.options.inboundJournal) {
185
+ await this.suppressRedelivered(record, this.options.inboundJournal)
186
+ continue
187
+ }
188
+ // Runtime state (restarts, ended turns) is never posted to channel users; the operator log
189
+ // carries it instead. Closing the coverage keeps boot recovery from re-importing it.
190
+ await this.suppressRecord(record, 'operator-log-only', crypto.randomUUID())
191
+ console.log(
192
+ `[channels] interrupted request in ${key} not re-answered (${record.cause ?? 'restart'}); no notice posted to the channel`,
193
+ )
194
+ } catch (error) {
195
+ this.options.onError?.(error)
196
+ continue
197
+ }
198
+ }
199
+ }
200
+
201
+ /** Only a never-attempted restart notice over inbound rows can be superseded by adapter redelivery. */
202
+ private redelivery(record: RecoveryRecord, now: number): RecoveryRedelivery {
203
+ const journal = this.options.inboundJournal
204
+ if (!journal || record.cause !== undefined || record.attempts > 0 || !this.router.recoveryRedelivery)
205
+ return 'not-redelivered'
206
+ const eventKinds = journal.noticeEventKinds(record)
207
+ if (!eventKinds) return 'not-redelivered'
208
+ const answer = this.router.recoveryRedelivery(record, eventKinds)
209
+ return answer === 'pending' && now - record.createdAt >= REDELIVERY_WAIT_MS ? 'not-redelivered' : answer
210
+ }
211
+
212
+ private async suppressRedelivered(record: RecoveryRecord, journal: InboundJournal): Promise<void> {
213
+ const decisionId = crypto.randomUUID()
214
+ const suppress = () => journal.suppressNoticeCoverage(record, { decisionId, reason: 'adapter-redelivered' })
215
+ const source = this.options.backgroundObligations
216
+ if (source) await source.withTargetLane(record.target, suppress)
217
+ else await suppress()
218
+ await this.outbox.suppress(record.deliveryId, 'adapter-redelivered', decisionId)
219
+ }
220
+
221
+ async suppressParent(target: ChannelKey, parentSessionId: string): Promise<void> {
222
+ const parentDecisionId = crypto.randomUUID()
223
+ for (const record of await this.outbox.list()) {
224
+ if (channelKeyId(record.target) !== channelKeyId(target)) continue
225
+ if (
226
+ record.sourceParentSessionId === parentSessionId ||
227
+ (record.covers.length > 0 && record.covers.every((coverage) => coverage.parentSessionId === parentSessionId))
228
+ ) {
229
+ await this.suppressRecord(record, 'user-stop', `${parentDecisionId}:${record.deliveryId}`, 'user_stop')
230
+ }
231
+ }
232
+ }
233
+
234
+ private async suppressRecord(
235
+ record: RecoveryRecord,
236
+ reason: string,
237
+ decisionId: string,
238
+ outboxReason = reason,
239
+ ): Promise<void> {
240
+ const source = this.options.backgroundObligations
241
+ const suppress = async () => {
242
+ if (record.covers.some((cover) => cover.store === 'inbound')) {
243
+ if (!this.options.inboundJournal) throw new Error('Inbound recovery requires journal authority')
244
+ await this.options.inboundJournal.suppressNoticeCoverage(record, { decisionId, reason })
245
+ } else if (source) {
246
+ if (record.covers.some((cover) => cover.store === 'background')) this.options.inboundJournal?.assertAvailable()
247
+ await source.suppressNoticeCoverage(record, { decisionId, reason })
248
+ }
249
+ }
250
+ if (source && record.covers.some((cover) => cover.store !== 'inventory'))
251
+ await source.withTargetLane(record.target, suppress)
252
+ else await suppress()
253
+ await this.outbox.suppress(record.deliveryId, outboxReason, decisionId)
254
+ }
255
+
256
+ async stop(): Promise<void> {
257
+ this.stopped = true
258
+ this.unsubscribe()
259
+ clearTimeout(this.timer)
260
+ this.timer = undefined
261
+ await Promise.all(this.lanes.values())
262
+ await this.outbox.flush()
263
+ }
264
+ }
@@ -0,0 +1,94 @@
1
+ import type { MatchableOrigin } from '../permissions/resolve'
2
+ import {
3
+ LIVE_TURN_ENDED_NOTICE_TEXT,
4
+ parseRecoveryRecord,
5
+ RECOVERY_NOTICE_TEXT,
6
+ recoveryDeliveryId,
7
+ } from './continuity-types'
8
+ import type { RecoveryNoticeCause, RecoveryRecord } from './continuity-types'
9
+ import { channelKeyId } from './types'
10
+ import type { ChannelKey } from './types'
11
+
12
+ const canonicalPrincipal = (principal: MatchableOrigin) =>
13
+ Object.entries(principal)
14
+ .filter(([, value]) => value !== undefined)
15
+ .sort(([left], [right]) => left.localeCompare(right))
16
+
17
+ /** Frozen principals compare by content; persisted key order is a serialization detail. */
18
+ export function sameRecoveryPrincipal(left: MatchableOrigin, right: MatchableOrigin): boolean {
19
+ return JSON.stringify(canonicalPrincipal(left)) === JSON.stringify(canonicalPrincipal(right))
20
+ }
21
+
22
+ /**
23
+ * One interruption notice may cover only sources sharing destination, authenticated account,
24
+ * frozen principal and captured effective parent (the `/stop` authority). Chat, text, turn
25
+ * timing, the current mapping and the current adapter account are never grouping evidence.
26
+ */
27
+ export function recoveryNoticePartitionKey(input: {
28
+ target: ChannelKey
29
+ accountIdentity: string
30
+ principal: MatchableOrigin
31
+ parentSessionId?: string
32
+ }): string {
33
+ return JSON.stringify([
34
+ channelKeyId(input.target),
35
+ input.accountIdentity,
36
+ canonicalPrincipal(input.principal),
37
+ input.parentSessionId ?? null,
38
+ ])
39
+ }
40
+
41
+ /**
42
+ * Freezes a transfer at preparation. `restart` (the default) is the RFC en/v1 boot-recovery
43
+ * notice, byte- and ID-identical to every record written before causes existed. Same-process
44
+ * abandonment passes `live-turn-ended`, which never asserts a restart.
45
+ */
46
+ export function createRecoveryNotice(
47
+ input: Pick<
48
+ RecoveryRecord,
49
+ | 'target'
50
+ | 'accountIdentity'
51
+ | 'accountIdentityConflict'
52
+ | 'principal'
53
+ | 'covers'
54
+ | 'recoveryGeneration'
55
+ | 'transferId'
56
+ > & { createdAt?: number; sourceParentSessionId?: string; cause?: RecoveryNoticeCause },
57
+ ): RecoveryRecord {
58
+ const source = {
59
+ target: input.target,
60
+ accountIdentity: input.accountIdentity,
61
+ ...(input.accountIdentityConflict !== undefined ? { accountIdentityConflict: input.accountIdentityConflict } : {}),
62
+ principal: input.principal,
63
+ covers: input.covers,
64
+ recoveryGeneration: input.recoveryGeneration,
65
+ transferId: input.transferId,
66
+ ...(input.sourceParentSessionId !== undefined ? { sourceParentSessionId: input.sourceParentSessionId } : {}),
67
+ }
68
+ const template =
69
+ input.cause === 'live-turn-ended'
70
+ ? {
71
+ schemaVersion: 2 as const,
72
+ purpose: 'interruption-notice' as const,
73
+ cause: 'live-turn-ended' as const,
74
+ templateVersion: 1 as const,
75
+ locale: 'en' as const,
76
+ text: LIVE_TURN_ENDED_NOTICE_TEXT,
77
+ }
78
+ : {
79
+ schemaVersion: 1 as const,
80
+ purpose: 'interruption-notice' as const,
81
+ templateVersion: 1 as const,
82
+ locale: 'en' as const,
83
+ text: RECOVERY_NOTICE_TEXT,
84
+ }
85
+ const record = {
86
+ ...source,
87
+ ...template,
88
+ createdAt: input.createdAt ?? Date.now(),
89
+ generation: 1,
90
+ state: 'pending' as const,
91
+ attempts: 0,
92
+ }
93
+ return parseRecoveryRecord({ ...record, deliveryId: recoveryDeliveryId(record) })
94
+ }