@bitkyc08/opencodex 2.40.0 → 2.41.0

package/src/combos/failover.ts

@@ -13,6 +13,28 @@ interface TargetCooldown {
 
 const DEFAULT_COOLDOWN_MS = 60_000;
 const MAX_COOLDOWN_MS = 10 * 60_000;
+/** Short cooldown for request-rate 429s (for example provider code 1302) that omit Retry-After. */
+export const COMBO_REQUEST_RATE_COOLDOWN_MS = 5_000;
+
+const QUOTA_LIMIT_CODES = new Set([
+  "1308",
+  "1310",
+  "1316",
+  "1317",
+  "1318",
+  "1319",
+  "1320",
+  "1321",
+  "insufficient_quota",
+]);
+const TRANSIENT_REQUEST_RATE_CODES = new Set(["1302", "1305"]);
+const IMF_FIXDATE_RE = /^(?:Mon|Tue|Wed|Thu|Fri|Sat|Sun), (\d{2}) (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) (\d{4}) (\d{2}):(\d{2}):(\d{2}) GMT$/i;
+const RFC850_DATE_RE = /^(?:Monday|Tuesday|Wednesday|Thursday|Friday|Saturday|Sunday), (\d{2})-(Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)-(\d{2}) (\d{2}):(\d{2}):(\d{2}) GMT$/i;
+const ASCTIME_DATE_RE = /^(?:Mon|Tue|Wed|Thu|Fri|Sat|Sun) (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) ( \d|\d{2}) (\d{2}):(\d{2}):(\d{2}) (\d{4})$/i;
+const HTTP_MONTH_INDEX: Record<string, number> = {
+  jan: 0, feb: 1, mar: 2, apr: 3, may: 4, jun: 5,
+  jul: 6, aug: 7, sep: 8, oct: 9, nov: 10, dec: 11,
+};
 
 /** Map<`${comboId}\0${provider/model}`, TargetCooldown> */
 const targetCooldowns = new Map<string, TargetCooldown>();
@@ -26,22 +48,92 @@ function cooldownMapKey(
   return `${comboId}\0${targetKey(target)}`;
 }
 
+function parseUtcDateParts(
+  year: number,
+  monthName: string,
+  day: number,
+  hour: number,
+  minute: number,
+  second: number,
+): number | undefined {
+  const month = HTTP_MONTH_INDEX[monthName.toLowerCase()];
+  if (month === undefined) return undefined;
+  const timestamp = Date.UTC(year, month, day, hour, minute, second);
+  const parsed = new Date(timestamp);
+  return parsed.getUTCFullYear() === year
+    && parsed.getUTCMonth() === month
+    && parsed.getUTCDate() === day
+    && parsed.getUTCHours() === hour
+    && parsed.getUTCMinutes() === minute
+    && parsed.getUTCSeconds() === second
+    ? timestamp
+    : undefined;
+}
+
+function parseHttpDate(value: string, now: number): number | undefined {
+  const imf = IMF_FIXDATE_RE.exec(value);
+  if (imf) {
+    return parseUtcDateParts(
+      Number(imf[3]), imf[2]!, Number(imf[1]),
+      Number(imf[4]), Number(imf[5]), Number(imf[6]),
+    );
+  }
+  const rfc850 = RFC850_DATE_RE.exec(value);
+  if (rfc850) {
+    const current = new Date(now);
+    const currentYear = current.getUTCFullYear();
+    const month = HTTP_MONTH_INDEX[rfc850[2]!.toLowerCase()];
+    if (month === undefined) return undefined;
+    let year = Math.floor(currentYear / 100) * 100 + Number(rfc850[3]);
+    const yearDelta = year - currentYear;
+    const candidateTimeOfYear = Date.UTC(
+      2000, month, Number(rfc850[1]),
+      Number(rfc850[4]), Number(rfc850[5]), Number(rfc850[6]),
+    );
+    const currentTimeOfYear = Date.UTC(
+      2000, current.getUTCMonth(), current.getUTCDate(),
+      current.getUTCHours(), current.getUTCMinutes(), current.getUTCSeconds(),
+      current.getUTCMilliseconds(),
+    );
+    if (yearDelta < -50 || (yearDelta === -50 && candidateTimeOfYear < currentTimeOfYear)) {
+      year += 100;
+    } else if (yearDelta > 50 || (yearDelta === 50 && candidateTimeOfYear > currentTimeOfYear)) {
+      year -= 100;
+    }
+    return parseUtcDateParts(
+      year, rfc850[2]!, Number(rfc850[1]),
+      Number(rfc850[4]), Number(rfc850[5]), Number(rfc850[6]),
+    );
+  }
+  const asctime = ASCTIME_DATE_RE.exec(value);
+  if (!asctime) return undefined;
+  return parseUtcDateParts(
+    Number(asctime[6]), asctime[1]!, Number(asctime[2]),
+    Number(asctime[3]), Number(asctime[4]), Number(asctime[5]),
+  );
+}
+
 export function parseRetryAfterMs(
   value: string | null | undefined,
   now = Date.now(),
+  options?: { preserveImmediate?: boolean },
 ): 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) {
+    if (
+      Number.isFinite(seconds)
+      && (seconds > 0 || (options?.preserveImmediate && 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 timestamp = parseHttpDate(text, now);
+  if (timestamp === undefined) return undefined;
   const delay = timestamp - now;
-  return delay > 0 ? Math.min(delay, MAX_COOLDOWN_MS) : undefined;
+  if (delay > 0) return Math.min(delay, MAX_COOLDOWN_MS);
+  return options?.preserveImmediate ? 1 : undefined;
 }
 
 export function isComboTargetInCooldown(
@@ -59,10 +151,59 @@ export function isComboTargetInCooldown(
   return true;
 }
 
+export function isTransientRequestRateLimit(input: {
+  status?: number;
+  code?: string | null;
+  message?: string;
+}): boolean {
+  if (isProviderScopedQuotaCap(input.status, input.message ?? "", input.code)) return false;
+  const code = (input.code ?? "").trim().toLowerCase().replaceAll("-", "_");
+  if (QUOTA_LIMIT_CODES.has(code)) return false;
+  if (TRANSIENT_REQUEST_RATE_CODES.has(code)) return true;
+  const text = (input.message ?? "").toLowerCase();
+  if (
+    text.includes("usage limit reached")
+    || text.includes("insufficient_quota")
+    || text.includes("quota exhausted")
+  ) {
+    return false;
+  }
+  return text.includes("rate limit reached for requests");
+}
+
+export function remainingComboCooldownMs(comboId: string, now = Date.now()): number | undefined {
+  const prefix = `${comboId}\0`;
+  let soonest: number | undefined;
+  for (const [key, cooldown] of targetCooldowns) {
+    if (!key.startsWith(prefix)) continue;
+    const remaining = cooldown.cooldownUntil - now;
+    if (remaining <= 0) {
+      targetCooldowns.delete(key);
+      continue;
+    }
+    if (soonest === undefined || remaining < soonest) soonest = remaining;
+  }
+  return soonest;
+}
+
+export function comboCooldownRetryAfterSeconds(comboId: string, now = Date.now()): string | undefined {
+  const remainingMs = remainingComboCooldownMs(comboId, now);
+  if (remainingMs === undefined) return undefined;
+  return String(Math.max(1, Math.ceil(remainingMs / 1000)));
+}
+
 export function coolComboTarget(
   comboId: string,
   target: Pick<OcxComboTarget, "provider" | "model">,
-  options?: { retryAfter?: string | null; now?: number; cooldownMs?: number; writerGeneration?: number },
+  options?: {
+    retryAfter?: string | null;
+    now?: number;
+    cooldownMs?: number;
+    writerGeneration?: number;
+    status?: number;
+    code?: string | null;
+    message?: string;
+  },
 ): void {
   const now = options?.now ?? Date.now();
   const writerGeneration = options?.writerGeneration ?? captureConfigGeneration();
@@ -70,7 +211,11 @@ export function coolComboTarget(
   if (writerGeneration < lastReconciledGeneration && !liveComboTargets.has(ownerKey)) return;
   const cooldownMs = options?.cooldownMs
     ?? parseRetryAfterMs(options?.retryAfter, now)
-    ?? DEFAULT_COOLDOWN_MS;
+    ?? (isTransientRequestRateLimit({
+      status: options?.status,
+      code: options?.code,
+      message: options?.message,
+    }) ? COMBO_REQUEST_RATE_COOLDOWN_MS : DEFAULT_COOLDOWN_MS);
   targetCooldowns.set(cooldownMapKey(comboId, target), {
     cooldownUntil: now + Math.min(Math.max(cooldownMs, 1), MAX_COOLDOWN_MS),
   });
@@ -108,6 +253,37 @@ export function clearComboTargetCooldowns(comboId?: string): void {
 }
 
 export type ComboFailureDecision = "hop" | "stop";
+export type ComboFailureCooldownScope = "target" | "provider";
+
+function normalizedFailureCode(code?: string | null): string {
+  return code?.trim().toLowerCase().replaceAll("-", "_") ?? "";
+}
+
+function isProviderScopedQuotaCap(
+  status: number | undefined,
+  message: string,
+  code?: string | null,
+): boolean {
+  const normalizedCode = normalizedFailureCode(code);
+  const text = message.toLowerCase();
+  if (
+    status === 429
+    && (normalizedCode === "gousagelimiterror" || text.includes("monthly usage limit reached"))
+  ) {
+    return true;
+  }
+  return normalizedCode === "free_rate_limited"
+    || text.includes("err_free_prompt_cap")
+    || (text.includes("free tier") && text.includes("single request"));
+}
+
+export function comboFailureCooldownScope(
+  status: number,
+  message: string,
+  options?: { code?: string | null },
+): ComboFailureCooldownScope {
+  return isProviderScopedQuotaCap(status, message, options?.code) ? "provider" : "target";
+}
 
 function isModelLifecycleGone(
   status: number,
@@ -168,6 +344,9 @@ export function comboFailureDecision(
   if (options?.code === "input_admission_refused" || error.code === "input_admission_refused") {
     return "hop";
   }
+  if (isProviderScopedQuotaCap(status, message, options?.code || error.code)) {
+    return "hop";
+  }
   if (["origin_rejected", "context_length_exceeded", "invalid_request_error"].includes(error.code ?? "")) {
     return "stop";
   }

package/src/combos/index.ts

@@ -31,11 +31,17 @@ export {
 } from "./resolve";
 export {
   clearComboTargetCooldowns,
+  comboCooldownRetryAfterSeconds,
+  COMBO_REQUEST_RATE_COOLDOWN_MS,
   coolComboTarget,
   isComboTargetInCooldown,
+  isTransientRequestRateLimit,
   parseRetryAfterMs,
+  remainingComboCooldownMs,
   comboFailureDecision,
+  comboFailureCooldownScope,
   type ComboFailureDecision,
+  type ComboFailureCooldownScope,
 } from "./failover";
 export {
   comboIdFromRawBody,

package/src/combos/resolve.ts

@@ -1,6 +1,7 @@
 import type { OcxComboTarget, OcxConfig } from "../types";
 import { getCachedProviderQuota } from "../providers/quota-routing-cache";
-import { coolComboTarget, isComboTargetInCooldown } from "./failover";
+import type { ProviderQuota } from "../providers/quota-types";
+import { coolComboTarget, isComboTargetInCooldown, type ComboFailureCooldownScope } from "./failover";
 import { quotaResetRemainingMs } from "./reset-window";
 import { getCombo, resolveComboId, targetKey } from "./types";
 import type { NormalizedComboConfig } from "./types";
@@ -58,6 +59,28 @@ function targetProviderIsUsable(config: OcxConfig, target: OcxComboTarget): bool
     && config.providers[target.provider]?.disabled !== true;
 }
 
+function quotaWindowExhausted(percent: number | undefined, resetAt: number | undefined, now: number): boolean {
+  if (typeof percent !== "number" || !Number.isFinite(percent) || percent < 100) return false;
+  return typeof resetAt !== "number" || !Number.isFinite(resetAt) || resetAt > now;
+}
+
+export function cachedProviderQuotaIsExhausted(
+  quota: ProviderQuota | null,
+  now = Date.now(),
+): boolean {
+  if (!quota) return false;
+  if (quotaWindowExhausted(quota.fiveHourPercent, quota.fiveHourResetAt, now)) return true;
+  if (quotaWindowExhausted(quota.weeklyPercent, quota.weeklyResetAt, now)) return true;
+  if (quotaWindowExhausted(quota.monthlyPercent, quota.monthlyResetAt, now)) return true;
+  if (quota.customWindows?.some(window => quotaWindowExhausted(window.percent, window.resetAt, now))) return true;
+  if (quota.creditsUsd?.unlimited !== true
+      && typeof quota.creditsUsd?.percent === "number"
+      && Number.isFinite(quota.creditsUsd.percent)
+      && quota.creditsUsd.percent >= 100
+      && quota.creditsUsd.remaining <= 0) return true;
+  return false;
+}
+
 function smoothWeightedIndex(
   targets: Required<OcxComboTarget>[],
   state: SelectionState,
@@ -121,14 +144,17 @@ export function pickComboTarget(
   options: {
     exclude?: Iterable<string>;
     eligible?: (target: Required<OcxComboTarget>) => boolean;
+    now?: number;
   } = {},
 ): ComboPick | null {
   const writerGeneration = captureConfigGeneration();
   const combo = getCombo(config, comboId);
   if (!combo) throw new UnknownComboError(comboId);
   const excluded = new Set(options.exclude ?? []);
+  const now = options.now ?? Date.now();
   const eligible = (target: Required<OcxComboTarget>): boolean =>
     targetProviderIsUsable(config, target)
+    && !cachedProviderQuotaIsExhausted(getCachedProviderQuota(target.provider, now), now)
     && !excluded.has(targetKey(target))
     && (options.eligible?.(target) ?? true);
 
@@ -187,7 +213,7 @@ export function pickComboTarget(
       }
     }
   } else if (combo.strategy === "reset-window") {
-    targetIndex = resetWindowIndex(combo.targets, eligible);
+    targetIndex = resetWindowIndex(combo.targets, eligible, now);
   } else {
     targetIndex = combo.targets.findIndex(eligible);
   }
@@ -250,15 +276,26 @@ export function advanceComboAfterFailure(
     retryAfter?: string | null;
     now?: number;
     eligible?: (target: Required<OcxComboTarget>) => boolean;
+    cooldownScope?: ComboFailureCooldownScope;
+    status?: number;
+    code?: string | null;
+    message?: string;
   } = {},
 ): ComboPick | null {
   noteComboFailure(pick.comboId, pick.target, pick.writerGeneration);
-  coolComboTarget(pick.comboId, pick.target, {
-    ...options,
-    writerGeneration: pick.writerGeneration,
-  });
+  const combo = getCombo(config, pick.comboId);
+  const cooldownTargets = options.cooldownScope === "provider" && combo
+    ? combo.targets.filter(target => target.provider === pick.target.provider)
+    : [pick.target];
+  for (const target of cooldownTargets) {
+    coolComboTarget(pick.comboId, target, {
+      ...options,
+      writerGeneration: pick.writerGeneration,
+    });
+  }
   return pickComboTarget(config, pick.comboId, {
     exclude: pick.attempted,
+    now: options.now,
     eligible: target => !isComboTargetInCooldown(pick.comboId, target, options.now)
       && (options.eligible?.(target) ?? true),
   });

package/src/config.ts

@@ -1010,7 +1010,9 @@ const configSchema = z.object({
   // A malformed present client block must remain diagnosable from raw config and
   // fail closed through src/client/state.ts; unrelated provider state still loads.
   client: clientConnectionSchema.optional().catch(undefined),
-  managementUsageMaxReadBytes: z.number().int().positive().default(64 * 1024 * 1024),
+  managementUsageMaxReadBytes: z.number().int().positive().default(64 * 1024 * 1024).describe(
+    "Deprecated compatibility limit for bounded legacy usage readers; GET /api/usage always aggregates the complete ledger",
+  ),
   // Invalid hand edits disable only this opt-in circuit. Live writes remain strict.
   upstreamHostCircuitThreshold: z.number().int()
     .min(0)
@@ -1046,6 +1048,8 @@ const configSchema = z.object({
   providers: z.record(z.string(), providerConfigSchema),
   defaultProvider: z.string().min(1).default("openai"),
   defaultModelAliases: z.boolean().optional(),
+  // Malformed hand edits disable this opt-in projection without rejecting providers.
+  cursorEffortRows: z.boolean().optional().catch(false),
   // Future versions remain opaque through passthrough-compatible whole-config saves.
   // Only version 1 grants deletion authority in the rebase path.
   configRebaseProvenance: z.unknown().optional(),