@iislee/opencodex 2.11.0

package/src/codex/warmup.ts

@@ -0,0 +1,192 @@
+export class CodexWarmupError extends Error {
+  code: "http_status" | "missing_body" | "stream_failed" | "stream_incomplete" | "stream_error" | "invalid_sse" | "no_terminal" | "transport";
+  status?: number;
+  /** Upstream error detail extracted from the response body (truncated to 512 chars). */
+  upstreamDetail?: string;
+
+  constructor(
+    code: CodexWarmupError["code"],
+    message = "Codex warmup failed",
+    options: { status?: number; cause?: unknown; upstreamDetail?: string } = {},
+  ) {
+    super(message);
+    this.name = "CodexWarmupError";
+    this.code = code;
+    this.status = options.status;
+    this.upstreamDetail = options.upstreamDetail;
+    if (options.cause !== undefined) this.cause = options.cause;
+  }
+}
+
+export interface CodexWarmupOptions {
+  accessToken: string;
+  chatgptAccountId: string;
+  model?: string;
+  timeoutMs?: number;
+}
+
+const CODEX_RESPONSES_URL = "https://chatgpt.com/backend-api/codex/responses";
+const DEFAULT_MODEL = "gpt-5.4-mini";
+const FALLBACK_MODELS = ["gpt-5.5"];
+const DEFAULT_TIMEOUT_MS = 30_000;
+const MAX_ERROR_BODY_BYTES = 2048;
+
+/** Read the first MAX_ERROR_BODY_BYTES of a response body and extract an error message. */
+async function readErrorDetail(res: Response): Promise<string | undefined> {
+  try {
+    const text = await res.text();
+    const trimmed = text.slice(0, MAX_ERROR_BODY_BYTES);
+    try {
+      const json = JSON.parse(trimmed) as Record<string, unknown>;
+      // ChatGPT backend error shape: { error: { message: "..." } } or { detail: "..." }
+      const nested = json.error;
+      if (nested && typeof nested === "object" && typeof (nested as Record<string, unknown>).message === "string") {
+        return ((nested as Record<string, unknown>).message as string).slice(0, 512);
+      }
+      if (typeof json.detail === "string") return json.detail.slice(0, 512);
+      if (typeof json.error === "string") return (json.error as string).slice(0, 512);
+      if (typeof json.message === "string") return json.message.slice(0, 512);
+    } catch {
+      // Non-JSON response body may contain sensitive data (tokens, credentials).
+      // Only surface structured error messages, never raw text.
+    }
+    return undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function safeWarmupReason(err: unknown): string {
+  if (err instanceof CodexWarmupError) {
+    const base = err.status ? `${err.code}:${err.status}` : err.code;
+    return err.upstreamDetail ? `${base} — ${err.upstreamDetail}` : base;
+  }
+  return "transport";
+}
+
+export function codexWarmupFailureReason(err: unknown): string {
+  return safeWarmupReason(err);
+}
+
+function eventTypeFromData(data: unknown): string | undefined {
+  if (!data || typeof data !== "object") return undefined;
+  const record = data as Record<string, unknown>;
+  return typeof record.type === "string" ? record.type : undefined;
+}
+
+function parseSseFrame(frame: string): unknown | null {
+  const dataLines = frame
+    .split(/\r?\n/)
+    .filter(line => line.startsWith("data:"))
+    .map(line => line.slice(5).trimStart());
+  if (dataLines.length === 0) return null;
+  const data = dataLines.join("\n").trim();
+  if (!data || data === "[DONE]") return null;
+  try {
+    return JSON.parse(data) as unknown;
+  } catch (err) {
+    throw new CodexWarmupError("invalid_sse", "Codex warmup received invalid SSE", { cause: err });
+  }
+}
+
+async function drainWarmupSse(body: ReadableStream<Uint8Array>): Promise<void> {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+
+      for (;;) {
+        const frameEnd = buffer.search(/\r?\n\r?\n/);
+        if (frameEnd < 0) break;
+        const frame = buffer.slice(0, frameEnd);
+        const delimiterLength = buffer[frameEnd] === "\r" ? 4 : 2;
+        buffer = buffer.slice(frameEnd + delimiterLength);
+        const parsed = parseSseFrame(frame);
+        const type = eventTypeFromData(parsed);
+        if (type === "response.completed") return;
+        if (type === "response.failed") throw new CodexWarmupError("stream_failed");
+        if (type === "response.incomplete") throw new CodexWarmupError("stream_incomplete");
+        if (type === "error") throw new CodexWarmupError("stream_error");
+      }
+    }
+
+    if (buffer.trim()) {
+      const parsed = parseSseFrame(buffer);
+      const type = eventTypeFromData(parsed);
+      if (type === "response.completed") return;
+      if (type === "response.failed") throw new CodexWarmupError("stream_failed");
+      if (type === "response.incomplete") throw new CodexWarmupError("stream_incomplete");
+      if (type === "error") throw new CodexWarmupError("stream_error");
+    }
+
+    throw new CodexWarmupError("no_terminal", "Codex warmup ended before completion");
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+async function tryWarmup(options: CodexWarmupOptions, model: string): Promise<void> {
+  let res: Response;
+  try {
+    res = await fetch(CODEX_RESPONSES_URL, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${options.accessToken}`,
+        "ChatGPT-Account-Id": options.chatgptAccountId,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        model,
+        instructions: "Reply with OK.",
+        input: [{ type: "message", role: "user", content: [{ type: "input_text", text: "hi" }] }],
+        stream: true,
+        store: false,
+      }),
+      signal: AbortSignal.timeout(options.timeoutMs ?? DEFAULT_TIMEOUT_MS),
+    });
+  } catch (err) {
+    throw new CodexWarmupError("transport", "Codex warmup request failed", { cause: err });
+  }
+
+  if (!res.ok) {
+    const upstreamDetail = await readErrorDetail(res);
+    throw new CodexWarmupError("http_status", "Codex warmup was rejected", {
+      status: res.status,
+      upstreamDetail,
+    });
+  }
+  if (!res.body) throw new CodexWarmupError("missing_body");
+
+  try {
+    await drainWarmupSse(res.body);
+  } finally {
+    await res.body?.cancel().catch(() => {});
+  }
+}
+
+export async function warmCodexAccount(options: CodexWarmupOptions): Promise<void> {
+  const primaryModel = options.model?.trim() || DEFAULT_MODEL;
+  try {
+    await tryWarmup(options, primaryModel);
+    return;
+  } catch (err) {
+    // Retry with fallback models on 400 (model may not be available for this account).
+    if (!(err instanceof CodexWarmupError) || err.status !== 400) throw err;
+    let lastErr = err;
+    for (const fallback of FALLBACK_MODELS) {
+      if (fallback === primaryModel) continue;
+      try {
+        await tryWarmup(options, fallback);
+        return;
+      } catch (retryErr) {
+        if (retryErr instanceof CodexWarmupError) lastErr = retryErr;
+      }
+    }
+    throw lastErr;
+  }
+}

package/src/codex/websocket-registry.ts

@@ -0,0 +1,100 @@
+import type { ServerWebSocket } from "bun";
+import type { WsData } from "../server/ws-bridge";
+import { createAdmissionGate, type AdmissionMetrics, type AdmissionReservation } from "../lib/admission";
+
+export const MAX_TRACKED_CODEX_WEBSOCKETS = 128;
+const websocketGate = createAdmissionGate("codex_websockets", MAX_TRACKED_CODEX_WEBSOCKETS);
+
+export function tryReserveCodexWebSocket(): AdmissionReservation<ServerWebSocket<WsData>> | null {
+  const gateLease = websocketGate.tryAcquire();
+  if (!gateLease) return null;
+  let socket: ServerWebSocket<WsData> | undefined;
+  let active = true;
+  return {
+    bind(value) {
+      if (!active) return;
+      socket = value;
+    },
+    release() {
+      if (!active) return;
+      active = false;
+      socket = undefined;
+      gateLease.release();
+    },
+  };
+}
+
+export function codexWebSocketAdmissionMetrics(): AdmissionMetrics {
+  return websocketGate.metrics();
+}
+
+const socketsByAccount = new Map<string, Set<ServerWebSocket<WsData>>>();
+
+function trackedAccountId(ws: ServerWebSocket<WsData>): string | null {
+  const ctx = ws.data.authContext;
+  return ctx?.kind === "pool" || ctx?.kind === "main-pool" ? ctx.accountId : null;
+}
+
+function addSocketForAccount(accountId: string | null, ws: ServerWebSocket<WsData>): void {
+  if (!accountId) return;
+  let sockets = socketsByAccount.get(accountId);
+  if (!sockets) {
+    sockets = new Set();
+    socketsByAccount.set(accountId, sockets);
+  }
+  sockets.add(ws);
+}
+
+function removeSocketForAccount(accountId: string | null, ws: ServerWebSocket<WsData>): void {
+  if (!accountId) return;
+  const sockets = socketsByAccount.get(accountId);
+  if (!sockets) return;
+  sockets.delete(ws);
+  if (sockets.size === 0) socketsByAccount.delete(accountId);
+}
+
+export function registerCodexWebSocket(ws: ServerWebSocket<WsData>): void {
+  addSocketForAccount(trackedAccountId(ws), ws);
+}
+
+export function unregisterCodexWebSocket(ws: ServerWebSocket<WsData>): void {
+  removeSocketForAccount(trackedAccountId(ws), ws);
+}
+
+export function updateCodexWebSocketAuthContext(
+  ws: ServerWebSocket<WsData>,
+  authContext: WsData["authContext"],
+): void {
+  const before = trackedAccountId(ws);
+  removeSocketForAccount(before, ws);
+  ws.data.authContext = authContext;
+  addSocketForAccount(trackedAccountId(ws), ws);
+}
+
+export function invalidateCodexWebSocketsForAccount(accountId: string): number {
+  const sockets = socketsByAccount.get(accountId);
+  if (!sockets) return 0;
+  const snapshot = [...sockets];
+  socketsByAccount.delete(accountId);
+  for (const ws of snapshot) {
+    try {
+      ws.data.cancel?.();
+    } catch {
+      /* ignore cancel callbacks during invalidation */
+    }
+    try {
+      ws.close(4001, "Codex account invalidated");
+    } catch {
+      /* socket may already be closing */
+    }
+  }
+  return snapshot.length;
+}
+
+export function getTrackedCodexWebSocketCountForAccount(accountId: string): number {
+  return socketsByAccount.get(accountId)?.size ?? 0;
+}
+
+export function clearCodexWebSocketRegistry(): void {
+  socketsByAccount.clear();
+}

package/src/combos/failover.ts

@@ -0,0 +1,140 @@
+import { classifyError, isCyberPolicyCode } from "../lib/errors";
+import type { OcxComboTarget } from "../types";
+import { targetKey } from "./types";
+import {
+  captureConfigGeneration,
+  sweepExpiredOnWrite,
+  type GenerationContext,
+} from "../lib/state-store-sweeper";
+
+interface TargetCooldown {
+  cooldownUntil: number;
+}
+
+const DEFAULT_COOLDOWN_MS = 60_000;
+const MAX_COOLDOWN_MS = 10 * 60_000;
+
+/** Map<`${comboId}\0${provider/model}`, TargetCooldown> */
+const targetCooldowns = new Map<string, TargetCooldown>();
+let lastReconciledGeneration = 0;
+let liveComboTargets = new Set<string>();
+
+function cooldownMapKey(
+  comboId: string,
+  target: Pick<OcxComboTarget, "provider" | "model">,
+): string {
+  return `${comboId}\0${targetKey(target)}`;
+}
+
+export function parseRetryAfterMs(
+  value: string | null | undefined,
+  now = Date.now(),
+): number | undefined {
+  const text = value?.trim();
+  if (!text) return undefined;
+  if (/^\d+(?:\.\d+)?$/.test(text)) {
+    const seconds = Number(text);
+    if (Number.isFinite(seconds) && seconds > 0) {
+      return Math.min(Math.max(Math.ceil(seconds * 1000), 1), MAX_COOLDOWN_MS);
+    }
+  }
+  const timestamp = Date.parse(text);
+  if (!Number.isFinite(timestamp)) return undefined;
+  const delay = timestamp - now;
+  return delay > 0 ? Math.min(delay, MAX_COOLDOWN_MS) : undefined;
+}
+
+export function isComboTargetInCooldown(
+  comboId: string,
+  target: Pick<OcxComboTarget, "provider" | "model">,
+  now = Date.now(),
+): boolean {
+  const key = cooldownMapKey(comboId, target);
+  const entry = targetCooldowns.get(key);
+  if (!entry) return false;
+  if (entry.cooldownUntil <= now) {
+    targetCooldowns.delete(key);
+    return false;
+  }
+  return true;
+}
+
+export function coolComboTarget(
+  comboId: string,
+  target: Pick<OcxComboTarget, "provider" | "model">,
+  options?: { retryAfter?: string | null; now?: number; cooldownMs?: number; writerGeneration?: number },
+): void {
+  const now = options?.now ?? Date.now();
+  const writerGeneration = options?.writerGeneration ?? captureConfigGeneration();
+  const ownerKey = `${comboId}::${targetKey(target)}`;
+  if (writerGeneration < lastReconciledGeneration && !liveComboTargets.has(ownerKey)) return;
+  const cooldownMs = options?.cooldownMs
+    ?? parseRetryAfterMs(options?.retryAfter, now)
+    ?? DEFAULT_COOLDOWN_MS;
+  targetCooldowns.set(cooldownMapKey(comboId, target), {
+    cooldownUntil: now + Math.min(Math.max(cooldownMs, 1), MAX_COOLDOWN_MS),
+  });
+  sweepExpiredOnWrite(now);
+}
+
+export function reconcileComboTargetCooldowns(context: GenerationContext): number {
+  if (context.generation <= lastReconciledGeneration) return 0;
+  liveComboTargets = new Set(context.comboTargets);
+  lastReconciledGeneration = context.generation;
+  return 0;
+}
+
+export function sweepExpiredComboTargetCooldowns(now = Date.now()): number {
+  let removed = 0;
+  for (const [key, cooldown] of targetCooldowns) {
+    if (cooldown.cooldownUntil > now) continue;
+    targetCooldowns.delete(key);
+    removed += 1;
+  }
+  return removed;
+}
+
+export function clearComboTargetCooldowns(comboId?: string): void {
+  if (comboId === undefined) {
+    targetCooldowns.clear();
+    liveComboTargets.clear();
+    lastReconciledGeneration = 0;
+    return;
+  }
+  const prefix = `${comboId}\0`;
+  for (const key of targetCooldowns.keys()) {
+    if (key.startsWith(prefix)) targetCooldowns.delete(key);
+  }
+}
+
+export type ComboFailureDecision = "hop" | "stop";
+
+export function comboFailureDecision(
+  status: number,
+  message: string,
+  options?: { code?: string | null },
+): ComboFailureDecision {
+  if (status === 499) return "stop";
+  if (message.toLowerCase().includes("origin_rejected")) return "stop";
+  // Cyber policy is a hard non-retryable refusal — honor structured code even when
+  // classificationText was truncated before the JSON code field.
+  if (isCyberPolicyCode(options?.code)) return "stop";
+  const error = classifyError(status, "upstream_error", message);
+  if (isCyberPolicyCode(error.code)) return "stop";
+  if (["origin_rejected", "context_length_exceeded", "invalid_request_error"].includes(error.code ?? "")) {
+    return "stop";
+  }
+  if ([401, 403, 404, 408, 429].includes(status) || status >= 500) return "hop";
+  if ([
+    "permission_denied",
+    "subscription_required",
+    "invalid_api_key",
+    "insufficient_quota",
+    "rate_limit_exceeded",
+    "server_is_overloaded",
+    "upstream_server_error",
+  ].includes(error.code ?? "")) {
+    return "hop";
+  }
+  return "stop";
+}

package/src/combos/index.ts

@@ -0,0 +1,41 @@
+export {
+  COMBO_NAMESPACE,
+  comboAliasIssues,
+  comboConfigError,
+  comboConfigIssues,
+  comboDefaultEffort,
+  comboModelId,
+  comboPublicModelId,
+  getCombo,
+  isValidComboId,
+  listComboIds,
+  normalizeComboConfig,
+  parseComboModelId,
+  preservesPhysicalComboProvider,
+  resolveComboId,
+  targetKey,
+} from "./types";
+export {
+  advanceComboAfterFailure,
+  clearComboSelectionState,
+  NoAvailableComboTargetsError,
+  noteComboFailure,
+  noteComboSuccess,
+  pickComboTarget,
+  tryPickComboModel,
+  UnknownComboError,
+  type ComboPick,
+} from "./resolve";
+export {
+  clearComboTargetCooldowns,
+  coolComboTarget,
+  isComboTargetInCooldown,
+  parseRetryAfterMs,
+  comboFailureDecision,
+  type ComboFailureDecision,
+} from "./failover";
+export {
+  comboIdFromRawBody,
+  concreteComboRequestBody,
+  resetComboEffortWarningStateForTests,
+} from "./request";

package/src/combos/request.ts

@@ -0,0 +1,62 @@
+import type { OcxComboDefaultEffort, OcxComboTarget, OcxConfig } from "../types";
+import { resolveComboId } from "./types";
+
+const warnedUnsupportedDefaults = new Set<string>();
+let lastWarningReconciledGeneration = 0;
+
+export function reconcileComboWarningMemos(generation: number): number {
+  if (generation <= lastWarningReconciledGeneration) return 0;
+  const removed = warnedUnsupportedDefaults.size;
+  warnedUnsupportedDefaults.clear();
+  lastWarningReconciledGeneration = generation;
+  return removed;
+}
+
+export function resetComboEffortWarningStateForTests(): void {
+  warnedUnsupportedDefaults.clear();
+}
+
+export function comboIdFromRawBody(body: unknown, config: OcxConfig): string | null {
+  if (!body || typeof body !== "object" || Array.isArray(body)) return null;
+  const model = (body as { model?: unknown }).model;
+  if (typeof model !== "string") return null;
+  return resolveComboId(config, model);
+}
+
+export function concreteComboRequestBody(
+  body: unknown,
+  target: Pick<OcxComboTarget, "provider" | "model">,
+  defaultEffort: OcxComboDefaultEffort | null,
+  targetReasoningEfforts: readonly string[] | undefined,
+): Record<string, unknown> {
+  const clone = structuredClone(body) as Record<string, unknown>;
+  clone.model = `${target.provider}/${target.model}`;
+  if (!defaultEffort) return clone;
+  const reasoning = clone.reasoning;
+  const needsDefault = reasoning === undefined || (
+    reasoning
+    && typeof reasoning === "object"
+    && !Array.isArray(reasoning)
+    && !Object.prototype.hasOwnProperty.call(reasoning, "effort")
+  );
+  if (!needsDefault) return clone;
+  if (!targetReasoningEfforts?.includes(defaultEffort)) {
+    const key = `${target.provider}/${target.model}:${defaultEffort}`;
+    if (!warnedUnsupportedDefaults.has(key)) {
+      warnedUnsupportedDefaults.add(key);
+      console.debug("[opencodex] combo default effort omitted", {
+        provider: target.provider,
+        model: target.model,
+        requestedEffort: defaultEffort,
+        capability: targetReasoningEfforts === undefined ? "unknown" : "unsupported",
+      });
+    }
+    return clone;
+  }
+  if (reasoning === undefined) {
+    clone.reasoning = { effort: defaultEffort };
+  } else {
+    clone.reasoning = { ...(reasoning as Record<string, unknown>), effort: defaultEffort };
+  }
+  return clone;
+}