@x12i/ai-gateway 9.1.0 → 9.1.1

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 { ChatRequest, GatewayConfig, ModelConfig } from './types.js';
 import type { Logxer } from '@x12i/logxer';
 /**
  * Generates MD5 hash of a string
@@ -43,6 +43,20 @@ 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;
 /** Default JSON string length cap for Activix `content.fullResponse` when diagnostics allow storing it. */
 export declare const DEFAULT_ACTIVITY_FULL_RESPONSE_MAX_CHARS = 512000;
 /**

package/dist/gateway-utils.js

@@ -315,6 +315,49 @@ 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;
+}
 /** 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 { capActivityFullResponsePayload, DEFAULT_ACTIVITY_FULL_RESPONSE_MAX_CHARS, extractCostUsdFromRouterResponse, extractTokenUsageFromRouterResponse, mergeConfig, pickEffectiveModelConfigForMetadata, pickInvokeRoutingMetadataSlice } 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';
@@ -524,6 +524,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 +538,8 @@ export class AIGateway {
                     agentType: 'ai',
                     contentType,
                     parsingMethod,
+                    ...routingMetadataSlice,
+                    ...(effectiveModelConfig !== undefined ? { effectiveModelConfig } : {}),
                     ...(typeof resolvedCostUsd === 'number'
                         ? {
                             costUsd: resolvedCostUsd,
@@ -545,27 +549,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
+                        }
                         : {})
                 }
             };

package/dist/types.d.ts

@@ -876,7 +876,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 +885,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,8 @@ exports.mergeConfig = mergeConfig;
 exports.normalizeRouterUsageTokens = normalizeRouterUsageTokens;
 exports.extractTokenUsageFromRouterResponse = extractTokenUsageFromRouterResponse;
 exports.extractCostUsdFromRouterResponse = extractCostUsdFromRouterResponse;
+exports.pickInvokeRoutingMetadataSlice = pickInvokeRoutingMetadataSlice;
+exports.pickEffectiveModelConfigForMetadata = pickEffectiveModelConfigForMetadata;
 exports.capActivityFullResponsePayload = capActivityFullResponsePayload;
 const crypto = __importStar(require("crypto"));
 const gateway_instructions_js_1 = require("./gateway-instructions.cjs");
@@ -358,6 +360,49 @@ 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;
+}
 /** 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 { ChatRequest, GatewayConfig, ModelConfig } from './types.js';
 import type { Logxer } from '@x12i/logxer';
 /**
  * Generates MD5 hash of a string
@@ -43,6 +43,20 @@ 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;
 /** Default JSON string length cap for Activix `content.fullResponse` when diagnostics allow storing it. */
 export declare const DEFAULT_ACTIVITY_FULL_RESPONSE_MAX_CHARS = 512000;
 /**

package/dist-cjs/gateway.cjs

@@ -527,6 +527,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 +541,8 @@ class AIGateway {
                     agentType: 'ai',
                     contentType,
                     parsingMethod,
+                    ...routingMetadataSlice,
+                    ...(effectiveModelConfig !== undefined ? { effectiveModelConfig } : {}),
                     ...(typeof resolvedCostUsd === 'number'
                         ? {
                             costUsd: resolvedCostUsd,
@@ -548,27 +552,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
+                        }
                         : {})
                 }
             };

package/dist-cjs/types.d.ts

@@ -876,7 +876,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 +885,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.1",
   "description": "AI Gateway - Unified interface for LLM provider routing and management",
   "type": "module",
   "exports": {