UNPKG

@bitkyc08/opencodex

Version:

Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code

1,932 lines • 101 kB
import type { Server, ServerWebSocket } from "bun";
import type { StartServerDeps } from "./startup-warnings";
import {
  GUI_PAIRING_EXCHANGE_BODY_LIMIT,
  REMOTE_WORKSPACE_PAIRING_BODY_LIMIT,
  readBoundedRequestText,
  withRemoteCatalogKeyId,
} from "./bounded-request";
import {
  LIVE_SIDEBAND_UPSTREAM_OPEN_TIMEOUT_MS,
  MAX_WS_FRAME_BYTES,
  WEBSOCKET_IDLE_TIMEOUT_SECONDS,
  attachLiveSidebandUpstream,
  closeLiveSideband,
  closeLiveSidebandBeforeUpgrade,
  enqueueLiveSidebandPendingFrame,
  exceedsLiveSidebandFrameByteLimit,
  openLiveSidebandUpstream,
  sendUpstreamFrame,
  webSocketFrameBytes,
} from "./live-sideband";
import {
  withRequestLogId,
} from "./startup-warnings";

import { remoteWorkspaceEnabled } from "../../remote-control/workspace-activation";
import { isClaudeInterceptedPath } from "../../claude/intercept/listener";
import { markActivity } from "../../lib/sidecar-tracker";
import { knownModelIdsForProvider } from "../../router";
import {
  buildWarmupCompletionFrames,
  buildWsErrorFrame,
  selectForwardHeaders,
  sendJsonFrame,
  buildResponsesWsData,
  sendResponseToWebSocket,
  sendTextFrame,
  type WsData,
} from "../ws-bridge";
import { websocketsEnabled } from "../../config";
import { metricsExportEnabled } from "../../config/feature-flags";
import { grokDefaultReasoningEffort } from "../../grok/effort";
import { OPENAI_CODEX_PROVIDER_ID } from "../../providers/openai-tiers";
import { providerCodexAccountMode } from "../../providers/registry";
import {
  codexAccountNamespaceEntries,
  isMainCodexAccountTarget,
} from "../../codex/account-namespaces";
import { MAIN_CODEX_ACCOUNT_ID } from "../../codex/main-account";
import {
  availableAccountGatedNativeModels,
  codexModelEntitlementStateForAccount,
} from "../../codex/model-entitlements";
import { resolveAdmittedCodexModelEntitlements } from "../../codex/model-entitlement-admission";
import { CatalogGatherBusyError } from "../../codex/catalog/provider-fetch";
import {
  registerCodexWebSocket,
  tryReserveCodexWebSocket,
  unregisterCodexWebSocket,
  updateCodexWebSocketAuthContext,
} from "../../codex/websocket-registry";
import {
  rootFallbackPayload,
  serveGuiFile,
  serveSessionBootstrap,
} from "../gui-static";
import {
  formatErrorResponse,
  type ResponsesTerminalStatus,
} from "../../bridge";
import {
  isDraining,
  registerTurn,
  tryAdmitTurn,
  unregisterTurn,
  type ActiveTurnLease,
} from "../lifecycle";
import {
  addFinalRequestLog,
  httpStatusForRequestLogTerminal,
  inspectResponseLogSsePayload,
  nextRequestLogId,
  recordFirstOutput,
  type RequestLogContext,
  type RequestLogEntry,
} from "../request-log";
import { sessionLaneIdFromRequest } from "../request-log-conversation";
import { responseWithDeferredRequestLog } from "../relay";
import { createRequestMetricsOwner } from "../request-metrics";
import { cachedKiroQuotaMetricRows } from "../../providers/kiro-quota-metrics";
import {
  corsHeaders,
  managementCorsHeaders,
  isAllowedRequestOrigin,
  isAllowedManagementOrigin,
  isApiAuthRequired,
  isLoopbackHostname,
  jsonResponse,
  admissionFields,
  resolveApiAuth,
  resolveResponsesApiAuth,
  type RequestPolicyView,
  withCors,
  withManagementCors,
} from "../auth-cors";
import { managementSessionIssuance } from "../management-auth";
import { resolveAdmissionModelScope, routeAllowedByScope } from "../admission-model-scope";
import {
  disableResponsesRequestTimeout,
  handleResponses,
  handleResponsesCompact,
} from "../responses";
import {
  handleClaudeCountTokens,
  handleClaudeMessages,
} from "../claude-messages";
import { handleChatCompletions } from "../chat-completions";
import { anthropicErrorResponse } from "../../claude/outbound";
import {
  buildDesktop3pRegistry,
  generateDesktop3pModels,
} from "../../claude/desktop-3p";
import { buildDesktopDiscoveryInputs } from "../../claude/desktop-discovery-inputs";
import { handleImages } from "../images";
import {
  handleLive,
  logLiveSidebandFrame,
  parseLiveSidebandTarget,
  resolveLiveSidebandUpgrade,
} from "../live";
import { handleAudioTranscriptions } from "../audio-transcriptions";
import {
  resolveAudioAdmission,
  TRANSCRIPTION_MODEL,
} from "../audio-upstream";
import { resolveAudioClient } from "../audio-client";
import { resolveDictationSocket } from "../audio-dictation";
import {
  handleExternalLive,
  resolveExternalLiveSocket,
} from "../audio-live";
import {
  EXTERNAL_CALL_PREFIX,
  type LiveCallBindings,
} from "../live-call-bindings";
import { clearableDeadline } from "../../lib/abort";
import { handleSearch } from "../search";
import { handleContextHistory } from "../context-history";
import {
  codexCompatibleUrl,
  contextEndpoint,
  contextRelayActivated,
} from "../../codex/context-compat";
import {
  fetchAllModels,
  handleManagementAPI,
  VERSION,
  type ManagementApiDeps,
} from "../management-api";
import {
  issueGuiSession,
  managementPrincipal,
  requireManagementAuth,
  type ManagementAuthState,
  type ManagementSessionControl,
} from "../management-auth";
import {
  LOCAL_ATTESTATION_CHALLENGE_HEADER,
  LOCAL_ATTESTATION_PROOF_HEADER,
  createLocalAttestationProof,
} from "../../lib/local-management-attestation";
import { SYSTEM_RESTART_CAPABILITY_VERSION } from "../../lib/system-restart-contract";
import { LOCAL_MANAGEMENT_NONCE_HEADER } from "../../lib/local-management-capability";
import { LOCAL_PROVIDER_RELOAD_CAPABILITY_VERSION } from "../../lib/local-provider-reload-contract";
import { LOCAL_ASIDE_SYNC_CAPABILITY_VERSION } from "../../lib/local-aside-sync-contract";
import {
  GUI_PAIR_BROWSER_ORIGIN_HEADER,
  GUI_PAIR_CAPABILITY_VERSION,
  GUI_PAIR_PATH,
} from "../../lib/gui-pair-capability";
import {
  GuiPairingGrantRateLimitError,
  consumeGuiPairingGrant,
  createGuiPairingGrant,
} from "../gui-session";
import { recordCursorSeen } from "../../integrations/cursor-seen";
import { detectCursorInstalls } from "../../integrations/cursor-detect";
import { loadCursorEffortTable } from "../../integrations/cursor-effort-table";
import {
  expandCursorEffortRow,
  knownEffortRowIds,
} from "../effort-row";
import {
  catalogFastRowEligible,
  expandFastRow,
} from "../fast-row";
import type { OcxConfig } from "../../types";
import type { PackageTreeIntegrityGuard } from "../../lib/package-tree-integrity";
import type { ReadinessGate } from "../readiness";
import type { WorkflowRefusalLog } from "../workflow-refusal";

import { readyProtocolMetadata } from "../../remote/protocol";
import { modelCapabilityFields } from "../models-capabilities";
import { createWebsocketHandler } from "./websocket-handler";

export type ServerIngress = "public" | "unauthenticated-loopback" | "hub-management" | "claude-intercept" | "hub-link";

export function trustedLoopbackForIngress(ingress: ServerIngress, hostname: string): boolean {
  return ingress === "unauthenticated-loopback"
    || (ingress === "public" && isLoopbackHostname(hostname));
}

/**
 * Routes the Claude intercept TLS listener may reach. Everything else on that socket is relayed
 * to the real upstream by the listener itself, so a request that lands here with another path
 * is a bug, not a client — refuse it.
 */
export function claudeInterceptRouteAllowed(url: URL, req: Request): boolean {
  return isClaudeInterceptedPath(url.pathname, req.method);
}

export interface ServeOptionsContext {
  readonly server: Server<WsData>;
  readonly boundPort: number | null;
  readonly remoteWorkspaceStopping: boolean;

  drainingResponse: (req: Request, policy: RequestPolicyView) => Response;
  ingressForServer: (requestServer: Server<WsData>) => ServerIngress;
  loopbackRouteAllowed: (url: URL, req: Request) => boolean;
  managementIngressRouteAllowed: (url: URL, req: Request) => boolean;
  linkRouteAllowed: (url: URL, req: Request) => boolean;
  onAuthenticatedCatalog: (apiKeyId: string) => void;
  linkPolicy: () => RequestPolicyView;
  packageTreeChangedResponse: (
    req: Request,
    policy: RequestPolicyView,
    message: string,
  ) => Response;
  serverBusyResponse: (
    req: Request,
    resource: string,
    policy: RequestPolicyView,
  ) => Response;
  runAdmittedHttpTurn: (
    req: Request,
    policy: RequestPolicyView,
    work: (lease: ActiveTurnLease) => Promise<Response>,
    refusalLog?: WorkflowRefusalLog,
  ) => Promise<Response>;

  config: OcxConfig;
  inboundBodyLimitBytes: number;
  listenPort: number;
  liveCallBindings: LiveCallBindings;
  loadRemoteWorkspaceRuntime: () => Promise<
    typeof import("../../remote-control/workspace-runtime")
  >;
  localAttestationSecret: string;
  loopbackPolicy: () => RequestPolicyView;
  managementApiDeps: ManagementApiDeps;
  managementAuth: ManagementAuthState;
  managementSessionControl: ManagementSessionControl;
  packageTreeIntegrity: PackageTreeIntegrityGuard;
  readinessGate: ReadinessGate;

  deps: StartServerDeps;
  port: number | undefined;
}

export function createServeOptions(ctx: ServeOptionsContext) {
  const {
    drainingResponse,
    ingressForServer,
    loopbackRouteAllowed,
    managementIngressRouteAllowed,
    linkRouteAllowed, onAuthenticatedCatalog,
    linkPolicy,
    packageTreeChangedResponse,
    serverBusyResponse,
    runAdmittedHttpTurn,
    config,
    inboundBodyLimitBytes,
    listenPort,
    liveCallBindings,
    loadRemoteWorkspaceRuntime,
    localAttestationSecret,
    loopbackPolicy,
    managementApiDeps,
    managementAuth,
    managementSessionControl,
    packageTreeIntegrity,
    readinessGate,
    deps,
    port,
  } = ctx;
  void port;
  const requestMetrics = metricsExportEnabled(config)
    ? createRequestMetricsOwner(Date.now() / 1000, cachedKiroQuotaMetricRows) : undefined;
  const requestMetricsLogContext = requestMetrics ? { requestMetricsRecorder: requestMetrics } : {};
  const requestManagementApiDeps: ManagementApiDeps = requestMetrics
    ? { ...managementApiDeps, requestMetrics: { snapshot: () => requestMetrics.snapshot() } }
    : managementApiDeps;
  const serveOptions = {
      idleTimeout: 255,
      // Bun rejects an oversized body before `fetch` runs, so the listener has to be raised
      // with the admission limit or the opt-in would do nothing. Fixed at bind time: a live
      // `maxInboundBodyBytes` edit needs a restart, which the config doc states.
      maxRequestBodySize: inboundBodyLimitBytes,
      async fetch(req: Request, requestServer: Server<WsData>): Promise<Response> {
      const ingress = ingressForServer(requestServer);
      const requestUrl = codexCompatibleUrl(req.url);
      const linkPolicyView = ingress === "hub-link" ? linkPolicy() : undefined;
      // The unauthenticated loopback listener (#1102) serves a fixed allowlist and nothing
      // else. Rejecting here, before any handler runs, is what keeps the surface from growing
      // silently when a route is added below.
      if (ingress === "unauthenticated-loopback" && !loopbackRouteAllowed(codexCompatibleUrl(req.url), req)) {
        return withCors(
          formatErrorResponse(404, "not_found", `Unknown endpoint: ${req.method} ${new URL(req.url).pathname}`),
          req,
          loopbackPolicy(),
        );
      }
      if (ingress === "hub-link" && !linkRouteAllowed(requestUrl, req)) {
        return withCors(
          formatErrorResponse(404, "not_found", `Unknown endpoint: ${req.method} ${new URL(req.url).pathname}`),
          req,
          linkPolicyView!,
        );
      }
      // Tailscale Serve terminates only on this separately bound loopback socket. Reject before
      // dispatch so no data, readiness, health, WebSocket, or unknown-static handler can run.
      if (ingress === "hub-management" && !managementIngressRouteAllowed(codexCompatibleUrl(req.url), req)) {
        return withCors(
          formatErrorResponse(404, "not_found", `Unknown endpoint: ${req.method} ${new URL(req.url).pathname}`),
          req,
          config,
        );
      }
      if (ingress === "claude-intercept" && !claudeInterceptRouteAllowed(codexCompatibleUrl(req.url), req)) {
        return withCors(
          formatErrorResponse(404, "not_found", `Unknown endpoint: ${req.method} ${new URL(req.url).pathname}`),
          req,
          loopbackPolicy(),
        );
      }
      // Auth and CORS decisions below read `policy`, not `config`. For the public listener the
      // two are the same object, so its behaviour is unchanged; for the loopback listener the
      // view substitutes 127.0.0.1 as the bind address, which is what routes it through the
      // same code path a plain loopback bind has always taken — Host-header check included.
      // Routing, provider selection and response bodies keep using `config`.
      // The Claude intercept listener is loopback by construction (the CONNECT proxy binds
      // 127.0.0.1 and the request was rewritten onto a loopback origin), and its callers carry
      // Anthropic credentials, not opencodex admission tokens — so it takes the loopback view too.
      const policy: RequestPolicyView = ingress === "hub-link"
        ? linkPolicyView!
        : ingress === "unauthenticated-loopback" || ingress === "claude-intercept"
          ? loopbackPolicy()
          : config;
      if (ingress === "hub-link") {
        const admission = resolveApiAuth(req, policy);
        if (!admission) return withCors(formatErrorResponse(401, "authentication_error", "opencodex API key required"), req, policy);
        if (requestUrl.pathname === "/v1/catalog" && requestUrl.search === ""
          && (req.method === "GET" || req.method === "HEAD")
          && admission.kind === "configured") onAuthenticatedCatalog(admission.keyId);
      }
      const url = requestUrl;
      const admissionOptions = { linkIngress: policy.linkIngress?.allowedKeyIds };
      markActivity(`${req.method} ${url.pathname}`);

      // Readiness is exact-GET on the literal /readyz path. Compare the DECODED
      // pathname so an encoded variant like /readyz%2F (which decodes to
      // /readyz/) cannot bypass the exact-path rejection and reach the GUI
      // fallback (serveGuiFile decodes the pathname and would serve index.html
      // with 200). Malformed percent-sequences fall back to the raw pathname,
      // which still cannot match the exact literal below.
      let readyzPath: string | undefined;
      try {
        const decoded = decodeURIComponent(url.pathname);
        if (decoded === "/readyz" || decoded === "/readyz/") readyzPath = decoded;
      } catch { /* malformed encoding — not a readiness path */ }

      const packageTreeStatus = packageTreeIntegrity.status();
      if (!packageTreeStatus.ok && (
        url.pathname === "/healthz"
        || readyzPath !== undefined
        || url.pathname.startsWith("/v1/")
      )) {
        const message = "OpenCodex package files changed while this proxy was running; it restarts on its own, or run 'ocx restart' ('ocx service restart' for a background service).";
        const fencedPort = ctx.boundPort ?? requestServer.port ?? listenPort;
        const fencedHealth = url.pathname === "/healthz";
        const response = fencedHealth || readyzPath !== undefined
          ? jsonResponse({
              status: "restart_required",
              service: "opencodex",
              version: VERSION,
              uptime: process.uptime(),
              pid: process.pid,
              port: fencedPort,
              // Identity stays attestable while readiness is fenced (#5496): the CLI can only
              // restart or stop what it can prove it owns, and an unverified 503 body is not proof.
              // installedVersion is what an in-place respawn will run from the replaced tree.
              ...(fencedHealth ? {
                restartCapability: SYSTEM_RESTART_CAPABILITY_VERSION,
                installedVersion: packageTreeIntegrity.installedVersion?.(),
              } : {}),
              error: { code: "package_tree_changed", message },
            }, 503, req, policy)
          : packageTreeChangedResponse(req, policy, message);
        const headers = new Headers(response.headers);
        headers.set("Retry-After", "5");
        const challenge = fencedHealth ? req.headers.get(LOCAL_ATTESTATION_CHALLENGE_HEADER) : null;
        const proof = challenge ? createLocalAttestationProof(localAttestationSecret, challenge, process.pid, fencedPort) : null;
        if (proof) headers.set(LOCAL_ATTESTATION_PROOF_HEADER, proof);
        return new Response(response.body, { status: 503, headers });
      }

      if (req.method === "OPTIONS") {
        // /readyz is exact-GET only; OPTIONS (like POST and the trailing-slash
        // path) must answer the deterministic JSON 404, never the generic 204
        // preflight response that the SPA fallback would otherwise allow.
        if (readyzPath !== undefined) {
          return withCors(formatErrorResponse(404, "not_found", `Unknown endpoint: ${req.method} ${url.pathname}`), req, policy);
        }
        const managementPreflight = url.pathname.startsWith("/api/");
        const allowed = managementPreflight
          ? isAllowedManagementOrigin(req, config)
          : isAllowedRequestOrigin(req, policy);
        if (!allowed) {
          return new Response(null, { status: 403, headers: corsHeaders() });
        }
        return new Response(null, {
          status: 204,
          headers: managementPreflight ? managementCorsHeaders(req, config) : corsHeaders(req, policy),
        });
      }

      // An OCX-only executor exchanges one short-lived pairing code for a device-scoped
      // token. This is intentionally outside /api: management auth belongs to the browser
      // that created the grant, while the new device owns only that one-time code.
      if (url.pathname === "/remote-workspace/pair" && req.method === "POST") {
        if (!remoteWorkspaceEnabled(config)) {
          return Response.json({ error: "Remote Workspace is not enabled on this OpenCodex instance." }, { status: 404 });
        }
        // Browser JavaScript must use the authenticated dashboard route. Refusing Origin-bearing
        // requests leaves this exchange to an explicit OCX device process and avoids turning a
        // copied pairing code into a cross-site enrollment action.
        if (req.headers.get("origin") !== null) {
          return Response.json({ error: "Remote Workspace device pairing does not accept browser-origin requests." }, {
            status: 403,
            headers: { "cache-control": "no-store" },
          });
        }
        const [{ remoteWorkspaceHubForConfig }, { RemoteWorkspacePairingRateLimitError }] = await Promise.all([
          loadRemoteWorkspaceRuntime(),
          import("../../remote-control/workspace-hub"),
        ]);
        if (ctx.remoteWorkspaceStopping) return Response.json({ error: "Remote Workspace is stopping." }, { status: 503 });
        const hub = deps.managementApi?.remoteWorkspaceHub ?? remoteWorkspaceHubForConfig(config);
        // A loopback socket alone cannot prove that Tailscale Serve supplied its identity header:
        // another local process can connect directly and forge it. Pairing therefore uses only the
        // kernel-observed peer on every listener; proxied management users intentionally share the
        // loopback bucket rather than gaining a header-rotation bypass.
        const peer = requestServer.requestIP(req)?.address ?? "unknown";
        const pairingSource = `${ingress}:${peer}`;
        const rateLimitResponse = (error: unknown): Response | null => {
          if (!(error instanceof RemoteWorkspacePairingRateLimitError)) return null;
          return Response.json({ error: "Remote Workspace pairing is temporarily rate limited." }, {
            status: 429,
            headers: {
              "cache-control": "no-store",
              "retry-after": String(error.retryAfterSeconds),
            },
          });
        };
        try {
          // Check the existing source block before reading or parsing an attacker-controlled body.
          // pairDevice checks again after the await and records only code-shaped authentication
          // failures, so malformed JSON cannot allocate one limiter entry per request.
          hub.assertPairingSourceAllowed(pairingSource);
        } catch (error) {
          const limited = rateLimitResponse(error);
          if (limited) return limited;
          throw error;
        }
        const declaredLength = Number(req.headers.get("content-length") ?? "0");
        if (!Number.isFinite(declaredLength) || declaredLength > REMOTE_WORKSPACE_PAIRING_BODY_LIMIT) {
          return Response.json({ error: "Remote Workspace pairing body is too large." }, { status: 413 });
        }
        const text = await readBoundedRequestText(req, REMOTE_WORKSPACE_PAIRING_BODY_LIMIT);
        if (text === null) return Response.json({ error: "Remote Workspace pairing body is too large." }, { status: 413 });
        if (ctx.remoteWorkspaceStopping) return Response.json({ error: "Remote Workspace is stopping." }, { status: 503 });
        let body: unknown;
        try { body = JSON.parse(text); }
        catch { return Response.json({ error: "Invalid Remote Workspace pairing request." }, { status: 400 }); }
        if (!body || typeof body !== "object" || Array.isArray(body)) {
          return Response.json({ error: "Invalid Remote Workspace pairing request." }, { status: 400 });
        }
        const record = body as Record<string, unknown>;
        const required = ["code", "name", "platform", "publicKey", "roots"];
        const allowed = new Set([...required, "capabilities"]);
        if (required.some(key => !Object.hasOwn(record, key))
          || Object.keys(record).some(key => !allowed.has(key))) {
          return Response.json({ error: "Invalid Remote Workspace pairing request." }, { status: 400 });
        }
        try {
          const paired = hub.pairDevice(record, pairingSource);
          return Response.json(paired, { status: 201, headers: { "cache-control": "no-store" } });
        } catch (error) {
          const limited = rateLimitResponse(error);
          if (limited) return limited;
          const message = error instanceof Error ? error.message : "Remote Workspace pairing failed.";
          const conflict = /already in use|limit reached/i.test(message);
          return Response.json({ error: message }, {
            status: conflict ? 409 : 401,
            headers: { "cache-control": "no-store" },
          });
        }
      }

      // Each executor holds one device-scoped bearer and opens one outbound WSS. The token is
      // authenticated only at upgrade and never enters ws.data; subsequent frames are bound to
      // the device identity and per-session signed E2EE handshake.
      if (url.pathname === "/remote-workspace/agent" && req.headers.get("upgrade")?.toLowerCase() === "websocket") {
        if (!remoteWorkspaceEnabled(config) || req.headers.get("origin") !== null) {
          return Response.json({ error: "Remote Workspace agent upgrade refused." }, { status: 403 });
        }
        const authorization = req.headers.get("authorization") ?? "";
        const match = /^Bearer (ocxrw_[A-Za-z0-9_-]{43})$/.exec(authorization);
        if (!match) return Response.json({ error: "Remote Workspace device authentication required." }, { status: 401 });
        const { remoteWorkspaceHubForConfig } = await loadRemoteWorkspaceRuntime();
        const { RemoteWorkspaceHubAgentConnection } = await import("../../remote-control/workspace-agent-connection");
        if (ctx.remoteWorkspaceStopping) return Response.json({ error: "Remote Workspace is stopping." }, { status: 503 });
        const hub = deps.managementApi?.remoteWorkspaceHub ?? remoteWorkspaceHubForConfig(config);
        const device = hub.authenticateDeviceToken(match[1]!);
        if (!device) return Response.json({ error: "Remote Workspace device authentication failed." }, { status: 401 });
        const upgraded = requestServer.upgrade(req, {
          data: {
            kind: "remote-workspace-agent",
            remoteWorkspaceOpen: socket => {
              const connection = new RemoteWorkspaceHubAgentConnection({
                deviceId: device.id,
                devicePublicKey: device.publicKey,
                hubIdentity: hub.identity(),
                capabilities: device.capabilities,
                onCapabilities: capabilities => hub.updateDeviceCapabilities(device.id, capabilities),
                socket: {
                  send: value => {
                    if (socket.send(value) === 0) throw new Error("remote workspace socket send dropped");
                  },
                  close: (code, reason) => socket.close(code, reason),
                },
              });
              hub.attachConnection(device.id, connection);
              socket.data.remoteWorkspaceClose = () => hub.detachConnection(device.id, connection);
              return connection;
            },
          } satisfies WsData,
        });
        return upgraded
          ? undefined as unknown as Response
          : Response.json({ error: "Remote Workspace WebSocket upgrade failed." }, { status: 426 });
      }

      // 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") {
        if (isDraining()) {
          return drainingResponse(req, policy);
        }
        const admission = resolveResponsesApiAuth(req, policy);
        if (!admission) {
          return withCors(formatErrorResponse(401, "authentication_error", "opencodex API key required"), req, policy);
        }
        if (!isAllowedRequestOrigin(req, policy)) {
          return withCors(formatErrorResponse(403, "origin_rejected", "WebSocket upgrade blocked: non-local Origin"), req, policy);
        }
        // WS transport gate: Codex's built-in `openai` provider hardcodes supports_websockets=true,
        // so under Design B it always tries the WS transport first. When the feature is off, reject
        // the upgrade with 426 — codex-rs maps a connect-time UPGRADE_REQUIRED to a clean
        // session-scoped HTTP fallback (client.rs WebsocketStreamOutcome::FallbackToHttp) instead of
        // surfacing broken-pipe errors from sockets a "disabled" feature would otherwise accept.
        if (!websocketsEnabled(config)) {
          return withCors(formatErrorResponse(426, "upgrade_required", "Responses WebSocket transport is disabled; use HTTP"), req, policy);
        }
        const websocketLease = tryReserveCodexWebSocket();
        if (!websocketLease) return serverBusyResponse(req, "Codex WebSockets", policy);
        // Upgrade on the server that RECEIVED this request, not the captured `server`
        // binding. They are the same object for the public listener, but the
        // unauthenticated loopback listener (#1102) is a second Bun.serve, and handing its
        // request to the public server's upgrade would fail or cross sockets.
        if (requestServer.upgrade(req, {
          data: buildResponsesWsData(
            selectForwardHeaders(req.headers),
            admission,
            websocketLease,
            sessionLaneIdFromRequest(req.headers),
          ),
        })) return undefined as unknown as Response;
        websocketLease.release();
        return withCors(formatErrorResponse(426, "upgrade_required", "WebSocket upgrade failed"), req, policy);
      }

      if (url.pathname === "/healthz" && req.method === "GET") {
        // service/pid/port let CLI liveness reject foreign 200s and verify pid identity.
        const healthPort = ctx.server.port ?? listenPort;
        const response = jsonResponse({
          status: "ok",
          service: "opencodex",
          version: VERSION,
          uptime: process.uptime(),
          pid: process.pid,
          port: healthPort,
          restartCapability: SYSTEM_RESTART_CAPABILITY_VERSION,
          providerReloadCapability: LOCAL_PROVIDER_RELOAD_CAPABILITY_VERSION,
          asideSyncCapability: LOCAL_ASIDE_SYNC_CAPABILITY_VERSION,
          guiPairCapability: GUI_PAIR_CAPABILITY_VERSION,
        }, 200, req, policy);
        const challenge = req.headers.get(LOCAL_ATTESTATION_CHALLENGE_HEADER);
        if (challenge) {
          const proof = createLocalAttestationProof(localAttestationSecret, challenge, process.pid, healthPort);
          if (proof) response.headers.set(LOCAL_ATTESTATION_PROOF_HEADER, proof);
        }
        return response;
      }

      // Readiness: like /healthz this is exact GET and unauthenticated (so a client can
      // back off BEFORE knowing the admission token), but stricter than liveness. The
      // body carries only sanitized identity + the fixed status enum; the sync message,
      // warning text, catalog path, provider output, and account data are never exposed.
      // POST or "/readyz/" must NOT match (exact pathname + GET method): answer them
      // with a JSON 404 here so they can never be silently accepted by the GUI SPA
      // fallback (which would serve index.html with HTTP 200 once gui/dist exists).
      if (readyzPath !== undefined) {
        if (readyzPath !== "/readyz" || req.method !== "GET") {
          return withCors(formatErrorResponse(404, "not_found", `Unknown endpoint: ${req.method} ${url.pathname}`), req, policy);
        }
        // A draining proxy must never advertise ready: every data-plane branch
        // answers drainingResponse while isDraining() is set, but the one-shot
        // readiness gate is not mutated on shutdown (it is owned by the startup
        // sync). Report pending so `ocx ready --wait` and external supervisors
        // keep polling instead of promoting a proxy that is draining.
        const status = isDraining() ? "pending" : readinessGate.getStatus();
        const body = {
          service: "opencodex",
          version: VERSION,
          uptime: process.uptime(),
          pid: process.pid,
          port: ctx.boundPort ?? listenPort,
          status,
          ...readyProtocolMetadata(config, req),
        };
        if (status === "ready") {
          return jsonResponse(body, 200, req, policy);
        }
        // Pending/failed: 503 with a conservative Retry-After so well-behaved clients
        // (and `ocx ready --wait`) back off instead of hot-looping.
        const resp = jsonResponse(body, 503, req, policy);
        const headers = new Headers(resp.headers);
        headers.set("Retry-After", "1");
        return new Response(resp.body, { status: 503, headers });
      }

      if (url.pathname.startsWith("/api/")) {
        const localManagementAuth = {
          attestationSecret: localAttestationSecret,
          pid: process.pid,
          port: ctx.boundPort ?? requestServer.port ?? listenPort,
        };
        const apiAuthError = requireManagementAuth(req, managementAuth, config, localManagementAuth);
        if (apiAuthError) return withManagementCors(apiAuthError, req, config);
        // Which credential passed the gate, resolved from the same session table the
        // gate used. Consent-bearing routes need this: request headers are forgeable
        // by anything holding the admin token, the credential is not.
        const principal = managementPrincipal(req, managementAuth, config, localManagementAuth) ?? undefined;
        if (url.pathname === GUI_PAIR_PATH) {
          if (req.method !== "POST" || principal !== "gui-pair-capability" || !managementAuth.available) {
            return withManagementCors(Response.json({ error: "GUI pairing capability required" }, { status: 403 }), req, config);
          }
          try {
            const grant = createGuiPairingGrant(
              req.headers.get(GUI_PAIR_BROWSER_ORIGIN_HEADER) ?? "",
              config,
              managementAuth,
            );
            return withManagementCors(Response.json(grant, {
              status: 201,
              headers: { "Cache-Control": "no-store" },
            }), req, config);
          } catch (error) {
            const status = error instanceof GuiPairingGrantRateLimitError ? 429 : 403;
            return withManagementCors(Response.json({ error: "GUI pairing grant refused" }, {
              status,
              ...(status === 429 ? { headers: { "Retry-After": "60" } } : {}),
            }), req, config);
          }
        }
        const mgmtResponse = await handleManagementAPI(req, url, config, requestManagementApiDeps, principal, managementSessionControl, {
          trustedLoopback: trustedLoopbackForIngress(ingress, config.hostname ?? "127.0.0.1"),
          guiSessionIssuance: managementSessionIssuance(req, managementAuth),
        });
        // A local read capability authenticates the request; sign its single-use nonce so the
        // caller can tell this answer came from this process and not from whoever holds the port.
        const readNonce = principal === "local-read-capability" ? req.headers.get(LOCAL_MANAGEMENT_NONCE_HEADER) : null;
        const readProof = readNonce
          ? createLocalAttestationProof(localAttestationSecret, readNonce, process.pid, localManagementAuth.port) : null;
        if (mgmtResponse && readProof) {
          const headers = new Headers(mgmtResponse.headers);
          headers.set(LOCAL_ATTESTATION_PROOF_HEADER, readProof);
          const signed = new Response(mgmtResponse.body, { status: mgmtResponse.status, statusText: mgmtResponse.statusText, headers });
          return withManagementCors(signed, req, config);
        }
        if (mgmtResponse) return withManagementCors(mgmtResponse, req, config);
        return withManagementCors(formatErrorResponse(404, "not_found", `Unknown endpoint: ${req.method} ${url.pathname}`), req, config);
      }

      if (url.pathname === "/v1/catalog" && (req.method === "GET" || req.method === "HEAD")) {
        // #809: remote Codex clients need the model catalog, and the only prior source was
        // GET /api/catalog behind management auth — so operators had to hand out an admin
        // token to read a list of models. This route fixes that on the data plane instead of
        // widening /api/*, which stays exactly as restricted as before.
        //
        // resolveApiAuth (not resolveResponsesApiAuth) for the same reason /v1/models uses
        // it: nothing here forwards a caller credential upstream, so accepting the dedicated
        // header, a recognized bearer, or x-api-key is safe — and rejecting x-api-key would
        // 401 Anthropic-SDK clients holding a perfectly valid data credential.
        const admission = resolveApiAuth(req, policy);
        if (!admission) return withCors(formatErrorResponse(401, "authentication_error", "opencodex API key required"), req, policy);
        if (!isAllowedRequestOrigin(req, policy)) {
          return withCors(formatErrorResponse(403, "origin_rejected", "cross-origin data-plane request blocked"), req, policy);
        }
        const { serializePersistedCatalog, persistedCodexVersion, MAX_REMOTE_CATALOG_BYTES } = await import("../catalog-download");
        const serialized = await serializePersistedCatalog();
        if (serialized.body === null) {
          // Built directly rather than through formatErrorResponse: that helper derives
          // `code` from the status and message via classifyError, and these two need stable,
          // specific codes. `catalog_not_found` in particular is what lets a caller — and
          // tests/server/api-key-attribution.test.ts — tell "this route exists and has no catalog"
          // apart from "this route is gone", which is the difference between admission proof
          // and a vacuous pass.
          return withCors(
            new Response(JSON.stringify({
              error: { type: "invalid_request_error", code: "catalog_not_found", message: "no materialized catalog is available" },
            }), {
              status: 404,
              headers: { "content-type": "application/json" },
            }),
            req,
            policy,
          );
        }
        // Size policy belongs to this route, not the shared serializer: the management route
        // must keep its existing behavior for a catalog of any supported size.
        if (serialized.bytes !== undefined && serialized.bytes > MAX_REMOTE_CATALOG_BYTES) {
          return withCors(
            new Response(JSON.stringify({
              error: { type: "server_error", code: "catalog_too_large", message: "catalog exceeds the maximum served size" },
            }), {
              status: 507,
              headers: { "content-type": "application/json" },
            }),
            req,
            policy,
          );
        }
        const headers: Record<string, string> = {
          "content-type": "application/json",
          // Identity-varying content behind a credential: never let a shared cache keep it,
          // and never hand out a validator it could revalidate with. `no-cache` alone does
          // not prevent storage — it forces revalidation, and the revalidation is exactly
          // what would cross identities here, because this body varies by key type and key
          // id while the ETag would be derived from bytes alone. A store keyed on URL plus
          // validator could then serve one credential's representation to another. Proving
          // an identity-partitioned cache key across every intermediary in the path is a
          // much larger commitment than the bandwidth a 304 saves on this payload, so this
          // route declines the trade: no-store, no ETag, no 304.
          //
          // GET /api/catalog keeps its validator. That route is management-authenticated
          // and loopback-scoped, and its representation does not vary by data-key identity.
          "cache-control": "no-store",
        };
        const version = await persistedCodexVersion();
        if (version) headers["x-opencodex-codex-version"] = version;
        // No conditional handling: with no validator emitted, an If-None-Match on this route
        // can only have been guessed or copied from elsewhere, and honoring it would
        // reintroduce the cross-identity path above. Every request gets the full body.
        if (serialized.bytes !== undefined) headers["content-length"] = String(serialized.bytes);
        // HEAD returns identical status and headers with no body.
        return withRemoteCatalogKeyId(
          withCors(
            new Response(req.method === "HEAD" ? null : serialized.body, { status: 200, headers }),
            req,
            policy,
          ),
          admission,
        );
      }

      if (url.pathname === "/v1/usage" && req.method === "GET") {
        const { handleHubUsage } = await import("../hub-usage");
        return handleHubUsage(req, config, policy);
      }

      if (url.pathname === "/v1/hub-state" && (req.method === "GET" || req.method === "HEAD")) {
        // #4236: a connected client had no way to learn which providers this hub can actually
        // serve, so `ocx status` on the client reported the CLIENT's empty credential store as
        // if it were the truth — "xai ✗ not logged in" on a machine whose hub has xAI logged
        // in. The fix is one least-privilege data-plane read, in the /v1/catalog (#809)
        // tradition: same admission resolver, same origin check, no parameters, no caller
        // credential forwarded upstream, and a body of booleans plus model ids. Widening
        // `/api/*` or handing the client an admin token to read `GET /api/providers` would
        // have traded a reporting defect for a credential one.
        //
        // What it discloses beyond /v1/catalog and /v1/models, exactly: `hasCredential`,
        // `loggedIn`, `authMode`, the featured roster, and the NAME and adapter of an ENABLED
        // provider those routes omit for want of a usable credential — which is the point of
        // the route. A `disabled` provider is NOT exported (`buildHubState` drops it), because
        // the catalog filters it out too and naming it here would be the only place a data key
        // learns of it.
        //
        // Placed between /v1/catalog and /v1/models so all three least-privilege client reads
        // stay in sight of each other.
        const admission = resolveApiAuth(req, policy);
        if (!admission) return withCors(formatErrorResponse(401, "authentication_error", "opencodex API key required"), req, policy);
        if (!isAllowedRequestOrigin(req, policy)) {
          return withCors(formatErrorResponse(403, "origin_rejected", "cross-origin data-plane request blocked"), req, policy);
        }
        // Role gate AFTER admission, deliberately: answering an unauthenticated caller would
        // turn this into a free "is that machine a hub?" probe. A standalone or client install
        // gains no surface at all — the route simply does not exist there.
        //
        // Built, not formatErrorResponse'd, for the same reason /v1/catalog builds its 404: the
        // code has to distinguish "this route exists and this host is not a hub" from "this
        // build has no such route", which is the difference between admission proof and a
        // vacuous pass in tests/server/api-key-attribution.test.ts.
        if (config.runtimeRole !== "hub") {
          return withCors(
            new Response(JSON.stringify({
              error: {
                type: "invalid_request_error",
                code: "hub_state_not_a_hub",
                message: "hub state is served only by a host whose runtimeRole is hub",
              },
            }), { status: 404, headers: { "content-type": "application/json" } }),
            req,
            policy,
          );
        }
        const { buildHubState } = await import("../hub-state");
        const { MAX_HUB_STATE_BYTES } = await import("../../remote/hub-state");
        const { oauthLoginSummary } = await import("../../oauth");
        // `true` masks emails, but the projection drops the field entirely; passing the mask
        // anyway means a future refactor that starts copying fields cannot leak a raw address.
        const body = JSON.stringify(buildHubState(config, oauthLoginSummary(true), VERSION));
        const bytes = Buffer.byteLength(body);
        if (bytes > MAX_HUB_STATE_BYTES) {
          return withCors(
            new Response(JSON.stringify({
              error: { type: "server_error", code: "hub_state_too_large", message: "hub state exceeds the maximum served size" },
            }), { status: 507, headers: { "content-type": "application/json" } }),
            req,
            policy,
          );
        }
        return withCors(
          new Response(req.method === "HEAD" ? null : body, {
            status: 200,
            headers: {
              "content-type": "application/json",
              // Varies by credential-bearing identity and by live login state: never cached,
              // and no validator to revalidate with (same rule as /v1/catalog).
              "cache-control": "no-store",
              "content-length": String(bytes),
            },
          }),
          req,
          policy,
        );
      }

      if (url.pathname === "/v1/models" && req.method === "GET") {
        // #809: the catalog read sits immediately before model discovery because it shares
        // that route's admission rationale exactly. Keep them adjacent so a future change to
        // one is made in sight of the other.
        // Model discovery never forwards Authorization upstream, so the broader admission
        // set (Authorization / x-api-key / x-opencodex-api-key) is safe here and required by
        // remote OpenAI-style bearer clients and Claude gateway discovery (anthropic-version).
        const admission = resolveApiAuth(req, policy);
        if (!admission) return withCors(formatErrorResponse(401, "authentication_error", "opencodex API key required"), req, policy);
        if (!isAllowedRequestOrigin(req, policy)) {
          return withCors(formatErrorResponse(403, "origin_rejected", "cross-origin data-plane request blocked"), req, policy);
        }
        const wantsDesktopConfig = url.searchParams.get("format") === "desktop-config";
        if (wantsDesktopConfig && (url.searchParams.get("ids") === "cli" || url.searchParams.has("client_version"))) {
          return jsonResponse({ error: "Desktop config format cannot use CLI or client-version selectors" }, 400, req, policy);
        }
        // The Integrations page reports whether a Cursor client has reached this proxy; the
        // recorder keeps only a bounded User-Agent value and a timestamp, in memory.
        recordCursorSeen(req.headers);
        let goModels;
        let modelEntitlements;
        try {
          [goModels, modelEntitlements] = await Promise.all([
            fetchAllModels(config),
            // Codex sends its own client_version on this request, and upstream filters the
            // entitlement roster by it. Passing it through is what stops an entitled account
            // being told it cannot use models a newer client can (#2886).
            // The request signal fences the credential phase too: a client that has already
            // gone away must not keep a native-main token refresh alive, and its late result
            // must not commit on behalf of a request that no longer exists.
            resolveAdmittedCodexModelEntitlements(config, {
              clientVersion: url.searchParams.get("client_version"),
              signal: req.signal,
            }),
          ]);
        } catch (error) {
          if (error instanceof CatalogGatherBusyError) {
            return withCors(new Response(JSON.stringify({ error: { type: "server_error", code: "catalog_busy", message: error.message } }), {
              status: 503,
              headers: { "content-type": "application/json", "Retry-After": "1" },
            }), req, policy);
          }
          throw error;
        }
        const { accountBoundNativeOpenAiSlugsBySelector, applyNativeVisibility, buildCatalogEntries, configuredNativeAliasSlugs, desktopAllowlistSuppressedNativeSlugs, disabledNativeSlugs, exactComboCatalogSlugs, loadCatalogTemplate, NATIVE_OPENAI_MODELS, nativeContextLimits, nativeInputModalities, nativeOpenAiContextWindow, nativeOpenAiMaxOutputTokens, nativeOpenAiContextTier, nativeOpenAiSlugs, nativeReasoningEfforts, nativeDefaultReasoningEffort, shouldIncludeAccountBoundNativeOpenAi, shouldIncludeNativeOpenAi, uniqueCatalogModelsForRawPublicList, visibleCodexAccountSelectors, visibleNativeSlugs, desktopVisibleNativeSlugs } = await import("../../codex/catalog");
        const { ACCOUNT_GATED_NATIVE_OPENAI_MODELS } = await import("../../codex/catalog/native-models");
        const includeNativeOpenAi = shouldIncludeNativeOpenAi(config);
        const includeAccountBoundNativeOpenAi = shouldIncludeAccountBoundNativeOpenAi(config);
        const bareEligibleAccountIds = providerCodexAccountMode(
          OPENAI_CODEX_PROVIDER_ID,
          config.providers[OPENAI_CODEX_PROVIDER_ID],
        ) === "direct" ? new Set([MAIN_CODEX_ACCOUNT_ID]) : undefined;
        const availableBareGatedNativeSlugs = availableAccountGatedNativeModels(
          modelEntitlements,
          bareEligibleAccountIds,
        );
        const availableAccountGatedNativeSlugs = availableAccountGatedNativeModels(modelEntitlements);
        const availableBareNativeSlugs = NATIVE_OPENAI_MODELS.filter(slug => (
          !ACCOUNT_GATED_NATIVE_OPENAI_MODELS.has(slug) || availableBareGatedNativeSlugs.has(slug)
        ));
        const availableAccountNativeSlugs = NATIVE_OPENAI_MODELS.filter(slug => (
          !ACCOUNT_GATED_NATIVE_OPENAI_MODELS.has(slug) || availableAccountGatedNativeSlugs.has(slug)
        ));
        const nativeSlugs = includeNativeOpenAi
          ? nativeOpenAiSlugs().filter(slug => (
              !ACCOUNT_GATED_NATIVE_OPENAI_MODELS.has(slug) || availableBareGatedNativeSlugs.has(slug)
            ))
          : [];
        const disabledNatives = disabledNativeSlugs(config);
        const disabledModels = new Set(config.disabledModels ?? []);
        const exactComboSlugs = exactComboCatalogSlugs(config);
        const shadowedNativeSlugs = configuredNativeAliasSlugs(config);
        const suppressedBareNativeSlugs = new Set([
          ...desktopAllowlistSuppressedNativeSlugs(config),
          ...[...ACCOUNT_GATED_NATIVE_OPENAI_MODELS].filter(slug => !availableBareGatedNativeSlugs.has(slug)),
        ]);
        const accountSelectors = includeAccountBoundNativeOpenAi
          ? visibleCodexAccountSelectors(config)
          : [];
        const accountTargets = new Map(codexAccountNamespaceEntries(config));
        const accountNativeSlugsBySelector = includeAccountBoundNativeOpenAi
          ? new Map([...accountBoundNativeOpenAiSlugsBySelector(config)].map(([selector, slugs]) => {
            const target = accountTargets.get(selector);
            const accountId = target && isMainCodexAccountTarget(target) ? MAIN_CODEX_ACCOUNT_ID : target;
            return [selector, slugs.filter(slug => (
              !ACCOUNT_GATED_NATIVE_OPENAI_MODELS.has(slug)
              || (accountId !== undefined
                && codexModelEntitlementStateForAccount(modelEntitlements, accountId, slug) === "granted")
            ))] as const;
          }))
          : new Map<string, readonly string[]>();
        const accountNativeSlugs = [...new Set(
          [...accountNativeSlugsBySelector.values()].flatMap(slugs => [...slugs]),
        )];
        const desktopInputs = buildDesktopDiscoveryInputs({
          config, models: goModels, modelEntitlements,
          desktopNativeCandidates: desktopVisibleNativeSlugs(config),
        });
        const desktopNativeSlugs = desktopInputs.nativeSlugs;
        const goOrdered = desktopInputs.routedModels;
        // Claude Code / Claude Desktop gateway model discovery (GET /v1/models with
        // Anthropic-style headers; 003 G1-G8 + devlog 131). Entries use the official
        // ModelInfo shape incl. capabilities (effort ladder / thinking) — Desktop 3P can
        // only learn capabilities through discovery, and Claude Code 2.1.207 strips the
        // extra fields (backward-safe). Ids are the claude-opus-4-8-{code} Desktop
        // aliases; legacy claude-ocx-* ids keep decoding via resolveAlias. Detection:
        // anthropic-version header (Claude Code sends it) or explicit ?flavor=anthropic.
        // Codex catalog (client_version) and the OpenAI list shape below stay byte-identical.
        const wantsAnthropicList = wantsDesktopConfig || req.headers.get("anthropic-version") !== null
          || url.searchParams.get("flavor") === "anthropic";
        /**
         * Whether a NATIVE slug may carry a Fast sibling.
         *
         * Both halves are required. Upstream asserts the tier per model — the same
         * `additional_speed_tiers` the Codex picker's own toggle is built from — but an
         * operator capability override or the final wire resolution can still make the
         * route ineligible, and `decideTier` would then drop the tier the row advertised.
         *
         * Declared here, above the Claude discovery call, because that call reads it while
         * the raw OpenAI mapper further down does too; defining it there would leave this
         * use in its temporal dead zone.
         */
        const nativeFastEligible = (metadataId: string): boolean =>
          catalogFastRowEligible(config, { provider: OPENAI_CODEX_PROVIDER_ID, id: metadataId, native: true });

        /**
         * Whether a routed catalog row may carry a Fast sibling.
         *
         * A combo is its own namespace with no `config.providers` entry — declaring a
         * provider named `combo` is rejected (combos/types.ts:191) — so provider lookup
         * cannot classify it. Its aggregated `supportsServiceTier` is already true only
         * when EVERY member supports the tier (aggregation.ts:201), which is the right
         * rule for a row that fans out to all of them.
         *
         * Declared beside nativeFastEligible, above the Claude discovery call that reads
         * both; defining it near the raw OpenAI mapper below would leave that use in its
         * temporal dead zone.
         */
        const catalogRowFastEligible = (m: { provider: string; id: string; supportsServiceTier?: boolean }): boolean =>
          catalogFastRowEligible(config, m);

        if (wantsAnthropicList && !url.searchParams.has("client_version")) {
          if (wantsDesktopConfig) {
            const models = config.claudeCode?.enabled === false ? [] : generateDesktop3pModels(
              desktopInputs.nativeSlugs, desktopInputs.routedModels,
              config.claudeCode?.desktopProfile, desktopInputs.nativeContextCap,
            );
            const response = jsonResponse({ version: 1, models }, 200, req, policy);
            response.headers.set("Cache-Control", "no-store");
            return response;
          }
          if (config.claudeCode?.enabled === false) return jsonResponse({ data: [] }, 200, req, policy);
          // Build Desktop 3P registry so inbound alias resolution works for subsequent requests.
          buildDesktop3pRegistry(
            desktopNativeSlugs,
            desktopInputs.routedModels,
            config.claudeCode?.desktopProfile,
            desktopInputs.nativeContextCap,
          );
          const { buildAnthropicModelInfos } = await import("../../claude/model-info");
          const { resolveAutoContext } = await import("../../claude/context-windows");
          const { activeDesktop3pAlias } = await import("../../claude/desktop-3p");
          // Per-surface id family (devlog 050): explicit ?ids= wins; otherwise the
          // Claude Code CLI discovery UA (`claude-code/<version>`, binary n_()) gets
          // readable claude-ocx ids and every other client (Desktop 3P) keeps the
          // hashed family its config was written with. Unknown UA -> hashed (safe).
          const idsParam = url.searchParams.get("ids");
          const idStyle = idsParam === "cli"
            ? "readable" as const
            : idsParam === "desktop"
              ? "desktop3p" as const
              : (/^claude-code\//i.test(req.headers.get("user-agent") ?? "") ? "readable" as const : "desktop3p" as const);
          const data = buildAnthropicModelInfos(
            desktopNativeSlugs,
            goOrdered,
            resolveAutoContext(config.claudeCode),
            idStyle,
            activeDesktop3pAlias,
            desktopInputs.nativeContextCap,
            config.fastMode,
            // Explicit opt-out omits the Fast predicate.
            config.fastRows !== false
              ? (model: { provider: string; id: string; supportsServiceTier?: boolean }) =>
                model.provider === "native"
                  ? nativeFastEligible(model.id)
                  : catalogRowFastEligible(model)
              : undefined,
            { modelPickerOrder: config.modelPickerOrder, featured: config.subagentModels },
          );
          return jsonResponse({ data }, 200, req, policy);
        }
        if (url.searchParams.has("client_version")) {
          // Codex client → Codex catalog shape: native gpt + namespaced routed models,
          // cloned from a native template so required fields (base_instructions, etc.) are present.
          // Pass the subagent picks so featured models lead by priority (matches the on-disk file).
          // Disabled natives stay in the catalog shape with visibility "hide" (mirrors the
          // on-disk sync; codex-rs keeps them out of the picker itself).
          const maMode = config.multiAgentMode === "v1" || config.multiAgentMode === "v2" ? config.multiAgentMode : "default";
          // Account rows use the same hidden-inclusive supported set as on-disk sync. This lets a
          // newly re-enabled native reappear under each selector before the next sync, while the
          // no-selector path keeps nativeOpenAiSlugs()'s existing visibility-sensitive behavior.
          const catalogNativeSlugs = accountSelectors.length > 0
            ? [...new Set([
              ...availableAccountNativeSlugs,
              ...accountNativeSlugs,
            ])]
            : nativeSlugs;
          const entries = buildCatalogEntries(
            loadCatalogTemplate(),
            catalogNativeSlugs,
            goOrdered,
            config.subagentModels,
            websocketsEnabled(config),
            maMode as "v1" | "default" | "v2",
            exactComboSlugs,
            accountSelectors,
            suppressedBareNativeSlugs,
            new Set(),
            nativeContextLimits(config),
            accountNativeSlugs,
            accountNativeSlugsBySelector,
            config.keepNativeChatGptOnV1 === true,
            config.modelPickerOrder,
          );
          return jsonResponse({
            models: applyNativeVisibility(
              entries,
              disabledModels,
              accountSelectors.length > 0,
              new Set(accountNativeSlugs),
            ),
          }, 200, req, policy);
        }
        // OpenAI list shape: native gpt bare + routed models namespaced "<provider>/<id>"
        // (pure availability list — disabled natives are omitted entirely).
        // Grok Build discovers models through this endpoint too, and its model picker only
        // enables /effort for entries that advertise the reasoning ladder in the Grok model
        // catalog shape (supports_reasoning_effort + reasoning_efforts[]). The Codex catalog
        // branch above already carries the same ladders, so mirror them here — native rows
        // from the upstream snapshot, routed rows from the configured provider tiers. The
        // default uses the same canonical fallback as the Codex catalog resolver
        // (configured default, then medium, then high, then the first tier). Extra fields
        // are ignored by plain OpenAI clients.
        const grokEffortOption = (value: string, isDefault: boolean) => ({
          value,
          label: `${value[0].toUpperCase()}${value.slice(1)} Effort`,
          ...(isDefault ? { default: true } : {}),
        });
        const grokEffortFields = (efforts: string[], configuredDefault?: string) => {
          const defaultEffort = grokDefaultReasoningEffort(efforts, configuredDefault);
          if (defaultEffort === undefined) return {};
          return {
            supports_reasoning_effort: true,
            reasoning_effort: defaultEffort,
            reasoning_efforts: efforts.map(effort => grokEffortOption(effort, effort === defaultEffort)),
          };
        };
        // Cursor's local-agent runtime (Private Inference build) reads api_types + capabilities
        // to enable its effort control; every other consumer ignores them. See
        // src/server/models-capabilities.ts.
        const nativeLimits = nativeContextLimits(config);
        const nativeContextInput = (metadataId: string) => {
          const tier = nativeOpenAiContextTier(metadataId, nativeLimits);
          return tier
            ? { contextWindow: tier.defaultWindow, longContextWindow: tier.longWindow }
            : { contextWindow: nativeOpenAiContextWindow(metadataId, nativeLimits) };
        };
        const nativeModelRow = (id: string, metadataId = id) => ({
            id,
            object: "model",
            created: 0,
            owned_by: "openai",
            ...grokEffortFields(
              nativeReasoningEfforts(metadataId),
              nativeDefaultReasoningEffort(metadataId),
            ),
            ...modelCapabilityFields({
              reasoningEfforts: nativeReasoningEfforts(metadataId),
              // Cursor "Max Mode": advertise the family's default/long pair (272k/922k for
              // GPT-5.6) so the client can pick per request; without a tier, the effective
              // window is the only value.
              ...nativeContextInput(metadataId),
              maxOutputTokens: nativeOpenAiMaxOutputTokens(metadataId),
              inputModalities: nativeInputModalities(metadataId),
            }),
          });
        // Resolved once per request, not per model: the global fast switch offers the fast
        // identity to clients that have no Fast toggle of their own. Null when the switch is
        // off, so the row mapper does no work and loads no adapter module.
        const cursorFastIdForListing = config.fastMode === true
          ? await (async () => {
            const { cursorFastIdFor } = await import("../../adapters/cursor/catalog");
            return (modelId: string, provider = "cursor") => provider === "cursor" ? cursorFastIdFor(modelId) : undefined;
          })()
          : null;
        // Selector-active discovery follows the same complete supported set as the Codex catalog
        // for both bare and qualified rows. Without selectors, the live catalog continues to own
        // bare availability.
        const selectorNativeSlugs = accountSelectors.length > 0
          ? availableBareNativeSlugs.filter(slug => !disabledNatives.has(slug))
          : [];
        const bareSelectorNativeSlugs = accountSelectors.length > 0
          ? selectorNativeSlugs
          : [];
        const visibleNatives = includeNativeOpenAi
          ? accountSelectors.length > 0
            ? bareSelectorNativeSlugs.filter(slug => !shadowedNativeSlugs.has(slug))
            : visibleNativeSlugs(config)
          : [];
        const visibleAccountNatives = accountSelectors.flatMap(selector =>
          (accountNativeSlugsBySelector.get(selector) ?? []).filter(metadataId => !disabledNatives.has(metadataId)).flatMap(metadataId => {
            const id = `${selector}/${metadataId}`;
            return disabledModels.has(id) ? [] : [{ id, metadataId }];
          })
        );
        // What a scoped key may see, filtered by the same predicate that refuses
        // it on the data plane, so the catalog and the send path cannot disagree.
        // This is a convenience, never the boundary: hiding a row only stops a
        // client that reads the catalog first, which is why the refusal lives on
        // the request path and this filter reuses it rather than replacing it.
        // Filtering happens where the resolved provider and model are still in
        // hand -- a published id is a selector, and re-resolving one here would
        // re-run combo selection just to render a list.
        const listScope = resolveAdmissionModelScope(config, admission);
        const listAllows = (providerName: string, modelId: string): boolean =>
          routeAllowedByScope(listScope, { providerName, modelId });
        // The projection is opt-in. Keep the default path free of Cursor install detection,
        // and resolve the bundle table once for the whole list rather than once per row.
        const effortRowsEnabled = config.cursorEffortRows === true;
        // Explicit opt-out skips policy resolution and additional rows.
        const fastRowsEnabled = config.fastRows !== false;
        // One inventory serves both grammars; building it twice would double the work on a
        // hot path for no benefit.
        const effortRowKnownIds = effortRowsEnabled || fastRowsEnabled
          ? knownEffortRowIds(config)
          : undefined;
        const privateInference = effortRowsEnabled
          ? detectCursorInstalls().find(install => install.build === "private-inference")
          : undefined;
        const cursorEffortTable = effortRowsEnabled
          ? (deps.managementApi?.loadCursorEffortTable ?? loadCursorEffortTable)(privateInference)
          : null;
        const expandedNativeModelRow = (id: string, metadataId = id) => {
          const reasoningEfforts = nativeReasoningEfforts(metadataId);
          return expandCursorEffortRow(nativeModelRow(id, metadataId), reasoningEfforts, config, {
            knownIds: effortRowKnownIds,
            table: cursorEffortTable,
            supportsReasoning: reasoningEfforts.length > 0,
          }).flatMap(row => expandFastRow(
            row,
            // Only the BASE row earns a fast sibling. An effort row already spent the
            // grammar, and the parser requires the stripped base to be routable, so
            // `<base>--<effort>--fast` would publish a row no ingress can resolve.
            row.id === id && nativeFastEligible(metadataId),
            config,
            effortRowKnownIds,
          ));
        };
        const routedRows = await Promise.all(uniqueCatalogModelsForRawPublicList(goOrdered)
          .filter(m => listAllows(m.provider, m.id))
          .map(async m => {
          // Same rule as the anthropic branch: with the global fast switch on, a client
          // that has no Fast toggle is offered the fast identity directly. An operator
          // alias is an explicit decision and still wins.
          const fastModelId = cursorFastIdForListing?.(m.id, m.provider);
          const publicId = m.alias ?? `${m.provider}/${fastModelId ?? m.id}`;
          const isCombo = m.provider === "combo" && exactComboSlugs.has(publicId);
          const provider = config.providers[m.provider];
          const effective = provider
            ? (await import("../../providers/default-aliases")).effectiveModelAliases(
                config,
                provider,
                knownModelIdsForProvider(m.provider, provider, config),
              ).get(m.id)
            : undefined;
          const row = {
            id: publicId,
            object: "model",
            created: 0,
            // This endpoint is an OpenAI-compatible inbound contract. Some clients use
            // owned_by as an adapter selector, so a virtual combo must name that wire
            // adapter rather than the internal catalog authority marker.
            owned_by: isCombo ? "openai" : (m.owned_by ?? m.provider),
            ...(isCombo ? { is_combo: true } : {}),
            ...(effective ? { alias_of: `${provider?.alias || m.provider}/${effective.alias}` } : {}),
            ...grokEffortFields(m.reasoningEfforts ?? [], m.defaultReasoningEffort),
            ...modelCapabilityFields({
              reasoningEfforts: m.reasoningEfforts,
              // contextWindow is already the post-cap effective value; contextCap is the raw
              // operator knob and over-reports models whose real window sits below it.
              contextWindow: m.contextWindow,
              maxOutputTokens: m.maxOutputTokens,
              inputModalities: m.inputModalities,
            }),
          };
          return expandCursorEffortRow(row, m.reasoningEfforts, config, {
            knownIds: effortRowKnownIds,
            table: cursorEffortTable,
            supportsReasoning: (m.reasoningEfforts ?? []).length > 0,
          }).flatMap(expanded => expandFastRow(
            expanded,
            expanded.id === row.id && catalogRowFastEligible(m),
            config,
            effortRowKnownIds,
          ));
        }));
        const data = [
          ...visibleNatives
            .filter(id => listAllows(OPENAI_CODEX_PROVIDER_ID, id))
            .flatMap(id => expandedNativeModelRow(id)),
          ...visibleAccountNatives
            .filter(({ metadataId }) => listAllows(OPENAI_CODEX_PROVIDER_ID, metadataId))
            .flatMap(({ id, metadataId }) => expandedNativeModelRow(id, metadataId)),
          ...routedRows.flat(),
        ];
        return jsonResponse({ object: "list", data }, 200, req, policy);
      }

      // Remote compaction v1 (codex-rs with Feature::RemoteCompactionV2 off — the default).
      // Must be matched BEFORE the /v1/responses POST branch never sees it (distinct path) and
      // before the /v1/* 404 guard below.
      if (url.pathname === "/v1/responses/compact" && req.method === "POST") {
        if (isDraining()) {
          return drainingResponse(req, policy);
        }
        const admission = resolveResponsesApiAuth(req, policy);
        if (!admission) return withCors(formatErrorResponse(401, "authentication_error", "opencodex API key required"), req, policy);
        if (!isAllowedRequestOrigin(req, policy)) {
          return withCors(formatErrorResponse(403, "origin_rejected", "cross-origin data-plane request blocked"), req, policy);
        }
        const start = Date.now();
        const requestId = nextRequestLogId(start);
        const logCtx: RequestLogContext = {
          model: "unknown",
          provider: "unknown",
          ...requestMetricsLogContext,
          ...admissionFields(admission),
          inboundProtocol: "responses",
        };
        return runAdmittedHttpTurn(req, policy, async turnAdmissionLease => {
          let response: Response;
          try {
            response = await handleResponsesCompact(req, config, logCtx, turnAdmissionLease, admission, {
              onRequestBodyRead: () => disableResponsesRequestTimeout(req, requestServer),
            });
          } catch {
            response = formatErrorResponse(500, "server_error", "Unexpected compact request failure");
          }
          addFinalRequestLog(requestId, start, logCtx, response.status,
            response.status === 499 ? { closeReason: "client_cancel" } : undefined);
          return withCors(response, req, policy);
        }, { requestId, start, logCtx });
      }

      if (
        req.method === "POST"
        && (url.pathname === "/v1/images/generations" || url.pathname === "/v1/images/edits")
      ) {
        disableResponsesRequestTimeout(req, requestServer);
        if (isDraining()) {
          return drainingResponse(req, policy);
        }
        const admission = resolveApiAuth(req, policy);
        if (!admission) return withCors(formatErrorResponse(401, "authentication_error", "opencodex API key required"), req, policy);
        if (!isAllowedRequestOrigin(req, policy)) {
          return withCors(formatErrorResponse(403, "origin_rejected", "cross-origin data-plane request blocked"), req, policy);
        }
        const start = Date.now();
        const requestId = nextRequestLogId(start);
        const logCtx: RequestLogContext = {
          model: "image_gen",
          provider: "unknown",
          ...requestMetricsLogContext,
          ...admissionFields(admission),
        };
        const endpoint = url.pathname.endsWith("/edits") ? "edits" as const : "generations" as const;
        return runAdmittedHttpTurn(req, policy, async turnAdmissionLease => {
          const response = await handleImages(req, config, endpoint, logCtx, turnAdmissionLease, admission);
          addFinalRequestLog(requestId, start, logCtx, response.status, response.status === 499 ? { closeReason: "client_cancel" } : undefined);
          return withCors(response, req, policy);
        }, { requestId, start, logCtx });
      }

      if (req.method === "GET" && url.pathname.startsWith("/v1/opencodex/artifacts/")) {
        const admission = resolveApiAuth(req, policy);
        if (!admission) return withCors(formatErrorResponse(401, "authentication_error", "opencodex API key required"), req, policy);
        if (!isAllowedRequestOrigin(req, policy)) {
          return withCors(formatErrorResponse(403, "origin_rejected", "cross-origin data-plane request blocked"), req, policy);
        }
        const id = decodeURIComponent(url.pathname.slice("/v1/opencodex/artifacts/".length));
        const { resolveArtifactPath } = await import("../../images/artifacts");
        const artifactPath = resolveArtifactPath(id);
        if (!artifactPath) {
          return withCors(formatErrorResponse(404, "not_found", "artifact not found"), req, policy);
        }
        const file = Bun.file(artifactPath);
        const ext = artifactPath.split(".").pop()?.toLowerCase();
        const contentType =
          ext === "png" ? "image/png"
            : ext === "jpg" || ext === "jpeg" ? "image/jpeg"
              : ext === "webp" ? "image/webp"
                : ext === "gif" ? "image/gif"
                  : "application/octet-stream";
        return withCors(new Response(file, {
          status: 200,
          headers: {
            "content-type": contentType,
            "cache-control": "private, max-age=3600",
            "x-content-type-options": "nosniff",
          },
        }), req, policy);
      }

      if (contextEndpoint(url.pathname) !== undefined && req.method === "POST" && contextRelayActivated()) {
        // No timeout disable here. The relay is a bounded JSON round trip that owns one deadline
        // from entry; removing the idle timeout first would let an unfinished body hold an
        // admitted turn slot indefinitely, before that deadline ever starts.
        if (isDraining()) {
          return drainingResponse(req, policy);
        }
        const admission = resolveApiAuth(req, policy);
        if (!admission) return withCors(formatErrorResponse(401, "authentication_error", "opencodex API key required"), req, policy);
        if (!isAllowedRequestOrigin(req, policy)) {
          return withCors(formatErrorResponse(403, "origin_rejected", "cross-origin data-plane request blocked"), req, policy);
        }
        const start = Date.now();
        const requestId = nextRequestLogId(start);
        const logCtx: RequestLogContext = {
          model: "context_history",
          provider: "unknown",
          ...requestMetricsLogContext,
          ...admissionFields(admission),
        };
        return runAdmittedHttpTurn(req, policy, async turnAdmissionLease => {
          const response = await handleContextHistory(req, config, logCtx, contextEndpoint(url.pathname)!,
            turnAdmissionLease, admission, () => resolveApiAuth(req, ingress === "hub-link" ? linkPolicy() : policy));
          addFinalRequestLog(requestId, start, logCtx, response.status,
            response.status === 499 ? { closeReason: "client_cancel" } : undefined);
          return withCors(response, req, policy);
        }, { requestId, start, logCtx });
      }

      if (url.pathname === "/v1/alpha/search" && req.method === "POST") {
        disableResponsesRequestTimeout(req, requestServer);
        if (isDraining()) {
          return drainingResponse(req, policy);
        }
        const admission = resolveApiAuth(req, policy);
        if (!admission) return withCors(formatErrorResponse(401, "authentication_error", "opencodex API key required"), req, policy);
        if (!isAllowedRequestOrigin(req, policy)) {
          return withCors(formatErrorResponse(403, "origin_rejected", "cross-origin data-plane request blocked"), req, policy);
        }
        const start = Date.now();
        const requestId = nextRequestLogId(start);
        const logCtx: RequestLogContext = {
          model: "web_search",
          provider: "unknown",
          ...requestMetricsLogContext,
          ...admissionFields(admission),
        };
        return runAdmittedHttpTurn(req, policy, async turnAdmissionLease => {
          const response = await handleSearch(req, config, logCtx, turnAdmissionLease, admission);
          addFinalRequestLog(requestId, start, logCtx, response.status,
            response.status === 499 ? { closeReason: "client_cancel" } : undefined);
          return withCors(response, req, policy);
        }, { requestId, start, logCtx });
      }

      if (url.pathname === "/v1/responses" && req.method === "POST") {
        if (isDraining()) {
          return drainingResponse(req, policy);
        }
        const admission = resolveResponsesApiAuth(req, policy);
        if (!admission) return withCors(formatErrorResponse(401, "authentication_error", "opencodex API key required"), req, policy);
        if (!isAllowedRequestOrigin(req, policy)) {
          return withCors(formatErrorResponse(403, "origin_rejected", "cross-origin data-plane request blocked"), req, policy);
        }
        const start = Date.now();
        const requestId = nextRequestLogId(start);
        const logCtx: RequestLogContext = {
          model: "unknown",
          provider: "unknown",
          ...requestMetricsLogContext,
          ...admissionFields(admission),
          inboundProtocol: "responses",
        };
        if (req.headers.get("x-opencodex-grok") === "1") logCtx.surface = "grok";
        let logged = false;
        const finalizeNativePassthroughLog = (
          status: number,
          meta: Pick<RequestLogEntry, "terminalStatus" | "closeReason">,
        ) => {
          if (logged) return;
          logged = true;
          addFinalRequestLog(requestId, start, logCtx, status, meta);
        };
        return runAdmittedHttpTurn(req, policy, async turnAdmissionLease => {
          let response: Response;
          try {
            response = await handleResponses(req, config, logCtx, {
              turnAdmissionLease,
              admission,
              onRequestBodyRead: () => disableResponsesRequestTimeout(req, requestServer),
              abortSignal: req.signal,
              onFirstOutput: () => recordFirstOutput(logCtx, start),
              onNativePassthroughTerminal: status => {
                finalizeNativePassthroughLog(httpStatusForRequestLogTerminal(status, logCtx), {
                  terminalStatus: status,
                  closeReason: "terminal",
                });
              },
              onNativePassthroughCancel: () => {
                finalizeNativePassthroughLog(499, { closeReason: "client_cancel" });
              },
            });
          } catch (error) {
            // A bounded upstream body can fail before handleResponses returns a client response.
            // Finalize before rethrow so accounting observes the physical send while the caller
            // retains the existing reset/rejection instead of receiving a synthesized response.
            finalizeNativePassthroughLog(
              req.signal.aborted ? 499 : 502,
              { closeReason: req.signal.aborted ? "client_cancel" : "non_stream" },
            );
            throw error;
          }
          return withRequestLogId(
            withCors(responseWithDeferredRequestLog(response, requestId, start, logCtx), req, policy),
            requestId,
          );
        }, { requestId, start, logCtx });
      }

      // Anthropic Messages inbound (Claude Code). count_tokens FIRST (longer path).
      // Claude Code posts `/v1/messages?beta=true` — pathname match ignores the query (003 G9).
      if (url.pathname === "/v1/messages/count_tokens" && req.method === "POST") {
        if (isDraining()) {
          return drainingResponse(req, policy);
        }
        const admission = resolveApiAuth(req, policy);
        if (!admission) {
          return withCors(anthropicErrorResponse(401, "opencodex API key required", "authentication_error"), req, policy);
        }
        if (!isAllowedRequestOrigin(req, policy)) {
          return withCors(anthropicErrorResponse(403, "cross-origin data-plane request blocked", "permission_error"), req, policy);
        }
        return runAdmittedHttpTurn(req, policy, async () => withCors(
          await handleClaudeCountTokens(req, config, policy, { claudeIntercept: ingress === "claude-intercept" }),
          req,
          policy,
        ));
      }

      if (url.pathname === "/v1/messages" && req.method === "POST") {
        disableResponsesRequestTimeout(req, requestServer);
        if (isDraining()) {
          return drainingResponse(req, policy);
        }
        const admission = resolveApiAuth(req, policy);
        if (!admission) {
          return withCors(anthropicErrorResponse(401, "opencodex API key required", "authentication_error"), req, policy);
        }
        if (!isAllowedRequestOrigin(req, policy)) {
          return withCors(anthropicErrorResponse(403, "cross-origin data-plane request blocked", "permission_error"), req, policy);
        }
        const start = Date.now();
        const requestId = nextRequestLogId(start);
        const logCtx: RequestLogContext = {
          model: "unknown",
          provider: "unknown",
          ...requestMetricsLogContext,
          ...admissionFields(admission),
          inboundProtocol: "messages",
        };
        // Logging is finalized inside handleClaudeMessages (Responses-vocab tap on the
        // pre-translation stream + native passthrough callbacks) — do not re-wrap the
        // translated Anthropic stream here.
        return runAdmittedHttpTurn(req, policy, async turnAdmissionLease => withCors(
          await handleClaudeMessages(req, config, logCtx, { requestId, start, turnAdmissionLease, admission }, policy, { claudeIntercept: ingress === "claude-intercept" }),
          req,
          policy,
        ), { requestId, start, logCtx });
      }

      // OpenAI Chat Completions inbound (GitHub Copilot App / OpenAI-compatible clients).
      if (url.pathname === "/v1/chat/completions" && req.method === "POST") {
        disableResponsesRequestTimeout(req, requestServer);
        if (isDraining()) {
          return drainingResponse(req, policy);
        }
        const admission = resolveResponsesApiAuth(req, policy);
        if (!admission) return withCors(formatErrorResponse(401, "authentication_error", "opencodex API key required"), req, policy);
        if (!isAllowedRequestOrigin(req, policy)) {
          return withCors(formatErrorResponse(403, "origin_rejected", "cross-origin data-plane request blocked"), req, policy);
        }
        const start = Date.now();
        const requestId = nextRequestLogId(start);
        const logCtx: RequestLogContext = {
          model: "unknown",
          provider: "unknown",
          ...requestMetricsLogContext,
          ...admissionFields(admission),
          inboundProtocol: "chat",
        };
        // `policy`, not `config`: this route is now served on the unauthenticated loopback
        // listener too (#4236), and only the receiving listener's view produces CORS headers
        // that match the admission decision made above.
        return runAdmittedHttpTurn(req, policy, async turnAdmissionLease => withCors(
          await handleChatCompletions(req, config, logCtx, { requestId, start, turnAdmissionLease, admission }),
          req,
          policy,
        ), { requestId, start, logCtx });
      }

      if (url.pathname === "/v1/audio/transcriptions" && req.method === "POST") {
        disableResponsesRequestTimeout(req, requestServer);
        if (isDraining()) return drainingResponse(req, policy);
        const admission = resolveAudioAdmission(req.headers, config, admissionOptions);
        if (!admission) return withCors(formatErrorResponse(401, "authentication_error", "opencodex API key required"), req, policy);
        if (!isAllowedRequestOrigin(req, policy)) {
          return withCors(formatErrorResponse(403, "origin_rejected", "cross-origin audio request blocked"), req, policy);
        }
        const start = Date.now();
        const requestId = nextRequestLogId(start);
        const logCtx: RequestLogContext = {
          model: TRANSCRIPTION_MODEL,
          provider: "unknown",
          ...requestMetricsLogContext,
          ...admissionFields(admission),
        };
        return runAdmittedHttpTurn(req, policy, async lease => {
          const response = await handleAudioTranscriptions(req, config, logCtx, admission, lease);
          addFinalRequestLog(requestId, start, logCtx, response.status);
          return withCors(response, req, policy);
        }, { requestId, start, logCtx });
      }

      // ChatGPT / Codex App voice (GPT‑Live / Frameless Bidi) + OpenAI Realtime call-create.
      // Clients hit either /v1/live (Frameless App) or /v1/realtime/calls (codex RealtimeCallClient /
      // public Realtime API). Sideband WS joins are handled just below.
      if (
        req.method === "POST"
        && (url.pathname === "/v1/live" || url.pathname === "/v1/realtime/calls")
      ) {
        disableResponsesRequestTimeout(req, requestServer);
        if (isDraining()) {
          return drainingResponse(req, policy);
        }
        const audioClient = resolveAudioClient(req, config, false, admissionOptions);
        if (audioClient instanceof Response) return withCors(audioClient, req, policy);
        const admission = audioClient?.admission ?? resolveApiAuth(req, policy);
        if (!admission) return withCors(formatErrorResponse(401, "authentication_error", "opencodex API key required"), req, policy);
        if (!isAllowedRequestOrigin(req, policy)) {
          return withCors(formatErrorResponse(403, "origin_rejected", "cross-origin data-plane request blocked"), req, policy);
        }
        const start = Date.now();
        const requestId = nextRequestLogId(start);
        const logCtx: RequestLogContext = {
          model: "gpt-live",
          provider: "unknown",
          ...requestMetricsLogContext,
          ...admissionFields(admission),
        };
        return runAdmittedHttpTurn(req, policy, async turnAdmissionLease => {
          const response = audioClient
            ? await handleExternalLive(req, config, logCtx, { client: audioClient, lease: turnAdmissionLease, bindings: liveCallBindings })
            : await handleLive(req, config, logCtx, turnAdmissionLease, admission);
          addFinalRequestLog(
            requestId,
            start,
            logCtx,
            response.status,
            response.status === 499 ? { closeReason: "client_cancel" } : undefined,
          );
          return withCors(response, req, policy);
        }, { requestId, start, logCtx });
      }

      // Voice / Realtime WebSocket relay. Sideband joins: Frameless /v1/live/{callId};
      // Realtime v1 /v1/realtime?call_id= (or /v1/realtime/calls/{callId}). Standalone
      // sessions (codex-rs thread/realtime/start, WebSocket transport — the desktop voice
      // path): /v1/realtime?intent=quicksilver&model= and /v1/live?model=.
      // Transparent bidirectional relay.
      const liveSidebandTarget = req.headers.get("upgrade")?.toLowerCase() === "websocket"
        ? parseLiveSidebandTarget(url.pathname, url.searchParams, url.search.replace(/^\?/, ""))
        : null;
      const dictationSocket = url.pathname === "/v1/audio/transcriptions/stream"
        && req.headers.get("upgrade")?.toLowerCase() === "websocket";
      if (liveSidebandTarget || dictationSocket) {
        if (isDraining()) {
          return drainingResponse(req, policy);
        }
        const audioClient = resolveAudioClient(req, config, dictationSocket, admissionOptions);
        if (audioClient instanceof Response) return withCors(audioClient, req, policy);
        if (!audioClient && liveSidebandTarget && "callId" in liveSidebandTarget
          && liveSidebandTarget.callId.startsWith(EXTERNAL_CALL_PREFIX)) {
          return withCors(formatErrorResponse(401, "authentication_error", "Live call requires its creator API key"), req, policy);
        }
        const admission = audioClient?.admission ?? resolveApiAuth(req, policy);
        if (!admission) return withCors(formatErrorResponse(401, "authentication_error", "opencodex API key required"), req, policy);
        if (!isAllowedRequestOrigin(req, policy)) {
          return withCors(formatErrorResponse(403, "origin_rejected", "WebSocket upgrade blocked: non-local Origin"), req, policy);
        }
        const start = Date.now();
        const requestId = nextRequestLogId(start);
        const logCtx: RequestLogContext = {
          model: "gpt-live",
          provider: "unknown",
          ...requestMetricsLogContext,
          ...admissionFields(admission),
        };
        let liveRequestFinalized = false;
        const finalizeLiveRequest = (
          status: number,
          meta?: Pick<RequestLogEntry, "terminalStatus" | "closeReason">,
        ): void => {
          if (liveRequestFinalized) return;
          liveRequestFinalized = true;
          addFinalRequestLog(requestId, start, logCtx, status, meta);
        };
        const turnAdmissionLease = tryAdmitTurn(sessionLaneIdFromRequest(req.headers));
        if (!turnAdmissionLease) {
          finalizeLiveRequest(503);
          return serverBusyResponse(req, "active turns", policy);
        }
        const audioController = audioClient ? new AbortController() : undefined;
        if (audioController) registerTurn(audioController, turnAdmissionLease);
        const acquisition = audioController
          ? clearableDeadline(120_000, AbortSignal.any([req.signal, audioController.signal])) : undefined;
        const releaseAcquisition = () => {
          acquisition?.clear();
          if (audioController) unregisterTurn(audioController);
          else turnAdmissionLease.release();
        };
        let resolved;
        try {
          resolved = dictationSocket && audioClient
            ? await resolveDictationSocket(audioClient, config, logCtx, turnAdmissionLease, acquisition?.signal)
            : liveSidebandTarget && audioClient
              ? await resolveExternalLiveSocket(audioClient, config, logCtx, liveSidebandTarget, { lease: turnAdmissionLease, bindings: liveCallBindings, signal: acquisition?.signal })
              : liveSidebandTarget
                ? await resolveLiveSidebandUpgrade(req, config, logCtx, liveSidebandTarget, turnAdmissionLease, admission)
                : formatErrorResponse(401, "authentication_error", "opencodex API key required");
        } catch (error) {
          try { releaseAcquisition(); }
          finally {
            finalizeLiveRequest(req.signal.aborted ? 499 : 500,
              req.signal.aborted ? { closeReason: "client_cancel" } : undefined);
          }
          throw error;
        }
        if (acquisition?.signal.aborted) {
          const status = req.signal.aborted ? 499 : acquisition.didExpire() ? 504 : 503;
          try { if (!(resolved instanceof Response) && "finish" in resolved) resolved.finish(); }
          finally {
            try { releaseAcquisition(); }
            finally { finalizeLiveRequest(status, status === 499 ? { closeReason: "client_cancel" } : undefined); }
          }
          return withCors(formatErrorResponse(status,
            "upstream_error", acquisition.didExpire() ? "Audio connection timed out" : "Audio connection canceled"), req, policy);
        }
        if (resolved instanceof Response) {
          releaseAcquisition();
          finalizeLiveRequest(resolved.status);
          return withCors(resolved, req, policy);
        }
        const audio = "finish" in resolved ? resolved : undefined;
        const finish = audio ? (outcome?: number | "timeout" | "connect_error") => {
          try { audio.finish(outcome); }
          finally { releaseAcquisition(); }
        } : undefined;
        const discardUpgrade = () => {
          if (finish) finish();
          else releaseAcquisition();
        };
        if (req.signal.aborted) {
          try { discardUpgrade(); }
          finally { finalizeLiveRequest(499, { closeReason: "client_cancel" }); }
          return withCors(formatErrorResponse(499, "client_closed_request", "Audio connection canceled"), req, policy);
        }
        const upstreamHandshake = await openLiveSidebandUpstream(
          resolved.upstreamWsUrl,
          resolved.headers,
          (url, headers) => (deps.liveSidebandWebSocketFactory ?? ((socketUrl, socketHeaders, protocols) => (
            new WebSocket(socketUrl, { headers: socketHeaders, protocols } as unknown as string[])
          )))(url, headers, audio?.protocols),
          LIVE_SIDEBAND_UPSTREAM_OPEN_TIMEOUT_MS,
          req.signal,
        );
        if (!upstreamHandshake.ok) {
          if (upstreamHandshake.socket) {
            closeLiveSidebandBeforeUpgrade(upstreamHandshake.socket, () => discardUpgrade());
          } else {
            discardUpgrade();
          }
          finalizeLiveRequest(upstreamHandshake.status,
            upstreamHandshake.status === 499 ? { closeReason: "client_cancel" } : undefined);
          console.error("[live] sideband upstream handshake failed: " + upstreamHandshake.message);
          return withCors(
            formatErrorResponse(upstreamHandshake.status, upstreamHandshake.code, upstreamHandshake.message),
            req,
            policy,
          );
        }
        const handoffFailure = upstreamHandshake.handoff.failure();
        if (handoffFailure || upstreamHandshake.socket.readyState !== WebSocket.OPEN) {
          closeLiveSidebandBeforeUpgrade(upstreamHandshake.socket, () => discardUpgrade());
          const failure = handoffFailure ?? {
            status: 502,
            code: "upstream_error",
            message: "voice upstream closed before client upgrade",
          };
          finalizeLiveRequest(failure.status);
          return withCors(formatErrorResponse(failure.status, failure.code, failure.message), req, policy);
        }
        let upgraded = false;
        try {
          upgraded = requestServer.upgrade(req, {
            ...(audioClient?.protocol ? { headers: { "sec-websocket-protocol": audioClient.protocol } } : {}),
            data: {
              kind: "live-sideband",
              liveUpstream: upstreamHandshake.socket,
              liveUpstreamUrl: resolved.upstreamWsUrl,
              liveUpstreamHeaders: resolved.headers,
              liveUpstreamHandoff: upstreamHandshake.handoff,
              admission,
              liveUpstreamProtocols: audio?.protocols,
              liveValidateFrame: audio?.validateFrame,
              liveMaxSessionMs: audio?.maxSessionMs,
              liveFinish: finish,
              liveAbortSignal: audioController?.signal,
              livePending: [],
              livePendingBytes: 0,
              liveOpened: true,
              liveTurnAdmissionLease: turnAdmissionLease,
            } satisfies WsData,
          });
        } catch {
          try {
            upstreamHandshake.handoff.take();
          } catch {
            /* ignore */
          }
          closeLiveSidebandBeforeUpgrade(upstreamHandshake.socket, () => discardUpgrade());
          finalizeLiveRequest(502);
          return withCors(formatErrorResponse(502, "upstream_error", "Audio WebSocket upgrade failed"), req, policy);
        }
        if (upgraded) {
          acquisition?.clear();
          finalizeLiveRequest(101);
          return undefined as unknown as Response;
        }
        try {
          upstreamHandshake.handoff.take();
        } catch {
          /* ignore */
        }
        closeLiveSidebandBeforeUpgrade(upstreamHandshake.socket, () => discardUpgrade());
        finalizeLiveRequest(426);
        return withCors(formatErrorResponse(426, "upgrade_required", "WebSocket upgrade failed"), req, policy);
      }

      // Data-plane guard: unknown /v1/* paths must fail with JSON 404, never fall through to the
      // GUI static handler (extensionless paths would get index.html with HTTP 200 and codex-rs
      // endpoint clients — memories/*, realtime/* — would surface confusing
      // serde decode errors instead of a clean not-found).
      if (url.pathname.startsWith("/v1/")) {
        return withCors(formatErrorResponse(404, "not_found", `Unknown endpoint: ${req.method} ${url.pathname}`), req, policy);
      }

      if (url.pathname === "/opencodex-session") {
        if (req.method === "GET") {
          const session = issueGuiSession(req, config, managementAuth, {
            trustedTailscaleIngress: ingress === "hub-management",
          });
          return session
            ? withManagementCors(serveSessionBootstrap(session), req, config)
            : withManagementCors(new Response(null, { status: 401, headers: { "Cache-Control": "no-store" } }), req, config);
        }
        if (req.method === "POST") {
          // This endpoint is reachable WITHOUT a credential — that is the point of a pairing
          // exchange — so the body limit has to hold against a caller who controls the
          // framing. A declared Content-Length is a claim, not a bound: omit the header and
          // `Number(null ?? "0")` is 0, send `Transfer-Encoding: chunked` and there is no
          // header at all. Both used to pass the pre-check and land in `req.text()`, which
          // buffers whatever arrives. The post-check then measured a string the process had
          // already been forced to hold.
          //
          // So the declared length is only a cheap early reject, and the real bound is
          // applied while reading: stop at limit+1 bytes and never accumulate more.
          const declaredLength = Number(req.headers.get("content-length") ?? "0");
          if (!Number.isFinite(declaredLength) || declaredLength > GUI_PAIRING_EXCHANGE_BODY_LIMIT) {
            return withManagementCors(Response.json({ error: "pairing exchange body too large" }, { status: 413, headers: { "Cache-Control": "no-store" } }), req, config);
          }
          const bounded = await readBoundedRequestText(req, GUI_PAIRING_EXCHANGE_BODY_LIMIT);
          if (bounded === null) {
            return withManagementCors(Response.json({ error: "pairing exchange body too large" }, { status: 413, headers: { "Cache-Control": "no-store" } }), req, config);
          }
          const text = bounded;
          let body: unknown;
          try {
            body = JSON.parse(text);
          } catch {
            return withManagementCors(Response.json({ error: "invalid pairing exchange body" }, { status: 400, headers: { "Cache-Control": "no-store" } }), req, config);
          }
          if (!body || typeof body !== "object" || Array.isArray(body)
            || Object.keys(body as Record<string, unknown>).length !== 1
            || typeof (body as Record<string, unknown>).grant !== "string") {
            return withManagementCors(Response.json({ error: "invalid pairing exchange body" }, { status: 400, headers: { "Cache-Control": "no-store" } }), req, config);
          }
          const pairing = managementAuth.available
            ? consumeGuiPairingGrant(req, body, config, managementAuth, Date.now(), {
              ingress: ingress === "hub-management" ? "hub-management" : "public",
              peerAddress: requestServer.requestIP(req)?.address ?? null,
              tailscaleUser: ingress === "hub-management" ? req.headers.get("Tailscale-User-Login") : null,
              browserOrigin: req.headers.get("Origin") ?? "",
            })
            : null;
          if (pairing && "allowed" in pairing) {
            return withManagementCors(Response.json({ error: "pairing exchange refused" }, {
              status: 429,
              headers: { "Cache-Control": "no-store", "Retry-After": String(pairing.retryAfterSeconds) },
            }), req, config);
          }
          return pairing
            ? withManagementCors(serveSessionBootstrap(pairing), req, config)
            : withManagementCors(new Response(null, { status: 401, headers: { "Cache-Control": "no-store" } }), req, config);
        }
        return withCors(formatErrorResponse(404, "not_found", `Unknown endpoint: ${req.method} ${url.pathname}`), req, policy);
      }
      const guiSessionCandidate = req.method === "GET" && (url.pathname === "/" || !url.pathname.includes("."))
        ? issueGuiSession(req, config, managementAuth, {
          trustedTailscaleIngress: ingress === "hub-management",
        })
        : null;
      const guiFile = serveGuiFile(
        url.pathname,
        undefined,
        guiSessionCandidate ?? undefined,
        config.runtimeRole ?? "standalone",
        isApiAuthRequired(policy),
      );
      if (guiFile) return guiFile;
      if (url.pathname === "/" && req.method === "GET") {
        return jsonResponse(rootFallbackPayload());
      }

      return withCors(formatErrorResponse(404, "not_found", `Unknown endpoint: ${req.method} ${url.pathname}`), req, config);
    },
    websocket: createWebsocketHandler(ctx, requestMetrics),
  } as const;
  return serveOptions;
}