@sayknow-cli/ai 0.3.15 → 0.4.0

package/src/providers/google-gemini-cli.ts

@@ -20,6 +20,7 @@ import type {
 } from "../types";
 import { normalizeSystemPrompts } from "../utils";
 import { AssistantMessageEventStream } from "../utils/event-stream";
+import { transportFailureFacts } from "../utils/fallback-transport";
 import { appendRawHttpRequestDumpFor400, type RawHttpRequestDump, withHttpStatus } from "../utils/http-inspector";
 import { resolveRetryBudget } from "../utils/retry-budget";
 // Refresh is the sole responsibility of AuthStorage (broker-aware, single-flighted);
@@ -130,6 +131,22 @@ function extractErrorMessage(errorText: string): string {
 	return errorText;
 }
 
+function createGeminiCliHttpError(response: Response, errorText: string, formatErrorMessage = true): Error {
+	const message = formatErrorMessage ? extractErrorMessage(errorText) : errorText;
+	const error = withHttpStatus(
+		new Error(`Cloud Code Assist API error (${response.status}): ${message}`),
+		response.status,
+	) as Error & { code?: string; headers?: Headers };
+	error.headers = response.headers;
+	try {
+		const code = (JSON.parse(errorText) as { error?: { code?: unknown } }).error?.code;
+		if (typeof code === "string") error.code = code;
+	} catch {
+		// The response body is not JSON.
+	}
+	return error;
+}
+
 interface GeminiCliApiKeyPayload {
 	token?: unknown;
 	projectId?: unknown;
@@ -380,11 +397,12 @@ export const streamGoogleGeminiCli: StreamFunction<"google-gemini-cli"> = (
 			);
 			if (!response.ok && sentForcedToolChoice) {
 				const errorText = await response.text();
-				const error = withHttpStatus(
-					new Error(`Cloud Code Assist API error (${response.status}): ${extractErrorMessage(errorText)}`),
-					response.status,
-				);
-				if (firstTokenTime === undefined && isForcedToolChoiceUnsupportedError(error, true)) {
+				const error = createGeminiCliHttpError(response, errorText);
+				if (
+					!options?.fallbackManaged &&
+					firstTokenTime === undefined &&
+					isForcedToolChoiceUnsupportedError(error, true)
+				) {
 					const beforeMark = resolveToolChoice(model, options?.toolChoice);
 					markToolChoiceIncapability(model, "auto", error.message);
 					stream.push({
@@ -423,10 +441,7 @@ export const streamGoogleGeminiCli: StreamFunction<"google-gemini-cli"> = (
 			}
 			if (!response.ok) {
 				const errorText = await response.text();
-				throw withHttpStatus(
-					new Error(`Cloud Code Assist API error (${response.status}): ${extractErrorMessage(errorText)}`),
-					response.status,
-				);
+				throw createGeminiCliHttpError(response, errorText);
 			}
 			const requestUrl = response.url;
 
@@ -629,10 +644,7 @@ export const streamGoogleGeminiCli: StreamFunction<"google-gemini-cli"> = (
 
 					if (!currentResponse.ok) {
 						const retryErrorText = await currentResponse.text();
-						throw withHttpStatus(
-							new Error(`Cloud Code Assist API error (${currentResponse.status}): ${retryErrorText}`),
-							currentResponse.status,
-						);
+						throw createGeminiCliHttpError(currentResponse, retryErrorText, false);
 					}
 				}
 
@@ -671,6 +683,7 @@ export const streamGoogleGeminiCli: StreamFunction<"google-gemini-cli"> = (
 			}
 			output.stopReason = options?.signal?.aborted ? "aborted" : "error";
 			output.errorStatus = extractHttpStatusFromError(error);
+			output.transportFailure = transportFailureFacts(error);
 			output.errorMessage = await appendRawHttpRequestDumpFor400(
 				error instanceof Error ? error.message : JSON.stringify(error),
 				error,

package/src/providers/google-shared.ts

@@ -20,6 +20,7 @@ import type {
 } from "../types";
 import { normalizeSystemPrompts, sanitizeJsonStrings } from "../utils";
 import { AssistantMessageEventStream } from "../utils/event-stream";
+import { transportFailureFacts } from "../utils/fallback-transport";
 import { finalizeErrorMessage, type RawHttpRequestDump, withHttpStatus } from "../utils/http-inspector";
 import { normalizeSchemaForCCA, normalizeSchemaForGoogle, toolWireSchema } from "../utils/schema";
 import {
@@ -868,7 +869,11 @@ export function streamGoogleGenAI<T extends "google-generative-ai" | "google-ver
 					new Error(`Google API error (${response.status}): ${extractGoogleErrorMessage(errorText)}`),
 					response.status,
 				);
-				if (firstTokenTime === undefined && isForcedToolChoiceUnsupportedError(error, true)) {
+				if (
+					!options?.fallbackManaged &&
+					firstTokenTime === undefined &&
+					isForcedToolChoiceUnsupportedError(error, true)
+				) {
 					const beforeMark = resolveToolChoice(model, options?.toolChoice);
 					markToolChoiceIncapability(model, "auto", error.message);
 					stream.push({
@@ -938,6 +943,7 @@ export function streamGoogleGenAI<T extends "google-generative-ai" | "google-ver
 			}
 			output.stopReason = options?.signal?.aborted ? "aborted" : "error";
 			output.errorStatus = extractHttpStatusFromError(error);
+			output.transportFailure = transportFailureFacts(error);
 			output.errorMessage = await finalizeErrorMessage(error, rawRequestDump);
 			output.duration = Date.now() - startTime;
 			if (firstTokenTime) output.ttft = firstTokenTime - startTime;

package/src/providers/ollama.ts

@@ -16,6 +16,7 @@ import type {
 } from "../types";
 import { normalizeSystemPrompts } from "../utils";
 import { AssistantMessageEventStream } from "../utils/event-stream";
+import { transportFailureFacts } from "../utils/fallback-transport";
 import { finalizeErrorMessage, type RawHttpRequestDump } from "../utils/http-inspector";
 import { parseStreamingJson } from "../utils/json-parse";
 import { resolveRetryBudget } from "../utils/retry-budget";
@@ -431,7 +432,11 @@ export const streamOllama: StreamFunction<"ollama-chat"> = (
 					`HTTP ${response.status} from ${baseUrl}/api/chat: ${await response.text().catch(() => "")}`,
 				);
 				(error as Error & { status?: number }).status = response.status;
-				if (firstTokenTime === undefined && isForcedToolChoiceUnsupportedError(error, true)) {
+				if (
+					firstTokenTime === undefined &&
+					!options.fallbackManaged &&
+					isForcedToolChoiceUnsupportedError(error, true)
+				) {
 					markToolChoiceIncapability(model, "auto", error.message);
 					stream.push({
 						type: "toolChoiceIncapability",
@@ -590,6 +595,7 @@ export const streamOllama: StreamFunction<"ollama-chat"> = (
 			}
 			output.stopReason = options.signal?.aborted ? "aborted" : "error";
 			output.errorStatus = extractHttpStatusFromError(error);
+			output.transportFailure = transportFailureFacts(error);
 			output.errorMessage = await finalizeErrorMessage(error, rawRequestDump);
 			output.duration = Date.now() - startTime;
 			if (firstTokenTime) {

package/src/providers/openai-chat-server.ts

@@ -14,6 +14,7 @@ import type {
 	ResolvedServiceTier,
 	StopReason,
 	TextContent,
+	ThinkingContent,
 	Tool,
 	ToolCall,
 	ToolResultMessage,
@@ -416,6 +417,29 @@ function buildUsage(message: AssistantMessage): Record<string, unknown> {
 	return usage;
 }
 
+function isResponsesFamilyApi(api: AssistantMessage["api"]): boolean {
+	return api === "openai-responses" || api === "openai-codex-responses";
+}
+
+function safeThinkingText(content: ThinkingContent, api: AssistantMessage["api"]): string | undefined {
+	if (isResponsesFamilyApi(api) && content.provenance === undefined) return undefined;
+	if (content.provenance === "raw") return undefined;
+	if (content.provenance === "mixed") return content.summaryText;
+	if (content.provenance === "summary") return content.summaryText ?? content.thinking;
+	return content.thinking;
+}
+
+function hasRawOrMixedThinking(partial: AssistantMessage, contentIndex: number): boolean {
+	const content = partial.content[contentIndex];
+	return content?.type === "thinking" && (content.provenance === "raw" || content.provenance === "mixed");
+}
+
+/** Responses-family reasoning is untrusted until output_item.done assigns provenance. */
+function hasUnfinalizedResponsesThinking(partial: AssistantMessage, contentIndex: number): boolean {
+	const content = partial.content[contentIndex];
+	return content?.type !== "thinking" || (isResponsesFamilyApi(partial.api) && content.provenance === undefined);
+}
+
 function flattenAssistant(message: AssistantMessage): {
 	text: string;
 	reasoning: string;
@@ -429,9 +453,11 @@ function flattenAssistant(message: AssistantMessage): {
 			case "text":
 				text += part.text;
 				break;
-			case "thinking":
-				reasoning += part.thinking;
+			case "thinking": {
+				const thinking = safeThinkingText(part, message.api);
+				if (thinking !== undefined) reasoning += thinking;
 				break;
+			}
 			case "redactedThinking":
 				// Opaque blob — surface verbatim on the reasoning channel so the
 				// concatenation round-trips through clients that just echo it.
@@ -521,6 +547,18 @@ export function encodeStream(
 			let nextToolIndex = 0;
 			let hasToolCalls = false;
 			let finishReason: string = "stop";
+			// contentIndexes that already streamed a reasoning summary delta, so a
+			// final-only reasoning_summary_end does not duplicate streamed summary text.
+			const summaryDeltaSeen = new Set<number>();
+			// Responses assigns reasoning provenance only at output_item.done. Keep its
+			// pre-classification bytes out of this public compatibility stream.
+			const pendingThinkingDeltas = new Map<number, string[]>();
+
+			const writeThinkingDelta = (thinking: string) => {
+				// DeepSeek-style / o-series reasoning channel. Clients that don't
+				// understand it ignore the unknown delta key.
+				if (thinking.length > 0) writeSse(controller, baseChunk({ reasoning_content: thinking }, null));
+			};
 
 			try {
 				// Initial role chunk.
@@ -534,14 +572,60 @@ export function encodeStream(
 							}
 							break;
 
-						case "thinking_delta":
-							// DeepSeek-style / o-series reasoning channel. Clients that don't
-							// understand it ignore the unknown delta key.
+						case "thinking_delta": {
+							if (hasRawOrMixedThinking(event.partial, event.contentIndex)) break;
+							if (hasUnfinalizedResponsesThinking(event.partial, event.contentIndex)) {
+								const deltas = pendingThinkingDeltas.get(event.contentIndex) ?? [];
+								deltas.push(event.delta);
+								pendingThinkingDeltas.set(event.contentIndex, deltas);
+								break;
+							}
+							writeThinkingDelta(event.delta);
+							break;
+						}
+						case "thinking_start":
+							if (
+								!hasRawOrMixedThinking(event.partial, event.contentIndex) &&
+								hasUnfinalizedResponsesThinking(event.partial, event.contentIndex)
+							) {
+								pendingThinkingDeltas.set(event.contentIndex, []);
+							}
+							break;
+						case "thinking_end": {
+							const pending = pendingThinkingDeltas.get(event.contentIndex);
+							pendingThinkingDeltas.delete(event.contentIndex);
+							if (
+								hasRawOrMixedThinking(event.partial, event.contentIndex) ||
+								hasUnfinalizedResponsesThinking(event.partial, event.contentIndex)
+							)
+								break;
+							if (pending) for (const delta of pending) writeThinkingDelta(delta);
+							break;
+						}
+						case "reasoning_summary_start":
+							// Chat format has no explicit reasoning open frame.
+							break;
+
+						case "reasoning_summary_delta":
+							// Provider-displayable summary reasoning surfaces on the same
+							// reasoning_content channel as raw thinking for this legacy format.
 							if (event.delta.length > 0) {
+								// Only a non-whitespace delta counts as a delivered summary; a bare
+								// separator ("\n\n") must not suppress a later final-only end content.
+								if (event.delta.trim().length > 0) summaryDeltaSeen.add(event.contentIndex);
 								writeSse(controller, baseChunk({ reasoning_content: event.delta }, null));
 							}
 							break;
 
+						case "reasoning_summary_end":
+							// Final-only summary: text arrives only on the end event with no prior
+							// deltas, so surface it now (skip when deltas already streamed to avoid
+							// duplicating the summary).
+							if (event.content.length > 0 && !summaryDeltaSeen.has(event.contentIndex)) {
+								writeSse(controller, baseChunk({ reasoning_content: event.content }, null));
+							}
+							break;
+
 						case "toolcall_start": {
 							hasToolCalls = true;
 							const idx = nextToolIndex++;
@@ -578,6 +662,7 @@ export function encodeStream(
 						}
 
 						case "done":
+							pendingThinkingDeltas.clear();
 							finishReason =
 								event.reason === "toolUse"
 									? "tool_calls"
@@ -593,6 +678,7 @@ export function encodeStream(
 							return;
 
 						case "error": {
+							pendingThinkingDeltas.clear();
 							const msg = event.error.errorMessage ?? "stream error";
 							writeSse(controller, { error: { message: msg, type: "upstream_error" } });
 							controller.close();
@@ -607,10 +693,12 @@ export function encodeStream(
 				}
 
 				// Stream ended without a terminal `done` (defensive). Close gracefully.
+				pendingThinkingDeltas.clear();
 				writeSse(controller, baseChunk({}, hasToolCalls ? "tool_calls" : "stop"));
 				controller.enqueue(encoder.encode("data: [DONE]\n\n"));
 				controller.close();
 			} catch (err) {
+				pendingThinkingDeltas.clear();
 				const msg = err instanceof Error ? err.message : String(err);
 				writeSse(controller, { error: { message: msg, type: "upstream_error" } });
 				controller.close();

package/src/providers/openai-codex/response-handler.ts

@@ -14,6 +14,7 @@ export type CodexRateLimits = {
 export type CodexErrorInfo = {
 	message: string;
 	status: number;
+	code?: string;
 	friendlyMessage?: string;
 	rateLimits?: CodexRateLimits;
 	raw?: string;
@@ -24,6 +25,7 @@ export async function parseCodexError(response: Response): Promise<CodexErrorInf
 	let message = raw || response.statusText || "Request failed";
 	let friendlyMessage: string | undefined;
 	let rateLimits: CodexRateLimits | undefined;
+	let code: string | undefined;
 
 	try {
 		const parsed = JSON.parse(raw) as { error?: Record<string, unknown> };
@@ -45,16 +47,21 @@ export async function parseCodexError(response: Response): Promise<CodexErrorInf
 				? { primary, secondary }
 				: undefined;
 
-		const code = String((err as { code?: string; type?: string }).code ?? (err as { type?: string }).type ?? "");
+		code =
+			typeof (err as { code?: unknown }).code === "string"
+				? (err as { code: string }).code
+				: typeof (err as { type?: unknown }).type === "string"
+					? (err as { type: string }).type
+					: undefined;
 		const resetsAt = (err as { resets_at?: number }).resets_at ?? primary.resets_at ?? secondary.resets_at;
 		const mins = resetsAt ? Math.max(0, Math.round((resetsAt * 1000 - Date.now()) / 60000)) : undefined;
 
-		if (/usage_limit_reached|usage_not_included/i.test(code)) {
+		if (/usage_limit_reached|usage_not_included/i.test(code ?? "")) {
 			const planType = (err as { plan_type?: string }).plan_type;
 			const plan = planType ? ` (${String(planType).toLowerCase()} plan)` : "";
 			const when = mins !== undefined ? ` Try again in ~${mins} min.` : "";
 			friendlyMessage = `You have hit your ChatGPT usage limit${plan}.${when}`.trim();
-		} else if (/rate_limit_exceeded/i.test(code) || response.status === 429) {
+		} else if (/rate_limit_exceeded/i.test(code ?? "") || response.status === 429) {
 			const when = mins !== undefined ? ` Try again in ~${mins} min.` : "";
 			friendlyMessage = `ChatGPT rate limit exceeded.${when}`.trim();
 		}
@@ -69,6 +76,7 @@ export async function parseCodexError(response: Response): Promise<CodexErrorInf
 		message,
 		status: response.status,
 		friendlyMessage,
+		code,
 		rateLimits,
 		raw: raw,
 	};

package/src/providers/openai-codex-responses.ts

@@ -43,10 +43,12 @@ import {
 	createOpenAIResponsesHistoryPayload,
 	getOpenAIResponsesHistoryItems,
 	getOpenAIResponsesHistoryPayload,
+	neutralizeResponsesInputControlTokens,
 	normalizeSystemPrompts,
 	sanitizeOpenAIResponsesHistoryItemsForReplay,
 } from "../utils";
 import { AssistantMessageEventStream } from "../utils/event-stream";
+import { transportFailureFacts } from "../utils/fallback-transport";
 import { finalizeErrorMessage, type RawHttpRequestDump } from "../utils/http-inspector";
 import { getOpenAIStreamIdleTimeoutMs, iterateWithIdleTimeout } from "../utils/idle-iterator";
 import { parseStreamingJson } from "../utils/json-parse";
@@ -111,9 +113,15 @@ const CODEX_NON_RETRYABLE_EVENT_CODES = new Set([
 	"invalid_request_error",
 	"invalid_schema",
 	"invalid_tool_schema",
+	// A poisoned-history rejection (`Request blocked (code=invalid_prompt)`) is a
+	// deterministic content fault, not a transient upstream failure: retrying the
+	// same request re-sends the same offending item and re-triggers the block, so
+	// classify it as explicitly non-retryable instead of relying on omission
+	// (the request-boundary sanitizer, not a provider retry, is the recovery path).
+	"invalid_prompt",
 ]);
 const CODEX_NON_RETRYABLE_EVENT_MESSAGE =
-	/invalid[_ -]function[_ -]parameters|invalid schema for function|invalid[_ -]tool[_ -]schema|schema must have type ["']?object["']?/i;
+	/invalid[_ -]function[_ -]parameters|invalid schema for function|invalid[_ -]tool[_ -]schema|schema must have type ["']?object["']?|request blocked[^\n]*invalid[_ -]prompt|code=invalid[_ -]prompt/i;
 const CODEX_RETRYABLE_EVENT_MESSAGE =
 	/processing your request|retry your request|temporar(?:y|ily)|overloaded|service.?unavailable|internal error|server error/i;
 const CODEX_PROVIDER_SESSION_STATE_KEY = "openai-codex-responses";
@@ -131,6 +139,7 @@ const CODEX_PROGRESS_EVENT_TYPES = new Set([
 	"response.reasoning_summary_part.added",
 	"response.reasoning_summary_text.delta",
 	"response.reasoning_summary_part.done",
+	"response.reasoning_text.delta",
 	"response.content_part.added",
 	"response.output_text.delta",
 	"response.refusal.delta",
@@ -153,8 +162,8 @@ function isCodexStreamProgressEvent(event: unknown): boolean {
 }
 type CodexTransport = "sse" | "websocket";
 type CodexEventItem = ResponseReasoningItem | ResponseOutputMessage | ResponseFunctionToolCall | ResponseCustomToolCall;
-type CodexOutputBlock = ThinkingContent | TextContent | (ToolCall & { partialJson: string });
-
+type CodexThinkingBlock = ThinkingContent & { summaryBuffer: string; rawBuffer: string; summaryStarted: boolean };
+type CodexOutputBlock = CodexThinkingBlock | TextContent | (ToolCall & { partialJson: string });
 export interface OpenAICodexWebSocketDebugStats {
 	fullContextRequests: number;
 	deltaRequests: number;
@@ -633,7 +642,7 @@ async function buildTransformedCodexRequestBody(
 ): Promise<RequestBody> {
 	const params: RequestBody = {
 		model: model.id,
-		input: [...convertMessages(model, context)],
+		input: neutralizeResponsesInputControlTokens(convertMessages(model, context)),
 		stream: true,
 		prompt_cache_key: normalizeOpenAIResponsesPromptCacheKey(options?.sessionId),
 	};
@@ -993,6 +1002,11 @@ function handleCodexStreamEvent(args: {
 		return firstTokenTime;
 	}
 
+	if (eventType === "response.reasoning_text.delta") {
+		handleReasoningTextDelta(runtime.currentItem, runtime.currentBlock, rawEvent, stream, output, blockIndex);
+		return firstTokenTime;
+	}
+
 	if (eventType === "response.content_part.added") {
 		handleContentPartAdded(runtime.currentItem, rawEvent);
 		return firstTokenTime;
@@ -1067,7 +1081,7 @@ function handleCodexStreamEvent(args: {
 
 function createOutputBlockForItem(item: CodexEventItem): CodexOutputBlock | null {
 	if (item.type === "reasoning") {
-		return { type: "thinking", thinking: "" };
+		return { type: "thinking", thinking: "", summaryBuffer: "", rawBuffer: "", summaryStarted: false };
 	}
 	if (item.type === "message") {
 		return { type: "text", text: "" };
@@ -1118,13 +1132,18 @@ function handleReasoningSummaryTextDelta(
 	blockIndex: () => number,
 ): void {
 	if (currentItem?.type !== "reasoning" || currentBlock?.type !== "thinking") return;
+	if (!currentBlock.summaryStarted) {
+		currentBlock.summaryStarted = true;
+		stream.push({ type: "reasoning_summary_start", contentIndex: blockIndex(), partial: output });
+	}
 	currentItem.summary = currentItem.summary || [];
 	const lastPart = currentItem.summary[currentItem.summary.length - 1];
 	if (!lastPart) return;
 	const delta = (rawEvent as { delta?: string }).delta || "";
 	currentBlock.thinking += delta;
+	currentBlock.summaryBuffer += delta;
 	lastPart.text += delta;
-	stream.push({ type: "thinking_delta", contentIndex: blockIndex(), delta, partial: output });
+	stream.push({ type: "reasoning_summary_delta", contentIndex: blockIndex(), delta, partial: output });
 }
 
 function handleReasoningSummaryPartDone(
@@ -1139,8 +1158,24 @@ function handleReasoningSummaryPartDone(
 	const lastPart = currentItem.summary[currentItem.summary.length - 1];
 	if (!lastPart) return;
 	currentBlock.thinking += "\n\n";
+	currentBlock.summaryBuffer += "\n\n";
 	lastPart.text += "\n\n";
-	stream.push({ type: "thinking_delta", contentIndex: blockIndex(), delta: "\n\n", partial: output });
+	stream.push({ type: "reasoning_summary_delta", contentIndex: blockIndex(), delta: "\n\n", partial: output });
+}
+
+function handleReasoningTextDelta(
+	currentItem: CodexEventItem | null,
+	currentBlock: CodexOutputBlock | null,
+	rawEvent: Record<string, unknown>,
+	stream: AssistantMessageEventStream,
+	output: AssistantMessage,
+	blockIndex: () => number,
+): void {
+	if (currentItem?.type !== "reasoning" || currentBlock?.type !== "thinking") return;
+	const delta = (rawEvent as { delta?: string }).delta || "";
+	currentBlock.thinking += delta;
+	currentBlock.rawBuffer += delta;
+	stream.push({ type: "thinking_delta", contentIndex: blockIndex(), delta, partial: output });
 }
 
 function handleContentPartAdded(currentItem: CodexEventItem | null, rawEvent: Record<string, unknown>): void {
@@ -1243,14 +1278,50 @@ function handleOutputItemDone(
 	runtime.nativeOutputItems.push(item as unknown as Record<string, unknown>);
 
 	if (item.type === "reasoning" && runtime.currentBlock?.type === "thinking") {
-		runtime.currentBlock.thinking = item.summary?.map(summary => summary.text).join("\n\n") || "";
-		runtime.currentBlock.thinkingSignature = JSON.stringify(item);
-		stream.push({
-			type: "thinking_end",
-			contentIndex: blockIndex(),
-			content: runtime.currentBlock.thinking,
-			partial: output,
-		});
+		const block = runtime.currentBlock;
+		// Prefer the streamed summary buffer only when it carries real text; a
+		// part.done before/without any summary_text delta leaves only separators, so
+		// fall back to the canonical item.summary from output_item.done (matches the
+		// shared Responses decoder).
+		const bufferSummary = block.summaryBuffer ?? "";
+		const itemSummary = item.summary?.map(summary => summary.text).join("\n\n") ?? "";
+		const summaryText = bufferSummary.trim() ? bufferSummary : itemSummary;
+		const rawText = block.rawBuffer;
+		const mutable = block as { provenance?: "summary" | "raw" | "mixed"; summaryText?: string; rawText?: string };
+		if (mutable.provenance === undefined) {
+			if (mutable.summaryText === undefined && summaryText) mutable.summaryText = summaryText;
+			if (mutable.rawText === undefined && rawText) mutable.rawText = rawText;
+			mutable.provenance = summaryText && rawText ? "mixed" : summaryText ? "summary" : rawText ? "raw" : undefined;
+		}
+		// Finalized display string must exclude raw CoT when a summary exists (parity
+		// with openai-responses-shared). Derive from STORED write-once provenance fields
+		// so a later/duplicate raw-only finalization cannot overwrite a summary/mixed
+		// block's safe display with raw CoT; raw-only stays raw.
+		{
+			const effSummary = mutable.summaryText ?? summaryText;
+			const effRaw = mutable.rawText ?? rawText;
+			block.thinking = mutable.provenance === "raw" ? effRaw : effSummary || effRaw;
+		}
+		block.thinkingSignature = JSON.stringify(item);
+		delete (block as { summaryBuffer?: string }).summaryBuffer;
+		delete (block as { rawBuffer?: string }).rawBuffer;
+		const wasSummaryStarted = block.summaryStarted;
+		delete (block as { summaryStarted?: boolean }).summaryStarted;
+		if (summaryText) {
+			// Emit a summary start first when none was streamed (part.added/done or
+			// canonical done-item summary with no summary_text delta), so consumers that
+			// open a summary on start don't receive an orphaned reasoning_summary_end.
+			if (!wasSummaryStarted) {
+				stream.push({ type: "reasoning_summary_start", contentIndex: blockIndex(), partial: output });
+			}
+			stream.push({
+				type: "reasoning_summary_end",
+				contentIndex: blockIndex(),
+				content: summaryText,
+				partial: output,
+			});
+		}
+		stream.push({ type: "thinking_end", contentIndex: blockIndex(), content: block.thinking, partial: output });
 		runtime.currentBlock = null;
 		return;
 	}
@@ -1372,6 +1443,7 @@ async function recoverCodexStreamError(
 	runtime: CodexStreamRuntime,
 	error: unknown,
 ): Promise<boolean> {
+	if (context.options?.fallbackManaged) return false;
 	if (await tryRetryWithoutForcedToolChoice(context, runtime, error)) {
 		return true;
 	}
@@ -1396,6 +1468,7 @@ async function tryRetryWithoutForcedToolChoice(
 	error: unknown,
 ): Promise<boolean> {
 	if (
+		context.options?.fallbackManaged ||
 		runtime.providerRetryAttempt > 0 ||
 		context.output.content.length > 0 ||
 		context.firstTokenTime !== undefined ||
@@ -1468,7 +1541,12 @@ async function tryReconnectCodexWebSocketOnConnectionLimit(
 		return false;
 	}
 	const websocketState = context.requestContext.websocketState;
-	if (!websocketState || runtime.transport !== "websocket" || context.options?.signal?.aborted) {
+	if (
+		!websocketState ||
+		runtime.transport !== "websocket" ||
+		context.options?.signal?.aborted ||
+		context.options?.fallbackManaged
+	) {
 		return false;
 	}
 
@@ -1519,6 +1597,7 @@ async function tryRecoverCodexPreviousResponseNotFound(
 	if (
 		!isCodexPreviousResponseNotFound(error) ||
 		!websocketState ||
+		context.options?.fallbackManaged ||
 		runtime.transport !== "websocket" ||
 		context.output.content.length > 0 ||
 		context.options?.signal?.aborted ||
@@ -1556,7 +1635,8 @@ async function tryReplayWebsocketFailureOverSse(
 		isCodexWebSocketRetryableStreamError(error) &&
 		runtime.canSafelyReplayWebsocketOverSse &&
 		!runtime.sawTerminalEvent &&
-		!context.options?.signal?.aborted;
+		!context.options?.signal?.aborted &&
+		!context.options?.fallbackManaged;
 	if (!canReplay) return false;
 
 	const state = websocketState;
@@ -1608,7 +1688,8 @@ async function tryRetryCodexProviderError(
 		!isRetryableCodexProviderError(error) ||
 		context.output.content.length > 0 ||
 		runtime.providerRetryAttempt >= resolveRetryBudget(context.options?.streamMaxRetries, CODEX_MAX_RETRIES) ||
-		context.options?.signal?.aborted
+		context.options?.signal?.aborted ||
+		context.options?.fallbackManaged
 	) {
 		return false;
 	}
@@ -1692,6 +1773,7 @@ async function handleCodexStreamFailure(
 	}
 	output.stopReason = context.options?.signal?.aborted ? "aborted" : "error";
 	output.errorStatus = extractHttpStatusFromError(error);
+	output.transportFailure = transportFailureFacts(error);
 	output.errorMessage = await finalizeErrorMessage(error, context.requestContext.rawRequestDump);
 	output.duration = Date.now() - context.startTime;
 	if (context.firstTokenTime) {
@@ -1719,6 +1801,7 @@ export const streamOpenAICodexResponses: StreamFunction<"openai-codex-responses"
 			try {
 				initialTransport = await openInitialCodexEventStream(model, options, requestSetup, requestContext);
 			} catch (error) {
+				if (options?.fallbackManaged) throw error;
 				initialTransport = await retryCodexInitialTransportWithoutToolChoice(
 					model,
 					options,
@@ -2408,6 +2491,7 @@ async function openCodexSseEventStream(
 		const error = new Error(info.friendlyMessage || info.message);
 		(error as { headers?: Headers; status?: number }).headers = response.headers;
 		(error as { headers?: Headers; status?: number }).status = response.status;
+		(error as { code?: string }).code = info.code;
 		throw error;
 	}
 	if (!response.body) {
@@ -2635,8 +2719,11 @@ function normalizeInputMessageContent(
 	return convertResponsesInputContent(content, model.input.includes("image")) ?? [];
 }
 
-/** @internal Exported for tests. */
-export { convertMessages as convertCodexResponsesMessages };
+/** @internal Exported for tests. `classifyCodexFailureEventRetryable` is the retry classification of a Codex failure event. */
+export {
+	convertMessages as convertCodexResponsesMessages,
+	isRetryableCodexFailureEvent as classifyCodexFailureEventRetryable,
+};
 
 /**
  * Whether this OpenAI code backend-backend model should get the custom-tool grammar