@yansigit/opencodex 2.31.0

package/src/combos/index.ts

@@ -0,0 +1,45 @@
+export {
+  COMBO_NAMESPACE,
+  comboAliasIssues,
+  comboConfigError,
+  comboConfigIssues,
+  comboDefaultEffort,
+  comboDisabledModelId,
+  comboDisabledModelSelectors,
+  comboModelId,
+  comboPublicModelId,
+  getCombo,
+  isNativeAliasCombo,
+  isValidComboId,
+  listComboIds,
+  normalizeComboConfig,
+  parseComboModelId,
+  preservesPhysicalComboProvider,
+  resolveComboId,
+  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,
+  comboRequestHasImageInput,
+  concreteComboRequestBody,
+  resetComboEffortWarningStateForTests,
+} from "./request";

package/src/combos/request.ts

@@ -0,0 +1,94 @@
+import type { OcxComboDefaultEffort, OcxComboTarget, OcxConfig } from "../types";
+import { resolveComboId } from "./types";
+
+const warnedUnsupportedDefaults = new Set<string>();
+let lastWarningReconciledGeneration = 0;
+
+export function reconcileComboWarningMemos(generation: number): number {
+  if (generation <= lastWarningReconciledGeneration) return 0;
+  const removed = warnedUnsupportedDefaults.size;
+  warnedUnsupportedDefaults.clear();
+  lastWarningReconciledGeneration = generation;
+  return removed;
+}
+
+export function resetComboEffortWarningStateForTests(): void {
+  warnedUnsupportedDefaults.clear();
+}
+
+export function comboIdFromRawBody(body: unknown, config: OcxConfig): 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 resolveComboId(config, model);
+}
+
+/**
+ * Detect image-bearing Responses *input* only.
+ *
+ * Must not walk the full request body: tool JSON schemas, metadata, or extension
+ * payloads can legally contain `{ "type": "input_image" }` without any image
+ * being dispatched. After previous_response_id expansion, scan the materialised
+ * `input` tree (message content and function_call_output.output).
+ */
+export function comboRequestHasImageInput(body: unknown): boolean {
+  if (!body || typeof body !== "object" || Array.isArray(body)) return false;
+  return responsesInputHasImage((body as { input?: unknown }).input);
+}
+
+function responsesInputHasImage(input: unknown): boolean {
+  if (typeof input === "string" || input == null) return false;
+  if (!Array.isArray(input)) return false;
+  return input.some(responsesInputNodeHasImage);
+}
+
+function responsesInputNodeHasImage(value: unknown): boolean {
+  if (!value || typeof value !== "object") return false;
+  if (Array.isArray(value)) return value.some(responsesInputNodeHasImage);
+  const record = value as Record<string, unknown>;
+  if (record.type === "input_image") return true;
+  // Message content parts and nested function_call_output content/output arrays.
+  if (record.content !== undefined && responsesInputNodeHasImage(record.content)) return true;
+  if (record.output !== undefined && responsesInputNodeHasImage(record.output)) return true;
+  return false;
+}
+
+export function concreteComboRequestBody(
+  body: unknown,
+  target: Pick<OcxComboTarget, "provider" | "model">,
+  defaultEffort: OcxComboDefaultEffort | null,
+  targetReasoningEfforts: readonly string[] | undefined,
+): 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;
+  const needsDefault = reasoning === undefined || (
+    reasoning
+    && typeof reasoning === "object"
+    && !Array.isArray(reasoning)
+    && !Object.prototype.hasOwnProperty.call(reasoning, "effort")
+  );
+  if (!needsDefault) return clone;
+  // Picker availability treats an unknown ladder as a wildcard, but runtime
+  // injection stays fail-closed until this concrete target advertises support.
+  if (!targetReasoningEfforts?.includes(defaultEffort)) {
+    const key = `${target.provider}/${target.model}:${defaultEffort}`;
+    if (!warnedUnsupportedDefaults.has(key)) {
+      warnedUnsupportedDefaults.add(key);
+      console.debug("[opencodex] combo default effort omitted", {
+        provider: target.provider,
+        model: target.model,
+        requestedEffort: defaultEffort,
+        capability: targetReasoningEfforts === undefined ? "unknown" : "unsupported",
+      });
+    }
+    return clone;
+  }
+  if (reasoning === undefined) {
+    clone.reasoning = { effort: defaultEffort };
+  } else {
+    clone.reasoning = { ...(reasoning as Record<string, unknown>), effort: defaultEffort };
+  }
+  return clone;
+}

package/src/combos/resolve.ts

@@ -0,0 +1,232 @@
+import type { OcxComboTarget, OcxConfig } from "../types";
+import { coolComboTarget, isComboTargetInCooldown } from "./failover";
+import { getCombo, resolveComboId, targetKey } from "./types";
+import type { NormalizedComboConfig } from "./types";
+import {
+  captureConfigGeneration,
+  type GenerationContext,
+} from "../lib/state-store-sweeper";
+
+export interface ComboPick {
+  comboId: string;
+  target: Required<OcxComboTarget>;
+  targetIndex: number;
+  attempted: string[];
+  writerGeneration: number;
+}
+
+interface SelectionState {
+  activeKey?: string;
+  successes: number;
+  currentWeights: Map<string, number>;
+}
+
+const selectionState = new Map<string, SelectionState>();
+let lastReconciledGeneration = 0;
+let liveComboTargets = new Set<string>();
+
+function comboTargetOwnerKey(comboId: string, key: string): string {
+  return `${comboId}::${key}`;
+}
+
+function mayCommitComboState(comboId: string, key: string, writerGeneration: number): boolean {
+  return writerGeneration >= lastReconciledGeneration
+    || liveComboTargets.has(comboTargetOwnerKey(comboId, key));
+}
+
+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 writerGeneration = captureConfigGeneration();
+  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)],
+    writerGeneration,
+  };
+}
+
+export function noteComboSuccess(
+  comboId: string,
+  combo: NormalizedComboConfig,
+  target: Required<OcxComboTarget>,
+  writerGeneration = captureConfigGeneration(),
+): void {
+  if (combo.strategy !== "round-robin") return;
+  const key = targetKey(target);
+  if (!mayCommitComboState(comboId, key, writerGeneration)) return;
+  const state = selectionState.get(comboId);
+  if (!state || state.activeKey !== key) return;
+  state.successes += 1;
+  if (state.successes >= combo.stickyLimit) {
+    delete state.activeKey;
+    state.successes = 0;
+  }
+}
+
+export function noteComboFailure(
+  comboId: string,
+  target: OcxComboTarget,
+  writerGeneration = captureConfigGeneration(),
+): void {
+  if (!mayCommitComboState(comboId, targetKey(target), writerGeneration)) return;
+  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;
+    eligible?: (target: Required<OcxComboTarget>) => boolean;
+  } = {},
+): ComboPick | null {
+  noteComboFailure(pick.comboId, pick.target, pick.writerGeneration);
+  coolComboTarget(pick.comboId, pick.target, {
+    ...options,
+    writerGeneration: pick.writerGeneration,
+  });
+  return pickComboTarget(config, pick.comboId, {
+    exclude: pick.attempted,
+    eligible: target => !isComboTargetInCooldown(pick.comboId, target, options.now)
+      && (options.eligible?.(target) ?? true),
+  });
+}
+
+export function reconcileComboRotationState(context: GenerationContext): number {
+  if (context.generation <= lastReconciledGeneration) return 0;
+  let removed = 0;
+  for (const [comboId, state] of selectionState) {
+    if (!context.comboIds.has(comboId)) {
+      selectionState.delete(comboId);
+      removed += 1;
+      continue;
+    }
+    if (state.activeKey && !context.comboTargets.has(comboTargetOwnerKey(comboId, state.activeKey))) {
+      delete state.activeKey;
+      state.successes = 0;
+      removed += 1;
+    }
+    for (const key of state.currentWeights.keys()) {
+      if (context.comboTargets.has(comboTargetOwnerKey(comboId, key))) continue;
+      state.currentWeights.delete(key);
+      removed += 1;
+    }
+  }
+  liveComboTargets = new Set(context.comboTargets);
+  lastReconciledGeneration = context.generation;
+  return removed;
+}
+
+export function clearComboSelectionState(comboId?: string): void {
+  if (comboId === undefined) {
+    selectionState.clear();
+    liveComboTargets.clear();
+    lastReconciledGeneration = 0;
+    return;
+  }
+  selectionState.delete(comboId);
+}
+
+export function tryPickComboModel(config: OcxConfig, modelId: string): ComboPick | null {
+  const comboId = resolveComboId(config, 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;
+}