@x12i/ai-gateway 9.1.1 → 9.1.3

package/dist/activity-manager.js

@@ -133,6 +133,30 @@ function logUpstreamIdentityWarnings(logger, incomingIdentity, merged) {
         }));
     }
 }
+/** Routing / generation facts from gateway response metadata for Activix `outer.metadata` on completion. */
+function pickActivixCompletionRoutingMetadata(response) {
+    if (response == null || typeof response !== 'object')
+        return {};
+    const meta = response.metadata;
+    if (meta == null || typeof meta !== 'object')
+        return {};
+    const m = meta;
+    const out = {};
+    if (typeof m.modelUsed === 'string')
+        out.modelUsed = m.modelUsed;
+    if (typeof m.model === 'string')
+        out.model = m.model;
+    if (typeof m.provider === 'string')
+        out.provider = m.provider;
+    if (typeof m.maxTokensRequested === 'number')
+        out.maxTokensRequested = m.maxTokensRequested;
+    if (typeof m.region === 'string')
+        out.region = m.region;
+    if (m.effectiveModelConfig != null && typeof m.effectiveModelConfig === 'object') {
+        out.effectiveModelConfig = m.effectiveModelConfig;
+    }
+    return out;
+}
 function mergeGatewayActivityIdentity(request, aiRequestId, extras) {
     const incomingIdentity = request.identity;
     const sessionId = resolveSessionIdForRequest(request, incomingIdentity, aiRequestId);
@@ -388,33 +412,37 @@ export class ActivityManager {
             // - provider, model, temperature, maxTokens → only in config object
             // - NO response, endTime, duration (these are added via logSuccess)
         };
-        // Config snapshot
-        // CRITICAL: This captures the exact config sent to the router (finalRouterConfig)
-        // This ensures activity records show the actual config that was sent, including that response_format was removed
-        if (request.config !== undefined) {
-            // Verify response_format is not present (for debugging)
-            const hasResponseFormat = 'responseFormat' in request.config || 'response_format' in request.config;
+        // Config snapshot — prefer gateway merge output (`_mergedRouterConfig`) over raw `request.config`.
+        // Callers often put model only on `modelConfig`; merge happens in `mergeConfig()` before `router.invoke`.
+        const mergedRouterConfig = request._mergedRouterConfig;
+        const configSource = mergedRouterConfig != null && typeof mergedRouterConfig === 'object'
+            ? mergedRouterConfig
+            : request.config;
+        // CRITICAL: Capture the exact config sent to the router (finalRouterConfig)
+        if (configSource !== undefined) {
+            const hasResponseFormat = 'responseFormat' in configSource || 'response_format' in configSource;
             if (hasResponseFormat) {
                 this.logger.warn('Activity tracking received config with response_format - this should not happen', {
                     aiRequestId,
-                    hasResponseFormat: 'responseFormat' in request.config,
-                    hasResponse_format: 'response_format' in request.config,
-                    configKeys: Object.keys(request.config)
+                    hasResponseFormat: 'responseFormat' in configSource,
+                    hasResponse_format: 'response_format' in configSource,
+                    configKeys: Object.keys(configSource)
                 });
             }
             activityMetadata.config = {
-                model: request.config.model,
-                provider: request.config.provider || null, // Ensure provider is captured (may be null if not set)
-                temperature: request.config.temperature,
-                maxTokens: request.config.maxTokens,
-                rawConfig: request.config // ✅ Captures finalRouterConfig (exact config sent to router)
+                model: configSource.model,
+                provider: configSource.provider || null,
+                temperature: configSource.temperature,
+                maxTokens: configSource.maxTokens,
+                rawConfig: configSource
             };
             this.logger.debug('Activity tracking config captured', {
                 aiRequestId,
-                model: request.config.model,
-                provider: request.config.provider,
-                hasResponseFormat: hasResponseFormat,
-                rawConfigKeys: Object.keys(request.config).slice(0, 10)
+                model: configSource.model,
+                provider: configSource.provider,
+                configSource: mergedRouterConfig != null ? '_mergedRouterConfig' : 'request.config',
+                hasResponseFormat,
+                rawConfigKeys: Object.keys(configSource).slice(0, 10)
             });
         }
         // Build request object snapshots (raw = incoming; parsed = constructed messages/meta)
@@ -605,14 +633,17 @@ export class ActivityManager {
             ...(aiRequest.masterSkillActivityId && { masterSkillActivityId: aiRequest.masterSkillActivityId }),
             ...(aiRequest.masterSkillId && { masterSkillId: aiRequest.masterSkillId })
         };
-        // Config snapshot (same as startActivity)
-        if (request.config !== undefined) {
+        const mergedRouterConfigSkill = request._mergedRouterConfig;
+        const configSourceSkill = mergedRouterConfigSkill != null && typeof mergedRouterConfigSkill === 'object'
+            ? mergedRouterConfigSkill
+            : request.config;
+        if (configSourceSkill !== undefined) {
             activityMetadata.config = {
-                model: request.config.model,
-                provider: request.config.provider || null,
-                temperature: request.config.temperature,
-                maxTokens: request.config.maxTokens,
-                rawConfig: request.config
+                model: configSourceSkill.model,
+                provider: configSourceSkill.provider || null,
+                temperature: configSourceSkill.temperature,
+                maxTokens: configSourceSkill.maxTokens,
+                rawConfig: configSourceSkill
             };
         }
         // Build request object snapshots (same as startActivity)
@@ -816,7 +847,7 @@ export class ActivityManager {
                 response: details.response,
                 outer: {
                     output: details.response,
-                    metadata: {}
+                    metadata: pickActivixCompletionRoutingMetadata(details.response)
                 },
                 endTime: details.endTime,
                 duration: details.duration

package/dist/gateway-utils.d.ts

@@ -2,7 +2,7 @@
  * Gateway Utilities Module
  * Handles utility functions
  */
-import type { ChatRequest, GatewayConfig, ModelConfig } from './types.js';
+import type { AIInvokeRequest, ChatRequest, GatewayConfig, GatewayInvokeRejectionMetadata, GatewayTraceMergedConfig, GatewayTraceRequestIds, ModelConfig } from './types.js';
 import type { Logxer } from '@x12i/logxer';
 /**
  * Generates MD5 hash of a string
@@ -57,6 +57,31 @@ 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;
+/**
+ * Allowlisted snapshot of merged router config for diagnostics trace responses (no arbitrary extras).
+ */
+export declare function pickTraceMergedRouterConfig(mergedConfig: unknown): GatewayTraceMergedConfig | 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;
 /**
@@ -64,3 +89,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

@@ -358,6 +358,148 @@ export function pickEffectiveModelConfigForMetadata(mergedConfig) {
     }
     return Object.keys(out).length ? out : undefined;
 }
+const TRACE_MERGED_ROUTER_NUMERIC_KEYS = [
+    'temperature',
+    'maxTokens',
+    'topP',
+    'frequencyPenalty',
+    'presencePenalty'
+];
+/**
+ * Allowlisted snapshot of merged router config for diagnostics trace responses (no arbitrary extras).
+ */
+export function pickTraceMergedRouterConfig(mergedConfig) {
+    if (mergedConfig == null || typeof mergedConfig !== 'object')
+        return undefined;
+    const c = mergedConfig;
+    const out = {};
+    for (const k of ['model', 'modelId', 'provider']) {
+        const v = c[k];
+        if (typeof v === 'string' && v.length > 0)
+            out[k] = v;
+    }
+    for (const k of TRACE_MERGED_ROUTER_NUMERIC_KEYS) {
+        const v = c[k];
+        if (typeof v === 'number' && Number.isFinite(v))
+            out[k] = v;
+    }
+    const stop = c.stop;
+    if (Array.isArray(stop) && stop.every((x) => typeof x === 'string')) {
+        out.stop = stop;
+    }
+    else if (typeof stop === 'string' && stop.length > 0) {
+        out.stop = [stop];
+    }
+    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, pickEffectiveModelConfigForMetadata, pickInvokeRoutingMetadataSlice } from './gateway-utils.js';
+import { attachGatewayInvokeRejectionMetadata, buildInvokeRejectionMetadata, capActivityFullResponsePayload, DEFAULT_ACTIVITY_FULL_RESPONSE_MAX_CHARS, extractCostUsdFromRouterResponse, extractTokenUsageFromRouterResponse, mergeConfig, pickEffectiveModelConfigForMetadata, pickInvokeRoutingMetadataSlice, pickTraceMergedRouterConfig, 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';
@@ -77,6 +77,8 @@ export class AIGateway {
         const messages = this.buildSimpleMessages(request);
         // Merge config (modelConfig > request.config > gateway defaults)
         const mergedConfig = await mergeConfig(request, this.config, this.logger);
+        // Activix start snapshot must match what the router receives (modelConfig-only callers omit request.config.model).
+        request._mergedRouterConfig = mergedConfig;
         // Lazy auto-register providers from env (OPENAI_API_KEY, etc.) so consumers don't have to call init
         if (!this._autoRegisterDone) {
             await autoRegisterProviders(this.router, this.logger);
@@ -223,6 +225,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;
         }
@@ -237,6 +246,7 @@ export class AIGateway {
         request._parsedRequest = parsedSnapshot;
         // Merge config (modelConfig > request.config > gateway defaults)
         const mergedConfig = await mergeConfig(request, this.config, this.logger);
+        request._mergedRouterConfig = mergedConfig;
         const diagnosticsMode = request.diagnostics?.mode;
         const traceEnabled = diagnosticsMode === 'trace';
         const includeRawProviderPayload = request.diagnostics?.includeRawProviderPayload === true;
@@ -526,6 +536,7 @@ export class AIGateway {
             const routerMetaForCost = routerResponse?.metadata || {};
             const routingMetadataSlice = pickInvokeRoutingMetadataSlice(routerResponse, mergedConfig);
             const effectiveModelConfig = pickEffectiveModelConfigForMetadata(mergedConfig);
+            const traceMergedRouterSnapshot = traceEnabled ? pickTraceMergedRouterConfig(mergedConfig) : undefined;
             const enhancedResponse = {
                 content: content,
                 parsedContent: parsedContent,
@@ -553,7 +564,10 @@ export class AIGateway {
                             requestIds: traceRequestIds,
                             retryCount: traceRetryCount,
                             fallbackCount: traceFallbackCount,
-                            attempts: traceAttempts
+                            attempts: traceAttempts,
+                            ...(traceMergedRouterSnapshot !== undefined
+                                ? { mergedRouterConfig: traceMergedRouterSnapshot }
+                                : {})
                         }
                         : {})
                 }
@@ -611,8 +625,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, GatewayTraceMergedConfig, 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,39 @@ export type GatewayTraceAttempt = {
      */
     rawProviderPayload?: unknown;
 };
+/**
+ * Allowlisted merged router/generation config returned in {@link EnhancedLLMResponse.metadata}
+ * when `diagnostics.mode === 'trace'`. Omits arbitrary extras and secrets.
+ */
+export type GatewayTraceMergedConfig = Partial<Pick<ModelConfig, 'model' | 'modelId' | 'provider' | 'temperature' | 'maxTokens' | 'topP' | 'frequencyPenalty' | 'presencePenalty' | 'stop'>>;
+/**
+ * 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+,
@@ -926,6 +959,12 @@ export interface EnhancedLLMResponse<TContent = unknown> extends Omit<AIResponse
          * Ordered, authoritative attempts across retries and fallbacks (trace mode).
          */
         attempts?: GatewayTraceAttempt[];
+        /**
+         * Merged gateway/router generation config actually used for the invocation (after
+         * {@link mergeConfig}: modelConfig / request.config / defaults / flex-md maxTokens).
+         * Only populated when diagnostics trace mode is enabled.
+         */
+        mergedRouterConfig?: GatewayTraceMergedConfig;
         /**
          * Content type classification
          * Indicates whether content is 'string', 'object', 'array', or 'null'

package/dist-cjs/activity-manager.cjs

@@ -137,6 +137,30 @@ function logUpstreamIdentityWarnings(logger, incomingIdentity, merged) {
         }));
     }
 }
+/** Routing / generation facts from gateway response metadata for Activix `outer.metadata` on completion. */
+function pickActivixCompletionRoutingMetadata(response) {
+    if (response == null || typeof response !== 'object')
+        return {};
+    const meta = response.metadata;
+    if (meta == null || typeof meta !== 'object')
+        return {};
+    const m = meta;
+    const out = {};
+    if (typeof m.modelUsed === 'string')
+        out.modelUsed = m.modelUsed;
+    if (typeof m.model === 'string')
+        out.model = m.model;
+    if (typeof m.provider === 'string')
+        out.provider = m.provider;
+    if (typeof m.maxTokensRequested === 'number')
+        out.maxTokensRequested = m.maxTokensRequested;
+    if (typeof m.region === 'string')
+        out.region = m.region;
+    if (m.effectiveModelConfig != null && typeof m.effectiveModelConfig === 'object') {
+        out.effectiveModelConfig = m.effectiveModelConfig;
+    }
+    return out;
+}
 function mergeGatewayActivityIdentity(request, aiRequestId, extras) {
     const incomingIdentity = request.identity;
     const sessionId = resolveSessionIdForRequest(request, incomingIdentity, aiRequestId);
@@ -392,33 +416,37 @@ class ActivityManager {
             // - provider, model, temperature, maxTokens → only in config object
             // - NO response, endTime, duration (these are added via logSuccess)
         };
-        // Config snapshot
-        // CRITICAL: This captures the exact config sent to the router (finalRouterConfig)
-        // This ensures activity records show the actual config that was sent, including that response_format was removed
-        if (request.config !== undefined) {
-            // Verify response_format is not present (for debugging)
-            const hasResponseFormat = 'responseFormat' in request.config || 'response_format' in request.config;
+        // Config snapshot — prefer gateway merge output (`_mergedRouterConfig`) over raw `request.config`.
+        // Callers often put model only on `modelConfig`; merge happens in `mergeConfig()` before `router.invoke`.
+        const mergedRouterConfig = request._mergedRouterConfig;
+        const configSource = mergedRouterConfig != null && typeof mergedRouterConfig === 'object'
+            ? mergedRouterConfig
+            : request.config;
+        // CRITICAL: Capture the exact config sent to the router (finalRouterConfig)
+        if (configSource !== undefined) {
+            const hasResponseFormat = 'responseFormat' in configSource || 'response_format' in configSource;
             if (hasResponseFormat) {
                 this.logger.warn('Activity tracking received config with response_format - this should not happen', {
                     aiRequestId,
-                    hasResponseFormat: 'responseFormat' in request.config,
-                    hasResponse_format: 'response_format' in request.config,
-                    configKeys: Object.keys(request.config)
+                    hasResponseFormat: 'responseFormat' in configSource,
+                    hasResponse_format: 'response_format' in configSource,
+                    configKeys: Object.keys(configSource)
                 });
             }
             activityMetadata.config = {
-                model: request.config.model,
-                provider: request.config.provider || null, // Ensure provider is captured (may be null if not set)
-                temperature: request.config.temperature,
-                maxTokens: request.config.maxTokens,
-                rawConfig: request.config // ✅ Captures finalRouterConfig (exact config sent to router)
+                model: configSource.model,
+                provider: configSource.provider || null,
+                temperature: configSource.temperature,
+                maxTokens: configSource.maxTokens,
+                rawConfig: configSource
             };
             this.logger.debug('Activity tracking config captured', {
                 aiRequestId,
-                model: request.config.model,
-                provider: request.config.provider,
-                hasResponseFormat: hasResponseFormat,
-                rawConfigKeys: Object.keys(request.config).slice(0, 10)
+                model: configSource.model,
+                provider: configSource.provider,
+                configSource: mergedRouterConfig != null ? '_mergedRouterConfig' : 'request.config',
+                hasResponseFormat,
+                rawConfigKeys: Object.keys(configSource).slice(0, 10)
             });
         }
         // Build request object snapshots (raw = incoming; parsed = constructed messages/meta)
@@ -609,14 +637,17 @@ class ActivityManager {
             ...(aiRequest.masterSkillActivityId && { masterSkillActivityId: aiRequest.masterSkillActivityId }),
             ...(aiRequest.masterSkillId && { masterSkillId: aiRequest.masterSkillId })
         };
-        // Config snapshot (same as startActivity)
-        if (request.config !== undefined) {
+        const mergedRouterConfigSkill = request._mergedRouterConfig;
+        const configSourceSkill = mergedRouterConfigSkill != null && typeof mergedRouterConfigSkill === 'object'
+            ? mergedRouterConfigSkill
+            : request.config;
+        if (configSourceSkill !== undefined) {
             activityMetadata.config = {
-                model: request.config.model,
-                provider: request.config.provider || null,
-                temperature: request.config.temperature,
-                maxTokens: request.config.maxTokens,
-                rawConfig: request.config
+                model: configSourceSkill.model,
+                provider: configSourceSkill.provider || null,
+                temperature: configSourceSkill.temperature,
+                maxTokens: configSourceSkill.maxTokens,
+                rawConfig: configSourceSkill
             };
         }
         // Build request object snapshots (same as startActivity)
@@ -820,7 +851,7 @@ class ActivityManager {
                 response: details.response,
                 outer: {
                     output: details.response,
-                    metadata: {}
+                    metadata: pickActivixCompletionRoutingMetadata(details.response)
                 },
                 endTime: details.endTime,
                 duration: details.duration

package/dist-cjs/gateway-utils.cjs

@@ -46,6 +46,12 @@ exports.extractTokenUsageFromRouterResponse = extractTokenUsageFromRouterRespons
 exports.extractCostUsdFromRouterResponse = extractCostUsdFromRouterResponse;
 exports.pickInvokeRoutingMetadataSlice = pickInvokeRoutingMetadataSlice;
 exports.pickEffectiveModelConfigForMetadata = pickEffectiveModelConfigForMetadata;
+exports.pickTraceMergedRouterConfig = pickTraceMergedRouterConfig;
+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");
@@ -403,6 +409,148 @@ function pickEffectiveModelConfigForMetadata(mergedConfig) {
     }
     return Object.keys(out).length ? out : undefined;
 }
+const TRACE_MERGED_ROUTER_NUMERIC_KEYS = [
+    'temperature',
+    'maxTokens',
+    'topP',
+    'frequencyPenalty',
+    'presencePenalty'
+];
+/**
+ * Allowlisted snapshot of merged router config for diagnostics trace responses (no arbitrary extras).
+ */
+function pickTraceMergedRouterConfig(mergedConfig) {
+    if (mergedConfig == null || typeof mergedConfig !== 'object')
+        return undefined;
+    const c = mergedConfig;
+    const out = {};
+    for (const k of ['model', 'modelId', 'provider']) {
+        const v = c[k];
+        if (typeof v === 'string' && v.length > 0)
+            out[k] = v;
+    }
+    for (const k of TRACE_MERGED_ROUTER_NUMERIC_KEYS) {
+        const v = c[k];
+        if (typeof v === 'number' && Number.isFinite(v))
+            out[k] = v;
+    }
+    const stop = c.stop;
+    if (Array.isArray(stop) && stop.every((x) => typeof x === 'string')) {
+        out.stop = stop;
+    }
+    else if (typeof stop === 'string' && stop.length > 0) {
+        out.stop = [stop];
+    }
+    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, ModelConfig } from './types.js';
+import type { AIInvokeRequest, ChatRequest, GatewayConfig, GatewayInvokeRejectionMetadata, GatewayTraceMergedConfig, GatewayTraceRequestIds, ModelConfig } from './types.js';
 import type { Logxer } from '@x12i/logxer';
 /**
  * Generates MD5 hash of a string
@@ -57,6 +57,31 @@ 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;
+/**
+ * Allowlisted snapshot of merged router config for diagnostics trace responses (no arbitrary extras).
+ */
+export declare function pickTraceMergedRouterConfig(mergedConfig: unknown): GatewayTraceMergedConfig | 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;
 /**
@@ -64,3 +89,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

@@ -80,6 +80,8 @@ class AIGateway {
         const messages = this.buildSimpleMessages(request);
         // Merge config (modelConfig > request.config > gateway defaults)
         const mergedConfig = await (0, gateway_utils_js_1.mergeConfig)(request, this.config, this.logger);
+        // Activix start snapshot must match what the router receives (modelConfig-only callers omit request.config.model).
+        request._mergedRouterConfig = mergedConfig;
         // Lazy auto-register providers from env (OPENAI_API_KEY, etc.) so consumers don't have to call init
         if (!this._autoRegisterDone) {
             await (0, gateway_provider_auto_register_js_1.autoRegisterProviders)(this.router, this.logger);
@@ -226,6 +228,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;
         }
@@ -240,6 +249,7 @@ class AIGateway {
         request._parsedRequest = parsedSnapshot;
         // Merge config (modelConfig > request.config > gateway defaults)
         const mergedConfig = await (0, gateway_utils_js_1.mergeConfig)(request, this.config, this.logger);
+        request._mergedRouterConfig = mergedConfig;
         const diagnosticsMode = request.diagnostics?.mode;
         const traceEnabled = diagnosticsMode === 'trace';
         const includeRawProviderPayload = request.diagnostics?.includeRawProviderPayload === true;
@@ -529,6 +539,7 @@ class AIGateway {
             const routerMetaForCost = routerResponse?.metadata || {};
             const routingMetadataSlice = (0, gateway_utils_js_1.pickInvokeRoutingMetadataSlice)(routerResponse, mergedConfig);
             const effectiveModelConfig = (0, gateway_utils_js_1.pickEffectiveModelConfigForMetadata)(mergedConfig);
+            const traceMergedRouterSnapshot = traceEnabled ? (0, gateway_utils_js_1.pickTraceMergedRouterConfig)(mergedConfig) : undefined;
             const enhancedResponse = {
                 content: content,
                 parsedContent: parsedContent,
@@ -556,7 +567,10 @@ class AIGateway {
                             requestIds: traceRequestIds,
                             retryCount: traceRetryCount,
                             fallbackCount: traceFallbackCount,
-                            attempts: traceAttempts
+                            attempts: traceAttempts,
+                            ...(traceMergedRouterSnapshot !== undefined
+                                ? { mergedRouterConfig: traceMergedRouterSnapshot }
+                                : {})
                         }
                         : {})
                 }
@@ -614,8 +628,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, GatewayTraceMergedConfig, 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,39 @@ export type GatewayTraceAttempt = {
      */
     rawProviderPayload?: unknown;
 };
+/**
+ * Allowlisted merged router/generation config returned in {@link EnhancedLLMResponse.metadata}
+ * when `diagnostics.mode === 'trace'`. Omits arbitrary extras and secrets.
+ */
+export type GatewayTraceMergedConfig = Partial<Pick<ModelConfig, 'model' | 'modelId' | 'provider' | 'temperature' | 'maxTokens' | 'topP' | 'frequencyPenalty' | 'presencePenalty' | 'stop'>>;
+/**
+ * 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+,
@@ -926,6 +959,12 @@ export interface EnhancedLLMResponse<TContent = unknown> extends Omit<AIResponse
          * Ordered, authoritative attempts across retries and fallbacks (trace mode).
          */
         attempts?: GatewayTraceAttempt[];
+        /**
+         * Merged gateway/router generation config actually used for the invocation (after
+         * {@link mergeConfig}: modelConfig / request.config / defaults / flex-md maxTokens).
+         * Only populated when diagnostics trace mode is enabled.
+         */
+        mergedRouterConfig?: GatewayTraceMergedConfig;
         /**
          * Content type classification
          * Indicates whether content is 'string', 'object', 'array', or 'null'

package/package.json

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