typeclaw 0.45.1 → 0.46.1

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 (163) hide show
  1. package/README.md +1 -1
  2. package/package.json +3 -2
  3. package/src/agent/git-nudge.ts +2 -1
  4. package/src/agent/index.ts +44 -30
  5. package/src/agent/live-subagents.ts +18 -0
  6. package/src/agent/multimodal/index.ts +1 -1
  7. package/src/agent/multimodal/look-at.ts +78 -44
  8. package/src/agent/multimodal/looker.ts +161 -39
  9. package/src/agent/network/response-body.ts +26 -0
  10. package/src/agent/network/safe-http.ts +207 -0
  11. package/src/agent/plugin-tools.ts +377 -157
  12. package/src/agent/provider-error.ts +52 -1
  13. package/src/agent/restart/index.ts +61 -40
  14. package/src/agent/restart-handoff/index.ts +73 -4
  15. package/src/agent/reviewer-bash-policy.ts +42 -1
  16. package/src/agent/session-origin.ts +2 -0
  17. package/src/agent/subagent-drain.ts +117 -7
  18. package/src/agent/subagents.ts +49 -16
  19. package/src/agent/throttle-circuit.ts +25 -5
  20. package/src/agent/tool-error-remediation.ts +72 -0
  21. package/src/agent/tool-file-safety.ts +1310 -0
  22. package/src/agent/tools/channel-fetch-attachment.ts +10 -3
  23. package/src/agent/tools/ddg.ts +16 -2
  24. package/src/agent/tools/post-github-review.ts +199 -0
  25. package/src/agent/tools/spawn-subagent.ts +21 -18
  26. package/src/agent/tools/webfetch/fetch.ts +163 -183
  27. package/src/agent/tools/webfetch/tool.ts +2 -3
  28. package/src/agent/tools/websearch.ts +23 -2
  29. package/src/agent/tools-without-local-file-operands.ts +30 -0
  30. package/src/agent/turn-runner.ts +86 -6
  31. package/src/bundled-plugins/backup/README.md +23 -10
  32. package/src/bundled-plugins/backup/git-auth.ts +6 -4
  33. package/src/bundled-plugins/backup/index.ts +85 -44
  34. package/src/bundled-plugins/backup/runner.ts +85 -1
  35. package/src/bundled-plugins/doc-render/render.ts +93 -12
  36. package/src/bundled-plugins/doc-render/skills/typeclaw-render-pdf/SKILL.md +13 -13
  37. package/src/bundled-plugins/github-cli-auth/effective-approval.ts +16 -6
  38. package/src/bundled-plugins/github-cli-auth/gh-command.ts +555 -15
  39. package/src/bundled-plugins/github-cli-auth/git-askpass.ts +74 -26
  40. package/src/bundled-plugins/github-cli-auth/git-command.ts +224 -36
  41. package/src/bundled-plugins/github-cli-auth/graphql-auth-nudge.ts +9 -9
  42. package/src/bundled-plugins/github-cli-auth/index.ts +207 -132
  43. package/src/bundled-plugins/github-cli-auth/review-checkout.ts +138 -0
  44. package/src/bundled-plugins/github-cli-auth/token-class.ts +4 -6
  45. package/src/bundled-plugins/guard/policies/uncommitted-changes.ts +2 -1
  46. package/src/bundled-plugins/memory/README.md +32 -11
  47. package/src/bundled-plugins/memory/append-tool.ts +15 -8
  48. package/src/bundled-plugins/memory/citations.ts +22 -9
  49. package/src/bundled-plugins/memory/dreaming.ts +13 -8
  50. package/src/bundled-plugins/memory/find-entry-tool.ts +4 -0
  51. package/src/bundled-plugins/memory/index.ts +0 -4
  52. package/src/bundled-plugins/memory/load-memory.ts +8 -3
  53. package/src/bundled-plugins/memory/provenance-index.ts +717 -0
  54. package/src/bundled-plugins/memory/provenance-sanitize.ts +40 -0
  55. package/src/bundled-plugins/memory/references/store-reference-tool.ts +4 -0
  56. package/src/bundled-plugins/memory/search-tool.ts +163 -60
  57. package/src/bundled-plugins/memory/stream-events.ts +2 -0
  58. package/src/bundled-plugins/memory/vector/embed-threads.ts +36 -0
  59. package/src/bundled-plugins/memory/vector/embedder.ts +19 -1
  60. package/src/bundled-plugins/memory/vector/hybrid.ts +126 -13
  61. package/src/bundled-plugins/researcher/write-report.ts +8 -5
  62. package/src/bundled-plugins/reviewer/index.ts +2 -2
  63. package/src/bundled-plugins/reviewer/reviewer.ts +10 -3
  64. package/src/bundled-plugins/reviewer/skills/code-review.ts +19 -9
  65. package/src/bundled-plugins/scout/scout.ts +8 -0
  66. package/src/bundled-plugins/security/index.ts +4 -4
  67. package/src/bundled-plugins/security/policies/outbound-secret-scan.ts +1 -0
  68. package/src/bundled-plugins/security/policies/private-surface-read.ts +787 -36
  69. package/src/bundled-plugins/security/policies/secret-exfil-read.ts +1 -0
  70. package/src/bundled-plugins/security/policies/ssrf.ts +147 -42
  71. package/src/channels/adapters/discord-bot-channel-resolver.ts +26 -14
  72. package/src/channels/adapters/discord-bot-thread-room.ts +44 -12
  73. package/src/channels/adapters/discord-bot.ts +66 -6
  74. package/src/channels/adapters/discord-channel-resolver.ts +91 -23
  75. package/src/channels/adapters/discord-id.ts +4 -0
  76. package/src/channels/adapters/discord-resolver-cache.ts +41 -0
  77. package/src/channels/adapters/discord.ts +57 -7
  78. package/src/channels/adapters/github/auth-app.ts +41 -12
  79. package/src/channels/adapters/github/inbound.ts +11 -0
  80. package/src/channels/adapters/github/index.ts +71 -65
  81. package/src/channels/adapters/github/reconcile-cooldown-store.ts +178 -0
  82. package/src/channels/adapters/github/reconcile-open-prs.ts +31 -0
  83. package/src/channels/adapters/github/review-submitter.ts +302 -0
  84. package/src/channels/adapters/kakaotalk-channel-resolver.ts +5 -3
  85. package/src/channels/adapters/kakaotalk-fetch-attachment.ts +8 -4
  86. package/src/channels/adapters/kakaotalk-typing.ts +17 -15
  87. package/src/channels/adapters/slack-attachment-download.ts +71 -0
  88. package/src/channels/adapters/slack-bot-edit.ts +85 -20
  89. package/src/channels/adapters/slack-bot.ts +26 -10
  90. package/src/channels/adapters/slack-classify.ts +21 -2
  91. package/src/channels/adapters/slack-format.ts +245 -0
  92. package/src/channels/adapters/slack.ts +59 -7
  93. package/src/channels/adapters/telegram-bot.ts +18 -5
  94. package/src/channels/adapters/webex-bot.ts +8 -3
  95. package/src/channels/adapters/webex.ts +8 -3
  96. package/src/channels/fetch-attachment.ts +43 -0
  97. package/src/{bundled-plugins/github-cli-auth/approve-idempotency.ts → channels/github-review-verdict-coordinator.ts} +25 -1
  98. package/src/channels/github-token-bridge.ts +12 -6
  99. package/src/channels/manager.ts +9 -0
  100. package/src/channels/router.ts +248 -6
  101. package/src/channels/types.ts +28 -1
  102. package/src/cli/channel.ts +1 -1
  103. package/src/cli/init.ts +1 -1
  104. package/src/cli/model.ts +57 -7
  105. package/src/compose/stop.ts +17 -5
  106. package/src/config/config.ts +6 -6
  107. package/src/config/models-mutation.ts +13 -1
  108. package/src/config/providers.ts +176 -0
  109. package/src/container/docker-app.ts +42 -13
  110. package/src/container/start.ts +62 -10
  111. package/src/cron/bridge.ts +9 -2
  112. package/src/doctor/checks.ts +8 -3
  113. package/src/doctor/commit.ts +2 -1
  114. package/src/doctor/file-ownership.ts +52 -0
  115. package/src/dreams/git.ts +2 -1
  116. package/src/git/bound-gc-config.ts +82 -0
  117. package/src/git/hookless.ts +5 -0
  118. package/src/git/reconcile-ignored.ts +18 -5
  119. package/src/git/system-commit.ts +12 -6
  120. package/src/hostd/spawn.ts +133 -47
  121. package/src/init/dockerfile.ts +99 -5
  122. package/src/init/index.ts +17 -5
  123. package/src/init/models-dev.ts +4 -0
  124. package/src/init/validate-api-key.ts +2 -0
  125. package/src/inspect/replay.ts +21 -9
  126. package/src/inspect/session-list.ts +71 -33
  127. package/src/mcp/tools.ts +17 -3
  128. package/src/network/internal-destinations.ts +267 -0
  129. package/src/permissions/builtins.ts +3 -1
  130. package/src/plugin/context.ts +2 -0
  131. package/src/plugin/index.ts +1 -0
  132. package/src/plugin/manager.ts +4 -0
  133. package/src/plugin/types.ts +22 -0
  134. package/src/run/index.ts +40 -0
  135. package/src/run/llm-fetch-observer.ts +41 -4
  136. package/src/sandbox/build.ts +37 -15
  137. package/src/sandbox/canonical-secrets.ts +18 -0
  138. package/src/sandbox/env-exposure.ts +83 -0
  139. package/src/sandbox/errors.ts +13 -6
  140. package/src/sandbox/hidden-paths.ts +102 -44
  141. package/src/sandbox/index.ts +22 -4
  142. package/src/sandbox/package-install.ts +3 -27
  143. package/src/sandbox/policy.ts +16 -28
  144. package/src/sandbox/privileged-runtime.ts +256 -0
  145. package/src/sandbox/session-tmp.ts +8 -2
  146. package/src/sandbox/writable-zones.ts +204 -140
  147. package/src/secrets/index.ts +8 -0
  148. package/src/secrets/refresh-provider-oauth.ts +128 -0
  149. package/src/server/command-runner.ts +48 -4
  150. package/src/server/index.ts +4 -0
  151. package/src/skills/typeclaw-channel-github/SKILL.md +49 -56
  152. package/src/skills/typeclaw-claude-code/SKILL.md +24 -60
  153. package/src/skills/typeclaw-claude-code/references/auth-flow.md +17 -158
  154. package/src/skills/typeclaw-codex-cli/SKILL.md +19 -49
  155. package/src/skills/typeclaw-codex-cli/references/auth-flow.md +17 -154
  156. package/src/skills/typeclaw-config/SKILL.md +27 -11
  157. package/src/skills/typeclaw-config/references/recommended-mounts.md +24 -24
  158. package/src/skills/typeclaw-github-contributing/SKILL.md +23 -26
  159. package/src/skills/typeclaw-memory/SKILL.md +9 -3
  160. package/src/skills/typeclaw-permissions/SKILL.md +36 -19
  161. package/src/skills/typeclaw-plugins/SKILL.md +37 -0
  162. package/src/usage/scan.ts +11 -2
  163. package/typeclaw.schema.json +25 -0
@@ -21,9 +21,11 @@ import {
21
21
  parseListHooksPermissionStatus,
22
22
  } from './permission-guidance'
23
23
  import { createGithubReactionCallback, createGithubRemoveReactionCallback } from './reactions'
24
+ import { loadReconcileCooldownStore, type ReconcileCooldownStore } from './reconcile-cooldown-store'
24
25
  import { reconcileOpenPrs } from './reconcile-open-prs'
25
26
  import { createRecoveredGuidLog, recoverFailedGithubDeliveries } from './recover-failed-deliveries'
26
27
  import { createGithubReviewStateResolver } from './review-state'
28
+ import { createGithubReviewSubmitter } from './review-submitter'
27
29
  import { createGithubReviewThreadResolver } from './review-thread-resolver'
28
30
  import { createTeamMembershipChecker } from './team-membership'
29
31
  import { deregisterGithubWebhooks, registerGithubWebhooks, type WebhookRegistrationResult } from './webhook-register'
@@ -60,7 +62,7 @@ export type GithubAdapterOptions = {
60
62
  // Test-only: replaces the wall-clock sleep used for the registration
61
63
  // delay above. Production leaves it undefined and we use `setTimeout`.
62
64
  sleep?: (ms: number) => Promise<void>
63
- // How often to proactively refresh the token and update GH_TOKEN
65
+ // How often to proactively refresh a PAT and update GH_TOKEN
64
66
  // when the adapter is running but has not made an outbound API call
65
67
  // recently. Zero disables the background refresh entirely.
66
68
  // Default: 30 minutes.
@@ -72,10 +74,15 @@ export type GithubAdapterOptions = {
72
74
  // inbound delivery failed (and that GitHub never redelivered), re-injecting
73
75
  // them through the live event path. Zero disables the sweep. Default: 5 min.
74
76
  deliveryRecoveryIntervalMs?: number
77
+ // How often to re-run the open-PR reconcile pass after the initial start()
78
+ // pass, so a genuinely-missed PR recovers without another restart. Per-PR
79
+ // replay is bounded by the durable cooldown store. Zero disables the periodic
80
+ // re-run (the start() pass still fires). Default: 30 min.
81
+ reconcileIntervalMs?: number
75
82
  // Write-side of the GithubTokenBridge. On App-auth start the adapter
76
- // registers a per-repo minter here so plugin hooks can resolve a token for
77
- // ad-hoc `gh` commands; it unregisters on stop and on start rollback. PAT
78
- // auth does not register (the seeded GH_TOKEN already covers every repo a
83
+ // registers a per-repo minter here so runtime consumers can resolve a token
84
+ // for validated `gh` commands and backup; it unregisters on stop. PAT auth
85
+ // does not register (the seeded GH_TOKEN already covers every repo a
79
86
  // classic PAT can reach, and a fine-grained PAT cannot be re-minted per repo).
80
87
  githubTokenBridge?: GithubTokenBridge
81
88
  }
@@ -100,6 +107,10 @@ const DEFAULT_DELIVERY_RECOVERY_INTERVAL_MS = 5 * 60 * 1000
100
107
  const DELIVERY_RECOVERY_LOOKBACK_MS = 70 * 60 * 60 * 1000
101
108
  // Bounds an LLM-session storm if a bad tunnel window drops a large burst.
102
109
  const MAX_RECOVERED_PER_SWEEP = 50
110
+ // The reconcile pass reruns on this cadence so a genuinely-missed `opened`
111
+ // recovers without waiting for another restart. Per-PR replay is bounded by the
112
+ // durable cooldown store, so a tick is cheap when nothing new needs review.
113
+ const DEFAULT_RECONCILE_INTERVAL_MS = 30 * 60 * 1000
103
114
 
104
115
  export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapter {
105
116
  const logger = options.logger ?? consoleLogger
@@ -117,6 +128,7 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
117
128
  let managedHooks: ReadonlyArray<{ repo: string; hookId: number }> = []
118
129
  let tokenRefreshTimer: { clear: () => void } | null = null
119
130
  let deliveryRecoveryTimer: { clear: () => void } | null = null
131
+ let reconcileTimer: { clear: () => void } | null = null
120
132
  let unregisterTokenBridge: (() => void) | null = null
121
133
  const workspaceByChat = new Map<string, string>()
122
134
  const setIntervalFn =
@@ -133,8 +145,8 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
133
145
  // Repo/owner-aware token resolver. A single GitHub App can span multiple
134
146
  // installations (one per owner); each consumer passes its repo/owner so the
135
147
  // right installation token is minted. Unlike the old single-token path, this
136
- // does NOT mutate process.env.GH_TOKEN — that global is seeded separately and
137
- // only when exactly one installation applies (see seedGhTokenIfSingle).
148
+ // does NOT mutate process.env.GH_TOKEN. App credentials stay behind this
149
+ // repo-scoped resolver instead of entering the ambient process environment.
138
150
  const authToken = (context?: GithubAuthContext) => auth.token(context)
139
151
  const outbound = createGithubOutboundCallback({
140
152
  token: authToken,
@@ -169,6 +181,11 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
169
181
  approve: () => options.configRef().review.approve,
170
182
  fetchImpl,
171
183
  })
184
+ const reviewSubmitter = createGithubReviewSubmitter({
185
+ token: authToken,
186
+ allowApprove: () => options.configRef().review.approve,
187
+ fetchImpl,
188
+ })
172
189
  const channelNameResolver = createGithubChannelNameResolver({ token: authToken, fetchImpl })
173
190
  // GitHub addresses by `@login`, not the numeric id, so `username` carries
174
191
  // the login the model should type; the id is kept for completeness.
@@ -227,6 +244,7 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
227
244
  options.router.registerSelfIdentity('github', selfIdentityResolver)
228
245
  options.router.registerReviewThreadResolver('github', reviewThreadResolver)
229
246
  options.router.registerReviewStateResolver('github', reviewStateResolver)
247
+ options.router.registerReviewSubmitter('github', reviewSubmitter)
230
248
  options.router.registerFetchAttachment('github', fetchAttachment)
231
249
  try {
232
250
  server = (options.httpListenImpl ?? listenWithBun)(options.configRef().webhookPort, handler)
@@ -243,22 +261,20 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
243
261
  options.router.unregisterSelfIdentity('github', selfIdentityResolver)
244
262
  options.router.unregisterReviewThreadResolver('github', reviewThreadResolver)
245
263
  options.router.unregisterReviewStateResolver('github', reviewStateResolver)
264
+ options.router.unregisterReviewSubmitter('github', reviewSubmitter)
246
265
  options.router.unregisterFetchAttachment('github', fetchAttachment)
247
266
  await auth.dispose()
248
- delete process.env.GH_TOKEN
267
+ if (options.secrets.auth.type === 'pat') delete process.env.GH_TOKEN
249
268
  selfId = null
250
269
  selfLogin = null
251
270
  throw err
252
271
  }
253
272
  started = true
254
- // Seed the process-wide GH_TOKEN when it's unambiguous; skip otherwise.
255
- // See ghTokenSeedDecision for why one owner is required. On skip, authToken
256
- // still resolves a repo-scoped token per call for the adapter's own traffic.
257
- const seed = ghTokenSeedDecision(options.secrets.auth.type, options.configRef().repos ?? [])
258
- if (seed.kind === 'seed') {
259
- const seedContext = seed.context
273
+ // PAT mode retains its process-wide token behavior. App credentials never
274
+ // enter process.env; App consumers mint through the repo-scoped bridge.
275
+ if (options.secrets.auth.type === 'pat') {
260
276
  const seedGhToken = async (): Promise<void> => {
261
- process.env.GH_TOKEN = await auth.token(seedContext)
277
+ process.env.GH_TOKEN = await auth.token()
262
278
  }
263
279
  await seedGhToken()
264
280
  const tokenRefreshIntervalMs = options.tokenRefreshIntervalMs ?? DEFAULT_TOKEN_REFRESH_INTERVAL_MS
@@ -272,10 +288,6 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
272
288
  }
273
289
  tokenRefreshTimer = setIntervalFn(refresh, tokenRefreshIntervalMs)
274
290
  }
275
- } else {
276
- logger.info(
277
- `${GH_TOKEN_SKIP_LOG[seed.reason]} Ad-hoc \`gh\` commands should set a repo-scoped token explicitly.`,
278
- )
279
291
  }
280
292
  if (options.secrets.auth.type === 'app' && options.githubTokenBridge !== undefined) {
281
293
  // Gate ad-hoc `gh` minting on the configured repos[]. The slug arrives
@@ -284,17 +296,20 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
284
296
  // would mint an installation-wide token for any repo the App is installed
285
297
  // on — a cross-tenant leak under a multi-owner App. Enforced here, not in
286
298
  // the parser, because this adapter is the authority that owns repos[].
287
- unregisterTokenBridge = options.githubTokenBridge.registerResolver((repoSlug) => {
288
- const allowed = new Set((options.configRef().repos ?? []).map(canonicalRepoSlug))
289
- if (!allowed.has(canonicalRepoSlug(repoSlug))) {
290
- throw new Error(
291
- `repo \`${repoSlug}\` is not in this agent's configured \`channels.github.repos[]\`; ` +
292
- 'refusing to mint a GitHub App token for it. Target a configured repo, ' +
293
- 'or add it to `repos[]` if the agent is meant to operate there.',
294
- )
295
- }
296
- return auth.token({ repoSlug })
297
- })
299
+ unregisterTokenBridge = options.githubTokenBridge.registerResolver(
300
+ (repoSlug) => {
301
+ const allowed = new Set((options.configRef().repos ?? []).map(canonicalRepoSlug))
302
+ if (!allowed.has(canonicalRepoSlug(repoSlug))) {
303
+ throw new Error(
304
+ `repo \`${repoSlug}\` is not in this agent's configured \`channels.github.repos[]\`; ` +
305
+ 'refusing to mint a GitHub App token for it. Target a configured repo, ' +
306
+ 'or add it to `repos[]` if the agent is meant to operate there.',
307
+ )
308
+ }
309
+ return auth.token({ repoSlug })
310
+ },
311
+ () => selfLogin,
312
+ )
298
313
  }
299
314
  logger.info(`[github] webhook listening on port ${options.configRef().webhookPort} as @${self.login}`)
300
315
  // Best-effort: App-only preflight that compares the installation's granted
@@ -350,13 +365,21 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
350
365
  }
351
366
  // Catch up on PRs whose opened/ready_for_review/review_requested delivery
352
367
  // was missed (tunnel-URL churn, dropped delivery, downtime). Best-effort
353
- // and last so a failure here never blocks the adapter from coming up; the
354
- // helper swallows per-repo errors internally. Runs on every start(), so a
355
- // tunnel-driven restart re-checks too. `off` short-circuits inside.
356
- if (repos.length > 0) {
357
- await reconcileOpenPrs({
368
+ // so a failure here never blocks the adapter from coming up; the helper
369
+ // swallows per-repo errors internally. `off` short-circuits inside. A
370
+ // durable per-PR cooldown store bounds replay to at most once per window,
371
+ // so the many restarts a churning tunnel causes don't re-review the same
372
+ // PRs; the periodic tick below retries genuinely-missed PRs after the
373
+ // cooldown without needing a restart.
374
+ const reconcileCooldownStore =
375
+ repos.length > 0 ? await loadReconcileCooldownStore(options.agentDir, logger) : null
376
+ // Resolve review.on per call, not from the captured startup cfg: review.on
377
+ // is live-reloadable, so a periodic tick must honor a change to `off`
378
+ // (reconcileOpenPrs short-circuits on `off`) instead of scanning forever.
379
+ const runReconcile = (store: ReconcileCooldownStore): Promise<unknown> =>
380
+ reconcileOpenPrs({
358
381
  repos,
359
- reviewOn: cfg.review.on,
382
+ reviewOn: options.configRef().review.on,
360
383
  selfLogin,
361
384
  authType: options.secrets.auth.type,
362
385
  token: authToken,
@@ -364,9 +387,16 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
364
387
  logger,
365
388
  isBotInTeam,
366
389
  fetchImpl,
390
+ cooldownStore: store,
367
391
  }).catch((err: unknown) => {
368
392
  logger.warn(`[github] reconcile pass failed: ${err instanceof Error ? err.message : String(err)}`)
369
393
  })
394
+ if (reconcileCooldownStore !== null) {
395
+ await runReconcile(reconcileCooldownStore)
396
+ const reconcileIntervalMs = options.reconcileIntervalMs ?? DEFAULT_RECONCILE_INTERVAL_MS
397
+ if (reconcileIntervalMs > 0) {
398
+ reconcileTimer = setIntervalFn(() => void runReconcile(reconcileCooldownStore), reconcileIntervalMs)
399
+ }
370
400
  }
371
401
  // Periodically recover inbound deliveries that failed at the tunnel and
372
402
  // were never redelivered (the cloudflare-quick 502 loss). Registered only
@@ -407,6 +437,10 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
407
437
  deliveryRecoveryTimer.clear()
408
438
  deliveryRecoveryTimer = null
409
439
  }
440
+ if (reconcileTimer !== null) {
441
+ reconcileTimer.clear()
442
+ reconcileTimer = null
443
+ }
410
444
  options.router.unregisterOutbound('github', outbound)
411
445
  options.router.unregisterReaction('github', reaction)
412
446
  options.router.unregisterRemoveReaction('github', removeReaction)
@@ -417,6 +451,7 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
417
451
  options.router.unregisterSelfIdentity('github', selfIdentityResolver)
418
452
  options.router.unregisterReviewThreadResolver('github', reviewThreadResolver)
419
453
  options.router.unregisterReviewStateResolver('github', reviewStateResolver)
454
+ options.router.unregisterReviewSubmitter('github', reviewSubmitter)
420
455
  options.router.unregisterFetchAttachment('github', fetchAttachment)
421
456
  await server?.stop()
422
457
  // Detach hooks AFTER closing the listener so any in-flight deliveries
@@ -441,7 +476,7 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
441
476
  unregisterTokenBridge = null
442
477
  }
443
478
  await auth.dispose()
444
- delete process.env.GH_TOKEN
479
+ if (options.secrets.auth.type === 'pat') delete process.env.GH_TOKEN
445
480
  server = null
446
481
  selfId = null
447
482
  selfLogin = null
@@ -576,35 +611,6 @@ function logDeregistrationOutcome(
576
611
  }
577
612
  }
578
613
 
579
- type GhTokenSeedDecision =
580
- | { kind: 'seed'; context?: GithubAuthContext }
581
- | { kind: 'skip'; reason: 'no-repos' | 'multiple-owners' }
582
-
583
- const GH_TOKEN_SKIP_LOG: Record<'no-repos' | 'multiple-owners', string> = {
584
- 'no-repos':
585
- '[github] no repos[] configured; GH_TOKEN not seeded globally (cannot prove which App installation to use).',
586
- 'multiple-owners': '[github] repos span multiple owners (multiple App installations); GH_TOKEN not seeded globally.',
587
- }
588
-
589
- // Decides how to seed the process-wide GH_TOKEN. PATs aren't installation-scoped
590
- // (seed context-free). For App auth we seed from a configured repo slug, which
591
- // resolves the installation via repos/{owner}/{repo}/installation — the only
592
- // lookup that works for both org- and user-owned repos. One owner is required:
593
- // no-repos can't prove an installation, multi-owner needs >1 token.
594
- function ghTokenSeedDecision(authType: 'pat' | 'app', repos: readonly string[]): GhTokenSeedDecision {
595
- if (authType === 'pat') return { kind: 'seed' }
596
- const slugs = [...new Set(repos.filter(isWellFormedSlug))].sort()
597
- if (slugs.length === 0) return { kind: 'skip', reason: 'no-repos' }
598
- const owners = new Set(slugs.map((slug) => slug.split('/')[0]))
599
- if (owners.size > 1) return { kind: 'skip', reason: 'multiple-owners' }
600
- return { kind: 'seed', context: { repoSlug: slugs[0] } }
601
- }
602
-
603
- function isWellFormedSlug(repo: string): boolean {
604
- const [owner, name, ...rest] = repo.split('/')
605
- return owner !== undefined && owner !== '' && name !== undefined && name !== '' && rest.length === 0
606
- }
607
-
608
614
  // Canonical form for repos[] allowlist comparison so the gate can't be bypassed
609
615
  // by case, a trailing slash, or a `.git` suffix (GitHub treats owner/name
610
616
  // case-insensitively). Applied identically to both configured repos[] and the
@@ -0,0 +1,178 @@
1
+ import { mkdir, readFile, rename, writeFile } from 'node:fs/promises'
2
+ import { dirname, join } from 'node:path'
3
+
4
+ // Durable per-PR replay cooldown for the open-PR reconcile pass.
5
+ //
6
+ // The reconcile pass (reconcile-open-prs.ts) runs on every adapter start() and
7
+ // replays every open PR that has no POSTED review yet. That predicate is wrong
8
+ // under two real conditions:
9
+ // 1. Review work happens in a subagent that a container restart can kill
10
+ // before it posts — the PR still reads "unreviewed" and gets replayed on
11
+ // the NEXT start, re-triggering the exact work the restart just lost.
12
+ // 2. `updatedAt`-keyed message dedup breaks the moment any activity bumps the
13
+ // PR's updatedAt, so an in-progress review is replayed again.
14
+ // With a churning tunnel (cloudflare-quick mints a fresh URL every restart) the
15
+ // adapter restarts many times a day, turning a rare-event "floor" into a
16
+ // re-review storm.
17
+ //
18
+ // This store decouples replay eligibility from adapter lifecycle: a PR is
19
+ // replayed at most once per cooldown window, keyed by a durable
20
+ // `repo#prId` marker that survives restarts. A genuinely-missed `opened` is
21
+ // still recovered — the periodic reconcile tick retries after the cooldown
22
+ // expires — without a restart being required. The marker records when a replay
23
+ // was LAUNCHED (not when a review completed): posted-review suppression stays
24
+ // the authoritative "done" signal in reconcile-open-prs.ts; this store only
25
+ // bounds retry frequency.
26
+
27
+ const FILE_VERSION = 1
28
+
29
+ // A PR that still needs review is replayed at most once per this window. Long
30
+ // enough that ~20 restarts/day collapse to a single daily retry, short enough
31
+ // that an interrupted review is retried the same day.
32
+ export const DEFAULT_RECONCILE_COOLDOWN_MS = 24 * 60 * 60 * 1000
33
+
34
+ // Markers older than this are pruned on save even if their PR is still open, so
35
+ // a long-lived PR that was reviewed once cannot pin its marker forever. Any PR
36
+ // that still needs review re-earns a fresh marker on the next eligible tick.
37
+ const MARKER_RETENTION_MS = 7 * 24 * 60 * 60 * 1000
38
+
39
+ export type ReconcileMarker = {
40
+ repo: string
41
+ prId: number
42
+ lastReplayAt: number
43
+ }
44
+
45
+ type FileV1 = {
46
+ version: 1
47
+ markers: ReconcileMarker[]
48
+ }
49
+
50
+ export type ReconcileCooldownLogger = {
51
+ info: (msg: string) => void
52
+ warn: (msg: string) => void
53
+ error: (msg: string) => void
54
+ }
55
+
56
+ const consoleLogger: ReconcileCooldownLogger = {
57
+ info: (m) => console.log(m),
58
+ warn: (m) => console.warn(m),
59
+ error: (m) => console.error(m),
60
+ }
61
+
62
+ export function reconcileCooldownPath(agentDir: string): string {
63
+ return join(agentDir, 'channels', 'github-reconcile.json')
64
+ }
65
+
66
+ function markerKey(repo: string, prId: number): string {
67
+ return `${repo}#${prId}`
68
+ }
69
+
70
+ export type ReconcileCooldownStore = {
71
+ isCoolingDown: (repo: string, prId: number, now: number, cooldownMs: number) => boolean
72
+ // Flush BEFORE routing the synthetic inbound: a crash between marking and
73
+ // session creation must not re-trigger a replay on the next restart.
74
+ markReplayed: (repo: string, prId: number, now: number) => Promise<void>
75
+ prune: (repo: string, openPrIds: ReadonlySet<number>, now: number) => Promise<void>
76
+ }
77
+
78
+ export async function loadReconcileCooldownStore(
79
+ agentDir: string,
80
+ logger: ReconcileCooldownLogger = consoleLogger,
81
+ ): Promise<ReconcileCooldownStore> {
82
+ const path = reconcileCooldownPath(agentDir)
83
+ const markers = new Map<string, ReconcileMarker>()
84
+ for (const marker of await readMarkers(path, logger)) {
85
+ markers.set(markerKey(marker.repo, marker.prId), marker)
86
+ }
87
+
88
+ const flush = async (): Promise<void> => {
89
+ const payload: FileV1 = { version: FILE_VERSION, markers: Array.from(markers.values()) }
90
+ await mkdir(dirname(path), { recursive: true })
91
+ const tmp = `${path}.tmp`
92
+ await writeFile(tmp, `${JSON.stringify(payload, null, 2)}\n`, 'utf8')
93
+ await rename(tmp, path)
94
+ }
95
+
96
+ return {
97
+ isCoolingDown(repo, prId, now, cooldownMs): boolean {
98
+ const marker = markers.get(markerKey(repo, prId))
99
+ if (marker === undefined) return false
100
+ return now - marker.lastReplayAt < cooldownMs
101
+ },
102
+ // Roll the in-memory marker back and rethrow if the disk write fails, so the
103
+ // caller skips routing rather than replaying a PR with no durable record —
104
+ // otherwise a restart would replay it immediately, defeating the cooldown.
105
+ async markReplayed(repo, prId, now): Promise<void> {
106
+ const key = markerKey(repo, prId)
107
+ const previous = markers.get(key)
108
+ markers.set(key, { repo, prId, lastReplayAt: now })
109
+ try {
110
+ await flush()
111
+ } catch (err) {
112
+ if (previous === undefined) markers.delete(key)
113
+ else markers.set(key, previous)
114
+ throw err
115
+ }
116
+ },
117
+ async prune(repo, openPrIds, now): Promise<void> {
118
+ let changed = false
119
+ for (const [key, marker] of markers) {
120
+ const stale = now - marker.lastReplayAt >= MARKER_RETENTION_MS
121
+ const closed = marker.repo === repo && !openPrIds.has(marker.prId)
122
+ if (stale || closed) {
123
+ markers.delete(key)
124
+ changed = true
125
+ }
126
+ }
127
+ if (changed) {
128
+ try {
129
+ await flush()
130
+ } catch (err) {
131
+ logger.error(`[github] failed to persist reconcile cooldown: ${describe(err)}`)
132
+ }
133
+ }
134
+ },
135
+ }
136
+ }
137
+
138
+ async function readMarkers(path: string, logger: ReconcileCooldownLogger): Promise<ReconcileMarker[]> {
139
+ let raw: string
140
+ try {
141
+ raw = await readFile(path, 'utf8')
142
+ } catch {
143
+ return []
144
+ }
145
+ let parsed: unknown
146
+ try {
147
+ parsed = JSON.parse(raw)
148
+ } catch (err) {
149
+ logger.error(`[github] ${path} corrupted: ${describe(err)}; starting fresh`)
150
+ return []
151
+ }
152
+ if (!isObject(parsed)) {
153
+ logger.warn(`[github] ${path} not an object; ignored`)
154
+ return []
155
+ }
156
+ const version = (parsed as { version?: unknown }).version
157
+ if (version !== FILE_VERSION) {
158
+ logger.warn(`[github] ${path} version ${String(version)} not supported (expected ${FILE_VERSION}); ignored`)
159
+ return []
160
+ }
161
+ const file = parsed as FileV1
162
+ if (!Array.isArray(file.markers)) return []
163
+ return file.markers.filter(isValidMarker)
164
+ }
165
+
166
+ function isObject(v: unknown): v is Record<string, unknown> {
167
+ return typeof v === 'object' && v !== null && !Array.isArray(v)
168
+ }
169
+
170
+ function isValidMarker(v: unknown): v is ReconcileMarker {
171
+ if (!isObject(v)) return false
172
+ const r = v as Record<string, unknown>
173
+ return typeof r.repo === 'string' && typeof r.prId === 'number' && typeof r.lastReplayAt === 'number'
174
+ }
175
+
176
+ function describe(err: unknown): string {
177
+ return err instanceof Error ? err.message : String(err)
178
+ }
@@ -3,6 +3,7 @@ import type { InboundMessage } from '@/channels/types'
3
3
 
4
4
  import type { GithubAuthContext } from './auth'
5
5
  import { GITHUB_API_BASE, githubJsonHeaders } from './auth-pat'
6
+ import { DEFAULT_RECONCILE_COOLDOWN_MS, type ReconcileCooldownStore } from './reconcile-cooldown-store'
6
7
  import type { TeamMembershipChecker } from './team-membership'
7
8
 
8
9
  // Catches up on review work that a live webhook delivery missed. The github
@@ -32,6 +33,12 @@ export type ReconcileOpenPrsOptions = {
32
33
  // tests that don't exercise team requests; treated as "not a member".
33
34
  isBotInTeam?: TeamMembershipChecker
34
35
  fetchImpl?: typeof fetch
36
+ // When provided, a PR that still needs review is replayed at most once per
37
+ // `cooldownMs`, keyed durably by `repo#prId` so restarts don't re-trigger it.
38
+ // Omitted in tests that assert the raw replay decision.
39
+ cooldownStore?: ReconcileCooldownStore
40
+ cooldownMs?: number
41
+ now?: () => number
35
42
  }
36
43
 
37
44
  export type ReconcileOutcome = { repo: string; scanned: number; replayed: number } | { repo: string; error: string }
@@ -79,13 +86,37 @@ async function reconcileRepo(
79
86
  const token = await options.token({ repoSlug: repo })
80
87
  const prs = await fetchOpenPrs(fetchImpl, token, target)
81
88
 
89
+ const cooldownStore = options.cooldownStore
90
+ const cooldownMs = options.cooldownMs ?? DEFAULT_RECONCILE_COOLDOWN_MS
91
+ const now = options.now ?? Date.now
92
+
82
93
  let replayed = 0
83
94
  for (const pr of prs) {
84
95
  const needs = await prNeedsReview({ pr, options, target, token, selfLogin, decoyLogin, fetchImpl })
85
96
  if (!needs) continue
97
+ if (cooldownStore !== undefined) {
98
+ if (cooldownStore.isCoolingDown(repo, pr.id, now(), cooldownMs)) continue
99
+ try {
100
+ // Persist the marker before routing: if the write fails the marker is
101
+ // rolled back and this throws, so we skip the route rather than replay a
102
+ // PR with no durable record (a restart would otherwise replay it again).
103
+ await cooldownStore.markReplayed(repo, pr.id, now())
104
+ } catch (err) {
105
+ options.logger.warn(
106
+ `[github] reconcile ${repo}: skipping PR #${pr.number} replay, cooldown persist failed: ${
107
+ err instanceof Error ? err.message : String(err)
108
+ }`,
109
+ )
110
+ continue
111
+ }
112
+ }
86
113
  options.route(buildSyntheticInbound(pr, target))
87
114
  replayed += 1
88
115
  }
116
+
117
+ if (cooldownStore !== undefined) {
118
+ await cooldownStore.prune(repo, new Set(prs.map((pr) => pr.id)), now())
119
+ }
89
120
  return { repo, scanned: prs.length, replayed }
90
121
  }
91
122