Skip to content

Commit b5a8e7c

Browse files
committed
feat(routing): record durable route decision traces (RI-01)
1 parent 97681a9 commit b5a8e7c

10 files changed

Lines changed: 991 additions & 12 deletions

File tree

‎src/router.ts‎

Lines changed: 107 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,12 @@
11
import type { CodexAccountMode, OcxConfig, OcxProviderConfig } from "./types";
2-
import { preservesPhysicalComboProvider, tryPickComboModel, type ComboPick } from "./combos";
2+
import {
3+
getCombo,
4+
isComboTargetInCooldown,
5+
preservesPhysicalComboProvider,
6+
targetKey,
7+
tryPickComboModel,
8+
type ComboPick,
9+
} from "./combos";
310
import { hasOwnProvider, resolveEnvValue } from "./config";
411
import { assertProviderDestinationAllowed } from "./lib/destination-policy";
512
import { redactSecretString, redactUrlForLog } from "./lib/redact";
@@ -14,17 +21,29 @@ import {
1421
import { decodeRoutedModelId, encodeRoutedModelId } from "./providers/slug-codec";
1522
import { getStaleCached } from "./codex/model-cache";
1623
import { codexAccountNamespaceEntries } from "./codex/account-namespaces";
24+
import {
25+
buildRouteDecisionTrace,
26+
type RouteDecisionKind,
27+
type RouteDecisionTraceV1,
28+
type TraceCandidateInput,
29+
} from "./routing/trace";
1730

1831
export interface RouteResult {
1932
providerName: string;
2033
provider: OcxProviderConfig;
2134
modelId: string;
35+
/** Which deterministic routing path produced this route (RI-01). */
36+
routeKind: RouteDecisionKind;
37+
/** Stable wire reason code for the selected route (RI-01). */
38+
routeReason: string;
2239
codexAccountMode?: CodexAccountMode;
2340
/** Exact account selected by an account-qualified native model. */
2441
codexAccountId?: string;
2542
/** Public namespace used by the account-qualified selector. */
2643
codexAccountNamespace?: string;
2744
combo?: ComboPick;
45+
/** Bounded route-decision trace (RI-01); never contains secrets. */
46+
routeDecision?: RouteDecisionTraceV1;
2847
}
2948

3049
const MODEL_PROVIDER_PATTERNS: Array<{ providerNames: string[]; prefixes: string[] }> = [
@@ -344,16 +363,63 @@ function isBareOpenAiFamilyModel(modelId: string): boolean {
344363
&& (/^(?:gpt-|o1-|o3-|o4-)/.test(modelId) || CODEX_INTERNAL_OPENAI_MODELS.has(modelId));
345364
}
346365

347-
function routeResult(providerName: string, provider: OcxProviderConfig, modelId: string): RouteResult {
366+
function routeResult(
367+
providerName: string,
368+
provider: OcxProviderConfig,
369+
modelId: string,
370+
routeKind: RouteDecisionKind,
371+
routeReason: string,
372+
): RouteResult {
348373
const codexAccountMode = providerCodexAccountMode(providerName, provider);
349374
return {
350375
providerName,
351376
provider: routedProviderConfig(providerName, provider),
352377
modelId,
378+
routeKind,
379+
routeReason,
353380
...(codexAccountMode ? { codexAccountMode } : {}),
354381
};
355382
}
356383

384+
/**
385+
* Candidate evidence for a combo route: every configured target with its
386+
* selection-time eligibility and exclusion reasons. Purely observational; the
387+
* pick already happened and this never re-selects.
388+
*/
389+
function comboRouteCandidates(config: OcxConfig, route: RouteResult): TraceCandidateInput[] | undefined {
390+
const combo = route.combo;
391+
if (!combo) return undefined;
392+
const normalized = getCombo(config, combo.comboId);
393+
if (!normalized) return undefined;
394+
const now = Date.now();
395+
return normalized.targets.map((target, index) => {
396+
const key = targetKey(target);
397+
const provider = config.providers[target.provider];
398+
const configured = provider !== undefined;
399+
const enabled = configured && provider.disabled !== true;
400+
const inCooldown = isComboTargetInCooldown(combo.comboId, target, now);
401+
const isSelected = index === combo.targetIndex;
402+
// The pick's `attempted` list includes the winner itself; only non-selected
403+
// targets can be "already-attempted" (fallback picks exclude earlier tries).
404+
const alreadyAttempted = !isSelected && combo.attempted.includes(key);
405+
const exclusions: TraceCandidateInput["exclusions"] = [];
406+
if (!configured) exclusions.push({ code: "unconfigured" });
407+
if (configured && !enabled) exclusions.push({ code: "disabled" });
408+
if (inCooldown) exclusions.push({ code: "cooldown" });
409+
if (isSelected && inCooldown) exclusions.push({ code: "selected-despite-cooldown" });
410+
if (!isSelected && alreadyAttempted && exclusions.length === 0) {
411+
exclusions.push({ code: "already-attempted" });
412+
}
413+
if (!isSelected && exclusions.length === 0) exclusions.push({ code: "not-selected" });
414+
return {
415+
provider: target.provider,
416+
model: target.model,
417+
eligible: enabled && !inCooldown && !alreadyAttempted,
418+
exclusions,
419+
};
420+
});
421+
}
422+
357423
function routeModelInternal(config: OcxConfig, modelId: string, bypassCombos: boolean): RouteResult {
358424
const slash = modelId.indexOf("/");
359425
if (slash > 0) {
@@ -378,7 +444,7 @@ function routeModelInternal(config: OcxConfig, modelId: string, bypassCombos: bo
378444
throw new NoEnabledOpenAiProviderError(nativeModelId);
379445
}
380446
return {
381-
...routeResult(OPENAI_CODEX_PROVIDER_ID, provider, nativeModelId),
447+
...routeResult(OPENAI_CODEX_PROVIDER_ID, provider, nativeModelId, "explicit-account", "account-namespace"),
382448
// Exact account injection uses the pool credential machinery even when the canonical
383449
// provider is globally Direct. The fixed id bypasses pool selection entirely.
384450
codexAccountMode: "pool",
@@ -395,7 +461,7 @@ function routeModelInternal(config: OcxConfig, modelId: string, bypassCombos: bo
395461
// The selected target is already a concrete provider/model reference. Resolve it without
396462
// consulting combo aliases again, otherwise an alias that shadows the target can recurse.
397463
const routed = routeModelInternal(config, concrete, true);
398-
return { ...routed, combo };
464+
return { ...routed, combo, routeKind: "combo" as const, routeReason: "combo-pick" };
399465
}
400466
}
401467

@@ -415,23 +481,33 @@ function routeModelInternal(config: OcxConfig, modelId: string, bypassCombos: bo
415481
// Self-namespaced native id — the vendor segment equals the provider id, so the FULL ref is
416482
// itself a known model (e.g. orcarouter/auto). Route it whole instead of stripping to the
417483
// remainder, which would send a bare `auto` the upstream cannot resolve.
418-
if (known.includes(modelId)) return routeResult(provName, prov, modelId);
484+
if (known.includes(modelId)) {
485+
return routeResult(provName, prov, modelId, "explicit-provider", "explicit-provider-namespace");
486+
}
419487
// Codex-facing alias ids (`provider/vendor-model`) decode back to the native
420488
// slash id via an exact known-id lookup; raw full-slash selectors keep working.
421-
return routeResult(provName, prov, decodeRoutedModelId(modelId.slice(slash + 1), known));
489+
return routeResult(
490+
provName,
491+
prov,
492+
decodeRoutedModelId(modelId.slice(slash + 1), known),
493+
"explicit-provider",
494+
"explicit-provider-namespace",
495+
);
422496
}
423497
}
424498

425499
if (isBareOpenAiFamilyModel(modelId)) {
426500
const provider = config.providers[OPENAI_CODEX_PROVIDER_ID];
427-
if (provider && provider.disabled !== true) return routeResult(OPENAI_CODEX_PROVIDER_ID, provider, modelId);
501+
if (provider && provider.disabled !== true) {
502+
return routeResult(OPENAI_CODEX_PROVIDER_ID, provider, modelId, "native", "native-family");
503+
}
428504
throw new NoEnabledOpenAiProviderError(modelId);
429505
}
430506

431507
for (const [provName, prov] of activeProviderEntries(config)) {
432508
if (prov.defaultModel === modelId
433509
|| (typeof prov.defaultModel === "string" && encodeRoutedModelId(prov.defaultModel) === modelId)) {
434-
return routeResult(provName, prov, prov.defaultModel as string);
510+
return routeResult(provName, prov, prov.defaultModel as string, "explicit-provider", "configured-default-model");
435511
}
436512
}
437513

@@ -441,7 +517,9 @@ function routeModelInternal(config: OcxConfig, modelId: string, bypassCombos: bo
441517
for (const [provName, prov] of activeProviderEntries(config)) {
442518
if (prov.models && Array.isArray(prov.models)) {
443519
const hit = (prov.models as string[]).find(id => id === modelId || encodeRoutedModelId(id) === modelId);
444-
if (hit !== undefined) return routeResult(provName, prov, hit);
520+
if (hit !== undefined) {
521+
return routeResult(provName, prov, hit, "explicit-provider", "configured-model-list");
522+
}
445523
}
446524
}
447525

@@ -451,14 +529,31 @@ function routeModelInternal(config: OcxConfig, modelId: string, bypassCombos: bo
451529
if (hasOwnProvider(config.providers, config.defaultProvider)) {
452530
const defaultProv = config.providers[config.defaultProvider];
453531
if (defaultProv.disabled === true) throw new Error(`Default provider is disabled: ${config.defaultProvider}`);
454-
return routeResult(config.defaultProvider, defaultProv, modelId);
532+
return routeResult(config.defaultProvider, defaultProv, modelId, "default-provider", "default-provider");
455533
}
456534

457535
throw new Error(`No provider configured for model: ${modelId}`);
458536
}
459537

460538
export function routeModel(config: OcxConfig, modelId: string): RouteResult {
461-
return routeModelInternal(config, modelId, false);
539+
const route = routeModelInternal(config, modelId, false);
540+
const accountRef = route.codexAccountNamespace;
541+
route.routeDecision = buildRouteDecisionTrace({
542+
requestedModel: modelId,
543+
routeKind: route.routeKind,
544+
selected: {
545+
provider: route.providerName,
546+
model: route.modelId,
547+
...(accountRef ? { accountRef } : {}),
548+
reason: route.routeReason,
549+
...(route.combo ? { candidateIndex: route.combo.targetIndex } : {}),
550+
...(route.combo
551+
? { tieBreak: getCombo(config, route.combo.comboId)?.strategy === "round-robin" ? "round-robin" : "failover" }
552+
: {}),
553+
},
554+
candidates: route.routeKind === "combo" ? comboRouteCandidates(config, route) : undefined,
555+
});
556+
return route;
462557
}
463558

464559
function routeByKnownModelPattern(config: OcxConfig, modelId: string): RouteResult | undefined {
@@ -469,7 +564,7 @@ function routeByKnownModelPattern(config: OcxConfig, modelId: string): RouteResu
469564
);
470565
if (matchingProvider) {
471566
const [provName, prov] = matchingProvider;
472-
return routeResult(provName, prov, modelId);
567+
return routeResult(provName, prov, modelId, "explicit-provider", "model-pattern");
473568
}
474569
}
475570
}

0 commit comments

Comments
 (0)