@x12i/ai-gateway 9.2.0 → 9.3.4

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 || '',
@@ -130,7 +142,10 @@ export class AIGateway {
                                 : { cost: costCompletionChat.cost })
                         }
                         : {}),
-                    ...(costCompletionChat.costStatus ? { costStatus: costCompletionChat.costStatus } : {})
+                    ...(costCompletionChat.costStatus ? { costStatus: costCompletionChat.costStatus } : {}),
+                    ...(costCompletionChat.costBreakdown
+                        ? { costBreakdown: costCompletionChat.costBreakdown }
+                        : {})
                 }
             };
             // Track activity success if activity was started
@@ -250,7 +265,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 +558,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);
@@ -567,6 +590,7 @@ export class AIGateway {
                         }
                         : {}),
                     ...(costCompletion.costStatus ? { costStatus: costCompletion.costStatus } : {}),
+                    ...(costCompletion.costBreakdown ? { costBreakdown: costCompletion.costBreakdown } : {}),
                     ...(traceEnabled
                         ? {
                             requestIds: traceRequestIds,
@@ -707,6 +731,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;

package/dist/index.d.ts

@@ -17,7 +17,9 @@ 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, GatewayTraceMergedConfig, EnhancedLLMResponse, InstructionMetadata, ValidationRule, TemplateRenderOptions, SmartInputConfig, SmartInputRenderOptions } from './types.js';
-export { attachGatewayInvokeRejectionMetadata, buildInvokeRejectionMetadata, tryExtractRouterLikePayloadFromErrorChain, pickRequestIdsFromRouterLike, resolveActivityCostCompletion, resolveCostCompletionForActivity, hasNonZeroTokenUsage } from './gateway-utils.js';
+export { attachGatewayInvokeRejectionMetadata, buildInvokeRejectionMetadata, tryExtractRouterLikePayloadFromErrorChain, pickRequestIdsFromRouterLike, resolveActivityCostCompletion, resolveCostCompletionForActivity, resolveCostCompletionWithAiTools, hasNonZeroTokenUsage } from './gateway-utils.js';
+export { getGatewayOperationalMode, isProdGatewayMode, resolveGatewayDefaultModel, parseModelProviderSpec, CODE_DEFAULT_MODEL } from './gateway-mode.js';
+export type { GatewayOperationalMode, GatewayDefaultModelSource, DefaultModelSubstitutionReason, ResolvedGatewayDefault } from './gateway-mode.js';
 export type { ActivityCostStatus, ResolvedActivityCost } from './gateway-utils.js';
 export { contractSpecToFieldKeys, enrichParsedContentForOutputContract, resolveOutputContractFieldKeys } from './output-contract-normalizer.js';
 export type { OutputContractSpec } from './output-contract-normalizer.js';

package/dist/index.js

@@ -17,7 +17,8 @@ export * from '@x12i/ai-providers-router';
 export { AIGateway } from './gateway.js';
 export { InstructionNotFoundError, InstructionBackendError } from './instruction-errors.js';
 export { autoRegisterProviders } from './gateway-provider-auto-register.js';
-export { attachGatewayInvokeRejectionMetadata, buildInvokeRejectionMetadata, tryExtractRouterLikePayloadFromErrorChain, pickRequestIdsFromRouterLike, resolveActivityCostCompletion, resolveCostCompletionForActivity, hasNonZeroTokenUsage } from './gateway-utils.js';
+export { attachGatewayInvokeRejectionMetadata, buildInvokeRejectionMetadata, tryExtractRouterLikePayloadFromErrorChain, pickRequestIdsFromRouterLike, resolveActivityCostCompletion, resolveCostCompletionForActivity, resolveCostCompletionWithAiTools, hasNonZeroTokenUsage } from './gateway-utils.js';
+export { getGatewayOperationalMode, isProdGatewayMode, resolveGatewayDefaultModel, parseModelProviderSpec, CODE_DEFAULT_MODEL } from './gateway-mode.js';
 export { contractSpecToFieldKeys, enrichParsedContentForOutputContract, resolveOutputContractFieldKeys } from './output-contract-normalizer.js';
 export { mergeGatewayAndRequestTemplateRenderOptions, mergeTemplateRenderOptions } from './template-render-merge.js';
 export { GATEWAY_DUAL_MEMORY_ROOTS, buildMemoryResolutionRootFromWorkingMemory, coalesceMergedInputBucket, extractCallerInputsBag, mapSmartInputPathsInputsToInput, parseLooseJsonObject, prepareWorkingMemoryForTemplateRender, resolveGatewayMemoryPathValue } from './memory-path-resolution.js';

package/dist/types.d.ts

@@ -340,6 +340,27 @@ export interface GatewayConfig extends Omit<RouterConfig, 'defaultEngine' | 'log
     openRouter?: {
         enabled?: boolean;
     };
+    /**
+     * Operational mode override (`process.env.mode` / `MODE` when omitted).
+     * - `prod`: unresolved models fall back to {@link AI_GATEWAY_DEFAULT_MODEL} / packaged default (with Logxer warn).
+     * - `dev` / `debug`: unresolved models throw {@link ModelResolutionError} from `@x12i/ai-tools`.
+     */
+    mode?: 'dev' | 'debug' | 'prod';
+    /**
+     * @x12i/ai-tools integration: catalog model resolution (request) and cost calculation (response).
+     */
+    aiTools?: {
+        /** @default true */
+        enabled?: boolean;
+        /** Inject Catalox; otherwise `createCataloxFromEnv()` from `@x12i/catalox/firebase`. */
+        catalox?: import('@x12i/catalox').Catalox;
+        cacheTtlMs?: number;
+        /** @default true */
+        resolveModels?: boolean;
+        /** @default true */
+        calculateCost?: boolean;
+        costIncludeBreakdown?: boolean;
+    };
     /**
      * InstructionsBlocks overrides
      * Key: block name, Value: block content