@bitkyc08/opencodex 2.1.8 → 2.1.9

package/src/server.ts

@@ -1,15 +1,16 @@
 import { existsSync, readFileSync } from "node:fs";
+import { timingSafeEqual } from "node:crypto";
 import { extname, join } from "node:path";
 import { createAnthropicAdapter } from "./adapters/anthropic";
 import { createAzureAdapter } from "./adapters/azure";
 import { createGoogleAdapter } from "./adapters/google";
 import { createOpenAIChatAdapter } from "./adapters/openai-chat";
 import { createResponsesPassthroughAdapter } from "./adapters/openai-responses";
-import { bridgeToResponsesSSE, buildResponseJSON, formatErrorResponse } from "./bridge";
+import { bridgeToResponsesSSE, buildResponseJSON, formatErrorResponse, type ResponsesTerminalStatus } from "./bridge";
 import {
   buildWarmupCompletionFrames,
   buildWsErrorFrame,
-  selectForwardHeaders,
+  selectForwardHeadersForAuthContext,
   sendJsonFrame,
   sendResponseToWebSocket,
   sendTextFrame,
@@ -25,12 +26,36 @@ import {
   listOAuthProviders, reconcileOAuthProviders, startLoginFlow, upsertOAuthProvider,
 } from "./oauth/index";
 import type { CatalogModel } from "./codex-catalog";
+import { invalidateCodexModelsCache } from "./codex-catalog";
 import { buildWebSearchTool, planWebSearch, runWithWebSearch } from "./web-search";
 import { describeImagesInPlace, planVisionSidecar } from "./vision";
 import { removeCredential } from "./oauth/store";
 import { enrichProviderFromCatalog, listKeyLoginProviders } from "./oauth/key-providers";
 import { deriveProviderPresets } from "./providers/derive";
 import type { OcxConfig, OcxProviderConfig } from "./types";
+import {
+  applyCodexAuthContextToProvider,
+  assertCodexAuthContextNotCooled,
+  CodexAccountCooldownError,
+  CodexAuthContextError,
+  CodexThreadAffinityExpiredError,
+  headersForCodexAuthContext,
+  isCodexAuthContextUsable,
+  resolveCodexAuthContext,
+  stripCodexRuntimeProviderFields,
+  type CodexAuthContext,
+} from "./codex-auth-context";
+export {
+  clearThreadAccountMap,
+  formatCodexProviderForLog,
+  resolveCodexAccountForThread,
+} from "./codex-routing";
+import {
+  formatCodexProviderForLog,
+  recordCodexUpstreamOutcome,
+  type CodexUpstreamOutcome,
+} from "./codex-routing";
+import { registerCodexWebSocket, unregisterCodexWebSocket } from "./codex-websocket-registry";
 
 // Single source of truth = package.json (../ from src/), so /healthz + the GUI badge match the
 // installed npm version instead of a stale hardcode.
@@ -116,11 +141,40 @@ export function resolveAdapter(providerConfig: OcxProviderConfig) {
   }
 }
 
+function sidecarOutcomeRecorder(config: OcxConfig, authCtx: CodexAuthContext): ((outcome: CodexUpstreamOutcome) => void) | undefined {
+  return authCtx.kind === "pool"
+    ? outcome => recordCodexUpstreamOutcome(config, authCtx.accountId, outcome)
+    : undefined;
+}
+
+function usesCodexForwardPoolAuth(
+  authCtx: CodexAuthContext,
+  provider: OcxProviderConfig,
+): authCtx is Extract<CodexAuthContext, { kind: "pool" }> {
+  return authCtx.kind === "pool" && provider.authMode === "forward" && provider.adapter === "openai-responses";
+}
+
+function codexForwardTerminalOutcomeRecorder(
+  config: OcxConfig,
+  authCtx: CodexAuthContext,
+  provider: OcxProviderConfig,
+): ((status: ResponsesTerminalStatus) => void) | undefined {
+  if (!usesCodexForwardPoolAuth(authCtx, provider)) return undefined;
+  return status => recordCodexUpstreamOutcome(config, authCtx.accountId, status === "completed" ? 200 : 502);
+}
+
 async function handleResponses(
   req: Request,
   config: OcxConfig,
   logCtx: { model: string; provider: string },
-  options: { forceEmptyResponseId?: boolean; abortSignal?: AbortSignal } = {},
+  options: {
+    forceEmptyResponseId?: boolean;
+    abortSignal?: AbortSignal;
+    authContext?: CodexAuthContext;
+    selectedForwardHeaders?: Headers;
+    recordTerminalOutcomes?: boolean;
+    setTerminalOutcomeRecorder?: (recorder: ((status: ResponsesTerminalStatus) => void) | undefined) => void;
+  } = {},
 ): Promise<Response> {
   let body: unknown;
   try {
@@ -155,6 +209,31 @@ async function handleResponses(
   logCtx.model = route.modelId;
   logCtx.provider = route.providerName;
 
+  let authCtx: CodexAuthContext;
+  let selectedForwardHeaders: Headers;
+  try {
+    authCtx = options.authContext ?? await resolveCodexAuthContext(req.headers, config);
+    selectedForwardHeaders = options.selectedForwardHeaders ?? headersForCodexAuthContext(req.headers, authCtx);
+  } catch (err) {
+    if (err instanceof CodexAccountCooldownError) {
+      return formatErrorResponse(429, "rate_limit_error", "Selected Codex account is cooling down");
+    }
+    if (err instanceof CodexThreadAffinityExpiredError) {
+      return formatErrorResponse(409, "invalid_request_error", "Codex thread account affinity expired; start a new session");
+    }
+    if (err instanceof CodexAuthContextError) {
+      const safeAccountLabel = formatCodexProviderForLog(route.providerName, err.accountId, config);
+      console.error(`[codex-auth] Pool account ${safeAccountLabel} token failed; reauthentication required`);
+      return formatErrorResponse(401, "authentication_error", "Selected Codex account needs reauthentication");
+    }
+    throw err;
+  }
+  if (!isCodexAuthContextUsable(authCtx, config)) {
+    return formatErrorResponse(401, "authentication_error", "Selected Codex account needs reauthentication");
+  }
+  route.provider = applyCodexAuthContextToProvider(route.provider, authCtx);
+  logCtx.provider = formatCodexProviderForLog(route.providerName, authCtx.kind === "pool" ? authCtx.accountId : null, config);
+
   // OAuth providers: swap in a fresh access token (auto-refreshed) as the Bearer key, so the
   // existing openai-chat / anthropic adapters authenticate with no change.
   if (route.provider.authMode === "oauth") {
@@ -168,16 +247,18 @@ async function handleResponses(
   // Vision sidecar: the routed model can't see images (provider.noVisionModels). Give it "eyes" —
   // describe each attached image with a gpt vision model via the ChatGPT passthrough and replace it
   // with text BEFORE the main call, so the text-only model can reason about it.
-  const visionPlan = planVisionSidecar(config, route.provider, route.modelId, parsed, req.headers);
+  const visionPlan = planVisionSidecar(config, route.provider, route.modelId, parsed, selectedForwardHeaders, authCtx);
+  const recordSidecarOutcome = sidecarOutcomeRecorder(config, authCtx);
   if (visionPlan) {
-    await describeImagesInPlace(parsed, visionPlan.forwardProvider, req.headers, visionPlan.settings, options.abortSignal);
+    await describeImagesInPlace(parsed, visionPlan.forwardProvider, selectedForwardHeaders, visionPlan.settings, options.abortSignal, recordSidecarOutcome);
   }
 
   const adapterProvider = resolveWireProtocolOverride(route.providerName, route.modelId, route.provider);
   const adapter = resolveAdapter(adapterProvider);
+  const recordTerminalOutcomes = options.recordTerminalOutcomes !== false;
 
   if ("passthrough" in adapter && adapter.passthrough) {
-    const request = adapter.buildRequest(parsed, { headers: req.headers });
+    const request = adapter.buildRequest(parsed, { headers: selectedForwardHeaders });
     // Abort the upstream if the client disconnects. A directly-relayed body does not propagate the
     // consumer's cancel to a signalled fetch, so we pass the signal and relay through relayWithAbort,
     // whose cancel() aborts the upstream — preventing leaked connections (RC2, passthrough path).
@@ -193,15 +274,55 @@ async function handleResponses(
       }, upstream.signal, connectMs);
     } catch (err) {
       upstream.abort();
-      const msg = err instanceof Error && err.name === "TimeoutError"
+      const outcome = err instanceof Error && err.name === "TimeoutError" ? "timeout" : "connect_error";
+      if (usesCodexForwardPoolAuth(authCtx, route.provider)) recordCodexUpstreamOutcome(config, authCtx.accountId, outcome);
+      const msg = outcome === "timeout"
         ? `Provider connect timeout after ${connectMs}ms`
         : `Provider unreachable: ${err instanceof Error ? err.message : String(err)}`;
       return formatErrorResponse(502, "upstream_error", msg);
     }
     const headers = sanitizePassthroughHeaders(upstreamResponse.headers);
     const isEventStream = headers.get("content-type")?.toLowerCase().includes("text/event-stream") ?? false;
+    const terminalRecorder = codexForwardTerminalOutcomeRecorder(config, authCtx, route.provider);
+    const terminalBodyWillRecord = !!terminalRecorder && upstreamResponse.ok && isEventStream;
+    // Capture quota from upstream response for multi-account tracking
+    if (usesCodexForwardPoolAuth(authCtx, route.provider)) {
+      const weeklyRaw = upstreamResponse.headers.get("x-codex-secondary-used-percent");
+      const fiveHourRaw = upstreamResponse.headers.get("x-codex-primary-used-percent");
+      const monthlyRaw = upstreamResponse.headers.get("x-codex-tertiary-used-percent");
+      const weeklyResetRaw = upstreamResponse.headers.get("x-codex-secondary-reset-at");
+      const fiveHourResetRaw = upstreamResponse.headers.get("x-codex-primary-reset-at");
+      const monthlyResetRaw = upstreamResponse.headers.get("x-codex-tertiary-reset-at");
+      const retryAfterRaw = upstreamResponse.headers.get("retry-after");
+      if (weeklyRaw || fiveHourRaw || monthlyRaw) {
+        const { updateAccountQuota } = await import("./codex-auth-api");
+        updateAccountQuota(
+          authCtx.accountId,
+          weeklyRaw,
+          fiveHourRaw,
+          weeklyResetRaw,
+          fiveHourResetRaw,
+          monthlyRaw,
+          monthlyResetRaw,
+        );
+      }
+      if (terminalBodyWillRecord) {
+        options.setTerminalOutcomeRecorder?.(terminalRecorder);
+      } else {
+        recordCodexUpstreamOutcome(config, authCtx.accountId, upstreamResponse.status, {
+          retryAfter: retryAfterRaw,
+          resetAt: [fiveHourResetRaw, weeklyResetRaw, monthlyResetRaw],
+        });
+      }
+    }
+
     const body = isEventStream
-      ? relaySseWithHeartbeat(upstreamResponse.body, upstream)
+      ? relaySseWithHeartbeat(
+          upstreamResponse.body,
+          upstream,
+          15_000,
+          terminalBodyWillRecord && recordTerminalOutcomes ? terminalRecorder : undefined,
+        )
       : relayWithAbort(upstreamResponse.body, upstream);
     return new Response(body, {
       status: upstreamResponse.status,
@@ -212,18 +333,19 @@ async function handleResponses(
   // Web-search sidecar: Codex enabled web_search but this is a routed (non-OpenAI) model that can't
   // run it server-side. Expose web_search as a function tool and run searches via the gpt-mini sidecar
   // through the ChatGPT passthrough, looping until the model answers. Otherwise take the normal path.
-  const wsPlan = planWebSearch(config, parsed, false, req.headers, route.provider, route.modelId);
+  const wsPlan = planWebSearch(config, parsed, false, selectedForwardHeaders, route.provider, route.modelId, authCtx);
   if (wsPlan) {
     parsed.context.tools = [...(parsed.context.tools ?? []), buildWebSearchTool()];
     return runWithWebSearch({
       parsed, adapter,
       forwardProvider: wsPlan.forwardProvider,
       hostedTool: wsPlan.hostedTool,
-      incomingHeaders: req.headers,
+      selectedForwardHeaders,
       settings: wsPlan.settings,
       maxSearches: wsPlan.maxSearches,
       forceEmptyResponseId: true,
       abortSignal: options.abortSignal,
+      recordSidecarOutcome,
     });
   }
 
@@ -231,7 +353,7 @@ async function handleResponses(
   linkAbortSignal(upstream, options.abortSignal);
   const connectMs = config.connectTimeoutMs ?? 30_000;
 
-  const request = adapter.buildRequest(parsed, { headers: req.headers });
+  const request = adapter.buildRequest(parsed, { headers: selectedForwardHeaders });
   let upstreamResponse: Response;
   try {
     upstreamResponse = await fetchWithHeaderTimeout(request.url, {
@@ -366,16 +488,80 @@ export function relayWithAbort(
   });
 }
 
+function nextSseBlock(buffer: string): { block: string; rest: string } | null {
+  const match = buffer.match(/\r?\n\r?\n/);
+  if (!match || match.index === undefined) return null;
+  return {
+    block: buffer.slice(0, match.index),
+    rest: buffer.slice(match.index + match[0].length),
+  };
+}
+
+function sseDataPayload(block: string): string | null {
+  const data: string[] = [];
+  for (const line of block.split(/\r?\n/)) {
+    if (!line.startsWith("data:")) continue;
+    const value = line.slice(5);
+    data.push(value.startsWith(" ") ? value.slice(1) : value);
+  }
+  return data.length > 0 ? data.join("\n") : null;
+}
+
+function terminalStatusFromSsePayload(payload: string): ResponsesTerminalStatus | null {
+  if (payload === "[DONE]") return null;
+  try {
+    const json = JSON.parse(payload) as { type?: unknown };
+    switch (json.type) {
+      case "response.completed":
+        return "completed";
+      case "response.failed":
+        return "failed";
+      case "response.incomplete":
+        return "incomplete";
+      default:
+        return null;
+    }
+  } catch {
+    return null;
+  }
+}
+
 export function relaySseWithHeartbeat(
   body: ReadableStream<Uint8Array> | null,
   upstream: AbortController,
   heartbeatMs = 15_000,
+  onTerminal?: (status: ResponsesTerminalStatus) => void,
 ): ReadableStream<Uint8Array> | null {
   if (!body) return null;
   const reader = body.getReader();
+  const decoder = new TextDecoder();
   const heartbeat = new TextEncoder().encode(": opencodex keepalive\n\n");
   let timer: ReturnType<typeof setInterval> | undefined;
   let closed = false;
+  let clientCancelled = false;
+  let terminalReported = false;
+  let buffer = "";
+
+  const reportTerminal = (status: ResponsesTerminalStatus) => {
+    if (terminalReported || clientCancelled || closed) return;
+    terminalReported = true;
+    onTerminal?.(status);
+  };
+
+  const inspectPayload = (payload: string | null) => {
+    if (!payload) return;
+    const status = terminalStatusFromSsePayload(payload);
+    if (status) reportTerminal(status);
+  };
+
+  const inspectChunk = (value: Uint8Array) => {
+    buffer += decoder.decode(value, { stream: true });
+    let next: { block: string; rest: string } | null;
+    while ((next = nextSseBlock(buffer))) {
+      buffer = next.rest;
+      inspectPayload(sseDataPayload(next.block));
+    }
+  };
 
   const cleanup = () => {
     closed = true;
@@ -398,17 +584,23 @@ export function relaySseWithHeartbeat(
       try {
         const { done, value } = await reader.read();
         if (done) {
+          buffer += decoder.decode();
+          if (buffer.trim()) inspectPayload(sseDataPayload(buffer));
+          if (!terminalReported && !clientCancelled) reportTerminal("incomplete");
           cleanup();
           controller.close();
           return;
         }
+        inspectChunk(value);
         controller.enqueue(value);
       } catch (err) {
+        if (!clientCancelled) reportTerminal("incomplete");
         cleanup();
         try { controller.error(err); } catch { /* already torn down */ }
       }
     },
     cancel(reason) {
+      clientCancelled = true;
       cleanup();
       upstream.abort(reason);
       reader.cancel(reason).catch(() => {});
@@ -444,11 +636,11 @@ export function sanitizePassthroughHeaders(upstream: Headers): Headers {
 
 let _corsOrigin = "http://localhost:10100";
 function setCorsOrigin(port: number): void { _corsOrigin = `http://localhost:${port}`; }
-function corsHeaders(): Record<string, string> {
+export function corsHeaders(): Record<string, string> {
   return {
     "Access-Control-Allow-Origin": _corsOrigin,
     "Access-Control-Allow-Methods": "GET, POST, PUT, DELETE, OPTIONS",
-    "Access-Control-Allow-Headers": "Content-Type, Authorization",
+    "Access-Control-Allow-Headers": "Content-Type, Authorization, X-OpenCodex-API-Key",
   };
 }
 
@@ -467,6 +659,93 @@ function isLocalOrigin(req: Request): boolean {
   return origin === localhostOrigin || origin === loopbackOrigin;
 }
 
+function configuredApiAuthToken(_config: OcxConfig): string | undefined {
+  const token = process.env.OPENCODEX_API_AUTH_TOKEN?.trim();
+  return token || undefined;
+}
+
+export function isLoopbackHostname(hostname: string | undefined): boolean {
+  const normalized = (hostname ?? "127.0.0.1").trim().toLowerCase();
+  return normalized === "" || normalized === "localhost" || normalized === "127.0.0.1" || normalized === "::1" || normalized === "[::1]";
+}
+
+export function isApiAuthRequired(config: OcxConfig): boolean {
+  return !isLoopbackHostname(config.hostname);
+}
+
+export function assertServerAuthConfig(config: OcxConfig): void {
+  if (isApiAuthRequired(config) && !configuredApiAuthToken(config)) {
+    throw new Error("OPENCODEX_API_AUTH_TOKEN is required when binding opencodex to a non-loopback hostname");
+  }
+}
+
+export function hasValidApiAuth(req: Request, config: OcxConfig): boolean {
+  if (!isApiAuthRequired(config)) return true;
+  const expected = configuredApiAuthToken(config);
+  const actual = req.headers.get("x-opencodex-api-key")?.trim();
+  if (!expected || !actual) return false;
+  const enc = new TextEncoder();
+  const expectedBytes = enc.encode(expected);
+  const actualBytes = enc.encode(actual);
+  return expectedBytes.length === actualBytes.length && timingSafeEqual(actualBytes, expectedBytes);
+}
+
+function requireApiAuth(req: Request, config: OcxConfig, kind: "management" | "data-plane"): Response | null {
+  if (hasValidApiAuth(req, config)) return null;
+  if (kind === "management") return jsonResponse({ error: "opencodex API key required" }, 401);
+  return formatErrorResponse(401, "authentication_error", "opencodex API key required");
+}
+
+function copyIfDefined<K extends keyof OcxProviderConfig>(
+  out: Record<string, unknown>,
+  provider: OcxProviderConfig,
+  key: K,
+): void {
+  const value = provider[key];
+  if (value !== undefined) out[key as string] = value as unknown;
+}
+
+export function safeConfigDTO(config: OcxConfig): unknown {
+  const providers: Record<string, Record<string, unknown>> = {};
+  for (const [name, provider] of Object.entries(config.providers)) {
+    const dto: Record<string, unknown> = {
+      adapter: provider.adapter,
+      baseUrl: provider.baseUrl,
+      hasApiKey: !!provider.apiKey,
+      hasHeaders: !!provider.headers && Object.keys(provider.headers).length > 0,
+    };
+    for (const key of [
+      "defaultModel",
+      "authMode",
+      "liveModels",
+      "models",
+      "contextWindow",
+      "modelContextWindows",
+      "reasoningEfforts",
+      "modelReasoningEfforts",
+      "noVisionModels",
+      "noReasoningModels",
+      "noTemperatureModels",
+      "noTopPModels",
+      "noPenaltyModels",
+      "autoToolChoiceOnlyModels",
+      "preserveReasoningContentModels",
+      "escapeBuiltinToolNames",
+    ] as const) {
+      copyIfDefined(dto, provider, key);
+    }
+    providers[name] = dto;
+  }
+  return {
+    port: config.port,
+    hostname: config.hostname ?? "127.0.0.1",
+    defaultProvider: config.defaultProvider,
+    codexAutoStart: codexAutoStartEnabled(config),
+    websockets: config.websockets,
+    providers,
+  };
+}
+
 async function handleManagementAPI(req: Request, url: URL, config: OcxConfig): Promise<Response | null> {
   if ((req.method === "POST" || req.method === "PUT" || req.method === "DELETE") && !isLocalOrigin(req)) {
     return jsonResponse({ error: "cross-origin request blocked" }, 403);
@@ -481,12 +760,7 @@ async function handleManagementAPI(req: Request, url: URL, config: OcxConfig): P
   }
 
   if (url.pathname === "/api/config" && req.method === "GET") {
-    const safeConfig = JSON.parse(JSON.stringify(config));
-    safeConfig.codexAutoStart = codexAutoStartEnabled(config);
-    for (const prov of Object.values(safeConfig.providers as Record<string, OcxProviderConfig>)) {
-      if (prov.apiKey) prov.apiKey = prov.apiKey.slice(0, 8) + "...";
-    }
-    return jsonResponse(safeConfig);
+    return jsonResponse(safeConfigDTO(config));
   }
 
   if (url.pathname === "/api/config" && req.method === "PUT") {
@@ -561,7 +835,7 @@ async function handleManagementAPI(req: Request, url: URL, config: OcxConfig): P
     let body: { name?: string; provider?: OcxProviderConfig; setDefault?: boolean };
     try { body = await req.json(); } catch { return jsonResponse({ error: "invalid JSON body" }, 400); }
     const name = body.name?.trim();
-    const prov = body.provider;
+    const prov = body.provider ? stripCodexRuntimeProviderFields(body.provider) : undefined;
     if (!name || !prov?.adapter || !prov?.baseUrl) {
       return jsonResponse({ error: "name, provider.adapter and provider.baseUrl are required" }, 400);
     }
@@ -572,6 +846,8 @@ async function handleManagementAPI(req: Request, url: URL, config: OcxConfig): P
     config.providers[name] = prov;
     if (body.setDefault) config.defaultProvider = name;
     save(config);
+    const { clearModelCache } = await import("./model-cache");
+    clearModelCache(name);
     await refreshCodexCatalogBestEffort();
     return jsonResponse({ success: true, name });
   }
@@ -582,7 +858,8 @@ async function handleManagementAPI(req: Request, url: URL, config: OcxConfig): P
     const { saveConfig: save } = await import("./config");
     delete config.providers[name];
     save(config);
-    // Drop its models from Codex's catalog immediately (re-sync + cache bust) so removal is live.
+    const { clearModelCache: clearCache } = await import("./model-cache");
+    clearCache(name);
     await refreshCodexCatalogBestEffort();
     return jsonResponse({ success: true });
   }
@@ -694,6 +971,11 @@ async function handleManagementAPI(req: Request, url: URL, config: OcxConfig): P
     return jsonResponse({ success: true, message: "Proxy stopping, native Codex restored." });
   }
 
+  if (url.pathname.startsWith("/api/codex-auth/")) {
+    const { handleCodexAuthAPI } = await import("./codex-auth-api");
+    return handleCodexAuthAPI(req, url, config);
+  }
+
   return null;
 }
 
@@ -710,15 +992,23 @@ async function fetchAllModels(config: OcxConfig): Promise<CatalogModel[]> {
 
 export function startServer(port?: number) {
   const config = loadConfig();
+  assertServerAuthConfig(config);
   // Refresh OAuth provider presets (models/noReasoningModels) from the registry so a proxy update
   // adding/dropping models reaches existing configs on start — not just fresh installs.
   reconcileOAuthProviders(config);
+  // Ensure the ChatGPT passthrough provider exists so gpt-* models route correctly.
+  if (!config.providers["chatgpt"]) {
+    upsertOAuthProvider(config, "chatgpt");
+    saveConfig(config);
+  }
   // Seed default featured subagent models on first run only (UNSET → defaults). A user-set list,
   // even [], is left alone so GUI removals persist.
   if (config.subagentModels === undefined) {
     config.subagentModels = [...DEFAULT_SUBAGENT_MODELS];
     saveConfig(config);
   }
+  invalidateCodexModelsCache();
+
   const listenPort = port ?? config.port ?? 10100;
   setCorsOrigin(listenPort);
 
@@ -736,10 +1026,34 @@ export function startServer(port?: number) {
       // Responses WebSocket (phase 120.2). Codex upgrades the same /v1/responses path; auth is
       // handshake-time only, so capture inbound headers and thread them into the pipeline.
       if (url.pathname === "/v1/responses" && req.headers.get("upgrade")?.toLowerCase() === "websocket") {
+        const apiAuthError = requireApiAuth(req, config, "data-plane");
+        if (apiAuthError) return apiAuthError;
         if (!isLocalOrigin(req)) {
           return formatErrorResponse(403, "origin_rejected", "WebSocket upgrade blocked: non-local Origin");
         }
-        if (server.upgrade(req, { data: { headers: selectForwardHeaders(req.headers) } })) return undefined as unknown as Response;
+        let authCtx: CodexAuthContext;
+        try {
+          authCtx = await resolveCodexAuthContext(req.headers, config);
+        } catch (err) {
+          if (err instanceof CodexAccountCooldownError) {
+            return formatErrorResponse(429, "rate_limit_error", "Selected Codex account is cooling down");
+          }
+          if (err instanceof CodexThreadAffinityExpiredError) {
+            return formatErrorResponse(409, "invalid_request_error", "Codex thread account affinity expired; start a new session");
+          }
+          if (err instanceof CodexAuthContextError) {
+            const safeAccountLabel = formatCodexProviderForLog("chatgpt", err.accountId, config);
+            console.error(`[codex-auth] Pool account ${safeAccountLabel} token failed during websocket upgrade; reauthentication required`);
+            return formatErrorResponse(401, "authentication_error", "Selected Codex account needs reauthentication");
+          }
+          throw err;
+        }
+        if (server.upgrade(req, {
+          data: {
+            headers: selectForwardHeadersForAuthContext(req.headers, authCtx),
+            authContext: authCtx,
+          },
+        })) return undefined as unknown as Response;
         return formatErrorResponse(426, "upgrade_required", "WebSocket upgrade failed");
       }
 
@@ -748,6 +1062,8 @@ export function startServer(port?: number) {
       }
 
       if (url.pathname.startsWith("/api/")) {
+        const apiAuthError = requireApiAuth(req, config, "management");
+        if (apiAuthError) return apiAuthError;
         const mgmtResponse = await handleManagementAPI(req, url, config);
         if (mgmtResponse) return mgmtResponse;
       }
@@ -774,6 +1090,8 @@ export function startServer(port?: number) {
       }
 
       if (url.pathname === "/v1/responses" && req.method === "POST") {
+        const apiAuthError = requireApiAuth(req, config, "data-plane");
+        if (apiAuthError) return apiAuthError;
         if (!isLocalOrigin(req)) {
           return formatErrorResponse(403, "origin_rejected", "cross-origin data-plane request blocked");
         }
@@ -799,6 +1117,9 @@ export function startServer(port?: number) {
       // Responses WebSocket data plane (phase 120.2). Re-frames the same SSE pipeline onto the
       // socket: parse response.create → run handleResponses unchanged → pump its SSE body as WS
       // Text frames. response.processed is a no-op ack. close() aborts the upstream (RC2 parity).
+      open(ws: ServerWebSocket<WsData>) {
+        registerCodexWebSocket(ws);
+      },
       message(ws: ServerWebSocket<WsData>, raw: string | Buffer) {
         let frame: Record<string, unknown>;
         try {
@@ -840,14 +1161,29 @@ export function startServer(port?: number) {
             body: JSON.stringify({ ...payload, stream: true }),
           });
           try {
+            assertCodexAuthContextNotCooled(ws.data.authContext);
+            let terminalRecorder: ((status: ResponsesTerminalStatus) => void) | undefined;
             const response = await handleResponses(req, config, logCtx, {
               forceEmptyResponseId: true,
               abortSignal: turnAbort.signal,
+              authContext: ws.data.authContext,
+              selectedForwardHeaders: ws.data.headers,
+              recordTerminalOutcomes: false,
+              setTerminalOutcomeRecorder: recorder => {
+                terminalRecorder = recorder;
+              },
             });
-            await sendResponseToWebSocket(ws, response, isCurrent);
+            await sendResponseToWebSocket(ws, response, isCurrent, { onTerminal: terminalRecorder });
           } catch (err) {
             if (!isCurrent()) return;
             try {
+              if (err instanceof CodexAccountCooldownError) {
+                sendJsonFrame(ws, buildWsErrorFrame(429, {
+                  type: "rate_limit_error",
+                  message: "Selected Codex account is cooling down",
+                }));
+                return;
+              }
               sendJsonFrame(ws, buildWsErrorFrame(502, {
                 type: "proxy_error",
                 message: err instanceof Error ? err.message : String(err),
@@ -861,6 +1197,7 @@ export function startServer(port?: number) {
         })();
       },
       close(ws: ServerWebSocket<WsData>) {
+        unregisterCodexWebSocket(ws);
         ws.data.cancel?.(); // RC2: abort the upstream when the client disconnects
       },
     },

package/src/types.ts

@@ -200,6 +200,14 @@ export interface OcxConfig {
   webSearchSidecar?: OcxWebSearchSidecarConfig;
   /** Vision sidecar: describe images via a gpt vision model so text-only models can "see" them. */
   visionSidecar?: OcxVisionSidecarConfig;
+  /** Codex multi-account pool. */
+  codexAccounts?: CodexAccount[];
+  /** Active pool account id for next session. undefined = main (passthrough as-is). */
+  activeCodexAccountId?: string;
+  /** Auto-switch threshold (0-100). Default 80. 0 = disabled. */
+  autoSwitchThreshold?: number;
+  /** Consecutive non-2xx upstream responses before switching future new threads. Default 3. 0 = disabled. */
+  upstreamFailoverThreshold?: number;
 }
 
 export interface OcxVisionSidecarConfig {
@@ -285,3 +293,27 @@ export interface OcxProviderConfig {
    */
   noVisionModels?: string[];
 }
+
+export interface CodexAccount {
+  id: string;
+  email: string;
+  plan?: string;
+  chatgptAccountId?: string;
+  logLabel?: string;
+  isMain: boolean;
+}
+
+export interface CodexAccountCredentials {
+  accessToken: string;
+  refreshToken: string;
+  expiresAt: number;
+  chatgptAccountId: string;
+}
+
+export interface CodexAccountCredentialRecord {
+  credential?: CodexAccountCredentials;
+  generation: number;
+  refreshGrantFingerprint?: string;
+  deletedAt?: number;
+  replacedAt?: number;
+}