@oh-my-pi/pi-ai 18.3.0 → 18.3.2

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

@@ -82,6 +82,13 @@ import {
 	transformRequestBody,
 } from "./openai-codex/request-transformer";
 import { applyCodexAccessPrograms, dropRejectedCodexAccessPrograms } from "./openai-codex/access-programs";
+import {
+	type CodexAcceptedSteer,
+	type CodexSteerAck,
+	CodexSteerPump,
+	planSteeredRequest,
+	toSteerInputItems,
+} from "./openai-codex/live-steering";
 import { CodexApiError } from "./openai-codex/response-handler";
 import { getCodexAttestationHeader } from "./openai-codex-attestation";
 export { createOpenAICodexCompactionRequestContext } from "./openai-codex-compaction";
@@ -423,6 +430,12 @@ type CodexWebSocketSessionState = {
 	canAppend: boolean;
 	modelsEtag?: string;
 	connection?: CodexWebSocketConnection;
+	/**
+	 * Steering the server accepted on `connection` for `lastResponseId`. The
+	 * next request reads the server's automatic successor or sends only the
+	 * pending tool output; see {@link planSteeredRequest}.
+	 */
+	acceptedSteering?: { connection: CodexWebSocketConnection; steers: CodexAcceptedSteer[] };
 	lastTransport?: CodexTransport;
 	fallbackCount: number;
 	lastFallbackAt?: number;
@@ -1636,6 +1649,8 @@ async function openInitialCodexEventStream(
 				break;
 			}
 		}
+	} else if (websocketState) {
+		releaseIdleCodexWebSocket(websocketState);
 	}
 	try {
 		return await openCodexSseTransport(model, requestContext, requestSetup, options, websocketState, transformedBody);
@@ -1795,8 +1810,78 @@ async function openCodexWebSocketTransport(
 	requestBodyForState: RequestBody;
 	transport: CodexTransport;
 }> {
+	const steered = websocketState.acceptedSteering;
+	websocketState.acceptedSteering = undefined;
 	const canAppendBeforeRequest = websocketState.canAppend === true;
-	const chainedBody = buildCodexChainedRequestBody(requestContext.transformedBody, websocketState);
+	let chainedBody = buildCodexChainedRequestBody(requestContext.transformedBody, websocketState);
+	const websocketHeaders = createCodexHeaders(
+		requestContext.requestHeaders,
+		requestContext.accountId,
+		requestContext.apiKey,
+		requestContext.codexClientVersion,
+		requestContext.transportSessionId,
+		"websocket",
+		websocketState,
+		requestContext.turnState,
+		requestContext.responsesLite,
+		requestContext.requestMetadata,
+		await getCodexAttestationHeader(requestContext.accountId),
+		requestContext.transformedBody,
+	);
+	let websocketConnection = await getOrCreateCodexWebSocketConnection(
+		websocketState,
+		requestContext.turnState,
+		toWebSocketUrl(requestContext.url),
+		websocketHeaders,
+		model.provider,
+		requestSetup.requestSignal,
+	);
+	const timeouts: CodexWebSocketRequestTimeouts = {
+		idleTimeoutMs: requestSetup.websocketIdleTimeoutMs,
+		firstEventTimeoutMs: requestSetup.websocketFirstEventTimeoutMs,
+	};
+	// Steering accepted for the previous response lives only on the socket that
+	// accepted it; a replaced socket lost it, so the input is plain history.
+	const steers = steered?.connection === websocketConnection ? steered.steers : [];
+	const liveSteers = steers.filter(steer => !websocketConnection.hasFailedSteer([steer.id]));
+	if (liveSteers.length > 0) {
+		const plan = planSteeredRequest(
+			chainedBody.previous_response_id ? chainedBody.input : undefined,
+			liveSteers.flatMap(steer => steer.items),
+		);
+		if (plan.kind === "attach") {
+			recordCodexTurnRequestDiagnostics(websocketState, chainedBody, "websocket", canAppendBeforeRequest);
+			requestContext.rawRequestDump.body = chainedBody;
+			return {
+				eventStream: websocketConnection.streamRequest(
+					{ attachSteerIds: liveSteers.map(steer => steer.id) },
+					timeouts,
+					requestSetup.requestSignal,
+					onSseEvent,
+				),
+				requestBodyForState: structuredCloneJSON(requestContext.transformedBody),
+				transport: "websocket",
+			};
+		}
+		if (plan.kind === "create") {
+			chainedBody = { ...chainedBody, input: plan.input };
+		} else {
+			// The server continues from input this request cannot line up with; a
+			// fresh socket drops its queue and the full transcript carries the input.
+			websocketConnection.close("steering-discard");
+			websocketState.connection = undefined;
+			resetCodexWebSocketAppendState(websocketState);
+			chainedBody = requestContext.transformedBody;
+			websocketConnection = await getOrCreateCodexWebSocketConnection(
+				websocketState,
+				requestContext.turnState,
+				toWebSocketUrl(requestContext.url),
+				websocketHeaders,
+				model.provider,
+				requestSetup.requestSignal,
+			);
+		}
+	}
 	// WebSocket frames cannot carry per-request HTTP headers. Canonical Codex
 	// request identity is already in `client_metadata`; connection-scoped
 	// compatibility values that can change after the upgrade ride alongside it
@@ -1818,20 +1903,6 @@ async function openCodexWebSocketTransport(
 		websocketRequest = replacementWebsocketRequest as typeof websocketRequest;
 	}
 	recordCodexTurnRequestDiagnostics(websocketState, websocketRequest, "websocket", canAppendBeforeRequest);
-	const websocketHeaders = createCodexHeaders(
-		requestContext.requestHeaders,
-		requestContext.accountId,
-		requestContext.apiKey,
-		requestContext.codexClientVersion,
-		requestContext.transportSessionId,
-		"websocket",
-		websocketState,
-		requestContext.turnState,
-		requestContext.responsesLite,
-		requestContext.requestMetadata,
-		await getCodexAttestationHeader(requestContext.accountId),
-		requestContext.transformedBody,
-	);
 	const requestBodyForState = structuredCloneJSON(requestContext.transformedBody);
 	// `onPayload` may rewrite the outgoing frame (e.g. drop `stream_options`);
 	// recorded state must reflect what was actually sent — the sequential-cutoff
@@ -1854,20 +1925,9 @@ async function openCodexWebSocketTransport(
 			retry,
 			retryBudget: CODEX_WEBSOCKET_RETRY_BUDGET,
 		});
-	const websocketConnection = await getOrCreateCodexWebSocketConnection(
-		websocketState,
-		requestContext.turnState,
-		toWebSocketUrl(requestContext.url),
-		websocketHeaders,
-		model.provider,
-		requestSetup.requestSignal,
-	);
 	const eventStream = websocketConnection.streamRequest(
-		websocketRequest,
-		{
-			idleTimeoutMs: requestSetup.websocketIdleTimeoutMs,
-			firstEventTimeoutMs: requestSetup.websocketFirstEventTimeoutMs,
-		},
+		{ send: websocketRequest },
+		timeouts,
 		requestSetup.requestSignal,
 		onSseEvent,
 	);
@@ -2097,6 +2157,12 @@ class CodexStreamProcessor {
 	requestContext: CodexRequestContext;
 	startTime: number;
 	firstTokenTime?: number;
+	/** Submits caller steering to the response currently streaming. */
+	#steerPump?: CodexSteerPump;
+	/** Socket {@link #steerPump} submits through. */
+	#steerConnection?: CodexWebSocketConnection;
+	/** A replaced attempt accepted steering its socket may still act on. */
+	#steerTainted = false;
 
 	constructor(init: {
 		runtime: CodexStreamRuntime;
@@ -2150,10 +2216,15 @@ class CodexStreamProcessor {
 						});
 					throw new CodexProviderStreamError("Codex stream ended before terminal completion event", true);
 				}
+				await this.#settleSteering(true);
 				return { firstTokenTime };
 			} catch (error) {
+				// The failed attempt's response no longer takes input; a retry
+				// steers its own response.
+				await this.#retireSteering();
 				const recovered = await this.#recoverStreamError(error);
 				if (!recovered) {
+					await this.#settleSteering(false);
 					throw error;
 				}
 				stream.push({ type: "start", partial: output });
@@ -2166,6 +2237,11 @@ class CodexStreamProcessor {
 		const eventType = typeof rawEvent.type === "string" ? rawEvent.type : "";
 		if (!eventType) return firstTokenTime;
 
+		if (eventType === "response.created") {
+			this.#startSteering(rawEvent);
+			return firstTokenTime;
+		}
+
 		if (eventType === "response.output_item.added") {
 			this.runtime.whitespaceToolCallArgumentsDelta = undefined;
 			if (!firstTokenTime) firstTokenTime = performance.now();
@@ -2376,6 +2452,67 @@ class CodexStreamProcessor {
 		return firstTokenTime;
 	}
 
+	/** Start delivering caller steering into the response `response.created` announced. */
+	#startSteering(rawEvent: Record<string, unknown>): void {
+		const source = this.options?.liveSteering;
+		const connection = this.runtime.websocketState?.connection;
+		const responseId = asRecord(rawEvent.response)?.id;
+		if (
+			!source ||
+			!connection ||
+			this.#steerPump ||
+			typeof responseId !== "string" ||
+			this.runtime.transport !== "websocket" ||
+			!this.model.compat.supportsSteering
+		) {
+			return;
+		}
+		this.#steerConnection = connection;
+		this.#steerPump = new CodexSteerPump(source, connection, messages =>
+			toSteerInputItems(convertMessages(this.model, { messages: [...messages] })),
+		);
+		this.#steerPump.start(responseId);
+	}
+
+	/** Stop steering an attempt that is being replaced; anything it delivered taints its socket. */
+	async #retireSteering(): Promise<void> {
+		const pump = this.#steerPump;
+		if (!pump) return;
+		this.#steerPump = undefined;
+		const outcome = await pump.finish();
+		if (outcome.accepted.length > 0 || outcome.uncertain) this.#steerTainted = true;
+	}
+
+	/**
+	 * Settle steering once the stream is over. Steering accepted for the final
+	 * response is handed to the next request; anything the session cannot line
+	 * up with the server's queue drops the socket so no stray successor streams
+	 * into a later request.
+	 */
+	async #settleSteering(completed: boolean): Promise<void> {
+		const pump = this.#steerPump;
+		this.#steerPump = undefined;
+		const outcome = pump ? await pump.finish() : undefined;
+		const accepted = outcome?.accepted ?? [];
+		const tainted = this.#steerTainted || outcome?.uncertain === true;
+		const state = this.runtime.websocketState;
+		const connection = this.#steerConnection;
+		if (!state || !connection || (accepted.length === 0 && !tainted)) return;
+		if (
+			completed &&
+			!tainted &&
+			state.canAppend &&
+			state.connection === connection &&
+			state.lastResponseId === outcome?.responseId
+		) {
+			state.acceptedSteering = { connection, steers: accepted };
+			return;
+		}
+		connection.close("steering-discard");
+		if (state.connection === connection) state.connection = undefined;
+		resetCodexWebSocketAppendState(state);
+	}
+
 	#flushSummaryDeltas(entry: CodexOpenItem | null): void {
 		if (entry?.block?.type !== "thinking") return;
 		for (const delta of this.runtime.takeSummaryDeltas(entry)) {
@@ -2529,6 +2666,21 @@ class CodexStreamProcessor {
 			output.responseId = responseId;
 		}
 
+		const incompleteDetails =
+			response &&
+			"incomplete_details" in response &&
+			response.incomplete_details &&
+			typeof response.incomplete_details === "object"
+				? response.incomplete_details
+				: undefined;
+		const incompleteReason =
+			incompleteDetails && "reason" in incompleteDetails ? incompleteDetails.reason : undefined;
+		// Steering stopped the response at an output boundary: every item is
+		// complete and the server continues from it, so it chains and ends like a
+		// completed response.
+		const steered = status === "incomplete" && incompleteReason === "steered";
+		if (steered) logger.debug("Codex response stopped for steering", { responseId });
+
 		const state = runtime.websocketState;
 		if (state) {
 			if (runtime.transport !== "websocket") {
@@ -2545,7 +2697,7 @@ class CodexStreamProcessor {
 				if (responseId && replayableResponseItems && replayableResponseItems.length === nativeOutputItems.length) {
 					state.lastResponseId = responseId;
 					state.lastResponseItems = replayableResponseItems;
-					state.canAppend = rawEvent.type === "response.done" || rawEvent.type === "response.completed";
+					state.canAppend = rawEvent.type === "response.done" || rawEvent.type === "response.completed" || steered;
 				} else {
 					// No response id, or replay sanitization dropped an item the server
 					// still holds. Sanitization is 1:1-or-fewer, so either case makes the
@@ -2555,24 +2707,15 @@ class CodexStreamProcessor {
 			}
 		}
 
-		const incompleteDetails =
-			response &&
-			"incomplete_details" in response &&
-			response.incomplete_details &&
-			typeof response.incomplete_details === "object"
-				? response.incomplete_details
-				: undefined;
 		const shouldPromoteIncompleteToolUse =
 			status === "incomplete" &&
-			incompleteDetails !== undefined &&
-			"reason" in incompleteDetails &&
-			incompleteDetails.reason === "max_output_tokens" &&
+			incompleteReason === "max_output_tokens" &&
 			hasExecutableIncompleteResponsesToolCalls(output);
 		finalizePendingResponsesToolCalls(output);
 
 		calculateCost(model, output.usage, output.timestamp);
 		applyCodexServiceTierPricing(model, output.usage, serviceTier, runtime.requestBodyForState.service_tier);
-		output.stopReason = mapOpenAIResponsesStopReason(status);
+		output.stopReason = mapOpenAIResponsesStopReason(steered ? "completed" : status);
 		promoteResponsesToolUseStopReason(
 			output,
 			endTurn === true ? true : endTurn === false ? false : undefined,
@@ -2581,6 +2724,17 @@ class CodexStreamProcessor {
 	}
 
 	async #recoverStreamError(error: unknown): Promise<boolean> {
+		if (
+			error instanceof CodexSteerCommitError &&
+			this.runtime.websocketState &&
+			this.output.content.length === 0 &&
+			!this.options?.signal?.aborted
+		) {
+			// No successor is coming: send this request explicitly, steering
+			// input included as ordinary history.
+			await this.#reopenWebSocketStream(this.runtime.websocketState);
+			return true;
+		}
 		if (await this.#tryDropRejectedAccessPrograms(error)) {
 			return true;
 		}
@@ -3241,6 +3395,19 @@ function recordCodexWebSocketFailure(state: CodexWebSocketSessionState, activate
 	}
 }
 
+/**
+ * WebSocket not selected for this request (e.g. the preference was switched off
+ * mid-session): close an idle cached socket so it stops heartbeating and is
+ * never reused against a transcript advanced over SSE.
+ */
+function releaseIdleCodexWebSocket(state: CodexWebSocketSessionState): void {
+	const connection = state.connection;
+	if (!connection || connection.isBusy()) return;
+	connection.close("transport_not_selected");
+	state.connection = undefined;
+	resetCodexWebSocketAppendState(state);
+}
+
 function shouldUseCodexWebSocket(
 	model: Model<"openai-codex-responses">,
 	state: CodexWebSocketSessionState | undefined,
@@ -3635,6 +3802,18 @@ interface CodexWebSocketRequestTimeouts {
 	firstEventTimeoutMs?: number;
 }
 
+/** What {@link CodexWebSocketConnection.streamRequest} puts on the wire before reading a response. */
+type CodexWebSocketExchange =
+	| { send: Record<string, unknown> }
+	/** Read the successor the server creates from accepted steering; nothing is sent. */
+	| { attachSteerIds: readonly string[] };
+
+interface CodexSteerWaiter {
+	previousResponseId: string;
+	resolve: (ack: CodexSteerAck) => void;
+	reject: (error: Error) => void;
+}
+
 interface CodexWebSocketConnectionOptions {
 	onHandshakeHeaders?: (headers: Headers) => void;
 	proxy?: string;
@@ -3670,6 +3849,14 @@ class CodexWebSocketConnection {
 	 * previous (cleanly-completed) response that outlived the queue drain.
 	 */
 	#lastSeenResponseId?: string;
+	/** `response.steer` submissions awaiting acknowledgement, oldest first. */
+	#steerWaiters: CodexSteerWaiter[] = [];
+	/** Steering ids the server accepted on this socket. */
+	#acceptedSteers = new Set<string>();
+	/** Accepted steering the server later failed to commit to a successor. */
+	#failedSteers = new Set<string>();
+	/** Steering whose automatic successor the active attach request is reading. */
+	#attachSteerIds?: ReadonlySet<string>;
 
 	constructor(url: string, headers: Record<string, string>, options: CodexWebSocketConnectionOptions) {
 		this.#url = url;
@@ -3687,6 +3874,11 @@ class CodexWebSocketConnection {
 		return this.#connectPromise !== undefined;
 	}
 
+	/** True while a handshake or a request stream is in flight on this socket. */
+	isBusy(): boolean {
+		return this.#activeRequest || this.#connectPromise !== undefined;
+	}
+
 	/**
 	 * Stricter variant of {@link isOpen} for the connection-pool reuse gate.
 	 * Refuses sockets that have been silent past {@link CODEX_WEBSOCKET_MAX_IDLE_REUSE_MS}.
@@ -3718,6 +3910,7 @@ class CodexWebSocketConnection {
 		const socket = this.#socket;
 		this.#socket = null;
 		this.#stopHeartbeat();
+		this.#rejectSteerWaiters(`websocket closed (${reason})`);
 		if (!socket || (socket.readyState !== WebSocket.OPEN && socket.readyState !== WebSocket.CONNECTING)) return;
 		try {
 			socket.close(1000, reason);
@@ -3808,6 +4001,7 @@ class CodexWebSocketConnection {
 		socket.onclose = event => {
 			this.#socket = null;
 			this.#stopHeartbeat();
+			this.#rejectSteerWaiters(`websocket closed (${event.code})`);
 			if (!settled) {
 				settled = true;
 				clearPending();
@@ -3837,6 +4031,12 @@ class CodexWebSocketConnection {
 					}
 				}
 				notifyCodexWebSocketInbound(this.#streamObserver, parsed, text);
+				// Steering acknowledgements belong to the submitter, not to the
+				// response stream they interleave with.
+				if (typeof parsed.type === "string" && parsed.type.startsWith("response.steer.")) {
+					this.#handleSteerEvent(parsed);
+					return;
+				}
 				this.#push(parsed);
 			} catch (error) {
 				notifyCodexWebSocketMalformed(this.#streamObserver, event.data, error);
@@ -3853,7 +4053,7 @@ class CodexWebSocketConnection {
 	}
 
 	async *streamRequest(
-		request: Record<string, unknown>,
+		exchange: CodexWebSocketExchange,
 		timeouts: CodexWebSocketRequestTimeouts,
 		signal?: AbortSignal,
 		onSseEvent?: (event: RawSseEvent) => void,
@@ -3870,6 +4070,8 @@ class CodexWebSocketConnection {
 		this.#activeRequest = true;
 		this.#streamObserver = onSseEvent;
 		// Drain any non-error frames left over from a prior request before sending.
+		// An attach reads exactly those frames: the successor the server started
+		// from accepted steering while no request was reading.
 		// `CodexStreamProcessor.process` breaks its `for-await` on the terminal event,
 		// which interrupts our generator at `yield next` (the post-yield `break`
 		// never runs). Any frame that landed between the consumer's break and the
@@ -3879,7 +4081,11 @@ class CodexWebSocketConnection {
 		// flip `sawFirstEvent` and silently downgrade the first-event timeout to
 		// the longer idle timeout. Transport errors are preserved so we surface
 		// the death signal instead of writing into a dead socket.
-		this.#dropStaleFrames();
+		if ("send" in exchange) {
+			this.#dropStaleFrames();
+		} else {
+			this.#attachSteerIds = new Set(exchange.attachSteerIds);
+		}
 		const onAbort = () => {
 			this.#push(new CodexWebSocketTransportError(`request was aborted`, { cause: signal?.reason }));
 			// Closing can synchronously enqueue a generic onclose error.
@@ -3888,39 +4094,44 @@ class CodexWebSocketConnection {
 		if (signal) signal.addEventListener("abort", onAbort, { once: true });
 
 		try {
-			const debugSession = isRequestDebugEnabled()
-				? await createRequestDebugSession({
-						protocol: "websocket",
-						method: "POST",
-						url: this.#url,
-						headers: this.#headers,
-						body: request,
-					})
-				: undefined;
-			this.#debugResponseLog = debugSession
-				? await debugSession.openResponseLog("WebSocket 101 Switching Protocols", this.#handshakeHeaders)
-				: undefined;
+			if ("send" in exchange) {
+				const request = exchange.send;
+				const debugSession = isRequestDebugEnabled()
+					? await createRequestDebugSession({
+							protocol: "websocket",
+							method: "POST",
+							url: this.#url,
+							headers: this.#headers,
+							body: request,
+						})
+					: undefined;
+				this.#debugResponseLog = debugSession
+					? await debugSession.openResponseLog("WebSocket 101 Switching Protocols", this.#handshakeHeaders)
+					: undefined;
 
-			const requestPayload = JSON.stringify(request);
-			notifyCodexWebSocketOutbound(onSseEvent, request, requestPayload);
-			// Re-check liveness: the debug-session await above can outlive the socket.
-			// Preserve the abort cause: onAbort already queued a caused error, but this
-			// throw would otherwise mask it before #nextMessage() drains the queue.
-			const socket = this.#socket;
-			if (!socket || socket.readyState !== WebSocket.OPEN) {
-				if (signal?.aborted) {
-					throw new CodexWebSocketTransportError(`websocket connection is unavailable`, {
-						cause: signal.reason,
-					});
+				const requestPayload = JSON.stringify(request);
+				notifyCodexWebSocketOutbound(onSseEvent, request, requestPayload);
+				// Re-check liveness: the debug-session await above can outlive the socket.
+				// Preserve the abort cause: onAbort already queued a caused error, but this
+				// throw would otherwise mask it before #nextMessage() drains the queue.
+				const socket = this.#socket;
+				if (!socket || socket.readyState !== WebSocket.OPEN) {
+					if (signal?.aborted) {
+						throw new CodexWebSocketTransportError(`websocket connection is unavailable`, {
+							cause: signal.reason,
+						});
+					}
+					throw new CodexWebSocketTransportError(`websocket connection is unavailable`);
 				}
-				throw new CodexWebSocketTransportError(`websocket connection is unavailable`);
-			}
-			try {
-				socket.send(requestPayload);
-			} catch (error) {
-				throw new CodexWebSocketTransportError(
-					`websocket send failed: ${error instanceof Error ? error.message : String(error)}`,
-				);
+				try {
+					socket.send(requestPayload);
+				} catch (error) {
+					throw new CodexWebSocketTransportError(
+						`websocket send failed: ${error instanceof Error ? error.message : String(error)}`,
+					);
+				}
+			} else if (this.hasFailedSteer(exchange.attachSteerIds)) {
+				throw new CodexSteerCommitError("accepted steering was not committed to a successor response");
 			}
 			let sawFirstEvent = false;
 			const { idleTimeoutMs, firstEventTimeoutMs } = timeouts;
@@ -4039,6 +4250,7 @@ class CodexWebSocketConnection {
 		} finally {
 			this.#activeRequest = false;
 			this.#streamObserver = undefined;
+			this.#attachSteerIds = undefined;
 			if (signal) {
 				signal.removeEventListener("abort", onAbort);
 			}
@@ -4048,6 +4260,83 @@ class CodexWebSocketConnection {
 		}
 	}
 
+	/**
+	 * Submit `response.steer` for `previousResponseId`, which must be streaming
+	 * on this socket. Resolves on the server's acknowledgement.
+	 */
+	steer(previousResponseId: string, input: InputItem[]): Promise<CodexSteerAck> {
+		const socket = this.#socket;
+		if (!socket || socket.readyState !== WebSocket.OPEN) {
+			return Promise.reject(new CodexWebSocketTransportError(`websocket connection is unavailable`));
+		}
+		const event = { type: "response.steer", previous_response_id: previousResponseId, input };
+		const payload = JSON.stringify(event);
+		const { promise, resolve, reject } = Promise.withResolvers<CodexSteerAck>();
+		const waiter: CodexSteerWaiter = { previousResponseId, resolve, reject };
+		this.#steerWaiters.push(waiter);
+		notifyCodexWebSocketOutbound(this.#streamObserver, event, payload);
+		try {
+			socket.send(payload);
+		} catch (error) {
+			this.#steerWaiters.splice(this.#steerWaiters.indexOf(waiter), 1);
+			reject(
+				new CodexWebSocketTransportError(
+					`websocket send failed: ${error instanceof Error ? error.message : String(error)}`,
+				),
+			);
+		}
+		return promise;
+	}
+
+	/** True when the server failed to commit any of the accepted steering `ids`. */
+	hasFailedSteer(ids: readonly string[]): boolean {
+		return ids.some(id => this.#failedSteers.has(id));
+	}
+
+	#handleSteerEvent(event: Record<string, unknown>): void {
+		const steer = asRecord(event.steer);
+		const id = typeof steer?.id === "string" ? steer.id : undefined;
+		const previousResponseId = typeof steer?.previous_response_id === "string" ? steer.previous_response_id : "";
+		if (event.type === "response.steer.accepted") {
+			if (!id) return;
+			this.#acceptedSteers.add(id);
+			this.#takeSteerWaiter(previousResponseId)?.resolve({ accepted: true, id });
+			return;
+		}
+		if (event.type === "response.steer.failed") {
+			const error = asRecord(event.error);
+			const code = typeof error?.code === "string" ? error.code : undefined;
+			const message = typeof error?.message === "string" ? error.message : undefined;
+			if (id && this.#acceptedSteers.has(id)) {
+				// Accepted input that never reached a successor response.
+				this.#failedSteers.add(id);
+				if (this.#attachSteerIds?.has(id)) {
+					this.#push(
+						new CodexSteerCommitError(`steering ${id} was not committed: ${code ?? message ?? "unknown"}`),
+					);
+				}
+				return;
+			}
+			this.#takeSteerWaiter(previousResponseId)?.resolve({ accepted: false, code, message });
+			return;
+		}
+		// `response.steer.pending` restates that accepted input awaits tool output;
+		// the request planner already derives that from the transcript.
+		CODEX_DEBUG && logger.debug("[codex] codex steering event", { type: event.type, id, previousResponseId });
+	}
+
+	#takeSteerWaiter(previousResponseId: string): CodexSteerWaiter | undefined {
+		const index = this.#steerWaiters.findIndex(waiter => waiter.previousResponseId === previousResponseId);
+		return index < 0 ? undefined : this.#steerWaiters.splice(index, 1)[0];
+	}
+
+	#rejectSteerWaiters(reason: string): void {
+		const waiters = this.#steerWaiters;
+		if (waiters.length === 0) return;
+		this.#steerWaiters = [];
+		for (const waiter of waiters) waiter.reject(new CodexWebSocketTransportError(reason));
+	}
+
 	#captureHandshakeHeaders(socket: Bun.WebSocket, openEvent?: Event): void {
 		const headers = extractCodexWebSocketHandshakeHeaders(socket, openEvent);
 		if (!headers) return;
@@ -4806,6 +5095,16 @@ export class CodexWebSocketTransportError extends Error {
 		this.name = "CodexWebSocketTransportError";
 	}
 }
+/**
+ * The server failed to commit accepted steering to its automatic successor, so
+ * the request that was reading that successor must be sent explicitly instead.
+ */
+class CodexSteerCommitError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "CodexSteerCommitError";
+	}
+}
 class CodexWhitespaceToolCallLoopError extends Error {
 	constructor(message: string) {
 		super(message);