feat: WebSocket transport + previous_response_id for multi-turn (#84)

* feat: WebSocket transport + previous_response_id for multi-turn (#83)

The Codex backend only supports `previous_response_id` over WebSocket,
not HTTP SSE. This adds a dual-track transport layer:

- /v1/responses now connects to the backend via WebSocket by default
- WebSocket omits the `store` field, letting the server persist responses
- Clients can send `previous_response_id` to reference earlier turns
- On WebSocket failure, automatically falls back to HTTP SSE

New files:
- src/proxy/ws-transport.ts — WebSocket-to-SSE bridge (ReadableStream)

Dependencies: ws, https-proxy-agent

* fix: move ws from devDependencies to dependencies

ws is imported at runtime by src/proxy/ws-transport.ts, so it must be
in dependencies for production installs (npm install --omit=dev).

---------

Co-authored-by: icebear0828 <icebear0828@users.noreply.github.com>

CHANGELOG.md

@@ -16,6 +16,7 @@
 
 - 模型列表自动同步：后端动态 fetch 成功后自动回写 `config/models.yaml`，静态配置不再滞后；前端每 60s 轮询模型列表，新模型无需刷新页面即可选择
 - Tuple Schema 支持：`prefixItems`（JSON Schema 2020-12 tuple）自动转换为等价 object schema 发给上游，响应侧还原为数组；OpenAI / Gemini / Responses 三端点统一支持
+- WebSocket 传输 + `previous_response_id` 多轮支持：`/v1/responses` 端点自动通过 WebSocket 连接上游，服务端持久化 response，客户端可通过 `previous_response_id` 引用前轮对话实现增量多轮；WebSocket 失败自动降级回 HTTP SSE (#83)
 
 ### Fixed
 

package-lock.json

@@ -1,24 +1,27 @@
 {
   "name": "codex-proxy",
-  "version": "1.0.45",
+  "version": "1.0.50",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "codex-proxy",
-      "version": "1.0.45",
+      "version": "1.0.50",
       "hasInstallScript": true,
       "dependencies": {
         "@hono/node-server": "^1.0.0",
         "hono": "^4.0.0",
+        "https-proxy-agent": "^8.0.0",
         "js-yaml": "^4.1.0",
         "undici": "^7.0.0",
+        "ws": "^8.19.0",
         "zod": "^3.23.0"
       },
       "devDependencies": {
         "@electron/asar": "^3.2.0",
         "@types/js-yaml": "^4.0.0",
         "@types/node": "^22.0.0",
+        "@types/ws": "^8.18.1",
         "@vitest/coverage-v8": "^3.2.4",
         "electron-to-chromium": "^1.5.302",
         "js-beautify": "^1.15.0",
@@ -1053,6 +1056,16 @@
         "undici-types": "~6.21.0"
       }
     },
+    "node_modules/@types/ws": {
+      "version": "8.18.1",
+      "resolved": "https://registry.npmjs.org/@types/ws/-/ws-8.18.1.tgz",
+      "integrity": "sha512-ThVF6DCVhA8kUGy+aazFQ4kXQ7E1Ty7A3ypFOe0IcJV8O/M511G99AW24irKrW56Wt44yG9+ij8FaqoBGkuBXg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/node": "*"
+      }
+    },
     "node_modules/@vitest/coverage-v8": {
       "version": "3.2.4",
       "resolved": "https://registry.npmmirror.com/@vitest/coverage-v8/-/coverage-v8-3.2.4.tgz",
@@ -1212,6 +1225,15 @@
         "node": "^14.17.0 || ^16.13.0 || >=18.0.0"
       }
     },
+    "node_modules/agent-base": {
+      "version": "8.0.0",
+      "resolved": "https://registry.npmjs.org/agent-base/-/agent-base-8.0.0.tgz",
+      "integrity": "sha512-QT8i0hCz6C/KQ+KTAbSNwCHDGdmUJl2tp2ZpNlGSWCfhUNVbYG2WLE3MdZGBAgXPV4GAvjGMxo+C1hroyxmZEg==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 14"
+      }
+    },
     "node_modules/ansi-regex": {
       "version": "6.2.2",
       "resolved": "https://registry.npmmirror.com/ansi-regex/-/ansi-regex-6.2.2.tgz",
@@ -1395,7 +1417,6 @@
       "version": "4.4.3",
       "resolved": "https://registry.npmmirror.com/debug/-/debug-4.4.3.tgz",
       "integrity": "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==",
-      "dev": true,
       "license": "MIT",
       "dependencies": {
         "ms": "^2.1.3"
@@ -1682,6 +1703,19 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/https-proxy-agent": {
+      "version": "8.0.0",
+      "resolved": "https://registry.npmjs.org/https-proxy-agent/-/https-proxy-agent-8.0.0.tgz",
+      "integrity": "sha512-YYeW+iCnAS3xhvj2dvVoWgsbca3RfQy/IlaNHHOtDmU0jMqPI9euIq3Y9BJETdxk16h9NHHCKqp/KB9nIMStCQ==",
+      "license": "MIT",
+      "dependencies": {
+        "agent-base": "8.0.0",
+        "debug": "^4.3.4"
+      },
+      "engines": {
+        "node": ">= 14"
+      }
+    },
     "node_modules/inflight": {
       "version": "1.0.6",
       "resolved": "https://registry.npmmirror.com/inflight/-/inflight-1.0.6.tgz",
@@ -1983,7 +2017,6 @@
       "version": "2.1.3",
       "resolved": "https://registry.npmmirror.com/ms/-/ms-2.1.3.tgz",
       "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==",
-      "dev": true,
       "license": "MIT"
     },
     "node_modules/nanoid": {
@@ -2941,6 +2974,27 @@
       "dev": true,
       "license": "ISC"
     },
+    "node_modules/ws": {
+      "version": "8.19.0",
+      "resolved": "https://registry.npmjs.org/ws/-/ws-8.19.0.tgz",
+      "integrity": "sha512-blAT2mjOEIi0ZzruJfIhb3nps74PRWTCz1IjglWEEpQl5XS/UNama6u2/rjFkDDouqr4L67ry+1aGIALViWjDg==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=10.0.0"
+      },
+      "peerDependencies": {
+        "bufferutil": "^4.0.1",
+        "utf-8-validate": ">=5.0.2"
+      },
+      "peerDependenciesMeta": {
+        "bufferutil": {
+          "optional": true
+        },
+        "utf-8-validate": {
+          "optional": true
+        }
+      }
+    },
     "node_modules/zod": {
       "version": "3.25.76",
       "resolved": "https://registry.npmmirror.com/zod/-/zod-3.25.76.tgz",

package.json

@@ -23,8 +23,10 @@
   "dependencies": {
     "@hono/node-server": "^1.0.0",
     "hono": "^4.0.0",
+    "https-proxy-agent": "^8.0.0",
     "js-yaml": "^4.1.0",
     "undici": "^7.0.0",
+    "ws": "^8.19.0",
     "zod": "^3.23.0"
   },
   "optionalDependencies": {
@@ -34,6 +36,7 @@
     "@electron/asar": "^3.2.0",
     "@types/js-yaml": "^4.0.0",
     "@types/node": "^22.0.0",
+    "@types/ws": "^8.18.1",
     "@vitest/coverage-v8": "^3.2.4",
     "electron-to-chromium": "^1.5.302",
     "js-beautify": "^1.15.0",

src/proxy/codex-api.ts

@@ -15,6 +15,7 @@ import {
   buildHeaders,
   buildHeadersWithContentType,
 } from "../fingerprint/manager.js";
+import { createWebSocketResponse, type WsCreateRequest } from "./ws-transport.js";
 import type { CookieJar } from "./cookie-jar.js";
 import type { BackendModelEntry } from "../models/model-store.js";
 
@@ -43,6 +44,10 @@ export interface CodexResponsesRequest {
       strict?: boolean;
     };
   };
+  /** Optional: reference a previous response for multi-turn (WebSocket only). */
+  previous_response_id?: string;
+  /** When true, use WebSocket transport (enables previous_response_id and server-side storage). */
+  useWebSocket?: boolean;
 }
 
 /** Structured content part for multimodal Codex input. */
@@ -244,11 +249,71 @@ export class CodexApi {
 
   /**
    * Create a response (streaming).
-   * Returns the raw Response so the caller can process the SSE stream.
+   * Routes to WebSocket when previous_response_id is present (HTTP SSE doesn't support it).
+   * Falls back to HTTP SSE if WebSocket fails.
    */
   async createResponse(
     request: CodexResponsesRequest,
     signal?: AbortSignal,
+  ): Promise<Response> {
+    if (request.useWebSocket) {
+      try {
+        return await this.createResponseViaWebSocket(request, signal);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.warn(`[CodexApi] WebSocket failed (${msg}), falling back to HTTP SSE`);
+        // Fallback: strip previous_response_id and use HTTP
+        const { previous_response_id: _, useWebSocket: _ws, ...httpRequest } = request;
+        return this.createResponseViaHttp(httpRequest as CodexResponsesRequest, signal);
+      }
+    }
+    return this.createResponseViaHttp(request, signal);
+  }
+
+  /**
+   * Create a response via WebSocket (for previous_response_id support).
+   * Returns a Response with SSE-formatted body, compatible with parseStream().
+   */
+  private async createResponseViaWebSocket(
+    request: CodexResponsesRequest,
+    signal?: AbortSignal,
+  ): Promise<Response> {
+    const config = getConfig();
+    const baseUrl = config.api.base_url;
+    const wsUrl = baseUrl.replace(/^https?:/, "wss:") + "/codex/responses";
+
+    // Build headers — same auth but no Content-Type (WebSocket upgrade)
+    const headers = this.applyHeaders(
+      buildHeaders(this.token, this.accountId),
+    );
+    headers["OpenAI-Beta"] = "responses_websockets=2026-02-06";
+    headers["x-openai-internal-codex-residency"] = "us";
+
+    // Build flat WebSocket message — omit store, stream, service_tier
+    const wsRequest: WsCreateRequest = {
+      type: "response.create",
+      model: request.model,
+      instructions: request.instructions,
+      input: request.input,
+    };
+    if (request.previous_response_id) {
+      wsRequest.previous_response_id = request.previous_response_id;
+    }
+    if (request.reasoning) wsRequest.reasoning = request.reasoning;
+    if (request.tools?.length) wsRequest.tools = request.tools;
+    if (request.tool_choice) wsRequest.tool_choice = request.tool_choice;
+    if (request.text) wsRequest.text = request.text;
+
+    return createWebSocketResponse(wsUrl, headers, wsRequest, signal, this.proxyUrl);
+  }
+
+  /**
+   * Create a response via HTTP SSE (default transport).
+   * Uses curl-impersonate for TLS fingerprinting.
+   */
+  private async createResponseViaHttp(
+    request: CodexResponsesRequest,
+    signal?: AbortSignal,
   ): Promise<Response> {
     const config = getConfig();
     const transport = getTransport();
@@ -262,10 +327,9 @@ export class CodexApi {
     // Codex Desktop sends this beta header to enable newer API features
     headers["OpenAI-Beta"] = "responses_websockets=2026-02-06";
 
-    // Strip service_tier from body — Codex backend doesn't accept it as a body field.
-    // Desktop app handles Fast mode internally (lighter reasoning), not via the API.
-    const { service_tier: _st, ...bodyWithoutServiceTier } = request;
-    const body = JSON.stringify(bodyWithoutServiceTier);
+    // Strip non-API fields from body — not supported by HTTP SSE.
+    const { service_tier: _st, previous_response_id: _pid, useWebSocket: _ws, ...bodyFields } = request;
+    const body = JSON.stringify(bodyFields);
 
     // No wall-clock timeout for streaming SSE — header timeout + AbortSignal provide protection
     let transportRes;

src/proxy/ws-transport.ts

@@ -0,0 +1,150 @@
+/**
+ * WebSocket transport for the Codex Responses API.
+ *
+ * Opens a WebSocket to the backend, sends a `response.create` message,
+ * and wraps incoming JSON messages into an SSE-formatted ReadableStream.
+ * This lets parseStream() and all downstream consumers work identically
+ * regardless of whether HTTP SSE or WebSocket was used.
+ *
+ * Used when `previous_response_id` is present — HTTP SSE does not support it.
+ */
+
+import WebSocket from "ws";
+import { HttpsProxyAgent } from "https-proxy-agent";
+import type { CodexInputItem } from "./codex-api.js";
+
+/** Flat WebSocket message format expected by the Codex backend. */
+export interface WsCreateRequest {
+  type: "response.create";
+  model: string;
+  instructions: string;
+  input: CodexInputItem[];
+  previous_response_id?: string;
+  reasoning?: { effort?: string; summary?: string };
+  tools?: unknown[];
+  tool_choice?: string | { type: string; name: string };
+  text?: {
+    format: {
+      type: "text" | "json_object" | "json_schema";
+      name?: string;
+      schema?: Record<string, unknown>;
+      strict?: boolean;
+    };
+  };
+  // NOTE: `store` and `stream` are intentionally omitted.
+  // The backend defaults to storing via WebSocket and always streams.
+}
+
+/**
+ * Open a WebSocket to the Codex backend, send `response.create`,
+ * and return a Response whose body is an SSE-formatted ReadableStream.
+ *
+ * The SSE format matches what parseStream() expects:
+ *   event: <type>\ndata: <json>\n\n
+ */
+export function createWebSocketResponse(
+  wsUrl: string,
+  headers: Record<string, string>,
+  request: WsCreateRequest,
+  signal?: AbortSignal,
+  proxyUrl?: string | null,
+): Promise<Response> {
+  return new Promise<Response>((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(new Error("Aborted before WebSocket connect"));
+      return;
+    }
+
+    const wsOpts: WebSocket.ClientOptions = { headers };
+    if (proxyUrl) {
+      wsOpts.agent = new HttpsProxyAgent(proxyUrl);
+    }
+    const ws = new WebSocket(wsUrl, wsOpts);
+    const encoder = new TextEncoder();
+    let controller: ReadableStreamDefaultController<Uint8Array> | null = null;
+    let streamClosed = false;
+    let connected = false;
+
+    function closeStream() {
+      if (!streamClosed && controller) {
+        streamClosed = true;
+        try { controller.close(); } catch { /* already closed */ }
+      }
+    }
+
+    function errorStream(err: Error) {
+      if (!streamClosed && controller) {
+        streamClosed = true;
+        try { controller.error(err); } catch { /* already closed */ }
+      }
+    }
+
+    // Abort signal handling
+    const onAbort = () => {
+      ws.close(1000, "aborted");
+      if (!connected) {
+        reject(new Error("Aborted during WebSocket connect"));
+      }
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+
+    const stream = new ReadableStream<Uint8Array>({
+      start(c) {
+        controller = c;
+      },
+      cancel() {
+        ws.close(1000, "stream cancelled");
+      },
+    });
+
+    ws.on("open", () => {
+      connected = true;
+      ws.send(JSON.stringify(request));
+
+      // Return the Response immediately — events will flow into the stream
+      const responseHeaders = new Headers({ "content-type": "text/event-stream" });
+      resolve(new Response(stream, { status: 200, headers: responseHeaders }));
+    });
+
+    ws.on("message", (data: Buffer | string) => {
+      if (streamClosed) return;
+      const raw = typeof data === "string" ? data : data.toString("utf-8");
+
+      try {
+        const msg = JSON.parse(raw) as Record<string, unknown>;
+        const type = (msg.type as string) ?? "unknown";
+
+        // Re-encode as SSE: event: <type>\ndata: <full json>\n\n
+        const sse = `event: ${type}\ndata: ${raw}\n\n`;
+        controller!.enqueue(encoder.encode(sse));
+
+        // Close stream after response.completed, response.failed, or error
+        if (type === "response.completed" || type === "response.failed" || type === "error") {
+          // Let the SSE chunk flush, then close
+          queueMicrotask(() => {
+            closeStream();
+            ws.close(1000);
+          });
+        }
+      } catch {
+        // Non-JSON message — emit as raw data
+        const sse = `data: ${raw}\n\n`;
+        controller!.enqueue(encoder.encode(sse));
+      }
+    });
+
+    ws.on("error", (err: Error) => {
+      signal?.removeEventListener("abort", onAbort);
+      if (!connected) {
+        reject(err);
+      } else {
+        errorStream(err);
+      }
+    });
+
+    ws.on("close", (_code: number, _reason: Buffer) => {
+      signal?.removeEventListener("abort", onAbort);
+      closeStream();
+    });
+  });
+}

src/routes/responses.ts

@@ -304,6 +304,13 @@ export function createResponsesRoutes(
       store: false,
     };
 
+    // Responses API always uses WebSocket transport — enables server-side storage
+    // and previous_response_id for multi-turn conversations.
+    codexRequest.useWebSocket = true;
+    if (typeof body.previous_response_id === "string") {
+      codexRequest.previous_response_id = body.previous_response_id;
+    }
+
     // Reasoning effort: explicit body > suffix > model default > config default
     const effort =
       (isRecord(body.reasoning) && typeof body.reasoning.effort === "string"