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.
- package/package.json +1 -1
- package/src/agent/attention-escalation.ts +11 -1
- package/src/agent/index.ts +10 -14
- package/src/agent/model-fallback.ts +13 -4
- package/src/agent/provider-error.ts +36 -1
- package/src/agent/subagents.ts +34 -3
- package/src/agent/throttle-circuit.ts +50 -0
- package/src/agent/tools/channel-reply.ts +48 -3
- package/src/agent/tools/ddg.ts +40 -5
- package/src/agent/tools/keyed-semaphore.ts +114 -0
- package/src/agent/tools/search-retry.ts +82 -0
- package/src/agent/turn-runner.ts +162 -0
- package/src/bundled-plugins/explorer/explorer.ts +5 -0
- package/src/bundled-plugins/memory/README.md +14 -14
- package/src/bundled-plugins/memory/append-tool.ts +98 -8
- package/src/bundled-plugins/memory/dreaming.ts +1 -1
- package/src/bundled-plugins/memory/fragment-parser.ts +10 -3
- package/src/bundled-plugins/memory/load-memory.ts +28 -2
- package/src/bundled-plugins/memory/memory-logger.ts +21 -5
- package/src/bundled-plugins/memory/search-tool.ts +50 -7
- package/src/bundled-plugins/memory/stream-events.ts +23 -0
- package/src/bundled-plugins/memory/vector/hybrid.ts +9 -2
- package/src/bundled-plugins/reviewer/reviewer.ts +3 -1
- package/src/bundled-plugins/scout/scout.ts +5 -0
- package/src/bundled-plugins/security/index.ts +24 -1
- package/src/bundled-plugins/security/policies/cron-promotion.ts +94 -62
- package/src/bundled-plugins/security/policies/plugin-addition.ts +2 -4
- package/src/bundled-plugins/security/policies/role-promotion.ts +2 -4
- package/src/channels/adapters/github/permission-guidance.ts +18 -0
- package/src/channels/adapters/webex-bot.ts +26 -25
- package/src/channels/adapters/webex-prefetch-limiter.ts +120 -0
- package/src/channels/adapters/webex.ts +27 -30
- package/src/channels/manager.ts +64 -57
- package/src/channels/router.ts +134 -4
- package/src/channels/types.ts +8 -1
- package/src/cli/builtins.ts +6 -32
- package/src/cli/channel.ts +7 -11
- package/src/cli/command-meta.ts +93 -0
- package/src/cli/help.ts +24 -0
- package/src/cli/index.ts +34 -10
- package/src/cli/init.ts +2 -2
- package/src/cli/plugin-commands-dispatch.ts +7 -1
- package/src/config/config.ts +27 -1
- package/src/container/start.ts +22 -2
- package/src/hostd/daemon.ts +55 -26
- package/src/hostd/spawn.ts +53 -19
- package/src/permissions/permissions.ts +12 -0
- package/src/run/codex-fetch-observer.ts +11 -6
- package/src/secrets/oauth-xai.ts +2 -2
- package/src/server/index.ts +27 -2
- package/src/skills/typeclaw-channel-github/SKILL.md +59 -13
- package/src/skills/typeclaw-channels/SKILL.md +1 -1
- package/src/skills/typeclaw-config/SKILL.md +1 -0
- package/src/skills/typeclaw-cron/SKILL.md +9 -4
- package/src/skills/typeclaw-permissions/SKILL.md +18 -6
package/package.json
CHANGED
|
@@ -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
|
}
|
package/src/agent/index.ts
CHANGED
|
@@ -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
|
|
248
|
-
//
|
|
249
|
-
//
|
|
250
|
-
//
|
|
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
|
-
//
|
|
254
|
-
//
|
|
255
|
-
//
|
|
256
|
-
//
|
|
257
|
-
//
|
|
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
|
-
|
|
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
|
-
|
|
107
|
+
const stop = isLast || !failoverGate(error)
|
|
108
|
+
if (!stop) opts.onAttemptFailed?.(attempt)
|
|
101
109
|
unsub()
|
|
102
110
|
await dispose()
|
|
103
|
-
if (
|
|
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
|
-
|
|
120
|
+
const stop = isLast || !failoverGate(softError)
|
|
121
|
+
if (!stop) opts.onAttemptFailed?.(attempt)
|
|
113
122
|
unsub()
|
|
114
123
|
await dispose()
|
|
115
|
-
if (
|
|
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
|
|
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
|
}
|
package/src/agent/subagents.ts
CHANGED
|
@@ -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 {
|
|
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
|
-
|
|
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
|
|
96
|
-
'
|
|
97
|
-
"It is safe to set by default: the runtime resolves
|
|
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
|
package/src/agent/tools/ddg.ts
CHANGED
|
@@ -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
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
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
|
+
}
|