@x12i/ai-gateway 9.3.5 → 9.5.2

package/dist/token-estimate.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Lightweight token-size estimates for Optimixer predict inputs.
+ * Uses a chars/4 heuristic (no tiktoken dependency).
+ */
+export declare function estimateTextTokens(text: string): number;
+export declare function estimateMessagesTokenSizes(messages: Array<{
+    role?: string;
+    content?: unknown;
+}>): {
+    inputSize: number;
+    contextSize: number;
+};

package/dist/token-estimate.js

@@ -0,0 +1,30 @@
+/**
+ * Lightweight token-size estimates for Optimixer predict inputs.
+ * Uses a chars/4 heuristic (no tiktoken dependency).
+ */
+export function estimateTextTokens(text) {
+    const trimmed = text.trim();
+    if (!trimmed)
+        return 0;
+    return Math.max(1, Math.ceil(trimmed.length / 4));
+}
+export function estimateMessagesTokenSizes(messages) {
+    let inputSize = 0;
+    let contextSize = 0;
+    for (const message of messages) {
+        const role = typeof message.role === 'string' ? message.role.toLowerCase() : '';
+        const content = typeof message.content === 'string'
+            ? message.content
+            : message.content != null
+                ? JSON.stringify(message.content)
+                : '';
+        const tokens = estimateTextTokens(content);
+        if (role === 'system') {
+            contextSize += tokens;
+        }
+        else {
+            inputSize += tokens;
+        }
+    }
+    return { inputSize, contextSize };
+}

package/dist/types.d.ts

@@ -73,6 +73,17 @@ export type GatewayTraceAttempt = {
     };
     modelUsed?: string;
     costUsd?: number;
+    /** Billing state for this attempt (trace mode; mirrors top-level {@link EnhancedLLMResponse.metadata.costStatus}). */
+    costStatus?: 'priced' | 'unpriced';
+    costBreakdown?: {
+        promptCostUsd: number;
+        completionCostUsd: number;
+        cachingCostUsd?: number;
+        reasoningCostUsd?: number;
+        audioCostUsd?: number;
+        imageCostUsd?: number;
+        requestFlatCostUsd?: number;
+    };
     ok: boolean;
     error?: {
         name: string;
@@ -88,6 +99,22 @@ export type GatewayTraceAttempt = {
  * Allowlisted merged router/generation config returned in {@link EnhancedLLMResponse.metadata}
  * when `diagnostics.mode === 'trace'`. Omits arbitrary extras and secrets.
  */
+/**
+ * Consolidated usage + billing summary on {@link EnhancedLLMResponse.metadata} when
+ * `diagnostics.mode === 'trace'` (single object for orchestrators / Run Analysis).
+ */
+export type GatewayTraceUsageSummary = {
+    tokens: {
+        prompt: number;
+        completion: number;
+        total: number;
+    };
+    maxTokensRequested?: number;
+    costUsd?: number;
+    cost?: number;
+    costStatus?: 'priced' | 'unpriced';
+    costBreakdown?: GatewayTraceAttempt['costBreakdown'];
+};
 export type GatewayTraceMergedConfig = Partial<Pick<ModelConfig, 'model' | 'modelId' | 'provider' | 'temperature' | 'maxTokens' | 'topP' | 'frequencyPenalty' | 'presencePenalty' | 'stop'>>;
 /**
  * Normalized observability payload attached to thrown errors from {@link AIGateway.invoke}
@@ -348,19 +375,35 @@ export interface GatewayConfig extends Omit<RouterConfig, 'defaultEngine' | 'log
     mode?: 'dev' | 'debug' | 'prod';
     /**
      * @x12i/ai-tools integration: catalog model resolution (request) and cost calculation (response).
+     * Pricing catalogs load from open-assets JSON (remote with bundled fallback).
      */
     aiTools?: {
         /** @default true */
         enabled?: boolean;
-        /** Inject Catalox; otherwise `createCataloxFromEnv()` from `@x12i/catalox/firebase`. */
-        catalox?: import('@x12i/catalox').Catalox;
+        /** In-memory catalog cache TTL (ms). Default in ai-tools is 24h. */
         cacheTtlMs?: number;
+        /** Use bundled catalog JSON only (offline / tests). */
+        bundledOnly?: boolean;
         /** @default true */
         resolveModels?: boolean;
         /** @default true */
         calculateCost?: boolean;
         costIncludeBreakdown?: boolean;
     };
+    /**
+     * Adaptive `max_tokens` via @x12i/optimixer (embedded Activix mode).
+     * When enabled, the gateway predicts completion budget before each LLM call unless
+     * the caller explicitly sets `maxTokens` on the request / modelConfig / gateway config.
+     */
+    optimixer?: {
+        /** @default false */
+        enabled?: boolean;
+        acceptableRisk?: 'very-low' | 'low' | 'medium' | 'high' | number;
+        /** Cap predicted max tokens with flex-md model limit when available. @default true */
+        useFlexMdCeiling?: boolean;
+        /** Passed to Optimixer warmup on create. */
+        warmupLimit?: number;
+    };
     /**
      * InstructionsBlocks overrides
      * Key: block name, Value: block content
@@ -1009,6 +1052,11 @@ export interface EnhancedLLMResponse<TContent = unknown> extends Omit<AIResponse
          * Ordered, authoritative attempts across retries and fallbacks (trace mode).
          */
         attempts?: GatewayTraceAttempt[];
+        /**
+         * Final usage + billing for the invocation (trace mode). Mirrors successful-attempt
+         * tokens and {@link costUsd} / {@link costStatus} after router passthrough + catalog pricing.
+         */
+        usage?: GatewayTraceUsageSummary;
         /**
          * Merged gateway/router generation config actually used for the invocation (after
          * {@link mergeConfig}: modelConfig / request.config / defaults / flex-md maxTokens).

package/dist-cjs/activity-manager.cjs

@@ -4,7 +4,7 @@
  * Manages activity tracking for LLM requests.
  * Wraps the ActivityTracker and provides convenience methods.
  */
-import { Activix, activixActivityIo, activixOuterTier, resolveActivixLogsDatabaseName, resolveActivixMongoUriFromEnv } from '@x12i/activix';
+import { Activix, activixActivityIo, activixOuterTier, normalizeToActivixCostShape, resolveActivixLogsDatabaseName, resolveActivixMongoUriFromEnv } from '@x12i/activix';
 import { resolveActivityTrackingConfig } from './config/activity-tracking-config.js';
 import { gatewayLogDebug, withActivityIdentity } from './gateway-log-meta.js';
 function readAiRequestIdFromRequest(request) {
@@ -165,16 +165,11 @@ function pickActivixUsageTokens(response) {
     };
 }
 /**
- * Activix v6+ `outer.cost` from gateway billing + routing metadata (Run Analysis G8).
+ * Activix 7.x `outer.cost` from gateway billing + routing (Run Analysis G8).
+ * Uses Activix {@link normalizeToActivixCostShape} so the shape matches package validators.
  */
 function buildActivixOuterCost(routingMeta, billing, response) {
-    const usd = typeof billing.cost === 'number' && Number.isFinite(billing.cost)
-        ? billing.cost
-        : typeof routingMeta.costUsd === 'number' && Number.isFinite(routingMeta.costUsd)
-            ? routingMeta.costUsd
-            : typeof routingMeta.cost === 'number' && Number.isFinite(routingMeta.cost)
-                ? routingMeta.cost
-                : undefined;
+    const usd = typeof billing.cost === 'number' && Number.isFinite(billing.cost) ? billing.cost : undefined;
     const tokens = pickActivixUsageTokens(response);
     const provider = typeof routingMeta.provider === 'string' ? routingMeta.provider : undefined;
     const model = typeof routingMeta.modelUsed === 'string'
@@ -189,20 +184,34 @@ function buildActivixOuterCost(routingMeta, billing, response) {
     if (billing.costBreakdown != null && typeof billing.costBreakdown === 'object') {
         details.costBreakdown = billing.costBreakdown;
     }
-    const hasDetails = Object.keys(details).length > 0;
-    if (usd === undefined && !tokens && !provider && !model && !hasDetails) {
-        return undefined;
-    }
-    return {
+    const candidate = {
         ...(usd !== undefined ? { usd, unit: 'USD' } : {}),
         ...(tokens ? { tokens } : {}),
         ...(provider ? { provider } : {}),
         ...(model ? { model } : {}),
-        ...(hasDetails ? { details } : {})
+        ...(Object.keys(details).length > 0 ? { details } : {})
     };
+    return normalizeToActivixCostShape(candidate, 'gateway.outer.cost') ?? undefined;
 }
-/** Routing / generation facts for Activix `outer.metadata` on completion (includes billing mirror). */
-function pickActivixCompletionRoutingMetadata(response, billing) {
+/** Run-level record metadata (Activix 7.x top-level `metadata`, sibling to `outer`). */
+function buildActivixRecordMetadata(response, billing) {
+    const out = {
+        ...pickActivixCompletionRoutingMetadata(response)
+    };
+    if (billing.costStatus === 'priced' || billing.costStatus === 'unpriced') {
+        out.costStatus = billing.costStatus;
+    }
+    if (typeof billing.cost === 'number' && Number.isFinite(billing.cost)) {
+        out.cost = billing.cost;
+        out.costUsd = billing.cost;
+    }
+    if (billing.costBreakdown != null && typeof billing.costBreakdown === 'object') {
+        out.costBreakdown = billing.costBreakdown;
+    }
+    return out;
+}
+/** Routing / generation facts for Activix `outer.metadata` on completion (no billing — see root + `outer.cost`). */
+function pickActivixCompletionRoutingMetadata(response) {
     const out = {};
     if (response != null && typeof response === 'object') {
         const meta = response.metadata;
@@ -221,30 +230,6 @@ function pickActivixCompletionRoutingMetadata(response, billing) {
             if (m.effectiveModelConfig != null && typeof m.effectiveModelConfig === 'object') {
                 out.effectiveModelConfig = m.effectiveModelConfig;
             }
-            if (typeof m.cost === 'number' && Number.isFinite(m.cost))
-                out.cost = m.cost;
-            if (typeof m.costUsd === 'number' && Number.isFinite(m.costUsd))
-                out.costUsd = m.costUsd;
-            if (m.costStatus === 'priced' || m.costStatus === 'unpriced')
-                out.costStatus = m.costStatus;
-            if (m.costBreakdown != null && typeof m.costBreakdown === 'object') {
-                out.costBreakdown = m.costBreakdown;
-            }
-        }
-    }
-    if (billing) {
-        if ((out.costStatus !== 'priced' && out.costStatus !== 'unpriced') &&
-            (billing.costStatus === 'priced' || billing.costStatus === 'unpriced')) {
-            out.costStatus = billing.costStatus;
-        }
-        if (typeof billing.cost === 'number' && Number.isFinite(billing.cost)) {
-            if (out.cost === undefined)
-                out.cost = billing.cost;
-            if (out.costUsd === undefined)
-                out.costUsd = billing.cost;
-        }
-        if (out.costBreakdown === undefined && billing.costBreakdown != null) {
-            out.costBreakdown = billing.costBreakdown;
         }
     }
     return out;
@@ -345,8 +330,7 @@ export class ActivityManager {
                     failed: 'failed',
                     timeout: 'timeout'
                 };
-                this.activix = config.customTracker ?? new Activix({
-                    // Keep mode explicit for operational clarity (matches integration checklist expectations).
+                const activixOptions = {
                     storageMode: 'automatic',
                     collections: [
                         {
@@ -385,41 +369,31 @@ export class ActivityManager {
                             exponentialBackoff: false
                         }
                     }
-                });
-                this.initPromise = this.activix
-                    .init()
-                    .then(() => {
-                    const ax = this.activix;
-                    if (!ax) {
-                        return;
-                    }
-                    const backend = ax.storageBackend;
-                    const mongoDb = backend === 'database' ? resolveActivixLogsDatabaseName() : undefined;
-                    const mongoUriConfigured = Boolean(resolveActivixMongoUriFromEnv());
-                    this.logger.info('Activity tracking persistence backend ready', {
-                        storageBackend: backend,
-                        mongoDatabase: mongoDb,
-                        mongoUriConfigured,
-                        mainCollection: collectionName,
-                        badRequestsCollection: badRequestsCollectionName,
-                        skillExecutionsCollection: this.skillExecutionsCollectionName,
-                        ...(backend === 'local'
-                            ? {
-                                note: 'Activix is using local playground storage, not MongoDB. The ai-actions collection will not appear in Mongo until URI is set (MONGO_URI or MONGO_LOGS_URI), Activix can ping the database, and at least one activity is written.'
-                            }
-                            : {
-                                note: 'MongoDB stores one document per activity; the ai-actions collection is created on first insert (empty collections may be hidden in some tools until then).'
-                            })
-                    });
-                })
-                    .catch((error) => {
-                    // Init threw — disable tracker so requests are not blocked.
-                    this.logger.warn('Activity tracking enabled but Activix init failed. Activity records will not be persisted.', {
-                        error: error instanceof Error ? error.message : String(error),
-                        hint: 'Set MONGO_URI or MONGO_LOGS_URI and a database name (MONGO_LOGS_DB, MONGO_DB, MONGO_AI_LOGS_DB, or ACTIVIX_DB_NAME). See README: Activity tracking / persistence troubleshooting.'
+                };
+                if (config.autoCost !== undefined && config.autoCost !== false) {
+                    activixOptions.autoCost =
+                        config.autoCost === true
+                            ? { enabled: true, overwriteOuterCost: false }
+                            : { enabled: true, overwriteOuterCost: false, ...config.autoCost };
+                }
+                if (config.customTracker) {
+                    this.activix = config.customTracker;
+                    this.initPromise = Promise.resolve().then(() => this.logActivixBackendReady(collectionName, badRequestsCollectionName));
+                }
+                else {
+                    this.initPromise = Activix.create(activixOptions)
+                        .then((ax) => {
+                        this.activix = ax;
+                        this.logActivixBackendReady(collectionName, badRequestsCollectionName);
+                    })
+                        .catch((error) => {
+                        this.logger.warn('Activity tracking enabled but Activix init failed. Activity records will not be persisted.', {
+                            error: error instanceof Error ? error.message : String(error),
+                            hint: 'Set MONGO_URI or MONGO_LOGS_URI and a database name (MONGO_LOGS_DB, MONGO_DB, MONGO_AI_LOGS_DB, or ACTIVIX_DB_NAME). See README: Activity tracking / persistence troubleshooting.'
+                        });
+                        this.activix = undefined;
                     });
-                    this.activix = undefined;
-                });
+                }
                 this.logger.debug('Activity tracking enabled with Activix', {
                     collection: collectionName,
                     badRequestsCollection: badRequestsCollectionName,
@@ -939,8 +913,9 @@ export class ActivityManager {
                 costStatus: details.costStatus,
                 costBreakdown: details.costBreakdown
             };
-            const outerMetadata = pickActivixCompletionRoutingMetadata(details.response, billingSlice);
+            const outerMetadata = pickActivixCompletionRoutingMetadata(details.response);
             const outerCost = buildActivixOuterCost(outerMetadata, billingSlice, details.response);
+            const recordMetadata = buildActivixRecordMetadata(details.response, billingSlice);
             await this.activix.completeRecord(activity.activityId, {
                 cost: details.cost,
                 ...(typeof details.cost === 'number' && Number.isFinite(details.cost)
@@ -948,13 +923,12 @@ export class ActivityManager {
                     : {}),
                 ...(details.costStatus ? { costStatus: details.costStatus } : {}),
                 response: details.response,
+                ...(Object.keys(recordMetadata).length > 0 ? { metadata: recordMetadata } : {}),
                 outer: {
                     output: details.response,
                     metadata: outerMetadata,
                     ...(outerCost ? { cost: outerCost } : {})
-                },
-                endTime: details.endTime,
-                duration: details.duration
+                }
             }, { collection });
             this.logger.debug('Activix.completeRecord completed', {
                 aiRequestId: activity.aiRequestId,
@@ -1224,6 +1198,36 @@ export class ActivityManager {
     getTracker() {
         return this.activix;
     }
+    /** Await Activix init (no-op when tracking is disabled). */
+    async getReadyTracker() {
+        if (this.initPromise) {
+            await this.initPromise;
+        }
+        return this.activix;
+    }
+    logActivixBackendReady(collectionName, badRequestsCollectionName) {
+        const ax = this.activix;
+        if (!ax)
+            return;
+        const backend = ax.storageBackend;
+        const mongoDb = backend === 'database' ? resolveActivixLogsDatabaseName() : undefined;
+        const mongoUriConfigured = Boolean(resolveActivixMongoUriFromEnv());
+        this.logger.info('Activity tracking persistence backend ready', {
+            storageBackend: backend,
+            mongoDatabase: mongoDb,
+            mongoUriConfigured,
+            mainCollection: collectionName,
+            badRequestsCollection: badRequestsCollectionName,
+            skillExecutionsCollection: this.skillExecutionsCollectionName,
+            ...(backend === 'local'
+                ? {
+                    note: 'Activix is using local playground storage, not MongoDB. The ai-actions collection will not appear in Mongo until URI is set (MONGO_URI or MONGO_LOGS_URI), Activix can ping the database, and at least one activity is written.'
+                }
+                : {
+                    note: 'MongoDB stores one document per activity; the ai-actions collection is created on first insert (empty collections may be hidden in some tools until then).'
+                })
+        });
+    }
     /**
      * Get status of activity tracker
      */

package/dist-cjs/activity-manager.d.ts

@@ -4,7 +4,7 @@
  * Manages activity tracking for LLM requests.
  * Wraps the ActivityTracker and provides convenience methods.
  */
-import { Activix } from '@x12i/activix';
+import { Activix, type ActivixAutoCostOptions } from '@x12i/activix';
 import type { Logxer } from '@x12i/logxer';
 import type { ActivityIdentity, ChatRequest, AIRequest, FailureType, LLMResponseFailureSubtype, ResponseParsingFailureSubtype } from './types.js';
 type Request = ChatRequest | AIRequest;
@@ -31,6 +31,11 @@ export interface ActivityManagerConfig {
     enableActivityTracking: boolean;
     customTracker?: Activix;
     logger: Logxer;
+    /**
+     * Activix 7.2+ {@link ActivixAutoCostOptions}: fill `outer.cost` via @x12i/ai-tools when the gateway
+     * did not supply a valid cost. Ignored when `customTracker` is provided.
+     */
+    autoCost?: boolean | ActivixAutoCostOptions;
 }
 /**
  * Manages activity tracking lifecycle
@@ -193,6 +198,9 @@ export declare class ActivityManager {
      * @returns Activix instance or undefined if not enabled
      */
     getTracker(): Activix | undefined;
+    /** Await Activix init (no-op when tracking is disabled). */
+    getReadyTracker(): Promise<Activix | undefined>;
+    private logActivixBackendReady;
     /**
      * Get status of activity tracker
      */

package/dist-cjs/ai-tools-client.cjs

@@ -1,14 +1,13 @@
 /**
  * Lazy @x12i/ai-tools catalog + cost calculator bootstrap.
  */
-import { AiModelsCatalogClient, CostCalculator, ensureAiModelsCatalog } from '@x12i/ai-tools';
+import { AiModelsCatalogClient, CostCalculator } 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 ?? ''}`;
+    return `${config.aiTools?.cacheTtlMs ?? ''}:${config.aiTools?.costIncludeBreakdown ?? ''}:${config.aiTools?.bundledOnly ?? ''}`;
 }
 /**
  * Returns catalog + calculator, or null when disabled or bootstrap fails.
@@ -35,16 +34,9 @@ export function resetAiToolsClientForTests() {
 }
 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
+            cacheTtlMs: config.aiTools?.cacheTtlMs,
+            ...(config.aiTools?.bundledOnly ? { bundledOnly: true } : {})
         });
         const calculator = new CostCalculator(catalog, {
             includeBreakdown: config.aiTools?.costIncludeBreakdown === true

package/dist-cjs/gateway-config.cjs

@@ -48,6 +48,7 @@ function getDefaultsDir() {
 import { LLMProviderRouter } from '@x12i/ai-providers-router';
 import { createGatewayLogger } from './logger-factory.js';
 import { ActivityManager } from './activity-manager.js';
+import { OptimixerManager } from './optimixer-manager.js';
 import { UsageTracker } from './usage-tracker.js';
 import { mergeTemplateRenderOptions } from './template-render-merge.js';
 import { GatewayRateLimiter } from './gateway-rate-limiter.js';
@@ -265,7 +266,23 @@ export function initializeGatewayComponents(config) {
     const activityManager = new ActivityManager({
         enableActivityTracking: config.enableActivityTracking ?? true,
         customTracker: config.activityTracker,
-        logger
+        logger,
+        ...(config.activityTracker
+            ? {}
+            : {
+                autoCost: config.aiTools?.enabled === false || config.aiTools?.calculateCost === false
+                    ? false
+                    : {
+                        enabled: true,
+                        overwriteOuterCost: false,
+                        ...(config.aiTools?.bundledOnly ? { bundledOnly: true } : {})
+                    }
+            })
+    });
+    const optimixerManager = new OptimixerManager({
+        optimixer: config.optimixer,
+        logger,
+        getActivix: () => activityManager.getReadyTracker()
     });
     const templateRendering = mergeTemplateRenderOptions(defaultTemplateRendering, config.templateRendering);
     const instructionsBlockOverrides = {
@@ -282,6 +299,7 @@ export function initializeGatewayComponents(config) {
         logger,
         router,
         activityManager,
+        optimixerManager,
         usageTracker,
         messageBuilderConfig,
         defaultModelConfig

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

@@ -6,6 +6,7 @@ import type { GatewayConfig } from './types.js';
 import type { Logxer } from '@x12i/logxer';
 import { LLMProviderRouter } from '@x12i/ai-providers-router';
 import { ActivityManager } from './activity-manager.js';
+import { OptimixerManager } from './optimixer-manager.js';
 import { UsageTracker } from './usage-tracker.js';
 import type { MessageBuilderConfig } from './message-builder.js';
 import type { TemplateRenderOptions } from '@x12i/rendrix';
@@ -16,6 +17,7 @@ export interface GatewayConfigContext {
     logger: Logxer;
     router: LLMProviderRouter;
     activityManager: ActivityManager;
+    optimixerManager: OptimixerManager;
     usageTracker: UsageTracker;
     messageBuilderConfig: MessageBuilderConfig;
 }
@@ -45,6 +47,7 @@ export declare function initializeGatewayComponents(config: GatewayConfig): {
     logger: Logxer;
     router: LLMProviderRouter;
     activityManager: ActivityManager;
+    optimixerManager: OptimixerManager;
     usageTracker: UsageTracker;
     messageBuilderConfig: MessageBuilderConfig;
     defaultModelConfig: Record<string, unknown>;