@x12i/ai-gateway 9.1.6 → 9.3.0

package/dist-cjs/gateway-provider.cjs

@@ -1,23 +1,11 @@
-"use strict";
 /**
  * Gateway Provider Module
  * Handles provider management
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.registerProvider = registerProvider;
-exports.unregisterProvider = unregisterProvider;
-exports.getProvider = getProvider;
-exports.listProviders = listProviders;
-exports.setDefaultProvider = setDefaultProvider;
-exports.setFallbackChain = setFallbackChain;
-exports.addRequestInterceptor = addRequestInterceptor;
-exports.addResponseInterceptor = addResponseInterceptor;
-exports.checkHealth = checkHealth;
-exports.checkAllHealth = checkAllHealth;
 /**
  * Register a provider with the router
  */
-function registerProvider(provider, router, logger) {
+export function registerProvider(provider, router, logger) {
     // Get provider name - try multiple methods
     let providerName = 'unknown';
     if (typeof provider.getProviderName === 'function') {
@@ -103,7 +91,7 @@ function registerProvider(provider, router, logger) {
 /**
  * Unregister a provider
  */
-function unregisterProvider(providerName, router, logger) {
+export function unregisterProvider(providerName, router, logger) {
     try {
         // Try to access registry directly to remove the provider
         const registry = router.getProviderRegistry();
@@ -128,7 +116,7 @@ function unregisterProvider(providerName, router, logger) {
 /**
  * Get a provider module
  */
-function getProvider(providerName, router) {
+export function getProvider(providerName, router) {
     try {
         const registry = router.getProviderRegistry();
         return registry.get(providerName);
@@ -141,7 +129,7 @@ function getProvider(providerName, router) {
 /**
  * List all registered providers
  */
-function listProviders(router) {
+export function listProviders(router) {
     return router.listProviders();
 }
 /**
@@ -151,7 +139,7 @@ function listProviders(router) {
  * This method is kept for API compatibility but does nothing.
  * Default provider must be set in router config during initialization.
  */
-function setDefaultProvider(provider, router, logger) {
+export function setDefaultProvider(provider, router, logger) {
     // Router doesn't support changing default provider after initialization
     // Default provider must be set in router config during initialization
     logger.warn('setDefaultProvider called but router does not support changing default provider after initialization', {
@@ -166,7 +154,7 @@ function setDefaultProvider(provider, router, logger) {
  * This method is kept for API compatibility but does nothing.
  * Fallback chain must be set in router config during initialization.
  */
-function setFallbackChain(chain, router, logger) {
+export function setFallbackChain(chain, router, logger) {
     // Router doesn't support changing fallback chain after initialization
     // Fallback chain must be set in router config during initialization
     logger.warn('setFallbackChain called but router does not support changing fallback chain after initialization', {
@@ -177,25 +165,25 @@ function setFallbackChain(chain, router, logger) {
 /**
  * Add request interceptor
  */
-function addRequestInterceptor(interceptor, router) {
+export function addRequestInterceptor(interceptor, router) {
     router.addRequestInterceptor(interceptor);
 }
 /**
  * Add response interceptor
  */
-function addResponseInterceptor(interceptor, router) {
+export function addResponseInterceptor(interceptor, router) {
     router.addResponseInterceptor(interceptor);
 }
 /**
  * Check health of a provider
  */
-async function checkHealth(provider, router) {
+export async function checkHealth(provider, router) {
     return router.checkHealth(provider);
 }
 /**
  * Check health of all providers
  */
-async function checkAllHealth(router) {
+export async function checkAllHealth(router) {
     const providers = listProviders(router);
     const results = {};
     for (const provider of providers) {

package/dist-cjs/gateway-rate-limiter-constants.cjs

@@ -1,19 +1,16 @@
-"use strict";
 /**
  * Rate Limiter Constants
  *
  * Default values for rate limiting configuration.
  * These defaults ensure the system works safely even if config is missing.
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_RATE_LIMIT_ENABLED = exports.DEFAULT_RATE_LIMIT_MIN_INTERVAL_MS = void 0;
 /**
  * Default minimum interval between API calls (in milliseconds)
  * Used when rateLimit.defaultMinIntervalMs is not specified
  */
-exports.DEFAULT_RATE_LIMIT_MIN_INTERVAL_MS = 500;
+export const DEFAULT_RATE_LIMIT_MIN_INTERVAL_MS = 500;
 /**
  * Default enabled state for rate limiting
  * Used when rateLimit.enabled is not specified
  */
-exports.DEFAULT_RATE_LIMIT_ENABLED = true;
+export const DEFAULT_RATE_LIMIT_ENABLED = true;

package/dist-cjs/gateway-rate-limiter.cjs

@@ -1,4 +1,3 @@
-"use strict";
 /**
  * Gateway Rate Limiter
  *
@@ -12,10 +11,8 @@
  * and only waits if necessary to maintain minimum intervals between separate API calls.
  * This prevents unnecessary delays when enough time has already passed.
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.GatewayRateLimiter = void 0;
-const gateway_retry_js_1 = require("./gateway-retry.cjs");
-const gateway_rate_limiter_constants_js_1 = require("./gateway-rate-limiter-constants.cjs");
+import { sleep } from './gateway-retry.js';
+import { DEFAULT_RATE_LIMIT_MIN_INTERVAL_MS } from './gateway-rate-limiter-constants.js';
 /**
  * Smart Rate Limiter (Between-Calls Only)
  *
@@ -27,12 +24,12 @@ const gateway_rate_limiter_constants_js_1 = require("./gateway-rate-limiter-cons
  *
  * This ensures minimum intervals between separate API calls regardless of what happens between them.
  */
-class GatewayRateLimiter {
+export class GatewayRateLimiter {
     lastCallTimes = new Map(); // provider -> last call timestamp
     defaultMinIntervalMs;
     providerIntervals = new Map(); // provider -> min interval
     logger;
-    constructor(defaultMinIntervalMs = gateway_rate_limiter_constants_js_1.DEFAULT_RATE_LIMIT_MIN_INTERVAL_MS, providerIntervals, logger) {
+    constructor(defaultMinIntervalMs = DEFAULT_RATE_LIMIT_MIN_INTERVAL_MS, providerIntervals, logger) {
         this.defaultMinIntervalMs = defaultMinIntervalMs;
         this.logger = logger;
         // Store per-provider intervals
@@ -69,7 +66,7 @@ class GatewayRateLimiter {
                 minIntervalMs,
                 usingProviderSpecific: this.providerIntervals.has(provider.toLowerCase())
             });
-            await (0, gateway_retry_js_1.sleep)(waitTime);
+            await sleep(waitTime);
         }
         else {
             this.logger?.verbose('Rate limit OK: enough time has passed', {
@@ -108,4 +105,3 @@ class GatewayRateLimiter {
         }
     }
 }
-exports.GatewayRateLimiter = GatewayRateLimiter;

package/dist-cjs/gateway-retry.cjs

@@ -1,4 +1,3 @@
-"use strict";
 /**
  * Gateway Retry Module
  * Handles retry logic for network and server errors
@@ -6,17 +5,10 @@
  * NOTE: Retry delays use SIMPLE SLEEP (not smart rate limiting).
  * Between-calls rate limiting is handled separately in gateway-rate-limiter.ts (smart).
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.isNetworkError = isNetworkError;
-exports.extractHttpStatusCode = extractHttpStatusCode;
-exports.isRetryableHttpError = isRetryableHttpError;
-exports.isRetryableError = isRetryableError;
-exports.sleep = sleep;
-exports.invokeWithRetry = invokeWithRetry;
 /**
  * Determines if an error is a network error (fetch failed, DNS, connectivity)
  */
-function isNetworkError(error) {
+export function isNetworkError(error) {
     const message = error.message.toLowerCase();
     const networkPatterns = [
         'fetch failed',
@@ -35,7 +27,7 @@ function isNetworkError(error) {
 /**
  * Extracts HTTP status code from error message or error object properties
  */
-function extractHttpStatusCode(error) {
+export function extractHttpStatusCode(error) {
     // Try to extract from error message
     const statusMatch = error.message.match(/\b(4\d{2}|5\d{2})\b/);
     if (statusMatch) {
@@ -59,7 +51,7 @@ function extractHttpStatusCode(error) {
  * Retryable: 429 (throttling), 5xx (server errors)
  * Non-retryable: 4xx except 429 (client errors)
  */
-function isRetryableHttpError(error, statusCode) {
+export function isRetryableHttpError(error, statusCode) {
     // 429 (throttling) is retryable
     if (statusCode === 429) {
         return true;
@@ -74,7 +66,7 @@ function isRetryableHttpError(error, statusCode) {
 /**
  * Determines if an error should be retried
  */
-function isRetryableError(error) {
+export function isRetryableError(error) {
     // Network errors are always retryable
     if (isNetworkError(error)) {
         return true;
@@ -94,14 +86,14 @@ function isRetryableError(error) {
 /**
  * Sleep helper for retry delays
  */
-function sleep(ms) {
+export function sleep(ms) {
     return new Promise(resolve => setTimeout(resolve, ms));
 }
 /**
  * Invokes router with retry logic for network and server errors
  * Returns response and retry metadata
  */
-async function invokeWithRetry(routerRequest, retryConfig, jobId, router, logger, hooks) {
+export async function invokeWithRetry(routerRequest, retryConfig, jobId, router, logger, hooks) {
     const maxRetries = retryConfig.maxRetries ?? 3;
     const initialDelay = retryConfig.initialDelay ?? 1000;
     const maxDelay = retryConfig.maxDelay ?? 30000;

package/dist-cjs/gateway-utils.cjs

@@ -1,75 +1,27 @@
-"use strict";
 /**
  * Gateway Utilities Module
  * Handles utility functions
  */
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_ACTIVITY_FULL_RESPONSE_MAX_CHARS = void 0;
-exports.generateMD5Hash = generateMD5Hash;
-exports.ensureTaskTypeId = ensureTaskTypeId;
-exports.mergeConfig = mergeConfig;
-exports.normalizeRouterUsageTokens = normalizeRouterUsageTokens;
-exports.extractTokenUsageFromRouterResponse = extractTokenUsageFromRouterResponse;
-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");
-const flex_md_loader_js_1 = require("./flex-md-loader.cjs");
+import * as crypto from 'crypto';
+import { ModelResolutionError } from '@x12i/ai-tools';
+import { getPreParsedInstructions } from './gateway-instructions.js';
+import { getModelMaxTokensFromFlexMd } from './flex-md-loader.js';
+import { applyModelResolution } from './ai-tools-client.js';
+import { getGatewayOperationalMode, isProdGatewayMode, resolveGatewayDefaultModel, warnDefaultModelSubstitution } from './gateway-mode.js';
 /**
  * Generates MD5 hash of a string
  */
-function generateMD5Hash(text) {
+export function generateMD5Hash(text) {
     return crypto.createHash('md5').update(text).digest('hex');
 }
 /**
  * Auto-generates taskTypeId from MD5 hash of pre-parsed instructions if not provided
  */
-async function ensureTaskTypeId(request, logger) {
+export async function ensureTaskTypeId(request, logger) {
     if (request.taskTypeId) {
         return request.taskTypeId;
     }
-    const preParsedInstructions = (0, gateway_instructions_js_1.getPreParsedInstructions)(request.instructions);
+    const preParsedInstructions = getPreParsedInstructions(request.instructions);
     // Generate MD5 hash
     const taskTypeId = generateMD5Hash(preParsedInstructions);
     logger.debug('Auto-generated taskTypeId from instructions MD5 hash', {
@@ -80,11 +32,34 @@ async function ensureTaskTypeId(request, logger) {
     });
     return taskTypeId;
 }
+function applyGatewayDefaultToMerged(merged, defaults, config) {
+    merged.model = defaults.model;
+    if (defaults.provider) {
+        merged.provider = defaults.provider;
+    }
+    else if (!merged.provider) {
+        merged.provider = config.defaultEngine;
+    }
+}
+async function substituteGatewayDefaultModel(merged, request, config, logger, mergeOptions, reason, original) {
+    const operationalMode = getGatewayOperationalMode(config);
+    const defaults = resolveGatewayDefaultModel(mergeOptions?.defaultModelConfig, config.defaultEngine);
+    warnDefaultModelSubstitution(logger, request.identity, {
+        reason,
+        mode: operationalMode,
+        defaultSource: defaults.source,
+        defaultProvider: defaults.provider ?? merged.provider,
+        defaultModel: defaults.model,
+        originalProvider: original?.provider ?? merged.provider,
+        originalModel: original?.model
+    });
+    applyGatewayDefaultToMerged(merged, defaults, config);
+}
 /**
  * Merges config with defaults
  * Supports using internal system action defaults (internalSkill or skillAudit) when useInternalDefaults is set
  */
-async function mergeConfig(request, config, logger) {
+export async function mergeConfig(request, config, logger, mergeOptions) {
     const useInternalDefaults = request.useInternalDefaults;
     const internalDefaults = useInternalDefaults
         ? (useInternalDefaults === 'skill'
@@ -103,8 +78,8 @@ async function mergeConfig(request, config, logger) {
         useInternalDefaults,
         hasInternalDefaults: !!internalDefaults
     });
-    // Default model to "gpt-5-nano" if nothing is provided (most permissive - always works)
-    const defaultModel = 'gpt-5-nano';
+    const operationalMode = getGatewayOperationalMode(config);
+    const resolveModels = config.aiTools?.resolveModels !== false;
     // Priority: modelConfig > request.config > internalSystemActions[useInternalDefaults] > gateway defaults
     // First, merge modelConfig into a config-like object if present
     const modelConfigAsConfig = request.modelConfig ? {
@@ -138,18 +113,67 @@ async function mergeConfig(request, config, logger) {
         ...request.config,
         // ModelConfig overrides (highest priority) - merge only defined values
         ...(modelConfigAsConfig ? Object.fromEntries(Object.entries(modelConfigAsConfig).filter(([_, value]) => value !== undefined)) : {}),
-        // Ensure model is set: modelConfig > request.config > internalDefaults > default
-        model: modelConfigAsConfig?.model || request.config?.model || internalDefaults?.model || defaultModel,
+        // Model resolved below (catalog, default chain, or explicit pass-through)
+        model: modelConfigAsConfig?.model || request.config?.model || internalDefaults?.model,
         // Ensure provider is set: modelConfig > request.config > internalDefaults > gateway default
-        // Provider is required for router to know which provider to use
         provider: modelConfigAsConfig?.provider || request.config?.provider || internalDefaults?.engine || config.defaultEngine
     };
-    // Log if using default model
-    if (!request.config?.model && !internalDefaults?.model) {
-        logger.info('Using default model: gpt-5-nano (no model provided in request)', {
-            jobId: request.identity.jobId,
-            note: 'Default model ensures requests always work regardless of configuration'
-        });
+    const explicitModel = merged.model;
+    const originalProvider = merged.provider;
+    const originalModel = explicitModel;
+    if (!explicitModel) {
+        await substituteGatewayDefaultModel(merged, request, config, logger, mergeOptions, 'no_model_provided');
+    }
+    else if (resolveModels && mergeOptions?.catalog) {
+        try {
+            const resolution = await mergeOptions.catalog.resolveModel({
+                provider: merged.provider,
+                model: explicitModel
+            });
+            if (resolution.found) {
+                applyModelResolution(merged, resolution, config.defaultEngine);
+                request._modelResolution = {
+                    modelId: resolution.modelId,
+                    routedViaOpenRouter: resolution.routedViaOpenRouter,
+                    confidence: resolution.confidence,
+                    resolvedVia: resolution.resolvedVia,
+                    originalProvider,
+                    originalModel
+                };
+                logger.verbose('Catalog resolved model name', {
+                    jobId: request.identity.jobId,
+                    originalModel,
+                    resolvedModelId: resolution.modelId,
+                    provider: merged.provider,
+                    model: merged.model,
+                    confidence: resolution.confidence,
+                    resolvedVia: resolution.resolvedVia
+                });
+            }
+            else if (isProdGatewayMode(operationalMode)) {
+                await substituteGatewayDefaultModel(merged, request, config, logger, mergeOptions, 'model_resolution_failed', { provider: originalProvider, model: originalModel });
+            }
+            else {
+                throw new ModelResolutionError({ provider: merged.provider, model: explicitModel }, resolution);
+            }
+        }
+        catch (error) {
+            if (error instanceof ModelResolutionError) {
+                throw error;
+            }
+            if (isProdGatewayMode(operationalMode)) {
+                await substituteGatewayDefaultModel(merged, request, config, logger, mergeOptions, 'ai_tools_unavailable', { provider: originalProvider, model: originalModel });
+            }
+            else {
+                throw error;
+            }
+        }
+    }
+    else if (resolveModels && !mergeOptions?.catalog && isProdGatewayMode(operationalMode)) {
+        await substituteGatewayDefaultModel(merged, request, config, logger, mergeOptions, 'ai_tools_unavailable', { provider: originalProvider, model: originalModel });
+    }
+    if (!merged.model) {
+        await substituteGatewayDefaultModel(merged, request, config, logger, mergeOptions, 'no_model_provided');
     }
     // Auto-get maxTokens from flex-md if not explicitly set in ANY config source
     // Check all possible sources: request.config, internalDefaults, gateway config
@@ -159,7 +183,7 @@ async function mergeConfig(request, config, logger) {
     if (!maxTokensExplicitlySet && merged.model && merged.provider) {
         // Try to get maxTokens from flex-md
         try {
-            const flexMdMaxTokens = await (0, flex_md_loader_js_1.getModelMaxTokensFromFlexMd)(merged.provider, merged.model);
+            const flexMdMaxTokens = await getModelMaxTokensFromFlexMd(merged.provider, merged.model);
             if (flexMdMaxTokens && flexMdMaxTokens > 0) {
                 merged.maxTokens = flexMdMaxTokens;
                 logger.debug('Using maxTokens from flex-md', {
@@ -249,7 +273,7 @@ function isNonZeroTokenCount(n) {
  * Maps provider/router usage objects to gateway token counts (`metadata.tokens`, Activix, trace attempts).
  * Handles promptTokens/inputTokens, OpenAI-style snake_case, Responses-style input/output tokens, and missing total (sum prompt+completion).
  */
-function normalizeRouterUsageTokens(usage) {
+export function normalizeRouterUsageTokens(usage) {
     if (usage == null || typeof usage !== 'object')
         return undefined;
     const u = usage;
@@ -297,7 +321,7 @@ function firstNonZeroUsageFromBuckets(buckets) {
  * Reads token usage from every stable location the router may populate (see docs/PROVIDERS_ROUTER_DIAGNOSTICS_TRACE_REQUIREMENTS.md).
  * Prefers the raw/provider body (`rawResponse` / `raw`) when it carries non-zero usage before re-reading the outer envelope.
  */
-function extractTokenUsageFromRouterResponse(routerResponse) {
+export function extractTokenUsageFromRouterResponse(routerResponse) {
     const zeros = { prompt: 0, completion: 0, total: 0 };
     if (routerResponse == null || typeof routerResponse !== 'object') {
         return zeros;
@@ -324,7 +348,7 @@ function extractTokenUsageFromRouterResponse(routerResponse) {
  * metadata.attempts[].costUsd, response root, then common raw payload locations.
  * Does not compute cost from tokens — adapters must populate normalized fields or raw usage.cost-style keys.
  */
-function extractCostUsdFromRouterResponse(routerResponse) {
+export function extractCostUsdFromRouterResponse(routerResponse) {
     if (routerResponse == null || typeof routerResponse !== 'object')
         return undefined;
     const r = routerResponse;
@@ -366,11 +390,105 @@ function extractCostUsdFromRouterResponse(routerResponse) {
     }
     return undefined;
 }
+export function hasNonZeroTokenUsage(tokens) {
+    return !!(tokens.prompt || tokens.completion || tokens.total);
+}
+function pickRouterCostStatus(routerResponse) {
+    if (routerResponse == null || typeof routerResponse !== 'object')
+        return undefined;
+    const r = routerResponse;
+    const meta = r.metadata != null && typeof r.metadata === 'object'
+        ? r.metadata
+        : undefined;
+    const status = meta?.costStatus ?? r.costStatus;
+    return status === 'priced' || status === 'unpriced' ? status : undefined;
+}
+/**
+ * Gateway fallback when the router does not set `metadata.costStatus`.
+ * Prefer {@link resolveCostCompletionForActivity} at invoke boundaries.
+ */
+export function resolveActivityCostCompletion(tokens, costUsd) {
+    if (typeof costUsd === 'number' && Number.isFinite(costUsd)) {
+        return { cost: costUsd, costStatus: 'priced' };
+    }
+    if (hasNonZeroTokenUsage(tokens)) {
+        return { costStatus: 'unpriced' };
+    }
+    return {};
+}
+/**
+ * Activity cost slice for Activix: router `metadata.costStatus` / cost wins when present;
+ * otherwise gateway applies the G8 fallback (usage + no price → `unpriced`).
+ */
+export function resolveCostCompletionForActivity(routerResponse, tokens) {
+    const routerStatus = pickRouterCostStatus(routerResponse);
+    const costUsd = extractCostUsdFromRouterResponse(routerResponse);
+    if (routerStatus === 'priced') {
+        return {
+            ...(typeof costUsd === 'number' && Number.isFinite(costUsd) ? { cost: costUsd } : {}),
+            costStatus: 'priced'
+        };
+    }
+    if (routerStatus === 'unpriced') {
+        return { costStatus: 'unpriced' };
+    }
+    return resolveActivityCostCompletion(tokens, costUsd);
+}
+/**
+ * Router cost passthrough, then optional @x12i/ai-tools catalog pricing when still unpriced.
+ */
+export async function resolveCostCompletionWithAiTools(routerResponse, tokens, options) {
+    const routerStatus = pickRouterCostStatus(routerResponse);
+    const base = resolveCostCompletionForActivity(routerResponse, tokens);
+    if (base.costStatus === 'priced') {
+        return base;
+    }
+    if (routerStatus === 'unpriced') {
+        return base;
+    }
+    if (options?.calculateCost === false || !options?.calculator) {
+        return base;
+    }
+    if (!hasNonZeroTokenUsage(tokens)) {
+        return base;
+    }
+    const routing = pickInvokeRoutingMetadataSlice(routerResponse, options.mergedConfig);
+    const cfg = options.mergedConfig != null && typeof options.mergedConfig === 'object'
+        ? options.mergedConfig
+        : {};
+    const provider = routing.provider ?? cfg.provider;
+    const modelUsed = routing.modelUsed ?? cfg.model;
+    if (!provider || !modelUsed) {
+        return base;
+    }
+    try {
+        const result = await options.calculator.calculate({
+            tokens: {
+                prompt: tokens.prompt,
+                completion: tokens.completion,
+                total: tokens.total
+            },
+            provider,
+            modelUsed
+        });
+        if (typeof result.cost === 'number' && Number.isFinite(result.cost)) {
+            return {
+                cost: result.cost,
+                costStatus: 'priced',
+                ...(result.breakdown ? { costBreakdown: result.breakdown } : {})
+            };
+        }
+    }
+    catch {
+        // Keep router/gateway unpriced fallback
+    }
+    return base;
+}
 /**
  * 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) {
+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 : {};
@@ -396,7 +514,7 @@ function pickInvokeRoutingMetadataSlice(routerResponse, mergedConfig) {
 /**
  * Allowlisted generation profile from merged config for client introspection (no secrets, no arbitrary extras).
  */
-function pickEffectiveModelConfigForMetadata(mergedConfig) {
+export function pickEffectiveModelConfigForMetadata(mergedConfig) {
     if (mergedConfig == null || typeof mergedConfig !== 'object')
         return undefined;
     const c = mergedConfig;
@@ -419,7 +537,7 @@ const TRACE_MERGED_ROUTER_NUMERIC_KEYS = [
 /**
  * Allowlisted snapshot of merged router config for diagnostics trace responses (no arbitrary extras).
  */
-function pickTraceMergedRouterConfig(mergedConfig) {
+export function pickTraceMergedRouterConfig(mergedConfig) {
     if (mergedConfig == null || typeof mergedConfig !== 'object')
         return undefined;
     const c = mergedConfig;
@@ -448,7 +566,7 @@ const EFFECTIVE_MODEL_CONFIG_KEYS = ['model', 'modelId', 'provider', 'temperatur
  * Allowlisted generation fields from request only (before mergeConfig / flex-md).
  * Priority matches mergeConfig: modelConfig overrides request.config per key.
  */
-function pickEffectiveModelConfigFromInvokeRequest(request) {
+export function pickEffectiveModelConfigFromInvokeRequest(request) {
     const cfg = (request.config ?? {});
     const mc = (request.modelConfig ?? {});
     const out = {};
@@ -476,7 +594,7 @@ function isRouterLikeEnvelope(value) {
  * 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) {
+export function tryExtractRouterLikePayloadFromErrorChain(error, maxDepth = 8) {
     const seen = new Set();
     let cur = error;
     for (let i = 0; i < maxDepth && cur != null; i++) {
@@ -497,7 +615,7 @@ function tryExtractRouterLikePayloadFromErrorChain(error, maxDepth = 8) {
     }
     return undefined;
 }
-function pickRequestIdsFromRouterLike(gatewayAiRequestId, routerLike) {
+export function pickRequestIdsFromRouterLike(gatewayAiRequestId, routerLike) {
     if (typeof gatewayAiRequestId !== 'string' || gatewayAiRequestId.length === 0) {
         return undefined;
     }
@@ -523,7 +641,7 @@ function pickRequestIdsFromRouterLike(gatewayAiRequestId, routerLike) {
     }
     return out;
 }
-function buildInvokeRejectionMetadata(args) {
+export function buildInvokeRejectionMetadata(args) {
     const gid = args.gatewayAiRequestId ?? args.request.aiRequestId;
     const partial = args.partialRouterPayload;
     const mc = args.mergedConfig;
@@ -548,16 +666,16 @@ function buildInvokeRejectionMetadata(args) {
         ...(mc === undefined ? { mergeConfigUnavailable: true } : {})
     };
 }
-function attachGatewayInvokeRejectionMetadata(err, metadata) {
+export 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;
+export const DEFAULT_ACTIVITY_FULL_RESPONSE_MAX_CHARS = 512_000;
 /**
  * Size-cap a provider/router payload before storing on an activity record.
  * Non-serializable values become a small marker object instead of throwing.
  */
-function capActivityFullResponsePayload(payload, maxChars = exports.DEFAULT_ACTIVITY_FULL_RESPONSE_MAX_CHARS) {
+export function capActivityFullResponsePayload(payload, maxChars = DEFAULT_ACTIVITY_FULL_RESPONSE_MAX_CHARS) {
     if (payload == null)
         return payload;
     let serialized;