typeclaw 0.44.0 → 0.45.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (45) hide show
  1. package/package.json +7 -6
  2. package/src/agent/index.ts +42 -3
  3. package/src/agent/loop-guard.ts +208 -10
  4. package/src/agent/model-fallback.ts +59 -40
  5. package/src/agent/multimodal/look-at.ts +2 -1
  6. package/src/agent/plugin-tools.ts +59 -5
  7. package/src/agent/provider-error.ts +78 -18
  8. package/src/agent/retry-same-ref.ts +205 -0
  9. package/src/agent/subagents.ts +34 -4
  10. package/src/agent/tools/channel-edit.ts +144 -0
  11. package/src/agent/tools/channel-fetch-attachment.ts +6 -5
  12. package/src/agent/tools/channel-reply.ts +15 -1
  13. package/src/agent/tools/channel-send.ts +17 -1
  14. package/src/agent/tools/curl-impersonate.ts +40 -1
  15. package/src/agent/tools/webfetch/fetch.ts +86 -3
  16. package/src/agent/tools/webfetch/tool.ts +26 -3
  17. package/src/agent/tools/webfetch/types.ts +8 -0
  18. package/src/agent/turn-runner.ts +79 -36
  19. package/src/bundled-plugins/agent-browser/skills/agent-browser/SKILL.md +28 -11
  20. package/src/bundled-plugins/reviewer/skills/code-review.ts +27 -2
  21. package/src/channels/adapters/discord-bot-edit.ts +49 -0
  22. package/src/channels/adapters/discord-bot.ts +30 -4
  23. package/src/channels/adapters/discord-edit.ts +51 -0
  24. package/src/channels/adapters/discord.ts +4 -0
  25. package/src/channels/adapters/kakaotalk-channel-resolver.ts +10 -1
  26. package/src/channels/adapters/kakaotalk-typing.ts +125 -0
  27. package/src/channels/adapters/kakaotalk.ts +19 -0
  28. package/src/channels/adapters/slack-bot-edit.ts +58 -0
  29. package/src/channels/adapters/slack-bot.ts +18 -6
  30. package/src/channels/adapters/slack-edit.ts +47 -0
  31. package/src/channels/adapters/slack.ts +5 -0
  32. package/src/channels/adapters/teams-edit.ts +61 -0
  33. package/src/channels/adapters/teams.ts +4 -0
  34. package/src/channels/adapters/telegram-bot-edit.ts +51 -0
  35. package/src/channels/adapters/telegram-bot.ts +5 -0
  36. package/src/channels/adapters/webex-bot.ts +5 -0
  37. package/src/channels/adapters/webex-edit.ts +47 -0
  38. package/src/channels/adapters/webex.ts +5 -0
  39. package/src/channels/continuation-willingness.ts +227 -35
  40. package/src/channels/router.ts +500 -20
  41. package/src/channels/schema.ts +24 -0
  42. package/src/channels/types.ts +36 -0
  43. package/src/run/llm-fetch-observer.ts +147 -9
  44. package/src/server/command-runner.ts +2 -1
  45. package/src/server/index.ts +2 -1
@@ -200,6 +200,7 @@ export type WrapToolOptions = {
200
200
  // time) because tools are wrapped BEFORE `createAgentSession` returns the
201
201
  // session whose `agent.abort` this points at. See `fireLoopAbort`.
202
202
  getAbort?: () => ((reason?: string) => void) | undefined
203
+ getLoopGuardTurn?: () => number | undefined
203
204
  }
204
205
 
205
206
  export type WrapSystemToolOptions = {
@@ -208,6 +209,7 @@ export type WrapSystemToolOptions = {
208
209
  hooks: HookBus
209
210
  getOrigin?: () => SessionOrigin | undefined
210
211
  getAbort?: () => ((reason?: string) => void) | undefined
212
+ getLoopGuardTurn?: () => number | undefined
211
213
  // When present, the bash builtin is rewritten through the per-tool bwrap
212
214
  // sandbox with role-derived path masks. Absent (or no masks for the role)
213
215
  // runs bash unchanged — preserving today's behavior for trusted+ and for
@@ -269,7 +271,13 @@ export function wrapPluginTool(tool: Tool<any>, opts: WrapToolOptions): ToolDefi
269
271
  return errorResult(`blocked: ${blockResult.reason}`)
270
272
  }
271
273
 
272
- const loopGate = gateLoopGuard(opts.sessionId, opts.toolName, before.args)
274
+ const loopGate = gateLoopGuard(
275
+ opts.sessionId,
276
+ opts.toolName,
277
+ before.args,
278
+ opts.getLoopGuardTurn?.(),
279
+ opts.agentDir,
280
+ )
273
281
  if (loopGate.blockNow) {
274
282
  fireLoopAbort(opts.getAbort, 'loop_guard:block')
275
283
  return errorResult(loopGate.message)
@@ -332,7 +340,7 @@ export function wrapSystemTool<TParams extends TSchema, TDetails = unknown, TSta
332
340
  if (blockResult !== undefined) {
333
341
  throw new Error(`blocked: ${blockResult.reason}`)
334
342
  }
335
- const loopGate = gateLoopGuard(opts.sessionId, tool.name, mutableArgs)
343
+ const loopGate = gateLoopGuard(opts.sessionId, tool.name, mutableArgs, opts.getLoopGuardTurn?.(), opts.agentDir)
336
344
  if (loopGate.blockNow) {
337
345
  fireLoopAbort(opts.getAbort, 'loop_guard:block')
338
346
  throw new Error(loopGate.message)
@@ -406,7 +414,7 @@ export function wrapBuiltinToolDefinition<TParams extends TSchema, TDetails = un
406
414
  // loop-detection state, or pi's execute.
407
415
  const bashEnvOverlay = readBashEnvOverlay(mutableArgs)
408
416
  delete mutableArgs[TYPECLAW_INTERNAL_BASH_ENV]
409
- const loopGate = gateLoopGuard(opts.sessionId, tool.name, mutableArgs)
417
+ const loopGate = gateLoopGuard(opts.sessionId, tool.name, mutableArgs, opts.getLoopGuardTurn?.(), opts.agentDir)
410
418
  if (loopGate.blockNow) {
411
419
  fireLoopAbort(opts.getAbort, 'loop_guard:block')
412
420
  throw new Error(loopGate.message)
@@ -818,6 +826,44 @@ function subagentPollStatus(toolName: string, result: ToolResult): 'running' | '
818
826
  return details.status === 'running' ? 'running' : 'terminal'
819
827
  }
820
828
 
829
+ function observedReadResult(
830
+ toolName: string,
831
+ result: ToolResult,
832
+ ): { nonEmpty: boolean; outputLines?: number; textual: boolean } | undefined {
833
+ if (toolName !== 'read') return undefined
834
+ const details = result.details as { truncation?: { outputLines?: unknown } } | undefined
835
+ const outputLines = details?.truncation?.outputLines
836
+ const hasImage = result.content.some((part) => part.type === 'image')
837
+ const hasText = result.content.some(
838
+ (part) => part.type === 'text' && typeof part.text === 'string' && part.text.trim().length > 0,
839
+ )
840
+ const imageFallback =
841
+ !hasImage &&
842
+ result.content.some(
843
+ (part) => part.type === 'text' && typeof part.text === 'string' && /^Read image file \[[^\]]+\]/.test(part.text),
844
+ )
845
+ const observedOutputLines =
846
+ typeof outputLines === 'number' && Number.isFinite(outputLines)
847
+ ? outputLines
848
+ : !hasImage && !imageFallback
849
+ ? countReadOutputLines(result.content)
850
+ : undefined
851
+ return {
852
+ nonEmpty: hasImage || hasText,
853
+ textual: !hasImage && !imageFallback,
854
+ ...(observedOutputLines !== undefined ? { outputLines: observedOutputLines } : {}),
855
+ }
856
+ }
857
+
858
+ function countReadOutputLines(content: ContentPart[]): number | undefined {
859
+ const textParts = content.filter(
860
+ (part): part is Extract<ContentPart, { type: 'text' }> => part.type === 'text' && typeof part.text === 'string',
861
+ )
862
+ if (textParts.length !== 1) return undefined
863
+ const fileText = textParts[0]!.text.replace(/\n\n\[\d+ more lines in file\. Use offset=\d+ to continue\.\]$/, '')
864
+ return fileText.length === 0 ? 0 : fileText.split('\n').length
865
+ }
866
+
821
867
  type LoopGuardGate = {
822
868
  // True when the guard wants to block AND the block is enforced now (every tool
823
869
  // except a deferable `subagent_output` poll). The caller aborts + errors.
@@ -835,13 +881,21 @@ type LoopGuardGate = {
835
881
  // semantics. `check` runs here (recording the observation); the returned
836
882
  // `resolve` is called after execute with the tool's result, feeding the poll's
837
883
  // running/terminal status back to the guard so future blocks stop deferring.
838
- function gateLoopGuard(sessionId: string, toolName: string, args: unknown): LoopGuardGate {
839
- const decision = sharedLoopGuard.check(sessionId, toolName, args)
884
+ function gateLoopGuard(
885
+ sessionId: string,
886
+ toolName: string,
887
+ args: unknown,
888
+ turnId?: number,
889
+ cwd?: string,
890
+ ): LoopGuardGate {
891
+ const decision = sharedLoopGuard.check(sessionId, toolName, args, { turnId, cwd })
840
892
  const defer = shouldDeferLoopBlock(toolName, decision)
841
893
  return {
842
894
  blockNow: decision.kind === 'block' && !defer,
843
895
  message: decision.kind === 'ok' ? '' : decision.message,
844
896
  resolve(result) {
897
+ const readResult = observedReadResult(toolName, result)
898
+ if (readResult !== undefined) sharedLoopGuard.noteReadResult(decision.receipt, readResult)
845
899
  const pollStatus = subagentPollStatus(toolName, result)
846
900
  if (pollStatus !== undefined) {
847
901
  sharedLoopGuard.noteResult(decision.receipt, pollStatus)
@@ -33,19 +33,36 @@ const GENERIC_SAFE_NOTICE = 'The upstream LLM provider failed. Operators can che
33
33
  // and surface it. The literal is the system's own token — English by design.
34
34
  const OBSERVER_TIMEOUT = /\(typeclaw observer timeout\)/i
35
35
 
36
+ // Transport-layer failure: the request died at the connection/session before a
37
+ // usable response — an expired live session, a WebSocket upgrade that never
38
+ // reached `101 Switching Protocols`, or a dropped transport. Unlike an
39
+ // account-wide auth/billing fault, this is transient AND ref-specific: a
40
+ // different ref opens its own session, so failing OVER can succeed. Observed from
41
+ // Codex/ChatGPT (`provider_transport_failure`, expired ChatGPT session, a
42
+ // `wss://…/codex/responses` non-101 upgrade). Provider protocol tokens — English
43
+ // by design (the system-token exception to the multi-language rule).
44
+ const TRANSPORT_FAILURE =
45
+ /provider[_ -]?transport[_ -]?failure|(?:websocket|ws)(?: connection)?(?:(?: was| is)? closed|.*failed)|expected 101|session expired/i
46
+
47
+ // Auth failure: the provider rejected our credentials (bad/expired/missing API
48
+ // key or token, 401/403, failed authentication). Account-wide — a different ref shares the
49
+ // same credential problem — so this is BOTH a redacted safe-message class (a
50
+ // 401 body can carry a Bearer token) AND a NON_FAILOVER_FAULT reason. Shared as
51
+ // one constant so the two uses can never drift: previously the safe-message copy
52
+ // matched `api key ... expired` but the failover copy didn't, letting
53
+ // `session expired: api key expired` wrongly fail over past the auth guard.
54
+ const AUTH_FAULT =
55
+ /\b(401|403|unauthori[sz]ed|forbidden|access denied|invalid[_ -]?api[_ -]?key|api key.*(?:invalid|expired|missing)|(?:access|session)[_ -]?token(?:(?:[_ -]+)(?:has|is))?[_ -]+expired|authentication(?: failed|[_ -]?error)|invalid bearer)\b/i
56
+
36
57
  // Each entry pairs a narrow matcher against the raw provider text with the
37
58
  // canonical, leak-free sentence shown in channels. Matchers are intentionally
38
59
  // specific: a miss falls through to GENERIC_SAFE_NOTICE rather than echoing raw
39
60
  // text, so adding a new class is opt-in and never widens what we expose.
40
61
  const SAFE_CLASSES: ReadonlyArray<{ match: RegExp; safe: string }> = [
41
62
  {
42
- // Auth failure: the provider rejected our credentials (bad/expired/missing
43
- // API key). Matched first because a 401 body can also mention "account",
44
- // which would otherwise fall into the billing class below. The safe text
45
- // names the operator action (check the API key) without echoing the raw
46
- // error, whose body can carry a Bearer token.
47
- match:
48
- /\b(401|unauthori[sz]ed|invalid[_ -]?api[_ -]?key|api key.*(?:invalid|expired|missing)|authentication failed|invalid bearer)\b/i,
63
+ // Matched first because a 401 body can also mention "account", which would
64
+ // otherwise fall into the billing class below.
65
+ match: AUTH_FAULT,
49
66
  safe: 'The upstream LLM provider rejected the request as unauthorized. Operators should check the provider API key configuration and `typeclaw logs`.',
50
67
  },
51
68
  {
@@ -71,6 +88,10 @@ const SAFE_CLASSES: ReadonlyArray<{ match: RegExp; safe: string }> = [
71
88
  match: OBSERVER_TIMEOUT,
72
89
  safe: 'The upstream LLM provider stopped responding and the request timed out. Try again shortly.',
73
90
  },
91
+ {
92
+ match: TRANSPORT_FAILURE,
93
+ safe: 'The connection to the upstream LLM provider dropped (session/transport failure). Try again shortly.',
94
+ },
74
95
  ]
75
96
 
76
97
  function toSafeMessage(raw: string): string {
@@ -92,9 +113,17 @@ const THROTTLE_OR_OVERLOAD =
92
113
  // help (same account) and would mask a config error the operator must fix. This
93
114
  // is checked BEFORE the throttle match because providers often pair a `429`
94
115
  // status with a quota/billing/auth reason (e.g. `429 insufficient quota`) — the
95
- // status code alone must not force a pointless failover.
96
- const NON_FAILOVER_FAULT =
97
- /\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
116
+ // status code alone must not force a pointless failover. The auth arm reuses the
117
+ // shared `AUTH_FAULT` source so it stays in lockstep with the safe-message class.
118
+ const NON_FAILOVER_FAULT = new RegExp(
119
+ `\\bcyber_policy\\b|insufficient.*(?:quota|credit|fund|balance)|\\bquota\\b|billing|payment|account is not active|${AUTH_FAULT.source}`,
120
+ 'i',
121
+ )
122
+
123
+ // Context-window exhaustion belongs to the SDK compaction/error path, never
124
+ // transport recovery. Keep this to provider protocol forms rather than matching
125
+ // natural-language user text.
126
+ const CONTEXT_OVERFLOW = /\bcontext[_ -]?length[_ -]?exceeded\b/i
98
127
 
99
128
  export function isThrottleOrOverload(raw: string): boolean {
100
129
  if (NON_FAILOVER_FAULT.test(raw)) return false
@@ -102,14 +131,42 @@ export function isThrottleOrOverload(raw: string): boolean {
102
131
  }
103
132
 
104
133
  // Failover predicate for turn-drivers' `shouldFailover`: rotate to the next model
105
- // ref on a transient capacity signal (throttle/overload) OR an observer stall
106
- // timeout. A stall — the provider accepted the stream but stopped sending bytes —
107
- // is as transient as an overload and another ref may well succeed, so it must
108
- // fail OVER before the caller surfaces a failure notice. Account-wide faults
109
- // (billing/quota/auth) still return false via `isThrottleOrOverload` — a
110
- // different ref shares the same account problem.
134
+ // ref on a transient capacity signal (throttle/overload), an observer stall
135
+ // timeout, or a transport/session failure. A stall or a dropped session is as
136
+ // transient as an overload and another ref (its own session/transport) may well
137
+ // succeed, so it must fail OVER before the caller surfaces a failure notice.
138
+ // Account-wide faults (billing/quota/auth) are excluded up front — a different
139
+ // ref shares the same account problem, so switching can't help.
111
140
  export function isFailoverWorthy(raw: string): boolean {
112
- return isThrottleOrOverload(raw) || OBSERVER_TIMEOUT.test(raw)
141
+ if (CONTEXT_OVERFLOW.test(raw)) return false
142
+ if (NON_FAILOVER_FAULT.test(raw)) return false
143
+ return isThrottleOrOverload(raw) || OBSERVER_TIMEOUT.test(raw) || TRANSPORT_FAILURE.test(raw)
144
+ }
145
+
146
+ // Transient network / upstream 5xx signals that a same-model replay may clear.
147
+ // Distinct from THROTTLE_OR_OVERLOAD (429/503/overload) on purpose: an overload
148
+ // means the model is out of capacity NOW, so the right move is to fail OVER to a
149
+ // different ref, not hammer the same one — whereas a socket hang-up or a 500 is a
150
+ // one-off blip a replay against the SAME ref often fixes. `\b` anchors the 5xx
151
+ // codes so they don't match digit runs in prose. Provider protocol tokens —
152
+ // English by design (the system-token exception to the multi-language rule).
153
+ const NETWORK_OR_5XX =
154
+ /econnreset|econnrefused|etimedout|enetunreach|socket hang up|network.?error|connection.?(?:error|refused|reset|lost)|fetch failed|other side closed|reset before headers|http2 request did not get a response|\b(?:500|502|504)\b/i
155
+
156
+ // Retry predicate for typeclaw-owned SAME-REF retry: replay the SAME model ref
157
+ // before advancing the chain. Deliberately NARROWER than `isFailoverWorthy` —
158
+ // only transient failures a same-model replay can plausibly clear: transport/
159
+ // session drops, observer stalls, and network/5xx blips. It intentionally EXCLUDES
160
+ // throttle/overload (429/503) — those mean "this ref is out of capacity now", so
161
+ // they should fail OVER to another ref rather than burn same-ref retries — and
162
+ // account-wide faults (auth/billing/quota/cyber_policy), which must surface. It
163
+ // does NOT match context-overflow: that stays on the SDK compaction path and must
164
+ // never be treated as a retryable provider failure.
165
+ export function isRetryableSameRef(raw: string): boolean {
166
+ if (CONTEXT_OVERFLOW.test(raw)) return false
167
+ if (NON_FAILOVER_FAULT.test(raw)) return false
168
+ if (isThrottleOrOverload(raw)) return false
169
+ return TRANSPORT_FAILURE.test(raw) || OBSERVER_TIMEOUT.test(raw) || NETWORK_OR_5XX.test(raw)
113
170
  }
114
171
 
115
172
  export function detectProviderError(message: unknown): DetectedProviderError | null {
@@ -134,7 +191,10 @@ export function detectProviderError(message: unknown): DetectedProviderError | n
134
191
  export function detectHardProviderError(err: unknown): DetectedProviderError | null {
135
192
  const message = err instanceof Error ? err.message : String(err)
136
193
  const isProviderFailure =
137
- isThrottleOrOverload(message) || NON_FAILOVER_FAULT.test(message) || OBSERVER_TIMEOUT.test(message)
194
+ isThrottleOrOverload(message) ||
195
+ NON_FAILOVER_FAULT.test(message) ||
196
+ OBSERVER_TIMEOUT.test(message) ||
197
+ TRANSPORT_FAILURE.test(message)
138
198
  if (!isProviderFailure) return null
139
199
  return { message, safeMessage: toSafeMessage(message) }
140
200
  }
@@ -0,0 +1,205 @@
1
+ import type { AgentSession } from './index'
2
+ import { isRetryableSameRef, subscribeProviderErrors } from './provider-error'
3
+
4
+ // Same-ref retry policy. Conservative on purpose: the pi-ai provider layer ALSO
5
+ // retries transport/5xx blips underneath us (WebSocket→SSE fallback + its own
6
+ // SSE retry loop), and each typeclaw attempt is bounded by the observer timeouts
7
+ // (TTFB 15s / idle 120s / overall 300s). Stacking a large per-ref retry count on
8
+ // top of that turns one outage into minutes of dead air, so we replay the same
9
+ // ref just ONCE by default and rely on cross-ref fallback for anything the single
10
+ // replay can't clear.
11
+ export const RETRIES_PER_REF = 1
12
+ const BASE_DELAY_MS = 1_000
13
+ const MAX_DELAY_MS = 5_000
14
+
15
+ // Full-jitter exponential backoff: random in [0, min(cap, base·2^attempt)].
16
+ // Jitter decorrelates concurrent turns (multiple channels/subagents recovering
17
+ // from the same upstream blip) so they don't retry in lockstep and re-collide.
18
+ export function retryBackoffMs(attempt: number, random: () => number = Math.random): number {
19
+ const ceiling = Math.min(MAX_DELAY_MS, BASE_DELAY_MS * 2 ** attempt)
20
+ return Math.floor(random() * ceiling)
21
+ }
22
+
23
+ function sleep(ms: number, signal?: AbortSignal): Promise<void> {
24
+ if (ms <= 0) return Promise.resolve()
25
+ return new Promise((resolve) => {
26
+ const timer = setTimeout(resolve, ms)
27
+ signal?.addEventListener('abort', () => {
28
+ clearTimeout(timer)
29
+ resolve()
30
+ })
31
+ })
32
+ }
33
+
34
+ // For callers that recreate the session themselves (cron) and only need the delay.
35
+ export function sleepBackoff(attempt: number, signal?: AbortSignal, random?: () => number): Promise<void> {
36
+ return sleep(retryBackoffMs(attempt, random), signal)
37
+ }
38
+
39
+ type ContinuableAgent = {
40
+ state?: { messages?: unknown }
41
+ continue?: () => Promise<void>
42
+ }
43
+
44
+ // Replay the CURRENT turn on a persistent session WITHOUT re-appending the user
45
+ // message. Mirrors the SDK's own auto-retry shape, resuming via `agent.continue()`
46
+ // (which replays from the trailing user/tool-result message). Re-calling
47
+ // `session.prompt(text)` instead would duplicate the user message and corrupt
48
+ // history, so we never do that.
49
+ //
50
+ // Two resolved shapes are retryable, matching `continue()`'s contract that the
51
+ // last message be user/tool-result:
52
+ // - trailing ASSISTANT error leaf → pop it, then continue (soft error, or a
53
+ // hard throw AFTER a partial assistant message was written)
54
+ // - trailing USER message → the provider died BEFORE writing any assistant
55
+ // message (the reported incident: transport/session failure before stream
56
+ // start). Nothing to pop — continue() replays the user turn as-is.
57
+ // Any other trailing shape (tool-result mid-execution, custom, empty transcript,
58
+ // no `agent.continue`) fails CLOSED — the caller falls back / surfaces instead.
59
+ export async function retryTurnOnPersistentSession(
60
+ session: AgentSession,
61
+ opts: { attempt: number; signal?: AbortSignal; random?: () => number } = { attempt: 0 },
62
+ ): Promise<boolean> {
63
+ const agent = (session as { agent?: ContinuableAgent }).agent
64
+ if (!agent || typeof agent.continue !== 'function') return false
65
+ const messages = agent.state?.messages
66
+ if (!Array.isArray(messages) || messages.length === 0) return false
67
+ const leafRole = (messages[messages.length - 1] as { role?: unknown }).role
68
+ if (leafRole !== 'assistant' && leafRole !== 'user') return false
69
+
70
+ await sleep(retryBackoffMs(opts.attempt, opts.random), opts.signal)
71
+ if (opts.signal?.aborted) return false
72
+
73
+ // Drop only a trailing assistant error leaf; a trailing user message is already
74
+ // the shape continue() wants, so leave it untouched (and never re-appended).
75
+ if (leafRole === 'assistant') {
76
+ ;(agent.state as { messages: unknown }).messages = messages.slice(0, -1)
77
+ }
78
+ await agent.continue()
79
+ return true
80
+ }
81
+
82
+ // Resume only the post-tool provider-failure shape. Unlike the generic helper,
83
+ // this deliberately refuses a trailing user leaf or an assistant error whose
84
+ // predecessor is anything other than the completed tool result. Callers use it
85
+ // after externally visible tool activity, where replaying the original turn
86
+ // could duplicate side effects.
87
+ export async function retryTurnAfterCompletedToolResult(
88
+ session: AgentSession,
89
+ opts: {
90
+ attempt: number
91
+ signal?: AbortSignal
92
+ random?: () => number
93
+ authorize: () => boolean
94
+ onBackoffStart?: () => void
95
+ },
96
+ ): Promise<boolean> {
97
+ const agent = (session as { agent?: ContinuableAgent }).agent
98
+ if (!agent || typeof agent.continue !== 'function') return false
99
+ if (!hasCompletedToolResultErrorTail(agent.state?.messages)) return false
100
+
101
+ opts.onBackoffStart?.()
102
+ await sleep(retryBackoffMs(opts.attempt, opts.random), opts.signal)
103
+ if (opts.signal?.aborted) return false
104
+
105
+ // Re-read after the backoff: another actor may have advanced the transcript
106
+ // while we slept. Mutation is safe only while the exact tail still holds.
107
+ const messages = agent.state?.messages
108
+ if (!hasCompletedToolResultErrorTail(messages)) return false
109
+ if (opts.authorize() !== true) return false
110
+
111
+ const originalMessages = messages
112
+ const prefix = messages.slice(0, -1)
113
+ ;(agent.state as { messages: unknown }).messages = prefix
114
+ try {
115
+ await agent.continue()
116
+ } catch (err) {
117
+ if (hasSameEntries(agent.state?.messages, prefix)) {
118
+ ;(agent.state as { messages: unknown }).messages = originalMessages
119
+ }
120
+ throw err
121
+ }
122
+ return true
123
+ }
124
+
125
+ function hasCompletedToolResultErrorTail(messages: unknown): messages is unknown[] {
126
+ if (!Array.isArray(messages) || messages.length < 2) return false
127
+ const predecessor = messages[messages.length - 2]
128
+ const leaf = messages[messages.length - 1]
129
+ return (
130
+ typeof predecessor === 'object' &&
131
+ predecessor !== null &&
132
+ (predecessor as { role?: unknown }).role === 'toolResult' &&
133
+ typeof leaf === 'object' &&
134
+ leaf !== null &&
135
+ (leaf as { role?: unknown }).role === 'assistant' &&
136
+ (leaf as { stopReason?: unknown }).stopReason === 'error'
137
+ )
138
+ }
139
+
140
+ function hasSameEntries(messages: unknown, expected: unknown[]): boolean {
141
+ return (
142
+ Array.isArray(messages) &&
143
+ messages.length === expected.length &&
144
+ messages.every((entry, i) => entry === expected[i])
145
+ )
146
+ }
147
+
148
+ // Same-ref retry for DIRECT `session.prompt()` call sites that bypass the model
149
+ // fallback helpers (non-stream TUI, slash commands, subagent drain/required-block
150
+ // nudges, multimodal look-at). These lost the SDK's built-in retry when it was
151
+ // disabled globally to kill the soft-error race; this restores equivalent
152
+ // same-model resilience WITHOUT cross-ref fallback (there's no chain here) and
153
+ // WITHOUT the race (typeclaw owns the soft-error signal). On a non-retryable
154
+ // failure it does exactly what a bare prompt() did: the throw propagates, or the
155
+ // soft error stays on the leaf for the caller to read.
156
+ export async function promptWithSameRefRetryOnly(
157
+ session: AgentSession,
158
+ text: string,
159
+ promptOpts?: Parameters<AgentSession['prompt']>[1],
160
+ ): Promise<void> {
161
+ let softError: Error | undefined
162
+ // Feature-detect subscribe: some lightweight call sites / test fakes pass a
163
+ // session without an event stream. Without it we simply can't observe soft
164
+ // errors — the wrapper then only retries hard throws, still safe.
165
+ const canSubscribe = typeof (session as { subscribe?: unknown }).subscribe === 'function'
166
+ const unsub = canSubscribe
167
+ ? subscribeProviderErrors(session, (err) => {
168
+ if (!softError) softError = new Error(err.message)
169
+ })
170
+ : () => {}
171
+ try {
172
+ // Carry the last attempt's failure so a retry that CAN'T run (unsafe
173
+ // transcript shape → retryTurnOnPersistentSession returns false) still
174
+ // surfaces the original failure instead of resolving as a phantom success.
175
+ let priorHardError: Error | undefined
176
+ for (let attempt = 0; ; attempt++) {
177
+ softError = undefined
178
+ let hardError: Error | undefined
179
+ try {
180
+ if (attempt === 0) {
181
+ await session.prompt(text, promptOpts)
182
+ } else if (!(await retryTurnOnPersistentSession(session, { attempt: attempt - 1 }))) {
183
+ // Continue-recipe not applicable: replay never happened, so the prior
184
+ // failure stands — re-throw a hard error, or return to leave a soft
185
+ // error on the leaf (bare-prompt() semantics).
186
+ if (priorHardError !== undefined) throw priorHardError
187
+ return
188
+ }
189
+ } catch (err) {
190
+ hardError = err instanceof Error ? err : new Error(String(err))
191
+ }
192
+ const error = hardError ?? softError
193
+ if (error === undefined) return
194
+ if (attempt >= RETRIES_PER_REF || !isRetryableSameRef(error.message)) {
195
+ // Out of budget or not retryable: preserve bare-prompt() semantics — a
196
+ // hard error throws; a soft error stays on the leaf for the caller.
197
+ if (hardError !== undefined) throw hardError
198
+ return
199
+ }
200
+ priorHardError = hardError
201
+ }
202
+ } finally {
203
+ unsub()
204
+ }
205
+ }
@@ -11,6 +11,7 @@ import { type AgentSession, createSession, type PluginSessionWiring } from './in
11
11
  import { resolveFallbackChain } from './model-fallback'
12
12
  import { applyModelRuntimeOverrides } from './model-overrides'
13
13
  import { isFailoverWorthy, subscribeProviderErrors } from './provider-error'
14
+ import { promptWithSameRefRetryOnly } from './retry-same-ref'
14
15
  import type { SubagentBashPolicy } from './reviewer-bash-policy'
15
16
  import type { SessionOrigin } from './session-origin'
16
17
  import {
@@ -366,6 +367,7 @@ export async function invokeSubagent(name: string, options: InvokeSubagentOption
366
367
  },
367
368
  })
368
369
  if (result.success) activeModelRef = result.refUsed
370
+ throwIfLoopGuardAborted(session)
369
371
  } finally {
370
372
  if (hooks && turnEvent !== undefined) {
371
373
  await hooks.runSessionTurnEnd(turnEvent)
@@ -375,11 +377,13 @@ export async function invokeSubagent(name: string, options: InvokeSubagentOption
375
377
  await runSubagentDrain(drainWatch, {
376
378
  drain: backgroundDrain,
377
379
  prompt: async (text) => {
378
- await session.prompt(`${renderTurnTimeAnchor()}\n\n${text}`)
380
+ await promptWithSameRefRetryOnly(session, `${renderTurnTimeAnchor()}\n\n${text}`)
381
+ throwIfLoopGuardAborted(session)
379
382
  },
380
383
  cancelled: () => aborted,
381
384
  })
382
385
  }
386
+ throwIfLoopGuardAborted(session)
383
387
  // Required-block guard (mirrors the channel empty-response guard): a subagent
384
388
  // that owes a result block but ended without one gets a bounded re-prompt to
385
389
  // emit it as text, then an honest fallback — never a silent stale-preamble
@@ -395,7 +399,11 @@ export async function invokeSubagent(name: string, options: InvokeSubagentOption
395
399
  console.warn(
396
400
  `[subagent] ${name} required_block_retry attempt=${attempt}/${MAX_REQUIRED_BLOCK_RETRIES} tag=${requiredBlockTag}`,
397
401
  )
398
- await session.prompt(`${renderTurnTimeAnchor()}\n\n${renderRequiredBlockRetryNudge(requiredBlockTag)}`)
402
+ await promptWithSameRefRetryOnly(
403
+ session,
404
+ `${renderTurnTimeAnchor()}\n\n${renderRequiredBlockRetryNudge(requiredBlockTag)}`,
405
+ )
406
+ throwIfLoopGuardAborted(session)
399
407
  }
400
408
  if (!aborted && !capture.hasRequiredBlock()) {
401
409
  console.warn(`[subagent] ${name} required_block_fallback tag=${requiredBlockTag}`)
@@ -444,6 +452,19 @@ export class SubagentTimeoutError extends Error {
444
452
  }
445
453
  }
446
454
 
455
+ class SubagentLoopGuardAbortError extends Error {
456
+ override readonly name = 'SubagentLoopGuardAbortError'
457
+
458
+ constructor(readonly reason: string) {
459
+ super(`subagent aborted by loop guard (${reason})`)
460
+ }
461
+ }
462
+
463
+ function throwIfLoopGuardAborted(session: AgentSession): void {
464
+ const reason = (session as AgentSession & { getAbortReason?: () => string | undefined }).getAbortReason?.()
465
+ if (reason?.startsWith('loop_guard:') === true) throw new SubagentLoopGuardAbortError(reason)
466
+ }
467
+
447
468
  export function isSubagentTimeoutError(err: unknown): err is SubagentTimeoutError {
448
469
  return err instanceof SubagentTimeoutError
449
470
  }
@@ -540,7 +561,7 @@ export function startSubagent(name: string, options: StartSubagentOptions): Star
540
561
  if (!handleSettled) {
541
562
  rejectHandle(err instanceof Error ? err : new Error(error))
542
563
  }
543
- return { ok: false as const, error }
564
+ return { ok: false as const, error, ...(finalMessage !== undefined ? { finalMessage } : {}) }
544
565
  })
545
566
 
546
567
  const timeoutMs = options.registry[name]?.timeoutMs
@@ -684,7 +705,7 @@ function attachFinalMessageCapture(
684
705
  let lastReview: string | null = null
685
706
  let lastRequired: string | null = null
686
707
  try {
687
- session.subscribe((event: unknown) => {
708
+ subscribeToAwaitedAgentEvents(session, (event: unknown) => {
688
709
  const ev = event as { type?: string; message?: { role?: string; content?: unknown } }
689
710
  if (ev?.type !== 'message_end') return
690
711
  // Real assistant messages carry role 'assistant'; older test doubles omit
@@ -727,6 +748,15 @@ function attachFinalMessageCapture(
727
748
  }
728
749
  }
729
750
 
751
+ function subscribeToAwaitedAgentEvents(session: AgentSession, listener: (event: unknown) => void): () => void {
752
+ const agent = (
753
+ session as AgentSession & {
754
+ agent?: { subscribe?: (listener: (event: unknown) => void) => () => void }
755
+ }
756
+ ).agent
757
+ return agent?.subscribe?.(listener) ?? session.subscribe(listener)
758
+ }
759
+
730
760
  function extractFinalMessageText(content: unknown): string | null {
731
761
  if (typeof content === 'string') {
732
762
  const trimmed = content.trim()