@x12i/ai-gateway 9.6.0 → 9.6.2

package/dist/gateway-utils.d.ts

@@ -155,6 +155,35 @@ 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}.
  */

package/dist/gateway-utils.js

@@ -4,7 +4,9 @@
  */
 import * as crypto from 'crypto';
 import { FallbackExhaustedError } from '@x12i/ai-providers-router';
-import { ModelResolutionError } from '@x12i/ai-tools';
+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';
@@ -208,7 +210,7 @@ export async function mergeConfig(request, config, logger, mergeOptions) {
                 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) {
@@ -822,6 +824,122 @@ 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),

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';
@@ -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);

package/dist/index.d.ts

@@ -17,7 +17,7 @@ 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, 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 { 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, tryExtractFallbackAttemptsFromErrorChain, 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-cjs/gateway-utils.cjs

@@ -4,7 +4,9 @@
  */
 import * as crypto from 'crypto';
 import { FallbackExhaustedError } from '@x12i/ai-providers-router';
-import { ModelResolutionError } from '@x12i/ai-tools';
+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';
@@ -208,7 +210,7 @@ export async function mergeConfig(request, config, logger, mergeOptions) {
                 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) {
@@ -822,6 +824,122 @@ 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),

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

@@ -155,6 +155,35 @@ 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}.
  */

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';
@@ -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);

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, tryExtractFallbackAttemptsFromErrorChain, 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

@@ -17,7 +17,7 @@ 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, 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 { 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x12i/ai-gateway",
-  "version": "9.6.0",
+  "version": "9.6.2",
   "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.5",
+    "@x12i/activix": "^8.3.0",
     "@x12i/ai-providers-router": "^4.8.5",
-    "@x12i/ai-tools": "^2.0.4",
+    "@x12i/ai-tools": "^2.0.7",
     "@x12i/flex-md": "^4.8.0",
     "@x12i/logxer": "^4.3.5",
-    "@x12i/optimixer": "^0.1.0",
+    "@x12i/optimixer": "^2.4.0",
     "@x12i/rendrix": "^4.3.0"
   },
   "devDependencies": {