UNPKG

@bitkyc08/opencodex

Version:

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

392 lines (354 loc) • 16.2 kB
import { readBoundedResponseBody } from "../lib/bounded-body"; const RESET_ELIGIBLE_CODE_VALUES = [ "usage_limit_exceeded", "insufficient_quota", ] as const; export type CodexResetEligibleExhaustionCode = (typeof RESET_ELIGIBLE_CODE_VALUES)[number]; /** * Upstream codes that name an ORGANIZATION- or PROJECT-scoped exhaustion (#4546). * * These are a different animal from the reset-eligible codes above, and the difference is the * whole point. `usage_limit_exceeded` describes the account that was asked; another pool account * carries its own plan allowance, so rotating to it is a real move. Every code here describes a * limit the CREDENTIAL does not own -- a balance, a spend cap, or a usage cap held by the * organization or project the credential belongs to. Two credentials inside that organization * are refused by the same counter, so rotating between them pays a cold prompt prefix for zero * new capacity, which is the send amplification this unit exists to stop. * * openai/codex reached the same classification from the client side: #44492 maps exactly these * HTTP 429 codes to a terminal `QuotaExceeded` instead of a retry-limit failure, and #45602 * extends it to the SSE path while deliberately KEEPING `rate_limit_exceeded` and `slow_down` * retryable. The platform documentation states the same rule for the whole class: "It does not * mean that quota, billing, or other errors that require user action can be resolved by * retrying." * * Membership here says nothing about reset credits. A reset credit reconciles a ChatGPT plan * window; it cannot pay an organization's bill, so these codes are deliberately absent from * {@link RESET_ELIGIBLE_CODE_VALUES} and never set `resetCreditEligible`. */ const SCOPED_EXHAUSTION_CODE_VALUES = [ "credit_balance_exhausted", "organization_spend_limit_exceeded", "project_spend_limit_exceeded", "organization_usage_limit_exceeded", ] as const; export type CodexScopedExhaustionCode = (typeof SCOPED_EXHAUSTION_CODE_VALUES)[number]; export type CodexPreStreamRejectionKind = | "reset-eligible-exhaustion" | "scoped-quota-exhaustion" | "generic-rate-limit" | "unverified-billing-or-quota" | "transient-server-error" | "authentication-error" | "permission-error" | "other"; export interface CodexPreStreamRejection { kind: CodexPreStreamRejectionKind; status: number; alternateRetryEligible: boolean; resetCreditEligible: boolean; semanticCode?: CodexResetEligibleExhaustionCode; /** * The organization- or project-scoped exhaustion code the upstream body named, when it named * one. Never accompanied by `semanticCode`: the two sets are disjoint, and only `semanticCode` * may authorize a reset credit. */ scopedExhaustionCode?: CodexScopedExhaustionCode; /** * Structured denial evidence for a 403. Present only when the upstream body names a * workspace/entitlement denial, which proves the CREDENTIAL is valid and the account * simply lacks access here (#1789). Status alone can never set this. */ denial?: "workspace" | "entitlement"; } /** * Upstream codes that identify a WORKSPACE denial rather than a bad credential. * * #1789: a K12 account whose credential validates and whose WHAM usage returns 200 still * gets 403 `codex_workspace_access_denied` on a routed prompt. Treating that as a credential * failure tells the user to re-authenticate a credential that is already valid, and the loop * repeats forever. */ const WORKSPACE_DENIAL_CODES: ReadonlySet<string> = new Set([ "codex_workspace_access_denied", "workspace_access_denied", ]); const ENTITLEMENT_DENIAL_CODES: ReadonlySet<string> = new Set([ "codex_entitlement_missing", "entitlement_missing", ]); /** Read a structured denial code out of a 403 body. Fails closed to undefined. */ async function denialFromResponse( response: Response, signal?: AbortSignal, ): Promise<"workspace" | "entitlement" | undefined> { try { const body = await readBoundedResponseBody(response.clone(), { signal, fatalUtf8: true }); if (!body.displaySafe || body.truncated || !body.text.trim()) return undefined; if (isUnsafeJsonDocument(body.text)) return undefined; const payload = JSON.parse(body.text) as unknown; const code = structuredDenialCode(payload); if (code === undefined) return undefined; if (WORKSPACE_DENIAL_CODES.has(code)) return "workspace"; if (ENTITLEMENT_DENIAL_CODES.has(code)) return "entitlement"; return undefined; } catch { // Same fail-closed rule as the exhaustion classifier: an unreadable body must not // downgrade a credential failure into a workspace one. return undefined; } } function ownStringField(container: Record<string, unknown>, field: string): string | undefined { const descriptor = Object.getOwnPropertyDescriptor(container, field); return descriptor && "value" in descriptor && typeof descriptor.value === "string" ? descriptor.value : undefined; } /** Own-property `code` lookup at the top level or under `error` / `detail`. No coercion or accessors. */ function structuredDenialCode(payload: unknown): string | undefined { if (payload === null || typeof payload !== "object" || Array.isArray(payload)) return undefined; const record = payload as Record<string, unknown>; const direct = ownStringField(record, "code"); if (direct !== undefined) return direct; for (const field of ["error", "detail"] as const) { const descriptor = Object.getOwnPropertyDescriptor(record, field); if (!descriptor || !("value" in descriptor)) continue; const nested = descriptor.value; if (nested === null || typeof nested !== "object" || Array.isArray(nested)) continue; const code = ownStringField(nested as Record<string, unknown>, "code"); if (code !== undefined) return code; } return undefined; } const RESET_ELIGIBLE_CODES: ReadonlySet<string> = new Set(RESET_ELIGIBLE_CODE_VALUES); const SCOPED_EXHAUSTION_CODES: ReadonlySet<string> = new Set(SCOPED_EXHAUSTION_CODE_VALUES); const TRANSIENT_SERVER_STATUSES = new Set([500, 502, 503, 504, 520, 521, 522]); const JSON_NUMBER_PATTERN = /-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?/y; function rejection( status: number, kind: CodexPreStreamRejectionKind, options: { alternateRetryEligible?: boolean; semanticCode?: CodexResetEligibleExhaustionCode; scopedExhaustionCode?: CodexScopedExhaustionCode; } = {}, ): CodexPreStreamRejection { return { kind, status, alternateRetryEligible: options.alternateRetryEligible === true, resetCreditEligible: options.semanticCode !== undefined, ...(options.semanticCode ? { semanticCode: options.semanticCode } : {}), ...(options.scopedExhaustionCode ? { scopedExhaustionCode: options.scopedExhaustionCode } : {}), }; } function hasOwnField(container: Record<string, unknown>, field: string): boolean { return Object.prototype.hasOwnProperty.call(container, field); } type JsonScanResult = { next: number; duplicate: boolean; }; function skipJsonWhitespace(text: string, index: number): number { while (index < text.length && /[\t\n\r ]/.test(text[index] ?? "")) index += 1; return index; } function scanJsonStringEnd(text: string, index: number): number { if (text[index] !== '"') throw new SyntaxError("expected JSON string"); for (let cursor = index + 1; cursor < text.length; cursor += 1) { const char = text[cursor]; if (char === '"') return cursor + 1; if (char === "\\") cursor += 1; } throw new SyntaxError("unterminated JSON string"); } function scanJsonValue(text: string, index: number): JsonScanResult { const start = skipJsonWhitespace(text, index); if (text[start] === "{") return scanJsonObject(text, start); if (text[start] === "[") return scanJsonArray(text, start); if (text[start] === '"') return { next: scanJsonStringEnd(text, start), duplicate: false }; for (const literal of ["true", "false", "null"]) { if (text.startsWith(literal, start)) { return { next: start + literal.length, duplicate: false }; } } JSON_NUMBER_PATTERN.lastIndex = start; const number = JSON_NUMBER_PATTERN.exec(text); if (!number) throw new SyntaxError("expected JSON value"); return { next: start + number[0].length, duplicate: false }; } function scanJsonObject(text: string, index: number): JsonScanResult { const keys = new Set<string>(); let duplicate = false; let cursor = skipJsonWhitespace(text, index + 1); if (text[cursor] === "}") return { next: cursor + 1, duplicate: false }; while (cursor < text.length) { const keyEnd = scanJsonStringEnd(text, cursor); const key = JSON.parse(text.slice(cursor, keyEnd)) as unknown; if (typeof key !== "string") throw new SyntaxError("invalid JSON object key"); if (keys.has(key)) duplicate = true; keys.add(key); cursor = skipJsonWhitespace(text, keyEnd); if (text[cursor] !== ":") throw new SyntaxError("expected JSON object colon"); const value = scanJsonValue(text, cursor + 1); duplicate ||= value.duplicate; cursor = skipJsonWhitespace(text, value.next); if (text[cursor] === "}") return { next: cursor + 1, duplicate }; if (text[cursor] !== ",") throw new SyntaxError("expected JSON object separator"); cursor = skipJsonWhitespace(text, cursor + 1); } throw new SyntaxError("unterminated JSON object"); } function scanJsonArray(text: string, index: number): JsonScanResult { let duplicate = false; let cursor = skipJsonWhitespace(text, index + 1); if (text[cursor] === "]") return { next: cursor + 1, duplicate: false }; while (cursor < text.length) { const value = scanJsonValue(text, cursor); duplicate ||= value.duplicate; cursor = skipJsonWhitespace(text, value.next); if (text[cursor] === "]") return { next: cursor + 1, duplicate }; if (text[cursor] !== ",") throw new SyntaxError("expected JSON array separator"); cursor = skipJsonWhitespace(text, cursor + 1); } throw new SyntaxError("unterminated JSON array"); } function isUnsafeJsonDocument(text: string): boolean { try { const result = scanJsonValue(text, 0); return result.duplicate || skipJsonWhitespace(text, result.next) !== text.length; } catch { // Scanner disagreement is untrusted input, just like JSON.parse failure. return true; } } /** * Read the one exact, unambiguous code a container declares, and only if it is in `allowed`. * * Generic over the allowed set so the reset-eligible and organization-scoped classifications * share one parser. They must: the strictness here -- a `code`/`type` pair that disagrees is * rejected rather than resolved, and no trimming or case folding is applied -- is what keeps a * near-miss from being read as an exact upstream code, and a second hand-written copy would * drift away from that. */ function exactAllowedCode( container: Record<string, unknown>, allowed: ReadonlySet<string>, ): string | undefined { const hasCode = hasOwnField(container, "code"); const hasType = hasOwnField(container, "type"); if (!hasCode && !hasType) return undefined; const code = hasCode ? container.code : undefined; const type = hasType ? container.type : undefined; if ((hasCode && typeof code !== "string") || (hasType && typeof type !== "string")) { return undefined; } if (hasCode && hasType && code !== type) return undefined; const value = hasCode ? code : type; if (typeof value !== "string") return undefined; return allowed.has(value) ? value : undefined; } function structuredAllowedCode(payload: unknown, allowed: ReadonlySet<string>): string | undefined { if (!payload || typeof payload !== "object" || Array.isArray(payload)) return undefined; const root = payload as Record<string, unknown>; const hasRootDiscriminator = hasOwnField(root, "code") || hasOwnField(root, "type"); if (!hasOwnField(root, "error")) return exactAllowedCode(root, allowed); if (hasRootDiscriminator) return undefined; const nested = root.error; if (!nested || typeof nested !== "object" || Array.isArray(nested)) return undefined; return exactAllowedCode(nested as Record<string, unknown>, allowed); } /** * Parse one bounded body and classify its structured code against both sets at once. * * One read, because the caller holds a `Response` whose body may only be consumed once per * clone and the two questions are asked about the same bytes. */ async function exhaustionCodeFromResponse( response: Response, signal?: AbortSignal, ): Promise<{ resetEligible?: CodexResetEligibleExhaustionCode; scoped?: CodexScopedExhaustionCode; }> { try { const body = await readBoundedResponseBody(response.clone(), { signal, fatalUtf8: true }); if (!body.displaySafe || body.truncated || !body.text.trim()) return {}; const payload = JSON.parse(body.text) as unknown; // JSON.parse silently keeps the last duplicate key, making contradictory // payloads order-dependent. Reject any duplicate at any object depth. if (isUnsafeJsonDocument(body.text)) return {}; const resetEligible = structuredAllowedCode(payload, RESET_ELIGIBLE_CODES); if (resetEligible !== undefined) { return { resetEligible: resetEligible as CodexResetEligibleExhaustionCode }; } const scoped = structuredAllowedCode(payload, SCOPED_EXHAUSTION_CODES); return scoped === undefined ? {} : { scoped: scoped as CodexScopedExhaustionCode }; } catch { // Classification must fail closed. A malformed, oversized, consumed, or // cancelled body cannot authorize an irreversible reset-credit operation. return {}; } } /** * The organization- or project-scoped exhaustion code this rejection names, if any. * * Exported for the account-rotation gate, which has to answer "may another pool account serve * this?" before it has any reason to build a full classification. Fails closed to `undefined`: * an unreadable, truncated, duplicate-keyed or aborted body leaves the caller's existing * behaviour untouched, so only positive evidence can ever withhold a rotation. */ export async function codexScopedExhaustionCode( response: Response, options: { signal?: AbortSignal } = {}, ): Promise<CodexScopedExhaustionCode | undefined> { return (await exhaustionCodeFromResponse(response, options.signal)).scoped; } /** * Classify an upstream Codex rejection before any response event is exposed. * * Only an exact structured exhaustion code on HTTP 429/402 is reset-eligible. * Status alone and message text are intentionally insufficient. The broad * alternate-account retry remains eligible for 429/402 to preserve #584. * * Organization- or project-scoped exhaustion ({@link SCOPED_EXHAUSTION_CODE_VALUES}) remains * alternate-retry eligible here because the response does not identify the refusing scope. The * account-rotation path may suppress the send later when the resolved alternate carries binding * evidence that it shares an organization-level counter. */ export async function classifyCodexPreStreamRejection( response: Response, options: { signal?: AbortSignal } = {}, ): Promise<CodexPreStreamRejection> { const status = response.status; if (status === 401) return rejection(status, "authentication-error"); if (status === 403) { const denial = await denialFromResponse(response, options.signal); return { ...rejection(status, "permission-error"), ...(denial ? { denial } : {}) }; } if (TRANSIENT_SERVER_STATUSES.has(status)) return rejection(status, "transient-server-error"); if (status !== 429 && status !== 402) return rejection(status, "other"); const { resetEligible: semanticCode, scoped } = await exhaustionCodeFromResponse( response, options.signal, ); if (semanticCode) { return rejection(status, "reset-eligible-exhaustion", { alternateRetryEligible: true, semanticCode, }); } if (scoped) { return rejection(status, "scoped-quota-exhaustion", { alternateRetryEligible: true, scopedExhaustionCode: scoped, }); } return rejection( status, status === 429 ? "generic-rate-limit" : "unverified-billing-or-quota", { alternateRetryEligible: true }, ); }