@x12i/ai-gateway 9.3.5 → 9.5.2

package/dist/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/activity-manager.js

@@ -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/ai-tools-client.js

@@ -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/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>;

package/dist/gateway-config.js

@@ -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/gateway-utils.d.ts

@@ -2,9 +2,9 @@
  * Gateway Utilities Module
  * Handles utility functions
  */
-import type { AIInvokeRequest, ChatRequest, GatewayConfig, GatewayInvokeRejectionMetadata, GatewayTraceMergedConfig, GatewayTraceRequestIds, ModelConfig } from './types.js';
+import type { AIInvokeRequest, ChatRequest, GatewayConfig, GatewayInvokeRejectionMetadata, GatewayTraceAttempt, GatewayTraceMergedConfig, GatewayTraceRequestIds, GatewayTraceUsageSummary, ModelConfig } from './types.js';
 import type { Logxer } from '@x12i/logxer';
-import { type AiModelsCatalogClient, type CostCalculator } from '@x12i/ai-tools';
+import { type AiCostResult, type AiModelsCatalogClient, type CostCalculator } from '@x12i/ai-tools';
 /**
  * Generates MD5 hash of a string
  */
@@ -17,6 +17,12 @@ export type MergeConfigOptions = {
     defaultModelConfig?: Record<string, unknown>;
     catalog?: AiModelsCatalogClient | null;
 };
+/**
+ * True when any caller-controlled config source set `maxTokens` (Optimixer should not override).
+ */
+export declare function isMaxTokensExplicitlySet(request: ChatRequest & {
+    useInternalDefaults?: 'skill' | 'audit';
+}, config: GatewayConfig): boolean;
 /**
  * Merges config with defaults
  * Supports using internal system action defaults (internalSkill or skillAudit) when useInternalDefaults is set
@@ -91,6 +97,13 @@ export type ResolveCostCompletionOptions = {
     calculator?: CostCalculator | null;
     calculateCost?: boolean;
 };
+/** Record shape for {@link CostCalculator.calculateFromRecord} (router + merged config + usage). */
+export declare function buildGatewayPricingRecord(routerResponse: unknown, tokens: {
+    prompt: number;
+    completion: number;
+    total: number;
+}, mergedConfig?: unknown): Record<string, unknown>;
+export declare function mapAiCostResultToResolvedActivityCost(base: ResolvedActivityCost, result: AiCostResult): ResolvedActivityCost;
 /**
  * Router cost passthrough, then optional @x12i/ai-tools catalog pricing when still unpriced.
  */
@@ -99,6 +112,19 @@ export declare function resolveCostCompletionWithAiTools(routerResponse: unknown
     completion: number;
     total: number;
 }, options?: ResolveCostCompletionOptions): Promise<ResolvedActivityCost>;
+/**
+ * Trace-mode summary: final token usage + resolved billing (after catalog pricing when applicable).
+ */
+export declare function buildTraceUsageSummary(tokens: {
+    prompt: number;
+    completion: number;
+    total: number;
+}, billing: ResolvedActivityCost, maxTokensRequested?: number): GatewayTraceUsageSummary | undefined;
+/**
+ * Apply resolved billing to trace attempts: final successful attempt gets aggregate billing;
+ * other successful attempts without router cost get per-attempt catalog pricing when enabled.
+ */
+export declare function enrichTraceAttemptsWithBilling(attempts: GatewayTraceAttempt[], finalBilling: ResolvedActivityCost, options?: ResolveCostCompletionOptions): Promise<void>;
 /**
  * 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.
@@ -145,4 +171,10 @@ export declare const DEFAULT_ACTIVITY_FULL_RESPONSE_MAX_CHARS = 512000;
  * Non-serializable values become a small marker object instead of throwing.
  */
 export declare function capActivityFullResponsePayload(payload: unknown, maxChars?: number): unknown;
+export declare function resolveFinishReasonFromRouterResponse(response: unknown): string | undefined;
+export declare function buildOptimixerActualUsage(tokens: {
+    prompt: number;
+    completion: number;
+    total: number;
+}, response: unknown, latencyMs: number): import('@x12i/optimixer').AiMaxTokensActualUsage;
 export {};