@x12i/ai-gateway 9.1.0 → 9.1.2

package/dist/gateway-utils.d.ts

@@ -2,7 +2,7 @@
  * Gateway Utilities Module
  * Handles utility functions
  */
-import type { ChatRequest, GatewayConfig } from './types.js';
+import type { AIInvokeRequest, ChatRequest, GatewayConfig, GatewayInvokeRejectionMetadata, GatewayTraceRequestIds, ModelConfig } from './types.js';
 import type { Logxer } from '@x12i/logxer';
 /**
  * Generates MD5 hash of a string
@@ -43,6 +43,41 @@ export declare function extractTokenUsageFromRouterResponse(routerResponse: unkn
  * Does not compute cost from tokens — adapters must populate normalized fields or raw usage.cost-style keys.
  */
 export declare function extractCostUsdFromRouterResponse(routerResponse: unknown): number | undefined;
+/**
+ * Stable routing facts for gateway response metadata (router metadata + merged config fallbacks).
+ * Matches trace-mode resolution; intended for every successful invoke(), not only diagnostics.trace.
+ */
+export declare function pickInvokeRoutingMetadataSlice(routerResponse: unknown, mergedConfig: unknown): Partial<{
+    provider: string;
+    modelUsed: string;
+    maxTokensRequested: number;
+    region: string;
+}>;
+/**
+ * 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;
+declare const EFFECTIVE_MODEL_CONFIG_KEYS: readonly ["model", "modelId", "provider", "temperature", "maxTokens", "topP"];
+/**
+ * Allowlisted generation fields from request only (before mergeConfig / flex-md).
+ * Priority matches mergeConfig: modelConfig overrides request.config per key.
+ */
+export declare function pickEffectiveModelConfigFromInvokeRequest(request: Pick<AIInvokeRequest, 'config' | 'modelConfig'>): Partial<Pick<ModelConfig, (typeof EFFECTIVE_MODEL_CONFIG_KEYS)[number]>> | undefined;
+/**
+ * Walk `error`, optional `error.cause`, and common adapter fields (`response`, `routerResponse`, …)
+ * to find a router-shaped object for token / correlation extraction.
+ */
+export declare function tryExtractRouterLikePayloadFromErrorChain(error: unknown, maxDepth?: number): unknown;
+export declare function pickRequestIdsFromRouterLike(gatewayAiRequestId: string | undefined, routerLike: unknown): GatewayTraceRequestIds | undefined;
+export declare function buildInvokeRejectionMetadata(args: {
+    request: Pick<AIInvokeRequest, 'aiRequestId' | 'identity' | 'config' | 'modelConfig'>;
+    taskTypeId: string;
+    startTime: number;
+    mergedConfig?: unknown;
+    partialRouterPayload?: unknown;
+    gatewayAiRequestId?: string;
+}): GatewayInvokeRejectionMetadata;
+export declare function attachGatewayInvokeRejectionMetadata(err: Error, metadata: GatewayInvokeRejectionMetadata): void;
 /** Default JSON string length cap for Activix `content.fullResponse` when diagnostics allow storing it. */
 export declare const DEFAULT_ACTIVITY_FULL_RESPONSE_MAX_CHARS = 512000;
 /**
@@ -50,3 +85,4 @@ export declare const DEFAULT_ACTIVITY_FULL_RESPONSE_MAX_CHARS = 512000;
  * Non-serializable values become a small marker object instead of throwing.
  */
 export declare function capActivityFullResponsePayload(payload: unknown, maxChars?: number): unknown;
+export {};

package/dist/gateway-utils.js

@@ -315,6 +315,157 @@ export function extractCostUsdFromRouterResponse(routerResponse) {
     }
     return undefined;
 }
+/**
+ * Stable routing facts for gateway response metadata (router metadata + merged config fallbacks).
+ * Matches trace-mode resolution; intended for every successful invoke(), not only diagnostics.trace.
+ */
+export function pickInvokeRoutingMetadataSlice(routerResponse, mergedConfig) {
+    const rr = routerResponse != null && typeof routerResponse === 'object' ? routerResponse : {};
+    const meta = rr.metadata != null && typeof rr.metadata === 'object' ? rr.metadata : {};
+    const cfg = mergedConfig != null && typeof mergedConfig === 'object' ? mergedConfig : {};
+    const provider = meta.provider || rr.provider || cfg.provider;
+    const modelUsed = meta.modelUsed || meta.model || rr.model || cfg.model;
+    const maxTokensRequested = typeof meta.maxTokensRequested === 'number'
+        ? meta.maxTokensRequested
+        : typeof cfg.maxTokens === 'number'
+            ? cfg.maxTokens
+            : undefined;
+    const region = typeof meta.region === 'string' ? meta.region : undefined;
+    const out = {};
+    if (provider !== undefined && provider !== null)
+        out.provider = provider;
+    if (modelUsed !== undefined && modelUsed !== null)
+        out.modelUsed = modelUsed;
+    if (maxTokensRequested !== undefined)
+        out.maxTokensRequested = maxTokensRequested;
+    if (region !== undefined)
+        out.region = region;
+    return out;
+}
+/**
+ * Allowlisted generation profile from merged config for client introspection (no secrets, no arbitrary extras).
+ */
+export function pickEffectiveModelConfigForMetadata(mergedConfig) {
+    if (mergedConfig == null || typeof mergedConfig !== 'object')
+        return undefined;
+    const c = mergedConfig;
+    const keys = ['model', 'modelId', 'provider', 'temperature', 'maxTokens', 'topP'];
+    const out = {};
+    for (const k of keys) {
+        const v = c[k];
+        if (v !== undefined)
+            out[k] = v;
+    }
+    return Object.keys(out).length ? out : undefined;
+}
+const EFFECTIVE_MODEL_CONFIG_KEYS = ['model', 'modelId', 'provider', 'temperature', 'maxTokens', 'topP'];
+/**
+ * Allowlisted generation fields from request only (before mergeConfig / flex-md).
+ * Priority matches mergeConfig: modelConfig overrides request.config per key.
+ */
+export function pickEffectiveModelConfigFromInvokeRequest(request) {
+    const cfg = (request.config ?? {});
+    const mc = (request.modelConfig ?? {});
+    const out = {};
+    for (const k of EFFECTIVE_MODEL_CONFIG_KEYS) {
+        const v = mc[k] ?? cfg[k];
+        if (v !== undefined)
+            out[k] = v;
+    }
+    const modelFromId = out.model === undefined && typeof mc.modelId === 'string' ? mc.modelId : undefined;
+    if (modelFromId !== undefined)
+        out.model = modelFromId;
+    return Object.keys(out).length ? out : undefined;
+}
+function isRouterLikeEnvelope(value) {
+    if (value == null || typeof value !== 'object')
+        return false;
+    const r = value;
+    return ('metadata' in r ||
+        'outputText' in r ||
+        'content' in r ||
+        'requestId' in r ||
+        'usage' in r);
+}
+/**
+ * Walk `error`, optional `error.cause`, and common adapter fields (`response`, `routerResponse`, …)
+ * to find a router-shaped object for token / correlation extraction.
+ */
+export function tryExtractRouterLikePayloadFromErrorChain(error, maxDepth = 8) {
+    const seen = new Set();
+    let cur = error;
+    for (let i = 0; i < maxDepth && cur != null; i++) {
+        if (typeof cur !== 'object')
+            break;
+        if (seen.has(cur))
+            break;
+        seen.add(cur);
+        const o = cur;
+        if (isRouterLikeEnvelope(cur))
+            return cur;
+        const nested = [o.response, o.routerResponse, o.lastResponse, o.body, o.data];
+        for (const n of nested) {
+            if (isRouterLikeEnvelope(n))
+                return n;
+        }
+        cur = o.cause;
+    }
+    return undefined;
+}
+export function pickRequestIdsFromRouterLike(gatewayAiRequestId, routerLike) {
+    if (typeof gatewayAiRequestId !== 'string' || gatewayAiRequestId.length === 0) {
+        return undefined;
+    }
+    const out = { gatewayAiRequestId };
+    if (routerLike == null || typeof routerLike !== 'object') {
+        return out;
+    }
+    const rr = routerLike;
+    const meta = rr.metadata != null && typeof rr.metadata === 'object' ? rr.metadata : {};
+    const routerRequestId = rr.requestId ?? meta.requestId;
+    if (typeof routerRequestId === 'string')
+        out.routerRequestId = routerRequestId;
+    if (typeof meta.providerRequestId === 'string')
+        out.providerRequestId = meta.providerRequestId;
+    if (typeof meta.openrouterRequestId === 'string')
+        out.openrouterRequestId = meta.openrouterRequestId;
+    const nested = meta.requestIds;
+    if (nested != null && typeof nested === 'object') {
+        for (const [k, v] of Object.entries(nested)) {
+            if (typeof v === 'string')
+                out[k] = v;
+        }
+    }
+    return out;
+}
+export function buildInvokeRejectionMetadata(args) {
+    const gid = args.gatewayAiRequestId ?? args.request.aiRequestId;
+    const partial = args.partialRouterPayload;
+    const mc = args.mergedConfig;
+    const routing = pickInvokeRoutingMetadataSlice(partial ?? {}, mc ?? {});
+    const effective = mc !== undefined
+        ? pickEffectiveModelConfigForMetadata(mc)
+        : pickEffectiveModelConfigFromInvokeRequest(args.request);
+    let tokens = partial !== undefined ? extractTokenUsageFromRouterResponse(partial) : undefined;
+    if (tokens && tokens.prompt === 0 && tokens.completion === 0 && tokens.total === 0) {
+        tokens = undefined;
+    }
+    const requestIds = pickRequestIdsFromRouterLike(gid, partial);
+    return {
+        aiRequestId: args.request.aiRequestId,
+        identity: args.request.identity,
+        taskTypeId: args.taskTypeId,
+        latencyMs: Date.now() - args.startTime,
+        ...routing,
+        ...(effective !== undefined ? { effectiveModelConfig: effective } : {}),
+        ...(tokens !== undefined ? { tokens } : {}),
+        ...(requestIds !== undefined ? { requestIds } : {}),
+        ...(mc === undefined ? { mergeConfigUnavailable: true } : {})
+    };
+}
+export function attachGatewayInvokeRejectionMetadata(err, metadata) {
+    err.metadata = metadata;
+}
 /** Default JSON string length cap for Activix `content.fullResponse` when diagnostics allow storing it. */
 export const DEFAULT_ACTIVITY_FULL_RESPONSE_MAX_CHARS = 512_000;
 /**

package/dist/gateway.js

@@ -8,7 +8,7 @@ import { ensureGatewayRequestIdentity } from './activity-manager.js';
 import { initializeGatewayComponents } from './gateway-config.js';
 import { buildMessages } from './message-builder.js';
 import { extractJsonFromFlexMd } from './flex-md-loader.js';
-import { capActivityFullResponsePayload, DEFAULT_ACTIVITY_FULL_RESPONSE_MAX_CHARS, extractCostUsdFromRouterResponse, extractTokenUsageFromRouterResponse, mergeConfig } from './gateway-utils.js';
+import { attachGatewayInvokeRejectionMetadata, buildInvokeRejectionMetadata, capActivityFullResponsePayload, DEFAULT_ACTIVITY_FULL_RESPONSE_MAX_CHARS, extractCostUsdFromRouterResponse, extractTokenUsageFromRouterResponse, mergeConfig, pickEffectiveModelConfigForMetadata, pickInvokeRoutingMetadataSlice, tryExtractRouterLikePayloadFromErrorChain } from './gateway-utils.js';
 import { autoRegisterProviders } from './gateway-provider-auto-register.js';
 import { setGatewayLastJobId, setGatewayRuntimeClients } from './runtime-objects.js';
 import { gatewayLogDebug, withActivityIdentity } from './gateway-log-meta.js';
@@ -223,6 +223,13 @@ export class AIGateway {
                     failureType: 'validation-failure'
                 }, startTime);
             }
+            const rejectMeta = buildInvokeRejectionMetadata({
+                request,
+                taskTypeId,
+                startTime,
+                gatewayAiRequestId: request.aiRequestId
+            });
+            attachGatewayInvokeRejectionMetadata(err, rejectMeta);
             // Re-throw the error so it propagates to the caller
             throw err;
         }
@@ -524,6 +531,8 @@ export class AIGateway {
             }
             const resolvedCostUsd = extractCostUsdFromRouterResponse(routerResponse);
             const routerMetaForCost = routerResponse?.metadata || {};
+            const routingMetadataSlice = pickInvokeRoutingMetadataSlice(routerResponse, mergedConfig);
+            const effectiveModelConfig = pickEffectiveModelConfigForMetadata(mergedConfig);
             const enhancedResponse = {
                 content: content,
                 parsedContent: parsedContent,
@@ -536,6 +545,8 @@ export class AIGateway {
                     agentType: 'ai',
                     contentType,
                     parsingMethod,
+                    ...routingMetadataSlice,
+                    ...(effectiveModelConfig !== undefined ? { effectiveModelConfig } : {}),
                     ...(typeof resolvedCostUsd === 'number'
                         ? {
                             costUsd: resolvedCostUsd,
@@ -545,27 +556,12 @@ export class AIGateway {
                         }
                         : {}),
                     ...(traceEnabled
-                        ? (() => {
-                            const meta = routerResponse?.metadata || {};
-                            const provider = meta.provider || routerResponse?.provider || mergedConfig?.provider;
-                            const region = typeof meta.region === 'string' ? meta.region : undefined;
-                            const modelUsed = meta.modelUsed || meta.model || routerResponse?.model || mergedConfig?.model;
-                            const maxTokensRequested = typeof meta.maxTokensRequested === 'number'
-                                ? meta.maxTokensRequested
-                                : typeof mergedConfig?.maxTokens === 'number'
-                                    ? mergedConfig.maxTokens
-                                    : undefined;
-                            return {
-                                provider,
-                                region,
-                                modelUsed,
-                                maxTokensRequested,
-                                requestIds: traceRequestIds,
-                                retryCount: traceRetryCount,
-                                fallbackCount: traceFallbackCount,
-                                attempts: traceAttempts
-                            };
-                        })()
+                        ? {
+                            requestIds: traceRequestIds,
+                            retryCount: traceRetryCount,
+                            fallbackCount: traceFallbackCount,
+                            attempts: traceAttempts
+                        }
                         : {})
                 }
             };
@@ -622,8 +618,21 @@ export class AIGateway {
         }
         catch (error) {
             const err = error instanceof Error ? error : new Error(String(error));
+            const partial = tryExtractRouterLikePayloadFromErrorChain(err);
+            const rejectMeta = buildInvokeRejectionMetadata({
+                request,
+                taskTypeId,
+                startTime,
+                mergedConfig,
+                partialRouterPayload: partial,
+                gatewayAiRequestId: request.aiRequestId
+            });
+            attachGatewayInvokeRejectionMetadata(err, rejectMeta);
             if (err.message.includes(NO_PROVIDER_ERROR)) {
-                throw new Error(err.message + NO_PROVIDER_HINT);
+                const wrapped = new Error(err.message + NO_PROVIDER_HINT);
+                wrapped.cause = err;
+                attachGatewayInvokeRejectionMetadata(wrapped, rejectMeta);
+                throw wrapped;
             }
             throw err;
         }

package/dist/index.d.ts

@@ -16,7 +16,8 @@ export * from '@x12i/ai-providers-router';
 export { AIGateway } from './gateway.js';
 export { InstructionNotFoundError, InstructionBackendError } from './instruction-errors.js';
 export { autoRegisterProviders } from './gateway-provider-auto-register.js';
-export type { GatewayConfig, ProviderModelRef, ModelConfig, RetryConfig, ChatRequest, AIInvokeRequest, AIRequest, GatewayActionType, EnhancedLLMResponse, InstructionMetadata, ValidationRule, TemplateRenderOptions } from './types.js';
+export type { GatewayConfig, ProviderModelRef, ModelConfig, RetryConfig, ChatRequest, AIInvokeRequest, AIRequest, GatewayActionType, GatewayInvokeRejectionMetadata, GatewayTraceRequestIds, EnhancedLLMResponse, InstructionMetadata, ValidationRule, TemplateRenderOptions } from './types.js';
+export { attachGatewayInvokeRejectionMetadata, buildInvokeRejectionMetadata, tryExtractRouterLikePayloadFromErrorChain, pickRequestIdsFromRouterLike } from './gateway-utils.js';
 export { mergeTemplateRenderOptions } from './template-render-merge.js';
 export type { UsageTier } from './types.js';
 export { Activix } from '@x12i/activix';

package/dist/index.js

@@ -17,6 +17,7 @@ export * from '@x12i/ai-providers-router';
 export { AIGateway } from './gateway.js';
 export { InstructionNotFoundError, InstructionBackendError } from './instruction-errors.js';
 export { autoRegisterProviders } from './gateway-provider-auto-register.js';
+export { attachGatewayInvokeRejectionMetadata, buildInvokeRejectionMetadata, tryExtractRouterLikePayloadFromErrorChain, pickRequestIdsFromRouterLike } from './gateway-utils.js';
 export { mergeTemplateRenderOptions } from './template-render-merge.js';
 // Usage tracking: UsageTracker class methods are available but consumption calculation is disabled
 // (x-models was previously used for RPM/TPM tracking but is no longer integrated)

package/dist/types.d.ts

@@ -84,6 +84,34 @@ export type GatewayTraceAttempt = {
      */
     rawProviderPayload?: unknown;
 };
+/**
+ * Normalized observability payload attached to thrown errors from {@link AIGateway.invoke}
+ * when the gateway can derive fields (merged config, partial router body on error).
+ * SDKs should read `(error as Error & { metadata?: GatewayInvokeRejectionMetadata }).metadata`
+ * (see docs/AI_GATEWAY_INVOKE_EXECUTION_METADATA.md).
+ */
+export type GatewayInvokeRejectionMetadata = {
+    aiRequestId?: string;
+    identity?: ActivityIdentity;
+    taskTypeId?: string;
+    latencyMs?: number;
+    tokens?: {
+        prompt: number;
+        completion: number;
+        total: number;
+    };
+    provider?: string;
+    modelUsed?: string;
+    maxTokensRequested?: number;
+    region?: string;
+    effectiveModelConfig?: Partial<Pick<ModelConfig, 'model' | 'modelId' | 'provider' | 'temperature' | 'maxTokens' | 'topP'>>;
+    requestIds?: GatewayTraceRequestIds;
+    /**
+     * True when {@link mergeConfig} did not run (e.g. message-building threw first).
+     * Routing facts may only reflect request.config / modelConfig, not flex-md defaults.
+     */
+    mergeConfigUnavailable?: true;
+};
 /**
  * Identity object used for activity linkage.
  * On gateway requests/responses it lives on `identity`. When activity tracking persists via Activix v5+,
@@ -876,7 +904,8 @@ export interface EnhancedLLMResponse<TContent = unknown> extends Omit<AIResponse
          */
         model?: string;
         /**
-         * Provider used (e.g., 'openai', 'anthropic')
+         * Provider used (e.g., 'openai', 'anthropic').
+         * Populated on every successful invoke when router or merged config supplies it.
          */
         provider?: string;
         /**
@@ -884,23 +913,30 @@ export interface EnhancedLLMResponse<TContent = unknown> extends Omit<AIResponse
          */
         cost?: number;
         /**
-         * Cost in USD (preferred, stable key for trace mode).
+         * Cost in USD (preferred stable key when the router exposes it).
          * When both are present, costUsd should mirror cost.
          */
         costUsd?: number;
         /**
          * Final effective max token cap applied (after merges/normalization), if known.
+         * Populated on every successful invoke when router or merged config supplies it.
          */
         maxTokensRequested?: number;
         /**
          * Model that actually served the response (after routing/fallback), if known.
          * This is distinct from requested model.
+         * Populated on every successful invoke when router or merged config supplies it.
          */
         modelUsed?: string;
         /**
          * Optional region identifier when applicable (provider-specific).
          */
         region?: string;
+        /**
+         * Sanitized merged generation profile (allowlisted fields only; no secrets).
+         * Reflects gateway merge order: modelConfig / request.config / defaults.
+         */
+        effectiveModelConfig?: Partial<Pick<ModelConfig, 'model' | 'modelId' | 'provider' | 'temperature' | 'maxTokens' | 'topP'>>;
         /**
          * Stable request/correlation identifiers across gateway/router/provider layers.
          * Only populated when diagnostics trace mode is enabled.

package/dist-cjs/gateway-utils.cjs

@@ -44,6 +44,13 @@ exports.mergeConfig = mergeConfig;
 exports.normalizeRouterUsageTokens = normalizeRouterUsageTokens;
 exports.extractTokenUsageFromRouterResponse = extractTokenUsageFromRouterResponse;
 exports.extractCostUsdFromRouterResponse = extractCostUsdFromRouterResponse;
+exports.pickInvokeRoutingMetadataSlice = pickInvokeRoutingMetadataSlice;
+exports.pickEffectiveModelConfigForMetadata = pickEffectiveModelConfigForMetadata;
+exports.pickEffectiveModelConfigFromInvokeRequest = pickEffectiveModelConfigFromInvokeRequest;
+exports.tryExtractRouterLikePayloadFromErrorChain = tryExtractRouterLikePayloadFromErrorChain;
+exports.pickRequestIdsFromRouterLike = pickRequestIdsFromRouterLike;
+exports.buildInvokeRejectionMetadata = buildInvokeRejectionMetadata;
+exports.attachGatewayInvokeRejectionMetadata = attachGatewayInvokeRejectionMetadata;
 exports.capActivityFullResponsePayload = capActivityFullResponsePayload;
 const crypto = __importStar(require("crypto"));
 const gateway_instructions_js_1 = require("./gateway-instructions.cjs");
@@ -358,6 +365,157 @@ function extractCostUsdFromRouterResponse(routerResponse) {
     }
     return undefined;
 }
+/**
+ * Stable routing facts for gateway response metadata (router metadata + merged config fallbacks).
+ * Matches trace-mode resolution; intended for every successful invoke(), not only diagnostics.trace.
+ */
+function pickInvokeRoutingMetadataSlice(routerResponse, mergedConfig) {
+    const rr = routerResponse != null && typeof routerResponse === 'object' ? routerResponse : {};
+    const meta = rr.metadata != null && typeof rr.metadata === 'object' ? rr.metadata : {};
+    const cfg = mergedConfig != null && typeof mergedConfig === 'object' ? mergedConfig : {};
+    const provider = meta.provider || rr.provider || cfg.provider;
+    const modelUsed = meta.modelUsed || meta.model || rr.model || cfg.model;
+    const maxTokensRequested = typeof meta.maxTokensRequested === 'number'
+        ? meta.maxTokensRequested
+        : typeof cfg.maxTokens === 'number'
+            ? cfg.maxTokens
+            : undefined;
+    const region = typeof meta.region === 'string' ? meta.region : undefined;
+    const out = {};
+    if (provider !== undefined && provider !== null)
+        out.provider = provider;
+    if (modelUsed !== undefined && modelUsed !== null)
+        out.modelUsed = modelUsed;
+    if (maxTokensRequested !== undefined)
+        out.maxTokensRequested = maxTokensRequested;
+    if (region !== undefined)
+        out.region = region;
+    return out;
+}
+/**
+ * Allowlisted generation profile from merged config for client introspection (no secrets, no arbitrary extras).
+ */
+function pickEffectiveModelConfigForMetadata(mergedConfig) {
+    if (mergedConfig == null || typeof mergedConfig !== 'object')
+        return undefined;
+    const c = mergedConfig;
+    const keys = ['model', 'modelId', 'provider', 'temperature', 'maxTokens', 'topP'];
+    const out = {};
+    for (const k of keys) {
+        const v = c[k];
+        if (v !== undefined)
+            out[k] = v;
+    }
+    return Object.keys(out).length ? out : undefined;
+}
+const EFFECTIVE_MODEL_CONFIG_KEYS = ['model', 'modelId', 'provider', 'temperature', 'maxTokens', 'topP'];
+/**
+ * Allowlisted generation fields from request only (before mergeConfig / flex-md).
+ * Priority matches mergeConfig: modelConfig overrides request.config per key.
+ */
+function pickEffectiveModelConfigFromInvokeRequest(request) {
+    const cfg = (request.config ?? {});
+    const mc = (request.modelConfig ?? {});
+    const out = {};
+    for (const k of EFFECTIVE_MODEL_CONFIG_KEYS) {
+        const v = mc[k] ?? cfg[k];
+        if (v !== undefined)
+            out[k] = v;
+    }
+    const modelFromId = out.model === undefined && typeof mc.modelId === 'string' ? mc.modelId : undefined;
+    if (modelFromId !== undefined)
+        out.model = modelFromId;
+    return Object.keys(out).length ? out : undefined;
+}
+function isRouterLikeEnvelope(value) {
+    if (value == null || typeof value !== 'object')
+        return false;
+    const r = value;
+    return ('metadata' in r ||
+        'outputText' in r ||
+        'content' in r ||
+        'requestId' in r ||
+        'usage' in r);
+}
+/**
+ * Walk `error`, optional `error.cause`, and common adapter fields (`response`, `routerResponse`, …)
+ * to find a router-shaped object for token / correlation extraction.
+ */
+function tryExtractRouterLikePayloadFromErrorChain(error, maxDepth = 8) {
+    const seen = new Set();
+    let cur = error;
+    for (let i = 0; i < maxDepth && cur != null; i++) {
+        if (typeof cur !== 'object')
+            break;
+        if (seen.has(cur))
+            break;
+        seen.add(cur);
+        const o = cur;
+        if (isRouterLikeEnvelope(cur))
+            return cur;
+        const nested = [o.response, o.routerResponse, o.lastResponse, o.body, o.data];
+        for (const n of nested) {
+            if (isRouterLikeEnvelope(n))
+                return n;
+        }
+        cur = o.cause;
+    }
+    return undefined;
+}
+function pickRequestIdsFromRouterLike(gatewayAiRequestId, routerLike) {
+    if (typeof gatewayAiRequestId !== 'string' || gatewayAiRequestId.length === 0) {
+        return undefined;
+    }
+    const out = { gatewayAiRequestId };
+    if (routerLike == null || typeof routerLike !== 'object') {
+        return out;
+    }
+    const rr = routerLike;
+    const meta = rr.metadata != null && typeof rr.metadata === 'object' ? rr.metadata : {};
+    const routerRequestId = rr.requestId ?? meta.requestId;
+    if (typeof routerRequestId === 'string')
+        out.routerRequestId = routerRequestId;
+    if (typeof meta.providerRequestId === 'string')
+        out.providerRequestId = meta.providerRequestId;
+    if (typeof meta.openrouterRequestId === 'string')
+        out.openrouterRequestId = meta.openrouterRequestId;
+    const nested = meta.requestIds;
+    if (nested != null && typeof nested === 'object') {
+        for (const [k, v] of Object.entries(nested)) {
+            if (typeof v === 'string')
+                out[k] = v;
+        }
+    }
+    return out;
+}
+function buildInvokeRejectionMetadata(args) {
+    const gid = args.gatewayAiRequestId ?? args.request.aiRequestId;
+    const partial = args.partialRouterPayload;
+    const mc = args.mergedConfig;
+    const routing = pickInvokeRoutingMetadataSlice(partial ?? {}, mc ?? {});
+    const effective = mc !== undefined
+        ? pickEffectiveModelConfigForMetadata(mc)
+        : pickEffectiveModelConfigFromInvokeRequest(args.request);
+    let tokens = partial !== undefined ? extractTokenUsageFromRouterResponse(partial) : undefined;
+    if (tokens && tokens.prompt === 0 && tokens.completion === 0 && tokens.total === 0) {
+        tokens = undefined;
+    }
+    const requestIds = pickRequestIdsFromRouterLike(gid, partial);
+    return {
+        aiRequestId: args.request.aiRequestId,
+        identity: args.request.identity,
+        taskTypeId: args.taskTypeId,
+        latencyMs: Date.now() - args.startTime,
+        ...routing,
+        ...(effective !== undefined ? { effectiveModelConfig: effective } : {}),
+        ...(tokens !== undefined ? { tokens } : {}),
+        ...(requestIds !== undefined ? { requestIds } : {}),
+        ...(mc === undefined ? { mergeConfigUnavailable: true } : {})
+    };
+}
+function attachGatewayInvokeRejectionMetadata(err, metadata) {
+    err.metadata = metadata;
+}
 /** Default JSON string length cap for Activix `content.fullResponse` when diagnostics allow storing it. */
 exports.DEFAULT_ACTIVITY_FULL_RESPONSE_MAX_CHARS = 512_000;
 /**

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

@@ -2,7 +2,7 @@
  * Gateway Utilities Module
  * Handles utility functions
  */
-import type { ChatRequest, GatewayConfig } from './types.js';
+import type { AIInvokeRequest, ChatRequest, GatewayConfig, GatewayInvokeRejectionMetadata, GatewayTraceRequestIds, ModelConfig } from './types.js';
 import type { Logxer } from '@x12i/logxer';
 /**
  * Generates MD5 hash of a string
@@ -43,6 +43,41 @@ export declare function extractTokenUsageFromRouterResponse(routerResponse: unkn
  * Does not compute cost from tokens — adapters must populate normalized fields or raw usage.cost-style keys.
  */
 export declare function extractCostUsdFromRouterResponse(routerResponse: unknown): number | undefined;
+/**
+ * Stable routing facts for gateway response metadata (router metadata + merged config fallbacks).
+ * Matches trace-mode resolution; intended for every successful invoke(), not only diagnostics.trace.
+ */
+export declare function pickInvokeRoutingMetadataSlice(routerResponse: unknown, mergedConfig: unknown): Partial<{
+    provider: string;
+    modelUsed: string;
+    maxTokensRequested: number;
+    region: string;
+}>;
+/**
+ * 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;
+declare const EFFECTIVE_MODEL_CONFIG_KEYS: readonly ["model", "modelId", "provider", "temperature", "maxTokens", "topP"];
+/**
+ * Allowlisted generation fields from request only (before mergeConfig / flex-md).
+ * Priority matches mergeConfig: modelConfig overrides request.config per key.
+ */
+export declare function pickEffectiveModelConfigFromInvokeRequest(request: Pick<AIInvokeRequest, 'config' | 'modelConfig'>): Partial<Pick<ModelConfig, (typeof EFFECTIVE_MODEL_CONFIG_KEYS)[number]>> | undefined;
+/**
+ * Walk `error`, optional `error.cause`, and common adapter fields (`response`, `routerResponse`, …)
+ * to find a router-shaped object for token / correlation extraction.
+ */
+export declare function tryExtractRouterLikePayloadFromErrorChain(error: unknown, maxDepth?: number): unknown;
+export declare function pickRequestIdsFromRouterLike(gatewayAiRequestId: string | undefined, routerLike: unknown): GatewayTraceRequestIds | undefined;
+export declare function buildInvokeRejectionMetadata(args: {
+    request: Pick<AIInvokeRequest, 'aiRequestId' | 'identity' | 'config' | 'modelConfig'>;
+    taskTypeId: string;
+    startTime: number;
+    mergedConfig?: unknown;
+    partialRouterPayload?: unknown;
+    gatewayAiRequestId?: string;
+}): GatewayInvokeRejectionMetadata;
+export declare function attachGatewayInvokeRejectionMetadata(err: Error, metadata: GatewayInvokeRejectionMetadata): void;
 /** Default JSON string length cap for Activix `content.fullResponse` when diagnostics allow storing it. */
 export declare const DEFAULT_ACTIVITY_FULL_RESPONSE_MAX_CHARS = 512000;
 /**
@@ -50,3 +85,4 @@ export declare const DEFAULT_ACTIVITY_FULL_RESPONSE_MAX_CHARS = 512000;
  * Non-serializable values become a small marker object instead of throwing.
  */
 export declare function capActivityFullResponsePayload(payload: unknown, maxChars?: number): unknown;
+export {};

package/dist-cjs/gateway.cjs

@@ -226,6 +226,13 @@ class AIGateway {
                     failureType: 'validation-failure'
                 }, startTime);
             }
+            const rejectMeta = (0, gateway_utils_js_1.buildInvokeRejectionMetadata)({
+                request,
+                taskTypeId,
+                startTime,
+                gatewayAiRequestId: request.aiRequestId
+            });
+            (0, gateway_utils_js_1.attachGatewayInvokeRejectionMetadata)(err, rejectMeta);
             // Re-throw the error so it propagates to the caller
             throw err;
         }
@@ -527,6 +534,8 @@ class AIGateway {
             }
             const resolvedCostUsd = (0, gateway_utils_js_1.extractCostUsdFromRouterResponse)(routerResponse);
             const routerMetaForCost = routerResponse?.metadata || {};
+            const routingMetadataSlice = (0, gateway_utils_js_1.pickInvokeRoutingMetadataSlice)(routerResponse, mergedConfig);
+            const effectiveModelConfig = (0, gateway_utils_js_1.pickEffectiveModelConfigForMetadata)(mergedConfig);
             const enhancedResponse = {
                 content: content,
                 parsedContent: parsedContent,
@@ -539,6 +548,8 @@ class AIGateway {
                     agentType: 'ai',
                     contentType,
                     parsingMethod,
+                    ...routingMetadataSlice,
+                    ...(effectiveModelConfig !== undefined ? { effectiveModelConfig } : {}),
                     ...(typeof resolvedCostUsd === 'number'
                         ? {
                             costUsd: resolvedCostUsd,
@@ -548,27 +559,12 @@ class AIGateway {
                         }
                         : {}),
                     ...(traceEnabled
-                        ? (() => {
-                            const meta = routerResponse?.metadata || {};
-                            const provider = meta.provider || routerResponse?.provider || mergedConfig?.provider;
-                            const region = typeof meta.region === 'string' ? meta.region : undefined;
-                            const modelUsed = meta.modelUsed || meta.model || routerResponse?.model || mergedConfig?.model;
-                            const maxTokensRequested = typeof meta.maxTokensRequested === 'number'
-                                ? meta.maxTokensRequested
-                                : typeof mergedConfig?.maxTokens === 'number'
-                                    ? mergedConfig.maxTokens
-                                    : undefined;
-                            return {
-                                provider,
-                                region,
-                                modelUsed,
-                                maxTokensRequested,
-                                requestIds: traceRequestIds,
-                                retryCount: traceRetryCount,
-                                fallbackCount: traceFallbackCount,
-                                attempts: traceAttempts
-                            };
-                        })()
+                        ? {
+                            requestIds: traceRequestIds,
+                            retryCount: traceRetryCount,
+                            fallbackCount: traceFallbackCount,
+                            attempts: traceAttempts
+                        }
                         : {})
                 }
             };
@@ -625,8 +621,21 @@ class AIGateway {
         }
         catch (error) {
             const err = error instanceof Error ? error : new Error(String(error));
+            const partial = (0, gateway_utils_js_1.tryExtractRouterLikePayloadFromErrorChain)(err);
+            const rejectMeta = (0, gateway_utils_js_1.buildInvokeRejectionMetadata)({
+                request,
+                taskTypeId,
+                startTime,
+                mergedConfig,
+                partialRouterPayload: partial,
+                gatewayAiRequestId: request.aiRequestId
+            });
+            (0, gateway_utils_js_1.attachGatewayInvokeRejectionMetadata)(err, rejectMeta);
             if (err.message.includes(NO_PROVIDER_ERROR)) {
-                throw new Error(err.message + NO_PROVIDER_HINT);
+                const wrapped = new Error(err.message + NO_PROVIDER_HINT);
+                wrapped.cause = err;
+                (0, gateway_utils_js_1.attachGatewayInvokeRejectionMetadata)(wrapped, rejectMeta);
+                throw wrapped;
             }
             throw err;
         }

package/dist-cjs/index.cjs

@@ -21,7 +21,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.resetObjectTypesLibrary = exports.getObjectTypesLibrary = exports.initializeObjectTypesLibrary = exports.getObjectTypesForAgent = exports.getObjectType = exports.OBJECT_TYPES_LIBRARY = exports.assertValidAIRequest = exports.formatDiagnostic = exports.runValidationTests = exports.createValidationTestCases = exports.createTestAIRequest = exports.supportsJSONMode = exports.diagnoseResponse = exports.diagnoseRequest = exports.validateResponse = exports.extractJSON = exports.validateJSON = exports.validateAIRequest = exports.DEFAULT_RATE_LIMIT_ENABLED = exports.DEFAULT_RATE_LIMIT_MIN_INTERVAL_MS = exports.GatewayRateLimiter = exports.runtimeObjects = exports.DebugLogAbstract = exports.createLogxer = exports.gatewayLogDebug = exports.withActivityIdentity = exports.activityIdentityToLogMeta = exports.ensureGatewayRequestIdentity = exports.ActivityManager = exports.Activix = exports.mergeTemplateRenderOptions = exports.autoRegisterProviders = exports.InstructionBackendError = exports.InstructionNotFoundError = exports.AIGateway = exports.FallbackExhaustedError = exports.ProviderNotFoundError = exports.createRouterFromConfig = exports.createRouter = exports.LLMProviderRouter = void 0;
+exports.resetObjectTypesLibrary = exports.getObjectTypesLibrary = exports.initializeObjectTypesLibrary = exports.getObjectTypesForAgent = exports.getObjectType = exports.OBJECT_TYPES_LIBRARY = exports.assertValidAIRequest = exports.formatDiagnostic = exports.runValidationTests = exports.createValidationTestCases = exports.createTestAIRequest = exports.supportsJSONMode = exports.diagnoseResponse = exports.diagnoseRequest = exports.validateResponse = exports.extractJSON = exports.validateJSON = exports.validateAIRequest = exports.DEFAULT_RATE_LIMIT_ENABLED = exports.DEFAULT_RATE_LIMIT_MIN_INTERVAL_MS = exports.GatewayRateLimiter = exports.runtimeObjects = exports.DebugLogAbstract = exports.createLogxer = exports.gatewayLogDebug = exports.withActivityIdentity = exports.activityIdentityToLogMeta = exports.ensureGatewayRequestIdentity = exports.ActivityManager = exports.Activix = exports.mergeTemplateRenderOptions = exports.pickRequestIdsFromRouterLike = exports.tryExtractRouterLikePayloadFromErrorChain = exports.buildInvokeRejectionMetadata = exports.attachGatewayInvokeRejectionMetadata = exports.autoRegisterProviders = exports.InstructionBackendError = exports.InstructionNotFoundError = exports.AIGateway = exports.FallbackExhaustedError = exports.ProviderNotFoundError = exports.createRouterFromConfig = exports.createRouter = exports.LLMProviderRouter = void 0;
 // Re-export router class and types (base functionality)
 var ai_providers_router_1 = require("@x12i/ai-providers-router");
 Object.defineProperty(exports, "LLMProviderRouter", { enumerable: true, get: function () { return ai_providers_router_1.LLMProviderRouter; } });
@@ -43,6 +43,11 @@ Object.defineProperty(exports, "InstructionNotFoundError", { enumerable: true, g
 Object.defineProperty(exports, "InstructionBackendError", { enumerable: true, get: function () { return instruction_errors_js_1.InstructionBackendError; } });
 var gateway_provider_auto_register_js_1 = require("./gateway-provider-auto-register.cjs");
 Object.defineProperty(exports, "autoRegisterProviders", { enumerable: true, get: function () { return gateway_provider_auto_register_js_1.autoRegisterProviders; } });
+var gateway_utils_js_1 = require("./gateway-utils.cjs");
+Object.defineProperty(exports, "attachGatewayInvokeRejectionMetadata", { enumerable: true, get: function () { return gateway_utils_js_1.attachGatewayInvokeRejectionMetadata; } });
+Object.defineProperty(exports, "buildInvokeRejectionMetadata", { enumerable: true, get: function () { return gateway_utils_js_1.buildInvokeRejectionMetadata; } });
+Object.defineProperty(exports, "tryExtractRouterLikePayloadFromErrorChain", { enumerable: true, get: function () { return gateway_utils_js_1.tryExtractRouterLikePayloadFromErrorChain; } });
+Object.defineProperty(exports, "pickRequestIdsFromRouterLike", { enumerable: true, get: function () { return gateway_utils_js_1.pickRequestIdsFromRouterLike; } });
 var template_render_merge_js_1 = require("./template-render-merge.cjs");
 Object.defineProperty(exports, "mergeTemplateRenderOptions", { enumerable: true, get: function () { return template_render_merge_js_1.mergeTemplateRenderOptions; } });
 // Usage tracking: UsageTracker class methods are available but consumption calculation is disabled

package/dist-cjs/index.d.ts

@@ -16,7 +16,8 @@ export * from '@x12i/ai-providers-router';
 export { AIGateway } from './gateway.js';
 export { InstructionNotFoundError, InstructionBackendError } from './instruction-errors.js';
 export { autoRegisterProviders } from './gateway-provider-auto-register.js';
-export type { GatewayConfig, ProviderModelRef, ModelConfig, RetryConfig, ChatRequest, AIInvokeRequest, AIRequest, GatewayActionType, EnhancedLLMResponse, InstructionMetadata, ValidationRule, TemplateRenderOptions } from './types.js';
+export type { GatewayConfig, ProviderModelRef, ModelConfig, RetryConfig, ChatRequest, AIInvokeRequest, AIRequest, GatewayActionType, GatewayInvokeRejectionMetadata, GatewayTraceRequestIds, EnhancedLLMResponse, InstructionMetadata, ValidationRule, TemplateRenderOptions } from './types.js';
+export { attachGatewayInvokeRejectionMetadata, buildInvokeRejectionMetadata, tryExtractRouterLikePayloadFromErrorChain, pickRequestIdsFromRouterLike } from './gateway-utils.js';
 export { mergeTemplateRenderOptions } from './template-render-merge.js';
 export type { UsageTier } from './types.js';
 export { Activix } from '@x12i/activix';

package/dist-cjs/types.d.ts

@@ -84,6 +84,34 @@ export type GatewayTraceAttempt = {
      */
     rawProviderPayload?: unknown;
 };
+/**
+ * Normalized observability payload attached to thrown errors from {@link AIGateway.invoke}
+ * when the gateway can derive fields (merged config, partial router body on error).
+ * SDKs should read `(error as Error & { metadata?: GatewayInvokeRejectionMetadata }).metadata`
+ * (see docs/AI_GATEWAY_INVOKE_EXECUTION_METADATA.md).
+ */
+export type GatewayInvokeRejectionMetadata = {
+    aiRequestId?: string;
+    identity?: ActivityIdentity;
+    taskTypeId?: string;
+    latencyMs?: number;
+    tokens?: {
+        prompt: number;
+        completion: number;
+        total: number;
+    };
+    provider?: string;
+    modelUsed?: string;
+    maxTokensRequested?: number;
+    region?: string;
+    effectiveModelConfig?: Partial<Pick<ModelConfig, 'model' | 'modelId' | 'provider' | 'temperature' | 'maxTokens' | 'topP'>>;
+    requestIds?: GatewayTraceRequestIds;
+    /**
+     * True when {@link mergeConfig} did not run (e.g. message-building threw first).
+     * Routing facts may only reflect request.config / modelConfig, not flex-md defaults.
+     */
+    mergeConfigUnavailable?: true;
+};
 /**
  * Identity object used for activity linkage.
  * On gateway requests/responses it lives on `identity`. When activity tracking persists via Activix v5+,
@@ -876,7 +904,8 @@ export interface EnhancedLLMResponse<TContent = unknown> extends Omit<AIResponse
          */
         model?: string;
         /**
-         * Provider used (e.g., 'openai', 'anthropic')
+         * Provider used (e.g., 'openai', 'anthropic').
+         * Populated on every successful invoke when router or merged config supplies it.
          */
         provider?: string;
         /**
@@ -884,23 +913,30 @@ export interface EnhancedLLMResponse<TContent = unknown> extends Omit<AIResponse
          */
         cost?: number;
         /**
-         * Cost in USD (preferred, stable key for trace mode).
+         * Cost in USD (preferred stable key when the router exposes it).
          * When both are present, costUsd should mirror cost.
          */
         costUsd?: number;
         /**
          * Final effective max token cap applied (after merges/normalization), if known.
+         * Populated on every successful invoke when router or merged config supplies it.
          */
         maxTokensRequested?: number;
         /**
          * Model that actually served the response (after routing/fallback), if known.
          * This is distinct from requested model.
+         * Populated on every successful invoke when router or merged config supplies it.
          */
         modelUsed?: string;
         /**
          * Optional region identifier when applicable (provider-specific).
          */
         region?: string;
+        /**
+         * Sanitized merged generation profile (allowlisted fields only; no secrets).
+         * Reflects gateway merge order: modelConfig / request.config / defaults.
+         */
+        effectiveModelConfig?: Partial<Pick<ModelConfig, 'model' | 'modelId' | 'provider' | 'temperature' | 'maxTokens' | 'topP'>>;
         /**
          * Stable request/correlation identifiers across gateway/router/provider layers.
          * Only populated when diagnostics trace mode is enabled.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x12i/ai-gateway",
-  "version": "9.1.0",
+  "version": "9.1.2",
   "description": "AI Gateway - Unified interface for LLM provider routing and management",
   "type": "module",
   "exports": {