@x12i/ai-gateway 9.5.3 → 9.6.1

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,39 @@ 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;
+/** Error code hint when a bundled profile name cannot be routed to a catalog target. */
+export declare const MODEL_PROFILE_UNROUTABLE = "MODEL_PROFILE_UNROUTABLE";
+export declare class ModelProfileUnroutableError extends Error {
+    readonly profileAlias: string;
+    readonly provider: string | undefined;
+    readonly code = "MODEL_PROFILE_UNROUTABLE";
+    constructor(profileAlias: string, provider: string | undefined, cause?: unknown);
+}
+type ModelResolutionCandidate = {
+    provider: string;
+    model: string;
+};
+/**
+ * Build rejection-metadata fallback attempts from trace-mode {@link GatewayTraceAttempt}s.
+ */
+export declare function buildGatewayFallbackAttemptsFromTrace(traceAttempts: GatewayTraceAttempt[], candidates: ModelResolutionCandidate[], lastError?: Error): GatewayFallbackAttempt[];
+/** Human-readable exhaustion message for trace fallback chains and rejection logs. */
+export declare function formatFallbackExhaustionMessage(attempts: GatewayFallbackAttempt[], candidates: ModelResolutionCandidate[]): string;
+export declare function mapGatewayFallbackAttemptsToRouter(attempts: GatewayFallbackAttempt[]): Array<{
+    provider: string;
+    model?: string;
+    httpStatus?: number;
+    error: Error;
+    responsePreview?: string;
+}>;
+/**
+ * Log profile alias vs OpenRouter model id actually sent to the router after catalog resolution.
+ */
+export declare function logResolvedModelRouting(logger: Logxer, request: ChatRequest, mergedConfig: ChatRequest['config']): void;
+/**
+ * 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 +195,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,7 +3,10 @@
  * Handles utility functions
  */
 import * as crypto from 'crypto';
-import { ModelResolutionError } from '@x12i/ai-tools';
+import { FallbackExhaustedError } from '@x12i/ai-providers-router';
+import { ModelResolutionError, isKnownProfileOrShortcut } from '@x12i/ai-tools';
+import { extractHttpStatusCode } from './gateway-retry.js';
+import { gatewayLogDebug, withActivityIdentity } from './gateway-log-meta.js';
 import { getPreParsedInstructions } from './gateway-instructions.js';
 import { getModelMaxTokensFromFlexMd } from './flex-md-loader.js';
 import { applyModelResolution } from './ai-tools-client.js';
@@ -55,6 +58,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 +178,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,10 +207,10 @@ 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);
+                throw buildModelResolutionFailureError(explicitModel, merged.provider, resolution);
             }
         }
         catch (error) {
@@ -177,7 +218,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 +226,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 +824,162 @@ export function pickRequestIdsFromRouterLike(gatewayAiRequestId, routerLike) {
     }
     return out;
 }
+/** Error code hint when a bundled profile name cannot be routed to a catalog target. */
+export const MODEL_PROFILE_UNROUTABLE = 'MODEL_PROFILE_UNROUTABLE';
+export class ModelProfileUnroutableError extends Error {
+    profileAlias;
+    provider;
+    code = MODEL_PROFILE_UNROUTABLE;
+    constructor(profileAlias, provider, cause) {
+        super(`${MODEL_PROFILE_UNROUTABLE}: profile "${profileAlias}" is retired or has no routable catalog target` +
+            (provider ? ` (provider: "${provider}")` : '') +
+            '. Update @x12i/ai-profiles or choose another profile alias.');
+        this.profileAlias = profileAlias;
+        this.provider = provider;
+        this.name = 'ModelProfileUnroutableError';
+        if (cause !== undefined) {
+            this.cause = cause;
+        }
+    }
+}
+function buildModelResolutionFailureError(explicitModel, provider, resolution) {
+    const base = new ModelResolutionError({ provider, model: explicitModel }, resolution);
+    if (isKnownProfileOrShortcut(explicitModel)) {
+        return new ModelProfileUnroutableError(explicitModel, provider, base);
+    }
+    return base;
+}
+/**
+ * Build rejection-metadata fallback attempts from trace-mode {@link GatewayTraceAttempt}s.
+ */
+export function buildGatewayFallbackAttemptsFromTrace(traceAttempts, candidates, lastError) {
+    const lastFailedByIndex = new Map();
+    for (const attempt of traceAttempts) {
+        if (!attempt.ok) {
+            lastFailedByIndex.set(attempt.routing.fallbackIndex, attempt);
+        }
+    }
+    return candidates.map((candidate, index) => {
+        const failed = lastFailedByIndex.get(index);
+        const errMsg = failed?.error?.message ??
+            (index === candidates.length - 1 && lastError ? lastError.message : 'invoke failed');
+        const httpStatus = extractHttpStatusCode(new Error(errMsg));
+        let responsePreview;
+        const raw = failed?.rawProviderPayload;
+        if (raw !== undefined) {
+            try {
+                const rawStr = typeof raw === 'string' ? raw : JSON.stringify(raw);
+                responsePreview = rawStr.length <= 500 ? rawStr : rawStr.slice(0, 500) + '…';
+            }
+            catch {
+                responsePreview = '[Unserializable]';
+            }
+        }
+        return {
+            provider: candidate.provider,
+            model: candidate.model,
+            ...(httpStatus !== undefined ? { httpStatus } : {}),
+            error: errMsg,
+            ...(responsePreview !== undefined ? { responsePreview } : {})
+        };
+    });
+}
+/** Human-readable exhaustion message for trace fallback chains and rejection logs. */
+export function formatFallbackExhaustionMessage(attempts, candidates) {
+    const providersTried = [...new Set(candidates.map((c) => c.provider))];
+    const providerNote = providersTried.length > 1
+        ? `; providers tried: ${providersTried.join(' → ')}`
+        : providersTried.length === 1
+            ? `; provider: ${providersTried[0]}`
+            : '';
+    const detail = attempts
+        .map((a) => {
+        const model = a.model ? `${a.provider}/${a.model}` : a.provider;
+        const status = a.httpStatus !== undefined ? ` HTTP ${a.httpStatus}` : '';
+        const preview = a.responsePreview ? ` body=${a.responsePreview}` : '';
+        return `[${model}${status}] ${a.error}${preview}`;
+    })
+        .join('; ');
+    const last = attempts[attempts.length - 1];
+    const lastBody = last?.responsePreview && !detail.includes(last.responsePreview)
+        ? ` Last response preview: ${last.responsePreview}`
+        : '';
+    return (`All fallback candidates failed (${candidates.length} tried${providerNote}). ` +
+        `Attempts: ${detail || 'no attempt details recorded'}.${lastBody}`);
+}
+export function mapGatewayFallbackAttemptsToRouter(attempts) {
+    return attempts.map((a) => ({
+        provider: a.provider,
+        model: a.model,
+        httpStatus: a.httpStatus,
+        error: new Error(a.error),
+        responsePreview: a.responsePreview
+    }));
+}
+/**
+ * Log profile alias vs OpenRouter model id actually sent to the router after catalog resolution.
+ */
+export function logResolvedModelRouting(logger, request, mergedConfig) {
+    const res = request._modelResolution;
+    if (!res?.modelId && res?.originalModel === undefined) {
+        return;
+    }
+    const profileAlias = res.originalModel ?? mergedConfig?.model;
+    const invokedModelId = res.modelId ?? mergedConfig?.model;
+    const provider = mergedConfig?.provider;
+    const openRouterPath = res.routedViaOpenRouter === true || provider === 'openrouter';
+    if (!openRouterPath) {
+        return;
+    }
+    logger.info('OpenRouter routing: profile alias resolved to model id for invoke', withActivityIdentity(request.identity, {
+        profileAlias,
+        invokedOpenRouterModelId: invokedModelId,
+        provider,
+        routedViaOpenRouter: res.routedViaOpenRouter,
+        resolvedVia: res.resolvedVia,
+        debugKind: gatewayLogDebug.trace
+    }));
+}
+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 +993,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 +1005,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

@@ -3,13 +3,14 @@
  *
  * Simplified AI Gateway - Clean proxy implementation
  */
+import { FallbackExhaustedError } from '@x12i/ai-providers-router';
 import { validateChatRequest, validateAIRequest } from './gateway-validation.js';
 import { ensureGatewayRequestIdentity } from './activity-manager.js';
 import { initializeGatewayComponents } from './gateway-config.js';
 import { buildMessages } from './message-builder.js';
 import { extractJsonFromFlexMd, getModelMaxTokensFromFlexMd } from './flex-md-loader.js';
 import { enrichParsedContentForOutputContract, resolveOutputContractFieldKeys } from './output-contract-normalizer.js';
-import { attachGatewayInvokeRejectionMetadata, buildInvokeRejectionMetadata, capActivityFullResponsePayload, DEFAULT_ACTIVITY_FULL_RESPONSE_MAX_CHARS, extractCostUsdFromRouterResponse, extractTokenUsageFromRouterResponse, mergeConfig, pickEffectiveModelConfigForMetadata, pickInvokeRoutingMetadataSlice, pickTraceMergedRouterConfig, resolveCostCompletionWithAiTools, buildOptimixerActualUsage, buildTraceUsageSummary, enrichTraceAttemptsWithBilling, isMaxTokensExplicitlySet, tryExtractRouterLikePayloadFromErrorChain } from './gateway-utils.js';
+import { attachGatewayInvokeRejectionMetadata, buildGatewayFallbackAttemptsFromTrace, buildInvokeRejectionMetadata, capActivityFullResponsePayload, formatFallbackExhaustionMessage, logResolvedModelRouting, mapGatewayFallbackAttemptsToRouter, hasNonZeroTokenUsage, DEFAULT_ACTIVITY_FULL_RESPONSE_MAX_CHARS, extractCostUsdFromRouterResponse, extractTokenUsageFromRouterResponse, mergeConfig, pickEffectiveModelConfigForMetadata, pickInvokeRoutingMetadataSlice, pickTraceMergedRouterConfig, resolveCostCompletionWithAiTools, buildOptimixerActualUsage, buildTraceUsageSummary, enrichTraceAttemptsWithBilling, isMaxTokensExplicitlySet, tryExtractRouterLikePayloadFromErrorChain } from './gateway-utils.js';
 import { getAiToolsClient } from './ai-tools-client.js';
 import { autoRegisterProviders } from './gateway-provider-auto-register.js';
 import { setGatewayLastJobId, setGatewayRuntimeClients } from './runtime-objects.js';
@@ -17,7 +18,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;
@@ -277,6 +278,7 @@ export class AIGateway {
             catalog: aiTools?.catalog ?? null
         });
         request._mergedRouterConfig = mergedConfig;
+        logResolvedModelRouting(this.logger, request, mergedConfig);
         const diagnosticsMode = request.diagnostics?.mode;
         const traceEnabled = diagnosticsMode === 'trace';
         const includeRawProviderPayload = request.diagnostics?.includeRawProviderPayload === true;
@@ -468,7 +470,20 @@ export class AIGateway {
                     }
                 }
                 if (!response) {
-                    throw lastError ?? new Error('All fallback candidates failed');
+                    const fallbackAttempts = buildGatewayFallbackAttemptsFromTrace(traceAttempts, deduped, lastError);
+                    const providersTried = [...new Set(deduped.map((c) => c.provider))];
+                    this.logger.error('Trace fallback chain exhausted', withActivityIdentity(request.identity, {
+                        providersTried,
+                        candidates: deduped,
+                        fallbackAttempts,
+                        debugKind: gatewayLogDebug.anomaly
+                    }));
+                    const exhausted = new FallbackExhaustedError(mapGatewayFallbackAttemptsToRouter(fallbackAttempts));
+                    exhausted.message = formatFallbackExhaustionMessage(fallbackAttempts, deduped);
+                    if (lastError) {
+                        exhausted.cause = lastError;
+                    }
+                    throw exhausted;
                 }
                 // Summary counts + final request ids.
                 traceRetryCount = traceAttempts.filter(a => a.routing.retryIndex > 0).length;
@@ -565,11 +580,14 @@ export class AIGateway {
                         tokens = second;
                 }
             }
-            const costCompletion = await resolveCostCompletionWithAiTools(routerResponse, tokens, {
+            let costCompletion = await resolveCostCompletionWithAiTools(routerResponse, tokens, {
                 mergedConfig,
                 calculator: aiTools?.calculator ?? null,
                 calculateCost: this.config.aiTools?.calculateCost
             });
+            if (!costCompletion.costStatus && hasNonZeroTokenUsage(tokens)) {
+                costCompletion = { ...costCompletion, costStatus: 'unpriced' };
+            }
             const routerMetaForCost = routerResponse?.metadata || {};
             const routingMetadataSlice = pickInvokeRoutingMetadataSlice(routerResponse, mergedConfig);
             const effectiveModelConfig = pickEffectiveModelConfigForMetadata(mergedConfig);
@@ -685,7 +703,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, MODEL_PROFILE_UNROUTABLE, ModelProfileUnroutableError, buildGatewayFallbackAttemptsFromTrace, formatFallbackExhaustionMessage, logResolvedModelRouting, mapGatewayFallbackAttemptsToRouter } 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, MODEL_PROFILE_UNROUTABLE, ModelProfileUnroutableError, buildGatewayFallbackAttemptsFromTrace, formatFallbackExhaustionMessage, logResolvedModelRouting, mapGatewayFallbackAttemptsToRouter } 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/optimixer-manager.js

@@ -1,14 +1,15 @@
 import { Optimixer } from '@x12i/optimixer';
 import { resolveActivityTrackingConfig } from './config/activity-tracking-config.js';
 import { estimateMessagesTokenSizes } from './token-estimate.js';
-function resolveActionTypeId(request) {
+/** Optimixer bucket key: prefer taskTypeId (template), then identity actionType, else gateway default. */
+function resolveTemplateId(request) {
+    if (request.taskTypeId && String(request.taskTypeId).trim()) {
+        return String(request.taskTypeId).trim();
+    }
     const identity = request.identity;
     if (identity?.actionType && String(identity.actionType).trim()) {
         return String(identity.actionType).trim();
     }
-    if (request.taskTypeId && String(request.taskTypeId).trim()) {
-        return String(request.taskTypeId).trim();
-    }
     return 'gateway.invoke';
 }
 function toActivixRunContext(identity) {
@@ -77,15 +78,18 @@ export class OptimixerManager {
         const { request, mergedConfig, messages } = ctx;
         const { inputSize, contextSize } = estimateMessagesTokenSizes(messages);
         const acceptableRisk = this.config?.acceptableRisk ?? 'medium';
+        const provider = typeof mergedConfig?.provider === 'string' ? mergedConfig.provider : undefined;
+        const model = typeof mergedConfig?.model === 'string' ? mergedConfig.model : undefined;
         try {
             return await optimixer.predictAiMaxTokens({
-                actionTypeId: resolveActionTypeId(request),
+                templateId: resolveTemplateId(request),
                 inputSize,
                 contextSize,
                 acceptableRisk,
                 runContext: toActivixRunContext(request.identity),
-                provider: typeof mergedConfig?.provider === 'string' ? mergedConfig.provider : undefined,
-                model: typeof mergedConfig?.model === 'string' ? mergedConfig.model : undefined
+                ...(provider || model
+                    ? { modelProfile: { ...(provider ? { provider } : {}), ...(model ? { model } : {}) } }
+                    : {})
             });
         }
         catch (error) {

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,7 +3,10 @@
  * Handles utility functions
  */
 import * as crypto from 'crypto';
-import { ModelResolutionError } from '@x12i/ai-tools';
+import { FallbackExhaustedError } from '@x12i/ai-providers-router';
+import { ModelResolutionError, isKnownProfileOrShortcut } from '@x12i/ai-tools';
+import { extractHttpStatusCode } from './gateway-retry.js';
+import { gatewayLogDebug, withActivityIdentity } from './gateway-log-meta.js';
 import { getPreParsedInstructions } from './gateway-instructions.js';
 import { getModelMaxTokensFromFlexMd } from './flex-md-loader.js';
 import { applyModelResolution } from './ai-tools-client.js';
@@ -55,6 +58,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 +178,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,10 +207,10 @@ 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);
+                throw buildModelResolutionFailureError(explicitModel, merged.provider, resolution);
             }
         }
         catch (error) {
@@ -177,7 +218,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 +226,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 +824,162 @@ export function pickRequestIdsFromRouterLike(gatewayAiRequestId, routerLike) {
     }
     return out;
 }
+/** Error code hint when a bundled profile name cannot be routed to a catalog target. */
+export const MODEL_PROFILE_UNROUTABLE = 'MODEL_PROFILE_UNROUTABLE';
+export class ModelProfileUnroutableError extends Error {
+    profileAlias;
+    provider;
+    code = MODEL_PROFILE_UNROUTABLE;
+    constructor(profileAlias, provider, cause) {
+        super(`${MODEL_PROFILE_UNROUTABLE}: profile "${profileAlias}" is retired or has no routable catalog target` +
+            (provider ? ` (provider: "${provider}")` : '') +
+            '. Update @x12i/ai-profiles or choose another profile alias.');
+        this.profileAlias = profileAlias;
+        this.provider = provider;
+        this.name = 'ModelProfileUnroutableError';
+        if (cause !== undefined) {
+            this.cause = cause;
+        }
+    }
+}
+function buildModelResolutionFailureError(explicitModel, provider, resolution) {
+    const base = new ModelResolutionError({ provider, model: explicitModel }, resolution);
+    if (isKnownProfileOrShortcut(explicitModel)) {
+        return new ModelProfileUnroutableError(explicitModel, provider, base);
+    }
+    return base;
+}
+/**
+ * Build rejection-metadata fallback attempts from trace-mode {@link GatewayTraceAttempt}s.
+ */
+export function buildGatewayFallbackAttemptsFromTrace(traceAttempts, candidates, lastError) {
+    const lastFailedByIndex = new Map();
+    for (const attempt of traceAttempts) {
+        if (!attempt.ok) {
+            lastFailedByIndex.set(attempt.routing.fallbackIndex, attempt);
+        }
+    }
+    return candidates.map((candidate, index) => {
+        const failed = lastFailedByIndex.get(index);
+        const errMsg = failed?.error?.message ??
+            (index === candidates.length - 1 && lastError ? lastError.message : 'invoke failed');
+        const httpStatus = extractHttpStatusCode(new Error(errMsg));
+        let responsePreview;
+        const raw = failed?.rawProviderPayload;
+        if (raw !== undefined) {
+            try {
+                const rawStr = typeof raw === 'string' ? raw : JSON.stringify(raw);
+                responsePreview = rawStr.length <= 500 ? rawStr : rawStr.slice(0, 500) + '…';
+            }
+            catch {
+                responsePreview = '[Unserializable]';
+            }
+        }
+        return {
+            provider: candidate.provider,
+            model: candidate.model,
+            ...(httpStatus !== undefined ? { httpStatus } : {}),
+            error: errMsg,
+            ...(responsePreview !== undefined ? { responsePreview } : {})
+        };
+    });
+}
+/** Human-readable exhaustion message for trace fallback chains and rejection logs. */
+export function formatFallbackExhaustionMessage(attempts, candidates) {
+    const providersTried = [...new Set(candidates.map((c) => c.provider))];
+    const providerNote = providersTried.length > 1
+        ? `; providers tried: ${providersTried.join(' → ')}`
+        : providersTried.length === 1
+            ? `; provider: ${providersTried[0]}`
+            : '';
+    const detail = attempts
+        .map((a) => {
+        const model = a.model ? `${a.provider}/${a.model}` : a.provider;
+        const status = a.httpStatus !== undefined ? ` HTTP ${a.httpStatus}` : '';
+        const preview = a.responsePreview ? ` body=${a.responsePreview}` : '';
+        return `[${model}${status}] ${a.error}${preview}`;
+    })
+        .join('; ');
+    const last = attempts[attempts.length - 1];
+    const lastBody = last?.responsePreview && !detail.includes(last.responsePreview)
+        ? ` Last response preview: ${last.responsePreview}`
+        : '';
+    return (`All fallback candidates failed (${candidates.length} tried${providerNote}). ` +
+        `Attempts: ${detail || 'no attempt details recorded'}.${lastBody}`);
+}
+export function mapGatewayFallbackAttemptsToRouter(attempts) {
+    return attempts.map((a) => ({
+        provider: a.provider,
+        model: a.model,
+        httpStatus: a.httpStatus,
+        error: new Error(a.error),
+        responsePreview: a.responsePreview
+    }));
+}
+/**
+ * Log profile alias vs OpenRouter model id actually sent to the router after catalog resolution.
+ */
+export function logResolvedModelRouting(logger, request, mergedConfig) {
+    const res = request._modelResolution;
+    if (!res?.modelId && res?.originalModel === undefined) {
+        return;
+    }
+    const profileAlias = res.originalModel ?? mergedConfig?.model;
+    const invokedModelId = res.modelId ?? mergedConfig?.model;
+    const provider = mergedConfig?.provider;
+    const openRouterPath = res.routedViaOpenRouter === true || provider === 'openrouter';
+    if (!openRouterPath) {
+        return;
+    }
+    logger.info('OpenRouter routing: profile alias resolved to model id for invoke', withActivityIdentity(request.identity, {
+        profileAlias,
+        invokedOpenRouterModelId: invokedModelId,
+        provider,
+        routedViaOpenRouter: res.routedViaOpenRouter,
+        resolvedVia: res.resolvedVia,
+        debugKind: gatewayLogDebug.trace
+    }));
+}
+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 +993,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 +1005,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,39 @@ 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;
+/** Error code hint when a bundled profile name cannot be routed to a catalog target. */
+export declare const MODEL_PROFILE_UNROUTABLE = "MODEL_PROFILE_UNROUTABLE";
+export declare class ModelProfileUnroutableError extends Error {
+    readonly profileAlias: string;
+    readonly provider: string | undefined;
+    readonly code = "MODEL_PROFILE_UNROUTABLE";
+    constructor(profileAlias: string, provider: string | undefined, cause?: unknown);
+}
+type ModelResolutionCandidate = {
+    provider: string;
+    model: string;
+};
+/**
+ * Build rejection-metadata fallback attempts from trace-mode {@link GatewayTraceAttempt}s.
+ */
+export declare function buildGatewayFallbackAttemptsFromTrace(traceAttempts: GatewayTraceAttempt[], candidates: ModelResolutionCandidate[], lastError?: Error): GatewayFallbackAttempt[];
+/** Human-readable exhaustion message for trace fallback chains and rejection logs. */
+export declare function formatFallbackExhaustionMessage(attempts: GatewayFallbackAttempt[], candidates: ModelResolutionCandidate[]): string;
+export declare function mapGatewayFallbackAttemptsToRouter(attempts: GatewayFallbackAttempt[]): Array<{
+    provider: string;
+    model?: string;
+    httpStatus?: number;
+    error: Error;
+    responsePreview?: string;
+}>;
+/**
+ * Log profile alias vs OpenRouter model id actually sent to the router after catalog resolution.
+ */
+export declare function logResolvedModelRouting(logger: Logxer, request: ChatRequest, mergedConfig: ChatRequest['config']): void;
+/**
+ * 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 +195,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

@@ -3,13 +3,14 @@
  *
  * Simplified AI Gateway - Clean proxy implementation
  */
+import { FallbackExhaustedError } from '@x12i/ai-providers-router';
 import { validateChatRequest, validateAIRequest } from './gateway-validation.js';
 import { ensureGatewayRequestIdentity } from './activity-manager.js';
 import { initializeGatewayComponents } from './gateway-config.js';
 import { buildMessages } from './message-builder.js';
 import { extractJsonFromFlexMd, getModelMaxTokensFromFlexMd } from './flex-md-loader.js';
 import { enrichParsedContentForOutputContract, resolveOutputContractFieldKeys } from './output-contract-normalizer.js';
-import { attachGatewayInvokeRejectionMetadata, buildInvokeRejectionMetadata, capActivityFullResponsePayload, DEFAULT_ACTIVITY_FULL_RESPONSE_MAX_CHARS, extractCostUsdFromRouterResponse, extractTokenUsageFromRouterResponse, mergeConfig, pickEffectiveModelConfigForMetadata, pickInvokeRoutingMetadataSlice, pickTraceMergedRouterConfig, resolveCostCompletionWithAiTools, buildOptimixerActualUsage, buildTraceUsageSummary, enrichTraceAttemptsWithBilling, isMaxTokensExplicitlySet, tryExtractRouterLikePayloadFromErrorChain } from './gateway-utils.js';
+import { attachGatewayInvokeRejectionMetadata, buildGatewayFallbackAttemptsFromTrace, buildInvokeRejectionMetadata, capActivityFullResponsePayload, formatFallbackExhaustionMessage, logResolvedModelRouting, mapGatewayFallbackAttemptsToRouter, hasNonZeroTokenUsage, DEFAULT_ACTIVITY_FULL_RESPONSE_MAX_CHARS, extractCostUsdFromRouterResponse, extractTokenUsageFromRouterResponse, mergeConfig, pickEffectiveModelConfigForMetadata, pickInvokeRoutingMetadataSlice, pickTraceMergedRouterConfig, resolveCostCompletionWithAiTools, buildOptimixerActualUsage, buildTraceUsageSummary, enrichTraceAttemptsWithBilling, isMaxTokensExplicitlySet, tryExtractRouterLikePayloadFromErrorChain } from './gateway-utils.js';
 import { getAiToolsClient } from './ai-tools-client.js';
 import { autoRegisterProviders } from './gateway-provider-auto-register.js';
 import { setGatewayLastJobId, setGatewayRuntimeClients } from './runtime-objects.js';
@@ -17,7 +18,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;
@@ -277,6 +278,7 @@ export class AIGateway {
             catalog: aiTools?.catalog ?? null
         });
         request._mergedRouterConfig = mergedConfig;
+        logResolvedModelRouting(this.logger, request, mergedConfig);
         const diagnosticsMode = request.diagnostics?.mode;
         const traceEnabled = diagnosticsMode === 'trace';
         const includeRawProviderPayload = request.diagnostics?.includeRawProviderPayload === true;
@@ -468,7 +470,20 @@ export class AIGateway {
                     }
                 }
                 if (!response) {
-                    throw lastError ?? new Error('All fallback candidates failed');
+                    const fallbackAttempts = buildGatewayFallbackAttemptsFromTrace(traceAttempts, deduped, lastError);
+                    const providersTried = [...new Set(deduped.map((c) => c.provider))];
+                    this.logger.error('Trace fallback chain exhausted', withActivityIdentity(request.identity, {
+                        providersTried,
+                        candidates: deduped,
+                        fallbackAttempts,
+                        debugKind: gatewayLogDebug.anomaly
+                    }));
+                    const exhausted = new FallbackExhaustedError(mapGatewayFallbackAttemptsToRouter(fallbackAttempts));
+                    exhausted.message = formatFallbackExhaustionMessage(fallbackAttempts, deduped);
+                    if (lastError) {
+                        exhausted.cause = lastError;
+                    }
+                    throw exhausted;
                 }
                 // Summary counts + final request ids.
                 traceRetryCount = traceAttempts.filter(a => a.routing.retryIndex > 0).length;
@@ -565,11 +580,14 @@ export class AIGateway {
                         tokens = second;
                 }
             }
-            const costCompletion = await resolveCostCompletionWithAiTools(routerResponse, tokens, {
+            let costCompletion = await resolveCostCompletionWithAiTools(routerResponse, tokens, {
                 mergedConfig,
                 calculator: aiTools?.calculator ?? null,
                 calculateCost: this.config.aiTools?.calculateCost
             });
+            if (!costCompletion.costStatus && hasNonZeroTokenUsage(tokens)) {
+                costCompletion = { ...costCompletion, costStatus: 'unpriced' };
+            }
             const routerMetaForCost = routerResponse?.metadata || {};
             const routingMetadataSlice = pickInvokeRoutingMetadataSlice(routerResponse, mergedConfig);
             const effectiveModelConfig = pickEffectiveModelConfigForMetadata(mergedConfig);
@@ -685,7 +703,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, MODEL_PROFILE_UNROUTABLE, ModelProfileUnroutableError, buildGatewayFallbackAttemptsFromTrace, formatFallbackExhaustionMessage, logResolvedModelRouting, mapGatewayFallbackAttemptsToRouter } 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, MODEL_PROFILE_UNROUTABLE, ModelProfileUnroutableError, buildGatewayFallbackAttemptsFromTrace, formatFallbackExhaustionMessage, logResolvedModelRouting, mapGatewayFallbackAttemptsToRouter } 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/optimixer-manager.cjs

@@ -1,14 +1,15 @@
 import { Optimixer } from '@x12i/optimixer';
 import { resolveActivityTrackingConfig } from './config/activity-tracking-config.js';
 import { estimateMessagesTokenSizes } from './token-estimate.js';
-function resolveActionTypeId(request) {
+/** Optimixer bucket key: prefer taskTypeId (template), then identity actionType, else gateway default. */
+function resolveTemplateId(request) {
+    if (request.taskTypeId && String(request.taskTypeId).trim()) {
+        return String(request.taskTypeId).trim();
+    }
     const identity = request.identity;
     if (identity?.actionType && String(identity.actionType).trim()) {
         return String(identity.actionType).trim();
     }
-    if (request.taskTypeId && String(request.taskTypeId).trim()) {
-        return String(request.taskTypeId).trim();
-    }
     return 'gateway.invoke';
 }
 function toActivixRunContext(identity) {
@@ -77,15 +78,18 @@ export class OptimixerManager {
         const { request, mergedConfig, messages } = ctx;
         const { inputSize, contextSize } = estimateMessagesTokenSizes(messages);
         const acceptableRisk = this.config?.acceptableRisk ?? 'medium';
+        const provider = typeof mergedConfig?.provider === 'string' ? mergedConfig.provider : undefined;
+        const model = typeof mergedConfig?.model === 'string' ? mergedConfig.model : undefined;
         try {
             return await optimixer.predictAiMaxTokens({
-                actionTypeId: resolveActionTypeId(request),
+                templateId: resolveTemplateId(request),
                 inputSize,
                 contextSize,
                 acceptableRisk,
                 runContext: toActivixRunContext(request.identity),
-                provider: typeof mergedConfig?.provider === 'string' ? mergedConfig.provider : undefined,
-                model: typeof mergedConfig?.model === 'string' ? mergedConfig.model : undefined
+                ...(provider || model
+                    ? { modelProfile: { ...(provider ? { provider } : {}), ...(model ? { model } : {}) } }
+                    : {})
             });
         }
         catch (error) {

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.1",
   "description": "AI Gateway - Unified interface for LLM provider routing and management",
   "type": "module",
   "exports": {
@@ -41,12 +41,12 @@
   "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.7",
+    "@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",
+    "@x12i/optimixer": "^2.0.1",
     "@x12i/rendrix": "^4.3.0"
   },
   "devDependencies": {