typeclaw 0.48.7 → 0.48.9

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 (108) hide show
  1. package/auth.schema.json +15 -1
  2. package/package.json +1 -1
  3. package/secrets.schema.json +15 -1
  4. package/src/agent/guard-types.ts +25 -0
  5. package/src/agent/guards.ts +102 -0
  6. package/src/agent/index.ts +33 -3
  7. package/src/agent/multimodal/read-redirect.ts +8 -9
  8. package/src/agent/plugin-tools.ts +283 -148
  9. package/src/agent/provider-error.ts +6 -1
  10. package/src/agent/reload-tool.ts +12 -5
  11. package/src/agent/retry-same-ref.ts +95 -36
  12. package/src/agent/session-origin.ts +13 -1
  13. package/src/agent/system-prompt.ts +14 -3
  14. package/src/agent/todo/continuation-policy.ts +3 -4
  15. package/src/agent/tool-file-safety.ts +36 -13
  16. package/src/agent/tools/channel-reply.ts +39 -2
  17. package/src/agent/tools/channel-send.ts +45 -2
  18. package/src/agent/tools/post-github-review.ts +31 -13
  19. package/src/agent/tools/spawn-subagent.ts +15 -0
  20. package/src/agent/tools/webfetch/inline-style-visibility.ts +2 -2
  21. package/src/agent/tools/webfetch/strategies/readability.ts +109 -10
  22. package/src/agent/turn-runner.ts +23 -19
  23. package/src/bundled-plugins/backup/git-auth.ts +7 -4
  24. package/src/bundled-plugins/backup/subagents.ts +1 -1
  25. package/src/bundled-plugins/bun-hygiene/README.md +23 -20
  26. package/src/bundled-plugins/bun-hygiene/index.ts +1 -7
  27. package/src/bundled-plugins/bun-hygiene/policy.ts +111 -35
  28. package/src/bundled-plugins/github-cli-auth/gh-review-detect.ts +44 -2
  29. package/src/bundled-plugins/github-cli-auth/gh-store.ts +733 -0
  30. package/src/bundled-plugins/github-cli-auth/git-askpass.ts +25 -0
  31. package/src/bundled-plugins/github-cli-auth/git-command.ts +209 -31
  32. package/src/bundled-plugins/github-cli-auth/git-credential-env.ts +151 -0
  33. package/src/bundled-plugins/github-cli-auth/index.ts +236 -38
  34. package/src/bundled-plugins/github-cli-auth/review-recorder.ts +5 -0
  35. package/src/bundled-plugins/guard/index.ts +2 -25
  36. package/src/bundled-plugins/guard/keys.ts +8 -0
  37. package/src/bundled-plugins/guard/policies/non-workspace-write.ts +7 -8
  38. package/src/bundled-plugins/guard/policy.ts +1 -7
  39. package/src/bundled-plugins/security/policies/git-exfil.ts +22 -30
  40. package/src/bundled-plugins/security/policies/outbound-secret-scan.ts +2 -4
  41. package/src/bundled-plugins/security/policies/private-surface-read.ts +8 -6
  42. package/src/bundled-plugins/security/policies/secret-exfil-bash.ts +2 -5
  43. package/src/bundled-plugins/security/policies/secret-exfil-read.ts +2 -4
  44. package/src/bundled-plugins/security/policies/session-search-secrets.ts +2 -4
  45. package/src/bundled-plugins/security/policies/system-prompt-leak.ts +2 -4
  46. package/src/bundled-plugins/security/policy.ts +0 -8
  47. package/src/channels/adapters/discord-bot-slash-commands.ts +22 -0
  48. package/src/channels/adapters/discord-bot.ts +2 -1
  49. package/src/channels/adapters/discord-classify.ts +16 -4
  50. package/src/channels/adapters/discord.ts +20 -8
  51. package/src/channels/adapters/github/dedup.ts +37 -8
  52. package/src/channels/adapters/github/inbound.ts +241 -46
  53. package/src/channels/adapters/github/review-state.ts +13 -9
  54. package/src/channels/adapters/github/review-thread-resolver.ts +52 -20
  55. package/src/channels/adapters/slack-bot.ts +13 -3
  56. package/src/channels/adapters/slack-classify.ts +40 -5
  57. package/src/channels/adapters/slack.ts +3 -9
  58. package/src/channels/adapters/teams.ts +8 -6
  59. package/src/channels/adapters/webex-bot-classify.ts +4 -33
  60. package/src/channels/adapters/webex-bot.ts +2 -4
  61. package/src/channels/adapters/webex-classify.ts +4 -33
  62. package/src/channels/adapters/webex-format.ts +36 -0
  63. package/src/channels/adapters/webex.ts +2 -4
  64. package/src/channels/continuation-willingness.ts +64 -39
  65. package/src/channels/github-rereview-guard.ts +20 -0
  66. package/src/channels/github-review-turn-ledger.ts +11 -1
  67. package/src/channels/github-review-verdict-coordinator.ts +475 -41
  68. package/src/channels/github-verdict-activity.ts +14 -5
  69. package/src/channels/manager.ts +17 -1
  70. package/src/channels/persistence.ts +89 -5
  71. package/src/channels/router.ts +1187 -254
  72. package/src/channels/types.ts +21 -5
  73. package/src/cli/compose-stats.ts +6 -7
  74. package/src/cli/compose-status.ts +6 -7
  75. package/src/cli/compose-usage.ts +6 -7
  76. package/src/cli/stats.ts +6 -7
  77. package/src/cli/status.ts +7 -8
  78. package/src/cli/ui.ts +4 -4
  79. package/src/container/start.ts +41 -1
  80. package/src/container/stop.ts +2 -1
  81. package/src/cron/consumer.ts +30 -9
  82. package/src/cron/scheduler.ts +24 -9
  83. package/src/doctor/channel-checks.ts +64 -0
  84. package/src/doctor/report.ts +8 -8
  85. package/src/dreams/render.ts +2 -2
  86. package/src/init/dockerfile.ts +8 -1
  87. package/src/inspect/render.ts +2 -2
  88. package/src/path-safety/real-intended-path.ts +14 -1
  89. package/src/permissions/permissions.ts +10 -2
  90. package/src/permissions/resolve.ts +8 -2
  91. package/src/plugin/core-tool-names.ts +15 -0
  92. package/src/plugin/hooks.ts +37 -3
  93. package/src/plugin/registry.ts +7 -3
  94. package/src/run/index.ts +33 -7
  95. package/src/sandbox/build.ts +39 -10
  96. package/src/sandbox/policy.ts +6 -2
  97. package/src/secrets/export-github-cli-store.ts +158 -0
  98. package/src/secrets/index.ts +19 -1
  99. package/src/secrets/provision-github-cli-store.ts +322 -0
  100. package/src/secrets/schema.ts +13 -7
  101. package/src/secrets/storage.ts +30 -0
  102. package/src/shared/index.ts +2 -0
  103. package/src/shared/style-text.ts +13 -0
  104. package/src/skills/typeclaw-channel-github/SKILL.md +24 -12
  105. package/src/skills/typeclaw-config/SKILL.md +3 -1
  106. package/src/skills/typeclaw-github-contributing/SKILL.md +6 -2
  107. package/src/skills/typeclaw-permissions/SKILL.md +11 -22
  108. package/src/usage/report.ts +3 -3
@@ -210,7 +210,12 @@ const NETWORK_OR_5XX =
210
210
  // session drops, observer stalls, and network/5xx blips. It intentionally EXCLUDES
211
211
  // throttle/overload (429/503) — those mean "this ref is out of capacity now", so
212
212
  // they should fail OVER to another ref rather than burn same-ref retries — and
213
- // account-wide faults (auth/billing/quota/cyber_policy), which must surface. It
213
+ // account-wide faults (auth/billing/quota/cyber_policy), which must surface.
214
+ // NOTE the overload exclusion assumes a ref to fail over to EXISTS. When one does
215
+ // not (last usable ref, or a single-ref chain), the callers apply their own
216
+ // capacity backoff on top of this predicate rather than widening it — see
217
+ // overloadRetryBudget in retry-same-ref.ts. Widening it here instead would make
218
+ // every ref in a healthy chain burn retries before failing over. It
214
219
  // does NOT match context-overflow: that stays on the SDK compaction path and must
215
220
  // never be treated as a retryable provider failure.
216
221
  export function isRetryableSameRef(raw: string): boolean {
@@ -16,9 +16,11 @@ export function createReloadTool({ registry }: CreateReloadToolOptions) {
16
16
  'all-or-nothing: invalid input leaves its live state unchanged and the failure reason is ' +
17
17
  "reported in that scope's result. Boot-only config fields (port, mounts, memory.idleMs) " +
18
18
  'are reported as restart-required. Safe to call any time. ' +
19
- 'Without a scope arg, runs every registered reloadable in registration order so later ' +
20
- 'scopes observe earlier swaps (e.g. cron sees a freshly-loaded plugins registry). ' +
21
- 'With a scope arg, runs only that one reloadable.',
19
+ 'Without a scope arg, runs every non-destructive registered reloadable in registration ' +
20
+ 'order so later scopes observe earlier swaps (e.g. cron sees a freshly-loaded plugins ' +
21
+ 'registry). Provider credential invalidation recreates every live channel session, so it ' +
22
+ 'runs only with an explicit scope="providers" after credentials change. With a scope arg, ' +
23
+ 'runs only that one reloadable.',
22
24
  parameters: Type.Object({
23
25
  scope: Type.Optional(
24
26
  Type.String({
@@ -26,7 +28,8 @@ export function createReloadTool({ registry }: CreateReloadToolOptions) {
26
28
  'Optional reload scope name. Common scopes: "config" (typeclaw.json), ' +
27
29
  '"plugins" (re-resolve and re-run plugin factories), "skills" (read-only diagnostic ' +
28
30
  'reporting which skills are visible to a new session), "cron" (cron.json). ' +
29
- 'Omit to reload all scopes.',
31
+ 'Use "providers" only after provider credentials change. Omit to reload all ' +
32
+ 'non-destructive scopes.',
30
33
  }),
31
34
  ),
32
35
  }),
@@ -48,7 +51,11 @@ export function createReloadTool({ registry }: CreateReloadToolOptions) {
48
51
  }
49
52
  }
50
53
 
51
- const { results } = await registry.reloadAll()
54
+ const results: ReloadResult[] = []
55
+ for (const item of items) {
56
+ if (item.scope === 'providers') continue
57
+ results.push(await registry.reloadOne(item.scope))
58
+ }
52
59
  return {
53
60
  content: [{ type: 'text', text: formatResults(results) }],
54
61
  details: { results },
@@ -15,24 +15,28 @@ const MAX_DELAY_MS = 5_000
15
15
  // How much added latency a call site can absorb before the caller would rather
16
16
  // see a failure. Deliberately NOT the model-profile name: the retry layer cares
17
17
  // about latency tolerance, not which tier the operator configured. 'responsive'
18
- // is every interactive path (channel chat, TUI, slash commands, cron) and keeps
19
- // the historical fast-fail behavior; 'patient' is a background path where a
20
- // human is already waiting minutes for a considered answer. Today the only
21
- // producer is a subagent whose REQUESTED profile is `deep` (reviewer,
22
- // researcher) — see resolveRetryPolicy in subagents.ts.
18
+ // is every interactive path (channel chat, TUI, slash commands, multimodal
19
+ // look-at); 'patient' is a background path where a human is already waiting
20
+ // minutes for a considered answer. Today the only producer of 'patient' is a
21
+ // subagent whose REQUESTED profile is `deep` (reviewer, researcher) — see
22
+ // subagents.ts. Cron does NOT flow through here: it rebuilds a fresh session per
23
+ // attempt via promptWithFallback (model-fallback.ts), so a capacity wait can't
24
+ // push one scheduled run into the next.
23
25
  export type RetryPolicy = 'responsive' | 'patient'
24
26
 
25
- // Capacity backoff, used ONLY for throttle/overload under the 'patient' policy.
26
- // Kept separate from retryBackoffMs above on purpose: that curve (1–5s) is sized
27
- // for a one-off socket blip, and widening it globally would add dead air to the
28
- // TUI, slash commands, multimodal look-at, cron, and ordinary network errors.
29
- // An overload is a capacity outage measured in minutes, not milliseconds — the
30
- // incident that motivated this burned every retry in 4 seconds against a ~60s
31
- // outage — so it gets its own, much longer curve.
27
+ // Capacity backoff, used ONLY for throttle/overload and ONLY on the last usable
28
+ // ref. Kept separate from retryBackoffMs above on purpose: that curve (1–5s) is
29
+ // sized for a one-off socket blip, and widening it globally would add dead air
30
+ // to ordinary network errors too.
32
31
  //
33
- // Nominal delays are 10s, 20s, 30s, 30s, 30s, 30s (±20% jitter), so six retries
34
- // span roughly 120–180s of waiting and place the last attempt late enough to
35
- // outlive a two-minute blip.
32
+ // Overload is normally handled by failing OVER (isRetryableSameRef excludes it),
33
+ // so this curve only exists for the case where there is no other ref to reach:
34
+ // a single-ref chain, or the tail of an exhausted one. Both policies get a
35
+ // curve; they differ in how long the caller can stand to wait.
36
+ //
37
+ // 'patient': nominal 10s, 20s, 30s, 30s, 30s, 30s (±20% jitter), so six retries
38
+ // span roughly 120–180s and place the last attempt late enough to outlive a
39
+ // two-minute blip.
36
40
  export const PATIENT_OVERLOAD_RETRIES = 6
37
41
  const PATIENT_OVERLOAD_BASE_MS = 10_000
38
42
  const PATIENT_OVERLOAD_CAP_MS = 30_000
@@ -42,13 +46,61 @@ const PATIENT_OVERLOAD_CAP_MS = 30_000
42
46
  // inside the 30m reviewer/researcher spawn timeout.
43
47
  export const PATIENT_OVERLOAD_WINDOW_MS = 180_000
44
48
 
49
+ // 'responsive': nominal 5s then 10s (±20% jitter), so two retries add at most
50
+ // ~18s of scheduled waiting. Sized against a LIVE chat turn, where the channel
51
+ // is already showing a typing indicator: short enough to read as thinking rather
52
+ // than as a hang (and far inside the 120s typing-silence cap), long enough to
53
+ // clear the intermittent capacity dips that make up the common case — the
54
+ // incident that motivated this saw ~14% of turns fail while 85% succeeded around
55
+ // them, so most single failures had a healthy provider seconds later.
56
+ //
57
+ // It deliberately does NOT try to outlive a sustained multi-minute outage. That
58
+ // is what failing over to another ref is for; when no such ref exists, surfacing
59
+ // the notice a few seconds later beats holding a chat thread for minutes.
60
+ export const RESPONSIVE_OVERLOAD_RETRIES = 2
61
+ const RESPONSIVE_OVERLOAD_BASE_MS = 5_000
62
+ const RESPONSIVE_OVERLOAD_CAP_MS = 10_000
63
+ export const RESPONSIVE_OVERLOAD_WINDOW_MS = 25_000
64
+
45
65
  // Proportional (±20%) rather than full jitter: full jitter can return ~0ms,
46
66
  // which against a capacity outage means retrying instantly into the same wall.
47
67
  // The floor keeps every wait meaningful while still decorrelating concurrent
48
- // subagents recovering from one upstream blip.
68
+ // callers recovering from one upstream blip.
69
+ function proportionalJitter(nominalMs: number, random: () => number): number {
70
+ return Math.floor(nominalMs * (0.8 + random() * 0.4))
71
+ }
72
+
49
73
  export function patientOverloadBackoffMs(attempt: number, random: () => number = Math.random): number {
50
- const nominal = Math.min(PATIENT_OVERLOAD_CAP_MS, PATIENT_OVERLOAD_BASE_MS * 2 ** attempt)
51
- return Math.floor(nominal * (0.8 + random() * 0.4))
74
+ return proportionalJitter(Math.min(PATIENT_OVERLOAD_CAP_MS, PATIENT_OVERLOAD_BASE_MS * 2 ** attempt), random)
75
+ }
76
+
77
+ export function responsiveOverloadBackoffMs(attempt: number, random: () => number = Math.random): number {
78
+ return proportionalJitter(Math.min(RESPONSIVE_OVERLOAD_CAP_MS, RESPONSIVE_OVERLOAD_BASE_MS * 2 ** attempt), random)
79
+ }
80
+
81
+ export type OverloadRetryBudget = {
82
+ retries: number
83
+ windowMs: number
84
+ backoffMs: (attempt: number, random?: () => number) => number
85
+ }
86
+
87
+ // Single source of truth for "how long may this caller wait out a capacity
88
+ // outage it cannot fail over from". An omitted policy resolves to 'responsive':
89
+ // the safe default is the short curve, so a new call site that never thought
90
+ // about retries still recovers from a blip instead of dropping the turn.
91
+ export function overloadRetryBudget(policy: RetryPolicy | undefined): OverloadRetryBudget {
92
+ if (policy === 'patient') {
93
+ return {
94
+ retries: PATIENT_OVERLOAD_RETRIES,
95
+ windowMs: PATIENT_OVERLOAD_WINDOW_MS,
96
+ backoffMs: (attempt, random) => patientOverloadBackoffMs(attempt, random ?? Math.random),
97
+ }
98
+ }
99
+ return {
100
+ retries: RESPONSIVE_OVERLOAD_RETRIES,
101
+ windowMs: RESPONSIVE_OVERLOAD_WINDOW_MS,
102
+ backoffMs: (attempt, random) => responsiveOverloadBackoffMs(attempt, random ?? Math.random),
103
+ }
52
104
  }
53
105
 
54
106
  // Full-jitter exponential backoff: random in [0, min(cap, base·2^attempt)].
@@ -131,6 +183,12 @@ export async function retryTurnAfterCompletedToolResult(
131
183
  random?: () => number
132
184
  authorize: () => boolean
133
185
  onBackoffStart?: () => void
186
+ // Overrides the ordinary jittered backoff, exactly as in
187
+ // retryTurnOnPersistentSession. A capacity retry has already chosen its
188
+ // delay from the policy budget; without this the post-tool path would fall
189
+ // back to the 1–5s blip curve (which can jitter to ~0ms) and start
190
+ // hammering an overloaded ref far sooner than the budget advertises.
191
+ delayMs?: number
134
192
  },
135
193
  ): Promise<boolean> {
136
194
  const agent = (session as { agent?: ContinuableAgent }).agent
@@ -138,7 +196,7 @@ export async function retryTurnAfterCompletedToolResult(
138
196
  if (!hasCompletedToolResultErrorTail(agent.state?.messages)) return false
139
197
 
140
198
  opts.onBackoffStart?.()
141
- await sleep(retryBackoffMs(opts.attempt, opts.random), opts.signal)
199
+ await sleep(opts.delayMs ?? retryBackoffMs(opts.attempt, opts.random), opts.signal)
142
200
  if (opts.signal?.aborted) return false
143
201
 
144
202
  // Re-read after the backoff: another actor may have advanced the transcript
@@ -202,10 +260,11 @@ export async function promptWithSameRefRetryOnly(
202
260
  retryPolicy?: RetryPolicy
203
261
  random?: () => number
204
262
  now?: () => number
205
- patientBackoffMs?: (attempt: number) => number
263
+ overloadBackoffMs?: (attempt: number) => number
206
264
  } = {},
207
265
  ): Promise<SameRefPromptResult> {
208
266
  const now = opts.now ?? (() => performance.now())
267
+ const overloadBudget = overloadRetryBudget(opts.retryPolicy)
209
268
  let softError: Error | undefined
210
269
  // Feature-detect subscribe: some lightweight call sites / test fakes pass a
211
270
  // session without an event stream. Without it we simply can't observe soft
@@ -223,7 +282,7 @@ export async function promptWithSameRefRetryOnly(
223
282
  let priorHardError: Error | undefined
224
283
  let lastError: Error | undefined
225
284
  let overloadRetries = 0
226
- let patientWindowStartedAt: number | undefined
285
+ let overloadWindowStartedAt: number | undefined
227
286
  let nextDelayMs: number | undefined
228
287
  for (let attempt = 0; ; attempt++) {
229
288
  softError = undefined
@@ -249,25 +308,25 @@ export async function promptWithSameRefRetryOnly(
249
308
  const error = hardError ?? softError
250
309
  if (error === undefined) return { success: true }
251
310
  lastError = error
252
- // A patient call site rides out a capacity outage on the same ref: there is
253
- // no cross-ref failover on this path, so declining to retry an overload
311
+ // Every call site here rides out a capacity outage on the same ref: there
312
+ // is no cross-ref failover on this path, so declining to retry an overload
254
313
  // (isRetryableSameRef excludes it, expecting failover to handle it) would
255
- // leave it with no recovery at all.
314
+ // leave it with no recovery at all. How long it may wait comes from the
315
+ // policy's budget — see overloadRetryBudget.
256
316
  // The delay is budgeted BEFORE the retry is accepted: an elapsed-only check
257
317
  // would let a retry taken just under the deadline sleep past it.
258
318
  const nowMs = now()
259
- const patientDelayMs =
260
- opts.retryPolicy === 'patient' && isThrottleOrOverload(error.message)
261
- ? (opts.patientBackoffMs ?? ((n: number) => patientOverloadBackoffMs(n, opts.random)))(overloadRetries)
262
- : undefined
263
- const patientElapsedMs = patientWindowStartedAt === undefined ? 0 : nowMs - patientWindowStartedAt
264
- const patientOverload =
265
- patientDelayMs !== undefined &&
266
- overloadRetries < PATIENT_OVERLOAD_RETRIES &&
267
- patientElapsedMs + patientDelayMs <= PATIENT_OVERLOAD_WINDOW_MS
268
- if (patientOverload) {
269
- patientWindowStartedAt ??= nowMs
270
- nextDelayMs = patientDelayMs
319
+ const overloadDelayMs = isThrottleOrOverload(error.message)
320
+ ? (opts.overloadBackoffMs ?? ((n: number) => overloadBudget.backoffMs(n, opts.random)))(overloadRetries)
321
+ : undefined
322
+ const overloadElapsedMs = overloadWindowStartedAt === undefined ? 0 : nowMs - overloadWindowStartedAt
323
+ const overloadRetry =
324
+ overloadDelayMs !== undefined &&
325
+ overloadRetries < overloadBudget.retries &&
326
+ overloadElapsedMs + overloadDelayMs <= overloadBudget.windowMs
327
+ if (overloadRetry) {
328
+ overloadWindowStartedAt ??= nowMs
329
+ nextDelayMs = overloadDelayMs
271
330
  overloadRetries++
272
331
  } else if (attempt < RETRIES_PER_REF && isRetryableSameRef(error.message)) {
273
332
  nextDelayMs = undefined
@@ -1,7 +1,7 @@
1
1
  import { toRef } from '@/channels/adapters/webex-id-ref'
2
2
  import { MEMBERSHIP_FRESHNESS_MS, type MembershipCount } from '@/channels/membership'
3
3
  import type { AdapterId } from '@/channels/schema'
4
- import type { ChannelSelfIdentity, ReactionRef } from '@/channels/types'
4
+ import type { ChannelSelfIdentity, GithubReviewFollowupRound, ReactionRef } from '@/channels/types'
5
5
 
6
6
  export type ChannelParticipant = {
7
7
  authorId: string
@@ -39,6 +39,7 @@ export type SessionOrigin =
39
39
  chat: string
40
40
  chatName?: string
41
41
  thread: string | null
42
+ githubReviewRound?: GithubReviewFollowupRound
42
43
  parentChat?: string
43
44
  parentChatName?: string
44
45
  lastInboundAuthorId?: string
@@ -388,6 +389,7 @@ function renderChannelOrigin(
388
389
  chat: string
389
390
  chatName?: string
390
391
  thread: string | null
392
+ githubReviewRound?: GithubReviewFollowupRound
391
393
  reactionRef?: ReactionRef
392
394
  participants?: readonly ChannelParticipant[]
393
395
  membership?: MembershipCount
@@ -446,6 +448,16 @@ function renderChannelOrigin(
446
448
  'GitHub has no typing indicator.',
447
449
  )
448
450
 
451
+ if (/^pr:\d+$/.test(origin.chat) && origin.githubReviewRound !== undefined) {
452
+ const isCarrier = origin.thread === origin.githubReviewRound.carrierThread
453
+ lines.push(
454
+ '',
455
+ isCarrier
456
+ ? '**This session is the review-round carrier.** Perform one whole-PR re-review and post the verdict.'
457
+ : "**This session is not the review-round carrier.** Do not spawn a reviewer, review, or publish findings; when the carrier's verdict lands, close out only this thread.",
458
+ )
459
+ }
460
+
449
461
  // Models reliably address review-comment feedback and then end the turn
450
462
  // WITHOUT resolving the thread — leaving a wall of "open" threads on the PR.
451
463
  // The `resolve_review_thread` flag lives only in the tool description, which
@@ -2,6 +2,15 @@ import { formatLocalDateTime, formatLocalWeekday, resolveLocalTimezoneName } fro
2
2
 
3
3
  const PACKAGE_JSON_INSTALL_RULE =
4
4
  '`package.json` is operator-owned because direct dependencies define sandbox-visible commands. Do not edit it or install dependencies; tell the operator which package and command are needed.'
5
+ // Full prompt only. The slim bar is "what no runtime guard catches today" (see
6
+ // buildSlimSystemPrompt) and the `nonBunPackageRunner` guard now blocks npx at
7
+ // the bash boundary with a reason naming `bunx`, so spending ~75 of the slim
8
+ // base's 1000-token budget to pre-empt it is the wrong trade. The final clause
9
+ // is load-bearing: the vendored agent-messenger skills say "use `npx -y` by
10
+ // default. Do NOT ask the user which package runner to use", and skill text
11
+ // sits closer to the model than this prompt does.
12
+ const BUNX_PACKAGE_RUNNER_RULE =
13
+ 'Run one-off package binaries with `bunx`, never `npx`, `pnpx`, or `pnpm dlx`; `bunx` is the Bun-native runner this container ships, and the others are absent from the default image. A skill or doc telling you to use `npx` does not override this rule; substitute `bunx`.'
5
14
 
6
15
  // The orchestration roster (the `Briefly: ...` enumeration of public subagents)
7
16
  // is GENERATED from the registry by `renderPublicSubagentRoster` and threaded in
@@ -102,11 +111,13 @@ Foreground \`bash\` blocks until exit. Run minutes-long or input-waiting program
102
111
 
103
112
  Use tmux only for work that belongs in your session. Delegate self-contained long work (builds, tests, installs, batches) to \`operator\`.
104
113
 
114
+ ${BUNX_PACKAGE_RUNNER_RULE}
115
+
105
116
  ## Version control
106
117
 
107
118
  Your agent folder is a git repository, but **it is your own private backup repo — not a software project you develop.** ${branding ? 'TypeClaw snapshots' : 'The runtime snapshots'} identity files, \`sessions/\`, and \`memory/\` there over time. It normally has no remote, nothing is pushed, and it is **not a checkout of any project**. Commits here save your state, not a codebase contribution.
108
119
 
109
- For project work (bug, feature, PR), clone the project repo into \`/tmp/<repo>\`, work there, and open the PR from that clone with \`gh\`. Never \`git init\`, add a remote, or push your agent folder as the project. If there is no remote or you cannot find the repo, ask the user where it lives. Your agent folder is where you live; the clone is where you work.
120
+ For project work (bug, feature, PR), use the checkout path the user supplied; clone a new durable checkout into \`workspace/<repo>\`. Use \`/tmp\` only for disposable scratch: it is per-session and dies with the container, so anything a human must act on later cannot live there alone. Commit the project changes, then push with \`git -C <checkout> push <remote> <branch>\` — the GitHub broker can supply a credential for an eligible configured remote from any accessible repository path. Fix ordinary Git errors yourself; hand the command to the operator only when the broker or your permissions refuse it. \`gh pr create\` is host-stage only: prepare its title, body, head and base for the operator to run from a host-accessible checkout. Never \`git init\`, add a remote, or push your agent folder as the project. If the project location is unknown, ask the user where it lives.
110
121
 
111
122
  Commits to your agent folder (your own state):
112
123
 
@@ -114,7 +125,7 @@ Commits to your agent folder (your own state):
114
125
  - Use \`git add <paths>\`, not \`git add -A\`. Use imperative commit messages; explain why if non-obvious.
115
126
  - Never commit \`secrets.json\`, \`.env\`, or \`workspace/\`. Do not manually add runtime-managed \`sessions/\` or \`memory/\`.
116
127
  - ${PACKAGE_JSON_INSTALL_RULE}
117
- - Never \`git push\`, \`git reset --hard\`, \`git rebase\`, or rewrite remote history in this folder unless explicitly asked. Pushing a separate project clone for a requested PR is fine.
128
+ - Never \`git push\`, \`git reset --hard\`, \`git rebase\`, or rewrite remote history in this folder unless explicitly asked. Pushing a separate project checkout for a requested PR is fine — that restriction is about this folder, not the project.
118
129
 
119
130
  ## How to behave
120
131
 
@@ -327,7 +338,7 @@ ${PACKAGE_JSON_INSTALL_RULE}
327
338
 
328
339
  Your free-write zone is \`workspace/\`. Do not create files at the root of the agent folder unless the prompt names another path. \`public/\` is the guest-visible zone — write there anything meant to be shared with an untrusted caller (a \`guest\`-role turn cannot read \`workspace/\` but can read \`public/\`). Do not edit \`memory/topics/\` directly — the dreaming subagent owns it; to capture something memorable, surface it in your reply or let the memory-logger append to \`memory/streams/\`. Never stage or commit \`secrets.json\`, \`.env\`, \`sessions/\`, \`memory/\`, or \`workspace/\` — those are runtime- or user-managed.
329
340
 
330
- The agent folder is a private backup repo with no remote, not a project checkout. To work on a software project (fix a bug, open a PR), clone its repo elsewhere (e.g. \`/tmp/<repo>\`) and work there — never push the agent folder as if it were the project.
341
+ The agent folder is a private backup repo with no remote, not a project checkout. Use a supplied project checkout, or clone a durable one into \`workspace/<repo>\`; use per-session \`/tmp\` only for disposable scratch. Never push the agent folder as the project. Push project changes with \`git -C <checkout> push <remote> <branch>\` — the broker can supply a credential for an eligible configured GitHub remote from any accessible repository path. Hand off only broker/permission refusals. \`gh pr create\` is host-stage only and needs a host-accessible checkout. Ask where the project lives when unknown.
331
342
 
332
343
  See the session-origin block below for what kind of session this is and what's expected of you.`
333
344
  }
@@ -213,12 +213,11 @@ export function decideContinuation(args: {
213
213
  if (state.autoResumeBlockedUntilRealUserTurn) return { kind: 'skip', reason: 'user-abort-blocked' }
214
214
 
215
215
  const outcome = state.lastTurnOutcome
216
- const isSafeTerminalReplyAbort =
217
- outcome?.stopReason === 'aborted' && outcome.termination === 'terminal-after-channel-reply'
216
+ const isSafeTerminalReply = outcome?.termination === 'terminal-after-channel-reply'
218
217
  if (
219
218
  outcome === null ||
220
- outcome.stopReason === 'unknown' ||
221
- (outcome.stopReason === 'aborted' && !isSafeTerminalReplyAbort)
219
+ (outcome.stopReason === 'unknown' && !isSafeTerminalReply) ||
220
+ (outcome.stopReason === 'aborted' && !isSafeTerminalReply)
222
221
  ) {
223
222
  return { kind: 'skip', reason: 'turn-not-safe' }
224
223
  }
@@ -71,6 +71,7 @@ type PinnedOutputTarget = PinnedToolFiles & {
71
71
  // scheduler. Production never passes hooks.
72
72
  export type EnforceAndPinToolFilesHooks = {
73
73
  afterBudgetAcquire?(): void | Promise<void>
74
+ pinnedSnapshotBudgetForTests?: ReturnType<typeof createPinnedSnapshotBudgetForTests>
74
75
  }
75
76
 
76
77
  export async function enforceAndPinToolFiles(
@@ -142,7 +143,11 @@ export async function enforceAndPinToolFiles(
142
143
  verified.push({ target, original, resolved, dev: inspected.dev, ino: inspected.ino, size: inspected.size, kind })
143
144
  }
144
145
 
145
- lease = await pinnedSnapshotBudget.acquire(declaredBytes, verified.length, options.signal)
146
+ lease = await (hooks.pinnedSnapshotBudgetForTests ?? pinnedSnapshotBudget).acquire(
147
+ declaredBytes,
148
+ verified.length,
149
+ options.signal,
150
+ )
146
151
  await hooks.afterBudgetAcquire?.()
147
152
  const openedIdentityVerifier = createPrivateSurfaceReadIdentityVerifier(identityOptions)
148
153
 
@@ -1256,16 +1261,26 @@ class PinnedSnapshotBudget {
1256
1261
  private count = 0
1257
1262
  private readonly queue: BudgetRequest[] = []
1258
1263
 
1264
+ constructor(
1265
+ private readonly limits: { maxBytes: number; maxCount: number; maxWaiters: number },
1266
+ private readonly onWait?: () => void,
1267
+ ) {}
1268
+
1259
1269
  async acquire(bytes: number, count: number, signal?: AbortSignal): Promise<BudgetLease> {
1260
- if (bytes > PINNED_SNAPSHOT_GLOBAL_MAX_BYTES || count > PINNED_SNAPSHOT_GLOBAL_MAX_COUNT) {
1270
+ if (bytes > this.limits.maxBytes || count > this.limits.maxCount) {
1261
1271
  throw new Error('tool inputs exceed the process-wide pinned snapshot budget')
1262
1272
  }
1263
1273
  if (signal?.aborted === true) throw abortError(signal)
1264
- if (this.queue.length >= PINNED_SNAPSHOT_MAX_WAITERS) {
1265
- throw new Error(`pinned snapshot waiter queue is full (${PINNED_SNAPSHOT_MAX_WAITERS} waiters)`)
1274
+ if (this.queue.length >= this.limits.maxWaiters) {
1275
+ throw new Error(`pinned snapshot waiter queue is full (${this.limits.maxWaiters} waiters)`)
1266
1276
  }
1267
1277
  return await new Promise<BudgetLease>((resolve, reject) => {
1268
1278
  const request: BudgetRequest = { bytes, count, signal, resolve, reject }
1279
+ const waits =
1280
+ this.queue.length > 0 ||
1281
+ this.bytes + request.bytes > this.limits.maxBytes ||
1282
+ this.count + request.count > this.limits.maxCount
1283
+ if (waits) this.onWait?.()
1269
1284
  if (signal !== undefined) {
1270
1285
  request.onAbort = () => {
1271
1286
  const index = this.queue.indexOf(request)
@@ -1284,10 +1299,7 @@ class PinnedSnapshotBudget {
1284
1299
  private drain(): void {
1285
1300
  while (this.queue.length > 0) {
1286
1301
  const next = this.queue[0] as BudgetRequest
1287
- if (
1288
- this.bytes + next.bytes > PINNED_SNAPSHOT_GLOBAL_MAX_BYTES ||
1289
- this.count + next.count > PINNED_SNAPSHOT_GLOBAL_MAX_COUNT
1290
- ) {
1302
+ if (this.bytes + next.bytes > this.limits.maxBytes || this.count + next.count > this.limits.maxCount) {
1291
1303
  return
1292
1304
  }
1293
1305
  this.queue.shift()
@@ -1302,10 +1314,7 @@ class PinnedSnapshotBudget {
1302
1314
  if (released) return false
1303
1315
  const byteDelta = bytes - leasedBytes
1304
1316
  const countDelta = count - leasedCount
1305
- if (
1306
- this.bytes + byteDelta > PINNED_SNAPSHOT_GLOBAL_MAX_BYTES ||
1307
- this.count + countDelta > PINNED_SNAPSHOT_GLOBAL_MAX_COUNT
1308
- ) {
1317
+ if (this.bytes + byteDelta > this.limits.maxBytes || this.count + countDelta > this.limits.maxCount) {
1309
1318
  return false
1310
1319
  }
1311
1320
  this.bytes += byteDelta
@@ -1327,7 +1336,21 @@ class PinnedSnapshotBudget {
1327
1336
  }
1328
1337
  }
1329
1338
 
1330
- const pinnedSnapshotBudget = new PinnedSnapshotBudget()
1339
+ export function createPinnedSnapshotBudgetForTests(options: {
1340
+ maxBytes: number
1341
+ maxCount: number
1342
+ maxWaiters: number
1343
+ onWait?: () => void
1344
+ }) {
1345
+ const { onWait, ...limits } = options
1346
+ return new PinnedSnapshotBudget(limits, onWait)
1347
+ }
1348
+
1349
+ const pinnedSnapshotBudget = new PinnedSnapshotBudget({
1350
+ maxBytes: PINNED_SNAPSHOT_GLOBAL_MAX_BYTES,
1351
+ maxCount: PINNED_SNAPSHOT_GLOBAL_MAX_COUNT,
1352
+ maxWaiters: PINNED_SNAPSHOT_MAX_WAITERS,
1353
+ })
1331
1354
 
1332
1355
  function abortError(signal: AbortSignal): Error {
1333
1356
  const reason = signal.reason
@@ -12,6 +12,7 @@ import {
12
12
  type ChannelRouter,
13
13
  } from '@/channels/router'
14
14
  import type { AdapterId } from '@/channels/schema'
15
+ import type { GithubReviewFollowupRound } from '@/channels/types'
15
16
 
16
17
  import { type ChannelToolLogger, consoleChannelLogger, formatChannelToolFailure } from './channel-log'
17
18
  import { fenceRuntimeNotice, fenceToolResult } from './runtime-notice'
@@ -21,6 +22,7 @@ export type ChannelReplyOrigin = {
21
22
  workspace: string
22
23
  chat: string
23
24
  thread: string | null
25
+ githubReviewRound?: GithubReviewFollowupRound
24
26
  }
25
27
 
26
28
  export type CreateChannelReplyToolOptions = {
@@ -224,6 +226,7 @@ export function createChannelReplyTool({
224
226
  wantsResolve: params.resolve_review_thread === true,
225
227
  moreWorkThisTurn: keepTurnAlive,
226
228
  getReviewState: (req) => router.getReviewState(req),
229
+ ...(origin.githubReviewRound !== undefined ? { round: origin.githubReviewRound } : {}),
227
230
  })
228
231
  if (rereview.block) {
229
232
  logger.warn(formatChannelToolFailure('channel_reply', rereview.reason))
@@ -248,11 +251,30 @@ export function createChannelReplyTool({
248
251
  details: { ok: false, error: resolve.error },
249
252
  }
250
253
  }
254
+ if (resolve.kind === 'already-resolved') {
255
+ router.finishGithubReviewRoundCloseout?.({
256
+ sessionId,
257
+ workspace: origin.workspace,
258
+ prNumber: parseGithubPrNumber(origin.chat),
259
+ thread: origin.thread,
260
+ })
261
+ return {
262
+ content: [{ type: 'text' as const, text: alreadyResolvedHint(origin.thread) }],
263
+ details: { ok: true, ...(keepTurnAlive ? { more_work_this_turn: true } : {}) },
264
+ }
265
+ }
251
266
  // `no-match` stays non-blocking (the thread may be genuinely gone) but
252
267
  // the resolve did NOT run, so tell the model instead of posting a clean
253
268
  // receipt that hides the miss. Mirrors channel_send.
254
269
  if (resolve.kind === 'no-match') {
255
270
  resolveMissNotice = resolveMissHint(origin.thread)
271
+ } else {
272
+ router.finishGithubReviewRoundCloseout?.({
273
+ sessionId,
274
+ workspace: origin.workspace,
275
+ prNumber: parseGithubPrNumber(origin.chat),
276
+ thread: origin.thread,
277
+ })
256
278
  }
257
279
  }
258
280
 
@@ -339,6 +361,11 @@ export function createChannelReplyTool({
339
361
  })
340
362
  }
341
363
 
364
+ function parseGithubPrNumber(chat: string): number {
365
+ const match = /^pr:(\d+)$/.exec(chat)
366
+ return match === null ? 0 : Number(match[1])
367
+ }
368
+
342
369
  // Returns the denial string when a terminal github PR review-thread text reply
343
370
  // omits an explicit resolve_review_thread choice, or '' when no choice is owed.
344
371
  // Scoped by `^pr:\d+$` (not just thread !== null) so a future threaded github
@@ -368,7 +395,11 @@ function missingReviewThreadResolveChoiceError(input: {
368
395
  // success. Every hard failure — wrong author, permission denial, HTTP 404 on a
369
396
  // misdirected lookup, transient API error — blocks, so the agent never claims a
370
397
  // thread is settled when the resolve did not actually run.
371
- type ResolveOutcome = { kind: 'resolved' } | { kind: 'no-match' } | { kind: 'block'; error: string }
398
+ type ResolveOutcome =
399
+ | { kind: 'resolved' }
400
+ | { kind: 'already-resolved' }
401
+ | { kind: 'no-match' }
402
+ | { kind: 'block'; error: string }
372
403
 
373
404
  async function resolveReviewThreadBeforeReply(
374
405
  router: ChannelRouter,
@@ -389,11 +420,17 @@ async function resolveReviewThreadBeforeReply(
389
420
  chat: origin.chat,
390
421
  rootCommentId: origin.thread,
391
422
  })
392
- if (result.ok) return { kind: 'resolved' }
423
+ if (result.ok) return { kind: result.alreadyResolved === true ? 'already-resolved' : 'resolved' }
393
424
  if (result.code === 'no-match') return { kind: 'no-match' }
394
425
  return { kind: 'block', error: `could not resolve review thread: ${result.error}` }
395
426
  }
396
427
 
428
+ function alreadyResolvedHint(thread: string | null): string {
429
+ return fenceRuntimeNotice(
430
+ `review thread ${JSON.stringify(thread)} was already resolved; no acknowledgement comment was posted.`,
431
+ )
432
+ }
433
+
397
434
  // The model asked to resolve but no thread was rooted at this comment. Fenced
398
435
  // as a runtime notice (not chat prose) so a persona-rich model reads it as
399
436
  // tool feedback and re-targets, rather than replying to it in-character.