@bastani/atomic 0.8.26-alpha.5 → 0.8.26-alpha.7

package/dist/builtin/subagents/src/runs/background/subagent-runner.ts

@@ -48,7 +48,12 @@ import { outputEntryFromAsyncResult, resolveOutputReferences } from "../shared/c
 import { createStructuredOutputRuntime, readStructuredOutput } from "../shared/structured-output.ts";
 import { collectDynamicResults, DynamicFanoutError, materializeDynamicParallelStep, validateDynamicCollection } from "../shared/dynamic-fanout.ts";
 import { nestedSummaryFromAsyncStatus, writeNestedEvent } from "../shared/nested-events.ts";
-import { formatModelAttemptNote, isRetryableModelFailure } from "../shared/model-fallback.ts";
+import { formatModelAttemptNote, isRetryableModelFailure, modelFailureMessage } from "../shared/model-fallback.ts";
+import {
+	assistantStopReason,
+	isAssistantFailureStopReason,
+	shouldStartSubagentFinalDrain,
+} from "../shared/final-drain.ts";
 import { attachPostExitStdioGuard, trySignalChild } from "../../shared/post-exit-stdio-guard.ts";
 import { detectSubagentError, extractTextFromContent, extractToolArgsPreview, getFinalOutput } from "../../shared/utils.ts";
 import { evaluateCompletionMutationGuard } from "../shared/completion-guard.ts";
@@ -230,6 +235,7 @@ interface RunPiStreamingResult {
 	finalOutput: string;
 	interrupted?: boolean;
 	observedMutationAttempt?: boolean;
+	modelFailureSignal?: unknown;
 }
 
 function runPiStreaming(
@@ -270,6 +276,7 @@ function runPiStreaming(
 		let model: string | undefined;
 		let error: string | undefined;
 		let assistantError: string | undefined;
+		let assistantFailureSignal: unknown;
 		let interrupted = false;
 		let observedMutationAttempt = false;
 		const rawStdoutLines: string[] = [];
@@ -330,7 +337,6 @@ function runPiStreaming(
 
 				if (event.type !== "message_end" || event.message.role !== "assistant") return;
 				if (event.message.model) model = event.message.model;
-				if (event.message.errorMessage) assistantError = event.message.errorMessage;
 				const eventUsage = event.message.usage;
 				if (eventUsage) {
 					usage.turns++;
@@ -340,12 +346,21 @@ function runPiStreaming(
 					usage.cacheWrite += eventUsage.cacheWrite ?? 0;
 					usage.cost += eventUsage.cost?.total ?? 0;
 				}
-				const stopReason = (event.message as { stopReason?: string }).stopReason;
-				const hasToolCall = Array.isArray(event.message.content)
-					&& event.message.content.some((part) => (part as { type?: string }).type === "toolCall");
-				if (stopReason === "stop" && !hasToolCall) {
-					if (!event.message.errorMessage && extractTextFromContent(event.message.content).trim()) assistantError = undefined;
-					cleanTerminalAssistantStopReceived ||= !event.message.errorMessage;
+				const stopReason = assistantStopReason(event.message);
+				if (event.message.errorMessage) {
+					assistantError = event.message.errorMessage;
+					assistantFailureSignal = event.message;
+				}
+				if (isAssistantFailureStopReason(stopReason)) {
+					assistantError = modelFailureMessage(event.message);
+					assistantFailureSignal = event.message;
+				}
+				if (shouldStartSubagentFinalDrain(event.message)) {
+					if (extractTextFromContent(event.message.content).trim()) {
+						assistantError = undefined;
+						assistantFailureSignal = undefined;
+					}
+					cleanTerminalAssistantStopReceived = true;
 					startFinalDrain();
 				}
 			}
@@ -448,6 +463,9 @@ function runPiStreaming(
 				finalOutput,
 				interrupted,
 				observedMutationAttempt,
+				...(assistantFailureSignal !== undefined && finalError === assistantError
+					? { modelFailureSignal: assistantFailureSignal }
+					: {}),
 			});
 		});
 
@@ -459,7 +477,20 @@ function runPiStreaming(
 			outputStream.end();
 			const finalOutput = getFinalOutput(messages) || rawStdoutLines.join("\n").trim();
 			const spawnErrorMessage = spawnError instanceof Error ? spawnError.message : String(spawnError);
-			resolve({ stderr, exitCode: 1, messages, usage, model, error: error ?? assistantError ?? spawnErrorMessage, finalOutput, observedMutationAttempt });
+			const finalError = error ?? assistantError ?? spawnErrorMessage;
+			resolve({
+				stderr,
+				exitCode: 1,
+				messages,
+				usage,
+				model,
+				error: finalError,
+				finalOutput,
+				observedMutationAttempt,
+				...(assistantFailureSignal !== undefined && finalError === assistantError
+					? { modelFailureSignal: assistantFailureSignal }
+					: {}),
+			});
 		});
 	});
 }
@@ -770,7 +801,14 @@ async function runSingleStep(
 		finalOutputSnapshot = outputSnapshot;
 		finalResult = { ...run, exitCode: effectiveExitCode, model: candidate ?? run.model, error, structuredOutput } as RunPiStreamingResult & { structuredOutput?: unknown };
 		if (attempt.success) break;
-		if (!completionGuardTriggered && isRetryableModelFailure(error) && index < candidates.length - 1) {
+		const retrySignal = run.modelFailureSignal ?? error;
+		if (
+			!completionGuardTriggered
+			&& structuredError === undefined
+			&& hiddenError?.hasError !== true
+			&& isRetryableModelFailure(retrySignal)
+			&& index < candidates.length - 1
+		) {
 			pendingAttemptNotes.push(formatModelAttemptNote(attempt, candidates[index + 1]));
 			continue;
 		}

package/dist/builtin/subagents/src/runs/foreground/execution.ts

@@ -54,7 +54,13 @@ import {
 	buildModelCandidates,
 	formatModelAttemptNote,
 	isRetryableModelFailure,
+	modelFailureMessage,
 } from "../shared/model-fallback.ts";
+import {
+	assistantStopReason,
+	isAssistantFailureStopReason,
+	shouldStartSubagentFinalDrain,
+} from "../shared/final-drain.ts";
 import {
 	createMutatingFailureState,
 	didMutatingToolFail,
@@ -76,6 +82,7 @@ import { acceptanceFailureMessage, evaluateAcceptance, formatAcceptancePrompt, r
 
 const artifactOutputByResult = new WeakMap<SingleResult, string>();
 const acceptanceOutputByResult = new WeakMap<SingleResult, string>();
+const modelFailureSignalByResult = new WeakMap<SingleResult, unknown>();
 
 function emptyUsage(): Usage {
 	return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 0 };
@@ -293,6 +300,7 @@ async function runSingleAttempt(
 		let detached = false;
 		let intercomStarted = false;
 		let assistantError: string | undefined;
+		let assistantFailureSignal: unknown;
 		let removeAbortListener: (() => void) | undefined;
 		let removeInterruptListener: (() => void) | undefined;
 		let activityTimer: NodeJS.Timeout | undefined;
@@ -544,16 +552,25 @@ async function runSingleAttempt(
 						progress.tokens = result.usage.input + result.usage.output;
 					}
 					if (!result.model && evt.message.model) result.model = evt.message.model;
-					if (evt.message.errorMessage) assistantError = evt.message.errorMessage;
 					const assistantText = extractTextFromContent(evt.message.content);
 					appendRecentOutput(progress, assistantText.split("\n").slice(-10));
-					// Final assistant message: start the exit drain window.
-					const stopReason = (evt.message as { stopReason?: string }).stopReason;
-					const hasToolCall = Array.isArray(evt.message.content)
-						&& evt.message.content.some((part) => (part as { type?: string }).type === "toolCall");
-					if (stopReason === "stop" && !hasToolCall) {
-						if (!evt.message.errorMessage && assistantText.trim()) assistantError = undefined;
-						cleanTerminalAssistantStopReceived ||= !evt.message.errorMessage;
+					// Clean final assistant stops start the exit drain window; provider error/aborted
+					// stop reasons remain failure evidence so pi-ai can auto-retry before exit.
+					const stopReason = assistantStopReason(evt.message);
+					if (evt.message.errorMessage) {
+						assistantError = evt.message.errorMessage;
+						assistantFailureSignal = evt.message;
+					}
+					if (isAssistantFailureStopReason(stopReason)) {
+						assistantError = modelFailureMessage(evt.message);
+						assistantFailureSignal = evt.message;
+					}
+					if (shouldStartSubagentFinalDrain(evt.message)) {
+						if (assistantText.trim()) {
+							assistantError = undefined;
+							assistantFailureSignal = undefined;
+						}
+						cleanTerminalAssistantStopReceived = true;
 						startFinalDrain();
 					}
 				}
@@ -633,6 +650,9 @@ async function runSingleAttempt(
 			processClosed = true;
 			if (buf.trim()) processLine(buf);
 			if (!result.error && assistantError) result.error = assistantError;
+			if (assistantFailureSignal !== undefined && result.error === assistantError) {
+				modelFailureSignalByResult.set(result, assistantFailureSignal);
+			}
 			const forcedDrainAfterFinalSuccess = forcedTerminationSignal && cleanTerminalAssistantStopReceived && !result.error;
 			if (code !== 0 && stderrBuf.trim() && !result.error && !forcedDrainAfterFinalSuccess) {
 				result.error = stderrBuf.trim();
@@ -964,7 +984,8 @@ export async function runSync(
 		if (attemptSucceeded) {
 			break;
 		}
-		if (isRetryableModelFailure(result.error) && i < modelsToTry.length - 1) {
+		const retrySignal = modelFailureSignalByResult.get(result) ?? result.error;
+		if (isRetryableModelFailure(retrySignal) && i < modelsToTry.length - 1) {
 			pendingAttemptNotes.push(formatModelAttemptNote(attempt, modelsToTry[i + 1]));
 			continue;
 		}

package/dist/builtin/subagents/src/runs/shared/final-drain.ts

@@ -0,0 +1,34 @@
+export interface SubagentAssistantDrainMessage {
+	readonly role?: unknown;
+	readonly content?: unknown;
+	readonly stopReason?: unknown;
+	readonly errorMessage?: unknown;
+}
+
+export function assistantStopReason(message: SubagentAssistantDrainMessage): string | undefined {
+	return typeof message.stopReason === "string" ? message.stopReason : undefined;
+}
+
+export function isAssistantFailureStopReason(stopReason: string | undefined): boolean {
+	return stopReason === "error" || stopReason === "aborted";
+}
+
+export function assistantMessageHasToolCall(message: SubagentAssistantDrainMessage): boolean {
+	return Array.isArray(message.content)
+		&& message.content.some((part) => part !== null
+			&& typeof part === "object"
+			&& (part as { readonly type?: unknown }).type === "toolCall");
+}
+
+function assistantMessageHasError(message: SubagentAssistantDrainMessage): boolean {
+	const errorMessage = message.errorMessage;
+	if (typeof errorMessage === "string") return errorMessage.trim().length > 0;
+	return errorMessage !== undefined && errorMessage !== null;
+}
+
+export function shouldStartSubagentFinalDrain(message: SubagentAssistantDrainMessage): boolean {
+	if (message.role !== undefined && message.role !== "assistant") return false;
+	return assistantStopReason(message) === "stop"
+		&& !assistantMessageHasError(message)
+		&& !assistantMessageHasToolCall(message);
+}

package/dist/builtin/subagents/src/runs/shared/model-fallback.ts

@@ -62,7 +62,7 @@ export function currentModelFullId(model: { provider: string; id: string } | und
 	return `${String(model.provider)}/${model.id}`;
 }
 
-const RETRYABLE_MODEL_FAILURE_PATTERNS = [
+const RETRYABLE_MODEL_FAILURE_PATTERNS: readonly RegExp[] = [
 	/rate\s*limit/i,
 	/too many requests/i,
 	/\b429\b/,
@@ -71,6 +71,7 @@ const RETRYABLE_MODEL_FAILURE_PATTERNS = [
 	/credit/i,
 	/auth(?:entication)?/i,
 	/unauthori[sz]ed/i,
+	/\b40[13]\b/,
 	/forbidden/i,
 	/api key/i,
 	/token expired/i,
@@ -90,14 +91,422 @@ const RETRYABLE_MODEL_FAILURE_PATTERNS = [
 	/upstream/i,
 	/timed? out/i,
 	/timeout/i,
-	/\b502\b/,
-	/\b503\b/,
-	/\b504\b/,
+	/\b50[0-4]\b/,
 ];
 
-export function isRetryableModelFailure(error: string | undefined): boolean {
-	if (!error) return false;
-	return RETRYABLE_MODEL_FAILURE_PATTERNS.some((pattern) => pattern.test(error));
+const NON_RETRYABLE_FAILURE_PATTERNS: readonly RegExp[] = [
+	/command failed/i,
+	/tests? failed/i,
+	/shell/i,
+	/missing file/i,
+	/no such file/i,
+	/completion guard/i,
+	/cancel/i,
+	/abort/i,
+	/interrupted/i,
+];
+
+const CANCELLED_FAILURE_PATTERNS: readonly RegExp[] = [
+	/cancel/i,
+	/abort/i,
+	/interrupted/i,
+];
+
+export type ModelFallbackFailureKind =
+	| "auth_on_candidate_provider"
+	| "rate_limit"
+	| "provider_unavailable"
+	| "network_timeout"
+	| "model_unavailable"
+	| "cancelled"
+	| "task_failure"
+	| "unknown";
+
+export type ModelFallbackFailureSource =
+	| "assistant_message"
+	| "diagnostic"
+	| "throw"
+	| "structured"
+	| "string_fallback";
+
+export interface ModelFallbackFailureSignal {
+	readonly kind: ModelFallbackFailureKind;
+	readonly message: string;
+	readonly source: ModelFallbackFailureSource;
+	readonly stopReason?: string;
+	readonly status?: number;
+	readonly code?: string | number;
+	readonly name?: string;
+}
+
+const FALLBACKABLE_FAILURE_KINDS: ReadonlySet<ModelFallbackFailureKind> = new Set([
+	"auth_on_candidate_provider",
+	"rate_limit",
+	"provider_unavailable",
+	"network_timeout",
+	"model_unavailable",
+]);
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+	return value !== null && typeof value === "object" ? value as Record<string, unknown> : undefined;
+}
+
+function field(value: unknown, key: string): unknown {
+	return asRecord(value)?.[key];
+}
+
+function stringField(value: unknown, key: string): string | undefined {
+	const raw = field(value, key);
+	return typeof raw === "string" && raw.trim().length > 0 ? raw : undefined;
+}
+
+function errorName(value: unknown): string | undefined {
+	return value instanceof Error ? value.name : stringField(value, "name");
+}
+
+function directMessageFrom(value: unknown): string | undefined {
+	return stringField(value, "errorMessage")
+		?? stringField(value, "message")
+		?? stringField(value, "statusText");
+}
+
+function integerFrom(value: unknown): number | undefined {
+	if (typeof value === "number" && Number.isInteger(value)) return value;
+	if (typeof value !== "string" || value.trim().length === 0) return undefined;
+	const parsed = Number(value.trim());
+	return Number.isInteger(parsed) ? parsed : undefined;
+}
+
+function statusFrom(value: unknown): number | undefined {
+	return integerFrom(field(value, "status"))
+		?? integerFrom(field(value, "statusCode"))
+		?? integerFrom(field(value, "httpStatus"));
+}
+
+function codeFrom(value: unknown): string | number | undefined {
+	const rawCode = field(value, "code");
+	return typeof rawCode === "string" || typeof rawCode === "number" ? rawCode : undefined;
+}
+
+function stopReasonFrom(value: unknown): string | undefined {
+	return stringField(value, "stopReason");
+}
+
+function finishReasonFrom(value: unknown): string | undefined {
+	return stringField(value, "finish_reason") ?? stringField(value, "finishReason");
+}
+
+function causeOf(value: unknown): unknown {
+	return value instanceof Error ? value.cause : field(value, "cause");
+}
+
+function diagnosticErrors(value: unknown): readonly unknown[] {
+	const diagnostics = field(value, "diagnostics");
+	if (!Array.isArray(diagnostics)) return [];
+	const errors: unknown[] = [];
+	for (const diagnostic of diagnostics) {
+		const diagnosticError = field(diagnostic, "error");
+		errors.push(diagnosticError ?? diagnostic);
+	}
+	return errors;
+}
+
+function normalizeCode(value: string | number | undefined): string | undefined {
+	if (value === undefined) return undefined;
+	const normalized = String(value)
+		.trim()
+		.toLowerCase()
+		.replace(/[^a-z0-9]+/g, "_")
+		.replace(/^_+|_+$/g, "");
+	return normalized.length > 0 ? normalized : undefined;
+}
+
+function kindFromStatus(status: number | undefined): ModelFallbackFailureKind | undefined {
+	switch (status) {
+		case 401:
+		case 403:
+			return "auth_on_candidate_provider";
+		case 408:
+			return "network_timeout";
+		case 404:
+			return "model_unavailable";
+		case 429:
+			return "rate_limit";
+		default:
+			if (status !== undefined && status >= 500 && status <= 599) return "provider_unavailable";
+			return undefined;
+	}
+}
+
+function refusalKindFromCode(code: string | number | undefined): ModelFallbackFailureKind | undefined {
+	const normalizedCode = normalizeCode(code);
+	if (normalizedCode === undefined) return undefined;
+	if (normalizedCode.includes("content_filter") || normalizedCode.includes("contentfilter")) return "task_failure";
+	if (normalizedCode.includes("safety") || normalizedCode.includes("policy")) return "task_failure";
+	switch (normalizedCode) {
+		case "blocked":
+		case "blocked_by_provider":
+		case "blocked_by_safety":
+		case "blocked_by_policy":
+		case "provider_refusal":
+		case "refusal":
+		case "tool_refusal":
+		case "tool_call_refusal":
+		case "tool_use_refusal":
+			return "task_failure";
+		default:
+			return undefined;
+	}
+}
+
+function kindFromCode(code: string | number | undefined): ModelFallbackFailureKind | undefined {
+	const normalizedCode = normalizeCode(code);
+	if (normalizedCode === undefined) return undefined;
+	const refusalKind = refusalKindFromCode(code);
+	if (refusalKind !== undefined) return refusalKind;
+	const httpStatusKind = kindFromStatus(integerFrom(code));
+	if (httpStatusKind !== undefined) return httpStatusKind;
+
+	switch (normalizedCode) {
+		case "auth":
+		case "auth_required":
+		case "authentication_required":
+		case "unauthorized":
+		case "forbidden":
+		case "invalid_api_key":
+		case "missing_api_key":
+		case "invalid_key":
+			return "auth_on_candidate_provider";
+		case "etimedout":
+		case "econnreset":
+		case "econnrefused":
+		case "enotfound":
+		case "eai_again":
+		case "fetch_failed":
+		case "network_error":
+		case "timeout":
+		case "timeout_error":
+		case "und_err_connect_timeout":
+			return "network_timeout";
+		case "rate_limit":
+		case "rate_limit_exceeded":
+		case "too_many_requests":
+		case "quota_exceeded":
+			return "rate_limit";
+		case "aborterror":
+		case "aborted":
+		case "cancelled":
+		case "canceled":
+			return "cancelled";
+		case "model_not_found":
+		case "model_unavailable":
+		case "model_disabled":
+		case "unknown_model":
+			return "model_unavailable";
+		case "provider_error":
+		case "api_error":
+		case "service_unavailable":
+		case "temporarily_unavailable":
+		case "overloaded":
+			return "provider_unavailable";
+		default:
+			return undefined;
+	}
+}
+
+const PROVIDER_REFUSAL_FAILURE_PATTERNS: readonly RegExp[] = [
+	/\bfinish[_\s-]?reason\b[^\n]*\bcontent[_\s-]?filter\b/i,
+	/\bcontent[_\s-]?filter(?:ed|ing)?\b/i,
+	/\b(?:safety|policy)\b[^\n]*\b(?:refus(?:e|al|ed|es|ing)?|block(?:ed|ing)?|filter(?:ed|ing)?|violat(?:e|ion|ed|ing)?|disallow(?:ed|ing)?|reject(?:ed|ion|ing)?)\b/i,
+	/\b(?:refus(?:e|al|ed|es|ing)?|block(?:ed|ing)?|filter(?:ed|ing)?|violat(?:e|ion|ed|ing)?|disallow(?:ed|ing)?|reject(?:ed|ion|ing)?)\b[^\n]*\b(?:safety|policy)\b/i,
+	/\btool[_\s-]?(?:call|use)?[_\s-]?refus(?:e|al|ed|es|ing)?\b/i,
+	/\btool(?:\s+call|\s+use)?\b[^\n]*\brefus(?:e|al|ed|es|ing)?\b/i,
+	/\brefus(?:e|al|ed|es|ing)?\b[^\n]*\btool(?:\s+call|\s+use)?\b/i,
+	/\bprovider[_\s-]?refus(?:e|al|ed|es|ing)?\b/i,
+	/\bprovider\b[^\n]*\brefus(?:e|al|ed|es|ing)?\b[^\n]*\b(?:prompt|request|content|policy|safety)\b/i,
+];
+
+function refusalKindFromMessage(message: string): ModelFallbackFailureKind | undefined {
+	if (CANCELLED_FAILURE_PATTERNS.some((pattern) => pattern.test(message))) return "cancelled";
+	if (NON_RETRYABLE_FAILURE_PATTERNS.some((pattern) => pattern.test(message))) return "task_failure";
+	if (PROVIDER_REFUSAL_FAILURE_PATTERNS.some((pattern) => pattern.test(message))) return "task_failure";
+	return undefined;
+}
+
+function fallbackKindFromMessage(message: string, name: string | undefined): ModelFallbackFailureKind | undefined {
+	const refusalKind = refusalKindFromMessage(message);
+	if (refusalKind !== undefined) return refusalKind;
+	const nameKind = kindFromCode(name);
+	if (nameKind !== undefined) return nameKind;
+	if (!RETRYABLE_MODEL_FAILURE_PATTERNS.some((pattern) => pattern.test(message))) return undefined;
+	if (/rate\s*limit|too many requests|\b429\b|quota|billing|credit/i.test(message)) return "rate_limit";
+	if (/auth|unauthori[sz]ed|\b40[13]\b|api key|token expired|forbidden|invalid key/i.test(message)) return "auth_on_candidate_provider";
+	if (/model.*(?:unavailable|disabled|not found|unknown)|(?:unavailable|disabled|not found|unknown).*model/i.test(message)) return "model_unavailable";
+	if (/network|fetch failed|socket|connection refused|timeout|timed? out/i.test(message)) return "network_timeout";
+	return "provider_unavailable";
+}
+
+function signalSource(value: unknown, fallback: ModelFallbackFailureSource | undefined): ModelFallbackFailureSource {
+	if (fallback !== undefined) return fallback;
+	if (stopReasonFrom(value) !== undefined || diagnosticErrors(value).length > 0) return "assistant_message";
+	if (value instanceof Error) return "throw";
+	return "structured";
+}
+
+function makeSignal(
+	kind: ModelFallbackFailureKind,
+	value: unknown,
+	source: ModelFallbackFailureSource | undefined,
+): ModelFallbackFailureSignal {
+	const status = statusFrom(value);
+	const code = codeFrom(value);
+	const name = errorName(value);
+	const stopReason = stopReasonFrom(value);
+	return {
+		kind,
+		message: modelFailureMessage(value),
+		source: signalSource(value, source),
+		...(stopReason !== undefined ? { stopReason } : {}),
+		...(status !== undefined ? { status } : {}),
+		...(code !== undefined ? { code } : {}),
+		...(name !== undefined ? { name } : {}),
+	};
+}
+
+function fallbackSignalFromMessage(
+	value: unknown,
+	source: ModelFallbackFailureSource | undefined,
+): ModelFallbackFailureSignal | undefined {
+	const message = modelFailureMessage(value);
+	if (!message.trim()) return undefined;
+	const kind = fallbackKindFromMessage(message, errorName(value));
+	return kind === undefined ? undefined : makeSignal(kind, value, source);
+}
+
+function classifyAssistantRefusalSignal(
+	value: unknown,
+	source: ModelFallbackFailureSource | undefined,
+): ModelFallbackFailureSignal | undefined {
+	const codeRefusalKind = refusalKindFromCode(codeFrom(value))
+		?? refusalKindFromCode(errorName(value))
+		?? refusalKindFromCode(finishReasonFrom(value));
+	if (codeRefusalKind !== undefined) return makeSignal(codeRefusalKind, value, source);
+
+	const messageRefusalKind = refusalKindFromMessage(directMessageFrom(value) ?? "");
+	return messageRefusalKind === undefined ? undefined : makeSignal(messageRefusalKind, value, source);
+}
+
+function isRefusalSignal(signal: ModelFallbackFailureSignal): boolean {
+	return signal.kind === "cancelled" || signal.kind === "task_failure";
+}
+
+function structuredSignal(
+	value: unknown,
+	seen: Set<unknown>,
+	source?: ModelFallbackFailureSource,
+): ModelFallbackFailureSignal | undefined {
+	if (value === undefined || value === null || seen.has(value)) return undefined;
+	if (typeof value === "object") seen.add(value);
+
+	const stopReason = stopReasonFrom(value)?.toLowerCase();
+	if (stopReason === "aborted") return makeSignal("cancelled", value, source);
+
+	const directRefusalSignal = classifyAssistantRefusalSignal(value, source);
+	if (directRefusalSignal !== undefined) return directRefusalSignal;
+
+	const codeKind = kindFromCode(codeFrom(value));
+	const nameKind = kindFromCode(errorName(value));
+	if (codeKind === "cancelled" || nameKind === "cancelled") return makeSignal("cancelled", value, source);
+
+	let firstNestedFallbackSignal: ModelFallbackFailureSignal | undefined;
+	const nestedSeen = new Set(seen);
+	for (const diagnosticError of diagnosticErrors(value)) {
+		const diagnosticSignal = structuredSignal(diagnosticError, nestedSeen, "diagnostic")
+			?? fallbackSignalFromMessage(diagnosticError, "diagnostic");
+		if (diagnosticSignal === undefined) continue;
+		if (isRefusalSignal(diagnosticSignal)) return diagnosticSignal;
+		firstNestedFallbackSignal ??= diagnosticSignal;
+	}
+
+	const cause = causeOf(value);
+	const causeSignal = structuredSignal(cause, nestedSeen, source)
+		?? fallbackSignalFromMessage(cause, source);
+	if (causeSignal !== undefined) {
+		if (isRefusalSignal(causeSignal)) return causeSignal;
+		firstNestedFallbackSignal ??= causeSignal;
+	}
+
+	const statusKind = kindFromStatus(statusFrom(value));
+	if (statusKind !== undefined) return makeSignal(statusKind, value, source);
+	if (codeKind !== undefined) return makeSignal(codeKind, value, source);
+	if (nameKind !== undefined) return makeSignal(nameKind, value, source);
+
+	if (firstNestedFallbackSignal !== undefined) return firstNestedFallbackSignal;
+
+	if (stopReason === "error") return makeSignal("provider_unavailable", value, source);
+
+	return undefined;
+}
+
+function messageFromUnknown(value: unknown, seen: Set<unknown>): string | undefined {
+	if (value === undefined || value === null || seen.has(value)) return undefined;
+	if (typeof value === "string") return value.trim().length > 0 ? value : undefined;
+	if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") return String(value);
+	if (typeof value === "symbol" || typeof value === "function") return undefined;
+	seen.add(value);
+
+	if (value instanceof Error && value.message.trim().length > 0) return value.message;
+	const directMessage = directMessageFrom(value);
+	if (directMessage !== undefined) return directMessage;
+
+	for (const diagnosticError of diagnosticErrors(value)) {
+		const diagnosticMessage = messageFromUnknown(diagnosticError, seen);
+		if (diagnosticMessage !== undefined) return diagnosticMessage;
+	}
+
+	const causeMessage = messageFromUnknown(causeOf(value), seen);
+	if (causeMessage !== undefined) return causeMessage;
+
+	const stopReason = stopReasonFrom(value);
+	if (stopReason !== undefined) return `Assistant message ended with stopReason:${stopReason}`;
+	const finishReason = finishReasonFrom(value);
+	if (finishReason !== undefined) return `Model request finished with finish_reason:${finishReason}`;
+	const status = statusFrom(value);
+	if (status !== undefined) return `Model request failed with status ${status}`;
+	const code = codeFrom(value);
+	if (code !== undefined) return `Model request failed with code ${String(code)}`;
+
+	return undefined;
+}
+
+export function modelFailureMessage(error: unknown): string {
+	const structuredMessage = messageFromUnknown(error, new Set());
+	if (structuredMessage !== undefined) return structuredMessage;
+	const rendered = String(error);
+	return rendered === "[object Object]" ? "Model request failed" : rendered;
+}
+
+export function normalizeModelFailureSignal(error: unknown): ModelFallbackFailureSignal {
+	const structured = structuredSignal(error, new Set());
+	if (structured !== undefined) return structured;
+
+	const message = modelFailureMessage(error);
+	const name = errorName(error);
+	const fallbackKind = message.trim().length > 0
+		? fallbackKindFromMessage(message, name)
+		: undefined;
+	return {
+		kind: fallbackKind ?? "unknown",
+		message,
+		source: "string_fallback",
+		...(name !== undefined ? { name } : {}),
+	};
+}
+
+export function isRetryableModelFailure(error: unknown): boolean {
+	if (error === undefined) return false;
+	const signal = normalizeModelFailureSignal(error);
+	return FALLBACKABLE_FAILURE_KINDS.has(signal.kind);
 }
 
 export function formatModelAttemptNote(attempt: ModelAttemptSummary, nextModel?: string): string {