@x12i/ai-gateway 10.4.1 → 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
@@ -438,8 +449,34 @@ Tool usage and artifacts appear under:
 - `response.metadata.patchProposals`
 - `response.metadata.openrouterRuntime`
 
+In **`diagnostics.mode: 'trace'`**, mirrors may also appear on **`response.metadata.usage.serverTools`** and **`response.metadata.usage.citations`**. Per-attempt slices are on **`metadata.attempts[n].openrouterRuntime`**.
+
+On failure, OpenRouter tool metadata is preserved on **`error.metadata`** (see [AI_GATEWAY_INVOKE_EXECUTION_METADATA.md](./docs/AI_GATEWAY_INVOKE_EXECUTION_METADATA.md)).
+
 Cost remains under `response.metadata.costUsd`, `response.metadata.costStatus`, and `response.metadata.tokens`.
 
+### Config merge precedence
+
+At invoke, gateway merges server-tool intent in this order (later wins):
+
+1. `GatewayConfig.defaultServerTools` / `openrouterRuntime` defaults
+2. `request.config.serverTools` / `request.config.openrouter`
+3. `request.modelConfig.serverTools` / `request.modelConfig.openrouter`
+
+Gateway then applies **post-routing policy** internally (`applyPostRoutingServerToolsPolicy`): required tools force `provider=openrouter`; `allowed` tools on non-OpenRouter providers are stripped with a warning. **Do not duplicate post-routing policy in consumers** — merge pre-invoke intent only.
+
+### Stable error codes
+
+| Code | When |
+|------|------|
+| `SERVER_TOOL_REQUIRES_OPENROUTER_PROVIDER` | Not thrown — gateway **forces** `provider=openrouter` when required tools are configured and a key is present |
+| `OPENROUTER_SERVER_TOOL_REQUIRES_KEY` | Required tools but no OpenRouter key (`codeAliases` includes `OPENROUTER_SERVER_TOOL_REQUIRES_OPENROUTER_KEY`) |
+| `WEB_SEARCH_REQUIRED_BUT_NOT_USED`, etc. | From `@x12i/openrouter-runtime` policy → `GatewayPolicyViolationError.code` and `error.metadata.openrouterRuntime.policyViolations` |
+| `CITATIONS_REQUIRED_BUT_MISSING` | `@x12i/openrouter-runtime` ≥ **1.0.3** policy when `webSearch.requireCitations: true` (or global default) and search used with no citations |
+| `APPLY_PATCH_REQUIRES_RESPONSES_API` | `applyPatch` with `openrouter.apiMode: 'chat'` |
+
+OpenRouter runtime is configured with **`onPolicyViolation: 'throw'`** so required-tool violations surface as **`policy_violation`** responses mapped to gateway errors.
+
 ---
 
 ## Documentation index

package/dist/activity-manager.js

@@ -244,20 +244,23 @@ function pickActivixCompletionRoutingMetadata(response) {
                 out.citationCount = citations.length;
             }
             const serverTools = m.serverTools;
+            if (serverTools != null && typeof serverTools === 'object') {
+                out.serverTools = serverTools;
+            }
             const generatedImages = m.generatedImages;
             const patchProposals = m.patchProposals;
+            if (Array.isArray(generatedImages) && generatedImages.length) {
+                out.generatedImageCount = generatedImages.length;
+            }
+            if (Array.isArray(patchProposals) && patchProposals.length) {
+                out.patchProposalCount = patchProposals.length;
+            }
             const openrouterRuntime = m.openrouterRuntime;
-            if (serverTools != null ||
-                openrouterRuntime != null ||
-                (Array.isArray(generatedImages) && generatedImages.length) ||
-                (Array.isArray(patchProposals) && patchProposals.length)) {
+            if (openrouterRuntime != null && typeof openrouterRuntime === 'object') {
+                const ort = openrouterRuntime;
                 out.openrouterRuntime = {
-                    ...(openrouterRuntime != null && typeof openrouterRuntime === 'object'
-                        ? {
-                            apiMode: openrouterRuntime.apiMode,
-                            serverTools,
-                        }
-                        : { serverTools }),
+                    ...(typeof ort.apiMode === 'string' ? { apiMode: ort.apiMode } : {}),
+                    ...(Array.isArray(ort.warnings) ? { warnings: ort.warnings } : {}),
                     citationCount: Array.isArray(citations) ? citations.length : 0,
                     generatedImageCount: Array.isArray(generatedImages) ? generatedImages.length : 0,
                     patchProposalCount: Array.isArray(patchProposals) ? patchProposals.length : 0,
@@ -948,6 +951,14 @@ export class ActivityManager {
             const outerMetadata = pickActivixCompletionRoutingMetadata(details.response);
             const outerCost = buildActivixOuterCost(outerMetadata, billingSlice, details.response);
             const recordMetadata = buildActivixRecordMetadata(details.response, billingSlice);
+            const outerOutput = details.response != null && typeof details.response === 'object'
+                ? {
+                    ...details.response,
+                    ...(Array.isArray(outerMetadata.citations) && outerMetadata.citations.length
+                        ? { citations: outerMetadata.citations }
+                        : {}),
+                }
+                : details.response;
             await this.activix.completeRecord(activity.activityId, {
                 cost: details.cost,
                 ...(typeof details.cost === 'number' && Number.isFinite(details.cost)
@@ -957,10 +968,10 @@ export class ActivityManager {
                 response: details.response,
                 ...(Object.keys(recordMetadata).length > 0 ? { metadata: recordMetadata } : {}),
                 outer: {
-                    output: details.response,
+                    output: outerOutput,
                     metadata: outerMetadata,
-                    ...(outerCost ? { cost: outerCost } : {})
-                }
+                    ...(outerCost ? { cost: outerCost } : {}),
+                },
             }, { collection });
             this.logger.debug('Activix.completeRecord completed', {
                 aiRequestId: activity.aiRequestId,

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';
@@ -158,7 +160,7 @@ export declare function pickInvokeRoutingMetadataSlice(routerResponse: unknown,
 /**
  * Allowlisted generation profile from merged config for client introspection (no secrets, no arbitrary extras).
  */
-export declare function pickEffectiveModelConfigForMetadata(mergedConfig: unknown): Partial<Pick<ModelConfig, 'model' | 'modelId' | 'provider' | 'temperature' | 'maxTokens' | 'topP'>> | undefined;
+export declare function pickEffectiveModelConfigForMetadata(mergedConfig: unknown): Partial<Pick<ModelConfig, 'model' | 'modelId' | 'provider' | 'temperature' | 'maxTokens' | 'topP' | 'serverTools' | 'openrouter'>> | undefined;
 /**
  * Allowlisted snapshot of merged router config for diagnostics trace responses (no arbitrary extras).
  */
@@ -174,6 +176,8 @@ export declare function pickEffectiveModelConfigFromInvokeRequest(request: Pick<
  * to find a router-shaped object for token / correlation extraction.
  */
 export declare function tryExtractRouterLikePayloadFromErrorChain(error: unknown, maxDepth?: number): unknown;
+/** Extract OpenRouter tool metadata from invoke error chains (policy errors, partial router bodies). */
+export declare function tryExtractOpenRouterMetadataFromErrorChain(error: unknown, maxDepth?: number): ReturnType<typeof pickEnhancedOpenRouterMetadata>;
 export declare function pickRequestIdsFromRouterLike(gatewayAiRequestId: string | undefined, routerLike: unknown): GatewayTraceRequestIds | undefined;
 type ModelResolutionCandidate = {
     provider: string;
@@ -189,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,11 +3,11 @@
  * 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';
-import { MaxTokensRequiredError, ModelRequiredError, } from './instruction-errors.js';
+import { MaxTokensRequiredError, ModelRequiredError, GatewayPolicyViolationError, } from './instruction-errors.js';
 import { normalizeInvokeModelAtIngress } from './invoke-model-ingress.js';
 import { applyOnlineVariantMigration, applyPostRoutingServerToolsPolicy, mergeOpenRouterConfig, mergeServerToolsConfig, normalizeApplyPatchDefaults, resolveOpenRouterRuntimeDefaults, pickOpenRouterRuntimeMetadataSlice, enrichTraceOpenRouterRuntimeMetadata, } from './openrouter-runtime-adapter/index.js';
 import { DEFAULT_ACTIVITY_FULL_RESPONSE_MAX_CHARS, GATEWAY_DEFAULT_FREQUENCY_PENALTY, GATEWAY_DEFAULT_PRESENCE_PENALTY, GATEWAY_DEFAULT_TEMPERATURE, GATEWAY_DEFAULT_TOP_P } from './gateway-defaults.js';
@@ -626,7 +626,9 @@ function buildTraceAttemptPricingRecord(attempt, mergedConfig) {
  * Trace-mode summary: final token usage + resolved billing (after catalog pricing when applicable).
  */
 export function buildTraceUsageSummary(tokens, billing, maxTokensRequested, openrouterExtras) {
-    if (!hasNonZeroTokenUsage(tokens) && !billing.costStatus) {
+    const hasOpenRouterMirror = openrouterExtras?.serverTools != null ||
+        (openrouterExtras?.citations?.length ?? 0) > 0;
+    if (!hasNonZeroTokenUsage(tokens) && !billing.costStatus && !hasOpenRouterMirror) {
         return undefined;
     }
     const summary = { tokens };
@@ -643,7 +645,7 @@ export function buildTraceUsageSummary(tokens, billing, maxTokensRequested, open
     if (billing.costBreakdown) {
         summary.costBreakdown = billing.costBreakdown;
     }
-    if (openrouterExtras?.serverTools)
+    if (openrouterExtras?.serverTools != null)
         summary.serverTools = openrouterExtras.serverTools;
     if (openrouterExtras?.citations?.length)
         summary.citations = openrouterExtras.citations;
@@ -729,7 +731,16 @@ export function pickEffectiveModelConfigForMetadata(mergedConfig) {
     if (mergedConfig == null || typeof mergedConfig !== 'object')
         return undefined;
     const c = mergedConfig;
-    const keys = ['model', 'modelId', 'provider', 'temperature', 'maxTokens', 'topP'];
+    const keys = [
+        'model',
+        'modelId',
+        'provider',
+        'temperature',
+        'maxTokens',
+        'topP',
+        'serverTools',
+        'openrouter',
+    ];
     const out = {};
     for (const k of keys) {
         const v = c[k];
@@ -822,10 +833,64 @@ export function tryExtractRouterLikePayloadFromErrorChain(error, maxDepth = 8) {
             if (isRouterLikeEnvelope(n))
                 return n;
         }
+        const rejMeta = o.metadata;
+        if (rejMeta != null && typeof rejMeta === 'object' && isRouterLikeEnvelope({ metadata: rejMeta })) {
+            return { metadata: rejMeta };
+        }
+        if (cur instanceof GatewayPolicyViolationError && cur.routerMetadata) {
+            return { metadata: cur.routerMetadata };
+        }
         cur = o.cause;
     }
     return undefined;
 }
+/** Extract OpenRouter tool metadata from invoke error chains (policy errors, partial router bodies). */
+export function tryExtractOpenRouterMetadataFromErrorChain(error, maxDepth = 8) {
+    const partial = tryExtractRouterLikePayloadFromErrorChain(error, maxDepth);
+    if (partial !== undefined) {
+        const fromPartial = pickEnhancedOpenRouterMetadata(partial, false);
+        if (fromPartial.serverTools ||
+            fromPartial.openrouterRuntime ||
+            (fromPartial.citations?.length ?? 0) > 0 ||
+            (fromPartial.generatedImages?.length ?? 0) > 0 ||
+            (fromPartial.patchProposals?.length ?? 0) > 0) {
+            return fromPartial;
+        }
+    }
+    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);
+        if (cur instanceof GatewayPolicyViolationError && cur.routerMetadata) {
+            return {
+                serverTools: cur.routerMetadata.serverTools,
+                citations: cur.routerMetadata.citations,
+                generatedImages: cur.routerMetadata.generatedImages,
+                patchProposals: cur.routerMetadata.patchProposals,
+                openrouterRuntime: cur.routerMetadata.openrouterRuntime,
+            };
+        }
+        const rejMeta = cur.metadata;
+        if (rejMeta &&
+            (rejMeta.serverTools ||
+                rejMeta.openrouterRuntime ||
+                (rejMeta.citations?.length ?? 0) > 0)) {
+            return {
+                serverTools: rejMeta.serverTools,
+                citations: rejMeta.citations,
+                generatedImages: rejMeta.generatedImages,
+                patchProposals: rejMeta.patchProposals,
+                openrouterRuntime: rejMeta.openrouterRuntime,
+            };
+        }
+        cur = cur.cause;
+    }
+    return {};
+}
 export function pickRequestIdsFromRouterLike(gatewayAiRequestId, routerLike) {
     if (typeof gatewayAiRequestId !== 'string' || gatewayAiRequestId.length === 0) {
         return undefined;
@@ -915,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.
  */
@@ -944,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);
         }
@@ -999,6 +1109,33 @@ 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 = {
+        ...openrouterFromPartial,
+        ...(openrouterFromError.serverTools ? { serverTools: openrouterFromError.serverTools } : {}),
+        ...(openrouterFromError.citations?.length ? { citations: openrouterFromError.citations } : {}),
+        ...(openrouterFromError.generatedImages?.length
+            ? { generatedImages: openrouterFromError.generatedImages }
+            : {}),
+        ...(openrouterFromError.patchProposals?.length
+            ? { patchProposals: openrouterFromError.patchProposals }
+            : {}),
+        ...(openrouterFromError.openrouterRuntime
+            ? { openrouterRuntime: openrouterFromError.openrouterRuntime }
+            : {}),
+    };
     return {
         aiRequestId: args.request.aiRequestId,
         identity: args.request.identity,
@@ -1009,7 +1146,24 @@ export function buildInvokeRejectionMetadata(args) {
         ...(tokens !== undefined ? { tokens } : {}),
         ...(requestIds !== undefined ? { requestIds } : {}),
         ...(fallbackAttempts !== undefined ? { fallbackAttempts } : {}),
-        ...(mc === undefined ? { mergeConfigUnavailable: true } : {})
+        ...(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 } : {}),
+        ...(openrouterMetadata.generatedImages?.length
+            ? { generatedImages: openrouterMetadata.generatedImages }
+            : {}),
+        ...(openrouterMetadata.patchProposals?.length
+            ? { patchProposals: openrouterMetadata.patchProposals }
+            : {}),
+        ...(openrouterMetadata.openrouterRuntime
+            ? { openrouterRuntime: openrouterMetadata.openrouterRuntime }
+            : {}),
+        ...(openrouterMetadata.openrouterRuntime?.policyViolations?.length
+            ? { policyViolations: openrouterMetadata.openrouterRuntime.policyViolations }
+            : {}),
     };
 }
 export function attachGatewayInvokeRejectionMetadata(err, metadata) {

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 } 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';
@@ -479,6 +479,10 @@ export class AIGateway {
                                     }
                                     else if (tryErr) {
                                         a.error = { name: tryErr.name || 'Error', message: capErrorMessage(tryErr.message || String(tryErr)) };
+                                        const errOpenRouter = tryExtractOpenRouterMetadataFromErrorChain(tryErr);
+                                        const runtimeSlice = buildTraceAttemptOpenRouterRuntimeSlice(errOpenRouter);
+                                        if (runtimeSlice)
+                                            a.openrouterRuntime = runtimeSlice;
                                     }
                                 }
                             });
@@ -508,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;
@@ -745,6 +749,22 @@ export class AIGateway {
                     error: err
                 });
                 attachGatewayInvokeRejectionMetadata(err, rejectMeta);
+                if (this.activityManager && activity) {
+                    try {
+                        await this.activityManager.logFailure(activity, err, {
+                            endTime: Date.now(),
+                            duration: Date.now() - startTime,
+                            error: err.message,
+                            response: { metadata: rejectMeta },
+                        });
+                    }
+                    catch (activityError) {
+                        this.logger.warn('Failed to track activity failure', {
+                            aiRequestId: request.aiRequestId,
+                            error: activityError instanceof Error ? activityError.message : String(activityError),
+                        });
+                    }
+                }
                 if (err.message.includes(NO_PROVIDER_ERROR)) {
                     const wrapped = new Error(err.message + NO_PROVIDER_HINT);
                     wrapped.cause = err;

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';
@@ -18,8 +18,8 @@ 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 type { GatewayConfig, ProviderModelRef, ModelConfig, GatewayModelConfig, GatewayServerToolsConfig, 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, 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 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, 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, 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/instruction-errors.d.ts

@@ -1,6 +1,7 @@
 /**
  * Errors for instruction / prompt template resolution.
  */
+import type { GatewayOpenRouterErrorMetadata } from './types.js';
 export declare class ModelRequiredError extends Error {
     readonly code = "MODEL_REQUIRED";
     constructor(message?: string);
@@ -20,7 +21,11 @@ export declare class GatewayValidationError extends Error {
 }
 export declare class ProviderConfigError extends Error {
     readonly code: string;
-    constructor(code: string, message: string);
+    /** Stable alternate codes documented for upstream consumers (e.g. CR-GW-ST-001). */
+    readonly codeAliases?: readonly string[];
+    constructor(code: string, message: string, options?: {
+        codeAliases?: readonly string[];
+    });
 }
 export declare class ProviderInvokeError extends Error {
     readonly code: string;
@@ -33,7 +38,11 @@ export declare class ProviderInvokeError extends Error {
 }
 export declare class GatewayPolicyViolationError extends Error {
     readonly code: string;
-    constructor(code: string, message: string);
+    /** Partial OpenRouter tool metadata preserved when policy fails after a runtime response. */
+    routerMetadata?: GatewayOpenRouterErrorMetadata;
+    constructor(code: string, message: string, options?: {
+        routerMetadata?: GatewayOpenRouterErrorMetadata;
+    });
 }
 export declare class InstructionNotFoundError extends Error {
     key: string;

package/dist/instruction-errors.js

@@ -35,10 +35,13 @@ export class GatewayValidationError extends Error {
 }
 export class ProviderConfigError extends Error {
     code;
-    constructor(code, message) {
+    /** Stable alternate codes documented for upstream consumers (e.g. CR-GW-ST-001). */
+    codeAliases;
+    constructor(code, message, options) {
         super(message);
         this.name = 'ProviderConfigError';
         this.code = code;
+        this.codeAliases = options?.codeAliases;
     }
 }
 export class ProviderInvokeError extends Error {
@@ -55,10 +58,13 @@ export class ProviderInvokeError extends Error {
 }
 export class GatewayPolicyViolationError extends Error {
     code;
-    constructor(code, message) {
+    /** Partial OpenRouter tool metadata preserved when policy fails after a runtime response. */
+    routerMetadata;
+    constructor(code, message, options) {
         super(message);
         this.name = 'GatewayPolicyViolationError';
         this.code = code;
+        this.routerMetadata = options?.routerMetadata;
     }
 }
 export class InstructionNotFoundError extends Error {

package/dist/openrouter-runtime-adapter/create-openrouter-runtime-provider.js

@@ -7,7 +7,7 @@ export function createOpenRouterRuntimeProvider(options) {
             apiKey: options.apiKey,
             defaults: {
                 retry: { enabled: false },
-                onPolicyViolation: 'return_error',
+                onPolicyViolation: 'throw',
             },
         });
     return {

package/dist/openrouter-runtime-adapter/index.d.ts

@@ -3,6 +3,6 @@ export { createOpenRouterRuntimeProvider } from './create-openrouter-runtime-pro
 export { createOpenRouterRuntimeAdapter } from './create-openrouter-runtime-adapter.js';
 export { mapGatewayServerTools } from './map-server-tools.js';
 export { mapGatewayRequestToRuntimeRequest } from './map-gateway-request.js';
-export { pickOpenRouterRuntimeMetadataSlice, extractOpenRouterRuntimeRouterMetadata, parseRuntimeResponseToAIResponse, } from './map-runtime-response.js';
+export { buildPartialMetadataFromRuntimeResponse, buildRouterLikeEnvelopeFromRuntimeResponse, pickOpenRouterRuntimeMetadataSlice, extractOpenRouterRuntimeRouterMetadata, parseRuntimeResponseToAIResponse, } from './map-runtime-response.js';
 export { applyOnlineVariantMigration, applyPostRoutingServerToolsPolicy, mergeOpenRouterConfig, mergeServerToolsConfig, normalizeApplyPatchDefaults, validateApplyPatchConfig, hasAnyActiveServerTool, hasRequiredServerTool, } from './validate-server-tools.js';
 export { buildTraceAttemptOpenRouterRuntimeSlice, enrichTraceOpenRouterRuntimeMetadata, redactRawOpenRouterPayload, } from './map-trace.js';

package/dist/openrouter-runtime-adapter/index.js

@@ -3,6 +3,6 @@ export { createOpenRouterRuntimeProvider } from './create-openrouter-runtime-pro
 export { createOpenRouterRuntimeAdapter } from './create-openrouter-runtime-adapter.js';
 export { mapGatewayServerTools } from './map-server-tools.js';
 export { mapGatewayRequestToRuntimeRequest } from './map-gateway-request.js';
-export { pickOpenRouterRuntimeMetadataSlice, extractOpenRouterRuntimeRouterMetadata, parseRuntimeResponseToAIResponse, } from './map-runtime-response.js';
+export { buildPartialMetadataFromRuntimeResponse, buildRouterLikeEnvelopeFromRuntimeResponse, pickOpenRouterRuntimeMetadataSlice, extractOpenRouterRuntimeRouterMetadata, parseRuntimeResponseToAIResponse, } from './map-runtime-response.js';
 export { applyOnlineVariantMigration, applyPostRoutingServerToolsPolicy, mergeOpenRouterConfig, mergeServerToolsConfig, normalizeApplyPatchDefaults, validateApplyPatchConfig, hasAnyActiveServerTool, hasRequiredServerTool, } from './validate-server-tools.js';
 export { buildTraceAttemptOpenRouterRuntimeSlice, enrichTraceOpenRouterRuntimeMetadata, redactRawOpenRouterPayload, } from './map-trace.js';