@x12i/ai-gateway 9.5.3 → 9.6.0

package/README.md

@@ -79,7 +79,7 @@ const response = await gateway.invoke({
     agentId: 'agent-456'
   },
   workingMemory: { input: 'Hello!' },
-  config: { model: 'openai/gpt-4o-mini', provider: 'openrouter' }
+  config: { model: 'cheap', provider: 'openrouter' }
 });
 
 console.log(response.content, response.metadata?.costUsd, response.metadata?.tokens);
@@ -87,7 +87,7 @@ console.log(response.content, response.metadata?.costUsd, response.metadata?.tok
 
 ### Providers without manual `register()`
 
-- **OpenRouter:** Set `OPEN_ROUTER_KEY` or `OPENROUTER_API_KEY` (unless `USE_OPENROUTER=false`). The gateway can lazy-register on first invoke.
+- **OpenRouter:** Set **`OPENROUTER_API_KEY`** in `.env` (unless `USE_OPENROUTER=false`). The gateway passes this key into the router on init and lazy-registers on first invoke. **`OPEN_ROUTER_KEY`** is a legacy alias still read if `OPENROUTER_API_KEY` is unset — prefer **`OPENROUTER_API_KEY`** so **`@x12i/ai-tools`** model resolution sets `routedViaOpenRouter` correctly (ai-tools does not read `OPEN_ROUTER_KEY`).
 - **Direct providers:** Set `OPENAI_API_KEY`, `GROK_API_KEY`, etc. Same lazy registration.
 
 Load `.env` before constructing the gateway if another package creates it first.
@@ -217,7 +217,7 @@ Set via constructor `mode` or env `mode` / `MODE`.
 | `npm run test:flex-md-esm-regression` | ESM build regression for flex-md |
 | `npm run test:prepublish` | `build` + `npm test` |
 
-Live tests use `LIVE_TEST_PROVIDER` / `LIVE_TEST_MODEL` (default `openrouter` + `openai/gpt-4o-mini`). Set `LIVE_SKIP_INVOKE=1` to skip the LLM call.
+Live tests use `LIVE_TEST_PROVIDER` / `LIVE_TEST_MODEL` (default `openrouter` + `cheap`, an ai-tools profile alias). Set `LIVE_SKIP_INVOKE=1` to skip the LLM call.
 
 ---
 

package/dist/defaults/model-config.json

@@ -1,6 +1,6 @@
 {
-  "defaultEngine": "openai",
-  "defaultModel": "gpt-5-nano",
+  "defaultEngine": "openrouter",
+  "defaultModel": "cheap",
   "temperature": 0.7,
   "topP": 1.0,
   "frequencyPenalty": 0.0,
@@ -13,4 +13,3 @@
     "throttlingDelay": 5000
   }
 }
-

package/dist/gateway-config.js

@@ -197,7 +197,7 @@ export function initializeGatewayComponents(config) {
     // Prefer explicit config from consumer (e.g. ai-skills) to avoid env-loading timing; fall back to process.env.
     const explicitOpenRouterKey = config.openrouter?.apiKey;
     const isExplicitKey = typeof explicitOpenRouterKey === 'string' && !explicitOpenRouterKey.startsWith('ENV.');
-    const openRouterKey = isExplicitKey ? explicitOpenRouterKey : (process.env.OPEN_ROUTER_KEY ?? process.env.OPENROUTER_API_KEY);
+    const openRouterKey = isExplicitKey ? explicitOpenRouterKey : (process.env.OPENROUTER_API_KEY ?? process.env.OPEN_ROUTER_KEY);
     const useOpenRouter = config.openRouter?.enabled !== undefined ? config.openRouter?.enabled : process.env.USE_OPENROUTER;
     if (openRouterKey && useOpenRouter !== false && useOpenRouter !== 'false') {
         routerConfig.openRouter = { enabled: true };

package/dist/gateway-meta.js

@@ -2,6 +2,7 @@
  * Gateway Meta Operations Module
  * Handles meta operations like instruction optimization and testing
  */
+import { CODE_DEFAULT_MODEL } from './gateway-mode.js';
 /**
  * Test instructions by running them and analyzing the response
  */
@@ -9,7 +10,7 @@ export async function testInstructions(instructions, testInput, expectedSchema,
     // Get internal system action config (instruction audit)
     const internalConfig = config.internalSystemActions?.instructionAudit;
     const defaultEngine = config.defaultEngine || 'openai';
-    const defaultModel = internalConfig?.model || 'gpt-5-nano';
+    const defaultModel = internalConfig?.model || CODE_DEFAULT_MODEL;
     const defaultProvider = internalConfig?.engine || defaultEngine;
     const { agentId = 'instruction-tester', model = options.model || defaultModel, // Use internal config default if not provided
     provider = options.provider || defaultProvider // Use internal config default if not provided

package/dist/gateway-mode.d.ts

@@ -6,7 +6,8 @@ import type { ActivityIdentity, GatewayConfig } from './types.js';
 export type GatewayOperationalMode = 'prod' | 'debug' | 'dev';
 export type GatewayDefaultModelSource = 'env' | 'model-config.json' | 'code';
 export type DefaultModelSubstitutionReason = 'no_model_provided' | 'model_resolution_failed' | 'ai_tools_unavailable';
-export declare const CODE_DEFAULT_MODEL = "gpt-5-nano";
+/** Profile name resolved via ai-tools + {@link @x12i/ai-profiles} when catalog is enabled. */
+export declare const CODE_DEFAULT_MODEL = "cheap";
 export type ResolvedGatewayDefault = {
     model: string;
     provider?: string;

package/dist/gateway-mode.js

@@ -2,7 +2,8 @@
  * Gateway operational mode (prod vs dev/debug) and default model resolution.
  */
 import { gatewayLogDebug, withActivityIdentity } from './gateway-log-meta.js';
-export const CODE_DEFAULT_MODEL = 'gpt-5-nano';
+/** Profile name resolved via ai-tools + {@link @x12i/ai-profiles} when catalog is enabled. */
+export const CODE_DEFAULT_MODEL = 'cheap';
 /**
  * Operational mode: `GatewayConfig.mode` overrides `process.env.mode` / `MODE`.
  * Only `prod` allows silent default-model substitution; all other values are strict.

package/dist/gateway-provider-auto-register.js

@@ -146,7 +146,7 @@ export async function autoRegisterProviders(router, logger) {
             optionalEnvVars: PROVIDER_CONFIGS
                 .filter(p => p.optional)
                 .map(p => p.envVar),
-            openRouter: 'Set OPEN_ROUTER_KEY or OPENROUTER_API_KEY (and do not set USE_OPENROUTER=false) to use OpenRouter without registering a provider.',
+            openRouter: 'Set OPENROUTER_API_KEY (and do not set USE_OPENROUTER=false) to use OpenRouter without registering a provider. Legacy OPEN_ROUTER_KEY is still accepted.',
             note: 'You can still manually register providers using gateway.register(provider)'
         });
     }

package/dist/gateway-utils.d.ts

@@ -2,7 +2,7 @@
  * Gateway Utilities Module
  * Handles utility functions
  */
-import type { AIInvokeRequest, ChatRequest, GatewayConfig, GatewayInvokeRejectionMetadata, GatewayTraceAttempt, GatewayTraceMergedConfig, GatewayTraceRequestIds, GatewayTraceUsageSummary, ModelConfig } from './types.js';
+import type { AIInvokeRequest, ChatRequest, GatewayConfig, GatewayFallbackAttempt, GatewayInvokeRejectionMetadata, GatewayTraceAttempt, GatewayTraceMergedConfig, GatewayTraceRequestIds, GatewayTraceUsageSummary, ModelConfig } from './types.js';
 import type { Logxer } from '@x12i/logxer';
 import { type AiCostResult, type AiModelsCatalogClient, type CostCalculator } from '@x12i/ai-tools';
 /**
@@ -155,6 +155,10 @@ export declare function pickEffectiveModelConfigFromInvokeRequest(request: Pick<
  */
 export declare function tryExtractRouterLikePayloadFromErrorChain(error: unknown, maxDepth?: number): unknown;
 export declare function pickRequestIdsFromRouterLike(gatewayAiRequestId: string | undefined, routerLike: unknown): GatewayTraceRequestIds | undefined;
+/**
+ * Walk `error` and `error.cause` for {@link FallbackExhaustedError.attempts}.
+ */
+export declare function tryExtractFallbackAttemptsFromErrorChain(error: unknown, maxDepth?: number): GatewayFallbackAttempt[] | undefined;
 export declare function buildInvokeRejectionMetadata(args: {
     request: Pick<AIInvokeRequest, 'aiRequestId' | 'identity' | 'config' | 'modelConfig'>;
     taskTypeId: string;
@@ -162,6 +166,7 @@ export declare function buildInvokeRejectionMetadata(args: {
     mergedConfig?: unknown;
     partialRouterPayload?: unknown;
     gatewayAiRequestId?: string;
+    error?: unknown;
 }): GatewayInvokeRejectionMetadata;
 export declare function attachGatewayInvokeRejectionMetadata(err: Error, metadata: GatewayInvokeRejectionMetadata): void;
 /** Default JSON string length cap for Activix `content.fullResponse` when diagnostics allow storing it. */

package/dist/gateway-utils.js

@@ -3,6 +3,7 @@
  * Handles utility functions
  */
 import * as crypto from 'crypto';
+import { FallbackExhaustedError } from '@x12i/ai-providers-router';
 import { ModelResolutionError } from '@x12i/ai-tools';
 import { getPreParsedInstructions } from './gateway-instructions.js';
 import { getModelMaxTokensFromFlexMd } from './flex-md-loader.js';
@@ -55,6 +56,44 @@ async function substituteGatewayDefaultModel(merged, request, config, logger, me
     });
     applyGatewayDefaultToMerged(merged, defaults, config);
 }
+async function tryResolveSubstitutedDefaultModel(merged, request, config, logger, mergeOptions, original) {
+    const resolveModels = config.aiTools?.resolveModels !== false;
+    const catalog = mergeOptions?.catalog;
+    if (!resolveModels || !catalog || !merged.model) {
+        return;
+    }
+    try {
+        const resolution = await catalog.resolveModel({
+            provider: merged.provider,
+            model: merged.model
+        });
+        if (!resolution.found) {
+            return;
+        }
+        applyModelResolution(merged, resolution, config.defaultEngine);
+        request._modelResolution = {
+            modelId: resolution.modelId,
+            routedViaOpenRouter: resolution.routedViaOpenRouter,
+            confidence: resolution.confidence,
+            resolvedVia: resolution.resolvedVia,
+            originalProvider: original?.provider ?? merged.provider,
+            originalModel: original?.model ?? merged.model
+        };
+        logger.verbose('Catalog resolved substituted default model', {
+            jobId: request.identity.jobId,
+            model: merged.model,
+            provider: merged.provider,
+            resolvedModelId: resolution.modelId
+        });
+    }
+    catch {
+        // Prod keeps the substituted bare default when re-resolution fails.
+    }
+}
+async function substituteGatewayDefaultModelAndResolve(merged, request, config, logger, mergeOptions, reason, original) {
+    await substituteGatewayDefaultModel(merged, request, config, logger, mergeOptions, reason, original);
+    await tryResolveSubstitutedDefaultModel(merged, request, config, logger, mergeOptions, original);
+}
 /**
  * True when any caller-controlled config source set `maxTokens` (Optimixer should not override).
  */
@@ -137,7 +176,7 @@ export async function mergeConfig(request, config, logger, mergeOptions) {
     const originalProvider = merged.provider;
     const originalModel = explicitModel;
     if (!explicitModel) {
-        await substituteGatewayDefaultModel(merged, request, config, logger, mergeOptions, 'no_model_provided');
+        await substituteGatewayDefaultModelAndResolve(merged, request, config, logger, mergeOptions, 'no_model_provided');
     }
     else if (resolveModels && mergeOptions?.catalog) {
         try {
@@ -166,7 +205,7 @@ export async function mergeConfig(request, config, logger, mergeOptions) {
                 });
             }
             else if (isProdGatewayMode(operationalMode)) {
-                await substituteGatewayDefaultModel(merged, request, config, logger, mergeOptions, 'model_resolution_failed', { provider: originalProvider, model: originalModel });
+                await substituteGatewayDefaultModelAndResolve(merged, request, config, logger, mergeOptions, 'model_resolution_failed', { provider: originalProvider, model: originalModel });
             }
             else {
                 throw new ModelResolutionError({ provider: merged.provider, model: explicitModel }, resolution);
@@ -177,7 +216,7 @@ export async function mergeConfig(request, config, logger, mergeOptions) {
                 throw error;
             }
             if (isProdGatewayMode(operationalMode)) {
-                await substituteGatewayDefaultModel(merged, request, config, logger, mergeOptions, 'ai_tools_unavailable', { provider: originalProvider, model: originalModel });
+                await substituteGatewayDefaultModelAndResolve(merged, request, config, logger, mergeOptions, 'ai_tools_unavailable', { provider: originalProvider, model: originalModel });
             }
             else {
                 throw error;
@@ -185,10 +224,10 @@ export async function mergeConfig(request, config, logger, mergeOptions) {
         }
     }
     else if (resolveModels && !mergeOptions?.catalog && isProdGatewayMode(operationalMode)) {
-        await substituteGatewayDefaultModel(merged, request, config, logger, mergeOptions, 'ai_tools_unavailable', { provider: originalProvider, model: originalModel });
+        await substituteGatewayDefaultModelAndResolve(merged, request, config, logger, mergeOptions, 'ai_tools_unavailable', { provider: originalProvider, model: originalModel });
     }
     if (!merged.model) {
-        await substituteGatewayDefaultModel(merged, request, config, logger, mergeOptions, 'no_model_provided');
+        await substituteGatewayDefaultModelAndResolve(merged, request, config, logger, mergeOptions, 'no_model_provided');
     }
     const maxTokensExplicitlySet = isMaxTokensExplicitlySet(request, config);
     const optimixerWillPredict = config.optimixer?.enabled === true && !maxTokensExplicitlySet;
@@ -783,6 +822,46 @@ export function pickRequestIdsFromRouterLike(gatewayAiRequestId, routerLike) {
     }
     return out;
 }
+function mapRouterFallbackAttempts(attempts) {
+    return attempts.map((attempt) => ({
+        provider: String(attempt.provider),
+        ...(attempt.model !== undefined ? { model: attempt.model } : {}),
+        ...(attempt.httpStatus !== undefined ? { httpStatus: attempt.httpStatus } : {}),
+        error: attempt.error instanceof Error ? attempt.error.message : String(attempt.error),
+        ...(attempt.responsePreview !== undefined ? { responsePreview: attempt.responsePreview } : {})
+    }));
+}
+function extractFallbackAttemptsFromError(error) {
+    if (error instanceof FallbackExhaustedError && error.attempts.length > 0) {
+        return mapRouterFallbackAttempts(error.attempts);
+    }
+    if (error != null && typeof error === 'object') {
+        const record = error;
+        if (record.name === 'FallbackExhaustedError' && Array.isArray(record.attempts) && record.attempts.length > 0) {
+            return mapRouterFallbackAttempts(record.attempts);
+        }
+    }
+    return undefined;
+}
+/**
+ * Walk `error` and `error.cause` for {@link FallbackExhaustedError.attempts}.
+ */
+export function tryExtractFallbackAttemptsFromErrorChain(error, maxDepth = 8) {
+    const seen = new Set();
+    let cur = error;
+    for (let i = 0; i < maxDepth && cur != null; i++) {
+        if (typeof cur !== 'object')
+            break;
+        if (seen.has(cur))
+            break;
+        seen.add(cur);
+        const attempts = extractFallbackAttemptsFromError(cur);
+        if (attempts?.length)
+            return attempts;
+        cur = cur.cause;
+    }
+    return undefined;
+}
 export function buildInvokeRejectionMetadata(args) {
     const gid = args.gatewayAiRequestId ?? args.request.aiRequestId;
     const partial = args.partialRouterPayload;
@@ -796,6 +875,9 @@ export function buildInvokeRejectionMetadata(args) {
         tokens = undefined;
     }
     const requestIds = pickRequestIdsFromRouterLike(gid, partial);
+    const fallbackAttempts = args.error !== undefined
+        ? tryExtractFallbackAttemptsFromErrorChain(args.error)
+        : undefined;
     return {
         aiRequestId: args.request.aiRequestId,
         identity: args.request.identity,
@@ -805,6 +887,7 @@ export function buildInvokeRejectionMetadata(args) {
         ...(effective !== undefined ? { effectiveModelConfig: effective } : {}),
         ...(tokens !== undefined ? { tokens } : {}),
         ...(requestIds !== undefined ? { requestIds } : {}),
+        ...(fallbackAttempts !== undefined ? { fallbackAttempts } : {}),
         ...(mc === undefined ? { mergeConfigUnavailable: true } : {})
     };
 }

package/dist/gateway.js

@@ -17,7 +17,7 @@ import { gatewayLogDebug, withActivityIdentity } from './gateway-log-meta.js';
 import { invokeWithRetry } from './gateway-retry.js';
 /** Error message thrown by the router when no provider is registered or specified */
 const NO_PROVIDER_ERROR = 'No provider specified and no providers registered';
-const NO_PROVIDER_HINT = ' Set OPEN_ROUTER_KEY (or OPENROUTER_API_KEY) in the environment to use OpenRouter, or register a provider with the router (e.g. via autoRegisterProviders or gateway config).';
+const NO_PROVIDER_HINT = ' Set OPENROUTER_API_KEY in the environment to use OpenRouter (legacy OPEN_ROUTER_KEY is still read as fallback), or register a provider with the router (e.g. via autoRegisterProviders or gateway config).';
 /** Warn when a successful call reports no tokens and/or explicit zero cost (often missing adapter metadata). */
 function warnIfSuccessfulInvokeReportsZeroUsageOrCost(logger, identity, meta, invokeKind) {
     const { tokens, costUsd, cost } = meta;
@@ -685,7 +685,8 @@ export class AIGateway {
                 startTime,
                 mergedConfig,
                 partialRouterPayload: partial,
-                gatewayAiRequestId: request.aiRequestId
+                gatewayAiRequestId: request.aiRequestId,
+                error: err
             });
             attachGatewayInvokeRejectionMetadata(err, rejectMeta);
             if (err.message.includes(NO_PROVIDER_ERROR)) {

package/dist/index.d.ts

@@ -16,8 +16,8 @@ export * from '@x12i/ai-providers-router';
 export { AIGateway } from './gateway.js';
 export { InstructionNotFoundError, InstructionBackendError } from './instruction-errors.js';
 export { autoRegisterProviders } from './gateway-provider-auto-register.js';
-export type { GatewayConfig, ProviderModelRef, ModelConfig, RetryConfig, ChatRequest, AIInvokeRequest, AIRequest, GatewayActionType, GatewayInvokeRejectionMetadata, GatewayTraceRequestIds, GatewayTraceAttempt, GatewayTraceUsageSummary, GatewayTraceMergedConfig, EnhancedLLMResponse, InstructionMetadata, ValidationRule, TemplateRenderOptions, SmartInputConfig, SmartInputRenderOptions } from './types.js';
-export { attachGatewayInvokeRejectionMetadata, buildInvokeRejectionMetadata, tryExtractRouterLikePayloadFromErrorChain, pickRequestIdsFromRouterLike, resolveActivityCostCompletion, resolveCostCompletionForActivity, resolveCostCompletionWithAiTools, buildGatewayPricingRecord, mapAiCostResultToResolvedActivityCost, buildTraceUsageSummary, enrichTraceAttemptsWithBilling, hasNonZeroTokenUsage } from './gateway-utils.js';
+export type { GatewayConfig, ProviderModelRef, ModelConfig, RetryConfig, ChatRequest, AIInvokeRequest, AIRequest, GatewayActionType, GatewayInvokeRejectionMetadata, GatewayFallbackAttempt, GatewayTraceRequestIds, GatewayTraceAttempt, GatewayTraceUsageSummary, GatewayTraceMergedConfig, EnhancedLLMResponse, InstructionMetadata, ValidationRule, TemplateRenderOptions, SmartInputConfig, SmartInputRenderOptions } from './types.js';
+export { attachGatewayInvokeRejectionMetadata, buildInvokeRejectionMetadata, tryExtractRouterLikePayloadFromErrorChain, tryExtractFallbackAttemptsFromErrorChain, pickRequestIdsFromRouterLike, resolveActivityCostCompletion, resolveCostCompletionForActivity, resolveCostCompletionWithAiTools, buildGatewayPricingRecord, mapAiCostResultToResolvedActivityCost, buildTraceUsageSummary, enrichTraceAttemptsWithBilling, hasNonZeroTokenUsage } from './gateway-utils.js';
 export { getGatewayOperationalMode, isProdGatewayMode, resolveGatewayDefaultModel, parseModelProviderSpec, CODE_DEFAULT_MODEL } from './gateway-mode.js';
 export type { GatewayOperationalMode, GatewayDefaultModelSource, DefaultModelSubstitutionReason, ResolvedGatewayDefault } from './gateway-mode.js';
 export type { ActivityCostStatus, ResolvedActivityCost } from './gateway-utils.js';

package/dist/index.js

@@ -17,7 +17,7 @@ export * from '@x12i/ai-providers-router';
 export { AIGateway } from './gateway.js';
 export { InstructionNotFoundError, InstructionBackendError } from './instruction-errors.js';
 export { autoRegisterProviders } from './gateway-provider-auto-register.js';
-export { attachGatewayInvokeRejectionMetadata, buildInvokeRejectionMetadata, tryExtractRouterLikePayloadFromErrorChain, pickRequestIdsFromRouterLike, resolveActivityCostCompletion, resolveCostCompletionForActivity, resolveCostCompletionWithAiTools, buildGatewayPricingRecord, mapAiCostResultToResolvedActivityCost, buildTraceUsageSummary, enrichTraceAttemptsWithBilling, hasNonZeroTokenUsage } from './gateway-utils.js';
+export { attachGatewayInvokeRejectionMetadata, buildInvokeRejectionMetadata, tryExtractRouterLikePayloadFromErrorChain, tryExtractFallbackAttemptsFromErrorChain, pickRequestIdsFromRouterLike, resolveActivityCostCompletion, resolveCostCompletionForActivity, resolveCostCompletionWithAiTools, buildGatewayPricingRecord, mapAiCostResultToResolvedActivityCost, buildTraceUsageSummary, enrichTraceAttemptsWithBilling, hasNonZeroTokenUsage } from './gateway-utils.js';
 export { getGatewayOperationalMode, isProdGatewayMode, resolveGatewayDefaultModel, parseModelProviderSpec, CODE_DEFAULT_MODEL } from './gateway-mode.js';
 export { contractSpecToFieldKeys, enrichParsedContentForOutputContract, resolveOutputContractFieldKeys } from './output-contract-normalizer.js';
 export { mergeGatewayAndRequestTemplateRenderOptions, mergeTemplateRenderOptions } from './template-render-merge.js';

package/dist/types.d.ts

@@ -138,12 +138,25 @@ export type GatewayInvokeRejectionMetadata = {
     region?: string;
     effectiveModelConfig?: Partial<Pick<ModelConfig, 'model' | 'modelId' | 'provider' | 'temperature' | 'maxTokens' | 'topP'>>;
     requestIds?: GatewayTraceRequestIds;
+    /**
+     * Fallback candidates tried before exhaustion (non-trace {@link AIGateway.invoke} only).
+     * Sourced from {@link FallbackExhaustedError.attempts} on the router error chain.
+     */
+    fallbackAttempts?: GatewayFallbackAttempt[];
     /**
      * True when {@link mergeConfig} did not run (e.g. message-building threw first).
      * Routing facts may only reflect request.config / modelConfig, not flex-md defaults.
      */
     mergeConfigUnavailable?: true;
 };
+/** Serializable slice of a router fallback attempt for rejection metadata. */
+export type GatewayFallbackAttempt = {
+    provider: string;
+    model?: string;
+    httpStatus?: number;
+    error: string;
+    responsePreview?: string;
+};
 /**
  * Identity object used for activity linkage.
  * On gateway requests/responses it lives on `identity`. When activity tracking persists via Activix v5+,

package/dist-cjs/defaults/model-config.json

@@ -1,6 +1,6 @@
 {
-  "defaultEngine": "openai",
-  "defaultModel": "gpt-5-nano",
+  "defaultEngine": "openrouter",
+  "defaultModel": "cheap",
   "temperature": 0.7,
   "topP": 1.0,
   "frequencyPenalty": 0.0,
@@ -13,4 +13,3 @@
     "throttlingDelay": 5000
   }
 }
-

package/dist-cjs/gateway-config.cjs

@@ -197,7 +197,7 @@ export function initializeGatewayComponents(config) {
     // Prefer explicit config from consumer (e.g. ai-skills) to avoid env-loading timing; fall back to process.env.
     const explicitOpenRouterKey = config.openrouter?.apiKey;
     const isExplicitKey = typeof explicitOpenRouterKey === 'string' && !explicitOpenRouterKey.startsWith('ENV.');
-    const openRouterKey = isExplicitKey ? explicitOpenRouterKey : (process.env.OPEN_ROUTER_KEY ?? process.env.OPENROUTER_API_KEY);
+    const openRouterKey = isExplicitKey ? explicitOpenRouterKey : (process.env.OPENROUTER_API_KEY ?? process.env.OPEN_ROUTER_KEY);
     const useOpenRouter = config.openRouter?.enabled !== undefined ? config.openRouter?.enabled : process.env.USE_OPENROUTER;
     if (openRouterKey && useOpenRouter !== false && useOpenRouter !== 'false') {
         routerConfig.openRouter = { enabled: true };

package/dist-cjs/gateway-meta.cjs

@@ -2,6 +2,7 @@
  * Gateway Meta Operations Module
  * Handles meta operations like instruction optimization and testing
  */
+import { CODE_DEFAULT_MODEL } from './gateway-mode.js';
 /**
  * Test instructions by running them and analyzing the response
  */
@@ -9,7 +10,7 @@ export async function testInstructions(instructions, testInput, expectedSchema,
     // Get internal system action config (instruction audit)
     const internalConfig = config.internalSystemActions?.instructionAudit;
     const defaultEngine = config.defaultEngine || 'openai';
-    const defaultModel = internalConfig?.model || 'gpt-5-nano';
+    const defaultModel = internalConfig?.model || CODE_DEFAULT_MODEL;
     const defaultProvider = internalConfig?.engine || defaultEngine;
     const { agentId = 'instruction-tester', model = options.model || defaultModel, // Use internal config default if not provided
     provider = options.provider || defaultProvider // Use internal config default if not provided

package/dist-cjs/gateway-mode.cjs

@@ -2,7 +2,8 @@
  * Gateway operational mode (prod vs dev/debug) and default model resolution.
  */
 import { gatewayLogDebug, withActivityIdentity } from './gateway-log-meta.js';
-export const CODE_DEFAULT_MODEL = 'gpt-5-nano';
+/** Profile name resolved via ai-tools + {@link @x12i/ai-profiles} when catalog is enabled. */
+export const CODE_DEFAULT_MODEL = 'cheap';
 /**
  * Operational mode: `GatewayConfig.mode` overrides `process.env.mode` / `MODE`.
  * Only `prod` allows silent default-model substitution; all other values are strict.

package/dist-cjs/gateway-mode.d.ts

@@ -6,7 +6,8 @@ import type { ActivityIdentity, GatewayConfig } from './types.js';
 export type GatewayOperationalMode = 'prod' | 'debug' | 'dev';
 export type GatewayDefaultModelSource = 'env' | 'model-config.json' | 'code';
 export type DefaultModelSubstitutionReason = 'no_model_provided' | 'model_resolution_failed' | 'ai_tools_unavailable';
-export declare const CODE_DEFAULT_MODEL = "gpt-5-nano";
+/** Profile name resolved via ai-tools + {@link @x12i/ai-profiles} when catalog is enabled. */
+export declare const CODE_DEFAULT_MODEL = "cheap";
 export type ResolvedGatewayDefault = {
     model: string;
     provider?: string;

package/dist-cjs/gateway-provider-auto-register.cjs

@@ -146,7 +146,7 @@ export async function autoRegisterProviders(router, logger) {
             optionalEnvVars: PROVIDER_CONFIGS
                 .filter(p => p.optional)
                 .map(p => p.envVar),
-            openRouter: 'Set OPEN_ROUTER_KEY or OPENROUTER_API_KEY (and do not set USE_OPENROUTER=false) to use OpenRouter without registering a provider.',
+            openRouter: 'Set OPENROUTER_API_KEY (and do not set USE_OPENROUTER=false) to use OpenRouter without registering a provider. Legacy OPEN_ROUTER_KEY is still accepted.',
             note: 'You can still manually register providers using gateway.register(provider)'
         });
     }

package/dist-cjs/gateway-utils.cjs

@@ -3,6 +3,7 @@
  * Handles utility functions
  */
 import * as crypto from 'crypto';
+import { FallbackExhaustedError } from '@x12i/ai-providers-router';
 import { ModelResolutionError } from '@x12i/ai-tools';
 import { getPreParsedInstructions } from './gateway-instructions.js';
 import { getModelMaxTokensFromFlexMd } from './flex-md-loader.js';
@@ -55,6 +56,44 @@ async function substituteGatewayDefaultModel(merged, request, config, logger, me
     });
     applyGatewayDefaultToMerged(merged, defaults, config);
 }
+async function tryResolveSubstitutedDefaultModel(merged, request, config, logger, mergeOptions, original) {
+    const resolveModels = config.aiTools?.resolveModels !== false;
+    const catalog = mergeOptions?.catalog;
+    if (!resolveModels || !catalog || !merged.model) {
+        return;
+    }
+    try {
+        const resolution = await catalog.resolveModel({
+            provider: merged.provider,
+            model: merged.model
+        });
+        if (!resolution.found) {
+            return;
+        }
+        applyModelResolution(merged, resolution, config.defaultEngine);
+        request._modelResolution = {
+            modelId: resolution.modelId,
+            routedViaOpenRouter: resolution.routedViaOpenRouter,
+            confidence: resolution.confidence,
+            resolvedVia: resolution.resolvedVia,
+            originalProvider: original?.provider ?? merged.provider,
+            originalModel: original?.model ?? merged.model
+        };
+        logger.verbose('Catalog resolved substituted default model', {
+            jobId: request.identity.jobId,
+            model: merged.model,
+            provider: merged.provider,
+            resolvedModelId: resolution.modelId
+        });
+    }
+    catch {
+        // Prod keeps the substituted bare default when re-resolution fails.
+    }
+}
+async function substituteGatewayDefaultModelAndResolve(merged, request, config, logger, mergeOptions, reason, original) {
+    await substituteGatewayDefaultModel(merged, request, config, logger, mergeOptions, reason, original);
+    await tryResolveSubstitutedDefaultModel(merged, request, config, logger, mergeOptions, original);
+}
 /**
  * True when any caller-controlled config source set `maxTokens` (Optimixer should not override).
  */
@@ -137,7 +176,7 @@ export async function mergeConfig(request, config, logger, mergeOptions) {
     const originalProvider = merged.provider;
     const originalModel = explicitModel;
     if (!explicitModel) {
-        await substituteGatewayDefaultModel(merged, request, config, logger, mergeOptions, 'no_model_provided');
+        await substituteGatewayDefaultModelAndResolve(merged, request, config, logger, mergeOptions, 'no_model_provided');
     }
     else if (resolveModels && mergeOptions?.catalog) {
         try {
@@ -166,7 +205,7 @@ export async function mergeConfig(request, config, logger, mergeOptions) {
                 });
             }
             else if (isProdGatewayMode(operationalMode)) {
-                await substituteGatewayDefaultModel(merged, request, config, logger, mergeOptions, 'model_resolution_failed', { provider: originalProvider, model: originalModel });
+                await substituteGatewayDefaultModelAndResolve(merged, request, config, logger, mergeOptions, 'model_resolution_failed', { provider: originalProvider, model: originalModel });
             }
             else {
                 throw new ModelResolutionError({ provider: merged.provider, model: explicitModel }, resolution);
@@ -177,7 +216,7 @@ export async function mergeConfig(request, config, logger, mergeOptions) {
                 throw error;
             }
             if (isProdGatewayMode(operationalMode)) {
-                await substituteGatewayDefaultModel(merged, request, config, logger, mergeOptions, 'ai_tools_unavailable', { provider: originalProvider, model: originalModel });
+                await substituteGatewayDefaultModelAndResolve(merged, request, config, logger, mergeOptions, 'ai_tools_unavailable', { provider: originalProvider, model: originalModel });
             }
             else {
                 throw error;
@@ -185,10 +224,10 @@ export async function mergeConfig(request, config, logger, mergeOptions) {
         }
     }
     else if (resolveModels && !mergeOptions?.catalog && isProdGatewayMode(operationalMode)) {
-        await substituteGatewayDefaultModel(merged, request, config, logger, mergeOptions, 'ai_tools_unavailable', { provider: originalProvider, model: originalModel });
+        await substituteGatewayDefaultModelAndResolve(merged, request, config, logger, mergeOptions, 'ai_tools_unavailable', { provider: originalProvider, model: originalModel });
     }
     if (!merged.model) {
-        await substituteGatewayDefaultModel(merged, request, config, logger, mergeOptions, 'no_model_provided');
+        await substituteGatewayDefaultModelAndResolve(merged, request, config, logger, mergeOptions, 'no_model_provided');
     }
     const maxTokensExplicitlySet = isMaxTokensExplicitlySet(request, config);
     const optimixerWillPredict = config.optimixer?.enabled === true && !maxTokensExplicitlySet;
@@ -783,6 +822,46 @@ export function pickRequestIdsFromRouterLike(gatewayAiRequestId, routerLike) {
     }
     return out;
 }
+function mapRouterFallbackAttempts(attempts) {
+    return attempts.map((attempt) => ({
+        provider: String(attempt.provider),
+        ...(attempt.model !== undefined ? { model: attempt.model } : {}),
+        ...(attempt.httpStatus !== undefined ? { httpStatus: attempt.httpStatus } : {}),
+        error: attempt.error instanceof Error ? attempt.error.message : String(attempt.error),
+        ...(attempt.responsePreview !== undefined ? { responsePreview: attempt.responsePreview } : {})
+    }));
+}
+function extractFallbackAttemptsFromError(error) {
+    if (error instanceof FallbackExhaustedError && error.attempts.length > 0) {
+        return mapRouterFallbackAttempts(error.attempts);
+    }
+    if (error != null && typeof error === 'object') {
+        const record = error;
+        if (record.name === 'FallbackExhaustedError' && Array.isArray(record.attempts) && record.attempts.length > 0) {
+            return mapRouterFallbackAttempts(record.attempts);
+        }
+    }
+    return undefined;
+}
+/**
+ * Walk `error` and `error.cause` for {@link FallbackExhaustedError.attempts}.
+ */
+export function tryExtractFallbackAttemptsFromErrorChain(error, maxDepth = 8) {
+    const seen = new Set();
+    let cur = error;
+    for (let i = 0; i < maxDepth && cur != null; i++) {
+        if (typeof cur !== 'object')
+            break;
+        if (seen.has(cur))
+            break;
+        seen.add(cur);
+        const attempts = extractFallbackAttemptsFromError(cur);
+        if (attempts?.length)
+            return attempts;
+        cur = cur.cause;
+    }
+    return undefined;
+}
 export function buildInvokeRejectionMetadata(args) {
     const gid = args.gatewayAiRequestId ?? args.request.aiRequestId;
     const partial = args.partialRouterPayload;
@@ -796,6 +875,9 @@ export function buildInvokeRejectionMetadata(args) {
         tokens = undefined;
     }
     const requestIds = pickRequestIdsFromRouterLike(gid, partial);
+    const fallbackAttempts = args.error !== undefined
+        ? tryExtractFallbackAttemptsFromErrorChain(args.error)
+        : undefined;
     return {
         aiRequestId: args.request.aiRequestId,
         identity: args.request.identity,
@@ -805,6 +887,7 @@ export function buildInvokeRejectionMetadata(args) {
         ...(effective !== undefined ? { effectiveModelConfig: effective } : {}),
         ...(tokens !== undefined ? { tokens } : {}),
         ...(requestIds !== undefined ? { requestIds } : {}),
+        ...(fallbackAttempts !== undefined ? { fallbackAttempts } : {}),
         ...(mc === undefined ? { mergeConfigUnavailable: true } : {})
     };
 }

package/dist-cjs/gateway-utils.d.ts

@@ -2,7 +2,7 @@
  * Gateway Utilities Module
  * Handles utility functions
  */
-import type { AIInvokeRequest, ChatRequest, GatewayConfig, GatewayInvokeRejectionMetadata, GatewayTraceAttempt, GatewayTraceMergedConfig, GatewayTraceRequestIds, GatewayTraceUsageSummary, ModelConfig } from './types.js';
+import type { AIInvokeRequest, ChatRequest, GatewayConfig, GatewayFallbackAttempt, GatewayInvokeRejectionMetadata, GatewayTraceAttempt, GatewayTraceMergedConfig, GatewayTraceRequestIds, GatewayTraceUsageSummary, ModelConfig } from './types.js';
 import type { Logxer } from '@x12i/logxer';
 import { type AiCostResult, type AiModelsCatalogClient, type CostCalculator } from '@x12i/ai-tools';
 /**
@@ -155,6 +155,10 @@ export declare function pickEffectiveModelConfigFromInvokeRequest(request: Pick<
  */
 export declare function tryExtractRouterLikePayloadFromErrorChain(error: unknown, maxDepth?: number): unknown;
 export declare function pickRequestIdsFromRouterLike(gatewayAiRequestId: string | undefined, routerLike: unknown): GatewayTraceRequestIds | undefined;
+/**
+ * Walk `error` and `error.cause` for {@link FallbackExhaustedError.attempts}.
+ */
+export declare function tryExtractFallbackAttemptsFromErrorChain(error: unknown, maxDepth?: number): GatewayFallbackAttempt[] | undefined;
 export declare function buildInvokeRejectionMetadata(args: {
     request: Pick<AIInvokeRequest, 'aiRequestId' | 'identity' | 'config' | 'modelConfig'>;
     taskTypeId: string;
@@ -162,6 +166,7 @@ export declare function buildInvokeRejectionMetadata(args: {
     mergedConfig?: unknown;
     partialRouterPayload?: unknown;
     gatewayAiRequestId?: string;
+    error?: unknown;
 }): GatewayInvokeRejectionMetadata;
 export declare function attachGatewayInvokeRejectionMetadata(err: Error, metadata: GatewayInvokeRejectionMetadata): void;
 /** Default JSON string length cap for Activix `content.fullResponse` when diagnostics allow storing it. */

package/dist-cjs/gateway.cjs

@@ -17,7 +17,7 @@ import { gatewayLogDebug, withActivityIdentity } from './gateway-log-meta.js';
 import { invokeWithRetry } from './gateway-retry.js';
 /** Error message thrown by the router when no provider is registered or specified */
 const NO_PROVIDER_ERROR = 'No provider specified and no providers registered';
-const NO_PROVIDER_HINT = ' Set OPEN_ROUTER_KEY (or OPENROUTER_API_KEY) in the environment to use OpenRouter, or register a provider with the router (e.g. via autoRegisterProviders or gateway config).';
+const NO_PROVIDER_HINT = ' Set OPENROUTER_API_KEY in the environment to use OpenRouter (legacy OPEN_ROUTER_KEY is still read as fallback), or register a provider with the router (e.g. via autoRegisterProviders or gateway config).';
 /** Warn when a successful call reports no tokens and/or explicit zero cost (often missing adapter metadata). */
 function warnIfSuccessfulInvokeReportsZeroUsageOrCost(logger, identity, meta, invokeKind) {
     const { tokens, costUsd, cost } = meta;
@@ -685,7 +685,8 @@ export class AIGateway {
                 startTime,
                 mergedConfig,
                 partialRouterPayload: partial,
-                gatewayAiRequestId: request.aiRequestId
+                gatewayAiRequestId: request.aiRequestId,
+                error: err
             });
             attachGatewayInvokeRejectionMetadata(err, rejectMeta);
             if (err.message.includes(NO_PROVIDER_ERROR)) {

package/dist-cjs/index.cjs

@@ -17,7 +17,7 @@ export * from '@x12i/ai-providers-router';
 export { AIGateway } from './gateway.js';
 export { InstructionNotFoundError, InstructionBackendError } from './instruction-errors.js';
 export { autoRegisterProviders } from './gateway-provider-auto-register.js';
-export { attachGatewayInvokeRejectionMetadata, buildInvokeRejectionMetadata, tryExtractRouterLikePayloadFromErrorChain, pickRequestIdsFromRouterLike, resolveActivityCostCompletion, resolveCostCompletionForActivity, resolveCostCompletionWithAiTools, buildGatewayPricingRecord, mapAiCostResultToResolvedActivityCost, buildTraceUsageSummary, enrichTraceAttemptsWithBilling, hasNonZeroTokenUsage } from './gateway-utils.js';
+export { attachGatewayInvokeRejectionMetadata, buildInvokeRejectionMetadata, tryExtractRouterLikePayloadFromErrorChain, tryExtractFallbackAttemptsFromErrorChain, pickRequestIdsFromRouterLike, resolveActivityCostCompletion, resolveCostCompletionForActivity, resolveCostCompletionWithAiTools, buildGatewayPricingRecord, mapAiCostResultToResolvedActivityCost, buildTraceUsageSummary, enrichTraceAttemptsWithBilling, hasNonZeroTokenUsage } from './gateway-utils.js';
 export { getGatewayOperationalMode, isProdGatewayMode, resolveGatewayDefaultModel, parseModelProviderSpec, CODE_DEFAULT_MODEL } from './gateway-mode.js';
 export { contractSpecToFieldKeys, enrichParsedContentForOutputContract, resolveOutputContractFieldKeys } from './output-contract-normalizer.js';
 export { mergeGatewayAndRequestTemplateRenderOptions, mergeTemplateRenderOptions } from './template-render-merge.js';

package/dist-cjs/index.d.ts

@@ -16,8 +16,8 @@ export * from '@x12i/ai-providers-router';
 export { AIGateway } from './gateway.js';
 export { InstructionNotFoundError, InstructionBackendError } from './instruction-errors.js';
 export { autoRegisterProviders } from './gateway-provider-auto-register.js';
-export type { GatewayConfig, ProviderModelRef, ModelConfig, RetryConfig, ChatRequest, AIInvokeRequest, AIRequest, GatewayActionType, GatewayInvokeRejectionMetadata, GatewayTraceRequestIds, GatewayTraceAttempt, GatewayTraceUsageSummary, GatewayTraceMergedConfig, EnhancedLLMResponse, InstructionMetadata, ValidationRule, TemplateRenderOptions, SmartInputConfig, SmartInputRenderOptions } from './types.js';
-export { attachGatewayInvokeRejectionMetadata, buildInvokeRejectionMetadata, tryExtractRouterLikePayloadFromErrorChain, pickRequestIdsFromRouterLike, resolveActivityCostCompletion, resolveCostCompletionForActivity, resolveCostCompletionWithAiTools, buildGatewayPricingRecord, mapAiCostResultToResolvedActivityCost, buildTraceUsageSummary, enrichTraceAttemptsWithBilling, hasNonZeroTokenUsage } from './gateway-utils.js';
+export type { GatewayConfig, ProviderModelRef, ModelConfig, RetryConfig, ChatRequest, AIInvokeRequest, AIRequest, GatewayActionType, GatewayInvokeRejectionMetadata, GatewayFallbackAttempt, GatewayTraceRequestIds, GatewayTraceAttempt, GatewayTraceUsageSummary, GatewayTraceMergedConfig, EnhancedLLMResponse, InstructionMetadata, ValidationRule, TemplateRenderOptions, SmartInputConfig, SmartInputRenderOptions } from './types.js';
+export { attachGatewayInvokeRejectionMetadata, buildInvokeRejectionMetadata, tryExtractRouterLikePayloadFromErrorChain, tryExtractFallbackAttemptsFromErrorChain, pickRequestIdsFromRouterLike, resolveActivityCostCompletion, resolveCostCompletionForActivity, resolveCostCompletionWithAiTools, buildGatewayPricingRecord, mapAiCostResultToResolvedActivityCost, buildTraceUsageSummary, enrichTraceAttemptsWithBilling, hasNonZeroTokenUsage } from './gateway-utils.js';
 export { getGatewayOperationalMode, isProdGatewayMode, resolveGatewayDefaultModel, parseModelProviderSpec, CODE_DEFAULT_MODEL } from './gateway-mode.js';
 export type { GatewayOperationalMode, GatewayDefaultModelSource, DefaultModelSubstitutionReason, ResolvedGatewayDefault } from './gateway-mode.js';
 export type { ActivityCostStatus, ResolvedActivityCost } from './gateway-utils.js';

package/dist-cjs/types.d.ts

@@ -138,12 +138,25 @@ export type GatewayInvokeRejectionMetadata = {
     region?: string;
     effectiveModelConfig?: Partial<Pick<ModelConfig, 'model' | 'modelId' | 'provider' | 'temperature' | 'maxTokens' | 'topP'>>;
     requestIds?: GatewayTraceRequestIds;
+    /**
+     * Fallback candidates tried before exhaustion (non-trace {@link AIGateway.invoke} only).
+     * Sourced from {@link FallbackExhaustedError.attempts} on the router error chain.
+     */
+    fallbackAttempts?: GatewayFallbackAttempt[];
     /**
      * True when {@link mergeConfig} did not run (e.g. message-building threw first).
      * Routing facts may only reflect request.config / modelConfig, not flex-md defaults.
      */
     mergeConfigUnavailable?: true;
 };
+/** Serializable slice of a router fallback attempt for rejection metadata. */
+export type GatewayFallbackAttempt = {
+    provider: string;
+    model?: string;
+    httpStatus?: number;
+    error: string;
+    responsePreview?: string;
+};
 /**
  * Identity object used for activity linkage.
  * On gateway requests/responses it lives on `identity`. When activity tracking persists via Activix v5+,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x12i/ai-gateway",
-  "version": "9.5.3",
+  "version": "9.6.0",
   "description": "AI Gateway - Unified interface for LLM provider routing and management",
   "type": "module",
   "exports": {
@@ -41,9 +41,9 @@
   "author": "x12i",
   "license": "mit",
   "dependencies": {
-    "@x12i/activix": "^8.0.0",
-    "@x12i/ai-providers-router": "^4.8.0",
-    "@x12i/ai-tools": "^2.0.0",
+    "@x12i/activix": "^8.0.5",
+    "@x12i/ai-providers-router": "^4.8.5",
+    "@x12i/ai-tools": "^2.0.4",
     "@x12i/flex-md": "^4.8.0",
     "@x12i/logxer": "^4.3.5",
     "@x12i/optimixer": "^0.1.0",