@bitkyc08/opencodex 2.7.23 → 2.7.24

package/src/combos/failover.ts

@@ -0,0 +1,102 @@
+import { classifyError } from "../lib/errors";
+import type { OcxComboTarget } from "../types";
+import { targetKey } from "./types";
+
+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>();
+
+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 },
+): void {
+  const now = options?.now ?? Date.now();
+  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),
+  });
+}
+
+export function clearComboTargetCooldowns(comboId?: string): void {
+  if (comboId === undefined) {
+    targetCooldowns.clear();
+    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): ComboFailureDecision {
+  if (status === 499) return "stop";
+  if (message.toLowerCase().includes("origin_rejected")) return "stop";
+  const error = classifyError(status, "upstream_error", message);
+  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,37 @@
+export {
+  COMBO_DEFAULT_EFFORT,
+  COMBO_NAMESPACE,
+  comboConfigError,
+  comboConfigIssues,
+  comboDefaultEffort,
+  comboModelId,
+  getCombo,
+  isValidComboId,
+  listComboIds,
+  normalizeComboConfig,
+  parseComboModelId,
+  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,
+} from "./request";

package/src/combos/request.ts

@@ -0,0 +1,31 @@
+import type { OcxComboDefaultEffort, OcxComboTarget } from "../types";
+import { parseComboModelId } from "./types";
+
+export function comboIdFromRawBody(body: unknown): 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 parseComboModelId(model);
+}
+
+export function concreteComboRequestBody(
+  body: unknown,
+  target: Pick<OcxComboTarget, "provider" | "model">,
+  defaultEffort: OcxComboDefaultEffort | null,
+): 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;
+  if (reasoning === undefined) {
+    clone.reasoning = { effort: defaultEffort };
+  } else if (
+    reasoning
+    && typeof reasoning === "object"
+    && !Array.isArray(reasoning)
+    && !Object.prototype.hasOwnProperty.call(reasoning, "effort")
+  ) {
+    clone.reasoning = { ...(reasoning as Record<string, unknown>), effort: defaultEffort };
+  }
+  return clone;
+}

package/src/combos/resolve.ts

@@ -0,0 +1,171 @@
+import type { OcxComboTarget, OcxConfig } from "../types";
+import { coolComboTarget, isComboTargetInCooldown } from "./failover";
+import { getCombo, parseComboModelId, targetKey } from "./types";
+import type { NormalizedComboConfig } from "./types";
+
+export interface ComboPick {
+  comboId: string;
+  target: Required<OcxComboTarget>;
+  targetIndex: number;
+  attempted: string[];
+}
+
+interface SelectionState {
+  activeKey?: string;
+  successes: number;
+  currentWeights: Map<string, number>;
+}
+
+const selectionState = new Map<string, SelectionState>();
+
+export class UnknownComboError extends Error {
+  constructor(readonly comboId: string) {
+    super(`Unknown combo: ${comboId}`);
+    this.name = "UnknownComboError";
+  }
+}
+
+export class NoAvailableComboTargetsError extends Error {
+  readonly code = "combo_unavailable";
+
+  constructor(readonly comboId: string) {
+    super(`No available targets for combo: ${comboId}`);
+    this.name = "NoAvailableComboTargetsError";
+  }
+}
+
+function targetProviderIsUsable(config: OcxConfig, target: OcxComboTarget): boolean {
+  return Object.hasOwn(config.providers, target.provider)
+    && config.providers[target.provider]?.disabled !== true;
+}
+
+function smoothWeightedIndex(
+  targets: Required<OcxComboTarget>[],
+  state: SelectionState,
+  eligible: (target: Required<OcxComboTarget>) => boolean,
+): number {
+  let best = -1;
+  let bestScore = Number.NEGATIVE_INFINITY;
+  let total = 0;
+  for (let i = 0; i < targets.length; i++) {
+    const target = targets[i]!;
+    if (!eligible(target)) continue;
+    const key = targetKey(target);
+    const score = (state.currentWeights.get(key) ?? 0) + target.weight;
+    state.currentWeights.set(key, score);
+    total += target.weight;
+    if (score > bestScore) {
+      best = i;
+      bestScore = score;
+    }
+  }
+  if (best >= 0) {
+    const key = targetKey(targets[best]!);
+    state.currentWeights.set(key, (state.currentWeights.get(key) ?? 0) - total);
+  }
+  return best;
+}
+
+export function pickComboTarget(
+  config: OcxConfig,
+  comboId: string,
+  options: {
+    exclude?: Iterable<string>;
+    eligible?: (target: Required<OcxComboTarget>) => boolean;
+  } = {},
+): ComboPick | null {
+  const combo = getCombo(config, comboId);
+  if (!combo) throw new UnknownComboError(comboId);
+  const excluded = new Set(options.exclude ?? []);
+  const eligible = (target: Required<OcxComboTarget>): boolean =>
+    targetProviderIsUsable(config, target)
+    && !excluded.has(targetKey(target))
+    && (options.eligible?.(target) ?? true);
+
+  let targetIndex = -1;
+  if (combo.strategy === "round-robin") {
+    let state = selectionState.get(comboId);
+    if (!state) {
+      state = { successes: 0, currentWeights: new Map() };
+      selectionState.set(comboId, state);
+    }
+    if (state.activeKey) {
+      targetIndex = combo.targets.findIndex(target => targetKey(target) === state.activeKey && eligible(target));
+      if (targetIndex < 0) {
+        delete state.activeKey;
+        state.successes = 0;
+      }
+    }
+    if (targetIndex < 0) {
+      targetIndex = smoothWeightedIndex(combo.targets, state, eligible);
+      if (targetIndex >= 0) {
+        state.activeKey = targetKey(combo.targets[targetIndex]!);
+        state.successes = 0;
+      }
+    }
+  } else {
+    targetIndex = combo.targets.findIndex(eligible);
+  }
+
+  if (targetIndex < 0) return null;
+  const target = combo.targets[targetIndex]!;
+  return {
+    comboId,
+    target,
+    targetIndex,
+    attempted: [...excluded, targetKey(target)],
+  };
+}
+
+export function noteComboSuccess(
+  comboId: string,
+  combo: NormalizedComboConfig,
+  target: Required<OcxComboTarget>,
+): void {
+  if (combo.strategy !== "round-robin") return;
+  const state = selectionState.get(comboId);
+  if (!state || state.activeKey !== targetKey(target)) return;
+  state.successes += 1;
+  if (state.successes >= combo.stickyLimit) {
+    delete state.activeKey;
+    state.successes = 0;
+  }
+}
+
+export function noteComboFailure(comboId: string, target: OcxComboTarget): void {
+  const state = selectionState.get(comboId);
+  if (state?.activeKey === targetKey(target)) {
+    delete state.activeKey;
+    state.successes = 0;
+  }
+}
+
+export function advanceComboAfterFailure(
+  config: OcxConfig,
+  pick: ComboPick,
+  options: { retryAfter?: string | null; now?: number } = {},
+): ComboPick | null {
+  noteComboFailure(pick.comboId, pick.target);
+  coolComboTarget(pick.comboId, pick.target, options);
+  return pickComboTarget(config, pick.comboId, {
+    exclude: pick.attempted,
+    eligible: target => !isComboTargetInCooldown(pick.comboId, target, options.now),
+  });
+}
+
+export function clearComboSelectionState(comboId?: string): void {
+  if (comboId === undefined) {
+    selectionState.clear();
+    return;
+  }
+  selectionState.delete(comboId);
+}
+
+export function tryPickComboModel(config: OcxConfig, modelId: string): ComboPick | null {
+  const comboId = parseComboModelId(modelId);
+  if (!comboId) return null;
+  if (!getCombo(config, comboId)) throw new UnknownComboError(comboId);
+  const picked = pickComboTarget(config, comboId);
+  if (!picked) throw new NoAvailableComboTargetsError(comboId);
+  return picked;
+}

package/src/combos/types.ts

@@ -0,0 +1,203 @@
+import { isCodexReasoningEffort } from "../reasoning-effort";
+import type {
+  OcxComboConfig,
+  OcxComboDefaultEffort,
+  OcxComboStrategy,
+  OcxComboTarget,
+  OcxProviderConfig,
+} from "../types";
+
+export const COMBO_NAMESPACE = "combo";
+export const COMBO_DEFAULT_EFFORT: OcxComboDefaultEffort = "medium";
+const COMBO_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+
+export interface ComboValidationIssue {
+  path: Array<string | number>;
+  message: string;
+}
+
+export interface NormalizedComboConfig {
+  strategy: OcxComboStrategy;
+  stickyLimit: number;
+  defaultEffort: OcxComboDefaultEffort;
+  targets: Array<Required<OcxComboTarget>>;
+}
+
+export function targetKey(target: Pick<OcxComboTarget, "provider" | "model">): string {
+  return `${target.provider}/${target.model}`;
+}
+
+export function parseComboModelId(modelId: string): string | null {
+  const slash = modelId.indexOf("/");
+  if (slash <= 0 || modelId.slice(0, slash) !== COMBO_NAMESPACE) return null;
+  const id = modelId.slice(slash + 1);
+  return id.length > 0 ? id : null;
+}
+
+export function comboModelId(id: string): string {
+  return `${COMBO_NAMESPACE}/${id}`;
+}
+
+export function comboConfigIssues(
+  id: string,
+  raw: unknown,
+  providers: Record<string, OcxProviderConfig>,
+  options: { requireEnabledTarget?: boolean } = {},
+): ComboValidationIssue[] {
+  const issues: ComboValidationIssue[] = [];
+  if (!isValidComboId(id)) {
+    issues.push({
+      path: [],
+      message: "combo id must start with a letter/number and use letters, numbers, dot, underscore, or hyphen (max 64)",
+    });
+  }
+  if (Object.hasOwn(providers, COMBO_NAMESPACE)) {
+    issues.push({
+      path: [],
+      message: 'provider name "combo" collides with the reserved "combo/" namespace while combos are configured',
+    });
+  }
+  if (Object.hasOwn(providers, id)) {
+    issues.push({
+      path: [],
+      message: `combo id "${id}" collides with configured provider name "${id}"`,
+    });
+  }
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    issues.push({ path: [], message: "combo must be an object" });
+    return issues;
+  }
+
+  const body = raw as Record<string, unknown>;
+  if (body.strategy !== undefined
+    && body.strategy !== "failover"
+    && body.strategy !== "round-robin") {
+    issues.push({ path: ["strategy"], message: 'strategy must be "failover" or "round-robin"' });
+  }
+  if (body.stickyLimit !== undefined
+    && (typeof body.stickyLimit !== "number" || !Number.isInteger(body.stickyLimit)
+      || body.stickyLimit < 1
+      || body.stickyLimit > 100)) {
+    issues.push({ path: ["stickyLimit"], message: "stickyLimit must be an integer from 1 to 100" });
+  }
+  if (body.defaultEffort !== undefined
+    && (typeof body.defaultEffort !== "string" || !isCodexReasoningEffort(body.defaultEffort))) {
+    issues.push({
+      path: ["defaultEffort"],
+      message: "defaultEffort must be one of: low, medium, high, xhigh, max, ultra",
+    });
+  }
+
+  if (!Array.isArray(body.targets) || body.targets.length === 0) {
+    issues.push({ path: ["targets"], message: "targets must be a non-empty array" });
+    return issues;
+  }
+
+  const seen = new Set<string>();
+  let configuredProviderCount = 0;
+  let enabledProviderCount = 0;
+  for (let i = 0; i < body.targets.length; i++) {
+    const rawTarget = body.targets[i];
+    if (!rawTarget || typeof rawTarget !== "object" || Array.isArray(rawTarget)) {
+      issues.push({ path: ["targets", i], message: `targets[${i}] must be an object` });
+      continue;
+    }
+    const target = rawTarget as Record<string, unknown>;
+    const provider = typeof target.provider === "string" ? target.provider.trim() : "";
+    const model = typeof target.model === "string" ? target.model.trim() : "";
+
+    if (!provider) {
+      issues.push({ path: ["targets", i, "provider"], message: `targets[${i}].provider is required` });
+    } else if (!Object.hasOwn(providers, provider)) {
+      issues.push({
+        path: ["targets", i, "provider"],
+        message: `targets[${i}].provider "${provider}" is not configured`,
+      });
+    } else {
+      configuredProviderCount += 1;
+      if (providers[provider]?.disabled !== true) enabledProviderCount += 1;
+    }
+
+    if (!model) {
+      issues.push({ path: ["targets", i, "model"], message: `targets[${i}].model is required` });
+    }
+    if (target.weight !== undefined
+      && (typeof target.weight !== "number" || !Number.isInteger(target.weight)
+        || target.weight < 1
+        || target.weight > 10_000)) {
+      issues.push({
+        path: ["targets", i, "weight"],
+        message: `targets[${i}].weight must be an integer from 1 to 10000`,
+      });
+    }
+
+    if (provider && model) {
+      const key = targetKey({ provider, model });
+      if (seen.has(key)) {
+        issues.push({ path: ["targets", i], message: `duplicate combo target "${key}"` });
+      } else {
+        seen.add(key);
+      }
+    }
+  }
+  if (options.requireEnabledTarget
+    && configuredProviderCount === body.targets.length
+    && enabledProviderCount === 0) {
+    issues.push({
+      path: ["targets"],
+      message: "targets must include at least one enabled provider",
+    });
+  }
+  return issues;
+}
+
+export function comboConfigError(
+  id: string,
+  raw: unknown,
+  providers: Record<string, OcxProviderConfig>,
+  options: { requireEnabledTarget?: boolean } = {},
+): string | null {
+  return comboConfigIssues(id, raw, providers, options)[0]?.message ?? null;
+}
+
+export function normalizeComboConfig(raw: OcxComboConfig): NormalizedComboConfig {
+  return {
+    strategy: raw.strategy ?? "failover",
+    stickyLimit: raw.stickyLimit ?? 1,
+    defaultEffort: raw.defaultEffort ?? COMBO_DEFAULT_EFFORT,
+    targets: raw.targets.map(target => ({
+      provider: target.provider.trim(),
+      model: target.model.trim(),
+      weight: target.weight ?? 1,
+    })),
+  };
+}
+
+export function comboDefaultEffort(
+  config: { combos?: Record<string, OcxComboConfig> },
+  id: string,
+): OcxComboDefaultEffort | null {
+  const combos = config.combos;
+  if (!combos || !Object.hasOwn(combos, id)) return null;
+  const value: unknown = combos[id]!.defaultEffort ?? COMBO_DEFAULT_EFFORT;
+  return typeof value === "string" && isCodexReasoningEffort(value)
+    ? value as OcxComboDefaultEffort
+    : null;
+}
+
+export function isValidComboId(id: string): boolean {
+  return COMBO_ID_PATTERN.test(id);
+}
+
+export function listComboIds(config: { combos?: Record<string, OcxComboConfig> }): string[] {
+  return Object.keys(config.combos ?? {}).sort((a, b) => a.localeCompare(b));
+}
+
+export function getCombo(
+  config: { combos?: Record<string, OcxComboConfig> },
+  id: string,
+): NormalizedComboConfig | undefined {
+  const combos = config.combos;
+  if (!combos || !Object.hasOwn(combos, id)) return undefined;
+  return normalizeComboConfig(combos[id]!);
+}