@x12i/ai-gateway 9.2.0 → 9.3.0

package/README.md

@@ -368,6 +368,51 @@ The gateway only exposes official queryable clients. It exposes `activixClient`
 
 See [Runtime Objects Observability Methodology](./docs/RUNTIME_OBJECTS_OBSERVABILITY.md) for the reusable package-level contract.
 
+### Model catalog resolution and defaults (`@x12i/ai-tools`)
+
+Before each invoke, the gateway can normalize caller `config.model` / `modelConfig` via the **ai-models** Catalox catalog (`@x12i/ai-tools`). After invoke, when the router leaves cost **unpriced**, the gateway may compute USD from the same catalog.
+
+**Environment variables:**
+
+| Variable | Purpose |
+|----------|---------|
+| `AI_GATEWAY_DEFAULT_MODEL` | Default model when none is provided, or when resolution fails in **`mode=prod`**. Supports `provider/model` (e.g. `openrouter/openai/gpt-5-nano`) or a bare model id. |
+| `mode` / `MODE` | `prod` — unresolved models fall back to the default chain (with **Logxer `warn`**). `dev` / `debug` / omitted — unresolved models throw **`ModelResolutionError`**. |
+
+**Default model priority** (prod fallback only): `AI_GATEWAY_DEFAULT_MODEL` → `src/defaults/model-config.json` `defaultModel` → code constant `gpt-5-nano`.
+
+**Logxer warnings** on default substitution include structured fields: `reason` (`no_model_provided`, `model_resolution_failed`, `ai_tools_unavailable`), `defaultSource` (`env`, `model-config.json`, `code`), `originalModel`, `defaultModel`, and `mode`.
+
+Catalox/Firebase credentials are required for catalog bootstrap (same as `@x12i/ai-tools` — see that package’s README). Disable with `aiTools: { enabled: false }` on `GatewayConfig`, or inject `aiTools.catalox` for tests.
+
+**GatewayConfig (optional overrides):**
+
+```typescript
+const gateway = new AIGateway({
+  mode: 'prod', // or 'dev' | 'debug' — overrides process.env.mode
+  aiTools: {
+    enabled: true,
+    resolveModels: true,
+    calculateCost: true,
+    costIncludeBreakdown: false,
+    cacheTtlMs: 60_000,
+    // catalox: injectedCataloxInstance,
+  },
+});
+```
+
+**Tests before release:**
+
+```bash
+npm run build
+npm test                    # integration (tsx)
+npm run test:ai-tools       # unit: mode, defaults, cost helper
+npm run test:live           # LIVE: catalog + invoke (needs .env + Firebase + LLM key)
+npm run test:real:comprehensive  # optional: compiled real router matrix + npm test
+```
+
+See [`.env.example`](./.env.example) for `AI_GATEWAY_DEFAULT_MODEL`, `mode`, provider keys, and Firebase/Catalox variables.
+
 **Recommended (auto-configured from environment variables):**
 
 ```typescript

package/dist/ai-tools-client.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Lazy @x12i/ai-tools catalog + cost calculator bootstrap.
+ */
+import { AiModelsCatalogClient, CostCalculator, type ModelResolutionSuccess } from '@x12i/ai-tools';
+import type { Logxer } from '@x12i/logxer';
+import type { ChatRequest, GatewayConfig } from './types.js';
+export type AiToolsClientBundle = {
+    catalog: AiModelsCatalogClient;
+    calculator: CostCalculator;
+};
+/**
+ * Returns catalog + calculator, or null when disabled or bootstrap fails.
+ */
+export declare function getAiToolsClient(config: GatewayConfig, logger: Logxer): Promise<AiToolsClientBundle | null>;
+/** Reset singleton (tests). */
+export declare function resetAiToolsClientForTests(): void;
+/**
+ * Map catalog resolution to router config provider/model fields.
+ */
+export declare function applyModelResolution(merged: NonNullable<ChatRequest['config']>, resolution: ModelResolutionSuccess, gatewayDefaultEngine?: string): void;

package/dist/ai-tools-client.js

@@ -0,0 +1,91 @@
+/**
+ * Lazy @x12i/ai-tools catalog + cost calculator bootstrap.
+ */
+import { AiModelsCatalogClient, CostCalculator, ensureAiModelsCatalog } from '@x12i/ai-tools';
+import { gatewayLogDebug, withActivityIdentity } from './gateway-log-meta.js';
+let sharedClientPromise = null;
+let sharedConfigKey;
+let bootstrapFailedLogged = false;
+function configKey(config) {
+    const injected = config.aiTools?.catalox ? 'injected' : 'env';
+    return `${injected}:${config.aiTools?.cacheTtlMs ?? ''}:${config.aiTools?.costIncludeBreakdown ?? ''}`;
+}
+/**
+ * Returns catalog + calculator, or null when disabled or bootstrap fails.
+ */
+export async function getAiToolsClient(config, logger) {
+    if (config.aiTools?.enabled === false) {
+        return null;
+    }
+    const key = configKey(config);
+    if (sharedClientPromise && sharedConfigKey !== key) {
+        sharedClientPromise = null;
+    }
+    sharedConfigKey = key;
+    if (!sharedClientPromise) {
+        sharedClientPromise = bootstrapAiTools(config, logger);
+    }
+    return sharedClientPromise;
+}
+/** Reset singleton (tests). */
+export function resetAiToolsClientForTests() {
+    sharedClientPromise = null;
+    sharedConfigKey = undefined;
+    bootstrapFailedLogged = false;
+}
+async function bootstrapAiTools(config, logger) {
+    try {
+        let catalox = config.aiTools?.catalox;
+        if (!catalox) {
+            const { createCataloxFromEnv } = await import('@x12i/catalox/firebase');
+            const bootstrapped = createCataloxFromEnv();
+            catalox = bootstrapped.catalox;
+        }
+        await ensureAiModelsCatalog(catalox);
+        const catalog = new AiModelsCatalogClient({
+            catalox,
+            cacheTtlMs: config.aiTools?.cacheTtlMs
+        });
+        const calculator = new CostCalculator(catalog, {
+            includeBreakdown: config.aiTools?.costIncludeBreakdown === true
+        });
+        logger.debug('ai-tools catalog client ready', {
+            debugKind: gatewayLogDebug.state
+        });
+        return { catalog, calculator };
+    }
+    catch (error) {
+        if (!bootstrapFailedLogged) {
+            bootstrapFailedLogged = true;
+            logger.warn('ai-tools catalog bootstrap failed; model resolution and catalog cost calculation disabled', withActivityIdentity(undefined, {
+                error: error instanceof Error ? error.message : String(error),
+                debugKind: gatewayLogDebug.anomaly
+            }));
+        }
+        return null;
+    }
+}
+/**
+ * Map catalog resolution to router config provider/model fields.
+ */
+export function applyModelResolution(merged, resolution, gatewayDefaultEngine) {
+    if (resolution.routedViaOpenRouter) {
+        merged.provider = 'openrouter';
+        merged.model = resolution.modelId;
+        return;
+    }
+    const slash = resolution.modelId.indexOf('/');
+    if (slash > 0) {
+        merged.provider = resolution.record?.providerId ?? resolution.modelId.slice(0, slash);
+        merged.model = resolution.modelId.slice(slash + 1);
+    }
+    else {
+        merged.model = resolution.modelId;
+        if (resolution.record?.providerId) {
+            merged.provider = resolution.record.providerId;
+        }
+    }
+    if (!merged.provider && gatewayDefaultEngine) {
+        merged.provider = gatewayDefaultEngine;
+    }
+}

package/dist/gateway-config.d.ts

@@ -19,6 +19,7 @@ export interface GatewayConfigContext {
     usageTracker: UsageTracker;
     messageBuilderConfig: MessageBuilderConfig;
 }
+export type InitializedGatewayComponents = ReturnType<typeof initializeGatewayComponents>;
 /**
  * Loads configuration from JSON files (model config and instructionsBlocks).
  * Pass a {@link Logxer} instance so load diagnostics go through logxer (not console).
@@ -46,4 +47,5 @@ export declare function initializeGatewayComponents(config: GatewayConfig): {
     activityManager: ActivityManager;
     usageTracker: UsageTracker;
     messageBuilderConfig: MessageBuilderConfig;
+    defaultModelConfig: Record<string, unknown>;
 };

package/dist/gateway-config.js

@@ -283,6 +283,7 @@ export function initializeGatewayComponents(config) {
         router,
         activityManager,
         usageTracker,
-        messageBuilderConfig
+        messageBuilderConfig,
+        defaultModelConfig
     };
 }

package/dist/gateway-mode.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Gateway operational mode (prod vs dev/debug) and default model resolution.
+ */
+import type { Logxer } from '@x12i/logxer';
+import type { ActivityIdentity, GatewayConfig } from './types.js';
+export type GatewayOperationalMode = 'prod' | 'debug' | 'dev';
+export type GatewayDefaultModelSource = 'env' | 'model-config.json' | 'code';
+export type DefaultModelSubstitutionReason = 'no_model_provided' | 'model_resolution_failed' | 'ai_tools_unavailable';
+export declare const CODE_DEFAULT_MODEL = "gpt-5-nano";
+export type ResolvedGatewayDefault = {
+    model: string;
+    provider?: string;
+    source: GatewayDefaultModelSource;
+};
+/**
+ * Operational mode: `GatewayConfig.mode` overrides `process.env.mode` / `MODE`.
+ * Only `prod` allows silent default-model substitution; all other values are strict.
+ */
+export declare function getGatewayOperationalMode(config?: Pick<GatewayConfig, 'mode'>): GatewayOperationalMode;
+export declare function isProdGatewayMode(mode: GatewayOperationalMode): boolean;
+/**
+ * Parse `provider/model` or bare model id (OpenRouter ids may contain multiple slashes).
+ */
+export declare function parseModelProviderSpec(spec: string): {
+    provider?: string;
+    model: string;
+};
+/**
+ * Default model priority: AI_GATEWAY_DEFAULT_MODEL → model-config.json → code constant.
+ */
+export declare function resolveGatewayDefaultModel(defaultModelConfig?: Record<string, unknown>, gatewayDefaultEngine?: string): ResolvedGatewayDefault;
+export declare function warnDefaultModelSubstitution(logger: Logxer, identity: Partial<ActivityIdentity> | undefined, details: {
+    reason: DefaultModelSubstitutionReason;
+    mode: GatewayOperationalMode;
+    defaultSource: GatewayDefaultModelSource;
+    defaultProvider?: string;
+    defaultModel: string;
+    originalProvider?: string;
+    originalModel?: string;
+}): void;

package/dist/gateway-mode.js

@@ -0,0 +1,75 @@
+/**
+ * Gateway operational mode (prod vs dev/debug) and default model resolution.
+ */
+import { gatewayLogDebug, withActivityIdentity } from './gateway-log-meta.js';
+export const CODE_DEFAULT_MODEL = 'gpt-5-nano';
+/**
+ * Operational mode: `GatewayConfig.mode` overrides `process.env.mode` / `MODE`.
+ * Only `prod` allows silent default-model substitution; all other values are strict.
+ */
+export function getGatewayOperationalMode(config) {
+    if (config?.mode) {
+        return config.mode;
+    }
+    const raw = (process.env.mode ?? process.env.MODE ?? '').toLowerCase();
+    if (raw === 'prod')
+        return 'prod';
+    if (raw === 'dev')
+        return 'dev';
+    return 'debug';
+}
+export function isProdGatewayMode(mode) {
+    return mode === 'prod';
+}
+/**
+ * Parse `provider/model` or bare model id (OpenRouter ids may contain multiple slashes).
+ */
+export function parseModelProviderSpec(spec) {
+    const trimmed = spec.trim();
+    if (!trimmed) {
+        return { model: CODE_DEFAULT_MODEL };
+    }
+    const slash = trimmed.indexOf('/');
+    if (slash === -1) {
+        return { model: trimmed };
+    }
+    const first = trimmed.slice(0, slash);
+    const rest = trimmed.slice(slash + 1);
+    if (rest.includes('/') && (first === 'openrouter' || first === 'open-router')) {
+        return { provider: 'openrouter', model: trimmed };
+    }
+    return { provider: first, model: rest };
+}
+/**
+ * Default model priority: AI_GATEWAY_DEFAULT_MODEL → model-config.json → code constant.
+ */
+export function resolveGatewayDefaultModel(defaultModelConfig, gatewayDefaultEngine) {
+    const envSpec = process.env.AI_GATEWAY_DEFAULT_MODEL?.trim();
+    if (envSpec) {
+        const parsed = parseModelProviderSpec(envSpec);
+        return { model: parsed.model, provider: parsed.provider, source: 'env' };
+    }
+    const jsonModel = typeof defaultModelConfig?.defaultModel === 'string' ? defaultModelConfig.defaultModel : undefined;
+    if (jsonModel) {
+        const parsed = parseModelProviderSpec(jsonModel);
+        const jsonEngine = typeof defaultModelConfig?.defaultEngine === 'string'
+            ? defaultModelConfig.defaultEngine
+            : gatewayDefaultEngine;
+        return {
+            model: parsed.model,
+            provider: parsed.provider ?? jsonEngine,
+            source: 'model-config.json'
+        };
+    }
+    return {
+        model: CODE_DEFAULT_MODEL,
+        provider: gatewayDefaultEngine,
+        source: 'code'
+    };
+}
+export function warnDefaultModelSubstitution(logger, identity, details) {
+    logger.warn('Gateway substituted default model for request', withActivityIdentity(identity, {
+        ...details,
+        debugKind: gatewayLogDebug.anomaly
+    }));
+}

package/dist/gateway-utils.d.ts

@@ -4,6 +4,7 @@
  */
 import type { AIInvokeRequest, ChatRequest, GatewayConfig, GatewayInvokeRejectionMetadata, GatewayTraceMergedConfig, GatewayTraceRequestIds, ModelConfig } from './types.js';
 import type { Logxer } from '@x12i/logxer';
+import { type AiModelsCatalogClient, type CostCalculator } from '@x12i/ai-tools';
 /**
  * Generates MD5 hash of a string
  */
@@ -12,13 +13,17 @@ export declare function generateMD5Hash(text: string): string;
  * Auto-generates taskTypeId from MD5 hash of pre-parsed instructions if not provided
  */
 export declare function ensureTaskTypeId(request: ChatRequest, logger: Logxer): Promise<string>;
+export type MergeConfigOptions = {
+    defaultModelConfig?: Record<string, unknown>;
+    catalog?: AiModelsCatalogClient | null;
+};
 /**
  * Merges config with defaults
  * Supports using internal system action defaults (internalSkill or skillAudit) when useInternalDefaults is set
  */
 export declare function mergeConfig(request: ChatRequest & {
     useInternalDefaults?: 'skill' | 'audit';
-}, config: GatewayConfig, logger: Logxer): Promise<ChatRequest['config']>;
+}, config: GatewayConfig, logger: Logxer, mergeOptions?: MergeConfigOptions): Promise<ChatRequest['config']>;
 /**
  * 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).
@@ -48,6 +53,15 @@ export type ActivityCostStatus = 'priced' | 'unpriced';
 export type ResolvedActivityCost = {
     cost?: number;
     costStatus?: ActivityCostStatus;
+    costBreakdown?: {
+        promptCostUsd: number;
+        completionCostUsd: number;
+        cachingCostUsd?: number;
+        reasoningCostUsd?: number;
+        audioCostUsd?: number;
+        imageCostUsd?: number;
+        requestFlatCostUsd?: number;
+    };
 };
 export declare function hasNonZeroTokenUsage(tokens: {
     prompt: number;
@@ -72,6 +86,19 @@ export declare function resolveCostCompletionForActivity(routerResponse: unknown
     completion: number;
     total: number;
 }): ResolvedActivityCost;
+export type ResolveCostCompletionOptions = {
+    mergedConfig?: unknown;
+    calculator?: CostCalculator | null;
+    calculateCost?: boolean;
+};
+/**
+ * Router cost passthrough, then optional @x12i/ai-tools catalog pricing when still unpriced.
+ */
+export declare function resolveCostCompletionWithAiTools(routerResponse: unknown, tokens: {
+    prompt: number;
+    completion: number;
+    total: number;
+}, options?: ResolveCostCompletionOptions): Promise<ResolvedActivityCost>;
 /**
  * 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.

package/dist/gateway-utils.js

@@ -3,8 +3,11 @@
  * Handles utility functions
  */
 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
  */
@@ -29,11 +32,34 @@ export 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
  */
-export async function mergeConfig(request, config, logger) {
+export async function mergeConfig(request, config, logger, mergeOptions) {
     const useInternalDefaults = request.useInternalDefaults;
     const internalDefaults = useInternalDefaults
         ? (useInternalDefaults === 'skill'
@@ -52,8 +78,8 @@ export 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 ? {
@@ -87,18 +113,67 @@ export 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
@@ -359,6 +434,56 @@ export function resolveCostCompletionForActivity(routerResponse, tokens) {
     }
     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.

package/dist/gateway.d.ts

@@ -16,7 +16,9 @@ export declare class AIGateway {
     private logger;
     private activityManager?;
     private messageBuilderConfig?;
+    private defaultModelConfig;
     private _autoRegisterDone;
+    private _aiToolsClient;
     constructor(config?: GatewayConfig, activityManager?: ActivityManager);
     /**
      * Invoke chat request (without structured output requirements)
@@ -36,4 +38,5 @@ export declare class AIGateway {
     getLogger(): Logxer;
     getActivityManager(): ActivityManager | undefined;
     setActivityManager(activityManager: ActivityManager): void;
+    private getAiTools;
 }

package/dist/gateway.js

@@ -9,7 +9,8 @@ import { initializeGatewayComponents } from './gateway-config.js';
 import { buildMessages } from './message-builder.js';
 import { extractJsonFromFlexMd } from './flex-md-loader.js';
 import { enrichParsedContentForOutputContract, resolveOutputContractFieldKeys } from './output-contract-normalizer.js';
-import { attachGatewayInvokeRejectionMetadata, buildInvokeRejectionMetadata, capActivityFullResponsePayload, DEFAULT_ACTIVITY_FULL_RESPONSE_MAX_CHARS, extractCostUsdFromRouterResponse, extractTokenUsageFromRouterResponse, mergeConfig, pickEffectiveModelConfigForMetadata, pickInvokeRoutingMetadataSlice, pickTraceMergedRouterConfig, resolveCostCompletionForActivity, tryExtractRouterLikePayloadFromErrorChain } from './gateway-utils.js';
+import { attachGatewayInvokeRejectionMetadata, buildInvokeRejectionMetadata, capActivityFullResponsePayload, DEFAULT_ACTIVITY_FULL_RESPONSE_MAX_CHARS, extractCostUsdFromRouterResponse, extractTokenUsageFromRouterResponse, mergeConfig, pickEffectiveModelConfigForMetadata, pickInvokeRoutingMetadataSlice, pickTraceMergedRouterConfig, resolveCostCompletionWithAiTools, tryExtractRouterLikePayloadFromErrorChain } from './gateway-utils.js';
+import { getAiToolsClient } from './ai-tools-client.js';
 import { autoRegisterProviders } from './gateway-provider-auto-register.js';
 import { setGatewayLastJobId, setGatewayRuntimeClients } from './runtime-objects.js';
 import { gatewayLogDebug, withActivityIdentity } from './gateway-log-meta.js';
@@ -45,7 +46,9 @@ export class AIGateway {
     logger;
     activityManager;
     messageBuilderConfig;
+    defaultModelConfig = {};
     _autoRegisterDone = false;
+    _aiToolsClient = null;
     constructor(config = {}, activityManager) {
         this.config = config;
         this.activityManager = activityManager;
@@ -54,6 +57,7 @@ export class AIGateway {
         this.router = components.router;
         this.activityManager = components.activityManager;
         this.messageBuilderConfig = components.messageBuilderConfig;
+        this.defaultModelConfig = components.defaultModelConfig ?? {};
         setGatewayRuntimeClients({
             activix: this.activityManager?.getTracker(),
             logger: this.logger
@@ -77,7 +81,11 @@ export class AIGateway {
         // Simple message construction
         const messages = this.buildSimpleMessages(request);
         // Merge config (modelConfig > request.config > gateway defaults)
-        const mergedConfig = await mergeConfig(request, this.config, this.logger);
+        const aiTools = await this.getAiTools();
+        const mergedConfig = await mergeConfig(request, this.config, this.logger, {
+            defaultModelConfig: this.defaultModelConfig,
+            catalog: aiTools?.catalog ?? null
+        });
         // 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
@@ -111,7 +119,11 @@ export class AIGateway {
             });
             const metaChat = response?.metadata || {};
             const tokensChat = extractTokenUsageFromRouterResponse(response);
-            const costCompletionChat = resolveCostCompletionForActivity(response, tokensChat);
+            const costCompletionChat = await resolveCostCompletionWithAiTools(response, tokensChat, {
+                mergedConfig,
+                calculator: aiTools?.calculator ?? null,
+                calculateCost: this.config.aiTools?.calculateCost
+            });
             // Create enhanced response
             const enhancedResponse = {
                 content: response.content || '',
@@ -250,7 +262,11 @@ export class AIGateway {
         // Attach parsedSnapshot to request for activity tracking
         request._parsedRequest = parsedSnapshot;
         // Merge config (modelConfig > request.config > gateway defaults)
-        const mergedConfig = await mergeConfig(request, this.config, this.logger);
+        const aiTools = await this.getAiTools();
+        const mergedConfig = await mergeConfig(request, this.config, this.logger, {
+            defaultModelConfig: this.defaultModelConfig,
+            catalog: aiTools?.catalog ?? null
+        });
         request._mergedRouterConfig = mergedConfig;
         const diagnosticsMode = request.diagnostics?.mode;
         const traceEnabled = diagnosticsMode === 'trace';
@@ -539,7 +555,11 @@ export class AIGateway {
                         tokens = second;
                 }
             }
-            const costCompletion = resolveCostCompletionForActivity(routerResponse, tokens);
+            const costCompletion = await resolveCostCompletionWithAiTools(routerResponse, tokens, {
+                mergedConfig,
+                calculator: aiTools?.calculator ?? null,
+                calculateCost: this.config.aiTools?.calculateCost
+            });
             const routerMetaForCost = routerResponse?.metadata || {};
             const routingMetadataSlice = pickInvokeRoutingMetadataSlice(routerResponse, mergedConfig);
             const effectiveModelConfig = pickEffectiveModelConfigForMetadata(mergedConfig);
@@ -707,6 +727,10 @@ export class AIGateway {
             logger: this.logger
         });
     }
+    getAiTools() {
+        this._aiToolsClient ??= getAiToolsClient(this.config, this.logger);
+        return this._aiToolsClient;
+    }
 }
 function resolveRuntimeJobId(request) {
     return request.identity.jobId || request.identity.sessionId || request.aiRequestId;