11import 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" ;
10+ import type { NormalizedComboConfig } from "./combos/types" ;
311import { hasOwnProvider , resolveEnvValue } from "./config" ;
412import { assertProviderDestinationAllowed } from "./lib/destination-policy" ;
513import { redactSecretString , redactUrlForLog } from "./lib/redact" ;
@@ -14,17 +22,29 @@ import {
1422import { decodeRoutedModelId , encodeRoutedModelId } from "./providers/slug-codec" ;
1523import { getStaleCached } from "./codex/model-cache" ;
1624import { codexAccountNamespaceEntries } from "./codex/account-namespaces" ;
25+ import {
26+ buildRouteDecisionTrace ,
27+ type RouteDecisionKind ,
28+ type RouteDecisionTraceV1 ,
29+ type TraceCandidateInput ,
30+ } from "./routing/trace" ;
1731
1832export interface RouteResult {
1933 providerName : string ;
2034 provider : OcxProviderConfig ;
2135 modelId : string ;
36+ /** Which deterministic routing path produced this route (RI-01). */
37+ routeKind : RouteDecisionKind ;
38+ /** Stable wire reason code for the selected route (RI-01). */
39+ routeReason : string ;
2240 codexAccountMode ?: CodexAccountMode ;
2341 /** Exact account selected by an account-qualified native model. */
2442 codexAccountId ?: string ;
2543 /** Public namespace used by the account-qualified selector. */
2644 codexAccountNamespace ?: string ;
2745 combo ?: ComboPick ;
46+ /** Bounded route-decision trace (RI-01); never contains secrets. */
47+ routeDecision ?: RouteDecisionTraceV1 ;
2848}
2949
3050const MODEL_PROVIDER_PATTERNS : Array < { providerNames : string [ ] ; prefixes : string [ ] } > = [
@@ -335,6 +355,34 @@ export class NoEnabledOpenAiProviderError extends Error {
335355 }
336356}
337357
358+ /**
359+ * One immutable selection trace for a combo request: built once from the
360+ * initial pick, before any child dispatch. Fallback execution stays in the
361+ * usage entry's `attempts[]`; the trace never changes after selection.
362+ */
363+ export function comboRouteDecisionTrace (
364+ config : OcxConfig ,
365+ comboId : string ,
366+ pick : ComboPick ,
367+ requestedModel : string ,
368+ ) : RouteDecisionTraceV1 {
369+ const combo = getCombo ( config , comboId ) ;
370+ return buildRouteDecisionTrace ( {
371+ requestedModel,
372+ routeKind : "combo" ,
373+ selected : {
374+ provider : pick . target . provider ,
375+ model : pick . target . model ,
376+ reason : "combo-pick" ,
377+ candidateIndex : pick . targetIndex ,
378+ ...( combo
379+ ? { tieBreak : combo . strategy === "round-robin" ? "round-robin" : "failover" }
380+ : { } ) ,
381+ } ,
382+ candidates : combo ? comboRouteCandidates ( config , pick , combo ) : undefined ,
383+ } ) ;
384+ }
385+
338386// Codex uses a small number of control-plane model ids that are not part of the public GPT/o
339387// naming families. Keep this exact: a broad `codex-*` rule could capture a third-party model.
340388const CODEX_INTERNAL_OPENAI_MODELS = new Set ( [ "codex-auto-review" ] ) ;
@@ -344,16 +392,63 @@ function isBareOpenAiFamilyModel(modelId: string): boolean {
344392 && ( / ^ (?: g p t - | o 1 - | o 3 - | o 4 - ) / . test ( modelId ) || CODEX_INTERNAL_OPENAI_MODELS . has ( modelId ) ) ;
345393}
346394
347- function routeResult ( providerName : string , provider : OcxProviderConfig , modelId : string ) : RouteResult {
395+ function routeResult (
396+ providerName : string ,
397+ provider : OcxProviderConfig ,
398+ modelId : string ,
399+ routeKind : RouteDecisionKind ,
400+ routeReason : string ,
401+ ) : RouteResult {
348402 const codexAccountMode = providerCodexAccountMode ( providerName , provider ) ;
349403 return {
350404 providerName,
351405 provider : routedProviderConfig ( providerName , provider ) ,
352406 modelId,
407+ routeKind,
408+ routeReason,
353409 ...( codexAccountMode ? { codexAccountMode } : { } ) ,
354410 } ;
355411}
356412
413+ /**
414+ * Candidate evidence for a combo route: every configured target with its
415+ * selection-time eligibility and exclusion reasons. Purely observational; the
416+ * pick already happened and this never re-selects.
417+ */
418+ function comboRouteCandidates (
419+ config : OcxConfig ,
420+ pick : NonNullable < RouteResult [ "combo" ] > ,
421+ combo : NormalizedComboConfig ,
422+ ) : TraceCandidateInput [ ] {
423+ const now = Date . now ( ) ;
424+ return combo . targets . map ( ( target , index ) => {
425+ const key = targetKey ( target ) ;
426+ const provider = config . providers [ target . provider ] ;
427+ const configured = provider !== undefined ;
428+ const enabled = configured && provider . disabled !== true ;
429+ const inCooldown = isComboTargetInCooldown ( pick . comboId , target , now ) ;
430+ const isSelected = index === pick . targetIndex ;
431+ // The pick's `attempted` list includes the winner itself; only non-selected
432+ // targets can be "already-attempted" (fallback picks exclude earlier tries).
433+ const alreadyAttempted = ! isSelected && pick . attempted . includes ( key ) ;
434+ const exclusions : TraceCandidateInput [ "exclusions" ] = [ ] ;
435+ if ( ! configured ) exclusions . push ( { code : "unconfigured" } ) ;
436+ if ( configured && ! enabled ) exclusions . push ( { code : "disabled" } ) ;
437+ if ( inCooldown ) exclusions . push ( { code : "cooldown" } ) ;
438+ if ( isSelected && inCooldown ) exclusions . push ( { code : "selected-despite-cooldown" } ) ;
439+ if ( ! isSelected && alreadyAttempted && exclusions . length === 0 ) {
440+ exclusions . push ( { code : "already-attempted" } ) ;
441+ }
442+ if ( ! isSelected && exclusions . length === 0 ) exclusions . push ( { code : "not-selected" } ) ;
443+ return {
444+ provider : target . provider ,
445+ model : target . model ,
446+ eligible : enabled && ! inCooldown && ! alreadyAttempted ,
447+ exclusions,
448+ } ;
449+ } ) ;
450+ }
451+
357452function routeModelInternal ( config : OcxConfig , modelId : string , bypassCombos : boolean ) : RouteResult {
358453 const slash = modelId . indexOf ( "/" ) ;
359454 if ( slash > 0 ) {
@@ -378,7 +473,7 @@ function routeModelInternal(config: OcxConfig, modelId: string, bypassCombos: bo
378473 throw new NoEnabledOpenAiProviderError ( nativeModelId ) ;
379474 }
380475 return {
381- ...routeResult ( OPENAI_CODEX_PROVIDER_ID , provider , nativeModelId ) ,
476+ ...routeResult ( OPENAI_CODEX_PROVIDER_ID , provider , nativeModelId , "explicit-account" , "account-namespace" ) ,
382477 // Exact account injection uses the pool credential machinery even when the canonical
383478 // provider is globally Direct. The fixed id bypasses pool selection entirely.
384479 codexAccountMode : "pool" ,
@@ -395,7 +490,7 @@ function routeModelInternal(config: OcxConfig, modelId: string, bypassCombos: bo
395490 // The selected target is already a concrete provider/model reference. Resolve it without
396491 // consulting combo aliases again, otherwise an alias that shadows the target can recurse.
397492 const routed = routeModelInternal ( config , concrete , true ) ;
398- return { ...routed , combo } ;
493+ return { ...routed , combo, routeKind : "combo" as const , routeReason : "combo-pick" } ;
399494 }
400495 }
401496
@@ -415,23 +510,33 @@ function routeModelInternal(config: OcxConfig, modelId: string, bypassCombos: bo
415510 // Self-namespaced native id — the vendor segment equals the provider id, so the FULL ref is
416511 // itself a known model (e.g. orcarouter/auto). Route it whole instead of stripping to the
417512 // remainder, which would send a bare `auto` the upstream cannot resolve.
418- if ( known . includes ( modelId ) ) return routeResult ( provName , prov , modelId ) ;
513+ if ( known . includes ( modelId ) ) {
514+ return routeResult ( provName , prov , modelId , "explicit-provider" , "explicit-provider-namespace" ) ;
515+ }
419516 // Codex-facing alias ids (`provider/vendor-model`) decode back to the native
420517 // 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 ) ) ;
518+ return routeResult (
519+ provName ,
520+ prov ,
521+ decodeRoutedModelId ( modelId . slice ( slash + 1 ) , known ) ,
522+ "explicit-provider" ,
523+ "explicit-provider-namespace" ,
524+ ) ;
422525 }
423526 }
424527
425528 if ( isBareOpenAiFamilyModel ( modelId ) ) {
426529 const provider = config . providers [ OPENAI_CODEX_PROVIDER_ID ] ;
427- if ( provider && provider . disabled !== true ) return routeResult ( OPENAI_CODEX_PROVIDER_ID , provider , modelId ) ;
530+ if ( provider && provider . disabled !== true ) {
531+ return routeResult ( OPENAI_CODEX_PROVIDER_ID , provider , modelId , "native" , "native-family" ) ;
532+ }
428533 throw new NoEnabledOpenAiProviderError ( modelId ) ;
429534 }
430535
431536 for ( const [ provName , prov ] of activeProviderEntries ( config ) ) {
432537 if ( prov . defaultModel === modelId
433538 || ( typeof prov . defaultModel === "string" && encodeRoutedModelId ( prov . defaultModel ) === modelId ) ) {
434- return routeResult ( provName , prov , prov . defaultModel as string ) ;
539+ return routeResult ( provName , prov , prov . defaultModel as string , "explicit-provider" , "configured-default-model" ) ;
435540 }
436541 }
437542
@@ -441,7 +546,9 @@ function routeModelInternal(config: OcxConfig, modelId: string, bypassCombos: bo
441546 for ( const [ provName , prov ] of activeProviderEntries ( config ) ) {
442547 if ( prov . models && Array . isArray ( prov . models ) ) {
443548 const hit = ( prov . models as string [ ] ) . find ( id => id === modelId || encodeRoutedModelId ( id ) === modelId ) ;
444- if ( hit !== undefined ) return routeResult ( provName , prov , hit ) ;
549+ if ( hit !== undefined ) {
550+ return routeResult ( provName , prov , hit , "explicit-provider" , "configured-model-list" ) ;
551+ }
445552 }
446553 }
447554
@@ -451,14 +558,34 @@ function routeModelInternal(config: OcxConfig, modelId: string, bypassCombos: bo
451558 if ( hasOwnProvider ( config . providers , config . defaultProvider ) ) {
452559 const defaultProv = config . providers [ config . defaultProvider ] ;
453560 if ( defaultProv . disabled === true ) throw new Error ( `Default provider is disabled: ${ config . defaultProvider } ` ) ;
454- return routeResult ( config . defaultProvider , defaultProv , modelId ) ;
561+ return routeResult ( config . defaultProvider , defaultProv , modelId , "default-provider" , "default-provider" ) ;
455562 }
456563
457564 throw new Error ( `No provider configured for model: ${ modelId } ` ) ;
458565}
459566
460567export function routeModel ( config : OcxConfig , modelId : string ) : RouteResult {
461- return routeModelInternal ( config , modelId , false ) ;
568+ const route = routeModelInternal ( config , modelId , false ) ;
569+ const accountRef = route . codexAccountNamespace ;
570+ const combo = route . combo ? getCombo ( config , route . combo . comboId ) : undefined ;
571+ route . routeDecision = buildRouteDecisionTrace ( {
572+ requestedModel : modelId ,
573+ routeKind : route . routeKind ,
574+ selected : {
575+ provider : route . providerName ,
576+ model : route . modelId ,
577+ ...( accountRef ? { accountRef } : { } ) ,
578+ reason : route . routeReason ,
579+ ...( route . combo ? { candidateIndex : route . combo . targetIndex } : { } ) ,
580+ ...( combo
581+ ? { tieBreak : combo . strategy === "round-robin" ? "round-robin" : "failover" }
582+ : { } ) ,
583+ } ,
584+ candidates : route . routeKind === "combo" && route . combo && combo
585+ ? comboRouteCandidates ( config , route . combo , combo )
586+ : undefined ,
587+ } ) ;
588+ return route ;
462589}
463590
464591function routeByKnownModelPattern ( config : OcxConfig , modelId : string ) : RouteResult | undefined {
@@ -469,7 +596,7 @@ function routeByKnownModelPattern(config: OcxConfig, modelId: string): RouteResu
469596 ) ;
470597 if ( matchingProvider ) {
471598 const [ provName , prov ] = matchingProvider ;
472- return routeResult ( provName , prov , modelId ) ;
599+ return routeResult ( provName , prov , modelId , "explicit-provider" , "model-pattern" ) ;
473600 }
474601 }
475602 }
0 commit comments