@bitkyc08/opencodex 2.10.0 → 2.10.1

package/src/router.ts

@@ -1,19 +1,69 @@
 import type { CodexAccountMode, OcxConfig, OcxProviderConfig } from "./types";
-import { preservesPhysicalComboProvider, tryPickComboModel, type ComboPick } from "./combos";
+import {
+  getCombo,
+  isComboTargetInCooldown,
+  preservesPhysicalComboProvider,
+  targetKey,
+  tryPickComboModel,
+  type ComboPick,
+} from "./combos";
+import type { NormalizedComboConfig } from "./combos/types";
 import { hasOwnProvider, resolveEnvValue } from "./config";
 import { assertProviderDestinationAllowed } from "./lib/destination-policy";
 import { redactSecretString, redactUrlForLog } from "./lib/redact";
 import { PROVIDER_REGISTRY, providerCodexAccountMode, providerMatchesRegistryTransport } from "./providers/registry";
-import { LEGACY_CHATGPT_PROVIDER_ID, LEGACY_OPENAI_MULTI_PROVIDER_ID, OPENAI_API_PROVIDER_ID, OPENAI_CODEX_PROVIDER_ID } from "./providers/openai-tiers";
+import {
+  isCanonicalOpenAiForwardProvider,
+  LEGACY_CHATGPT_PROVIDER_ID,
+  LEGACY_OPENAI_MULTI_PROVIDER_ID,
+  OPENAI_API_PROVIDER_ID,
+  OPENAI_CODEX_PROVIDER_ID,
+} from "./providers/openai-tiers";
 import { decodeRoutedModelId, encodeRoutedModelId } from "./providers/slug-codec";
 import { getStaleCached } from "./codex/model-cache";
+import { codexAccountNamespaceEntries } from "./codex/account-namespaces";
+import { getEffectiveActiveCodexAccountId } from "./codex/routing";
+import { getAccountSet } from "./oauth/store";
+import {
+  buildRouteDecisionTrace,
+  type RouteDecisionKind,
+  type RouteDecisionTraceV1,
+  type TraceCandidateInput,
+} from "./routing/trace";
+import { getRoutingProfile, resolvePolicyProfileId } from "./routing/profile";
+import { evaluatePolicyProfile, type PolicyRequestEvidence } from "./routing/evaluator";
+import { candidateCapabilityEvidence } from "./routing/capability";
+import { policyCandidateHealthEvidence } from "./routing/health";
+import { quotaEvidenceForCandidate } from "./routing/quota";
+import { costEvidenceForCandidate } from "./routing/cost";
+
+export class NoEligiblePolicyCandidateError extends Error {
+  /** Evaluation trace (with per-candidate exclusions) when nothing qualified. */
+  readonly trace?: RouteDecisionTraceV1;
+
+  constructor(readonly profileId: string, trace?: RouteDecisionTraceV1) {
+    super(`No eligible candidates for policy profile: ${profileId}`);
+    this.name = "NoEligiblePolicyCandidateError";
+    this.trace = trace;
+  }
+}
 
 export interface RouteResult {
   providerName: string;
   provider: OcxProviderConfig;
   modelId: string;
+  /** Which deterministic routing path produced this route (RI-01). */
+  routeKind: RouteDecisionKind;
+  /** Stable wire reason code for the selected route (RI-01). */
+  routeReason: string;
   codexAccountMode?: CodexAccountMode;
+  /** Exact account selected by an account-qualified native model. */
+  codexAccountId?: string;
+  /** Public namespace used by the account-qualified selector. */
+  codexAccountNamespace?: string;
   combo?: ComboPick;
+  /** Bounded route-decision trace (RI-01); never contains secrets. */
+  routeDecision?: RouteDecisionTraceV1;
 }
 
 const MODEL_PROVIDER_PATTERNS: Array<{ providerNames: string[]; prefixes: string[] }> = [
@@ -259,6 +309,29 @@ function routedProviderConfig(providerName: string, provider: OcxProviderConfig)
     ...(provider.responsesPath === undefined && registryEntry.responsesPath !== undefined
       ? { responsesPath: registryEntry.responsesPath }
       : {}),
+    ...(provider.supportsServiceTier === undefined && registryEntry.supportsServiceTier !== undefined
+      ? { supportsServiceTier: registryEntry.supportsServiceTier }
+      : {}),
+    ...(provider.preserveResponsesReasoningContent === undefined && registryEntry.preserveResponsesReasoningContent !== undefined
+      ? { preserveResponsesReasoningContent: registryEntry.preserveResponsesReasoningContent }
+      : {}),
+    // Registry-only client-facing repair policy (#938): fill only when the
+    // saved provider has no explicit policy; clone so runtime never aliases
+    // the registry constant.
+    ...(provider.responsesItemIdRepair === undefined && registryEntry.responsesItemIdRepair
+      ? {
+        responsesItemIdRepair: {
+          ...(registryEntry.responsesItemIdRepair.message ? { message: [...registryEntry.responsesItemIdRepair.message] } : {}),
+          ...(registryEntry.responsesItemIdRepair.reasoning ? { reasoning: [...registryEntry.responsesItemIdRepair.reasoning] } : {}),
+          ...(registryEntry.responsesItemIdRepair.repairMissingTerminalIds !== undefined
+            ? { repairMissingTerminalIds: registryEntry.responsesItemIdRepair.repairMissingTerminalIds }
+            : {}),
+          ...(registryEntry.responsesItemIdRepair.repairInvalidIds !== undefined
+            ? { repairInvalidIds: registryEntry.responsesItemIdRepair.repairInvalidIds }
+            : {}),
+        },
+      }
+      : {}),
     authMode: canonicalAuthMode,
     apiKey: resolvedApiKey,
     // Backfill the Google wire mode + Vertex project/location from the registry when the user
@@ -276,6 +349,9 @@ function routedProviderConfig(providerName: string, provider: OcxProviderConfig)
     // opt-in, while an explicit user `false` keeps overriding registry `true`.
     ...(provider.parallelToolCalls === undefined && registryEntry.parallelToolCalls !== undefined ? { parallelToolCalls: registryEntry.parallelToolCalls } : {}),
     ...(provider.promptCacheKey === undefined && registryEntry.promptCacheKey !== undefined ? { promptCacheKey: registryEntry.promptCacheKey } : {}),
+    ...(provider.reasoningWireFormat === undefined && registryEntry.reasoningWireFormat !== undefined
+      ? { reasoningWireFormat: registryEntry.reasoningWireFormat }
+      : {}),
     ...(provider.defaultMaxOutputTokens === undefined && registryEntry.defaultMaxOutputTokens !== undefined
       ? { defaultMaxOutputTokens: registryEntry.defaultMaxOutputTokens }
       : {}),
@@ -315,6 +391,34 @@ export class NoEnabledOpenAiProviderError extends Error {
   }
 }
 
+/**
+ * One immutable selection trace for a combo request: built once from the
+ * initial pick, before any child dispatch. Fallback execution stays in the
+ * usage entry's `attempts[]`; the trace never changes after selection.
+ */
+export function comboRouteDecisionTrace(
+  config: OcxConfig,
+  comboId: string,
+  pick: ComboPick,
+  requestedModel: string,
+): RouteDecisionTraceV1 {
+  const combo = getCombo(config, comboId);
+  return buildRouteDecisionTrace({
+    requestedModel,
+    routeKind: "combo",
+    selected: {
+      provider: pick.target.provider,
+      model: pick.target.model,
+      reason: "combo-pick",
+      candidateIndex: pick.targetIndex,
+      ...(combo
+        ? { tieBreak: combo.strategy === "round-robin" ? "round-robin" : "failover" }
+        : {}),
+    },
+    candidates: combo ? comboRouteCandidates(config, pick, combo) : undefined,
+  });
+}
+
 // Codex uses a small number of control-plane model ids that are not part of the public GPT/o
 // naming families. Keep this exact: a broad `codex-*` rule could capture a third-party model.
 const CODEX_INTERNAL_OPENAI_MODELS = new Set(["codex-auto-review"]);
@@ -324,25 +428,170 @@ function isBareOpenAiFamilyModel(modelId: string): boolean {
     && (/^(?:gpt-|o1-|o3-|o4-)/.test(modelId) || CODEX_INTERNAL_OPENAI_MODELS.has(modelId));
 }
 
-function routeResult(providerName: string, provider: OcxProviderConfig, modelId: string): RouteResult {
+function routeResult(
+  providerName: string,
+  provider: OcxProviderConfig,
+  modelId: string,
+  routeKind: RouteDecisionKind,
+  routeReason: string,
+): RouteResult {
   const codexAccountMode = providerCodexAccountMode(providerName, provider);
   return {
     providerName,
     provider: routedProviderConfig(providerName, provider),
     modelId,
+    routeKind,
+    routeReason,
     ...(codexAccountMode ? { codexAccountMode } : {}),
   };
 }
 
-function routeModelInternal(config: OcxConfig, modelId: string, bypassCombos: boolean): RouteResult {
+/**
+ * Candidate evidence for a combo route: every configured target with its
+ * selection-time eligibility and exclusion reasons. Purely observational; the
+ * pick already happened and this never re-selects.
+ */
+function comboRouteCandidates(
+  config: OcxConfig,
+  pick: NonNullable<RouteResult["combo"]>,
+  combo: NormalizedComboConfig,
+): TraceCandidateInput[] {
+  const now = Date.now();
+  return combo.targets.map((target, index) => {
+    const key = targetKey(target);
+    const provider = config.providers[target.provider];
+    const configured = provider !== undefined;
+    const enabled = configured && provider.disabled !== true;
+    const inCooldown = isComboTargetInCooldown(pick.comboId, target, now);
+    const isSelected = index === pick.targetIndex;
+    // The pick's `attempted` list includes the winner itself; only non-selected
+    // targets can be "already-attempted" (fallback picks exclude earlier tries).
+    const alreadyAttempted = !isSelected && pick.attempted.includes(key);
+    const exclusions: TraceCandidateInput["exclusions"] = [];
+    if (!configured) exclusions.push({ code: "unconfigured" });
+    if (configured && !enabled) exclusions.push({ code: "disabled" });
+    if (inCooldown) exclusions.push({ code: "cooldown" });
+    if (isSelected && inCooldown) exclusions.push({ code: "selected-despite-cooldown" });
+    if (!isSelected && alreadyAttempted && exclusions.length === 0) {
+      exclusions.push({ code: "already-attempted" });
+    }
+    if (!isSelected && exclusions.length === 0) exclusions.push({ code: "not-selected" });
+    return {
+      provider: target.provider,
+      model: target.model,
+      eligible: enabled && !inCooldown && !alreadyAttempted,
+      exclusions,
+    };
+  });
+}
+
+function routeModelInternal(
+  config: OcxConfig,
+  modelId: string,
+  bypassCombos: boolean,
+  policyEvidence?: PolicyRequestEvidence,
+): RouteResult {
+  const slash = modelId.indexOf("/");
+  // Policy namespace is system-reserved: an explicit `policy/<id>` or a
+  // configured profile alias executes the policy evaluator and routes the
+  // selected candidate. Only explicit requests reach this branch; concrete
+  // recursive targets skip policy resolution entirely (bypassCombos) so an
+  // alias matching a selected candidate can never recurse, and a
+  // `policy/<id>` without a configured profile falls through to normal
+  // provider/default resolution instead of failing.
+  const policyId = !bypassCombos ? resolvePolicyProfileId(config, modelId) : null;
+  const profile = policyId ? getRoutingProfile(config, policyId) : undefined;
+  if (profile && policyId) {
+    // One clock read per decision keeps candidate evidence, exclusions, and
+    // scores mutually consistent and reproducible.
+    const now = Date.now();
+    const candidateEvidence = profile.candidates.map(candidate => ({
+      provider: candidate.provider,
+      model: candidate.model,
+      capability: candidateCapabilityEvidence(config, candidate.provider, candidate.model),
+      health: policyCandidateHealthEvidence(config, candidate, now),
+      quota: quotaEvidenceForCandidate({
+        provider: candidate.provider,
+        model: candidate.model,
+        ...(candidate.provider === OPENAI_CODEX_PROVIDER_ID
+          && providerCodexAccountMode(
+            OPENAI_CODEX_PROVIDER_ID,
+            config.providers[OPENAI_CODEX_PROVIDER_ID],
+          ) === "pool"
+          ? (() => {
+              const codexAccountId = getEffectiveActiveCodexAccountId(config);
+              return {
+                codexAccountId,
+                codexAccountPlan: codexAccountId
+                  ? config.codexAccounts?.find(account => account.id === codexAccountId)?.plan
+                  : undefined,
+              };
+            })()
+          : {}),
+        accountRef: candidate.provider === "anthropic"
+          ? getAccountSet("anthropic")?.activeAccountId
+          : undefined,
+      }),
+      cost: costEvidenceForCandidate({
+        provider: candidate.provider,
+        model: candidate.model,
+        limitUsd: profile.limits.maxEstimatedCostUsd,
+      }),
+    }));
+    const evaluation = evaluatePolicyProfile(config, policyId, policyEvidence ?? {}, candidateEvidence, now);
+    if (evaluation.selectedIndex === null) {
+      throw new NoEligiblePolicyCandidateError(policyId, evaluation.trace);
+    }
+    const selected = evaluation.candidates[evaluation.selectedIndex]!;
+    const concrete = `${selected.provider}/${selected.model}`;
+    const routed = routeModelInternal(config, concrete, true);
+    return {
+      ...routed,
+      routeKind: "policy" as const,
+      routeReason: "policy-selected",
+      routeDecision: evaluation.trace,
+    };
+  }
+  if (slash > 0) {
+    const namespace = modelId.slice(0, slash);
+    const binding = codexAccountNamespaceEntries(config)
+      .find(([candidate]) => candidate === namespace);
+    if (binding) {
+      const nativeModelId = modelId.slice(slash + 1);
+      if (!isBareOpenAiFamilyModel(nativeModelId)) {
+        throw new Error(`Codex account namespace ${namespace} only supports native OpenAI model ids`);
+      }
+      const provider = config.providers[OPENAI_CODEX_PROVIDER_ID];
+      if (!provider || provider.disabled === true) {
+        throw new NoEnabledOpenAiProviderError(nativeModelId);
+      }
+      // Registry routing backfills an omitted authMode on the built-in OpenAI row to forward.
+      // Mirror only that default here; explicit non-forward modes still fail closed.
+      const providerForCanonicalCheck = provider.authMode === undefined
+        ? { ...provider, authMode: "forward" as const }
+        : provider;
+      if (!isCanonicalOpenAiForwardProvider(providerForCanonicalCheck)) {
+        throw new NoEnabledOpenAiProviderError(nativeModelId);
+      }
+      return {
+        ...routeResult(OPENAI_CODEX_PROVIDER_ID, provider, nativeModelId, "explicit-account", "account-namespace"),
+        // Exact account injection uses the pool credential machinery even when the canonical
+        // provider is globally Direct. The fixed id bypasses pool selection entirely.
+        codexAccountMode: "pool",
+        codexAccountId: binding[1],
+        codexAccountNamespace: namespace,
+      };
+    }
+  }
+
   if (!bypassCombos && !preservesPhysicalComboProvider(config)) {
     const combo = tryPickComboModel(config, modelId);
     if (combo) {
       const concrete = `${combo.target.provider}/${combo.target.model}`;
       // The selected target is already a concrete provider/model reference. Resolve it without
       // consulting combo aliases again, otherwise an alias that shadows the target can recurse.
-      const routed = routeModelInternal(config, concrete, true);
-      return { ...routed, combo };
+      const routed = routeModelInternal(config, concrete, true, undefined);
+      return { ...routed, combo, routeKind: "combo" as const, routeReason: "combo-pick" };
     }
   }
 
@@ -350,7 +599,6 @@ function routeModelInternal(config: OcxConfig, modelId: string, bypassCombos: bo
   //    Only triggers when the prefix matches a CONFIGURED provider, so genuine
   //    slash-containing model ids (e.g. "anthropic/claude-...") fall through when
   //    no such provider exists.
-  const slash = modelId.indexOf("/");
   if (slash > 0) {
     const provName = modelId.slice(0, slash);
     if (provName === LEGACY_CHATGPT_PROVIDER_ID || provName === LEGACY_OPENAI_MULTI_PROVIDER_ID) {
@@ -363,23 +611,33 @@ function routeModelInternal(config: OcxConfig, modelId: string, bypassCombos: bo
       // Self-namespaced native id — the vendor segment equals the provider id, so the FULL ref is
       // itself a known model (e.g. orcarouter/auto). Route it whole instead of stripping to the
       // remainder, which would send a bare `auto` the upstream cannot resolve.
-      if (known.includes(modelId)) return routeResult(provName, prov, modelId);
+      if (known.includes(modelId)) {
+        return routeResult(provName, prov, modelId, "explicit-provider", "explicit-provider-namespace");
+      }
       // Codex-facing alias ids (`provider/vendor-model`) decode back to the native
       // slash id via an exact known-id lookup; raw full-slash selectors keep working.
-      return routeResult(provName, prov, decodeRoutedModelId(modelId.slice(slash + 1), known));
+      return routeResult(
+        provName,
+        prov,
+        decodeRoutedModelId(modelId.slice(slash + 1), known),
+        "explicit-provider",
+        "explicit-provider-namespace",
+      );
     }
   }
 
   if (isBareOpenAiFamilyModel(modelId)) {
     const provider = config.providers[OPENAI_CODEX_PROVIDER_ID];
-    if (provider && provider.disabled !== true) return routeResult(OPENAI_CODEX_PROVIDER_ID, provider, modelId);
+    if (provider && provider.disabled !== true) {
+      return routeResult(OPENAI_CODEX_PROVIDER_ID, provider, modelId, "native", "native-family");
+    }
     throw new NoEnabledOpenAiProviderError(modelId);
   }
 
   for (const [provName, prov] of activeProviderEntries(config)) {
     if (prov.defaultModel === modelId
       || (typeof prov.defaultModel === "string" && encodeRoutedModelId(prov.defaultModel) === modelId)) {
-      return routeResult(provName, prov, prov.defaultModel as string);
+      return routeResult(provName, prov, prov.defaultModel as string, "explicit-provider", "configured-default-model");
     }
   }
 
@@ -389,7 +647,9 @@ function routeModelInternal(config: OcxConfig, modelId: string, bypassCombos: bo
   for (const [provName, prov] of activeProviderEntries(config)) {
     if (prov.models && Array.isArray(prov.models)) {
       const hit = (prov.models as string[]).find(id => id === modelId || encodeRoutedModelId(id) === modelId);
-      if (hit !== undefined) return routeResult(provName, prov, hit);
+      if (hit !== undefined) {
+        return routeResult(provName, prov, hit, "explicit-provider", "configured-model-list");
+      }
     }
   }
 
@@ -399,14 +659,40 @@ function routeModelInternal(config: OcxConfig, modelId: string, bypassCombos: bo
   if (hasOwnProvider(config.providers, config.defaultProvider)) {
     const defaultProv = config.providers[config.defaultProvider];
     if (defaultProv.disabled === true) throw new Error(`Default provider is disabled: ${config.defaultProvider}`);
-    return routeResult(config.defaultProvider, defaultProv, modelId);
+    return routeResult(config.defaultProvider, defaultProv, modelId, "default-provider", "default-provider");
   }
 
   throw new Error(`No provider configured for model: ${modelId}`);
 }
 
-export function routeModel(config: OcxConfig, modelId: string): RouteResult {
-  return routeModelInternal(config, modelId, false);
+export function routeModel(
+  config: OcxConfig,
+  modelId: string,
+  policyEvidence?: PolicyRequestEvidence,
+): RouteResult {
+  const route = routeModelInternal(config, modelId, false, policyEvidence);
+  // Policy routes carry a full evaluation trace already; never rebuild it.
+  if (route.routeDecision) return route;
+  const accountRef = route.codexAccountNamespace;
+  const combo = route.combo ? getCombo(config, route.combo.comboId) : undefined;
+  route.routeDecision = buildRouteDecisionTrace({
+    requestedModel: modelId,
+    routeKind: route.routeKind,
+    selected: {
+      provider: route.providerName,
+      model: route.modelId,
+      ...(accountRef ? { accountRef } : {}),
+      reason: route.routeReason,
+      ...(route.combo ? { candidateIndex: route.combo.targetIndex } : {}),
+      ...(combo
+        ? { tieBreak: combo.strategy === "round-robin" ? "round-robin" : "failover" }
+        : {}),
+    },
+    candidates: route.routeKind === "combo" && route.combo && combo
+      ? comboRouteCandidates(config, route.combo, combo)
+      : undefined,
+  });
+  return route;
 }
 
 function routeByKnownModelPattern(config: OcxConfig, modelId: string): RouteResult | undefined {
@@ -417,7 +703,7 @@ function routeByKnownModelPattern(config: OcxConfig, modelId: string): RouteResu
       );
       if (matchingProvider) {
         const [provName, prov] = matchingProvider;
-        return routeResult(provName, prov, modelId);
+        return routeResult(provName, prov, modelId, "explicit-provider", "model-pattern");
       }
     }
   }