pi-openai-toolkit 0.20.0 → 0.20.2

package/src/responses-websocket/transport.ts

@@ -1,40 +1,26 @@
-import {
-	clampThinkingLevel,
-	createAssistantMessageEventStream,
-	type Api,
-	type AssistantMessage,
-	type AssistantMessageEventStream,
-	type Model,
-	type StreamOptions,
-	type TranscriptContext,
+import type {
+	Api,
+	FetchFunction,
+	Model,
+	SimpleStreamOptions,
+	StreamOptions,
 } from "@earendil-works/pi-ai";
-import { buildBaseOptions } from "@earendil-works/pi-ai/api/simple-options";
-import { clampOpenAIPromptCacheKey } from "@earendil-works/pi-ai/api/openai-prompt-cache";
-import {
-	convertResponsesMessages,
-	convertResponsesTools,
-	processResponsesStream,
-} from "@earendil-works/pi-ai/api/openai-responses-shared";
-import { createGrammarToolInputProperties } from "@earendil-works/pi-ai/api/constrained-sampling";
-import { formatProviderError, normalizeProviderError } from "@earendil-works/pi-ai/utils/error-body";
-import {
-	getDeclaredTools,
-	resolveTranscript,
-	resolveTranscriptTools,
-} from "@earendil-works/pi-ai/utils/transcript";
 import type { ApiProvider } from "@earendil-works/pi-ai/compat";
-import type { ResponseCreateParamsStreaming } from "openai/resources/responses/responses.js";
 
-const OPENAI_TOOL_CALL_PROVIDERS = new Set(["openai", "openai-codex", "opencode"]);
-const OPENAI_RESPONSES_MIN_OUTPUT_TOKENS = 16;
 const RESPONSES_WEBSOCKET_BETA = "responses_websockets=2026-02-06";
 const WEBSOCKET_OPEN = 1;
 const WEBSOCKET_CONNECTING = 0;
+const CACHE_IDLE_TTL_MS = 5 * 60 * 1000;
+const CACHE_MAX_AGE_MS = 55 * 60 * 1000;
+const TERMINAL_EVENTS = new Set([
+	"response.completed",
+	"response.done",
+	"response.incomplete",
+	"response.failed",
+	"error",
+]);
 
-type ResponsesEvent = Parameters<typeof processResponsesStream>[0] extends AsyncIterable<infer Event> ? Event : never;
 type ResponsesPayload = Record<string, unknown>;
-type HeaderInput = Record<string, string | null> | undefined;
-
 type WebSocketEvent = {
 	data?: unknown;
 	message?: string;
@@ -42,7 +28,6 @@ type WebSocketEvent = {
 	code?: number;
 	reason?: string;
 };
-
 type WebSocketLike = {
 	readyState: number;
 	send(data: string): void;
@@ -50,65 +35,28 @@ type WebSocketLike = {
 	addEventListener(type: string, listener: (event: WebSocketEvent) => void): void;
 	removeEventListener(type: string, listener: (event: WebSocketEvent) => void): void;
 };
-
 type WebSocketConstructor = new (url: string, options?: { headers?: Record<string, string> }) => WebSocketLike;
-
-type ResponsesStreamOptions = StreamOptions & {
-	reasoningEffort?: "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
-	reasoningSummary?: "auto" | "detailed" | "concise" | null;
-	serviceTier?: ResponseCreateParamsStreaming["service_tier"];
-	toolChoice?: unknown;
+type CachedContinuation = {
+	lastRequestBody: ResponsesPayload;
+	lastResponseId: string;
+	lastResponseItems: unknown[];
+};
+type CachedSocketEntry = {
+	key: string;
+	sessionId: string;
+	socket: WebSocketLike;
+	busy: boolean;
+	createdAt: number;
+	idleTimer?: ReturnType<typeof setTimeout>;
+	continuation?: CachedContinuation;
+};
+type AcquiredSocket = {
+	socket: WebSocketLike;
+	entry?: CachedSocketEntry;
+	release(keep: boolean): void;
 };
 
-type TransportMode = "auto" | "sse" | "websocket" | "websocket-cached";
-
-class AsyncEventQueue<T> implements AsyncIterable<T> {
-	private readonly items: T[] = [];
-	private readonly waiters: Array<{
-		resolve: (result: IteratorResult<T>) => void;
-		reject: (error: unknown) => void;
-	}> = [];
-	private closed = false;
-	private failure: unknown;
-
-	push(item: T): void {
-		if (this.closed) return;
-		const waiter = this.waiters.shift();
-		if (waiter) {
-			waiter.resolve({ value: item, done: false });
-			return;
-		}
-		this.items.push(item);
-	}
-
-	fail(error: unknown): void {
-		if (this.closed) return;
-		this.failure = error;
-		this.closed = true;
-		while (this.waiters.length > 0) this.waiters.shift()!.reject(error);
-	}
-
-	close(): void {
-		if (this.closed) return;
-		this.closed = true;
-		while (this.waiters.length > 0) {
-			this.waiters.shift()!.resolve({ value: undefined, done: true });
-		}
-	}
-
-	next(): Promise<IteratorResult<T>> {
-		if (this.items.length > 0) {
-			return Promise.resolve({ value: this.items.shift()!, done: false });
-		}
-		if (this.failure !== undefined) return Promise.reject(this.failure);
-		if (this.closed) return Promise.resolve({ value: undefined, done: true });
-		return new Promise((resolve, reject) => this.waiters.push({ resolve, reject }));
-	}
-
-	[Symbol.asyncIterator](): AsyncIterator<T> {
-		return this;
-	}
-}
+const cachedSockets = new Map<string, CachedSocketEntry>();
 
 function isRecord(value: unknown): value is Record<string, unknown> {
 	return !!value && typeof value === "object" && !Array.isArray(value);
@@ -118,13 +66,13 @@ function isGptResponsesModel(model: Model<Api>): boolean {
 	return model.api === "openai-responses" && /^gpt/iu.test(model.id);
 }
 
-function transportMode(options: StreamOptions | undefined): TransportMode {
+function transportMode(options: Pick<StreamOptions, "transport"> | undefined): NonNullable<StreamOptions["transport"]> {
 	return options?.transport ?? "auto";
 }
 
 export function shouldUseResponsesWebSocket(
 	model: Model<Api>,
-	options?: StreamOptions,
+	options?: Pick<StreamOptions, "transport">,
 	enabled = false,
 ): boolean {
 	return enabled && isGptResponsesModel(model) && transportMode(options) !== "sse";
@@ -144,11 +92,57 @@ export function buildResponsesWebSocketUrl(model: Model<Api>): string {
 	return url.toString();
 }
 
+function requestUrl(input: RequestInfo | URL): string {
+	if (typeof input === "string") return input;
+	if (input instanceof URL) return input.toString();
+	return input.url;
+}
+
+function requestMethod(input: RequestInfo | URL, init?: RequestInit): string {
+	if (init?.method) return init.method.toUpperCase();
+	if (typeof input !== "string" && !(input instanceof URL) && "method" in input) {
+		return String(input.method || "GET").toUpperCase();
+	}
+	return "GET";
+}
+
+function requestHeaders(input: RequestInfo | URL, init?: RequestInit): Headers {
+	const headers = new Headers();
+	if (typeof input !== "string" && !(input instanceof URL) && "headers" in input) {
+		new Headers(input.headers).forEach((value, name) => headers.set(name, value));
+	}
+	if (init?.headers) {
+		new Headers(init.headers).forEach((value, name) => headers.set(name, value));
+	}
+	return headers;
+}
+
+async function requestBody(input: RequestInfo | URL, init?: RequestInit): Promise<string | undefined> {
+	const body = init?.body as unknown;
+	if (typeof body === "string") return body;
+	if (body instanceof ArrayBuffer) return new TextDecoder().decode(body);
+	if (ArrayBuffer.isView(body)) {
+		return new TextDecoder().decode(new Uint8Array(body.buffer, body.byteOffset, body.byteLength));
+	}
+	if (body && typeof body === "object" && "text" in body && typeof body.text === "function") {
+		return await (body.text as () => Promise<string>)();
+	}
+	if (typeof input !== "string" && !(input instanceof URL) && "clone" in input && typeof input.clone === "function") {
+		return await input.clone().text();
+	}
+	return undefined;
+}
+
 function hasHeader(headers: Headers, name: string): boolean {
-	return headers.has(name) && headers.get(name)!.trim().length > 0;
+	const value = headers.get(name);
+	return value !== null && value.trim().length > 0;
 }
 
-function mergeHeaders(modelHeaders: HeaderInput, optionHeaders: HeaderInput): Headers {
+function mergeHeaders(
+	modelHeaders: Record<string, string> | undefined,
+	optionHeaders: Record<string, string | null> | undefined,
+	requestHeadersFromFetch: Headers,
+): Headers {
 	const headers = new Headers();
 	for (const source of [modelHeaders, optionHeaders]) {
 		for (const [name, value] of Object.entries(source ?? {})) {
@@ -156,154 +150,53 @@ function mergeHeaders(modelHeaders: HeaderInput, optionHeaders: HeaderInput): He
 			else if (typeof value === "string" && value.trim()) headers.set(name, value);
 		}
 	}
+	requestHeadersFromFetch.forEach((value, name) => {
+		if (value.trim()) headers.set(name, value);
+	});
 	return headers;
 }
 
-function buildWebSocketHeaders(model: Model<Api>, options: StreamOptions, requestId: string): Record<string, string> {
-	const headers = mergeHeaders(model.headers, options.headers);
-	if (options.apiKey && !hasHeader(headers, "authorization")) {
+function buildWebSocketHeaders(
+	model: Model<Api>,
+	options: StreamOptions,
+	requestHeadersFromFetch: Headers,
+	requestId: string,
+): Record<string, string> {
+	const headers = mergeHeaders(model.headers, options.headers, requestHeadersFromFetch);
+	if (!hasHeader(headers, "authorization") && options.apiKey?.trim()) {
 		const apiKey = options.apiKey.trim();
 		headers.set("Authorization", apiKey.startsWith("Bearer ") ? apiKey : `Bearer ${apiKey}`);
 	}
 	if (!hasHeader(headers, "authorization") && !hasHeader(headers, "cf-aig-authorization")) {
 		throw new Error(`No API key for provider: ${model.provider}`);
 	}
-
-	// This is the Responses WebSocket capability marker used by Pi's official
-	// Codex transport. It is an API-level header, not a provider-specific value.
 	if (!hasHeader(headers, "openai-beta")) headers.set("OpenAI-Beta", RESPONSES_WEBSOCKET_BETA);
 	if (!hasHeader(headers, "x-client-request-id")) headers.set("X-Client-Request-Id", requestId);
-
 	return Object.fromEntries(headers.entries());
 }
 
-type ResponsesCompat = {
-	supportsMidConvoSystemMessages?: boolean;
-	supportsLongCacheRetention?: boolean;
-	supportsStrictMode?: boolean;
-	supportsOpenAIGrammarTools?: boolean;
-	supportsAdditionalTools?: boolean;
-	supportsToolSearch?: boolean;
-	supportsExplicitPromptCacheMode?: boolean;
-	supportsMaxOutputTokens?: boolean;
-};
-
-function getCompat(model: Model<Api>): Required<ResponsesCompat> {
-	const compat = (model.compat ?? {}) as ResponsesCompat;
-	return {
-		supportsMidConvoSystemMessages: compat.supportsMidConvoSystemMessages ?? false,
-		supportsLongCacheRetention: compat.supportsLongCacheRetention ?? true,
-		supportsStrictMode: compat.supportsStrictMode ?? false,
-		supportsOpenAIGrammarTools: compat.supportsOpenAIGrammarTools ?? false,
-		supportsAdditionalTools: compat.supportsAdditionalTools ?? false,
-		supportsToolSearch: compat.supportsToolSearch ?? false,
-		supportsExplicitPromptCacheMode: compat.supportsExplicitPromptCacheMode ?? false,
-		supportsMaxOutputTokens: compat.supportsMaxOutputTokens ?? true,
-	};
-}
-
-function getPromptCacheOptions(compat: ReturnType<typeof getCompat>, cacheRetention: StreamOptions["cacheRetention"]): Record<string, unknown> | undefined {
-	if (!compat.supportsExplicitPromptCacheMode) return undefined;
-	if (cacheRetention === "none") return { mode: "explicit" };
-	if (cacheRetention === "long" && compat.supportsLongCacheRetention) return { ttl: "30m" };
-	return undefined;
-}
-
-function getPromptCacheRetention(compat: ReturnType<typeof getCompat>, cacheRetention: StreamOptions["cacheRetention"]): string | undefined {
-	return cacheRetention === "long" && compat.supportsLongCacheRetention && !compat.supportsExplicitPromptCacheMode
-		? "24h"
-		: undefined;
-}
-
-function buildResponsesPayload(
-	model: Model<Api>,
-	context: TranscriptContext,
-	options: ResponsesStreamOptions | undefined,
-): ResponsesPayload {
-	const normalizedContext = resolveTranscript(context, getCompat(model).supportsMidConvoSystemMessages);
-	const compat = getCompat(model);
-	const grammarToolInputProperties = createGrammarToolInputProperties(
-		getDeclaredTools(normalizedContext.messages),
-		compat.supportsOpenAIGrammarTools,
-	);
-	const transcriptTools = resolveTranscriptTools(
-		normalizedContext.messages,
-		compat.supportsAdditionalTools || compat.supportsToolSearch,
-	);
-	const cacheRetention = options?.cacheRetention ?? "short";
-	const params: ResponsesPayload = {
-		model: model.id,
-		input: convertResponsesMessages(model, normalizedContext, OPENAI_TOOL_CALL_PROVIDERS, {
-			grammarToolInputProperties,
-			supportsMidConvoSystemMessages: compat.supportsMidConvoSystemMessages,
-			supportsAdditionalTools: compat.supportsAdditionalTools,
-			supportsToolSearch: compat.supportsToolSearch,
-			toolOptions: {
-				supportsStrictMode: compat.supportsStrictMode,
-				supportsOpenAIGrammarTools: compat.supportsOpenAIGrammarTools,
-			},
-		}),
-		stream: true,
-		prompt_cache_key: cacheRetention === "none" ? undefined : clampOpenAIPromptCacheKey(options?.sessionId),
-		prompt_cache_retention: getPromptCacheRetention(compat, cacheRetention),
-		prompt_cache_options: getPromptCacheOptions(compat, cacheRetention),
-		store: false,
-	};
-
-	if (options?.maxTokens !== undefined && compat.supportsMaxOutputTokens) {
-		params.max_output_tokens = Math.max(options.maxTokens, OPENAI_RESPONSES_MIN_OUTPUT_TOKENS);
+function stableHash(value: string): string {
+	let hash = 2166136261;
+	for (let index = 0; index < value.length; index++) {
+		hash ^= value.charCodeAt(index);
+		hash = Math.imul(hash, 16777619);
 	}
-	if (options?.temperature !== undefined) params.temperature = options.temperature;
-	if (options?.serviceTier !== undefined) params.service_tier = options.serviceTier;
-	if (transcriptTools.requestTools.length > 0) {
-		params.tools = convertResponsesTools(transcriptTools.requestTools, {
-			supportsStrictMode: compat.supportsStrictMode,
-			supportsOpenAIGrammarTools: compat.supportsOpenAIGrammarTools,
-		});
-	}
-	if (options?.toolChoice !== undefined) params.tool_choice = options.toolChoice;
-
-	if (model.reasoning) {
-		if (options?.reasoningEffort || options?.reasoningSummary) {
-			const effort = options.reasoningEffort
-				? (model.thinkingLevelMap?.[options.reasoningEffort] ?? options.reasoningEffort)
-				: "medium";
-			params.reasoning = {
-				effort,
-				summary: options.reasoningSummary || "auto",
-			};
-			params.include = ["reasoning.encrypted_content"];
-		} else if (model.thinkingLevelMap?.off !== null) {
-			params.reasoning = { effort: model.thinkingLevelMap?.off ?? "none" };
-		}
-	}
-
-	Object.assign(params, model.samplingParams, options?.samplingParams);
-	return params;
+	return (hash >>> 0).toString(16);
 }
 
-function createAssistantOutput(model: Model<Api>): AssistantMessage {
-	return {
-		role: "assistant",
-		content: [],
-		api: model.api,
-		provider: model.provider,
-		model: model.id,
-		usage: {
-			input: 0,
-			output: 0,
-			cacheRead: 0,
-			cacheWrite: 0,
-			totalTokens: 0,
-			cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
-		},
-		stopReason: "pending",
-		timestamp: Date.now(),
-	};
-}
-
-function thrownMessage(error: unknown): string {
-	return formatProviderError(normalizeProviderError(error), "OpenAI Responses API error");
+function buildCacheKey(model: Model<Api>, options: StreamOptions, requestHeadersFromFetch: Headers): string | undefined {
+	if (!options.sessionId || options.cacheRetention === "none") return undefined;
+	const headers = mergeHeaders(model.headers, options.headers, requestHeadersFromFetch);
+	if (!hasHeader(headers, "authorization") && options.apiKey?.trim()) {
+		const apiKey = options.apiKey.trim();
+		headers.set("authorization", apiKey.startsWith("Bearer ") ? apiKey : `Bearer ${apiKey}`);
+	}
+	// Request ids identify individual calls and must not split one Pi session into
+	// a fresh cache entry on every turn. The remaining headers capture auth and
+	// provider-specific routing that must not be mixed across sockets.
+	headers.delete("x-client-request-id");
+	const identity = [...headers.entries()].sort(([a], [b]) => a.localeCompare(b));
+	return [model.provider, model.id, cleanBaseUrl(model.baseUrl), options.sessionId, stableHash(JSON.stringify(identity))].join("\u0000");
 }
 
 function socketError(event: WebSocketEvent): Error {
@@ -323,27 +216,61 @@ function closeSocket(socket: WebSocketLike | undefined, reason = "done"): void {
 	}
 }
 
+function socketReusable(socket: WebSocketLike): boolean {
+	return socket.readyState === WEBSOCKET_OPEN;
+}
+
+function removeCachedSocket(entry: CachedSocketEntry, reason: string): void {
+	if (entry.idleTimer) clearTimeout(entry.idleTimer);
+	if (cachedSockets.get(entry.key) === entry) cachedSockets.delete(entry.key);
+	closeSocket(entry.socket, reason);
+}
+
+function scheduleCachedSocketExpiry(entry: CachedSocketEntry): void {
+	if (entry.idleTimer) clearTimeout(entry.idleTimer);
+	const remainingAge = CACHE_MAX_AGE_MS - (Date.now() - entry.createdAt);
+	const delay = Math.min(CACHE_IDLE_TTL_MS, remainingAge);
+	if (delay <= 0) {
+		removeCachedSocket(entry, "connection_age_limit");
+		return;
+	}
+	entry.idleTimer = setTimeout(() => {
+		if (!entry.busy) removeCachedSocket(entry, "idle_timeout");
+	}, delay);
+	(entry.idleTimer as unknown as { unref?: () => void }).unref?.();
+}
+
+export function closeResponsesWebSocketSessions(sessionId?: string): void {
+	for (const entry of [...cachedSockets.values()]) {
+		if (sessionId === undefined || entry.sessionId === sessionId) removeCachedSocket(entry, "session_closed");
+	}
+}
+
+
+function liveSignals(options: StreamOptions, init?: RequestInit): AbortSignal[] {
+	return [options.signal, init?.signal].filter((signal): signal is AbortSignal => signal !== undefined);
+}
+
 async function connectWebSocket(
 	url: string,
 	headers: Record<string, string>,
-	signal: AbortSignal | undefined,
+	signals: AbortSignal[],
 	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 (signal?.aborted) throw new Error("Request was aborted");
+	if (signals.some((signal) => signal.aborted)) throw new Error("Request was aborted");
 
 	return new Promise((resolve, reject) => {
-		let socket: WebSocketLike;
+		let socket: WebSocketLike | undefined;
 		let settled = false;
 		let timeout: ReturnType<typeof setTimeout> | undefined;
-
 		const cleanup = () => {
 			if (timeout) clearTimeout(timeout);
 			socket?.removeEventListener("open", onOpen);
 			socket?.removeEventListener("error", onError);
 			socket?.removeEventListener("close", onClose);
-			signal?.removeEventListener("abort", onAbort);
+			for (const signal of signals) signal.removeEventListener("abort", onAbort);
 		};
 		const fail = (error: Error) => {
 			if (settled) return;
@@ -356,7 +283,7 @@ async function connectWebSocket(
 			if (settled) return;
 			settled = true;
 			cleanup();
-			resolve(socket);
+			resolve(socket!);
 		};
 		const onError = (event: WebSocketEvent) => fail(socketError(event));
 		const onClose = (event: WebSocketEvent) => fail(new Error(
@@ -373,7 +300,7 @@ async function connectWebSocket(
 		socket.addEventListener("open", onOpen);
 		socket.addEventListener("error", onError);
 		socket.addEventListener("close", onClose);
-		signal?.addEventListener("abort", onAbort, { once: true });
+		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);
 	});
 }
@@ -381,9 +308,7 @@ async function connectWebSocket(
 async function decodeSocketData(value: unknown): Promise<string | undefined> {
 	if (typeof value === "string") return value;
 	if (value instanceof ArrayBuffer) return new TextDecoder().decode(new Uint8Array(value));
-	if (ArrayBuffer.isView(value)) {
-		return new TextDecoder().decode(new Uint8Array(value.buffer, value.byteOffset, value.byteLength));
-	}
+	if (ArrayBuffer.isView(value)) return new TextDecoder().decode(new Uint8Array(value.buffer, value.byteOffset, value.byteLength));
 	if (isRecord(value) && typeof value.arrayBuffer === "function") {
 		const bytes = await (value.arrayBuffer as () => Promise<ArrayBuffer>)();
 		return new TextDecoder().decode(new Uint8Array(bytes));
@@ -391,165 +316,306 @@ async function decodeSocketData(value: unknown): Promise<string | undefined> {
 	return undefined;
 }
 
-async function* readSocketEvents(
-	socket: WebSocketLike,
-	signal: AbortSignal | undefined,
-	timeoutMs: number,
-): AsyncIterable<ResponsesEvent> {
-	const queue = new AsyncEventQueue<ResponsesEvent>();
-	let sawTerminal = false;
-	let idleTimer: ReturnType<typeof setTimeout> | undefined;
-	const armIdleTimer = () => {
-		if (timeoutMs <= 0) return;
-		if (idleTimer) clearTimeout(idleTimer);
-		idleTimer = setTimeout(() => queue.fail(new Error(`WebSocket idle timeout after ${timeoutMs}ms`)), timeoutMs);
+async function acquireWebSocket(
+	url: string,
+	headers: Record<string, string>,
+	signals: AbortSignal[],
+	connectTimeoutMs: number,
+	cacheKey: string | undefined,
+	sessionId: string | undefined,
+): Promise<AcquiredSocket> {
+	if (cacheKey) {
+		const cached = cachedSockets.get(cacheKey);
+		if (cached) {
+			if (!socketReusable(cached.socket) || Date.now() - cached.createdAt >= CACHE_MAX_AGE_MS) {
+				removeCachedSocket(cached, "cache_expired");
+			} else if (!cached.busy) {
+				if (cached.idleTimer) clearTimeout(cached.idleTimer);
+				cached.idleTimer = undefined;
+				cached.busy = true;
+				return {
+					socket: cached.socket,
+					entry: cached,
+					release(keep) {
+						if (keep && socketReusable(cached.socket) && Date.now() - cached.createdAt < CACHE_MAX_AGE_MS) {
+							cached.busy = false;
+							scheduleCachedSocketExpiry(cached);
+						} else {
+							removeCachedSocket(cached, "request_finished");
+						}
+					},
+				};
+			}
+		}
+	}
+
+	const socket = await connectWebSocket(url, headers, signals, connectTimeoutMs);
+	if (!cacheKey || !sessionId || cachedSockets.has(cacheKey)) {
+		return { socket, release: () => closeSocket(socket, "request_finished") };
+	}
+	const entry: CachedSocketEntry = { key: cacheKey, sessionId, socket, busy: true, createdAt: Date.now() };
+	cachedSockets.set(cacheKey, entry);
+	return {
+		socket,
+		entry,
+		release(keep) {
+			if (keep && socketReusable(entry.socket) && Date.now() - entry.createdAt < CACHE_MAX_AGE_MS) {
+				entry.busy = false;
+				scheduleCachedSocketExpiry(entry);
+			} else {
+				removeCachedSocket(entry, "request_finished");
+			}
+		},
 	};
-	const onMessage = (event: WebSocketEvent) => {
-		void (async () => {
+}
+
+function cloneJson<T>(value: T): T {
+	return JSON.parse(JSON.stringify(value)) as T;
+}
+
+function responseInputsEqual(a: unknown, b: unknown): boolean {
+	if (Object.is(a, b)) return true;
+	if (Array.isArray(a) || Array.isArray(b)) {
+		return Array.isArray(a) && Array.isArray(b) && a.length === b.length && a.every((value, index) => responseInputsEqual(value, b[index]));
+	}
+	if (isRecord(a) || isRecord(b)) {
+		if (!isRecord(a) || !isRecord(b)) return false;
+		const aKeys = Object.keys(a).sort();
+		const bKeys = Object.keys(b).sort();
+		return aKeys.length === bKeys.length && aKeys.every((key, index) => key === bKeys[index] && responseInputsEqual(a[key], b[key]));
+	}
+	return false;
+}
+
+function requestBodyWithoutInput(body: ResponsesPayload): ResponsesPayload {
+	const { input: _input, previous_response_id: _previousResponseId, ...rest } = body;
+	return rest;
+}
+
+function requestBodiesMatchExceptInput(a: ResponsesPayload, b: ResponsesPayload): boolean {
+	return responseInputsEqual(requestBodyWithoutInput(a), requestBodyWithoutInput(b));
+}
+
+function inputItems(body: ResponsesPayload): unknown[] {
+	return Array.isArray(body.input) ? body.input : [];
+}
+
+function buildCachedRequestBody(entry: CachedSocketEntry, body: ResponsesPayload): ResponsesPayload {
+	const continuation = entry.continuation;
+	if (!continuation) return body;
+	if (!requestBodiesMatchExceptInput(body, continuation.lastRequestBody)) {
+		entry.continuation = undefined;
+		return body;
+	}
+	const currentInput = inputItems(body);
+	const baseline = [...inputItems(continuation.lastRequestBody), ...continuation.lastResponseItems];
+	if (currentInput.length < baseline.length || !responseInputsEqual(currentInput.slice(0, baseline.length), baseline)) {
+		entry.continuation = undefined;
+		return body;
+	}
+	return {
+		...body,
+		previous_response_id: continuation.lastResponseId,
+		input: currentInput.slice(baseline.length),
+	};
+}
+
+function completedContinuation(entry: CachedSocketEntry | undefined, fullPayload: ResponsesPayload, event: Record<string, unknown>): boolean {
+	if (!entry || (event.type !== "response.completed" && event.type !== "response.done")) return false;
+	const response = isRecord(event.response) ? event.response : undefined;
+	const responseId = typeof response?.id === "string" ? response.id : undefined;
+	if (!responseId) {
+		entry.continuation = undefined;
+		return true;
+	}
+	const output = Array.isArray(response?.output)
+		? response.output.filter((item): item is Record<string, unknown> => isRecord(item) && item.type !== "function_call_output" && item.type !== "custom_tool_call_output")
+		: [];
+	entry.continuation = {
+		lastRequestBody: cloneJson(fullPayload),
+		lastResponseId: responseId,
+		lastResponseItems: cloneJson(output),
+	};
+	return true;
+}
+
+function createSseResponse(
+	socket: WebSocketLike,
+	signals: AbortSignal[],
+	idleTimeoutMs: number,
+	requestFrame: string,
+	onTerminal: (event: Record<string, unknown>) => boolean,
+	onRelease: (keep: boolean) => void,
+): Response {
+	const encoder = new TextEncoder();
+	let cancelBody: (reason?: unknown) => void = () => closeSocket(socket, "consumer_cancelled");
+	const body = new ReadableStream<Uint8Array>({
+		start(controller) {
+			let closed = false;
+			let released = false;
+			let idleTimer: ReturnType<typeof setTimeout> | undefined;
+			let sawTerminal = false;
+			const cleanup = () => {
+				if (idleTimer) clearTimeout(idleTimer);
+				socket.removeEventListener("message", onMessage);
+				socket.removeEventListener("error", onError);
+				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");
+				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);
+					}
+				})();
+			};
+			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 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 });
+			armIdleTimer();
 			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");
-				const responseEvent = parsed as unknown as ResponsesEvent;
-				armIdleTimer();
-				queue.push(responseEvent);
-				if (["response.completed", "response.done", "response.incomplete", "response.failed", "error"].includes(parsed.type)) {
-					sawTerminal = true;
-					queue.close();
-				}
+				socket.send(requestFrame);
 			} catch (error) {
-				queue.fail(error);
+				fail(error);
 			}
-		})();
-	};
-	const onError = (event: WebSocketEvent) => queue.fail(socketError(event));
-	const onClose = (event: WebSocketEvent) => {
-		if (sawTerminal) queue.close();
-		else queue.fail(new Error(`WebSocket closed before response completion${event.reason ? `: ${event.reason}` : ""}`));
-	};
-	const onAbort = () => queue.fail(new Error("Request was aborted"));
+		},
+		cancel(reason) {
+			cancelBody(reason);
+		},
+	});
+	return new Response(body, {
+		status: 200,
+		headers: { "content-type": "text/event-stream", connection: "keep-alive" },
+	});
+}
 
-	socket.addEventListener("message", onMessage);
-	socket.addEventListener("error", onError);
-	socket.addEventListener("close", onClose);
-	signal?.addEventListener("abort", onAbort, { once: true });
-	armIdleTimer();
+function isResponsesPost(input: RequestInfo | URL, init?: RequestInit): boolean {
+	if (requestMethod(input, init) !== "POST") return false;
 	try {
-		for await (const event of queue) {
-			yield event;
-		}
-	} finally {
-		socket.removeEventListener("message", onMessage);
-		socket.removeEventListener("error", onError);
-		socket.removeEventListener("close", onClose);
-		signal?.removeEventListener("abort", onAbort);
-		if (idleTimer) clearTimeout(idleTimer);
+		return new URL(requestUrl(input)).pathname.replace(/\/+$/u, "").endsWith("/responses");
+	} catch {
+		return false;
 	}
 }
 
-function assertSuccessfulOutput(
-	output: AssistantMessage,
-): asserts output is AssistantMessage & { stopReason: "stop" | "length" | "toolUse" | "deferred" } {
-	if (output.stopReason === "pending") throw new Error("Responses WebSocket stream ended without a stop reason");
-	if (output.stopReason === "error" || output.stopReason === "aborted") {
-		throw new Error(output.errorMessage || "Responses WebSocket response failed");
-	}
+function shouldCacheSocket(options: StreamOptions): boolean {
+	return Boolean(options.sessionId && options.cacheRetention !== "none" && (transportMode(options) === "auto" || transportMode(options) === "websocket-cached"));
 }
 
-async function pipeFallback(
-	original: ApiProvider,
-	model: Model<Api>,
-	context: TranscriptContext,
-	options: ResponsesStreamOptions | undefined,
-	payload: ResponsesPayload | undefined,
-	stream: AssistantMessageEventStream,
-): Promise<void> {
-	const fallbackOptions = payload
-		? { ...options, onPayload: () => payload }
-		: options;
-	const fallback = original.stream(model, context, fallbackOptions);
-	for await (const event of fallback) stream.push(event);
-	stream.end();
-}
-
-async function runResponsesWebSocket(
-	original: ApiProvider,
-	model: Model<Api>,
-	context: TranscriptContext,
-	options: ResponsesStreamOptions | undefined,
-	stream: AssistantMessageEventStream,
-): Promise<void> {
-	const output = createAssistantOutput(model);
-	let socket: WebSocketLike | undefined;
-	let streamStarted = false;
-	let payload: ResponsesPayload | undefined;
-	try {
-		if (options?.signal?.aborted) throw new Error("Request was aborted");
-		payload = buildResponsesPayload(model, context, options);
-		const replaced = await options?.onPayload?.(payload, model);
-		if (replaced !== undefined) {
-			if (!isRecord(replaced)) throw new Error("OpenAI Responses payload must be an object");
-			payload = replaced;
+/**
+ * Adapt the Responses WebSocket frame protocol to the HTTP/SSE surface already
+ * consumed by Pi's stock openai-responses adapter. Payload conversion, tool
+ * handling, usage accounting, and event normalization therefore stay in Pi.
+ *
+ * With a stable Pi sessionId, auto/websocket-cached keep one connection alive
+ * for subsequent turns. After a completed response, the next request sends
+ * previous_response_id plus only the input items after the cached response;
+ * it falls back to the full payload when the transcript cannot be matched.
+ */
+export function createResponsesWebSocketFetch(model: Model<Api>, options: StreamOptions): FetchFunction {
+	const fallback = options.fetch ?? globalThis.fetch;
+	if (typeof fallback !== "function") throw new Error("HTTP fetch is not available in this runtime");
+	return async (input, init) => {
+		if (!isResponsesPost(input, init) || transportMode(options) === "sse") return fallback(input, init);
+		const bodyText = await requestBody(input, init);
+		if (!bodyText) return fallback(input, init);
+		let payload: unknown;
+		try {
+			payload = JSON.parse(bodyText);
+		} catch {
+			return fallback(input, init);
 		}
-		const requestId = options?.sessionId?.slice(0, 64) || crypto.randomUUID();
-		const headers = buildWebSocketHeaders(model, options ?? {}, requestId);
-		socket = await connectWebSocket(
-			buildResponsesWebSocketUrl(model),
-			headers,
-			options?.signal,
-			options?.websocketConnectTimeoutMs ?? 15_000,
-		);
-		await options?.onResponse?.({ status: 101, headers: {} }, model);
-		streamStarted = true;
-		stream.push({ type: "start", partial: output });
-		socket.send(JSON.stringify({ type: "response.create", ...payload }));
-		const compat = getCompat(model);
-		const grammarToolInputProperties = createGrammarToolInputProperties(
-			getDeclaredTools(resolveTranscript(context, compat.supportsMidConvoSystemMessages).messages),
-			compat.supportsOpenAIGrammarTools,
-		);
-		await processResponsesStream(readSocketEvents(socket, options?.signal, options?.timeoutMs ?? 0), output, stream, model, {
-			onProviderStreamEvent: options?.onProviderStreamEvent,
-			serviceTier: options?.serviceTier,
-			grammarToolInputProperties,
-		});
-		if (options?.signal?.aborted) throw new Error("Request was aborted");
-		assertSuccessfulOutput(output);
-		stream.push({ type: "done", reason: output.stopReason, message: output });
-		stream.end();
-	} catch (error) {
-		if (!streamStarted && transportMode(options) === "auto" && !options?.signal?.aborted) {
-			try {
-				await pipeFallback(original, model, context, options, payload, stream);
-				return;
-			} catch (fallbackError) {
-				error = fallbackError;
+		if (!isRecord(payload)) return fallback(input, init);
+
+		const signals = liveSignals(options, 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;
+		try {
+			const lease = await acquireWebSocket(
+				buildResponsesWebSocketUrl(model),
+				headers,
+				signals,
+				options.websocketConnectTimeoutMs ?? 15_000,
+				cacheKey,
+				options.sessionId,
+			);
+			acquired = lease;
+			const fullPayload = payload;
+			const requestPayload = lease.entry ? buildCachedRequestBody(lease.entry, fullPayload) : fullPayload;
+			const requestFrame = JSON.stringify({ type: "response.create", ...requestPayload });
+			return createSseResponse(
+				lease.socket,
+				signals,
+				options.timeoutMs ?? 0,
+				requestFrame,
+				(event) => completedContinuation(lease.entry, fullPayload, event),
+				(keep) => lease.release(keep),
+			);
+		} catch (error) {
+			acquired?.release(false);
+			if (transportMode(options) === "auto" && !signals.some((signal) => signal.aborted)) {
+				return fallback(input, init);
 			}
+			throw error;
 		}
-		for (const block of output.content) {
-			const scratch = block as unknown as { partialJson?: unknown; customInput?: unknown };
-			delete scratch.partialJson;
-			delete scratch.customInput;
-		}
-		output.stopReason = options?.signal?.aborted ? "aborted" : "error";
-		output.errorMessage = thrownMessage(error);
-		stream.push({ type: "error", reason: output.stopReason, error: output });
-		stream.end();
-	} finally {
-		closeSocket(socket, "done");
-	}
+	};
 }
 
-export function streamResponsesWebSocket(
-	original: ApiProvider,
-	model: Model<Api>,
-	context: TranscriptContext,
-	options?: StreamOptions,
-): AssistantMessageEventStream {
-	const stream = createAssistantMessageEventStream();
-	void runResponsesWebSocket(original, model, context, options as ResponsesStreamOptions | undefined, stream);
-	return stream;
+function withWebSocketFetch<T extends StreamOptions>(model: Model<Api>, options?: T): T {
+	const effective = options ?? ({} as T);
+	return {
+		...effective,
+		fetch: createResponsesWebSocketFetch(model, effective),
+	};
 }
 
 export function createResponsesWebSocketProvider(original: ApiProvider, enabled = false): ApiProvider {
@@ -557,21 +623,11 @@ export function createResponsesWebSocketProvider(original: ApiProvider, enabled
 		api: "openai-responses",
 		stream(model, context, options) {
 			if (!shouldUseResponsesWebSocket(model, options, enabled)) return original.stream(model, context, options);
-			return streamResponsesWebSocket(original, model, context, options);
+			return original.stream(model, context, withWebSocketFetch(model, options));
 		},
 		streamSimple(model, context, options) {
 			if (!shouldUseResponsesWebSocket(model, options, enabled)) return original.streamSimple(model, context, options);
-			const apiKey = options?.apiKey;
-			const base = {
-				...buildBaseOptions(model, context, options, apiKey),
-				toolChoice: options?.toolChoice,
-			};
-			const clampedReasoning = options?.reasoning ? clampThinkingLevel(model, options.reasoning) : undefined;
-			const reasoningEffort = clampedReasoning === "off" ? undefined : clampedReasoning;
-			return streamResponsesWebSocket(original, model, context, {
-				...base,
-				reasoningEffort,
-			} as ResponsesStreamOptions);
+			return original.streamSimple(model, context, withWebSocketFetch(model, options));
 		},
 	};
 }