typeclaw 0.46.0 → 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 (52) hide show
  1. package/README.md +1 -1
  2. package/package.json +2 -2
  3. package/src/agent/multimodal/looker.ts +11 -1
  4. package/src/agent/network/safe-http.ts +17 -8
  5. package/src/agent/plugin-tools.ts +1 -3
  6. package/src/agent/tool-file-safety.ts +396 -136
  7. package/src/agent/tools/webfetch/fetch.ts +22 -2
  8. package/src/agent/tools-without-local-file-operands.ts +9 -6
  9. package/src/bundled-plugins/backup/README.md +23 -10
  10. package/src/bundled-plugins/backup/git-auth.ts +6 -4
  11. package/src/bundled-plugins/backup/index.ts +83 -43
  12. package/src/bundled-plugins/backup/runner.ts +83 -0
  13. package/src/bundled-plugins/github-cli-auth/git-askpass.ts +74 -26
  14. package/src/bundled-plugins/github-cli-auth/git-command.ts +224 -36
  15. package/src/bundled-plugins/github-cli-auth/graphql-auth-nudge.ts +9 -9
  16. package/src/bundled-plugins/github-cli-auth/index.ts +110 -31
  17. package/src/bundled-plugins/github-cli-auth/token-class.ts +4 -6
  18. package/src/bundled-plugins/memory/README.md +9 -0
  19. package/src/bundled-plugins/memory/vector/embed-threads.ts +36 -0
  20. package/src/bundled-plugins/memory/vector/embedder.ts +19 -1
  21. package/src/bundled-plugins/researcher/write-report.ts +3 -3
  22. package/src/bundled-plugins/security/policies/private-surface-read.ts +610 -50
  23. package/src/bundled-plugins/security/policies/ssrf.ts +119 -34
  24. package/src/channels/adapters/github/inbound.ts +11 -0
  25. package/src/channels/adapters/github/index.ts +48 -54
  26. package/src/channels/adapters/github/reconcile-cooldown-store.ts +178 -0
  27. package/src/channels/adapters/github/reconcile-open-prs.ts +31 -0
  28. package/src/channels/adapters/slack-bot-edit.ts +85 -20
  29. package/src/channels/adapters/slack-bot.ts +7 -2
  30. package/src/channels/adapters/slack-format.ts +245 -0
  31. package/src/channels/github-token-bridge.ts +2 -3
  32. package/src/container/docker-app.ts +42 -13
  33. package/src/container/start.ts +13 -0
  34. package/src/cron/bridge.ts +9 -2
  35. package/src/doctor/checks.ts +5 -2
  36. package/src/git/bound-gc-config.ts +82 -0
  37. package/src/hostd/spawn.ts +133 -47
  38. package/src/init/dockerfile.ts +13 -0
  39. package/src/inspect/replay.ts +21 -9
  40. package/src/inspect/session-list.ts +71 -33
  41. package/src/mcp/tools.ts +1 -0
  42. package/src/network/internal-destinations.ts +267 -0
  43. package/src/plugin/types.ts +3 -2
  44. package/src/sandbox/env-exposure.ts +18 -15
  45. package/src/sandbox/policy.ts +5 -3
  46. package/src/sandbox/privileged-runtime.ts +1 -0
  47. package/src/skills/typeclaw-config/SKILL.md +22 -6
  48. package/src/skills/typeclaw-permissions/SKILL.md +22 -9
  49. package/src/skills/typeclaw-plugins/SKILL.md +37 -0
  50. package/src/usage/scan.ts +11 -2
  51. package/typeclaw.schema.json +5 -0
  52. package/src/git/secret-history.ts +0 -371
@@ -1,7 +1,16 @@
1
1
  import { isIP } from 'node:net'
2
2
 
3
+ import {
4
+ addressMatchesPolicy,
5
+ extractEmbeddedIpv4Address,
6
+ extractRfc6052Ipv4Addresses,
7
+ getBootInternalDestinationPolicy,
8
+ hostnameMatchesPolicy,
9
+ type InternalDestinationPolicy,
10
+ } from '@/network/internal-destinations'
11
+
3
12
  import type { SecuritySeverity } from '../permissions'
4
- import { ACKNOWLEDGE_GUARDS, type SecurityBlock, isGuardAcknowledged } from '../policy'
13
+ import type { SecurityBlock } from '../policy'
5
14
 
6
15
  export const GUARD_SSRF = 'ssrf'
7
16
  // Classified `medium` (silent-attack axis): bypass lets `curl
@@ -10,14 +19,13 @@ export const GUARD_SSRF = 'ssrf'
10
19
  // Catastrophic on follow-up because the model now has live cloud creds.
11
20
  export const GUARD_SSRF_SEVERITY: SecuritySeverity = 'medium'
12
21
 
13
- const ALWAYS_BLOCKED_HOSTS = new Set([
14
- 'localhost',
15
- 'localhost.localdomain',
16
- 'ip6-localhost',
17
- 'ip6-loopback',
22
+ const ALWAYS_BLOCKED_HOSTS = new Set(['localhost', 'localhost.localdomain', 'ip6-localhost', 'ip6-loopback'])
23
+
24
+ const CLOUD_METADATA_HOSTS = new Set([
18
25
  'metadata.google.internal',
19
26
  'metadata',
20
27
  'metadata.aws.internal',
28
+ 'metadata.azure.internal',
21
29
  'instance-data',
22
30
  'instance-data.ec2.internal',
23
31
  ])
@@ -39,7 +47,7 @@ export type SsrfClassification = {
39
47
  reason?: string
40
48
  }
41
49
 
42
- export function classifyUrl(rawUrl: string): SsrfClassification {
50
+ export function classifyUrl(rawUrl: string, internalDestinationPolicy?: InternalDestinationPolicy): SsrfClassification {
43
51
  let parsed: URL
44
52
  try {
45
53
  parsed = new URL(rawUrl)
@@ -67,27 +75,48 @@ export function classifyUrl(rawUrl: string): SsrfClassification {
67
75
  }
68
76
 
69
77
  const host = parsed.hostname.toLowerCase()
70
- const decoded = decodeBracketedIpv6(host)
78
+ const decoded = decodeBracketedIpv6(host).replace(/\.$/, '')
71
79
 
72
- if (ALWAYS_BLOCKED_HOSTS.has(decoded)) {
80
+ if (isCloudMetadataHostname(decoded)) {
73
81
  return {
82
+ blocked: true,
83
+ category: 'cloud_metadata',
84
+ reason: `cloud metadata hostname "${decoded}" is never allowed`,
85
+ }
86
+ }
87
+
88
+ if (ALWAYS_BLOCKED_HOSTS.has(decoded)) {
89
+ const classification: SsrfClassification = {
74
90
  blocked: true,
75
91
  category: 'reserved_internal_host',
76
92
  reason: `host "${decoded}" resolves to internal/loopback infrastructure`,
77
93
  }
94
+ return internalDestinationPolicy !== undefined &&
95
+ allowsInternalDestination(decoded, undefined, internalDestinationPolicy)
96
+ ? { blocked: false }
97
+ : classification
78
98
  }
79
99
  for (const suffix of ALWAYS_BLOCKED_HOST_SUFFIXES) {
80
100
  if (decoded.endsWith(suffix)) {
81
- return {
101
+ const classification: SsrfClassification = {
82
102
  blocked: true,
83
103
  category: 'reserved_internal_host',
84
104
  reason: `host suffix "${suffix}" is reserved for internal networks`,
85
105
  }
106
+ return internalDestinationPolicy !== undefined &&
107
+ allowsInternalDestination(decoded, undefined, internalDestinationPolicy)
108
+ ? { blocked: false }
109
+ : classification
86
110
  }
87
111
  }
88
112
 
89
113
  const addressClassification = classifyIpAddress(decoded)
90
- if (addressClassification.blocked) return addressClassification
114
+ if (addressClassification.blocked) {
115
+ return internalDestinationPolicy !== undefined &&
116
+ allowsInternalDestination(decoded, decoded, internalDestinationPolicy)
117
+ ? { blocked: false }
118
+ : addressClassification
119
+ }
91
120
 
92
121
  return { blocked: false }
93
122
  }
@@ -108,6 +137,20 @@ export function classifyIpAddress(address: string): SsrfClassification {
108
137
  return { blocked: false }
109
138
  }
110
139
 
140
+ export function allowsInternalDestination(
141
+ hostname: string,
142
+ address: string | undefined,
143
+ policy: InternalDestinationPolicy,
144
+ ): boolean {
145
+ const normalizedHostname = decodeBracketedIpv6(hostname.toLowerCase()).replace(/\.$/, '')
146
+ if (isCloudMetadataHostname(normalizedHostname)) return false
147
+ if (address !== undefined && isCloudMetadataAddress(address)) return false
148
+ return (
149
+ hostnameMatchesPolicy(normalizedHostname, policy) ||
150
+ (address !== undefined && addressMatchesPolicy(address, policy))
151
+ )
152
+ }
153
+
111
154
  function normalizeIpv6(address: string): string | undefined {
112
155
  if (isIP(address) !== 6) return undefined
113
156
  try {
@@ -117,14 +160,17 @@ function normalizeIpv6(address: string): string | undefined {
117
160
  }
118
161
  }
119
162
 
120
- export function checkSsrfGuard(options: { tool: string; args: Record<string, unknown> }): SecurityBlock | undefined {
163
+ export function checkSsrfGuard(options: {
164
+ tool: string
165
+ args: Record<string, unknown>
166
+ internalDestinationPolicy?: InternalDestinationPolicy
167
+ }): SecurityBlock | undefined {
121
168
  const { tool, args } = options
122
169
  if (tool !== 'web_fetch') return undefined
123
170
  const url = args.url
124
171
  if (typeof url !== 'string') return undefined
125
- if (isGuardAcknowledged(args, GUARD_SSRF)) return undefined
126
172
 
127
- const result = classifyUrl(url)
173
+ const result = classifyUrl(url, options.internalDestinationPolicy ?? getBootInternalDestinationPolicy())
128
174
  if (!result.blocked) return undefined
129
175
 
130
176
  return {
@@ -132,7 +178,7 @@ export function checkSsrfGuard(options: { tool: string; args: Record<string, unk
132
178
  reason: [
133
179
  `Guard \`${GUARD_SSRF}\` blocked web_fetch to a non-public destination (${result.category ?? 'unknown'}): ${result.reason ?? 'classified as internal'}.`,
134
180
  'This protects against SSRF, cloud metadata exfiltration, and accidental fetches against internal services.',
135
- `If this is genuinely intentional and you trust the URL, retry with \`${ACKNOWLEDGE_GUARDS}.${GUARD_SSRF}: true\` in the web_fetch arguments.`,
181
+ 'Intentional internal destinations must be configured by the operator through the boot-only model HTTP environment policy; model-authored acknowledgements cannot bypass this guard.',
136
182
  ].join(' '),
137
183
  }
138
184
  }
@@ -171,6 +217,8 @@ function classifyIpv4(
171
217
  ip: [number, number, number, number],
172
218
  ): { category: SsrfClassification['category']; reason: string } | undefined {
173
219
  const [a, b] = ip
220
+ if (isCloudMetadataIpv4(ip))
221
+ return { category: 'cloud_metadata', reason: `cloud metadata endpoint (${ip.join('.')})` }
174
222
  if (a === 127) return { category: 'loopback', reason: `IPv4 loopback (${ip.join('.')})` }
175
223
  if (a === 10) return { category: 'private_ipv4', reason: `private RFC1918 10.0.0.0/8 (${ip.join('.')})` }
176
224
  if (a === 172 && b >= 16 && b <= 31)
@@ -178,7 +226,7 @@ function classifyIpv4(
178
226
  if (a === 192 && b === 168)
179
227
  return { category: 'private_ipv4', reason: `private RFC1918 192.168.0.0/16 (${ip.join('.')})` }
180
228
  if (a === 169 && b === 254)
181
- return { category: 'cloud_metadata', reason: `link-local / cloud metadata 169.254.0.0/16 (${ip.join('.')})` }
229
+ return { category: 'link_local', reason: `IPv4 link-local 169.254.0.0/16 (${ip.join('.')})` }
182
230
  if (a === 100 && b >= 64 && b <= 127)
183
231
  return { category: 'shared_cgnat', reason: `CGNAT 100.64.0.0/10 (${ip.join('.')})` }
184
232
  if (a === 198 && (b === 18 || b === 19))
@@ -190,6 +238,39 @@ function classifyIpv4(
190
238
 
191
239
  function classifyIpv6(host: string): { category: SsrfClassification['category']; reason: string } | undefined {
192
240
  const lower = host.toLowerCase()
241
+ if (lower === 'fd00:ec2::254' || lower === 'fd20:ce::254') {
242
+ return { category: 'cloud_metadata', reason: `cloud IPv6 metadata endpoint (${lower})` }
243
+ }
244
+ if (lower.startsWith('64:ff9b:1:')) {
245
+ return {
246
+ category: 'cloud_metadata',
247
+ reason: `RFC8215 local-use translation prefix has no safely inferable IPv4 field (${lower})`,
248
+ }
249
+ }
250
+ const internalClassification = classifyInternalIpv6(lower)
251
+ if (internalClassification !== undefined) {
252
+ const translatedMetadata = extractRfc6052Ipv4Addresses(lower).find((candidate) => {
253
+ const ipv4 = parseIpv4Loose(candidate)
254
+ return ipv4 !== undefined && isCloudMetadataIpv4(ipv4)
255
+ })
256
+ if (translatedMetadata !== undefined) {
257
+ return {
258
+ category: 'cloud_metadata',
259
+ reason: `RFC6052 network-specific translation of cloud metadata endpoint (${translatedMetadata})`,
260
+ }
261
+ }
262
+ return internalClassification
263
+ }
264
+ const embeddedIpv4 = extractEmbeddedIpv4Address(lower)
265
+ if (embeddedIpv4 !== undefined) {
266
+ const parsed = parseIpv4Loose(embeddedIpv4)
267
+ const cls = parsed === undefined ? undefined : classifyIpv4(parsed)
268
+ if (cls) return { category: cls.category, reason: `IPv4-embedded IPv6: ${cls.reason}` }
269
+ }
270
+ return undefined
271
+ }
272
+
273
+ function classifyInternalIpv6(lower: string): { category: SsrfClassification['category']; reason: string } | undefined {
193
274
  if (lower === '::1' || lower === '0:0:0:0:0:0:0:1') return { category: 'loopback', reason: 'IPv6 loopback ::1' }
194
275
  if (lower === '::' || lower === '0:0:0:0:0:0:0:0') return { category: 'unspecified', reason: 'IPv6 unspecified ::' }
195
276
  const firstHextet = Number.parseInt(lower.split(':')[0] ?? '', 16)
@@ -200,23 +281,27 @@ function classifyIpv6(host: string): { category: SsrfClassification['category'];
200
281
  if (lower.startsWith('fc') || lower.startsWith('fd'))
201
282
  return { category: 'ipv6_internal', reason: 'IPv6 unique-local fc00::/7' }
202
283
  if (lower.startsWith('ff')) return { category: 'ipv6_internal', reason: 'IPv6 multicast ff00::/8' }
203
- if (lower.startsWith('::ffff:')) {
204
- const tail = lower.slice('::ffff:'.length)
205
- const dotted = parseIpv4Loose(tail)
206
- if (dotted) {
207
- const cls = classifyIpv4(dotted)
208
- if (cls) return { category: cls.category, reason: `IPv4-mapped IPv6: ${cls.reason}` }
209
- }
210
- const hexPair = tail.match(/^([0-9a-f]{1,4}):([0-9a-f]{1,4})$/)
211
- if (hexPair && hexPair[1] && hexPair[2]) {
212
- const hi = parseInt(hexPair[1], 16)
213
- const lo = parseInt(hexPair[2], 16)
214
- if (Number.isFinite(hi) && Number.isFinite(lo)) {
215
- const ip: [number, number, number, number] = [(hi >>> 8) & 0xff, hi & 0xff, (lo >>> 8) & 0xff, lo & 0xff]
216
- const cls = classifyIpv4(ip)
217
- if (cls) return { category: cls.category, reason: `IPv4-mapped IPv6: ${cls.reason}` }
218
- }
219
- }
220
- }
221
284
  return undefined
222
285
  }
286
+
287
+ function isCloudMetadataHostname(hostname: string): boolean {
288
+ return CLOUD_METADATA_HOSTS.has(hostname) || hostname.endsWith('.metadata.google.internal')
289
+ }
290
+
291
+ function isCloudMetadataAddress(address: string): boolean {
292
+ return classifyIpAddress(address).category === 'cloud_metadata'
293
+ }
294
+
295
+ function isCloudMetadataIpv4(ip: [number, number, number, number]): boolean {
296
+ const value = ip.join('.')
297
+ return (
298
+ value === '169.254.169.254' ||
299
+ value === '169.254.170.2' ||
300
+ value === '169.254.170.23' ||
301
+ value === '169.254.0.23' ||
302
+ value === '169.254.0.24' ||
303
+ value === '100.100.100.200' ||
304
+ value === '192.0.0.192' ||
305
+ value === '168.63.129.16'
306
+ )
307
+ }
@@ -566,6 +566,13 @@ export function classifyGithubInbound(
566
566
  const reviewer = readUser(review.user)
567
567
  const body = readString(review, 'body')
568
568
  const hasBody = body !== null && body.trim() !== ''
569
+ // A body-less COMMENTED review is the container GitHub submits when a user
570
+ // replies inline to a review thread; those replies arrive separately as
571
+ // pull_request_review_comment events. Synthesizing "@x submitted a review"
572
+ // here duplicates that traffic with a contentless line that trips the
573
+ // solo-human engagement fallback into a reflexive "Thanks for the review!".
574
+ // APPROVED / CHANGES_REQUESTED are real verdicts, so their synthesis stays.
575
+ if (!hasBody && isCommentedReviewState(readString(review, 'state'))) return null
569
576
  const text = hasBody
570
577
  ? body
571
578
  : reviewer !== null
@@ -912,6 +919,10 @@ function isActionableReviewState(state: string | null): boolean {
912
919
  return state?.toLowerCase() !== 'approved'
913
920
  }
914
921
 
922
+ function isCommentedReviewState(state: string | null): boolean {
923
+ return state?.toLowerCase() === 'commented'
924
+ }
925
+
915
926
  async function resolveTeamMembership(
916
927
  event: string,
917
928
  payload: Record<string, unknown>,
@@ -21,6 +21,7 @@ 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'
@@ -61,7 +62,7 @@ export type GithubAdapterOptions = {
61
62
  // Test-only: replaces the wall-clock sleep used for the registration
62
63
  // delay above. Production leaves it undefined and we use `setTimeout`.
63
64
  sleep?: (ms: number) => Promise<void>
64
- // How often to proactively refresh the token and update GH_TOKEN
65
+ // How often to proactively refresh a PAT and update GH_TOKEN
65
66
  // when the adapter is running but has not made an outbound API call
66
67
  // recently. Zero disables the background refresh entirely.
67
68
  // Default: 30 minutes.
@@ -73,10 +74,15 @@ export type GithubAdapterOptions = {
73
74
  // inbound delivery failed (and that GitHub never redelivered), re-injecting
74
75
  // them through the live event path. Zero disables the sweep. Default: 5 min.
75
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
76
82
  // Write-side of the GithubTokenBridge. On App-auth start the adapter
77
- // registers a per-repo minter here so plugin hooks can resolve a token for
78
- // ad-hoc `gh` commands; it unregisters on stop and on start rollback. PAT
79
- // 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
80
86
  // classic PAT can reach, and a fine-grained PAT cannot be re-minted per repo).
81
87
  githubTokenBridge?: GithubTokenBridge
82
88
  }
@@ -101,6 +107,10 @@ const DEFAULT_DELIVERY_RECOVERY_INTERVAL_MS = 5 * 60 * 1000
101
107
  const DELIVERY_RECOVERY_LOOKBACK_MS = 70 * 60 * 60 * 1000
102
108
  // Bounds an LLM-session storm if a bad tunnel window drops a large burst.
103
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
104
114
 
105
115
  export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapter {
106
116
  const logger = options.logger ?? consoleLogger
@@ -118,6 +128,7 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
118
128
  let managedHooks: ReadonlyArray<{ repo: string; hookId: number }> = []
119
129
  let tokenRefreshTimer: { clear: () => void } | null = null
120
130
  let deliveryRecoveryTimer: { clear: () => void } | null = null
131
+ let reconcileTimer: { clear: () => void } | null = null
121
132
  let unregisterTokenBridge: (() => void) | null = null
122
133
  const workspaceByChat = new Map<string, string>()
123
134
  const setIntervalFn =
@@ -134,8 +145,8 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
134
145
  // Repo/owner-aware token resolver. A single GitHub App can span multiple
135
146
  // installations (one per owner); each consumer passes its repo/owner so the
136
147
  // right installation token is minted. Unlike the old single-token path, this
137
- // does NOT mutate process.env.GH_TOKEN — that global is seeded separately and
138
- // 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.
139
150
  const authToken = (context?: GithubAuthContext) => auth.token(context)
140
151
  const outbound = createGithubOutboundCallback({
141
152
  token: authToken,
@@ -253,20 +264,17 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
253
264
  options.router.unregisterReviewSubmitter('github', reviewSubmitter)
254
265
  options.router.unregisterFetchAttachment('github', fetchAttachment)
255
266
  await auth.dispose()
256
- delete process.env.GH_TOKEN
267
+ if (options.secrets.auth.type === 'pat') delete process.env.GH_TOKEN
257
268
  selfId = null
258
269
  selfLogin = null
259
270
  throw err
260
271
  }
261
272
  started = true
262
- // Seed the process-wide GH_TOKEN when it's unambiguous; skip otherwise.
263
- // See ghTokenSeedDecision for why one owner is required. On skip, authToken
264
- // still resolves a repo-scoped token per call for the adapter's own traffic.
265
- const seed = ghTokenSeedDecision(options.secrets.auth.type, options.configRef().repos ?? [])
266
- if (seed.kind === 'seed') {
267
- 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') {
268
276
  const seedGhToken = async (): Promise<void> => {
269
- process.env.GH_TOKEN = await auth.token(seedContext)
277
+ process.env.GH_TOKEN = await auth.token()
270
278
  }
271
279
  await seedGhToken()
272
280
  const tokenRefreshIntervalMs = options.tokenRefreshIntervalMs ?? DEFAULT_TOKEN_REFRESH_INTERVAL_MS
@@ -280,10 +288,6 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
280
288
  }
281
289
  tokenRefreshTimer = setIntervalFn(refresh, tokenRefreshIntervalMs)
282
290
  }
283
- } else {
284
- logger.info(
285
- `${GH_TOKEN_SKIP_LOG[seed.reason]} Ad-hoc \`gh\` commands should set a repo-scoped token explicitly.`,
286
- )
287
291
  }
288
292
  if (options.secrets.auth.type === 'app' && options.githubTokenBridge !== undefined) {
289
293
  // Gate ad-hoc `gh` minting on the configured repos[]. The slug arrives
@@ -361,13 +365,21 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
361
365
  }
362
366
  // Catch up on PRs whose opened/ready_for_review/review_requested delivery
363
367
  // was missed (tunnel-URL churn, dropped delivery, downtime). Best-effort
364
- // and last so a failure here never blocks the adapter from coming up; the
365
- // helper swallows per-repo errors internally. Runs on every start(), so a
366
- // tunnel-driven restart re-checks too. `off` short-circuits inside.
367
- if (repos.length > 0) {
368
- 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({
369
381
  repos,
370
- reviewOn: cfg.review.on,
382
+ reviewOn: options.configRef().review.on,
371
383
  selfLogin,
372
384
  authType: options.secrets.auth.type,
373
385
  token: authToken,
@@ -375,9 +387,16 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
375
387
  logger,
376
388
  isBotInTeam,
377
389
  fetchImpl,
390
+ cooldownStore: store,
378
391
  }).catch((err: unknown) => {
379
392
  logger.warn(`[github] reconcile pass failed: ${err instanceof Error ? err.message : String(err)}`)
380
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
+ }
381
400
  }
382
401
  // Periodically recover inbound deliveries that failed at the tunnel and
383
402
  // were never redelivered (the cloudflare-quick 502 loss). Registered only
@@ -418,6 +437,10 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
418
437
  deliveryRecoveryTimer.clear()
419
438
  deliveryRecoveryTimer = null
420
439
  }
440
+ if (reconcileTimer !== null) {
441
+ reconcileTimer.clear()
442
+ reconcileTimer = null
443
+ }
421
444
  options.router.unregisterOutbound('github', outbound)
422
445
  options.router.unregisterReaction('github', reaction)
423
446
  options.router.unregisterRemoveReaction('github', removeReaction)
@@ -453,7 +476,7 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
453
476
  unregisterTokenBridge = null
454
477
  }
455
478
  await auth.dispose()
456
- delete process.env.GH_TOKEN
479
+ if (options.secrets.auth.type === 'pat') delete process.env.GH_TOKEN
457
480
  server = null
458
481
  selfId = null
459
482
  selfLogin = null
@@ -588,35 +611,6 @@ function logDeregistrationOutcome(
588
611
  }
589
612
  }
590
613
 
591
- type GhTokenSeedDecision =
592
- | { kind: 'seed'; context?: GithubAuthContext }
593
- | { kind: 'skip'; reason: 'no-repos' | 'multiple-owners' }
594
-
595
- const GH_TOKEN_SKIP_LOG: Record<'no-repos' | 'multiple-owners', string> = {
596
- 'no-repos':
597
- '[github] no repos[] configured; GH_TOKEN not seeded globally (cannot prove which App installation to use).',
598
- 'multiple-owners': '[github] repos span multiple owners (multiple App installations); GH_TOKEN not seeded globally.',
599
- }
600
-
601
- // Decides how to seed the process-wide GH_TOKEN. PATs aren't installation-scoped
602
- // (seed context-free). For App auth we seed from a configured repo slug, which
603
- // resolves the installation via repos/{owner}/{repo}/installation — the only
604
- // lookup that works for both org- and user-owned repos. One owner is required:
605
- // no-repos can't prove an installation, multi-owner needs >1 token.
606
- function ghTokenSeedDecision(authType: 'pat' | 'app', repos: readonly string[]): GhTokenSeedDecision {
607
- if (authType === 'pat') return { kind: 'seed' }
608
- const slugs = [...new Set(repos.filter(isWellFormedSlug))].sort()
609
- if (slugs.length === 0) return { kind: 'skip', reason: 'no-repos' }
610
- const owners = new Set(slugs.map((slug) => slug.split('/')[0]))
611
- if (owners.size > 1) return { kind: 'skip', reason: 'multiple-owners' }
612
- return { kind: 'seed', context: { repoSlug: slugs[0] } }
613
- }
614
-
615
- function isWellFormedSlug(repo: string): boolean {
616
- const [owner, name, ...rest] = repo.split('/')
617
- return owner !== undefined && owner !== '' && name !== undefined && name !== '' && rest.length === 0
618
- }
619
-
620
614
  // Canonical form for repos[] allowlist comparison so the gate can't be bypassed
621
615
  // by case, a trailing slash, or a `.git` suffix (GitHub treats owner/name
622
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
+ }