@x12i/ai-gateway 10.4.3 → 10.4.4

package/README.md

@@ -13,7 +13,7 @@ Unified gateway for LLM provider routing, structured logging, optional Activix a
 | **Activix** | Optional Mongo-backed activity rows; billing written from gateway-computed slice on **`completeRecord`** (`outer.cost` + root fields). No Activix **`autoCost`** re-pricing. |
 | **Trace mode** | `diagnostics.mode === 'trace'` adds `metadata.attempts[]`, `metadata.usage`, and per-attempt **`costUsd`** / **`costStatus`**. |
 
-Pinned dependency versions are in `package.json` (currently **Activix ^9.0**, **ai-tools ^3.3**, **ai-profiles ^3.4**, **ai-providers-router ^4.9**, **openrouter-runtime ^1.0**).
+Pinned dependency versions are in `package.json` (currently **Activix ^9.0**, **ai-tools ^3.3**, **ai-profiles ^3.4**, **ai-providers-router ^4.10**, **openrouter-runtime ^1.0.4**).
 
 ---
 
@@ -308,6 +308,17 @@ Do **not** add a direct **`@x12i/ai-tools`** dependency for post-call cost. For
 
 Full contract: [AI Gateway invoke execution metadata](./docs/AI_GATEWAY_INVOKE_EXECUTION_METADATA.md).
 
+### Provider failure taxonomy (router ≥ 4.10)
+
+When the fallback chain exhausts, **`@x12i/ai-providers-router`** assigns stable sub-codes (`PROVIDER_AUTH_FAILED`, `PROVIDER_RATE_LIMITED`, `PROVIDER_QUOTA_EXCEEDED`, `PROVIDER_MODEL_NOT_FOUND`, `PROVIDER_GATEWAY_UNREACHABLE`, `OPENROUTER_API_KEY_MISSING`, …). The gateway forwards them on:
+
+| Surface | Fields |
+|---------|--------|
+| Thrown error | `error.code`, `error.operatorHint`, `error.details.providerAttempts[]` |
+| Rejection metadata | `error.metadata.fallbackAttempts[]`, `error.metadata.providerAttempts[]`, `error.metadata.providerSubCode`, `error.metadata.operatorHint` |
+
+Each attempt includes `{ provider, modelId?, httpStatus?, message, code }` — no prose parsing required. Trace-mode exhaustion uses `enrichGatewayFallbackExhaustedError()` before throw. Helpers are re-exported from `@x12i/ai-gateway` via the router (`enrichRunTaskError`, `providerAttemptsFromFallbackAttempts`, `operatorHintForProviderFailureCode`, …).
+
 ### Trace diagnostics
 
 ```typescript

package/dist/gateway-utils.d.ts

@@ -3,6 +3,8 @@
  * Handles utility functions
  */
 import type { AIInvokeRequest, ChatRequest, GatewayConfig, GatewayFallbackAttempt, GatewayInvokeRejectionMetadata, GatewayTraceAttempt, GatewayTraceMergedConfig, GatewayTraceRequestIds, GatewayTraceUsageSummary, ModelConfig } from './types.js';
+import { FallbackExhaustedError } from '@x12i/ai-providers-router';
+import type { ProviderFailureCode } from '@x12i/ai-providers-router';
 import type { Logxer } from '@x12i/logxer';
 import { type AiCostResult, type AiModelsCatalogClient, type CostCalculator, type OpenRouterRoutingConfig } from '@x12i/ai-tools';
 import { pickOpenRouterRuntimeMetadataSlice, enrichTraceOpenRouterRuntimeMetadata } from './openrouter-runtime-adapter/index.js';
@@ -191,9 +193,13 @@ export declare function mapGatewayFallbackAttemptsToRouter(attempts: GatewayFall
     provider: string;
     model?: string;
     httpStatus?: number;
+    code?: ProviderFailureCode;
+    message?: string;
     error: Error;
     responsePreview?: string;
 }>;
+/** Apply router ≥ 4.10 provider failure enrichment (code, operatorHint, details.providerAttempts). */
+export declare function enrichGatewayFallbackExhaustedError(exhausted: FallbackExhaustedError): FallbackExhaustedError;
 /**
  * Log original input vs OpenRouter model id actually sent to the router after catalog resolution.
  */

package/dist/gateway-utils.js

@@ -3,7 +3,7 @@
  * Handles utility functions
  */
 import * as crypto from 'crypto';
-import { FallbackExhaustedError } from '@x12i/ai-providers-router';
+import { FallbackExhaustedError, enrichRunTaskError, providerAttemptsFromFallbackAttempts } from '@x12i/ai-providers-router';
 import { ModelResolutionError, ModelProfileInputRejectedError, ModelProfileUnroutableError, resolveInvokeModel, } from '@x12i/ai-tools';
 import { extractHttpStatusCode } from './gateway-retry.js';
 import { gatewayLogDebug, withActivityIdentity } from './gateway-log-meta.js';
@@ -980,10 +980,17 @@ export function mapGatewayFallbackAttemptsToRouter(attempts) {
         provider: a.provider,
         model: a.model,
         httpStatus: a.httpStatus,
+        ...(a.code !== undefined ? { code: a.code } : {}),
+        message: a.error,
         error: new Error(a.error),
-        responsePreview: a.responsePreview
+        responsePreview: a.responsePreview,
     }));
 }
+/** Apply router ≥ 4.10 provider failure enrichment (code, operatorHint, details.providerAttempts). */
+export function enrichGatewayFallbackExhaustedError(exhausted) {
+    const routerAttempts = providerAttemptsFromFallbackAttempts(exhausted.attempts);
+    return enrichRunTaskError(exhausted, { providerAttempts: routerAttempts });
+}
 /**
  * Log original input vs OpenRouter model id actually sent to the router after catalog resolution.
  */
@@ -1009,20 +1016,58 @@ export function logResolvedModelRouting(logger, request, mergedConfig) {
     }));
 }
 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 } : {})
+    return attempts.map((attempt) => {
+        const errorMsg = typeof attempt.message === 'string' && attempt.message.trim()
+            ? attempt.message
+            : attempt.error instanceof Error
+                ? attempt.error.message
+                : String(attempt.error);
+        return {
+            provider: String(attempt.provider),
+            ...(attempt.model !== undefined ? { model: attempt.model } : {}),
+            ...(attempt.httpStatus !== undefined ? { httpStatus: attempt.httpStatus } : {}),
+            error: errorMsg,
+            ...(attempt.code !== undefined ? { code: attempt.code } : {}),
+            ...(attempt.responsePreview !== undefined ? { responsePreview: attempt.responsePreview } : {}),
+        };
+    });
+}
+function mapProviderAttemptDetailsToGateway(attempts) {
+    return attempts.map((a) => ({
+        provider: a.provider,
+        ...(a.modelId !== undefined ? { model: a.modelId } : {}),
+        ...(a.httpStatus !== undefined ? { httpStatus: a.httpStatus } : {}),
+        error: a.message,
+        ...(a.code !== undefined ? { code: a.code } : {}),
     }));
 }
+function extractEnrichedFieldsFromError(error) {
+    if (error == null || typeof error !== 'object')
+        return {};
+    const e = error;
+    return {
+        ...(typeof e.code === 'string' ? { providerSubCode: e.code } : {}),
+        ...(typeof e.operatorHint === 'string' ? { operatorHint: e.operatorHint } : {}),
+        ...(e.details?.providerAttempts?.length
+            ? { providerAttempts: e.details.providerAttempts }
+            : {}),
+    };
+}
 function extractFallbackAttemptsFromError(error) {
-    if (error instanceof FallbackExhaustedError && error.attempts.length > 0) {
-        return mapRouterFallbackAttempts(error.attempts);
+    if (error instanceof FallbackExhaustedError) {
+        if (error.details?.providerAttempts?.length) {
+            return mapProviderAttemptDetailsToGateway(error.details.providerAttempts);
+        }
+        if (error.attempts.length > 0) {
+            return mapRouterFallbackAttempts(error.attempts);
+        }
     }
     if (error != null && typeof error === 'object') {
         const record = error;
+        const details = record.details;
+        if (details?.providerAttempts?.length) {
+            return mapProviderAttemptDetailsToGateway(details.providerAttempts);
+        }
         if (record.name === 'FallbackExhaustedError' && Array.isArray(record.attempts) && record.attempts.length > 0) {
             return mapRouterFallbackAttempts(record.attempts);
         }
@@ -1064,6 +1109,17 @@ export function buildInvokeRejectionMetadata(args) {
     const fallbackAttempts = args.error !== undefined
         ? tryExtractFallbackAttemptsFromErrorChain(args.error)
         : undefined;
+    const enriched = args.error !== undefined ? extractEnrichedFieldsFromError(args.error) : {};
+    const providerAttempts = enriched.providerAttempts ??
+        (fallbackAttempts?.length
+            ? fallbackAttempts.map((a) => ({
+                provider: a.provider,
+                ...(a.model ? { modelId: a.model } : {}),
+                ...(a.httpStatus !== undefined ? { httpStatus: a.httpStatus } : {}),
+                message: a.error,
+                ...(a.code ? { code: a.code } : {}),
+            }))
+            : undefined);
     const openrouterFromPartial = partial !== undefined ? pickEnhancedOpenRouterMetadata(partial, false) : {};
     const openrouterFromError = args.error !== undefined ? tryExtractOpenRouterMetadataFromErrorChain(args.error) : {};
     const openrouterMetadata = {
@@ -1090,6 +1146,9 @@ export function buildInvokeRejectionMetadata(args) {
         ...(tokens !== undefined ? { tokens } : {}),
         ...(requestIds !== undefined ? { requestIds } : {}),
         ...(fallbackAttempts !== undefined ? { fallbackAttempts } : {}),
+        ...(providerAttempts?.length ? { providerAttempts } : {}),
+        ...(enriched.providerSubCode ? { providerSubCode: enriched.providerSubCode } : {}),
+        ...(enriched.operatorHint ? { operatorHint: enriched.operatorHint } : {}),
         ...(mc === undefined ? { mergeConfigUnavailable: true } : {}),
         ...(openrouterMetadata.serverTools ? { serverTools: openrouterMetadata.serverTools } : {}),
         ...(openrouterMetadata.citations?.length ? { citations: openrouterMetadata.citations } : {}),

package/dist/gateway.js

@@ -11,7 +11,7 @@ import { resolveRetryConfig } from './gateway-defaults.js';
 import { buildMessages } from './message-builder.js';
 import { extractJsonFromFlexMd } from './flex-md-loader.js';
 import { enrichParsedContentForOutputContract, resolveOutputContractFieldKeys } from './output-contract-normalizer.js';
-import { attachGatewayInvokeRejectionMetadata, buildGatewayFallbackAttemptsFromTrace, buildInvokeRejectionMetadata, capActivityFullResponsePayload, formatFallbackExhaustionMessage, logResolvedModelRouting, mapGatewayFallbackAttemptsToRouter, DEFAULT_ACTIVITY_FULL_RESPONSE_MAX_CHARS, extractCostUsdFromRouterResponse, extractTokenUsageFromRouterResponse, mergeConfig, pickEffectiveModelConfigForMetadata, pickInvokeRoutingMetadataSlice, pickTraceMergedRouterConfig, pickEnhancedOpenRouterMetadata, resolveCostCompletionWithAiTools, buildTraceUsageSummary, enrichTraceAttemptsWithBilling, tryExtractRouterLikePayloadFromErrorChain, tryExtractOpenRouterMetadataFromErrorChain, } from './gateway-utils.js';
+import { attachGatewayInvokeRejectionMetadata, buildGatewayFallbackAttemptsFromTrace, buildInvokeRejectionMetadata, capActivityFullResponsePayload, formatFallbackExhaustionMessage, logResolvedModelRouting, enrichGatewayFallbackExhaustedError, mapGatewayFallbackAttemptsToRouter, DEFAULT_ACTIVITY_FULL_RESPONSE_MAX_CHARS, extractCostUsdFromRouterResponse, extractTokenUsageFromRouterResponse, mergeConfig, pickEffectiveModelConfigForMetadata, pickInvokeRoutingMetadataSlice, pickTraceMergedRouterConfig, pickEnhancedOpenRouterMetadata, resolveCostCompletionWithAiTools, buildTraceUsageSummary, enrichTraceAttemptsWithBilling, tryExtractRouterLikePayloadFromErrorChain, tryExtractOpenRouterMetadataFromErrorChain, } from './gateway-utils.js';
 import { buildTraceAttemptOpenRouterRuntimeSlice } from './openrouter-runtime-adapter/index.js';
 import { getAiToolsClient } from './ai-tools-client.js';
 import { autoRegisterProviders } from './gateway-provider-auto-register.js';
@@ -512,7 +512,7 @@ export class AIGateway {
                                 actual: 'All candidates failed or returned no response.'
                             }
                         });
-                        const exhausted = new FallbackExhaustedError(mapGatewayFallbackAttemptsToRouter(fallbackAttempts));
+                        const exhausted = enrichGatewayFallbackExhaustedError(new FallbackExhaustedError(mapGatewayFallbackAttemptsToRouter(fallbackAttempts)));
                         exhausted.message = formatFallbackExhaustionMessage(fallbackAttempts, deduped);
                         if (lastError) {
                             exhausted.cause = lastError;

package/dist/index.d.ts

@@ -9,7 +9,7 @@ export { LLMProviderRouter } from '@x12i/ai-providers-router';
 export type { RouterConfig, HealthCheckResult } from '@x12i/ai-providers-router';
 export { createRouter, createRouterFromConfig } from '@x12i/ai-providers-router';
 export type { CreateRouterConfig } from '@x12i/ai-providers-router';
-export { ProviderNotFoundError, FallbackExhaustedError } from '@x12i/ai-providers-router';
+export { ProviderNotFoundError, FallbackExhaustedError, OpenRouterApiKeyMissingError, } from '@x12i/ai-providers-router';
 export type { RequestInterceptor, ResponseInterceptor } from '@x12i/ai-providers-router';
 export type { UsageTracker } from '@x12i/ai-providers-router';
 export * from '@x12i/ai-providers-router';
@@ -19,7 +19,7 @@ export { normalizeInvokeModelAtIngress } from './invoke-model-ingress.js';
 export { autoRegisterProviders } from './gateway-provider-auto-register.js';
 export { registerOpenRouterRuntime, shouldUseOpenRouterRuntime, mapGatewayServerTools, } from './openrouter-runtime-adapter/index.js';
 export type { GatewayConfig, ProviderModelRef, ModelConfig, GatewayModelConfig, GatewayServerToolsConfig, GatewayServerToolMode, GatewayServerToolUsage, GatewayNestedServerTool, GatewayWebSearchToolConfig, GatewayWebFetchToolConfig, GatewayDatetimeToolConfig, GatewayImageGenerationToolConfig, GatewayApplyPatchToolConfig, GatewayFusionToolConfig, GatewayAdvisorToolConfig, GatewaySubagentToolConfig, GatewayOpenRouterErrorMetadata, GatewayOpenRouterConfig, GatewayOpenRouterRuntimeConfig, GatewayServerToolUsageMap, GatewayCitation, GatewayGeneratedImage, GatewayPatchProposal, GatewayOpenRouterRuntimeMetadata, RetryConfig, ChatRequest, AIInvokeRequest, AIRequest, GatewayActionType, GatewayInvokeRejectionMetadata, GatewayFallbackAttempt, GatewayTraceRequestIds, GatewayTraceAttempt, GatewayTraceUsageSummary, GatewayTraceMergedConfig, EnhancedLLMResponse, InstructionMetadata, ValidationRule, TemplateRenderOptions, SmartInputConfig, SmartInputRenderOptions } from './types.js';
-export { attachGatewayInvokeRejectionMetadata, buildInvokeRejectionMetadata, tryExtractRouterLikePayloadFromErrorChain, tryExtractOpenRouterMetadataFromErrorChain, tryExtractFallbackAttemptsFromErrorChain, pickRequestIdsFromRouterLike, resolveActivityCostCompletion, resolveCostCompletionForActivity, resolveCostCompletionWithAiTools, buildGatewayPricingRecord, mapAiCostResultToResolvedActivityCost, catalogPricingSucceeded, extractUsageExtrasFromRouterResponse, buildTraceUsageSummary, enrichTraceAttemptsWithBilling, pickEnhancedOpenRouterMetadata, hasNonZeroTokenUsage, MODEL_PROFILE_UNROUTABLE, ModelProfileUnroutableError, ModelProfileInputRejectedError, buildGatewayFallbackAttemptsFromTrace, formatFallbackExhaustionMessage, logResolvedModelRouting, mapGatewayFallbackAttemptsToRouter } from './gateway-utils.js';
+export { attachGatewayInvokeRejectionMetadata, buildInvokeRejectionMetadata, tryExtractRouterLikePayloadFromErrorChain, tryExtractOpenRouterMetadataFromErrorChain, tryExtractFallbackAttemptsFromErrorChain, pickRequestIdsFromRouterLike, resolveActivityCostCompletion, resolveCostCompletionForActivity, resolveCostCompletionWithAiTools, buildGatewayPricingRecord, mapAiCostResultToResolvedActivityCost, catalogPricingSucceeded, extractUsageExtrasFromRouterResponse, buildTraceUsageSummary, enrichTraceAttemptsWithBilling, pickEnhancedOpenRouterMetadata, hasNonZeroTokenUsage, MODEL_PROFILE_UNROUTABLE, ModelProfileUnroutableError, ModelProfileInputRejectedError, buildGatewayFallbackAttemptsFromTrace, formatFallbackExhaustionMessage, enrichGatewayFallbackExhaustedError, logResolvedModelRouting, mapGatewayFallbackAttemptsToRouter } from './gateway-utils.js';
 export { getGatewayOperationalMode, isProdGatewayMode, parseModelProviderSpec } from './gateway-mode.js';
 export type { GatewayOperationalMode } from './gateway-mode.js';
 export { DEFAULT_ACTIVITY_FULL_RESPONSE_MAX_CHARS, GATEWAY_DEFAULT_FREQUENCY_PENALTY, GATEWAY_DEFAULT_PRESENCE_PENALTY, GATEWAY_DEFAULT_RETRY, GATEWAY_DEFAULT_TEMPERATURE, GATEWAY_DEFAULT_TOP_P, resolveRetryConfig } from './gateway-defaults.js';

package/dist/index.js

@@ -10,7 +10,7 @@ export { LLMProviderRouter } from '@x12i/ai-providers-router';
 // Re-export factory functions
 export { createRouter, createRouterFromConfig } from '@x12i/ai-providers-router';
 // Re-export error classes
-export { ProviderNotFoundError, FallbackExhaustedError } from '@x12i/ai-providers-router';
+export { ProviderNotFoundError, FallbackExhaustedError, OpenRouterApiKeyMissingError, } from '@x12i/ai-providers-router';
 // Re-export all from router (includes everything it exports)
 export * from '@x12i/ai-providers-router';
 // Export enhanced gateway
@@ -19,7 +19,7 @@ export { InstructionNotFoundError, InstructionBackendError, ModelRequiredError,
 export { normalizeInvokeModelAtIngress } from './invoke-model-ingress.js';
 export { autoRegisterProviders } from './gateway-provider-auto-register.js';
 export { registerOpenRouterRuntime, shouldUseOpenRouterRuntime, mapGatewayServerTools, } from './openrouter-runtime-adapter/index.js';
-export { attachGatewayInvokeRejectionMetadata, buildInvokeRejectionMetadata, tryExtractRouterLikePayloadFromErrorChain, tryExtractOpenRouterMetadataFromErrorChain, tryExtractFallbackAttemptsFromErrorChain, pickRequestIdsFromRouterLike, resolveActivityCostCompletion, resolveCostCompletionForActivity, resolveCostCompletionWithAiTools, buildGatewayPricingRecord, mapAiCostResultToResolvedActivityCost, catalogPricingSucceeded, extractUsageExtrasFromRouterResponse, buildTraceUsageSummary, enrichTraceAttemptsWithBilling, pickEnhancedOpenRouterMetadata, hasNonZeroTokenUsage, MODEL_PROFILE_UNROUTABLE, ModelProfileUnroutableError, ModelProfileInputRejectedError, buildGatewayFallbackAttemptsFromTrace, formatFallbackExhaustionMessage, logResolvedModelRouting, mapGatewayFallbackAttemptsToRouter } from './gateway-utils.js';
+export { attachGatewayInvokeRejectionMetadata, buildInvokeRejectionMetadata, tryExtractRouterLikePayloadFromErrorChain, tryExtractOpenRouterMetadataFromErrorChain, tryExtractFallbackAttemptsFromErrorChain, pickRequestIdsFromRouterLike, resolveActivityCostCompletion, resolveCostCompletionForActivity, resolveCostCompletionWithAiTools, buildGatewayPricingRecord, mapAiCostResultToResolvedActivityCost, catalogPricingSucceeded, extractUsageExtrasFromRouterResponse, buildTraceUsageSummary, enrichTraceAttemptsWithBilling, pickEnhancedOpenRouterMetadata, hasNonZeroTokenUsage, MODEL_PROFILE_UNROUTABLE, ModelProfileUnroutableError, ModelProfileInputRejectedError, buildGatewayFallbackAttemptsFromTrace, formatFallbackExhaustionMessage, enrichGatewayFallbackExhaustedError, logResolvedModelRouting, mapGatewayFallbackAttemptsToRouter } from './gateway-utils.js';
 export { getGatewayOperationalMode, isProdGatewayMode, parseModelProviderSpec } from './gateway-mode.js';
 export { DEFAULT_ACTIVITY_FULL_RESPONSE_MAX_CHARS, GATEWAY_DEFAULT_FREQUENCY_PENALTY, GATEWAY_DEFAULT_PRESENCE_PENALTY, GATEWAY_DEFAULT_RETRY, GATEWAY_DEFAULT_TEMPERATURE, GATEWAY_DEFAULT_TOP_P, resolveRetryConfig } from './gateway-defaults.js';
 export { contractSpecToFieldKeys, enrichParsedContentForOutputContract, resolveOutputContractFieldKeys } from './output-contract-normalizer.js';

package/dist/types.d.ts

@@ -359,6 +359,21 @@ export type GatewayInvokeRejectionMetadata = {
      * Sourced from {@link FallbackExhaustedError.attempts} on the router error chain.
      */
     fallbackAttempts?: GatewayFallbackAttempt[];
+    /**
+     * Structured per-attempt diagnostics (`@x12i/ai-providers-router` ≥ 4.10).
+     * Same attempts as {@link fallbackAttempts} when enriched; prefer this for UIs.
+     */
+    providerAttempts?: Array<{
+        provider: string;
+        modelId?: string;
+        httpStatus?: number;
+        message: string;
+        code?: string;
+    }>;
+    /** Dominant stable failure sub-code when fallback chain exhausts (router ≥ 4.10). */
+    providerSubCode?: string;
+    /** Short remediation hint from router enrichment (router ≥ 4.10). */
+    operatorHint?: string;
     /**
      * 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.
@@ -378,6 +393,8 @@ export type GatewayFallbackAttempt = {
     model?: string;
     httpStatus?: number;
     error: string;
+    /** Stable sub-code from `@x12i/ai-providers-router` ≥ 4.10 (`PROVIDER_AUTH_FAILED`, …). */
+    code?: string;
     responsePreview?: string;
 };
 /**

package/dist-cjs/gateway-utils.cjs

@@ -3,7 +3,7 @@
  * Handles utility functions
  */
 import * as crypto from 'crypto';
-import { FallbackExhaustedError } from '@x12i/ai-providers-router';
+import { FallbackExhaustedError, enrichRunTaskError, providerAttemptsFromFallbackAttempts } from '@x12i/ai-providers-router';
 import { ModelResolutionError, ModelProfileInputRejectedError, ModelProfileUnroutableError, resolveInvokeModel, } from '@x12i/ai-tools';
 import { extractHttpStatusCode } from './gateway-retry.js';
 import { gatewayLogDebug, withActivityIdentity } from './gateway-log-meta.js';
@@ -980,10 +980,17 @@ export function mapGatewayFallbackAttemptsToRouter(attempts) {
         provider: a.provider,
         model: a.model,
         httpStatus: a.httpStatus,
+        ...(a.code !== undefined ? { code: a.code } : {}),
+        message: a.error,
         error: new Error(a.error),
-        responsePreview: a.responsePreview
+        responsePreview: a.responsePreview,
     }));
 }
+/** Apply router ≥ 4.10 provider failure enrichment (code, operatorHint, details.providerAttempts). */
+export function enrichGatewayFallbackExhaustedError(exhausted) {
+    const routerAttempts = providerAttemptsFromFallbackAttempts(exhausted.attempts);
+    return enrichRunTaskError(exhausted, { providerAttempts: routerAttempts });
+}
 /**
  * Log original input vs OpenRouter model id actually sent to the router after catalog resolution.
  */
@@ -1009,20 +1016,58 @@ export function logResolvedModelRouting(logger, request, mergedConfig) {
     }));
 }
 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 } : {})
+    return attempts.map((attempt) => {
+        const errorMsg = typeof attempt.message === 'string' && attempt.message.trim()
+            ? attempt.message
+            : attempt.error instanceof Error
+                ? attempt.error.message
+                : String(attempt.error);
+        return {
+            provider: String(attempt.provider),
+            ...(attempt.model !== undefined ? { model: attempt.model } : {}),
+            ...(attempt.httpStatus !== undefined ? { httpStatus: attempt.httpStatus } : {}),
+            error: errorMsg,
+            ...(attempt.code !== undefined ? { code: attempt.code } : {}),
+            ...(attempt.responsePreview !== undefined ? { responsePreview: attempt.responsePreview } : {}),
+        };
+    });
+}
+function mapProviderAttemptDetailsToGateway(attempts) {
+    return attempts.map((a) => ({
+        provider: a.provider,
+        ...(a.modelId !== undefined ? { model: a.modelId } : {}),
+        ...(a.httpStatus !== undefined ? { httpStatus: a.httpStatus } : {}),
+        error: a.message,
+        ...(a.code !== undefined ? { code: a.code } : {}),
     }));
 }
+function extractEnrichedFieldsFromError(error) {
+    if (error == null || typeof error !== 'object')
+        return {};
+    const e = error;
+    return {
+        ...(typeof e.code === 'string' ? { providerSubCode: e.code } : {}),
+        ...(typeof e.operatorHint === 'string' ? { operatorHint: e.operatorHint } : {}),
+        ...(e.details?.providerAttempts?.length
+            ? { providerAttempts: e.details.providerAttempts }
+            : {}),
+    };
+}
 function extractFallbackAttemptsFromError(error) {
-    if (error instanceof FallbackExhaustedError && error.attempts.length > 0) {
-        return mapRouterFallbackAttempts(error.attempts);
+    if (error instanceof FallbackExhaustedError) {
+        if (error.details?.providerAttempts?.length) {
+            return mapProviderAttemptDetailsToGateway(error.details.providerAttempts);
+        }
+        if (error.attempts.length > 0) {
+            return mapRouterFallbackAttempts(error.attempts);
+        }
     }
     if (error != null && typeof error === 'object') {
         const record = error;
+        const details = record.details;
+        if (details?.providerAttempts?.length) {
+            return mapProviderAttemptDetailsToGateway(details.providerAttempts);
+        }
         if (record.name === 'FallbackExhaustedError' && Array.isArray(record.attempts) && record.attempts.length > 0) {
             return mapRouterFallbackAttempts(record.attempts);
         }
@@ -1064,6 +1109,17 @@ export function buildInvokeRejectionMetadata(args) {
     const fallbackAttempts = args.error !== undefined
         ? tryExtractFallbackAttemptsFromErrorChain(args.error)
         : undefined;
+    const enriched = args.error !== undefined ? extractEnrichedFieldsFromError(args.error) : {};
+    const providerAttempts = enriched.providerAttempts ??
+        (fallbackAttempts?.length
+            ? fallbackAttempts.map((a) => ({
+                provider: a.provider,
+                ...(a.model ? { modelId: a.model } : {}),
+                ...(a.httpStatus !== undefined ? { httpStatus: a.httpStatus } : {}),
+                message: a.error,
+                ...(a.code ? { code: a.code } : {}),
+            }))
+            : undefined);
     const openrouterFromPartial = partial !== undefined ? pickEnhancedOpenRouterMetadata(partial, false) : {};
     const openrouterFromError = args.error !== undefined ? tryExtractOpenRouterMetadataFromErrorChain(args.error) : {};
     const openrouterMetadata = {
@@ -1090,6 +1146,9 @@ export function buildInvokeRejectionMetadata(args) {
         ...(tokens !== undefined ? { tokens } : {}),
         ...(requestIds !== undefined ? { requestIds } : {}),
         ...(fallbackAttempts !== undefined ? { fallbackAttempts } : {}),
+        ...(providerAttempts?.length ? { providerAttempts } : {}),
+        ...(enriched.providerSubCode ? { providerSubCode: enriched.providerSubCode } : {}),
+        ...(enriched.operatorHint ? { operatorHint: enriched.operatorHint } : {}),
         ...(mc === undefined ? { mergeConfigUnavailable: true } : {}),
         ...(openrouterMetadata.serverTools ? { serverTools: openrouterMetadata.serverTools } : {}),
         ...(openrouterMetadata.citations?.length ? { citations: openrouterMetadata.citations } : {}),

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

@@ -3,6 +3,8 @@
  * Handles utility functions
  */
 import type { AIInvokeRequest, ChatRequest, GatewayConfig, GatewayFallbackAttempt, GatewayInvokeRejectionMetadata, GatewayTraceAttempt, GatewayTraceMergedConfig, GatewayTraceRequestIds, GatewayTraceUsageSummary, ModelConfig } from './types.js';
+import { FallbackExhaustedError } from '@x12i/ai-providers-router';
+import type { ProviderFailureCode } from '@x12i/ai-providers-router';
 import type { Logxer } from '@x12i/logxer';
 import { type AiCostResult, type AiModelsCatalogClient, type CostCalculator, type OpenRouterRoutingConfig } from '@x12i/ai-tools';
 import { pickOpenRouterRuntimeMetadataSlice, enrichTraceOpenRouterRuntimeMetadata } from './openrouter-runtime-adapter/index.js';
@@ -191,9 +193,13 @@ export declare function mapGatewayFallbackAttemptsToRouter(attempts: GatewayFall
     provider: string;
     model?: string;
     httpStatus?: number;
+    code?: ProviderFailureCode;
+    message?: string;
     error: Error;
     responsePreview?: string;
 }>;
+/** Apply router ≥ 4.10 provider failure enrichment (code, operatorHint, details.providerAttempts). */
+export declare function enrichGatewayFallbackExhaustedError(exhausted: FallbackExhaustedError): FallbackExhaustedError;
 /**
  * Log original input vs OpenRouter model id actually sent to the router after catalog resolution.
  */

package/dist-cjs/gateway.cjs

@@ -11,7 +11,7 @@ import { resolveRetryConfig } from './gateway-defaults.js';
 import { buildMessages } from './message-builder.js';
 import { extractJsonFromFlexMd } from './flex-md-loader.js';
 import { enrichParsedContentForOutputContract, resolveOutputContractFieldKeys } from './output-contract-normalizer.js';
-import { attachGatewayInvokeRejectionMetadata, buildGatewayFallbackAttemptsFromTrace, buildInvokeRejectionMetadata, capActivityFullResponsePayload, formatFallbackExhaustionMessage, logResolvedModelRouting, mapGatewayFallbackAttemptsToRouter, DEFAULT_ACTIVITY_FULL_RESPONSE_MAX_CHARS, extractCostUsdFromRouterResponse, extractTokenUsageFromRouterResponse, mergeConfig, pickEffectiveModelConfigForMetadata, pickInvokeRoutingMetadataSlice, pickTraceMergedRouterConfig, pickEnhancedOpenRouterMetadata, resolveCostCompletionWithAiTools, buildTraceUsageSummary, enrichTraceAttemptsWithBilling, tryExtractRouterLikePayloadFromErrorChain, tryExtractOpenRouterMetadataFromErrorChain, } from './gateway-utils.js';
+import { attachGatewayInvokeRejectionMetadata, buildGatewayFallbackAttemptsFromTrace, buildInvokeRejectionMetadata, capActivityFullResponsePayload, formatFallbackExhaustionMessage, logResolvedModelRouting, enrichGatewayFallbackExhaustedError, mapGatewayFallbackAttemptsToRouter, DEFAULT_ACTIVITY_FULL_RESPONSE_MAX_CHARS, extractCostUsdFromRouterResponse, extractTokenUsageFromRouterResponse, mergeConfig, pickEffectiveModelConfigForMetadata, pickInvokeRoutingMetadataSlice, pickTraceMergedRouterConfig, pickEnhancedOpenRouterMetadata, resolveCostCompletionWithAiTools, buildTraceUsageSummary, enrichTraceAttemptsWithBilling, tryExtractRouterLikePayloadFromErrorChain, tryExtractOpenRouterMetadataFromErrorChain, } from './gateway-utils.js';
 import { buildTraceAttemptOpenRouterRuntimeSlice } from './openrouter-runtime-adapter/index.js';
 import { getAiToolsClient } from './ai-tools-client.js';
 import { autoRegisterProviders } from './gateway-provider-auto-register.js';
@@ -512,7 +512,7 @@ export class AIGateway {
                                 actual: 'All candidates failed or returned no response.'
                             }
                         });
-                        const exhausted = new FallbackExhaustedError(mapGatewayFallbackAttemptsToRouter(fallbackAttempts));
+                        const exhausted = enrichGatewayFallbackExhaustedError(new FallbackExhaustedError(mapGatewayFallbackAttemptsToRouter(fallbackAttempts)));
                         exhausted.message = formatFallbackExhaustionMessage(fallbackAttempts, deduped);
                         if (lastError) {
                             exhausted.cause = lastError;

package/dist-cjs/index.cjs

@@ -10,7 +10,7 @@ export { LLMProviderRouter } from '@x12i/ai-providers-router';
 // Re-export factory functions
 export { createRouter, createRouterFromConfig } from '@x12i/ai-providers-router';
 // Re-export error classes
-export { ProviderNotFoundError, FallbackExhaustedError } from '@x12i/ai-providers-router';
+export { ProviderNotFoundError, FallbackExhaustedError, OpenRouterApiKeyMissingError, } from '@x12i/ai-providers-router';
 // Re-export all from router (includes everything it exports)
 export * from '@x12i/ai-providers-router';
 // Export enhanced gateway
@@ -19,7 +19,7 @@ export { InstructionNotFoundError, InstructionBackendError, ModelRequiredError,
 export { normalizeInvokeModelAtIngress } from './invoke-model-ingress.js';
 export { autoRegisterProviders } from './gateway-provider-auto-register.js';
 export { registerOpenRouterRuntime, shouldUseOpenRouterRuntime, mapGatewayServerTools, } from './openrouter-runtime-adapter/index.js';
-export { attachGatewayInvokeRejectionMetadata, buildInvokeRejectionMetadata, tryExtractRouterLikePayloadFromErrorChain, tryExtractOpenRouterMetadataFromErrorChain, tryExtractFallbackAttemptsFromErrorChain, pickRequestIdsFromRouterLike, resolveActivityCostCompletion, resolveCostCompletionForActivity, resolveCostCompletionWithAiTools, buildGatewayPricingRecord, mapAiCostResultToResolvedActivityCost, catalogPricingSucceeded, extractUsageExtrasFromRouterResponse, buildTraceUsageSummary, enrichTraceAttemptsWithBilling, pickEnhancedOpenRouterMetadata, hasNonZeroTokenUsage, MODEL_PROFILE_UNROUTABLE, ModelProfileUnroutableError, ModelProfileInputRejectedError, buildGatewayFallbackAttemptsFromTrace, formatFallbackExhaustionMessage, logResolvedModelRouting, mapGatewayFallbackAttemptsToRouter } from './gateway-utils.js';
+export { attachGatewayInvokeRejectionMetadata, buildInvokeRejectionMetadata, tryExtractRouterLikePayloadFromErrorChain, tryExtractOpenRouterMetadataFromErrorChain, tryExtractFallbackAttemptsFromErrorChain, pickRequestIdsFromRouterLike, resolveActivityCostCompletion, resolveCostCompletionForActivity, resolveCostCompletionWithAiTools, buildGatewayPricingRecord, mapAiCostResultToResolvedActivityCost, catalogPricingSucceeded, extractUsageExtrasFromRouterResponse, buildTraceUsageSummary, enrichTraceAttemptsWithBilling, pickEnhancedOpenRouterMetadata, hasNonZeroTokenUsage, MODEL_PROFILE_UNROUTABLE, ModelProfileUnroutableError, ModelProfileInputRejectedError, buildGatewayFallbackAttemptsFromTrace, formatFallbackExhaustionMessage, enrichGatewayFallbackExhaustedError, logResolvedModelRouting, mapGatewayFallbackAttemptsToRouter } from './gateway-utils.js';
 export { getGatewayOperationalMode, isProdGatewayMode, parseModelProviderSpec } from './gateway-mode.js';
 export { DEFAULT_ACTIVITY_FULL_RESPONSE_MAX_CHARS, GATEWAY_DEFAULT_FREQUENCY_PENALTY, GATEWAY_DEFAULT_PRESENCE_PENALTY, GATEWAY_DEFAULT_RETRY, GATEWAY_DEFAULT_TEMPERATURE, GATEWAY_DEFAULT_TOP_P, resolveRetryConfig } from './gateway-defaults.js';
 export { contractSpecToFieldKeys, enrichParsedContentForOutputContract, resolveOutputContractFieldKeys } from './output-contract-normalizer.js';

package/dist-cjs/index.d.ts

@@ -9,7 +9,7 @@ export { LLMProviderRouter } from '@x12i/ai-providers-router';
 export type { RouterConfig, HealthCheckResult } from '@x12i/ai-providers-router';
 export { createRouter, createRouterFromConfig } from '@x12i/ai-providers-router';
 export type { CreateRouterConfig } from '@x12i/ai-providers-router';
-export { ProviderNotFoundError, FallbackExhaustedError } from '@x12i/ai-providers-router';
+export { ProviderNotFoundError, FallbackExhaustedError, OpenRouterApiKeyMissingError, } from '@x12i/ai-providers-router';
 export type { RequestInterceptor, ResponseInterceptor } from '@x12i/ai-providers-router';
 export type { UsageTracker } from '@x12i/ai-providers-router';
 export * from '@x12i/ai-providers-router';
@@ -19,7 +19,7 @@ export { normalizeInvokeModelAtIngress } from './invoke-model-ingress.js';
 export { autoRegisterProviders } from './gateway-provider-auto-register.js';
 export { registerOpenRouterRuntime, shouldUseOpenRouterRuntime, mapGatewayServerTools, } from './openrouter-runtime-adapter/index.js';
 export type { GatewayConfig, ProviderModelRef, ModelConfig, GatewayModelConfig, GatewayServerToolsConfig, GatewayServerToolMode, GatewayServerToolUsage, GatewayNestedServerTool, GatewayWebSearchToolConfig, GatewayWebFetchToolConfig, GatewayDatetimeToolConfig, GatewayImageGenerationToolConfig, GatewayApplyPatchToolConfig, GatewayFusionToolConfig, GatewayAdvisorToolConfig, GatewaySubagentToolConfig, GatewayOpenRouterErrorMetadata, GatewayOpenRouterConfig, GatewayOpenRouterRuntimeConfig, GatewayServerToolUsageMap, GatewayCitation, GatewayGeneratedImage, GatewayPatchProposal, GatewayOpenRouterRuntimeMetadata, RetryConfig, ChatRequest, AIInvokeRequest, AIRequest, GatewayActionType, GatewayInvokeRejectionMetadata, GatewayFallbackAttempt, GatewayTraceRequestIds, GatewayTraceAttempt, GatewayTraceUsageSummary, GatewayTraceMergedConfig, EnhancedLLMResponse, InstructionMetadata, ValidationRule, TemplateRenderOptions, SmartInputConfig, SmartInputRenderOptions } from './types.js';
-export { attachGatewayInvokeRejectionMetadata, buildInvokeRejectionMetadata, tryExtractRouterLikePayloadFromErrorChain, tryExtractOpenRouterMetadataFromErrorChain, tryExtractFallbackAttemptsFromErrorChain, pickRequestIdsFromRouterLike, resolveActivityCostCompletion, resolveCostCompletionForActivity, resolveCostCompletionWithAiTools, buildGatewayPricingRecord, mapAiCostResultToResolvedActivityCost, catalogPricingSucceeded, extractUsageExtrasFromRouterResponse, buildTraceUsageSummary, enrichTraceAttemptsWithBilling, pickEnhancedOpenRouterMetadata, hasNonZeroTokenUsage, MODEL_PROFILE_UNROUTABLE, ModelProfileUnroutableError, ModelProfileInputRejectedError, buildGatewayFallbackAttemptsFromTrace, formatFallbackExhaustionMessage, logResolvedModelRouting, mapGatewayFallbackAttemptsToRouter } from './gateway-utils.js';
+export { attachGatewayInvokeRejectionMetadata, buildInvokeRejectionMetadata, tryExtractRouterLikePayloadFromErrorChain, tryExtractOpenRouterMetadataFromErrorChain, tryExtractFallbackAttemptsFromErrorChain, pickRequestIdsFromRouterLike, resolveActivityCostCompletion, resolveCostCompletionForActivity, resolveCostCompletionWithAiTools, buildGatewayPricingRecord, mapAiCostResultToResolvedActivityCost, catalogPricingSucceeded, extractUsageExtrasFromRouterResponse, buildTraceUsageSummary, enrichTraceAttemptsWithBilling, pickEnhancedOpenRouterMetadata, hasNonZeroTokenUsage, MODEL_PROFILE_UNROUTABLE, ModelProfileUnroutableError, ModelProfileInputRejectedError, buildGatewayFallbackAttemptsFromTrace, formatFallbackExhaustionMessage, enrichGatewayFallbackExhaustedError, logResolvedModelRouting, mapGatewayFallbackAttemptsToRouter } from './gateway-utils.js';
 export { getGatewayOperationalMode, isProdGatewayMode, parseModelProviderSpec } from './gateway-mode.js';
 export type { GatewayOperationalMode } from './gateway-mode.js';
 export { DEFAULT_ACTIVITY_FULL_RESPONSE_MAX_CHARS, GATEWAY_DEFAULT_FREQUENCY_PENALTY, GATEWAY_DEFAULT_PRESENCE_PENALTY, GATEWAY_DEFAULT_RETRY, GATEWAY_DEFAULT_TEMPERATURE, GATEWAY_DEFAULT_TOP_P, resolveRetryConfig } from './gateway-defaults.js';

package/dist-cjs/types.d.ts

@@ -359,6 +359,21 @@ export type GatewayInvokeRejectionMetadata = {
      * Sourced from {@link FallbackExhaustedError.attempts} on the router error chain.
      */
     fallbackAttempts?: GatewayFallbackAttempt[];
+    /**
+     * Structured per-attempt diagnostics (`@x12i/ai-providers-router` ≥ 4.10).
+     * Same attempts as {@link fallbackAttempts} when enriched; prefer this for UIs.
+     */
+    providerAttempts?: Array<{
+        provider: string;
+        modelId?: string;
+        httpStatus?: number;
+        message: string;
+        code?: string;
+    }>;
+    /** Dominant stable failure sub-code when fallback chain exhausts (router ≥ 4.10). */
+    providerSubCode?: string;
+    /** Short remediation hint from router enrichment (router ≥ 4.10). */
+    operatorHint?: string;
     /**
      * 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.
@@ -378,6 +393,8 @@ export type GatewayFallbackAttempt = {
     model?: string;
     httpStatus?: number;
     error: string;
+    /** Stable sub-code from `@x12i/ai-providers-router` ≥ 4.10 (`PROVIDER_AUTH_FAILED`, …). */
+    code?: string;
     responsePreview?: string;
 };
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x12i/ai-gateway",
-  "version": "10.4.3",
+  "version": "10.4.4",
   "description": "AI Gateway - Unified interface for LLM provider routing and management",
   "type": "module",
   "exports": {
@@ -44,11 +44,11 @@
   "dependencies": {
     "@x12i/activix": "^9.0.2",
     "@x12i/ai-profiles": "^3.4.1",
-    "@x12i/ai-providers-router": "^4.9.2",
+    "@x12i/ai-providers-router": "^4.10.0",
     "@x12i/ai-tools": "^3.3.5",
     "@x12i/flex-md": "^4.8.0",
     "@x12i/logxer": "^5.1.0",
-    "@x12i/openrouter-runtime": "^1.0.3",
+    "@x12i/openrouter-runtime": "^1.0.4",
     "@x12i/rendrix": "^4.3.0"
   },
   "devDependencies": {