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" ;
310import { hasOwnProvider , resolveEnvValue } from "./config" ;
411import { assertProviderDestinationAllowed } from "./lib/destination-policy" ;
512import { redactSecretString , redactUrlForLog } from "./lib/redact" ;
@@ -14,17 +21,29 @@ import {
1421import { decodeRoutedModelId , encodeRoutedModelId } from "./providers/slug-codec" ;
1522import { getStaleCached } from "./codex/model-cache" ;
1623import { codexAccountNamespaceEntries } from "./codex/account-namespaces" ;
24+ import {
25+ buildRouteDecisionTrace ,
26+ type RouteDecisionKind ,
27+ type RouteDecisionTraceV1 ,
28+ type TraceCandidateInput ,
29+ } from "./routing/trace" ;
1730
1831export 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
3049const MODEL_PROVIDER_PATTERNS : Array < { providerNames : string [ ] ; prefixes : string [ ] } > = [
@@ -344,16 +363,63 @@ function isBareOpenAiFamilyModel(modelId: string): boolean {
344363 && ( / ^ (?: g p t - | o 1 - | o 3 - | o 4 - ) / . 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+
357423function 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
460538export 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
464559function 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