Skip to content

Use Claude Code with your ChatGPT, Kimi, Cursor or Grok subscription via a local Anthropic-compatible proxy

Rust

codex: use websocket transport

Raine Virta6ebe8d74b717
diff --git a/README.md b/README.md
index 23abb30..9f5fc2b 100644
--- a/README.md
+++ b/README.md
@@ -484,7 +484,9 @@ Windows, and at
"model": "gpt-5.4",
"effort": "medium",
"serviceTier": "fast",
- "baseUrl": "https://chatgpt.com/backend-api/codex/responses"
+ "baseUrl": "https://chatgpt.com/backend-api/codex/responses",
+ "transport": "websocket",
+ "previousResponseId": false
},
"kimi": {
"userAgent": "KimiCLI/1.37.0",
@@ -498,30 +500,39 @@ Windows, and at
}
```
-| Variable | Config key | Default | Purpose |
-| ------------------------ | ------------------- | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
-| `PORT` | `port` | `18765` | Proxy listen port |
-| `XDG_STATE_HOME` | — | `~/.local/state` | Linux/macOS base dir for `proxy.log` |
-| `CCP_LOG_STDERR` | `log.stderr` | unset | Also mirror log lines to stderr |
-| `CCP_LOG_VERBOSE` | `log.verbose` | unset | Log full request/response bodies + every SSE event |
-| `CCP_TRAFFIC_LOG` | — | unset | Write per-request traffic captures under `traffic/` for session debugging |
-| `CCP_ALIAS_PROVIDER` | `aliasProvider` | `codex` | Route Anthropic-style aliases (`haiku`, `sonnet`, `opus`, `claude-*`) through `codex` or `kimi` |
-| `CCP_KIMI_OAUTH_HOST` | `kimi.oauthHost` | `https://auth.kimi.com` | Override Kimi's OAuth host (debugging only) |
-| `CCP_KIMI_BASE_URL` | `kimi.baseUrl` | `https://api.kimi.com/coding/v1` | Override Kimi's API base URL |
-| `CCP_CODEX_MODEL` | `codex.model` | unset | Force all Codex requests to this model (`gpt-5.2`, `gpt-5.3-codex`, `gpt-5.3-codex-spark`, `gpt-5.4`, `gpt-5.4-mini`, `gpt-5.5`) |
-| `CCP_CODEX_EFFORT` | `codex.effort` | unset | Force all Codex requests to this reasoning effort (`none`, `low`, `medium`, `high`, `xhigh`) |
-| `CCP_CODEX_SERVICE_TIER` | `codex.serviceTier` | unset | Force all Codex requests to this service tier (`fast`/`priority`, `flex`; `fast` is sent upstream as `priority`) |
-| `CCP_CODEX_BASE_URL` | `codex.baseUrl` | `https://chatgpt.com/backend-api/codex/responses` | Override the Codex Responses endpoint |
-| `CCP_CODEX_ORIGINATOR` | `codex.originator` | `claude-code-proxy` | Override the `originator` header sent to Codex |
-| `CCP_CODEX_USER_AGENT` | `codex.userAgent` | `claude-code-proxy/<version>` | Override the `User-Agent` header sent to Codex |
-| `CCP_KIMI_USER_AGENT` | `kimi.userAgent` | `KimiCLI/1.37.0` | Override the `User-Agent` header sent to Kimi |
-| `CCP_ORIGINATOR` | — | `claude-code-proxy` | Fallback for `CCP_CODEX_ORIGINATOR` |
-| `CCP_USER_AGENT` | — | unset | Fallback for `CCP_CODEX_USER_AGENT` and `CCP_KIMI_USER_AGENT` |
+| Variable | Config key | Default | Purpose |
+| -------------------------------- | -------------------------- | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `PORT` | `port` | `18765` | Proxy listen port |
+| `XDG_STATE_HOME` | — | `~/.local/state` | Linux/macOS base dir for `proxy.log` |
+| `CCP_LOG_STDERR` | `log.stderr` | unset | Also mirror log lines to stderr |
+| `CCP_LOG_VERBOSE` | `log.verbose` | unset | Log full request/response bodies + every SSE event |
+| `CCP_TRAFFIC_LOG` | — | unset | Write per-request traffic captures under `traffic/` for session debugging |
+| `CCP_ALIAS_PROVIDER` | `aliasProvider` | `codex` | Route Anthropic-style aliases (`haiku`, `sonnet`, `opus`, `claude-*`) through `codex` or `kimi` |
+| `CCP_KIMI_OAUTH_HOST` | `kimi.oauthHost` | `https://auth.kimi.com` | Override Kimi's OAuth host (debugging only) |
+| `CCP_KIMI_BASE_URL` | `kimi.baseUrl` | `https://api.kimi.com/coding/v1` | Override Kimi's API base URL |
+| `CCP_CODEX_MODEL` | `codex.model` | unset | Force all Codex requests to this model (`gpt-5.2`, `gpt-5.3-codex`, `gpt-5.3-codex-spark`, `gpt-5.4`, `gpt-5.4-mini`, `gpt-5.5`) |
+| `CCP_CODEX_EFFORT` | `codex.effort` | unset | Force all Codex requests to this reasoning effort (`none`, `low`, `medium`, `high`, `xhigh`) |
+| `CCP_CODEX_SERVICE_TIER` | `codex.serviceTier` | unset | Force all Codex requests to this service tier (`fast`/`priority`, `flex`; `fast` is sent upstream as `priority`) |
+| `CCP_CODEX_BASE_URL` | `codex.baseUrl` | `https://chatgpt.com/backend-api/codex/responses` | Override the Codex Responses endpoint |
+| `CCP_CODEX_TRANSPORT` | `codex.transport` | `websocket` | Codex transport: `websocket`, `http`, or `auto` |
+| `CCP_CODEX_PREVIOUS_RESPONSE_ID` | `codex.previousResponseId` | `false` | Enable WebSocket continuation with `previous_response_id` when the request is append-only |
+| `CCP_CODEX_ORIGINATOR` | `codex.originator` | `claude-code-proxy` | Override the `originator` header sent to Codex |
+| `CCP_CODEX_USER_AGENT` | `codex.userAgent` | `claude-code-proxy/<version>` | Override the `User-Agent` header sent to Codex |
+| `CCP_KIMI_USER_AGENT` | `kimi.userAgent` | `KimiCLI/1.37.0` | Override the `User-Agent` header sent to Kimi |
+| `CCP_ORIGINATOR` | — | `claude-code-proxy` | Fallback for `CCP_CODEX_ORIGINATOR` |
+| `CCP_USER_AGENT` | — | unset | Fallback for `CCP_CODEX_USER_AGENT` and `CCP_KIMI_USER_AGENT` |
A malformed `config.json` is reported on stderr and ignored; defaults are used
in its place. Invalid types for individual keys are warned and skipped without
affecting other keys.
+Codex uses the WebSocket Responses transport by default. Set
+`CCP_CODEX_TRANSPORT=http` to use the older HTTP SSE transport for debugging or
+compatibility, or `CCP_CODEX_TRANSPORT=auto` to try WebSocket with HTTP fallback
+before any upstream event is exposed. `CCP_CODEX_PREVIOUS_RESPONSE_ID=1` enables
+WebSocket continuation for append-only turns. Continuation reduces repeated
+request upload size, but it does not increase the upstream model context window.
+
### Files
- `proxy.log` — JSON-lines log, rotated at 20 MiB. It lives at
diff --git a/bun.lock b/bun.lock
index e352aec..b317169 100644
--- a/bun.lock
+++ b/bun.lock
@@ -6,9 +6,11 @@
"name": "claude-openai-proxy",
"dependencies": {
"gpt-tokenizer": "^2.9.0",
+ "ws": "^8.21.0",
},
"devDependencies": {
"@types/bun": "latest",
+ "@types/ws": "^8.18.1",
"bun-types": "^1.3.14",
"oxfmt": "^0.49.0",
"oxlint": "^1.64.0",
@@ -110,6 +112,8 @@
"@types/node": ["@types/[email protected]", "", { "dependencies": { "undici-types": "~7.19.0" } }, "sha512-+qIYRKdNYJwY3vRCZMdJbPLJAtGjQBudzZzdzwQYkEPQd+PJGixUL5QfvCLDaULoLv+RhT3LDkwEfKaAkgSmNQ=="],
+ "@types/ws": ["@types/[email protected]", "", { "dependencies": { "@types/node": "*" } }, "sha512-ThVF6DCVhA8kUGy+aazFQ4kXQ7E1Ty7A3ypFOe0IcJV8O/M511G99AW24irKrW56Wt44yG9+ij8FaqoBGkuBXg=="],
+
"bun-types": ["[email protected]", "", { "dependencies": { "@types/node": "*" } }, "sha512-4N0ig0fEomHt5R0KCFWjovxow98rIoRwKolrYdCcknNwMekCXRnWEUvgu5soYV8QXtVsrUD8B95MBOZGPvr6KQ=="],
"gpt-tokenizer": ["[email protected]", "", {}, "sha512-YSpexBL/k4bfliAzMrRqn3M6+it02LutVyhVpDeMKrC/O9+pCe/5s8U2hYKa2vFLD5/vHhsKc8sOn/qGqII8Kg=="],
@@ -126,6 +130,8 @@
"undici-types": ["[email protected]", "", {}, "sha512-qYVnV5OEm2AW8cJMCpdV20CDyaN3g0AjDlOGf1OW4iaDEx8MwdtChUp4zu4H0VP3nDRF/8RKWH+IPp9uW0YGZg=="],
+ "ws": ["[email protected]", "", { "peerDependencies": { "bufferutil": "^4.0.1", "utf-8-validate": ">=5.0.2" }, "optionalPeers": ["bufferutil", "utf-8-validate"] }, "sha512-Vsp28b7DRcimFQvrqu2Wek3z1iYxDCWqHYB8Qsnk/S4RfaCQzPGPyBNuVjJV3cd6UiKtUtp6sNM77gWvzcCH+g=="],
+
"@types/bun/bun-types": ["[email protected]", "", { "dependencies": { "@types/node": "*" } }, "sha512-HqOLj5PoFajAQciOMRiIZGNoKxDJSr6qigAttOX40vJuSp6DN/CxWp9s3C1Xwm4oH7ybueITwiaOcWXoYVoRkA=="],
}
}
diff --git a/package.json b/package.json
index 50e1817..7a03556 100644
--- a/package.json
+++ b/package.json
@@ -12,10 +12,12 @@
"typecheck": "tsc --noEmit"
},
"dependencies": {
- "gpt-tokenizer": "^2.9.0"
+ "gpt-tokenizer": "^2.9.0",
+ "ws": "^8.21.0"
},
"devDependencies": {
"@types/bun": "latest",
+ "@types/ws": "^8.18.1",
"bun-types": "^1.3.14",
"oxfmt": "^0.49.0",
"oxlint": "^1.64.0",
diff --git a/src/cli.ts b/src/cli.ts
index 50e1640..e938432 100755
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -1,7 +1,13 @@
#!/usr/bin/env bun
import { startServer } from "./server.ts";
import { createLogger, logFile } from "./log.ts";
-import { port as configPort, getConfig, aliasProvider as configAliasProvider } from "./config.ts";
+import {
+ port as configPort,
+ getConfig,
+ aliasProvider as configAliasProvider,
+ codexTransport,
+ codexPreviousResponseId,
+} from "./config.ts";
import { configDir } from "./paths.ts";
import { existsSync } from "node:fs";
import { join } from "node:path";
@@ -149,6 +155,15 @@ function printConfigSummary(): void {
if (cfg.env.CCP_CODEX_BASE_URL) overrides.push("CCP_CODEX_BASE_URL (env)");
else if (fromFile.codex?.baseUrl) overrides.push("codex.baseUrl (config)");
+ if (cfg.env.CCP_CODEX_TRANSPORT) overrides.push(`CCP_CODEX_TRANSPORT=${codexTransport()} (env)`);
+ else if (fromFile.codex?.transport)
+ overrides.push(`codex.transport=${fromFile.codex.transport} (config)`);
+
+ if (cfg.env.CCP_CODEX_PREVIOUS_RESPONSE_ID !== undefined)
+ overrides.push(`CCP_CODEX_PREVIOUS_RESPONSE_ID=${codexPreviousResponseId()} (env)`);
+ else if (fromFile.codex?.previousResponseId !== undefined)
+ overrides.push(`codex.previousResponseId=${fromFile.codex.previousResponseId} (config)`);
+
if (cfg.env.CCP_ALIAS_PROVIDER)
overrides.push(`CCP_ALIAS_PROVIDER=${configAliasProvider()} (env)`);
else if (fromFile.aliasProvider)
diff --git a/src/config.test.ts b/src/config.test.ts
index aa5e10b..71be924 100644
--- a/src/config.test.ts
+++ b/src/config.test.ts
@@ -11,6 +11,8 @@ import {
codexEffort,
codexServiceTier,
codexBaseUrl,
+ codexTransport,
+ codexPreviousResponseId,
aliasProvider,
kimiUserAgent,
kimiOauthHost,
@@ -48,6 +50,8 @@ describe("config defaults", () => {
expect(codexEffort()).toBeUndefined();
expect(codexServiceTier()).toBeUndefined();
expect(codexBaseUrl("default-codex-url")).toBe("default-codex-url");
+ expect(codexTransport()).toBe("websocket");
+ expect(codexPreviousResponseId()).toBe(false);
expect(aliasProvider()).toBe("codex");
expect(kimiUserAgent("default-kimi-ua")).toBe("default-kimi-ua");
expect(kimiOauthHost()).toBe("https://auth.kimi.com");
@@ -87,6 +91,16 @@ describe("file overrides default", () => {
expect(codexBaseUrl("default")).toBe("http://127.0.0.1:2455/backend-api/codex/responses");
});
+ it("codex transport and previous response id from config.json", () => {
+ writeFileSync(
+ configPath,
+ JSON.stringify({ codex: { transport: "http", previousResponseId: true } }),
+ );
+ setEnv({});
+ expect(codexTransport()).toBe("http");
+ expect(codexPreviousResponseId()).toBe(true);
+ });
+
it("aliasProvider from config.json", () => {
writeFileSync(configPath, JSON.stringify({ aliasProvider: "codex" }));
setEnv({});
@@ -131,6 +145,16 @@ describe("env overrides file", () => {
expect(codexBaseUrl("default")).toBe("http://127.0.0.1:2455/env");
});
+ it("Codex transport env wins over config", () => {
+ writeFileSync(
+ configPath,
+ JSON.stringify({ codex: { transport: "http", previousResponseId: false } }),
+ );
+ setEnv({ CCP_CODEX_TRANSPORT: "auto", CCP_CODEX_PREVIOUS_RESPONSE_ID: "true" });
+ expect(codexTransport()).toBe("auto");
+ expect(codexPreviousResponseId()).toBe(true);
+ });
+
it("CCP_ALIAS_PROVIDER env wins over config", () => {
writeFileSync(configPath, JSON.stringify({ aliasProvider: "kimi" }));
setEnv({ CCP_ALIAS_PROVIDER: "codex" });
@@ -163,6 +187,16 @@ describe("empty-string semantics", () => {
expect(codexModel()).toBeUndefined();
});
+ it("empty Codex transport env falls through to file value", () => {
+ writeFileSync(
+ configPath,
+ JSON.stringify({ codex: { transport: "http", previousResponseId: true } }),
+ );
+ setEnv({ CCP_CODEX_TRANSPORT: "", CCP_CODEX_PREVIOUS_RESPONSE_ID: "" });
+ expect(codexTransport()).toBe("http");
+ expect(codexPreviousResponseId()).toBe(true);
+ });
+
it("empty CCP_CODEX_SERVICE_TIER env falls through to file value", () => {
writeFileSync(configPath, JSON.stringify({ codex: { serviceTier: "flex" } }));
setEnv({ CCP_CODEX_SERVICE_TIER: "" });
@@ -228,6 +262,12 @@ describe("malformed config", () => {
expect(aliasProvider()).toBe("codex");
});
+ it("ignores invalid Codex transport values", () => {
+ writeFileSync(configPath, JSON.stringify({ codex: { transport: "websockets" } }));
+ setEnv({});
+ expect(codexTransport()).toBe("websocket");
+ });
+
it("returns defaults when file is missing entirely", () => {
setEnv({});
expect(port()).toBe(18765);
diff --git a/src/config.ts b/src/config.ts
index 74ee139..bef4c00 100644
--- a/src/config.ts
+++ b/src/config.ts
@@ -10,6 +10,7 @@ import { configDir } from "./paths.ts";
// to the next layer (matches existing CCP_CODEX_MODEL behavior).
export type AliasProvider = "codex" | "kimi";
+export type CodexTransport = "http" | "websocket" | "auto";
export interface FileConfig {
port?: number;
@@ -21,6 +22,8 @@ export interface FileConfig {
effort?: string;
serviceTier?: string;
baseUrl?: string;
+ transport?: CodexTransport;
+ previousResponseId?: boolean;
};
kimi?: {
userAgent?: string;
@@ -67,6 +70,26 @@ function parseAliasProvider(key: string, value: unknown): AliasProvider | undefi
return undefined;
}
+function parseCodexTransport(key: string, value: unknown): CodexTransport | undefined {
+ if (value === undefined) return undefined;
+ if (value === "http" || value === "websocket" || value === "auto") return value;
+ warnInvalid(key, '"http", "websocket", or "auto"', value);
+ return undefined;
+}
+
+function parseBoolean(key: string, value: unknown): boolean | undefined {
+ if (value === undefined) return undefined;
+ if (typeof value === "boolean") return value;
+ warnInvalid(key, "boolean", value);
+ return undefined;
+}
+
+function parseBooleanEnv(value: string | undefined): boolean | undefined {
+ const normalized = emptyOrUnset(value)?.toLowerCase();
+ if (normalized === undefined) return undefined;
+ return normalized === "1" || normalized === "true" || normalized === "yes";
+}
+
function validate(raw: unknown): FileConfig {
if (!raw || typeof raw !== "object" || Array.isArray(raw)) return {};
const r = raw as Record<string, unknown>;
@@ -103,7 +126,16 @@ function validate(raw: unknown): FileConfig {
const codex = validateStringSection(
"codex",
- ["originator", "userAgent", "model", "effort", "serviceTier", "baseUrl"],
+ [
+ "originator",
+ "userAgent",
+ "model",
+ "effort",
+ "serviceTier",
+ "baseUrl",
+ "transport",
+ "previousResponseId",
+ ],
{
originator: "string",
userAgent: "string",
@@ -111,9 +143,15 @@ function validate(raw: unknown): FileConfig {
effort: "string",
serviceTier: "string",
baseUrl: "string",
+ transport: "string",
+ previousResponseId: "boolean",
},
);
- if (codex) out.codex = codex;
+ if (codex) {
+ codex.transport = parseCodexTransport("codex.transport", codex.transport);
+ codex.previousResponseId = parseBoolean("codex.previousResponseId", codex.previousResponseId);
+ out.codex = codex;
+ }
const kimi = validateStringSection("kimi", ["userAgent", "oauthHost", "baseUrl"], {
userAgent: "string",
@@ -217,6 +255,24 @@ export function codexBaseUrl(defaultValue: string): string {
return c.env.CCP_CODEX_BASE_URL ?? c.file.codex?.baseUrl ?? defaultValue;
}
+export function codexTransport(): CodexTransport {
+ const c = getConfig();
+ return (
+ parseCodexTransport("CCP_CODEX_TRANSPORT", emptyOrUnset(c.env.CCP_CODEX_TRANSPORT)) ??
+ c.file.codex?.transport ??
+ "websocket"
+ );
+}
+
+export function codexPreviousResponseId(): boolean {
+ const c = getConfig();
+ return (
+ parseBooleanEnv(c.env.CCP_CODEX_PREVIOUS_RESPONSE_ID) ??
+ c.file.codex?.previousResponseId ??
+ false
+ );
+}
+
export function aliasProvider(): AliasProvider {
const c = getConfig();
return (
diff --git a/src/providers/codex/client.ts b/src/providers/codex/client.ts
index 03cb9ee..2604757 100644
--- a/src/providers/codex/client.ts
+++ b/src/providers/codex/client.ts
@@ -1,14 +1,20 @@
import { CODEX_API_ENDPOINT, ORIGINATOR as ORIGINATOR_DEFAULT } from "./auth/constants.ts";
-import { codexBaseUrl, codexOriginator, codexUserAgent } from "../../config.ts";
+import { codexBaseUrl, codexOriginator, codexTransport, codexUserAgent } from "../../config.ts";
declare const BUILD_VERSION: string | undefined;
const PROXY_VERSION = typeof BUILD_VERSION === "string" ? BUILD_VERSION : "dev";
import { forceRefresh, getAuth } from "./auth/manager.ts";
import type { Logger } from "../../log.ts";
import type { RequestContext } from "../types.ts";
-import type { ResponsesRequest } from "./translate/request.ts";
+import { toWebSocketRequest, type ResponsesRequest } from "./translate/request.ts";
import { retryOn429, sleep } from "../retry.ts";
import { headersToRecord } from "../../traffic.ts";
import { summarizeCodexRequestSize } from "./request-summary.ts";
+import {
+ CodexWebSocketSetupError,
+ codexWebSocketHeaders,
+ codexWebSocketRequest,
+} from "./websocket.ts";
+import type { ContinuationCandidate } from "./continuation.ts";
const FETCH_WATCHDOG_INTERVAL_MS = 30_000;
let fetchHeaderTimeoutMs = 60_000;
@@ -25,14 +31,19 @@ export interface CodexResponse {
headers: Headers;
}
+export interface PostCodexOptions {
+ continuation?: ContinuationCandidate;
+}
+
export async function postCodex(
body: ResponsesRequest,
ctx: RequestContext,
+ opts: PostCodexOptions = {},
): Promise<CodexResponse> {
const log = ctx.childLogger("codex.client");
return retryHeaderTimeouts(
() =>
- retryOn429(() => attemptPostCodex(body, ctx, log), {
+ retryOn429(() => attemptPostCodex(body, ctx, log, opts), {
log,
signal: ctx.signal,
classify: (err) =>
@@ -78,15 +89,28 @@ async function attemptPostCodex(
body: ResponsesRequest,
ctx: RequestContext,
log: Logger,
+ opts: PostCodexOptions,
): Promise<CodexResponse> {
let auth = await getAuth();
- let resp = await doFetch(auth.access, auth.accountId, body, ctx, log);
+ let resp: Response;
+ try {
+ resp = await doFetch(auth.access, auth.accountId, body, ctx, log, opts);
+ } catch (err) {
+ if (!(err instanceof CodexWebSocketSetupError)) throw err;
+ if (err.status === 429) {
+ throw new CodexError(429, "Rate limited", err.message, { retryAfter: err.retryAfter });
+ }
+ if (err.status !== 401 && err.status !== 403) throw err;
+ log.warn("codex websocket auth failed, refreshing token", { status: err.status });
+ auth = await forceRefresh();
+ resp = await doFetch(auth.access, auth.accountId, body, ctx, log, opts);
+ }
if (resp.status === 401) {
log.warn("got 401, refreshing token", {});
try {
auth = await forceRefresh();
- resp = await doFetch(auth.access, auth.accountId, body, ctx, log);
+ resp = await doFetch(auth.access, auth.accountId, body, ctx, log, opts);
} catch (err) {
log.error("refresh after 401 failed", { err: String(err) });
}
@@ -123,7 +147,27 @@ async function doFetch(
body: ResponsesRequest,
ctx: RequestContext,
log: Logger,
+ opts: PostCodexOptions,
): Promise<Response> {
+ const mode = codexTransport();
+ if (mode === "websocket") return doFetchWebSocket(accessToken, accountId, body, ctx, log, opts);
+ if (mode === "auto") {
+ try {
+ return await doFetchWebSocket(accessToken, accountId, body, ctx, log, opts);
+ } catch (err) {
+ log.warn("codex websocket failed before response, falling back to http", {
+ err: String(err),
+ });
+ }
+ }
+ return doFetchHttp(accessToken, accountId, body, ctx, log);
+}
+
+function codexHeaders(
+ accessToken: string,
+ accountId: string | undefined,
+ ctx: RequestContext,
+): Headers {
const headers = new Headers({
"Content-Type": "application/json",
accept: "text/event-stream",
@@ -139,7 +183,84 @@ async function doFetch(
headers.set("x-client-request-id", ctx.sessionId);
headers.set("x-codex-window-id", `${ctx.sessionId}:0`);
}
+ return headers;
+}
+
+async function doFetchWebSocket(
+ accessToken: string,
+ accountId: string | undefined,
+ body: ResponsesRequest,
+ ctx: RequestContext,
+ log: Logger,
+ opts: PostCodexOptions,
+): Promise<Response> {
+ const headers = codexHeaders(accessToken, accountId, ctx);
+ const requestHeaders = codexWebSocketHeaders(headers);
+ const codexUrl = codexBaseUrl(CODEX_API_ENDPOINT);
+ const continuation = opts.continuation;
+ const wsBody = toWebSocketRequest(body, {
+ previousResponseId: continuation?.previousResponseId,
+ input: continuation?.inputDelta,
+ });
+ const bodyJson = JSON.stringify(wsBody);
+ const size = summarizeCodexRequestSize(wsBody, bodyJson);
+ ctx.traffic?.writeJson("020-upstream-request", wsBody);
+ ctx.traffic?.writeJson("021-upstream-request-metadata", {
+ provider: "codex",
+ transport: "websocket",
+ url: codexUrl,
+ method: "GET",
+ headers: requestHeaders,
+ size,
+ continuation: {
+ previousResponseId: continuation?.previousResponseId,
+ inputDeltaCount: continuation?.inputDeltaCount ?? body.input.length,
+ disabledReason: continuation?.disabledReason,
+ },
+ });
+ log.debug("posting to codex websocket", {
+ url: codexUrl,
+ model: body.model,
+ inputCount: wsBody.input.length,
+ toolCount: body.tools?.length ?? 0,
+ serviceTier: body.service_tier,
+ reasoningEffort: body.reasoning?.effort,
+ promptCacheKey: body.prompt_cache_key,
+ continuation: {
+ previousResponseId: continuation?.previousResponseId,
+ inputDeltaCount: continuation?.inputDeltaCount,
+ disabledReason: continuation?.disabledReason,
+ },
+ size,
+ });
+ const startedAt = Date.now();
+ const stream = await codexWebSocketRequest({
+ url: codexUrl,
+ headers,
+ body: wsBody,
+ ctx,
+ connectTimeoutMs: 15_000,
+ idleTimeoutMs: 300_000,
+ });
+ const elapsedMs = Date.now() - startedAt;
+ const responseHeaders = new Headers({ "content-type": "text/event-stream" });
+ ctx.traffic?.writeJson("030-upstream-response-headers", {
+ status: 200,
+ statusText: "OK",
+ elapsedMs,
+ headers: headersToRecord(responseHeaders),
+ });
+ return new Response(stream, { status: 200, headers: responseHeaders });
+}
+async function doFetchHttp(
+ accessToken: string,
+ accountId: string | undefined,
+ body: ResponsesRequest,
+ ctx: RequestContext,
+ log: Logger,
+): Promise<Response> {
+ const headers = codexHeaders(accessToken, accountId, ctx);
const codexUrl = codexBaseUrl(CODEX_API_ENDPOINT);
const bodyJson = JSON.stringify(body);
@@ -147,6 +268,7 @@ async function doFetch(
ctx.traffic?.writeJson("020-upstream-request", body);
ctx.traffic?.writeJson("021-upstream-request-metadata", {
provider: "codex",
+ transport: "http",
url: codexUrl,
method: "POST",
headers: headersToRecord(headers),
diff --git a/src/providers/codex/continuation.test.ts b/src/providers/codex/continuation.test.ts
new file mode 100644
index 0000000..2cdeda5
--- /dev/null
+++ b/src/providers/codex/continuation.test.ts
@@ -0,0 +1,151 @@
+import { afterEach, describe, expect, it } from "bun:test";
+import {
+ clearAllContinuationsForTests,
+ continuationCandidate,
+ recordContinuation,
+} from "./continuation.ts";
+import type { ResponsesInputItem, ResponsesRequest } from "./translate/request.ts";
+
+function requestWithInput(
+ input: ResponsesInputItem[],
+ extra: Partial<ResponsesRequest> = {},
+): ResponsesRequest {
+ return {
+ model: "gpt-5.5",
+ input,
+ store: false,
+ stream: true,
+ text: { verbosity: "low" },
+ ...extra,
+ };
+}
+
+afterEach(() => {
+ clearAllContinuationsForTests();
+});
+
+describe("continuationCandidate", () => {
+ it("is disabled unless the feature is enabled", () => {
+ const req = requestWithInput([
+ { type: "message", role: "user", content: [{ type: "input_text", text: "one" }] },
+ ]);
+
+ expect(continuationCandidate("s1", req, false)).toEqual({
+ inputDeltaCount: 1,
+ disabledReason: "disabled",
+ });
+ });
+
+ it("uses previous response id for append-only input", () => {
+ const first = requestWithInput([
+ { type: "message", role: "user", content: [{ type: "input_text", text: "one" }] },
+ ]);
+ recordContinuation("s1", first, "resp_1", [
+ { type: "message", role: "assistant", content: [{ type: "output_text", text: "two" }] },
+ ]);
+
+ const second = requestWithInput([
+ { type: "message", role: "user", content: [{ type: "input_text", text: "one" }] },
+ { type: "message", role: "assistant", content: [{ type: "output_text", text: "two" }] },
+ { type: "message", role: "user", content: [{ type: "input_text", text: "three" }] },
+ ]);
+
+ const result = continuationCandidate("s1", second, true);
+
+ expect(result.previousResponseId).toBe("resp_1");
+ expect(result.inputDeltaCount).toBe(1);
+ expect(result.inputDelta).toEqual([
+ { type: "message", role: "user", content: [{ type: "input_text", text: "three" }] },
+ ]);
+ });
+
+ it("clears state when the prompt signature changes", () => {
+ const first = requestWithInput([
+ { type: "message", role: "user", content: [{ type: "input_text", text: "one" }] },
+ ]);
+ recordContinuation("s1", first, "resp_1", []);
+
+ const second = requestWithInput(first.input, { tool_choice: "none" });
+
+ expect(continuationCandidate("s1", second, true).disabledReason).toBe("prompt_changed");
+ expect(continuationCandidate("s1", second, true).disabledReason).toBe("missing_state");
+ });
+
+ it("preserves state when an exact repeat has no input delta", () => {
+ const first = requestWithInput([
+ { type: "message", role: "user", content: [{ type: "input_text", text: "one" }] },
+ ]);
+ recordContinuation("s1", first, "resp_1", []);
+
+ expect(continuationCandidate("s1", first, true).disabledReason).toBe("empty_delta");
+ expect(
+ continuationCandidate(
+ "s1",
+ requestWithInput([
+ ...first.input,
+ { type: "message", role: "user", content: [{ type: "input_text", text: "two" }] },
+ ]),
+ true,
+ ).previousResponseId,
+ ).toBe("resp_1");
+ });
+
+ it("clears state when the transcript is not a strict prefix", () => {
+ const first = requestWithInput([
+ { type: "message", role: "user", content: [{ type: "input_text", text: "one" }] },
+ ]);
+ recordContinuation("s1", first, "resp_1", []);
+
+ const second = requestWithInput([
+ { type: "message", role: "user", content: [{ type: "input_text", text: "changed" }] },
+ { type: "message", role: "user", content: [{ type: "input_text", text: "three" }] },
+ ]);
+
+ expect(continuationCandidate("s1", second, true).disabledReason).toBe("not_append_only");
+ });
+
+ it("handles previous function call output as visible transcript", () => {
+ const first = requestWithInput([
+ { type: "message", role: "user", content: [{ type: "input_text", text: "read" }] },
+ ]);
+ recordContinuation("s1", first, "resp_1", [
+ {
+ type: "function_call",
+ call_id: "call_1",
+ name: "Read",
+ arguments: '{"file_path":"/tmp/a"}',
+ },
+ ]);
+
+ const second = requestWithInput([
+ { type: "message", role: "user", content: [{ type: "input_text", text: "read" }] },
+ {
+ type: "function_call",
+ call_id: "call_1",
+ name: "Read",
+ arguments: '{"file_path":"/tmp/a"}',
+ },
+ { type: "function_call_output", call_id: "call_1", output: "contents" },
+ { type: "message", role: "user", content: [{ type: "input_text", text: "summarize" }] },
+ ]);
+
+ const result = continuationCandidate("s1", second, true);
+
+ expect(result.previousResponseId).toBe("resp_1");
+ expect(result.inputDelta).toEqual([
+ { type: "function_call_output", call_id: "call_1", output: "contents" },
+ { type: "message", role: "user", content: [{ type: "input_text", text: "summarize" }] },
+ ]);
+ });
+
+ it("does not store oversized session transcripts", () => {
+ const largeText = "x".repeat(2_000_001);
+ const first = requestWithInput([
+ { type: "message", role: "user", content: [{ type: "input_text", text: largeText }] },
+ ]);
+
+ recordContinuation("s1", first, "resp_1", []);
+
+ expect(continuationCandidate("s1", first, true).disabledReason).toBe("missing_state");
+ });
+});
diff --git a/src/providers/codex/continuation.ts b/src/providers/codex/continuation.ts
new file mode 100644
index 0000000..e39ab6a
--- /dev/null
+++ b/src/providers/codex/continuation.ts
@@ -0,0 +1,131 @@
+import type { ResponsesInputItem, ResponsesRequest } from "./translate/request.ts";
+
+interface ContinuationState {
+ responseId: string;
+ promptSignature: string;
+ transcript: ResponsesInputItem[];
+ transcriptBytes: number;
+ updatedAt: number;
+}
+
+const states = new Map<string, ContinuationState>();
+const TTL_MS = 30 * 60 * 1000;
+const MAX_STATES = 10_000;
+const MAX_SESSION_TRANSCRIPT_BYTES = 2_000_000;
+const MAX_TOTAL_TRANSCRIPT_BYTES = 20_000_000;
+let totalTranscriptBytes = 0;
+
+export interface ContinuationCandidate {
+ previousResponseId?: string;
+ inputDelta?: ResponsesInputItem[];
+ inputDeltaCount: number;
+ disabledReason?: string;
+}
+
+export function continuationCandidate(
+ sessionId: string | undefined,
+ body: ResponsesRequest,
+ enabled: boolean,
+ now = Date.now(),
+): ContinuationCandidate {
+ if (!enabled) return { inputDeltaCount: body.input.length, disabledReason: "disabled" };
+ if (!sessionId) return { inputDeltaCount: body.input.length, disabledReason: "missing_session" };
+ const state = states.get(sessionId);
+ if (!state || now - state.updatedAt > TTL_MS) {
+ clearContinuation(sessionId);
+ return { inputDeltaCount: body.input.length, disabledReason: "missing_state" };
+ }
+ const signature = promptSignature(body);
+ if (signature !== state.promptSignature) {
+ clearContinuation(sessionId);
+ return { inputDeltaCount: body.input.length, disabledReason: "prompt_changed" };
+ }
+ const suffix = inputSuffixAfterPrefix(body.input, state.transcript);
+ if (!suffix) {
+ clearContinuation(sessionId);
+ return { inputDeltaCount: body.input.length, disabledReason: "not_append_only" };
+ }
+ if (suffix.length === 0) {
+ return { inputDeltaCount: 0, disabledReason: "empty_delta" };
+ }
+ return {
+ previousResponseId: state.responseId,
+ inputDelta: suffix,
+ inputDeltaCount: suffix.length,
+ };
+}
+
+export function recordContinuation(
+ sessionId: string | undefined,
+ requestBody: ResponsesRequest,
+ responseId: string | undefined,
+ outputItems: ResponsesInputItem[],
+ now = Date.now(),
+): void {
+ if (!sessionId || !responseId) return;
+ const transcript = [...requestBody.input, ...outputItems];
+ const transcriptBytes = byteLength(JSON.stringify(transcript));
+ if (transcriptBytes > MAX_SESSION_TRANSCRIPT_BYTES) {
+ clearContinuation(sessionId);
+ return;
+ }
+ clearContinuation(sessionId);
+ states.set(sessionId, {
+ responseId,
+ promptSignature: promptSignature(requestBody),
+ transcript,
+ transcriptBytes,
+ updatedAt: now,
+ });
+ totalTranscriptBytes += transcriptBytes;
+ evictOldest();
+}
+
+export function clearContinuation(sessionId: string | undefined): void {
+ if (!sessionId) return;
+ const existing = states.get(sessionId);
+ if (existing) totalTranscriptBytes -= existing.transcriptBytes;
+ states.delete(sessionId);
+}
+
+export function clearAllContinuationsForTests(): void {
+ states.clear();
+ totalTranscriptBytes = 0;
+}
+
+function inputSuffixAfterPrefix(
+ input: ResponsesInputItem[],
+ prefix: ResponsesInputItem[],
+): ResponsesInputItem[] | undefined {
+ if (prefix.length > input.length) return undefined;
+ for (let i = 0; i < prefix.length; i++) {
+ if (JSON.stringify(input[i]) !== JSON.stringify(prefix[i])) return undefined;
+ }
+ return input.slice(prefix.length);
+}
+
+function promptSignature(body: ResponsesRequest): string {
+ const { input: _input, ...signature } = body;
+ return stableJson(signature);
+}
+
+function stableJson(value: unknown): string {
+ if (value === null || typeof value !== "object") return JSON.stringify(value);
+ if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+ const entries = Object.entries(value as Record<string, unknown>)
+ .filter(([, child]) => child !== undefined)
+ .sort(([a], [b]) => a.localeCompare(b));
+ return `{${entries.map(([key, child]) => `${JSON.stringify(key)}:${stableJson(child)}`).join(",")}}`;
+}
+
+function evictOldest(): void {
+ while (states.size > MAX_STATES || totalTranscriptBytes > MAX_TOTAL_TRANSCRIPT_BYTES) {
+ const key = states.keys().next().value;
+ if (!key) return;
+ clearContinuation(key);
+ }
+}
+
+function byteLength(value: string): number {
+ return new TextEncoder().encode(value).byteLength;
+}
diff --git a/src/providers/codex/index.ts b/src/providers/codex/index.ts
index 3b206f3..37dc74b 100644
--- a/src/providers/codex/index.ts
+++ b/src/providers/codex/index.ts
@@ -19,7 +19,8 @@ import { runBrowserLogin } from "./auth/pkce.ts";
import { runDeviceLogin } from "./auth/device.ts";
import { persistInitialTokens } from "./auth/manager.ts";
import { loadAuth, authPath, clearAuth } from "./auth/token-store.ts";
-import { logVerbose } from "../../config.ts";
+import { codexPreviousResponseId, logVerbose } from "../../config.ts";
+import { clearContinuation, continuationCandidate, recordContinuation } from "./continuation.ts";
interface SessionCountSnapshot {
reqId: string;
@@ -287,10 +288,20 @@ async function handleMessages(body: AnthropicRequest, ctx: RequestContext): Prom
});
}
+ const previousResponseIdEnabled = codexPreviousResponseId();
+ const continuation = continuationCandidate(ctx.sessionId, translated, previousResponseIdEnabled);
+ log.debug("codex continuation", {
+ enabled: previousResponseIdEnabled,
+ previousResponseId: continuation.previousResponseId,
+ inputDeltaCount: continuation.inputDeltaCount,
+ disabledReason: continuation.disabledReason,
+ });
+
let upstream;
try {
- upstream = await postCodex(translated, ctx);
+ upstream = await postCodex(translated, ctx, { continuation });
} catch (err) {
+ clearContinuation(ctx.sessionId);
if (err instanceof CodexError) {
log.warn("codex error", { status: err.status, detail: err.detail });
if (err.status === 429) {
@@ -321,35 +332,41 @@ async function handleMessages(body: AnthropicRequest, ctx: RequestContext): Prom
upstreamHeaders: upstream.headers,
traffic: ctx.traffic,
requestSize,
- onFinish: logVerbose()
- ? (finish) => {
- const mappedUsage = finish.usage ? mapUsageToAnthropic(finish.usage) : undefined;
- log.info("compaction telemetry", {
- phase: "upstream_finish",
- mode: "stream",
- requestedModel: body.model,
- resolvedModel,
- serverModel,
- serverReasoningIncluded,
- messageCount,
- toolCount,
- localInputTokens,
- translatedInputTokens,
- requestedMaxTokens: body.max_tokens,
- hasContextManagement: contextManagement !== undefined,
- contextManagement,
- upstreamInputTokens: finish.usage?.input_tokens ?? 0,
- upstreamOutputTokens: finish.usage?.output_tokens ?? 0,
- upstreamCachedInputTokens: finish.usage?.input_tokens_details?.cached_tokens ?? 0,
- upstreamReasoningTokens: finish.usage?.output_tokens_details?.reasoning_tokens ?? 0,
- mappedInputTokens: mappedUsage?.input_tokens ?? 0,
- mappedOutputTokens: mappedUsage?.output_tokens ?? 0,
- mappedCachedInputTokens: mappedUsage?.cache_read_input_tokens ?? 0,
- mappedContextWindowTokens: mappedUsage ? usageWindowTokens(mappedUsage) : 0,
- stopReason: finish.stopReason,
- });
- }
- : undefined,
+ onFinish: (finish) => {
+ if (finish.continuationEligible) {
+ recordContinuation(ctx.sessionId, translated, finish.responseId, finish.outputItems);
+ } else {
+ clearContinuation(ctx.sessionId);
+ }
+ if (logVerbose()) {
+ const mappedUsage = finish.usage ? mapUsageToAnthropic(finish.usage) : undefined;
+ log.info("compaction telemetry", {
+ phase: "upstream_finish",
+ mode: "stream",
+ requestedModel: body.model,
+ resolvedModel,
+ serverModel,
+ serverReasoningIncluded,
+ messageCount,
+ toolCount,
+ localInputTokens,
+ translatedInputTokens,
+ requestedMaxTokens: body.max_tokens,
+ hasContextManagement: contextManagement !== undefined,
+ contextManagement,
+ upstreamInputTokens: finish.usage?.input_tokens ?? 0,
+ upstreamOutputTokens: finish.usage?.output_tokens ?? 0,
+ upstreamCachedInputTokens: finish.usage?.input_tokens_details?.cached_tokens ?? 0,
+ upstreamReasoningTokens: finish.usage?.output_tokens_details?.reasoning_tokens ?? 0,
+ mappedInputTokens: mappedUsage?.input_tokens ?? 0,
+ mappedOutputTokens: mappedUsage?.output_tokens ?? 0,
+ mappedCachedInputTokens: mappedUsage?.cache_read_input_tokens ?? 0,
+ mappedContextWindowTokens: mappedUsage ? usageWindowTokens(mappedUsage) : 0,
+ stopReason: finish.stopReason,
+ });
+ }
+ },
+ onInvalidateContinuation: () => clearContinuation(ctx.sessionId),
});
return new Response(stream, {
status: 200,
@@ -368,6 +385,11 @@ async function handleMessages(body: AnthropicRequest, ctx: RequestContext): Prom
log: ctx.childLogger("codex.accumulate"),
traffic: ctx.traffic,
});
+ if (result.continuationEligible) {
+ recordContinuation(ctx.sessionId, translated, result.responseId, result.outputItems);
+ } else {
+ clearContinuation(ctx.sessionId);
+ }
if (logVerbose()) {
const { serverModel, serverReasoningIncluded } = upstreamHeaderSnapshot(upstream.headers);
log.info("compaction telemetry", {
@@ -399,6 +421,7 @@ async function handleMessages(body: AnthropicRequest, ctx: RequestContext): Prom
headers: { "content-type": "application/json" },
});
} catch (err) {
+ clearContinuation(ctx.sessionId);
if (err instanceof UpstreamStreamError) {
log.warn("upstream stream error (non-streaming)", {
kind: err.kind,
diff --git a/src/providers/codex/translate/accumulate.ts b/src/providers/codex/translate/accumulate.ts
index 4708ebb..92f824f 100644
--- a/src/providers/codex/translate/accumulate.ts
+++ b/src/providers/codex/translate/accumulate.ts
@@ -1,5 +1,5 @@
import { mapUsageToAnthropic, reduceUpstream } from "./reducer.ts";
-import type { CodexUsage } from "./reducer.ts";
+import type { CodexUsage, ReducerEvent } from "./reducer.ts";
import type { Logger } from "../../../log.ts";
import type { TrafficCapture } from "../../types.ts";
import { attachTrafficCapture, createUpstreamStreamDiagnostics } from "./reducer.ts";
@@ -24,9 +24,15 @@ export interface AnthropicNonStreamResponse {
};
}
+type FinishEvent = Extract<ReducerEvent, { kind: "finish" }>;
+
export interface AccumulatedResponse {
response: AnthropicNonStreamResponse;
rawUsage?: CodexUsage;
+ terminalType?: FinishEvent["terminalType"];
+ continuationEligible: boolean;
+ responseId?: string;
+ outputItems: FinishEvent["outputItems"];
}
/**
@@ -48,6 +54,10 @@ export async function accumulateResponse(
let stopReason: AnthropicNonStreamResponse["stop_reason"] = null;
let usage: ReturnType<typeof mapUsageToAnthropic> | undefined;
let rawUsage: CodexUsage | undefined;
+ let terminalType: FinishEvent["terminalType"] | undefined;
+ let continuationEligible = false;
+ let responseId: string | undefined;
+ let outputItems: FinishEvent["outputItems"] = [];
const diagnostics = attachTrafficCapture(createUpstreamStreamDiagnostics(), opts.traffic);
@@ -78,6 +88,10 @@ export async function accumulateResponse(
stopReason = e.stopReason;
rawUsage = e.usage;
usage = mapUsageToAnthropic(e.usage);
+ terminalType = e.terminalType;
+ continuationEligible = e.continuationEligible;
+ responseId = e.responseId;
+ outputItems = e.outputItems;
break;
}
}
@@ -101,6 +115,10 @@ export async function accumulateResponse(
return {
rawUsage,
+ terminalType,
+ continuationEligible,
+ responseId,
+ outputItems,
response: {
id: opts.messageId,
type: "message",
diff --git a/src/providers/codex/translate/reducer.test.ts b/src/providers/codex/translate/reducer.test.ts
new file mode 100644
index 0000000..501f66f
--- /dev/null
+++ b/src/providers/codex/translate/reducer.test.ts
@@ -0,0 +1,140 @@
+import { describe, expect, it } from "bun:test";
+import { reduceUpstream } from "./reducer.ts";
+
+const silentLog = {
+ debug: () => {},
+ info: () => {},
+ warn: () => {},
+ error: () => {},
+ child: () => silentLog,
+};
+
+function sse(type: string, payload: Record<string, unknown>): string {
+ return `data: ${JSON.stringify({ type, ...payload })}\n\n`;
+}
+
+function upstreamFromChunks(chunks: string[]): ReadableStream<Uint8Array> {
+ const encoder = new TextEncoder();
+ return new ReadableStream<Uint8Array>({
+ start(controller) {
+ for (const chunk of chunks) controller.enqueue(encoder.encode(chunk));
+ controller.close();
+ },
+ });
+}
+
+async function events(chunks: string[]) {
+ const out = [];
+ for await (const event of reduceUpstream(upstreamFromChunks(chunks), silentLog)) out.push(event);
+ return out;
+}
+
+describe("reduceUpstream finish metadata", () => {
+ it("captures completed response id and assistant text output items", async () => {
+ const out = await events([
+ sse("response.output_item.added", {
+ output_index: 0,
+ item: { type: "message", id: "msg_upstream" },
+ }),
+ sse("response.output_text.delta", { output_index: 0, delta: "hello" }),
+ sse("response.output_item.done", {
+ output_index: 0,
+ item: { type: "message", id: "msg_upstream" },
+ }),
+ sse("response.completed", { response: { id: "resp_1", usage: { input_tokens: 3 } } }),
+ ]);
+
+ expect(out.at(-1)).toEqual({
+ kind: "finish",
+ stopReason: "end_turn",
+ terminalType: "response.completed",
+ continuationEligible: true,
+ usage: { input_tokens: 3 },
+ responseId: "resp_1",
+ outputItems: [
+ { type: "message", role: "assistant", content: [{ type: "output_text", text: "hello" }] },
+ ],
+ });
+ });
+
+ it("captures sanitized Read function call arguments", async () => {
+ const out = await events([
+ sse("response.output_item.added", {
+ output_index: 0,
+ item: { type: "function_call", call_id: "call_1", name: "Read" },
+ }),
+ sse("response.function_call_arguments.done", {
+ output_index: 0,
+ arguments: '{"file_path":"/tmp/a","pages":""}',
+ }),
+ sse("response.output_item.done", {
+ output_index: 0,
+ item: {
+ type: "function_call",
+ call_id: "call_1",
+ name: "Read",
+ arguments: '{"file_path":"/tmp/a","pages":""}',
+ },
+ }),
+ sse("response.completed", { response: { id: "resp_1", usage: {} } }),
+ ]);
+
+ expect(out.at(-1)).toMatchObject({
+ kind: "finish",
+ stopReason: "tool_use",
+ terminalType: "response.completed",
+ continuationEligible: true,
+ responseId: "resp_1",
+ outputItems: [
+ {
+ type: "function_call",
+ call_id: "call_1",
+ name: "Read",
+ arguments: '{"file_path":"/tmp/a"}',
+ },
+ ],
+ });
+ });
+
+ it("marks response.done as continuation eligible when complete", async () => {
+ const out = await events([
+ sse("response.done", {
+ response: {
+ id: "resp_1",
+ usage: {},
+ },
+ }),
+ ]);
+
+ expect(out.at(-1)).toMatchObject({
+ kind: "finish",
+ stopReason: "end_turn",
+ terminalType: "response.done",
+ continuationEligible: true,
+ responseId: "resp_1",
+ outputItems: [],
+ });
+ });
+
+ it("marks incomplete terminals as max tokens and preserves terminal type", async () => {
+ const out = await events([
+ sse("response.incomplete", {
+ response: {
+ id: "resp_1",
+ status: "incomplete",
+ incomplete_details: { reason: "max_output_tokens" },
+ usage: {},
+ },
+ }),
+ ]);
+
+ expect(out.at(-1)).toMatchObject({
+ kind: "finish",
+ stopReason: "max_tokens",
+ terminalType: "response.incomplete",
+ continuationEligible: false,
+ responseId: "resp_1",
+ outputItems: [],
+ });
+ });
+});
diff --git a/src/providers/codex/translate/reducer.ts b/src/providers/codex/translate/reducer.ts
index 416ff68..4fdf3c1 100644
--- a/src/providers/codex/translate/reducer.ts
+++ b/src/providers/codex/translate/reducer.ts
@@ -2,6 +2,7 @@ import { createSseStreamStats, parseSseStream, type SseStreamStats } from "../..
import type { Logger } from "../../../log.ts";
import { logVerbose } from "../../../config.ts";
import type { TrafficCapture } from "../../types.ts";
+import type { ResponsesInputItem } from "./request.ts";
export class UpstreamStreamError extends Error {
constructor(
@@ -22,6 +23,7 @@ export interface CodexUsage {
}
export type StopReason = "end_turn" | "tool_use" | "max_tokens";
+export type TerminalType = "response.completed" | "response.incomplete" | "response.done";
export type ReducerEvent =
| { kind: "text-start"; index: number }
@@ -32,7 +34,15 @@ export type ReducerEvent =
| { kind: "tool-progress"; index: number }
| { kind: "progress" }
| { kind: "tool-stop"; index: number }
- | { kind: "finish"; stopReason: StopReason; usage: CodexUsage | undefined };
+ | {
+ kind: "finish";
+ stopReason: StopReason;
+ terminalType: TerminalType;
+ continuationEligible: boolean;
+ usage: CodexUsage | undefined;
+ responseId?: string;
+ outputItems: ResponsesInputItem[];
+ };
interface TextState {
kind: "text";
@@ -217,12 +227,34 @@ export async function* reduceUpstream(
diagnostics = createUpstreamStreamDiagnostics(),
): AsyncGenerator<ReducerEvent> {
const blocksByOutputIndex = new Map<number, BlockState>();
+ const outputItemsByIndex = new Map<number, ResponsesInputItem>();
const itemIdToOutputIndex = new Map<string, number>();
let anthropicIndex = 0;
let sawToolUse = false;
let finalUsage: CodexUsage | undefined;
+ let responseId: string | undefined;
+ let terminalType: TerminalType | undefined;
+ let continuationEligible = false;
let incomplete = false;
+ function captureOutputItem(outputIndex: number, state: BlockState): void {
+ if (state.kind === "text") {
+ if (!state.textAccum) return;
+ outputItemsByIndex.set(outputIndex, {
+ type: "message",
+ role: "assistant",
+ content: [{ type: "output_text", text: state.textAccum }],
+ });
+ return;
+ }
+ outputItemsByIndex.set(outputIndex, {
+ type: "function_call",
+ call_id: state.callId,
+ name: state.name,
+ arguments: state.argsAccum,
+ });
+ }
+
for await (const evt of parseSseStream(upstream, diagnostics.stats)) {
if (!evt.data) continue;
let p: any;
@@ -396,6 +428,7 @@ export async function* reduceUpstream(
}
}
}
+ captureOutputItem(p.output_index, state);
if (state.kind === "text") {
log.debug("text block complete", { index: state.index, text: state.textAccum });
yield { kind: "text-stop", index: state.index };
@@ -412,17 +445,20 @@ export async function* reduceUpstream(
continue;
}
- if (t === "response.completed" || t === "response.incomplete") {
+ if (t === "response.completed" || t === "response.incomplete" || t === "response.done") {
diagnostics.sawTerminalEvent = true;
+ terminalType = t;
+ responseId = p.response?.id;
finalUsage = p.response?.usage;
const reason = p.response?.incomplete_details?.reason;
if (
t === "response.incomplete" ||
- reason === "max_output_tokens" ||
+ reason !== undefined ||
p.response?.status === "incomplete"
) {
incomplete = true;
}
+ continuationEligible = (t === "response.completed" || t === "response.done") && !incomplete;
continue;
}
}
@@ -446,7 +482,18 @@ export async function* reduceUpstream(
}
const stopReason: StopReason = incomplete ? "max_tokens" : sawToolUse ? "tool_use" : "end_turn";
- yield { kind: "finish", stopReason, usage: finalUsage };
+ const outputItems = Array.from(outputItemsByIndex.entries())
+ .sort(([a], [b]) => a - b)
+ .map(([, item]) => item);
+ yield {
+ kind: "finish",
+ stopReason,
+ terminalType: terminalType ?? "response.incomplete",
+ continuationEligible,
+ usage: finalUsage,
+ responseId,
+ outputItems,
+ };
}
export function mapUsageToAnthropic(u: CodexUsage | undefined): {
diff --git a/src/providers/codex/translate/request.test.ts b/src/providers/codex/translate/request.test.ts
index 6da273d..91dbc2e 100644
--- a/src/providers/codex/translate/request.test.ts
+++ b/src/providers/codex/translate/request.test.ts
@@ -2,7 +2,12 @@ import { afterEach, describe, expect, it } from "bun:test";
import { loadConfig } from "../../../config.ts";
import type { AnthropicRequest } from "../../../anthropic/schema.ts";
import { countTokens } from "../count-tokens.ts";
-import { InvalidServiceTierError, toolResultToString, translateRequest } from "./request.ts";
+import {
+ InvalidServiceTierError,
+ toWebSocketRequest,
+ toolResultToString,
+ translateRequest,
+} from "./request.ts";
const baseRequest: AnthropicRequest = {
model: "claude-sonnet-4-6",
messages: [{ role: "user", content: "hello" }],
@@ -168,6 +173,29 @@ describe("translateRequest", () => {
});
});
+ it("builds a websocket request without mutating the HTTP request", () => {
+ const translated = translateRequest(baseRequest);
+ const delta = [
+ {
+ type: "message" as const,
+ role: "user" as const,
+ content: [{ type: "input_text" as const, text: "next" }],
+ },
+ ];
+
+ const ws = toWebSocketRequest(translated, {
+ previousResponseId: "resp_1",
+ input: delta,
+ generate: false,
+ });
+
+ expect(ws.previous_response_id).toBe("resp_1");
+ expect(ws.generate).toBe(false);
+ expect(ws.input).toEqual(delta);
+ expect(translated.input).not.toEqual(delta);
+ expect("previous_response_id" in translated).toBe(false);
+ });
+
it("returns only the expected top-level upstream request fields", () => {
const translated = translateRequest({
...baseRequest,
diff --git a/src/providers/codex/translate/request.ts b/src/providers/codex/translate/request.ts
index ee9fe35..bd31d8f 100644
--- a/src/providers/codex/translate/request.ts
+++ b/src/providers/codex/translate/request.ts
@@ -46,6 +46,23 @@ export interface ResponsesRequest {
client_metadata?: Record<string, string>;
}
+export interface ResponsesWebSocketRequest extends ResponsesRequest {
+ previous_response_id?: string;
+ generate?: boolean;
+}
+
+export function toWebSocketRequest(
+ body: ResponsesRequest,
+ opts: { previousResponseId?: string; input?: ResponsesInputItem[]; generate?: boolean } = {},
+): ResponsesWebSocketRequest {
+ return {
+ ...body,
+ ...(opts.input ? { input: opts.input } : {}),
+ ...(opts.previousResponseId ? { previous_response_id: opts.previousResponseId } : {}),
+ ...(opts.generate !== undefined ? { generate: opts.generate } : {}),
+ };
+}
+
export type ResponsesInputItem =
| {
type: "message";
@@ -67,7 +84,7 @@ export type ResponsesInputItem =
export type ResponsesContentPart =
| { type: "input_text"; text: string }
| { type: "output_text"; text: string }
- | { type: "input_image"; image_url: string };
+ | { type: "input_image"; image_url: string; detail?: "auto" | "low" | "high" };
export interface ResponsesTool {
type: "function";
diff --git a/src/providers/codex/translate/stream.ts b/src/providers/codex/translate/stream.ts
index 612a277..8fe4226 100644
--- a/src/providers/codex/translate/stream.ts
+++ b/src/providers/codex/translate/stream.ts
@@ -11,6 +11,7 @@ import {
mapUsageToAnthropic,
reduceUpstream,
UpstreamStreamError,
+ type ReducerEvent,
} from "./reducer.ts";
/**
@@ -35,10 +36,8 @@ export function translateStream(
upstreamHeaders?: Headers;
traffic?: TrafficCapture;
requestSize?: CodexRequestSizeSummary;
- onFinish?: (finish: {
- stopReason: "end_turn" | "tool_use" | "max_tokens";
- usage?: Parameters<typeof mapUsageToAnthropic>[0];
- }) => void;
+ onFinish?: (finish: Extract<ReducerEvent, { kind: "finish" }>) => void;
+ onInvalidateContinuation?: () => void;
},
): ReadableStream<Uint8Array> {
const encoder = new TextEncoder();
@@ -189,7 +188,7 @@ export function translateStream(
throw new UpstreamStreamError("failed", "Stream finished with open content blocks");
}
ensureMessageStart();
- opts.onFinish?.({ stopReason: e.stopReason, usage: e.usage });
+ opts.onFinish?.(e);
emit("message_delta", {
type: "message_delta",
delta: { stop_reason: e.stopReason, stop_sequence: null },
@@ -209,6 +208,7 @@ export function translateStream(
index,
...block,
}));
+ opts.onInvalidateContinuation?.();
if (opts.signal?.aborted) {
opts.log.info("stream cancelled", {
err: describeError(err),
diff --git a/src/providers/codex/websocket.test.ts b/src/providers/codex/websocket.test.ts
new file mode 100644
index 0000000..924c2e5
--- /dev/null
+++ b/src/providers/codex/websocket.test.ts
@@ -0,0 +1,176 @@
+import { describe, expect, it } from "bun:test";
+import { createServer } from "node:http";
+import WebSocket, { WebSocketServer } from "ws";
+import type { RequestContext } from "../types.ts";
+import {
+ CodexWebSocketSetupError,
+ codexWebSocketHeaders,
+ codexWebSocketRequest,
+ toWebSocketUrl,
+ WEBSOCKET_PROTOCOL_HEADER,
+} from "./websocket.ts";
+import type { ResponsesWebSocketRequest } from "./translate/request.ts";
+
+const silentLog = {
+ debug: () => {},
+ info: () => {},
+ warn: () => {},
+ error: () => {},
+ child: () => silentLog,
+};
+
+function ctx(): RequestContext {
+ return {
+ reqId: "req_1",
+ signal: new AbortController().signal,
+ childLogger: () => silentLog,
+ };
+}
+
+function body(): ResponsesWebSocketRequest {
+ return {
+ model: "gpt-5.5",
+ input: [{ type: "message", role: "user", content: [{ type: "input_text", text: "hello" }] }],
+ store: false,
+ stream: true,
+ };
+}
+
+async function collect(stream: ReadableStream<Uint8Array>): Promise<string> {
+ const reader = stream.getReader();
+ const decoder = new TextDecoder();
+ let out = "";
+ while (true) {
+ const { done, value } = await reader.read();
+ if (done) return out;
+ out += decoder.decode(value, { stream: true });
+ }
+}
+
+async function withServer(
+ handler: (socket: WebSocket, requestBody: Promise<unknown>) => void,
+): Promise<{ url: string; close: () => Promise<void> }> {
+ const server = createServer();
+ const wss = new WebSocketServer({ server });
+ wss.on("connection", (socket) => {
+ let resolveBody: (value: unknown) => void = () => {};
+ const requestBody = new Promise<unknown>((resolve) => {
+ resolveBody = resolve;
+ });
+ socket.once("message", (data) => resolveBody(JSON.parse(data.toString())));
+ handler(socket, requestBody);
+ });
+ await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+ const address = server.address();
+ if (!address || typeof address === "string") throw new Error("missing server address");
+ return {
+ url: `http://127.0.0.1:${address.port}/backend-api/codex/responses`,
+ close: () =>
+ new Promise<void>((resolve, reject) => {
+ wss.close((err) => {
+ if (err) reject(err);
+ else server.close((closeErr) => (closeErr ? reject(closeErr) : resolve()));
+ });
+ }),
+ };
+}
+
+describe("Codex WebSocket helpers", () => {
+ it("converts HTTP URLs to WebSocket URLs", () => {
+ expect(toWebSocketUrl("https://chatgpt.com/backend-api/codex/responses")).toBe(
+ "wss://chatgpt.com/backend-api/codex/responses",
+ );
+ expect(toWebSocketUrl("http://127.0.0.1:1234/backend-api/codex/responses")).toBe(
+ "ws://127.0.0.1:1234/backend-api/codex/responses",
+ );
+ });
+
+ it("rejects unsupported URL schemes", () => {
+ expect(() => toWebSocketUrl("file:///tmp/responses")).toThrow(
+ "Unsupported Codex WebSocket URL scheme",
+ );
+ });
+
+ it("sets the WebSocket beta header and removes content length", () => {
+ const headers = new Headers({
+ "openai-beta": "responses=experimental",
+ "content-length": "123",
+ authorization: "Bearer token",
+ });
+
+ expect(codexWebSocketHeaders(headers)).toEqual({
+ authorization: "Bearer token",
+ "openai-beta": WEBSOCKET_PROTOCOL_HEADER,
+ });
+ });
+
+ it("carries upgrade failure status for auth refresh", () => {
+ const err = new CodexWebSocketSetupError("upgrade failed", 401);
+
+ expect(err.name).toBe("CodexWebSocketSetupError");
+ expect(err.status).toBe(401);
+ });
+
+ it("converts websocket events to SSE and sends response.create without stream", async () => {
+ const server = await withServer(async (socket, requestBody) => {
+ const req = await requestBody;
+ expect(req).toEqual({
+ type: "response.create",
+ model: "gpt-5.5",
+ input: [
+ { type: "message", role: "user", content: [{ type: "input_text", text: "hello" }] },
+ ],
+ store: false,
+ });
+ socket.send(JSON.stringify({ type: "response.completed", response: { id: "resp_1" } }));
+ });
+ try {
+ const stream = await codexWebSocketRequest({
+ url: server.url,
+ headers: new Headers(),
+ body: body(),
+ ctx: ctx(),
+ connectTimeoutMs: 1_000,
+ idleTimeoutMs: 1_000,
+ });
+
+ await expect(collect(stream)).resolves.toBe(
+ 'data: {"type":"response.completed","response":{"id":"resp_1"}}\n\ndata: [DONE]\n\n',
+ );
+ } finally {
+ await server.close();
+ }
+ });
+
+ it("rejects setup errors before exposing a stream", async () => {
+ const server = await withServer((socket) => {
+ socket.send(
+ JSON.stringify({
+ type: "error",
+ status: 429,
+ error: { code: "rate_limit", message: "slow down" },
+ headers: { "retry-after": "3" },
+ }),
+ );
+ });
+ try {
+ await expect(
+ codexWebSocketRequest({
+ url: server.url,
+ headers: new Headers(),
+ body: body(),
+ ctx: ctx(),
+ connectTimeoutMs: 1_000,
+ idleTimeoutMs: 1_000,
+ }),
+ ).rejects.toMatchObject({
+ name: "CodexWebSocketSetupError",
+ status: 429,
+ code: "rate_limit",
+ retryAfter: "3",
+ });
+ } finally {
+ await server.close();
+ }
+ });
+});
diff --git a/src/providers/codex/websocket.ts b/src/providers/codex/websocket.ts
new file mode 100644
index 0000000..39f35e3
--- /dev/null
+++ b/src/providers/codex/websocket.ts
@@ -0,0 +1,204 @@
+import WebSocket from "ws";
+import { headersToRecord } from "../../traffic.ts";
+import type { RequestContext } from "../types.ts";
+import type { ResponsesWebSocketRequest } from "./translate/request.ts";
+
+export const WEBSOCKET_PROTOCOL_HEADER = "responses_websockets=2026-02-06";
+
+export class CodexWebSocketSetupError extends Error {
+ constructor(
+ message: string,
+ public status?: number,
+ public code?: string,
+ public retryAfter?: string,
+ ) {
+ super(message);
+ this.name = "CodexWebSocketSetupError";
+ }
+}
+
+export interface CodexWebSocketOptions {
+ url: string;
+ headers: Headers;
+ body: ResponsesWebSocketRequest;
+ ctx: RequestContext;
+ connectTimeoutMs: number;
+ idleTimeoutMs: number;
+}
+
+export function toWebSocketUrl(url: string): string {
+ const parsed = new URL(url);
+ if (parsed.protocol === "http:") {
+ parsed.protocol = "ws:";
+ return parsed.toString();
+ }
+ if (parsed.protocol === "https:") {
+ parsed.protocol = "wss:";
+ return parsed.toString();
+ }
+ throw new Error(`Unsupported Codex WebSocket URL scheme: ${parsed.protocol}`);
+}
+
+export function codexWebSocketHeaders(headers: Headers): Record<string, string> {
+ const requestHeaders = headersToRecord(headers);
+ requestHeaders["openai-beta"] = WEBSOCKET_PROTOCOL_HEADER;
+ delete requestHeaders["content-length"];
+ return requestHeaders;
+}
+
+export async function codexWebSocketRequest(
+ opts: CodexWebSocketOptions,
+): Promise<ReadableStream<Uint8Array>> {
+ const encoder = new TextEncoder();
+ const wsUrl = toWebSocketUrl(opts.url);
+ const requestHeaders = codexWebSocketHeaders(opts.headers);
+
+ opts.ctx.traffic?.writeJson("022-upstream-websocket-metadata", {
+ provider: "codex",
+ url: wsUrl,
+ headers: requestHeaders,
+ });
+
+ return new Promise((resolve, reject) => {
+ const socket = new WebSocket(wsUrl, { headers: requestHeaders });
+ let controller: ReadableStreamDefaultController<Uint8Array> | undefined;
+ let settled = false;
+ let done = false;
+ let idleTimer: ReturnType<typeof setTimeout> | undefined;
+ let connectTimer: ReturnType<typeof setTimeout> | undefined;
+ const pendingChunks: Uint8Array[] = [];
+
+ const stream = new ReadableStream<Uint8Array>({
+ start(next) {
+ controller = next;
+ for (const chunk of pendingChunks.splice(0)) controller.enqueue(chunk);
+ },
+ cancel() {
+ done = true;
+ cleanup();
+ socket.on("error", () => {});
+ socket.terminate();
+ },
+ });
+
+ const cleanup = () => {
+ if (idleTimer) clearTimeout(idleTimer);
+ if (connectTimer) clearTimeout(connectTimer);
+ opts.ctx.signal.removeEventListener("abort", onAbort);
+ };
+ const fail = (err: Error) => {
+ if (done) return;
+ done = true;
+ cleanup();
+ socket.on("error", () => {});
+ socket.terminate();
+ if (!settled) reject(err);
+ else controller?.error(err);
+ };
+ const enqueue = (chunk: Uint8Array) => {
+ if (controller) controller.enqueue(chunk);
+ else pendingChunks.push(chunk);
+ };
+ const closeController = () => {
+ if (controller) controller.close();
+ else queueMicrotask(closeController);
+ };
+ const close = () => {
+ if (done) return;
+ done = true;
+ cleanup();
+ enqueue(encoder.encode("data: [DONE]\n\n"));
+ closeController();
+ socket.close();
+ };
+ const resetIdle = () => {
+ if (idleTimer) clearTimeout(idleTimer);
+ idleTimer = setTimeout(
+ () => fail(new Error("Timed out waiting for Codex WebSocket event")),
+ opts.idleTimeoutMs,
+ );
+ };
+ const onAbort = () => fail(new DOMException("Aborted", "AbortError"));
+ const encodeSse = (text: string) =>
+ `${text
+ .split(/\r?\n/)
+ .map((line) => `data: ${line}`)
+ .join("\n")}\n\n`;
+
+ connectTimer = setTimeout(
+ () => fail(new Error("Timed out connecting to Codex WebSocket")),
+ opts.connectTimeoutMs,
+ );
+ opts.ctx.signal.addEventListener("abort", onAbort, { once: true });
+
+ socket.on("unexpected-response", (_req, res) => {
+ fail(
+ new CodexWebSocketSetupError(
+ `Unexpected Codex WebSocket upgrade response: ${res.statusCode}`,
+ res.statusCode,
+ ),
+ );
+ });
+ socket.on("open", () => {
+ if (connectTimer) clearTimeout(connectTimer);
+ resetIdle();
+ const { stream: _stream, ...payload } = opts.body;
+ try {
+ socket.send(JSON.stringify({ type: "response.create", ...payload }), (err) => {
+ if (err) fail(err instanceof Error ? err : new Error(String(err)));
+ });
+ } catch (err) {
+ fail(err instanceof Error ? err : new Error(String(err)));
+ }
+ });
+ socket.on("message", (data, isBinary) => {
+ if (isBinary) {
+ fail(new Error("Unexpected binary Codex WebSocket frame"));
+ return;
+ }
+ resetIdle();
+ const text = data.toString();
+ let event: {
+ type?: string;
+ status?: number;
+ error?: { code?: string; message?: string };
+ headers?: Record<string, string>;
+ };
+ try {
+ event = JSON.parse(text);
+ } catch (err) {
+ fail(err instanceof Error ? err : new Error(String(err)));
+ return;
+ }
+ if (!settled && event.type === "error") {
+ fail(
+ new CodexWebSocketSetupError(
+ event.error?.message ?? event.error?.code ?? "Codex WebSocket setup error",
+ event.status,
+ event.error?.code,
+ event.headers?.["retry-after"],
+ ),
+ );
+ return;
+ }
+ enqueue(encoder.encode(encodeSse(text)));
+ if (!settled) {
+ settled = true;
+ resolve(stream);
+ }
+ if (
+ event.type === "response.completed" ||
+ event.type === "response.failed" ||
+ event.type === "response.incomplete" ||
+ event.type === "response.done" ||
+ event.type === "error"
+ ) {
+ close();
+ }
+ });
+ socket.on("error", (err) => fail(err instanceof Error ? err : new Error(String(err))));
+ socket.on("close", (code, reason) => {
+ if (!done) fail(new Error(`Codex WebSocket closed before terminal event: ${code} ${reason}`));
+ });
+ });
+}