@x12i/ai-gateway 9.1.2 → 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 { AIInvokeRequest, ChatRequest, GatewayConfig, GatewayInvokeRejectionMetadata, GatewayTraceRequestIds, 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,10 @@ 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).

package/dist/gateway-utils.js

@@ -358,6 +358,40 @@ 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).

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 { attachGatewayInvokeRejectionMetadata, buildInvokeRejectionMetadata, capActivityFullResponsePayload, DEFAULT_ACTIVITY_FULL_RESPONSE_MAX_CHARS, extractCostUsdFromRouterResponse, extractTokenUsageFromRouterResponse, mergeConfig, pickEffectiveModelConfigForMetadata, pickInvokeRoutingMetadataSlice, tryExtractRouterLikePayloadFromErrorChain } 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);
@@ -244,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;
@@ -533,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,
@@ -560,7 +564,10 @@ export class AIGateway {
                             requestIds: traceRequestIds,
                             retryCount: traceRetryCount,
                             fallbackCount: traceFallbackCount,
-                            attempts: traceAttempts
+                            attempts: traceAttempts,
+                            ...(traceMergedRouterSnapshot !== undefined
+                                ? { mergedRouterConfig: traceMergedRouterSnapshot }
+                                : {})
                         }
                         : {})
                 }

package/dist/index.d.ts

@@ -16,7 +16,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 type { GatewayConfig, ProviderModelRef, ModelConfig, RetryConfig, ChatRequest, AIInvokeRequest, AIRequest, GatewayActionType, GatewayInvokeRejectionMetadata, GatewayTraceRequestIds, 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';

package/dist/types.d.ts

@@ -84,6 +84,11 @@ 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).
@@ -954,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,7 @@ exports.extractTokenUsageFromRouterResponse = extractTokenUsageFromRouterRespons
 exports.extractCostUsdFromRouterResponse = extractCostUsdFromRouterResponse;
 exports.pickInvokeRoutingMetadataSlice = pickInvokeRoutingMetadataSlice;
 exports.pickEffectiveModelConfigForMetadata = pickEffectiveModelConfigForMetadata;
+exports.pickTraceMergedRouterConfig = pickTraceMergedRouterConfig;
 exports.pickEffectiveModelConfigFromInvokeRequest = pickEffectiveModelConfigFromInvokeRequest;
 exports.tryExtractRouterLikePayloadFromErrorChain = tryExtractRouterLikePayloadFromErrorChain;
 exports.pickRequestIdsFromRouterLike = pickRequestIdsFromRouterLike;
@@ -408,6 +409,40 @@ 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).

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

@@ -2,7 +2,7 @@
  * Gateway Utilities Module
  * Handles utility functions
  */
-import type { AIInvokeRequest, ChatRequest, GatewayConfig, GatewayInvokeRejectionMetadata, GatewayTraceRequestIds, 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,10 @@ 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).

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);
@@ -247,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;
@@ -536,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,
@@ -563,7 +567,10 @@ class AIGateway {
                             requestIds: traceRequestIds,
                             retryCount: traceRetryCount,
                             fallbackCount: traceFallbackCount,
-                            attempts: traceAttempts
+                            attempts: traceAttempts,
+                            ...(traceMergedRouterSnapshot !== undefined
+                                ? { mergedRouterConfig: traceMergedRouterSnapshot }
+                                : {})
                         }
                         : {})
                 }

package/dist-cjs/index.d.ts

@@ -16,7 +16,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 type { GatewayConfig, ProviderModelRef, ModelConfig, RetryConfig, ChatRequest, AIInvokeRequest, AIRequest, GatewayActionType, GatewayInvokeRejectionMetadata, GatewayTraceRequestIds, 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';

package/dist-cjs/types.d.ts

@@ -84,6 +84,11 @@ 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).
@@ -954,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.2",
+  "version": "9.1.3",
   "description": "AI Gateway - Unified interface for LLM provider routing and management",
   "type": "module",
   "exports": {