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
@@ -0,0 +1,141 @@
1
+ import { mkdir, readFile, rename, writeFile } from 'node:fs/promises'
2
+ import { dirname, join } from 'node:path'
3
+
4
+ import { z } from 'zod'
5
+
6
+ import { describeError } from '../../describe-error'
7
+ import { canonicalGithubRepo } from '../../github-repo'
8
+
9
+ const pendingReviewSchema = z.object({
10
+ repo: z.string().regex(/^[^/]+\/[^/]+$/),
11
+ prNumber: z.number().int().positive(),
12
+ prId: z.number().int().positive(),
13
+ kind: z.enum(['review', 'rereview']),
14
+ headSha: z.string().min(1),
15
+ admittedAt: z.number().finite().nonnegative(),
16
+ authorId: z.string().min(1),
17
+ authorName: z.string(),
18
+ authorIsBot: z.boolean(),
19
+ })
20
+
21
+ export type PendingReview = Readonly<z.infer<typeof pendingReviewSchema>>
22
+
23
+ export type PendingReviewStore = {
24
+ list: () => Promise<readonly PendingReview[]>
25
+ has: (repo: string, prNumber: number) => boolean
26
+ record: (entry: PendingReview) => Promise<void>
27
+ clear: (repo: string, prNumber: number, expected?: PendingReview) => Promise<void>
28
+ }
29
+
30
+ type Logger = { warn: (message: string) => void }
31
+
32
+ export function pendingReviewPath(agentDir: string): string {
33
+ return join(agentDir, 'channels', 'github-pending-reviews.json')
34
+ }
35
+
36
+ function key(repo: string, prNumber: number): string {
37
+ return `${canonicalGithubRepo(repo)}#${prNumber}`
38
+ }
39
+
40
+ // All instances share a lane. A detached old adapter must not overwrite the
41
+ // replacement's admissions from a stale snapshot.
42
+ const fileLanes = new Map<string, Promise<void>>()
43
+
44
+ function onFileLane<T>(path: string, task: () => Promise<T>): Promise<T> {
45
+ const result = (fileLanes.get(path) ?? Promise.resolve()).then(task)
46
+ const tail = result.then(
47
+ () => undefined,
48
+ () => undefined,
49
+ )
50
+ fileLanes.set(path, tail)
51
+ void tail.then(() => {
52
+ if (fileLanes.get(path) === tail) fileLanes.delete(path)
53
+ })
54
+ return result
55
+ }
56
+
57
+ export async function loadPendingReviewStore(agentDir: string, logger: Logger = console): Promise<PendingReviewStore> {
58
+ const path = pendingReviewPath(agentDir)
59
+ let entries = await onFileLane(path, () => readEntries(path, logger))
60
+ const latest = async (): Promise<Map<string, PendingReview>> => {
61
+ entries = await readEntries(path, logger)
62
+ return new Map(entries)
63
+ }
64
+ const persist = async (next: Map<string, PendingReview>): Promise<void> => {
65
+ await mkdir(dirname(path), { recursive: true })
66
+ await writeFile(`${path}.tmp`, `${JSON.stringify({ version: 1, entries: [...next.values()] }, null, 2)}\n`, 'utf8')
67
+ await rename(`${path}.tmp`, path)
68
+ entries = next
69
+ }
70
+ return {
71
+ list: () => onFileLane(path, async () => [...(await latest()).values()]),
72
+ has: (repo, prNumber) => entries.has(key(repo, prNumber)),
73
+ record: (entry) =>
74
+ onFileLane(path, async () => {
75
+ const next = await latest()
76
+ const id = key(entry.repo, entry.prNumber)
77
+ const previous = next.get(id)
78
+ if (previous !== undefined && previous.admittedAt > entry.admittedAt) return
79
+ // Several thread siblings can carry the same push. They share one PR
80
+ // obligation; keep its original admission time for completion checks.
81
+ if (
82
+ previous?.headSha === entry.headSha &&
83
+ previous.kind === entry.kind &&
84
+ previous.authorId === entry.authorId &&
85
+ previous.authorName === entry.authorName &&
86
+ previous.authorIsBot === entry.authorIsBot
87
+ )
88
+ return
89
+ next.set(id, entry)
90
+ await persist(next)
91
+ }),
92
+ clear: (repo, prNumber, expected) =>
93
+ onFileLane(path, async () => {
94
+ const next = await latest()
95
+ const id = key(repo, prNumber)
96
+ const current = next.get(id)
97
+ if (current === undefined) return
98
+ if (
99
+ expected !== undefined &&
100
+ (current.prId !== expected.prId ||
101
+ current.headSha !== expected.headSha ||
102
+ current.kind !== expected.kind ||
103
+ current.admittedAt !== expected.admittedAt ||
104
+ current.authorId !== expected.authorId ||
105
+ current.authorName !== expected.authorName ||
106
+ current.authorIsBot !== expected.authorIsBot)
107
+ )
108
+ return
109
+ next.delete(id)
110
+ await persist(next)
111
+ }),
112
+ }
113
+ }
114
+
115
+ async function readEntries(path: string, logger: Logger): Promise<Map<string, PendingReview>> {
116
+ const entries = new Map<string, PendingReview>()
117
+ let raw: string
118
+ try {
119
+ raw = await readFile(path, 'utf8')
120
+ } catch (error) {
121
+ if (error instanceof Error && 'code' in error && error.code === 'ENOENT') return entries
122
+ throw error
123
+ }
124
+ let parsed: unknown
125
+ try {
126
+ parsed = JSON.parse(raw)
127
+ } catch (error) {
128
+ logger.warn(`[github] pending review log corrupted: ${describeError(error)}; starting fresh`)
129
+ return entries
130
+ }
131
+ const envelope = z.object({ version: z.literal(1), entries: z.array(z.unknown()) }).safeParse(parsed)
132
+ if (!envelope.success) {
133
+ logger.warn('[github] pending review log has an unsupported format; starting fresh')
134
+ return entries
135
+ }
136
+ for (const value of envelope.data.entries) {
137
+ const entry = pendingReviewSchema.safeParse(value)
138
+ if (entry.success) entries.set(key(entry.data.repo, entry.data.prNumber), entry.data)
139
+ }
140
+ return entries
141
+ }
@@ -28,6 +28,7 @@ export function githubRequiredPermissionsNote(includeWebhookNote: boolean): stri
28
28
  return [
29
29
  'Required permissions: Issues read/write, Pull requests read/write, Discussions read/write (if used),',
30
30
  `Actions read/write, Metadata read, and ${webhooks}`,
31
+ 'For the typeclaw/review PR check: Checks read/write (GitHub App) or Commit statuses read/write (PAT).',
31
32
  ].join('\n')
32
33
  }
33
34
 
@@ -4,6 +4,9 @@ import type {
4
4
  ReactionErrorCode,
5
5
  ReactionRef,
6
6
  ReactionResult,
7
+ PrepareOwnReactionCallback,
8
+ RemoveOwnReactionCallback,
9
+ RemoveOwnReactionResult,
7
10
  } from '@/channels/types'
8
11
 
9
12
  import { describeError } from '../../describe-error'
@@ -275,3 +278,100 @@ function classifyStatus(status: number): ReactionErrorCode {
275
278
  if (status === 429) return 'rate-limited'
276
279
  return 'transient'
277
280
  }
281
+
282
+ export function createGithubOwnReactionCallbacks(deps: {
283
+ token: (context?: GithubAuthContext) => Promise<string>
284
+ getSelf: () => Promise<{ id: number }>
285
+ authType: GithubAuthType
286
+ fetchImpl?: typeof fetch
287
+ }): { prepare: PrepareOwnReactionCallback; remove: RemoveOwnReactionCallback } {
288
+ const fetchImpl = deps.fetchImpl ?? fetch
289
+ const prepare: PrepareOwnReactionCallback = async (req) => {
290
+ const target = decodeGithubReactionRef(req.reactionRef)
291
+ const emoji = REACTION_CONTENT[req.emoji.replace(/^:|:$/g, '')]
292
+ if (req.adapter !== 'github' || target === null || emoji === undefined) return null
293
+ const self = await deps.getSelf()
294
+ if (!Number.isSafeInteger(self.id) || self.id <= 0) return null
295
+ return { accountIdentity: String(self.id), target: encodeGithubReactionRef(target), emoji }
296
+ }
297
+ const remove: RemoveOwnReactionCallback = async (req) => {
298
+ const target = decodeGithubReactionRef(req.target)
299
+ const emoji = REACTION_CONTENT[req.emoji.replace(/^:|:$/g, '')]
300
+ if (req.adapter !== 'github' || target === null || emoji === undefined)
301
+ return { ok: false, code: 'unsupported', error: 'invalid GitHub reaction target or emoji' }
302
+ try {
303
+ const self = await deps.getSelf()
304
+ if (!Number.isSafeInteger(self.id) || self.id <= 0 || String(self.id) !== req.expectedAccountIdentity)
305
+ return { ok: false, code: 'identity', error: 'authenticated GitHub actor changed or unavailable' }
306
+ const token = await deps.token({ repoSlug: `${target.owner}/${target.repo}` })
307
+ const endpoint = reactionEndpoint(target)
308
+ let next: string | null = `${endpoint}?per_page=100`
309
+ const visited = new Set<string>()
310
+ const ownIds = new Set<number>()
311
+ // Finish enumeration before deleting: a failed later page must leave every reaction intact.
312
+ while (next !== null) {
313
+ if (visited.has(next)) return { ok: false, code: 'transient', error: 'cyclic GitHub reaction pagination' }
314
+ visited.add(next)
315
+ const response: Response = await fetchImpl(next, { headers: githubJsonHeaders(token) })
316
+ if (response.status === 404)
317
+ return { ok: false, code: 'permission', error: 'GitHub reaction target inaccessible' }
318
+ if (!response.ok) return await ownReactionHttpError(response)
319
+ const rows: unknown = await response.json()
320
+ if (!Array.isArray(rows)) return { ok: false, code: 'transient', error: 'invalid GitHub reaction page' }
321
+ for (const row of rows) {
322
+ if (typeof row !== 'object' || row === null)
323
+ return { ok: false, code: 'transient', error: 'invalid GitHub reaction row' }
324
+ const reaction = row as { id?: unknown; content?: unknown; user?: { id?: unknown } | null }
325
+ if (reaction.content === emoji && reaction.user?.id === self.id) {
326
+ if (typeof reaction.id !== 'number' || !Number.isSafeInteger(reaction.id) || reaction.id <= 0)
327
+ return { ok: false, code: 'transient', error: 'invalid GitHub reaction id' }
328
+ ownIds.add(reaction.id)
329
+ }
330
+ }
331
+ const link: string | null = response.headers.get('link')
332
+ const match: RegExpMatchArray | null | undefined = link
333
+ ?.split(',')
334
+ .map((part) => part.trim())
335
+ .find((part) => /;\s*rel="next"/.test(part))
336
+ ?.match(/^<([^>]+)>/)
337
+ next = match?.[1] ?? null
338
+ if (next !== null) {
339
+ const url = new URL(next)
340
+ if (url.origin !== new URL(GITHUB_API_BASE).origin || url.pathname !== new URL(endpoint).pathname)
341
+ return { ok: false, code: 'transient', error: 'invalid GitHub reaction pagination destination' }
342
+ }
343
+ }
344
+ for (const id of ownIds) {
345
+ const response = await fetchImpl(`${endpoint}/${id}`, { method: 'DELETE', headers: githubJsonHeaders(token) })
346
+ if (response.status !== 204 && response.status !== 404) return await ownReactionHttpError(response)
347
+ }
348
+ return { ok: true }
349
+ } catch (error) {
350
+ return { ok: false, code: 'transient', error: describeError(error) }
351
+ }
352
+ }
353
+ return { prepare, remove }
354
+ }
355
+
356
+ async function ownReactionHttpError(response: Response): Promise<RemoveOwnReactionResult> {
357
+ const text = await response.text().catch(() => '')
358
+ const rateLimited =
359
+ response.status === 429 ||
360
+ (response.status === 403 &&
361
+ (response.headers.get('x-ratelimit-remaining') === '0' ||
362
+ response.headers.has('retry-after') ||
363
+ /rate limit/i.test(text)))
364
+ const retry = Number(response.headers.get('retry-after'))
365
+ return {
366
+ ok: false,
367
+ code: rateLimited
368
+ ? 'rate-limit'
369
+ : response.status === 401 || response.status === 403 || response.status === 404
370
+ ? 'permission'
371
+ : 'transient',
372
+ error: `GitHub API ${response.status}: ${text}`,
373
+ ...(rateLimited && response.headers.has('retry-after') && Number.isFinite(retry) && retry >= 0
374
+ ? { retryAfter: retry * 1000 }
375
+ : {}),
376
+ }
377
+ }
@@ -1,3 +1,4 @@
1
+ import { randomUUID } from 'node:crypto'
1
2
  import { mkdir, readFile, rename, writeFile } from 'node:fs/promises'
2
3
  import { dirname, join } from 'node:path'
3
4
 
@@ -26,6 +27,11 @@ import { canonicalGithubRepo } from '../../github-repo'
26
27
  // was LAUNCHED (not when a review completed): posted-review suppression stays
27
28
  // the authoritative "done" signal in reconcile-open-prs.ts; this store only
28
29
  // bounds retry frequency.
30
+ //
31
+ // A launch marker is a reservation owned by one replay attempt (`replayId`).
32
+ // The attempt keeps it once the router durably admits the replay, and rolls
33
+ // back only its own reservation when the replay was never admitted, so a later
34
+ // pass retries the PR instead of losing it for a whole cooldown window.
29
35
 
30
36
  const FILE_VERSION = 1
31
37
 
@@ -43,6 +49,25 @@ export type ReconcileMarker = {
43
49
  repo: string
44
50
  prId: number
45
51
  lastReplayAt: number
52
+ // The attempt that owns this launch reservation. Markers written before
53
+ // reservations had owners omit it: they keep their cooldown meaning, and no
54
+ // attempt's rollback can remove them.
55
+ replayId?: string
56
+ // When this PR was first replayed in its current owed streak; carried across
57
+ // re-reservations so `owesReplay` eligibility expires instead of renewing daily.
58
+ firstReplayAt?: number
59
+ }
60
+
61
+ export type ReconcileReplayReservation = {
62
+ readonly replayId: string
63
+ }
64
+
65
+ export type ReconcileReplayOptions = {
66
+ now: number
67
+ cooldownMs: number
68
+ // The reconcile pass runs detached from its adapter lifecycle. Once this
69
+ // flips, the replay this reservation would guard is never dispatched.
70
+ isCancelled?: () => boolean
46
71
  }
47
72
 
48
73
  type FileV1 = {
@@ -71,30 +96,85 @@ function markerKey(repo: string, prId: number): string {
71
96
  }
72
97
 
73
98
  export type ReconcileCooldownStore = {
99
+ // Snapshot as of this instance's most recent read or write of the file. It
100
+ // can be stale across store instances, so it must not decide a launch; only
101
+ // markReplayed's serialized check against the latest file does.
74
102
  isCoolingDown: (repo: string, prId: number, now: number, cooldownMs: number) => boolean
75
- // Flush BEFORE routing the synthetic inbound: a crash between marking and
76
- // session creation must not re-trigger a replay on the next restart.
77
- markReplayed: (repo: string, prId: number, now: number) => Promise<void>
103
+ // Whether reconcile first replayed this PR less than MARKER_RETENTION_MS ago,
104
+ // i.e. it still owes the PR an unfinished review regardless of the last-alive
105
+ // creation bound. Measured from the first replay, so retries are bounded.
106
+ owesReplay: (repo: string, prId: number, now: number) => boolean
107
+ // Persists a launch reservation BEFORE the synthetic inbound is routed: a
108
+ // crash between reserving and session creation must not re-trigger a replay
109
+ // on the next restart. Resolves null without launching when the latest
110
+ // persisted marker is still cooling down (another attempt holds it), or when
111
+ // `isCancelled` flipped — a reservation written before the cancellation was
112
+ // observed is rolled back inside the same serialized write. Rejects when the
113
+ // reservation could not be persisted; the caller must not route then.
114
+ markReplayed: (
115
+ repo: string,
116
+ prId: number,
117
+ options: ReconcileReplayOptions,
118
+ ) => Promise<ReconcileReplayReservation | null>
119
+ // Releases a reservation whose replay was not durably admitted. Removes the
120
+ // marker only while it is still owned by `replayId`, so an older attempt
121
+ // settling late never erases a newer attempt's reservation. Rejects when the
122
+ // release could not be persisted: the cooldown then still stands.
123
+ rollbackReplay: (repo: string, prId: number, replayId: string) => Promise<void>
124
+ // Unconditionally forgets the PR's marker, whichever attempt owns it.
78
125
  clear: (repo: string, prId: number) => Promise<void>
79
126
  prune: (repo: string, openPrIds: ReadonlySet<number>, now: number) => Promise<void>
80
127
  }
81
128
 
129
+ // One mutation lane per cooldown file, shared by every store instance in this
130
+ // process. A stopped adapter's detached pass and its replacement hold separate
131
+ // instances of the same file; each mutation re-reads the file inside the lane
132
+ // and applies only its own change, so no instance rewrites the file from a
133
+ // stale snapshot, erases another attempt's reservation, or races another write
134
+ // on the shared tmp path. Lane tasks do file I/O only — never await a router
135
+ // receipt — so a replacement store load queued behind them waits for writes,
136
+ // not for pending routing.
137
+ const fileLanes = new Map<string, Promise<void>>()
138
+
139
+ function onFileLane<T>(path: string, task: () => Promise<T>): Promise<T> {
140
+ const result = (fileLanes.get(path) ?? Promise.resolve()).then(task)
141
+ const tail = result.then(
142
+ () => undefined,
143
+ () => undefined,
144
+ )
145
+ fileLanes.set(path, tail)
146
+ void tail.then(() => {
147
+ if (fileLanes.get(path) === tail) fileLanes.delete(path)
148
+ })
149
+ return result
150
+ }
151
+
82
152
  export async function loadReconcileCooldownStore(
83
153
  agentDir: string,
84
154
  logger: ReconcileCooldownLogger = consoleLogger,
85
155
  ): Promise<ReconcileCooldownStore> {
86
156
  const path = reconcileCooldownPath(agentDir)
87
- const markers = new Map<string, ReconcileMarker>()
88
- for (const marker of await readMarkers(path, logger)) {
89
- markers.set(markerKey(marker.repo, marker.prId), marker)
90
- }
157
+ let markers = await onFileLane(path, async () => {
158
+ try {
159
+ return await readMarkers(path, logger)
160
+ } catch (err) {
161
+ logger.error(`[github] ${path} unreadable: ${describeError(err)}; starting fresh`)
162
+ return new Map<string, ReconcileMarker>()
163
+ }
164
+ })
91
165
 
92
- const flush = async (): Promise<void> => {
93
- const payload: FileV1 = { version: FILE_VERSION, markers: Array.from(markers.values()) }
94
- await mkdir(dirname(path), { recursive: true })
95
- const tmp = `${path}.tmp`
96
- await writeFile(tmp, `${JSON.stringify(payload, null, 2)}\n`, 'utf8')
97
- await rename(tmp, path)
166
+ // Lane-only helpers. `latest` refreshes this instance's view from disk and
167
+ // hands back a working copy; `persist` publishes the copy once it is on disk.
168
+ // A mutation that fails before the rename leaves the file and view unchanged.
169
+ // Markers a still-unsettled reservation replaced, keyed by its replayId.
170
+ const supersededMarkers = new Map<string, ReconcileMarker>()
171
+ const latest = async (): Promise<Map<string, ReconcileMarker>> => {
172
+ markers = await readMarkers(path, logger)
173
+ return new Map(markers)
174
+ }
175
+ const persist = async (next: Map<string, ReconcileMarker>): Promise<void> => {
176
+ await writeMarkers(path, next)
177
+ markers = next
98
178
  }
99
179
 
100
180
  return {
@@ -103,88 +183,138 @@ export async function loadReconcileCooldownStore(
103
183
  if (marker === undefined) return false
104
184
  return now - marker.lastReplayAt < cooldownMs
105
185
  },
106
- // Roll the in-memory marker back and rethrow if the disk write fails, so the
107
- // caller skips routing rather than replaying a PR with no durable record —
108
- // otherwise a restart would replay it immediately, defeating the cooldown.
109
- async markReplayed(repo, prId, now): Promise<void> {
110
- const key = markerKey(repo, prId)
111
- const previous = markers.get(key)
112
- markers.set(key, { repo, prId, lastReplayAt: now })
113
- try {
114
- await flush()
115
- } catch (err) {
116
- if (previous === undefined) markers.delete(key)
117
- else markers.set(key, previous)
118
- throw err
119
- }
120
- },
121
- async clear(repo, prId): Promise<void> {
122
- const key = markerKey(repo, prId)
123
- const previous = markers.get(key)
124
- if (previous === undefined) return
125
- markers.delete(key)
126
- try {
127
- await flush()
128
- } catch (err) {
129
- markers.set(key, previous)
130
- throw err
131
- }
186
+ owesReplay(repo, prId, now): boolean {
187
+ const marker = markers.get(markerKey(repo, prId))
188
+ if (marker === undefined) return false
189
+ return now - (marker.firstReplayAt ?? marker.lastReplayAt) < MARKER_RETENTION_MS
132
190
  },
133
- async prune(repo, openPrIds, now): Promise<void> {
134
- let changed = false
135
- for (const [key, marker] of markers) {
136
- const stale = now - marker.lastReplayAt >= MARKER_RETENTION_MS
137
- const closed = marker.repo === repo && !openPrIds.has(marker.prId)
138
- if (stale || closed) {
139
- markers.delete(key)
140
- changed = true
191
+ markReplayed(repo, prId, { now, cooldownMs, isCancelled }): Promise<ReconcileReplayReservation | null> {
192
+ return onFileLane(path, async () => {
193
+ const next = await latest()
194
+ if (isCancelled?.() === true) return null
195
+ const key = markerKey(repo, prId)
196
+ const previous = next.get(key)
197
+ if (previous !== undefined && now - previous.lastReplayAt < cooldownMs) return null
198
+ const replayId = randomUUID()
199
+ const firstReplayAt = previous !== undefined ? (previous.firstReplayAt ?? previous.lastReplayAt) : now
200
+ next.set(key, { repo, prId, lastReplayAt: now, replayId, firstReplayAt })
201
+ await persist(next)
202
+ if (isCancelled?.() !== true) {
203
+ if (previous !== undefined) supersededMarkers.set(replayId, previous)
204
+ return { replayId }
141
205
  }
142
- }
143
- if (changed) {
206
+ const restored = new Map(next)
207
+ if (previous === undefined) restored.delete(key)
208
+ else restored.set(key, previous)
144
209
  try {
145
- await flush()
210
+ await persist(restored)
146
211
  } catch (err) {
147
- logger.error(`[github] failed to persist reconcile cooldown: ${describeError(err)}`)
212
+ throw new Error(`cancelled replay reservation was not rolled back: ${describeError(err)}`, { cause: err })
148
213
  }
214
+ return null
215
+ })
216
+ },
217
+ rollbackReplay(repo, prId, replayId): Promise<void> {
218
+ return onFileLane(path, async () => {
219
+ const next = await latest()
220
+ const key = markerKey(repo, prId)
221
+ const superseded = supersededMarkers.get(replayId)
222
+ supersededMarkers.delete(replayId)
223
+ if (next.get(key)?.replayId !== replayId) return
224
+ // Restore the marker this attempt replaced: it may be the PR's only claim
225
+ // to a retry once the last-alive bound has moved past its creation.
226
+ if (superseded !== undefined) next.set(key, superseded)
227
+ else next.delete(key)
228
+ await persist(next)
229
+ })
230
+ },
231
+ clear(repo, prId): Promise<void> {
232
+ return onFileLane(path, async () => {
233
+ const next = await latest()
234
+ if (!next.delete(markerKey(repo, prId))) return
235
+ await persist(next)
236
+ })
237
+ },
238
+ async prune(repo, openPrIds, now): Promise<void> {
239
+ try {
240
+ await onFileLane(path, async () => {
241
+ const next = await latest()
242
+ let changed = false
243
+ for (const [key, marker] of next) {
244
+ const stale = now - marker.lastReplayAt >= MARKER_RETENTION_MS
245
+ const closed = marker.repo === repo && !openPrIds.has(marker.prId)
246
+ if (stale || closed) {
247
+ next.delete(key)
248
+ changed = true
249
+ }
250
+ }
251
+ if (changed) await persist(next)
252
+ })
253
+ } catch (err) {
254
+ logger.error(`[github] failed to persist reconcile cooldown: ${describeError(err)}`)
149
255
  }
150
256
  },
151
257
  }
152
258
  }
153
259
 
154
- async function readMarkers(path: string, logger: ReconcileCooldownLogger): Promise<ReconcileMarker[]> {
260
+ async function writeMarkers(path: string, markers: ReadonlyMap<string, ReconcileMarker>): Promise<void> {
261
+ const payload: FileV1 = { version: FILE_VERSION, markers: Array.from(markers.values()) }
262
+ await mkdir(dirname(path), { recursive: true })
263
+ const tmp = `${path}.tmp`
264
+ await writeFile(tmp, `${JSON.stringify(payload, null, 2)}\n`, 'utf8')
265
+ await rename(tmp, path)
266
+ }
267
+
268
+ // A missing file is an empty store and unparseable content is replaced on the
269
+ // next write, but any other read failure throws: a mutation that treated an
270
+ // unreadable file as empty would overwrite every other PR's marker.
271
+ async function readMarkers(path: string, logger: ReconcileCooldownLogger): Promise<Map<string, ReconcileMarker>> {
272
+ const markers = new Map<string, ReconcileMarker>()
155
273
  let raw: string
156
274
  try {
157
275
  raw = await readFile(path, 'utf8')
158
- } catch {
159
- return []
276
+ } catch (err) {
277
+ if (err instanceof Error && 'code' in err && err.code === 'ENOENT') return markers
278
+ throw err
160
279
  }
161
280
  let parsed: unknown
162
281
  try {
163
282
  parsed = JSON.parse(raw)
164
283
  } catch (err) {
165
284
  logger.error(`[github] ${path} corrupted: ${describeError(err)}; starting fresh`)
166
- return []
285
+ return markers
167
286
  }
168
287
  if (!isObject(parsed)) {
169
288
  logger.warn(`[github] ${path} not an object; ignored`)
170
- return []
289
+ return markers
290
+ }
291
+ if (parsed.version !== FILE_VERSION) {
292
+ logger.warn(`[github] ${path} version ${String(parsed.version)} not supported (expected ${FILE_VERSION}); ignored`)
293
+ return markers
171
294
  }
172
- const version = (parsed as { version?: unknown }).version
173
- if (version !== FILE_VERSION) {
174
- logger.warn(`[github] ${path} version ${String(version)} not supported (expected ${FILE_VERSION}); ignored`)
175
- return []
295
+ if (!Array.isArray(parsed.markers)) return markers
296
+ for (const entry of parsed.markers) {
297
+ const marker = parseMarker(entry)
298
+ if (marker !== null) markers.set(markerKey(marker.repo, marker.prId), marker)
176
299
  }
177
- const file = parsed as FileV1
178
- if (!Array.isArray(file.markers)) return []
179
- return file.markers.filter(isValidMarker)
300
+ return markers
180
301
  }
181
302
 
182
303
  function isObject(v: unknown): v is Record<string, unknown> {
183
304
  return typeof v === 'object' && v !== null && !Array.isArray(v)
184
305
  }
185
306
 
186
- function isValidMarker(v: unknown): v is ReconcileMarker {
187
- if (!isObject(v)) return false
188
- const r = v as Record<string, unknown>
189
- return typeof r.repo === 'string' && typeof r.prId === 'number' && typeof r.lastReplayAt === 'number'
307
+ function parseMarker(v: unknown): ReconcileMarker | null {
308
+ if (!isObject(v)) return null
309
+ const { repo, prId, lastReplayAt, replayId, firstReplayAt } = v
310
+ if (typeof repo !== 'string' || typeof prId !== 'number' || typeof lastReplayAt !== 'number') return null
311
+ if (replayId !== undefined && typeof replayId !== 'string') return null
312
+ if (firstReplayAt !== undefined && typeof firstReplayAt !== 'number') return null
313
+ return {
314
+ repo,
315
+ prId,
316
+ lastReplayAt,
317
+ ...(replayId !== undefined ? { replayId } : {}),
318
+ ...(firstReplayAt !== undefined ? { firstReplayAt } : {}),
319
+ }
190
320
  }