pi-openai-toolkit 0.21.0 → 0.22.0

package/README.md

@@ -60,6 +60,14 @@ Change `mode` in the example above to `remote-windows`. Eligible sessions expose
 
 Remote windows use alpha endpoints that may change upstream. When switching models, the remote window remains persisted and reusable; see the [window lifecycle](docs/internals.md#rollover-lifecycle).
 
+## Codex Fast
+
+Fast is OFF by default. In the terminal, run `/fast` to turn it ON, then run `/fast` again to turn it OFF. The status bar shows `Fast ON`, `Fast OFF`, or `Fast N/A` for an ineligible route. No Fast configuration is needed.
+
+Supports native Codex and recognizable GPT/Codex models on compatible Responses gateways. The selection is saved only in the current session: reload/resume and `new_context` retain it; new or forked sessions start OFF. ON requests Fast, while OFF requests Standard, overriding an existing service-tier preference on eligible conversation requests without changing reasoning effort or configuration files.
+
+Fast may increase usage/cost. The indicator shows the requested mode, not confirmed backend acceleration; a gateway may reject, ignore, or downgrade it. Opaque gateway model aliases need an existing Codex gateway identity. See the [Fast contract](docs/internals.md#codex-fast-session-control) for scope and lifecycle details.
+
 ## Search, images, and transport
 
 ### Web search

package/README.zh.md

@@ -60,6 +60,14 @@ Toolkit 只读取一个全局配置文件，即使扩展安装在项目内也一
 
 远程窗口依赖 alpha 接口，上游可能随时调整。切换模型时远程窗口状态仍会持久化并可复用，详见[窗口生命周期](docs/internals.md#rollover-lifecycle)。
 
+## Codex Fast
+
+Fast 默认关闭。在终端输入 `/fast` 开启，再输入一次 `/fast` 关闭。状态栏显示 `Fast ON`、`Fast OFF`，不适用的路由显示 `Fast N/A`。无需添加 Fast 配置。
+
+支持原生 Codex，以及兼容 Responses 网关中可识别的 GPT/Codex 模型。开关只保存在当前会话：reload、续聊和 `new_context` 保留状态，新建或 fork 的会话默认关闭。开启时请求 Fast，关闭时请求标准档，会覆盖符合条件的对话请求中原有的服务档位，但不改变 reasoning effort 或配置文件。
+
+Fast 可能增加额度消耗或费用。状态栏表示请求模式，不代表后端已确认加速；网关可能拒绝、忽略或降级请求。无法识别的网关模型别名需要已有的 Codex 网关路由标识。适用范围和生命周期见 [Fast 规则](docs/internals.md#codex-fast-session-control)。
+
 ## 搜索、生图与传输
 
 ### 联网搜索

package/docs/configuration.md

@@ -93,19 +93,23 @@ This selects an existing Toolkit protocol profile, independently of context mode
 
 The Responses WebSocket extension is disabled by default. Enable it globally with `defaults.responsesWebSocket.enabled: true`; it is intentionally not a model-scoped override. Restart or reload Pi after changing this setting. An invalid or legacy configuration keeps the feature disabled.
 
-The extension is an API-adapter override, not a provider registration. It applies to GPT model IDs whose Pi API is `openai-responses`, regardless of provider name. The active model's `baseUrl`, `apiKey`, configured headers, session id, and payload remain the source of truth.
+The extension is an API-adapter override, not a provider registration. For requests dispatched through this API adapter, it applies to GPT model IDs whose Pi API is `openai-responses`, regardless of provider name. Providers that bypass the compat API adapter keep their own transport behavior. The active model's `baseUrl`, `apiKey`, configured headers, session id, and payload remain the source of truth.
 
 The extension honors Pi's global `transport` setting:
 
 | Pi `transport` | Behavior |
 | --- | --- |
-| `auto` | Try `wss://.../responses?model=...` first; fall back to the original SSE adapter only before a stream starts. With a stable session id, reuse the WebSocket and send a continuation delta when possible. |
+| `auto` | Try `wss://.../responses?model=...` first; allow one original HTTP/SSE fallback per fetch call for a recoverable WS failure before the first valid event is exposed. With a stable session id, reuse the WebSocket and send a continuation delta when possible. |
 | `websocket` | Require the WebSocket path; do not fall back to SSE. This mode opens a request-scoped connection. |
 | `websocket-cached` | Require the WebSocket path and keep a session-scoped connection for later turns. |
 | `sse` | Bypass the extension and use the original HTTP/SSE adapter. |
 
 The endpoint is derived from the model's base URL by appending `/responses` when needed and switching `https:`/`http:` to `wss:`/`ws:`. The first frame is a standard `response.create` object and incoming frames are passed through Pi's existing Responses event normalizer. For `auto` and `websocket-cached`, Toolkit caches an open socket by session/model/endpoint/auth identity for up to five minutes idle or 55 minutes of age. When the current transcript has the cached request and response as a prefix, the next frame uses `previous_response_id` and only the new input items; if it cannot prove that relationship, it sends the full payload instead. A missing session id or `cacheRetention: "none"` disables reuse. The upstream must support the standard Responses WebSocket contract, including continuation semantics for `previous_response_id`; this does not rewrite a server that only exposes Codex's `/codex/responses` path or Codex-only authentication.
 
+The first valid exposed event commits the WS attempt, including `response.created` even before text or tool arguments arrive. After that boundary, Toolkit never switches transport or splices a new generation into the same stream. Local transient WS failures and compatible WS error envelopes containing `stream closed before response.completed` retain their diagnostics with a Pi-recognized transport indication; Pi's native retry settings and budget decide whether to retry the failed step. Authentication, quota/billing, context/invalid-request/policy errors, malformed frames, and cancellation do not authorize Toolkit fallback. An SDK request deadline can cancel startup before a fallback is possible.
+
+A failed connection is evicted. Any permitted fallback receives the original complete effective request, not a cached input delta; a new WS connection also starts from the full request. Pi remains responsible for effective context, completed tool results, failed-attempt history, tool execution, and usage. This prevents Toolkit from replaying completed tools as part of recovery, but does not guarantee idempotency if the model explicitly requests the same operation again. Direct SSE and errors from the original fallback SSE path are unchanged. Recovery depends on backend health and Pi's native retry policy; it is not token-level resumption or an unlimited retry loop.
+
 This feature does not write Pi settings, model files, auth files, or global extensions. To keep the Toolkit adapter disabled, set `defaults.responsesWebSocket.enabled` to `false` or omit it. Once enabled, Pi's global `transport: "sse"` still bypasses the WebSocket path for a request.
 
 ---

package/docs/internals.md

@@ -7,6 +7,7 @@ Developer-facing reference for [pi-openai-toolkit](../README.md). The README kee
 ### Table of Contents
 
 - [Configuration resolution](#configuration-resolution)
+- [Codex Fast session control](#codex-fast-session-control)
 - [Remote Context protocol](#remote-context-protocol)
 - [Rollover lifecycle](#rollover-lifecycle)
 - [Managed manual compact](#managed-manual-compact)
@@ -26,6 +27,20 @@ Selected invalid policy blocks dependent operations; unrelated model errors rema
 
 ---
 
+### Codex Fast session control
+
+[src/codex-fast/extension.ts](../src/codex-fast/extension.ts) registers the human-only, no-argument `/fast` toggle and an owned `ctx.ui.setStatus()` item. Default OFF requests `service_tier: "default"`; ON requests `"priority"`, the Codex Fast wire value. The status is the local request preference, not verified server acceptance or latency. Fast can increase usage/cost. No config setting, model tool, credential probe, retry, new header, reasoning-effort change or custom footer is added.
+
+Native `openai-codex-responses` routes qualify. Non-official HTTP(S) `openai-responses` gateways qualify for recognizable GPT/Codex IDs or an existing exact Codex gateway identity, including a resolved virtual route. Unknown opaque aliases without that identity, Azure, other APIs and ordinary `api.openai.com` API-key routes remain untouched. A capability marker is not backend entitlement.
+
+Version-1 `pi-openai-toolkit:codex-fast` custom entries contain only the owning Pi `sessionId` and `enabled` boolean. They are excluded from model context. Reload/resume and active-branch navigation reconstruct the latest valid owned preference; malformed latest metadata defaults OFF. Independent new/forked sessions ignore copied foreign preferences and start OFF. Remote window UUID changes do not reset the Pi session selection. A model switch shows N/A without discarding it. Missing identity or a failed append does not report a successful toggle.
+
+The payload hook takes one selection snapshot and returns a new object only when a matching ordinary Responses request needs a tier change. Explicit OFF also overrides an existing Fast/Flex tier to Standard. Dedicated compaction shapes and malformed/foreign payloads are left unchanged. Fast loads after Web Search/image registration and before the final Astra effort pass, so its tier does not alter the pre-search cached extras used by separate search/image/compaction clients.
+
+Native Pi and Toolkit gateway WebSocket adapters already compare non-input body fields before incremental reuse. A changed `service_tier` invalidates the incompatible `previous_response_id` delta; the existing transport/retry logic is retained. Offline official-Pi fixtures in [test/pi-codex-fast.test.ts](../test/pi-codex-fast.test.ts) cover terminal command/status, actual native/gateway HTTP/WebSocket bodies, saved reopen/reload, fork isolation and continuation transitions. They do not establish live Fast availability.
+
+---
+
 ### Remote Context protocol
 
 Internal alpha endpoints, adapted from `@howaboua/pi-codex-conversion`:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-openai-toolkit",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "private": false,
   "type": "module",
   "engines": {
@@ -36,6 +36,7 @@
       "./src/extension-runtime.ts",
       "./src/web-search/extension.ts",
       "./src/image-generation/extension.ts",
+      "./src/codex-fast/extension.ts",
       "./src/codex-astra/extension.ts",
       "./src/responses-websocket/extension.ts"
     ]
@@ -78,6 +79,9 @@
     "src/image-generation/render.ts",
     "src/image-generation/service.ts",
     "src/image-generation/types.ts",
+    "src/codex-fast/extension.ts",
+    "src/codex-fast/payload.ts",
+    "src/codex-fast/state.ts",
     "src/codex-astra/effort-planner.ts",
     "src/codex-astra/extension.ts",
     "src/responses-websocket/extension.ts",

package/src/codex-fast/extension.ts

@@ -0,0 +1,119 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { loadToolkitConfig, resolveToolkitConfig } from "../config";
+import { resolveEffectiveModel } from "../runtime";
+import { isCodexFastModel, rewriteCodexFastPayload } from "./payload";
+import { CODEX_FAST_ENTRY_TYPE, readCodexFastState, type CodexFastState } from "./state";
+
+export const CODEX_FAST_STATUS_KEY = "pi-openai-toolkit:codex-fast";
+
+function sessionId(ctx: ExtensionContext): string | undefined {
+	try {
+		const id = ctx.sessionManager.getSessionId();
+		return typeof id === "string" && id.trim() ? id : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+export function registerCodexFastExtension(
+	pi: ExtensionAPI,
+	loadConfig: typeof loadToolkitConfig = loadToolkitConfig,
+	resolveModel: typeof resolveEffectiveModel = resolveEffectiveModel,
+): void {
+	let currentSessionId: string | undefined;
+	let enabled = false;
+	let statusEpoch = 0;
+
+	function restore(ctx: ExtensionContext): void {
+		currentSessionId = sessionId(ctx);
+		try {
+			enabled = readCodexFastState(ctx.sessionManager.getBranch(), currentSessionId);
+		} catch {
+			enabled = false;
+		}
+	}
+	function synchronize(ctx: ExtensionContext): void {
+		if (sessionId(ctx) !== currentSessionId) restore(ctx);
+	}
+	function notify(ctx: ExtensionContext, text: string, level: "info" | "warning" = "info"): void {
+		if (ctx.hasUI) ctx.ui.notify(text, level);
+	}
+	async function eligibleModel(ctx: ExtensionContext, selected = ctx.model): Promise<ExtensionContext["model"]> {
+		try {
+			const effective = await resolveModel(ctx, selected);
+			if (!effective.ok) return undefined;
+			if (isCodexFastModel(effective.model)) return effective.model;
+			// Only opaque aliases need the existing compatibility marker. Known
+			// Codex/GPT routes work without loading or adding Toolkit settings.
+			if (effective.model.api !== "openai-responses") return undefined;
+			const resolved = resolveToolkitConfig(loadConfig(), selected);
+			if (resolved.invalidFeatures.includes("compatibility")) return undefined;
+			return isCodexFastModel(effective.model, resolved.gatewayModelKeys, selected) ? effective.model : undefined;
+		} catch {
+			return undefined;
+		}
+	}
+	async function refreshStatus(ctx: ExtensionContext, model = ctx.model): Promise<void> {
+		synchronize(ctx);
+		const epoch = ++statusEpoch;
+		const id = currentSessionId;
+		const eligible = id && await eligibleModel(ctx, model);
+		if (epoch !== statusEpoch || sessionId(ctx) !== id) return;
+		if (ctx.hasUI) ctx.ui.setStatus(CODEX_FAST_STATUS_KEY, eligible ? "Fast " + (enabled ? "ON" : "OFF") : "Fast N/A");
+	}
+
+	pi.on("session_start", async (_event, ctx) => { restore(ctx); await refreshStatus(ctx); });
+	pi.on("session_tree", async (_event, ctx) => { restore(ctx); await refreshStatus(ctx); });
+	pi.on("model_select", async (event, ctx) => { await refreshStatus(ctx, event.model); });
+	pi.on("session_shutdown", (_event, ctx) => {
+		statusEpoch++;
+		if (ctx.hasUI) ctx.ui.setStatus(CODEX_FAST_STATUS_KEY, undefined);
+	});
+	pi.registerCommand("fast", {
+		description: "Toggle Codex Fast for this session (default OFF; may increase usage/cost).",
+		handler: async (args, ctx) => {
+			if (!ctx.hasUI || (ctx.mode !== undefined && ctx.mode !== "tui")) {
+				notify(ctx, "/fast requires an interactive terminal.", "warning");
+				return;
+			}
+			if (args.trim()) { notify(ctx, "Usage: /fast (toggle ON/OFF)", "warning"); return; }
+			synchronize(ctx);
+			const id = currentSessionId;
+			const selected = ctx.model;
+			const model = await eligibleModel(ctx, selected);
+			if (!id || sessionId(ctx) !== id || ctx.model !== selected) {
+				notify(ctx, "Fast unchanged: session/model unavailable or changed.", "warning");
+				return;
+			}
+			if (!model) { notify(ctx, "Fast unavailable on this model/route.", "warning"); return; }
+			const next = !enabled;
+			const data: CodexFastState = { version: 1, sessionId: id, enabled: next };
+			try {
+				pi.appendEntry(CODEX_FAST_ENTRY_TYPE, data);
+			} catch {
+				notify(ctx, "Fast unchanged: could not save the session preference.", "warning");
+				return;
+			}
+			enabled = next;
+			statusEpoch++;
+			ctx.ui.setStatus(CODEX_FAST_STATUS_KEY, "Fast " + (next ? "ON" : "OFF"));
+			notify(ctx, next
+				? "Fast ON for this session's next Codex requests; may increase usage/cost. Backend acceptance is not verified."
+				: "Fast OFF for this session's next Codex requests (Standard). No configuration file changed.");
+		},
+	});
+	pi.on("before_provider_request", async (event, ctx) => {
+		synchronize(ctx);
+		const id = currentSessionId;
+		const selection = enabled;
+		const selected = ctx.model;
+		if (!id) return undefined;
+		const model = await eligibleModel(ctx, selected);
+		if (!model || sessionId(ctx) !== id || ctx.model !== selected) return undefined;
+		return rewriteCodexFastPayload(event.payload, model.id, selection);
+	});
+}
+
+export default function codexFastExtension(pi: ExtensionAPI): void {
+	registerCodexFastExtension(pi);
+}

package/src/codex-fast/payload.ts

@@ -0,0 +1,36 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { isExactModelAllowed } from "../model-scope";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+/** This checks route identity, never backend entitlement or actual speed. */
+export function isCodexFastModel(
+	model: ExtensionContext["model"],
+	gatewayModels: readonly string[] = [],
+	logicalModel?: ExtensionContext["model"],
+): boolean {
+	if (!model || typeof model.id !== "string" || !model.id.trim()) return false;
+	if (model.api === "openai-codex-responses") return true;
+	if (model.api !== "openai-responses") return false;
+	try {
+		const url = new URL(model.baseUrl);
+		if (!["http:", "https:"].includes(url.protocol) || url.hostname.toLowerCase() === "api.openai.com") return false;
+	} catch {
+		return false;
+	}
+	return /^(?:gpt|codex)(?:-|$)/iu.test(model.id)
+		|| isExactModelAllowed(model, gatewayModels)
+		|| (logicalModel?.api === "pi-virtual" && isExactModelAllowed(logicalModel, gatewayModels));
+}
+
+/** Only ordinary matching conversation payloads are owned by the session switch. */
+export function rewriteCodexFastPayload(payload: unknown, modelId: string, enabled: boolean): Record<string, unknown> | undefined {
+	if (!isRecord(payload) || payload.model !== modelId || !Array.isArray(payload.input)) return undefined;
+	if (!payload.input.every(isRecord)) return undefined;
+	if (payload.input.some((item) => item.type === "compaction_trigger")) return undefined;
+	if (Array.isArray(payload.tools) && payload.tools.some((tool) => isRecord(tool) && tool.type === "remote_compaction_v2")) return undefined;
+	const tier = enabled ? "priority" : "default";
+	return payload.service_tier === tier ? undefined : { ...payload, service_tier: tier };
+}

package/src/codex-fast/state.ts

@@ -0,0 +1,25 @@
+export const CODEX_FAST_ENTRY_TYPE = "pi-openai-toolkit:codex-fast";
+
+export type CodexFastState = {
+	version: 1;
+	sessionId: string;
+	enabled: boolean;
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+/** Session metadata, not model input. Foreign fork/copy entries never apply. */
+export function readCodexFastState(entries: readonly unknown[], sessionId: string | undefined): boolean {
+	if (!sessionId) return false;
+	for (let index = entries.length - 1; index >= 0; index--) {
+		const entry = entries[index];
+		if (!isRecord(entry) || entry.type !== "custom" || entry.customType !== CODEX_FAST_ENTRY_TYPE) continue;
+		const data = entry.data;
+		// A malformed latest preference must not resurrect an older ON.
+		if (!isRecord(data) || data.version !== 1 || typeof data.sessionId !== "string" || typeof data.enabled !== "boolean") return false;
+		if (data.sessionId === sessionId) return data.enabled;
+	}
+	return false;
+}

package/src/responses-websocket/transport.ts

@@ -199,10 +199,69 @@ function buildCacheKey(model: Model<Api>, options: StreamOptions, requestHeaders
 	return [model.provider, model.id, cleanBaseUrl(model.baseUrl), options.sessionId, stableHash(JSON.stringify(identity))].join("\u0000");
 }
 
+// Only transport failures (not arbitrary caught errors) authorize auto fallback.
+class RecoverableWebSocketError extends Error {}
+
+const STREAM_INTERRUPTION = /\bstream closed before response\.completed\b/iu;
+const TERMINAL_FAILURE_TEXT = /quota|billing|budget|usage.?limit|api.?key|unauthori[sz]ed|forbidden|authenticat|permission|invalid|malformed|unsupported|policy|context.?length|context.?overflow|\babort(?:ed)?\b|\bcancell?ed\b/iu;
+const TRANSIENT_ERROR_CODES = new Set(["stream_error", "server_error", "request_timeout"]);
+
+function transportError(error: unknown): Error {
+	const message = error instanceof Error ? error.message : String(error);
+	if ((error instanceof Error && error.name === "AbortError") || TERMINAL_FAILURE_TEXT.test(message)) {
+		return error instanceof Error ? error : new Error(message);
+	}
+	return new RecoverableWebSocketError(/^WebSocket (?:error|closed|.*timeout)/iu.test(message)
+		? message : `WebSocket error: ${message}`);
+}
+
 function socketError(event: WebSocketEvent): Error {
-	if (typeof event.message === "string" && event.message.length > 0) return new Error(event.message);
-	if (event.error instanceof Error) return event.error;
-	return new Error("WebSocket transport failed");
+	if (typeof event.message === "string" && event.message.length > 0) return transportError(event.message);
+	if (event.error instanceof Error) return transportError(event.error);
+	return transportError("WebSocket transport failed");
+}
+
+function socketCloseError(event: WebSocketEvent, streaming: boolean): Error {
+	const suffix = event.reason ? `: ${event.reason}` : "";
+	if ([1002, 1003, 1007, 1008].includes(event.code ?? 0) || TERMINAL_FAILURE_TEXT.test(event.reason ?? "")) {
+		return new Error(`Responses connection rejected${event.code ? ` (${event.code})` : ""}${suffix}`);
+	}
+	return transportError(streaming
+		? `WebSocket closed before response completion${suffix}`
+		: `WebSocket closed${event.code ? ` ${event.code}` : ""}${suffix}`);
+}
+
+function compatibleFailureMetadata(error: Record<string, unknown>): boolean {
+	if (typeof error.message === "string" && TERMINAL_FAILURE_TEXT.test(error.message)) return false;
+	for (const field of ["code", "type"]) {
+		const value = error[field];
+		if (value !== undefined && value !== null && value !== "" &&
+			(typeof value !== "string" || !TRANSIENT_ERROR_CODES.has(value.toLowerCase()))) return false;
+	}
+	for (const field of ["status", "status_code"]) {
+		const value = error[field];
+		if (value !== undefined && value !== null &&
+			(typeof value !== "number" || ![408, 429, 500, 502, 503, 504].includes(value))) return false;
+	}
+	return true;
+}
+
+function normalizeStreamInterruption(event: Record<string, unknown>): Record<string, unknown> | undefined {
+	const response = isRecord(event.response) ? event.response : undefined;
+	const error = event.type === "error" ? event : event.type === "response.failed" && isRecord(response?.error) ? response.error : undefined;
+	if (!error || typeof error.message !== "string" || !STREAM_INTERRUPTION.test(error.message) ||
+		TERMINAL_FAILURE_TEXT.test(error.message)) return undefined;
+	// Envelope type/status describe the event/response, not its failure category.
+	// Still check their code/HTTP status so a nested transient message cannot
+	// override explicit fatal metadata on an enclosing envelope.
+	const metadata: Record<string, unknown>[] = [{ ...event, type: undefined }];
+	if (event.type === "response.failed") {
+		metadata.push({ ...response, type: undefined, status: response?.status === "failed" ? undefined : response?.status }, error);
+	}
+	if (isRecord(error.error)) metadata.push(error.error);
+	if (metadata.some((value) => !compatibleFailureMetadata(value))) return undefined;
+	const normalized = { ...error, message: `WebSocket error: ${error.message}` };
+	return event.type === "error" ? normalized : { ...event, response: { ...response, error: normalized } };
 }
 
 function closeSocket(socket: WebSocketLike | undefined, reason = "done"): void {
@@ -247,8 +306,9 @@ export function closeResponsesWebSocketSessions(sessionId?: string): void {
 }
 
 
-function liveSignals(options: StreamOptions, init?: RequestInit): AbortSignal[] {
-	return [options.signal, init?.signal].filter((signal): signal is AbortSignal => signal !== undefined);
+function liveSignals(options: StreamOptions, input: RequestInfo | URL, init?: RequestInit): AbortSignal[] {
+	return [...new Set([options.signal, init?.signal, input instanceof Request ? input.signal : undefined]
+		.filter((signal): signal is AbortSignal => signal !== undefined && signal !== null))];
 }
 
 async function connectWebSocket(
@@ -258,7 +318,7 @@ async function connectWebSocket(
 	timeoutMs: number,
 ): Promise<WebSocketLike> {
 	const WebSocketCtor = globalThis.WebSocket as unknown as WebSocketConstructor | undefined;
-	if (typeof WebSocketCtor !== "function") throw new Error("WebSocket transport is not available in this runtime");
+	if (typeof WebSocketCtor !== "function") throw transportError("WebSocket transport is not available in this runtime");
 	if (signals.some((signal) => signal.aborted)) throw new Error("Request was aborted");
 
 	return new Promise((resolve, reject) => {
@@ -286,9 +346,7 @@ async function connectWebSocket(
 			resolve(socket!);
 		};
 		const onError = (event: WebSocketEvent) => fail(socketError(event));
-		const onClose = (event: WebSocketEvent) => fail(new Error(
-			`WebSocket closed${typeof event.code === "number" ? ` ${event.code}` : ""}${event.reason ? ` ${event.reason}` : ""}`,
-		));
+		const onClose = (event: WebSocketEvent) => fail(socketCloseError(event, false));
 		const onAbort = () => fail(new Error("Request was aborted"));
 
 		try {
@@ -301,7 +359,8 @@ async function connectWebSocket(
 		socket.addEventListener("error", onError);
 		socket.addEventListener("close", onClose);
 		for (const signal of signals) signal.addEventListener("abort", onAbort, { once: true });
-		if (timeoutMs > 0) timeout = setTimeout(() => fail(new Error(`WebSocket connect timeout after ${timeoutMs}ms`)), timeoutMs);
+		if (signals.some((signal) => signal.aborted)) { onAbort(); return; }
+		if (timeoutMs > 0) timeout = setTimeout(() => fail(transportError(`WebSocket connect timeout after ${timeoutMs}ms`)), timeoutMs);
 	});
 }
 
@@ -439,22 +498,26 @@ function completedContinuation(entry: CachedSocketEntry | undefined, fullPayload
 	return true;
 }
 
-function createSseResponse(
+async function createSseResponse(
 	socket: WebSocketLike,
 	signals: AbortSignal[],
 	idleTimeoutMs: number,
 	requestFrame: string,
 	onTerminal: (event: Record<string, unknown>) => boolean,
 	onRelease: (keep: boolean) => void,
-): Response {
+	allowBootstrapFallback: boolean,
+): Promise<Response> {
 	const encoder = new TextEncoder();
-	let cancelBody: (reason?: unknown) => void = () => closeSocket(socket, "consumer_cancelled");
+	let resolveReady!: () => void;
+	let rejectReady!: (error: unknown) => void;
+	const ready = new Promise<void>((resolve, reject) => { resolveReady = resolve; rejectReady = reject; });
+	let cancelBody: (reason?: unknown) => void = () => {};
 	const body = new ReadableStream<Uint8Array>({
 		start(controller) {
 			let closed = false;
-			let released = false;
+			let committed = false;
 			let idleTimer: ReturnType<typeof setTimeout> | undefined;
-			let sawTerminal = false;
+			let pending = Promise.resolve();
 			const cleanup = () => {
 				if (idleTimer) clearTimeout(idleTimer);
 				socket.removeEventListener("message", onMessage);
@@ -462,73 +525,75 @@ function createSseResponse(
 				socket.removeEventListener("close", onClose);
 				for (const signal of signals) signal.removeEventListener("abort", onAbort);
 			};
-			const release = (keep: boolean) => {
-				if (released) return;
-				released = true;
-				onRelease(keep);
-			};
-			const finish = () => {
-				if (closed) return;
-				closed = true;
-				cleanup();
-				controller.close();
-			};
 			const fail = (error: unknown) => {
 				if (closed) return;
 				closed = true;
 				cleanup();
-				release(false);
-				closeSocket(socket, "stream_failed");
+				onRelease(false);
+				if (!committed) {
+					if (signals.some((signal) => signal.aborted) || (allowBootstrapFallback && error instanceof RecoverableWebSocketError)) {
+						rejectReady(error);
+					} else {
+						// Return an errored body for deterministic failures/explicit WS.
+						// Rejecting fetch would make the SDK recast these as connection errors.
+						resolveReady();
+					}
+				}
 				controller.error(error);
 			};
 			const armIdleTimer = () => {
 				if (idleTimeoutMs <= 0) return;
 				if (idleTimer) clearTimeout(idleTimer);
-				idleTimer = setTimeout(() => fail(new Error(`WebSocket idle timeout after ${idleTimeoutMs}ms`)), idleTimeoutMs);
-			};
-			const onMessage = (event: WebSocketEvent) => {
-				void (async () => {
-					try {
-						const text = await decodeSocketData(event.data);
-						if (!text) return;
-						const parsed: unknown = JSON.parse(text);
-						if (!isRecord(parsed) || typeof parsed.type !== "string") throw new Error("Invalid Responses WebSocket event");
-						controller.enqueue(encoder.encode(`event: ${parsed.type}\ndata: ${JSON.stringify(parsed)}\n\n`));
-						armIdleTimer();
-						if (TERMINAL_EVENTS.has(parsed.type)) {
-							sawTerminal = true;
-							const keep = onTerminal(parsed);
-							release(keep);
-							finish();
-						}
-					} catch (error) {
-						fail(error);
-					}
-				})();
+				idleTimer = setTimeout(() => fail(transportError(`WebSocket idle timeout after ${idleTimeoutMs}ms`)), idleTimeoutMs);
 			};
-			const onError = (event: WebSocketEvent) => fail(socketError(event));
-			const onClose = (event: WebSocketEvent) => {
-				if (sawTerminal) finish();
-				else fail(new Error(`WebSocket closed before response completion${event.reason ? `: ${event.reason}` : ""}`));
+			const enqueue = (operation: () => Promise<void> | void) => {
+				pending = pending.then(() => { if (!closed) return operation(); }).catch(fail);
 			};
+			const onMessage = (event: WebSocketEvent) => enqueue(async () => {
+				const text = await decodeSocketData(event.data);
+				if (closed) return;
+				if (text === undefined) throw new Error("Invalid Responses WebSocket frame");
+				const parsed: unknown = JSON.parse(text);
+				if (!isRecord(parsed) || typeof parsed.type !== "string" || !parsed.type) throw new Error("Invalid Responses WebSocket event");
+				const normalized = normalizeStreamInterruption(parsed);
+				if (!committed && allowBootstrapFallback && normalized) {
+					fail(transportError("stream closed before response.completed"));
+					return;
+				}
+				const forwarded = normalized ?? parsed;
+				controller.enqueue(encoder.encode(`event: ${forwarded.type}\ndata: ${JSON.stringify(forwarded)}\n\n`));
+				committed = true;
+				resolveReady();
+				armIdleTimer();
+				if (TERMINAL_EVENTS.has(parsed.type)) {
+					closed = true;
+					cleanup();
+					const keep = onTerminal(parsed);
+					onRelease(keep);
+					controller.close();
+				}
+			});
+			const onError = (event: WebSocketEvent) => enqueue(() => fail(socketError(event)));
+			const onClose = (event: WebSocketEvent) => enqueue(() => fail(socketCloseError(event, true)));
+			// Abort/timeout deliberately bypass decoding: a stuck decoder must not
+			// prevent cancellation. Its late result sees closed and is discarded.
 			const onAbort = () => fail(new Error("Request was aborted"));
-
 			cancelBody = (reason) => fail(reason instanceof Error ? reason : new Error("Response stream was cancelled"));
 			socket.addEventListener("message", onMessage);
 			socket.addEventListener("error", onError);
 			socket.addEventListener("close", onClose);
 			for (const signal of signals) signal.addEventListener("abort", onAbort, { once: true });
+			if (signals.some((signal) => signal.aborted)) { onAbort(); return; }
 			armIdleTimer();
 			try {
 				socket.send(requestFrame);
 			} catch (error) {
-				fail(error);
+				fail(transportError(error));
 			}
 		},
-		cancel(reason) {
-			cancelBody(reason);
-		},
+		cancel(reason) { cancelBody(reason); },
 	});
+	await ready;
 	return new Response(body, {
 		status: 200,
 		headers: { "content-type": "text/event-stream", connection: "keep-alive" },
@@ -573,12 +638,12 @@ export function createResponsesWebSocketFetch(model: Model<Api>, options: Stream
 		}
 		if (!isRecord(payload)) return fallback(input, init);
 
-		const signals = liveSignals(options, init);
+		const signals = liveSignals(options, input, init);
 		const requestId = options.sessionId?.slice(0, 64) || crypto.randomUUID();
 		const fetchHeaders = requestHeaders(input, init);
 		const headers = buildWebSocketHeaders(model, options, fetchHeaders, requestId);
 		const cacheKey = shouldCacheSocket(options) ? buildCacheKey(model, options, fetchHeaders) : undefined;
-		let acquired: AcquiredSocket | undefined;
+		let release: ((keep: boolean) => void) | undefined;
 		try {
 			const lease = await acquireWebSocket(
 				buildResponsesWebSocketUrl(model),
@@ -588,21 +653,27 @@ export function createResponsesWebSocketFetch(model: Model<Api>, options: Stream
 				cacheKey,
 				options.sessionId,
 			);
-			acquired = lease;
+			let released = false;
+			release = (keep) => {
+				if (released) return;
+				released = true;
+				lease.release(keep);
+			};
 			const fullPayload = payload;
 			const requestPayload = lease.entry ? buildCachedRequestBody(lease.entry, fullPayload) : fullPayload;
 			const requestFrame = JSON.stringify({ type: "response.create", ...requestPayload });
-			return createSseResponse(
+			return await createSseResponse(
 				lease.socket,
 				signals,
 				options.timeoutMs ?? 0,
 				requestFrame,
 				(event) => completedContinuation(lease.entry, fullPayload, event),
-				(keep) => lease.release(keep),
+				release,
+				transportMode(options) === "auto",
 			);
 		} catch (error) {
-			acquired?.release(false);
-			if (transportMode(options) === "auto" && !signals.some((signal) => signal.aborted)) {
+			release?.(false);
+			if (error instanceof RecoverableWebSocketError && transportMode(options) === "auto" && !signals.some((signal) => signal.aborted)) {
 				return fallback(input, init);
 			}
 			throw error;