@f5-sales-demo/pi-ai 19.51.2

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

@@ -0,0 +1,2345 @@
+import * as os from "node:os";
+import {
+	$env,
+	$flag,
+	abortableSleep,
+	asRecord,
+	logger,
+	readSseJson,
+	structuredCloneJSON,
+} from "@f5xc-salesdemos/pi-utils";
+import type OpenAI from "openai";
+import type {
+	ResponseFunctionToolCall,
+	ResponseInput,
+	ResponseInputContent,
+	ResponseInputImage,
+	ResponseInputText,
+	ResponseOutputMessage,
+	ResponseReasoningItem,
+} from "openai/resources/responses/responses";
+import packageJson from "../../package.json" with { type: "json" };
+import { calculateCost } from "../models";
+import { isUsageLimitError } from "../rate-limit-utils";
+import { getEnvApiKey } from "../stream";
+import {
+	type Api,
+	type AssistantMessage,
+	type Context,
+	isSpecialServiceTier,
+	type Model,
+	type ProviderSessionState,
+	type ServiceTier,
+	type StreamFunction,
+	type StreamOptions,
+	type TextContent,
+	type ThinkingContent,
+	type Tool,
+	type ToolCall,
+	type ToolChoice,
+} from "../types";
+import {
+	createOpenAIResponsesHistoryPayload,
+	getOpenAIResponsesHistoryItems,
+	getOpenAIResponsesHistoryPayload,
+	normalizeResponsesToolCallId,
+} from "../utils";
+import { AssistantMessageEventStream } from "../utils/event-stream";
+import { finalizeErrorMessage, type RawHttpRequestDump } from "../utils/http-inspector";
+import { getOpenAIStreamIdleTimeoutMs, iterateWithIdleTimeout } from "../utils/idle-iterator";
+import { parseStreamingJson } from "../utils/json-parse";
+import { adaptSchemaForStrict, NO_STRICT } from "../utils/schema";
+import {
+	CODEX_BASE_URL,
+	getCodexAccountId,
+	OPENAI_HEADER_VALUES,
+	OPENAI_HEADERS,
+	URL_PATHS,
+} from "./openai-codex/constants";
+import {
+	type CodexRequestOptions,
+	type InputItem,
+	type RequestBody,
+	transformRequestBody,
+} from "./openai-codex/request-transformer";
+import { parseCodexError } from "./openai-codex/response-handler";
+import { encodeTextSignatureV1, mapOpenAIResponsesStopReason, parseTextSignature } from "./openai-responses-shared";
+import { transformMessages } from "./transform-messages";
+
+export interface OpenAICodexResponsesOptions extends StreamOptions {
+	reasoning?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh";
+	reasoningSummary?: "auto" | "concise" | "detailed" | null;
+	textVerbosity?: "low" | "medium" | "high";
+	include?: string[];
+	codexMode?: boolean;
+	toolChoice?: ToolChoice;
+	preferWebsockets?: boolean;
+	serviceTier?: ServiceTier;
+}
+
+export const CODEX_INSTRUCTIONS = `You are an expert coding assistant operating inside pi, a coding agent harness.`;
+
+export interface CodexSystemPrompt {
+	instructions: string;
+	developerMessages: string[];
+}
+
+export function buildCodexSystemPrompt(args: { userSystemPrompt?: string }): CodexSystemPrompt {
+	const { userSystemPrompt } = args;
+	const developerMessages: string[] = [];
+
+	if (userSystemPrompt && userSystemPrompt.trim().length > 0) {
+		developerMessages.push(userSystemPrompt.trim());
+	}
+
+	return {
+		instructions: CODEX_INSTRUCTIONS,
+		developerMessages,
+	};
+}
+
+const CODEX_DEBUG = $flag("PI_CODEX_DEBUG");
+const CODEX_MAX_RETRIES = 5;
+const CODEX_RETRYABLE_STATUS = new Set([408, 429, 500, 502, 503, 504]);
+const CODEX_RETRY_DELAY_MS = 500;
+const CODEX_WEBSOCKET_CONNECT_TIMEOUT_MS = 10000;
+const CODEX_WEBSOCKET_IDLE_TIMEOUT_MS = 300000;
+const CODEX_WEBSOCKET_FIRST_EVENT_TIMEOUT_MS = 15000;
+const CODEX_WEBSOCKET_RETRY_BUDGET = CODEX_MAX_RETRIES;
+const CODEX_WEBSOCKET_TRANSPORT_ERROR_PREFIX = "Codex websocket transport error";
+const CODEX_RETRYABLE_EVENT_CODES = new Set(["model_error", "server_error", "internal_error"]);
+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";
+const X_CODEX_TURN_STATE_HEADER = "x-codex-turn-state";
+const X_MODELS_ETAG_HEADER = "x-models-etag";
+const X_REASONING_INCLUDED_HEADER = "x-reasoning-included";
+/** Connection-level websocket failures that should immediately fall back to SSE without retrying. */
+const CODEX_WEBSOCKET_FATAL_PATTERNS = ["websocket error:", "websocket closed before open", "connection timeout"];
+/** Max total time to spend retrying 429s with server-provided delays (5 minutes). */
+const CODEX_RATE_LIMIT_BUDGET_MS = 5 * 60 * 1000;
+
+type CodexTransport = "sse" | "websocket";
+type CodexEventItem = ResponseReasoningItem | ResponseOutputMessage | ResponseFunctionToolCall;
+type CodexOutputBlock = ThinkingContent | TextContent | (ToolCall & { partialJson: string });
+
+type CodexWebSocketSessionState = {
+	disableWebsocket: boolean;
+	lastRequest?: RequestBody;
+	lastResponseId?: string;
+	canAppend: boolean;
+	turnState?: string;
+	modelsEtag?: string;
+	reasoningIncluded?: boolean;
+	connection?: CodexWebSocketConnection;
+	lastTransport?: CodexTransport;
+	fallbackCount: number;
+	lastFallbackAt?: number;
+	prewarmed: boolean;
+};
+
+interface CodexProviderSessionState extends ProviderSessionState {
+	webSocketSessions: Map<string, CodexWebSocketSessionState>;
+	webSocketPublicToPrivate: Map<string, string>;
+}
+
+interface CodexRequestContext {
+	apiKey: string;
+	accountId: string;
+	baseUrl: string;
+	url: string;
+	requestHeaders: Record<string, string>;
+	providerSessionState?: CodexProviderSessionState;
+	websocketState?: CodexWebSocketSessionState;
+	transformedBody: RequestBody;
+	rawRequestDump: RawHttpRequestDump;
+}
+
+interface CodexRequestSetup {
+	requestSignal: AbortSignal;
+	wrapCodexSseStream: (source: AsyncGenerator<Record<string, unknown>>) => AsyncGenerator<Record<string, unknown>>;
+	requestAbortController: AbortController;
+}
+
+interface CodexStreamRuntime {
+	eventStream: AsyncGenerator<Record<string, unknown>>;
+	requestBodyForState: RequestBody;
+	transport: CodexTransport;
+	websocketState?: CodexWebSocketSessionState;
+	currentItem: CodexEventItem | null;
+	currentBlock: CodexOutputBlock | null;
+	nativeOutputItems: Array<Record<string, unknown>>;
+	websocketStreamRetries: number;
+	providerRetryAttempt: number;
+	sawTerminalEvent: boolean;
+	canSafelyReplayWebsocketOverSse: boolean;
+}
+
+interface CodexStreamProcessingContext {
+	model: Model<"openai-codex-responses">;
+	output: AssistantMessage;
+	stream: AssistantMessageEventStream;
+	options: OpenAICodexResponsesOptions | undefined;
+	requestSetup: CodexRequestSetup;
+	requestContext: CodexRequestContext;
+	startTime: number;
+	firstTokenTime?: number;
+}
+
+interface CodexStreamCompletion {
+	firstTokenTime?: number;
+}
+
+function parseCodexNonNegativeInteger(value: string | undefined, fallback: number): number {
+	if (!value) return fallback;
+	const parsed = Number(value);
+	if (!Number.isFinite(parsed) || parsed < 0) return fallback;
+	return Math.trunc(parsed);
+}
+
+function parseCodexPositiveInteger(value: string | undefined, fallback: number): number {
+	if (!value) return fallback;
+	const parsed = Number(value);
+	if (!Number.isFinite(parsed) || parsed <= 0) return fallback;
+	return Math.trunc(parsed);
+}
+
+function isCodexWebSocketEnvEnabled(): boolean {
+	return $flag("PI_CODEX_WEBSOCKET");
+}
+
+function getCodexWebSocketRetryBudget(): number {
+	return parseCodexNonNegativeInteger($env.PI_CODEX_WEBSOCKET_RETRY_BUDGET, CODEX_WEBSOCKET_RETRY_BUDGET);
+}
+
+function getCodexWebSocketRetryDelayMs(retry: number): number {
+	const baseDelay = parseCodexPositiveInteger($env.PI_CODEX_WEBSOCKET_RETRY_DELAY_MS, CODEX_RETRY_DELAY_MS);
+	return baseDelay * Math.max(1, retry);
+}
+
+function getCodexWebSocketIdleTimeoutMs(): number {
+	return parseCodexPositiveInteger($env.PI_CODEX_WEBSOCKET_IDLE_TIMEOUT_MS, CODEX_WEBSOCKET_IDLE_TIMEOUT_MS);
+}
+
+function getCodexWebSocketFirstEventTimeoutMs(): number {
+	return parseCodexPositiveInteger(
+		$env.PI_CODEX_WEBSOCKET_FIRST_EVENT_TIMEOUT_MS,
+		Math.min(CODEX_WEBSOCKET_FIRST_EVENT_TIMEOUT_MS, getCodexWebSocketIdleTimeoutMs()),
+	);
+}
+
+function createCodexProviderSessionState(): CodexProviderSessionState {
+	const state: CodexProviderSessionState = {
+		webSocketSessions: new Map(),
+		webSocketPublicToPrivate: new Map(),
+		close: () => {
+			for (const session of state.webSocketSessions.values()) {
+				session.connection?.close("session_disposed");
+			}
+			state.webSocketSessions.clear();
+			state.webSocketPublicToPrivate.clear();
+		},
+	};
+	return state;
+}
+
+function getCodexProviderSessionState(
+	providerSessionState: Map<string, ProviderSessionState> | undefined,
+): CodexProviderSessionState | undefined {
+	if (!providerSessionState) return undefined;
+	const existing = providerSessionState.get(CODEX_PROVIDER_SESSION_STATE_KEY) as CodexProviderSessionState | undefined;
+	if (existing) return existing;
+	const created = createCodexProviderSessionState();
+	providerSessionState.set(CODEX_PROVIDER_SESSION_STATE_KEY, created);
+	return created;
+}
+
+function createCodexWebSocketTransportError(message: string): Error {
+	return new Error(`${CODEX_WEBSOCKET_TRANSPORT_ERROR_PREFIX}: ${message}`);
+}
+
+function isCodexWebSocketFatalError(error: Error): boolean {
+	const msg = error.message.toLowerCase();
+	return CODEX_WEBSOCKET_FATAL_PATTERNS.some(pattern => msg.includes(pattern.toLowerCase()));
+}
+
+function isCodexWebSocketTransportError(error: unknown): boolean {
+	if (!(error instanceof Error)) return false;
+	return error.message.startsWith(CODEX_WEBSOCKET_TRANSPORT_ERROR_PREFIX);
+}
+
+function isCodexWebSocketRetryableStreamError(error: unknown): boolean {
+	if (!(error instanceof Error) || !isCodexWebSocketTransportError(error)) return false;
+	const message = error.message.toLowerCase();
+	return (
+		message.includes("websocket closed (") ||
+		message.includes("websocket closed before response completion") ||
+		message.includes("websocket connection is unavailable") ||
+		message.includes("idle timeout waiting for websocket") ||
+		message.includes("timeout waiting for first websocket event") ||
+		message.includes("syntaxerror") ||
+		message.includes("json")
+	);
+}
+
+function toCodexHeaderRecord(value: unknown): Record<string, string> | null {
+	if (!value || typeof value !== "object") return null;
+	const headers: Record<string, string> = {};
+	for (const [key, entry] of Object.entries(value as Record<string, unknown>)) {
+		if (typeof entry === "string") {
+			headers[key] = entry;
+		} else if (Array.isArray(entry) && entry.every(item => typeof item === "string")) {
+			headers[key] = entry.join(",");
+		} else if (typeof entry === "number" || typeof entry === "boolean") {
+			headers[key] = String(entry);
+		}
+	}
+	return Object.keys(headers).length > 0 ? headers : null;
+}
+
+function toCodexHeaders(value: unknown): Headers | undefined {
+	if (!value) return undefined;
+	if (value instanceof Headers) return value;
+	if (Array.isArray(value)) {
+		try {
+			return new Headers(value as Array<[string, string]>);
+		} catch {
+			return undefined;
+		}
+	}
+	const record = toCodexHeaderRecord(value);
+	if (!record) return undefined;
+	return new Headers(record);
+}
+
+function updateCodexSessionMetadataFromHeaders(
+	state: CodexWebSocketSessionState | undefined,
+	headers: Headers | Record<string, string> | null | undefined,
+): void {
+	if (!state || !headers) return;
+	const resolvedHeaders = headers instanceof Headers ? headers : new Headers(headers);
+	const turnState = resolvedHeaders.get(X_CODEX_TURN_STATE_HEADER);
+	if (turnState && turnState.length > 0) {
+		state.turnState = turnState;
+	}
+	const modelsEtag = resolvedHeaders.get(X_MODELS_ETAG_HEADER);
+	if (modelsEtag && modelsEtag.length > 0) {
+		state.modelsEtag = modelsEtag;
+	}
+	const reasoningIncluded = resolvedHeaders.get(X_REASONING_INCLUDED_HEADER);
+	if (reasoningIncluded !== null) {
+		const normalized = reasoningIncluded.trim().toLowerCase();
+		state.reasoningIncluded = normalized.length === 0 ? true : normalized !== "false";
+	}
+}
+
+function extractCodexWebSocketHandshakeHeaders(socket: WebSocket, openEvent?: Event): Headers | undefined {
+	const eventRecord = openEvent as Record<string, unknown> | undefined;
+	const eventResponse = eventRecord?.response as Record<string, unknown> | undefined;
+	const socketRecord = socket as unknown as Record<string, unknown>;
+	const socketResponse = socketRecord.response as Record<string, unknown> | undefined;
+	const socketHandshake = socketRecord.handshake as Record<string, unknown> | undefined;
+	return (
+		toCodexHeaders(eventRecord?.responseHeaders) ??
+		toCodexHeaders(eventRecord?.headers) ??
+		toCodexHeaders(eventResponse?.headers) ??
+		toCodexHeaders(socketRecord.responseHeaders) ??
+		toCodexHeaders(socketRecord.handshakeHeaders) ??
+		toCodexHeaders(socketResponse?.headers) ??
+		toCodexHeaders(socketHandshake?.headers)
+	);
+}
+
+function normalizeCodexToolChoice(choice: ToolChoice | undefined): string | Record<string, unknown> | undefined {
+	if (!choice) return undefined;
+	if (typeof choice === "string") return choice;
+	if (choice.type === "function") {
+		if ("function" in choice && choice.function?.name) {
+			return { type: "function", name: choice.function.name };
+		}
+		if ("name" in choice && choice.name) {
+			return { type: "function", name: choice.name };
+		}
+	}
+	if (choice.type === "tool" && choice.name) {
+		return { type: "function", name: choice.name };
+	}
+	return undefined;
+}
+
+function createEmptyUsage(): AssistantMessage["usage"] {
+	return {
+		input: 0,
+		output: 0,
+		cacheRead: 0,
+		cacheWrite: 0,
+		totalTokens: 0,
+		cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+	};
+}
+
+function createAssistantOutput(model: Model<"openai-codex-responses">): AssistantMessage {
+	return {
+		role: "assistant",
+		content: [],
+		api: "openai-codex-responses" as Api,
+		provider: model.provider,
+		model: model.id,
+		usage: createEmptyUsage(),
+		stopReason: "stop",
+		timestamp: Date.now(),
+	};
+}
+
+function resetOutputState(output: AssistantMessage): void {
+	output.content.length = 0;
+	output.usage = createEmptyUsage();
+	output.stopReason = "stop";
+}
+
+function removeTransientBlockIndices(output: AssistantMessage): void {
+	for (const block of output.content) {
+		delete (block as { index?: number }).index;
+	}
+}
+
+function createRequestSetup(options: OpenAICodexResponsesOptions | undefined): CodexRequestSetup {
+	const requestAbortController = new AbortController();
+	const requestSignal = options?.signal
+		? AbortSignal.any([options.signal, requestAbortController.signal])
+		: requestAbortController.signal;
+	const wrapCodexSseStream = (
+		source: AsyncGenerator<Record<string, unknown>>,
+	): AsyncGenerator<Record<string, unknown>> =>
+		iterateWithIdleTimeout(source, {
+			idleTimeoutMs: getOpenAIStreamIdleTimeoutMs(),
+			errorMessage: "OpenAI Codex SSE stream stalled while waiting for the next event",
+			onIdle: () => requestAbortController.abort(),
+		});
+	return { requestAbortController, requestSignal, wrapCodexSseStream };
+}
+
+async function buildCodexRequestContext(
+	model: Model<"openai-codex-responses">,
+	context: Context,
+	options: OpenAICodexResponsesOptions | undefined,
+	output: AssistantMessage,
+): Promise<CodexRequestContext> {
+	const apiKey = options?.apiKey || getEnvApiKey(model.provider) || "";
+	if (!apiKey) {
+		throw new Error(`No API key for provider: ${model.provider}`);
+	}
+
+	const accountId = getAccountId(apiKey);
+	const baseUrl = model.baseUrl || CODEX_BASE_URL;
+	const baseWithSlash = baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`;
+	const url = rewriteUrlForCodex(new URL(URL_PATHS.RESPONSES.slice(1), baseWithSlash).toString());
+	const transformedBody = await buildTransformedCodexRequestBody(model, context, options);
+	options?.onPayload?.(transformedBody);
+
+	const requestHeaders = { ...(model.headers ?? {}), ...(options?.headers ?? {}) };
+	const rawRequestDump: RawHttpRequestDump = {
+		provider: model.provider,
+		api: output.api,
+		model: model.id,
+		method: "POST",
+		url,
+		body: transformedBody,
+	};
+
+	const providerSessionState = getCodexProviderSessionState(options?.providerSessionState);
+	const sessionKey = getCodexWebSocketSessionKey(options?.sessionId, model, accountId, baseUrl);
+	const publicSessionKey = getCodexPublicSessionKey(options?.sessionId, model, baseUrl);
+	if (sessionKey && publicSessionKey) {
+		providerSessionState?.webSocketPublicToPrivate.set(publicSessionKey, sessionKey);
+	}
+	const websocketState =
+		sessionKey && providerSessionState ? getCodexWebSocketSessionState(sessionKey, providerSessionState) : undefined;
+
+	return {
+		apiKey,
+		accountId,
+		baseUrl,
+		url,
+		requestHeaders,
+		providerSessionState,
+		websocketState,
+		transformedBody,
+		rawRequestDump,
+	};
+}
+
+async function buildTransformedCodexRequestBody(
+	model: Model<"openai-codex-responses">,
+	context: Context,
+	options: OpenAICodexResponsesOptions | undefined,
+): Promise<RequestBody> {
+	const params: RequestBody = {
+		model: model.id,
+		input: [...convertMessages(model, context)],
+		stream: true,
+		prompt_cache_key: options?.sessionId,
+	};
+
+	if (options?.maxTokens) {
+		params.max_output_tokens = options.maxTokens;
+	}
+	if (options?.temperature !== undefined) {
+		params.temperature = options.temperature;
+	}
+	if (options?.topP !== undefined) {
+		params.top_p = options.topP;
+	}
+	if (options?.topK !== undefined) {
+		params.top_k = options.topK;
+	}
+	if (options?.minP !== undefined) {
+		params.min_p = options.minP;
+	}
+	if (options?.presencePenalty !== undefined) {
+		params.presence_penalty = options.presencePenalty;
+	}
+	if (options?.repetitionPenalty !== undefined) {
+		params.repetition_penalty = options.repetitionPenalty;
+	}
+	if (isSpecialServiceTier(options?.serviceTier)) {
+		params.service_tier = options.serviceTier;
+	}
+	if (context.tools && context.tools.length > 0) {
+		params.tools = convertTools(context.tools);
+		if (options?.toolChoice) {
+			const toolChoice = normalizeCodexToolChoice(options.toolChoice);
+			if (toolChoice) {
+				params.tool_choice = toolChoice;
+			}
+		}
+	}
+
+	const systemPrompt = buildCodexSystemPrompt({ userSystemPrompt: context.systemPrompt });
+	params.instructions = systemPrompt.instructions;
+
+	const codexOptions: CodexRequestOptions = {
+		reasoningEffort: options?.reasoning,
+		reasoningSummary: options?.reasoningSummary ?? "auto",
+		textVerbosity: options?.textVerbosity,
+		include: options?.include,
+	};
+
+	return transformRequestBody(params, model, codexOptions, systemPrompt);
+}
+
+async function openInitialCodexEventStream(
+	model: Model<"openai-codex-responses">,
+	options: OpenAICodexResponsesOptions | undefined,
+	requestSetup: CodexRequestSetup,
+	requestContext: CodexRequestContext,
+): Promise<{
+	eventStream: AsyncGenerator<Record<string, unknown>>;
+	requestBodyForState: RequestBody;
+	transport: CodexTransport;
+}> {
+	const { transformedBody, websocketState } = requestContext;
+	if (websocketState && shouldUseCodexWebSocket(model, websocketState, options?.preferWebsockets)) {
+		const websocketRetryBudget = getCodexWebSocketRetryBudget();
+		let websocketRetries = 0;
+		while (true) {
+			try {
+				return await openCodexWebSocketTransport(
+					requestContext,
+					requestSetup,
+					options,
+					websocketState,
+					websocketRetries,
+				);
+			} catch (error) {
+				const websocketError = error instanceof Error ? error : new Error(String(error));
+				const isFatal = isCodexWebSocketFatalError(websocketError);
+				const activateFallback = isFatal || websocketRetries >= websocketRetryBudget;
+				recordCodexWebSocketFailure(websocketState, activateFallback);
+				logCodexDebug("codex websocket fallback", {
+					error: websocketError.message,
+					retry: websocketRetries,
+					retryBudget: websocketRetryBudget,
+					activated: activateFallback,
+					fatal: isFatal,
+				});
+				if (!activateFallback) {
+					websocketRetries += 1;
+					await abortableSleep(getCodexWebSocketRetryDelayMs(websocketRetries), requestSetup.requestSignal);
+					continue;
+				}
+				break;
+			}
+		}
+	}
+	return openCodexSseTransport(requestContext, requestSetup, options, websocketState, transformedBody);
+}
+async function openCodexWebSocketTransport(
+	requestContext: CodexRequestContext,
+	requestSetup: CodexRequestSetup,
+	options: OpenAICodexResponsesOptions | undefined,
+	websocketState: CodexWebSocketSessionState,
+	retry: number,
+): Promise<{
+	eventStream: AsyncGenerator<Record<string, unknown>>;
+	requestBodyForState: RequestBody;
+	transport: CodexTransport;
+}> {
+	const websocketRequest = buildCodexWebSocketRequest(requestContext.transformedBody, websocketState);
+	const websocketHeaders = createCodexHeaders(
+		requestContext.requestHeaders,
+		requestContext.accountId,
+		requestContext.apiKey,
+		options?.sessionId,
+		"websocket",
+		websocketState,
+	);
+	const requestBodyForState = structuredCloneJSON(requestContext.transformedBody);
+	logCodexDebug("codex websocket request", {
+		url: toWebSocketUrl(requestContext.url),
+		model: requestContext.transformedBody.model,
+		reasoningEffort: requestContext.transformedBody.reasoning?.effort ?? null,
+		headers: redactHeaders(websocketHeaders),
+		sentTurnStateHeader: websocketHeaders.has(X_CODEX_TURN_STATE_HEADER),
+		sentModelsEtagHeader: websocketHeaders.has(X_MODELS_ETAG_HEADER),
+		requestType: websocketRequest.type,
+		retry,
+		retryBudget: getCodexWebSocketRetryBudget(),
+	});
+	const eventStream = await openCodexWebSocketEventStream(
+		toWebSocketUrl(requestContext.url),
+		websocketHeaders,
+		websocketRequest,
+		websocketState,
+		requestSetup.requestSignal,
+	);
+	return { eventStream, requestBodyForState, transport: "websocket" };
+}
+
+async function openCodexSseTransport(
+	requestContext: CodexRequestContext,
+	requestSetup: CodexRequestSetup,
+	options: OpenAICodexResponsesOptions | undefined,
+	state: CodexWebSocketSessionState | undefined,
+	body = requestContext.transformedBody,
+): Promise<{
+	eventStream: AsyncGenerator<Record<string, unknown>>;
+	requestBodyForState: RequestBody;
+	transport: CodexTransport;
+}> {
+	const eventStream = requestSetup.wrapCodexSseStream(
+		await openCodexSseEventStream(
+			requestContext.url,
+			requestContext.requestHeaders,
+			requestContext.accountId,
+			requestContext.apiKey,
+			options?.sessionId,
+			body,
+			state,
+			requestSetup.requestSignal,
+		),
+	);
+	return { eventStream, requestBodyForState: structuredCloneJSON(body), transport: "sse" };
+}
+
+async function reopenCodexWebSocketRuntimeStream(
+	context: CodexStreamProcessingContext,
+	runtime: CodexStreamRuntime,
+	state: CodexWebSocketSessionState,
+): Promise<void> {
+	const next = await openCodexWebSocketTransport(
+		context.requestContext,
+		context.requestSetup,
+		context.options,
+		state,
+		runtime.websocketStreamRetries,
+	);
+	runtime.eventStream = next.eventStream;
+	runtime.requestBodyForState = next.requestBodyForState;
+	runtime.transport = next.transport;
+	state.lastTransport = next.transport;
+}
+
+async function reopenCodexSseRuntimeStream(
+	context: CodexStreamProcessingContext,
+	runtime: CodexStreamRuntime,
+	state: CodexWebSocketSessionState | undefined,
+): Promise<void> {
+	const next = await openCodexSseTransport(context.requestContext, context.requestSetup, context.options, state);
+	runtime.eventStream = next.eventStream;
+	runtime.requestBodyForState = next.requestBodyForState;
+	runtime.transport = next.transport;
+	if (state) {
+		state.lastTransport = next.transport;
+	}
+}
+
+function createCodexStreamRuntime(initial: {
+	eventStream: AsyncGenerator<Record<string, unknown>>;
+	requestBodyForState: RequestBody;
+	transport: CodexTransport;
+	websocketState?: CodexWebSocketSessionState;
+}): CodexStreamRuntime {
+	return {
+		eventStream: initial.eventStream,
+		requestBodyForState: initial.requestBodyForState,
+		transport: initial.transport,
+		websocketState: initial.websocketState,
+		currentItem: null,
+		currentBlock: null,
+		nativeOutputItems: [],
+		websocketStreamRetries: 0,
+		providerRetryAttempt: 0,
+		sawTerminalEvent: false,
+		canSafelyReplayWebsocketOverSse: true,
+	};
+}
+
+async function processCodexResponseStream(
+	context: CodexStreamProcessingContext,
+	runtime: CodexStreamRuntime,
+): Promise<CodexStreamCompletion> {
+	const { output, stream } = context;
+	stream.push({ type: "start", partial: output });
+
+	while (true) {
+		try {
+			let firstTokenTime = context.firstTokenTime;
+			for await (const rawEvent of runtime.eventStream) {
+				firstTokenTime = handleCodexStreamEvent({
+					...context,
+					runtime,
+					rawEvent,
+					firstTokenTime,
+				});
+			}
+			return { firstTokenTime };
+		} catch (error) {
+			const recovered = await recoverCodexStreamError(context, runtime, error);
+			if (!recovered) {
+				throw error;
+			}
+		}
+	}
+}
+
+function handleCodexStreamEvent(args: {
+	model: Model<"openai-codex-responses">;
+	output: AssistantMessage;
+	stream: AssistantMessageEventStream;
+	runtime: CodexStreamRuntime;
+	rawEvent: Record<string, unknown>;
+	firstTokenTime?: number;
+}): number | undefined {
+	const { model, output, stream, runtime, rawEvent } = args;
+	const eventType = typeof rawEvent.type === "string" ? rawEvent.type : "";
+	if (!eventType) return args.firstTokenTime;
+
+	const blocks = output.content;
+	const blockIndex = () => blocks.length - 1;
+	let firstTokenTime = args.firstTokenTime;
+
+	if (eventType === "response.output_item.added") {
+		if (!firstTokenTime) firstTokenTime = Date.now();
+		const item = rawEvent.item as CodexEventItem;
+		runtime.currentItem = item;
+		runtime.currentBlock = createOutputBlockForItem(item);
+		if (!runtime.currentBlock) return firstTokenTime;
+		output.content.push(runtime.currentBlock);
+		stream.push({
+			type: getOutputBlockStartEventType(runtime.currentBlock),
+			contentIndex: blockIndex(),
+			partial: output,
+		});
+		return firstTokenTime;
+	}
+
+	if (eventType === "response.reasoning_summary_part.added") {
+		handleReasoningSummaryPartAdded(runtime.currentItem, rawEvent);
+		return firstTokenTime;
+	}
+
+	if (eventType === "response.reasoning_summary_text.delta") {
+		handleReasoningSummaryTextDelta(runtime.currentItem, runtime.currentBlock, rawEvent, stream, output, blockIndex);
+		return firstTokenTime;
+	}
+
+	if (eventType === "response.reasoning_summary_part.done") {
+		handleReasoningSummaryPartDone(runtime.currentItem, runtime.currentBlock, stream, output, blockIndex);
+		return firstTokenTime;
+	}
+
+	if (eventType === "response.content_part.added") {
+		handleContentPartAdded(runtime.currentItem, rawEvent);
+		return firstTokenTime;
+	}
+
+	if (eventType === "response.output_text.delta") {
+		handleMessageTextDelta(
+			runtime.currentItem,
+			runtime.currentBlock,
+			rawEvent,
+			stream,
+			output,
+			blockIndex,
+			"output_text",
+		);
+		return firstTokenTime;
+	}
+
+	if (eventType === "response.refusal.delta") {
+		handleMessageTextDelta(
+			runtime.currentItem,
+			runtime.currentBlock,
+			rawEvent,
+			stream,
+			output,
+			blockIndex,
+			"refusal",
+		);
+		return firstTokenTime;
+	}
+
+	if (eventType === "response.function_call_arguments.delta") {
+		handleToolCallArgumentsDelta(runtime.currentItem, runtime.currentBlock, rawEvent, stream, output, blockIndex);
+		return firstTokenTime;
+	}
+
+	if (eventType === "response.function_call_arguments.done") {
+		handleToolCallArgumentsDone(runtime.currentItem, runtime.currentBlock, rawEvent);
+		return firstTokenTime;
+	}
+
+	if (eventType === "response.output_item.done") {
+		handleOutputItemDone(model, output, stream, runtime, rawEvent, blockIndex);
+		return firstTokenTime;
+	}
+
+	if (eventType === "response.created") {
+		return handleResponseCreated(runtime, rawEvent);
+	}
+
+	if (eventType === "response.completed" || eventType === "response.done" || eventType === "response.incomplete") {
+		handleResponseCompleted(model, output, runtime, rawEvent);
+		return firstTokenTime;
+	}
+
+	if (eventType === "error" || eventType === "response.failed") {
+		throw createCodexProviderStreamError(rawEvent);
+	}
+
+	return firstTokenTime;
+}
+
+function createOutputBlockForItem(item: CodexEventItem): CodexOutputBlock | null {
+	if (item.type === "reasoning") {
+		return { type: "thinking", thinking: "" };
+	}
+	if (item.type === "message") {
+		return { type: "text", text: "" };
+	}
+	if (item.type === "function_call") {
+		return {
+			type: "toolCall",
+			id: `${item.call_id}|${item.id}`,
+			name: item.name,
+			arguments: {},
+			partialJson: item.arguments || "",
+		};
+	}
+	return null;
+}
+
+function getOutputBlockStartEventType(block: CodexOutputBlock): "thinking_start" | "text_start" | "toolcall_start" {
+	if (block.type === "thinking") return "thinking_start";
+	if (block.type === "text") return "text_start";
+	return "toolcall_start";
+}
+
+function handleReasoningSummaryPartAdded(currentItem: CodexEventItem | null, rawEvent: Record<string, unknown>): void {
+	if (currentItem?.type !== "reasoning") return;
+	currentItem.summary = currentItem.summary || [];
+	currentItem.summary.push((rawEvent as { part: ResponseReasoningItem["summary"][number] }).part);
+}
+
+function handleReasoningSummaryTextDelta(
+	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;
+	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;
+	lastPart.text += delta;
+	stream.push({ type: "thinking_delta", contentIndex: blockIndex(), delta, partial: output });
+}
+
+function handleReasoningSummaryPartDone(
+	currentItem: CodexEventItem | null,
+	currentBlock: CodexOutputBlock | null,
+	stream: AssistantMessageEventStream,
+	output: AssistantMessage,
+	blockIndex: () => number,
+): void {
+	if (currentItem?.type !== "reasoning" || currentBlock?.type !== "thinking") return;
+	currentItem.summary = currentItem.summary || [];
+	const lastPart = currentItem.summary[currentItem.summary.length - 1];
+	if (!lastPart) return;
+	currentBlock.thinking += "\n\n";
+	lastPart.text += "\n\n";
+	stream.push({ type: "thinking_delta", contentIndex: blockIndex(), delta: "\n\n", partial: output });
+}
+
+function handleContentPartAdded(currentItem: CodexEventItem | null, rawEvent: Record<string, unknown>): void {
+	if (currentItem?.type !== "message") return;
+	currentItem.content = currentItem.content || [];
+	const part = (rawEvent as { part?: ResponseOutputMessage["content"][number] }).part;
+	if (part && (part.type === "output_text" || part.type === "refusal")) {
+		currentItem.content.push(part);
+	}
+}
+
+function handleMessageTextDelta(
+	currentItem: CodexEventItem | null,
+	currentBlock: CodexOutputBlock | null,
+	rawEvent: Record<string, unknown>,
+	stream: AssistantMessageEventStream,
+	output: AssistantMessage,
+	blockIndex: () => number,
+	partType: "output_text" | "refusal",
+): void {
+	if (currentItem?.type !== "message" || currentBlock?.type !== "text") return;
+	if (!currentItem.content || currentItem.content.length === 0) return;
+	const lastPart = currentItem.content[currentItem.content.length - 1];
+	if (!lastPart || lastPart.type !== partType) return;
+	const delta = (rawEvent as { delta?: string }).delta || "";
+	currentBlock.text += delta;
+	if (lastPart.type === "output_text") {
+		lastPart.text += delta;
+	} else {
+		lastPart.refusal += delta;
+	}
+	stream.push({ type: "text_delta", contentIndex: blockIndex(), delta, partial: output });
+}
+
+function handleToolCallArgumentsDelta(
+	currentItem: CodexEventItem | null,
+	currentBlock: CodexOutputBlock | null,
+	rawEvent: Record<string, unknown>,
+	stream: AssistantMessageEventStream,
+	output: AssistantMessage,
+	blockIndex: () => number,
+): void {
+	if (currentItem?.type !== "function_call" || currentBlock?.type !== "toolCall") return;
+	const delta = (rawEvent as { delta?: string }).delta || "";
+	currentBlock.partialJson += delta;
+	currentBlock.arguments = parseStreamingJson(currentBlock.partialJson);
+	stream.push({ type: "toolcall_delta", contentIndex: blockIndex(), delta, partial: output });
+}
+
+function handleToolCallArgumentsDone(
+	currentItem: CodexEventItem | null,
+	currentBlock: CodexOutputBlock | null,
+	rawEvent: Record<string, unknown>,
+): void {
+	if (currentItem?.type !== "function_call" || currentBlock?.type !== "toolCall") return;
+	const args = (rawEvent as { arguments?: string }).arguments;
+	if (typeof args === "string") {
+		currentBlock.partialJson = args;
+		currentBlock.arguments = parseStreamingJson(currentBlock.partialJson);
+	}
+}
+
+function handleOutputItemDone(
+	model: Model<"openai-codex-responses">,
+	output: AssistantMessage,
+	stream: AssistantMessageEventStream,
+	runtime: CodexStreamRuntime,
+	rawEvent: Record<string, unknown>,
+	blockIndex: () => number,
+): void {
+	const item = structuredCloneJSON(rawEvent.item) as CodexEventItem;
+	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,
+		});
+		runtime.currentBlock = null;
+		return;
+	}
+
+	if (item.type === "message" && runtime.currentBlock?.type === "text") {
+		runtime.currentBlock.text = item.content
+			.map(content => (content.type === "output_text" ? content.text : content.refusal))
+			.join("");
+		const phase = item.phase === "commentary" || item.phase === "final_answer" ? item.phase : undefined;
+		runtime.currentBlock.textSignature = encodeTextSignatureV1(item.id, phase);
+		stream.push({
+			type: "text_end",
+			contentIndex: blockIndex(),
+			content: runtime.currentBlock.text,
+			partial: output,
+		});
+		runtime.currentBlock = null;
+		return;
+	}
+
+	if (item.type === "function_call") {
+		const toolCall: ToolCall = {
+			type: "toolCall",
+			id: `${item.call_id}|${item.id}`,
+			name: item.name,
+			arguments: parseStreamingJson(item.arguments || "{}"),
+		};
+		runtime.canSafelyReplayWebsocketOverSse = false;
+		stream.push({ type: "toolcall_end", contentIndex: blockIndex(), toolCall, partial: output });
+		return;
+	}
+
+	void model;
+}
+
+function handleResponseCreated(runtime: CodexStreamRuntime, rawEvent: Record<string, unknown>): number | undefined {
+	const response = (rawEvent as { response?: { id?: string } }).response;
+	const state = runtime.websocketState;
+	if (runtime.transport === "websocket" && state && typeof response?.id === "string" && response.id.length > 0) {
+		state.lastResponseId = response.id;
+	}
+	return undefined;
+}
+
+function handleResponseCompleted(
+	model: Model<"openai-codex-responses">,
+	output: AssistantMessage,
+	runtime: CodexStreamRuntime,
+	rawEvent: Record<string, unknown>,
+): void {
+	runtime.sawTerminalEvent = true;
+	const response = (
+		rawEvent as {
+			response?: {
+				id?: string;
+				usage?: {
+					input_tokens?: number;
+					output_tokens?: number;
+					total_tokens?: number;
+					input_tokens_details?: { cached_tokens?: number };
+				};
+				status?: string;
+			};
+		}
+	).response;
+
+	if (response?.usage) {
+		const cachedTokens = response.usage.input_tokens_details?.cached_tokens || 0;
+		output.usage = {
+			input: (response.usage.input_tokens || 0) - cachedTokens,
+			output: response.usage.output_tokens || 0,
+			cacheRead: cachedTokens,
+			cacheWrite: 0,
+			totalTokens: response.usage.total_tokens || 0,
+			cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+		};
+	}
+	if (typeof response?.id === "string" && response.id.length > 0) {
+		output.responseId = response.id;
+	}
+
+	const state = runtime.websocketState;
+	if (runtime.transport === "websocket" && state) {
+		state.lastRequest = structuredCloneJSON(runtime.requestBodyForState);
+		if (typeof response?.id === "string" && response.id.length > 0) {
+			state.lastResponseId = response.id;
+		}
+		state.canAppend = rawEvent.type === "response.done";
+	}
+
+	calculateCost(model, output.usage);
+	output.stopReason = mapOpenAIResponsesStopReason(response?.status as OpenAI.Responses.ResponseStatus | undefined);
+	if (output.content.some(block => block.type === "toolCall") && output.stopReason === "stop") {
+		output.stopReason = "toolUse";
+	}
+}
+
+async function recoverCodexStreamError(
+	context: CodexStreamProcessingContext,
+	runtime: CodexStreamRuntime,
+	error: unknown,
+): Promise<boolean> {
+	if (await tryReconnectCodexWebSocketOnConnectionLimit(context, runtime, error)) {
+		return true;
+	}
+	if (await tryReplayWebsocketFailureOverSse(context, runtime, error)) {
+		return true;
+	}
+	if (await tryRetryCodexProviderError(context, runtime, error)) {
+		return true;
+	}
+	return false;
+}
+
+/**
+ * Handles `websocket_connection_limit_reached` errors by closing the stale connection
+ * and opening a fresh websocket. If content has already been emitted to the caller,
+ * falls back to SSE replay (same as other WS failures) since we cannot safely
+ * continue a partial response on a new connection.
+ */
+async function tryReconnectCodexWebSocketOnConnectionLimit(
+	context: CodexStreamProcessingContext,
+	runtime: CodexStreamRuntime,
+	error: unknown,
+): Promise<boolean> {
+	if (!(error instanceof CodexProviderStreamError) || error.code !== "websocket_connection_limit_reached") {
+		return false;
+	}
+	const websocketState = context.requestContext.websocketState;
+	if (!websocketState || runtime.transport !== "websocket" || context.options?.signal?.aborted) {
+		return false;
+	}
+
+	// Close the stale connection so getOrCreateCodexWebSocketConnection creates a fresh one.
+	websocketState.connection?.close("connection_limit");
+	websocketState.connection = undefined;
+	resetCodexWebSocketAppendState(websocketState);
+
+	logCodexDebug("codex websocket connection limit reached, reconnecting", {
+		hadContent: context.output.content.length > 0,
+		retry: runtime.websocketStreamRetries,
+	});
+
+	if (context.output.content.length > 0) {
+		// Content already emitted to the caller — cannot safely continue on a new WS.
+		// Reset and replay the full request over SSE.
+		runtime.canSafelyReplayWebsocketOverSse = true;
+		runtime.currentItem = null;
+		runtime.currentBlock = null;
+		runtime.nativeOutputItems.length = 0;
+		resetOutputState(context.output);
+		context.firstTokenTime = undefined;
+		recordCodexWebSocketFailure(websocketState, true);
+		await reopenCodexSseRuntimeStream(context, runtime, websocketState);
+		return true;
+	}
+
+	// No content emitted yet — reconnect over websocket.
+	runtime.websocketStreamRetries += 1;
+	await reopenCodexWebSocketRuntimeStream(context, runtime, websocketState);
+	return true;
+}
+
+async function tryReplayWebsocketFailureOverSse(
+	context: CodexStreamProcessingContext,
+	runtime: CodexStreamRuntime,
+	error: unknown,
+): Promise<boolean> {
+	const websocketState = context.requestContext.websocketState;
+	const canReplay =
+		runtime.transport === "websocket" &&
+		websocketState &&
+		isCodexWebSocketRetryableStreamError(error) &&
+		runtime.canSafelyReplayWebsocketOverSse &&
+		!runtime.sawTerminalEvent &&
+		!context.options?.signal?.aborted;
+	if (!canReplay) return false;
+
+	const state = websocketState;
+	const streamError = error instanceof Error ? error : new Error(String(error));
+	const replayingBufferedOutputOverSse = context.output.content.length > 0;
+	const isFatal = isCodexWebSocketFatalError(streamError);
+	const activateFallback =
+		replayingBufferedOutputOverSse || isFatal || runtime.websocketStreamRetries >= getCodexWebSocketRetryBudget();
+	recordCodexWebSocketFailure(state, activateFallback);
+	logCodexDebug("codex websocket stream fallback", {
+		error: streamError.message,
+		retry: runtime.websocketStreamRetries,
+		retryBudget: getCodexWebSocketRetryBudget(),
+		activated: activateFallback,
+		fatal: isFatal,
+		replayedBufferedOutput: replayingBufferedOutputOverSse,
+	});
+
+	if (!activateFallback) {
+		runtime.websocketStreamRetries += 1;
+		await abortableSleep(
+			getCodexWebSocketRetryDelayMs(runtime.websocketStreamRetries),
+			context.requestSetup.requestSignal,
+		);
+		await reopenCodexWebSocketRuntimeStream(context, runtime, state);
+		return true;
+	}
+
+	if (replayingBufferedOutputOverSse) {
+		runtime.canSafelyReplayWebsocketOverSse = true;
+		runtime.currentItem = null;
+		runtime.currentBlock = null;
+		runtime.nativeOutputItems.length = 0;
+		resetOutputState(context.output);
+		context.firstTokenTime = undefined;
+	}
+
+	await reopenCodexSseRuntimeStream(context, runtime, state);
+	return true;
+}
+
+async function tryRetryCodexProviderError(
+	context: CodexStreamProcessingContext,
+	runtime: CodexStreamRuntime,
+	error: unknown,
+): Promise<boolean> {
+	if (
+		!isRetryableCodexProviderError(error) ||
+		context.output.content.length > 0 ||
+		runtime.providerRetryAttempt >= CODEX_MAX_RETRIES ||
+		context.options?.signal?.aborted
+	) {
+		return false;
+	}
+
+	runtime.providerRetryAttempt += 1;
+	const websocketState = context.requestContext.websocketState;
+	if (runtime.transport === "websocket" && websocketState) {
+		resetCodexWebSocketAppendState(websocketState);
+		resetCodexSessionMetadata(websocketState);
+	}
+
+	logCodexDebug("retrying codex provider stream error", {
+		error: error instanceof Error ? error.message : String(error),
+		retry: runtime.providerRetryAttempt,
+		retryBudget: CODEX_MAX_RETRIES,
+		transport: runtime.transport,
+	});
+
+	runtime.currentItem = null;
+	runtime.currentBlock = null;
+	runtime.sawTerminalEvent = false;
+	resetOutputState(context.output);
+	context.firstTokenTime = undefined;
+	await abortableSleep(CODEX_RETRY_DELAY_MS * runtime.providerRetryAttempt, context.requestSetup.requestSignal);
+
+	if (runtime.transport === "websocket" && websocketState) {
+		await reopenCodexWebSocketRuntimeStream(context, runtime, websocketState);
+		return true;
+	}
+
+	await reopenCodexSseRuntimeStream(context, runtime, websocketState);
+	return true;
+}
+
+function finalizeCodexResponse(
+	context: CodexStreamProcessingContext,
+	runtime: CodexStreamRuntime,
+	completion: CodexStreamCompletion,
+): AssistantMessage {
+	const { output } = context;
+	if (context.options?.signal?.aborted) {
+		throw new Error("Request was aborted");
+	}
+	if (!runtime.sawTerminalEvent) {
+		if (runtime.transport === "websocket" && context.requestContext.websocketState) {
+			resetCodexWebSocketAppendState(context.requestContext.websocketState);
+			resetCodexSessionMetadata(context.requestContext.websocketState);
+		}
+		logCodexDebug("codex stream ended unexpectedly", {
+			transport: runtime.transport,
+			terminalEventSeen: runtime.sawTerminalEvent,
+			unexpectedStreamEnd: true,
+			sentTurnStateHeader: Boolean(context.requestContext.websocketState?.turnState),
+			sentModelsEtagHeader: Boolean(context.requestContext.websocketState?.modelsEtag),
+		});
+		throw new Error("Codex stream ended before terminal completion event");
+	}
+	if (output.stopReason === "aborted" || output.stopReason === "error") {
+		throw new Error("Codex response failed");
+	}
+
+	output.providerPayload = createOpenAIResponsesHistoryPayload(context.model.provider, runtime.nativeOutputItems);
+	output.duration = Date.now() - context.startTime;
+	if (completion.firstTokenTime) {
+		output.ttft = completion.firstTokenTime - context.startTime;
+	}
+	return output;
+}
+
+async function handleCodexStreamFailure(
+	context: CodexStreamProcessingContext,
+	error: unknown,
+): Promise<AssistantMessage> {
+	const { output } = context;
+	removeTransientBlockIndices(output);
+	if (context.requestContext.websocketState) {
+		resetCodexWebSocketAppendState(context.requestContext.websocketState);
+		resetCodexSessionMetadata(context.requestContext.websocketState);
+	}
+	output.stopReason = context.options?.signal?.aborted ? "aborted" : "error";
+	output.errorMessage = await finalizeErrorMessage(error, context.requestContext.rawRequestDump);
+	output.duration = Date.now() - context.startTime;
+	if (context.firstTokenTime) {
+		output.ttft = context.firstTokenTime - context.startTime;
+	}
+	return output;
+}
+
+export const streamOpenAICodexResponses: StreamFunction<"openai-codex-responses"> = (
+	model: Model<"openai-codex-responses">,
+	context: Context,
+	options?: OpenAICodexResponsesOptions,
+): AssistantMessageEventStream => {
+	const stream = new AssistantMessageEventStream();
+
+	(async () => {
+		const startTime = Date.now();
+		const output = createAssistantOutput(model);
+		const requestSetup = createRequestSetup(options);
+		let processingContext: CodexStreamProcessingContext | undefined;
+
+		try {
+			const requestContext = await buildCodexRequestContext(model, context, options, output);
+			const initialTransport = await openInitialCodexEventStream(model, options, requestSetup, requestContext);
+			const runtime = createCodexStreamRuntime({
+				...initialTransport,
+				websocketState: requestContext.websocketState,
+			});
+			if (requestContext.websocketState) {
+				requestContext.websocketState.lastTransport = initialTransport.transport;
+			}
+
+			processingContext = {
+				model,
+				output,
+				stream,
+				options,
+				requestSetup,
+				requestContext,
+				startTime,
+			};
+
+			const completion = await processCodexResponseStream(processingContext, runtime);
+			processingContext.firstTokenTime = completion.firstTokenTime;
+			const message = finalizeCodexResponse(processingContext, runtime, completion);
+			stream.push({ type: "done", reason: message.stopReason as "stop" | "length" | "toolUse", message });
+			stream.end();
+		} catch (error) {
+			const failureContext =
+				processingContext ??
+				({
+					model,
+					output,
+					stream,
+					options,
+					requestSetup,
+					requestContext: {
+						apiKey: "",
+						accountId: "",
+						baseUrl: model.baseUrl || CODEX_BASE_URL,
+						url: "",
+						requestHeaders: {},
+						transformedBody: { model: model.id },
+						rawRequestDump: {
+							provider: model.provider,
+							api: output.api,
+							model: model.id,
+							method: "POST",
+							url: "",
+							body: { model: model.id },
+						},
+					},
+					startTime,
+				} satisfies CodexStreamProcessingContext);
+			const failure = await handleCodexStreamFailure(failureContext, error);
+			stream.push({ type: "error", reason: failure.stopReason as "error" | "aborted", error: failure });
+			stream.end();
+		}
+	})();
+
+	return stream;
+};
+
+export async function prewarmOpenAICodexResponses(
+	model: Model<"openai-codex-responses">,
+	options?: Pick<
+		OpenAICodexResponsesOptions,
+		"apiKey" | "headers" | "sessionId" | "signal" | "preferWebsockets" | "providerSessionState"
+	>,
+): Promise<void> {
+	const apiKey = options?.apiKey || getEnvApiKey(model.provider) || "";
+	if (!apiKey) return;
+	const accountId = getAccountId(apiKey);
+	const baseUrl = model.baseUrl || CODEX_BASE_URL;
+	const baseWithSlash = baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`;
+	const url = rewriteUrlForCodex(new URL(URL_PATHS.RESPONSES.slice(1), baseWithSlash).toString());
+	const providerSessionState = getCodexProviderSessionState(options?.providerSessionState);
+	const sessionKey = getCodexWebSocketSessionKey(options?.sessionId, model, accountId, baseUrl);
+	const publicSessionKey = getCodexPublicSessionKey(options?.sessionId, model, baseUrl);
+	if (publicSessionKey && sessionKey) {
+		providerSessionState?.webSocketPublicToPrivate.set(publicSessionKey, sessionKey);
+	}
+	if (!sessionKey || !providerSessionState) return;
+	const state = getCodexWebSocketSessionState(sessionKey, providerSessionState);
+	if (!shouldUseCodexWebSocket(model, state, options?.preferWebsockets)) return;
+	logger.time("prewarmCodex:createHeaders");
+	const headers = createCodexHeaders(
+		{ ...(model.headers ?? {}), ...(options?.headers ?? {}) },
+		accountId,
+		apiKey,
+		options?.sessionId,
+		"websocket",
+		state,
+	);
+	logger.time("prewarmCodex:establishWs");
+	await getOrCreateCodexWebSocketConnection(state, toWebSocketUrl(url), headers, options?.signal);
+	state.prewarmed = true;
+}
+
+function getCodexWebSocketSessionKey(
+	sessionId: string | undefined,
+	model: Model<"openai-codex-responses">,
+	accountId: string,
+	baseUrl: string,
+): string | undefined {
+	if (!sessionId || sessionId.length === 0) return undefined;
+	return `${accountId}:${baseUrl}:${model.id}:${sessionId}`;
+}
+
+function getCodexPublicSessionKey(
+	sessionId: string | undefined,
+	model: Model<"openai-codex-responses">,
+	baseUrl: string,
+): string | undefined {
+	if (!sessionId || sessionId.length === 0) return undefined;
+	return `${baseUrl}:${model.id}:${sessionId}`;
+}
+
+function getCodexWebSocketSessionState(
+	sessionKey: string,
+	providerSessionState: CodexProviderSessionState,
+): CodexWebSocketSessionState {
+	const existing = providerSessionState.webSocketSessions.get(sessionKey);
+	if (existing) return existing;
+	const created: CodexWebSocketSessionState = {
+		disableWebsocket: false,
+		canAppend: false,
+		fallbackCount: 0,
+		prewarmed: false,
+	};
+	providerSessionState.webSocketSessions.set(sessionKey, created);
+	return created;
+}
+
+function resetCodexWebSocketAppendState(state: CodexWebSocketSessionState): void {
+	state.canAppend = false;
+	state.lastRequest = undefined;
+	state.lastResponseId = undefined;
+}
+
+function resetCodexSessionMetadata(state: CodexWebSocketSessionState): void {
+	state.turnState = undefined;
+	state.modelsEtag = undefined;
+	state.reasoningIncluded = undefined;
+}
+
+function recordCodexWebSocketFailure(state: CodexWebSocketSessionState, activateFallback: boolean): void {
+	resetCodexWebSocketAppendState(state);
+	state.connection?.close("fallback");
+	state.connection = undefined;
+	state.lastFallbackAt = Date.now();
+	if (activateFallback && !state.disableWebsocket) {
+		state.disableWebsocket = true;
+		state.fallbackCount += 1;
+	}
+}
+
+function shouldUseCodexWebSocket(
+	model: Model<"openai-codex-responses">,
+	state: CodexWebSocketSessionState | undefined,
+	preferWebsockets?: boolean,
+): boolean {
+	if (!state || state.disableWebsocket) return false;
+	if (preferWebsockets === false) return false;
+	return isCodexWebSocketEnvEnabled() || preferWebsockets === true || model.preferWebsockets === true;
+}
+
+export interface OpenAICodexTransportDetails {
+	websocketPreferred: boolean;
+	lastTransport?: CodexTransport;
+	websocketDisabled: boolean;
+	websocketConnected: boolean;
+	fallbackCount: number;
+	canAppend: boolean;
+	prewarmed: boolean;
+	hasSessionState: boolean;
+	lastFallbackAt?: number;
+}
+
+export function getOpenAICodexTransportDetails(
+	model: Model<"openai-codex-responses">,
+	options?: {
+		sessionId?: string;
+		baseUrl?: string;
+		preferWebsockets?: boolean;
+		providerSessionState?: Map<string, ProviderSessionState>;
+	},
+): OpenAICodexTransportDetails {
+	const baseUrl = options?.baseUrl || model.baseUrl || CODEX_BASE_URL;
+	const websocketPreferred =
+		options?.preferWebsockets === false
+			? false
+			: isCodexWebSocketEnvEnabled() || options?.preferWebsockets === true || model.preferWebsockets === true;
+	const providerSessionState = getCodexProviderSessionState(options?.providerSessionState);
+	const publicSessionKey = getCodexPublicSessionKey(options?.sessionId, model, baseUrl);
+	const privateSessionKey = publicSessionKey
+		? providerSessionState?.webSocketPublicToPrivate.get(publicSessionKey)
+		: undefined;
+	const state = privateSessionKey ? providerSessionState?.webSocketSessions.get(privateSessionKey) : undefined;
+
+	return {
+		websocketPreferred,
+		lastTransport: state?.lastTransport,
+		websocketDisabled: state?.disableWebsocket ?? false,
+		websocketConnected: state?.connection?.isOpen() ?? false,
+		fallbackCount: state?.fallbackCount ?? 0,
+		canAppend: state?.canAppend ?? false,
+		prewarmed: state?.prewarmed ?? false,
+		hasSessionState: state !== undefined,
+		lastFallbackAt: state?.lastFallbackAt,
+	};
+}
+
+function buildAppendInput(previous: RequestBody | undefined, current: RequestBody): InputItem[] | null {
+	if (!previous) return null;
+	if (!Array.isArray(previous.input) || !Array.isArray(current.input)) return null;
+	if (current.input.length <= previous.input.length) return null;
+	const previousWithoutInput = { ...previous, input: undefined };
+	const currentWithoutInput = { ...current, input: undefined };
+	if (JSON.stringify(previousWithoutInput) !== JSON.stringify(currentWithoutInput)) {
+		return null;
+	}
+	for (let index = 0; index < previous.input.length; index += 1) {
+		if (JSON.stringify(previous.input[index]) !== JSON.stringify(current.input[index])) {
+			return null;
+		}
+	}
+	return current.input.slice(previous.input.length) as InputItem[];
+}
+
+function buildCodexWebSocketRequest(
+	requestBody: RequestBody,
+	state: CodexWebSocketSessionState | undefined,
+): Record<string, unknown> {
+	const appendInput = state?.canAppend ? buildAppendInput(state.lastRequest, requestBody) : null;
+	if (appendInput && appendInput.length > 0) {
+		if (state?.lastResponseId) {
+			return {
+				type: "response.create",
+				...requestBody,
+				previous_response_id: state.lastResponseId,
+				input: appendInput,
+			};
+		}
+		return {
+			type: "response.append",
+			input: appendInput,
+		};
+	}
+	if (state?.canAppend) {
+		logCodexDebug("codex websocket append reset", {
+			hadTurnStateHeader: Boolean(state.turnState),
+			hadModelsEtagHeader: Boolean(state.modelsEtag),
+		});
+		resetCodexWebSocketAppendState(state);
+		resetCodexSessionMetadata(state);
+	}
+	return {
+		type: "response.create",
+		...requestBody,
+	};
+}
+
+function toWebSocketUrl(url: string): string {
+	const parsed = new URL(url);
+	if (parsed.protocol === "https:") {
+		parsed.protocol = "wss:";
+	} else if (parsed.protocol === "http:") {
+		parsed.protocol = "ws:";
+	}
+	return parsed.toString();
+}
+
+function headersToRecord(headers: Headers): Record<string, string> {
+	const result: Record<string, string> = {};
+	for (const [key, value] of headers.entries()) {
+		result[key] = value;
+	}
+	return result;
+}
+
+interface CodexWebSocketConnectionOptions {
+	idleTimeoutMs: number;
+	firstEventTimeoutMs: number;
+	onHandshakeHeaders?: (headers: Headers) => void;
+}
+
+class CodexWebSocketConnection {
+	#url: string;
+	#headers: Record<string, string>;
+	#idleTimeoutMs: number;
+	#firstEventTimeoutMs: number;
+	#onHandshakeHeaders?: (headers: Headers) => void;
+	#socket: WebSocket | null = null;
+	#queue: Array<Record<string, unknown> | Error | null> = [];
+	#waiters: Array<() => void> = [];
+	#connectPromise?: Promise<void>;
+	#activeRequest = false;
+
+	constructor(url: string, headers: Record<string, string>, options: CodexWebSocketConnectionOptions) {
+		this.#url = url;
+		this.#headers = headers;
+		this.#idleTimeoutMs = options.idleTimeoutMs;
+		this.#firstEventTimeoutMs = options.firstEventTimeoutMs;
+		this.#onHandshakeHeaders = options.onHandshakeHeaders;
+	}
+
+	isOpen(): boolean {
+		return this.#socket?.readyState === WebSocket.OPEN;
+	}
+
+	matchesAuth(headers: Record<string, string>): boolean {
+		return this.#headers.authorization === headers.authorization;
+	}
+
+	close(reason = "done"): void {
+		if (
+			this.#socket &&
+			(this.#socket.readyState === WebSocket.OPEN || this.#socket.readyState === WebSocket.CONNECTING)
+		) {
+			this.#socket.close(1000, reason);
+		}
+		this.#socket = null;
+	}
+
+	async connect(signal?: AbortSignal): Promise<void> {
+		if (this.isOpen()) return;
+		if (this.#connectPromise) {
+			logger.time("codexWs:awaitSharedHandshake");
+			await this.#connectPromise;
+			return;
+		}
+		const WebSocketWithHeaders = WebSocket as unknown as {
+			new (url: string, options?: { headers?: Record<string, string> }): WebSocket;
+		};
+		const { promise, resolve, reject } = Promise.withResolvers<void>();
+		this.#connectPromise = promise;
+		const socket = new WebSocketWithHeaders(this.#url, { headers: this.#headers });
+		this.#socket = socket;
+		let settled = false;
+		let timeout: NodeJS.Timeout | undefined;
+		const onAbort = () => {
+			socket.close(1000, "aborted");
+			if (!settled) {
+				settled = true;
+				reject(createCodexWebSocketTransportError("request was aborted"));
+			}
+		};
+		if (signal) {
+			if (signal.aborted) {
+				onAbort();
+			} else {
+				signal.addEventListener("abort", onAbort, { once: true });
+			}
+		}
+		const clearPending = () => {
+			if (timeout) clearTimeout(timeout);
+			if (signal) signal.removeEventListener("abort", onAbort);
+		};
+		timeout = setTimeout(() => {
+			socket.close(1000, "connect-timeout");
+			if (!settled) {
+				settled = true;
+				reject(createCodexWebSocketTransportError("connection timeout"));
+			}
+		}, CODEX_WEBSOCKET_CONNECT_TIMEOUT_MS);
+
+		socket.addEventListener("open", event => {
+			if (!settled) {
+				settled = true;
+				clearPending();
+				this.#captureHandshakeHeaders(socket, event);
+				resolve();
+			}
+		});
+		socket.addEventListener("error", event => {
+			const eventRecord = event as unknown as Record<string, unknown>;
+			const detail =
+				(typeof eventRecord.message === "string" && eventRecord.message) ||
+				(eventRecord.error instanceof Error && eventRecord.error.message) ||
+				String(event.type);
+			const error = createCodexWebSocketTransportError(`websocket error: ${detail}`);
+			if (!settled) {
+				settled = true;
+				clearPending();
+				reject(error);
+				return;
+			}
+			this.#push(error);
+		});
+		socket.addEventListener("close", event => {
+			this.#socket = null;
+			if (!settled) {
+				settled = true;
+				clearPending();
+				reject(createCodexWebSocketTransportError(`websocket closed before open (${event.code})`));
+				return;
+			}
+			this.#push(createCodexWebSocketTransportError(`websocket closed (${event.code})`));
+			this.#push(null);
+		});
+		socket.addEventListener("message", event => {
+			if (typeof event.data !== "string") return;
+			try {
+				const parsed = JSON.parse(event.data) as Record<string, unknown>;
+				if (parsed.type === "error" && typeof parsed.error === "object" && parsed.error) {
+					const inner = parsed.error as Record<string, unknown>;
+					if (typeof parsed.code !== "string" && typeof inner.code === "string") {
+						parsed.code = inner.code;
+					}
+					if (typeof parsed.message !== "string" && typeof inner.message === "string") {
+						parsed.message = inner.message;
+					}
+				}
+				this.#push(parsed);
+			} catch (error) {
+				this.#push(createCodexWebSocketTransportError(String(error)));
+			}
+		});
+
+		logger.time("codexWs:awaitTcpHandshake");
+		try {
+			await promise;
+		} finally {
+			this.#connectPromise = undefined;
+		}
+	}
+
+	async *streamRequest(
+		request: Record<string, unknown>,
+		signal?: AbortSignal,
+	): AsyncGenerator<Record<string, unknown>> {
+		if (!this.#socket || this.#socket.readyState !== WebSocket.OPEN) {
+			throw createCodexWebSocketTransportError("websocket connection is unavailable");
+		}
+		if (this.#activeRequest) {
+			throw createCodexWebSocketTransportError("websocket request already in progress");
+		}
+		this.#activeRequest = true;
+		const onAbort = () => {
+			this.close("aborted");
+			this.#push(createCodexWebSocketTransportError("request was aborted"));
+		};
+		if (signal) {
+			if (signal.aborted) {
+				onAbort();
+			} else {
+				signal.addEventListener("abort", onAbort, { once: true });
+			}
+		}
+
+		try {
+			this.#socket.send(JSON.stringify(request));
+			let sawFirstEvent = false;
+			while (true) {
+				const next = await this.#nextMessage(
+					sawFirstEvent ? this.#idleTimeoutMs : this.#firstEventTimeoutMs,
+					sawFirstEvent ? "idle timeout waiting for websocket" : "timeout waiting for first websocket event",
+				);
+				if (next instanceof Error) {
+					throw next;
+				}
+				if (next === null) {
+					throw createCodexWebSocketTransportError("websocket closed before response completion");
+				}
+				sawFirstEvent = true;
+				yield next;
+				const eventType = typeof next.type === "string" ? next.type : "";
+				if (
+					eventType === "response.completed" ||
+					eventType === "response.done" ||
+					eventType === "response.incomplete" ||
+					eventType === "response.failed" ||
+					eventType === "error"
+				) {
+					break;
+				}
+			}
+		} finally {
+			this.#activeRequest = false;
+			if (signal) {
+				signal.removeEventListener("abort", onAbort);
+			}
+		}
+	}
+
+	#captureHandshakeHeaders(socket: WebSocket, openEvent?: Event): void {
+		if (!this.#onHandshakeHeaders) return;
+		const headers = extractCodexWebSocketHandshakeHeaders(socket, openEvent);
+		if (!headers) return;
+		this.#onHandshakeHeaders(headers);
+	}
+
+	#push(item: Record<string, unknown> | Error | null): void {
+		this.#queue.push(item);
+		const waiter = this.#waiters.shift();
+		if (waiter) waiter();
+	}
+
+	async #nextMessage(timeoutMs: number, timeoutReason: string): Promise<Record<string, unknown> | Error | null> {
+		while (this.#queue.length === 0) {
+			const { promise, resolve } = Promise.withResolvers<void>();
+			this.#waiters.push(resolve);
+			let timedOut = false;
+			let timeout: NodeJS.Timeout | undefined;
+			if (timeoutMs > 0) {
+				timeout = setTimeout(() => {
+					timedOut = true;
+					const waiterIndex = this.#waiters.indexOf(resolve);
+					if (waiterIndex >= 0) {
+						this.#waiters.splice(waiterIndex, 1);
+					}
+					resolve();
+				}, timeoutMs);
+			}
+			await promise;
+			if (timeout) clearTimeout(timeout);
+			if (timedOut && this.#queue.length === 0) {
+				return createCodexWebSocketTransportError(timeoutReason);
+			}
+		}
+		return this.#queue.shift() ?? null;
+	}
+}
+
+async function getOrCreateCodexWebSocketConnection(
+	state: CodexWebSocketSessionState,
+	url: string,
+	headers: Headers,
+	signal?: AbortSignal,
+): Promise<CodexWebSocketConnection> {
+	const headerRecord = headersToRecord(headers);
+	if (state.connection?.isOpen()) {
+		if (state.connection.matchesAuth(headerRecord)) {
+			logger.time("codexWs:reuseOpenSocket");
+			return state.connection;
+		}
+		state.connection.close("token-refresh");
+		resetCodexWebSocketAppendState(state);
+	}
+	state.connection?.close("reconnect");
+	resetCodexWebSocketAppendState(state);
+	logger.time("codexWs:newSocket");
+	state.connection = new CodexWebSocketConnection(url, headerRecord, {
+		idleTimeoutMs: getCodexWebSocketIdleTimeoutMs(),
+		firstEventTimeoutMs: getCodexWebSocketFirstEventTimeoutMs(),
+		onHandshakeHeaders: handshakeHeaders => {
+			updateCodexSessionMetadataFromHeaders(state, handshakeHeaders);
+		},
+	});
+	await state.connection.connect(signal);
+	return state.connection;
+}
+
+async function openCodexSseEventStream(
+	url: string,
+	requestHeaders: Record<string, string> | undefined,
+	accountId: string,
+	apiKey: string,
+	sessionId: string | undefined,
+	body: RequestBody,
+	state: CodexWebSocketSessionState | undefined,
+	signal?: AbortSignal,
+): Promise<AsyncGenerator<Record<string, unknown>>> {
+	const headers = createCodexHeaders(requestHeaders, accountId, apiKey, sessionId, "sse", state);
+	logCodexDebug("codex request", {
+		url,
+		model: body.model,
+		headers: redactHeaders(headers),
+		sentTurnStateHeader: headers.has(X_CODEX_TURN_STATE_HEADER),
+		sentModelsEtagHeader: headers.has(X_MODELS_ETAG_HEADER),
+	});
+	const response = await fetchWithRetry(
+		url,
+		{
+			method: "POST",
+			headers,
+			body: JSON.stringify(body),
+		},
+		signal,
+	);
+	logCodexDebug("codex response", {
+		url: response.url,
+		status: response.status,
+		statusText: response.statusText,
+		contentType: response.headers.get("content-type") || null,
+		cfRay: response.headers.get("cf-ray") || null,
+	});
+	updateCodexSessionMetadataFromHeaders(state, response.headers);
+	if (!response.ok) {
+		const info = await parseCodexError(response);
+		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;
+		throw error;
+	}
+	if (!response.body) {
+		throw new Error("No response body");
+	}
+	return readSseJson<Record<string, unknown>>(response.body, signal);
+}
+
+async function openCodexWebSocketEventStream(
+	url: string,
+	headers: Headers,
+	request: Record<string, unknown>,
+	state: CodexWebSocketSessionState,
+	signal?: AbortSignal,
+): Promise<AsyncGenerator<Record<string, unknown>>> {
+	const connection = await getOrCreateCodexWebSocketConnection(state, url, headers, signal);
+	return connection.streamRequest(request, signal);
+}
+
+function createCodexHeaders(
+	initHeaders: Record<string, string> | undefined,
+	accountId: string,
+	accessToken: string,
+	promptCacheKey?: string,
+	transport: CodexTransport = "sse",
+	state?: CodexWebSocketSessionState,
+): Headers {
+	const headers = new Headers(initHeaders ?? {});
+	headers.delete("x-api-key");
+	headers.set("Authorization", `Bearer ${accessToken}`);
+	headers.set(OPENAI_HEADERS.ACCOUNT_ID, accountId);
+	const betaHeader =
+		transport === "websocket"
+			? OPENAI_HEADER_VALUES.BETA_RESPONSES_WEBSOCKETS_V2
+			: OPENAI_HEADER_VALUES.BETA_RESPONSES;
+	headers.set(OPENAI_HEADERS.BETA, betaHeader);
+	headers.set(OPENAI_HEADERS.ORIGINATOR, OPENAI_HEADER_VALUES.ORIGINATOR_CODEX);
+	headers.set("User-Agent", `pi/${packageJson.version} (${os.platform()} ${os.release()}; ${os.arch()})`);
+	if (promptCacheKey) {
+		headers.set(OPENAI_HEADERS.CONVERSATION_ID, promptCacheKey);
+		headers.set(OPENAI_HEADERS.SESSION_ID, promptCacheKey);
+	} else {
+		headers.delete(OPENAI_HEADERS.CONVERSATION_ID);
+		headers.delete(OPENAI_HEADERS.SESSION_ID);
+	}
+	if (state?.turnState) {
+		headers.set(X_CODEX_TURN_STATE_HEADER, state.turnState);
+	} else {
+		headers.delete(X_CODEX_TURN_STATE_HEADER);
+	}
+	if (state?.modelsEtag) {
+		headers.set(X_MODELS_ETAG_HEADER, state.modelsEtag);
+	} else {
+		headers.delete(X_MODELS_ETAG_HEADER);
+	}
+	if (transport === "sse") {
+		headers.set("accept", "text/event-stream");
+	} else {
+		headers.delete("accept");
+	}
+	headers.set("content-type", "application/json");
+	return headers;
+}
+
+function logCodexDebug(message: string, details?: Record<string, unknown>): void {
+	if (!CODEX_DEBUG) return;
+	logger.debug(`[codex] ${message}`, details ?? {});
+}
+
+function getRetryDelayMs(
+	response: Response | null,
+	attempt: number,
+	errorBody?: string,
+): { delay: number; serverProvided: boolean } {
+	const retryAfter = response?.headers?.get("retry-after") || null;
+	if (retryAfter) {
+		const seconds = Number(retryAfter);
+		if (Number.isFinite(seconds)) {
+			return { delay: Math.max(0, seconds * 1000), serverProvided: true };
+		}
+		const parsedDate = Date.parse(retryAfter);
+		if (!Number.isNaN(parsedDate)) {
+			return { delay: Math.max(0, parsedDate - Date.now()), serverProvided: true };
+		}
+	}
+	if (errorBody) {
+		const msMatch = /try again in\s+(\d+(?:\.\d+)?)\s*ms/i.exec(errorBody);
+		if (msMatch) {
+			const ms = Number(msMatch[1]);
+			if (Number.isFinite(ms)) return { delay: Math.max(ms, 100), serverProvided: true };
+		}
+		const sMatch = /try again in\s+(\d+(?:\.\d+)?)\s*s(?:ec)?/i.exec(errorBody);
+		if (sMatch) {
+			const seconds = Number(sMatch[1]);
+			if (Number.isFinite(seconds)) return { delay: Math.max(seconds * 1000, 100), serverProvided: true };
+		}
+	}
+	return { delay: CODEX_RETRY_DELAY_MS * (attempt + 1), serverProvided: false };
+}
+
+async function fetchWithRetry(url: string, init: RequestInit, signal?: AbortSignal): Promise<Response> {
+	let attempt = 0;
+	let rateLimitTimeSpent = 0;
+	while (true) {
+		try {
+			const response = await fetch(url, { ...init, signal: signal ?? init.signal });
+			if (!CODEX_RETRYABLE_STATUS.has(response.status)) {
+				return response;
+			}
+			if (signal?.aborted) return response;
+			const errorBody = await response.clone().text();
+			// Usage-limit errors are persistent (account allocation exhausted) — retrying with the
+			// same credential is futile. Bail out immediately so the error propagates to the agent
+			// session layer where credential switching happens.
+			if (response.status === 429 && isUsageLimitError(errorBody)) {
+				return response;
+			}
+			const { delay, serverProvided } = getRetryDelayMs(response, attempt, errorBody);
+			if (response.status === 429 && serverProvided) {
+				if (rateLimitTimeSpent + delay > CODEX_RATE_LIMIT_BUDGET_MS) {
+					return response;
+				}
+				rateLimitTimeSpent += delay;
+			} else if (attempt >= CODEX_MAX_RETRIES) {
+				return response;
+			}
+			await abortableSleep(delay, signal);
+		} catch (error) {
+			if (attempt >= CODEX_MAX_RETRIES || signal?.aborted) {
+				throw error;
+			}
+			const delay = CODEX_RETRY_DELAY_MS * (attempt + 1);
+			await abortableSleep(delay, signal);
+		}
+		attempt += 1;
+	}
+}
+
+function redactHeaders(headers: Headers): Record<string, string> {
+	const redacted: Record<string, string> = {};
+	for (const [key, value] of headers.entries()) {
+		const lower = key.toLowerCase();
+		if (lower === "authorization") {
+			redacted[key] = "Bearer [redacted]";
+			continue;
+		}
+		if (
+			lower.includes("account") ||
+			lower.includes("session") ||
+			lower.includes("conversation") ||
+			lower === "cookie"
+		) {
+			redacted[key] = "[redacted]";
+			continue;
+		}
+		redacted[key] = value;
+	}
+	return redacted;
+}
+
+function rewriteUrlForCodex(url: string): string {
+	return url.replace(URL_PATHS.RESPONSES, URL_PATHS.CODEX_RESPONSES);
+}
+
+function getAccountId(accessToken: string): string {
+	const accountId = getCodexAccountId(accessToken);
+	if (!accountId) {
+		throw new Error("Failed to extract accountId from token");
+	}
+	return accountId;
+}
+
+function convertMessages(model: Model<"openai-codex-responses">, context: Context): ResponseInput {
+	const messages: ResponseInput = [];
+
+	const normalizeToolCallId = (id: string): string => {
+		if (!id.includes("|")) return id;
+		const [callId, itemId] = id.split("|");
+		const sanitizedCallId = callId.replace(/[^a-zA-Z0-9_-]/g, "_");
+		let sanitizedItemId = itemId.replace(/[^a-zA-Z0-9_-]/g, "_");
+		if (!sanitizedItemId.startsWith("fc")) {
+			sanitizedItemId = `fc_${sanitizedItemId}`;
+		}
+		let normalizedCallId = sanitizedCallId.length > 64 ? sanitizedCallId.slice(0, 64) : sanitizedCallId;
+		let normalizedItemId = sanitizedItemId.length > 64 ? sanitizedItemId.slice(0, 64) : sanitizedItemId;
+		normalizedCallId = normalizedCallId.replace(/_+$/, "");
+		normalizedItemId = normalizedItemId.replace(/_+$/, "");
+		return `${normalizedCallId}|${normalizedItemId}`;
+	};
+
+	const transformedMessages = transformMessages(context.messages, model, normalizeToolCallId);
+	let msgIndex = 0;
+
+	for (const msg of transformedMessages) {
+		if (msg.role === "user" || msg.role === "developer") {
+			const providerPayload = (msg as { providerPayload?: AssistantMessage["providerPayload"] }).providerPayload;
+			const historyItems = getOpenAIResponsesHistoryItems(providerPayload, model.provider) as
+				| Array<ResponseInput[number]>
+				| undefined;
+			if (historyItems) {
+				messages.push(...historyItems);
+				msgIndex += 1;
+				continue;
+			}
+
+			const normalizedContent = normalizeInputMessageContent(model, msg.content);
+			if (normalizedContent.length === 0) continue;
+			messages.push({ role: msg.role, content: normalizedContent });
+			msgIndex += 1;
+			continue;
+		}
+
+		if (msg.role === "assistant") {
+			const assistantMsg = msg as AssistantMessage;
+			const providerPayload = getOpenAIResponsesHistoryPayload(
+				assistantMsg.providerPayload,
+				model.provider,
+				assistantMsg.provider,
+			);
+			const historyItems = providerPayload?.items as Array<ResponseInput[number]> | undefined;
+			if (historyItems) {
+				if (providerPayload?.dt) {
+					messages.push(...historyItems);
+				} else {
+					messages.splice(0, messages.length, ...historyItems);
+				}
+				msgIndex += 1;
+				continue;
+			}
+
+			const outputItems: ResponseInput = [];
+			for (const block of msg.content) {
+				if (block.type === "thinking" && msg.stopReason !== "error") {
+					if (block.thinkingSignature) {
+						outputItems.push(JSON.parse(block.thinkingSignature) as ResponseReasoningItem);
+					}
+					continue;
+				}
+				if (block.type === "text") {
+					const textBlock = block as TextContent;
+					const parsedSignature = parseTextSignature(textBlock.textSignature);
+					let msgId = parsedSignature?.id;
+					if (!msgId) {
+						msgId = `msg_${msgIndex}`;
+					} else if (msgId.length > 64) {
+						msgId = `msg_${Bun.hash(msgId).toString(36)}`;
+					}
+					outputItems.push({
+						type: "message",
+						role: "assistant",
+						content: [{ type: "output_text", text: textBlock.text.toWellFormed(), annotations: [] }],
+						status: "completed",
+						id: msgId,
+						phase: parsedSignature?.phase,
+					} satisfies ResponseOutputMessage);
+					continue;
+				}
+				if (block.type === "toolCall") {
+					const toolCall = block as ToolCall;
+					const normalized = normalizeResponsesToolCallId(toolCall.id);
+					outputItems.push({
+						type: "function_call",
+						id: normalized.itemId,
+						call_id: normalized.callId,
+						name: toolCall.name,
+						arguments: JSON.stringify(toolCall.arguments),
+					});
+				}
+			}
+			if (outputItems.length > 0) {
+				messages.push(...outputItems);
+			}
+			msgIndex += 1;
+			continue;
+		}
+
+		if (msg.role === "toolResult") {
+			const textResult = msg.content
+				.filter(content => content.type === "text")
+				.map(content => content.text)
+				.join("\n");
+			const hasImages = msg.content.some(content => content.type === "image");
+			const normalized = normalizeResponsesToolCallId(msg.toolCallId);
+			messages.push({
+				type: "function_call_output",
+				call_id: normalized.callId,
+				output: (textResult.length > 0 ? textResult : "(see attached image)").toWellFormed(),
+			});
+			if (hasImages && model.input.includes("image")) {
+				const contentParts: ResponseInputContent[] = [
+					{ type: "input_text", text: "Attached image(s) from tool result:" } satisfies ResponseInputText,
+				];
+				for (const block of msg.content) {
+					if (block.type === "image") {
+						contentParts.push({
+							type: "input_image",
+							detail: "auto",
+							image_url: `data:${block.mimeType};base64,${block.data}`,
+						} satisfies ResponseInputImage);
+					}
+				}
+				messages.push({ role: "user", content: contentParts });
+			}
+		}
+
+		msgIndex += 1;
+	}
+
+	return messages;
+}
+
+function normalizeInputMessageContent(
+	model: Model<"openai-codex-responses">,
+	content: string | Array<{ type: "text"; text: string } | { type: "image"; mimeType: string; data: string }>,
+): ResponseInputContent[] {
+	if (typeof content === "string") {
+		if (!content || content.trim() === "") return [];
+		return [{ type: "input_text", text: content.toWellFormed() }];
+	}
+
+	const normalizedContent: ResponseInputContent[] = content.map(item => {
+		if (item.type === "text") {
+			return { type: "input_text", text: item.text.toWellFormed() } satisfies ResponseInputText;
+		}
+		return {
+			type: "input_image",
+			detail: "auto",
+			image_url: `data:${item.mimeType};base64,${item.data}`,
+		} satisfies ResponseInputImage;
+	});
+
+	const maybeWithoutImages = model.input.includes("image")
+		? normalizedContent
+		: normalizedContent.filter(item => item.type !== "input_image");
+	return maybeWithoutImages.filter(item => item.type !== "input_text" || item.text.trim().length > 0);
+}
+
+function convertTools(tools: Tool[]): Array<{
+	type: "function";
+	name: string;
+	description: string;
+	parameters: Record<string, unknown>;
+	strict?: boolean;
+}> {
+	return tools.map(tool => {
+		const strict = !!(!NO_STRICT && tool.strict);
+		const baseParameters = tool.parameters as unknown as Record<string, unknown>;
+		const { schema: parameters, strict: effectiveStrict } = adaptSchemaForStrict(baseParameters, strict);
+		return {
+			type: "function",
+			name: tool.name,
+			description: tool.description || "",
+			parameters,
+			...(effectiveStrict && { strict: true }),
+		};
+	});
+}
+
+function getString(value: unknown): string | undefined {
+	return typeof value === "string" ? value : undefined;
+}
+
+class CodexProviderStreamError extends Error {
+	readonly retryable: boolean;
+	readonly code?: string;
+
+	constructor(message: string, retryable: boolean, code?: string) {
+		super(message);
+		this.name = "CodexProviderStreamError";
+		this.retryable = retryable;
+		this.code = code;
+	}
+}
+
+function isRetryableCodexFailureEvent(rawEvent: Record<string, unknown>): boolean {
+	const response = asRecord(rawEvent.response);
+	const error = asRecord(rawEvent.error) ?? (response ? asRecord(response.error) : null);
+	const code = getString(error?.code) ?? getString(error?.type) ?? getString(rawEvent.code);
+	if (code && CODEX_RETRYABLE_EVENT_CODES.has(code.toLowerCase())) {
+		return true;
+	}
+	const message = getString(error?.message) ?? getString(rawEvent.message) ?? getString(response?.message);
+	return !!message && CODEX_RETRYABLE_EVENT_MESSAGE.test(message);
+}
+
+function createCodexProviderStreamError(rawEvent: Record<string, unknown>): CodexProviderStreamError {
+	const code = getString(rawEvent.code) ?? "";
+	const message = getString(rawEvent.message) ?? "";
+	const formattedMessage =
+		typeof rawEvent.type === "string" && rawEvent.type === "error"
+			? formatCodexErrorEvent(rawEvent, code, message)
+			: (formatCodexFailure(rawEvent) ?? "Codex response failed");
+	return new CodexProviderStreamError(formattedMessage, isRetryableCodexFailureEvent(rawEvent), code || undefined);
+}
+
+function isRetryableCodexProviderError(error: unknown): boolean {
+	return error instanceof CodexProviderStreamError && error.retryable;
+}
+
+function truncate(text: string, limit: number): string {
+	if (text.length <= limit) return text;
+	return `${text.slice(0, limit)}…[truncated ${text.length - limit}]`;
+}
+
+function formatCodexFailure(rawEvent: Record<string, unknown>): string | null {
+	const response = asRecord(rawEvent.response);
+	const error = asRecord(rawEvent.error) ?? (response ? asRecord(response.error) : null);
+	const message = getString(error?.message) ?? getString(rawEvent.message) ?? getString(response?.message);
+	const code = getString(error?.code) ?? getString(error?.type) ?? getString(rawEvent.code);
+	const status = getString(response?.status) ?? getString(rawEvent.status);
+
+	const meta: string[] = [];
+	if (code) meta.push(`code=${code}`);
+	if (status) meta.push(`status=${status}`);
+
+	if (message) {
+		const metaText = meta.length ? ` (${meta.join(", ")})` : "";
+		return `Codex response failed: ${message}${metaText}`;
+	}
+	if (meta.length) {
+		return `Codex response failed (${meta.join(", ")})`;
+	}
+	try {
+		return `Codex response failed: ${truncate(JSON.stringify(rawEvent), 800)}`;
+	} catch {
+		return "Codex response failed";
+	}
+}
+
+function formatCodexErrorEvent(rawEvent: Record<string, unknown>, code: string, message: string): string {
+	const detail = formatCodexFailure(rawEvent);
+	if (detail) {
+		return detail.replace("response failed", "error event");
+	}
+	const meta: string[] = [];
+	if (code) meta.push(`code=${code}`);
+	if (message) meta.push(`message=${message}`);
+	if (meta.length > 0) {
+		return `Codex error event (${meta.join(", ")})`;
+	}
+	try {
+		return `Codex error event: ${truncate(JSON.stringify(rawEvent), 800)}`;
+	} catch {
+		return "Codex error event";
+	}
+}