@opengeni/codex 0.2.7 → 0.2.10

package/src/realtime.ts

@@ -0,0 +1,356 @@
+import { codexSubscriptionHeaders, type CodexAuthHeaders } from "./api-client";
+import {
+  CODEX_REALTIME_CALL_TIMEOUT_MS,
+  CODEX_REALTIME_DEFAULT_VOICE,
+  CODEX_REALTIME_MODEL,
+  CODEX_REALTIME_VERSION,
+  CODEX_RESPONSES_BASE,
+} from "./constants";
+import type { CodexFetch } from "./device-code";
+import {
+  CODEX_REALTIME_INITIAL_ITEMS_MAX_COUNT,
+  CODEX_REALTIME_INITIAL_ITEMS_MAX_TOKENS,
+  type CodexRealtimeInitialItem,
+} from "./realtime-v3";
+
+const CODEX_REALTIME_CALL_URL = `${CODEX_RESPONSES_BASE}/realtime/calls?intent=quicksilver&architecture=avas`;
+const MAX_REALTIME_SDP_BYTES = 1024 * 1024;
+const REALTIME_CALL_ID =
+  /^(?:rtc_.+|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$/i;
+
+export const CODEX_REALTIME_VOICES = [
+  "juniper",
+  "maple",
+  "spruce",
+  "ember",
+  "vale",
+  "breeze",
+  "arbor",
+  "sol",
+  "cove",
+] as const;
+
+export type CodexRealtimeVoice = (typeof CODEX_REALTIME_VOICES)[number];
+
+export type CodexRealtimeCallInput = {
+  /** Browser-created WebRTC offer. It must negotiate an audio media section. */
+  sdp: string;
+  /** This transport intentionally supports only Codex's Frameless/V3 protocol. */
+  version: typeof CODEX_REALTIME_VERSION;
+  /** Server-owned session/thread binding; sent upstream but never returned. */
+  sessionId: string;
+  /** Server-projected ordinary-session history for Frameless V3 bootstrap. */
+  initialItems?: CodexRealtimeInitialItem[] | undefined;
+  instructions?: string | undefined;
+  voice?: CodexRealtimeVoice | undefined;
+};
+
+export type CodexRealtimeCallResult = {
+  sdp: string;
+  version: typeof CODEX_REALTIME_VERSION;
+  model: typeof CODEX_REALTIME_MODEL;
+};
+
+export type CodexRealtimeErrorCode =
+  | "invalid_request"
+  | "incompatible"
+  | "authentication"
+  | "entitlement"
+  | "rate_limited"
+  | "provider"
+  | "invalid_response"
+  | "network"
+  | "timeout"
+  | "cancelled";
+
+/** Safe provider failure: it contains no response body, credential, or account identity. */
+export class CodexRealtimeError extends Error {
+  constructor(
+    readonly code: CodexRealtimeErrorCode,
+    message: string,
+    readonly providerStatus: number | null = null,
+  ) {
+    super(message);
+    this.name = "CodexRealtimeError";
+  }
+}
+
+export type CodexRealtimeCallOptions = {
+  signal?: AbortSignal | undefined;
+  timeoutMs?: number | undefined;
+};
+
+/**
+ * Create one native subscription-authenticated Codex GPT-Live V3 WebRTC call.
+ *
+ * There is deliberately no API-key or WebSocket fallback and no transport
+ * retry. A caller may refresh the same connected subscription after one 401,
+ * but this adapter always performs exactly one provider request.
+ */
+export async function createCodexRealtimeCall(
+  auth: CodexAuthHeaders,
+  input: CodexRealtimeCallInput,
+  fetchImpl: CodexFetch = fetch,
+  options: CodexRealtimeCallOptions = {},
+): Promise<CodexRealtimeCallResult> {
+  validateRealtimeInput(input);
+  const timeoutMs = options.timeoutMs ?? CODEX_REALTIME_CALL_TIMEOUT_MS;
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+    throw new CodexRealtimeError("invalid_request", "Codex realtime timeout must be positive");
+  }
+  if (options.signal?.aborted) {
+    throw new CodexRealtimeError("cancelled", "Codex realtime request cancelled");
+  }
+
+  const controller = new AbortController();
+  let timedOut = false;
+  let timeout: ReturnType<typeof setTimeout> | undefined;
+  let rejectCancellation: ((error: CodexRealtimeError) => void) | undefined;
+  const cancellation = new Promise<never>((_resolve, reject) => {
+    rejectCancellation = reject;
+  });
+  const onAbort = (): void => {
+    controller.abort(options.signal?.reason);
+    rejectCancellation?.(new CodexRealtimeError("cancelled", "Codex realtime request cancelled"));
+  };
+  options.signal?.addEventListener("abort", onAbort, { once: true });
+
+  const deadline = new Promise<never>((_resolve, reject) => {
+    timeout = setTimeout(() => {
+      timedOut = true;
+      controller.abort();
+      reject(new CodexRealtimeError("timeout", "Codex realtime request timed out"));
+    }, timeoutMs);
+  });
+
+  const request = (async (): Promise<CodexRealtimeCallResult> => {
+    const response = await fetchImpl(CODEX_REALTIME_CALL_URL, {
+      method: "POST",
+      headers: {
+        ...codexSubscriptionHeaders(auth),
+        "content-type": "application/json",
+        "openai-alpha": "quicksilver=v2",
+        "session-id": input.sessionId,
+        "thread-id": input.sessionId,
+      },
+      body: JSON.stringify({
+        sdp: input.sdp,
+        session: {
+          instructions: input.instructions ?? "",
+          audio: {
+            output: { voice: input.voice ?? CODEX_REALTIME_DEFAULT_VOICE },
+          },
+          delegation: { type: "client" },
+          model: CODEX_REALTIME_MODEL,
+          ...(input.initialItems?.length
+            ? {
+                initial_items: input.initialItems.map((item) => ({
+                  type: "message",
+                  role: item.role,
+                  content: [
+                    {
+                      type: item.role === "assistant" ? "output_text" : "input_text",
+                      text: item.text,
+                    },
+                  ],
+                })),
+              }
+            : {}),
+        },
+      }),
+      signal: controller.signal,
+    });
+
+    if (!response.ok) {
+      await response.body?.cancel().catch(() => undefined);
+      throw providerHttpError(response.status);
+    }
+    const location = response.headers.get("location");
+    if (!location || !validRealtimeLocation(location)) {
+      await response.body?.cancel().catch(() => undefined);
+      throw new CodexRealtimeError(
+        "invalid_response",
+        "Codex realtime response did not identify a compatible call",
+        response.status,
+      );
+    }
+    const sdp = await readBoundedSdp(response);
+    if (!isAudioSdp(sdp)) {
+      throw new CodexRealtimeError(
+        "invalid_response",
+        "Codex realtime response was not an audio SDP answer",
+        response.status,
+      );
+    }
+    return {
+      sdp,
+      version: CODEX_REALTIME_VERSION,
+      model: CODEX_REALTIME_MODEL,
+    };
+  })();
+
+  try {
+    // Promise.race attaches rejection handlers to every branch, so a custom
+    // fetch that ignores AbortSignal cannot produce a late unhandled rejection.
+    return await Promise.race([request, cancellation, deadline]);
+  } catch (error) {
+    if (error instanceof CodexRealtimeError) throw error;
+    if (options.signal?.aborted) {
+      throw new CodexRealtimeError("cancelled", "Codex realtime request cancelled");
+    }
+    if (timedOut || controller.signal.aborted) {
+      throw new CodexRealtimeError("timeout", "Codex realtime request timed out");
+    }
+    throw new CodexRealtimeError("network", "Codex realtime provider request failed");
+  } finally {
+    if (timeout) clearTimeout(timeout);
+    options.signal?.removeEventListener("abort", onAbort);
+  }
+}
+
+/** Shared pin→active selection for worker turns and direct realtime calls. */
+export function selectCodexCredentialId(args: {
+  sessionPinnedCredentialId: string | null;
+  activeCredentialId: string | null;
+  connectedIds: ReadonlySet<string>;
+}): string | null {
+  if (args.sessionPinnedCredentialId && args.connectedIds.has(args.sessionPinnedCredentialId)) {
+    return args.sessionPinnedCredentialId;
+  }
+  if (args.activeCredentialId && args.connectedIds.has(args.activeCredentialId)) {
+    return args.activeCredentialId;
+  }
+  return null;
+}
+
+function validateRealtimeInput(input: CodexRealtimeCallInput): void {
+  if (input.version !== CODEX_REALTIME_VERSION) {
+    throw new CodexRealtimeError(
+      "incompatible",
+      `Codex realtime requires ${CODEX_REALTIME_VERSION}`,
+    );
+  }
+  if (!input.sessionId || input.sessionId.length > 128) {
+    throw new CodexRealtimeError("invalid_request", "Codex realtime session id is invalid");
+  }
+  if (new TextEncoder().encode(input.sdp).byteLength > MAX_REALTIME_SDP_BYTES) {
+    throw new CodexRealtimeError("invalid_request", "Codex realtime SDP offer is too large");
+  }
+  if (!isAudioSdp(input.sdp)) {
+    throw new CodexRealtimeError("invalid_request", "Codex realtime requires an audio SDP offer");
+  }
+  if (input.voice !== undefined && !CODEX_REALTIME_VOICES.includes(input.voice)) {
+    throw new CodexRealtimeError("invalid_request", "Codex realtime voice is unsupported");
+  }
+  const initialItems = input.initialItems ?? [];
+  if (initialItems.length > CODEX_REALTIME_INITIAL_ITEMS_MAX_COUNT) {
+    throw new CodexRealtimeError(
+      "invalid_request",
+      `Codex realtime history exceeds ${CODEX_REALTIME_INITIAL_ITEMS_MAX_COUNT} items`,
+    );
+  }
+  let estimatedTokens = 0;
+  for (const item of initialItems) {
+    if (
+      (item.role !== "user" && item.role !== "developer" && item.role !== "assistant") ||
+      typeof item.text !== "string"
+    ) {
+      throw new CodexRealtimeError("invalid_request", "Codex realtime history item is invalid");
+    }
+    const itemTokens = Math.ceil(new TextEncoder().encode(item.text).byteLength / 4);
+    if (itemTokens > CODEX_REALTIME_INITIAL_ITEMS_MAX_TOKENS) {
+      throw new CodexRealtimeError("invalid_request", "Codex realtime history item is too large");
+    }
+    estimatedTokens += itemTokens;
+  }
+  if (estimatedTokens > CODEX_REALTIME_INITIAL_ITEMS_MAX_TOKENS) {
+    throw new CodexRealtimeError("invalid_request", "Codex realtime history is too large");
+  }
+}
+
+function providerHttpError(status: number): CodexRealtimeError {
+  if (status === 401) {
+    return new CodexRealtimeError(
+      "authentication",
+      "Codex subscription rejected authentication",
+      status,
+    );
+  }
+  if (status === 403) {
+    return new CodexRealtimeError(
+      "entitlement",
+      "Codex subscription lacks realtime entitlement",
+      status,
+    );
+  }
+  if (status === 404) {
+    return new CodexRealtimeError(
+      "incompatible",
+      "Codex subscription realtime is unavailable",
+      status,
+    );
+  }
+  if (status === 429) {
+    return new CodexRealtimeError("rate_limited", "Codex realtime is rate limited", status);
+  }
+  return new CodexRealtimeError("provider", "Codex realtime provider request failed", status);
+}
+
+function validRealtimeLocation(location: string): boolean {
+  const path = location.split("?", 1)[0] ?? "";
+  const segment = path.split("/").filter(Boolean).at(-1) ?? "";
+  return REALTIME_CALL_ID.test(segment);
+}
+
+function isAudioSdp(sdp: string): boolean {
+  return /^v=0(?:\r?\n)/.test(sdp) && /(?:^|\r?\n)m=audio\s/m.test(sdp);
+}
+
+async function readBoundedSdp(response: Response): Promise<string> {
+  const declared = Number(response.headers.get("content-length"));
+  if (Number.isFinite(declared) && declared > MAX_REALTIME_SDP_BYTES) {
+    await response.body?.cancel().catch(() => undefined);
+    throw new CodexRealtimeError(
+      "invalid_response",
+      "Codex realtime SDP answer is too large",
+      response.status,
+    );
+  }
+  if (!response.body) return "";
+  const reader = response.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  try {
+    while (true) {
+      const next = await reader.read();
+      if (next.done) break;
+      total += next.value.byteLength;
+      if (total > MAX_REALTIME_SDP_BYTES) {
+        await reader.cancel();
+        throw new CodexRealtimeError(
+          "invalid_response",
+          "Codex realtime SDP answer is too large",
+          response.status,
+        );
+      }
+      chunks.push(next.value);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  const bytes = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  try {
+    return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+  } catch {
+    throw new CodexRealtimeError(
+      "invalid_response",
+      "Codex realtime SDP answer was not valid UTF-8",
+      response.status,
+    );
+  }
+}

package/src/request-context.ts

@@ -96,6 +96,26 @@ export type CodexRequestContext = {
   onModelRequestEvent?: (event: CodexModelRequestEvent) => Promise<void> | void;
   /** Stable request identity supplied by the owning durable execution. */
   nextRequestId?: () => string;
+  /**
+   * Optional Codex beta feature flags advertised as `x-codex-beta-features`
+   * (comma-separated). Used for remote compaction v2 (`remote_compaction_v2`).
+   */
+  betaFeatures?: readonly string[];
+  /**
+   * Optional turn analytics / routing metadata sent as `x-codex-turn-metadata`
+   * (JSON). Body `metadata` is stripped by normalize — never put request_kind there.
+   */
+  turnMetadata?: Record<string, unknown>;
 };
 
 export const codexRequestStorage = new AsyncLocalStorage<CodexRequestContext>();
+
+/** Nest a Codex ALS scope with header overrides (e.g. remote compaction v2). */
+export function withCodexRequestOverrides<T>(
+  overrides: Pick<CodexRequestContext, "betaFeatures" | "turnMetadata">,
+  fn: () => T,
+): T {
+  const current = codexRequestStorage.getStore();
+  if (!current) return fn();
+  return codexRequestStorage.run({ ...current, ...overrides }, fn);
+}

package/dist/chunk-YGKQDUY7.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/constants.ts"],"sourcesContent":["// Wire constants for the ChatGPT/Codex subscription backend.\n// Source: CODEX-SUBSCRIPTION-SPEC.md (verified against openai/codex codex-rs).\n\nexport const CODEX_ISSUER = \"https://auth.openai.com\";\nexport const CODEX_CLIENT_ID = \"app_EMoamEEZ73f0CkXaXp7hrann\"; // spec §1.1 (manager.rs:1444)\nexport const CODEX_AUTH_BASE = `${CODEX_ISSUER}/api/accounts`; // device endpoints (device_code_auth.rs:164)\nexport const CODEX_TOKEN_URL = `${CODEX_ISSUER}/oauth/token`; // exchange (form) + refresh (json)\nexport const CODEX_DEVICE_VERIFICATION_URL = `${CODEX_ISSUER}/codex/device`;\nexport const CODEX_DEVICE_REDIRECT_URI = `${CODEX_ISSUER}/deviceauth/callback`;\n\n// Model requests: base already includes /codex; client appends /responses, /models.\nexport const CODEX_RESPONSES_BASE = \"https://chatgpt.com/backend-api/codex\";\n// Usage lives on the WHAM base — NOT under /codex (verified, spec §1.8a).\nexport const CODEX_WHAM_BASE = \"https://chatgpt.com/backend-api\";\n\nexport const CODEX_ORIGINATOR = \"codex_cli_rs\"; // whitelisted originator (spec §1.2)\nexport const CODEX_ID_TOKEN_AUTH_CLAIM = \"https://api.openai.com/auth\";\n\n// Synthetic registry-provider identity. The provider's baseURL is the bare\n// /backend-api (NOT /codex) — codexSubscriptionFetch rewrites /responses ->\n// /codex/responses. Codex model ids are namespaced `codex/<slug>` so they never\n// collide with the built-in OpenAI provider's model ids; the fetch's resolveModel\n// strips the prefix before the slug reaches the backend.\nexport const CODEX_PROVIDER_ID = \"codex-subscription\";\nexport const CODEX_PROVIDER_BASE_URL = \"https://chatgpt.com/backend-api\";\nexport const CODEX_MODEL_ID_PREFIX = \"codex/\";\n\n// The only Codex subscription models OpenGeni exposes. The live GET /models\n// catalog must contain every exact slug; older or internal models never broaden\n// this product allowlist.\nexport const CODEX_FALLBACK_MODEL_SLUGS = [\"gpt-5.6-sol\", \"gpt-5.6-terra\", \"gpt-5.6-luna\"] as const;\n\n// Live Codex model-catalog values for every exposed gpt-5.6 subscription slug.\n// Verified 2026-07-18 against Codex CLI 0.144.6's freshly fetched\n// ~/.codex/models_cache.json and the matching openai/codex core derivations:\n//   raw context window                = 272,000\n//   effective input window (95%)      = 258,400\n//   automatic compaction limit (90%)  = 244,800\n// Keep all three explicit: the effective ceiling is a hard input guard while\n// the lower auto-compact limit is the proactive checkpoint trigger.\nexport const CODEX_MODEL_CONTEXT_WINDOW_TOKENS = 272_000;\nexport const CODEX_EFFECTIVE_CONTEXT_WINDOW_PERCENT = 95;\nexport const CODEX_MODEL_EFFECTIVE_CONTEXT_WINDOW_TOKENS = Math.floor(\n  (CODEX_MODEL_CONTEXT_WINDOW_TOKENS * CODEX_EFFECTIVE_CONTEXT_WINDOW_PERCENT) / 100,\n);\nexport const CODEX_AUTO_COMPACTION_PERCENT = 90;\nexport const CODEX_MODEL_AUTO_COMPACT_TOKEN_LIMIT = Math.floor(\n  (CODEX_MODEL_CONTEXT_WINDOW_TOKENS * CODEX_AUTO_COMPACTION_PERCENT) / 100,\n);\n\n// Sent as the `version` header and inside the User-Agent. Staging-proven on\n// 2026-07-09: 0.142.4 filtered every GPT-5.6 slug out of GET /models, while the\n// official Codex 0.144.0+ releases return all three exact slugs above. Keep\n// this pinned to the latest stable Codex release we have verified end-to-end.\nexport const CODEX_CLIENT_VERSION = \"0.144.6\";\n\nexport const CODEX_REFRESH_WINDOW_MS = 5 * 60 * 1000; // proactive refresh when within 5 min of exp (spec §1.1)\nexport const CODEX_REFRESH_FALLBACK_MS = 8 * 24 * 60 * 60 * 1000; // 8 days when exp is unparseable\n\n// Codex Responses transport deadlines. The OpenAI SDK's own timeout only covers\n// the wait for response headers and erases the underlying timeout class into the\n// bare `Request timed out.` error. Keep the provider-specific budgets here so\n// the transport can enforce and durably report them without enabling the SDK's\n// blind request replay.\nexport const CODEX_RESPONSE_HEADERS_TIMEOUT_MS = 4 * 60_000;\nexport const CODEX_RESPONSE_STREAM_IDLE_TIMEOUT_MS = 5 * 60_000;\nexport const CODEX_RESPONSE_WHOLE_TIMEOUT_MS = 30 * 60_000;\n// Kept as a compatibility-shaped policy field, but automatic replay is disabled\n// until a provider-specific operation receipt can prove non-acceptance or resume\n// the same operation identity. An absent response does not prove that the\n// provider never accepted the request.\nexport const CODEX_RESPONSE_NO_BYTE_RETRIES = 0;\nexport const CODEX_RESPONSE_RETRY_BACKOFF_MS = 1_000;\n// Must exceed the transport-owned whole-response deadline. This SDK guard is a\n// last-resort envelope; the inner transport emits the typed/durable failure.\nexport const CODEX_RESPONSE_SDK_OUTER_TIMEOUT_MS = 35 * 60_000;\n\n// ── Apps / connectors MCP (spec §1.10, §E) ───────────────────────────────────\n// One server-side MCP exposes ALL the user's ChatGPT/Codex connectors\n// (gmail/github/linear/slack/sentry/drive/calendar/…). Streamable HTTP, always.\nexport const CODEX_APPS_MCP_SERVER_ID = \"codex_apps\"; // tools surface as mcp__codex_apps__<tool>\nexport const CODEX_APPS_MCP_SERVER_NAME = \"codex_apps\"; // MCP `name` — MUST equal the id so the SDK namespaces tools as mcp__codex_apps__*\nexport const CODEX_APPS_MCP_URL = \"https://chatgpt.com/backend-api/ps/mcp\"; // live URL (NOT /codex, NOT the legacy /wham/apps)\nexport const CODEX_APPS_STARTUP_TIMEOUT_MS = 30_000; // startup_timeout 30s (spec §1.10) — maps to timeoutMs on this server only\n// Connector scopes that the apps MCP requires. Present ONLY when granted at\n// browser-authorize time; the device-code path CANNOT be confirmed to grant\n// them, so treat connector availability as runtime-discovered (spec §1.10 / §E).\nexport const CODEX_APPS_REQUIRED_SCOPES = [\"api.connectors.read\", \"api.connectors.invoke\"] as const;\n"],"mappings":";AAGO,IAAM,eAAe;AACrB,IAAM,kBAAkB;AACxB,IAAM,kBAAkB,GAAG,YAAY;AACvC,IAAM,kBAAkB,GAAG,YAAY;AACvC,IAAM,gCAAgC,GAAG,YAAY;AACrD,IAAM,4BAA4B,GAAG,YAAY;AAGjD,IAAM,uBAAuB;AAE7B,IAAM,kBAAkB;AAExB,IAAM,mBAAmB;AACzB,IAAM,4BAA4B;AAOlC,IAAM,oBAAoB;AAC1B,IAAM,0BAA0B;AAChC,IAAM,wBAAwB;AAK9B,IAAM,6BAA6B,CAAC,eAAe,iBAAiB,cAAc;AAUlF,IAAM,oCAAoC;AAC1C,IAAM,yCAAyC;AAC/C,IAAM,8CAA8C,KAAK;AAAA,EAC7D,oCAAoC,yCAA0C;AACjF;AACO,IAAM,gCAAgC;AACtC,IAAM,uCAAuC,KAAK;AAAA,EACtD,oCAAoC,gCAAiC;AACxE;AAMO,IAAM,uBAAuB;AAE7B,IAAM,0BAA0B,IAAI,KAAK;AACzC,IAAM,4BAA4B,IAAI,KAAK,KAAK,KAAK;AAOrD,IAAM,oCAAoC,IAAI;AAC9C,IAAM,wCAAwC,IAAI;AAClD,IAAM,kCAAkC,KAAK;AAK7C,IAAM,iCAAiC;AACvC,IAAM,kCAAkC;AAGxC,IAAM,sCAAsC,KAAK;AAKjD,IAAM,2BAA2B;AACjC,IAAM,6BAA6B;AACnC,IAAM,qBAAqB;AAC3B,IAAM,gCAAgC;AAItC,IAAM,6BAA6B,CAAC,uBAAuB,uBAAuB;","names":[]}