typeclaw 0.39.3 → 0.39.5

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 (55) hide show
  1. package/package.json +1 -1
  2. package/src/agent/attention-escalation.ts +11 -1
  3. package/src/agent/index.ts +10 -14
  4. package/src/agent/model-fallback.ts +13 -4
  5. package/src/agent/provider-error.ts +36 -1
  6. package/src/agent/subagents.ts +34 -3
  7. package/src/agent/throttle-circuit.ts +50 -0
  8. package/src/agent/tools/channel-reply.ts +48 -3
  9. package/src/agent/tools/ddg.ts +40 -5
  10. package/src/agent/tools/keyed-semaphore.ts +114 -0
  11. package/src/agent/tools/search-retry.ts +82 -0
  12. package/src/agent/turn-runner.ts +162 -0
  13. package/src/bundled-plugins/explorer/explorer.ts +5 -0
  14. package/src/bundled-plugins/memory/README.md +14 -14
  15. package/src/bundled-plugins/memory/append-tool.ts +98 -8
  16. package/src/bundled-plugins/memory/dreaming.ts +1 -1
  17. package/src/bundled-plugins/memory/fragment-parser.ts +10 -3
  18. package/src/bundled-plugins/memory/load-memory.ts +28 -2
  19. package/src/bundled-plugins/memory/memory-logger.ts +21 -5
  20. package/src/bundled-plugins/memory/search-tool.ts +50 -7
  21. package/src/bundled-plugins/memory/stream-events.ts +23 -0
  22. package/src/bundled-plugins/memory/vector/hybrid.ts +9 -2
  23. package/src/bundled-plugins/reviewer/reviewer.ts +3 -1
  24. package/src/bundled-plugins/scout/scout.ts +5 -0
  25. package/src/bundled-plugins/security/index.ts +24 -1
  26. package/src/bundled-plugins/security/policies/cron-promotion.ts +94 -62
  27. package/src/bundled-plugins/security/policies/plugin-addition.ts +2 -4
  28. package/src/bundled-plugins/security/policies/role-promotion.ts +2 -4
  29. package/src/channels/adapters/github/permission-guidance.ts +18 -0
  30. package/src/channels/adapters/webex-bot.ts +26 -25
  31. package/src/channels/adapters/webex-prefetch-limiter.ts +120 -0
  32. package/src/channels/adapters/webex.ts +27 -30
  33. package/src/channels/manager.ts +64 -57
  34. package/src/channels/router.ts +134 -4
  35. package/src/channels/types.ts +8 -1
  36. package/src/cli/builtins.ts +6 -32
  37. package/src/cli/channel.ts +7 -11
  38. package/src/cli/command-meta.ts +93 -0
  39. package/src/cli/help.ts +24 -0
  40. package/src/cli/index.ts +34 -10
  41. package/src/cli/init.ts +2 -2
  42. package/src/cli/plugin-commands-dispatch.ts +7 -1
  43. package/src/config/config.ts +27 -1
  44. package/src/container/start.ts +22 -2
  45. package/src/hostd/daemon.ts +55 -26
  46. package/src/hostd/spawn.ts +53 -19
  47. package/src/permissions/permissions.ts +12 -0
  48. package/src/run/codex-fetch-observer.ts +11 -6
  49. package/src/secrets/oauth-xai.ts +2 -2
  50. package/src/server/index.ts +27 -2
  51. package/src/skills/typeclaw-channel-github/SKILL.md +59 -13
  52. package/src/skills/typeclaw-channels/SKILL.md +1 -1
  53. package/src/skills/typeclaw-config/SKILL.md +1 -0
  54. package/src/skills/typeclaw-cron/SKILL.md +9 -4
  55. package/src/skills/typeclaw-permissions/SKILL.md +18 -6
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "typeclaw",
3
- "version": "0.39.3",
3
+ "version": "0.39.5",
4
4
  "homepage": "https://github.com/typeclaw/typeclaw#readme",
5
5
  "bugs": {
6
6
  "url": "https://github.com/typeclaw/typeclaw/issues"
@@ -715,11 +715,20 @@ export function detectAttentionEscalation(text: string, prior?: QuestionSignal |
715
715
  // unconditionally and gives OpenAI models maximum effort on escalation turns.
716
716
  const ESCALATED_LEVEL: ThinkingLevel = 'xhigh'
717
717
 
718
+ // `allowEscalation: false` pins the turn to `sessionDefault`. Subagent turns set
719
+ // it because their "user prompt" is composed by another agent, not a human — so
720
+ // the question-mark/frustration heuristics would misread a multi-question brief
721
+ // and silently bump a `fast`/`low` worker to `xhigh`. Default `true` keeps the
722
+ // human-facing sessions (TUI, channels, cron) escalating as before.
723
+ export type TurnThinkingOptions = { allowEscalation?: boolean }
724
+
718
725
  export function resolveTurnThinkingLevel(
719
726
  text: string,
720
727
  sessionDefault: ThinkingLevel | undefined,
721
728
  prior?: QuestionSignal | null,
729
+ options?: TurnThinkingOptions,
722
730
  ): ThinkingLevel | undefined {
731
+ if (options?.allowEscalation === false) return sessionDefault
723
732
  return detectAttentionEscalation(text, prior) ? ESCALATED_LEVEL : sessionDefault
724
733
  }
725
734
 
@@ -735,7 +744,8 @@ export function applyTurnThinkingLevel(
735
744
  text: string,
736
745
  sessionDefault: ThinkingLevel | undefined,
737
746
  prior?: QuestionSignal | null,
747
+ options?: TurnThinkingOptions,
738
748
  ): void {
739
- const resolved = resolveTurnThinkingLevel(text, sessionDefault, prior)
749
+ const resolved = resolveTurnThinkingLevel(text, sessionDefault, prior, options)
740
750
  if (resolved !== undefined) session.setThinkingLevel(resolved)
741
751
  }
@@ -244,26 +244,22 @@ export type CreateSessionResult = {
244
244
  }
245
245
 
246
246
  // A session's reasoning effort layers like the model does: the resolved
247
- // profile's own `thinkingLevel` → the built-in `deep` default → the `default`
248
- // profile's `thinkingLevel` (the de-facto global default) → the per-provider/SDK
249
- // default for the active ref. When the requested profile was unknown, `resolved`
250
- // is already the `default` profile, so those terms coincide and the expression
251
- // still does the right thing.
247
+ // profile's own `thinkingLevel` → the `default` profile's `thinkingLevel` (the
248
+ // de-facto global default) → the per-provider/SDK default for the active ref.
249
+ // When the requested profile was unknown, `resolved` is already the `default`
250
+ // profile, so those terms coincide and the expression still does the right thing.
252
251
  //
253
- // The `deep` `high` default sits ABOVE `models.default.thinkingLevel` on purpose:
254
- // lowering the global default must not stop the "think hard" profile from
255
- // thinking hard. `high` (not `xhigh`) because `xhigh` ~doubles latency and token
256
- // spend for no agentic-quality gain. An explicit `models.deep.thinkingLevel`
257
- // still wins — it is the first term.
258
- const DEEP_PROFILE_DEFAULT_THINKING_LEVEL: ThinkingLevel = 'high'
259
-
252
+ // Built-in per-profile defaults (e.g. `fast: 'low'`, `deep: 'high'`) are
253
+ // materialized onto the entry at config-parse time (see PROFILE_THINKING_LEVEL_DEFAULTS
254
+ // in config.ts), so they arrive here as `resolved.thinkingLevel` — the first term.
255
+ // That is why `deep`'s `high` still beats a lowered global default, and why there
256
+ // is no profile special-casing in this function.
260
257
  export function resolveSessionThinkingLevel(
261
258
  models: Models,
262
259
  resolved: Pick<ResolvedProfile, 'thinkingLevel' | 'profile'>,
263
260
  activeRef: ModelRef,
264
261
  ): ThinkingLevel | undefined {
265
- const deepDefault = resolved.profile === 'deep' ? DEEP_PROFILE_DEFAULT_THINKING_LEVEL : undefined
266
- return resolved.thinkingLevel ?? deepDefault ?? models.default.thinkingLevel ?? defaultThinkingLevelForRef(activeRef)
262
+ return resolved.thinkingLevel ?? models.default.thinkingLevel ?? defaultThinkingLevelForRef(activeRef)
267
263
  }
268
264
 
269
265
  export async function createSession(options: CreateSessionOptions = {}): Promise<AgentSession> {
@@ -71,10 +71,17 @@ export async function promptWithFallback<TRef extends FallbackModelRef>(opts: {
71
71
  // Called after each non-final attempt so callers can log the per-attempt
72
72
  // failure with their own context (sessionId, channel key, job id, ...).
73
73
  onAttemptFailed?: (attempt: FallbackAttempt<TRef>) => void
74
+ // Gate that decides whether a given failure is worth advancing the chain.
75
+ // Omitted (cron) means "advance on any error" — the original behavior.
76
+ // Interactive callers pass `isThrottleOrOverload` so a one-off real error
77
+ // (billing, malformed response) surfaces on the active ref instead of
78
+ // silently switching providers.
79
+ shouldFailover?: (err: Error) => boolean
74
80
  }): Promise<FallbackPromptResult<TRef>> {
75
81
  if (opts.refs.length === 0) {
76
82
  throw new Error('promptWithFallback: refs[] must be non-empty')
77
83
  }
84
+ const failoverGate = opts.shouldFailover ?? (() => true)
78
85
  const attempts: FallbackAttempt<TRef>[] = []
79
86
  let lastError: Error | undefined
80
87
  for (let i = 0; i < opts.refs.length; i++) {
@@ -97,10 +104,11 @@ export async function promptWithFallback<TRef extends FallbackModelRef>(opts: {
97
104
  const attempt: FallbackAttempt<TRef> = { ref, outcome: 'hard', errorMessage: error.message }
98
105
  attempts.push(attempt)
99
106
  lastError = error
100
- if (!isLast) opts.onAttemptFailed?.(attempt)
107
+ const stop = isLast || !failoverGate(error)
108
+ if (!stop) opts.onAttemptFailed?.(attempt)
101
109
  unsub()
102
110
  await dispose()
103
- if (isLast) {
111
+ if (stop) {
104
112
  return { success: false, refUsed: ref, attempts, session, dispose: async () => {}, lastError }
105
113
  }
106
114
  continue
@@ -109,10 +117,11 @@ export async function promptWithFallback<TRef extends FallbackModelRef>(opts: {
109
117
  const attempt: FallbackAttempt<TRef> = { ref, outcome: 'soft', errorMessage: softError.message }
110
118
  attempts.push(attempt)
111
119
  lastError = softError
112
- if (!isLast) opts.onAttemptFailed?.(attempt)
120
+ const stop = isLast || !failoverGate(softError)
121
+ if (!stop) opts.onAttemptFailed?.(attempt)
113
122
  unsub()
114
123
  await dispose()
115
- if (isLast) {
124
+ if (stop) {
116
125
  return { success: false, refUsed: ref, attempts, session, dispose: async () => {}, lastError }
117
126
  }
118
127
  continue
@@ -41,6 +41,17 @@ const SAFE_CLASSES: ReadonlyArray<{ match: RegExp; safe: string }> = [
41
41
  /\b(401|unauthori[sz]ed|invalid[_ -]?api[_ -]?key|api key.*(?:invalid|expired|missing)|authentication failed|invalid bearer)\b/i,
42
42
  safe: 'The upstream LLM provider rejected the request as unauthorized. Operators should check the provider API key configuration and `typeclaw logs`.',
43
43
  },
44
+ {
45
+ // Content-policy refusal: OpenAI Codex flags a prompt under its cybersecurity
46
+ // policy (`code: "cyber_policy"`) and rejects the whole turn with
47
+ // `invalid_request`. Retrying or failing over to another Codex ref can't help
48
+ // — it's the same account-wide policy — so this must surface with the operator
49
+ // action (get the account authorized) rather than collapse to the generic
50
+ // notice. Common for security-focused PR reviews, where the diff content trips
51
+ // the filter. The URL is OpenAI's own published enrollment page, safe to echo.
52
+ match: /\bcyber_policy\b/i,
53
+ safe: 'The upstream LLM provider (OpenAI Codex) refused the request under its cybersecurity content policy. Operators must enroll the account in OpenAI Trusted Access for Cyber at https://chatgpt.com/cyber, or switch the configured model.',
54
+ },
44
55
  {
45
56
  match: /\b(usage limit|rate limit|rate.?limited|too many requests|429)\b/i,
46
57
  safe: 'The upstream LLM provider is rate-limited (usage limit reached). Try again shortly.',
@@ -58,6 +69,27 @@ function toSafeMessage(raw: string): string {
58
69
  return GENERIC_SAFE_NOTICE
59
70
  }
60
71
 
72
+ // Capacity/rate signals worth failing OVER to another model ref (vs. retrying
73
+ // the same one). English-only is correct — these are provider protocol tokens,
74
+ // the explicit system-token exception to the multi-language rule. `\b` anchors
75
+ // `429`/`503` so they don't match digit runs in prose (token counts,
76
+ // elapsed-ms); `\b` is ASCII-safe because these are ASCII-only codes.
77
+ const THROTTLE_OR_OVERLOAD =
78
+ /overloaded|server_is_overloaded|service.?unavailable|rate.?limit|rate.?limited|too many requests|\b(?:429|503)\b/i
79
+
80
+ // Account-wide faults that must SURFACE, never fail over: switching refs can't
81
+ // help (same account) and would mask a config error the operator must fix. This
82
+ // is checked BEFORE the throttle match because providers often pair a `429`
83
+ // status with a quota/billing/auth reason (e.g. `429 insufficient quota`) — the
84
+ // status code alone must not force a pointless failover.
85
+ const NON_FAILOVER_FAULT =
86
+ /\bcyber_policy\b|insufficient.*(?:quota|credit|fund|balance)|\bquota\b|billing|payment|account is not active|unauthori[sz]ed|invalid[_ -]?api[_ -]?key|authentication failed|invalid bearer/i
87
+
88
+ export function isThrottleOrOverload(raw: string): boolean {
89
+ if (NON_FAILOVER_FAULT.test(raw)) return false
90
+ return THROTTLE_OR_OVERLOAD.test(raw)
91
+ }
92
+
61
93
  export function detectProviderError(message: unknown): DetectedProviderError | null {
62
94
  if (typeof message !== 'object' || message === null) return null
63
95
  const m = message as { role?: unknown; stopReason?: unknown; errorMessage?: unknown }
@@ -81,6 +113,9 @@ export function subscribeProviderErrors(session: AgentSession, onError: Provider
81
113
  return session.subscribe((event) => {
82
114
  if (event.type !== 'message_end') return
83
115
  const detected = detectProviderError(event.message)
84
- if (detected !== null) onError(detected)
116
+ if (detected === null) return
117
+ const abortRetry = (session as { abortRetry?: unknown }).abortRetry
118
+ if (isThrottleOrOverload(detected.message) && typeof abortRetry === 'function') abortRetry.call(session)
119
+ onError(detected)
85
120
  })
86
121
  }
@@ -1,13 +1,16 @@
1
1
  import type { ToolDefinition } from '@mariozechner/pi-coding-agent'
2
2
  import type { z } from 'zod'
3
3
 
4
+ import { getConfig, resolveModel } from '@/config'
4
5
  import type { PermissionService } from '@/permissions'
5
6
  import type { HookBus } from '@/plugin'
6
7
  import type { Stream, Unsubscribe } from '@/stream'
7
8
 
8
9
  import { applyTurnThinkingLevel } from './attention-escalation'
9
10
  import { type AgentSession, createSession, type PluginSessionWiring } from './index'
10
- import { subscribeProviderErrors } from './provider-error'
11
+ import { resolveFallbackChain } from './model-fallback'
12
+ import { applyModelRuntimeOverrides } from './model-overrides'
13
+ import { isThrottleOrOverload, subscribeProviderErrors } from './provider-error'
11
14
  import type { SubagentBashPolicy } from './reviewer-bash-policy'
12
15
  import type { SessionOrigin } from './session-origin'
13
16
  import {
@@ -18,6 +21,7 @@ import {
18
21
  } from './subagent-drain'
19
22
  import { renderTurnTimeAnchor } from './system-prompt'
20
23
  import type { ToolResultBudget } from './tool-result-budget'
24
+ import { promptPersistentTurnWithFallback } from './turn-runner'
21
25
 
22
26
  type AgentSessionTools = NonNullable<Parameters<typeof createSession>[0]>['tools']
23
27
 
@@ -294,6 +298,7 @@ export async function invokeSubagent(name: string, options: InvokeSubagentOption
294
298
  const { session, dispose, hooks, sessionId, agentDir, origin, getTranscriptPath, backgroundDrain } =
295
299
  normalizeSubagentSession(await createSessionForSubagent(subagent, sessionOptions))
296
300
  let aborted = false
301
+ let activeModelRef = resolveFallbackChain(getConfig().models, resolveSubagentProfile(subagent, sessionOptions))[0]!
297
302
  let drainWatch: SubagentDrainWatch | undefined
298
303
  const requiredBlockTag = REQUIRED_FINAL_BLOCK[name]
299
304
  const capture = attachFinalMessageCapture(session, requiredBlockTag, options.onFinalMessageCaptured ?? (() => {}))
@@ -333,8 +338,34 @@ export async function invokeSubagent(name: string, options: InvokeSubagentOption
333
338
  retrievalContext.results.length > 0
334
339
  ? `${renderTurnTimeAnchor()}\n\n${userPromptForTurn}\n\n${retrievalContext.results}`
335
340
  : `${renderTurnTimeAnchor()}\n\n${userPromptForTurn}`
336
- applyTurnThinkingLevel(session, userPromptForTurn, session.thinkingLevel)
337
- await session.prompt(turnText)
341
+ applyTurnThinkingLevel(session, userPromptForTurn, session.thinkingLevel, undefined, {
342
+ allowEscalation: false,
343
+ })
344
+ const result = await promptPersistentTurnWithFallback({
345
+ refs: resolveFallbackChain(getConfig().models, resolveSubagentProfile(subagent, sessionOptions)),
346
+ currentModelRef: activeModelRef,
347
+ profile: resolveSubagentProfile(subagent, sessionOptions),
348
+ session,
349
+ text: turnText,
350
+ skipProviderErrorSubscription: true,
351
+ detectSoftErrorFromLeaf: true,
352
+ shouldFailover: (err) => isThrottleOrOverload(err.message),
353
+ setModelForRef: async (ref) => {
354
+ await session.setModel(applyModelRuntimeOverrides(resolveModel(ref), ref))
355
+ activeModelRef = ref
356
+ },
357
+ beforeAttempt: () => {
358
+ applyTurnThinkingLevel(session, userPromptForTurn, session.thinkingLevel, undefined, {
359
+ allowEscalation: false,
360
+ })
361
+ },
362
+ onAttemptFailed: (attempt) => {
363
+ console.warn(
364
+ `[subagent] ${name} ${attempt.outcome} failure on ${attempt.ref}: ${attempt.errorMessage ?? 'unknown'}; falling back`,
365
+ )
366
+ },
367
+ })
368
+ if (result.success) activeModelRef = result.refUsed
338
369
  } finally {
339
370
  if (hooks && turnEvent !== undefined) {
340
371
  await hooks.runSessionTurnEnd(turnEvent)
@@ -0,0 +1,50 @@
1
+ import { providerForModelRef, type ModelRef } from '@/config/providers'
2
+
3
+ export const THROTTLE_THRESHOLD = 2
4
+ export const THROTTLE_WINDOW_MS = 60_000
5
+ export const COOLDOWN_MS = 180_000
6
+
7
+ export type ThrottleCircuitKey = {
8
+ profile?: string
9
+ ref: ModelRef
10
+ }
11
+
12
+ type CircuitEntry = {
13
+ failures: number[]
14
+ openUntil: number
15
+ }
16
+
17
+ export class ThrottleCircuit {
18
+ private readonly entries = new Map<string, CircuitEntry>()
19
+ private readonly now: () => number
20
+
21
+ constructor(opts: { now?: () => number } = {}) {
22
+ this.now = opts.now ?? Date.now
23
+ }
24
+
25
+ isOpen(key: ThrottleCircuitKey): boolean {
26
+ const entry = this.entries.get(this.keyId(key))
27
+ if (entry === undefined) return false
28
+ return this.now() < entry.openUntil
29
+ }
30
+
31
+ recordThrottle(key: ThrottleCircuitKey): void {
32
+ const id = this.keyId(key)
33
+ const now = this.now()
34
+ const entry = this.entries.get(id) ?? { failures: [], openUntil: 0 }
35
+ entry.failures = entry.failures.filter((ts) => now - ts <= THROTTLE_WINDOW_MS)
36
+ entry.failures.push(now)
37
+ if (entry.failures.length >= THROTTLE_THRESHOLD) entry.openUntil = now + COOLDOWN_MS
38
+ this.entries.set(id, entry)
39
+ }
40
+
41
+ recordSuccess(key: ThrottleCircuitKey): void {
42
+ this.entries.delete(this.keyId(key))
43
+ }
44
+
45
+ private keyId(key: ThrottleCircuitKey): string {
46
+ return `${key.profile ?? 'default'}:${providerForModelRef(key.ref)}:${key.ref}`
47
+ }
48
+ }
49
+
50
+ export const modelThrottleCircuit = new ThrottleCircuit()
@@ -92,9 +92,9 @@ export function createChannelReplyTool({
92
92
  resolve_review_thread: Type.Optional(
93
93
  Type.Boolean({
94
94
  description:
95
- 'GitHub review threads ONLY — ignored on Slack, Discord, Telegram, KakaoTalk, and any non-github session, and ignored on a github reply that is not inside a `thread`. On those, leave this unset and ignore the rest of this description. ' +
96
- 'On a github reply inside a review thread you authored: when your `text` acknowledges the concern is fixed/verified/addressed (e.g. "verified at <sha>", "thanks, that resolves it"), treat setting this `true` as the expected close-out — do it in the SAME call. This is a strong instruction, not a schema requirement: the field stays optional and nothing rejects an acknowledgement that omits it, but a bare ack without it leaves the thread open, because a successful reply ends the turn and the resolve cannot run in a later one. So this flag is the only way the close-out actually happens. ' +
97
- "It is safe to set by default: the runtime resolves BEFORE posting and ONLY if the thread's root comment is yours — it refuses (and blocks the reply) on a human reviewer's thread, so you never close someone else's open question. You need not pre-check authorship; just set it on your acknowledgement and let the runtime enforce ownership. Leave it unset when you intend to keep the thread open (partial fix, disagreement, mid-discussion).",
95
+ 'GitHub PR review threads ONLY. On a TERMINAL (`continue:false`) github PR review-thread reply that carries `text`, this is REQUIRED: you must set it to `true` or `false` and omitting it is rejected — you will be told to re-call with an explicit choice. (It stays a normal optional field everywhere else: ignored on Slack/Discord/Telegram/KakaoTalk and any non-github session, on github replies outside a review thread, on attachments-only replies, and on mid-turn `continue:true` status updates — leave it unset there.) ' +
96
+ 'Set `true` when your `text` acknowledges the concern is fixed/verified/addressed (e.g. "verified at <sha>", "thanks, that resolves it"): the runtime resolves the thread BEFORE posting, so the close-out actually happens in this same turn — a successful reply ends the turn, so a resolve deferred to "later" never runs. ' +
97
+ "Set `false` when the thread should stay open (partial fix, disagreement, mid-discussion). It is safe to set `true` by default: the runtime resolves ONLY if the thread's root comment is yours — it refuses (and blocks the reply) on a human reviewer's thread, so you never close someone else's open question. You need not pre-check authorship; let the runtime enforce ownership.",
98
98
  }),
99
99
  ),
100
100
  }),
@@ -140,6 +140,27 @@ export function createChannelReplyTool({
140
140
  }
141
141
  }
142
142
 
143
+ // Required-choice guard: a terminal github review-thread text reply must
144
+ // make an explicit resolve_review_thread choice. The model kept silently
145
+ // omitting the flag after acknowledging a fix, leaving the thread open;
146
+ // forcing the choice (the discipline `continue` already enforces) closes
147
+ // the loop where prose instructions did not. The field stays optional in
148
+ // the schema precisely so omission is still detectable here (vs explicit
149
+ // false). Runs before the resolve/guards so a missing choice never acts.
150
+ const missingResolveChoice = missingReviewThreadResolveChoiceError({
151
+ origin,
152
+ text,
153
+ isContinue: keepTurnAlive,
154
+ resolveReviewThread: params.resolve_review_thread,
155
+ })
156
+ if (missingResolveChoice) {
157
+ logger.warn(formatChannelToolFailure('channel_reply', missingResolveChoice))
158
+ return {
159
+ content: [{ type: 'text' as const, text: `channel_reply denied: ${missingResolveChoice}` }],
160
+ details: { ok: false, error: missingResolveChoice },
161
+ }
162
+ }
163
+
143
164
  // False-receipt guard: deny a terminal reply that CLAIMS a PR verdict /
144
165
  // thread close-out the agent never actually performed this turn. Warn-tier
145
166
  // claims fall through and have their notice appended on success below.
@@ -279,6 +300,30 @@ export function createChannelReplyTool({
279
300
  })
280
301
  }
281
302
 
303
+ // Returns the denial string when a terminal github PR review-thread text reply
304
+ // omits an explicit resolve_review_thread choice, or '' when no choice is owed.
305
+ // Scoped by `^pr:\d+$` (not just thread !== null) so a future threaded github
306
+ // context can't be forced into a resolve choice that means nothing there.
307
+ function missingReviewThreadResolveChoiceError(input: {
308
+ origin: ChannelReplyOrigin
309
+ text: string | undefined
310
+ isContinue: boolean
311
+ resolveReviewThread: boolean | undefined
312
+ }): string {
313
+ const isGithubPrReviewThread =
314
+ input.origin.adapter === 'github' && /^pr:\d+$/.test(input.origin.chat) && input.origin.thread !== null
315
+ const hasText = input.text !== undefined && input.text.trim() !== ''
316
+ if (!isGithubPrReviewThread || !hasText || input.isContinue || input.resolveReviewThread !== undefined) {
317
+ return ''
318
+ }
319
+ return (
320
+ 'This is a terminal github PR review-thread reply with text, so `resolve_review_thread` is required: ' +
321
+ 'set it to `true` when the concern is fixed and this bot-authored thread should be closed (the runtime ' +
322
+ 'resolves before posting and only on your own thread), or `false` to leave it open. You omitted it; ' +
323
+ 're-call channel_reply with an explicit boolean.'
324
+ )
325
+ }
326
+
282
327
  // Returns an error string when the resolve should block the reply, or null
283
328
  // when it's safe to proceed. Only `no-match` (the thread is already gone, so
284
329
  // there's nothing to close) joins success as non-blocking; every hard failure
@@ -13,23 +13,58 @@
13
13
  // for the full rationale and AGENTS.md §"Web search" for the original story.
14
14
 
15
15
  import { curlImpersonate } from './curl-impersonate'
16
+ import { createKeyedSemaphore } from './keyed-semaphore'
17
+ import { type SearchRetryOptions, withSearchRetry } from './search-retry'
16
18
 
17
19
  export { _setCurlBinaryForTest } from './curl-impersonate'
18
20
 
19
21
  const DDG_LITE_URL = 'https://lite.duckduckgo.com/lite/'
20
22
 
23
+ // Empirically derived: a clean source IP serves DDG-lite at concurrency ~4 but
24
+ // trips a sticky multi-minute CAPTCHA at 5-6 (see keyed-semaphore.ts header).
25
+ // The whole agent egresses from one IP and the scout subagent fans out parallel
26
+ // searches, so 2 sits well under the observed ceiling with headroom for the
27
+ // concurrent membership-style overlap — matching the webex-prefetch-limiter
28
+ // default for the same reason.
29
+ export const DDG_CONCURRENCY = 2
30
+
31
+ // Process-wide, so the cap spans every session/subagent/cron in this agent.
32
+ const searchLimiter = createKeyedSemaphore({ concurrency: DDG_CONCURRENCY })
33
+
34
+ const DDG_KEY = 'ddg'
35
+
21
36
  export type DdgResult = {
22
37
  title: string
23
38
  url: string
24
39
  snippet: string
25
40
  }
26
41
 
42
+ type RetryOverride = Pick<SearchRetryOptions, 'attempts' | 'baseDelayMs' | 'maxDelayMs' | 'sleep'>
43
+ let retryOverride: RetryOverride = {}
44
+
45
+ // Test-only seam: lets *.test.ts collapse the generous production backoff to
46
+ // zero-delay single-shot retries so CAPTCHA tests don't burn real seconds.
47
+ // Production never calls this — the empty default above is what production sees.
48
+ export function _setSearchRetryForTest(override: RetryOverride | null): void {
49
+ retryOverride = override ?? {}
50
+ }
51
+
27
52
  export async function ddgSearch(query: string, limit: number, signal?: AbortSignal): Promise<DdgResult[]> {
28
- const html = await fetchDdgHtml(query, signal)
29
- if (isCaptcha(html)) {
30
- throw new DdgCaptchaError()
31
- }
32
- return parseDdgHtml(html).slice(0, limit)
53
+ return searchLimiter.run(
54
+ DDG_KEY,
55
+ () =>
56
+ withSearchRetry(
57
+ async () => {
58
+ const html = await fetchDdgHtml(query, signal)
59
+ if (isCaptcha(html)) {
60
+ throw new DdgCaptchaError()
61
+ }
62
+ return parseDdgHtml(html).slice(0, limit)
63
+ },
64
+ { ...retryOverride, shouldRetry: (error) => error instanceof DdgCaptchaError, signal },
65
+ ),
66
+ signal,
67
+ )
33
68
  }
34
69
 
35
70
  export class DdgCaptchaError extends Error {
@@ -0,0 +1,114 @@
1
+ // A process-wide keyed concurrency limiter: at most `concurrency` calls run
2
+ // at once PER KEY, and work queued behind a full key WAITS for a slot rather
3
+ // than being skipped. Distinct keys never contend.
4
+ //
5
+ // This is the queue-and-wait sibling of src/channels/adapters/webex-prefetch-
6
+ // limiter.ts. That limiter uses admit-or-skip because its work (history
7
+ // prefetch) is an optional context improvement — dropping it is fine. Here the
8
+ // work is a search the model explicitly asked for, so dropping it is NOT fine;
9
+ // callers must block until a slot frees.
10
+ //
11
+ // Why this exists: one typeclaw agent is one process, and all sessions
12
+ // (TUI, channel, cron, subagent) share that process. A search engine like
13
+ // DuckDuckGo rate-limits by source IP, and the whole agent egresses from one
14
+ // IP, so parallel searches across sessions/subagents stack onto the same
15
+ // per-engine budget. An empirical probe of lite.duckduckgo.com showed a clean
16
+ // IP serves ~4 concurrent requests but trips a sticky multi-minute CAPTCHA at
17
+ // 5-6 — and once tripped, even serial requests stay boxed. Capping concurrency
18
+ // PER ENGINE keeps the burst under that ceiling so the box is never tripped.
19
+
20
+ export type KeyedSemaphore = {
21
+ // Runs `work` once a slot for `key` is free, waiting if necessary. The slot
22
+ // is released when `work` settles (resolve or reject). Distinct keys run
23
+ // fully independently. If `signal` aborts while the call is still queued (or
24
+ // is already aborted on entry), the call rejects with SemaphoreAbortedError
25
+ // WITHOUT ever running `work` or holding a slot.
26
+ run<T>(key: string, work: () => Promise<T>, signal?: AbortSignal): Promise<T>
27
+ }
28
+
29
+ export type KeyedSemaphoreOptions = {
30
+ // Max concurrent runs PER KEY. Defaults to 1.
31
+ concurrency?: number
32
+ }
33
+
34
+ export class SemaphoreAbortedError extends Error {
35
+ constructor() {
36
+ super('Semaphore acquisition aborted before admission.')
37
+ this.name = 'SemaphoreAbortedError'
38
+ }
39
+ }
40
+
41
+ export function createKeyedSemaphore(options: KeyedSemaphoreOptions = {}): KeyedSemaphore {
42
+ const concurrency = Math.max(1, Math.floor(options.concurrency ?? 1))
43
+
44
+ type Waiter = () => void
45
+ type Pool = { active: number; waiters: Waiter[] }
46
+ const pools = new Map<string, Pool>()
47
+
48
+ const poolFor = (key: string): Pool => {
49
+ let pool = pools.get(key)
50
+ if (pool === undefined) {
51
+ pool = { active: 0, waiters: [] }
52
+ pools.set(key, pool)
53
+ }
54
+ return pool
55
+ }
56
+
57
+ const release = (key: string): void => {
58
+ const pool = pools.get(key)
59
+ if (pool === undefined) return
60
+ pool.active--
61
+ const next = pool.waiters.shift()
62
+ if (next) {
63
+ pool.active++
64
+ next()
65
+ // Drop idle pools so a long-lived semaphore does not accumulate one entry
66
+ // per key ever seen.
67
+ } else if (pool.active === 0 && pool.waiters.length === 0) {
68
+ pools.delete(key)
69
+ }
70
+ }
71
+
72
+ const acquire = (key: string, signal?: AbortSignal): Promise<void> => {
73
+ if (signal?.aborted) return Promise.reject(new SemaphoreAbortedError())
74
+ const pool = poolFor(key)
75
+ if (pool.active < concurrency) {
76
+ pool.active++
77
+ return Promise.resolve()
78
+ }
79
+ return new Promise<void>((resolve, reject) => {
80
+ let settled = false
81
+ const grant: Waiter = () => {
82
+ if (settled) {
83
+ // Granted after we already aborted: hand the freed slot to the next
84
+ // waiter so an aborted grant never leaks a permanently-held slot.
85
+ release(key)
86
+ return
87
+ }
88
+ settled = true
89
+ signal?.removeEventListener('abort', onAbort)
90
+ resolve()
91
+ }
92
+ const onAbort = (): void => {
93
+ if (settled) return
94
+ settled = true
95
+ const idx = pool.waiters.indexOf(grant)
96
+ if (idx >= 0) pool.waiters.splice(idx, 1)
97
+ reject(new SemaphoreAbortedError())
98
+ }
99
+ pool.waiters.push(grant)
100
+ signal?.addEventListener('abort', onAbort, { once: true })
101
+ })
102
+ }
103
+
104
+ return {
105
+ async run<T>(key: string, work: () => Promise<T>, signal?: AbortSignal): Promise<T> {
106
+ await acquire(key, signal)
107
+ try {
108
+ return await work()
109
+ } finally {
110
+ release(key)
111
+ }
112
+ },
113
+ }
114
+ }
@@ -0,0 +1,82 @@
1
+ // Retry-with-backoff for search-engine calls that hit a transient rate-limit
2
+ // or CAPTCHA wall.
3
+ //
4
+ // Empirically, lite.duckduckgo.com does NOT recover in milliseconds once it
5
+ // starts gating: a tripped source IP stays boxed for minutes, and the gate
6
+ // surfaces as a CAPTCHA page (parsed as DdgCaptchaError) rather than a clean
7
+ // 429. So the backoff here is deliberately generous (seconds, growing) — a
8
+ // tight millisecond retry would just burn the remaining budget and confirm the
9
+ // box. The concurrency cap (keyed-semaphore.ts) is the real preventer; this is
10
+ // the second line of defense for a request that still raced into a gate.
11
+ //
12
+ // `shouldRetry` decides which errors are worth retrying — only transient
13
+ // rate-limit/CAPTCHA signals, never a parse error or a hard network failure.
14
+
15
+ export type SearchRetryOptions = {
16
+ attempts?: number
17
+ baseDelayMs?: number
18
+ maxDelayMs?: number
19
+ shouldRetry: (error: unknown) => boolean
20
+ signal?: AbortSignal
21
+ // Injectable sleep so tests can run without real timers.
22
+ sleep?: (ms: number, signal?: AbortSignal) => Promise<void>
23
+ }
24
+
25
+ export const DEFAULT_SEARCH_RETRY_ATTEMPTS = 3
26
+ export const DEFAULT_SEARCH_RETRY_BASE_DELAY_MS = 2_000
27
+ export const DEFAULT_SEARCH_RETRY_MAX_DELAY_MS = 15_000
28
+
29
+ export async function withSearchRetry<T>(work: () => Promise<T>, options: SearchRetryOptions): Promise<T> {
30
+ const attempts = Math.max(1, Math.floor(options.attempts ?? DEFAULT_SEARCH_RETRY_ATTEMPTS))
31
+ const baseDelayMs = options.baseDelayMs ?? DEFAULT_SEARCH_RETRY_BASE_DELAY_MS
32
+ const maxDelayMs = options.maxDelayMs ?? DEFAULT_SEARCH_RETRY_MAX_DELAY_MS
33
+ const sleep = options.sleep ?? defaultSleep
34
+
35
+ let lastError: unknown
36
+ for (let attempt = 0; attempt < attempts; attempt++) {
37
+ if (options.signal?.aborted) throw new SearchRetryAbortedError()
38
+ try {
39
+ return await work()
40
+ } catch (error) {
41
+ lastError = error
42
+ const isLastAttempt = attempt === attempts - 1
43
+ if (isLastAttempt || !options.shouldRetry(error)) throw error
44
+ await sleep(backoffDelayMs(attempt, baseDelayMs, maxDelayMs), options.signal)
45
+ }
46
+ }
47
+ throw lastError
48
+ }
49
+
50
+ export class SearchRetryAbortedError extends Error {
51
+ constructor() {
52
+ super('Search retry aborted.')
53
+ this.name = 'SearchRetryAbortedError'
54
+ }
55
+ }
56
+
57
+ // Exponential backoff with full jitter (AWS "Exponential Backoff And Jitter").
58
+ // Full jitter — random in [0, capped] — decorrelates concurrent retriers so a
59
+ // burst that all tripped the gate together does not re-collide on the same
60
+ // wake-up, which would just re-trip the box.
61
+ export function backoffDelayMs(attempt: number, baseDelayMs: number, maxDelayMs: number): number {
62
+ const capped = Math.min(maxDelayMs, baseDelayMs * 2 ** attempt)
63
+ return Math.floor(Math.random() * capped)
64
+ }
65
+
66
+ function defaultSleep(ms: number, signal?: AbortSignal): Promise<void> {
67
+ return new Promise((resolve, reject) => {
68
+ if (signal?.aborted) {
69
+ reject(new SearchRetryAbortedError())
70
+ return
71
+ }
72
+ const timer = setTimeout(() => {
73
+ signal?.removeEventListener('abort', onAbort)
74
+ resolve()
75
+ }, ms)
76
+ const onAbort = (): void => {
77
+ clearTimeout(timer)
78
+ reject(new SearchRetryAbortedError())
79
+ }
80
+ signal?.addEventListener('abort', onAbort, { once: true })
81
+ })
82
+ }