@juspay/neurolink 11.2.0 → 11.2.2

package/dist/server/routes/codexProxyRoutes.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Codex (OpenAI ChatGPT) Proxy Routes
+ *
+ * Exposes `POST /backend-api/codex/responses` — the ChatGPT-backend Responses
+ * API endpoint the Codex CLI talks to — and pools it across multiple ChatGPT
+ * OAuth accounts, mirroring the Anthropic Claude pool engine.
+ *
+ * A Codex CLI configured with `model_providers.<name>.base_url` pointing at this
+ * proxy sends its own OAuth token; the proxy strips it, selects a pooled
+ * `codex:*` account, attaches that account's Bearer + matching chatgpt-account-id,
+ * forwards to https://chatgpt.com/backend-api/codex, and relays the SSE stream.
+ * On quota exhaustion (429 / usage limit) the account is cooled and the next
+ * account is tried — so the user never has to switch accounts by hand.
+ *
+ * This engine is deliberately leaner than claudeProxyRoutes.ts: it reuses the
+ * shared cooldown/quota persistence (keyed by the `codex:` account key so it
+ * never collides with anthropic entries) and does pre-commit rotation only, not
+ * the full transient-budget / admission machinery.
+ */
+import type { AccountCoolingReason, AccountQuota, CodexRuntimeAccount, RouteGroup } from "../../types/index.js";
+/** Refresh an account's token at most once at a time. */
+declare function refreshCodexTokenOnce(key: string, refreshToken: string): Promise<{
+    accessToken: string;
+    refreshToken: string;
+    expiresAt?: number;
+}>;
+/**
+ * Load the Codex account pool from the token store, refreshing expired OAuth
+ * tokens and hydrating cooldown + quota state from disk.
+ */
+declare function loadCodexProxyAccounts(): Promise<CodexRuntimeAccount[]>;
+/**
+ * Order accounts fill-first by quota: eligible (not cooling) first, then least
+ * session utilization, treating unknown quota as "probe first" so a fresh
+ * account gets observed rather than starved.
+ */
+declare function orderCodexAccounts(accounts: CodexRuntimeAccount[], now: number): CodexRuntimeAccount[];
+/** Build the upstream request headers, replacing client auth with the account's. */
+declare function buildCodexUpstreamHeaders(clientHeaders: Record<string, string>, account: CodexRuntimeAccount): Record<string, string>;
+/**
+ * Classify a 429 into a cooldown plan. Codex reports primary (session) and
+ * secondary (weekly) windows; a rejected window cools until its reset, a plain
+ * burst limit cools briefly and clamps to 15 min.
+ */
+declare function planCodexCooldown(quota: AccountQuota | null, retryAfterMs: number, now: number): {
+    coolingUntil: number;
+    reason: AccountCoolingReason;
+};
+/**
+ * Create Codex proxy routes.
+ *
+ * @param basePath - Base path prefix (default "").
+ * @returns RouteGroup with the Codex backend Responses endpoint.
+ */
+export declare function createCodexProxyRoutes(basePath?: string): RouteGroup;
+export declare const __testHooks: {
+    loadCodexProxyAccounts: typeof loadCodexProxyAccounts;
+    orderCodexAccounts: typeof orderCodexAccounts;
+    buildCodexUpstreamHeaders: typeof buildCodexUpstreamHeaders;
+    planCodexCooldown: typeof planCodexCooldown;
+    refreshCodexTokenOnce: typeof refreshCodexTokenOnce;
+    codexRefreshInFlightSize: () => number;
+};
+export {};

package/dist/server/routes/codexProxyRoutes.js

@@ -0,0 +1,453 @@
+/**
+ * Codex (OpenAI ChatGPT) Proxy Routes
+ *
+ * Exposes `POST /backend-api/codex/responses` — the ChatGPT-backend Responses
+ * API endpoint the Codex CLI talks to — and pools it across multiple ChatGPT
+ * OAuth accounts, mirroring the Anthropic Claude pool engine.
+ *
+ * A Codex CLI configured with `model_providers.<name>.base_url` pointing at this
+ * proxy sends its own OAuth token; the proxy strips it, selects a pooled
+ * `codex:*` account, attaches that account's Bearer + matching chatgpt-account-id,
+ * forwards to https://chatgpt.com/backend-api/codex, and relays the SSE stream.
+ * On quota exhaustion (429 / usage limit) the account is cooled and the next
+ * account is tried — so the user never has to switch accounts by hand.
+ *
+ * This engine is deliberately leaner than claudeProxyRoutes.ts: it reuses the
+ * shared cooldown/quota persistence (keyed by the `codex:` account key so it
+ * never collides with anthropic entries) and does pre-commit rotation only, not
+ * the full transient-budget / admission machinery.
+ */
+import { tokenStore } from "../../auth/tokenStore.js";
+import { CODEX_ORIGINATOR, CODEX_RESPONSES_URL, CODEX_USER_AGENT, codexTokenNeedsRefresh, isPermanentCodexRefreshFailure, refreshCodexToken, resolveCodexAccountId, } from "../../auth/codexOAuth.js";
+import { clearAccountCooldown, loadAccountCooldowns, saveAccountCooldown, } from "../../proxy/accountCooldown.js";
+import { loadAccountQuotas, saveAccountQuota, } from "../../proxy/accountQuota.js";
+import { CODEX_ACCOUNT_PREFIX, parseCodexRateLimitHeaders, } from "../../proxy/codexAccountUsage.js";
+import { logRequest } from "../../proxy/requestLogger.js";
+import { parseRetryAfterMs } from "../../proxy/routingPolicy.js";
+import { sanitizeForLog } from "../../utils/logSanitize.js";
+import { logger } from "../../utils/logger.js";
+const CODEX_UPSTREAM_TIMEOUT_MS = 15 * 60 * 1000; // 15 min, matches Claude path
+const DEFAULT_TRANSIENT_COOLDOWN_MS = 60_000;
+const MAX_TRANSIENT_COOLDOWN_MS = 15 * 60 * 1000;
+/** Brief park after a refresh attempt that never reached a verdict. */
+const CODEX_AUTH_COOLDOWN_MS = 60_000;
+/**
+ * In-flight proactive refreshes, keyed by account.
+ *
+ * The pool is rebuilt per request with no shared state, so without this every
+ * concurrent request for the same account fires its own refresh. OpenAI rotates
+ * the refresh token on each call, so those attempts invalidate one another — the
+ * losers then see a rejected grant and, via the 401 path, can disable an account
+ * that is perfectly healthy.
+ */
+const codexRefreshInFlight = new Map();
+/** Refresh an account's token at most once at a time. */
+async function refreshCodexTokenOnce(key, refreshToken) {
+    const existing = codexRefreshInFlight.get(key);
+    if (existing) {
+        return existing;
+    }
+    const pending = (async () => {
+        // Re-read the stored token instead of trusting the caller's snapshot. A
+        // request that captured the pool just before a previous refresh completed
+        // holds a token that has since been rotated; using it would spend a real
+        // attempt on a grant the server has already invalidated.
+        const latest = await tokenStore.peekTokens(key).catch(() => null);
+        const current = latest?.refreshToken ?? refreshToken;
+        const refreshed = await refreshCodexToken(current);
+        return {
+            accessToken: refreshed.accessToken,
+            refreshToken: refreshed.refreshToken ?? current,
+            expiresAt: refreshed.expiresAt,
+        };
+    })().finally(() => {
+        codexRefreshInFlight.delete(key);
+    });
+    codexRefreshInFlight.set(key, pending);
+    return pending;
+}
+// Headers we never forward upstream (hop-by-hop, client creds, or things we
+// re-derive). The client's own auth is replaced with the pooled account's.
+const BLOCKED_UPSTREAM_HEADERS = new Set([
+    "host",
+    "connection",
+    "content-length",
+    "transfer-encoding",
+    "cookie",
+    "proxy-authorization",
+    "authorization",
+    "x-api-key",
+    "chatgpt-account-id",
+    "accept-encoding",
+]);
+/** Build a Codex error body as a Response with the intended status. */
+function buildCodexErrorResponse(status, message) {
+    return new Response(JSON.stringify({ error: { type: "proxy_error", message } }), { status, headers: { "content-type": "application/json" } });
+}
+/**
+ * Load the Codex account pool from the token store, refreshing expired OAuth
+ * tokens and hydrating cooldown + quota state from disk.
+ */
+async function loadCodexProxyAccounts() {
+    const keys = await tokenStore.listByPrefix(CODEX_ACCOUNT_PREFIX);
+    const [cooldowns, quotas] = await Promise.all([
+        loadAccountCooldowns(),
+        loadAccountQuotas(),
+    ]);
+    const now = Date.now();
+    const accounts = [];
+    for (const key of keys) {
+        if (await tokenStore.isDisabled(key)) {
+            continue;
+        }
+        const tokens = await tokenStore.loadTokens(key);
+        if (!tokens || tokens.tokenType !== "Bearer") {
+            // Only OAuth (Bearer) accounts can serve the ChatGPT backend.
+            continue;
+        }
+        let accessToken = tokens.accessToken;
+        let expiresAt = tokens.expiresAt;
+        if (codexTokenNeedsRefresh(expiresAt) && tokens.refreshToken) {
+            try {
+                const refreshed = await refreshCodexTokenOnce(key, tokens.refreshToken);
+                accessToken = refreshed.accessToken;
+                expiresAt = refreshed.expiresAt ?? expiresAt;
+                await tokenStore.saveTokens(key, {
+                    accessToken,
+                    refreshToken: refreshed.refreshToken,
+                    expiresAt: expiresAt ?? Date.now() + 3_600_000,
+                    tokenType: "Bearer",
+                    scope: tokens.scope,
+                });
+            }
+            catch (error) {
+                // Keep the stale token; a 401 upstream will trigger rotation.
+                logger.debug(`Codex proactive refresh failed for ${key.slice(CODEX_ACCOUNT_PREFIX.length)}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        const cooldown = cooldowns[key];
+        const cooling = cooldown && cooldown.coolingUntil > now;
+        accounts.push({
+            key,
+            label: key.slice(CODEX_ACCOUNT_PREFIX.length) || key,
+            token: accessToken,
+            refreshToken: tokens.refreshToken,
+            expiresAt,
+            accountId: resolveCodexAccountId(accessToken),
+            quota: quotas[key],
+            coolingUntil: cooling ? cooldown.coolingUntil : undefined,
+            coolingReason: cooldown?.reason,
+            // Kept even once expired: an account only reaches the request loop when it
+            // is NOT cooling, so this is the only handle the success path has for
+            // deleting the spent record. Without it they accumulate forever.
+            expiredCooldownUntil: cooldown && !cooling ? cooldown.coolingUntil : undefined,
+        });
+    }
+    return accounts;
+}
+/**
+ * Order accounts fill-first by quota: eligible (not cooling) first, then least
+ * session utilization, treating unknown quota as "probe first" so a fresh
+ * account gets observed rather than starved.
+ */
+function orderCodexAccounts(accounts, now) {
+    return [...accounts].sort((a, b) => {
+        const aCooling = a.coolingUntil !== undefined && a.coolingUntil > now;
+        const bCooling = b.coolingUntil !== undefined && b.coolingUntil > now;
+        if (aCooling !== bCooling) {
+            return aCooling ? 1 : -1;
+        }
+        const aUsed = a.quota ? a.quota.sessionUsed : -1;
+        const bUsed = b.quota ? b.quota.sessionUsed : -1;
+        return aUsed - bUsed;
+    });
+}
+/** Build the upstream request headers, replacing client auth with the account's. */
+function buildCodexUpstreamHeaders(clientHeaders, account) {
+    const headers = {};
+    for (const [name, value] of Object.entries(clientHeaders)) {
+        const lower = name.toLowerCase();
+        if (BLOCKED_UPSTREAM_HEADERS.has(lower)) {
+            continue;
+        }
+        headers[lower] = value;
+    }
+    headers.authorization = `Bearer ${account.token}`;
+    const accountId = resolveCodexAccountId(account.token, account.accountId);
+    if (accountId) {
+        headers["chatgpt-account-id"] = accountId;
+    }
+    headers["content-type"] = "application/json";
+    if (!headers["user-agent"]) {
+        headers["user-agent"] = CODEX_USER_AGENT;
+    }
+    if (!headers.originator) {
+        headers.originator = CODEX_ORIGINATOR;
+    }
+    if (!headers.accept) {
+        headers.accept = "text/event-stream";
+    }
+    return headers;
+}
+/**
+ * Classify a 429 into a cooldown plan. Codex reports primary (session) and
+ * secondary (weekly) windows; a rejected window cools until its reset, a plain
+ * burst limit cools briefly and clamps to 15 min.
+ */
+function planCodexCooldown(quota, retryAfterMs, now) {
+    // A reported reset can already be in the past — a stale header, or a clock
+    // skew. Taken literally the account is eligible again immediately and the
+    // pool re-sends to something the provider just rejected.
+    const floor = now + DEFAULT_TRANSIENT_COOLDOWN_MS;
+    if (quota) {
+        if (quota.weeklyStatus === "rejected" && quota.weeklyResetAt > 0) {
+            return {
+                coolingUntil: Math.max(quota.weeklyResetAt * 1000, floor),
+                reason: "weekly",
+            };
+        }
+        if (quota.sessionStatus === "rejected" && quota.sessionResetAt > 0) {
+            return {
+                coolingUntil: Math.max(quota.sessionResetAt * 1000, floor),
+                reason: "session",
+            };
+        }
+    }
+    const delay = Math.min(MAX_TRANSIENT_COOLDOWN_MS, Math.max(retryAfterMs, DEFAULT_TRANSIENT_COOLDOWN_MS));
+    return { coolingUntil: now + delay, reason: "transient" };
+}
+/** Set the x-neurolink-* attribution headers on the context. */
+function publishCodexHeaders(ctx, account, attempt, quota) {
+    if (!ctx.responseHeaders) {
+        ctx.responseHeaders = {};
+    }
+    ctx.responseHeaders["x-neurolink-account"] = account.label;
+    ctx.responseHeaders["x-neurolink-account-type"] = "codex-oauth";
+    ctx.responseHeaders["x-neurolink-served-by"] = "codex";
+    ctx.responseHeaders["x-neurolink-attempt"] = String(attempt);
+    ctx.responseHeaders["x-neurolink-quota-source"] = quota ? "live" : "none";
+    if (quota) {
+        ctx.responseHeaders["x-neurolink-quota-session-left-pct"] = String(Math.round((1 - quota.sessionUsed) * 100));
+        ctx.responseHeaders["x-neurolink-weekly-left-pct"] = String(Math.round((1 - quota.weeklyUsed) * 100));
+    }
+}
+/** Core pooled handler for POST /backend-api/codex/responses. */
+async function handleCodexResponsesRequest(ctx) {
+    const requestStartTime = Date.now();
+    const body = ctx.body ?? {};
+    const bodyStr = JSON.stringify(body);
+    const model = typeof body.model === "string"
+        ? body.model
+        : "-";
+    const writeLog = (account, responseStatus, extra = {}) => logRequest({
+        timestamp: new Date().toISOString(),
+        requestId: ctx.requestId,
+        method: ctx.method,
+        path: ctx.path,
+        model,
+        stream: true,
+        toolCount: Array.isArray(body.tools)
+            ? body.tools.length
+            : 0,
+        account,
+        accountType: "codex-oauth",
+        responseStatus,
+        responseTimeMs: Date.now() - requestStartTime,
+        ...extra,
+    });
+    const accounts = await loadCodexProxyAccounts();
+    if (accounts.length === 0) {
+        await writeLog("", 401, {
+            errorType: "no_accounts",
+            errorMessage: "No Codex accounts",
+        });
+        return buildCodexErrorResponse(401, "No Codex accounts configured. Run `neurolink auth login codex`.");
+    }
+    const now = Date.now();
+    const ordered = orderCodexAccounts(accounts, now);
+    const eligible = ordered.filter((a) => !(a.coolingUntil !== undefined && a.coolingUntil > now));
+    if (eligible.length === 0) {
+        // Every account is cooling; surface the soonest recovery as retry-after.
+        const soonest = ordered.reduce((min, a) => {
+            if (a.coolingUntil === undefined) {
+                return min;
+            }
+            return min === undefined ? a.coolingUntil : Math.min(min, a.coolingUntil);
+        }, undefined);
+        const retryAfterSec = soonest
+            ? Math.max(1, Math.ceil((soonest - now) / 1000))
+            : 60;
+        await writeLog("", 429, {
+            errorType: "all_accounts_cooling",
+            errorMessage: "All Codex accounts are rate-limited",
+        });
+        return new Response(JSON.stringify({
+            error: {
+                type: "rate_limit_error",
+                message: "All Codex accounts are currently rate-limited",
+            },
+        }), {
+            status: 429,
+            headers: {
+                "content-type": "application/json",
+                "retry-after": String(retryAfterSec),
+            },
+        });
+    }
+    let attempt = 0;
+    let lastErrorMessage = "All Codex accounts failed";
+    let lastErrorStatus = 502;
+    for (const account of eligible) {
+        attempt += 1;
+        let authRetried = false;
+        // Same-account loop only re-runs once, for a post-401 token refresh.
+        for (;;) {
+            let upstream;
+            try {
+                upstream = await fetch(CODEX_RESPONSES_URL, {
+                    method: "POST",
+                    headers: buildCodexUpstreamHeaders(ctx.headers, account),
+                    body: bodyStr,
+                    signal: AbortSignal.timeout(CODEX_UPSTREAM_TIMEOUT_MS),
+                });
+            }
+            catch (error) {
+                // A transport failure message is derived from local state — resolved
+                // hostnames, socket paths, Node internals — and says nothing the caller
+                // can act on. Keep the detail in the log and return a fixed string, so
+                // internal topology never reaches the client.
+                logger.debug(`Codex upstream fetch failed (${account.label}): ${sanitizeForLog(error instanceof Error ? error.message : String(error))}`);
+                lastErrorMessage = "Codex upstream request failed";
+                lastErrorStatus = 502;
+                break; // rotate to next account
+            }
+            if (upstream.ok) {
+                const quota = parseCodexRateLimitHeaders(upstream.headers);
+                if (quota) {
+                    saveAccountQuota(account.key, quota).catch(() => undefined);
+                }
+                // A prior cooldown that has expired is cleared on success. The
+                // compare-and-swap guards against wiping a longer cooldown that another
+                // in-flight request set while this one was upstream.
+                if (account.expiredCooldownUntil !== undefined) {
+                    clearAccountCooldown(account.key, account.expiredCooldownUntil).catch(() => undefined);
+                }
+                publishCodexHeaders(ctx, account, attempt, quota);
+                await writeLog(account.label, upstream.status);
+                const headers = {
+                    "content-type": upstream.headers.get("content-type") ?? "text/event-stream",
+                    "cache-control": "no-cache",
+                    connection: "keep-alive",
+                    ...(ctx.responseHeaders ?? {}),
+                };
+                return new Response(upstream.body, {
+                    status: upstream.status,
+                    headers,
+                });
+            }
+            const errText = await upstream.text().catch(() => "");
+            // 401/403 → try a forced token refresh once, then rotate.
+            if ((upstream.status === 401 || upstream.status === 403) &&
+                !authRetried &&
+                account.refreshToken) {
+                authRetried = true;
+                const staleTokens = {
+                    accessToken: account.token,
+                    refreshToken: account.refreshToken,
+                    expiresAt: account.expiresAt ?? 0,
+                };
+                try {
+                    const refreshed = await refreshCodexToken(account.refreshToken);
+                    account.token = refreshed.accessToken;
+                    account.refreshToken = refreshed.refreshToken ?? account.refreshToken;
+                    account.expiresAt = refreshed.expiresAt ?? account.expiresAt;
+                    account.accountId = resolveCodexAccountId(refreshed.accessToken);
+                    await tokenStore.saveTokens(account.key, {
+                        accessToken: account.token,
+                        refreshToken: account.refreshToken,
+                        expiresAt: account.expiresAt ?? Date.now() + 3_600_000,
+                        tokenType: "Bearer",
+                    });
+                    continue; // retry same account with the fresh token
+                }
+                catch (error) {
+                    if (isPermanentCodexRefreshFailure(error)) {
+                        // Compare-and-swap: the pool is rebuilt per request with no shared
+                        // state, so a concurrent request may already have rotated this
+                        // credential. Disabling unconditionally would kill the account that
+                        // the other request just healed.
+                        const disabled = await tokenStore.markDisabledIfCurrent(account.key, staleTokens, "refresh_invalid");
+                        if (disabled) {
+                            logger.always(`[proxy] codex account=${account.label} disabled until re-authentication. Run: neurolink auth login codex --label ${account.label}`);
+                        }
+                        lastErrorStatus = 401;
+                        lastErrorMessage = "Codex token refresh failed; re-login required";
+                        break;
+                    }
+                    // No verdict on the credential — cool briefly and try the next
+                    // account, so a 5xx or a timeout cannot cost the user a login.
+                    await saveAccountCooldown(account.key, Date.now() + CODEX_AUTH_COOLDOWN_MS, "auth").catch(() => undefined);
+                    logger.debug(`[proxy] codex account=${account.label} refresh failed transiently; cooling and rotating`);
+                    lastErrorStatus = 503;
+                    lastErrorMessage = "Codex token refresh temporarily unavailable";
+                    break;
+                }
+            }
+            // 429 → cooldown + rotate.
+            if (upstream.status === 429) {
+                const quota = parseCodexRateLimitHeaders(upstream.headers);
+                if (quota) {
+                    saveAccountQuota(account.key, quota).catch(() => undefined);
+                }
+                const retryAfterMs = parseRetryAfterMs(upstream.headers.get("retry-after"));
+                const plan = planCodexCooldown(quota, retryAfterMs, Date.now());
+                await saveAccountCooldown(account.key, plan.coolingUntil, plan.reason).catch(() => undefined);
+                lastErrorStatus = 429;
+                lastErrorMessage = "Codex account rate-limited";
+                break; // rotate
+            }
+            // Other non-ok → record and rotate.
+            if (upstream.status === 401 || upstream.status === 403) {
+                // Reached only when the account has no refresh token to retry with, so
+                // it will fail identically on the next request. Park it briefly instead
+                // of letting it stay first in line with unknown quota.
+                await saveAccountCooldown(account.key, Date.now() + CODEX_AUTH_COOLDOWN_MS, "auth").catch(() => undefined);
+            }
+            lastErrorStatus = upstream.status >= 500 ? 502 : upstream.status;
+            lastErrorMessage = sanitizeForLog(errText).slice(0, 200) || "Codex error";
+            break; // rotate
+        }
+    }
+    await writeLog("", lastErrorStatus, {
+        errorType: "all_accounts_failed",
+        errorMessage: lastErrorMessage,
+    });
+    return buildCodexErrorResponse(lastErrorStatus, lastErrorMessage);
+}
+/**
+ * Create Codex proxy routes.
+ *
+ * @param basePath - Base path prefix (default "").
+ * @returns RouteGroup with the Codex backend Responses endpoint.
+ */
+export function createCodexProxyRoutes(basePath = "") {
+    return {
+        prefix: `${basePath}/backend-api/codex`,
+        routes: [
+            {
+                method: "POST",
+                path: `${basePath}/backend-api/codex/responses`,
+                description: "Codex ChatGPT-backend Responses API (account pool)",
+                handler: (ctx) => handleCodexResponsesRequest(ctx),
+            },
+        ],
+    };
+}
+export const __testHooks = {
+    loadCodexProxyAccounts,
+    orderCodexAccounts,
+    buildCodexUpstreamHeaders,
+    planCodexCooldown,
+    refreshCodexTokenOnce,
+    codexRefreshInFlightSize: () => codexRefreshInFlight.size,
+};

package/dist/types/cli.d.ts

@@ -956,6 +956,12 @@ export type AuthCommandArgs = BaseCommandArgs & {
     config?: string;
     /** Email passed to `auth set-primary <email>` */
     email?: string;
+    /** Why an account is being disabled, recorded by `auth disable` */
+    reason?: string;
+    /** Subcommand verb for `auth cooldown <action>` */
+    action?: string;
+    /** `auth cooldown clear --all` */
+    all?: boolean;
     /** Yargs positional arguments */
     _?: (string | number)[];
 };
@@ -1211,7 +1217,7 @@ export type ProviderSetupConfig = {
     isReconfiguring?: boolean;
 };
 /** Providers supported by the `neurolink auth` command. */
-export type SupportedProvider = "anthropic";
+export type SupportedProvider = "anthropic" | "codex";
 /** Arguments for `neurolink autoresearch init`. */
 export type AutoresearchInitArgs = {
     repoPath: string;

package/dist/types/codex.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Codex (OpenAI ChatGPT subscription) proxy types.
+ *
+ * Codex authenticates with a ChatGPT account over OAuth and talks to the
+ * ChatGPT backend Responses API (https://chatgpt.com/backend-api/codex).
+ * These types describe the on-disk `~/.codex/auth.json` shape we import from,
+ * the OAuth refresh contract, and the usage/rate-limit payloads we normalise
+ * into the shared AccountQuota model.
+ *
+ * Naming: all exported names carry the `Codex` prefix (rule 9). Codex quota is
+ * stored through the same AccountQuota shape as Anthropic — its primary window
+ * maps onto the session fields and its secondary window onto the weekly fields.
+ */
+import type { AccountCoolingReason, AccountQuota } from "./proxy.js";
+/** Token block inside `~/.codex/auth.json`. */
+export type CodexAuthFileTokens = {
+    id_token?: string;
+    access_token: string;
+    refresh_token?: string;
+    account_id?: string;
+};
+/** Shape of `~/.codex/auth.json` written by the Codex CLI. */
+export type CodexAuthFile = {
+    auth_mode?: string;
+    OPENAI_API_KEY?: string | null;
+    tokens?: CodexAuthFileTokens;
+    last_refresh?: string;
+};
+/** Result of importing a Codex credential (from auth.json or the OAuth flow). */
+export type CodexImportedCredential = {
+    accessToken: string;
+    refreshToken?: string;
+    idToken?: string;
+    /** ChatGPT account id (from auth.json or decoded from the access token). */
+    accountId?: string;
+    /** Epoch ms when the access token expires (decoded from the JWT `exp`). */
+    expiresAt?: number;
+    /** ChatGPT plan type decoded from the token, for display only. */
+    planType?: string;
+    /** Account email decoded from the id token, for the account label. */
+    email?: string;
+};
+/** Raw OpenAI OAuth token endpoint response. */
+export type CodexTokenResponse = {
+    access_token?: string;
+    refresh_token?: string;
+    id_token?: string;
+    token_type?: string;
+    expires_in?: number;
+};
+/** One rate-limit window as reported by the Codex backend (primary/secondary). */
+export type CodexRateLimitWindow = {
+    used_percent?: number | null;
+    window_minutes?: number | null;
+    resets_in_seconds?: number | null;
+    /** Seconds until reset. Observed alias of `resets_in_seconds` on some
+     *  responses; accepted defensively so a cooldown lands on the real reset
+     *  instead of degrading to the transient ceiling. */
+    reset_after?: number | null;
+    resets_at?: number | null;
+};
+/** Codex rate-limit block: a primary (short) and secondary (long) window. */
+export type CodexRateLimits = {
+    primary?: CodexRateLimitWindow | null;
+    secondary?: CodexRateLimitWindow | null;
+};
+/** Loose shape of the Codex usage endpoint response. */
+export type CodexUsageResponse = {
+    rate_limits?: CodexRateLimits | null;
+    plan_type?: string | null;
+};
+/** Result of a single Codex usage fetch. */
+export type CodexUsageFetchResult = {
+    ok: true;
+    quota: AccountQuota;
+} | {
+    ok: false;
+    reason: "not_oauth" | "auth" | "http" | "network" | "parse";
+};
+/** A Codex account with its runtime cooldown/quota state hydrated from disk. */
+export type CodexRuntimeAccount = {
+    key: string;
+    label: string;
+    token: string;
+    refreshToken?: string;
+    expiresAt?: number;
+    accountId?: string;
+    quota?: AccountQuota;
+    coolingUntil?: number;
+    coolingReason?: AccountCoolingReason;
+    /** A persisted cooldown whose window has already passed. Present only when the
+     *  account is therefore eligible again, so the success path can delete the
+     *  spent record — nothing else ever reaps it. */
+    expiredCooldownUntil?: number;
+};

package/dist/types/codex.js

@@ -0,0 +1,14 @@
+/**
+ * Codex (OpenAI ChatGPT subscription) proxy types.
+ *
+ * Codex authenticates with a ChatGPT account over OAuth and talks to the
+ * ChatGPT backend Responses API (https://chatgpt.com/backend-api/codex).
+ * These types describe the on-disk `~/.codex/auth.json` shape we import from,
+ * the OAuth refresh contract, and the usage/rate-limit payloads we normalise
+ * into the shared AccountQuota model.
+ *
+ * Naming: all exported names carry the `Codex` prefix (rule 9). Codex quota is
+ * stored through the same AccountQuota shape as Anthropic — its primary window
+ * maps onto the session fields and its secondary window onto the weekly fields.
+ */
+export {};

package/dist/types/index.d.ts

@@ -12,6 +12,7 @@ export * from "./autoresearch.js";
 export * from "./circuitBreakerErrors.js";
 export * from "./cli.js";
 export * from "./client.js";
+export * from "./codex.js";
 export * from "./common.js";
 export * from "./config.js";
 export * from "./context.js";

package/dist/types/index.js

@@ -13,6 +13,7 @@ export * from "./autoresearch.js";
 export * from "./circuitBreakerErrors.js";
 export * from "./cli.js";
 export * from "./client.js";
+export * from "./codex.js";
 export * from "./common.js";
 export * from "./config.js";
 export * from "./context.js";