@x12i/ai-gateway 9.2.0 → 9.3.4

package/dist-cjs/activity-manager.cjs

@@ -1,16 +1,12 @@
-"use strict";
 /**
  * Activity Manager
  *
  * Manages activity tracking for LLM requests.
  * Wraps the ActivityTracker and provides convenience methods.
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ActivityManager = void 0;
-exports.ensureGatewayRequestIdentity = ensureGatewayRequestIdentity;
-const activix_1 = require("@x12i/activix");
-const activity_tracking_config_js_1 = require("./config/activity-tracking-config.cjs");
-const gateway_log_meta_js_1 = require("./gateway-log-meta.cjs");
+import { Activix, activixActivityIo, activixOuterTier, resolveActivixLogsDatabaseName, resolveActivixMongoUriFromEnv } from '@x12i/activix';
+import { resolveActivityTrackingConfig } from './config/activity-tracking-config.js';
+import { gatewayLogDebug, withActivityIdentity } from './gateway-log-meta.js';
 function readAiRequestIdFromRequest(request) {
     const aiRequestId = request.aiRequestId;
     if (typeof aiRequestId === 'string' && aiRequestId.trim().length > 0) {
@@ -116,10 +112,10 @@ function resolveSessionIdForRequest(request, incomingIdentity, aiRequestId) {
 function logUpstreamIdentityWarnings(logger, incomingIdentity, merged) {
     const aiRequestId = merged.aiRequestId;
     if (!incomingIdentity || typeof incomingIdentity !== 'object') {
-        logger?.warn('missingRuntimeIdentityObject', (0, gateway_log_meta_js_1.withActivityIdentity)(merged, {
+        logger?.warn('missingRuntimeIdentityObject', withActivityIdentity(merged, {
             message: 'request.identity is missing; upstream must send the mandatory runtime identity object',
             aiRequestId,
-            debugKind: gateway_log_meta_js_1.gatewayLogDebug.anomaly
+            debugKind: gatewayLogDebug.anomaly
         }));
         return;
     }
@@ -129,42 +125,128 @@ function logUpstreamIdentityWarnings(logger, incomingIdentity, merged) {
     if (!trimIdentityString(incomingIdentity.taskId))
         missing.push('taskId');
     if (missing.length > 0) {
-        logger?.warn('missingUpstreamIdentityFields', (0, gateway_log_meta_js_1.withActivityIdentity)(merged, {
+        logger?.warn('missingUpstreamIdentityFields', withActivityIdentity(merged, {
             message: `Upstream identity is missing required field(s): ${missing.join(', ')}. jobId and taskId must be set on request.identity by the client; the gateway does not generate them.`,
             missingFields: missing,
             aiRequestId,
-            debugKind: gateway_log_meta_js_1.gatewayLogDebug.anomaly
+            debugKind: gatewayLogDebug.anomaly
         }));
     }
 }
-/** Routing / generation facts from gateway response metadata for Activix `outer.metadata` on completion. */
-function pickActivixCompletionRoutingMetadata(response) {
+/** Token counts for Activix `outer.cost.tokens` (maps gateway prompt/completion → input/output). */
+function pickActivixUsageTokens(response) {
     if (response == null || typeof response !== 'object')
-        return {};
-    const meta = response.metadata;
-    if (meta == null || typeof meta !== 'object')
-        return {};
-    const m = meta;
+        return undefined;
+    const r = response;
+    const raw = (r.usage != null && typeof r.usage === 'object' ? r.usage : undefined) ??
+        (r.metadata != null && typeof r.metadata === 'object'
+            ? r.metadata.tokens
+            : undefined);
+    if (raw == null || typeof raw !== 'object')
+        return undefined;
+    const t = raw;
+    const input = typeof t.prompt === 'number'
+        ? t.prompt
+        : typeof t.input === 'number'
+            ? t.input
+            : undefined;
+    const output = typeof t.completion === 'number'
+        ? t.completion
+        : typeof t.output === 'number'
+            ? t.output
+            : undefined;
+    const total = typeof t.total === 'number' ? t.total : undefined;
+    if (input === undefined && output === undefined && total === undefined)
+        return undefined;
+    return {
+        ...(input !== undefined ? { input } : {}),
+        ...(output !== undefined ? { output } : {}),
+        ...(total !== undefined ? { total } : {})
+    };
+}
+/**
+ * Activix v6+ `outer.cost` from gateway billing + routing metadata (Run Analysis G8).
+ */
+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 tokens = pickActivixUsageTokens(response);
+    const provider = typeof routingMeta.provider === 'string' ? routingMeta.provider : undefined;
+    const model = typeof routingMeta.modelUsed === 'string'
+        ? routingMeta.modelUsed
+        : typeof routingMeta.model === 'string'
+            ? routingMeta.model
+            : undefined;
+    const details = {};
+    if (billing.costStatus === 'priced' || billing.costStatus === 'unpriced') {
+        details.costStatus = billing.costStatus;
+    }
+    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 {
+        ...(usd !== undefined ? { usd, unit: 'USD' } : {}),
+        ...(tokens ? { tokens } : {}),
+        ...(provider ? { provider } : {}),
+        ...(model ? { model } : {}),
+        ...(hasDetails ? { details } : {})
+    };
+}
+/** Routing / generation facts for Activix `outer.metadata` on completion (includes billing mirror). */
+function pickActivixCompletionRoutingMetadata(response, billing) {
     const out = {};
-    if (typeof m.modelUsed === 'string')
-        out.modelUsed = m.modelUsed;
-    if (typeof m.model === 'string')
-        out.model = m.model;
-    if (typeof m.provider === 'string')
-        out.provider = m.provider;
-    if (typeof m.maxTokensRequested === 'number')
-        out.maxTokensRequested = m.maxTokensRequested;
-    if (typeof m.region === 'string')
-        out.region = m.region;
-    if (m.effectiveModelConfig != null && typeof m.effectiveModelConfig === 'object') {
-        out.effectiveModelConfig = m.effectiveModelConfig;
+    if (response != null && typeof response === 'object') {
+        const meta = response.metadata;
+        if (meta != null && typeof meta === 'object') {
+            const m = meta;
+            if (typeof m.modelUsed === 'string')
+                out.modelUsed = m.modelUsed;
+            if (typeof m.model === 'string')
+                out.model = m.model;
+            if (typeof m.provider === 'string')
+                out.provider = m.provider;
+            if (typeof m.maxTokensRequested === 'number')
+                out.maxTokensRequested = m.maxTokensRequested;
+            if (typeof m.region === 'string')
+                out.region = m.region;
+            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;
+        }
     }
-    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;
     return out;
 }
 function mergeGatewayActivityIdentity(request, aiRequestId, extras) {
@@ -218,7 +300,7 @@ function mergeGatewayActivityIdentity(request, aiRequestId, extras) {
  *
  * @param logger - Optional Logxer used to WARN when mandatory upstream `identity.jobId` / `identity.taskId` are absent.
  */
-function ensureGatewayRequestIdentity(request, extras, logger) {
+export function ensureGatewayRequestIdentity(request, extras, logger) {
     const aiRequestId = readAiRequestIdFromRequest(request);
     const identity = mergeGatewayActivityIdentity(request, aiRequestId, {
         ...graphIdentityExtrasFromRequest(request),
@@ -236,12 +318,12 @@ function buildActivixStartIo(aiRequestId, activityType, requestData) {
         Object.keys(requestData).length > 0
         ? { activityType, request: requestData }
         : { activityType };
-    return (0, activix_1.activixActivityIo)((0, activix_1.activixOuterTier)(input, null, { aiRequestId }));
+    return activixActivityIo(activixOuterTier(input, null, { aiRequestId }));
 }
 /**
  * Manages activity tracking lifecycle
  */
-class ActivityManager {
+export class ActivityManager {
     activix;
     initPromise;
     mainCollectionName;
@@ -251,7 +333,7 @@ class ActivityManager {
     constructor(config) {
         this.logger = config.logger;
         if (config.enableActivityTracking) {
-            const { collectionName, badRequestsCollectionName } = (0, activity_tracking_config_js_1.resolveActivityTrackingConfig)();
+            const { collectionName, badRequestsCollectionName } = resolveActivityTrackingConfig();
             this.mainCollectionName = collectionName;
             this.badRequestsCollectionName = badRequestsCollectionName;
             try {
@@ -263,7 +345,7 @@ class ActivityManager {
                     failed: 'failed',
                     timeout: 'timeout'
                 };
-                this.activix = config.customTracker ?? new activix_1.Activix({
+                this.activix = config.customTracker ?? new Activix({
                     // Keep mode explicit for operational clarity (matches integration checklist expectations).
                     storageMode: 'automatic',
                     collections: [
@@ -312,8 +394,8 @@ class ActivityManager {
                         return;
                     }
                     const backend = ax.storageBackend;
-                    const mongoDb = backend === 'database' ? (0, activix_1.resolveActivixLogsDatabaseName)() : undefined;
-                    const mongoUriConfigured = Boolean((0, activix_1.resolveActivixMongoUriFromEnv)());
+                    const mongoDb = backend === 'database' ? resolveActivixLogsDatabaseName() : undefined;
+                    const mongoUriConfigured = Boolean(resolveActivixMongoUriFromEnv());
                     this.logger.info('Activity tracking persistence backend ready', {
                         storageBackend: backend,
                         mongoDatabase: mongoDb,
@@ -852,13 +934,24 @@ class ActivityManager {
                 });
                 return;
             }
+            const billingSlice = {
+                cost: details.cost,
+                costStatus: details.costStatus,
+                costBreakdown: details.costBreakdown
+            };
+            const outerMetadata = pickActivixCompletionRoutingMetadata(details.response, billingSlice);
+            const outerCost = buildActivixOuterCost(outerMetadata, billingSlice, details.response);
             await this.activix.completeRecord(activity.activityId, {
                 cost: details.cost,
+                ...(typeof details.cost === 'number' && Number.isFinite(details.cost)
+                    ? { costUsd: details.cost }
+                    : {}),
                 ...(details.costStatus ? { costStatus: details.costStatus } : {}),
                 response: details.response,
                 outer: {
                     output: details.response,
-                    metadata: pickActivixCompletionRoutingMetadata(details.response)
+                    metadata: outerMetadata,
+                    ...(outerCost ? { cost: outerCost } : {})
                 },
                 endTime: details.endTime,
                 duration: details.duration
@@ -1162,4 +1255,3 @@ class ActivityManager {
         }
     }
 }
-exports.ActivityManager = ActivityManager;

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

@@ -121,6 +121,7 @@ export declare class ActivityManager {
     logSuccess(activity: ActivityMetadata | undefined, details: {
         cost?: number;
         costStatus?: 'priced' | 'unpriced';
+        costBreakdown?: Record<string, unknown>;
         response: any;
         endTime: number;
         duration: number;

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

@@ -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-cjs/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-cjs/config/activity-tracking-config.cjs

@@ -1,14 +1,11 @@
-"use strict";
 /**
  * Centralized activity tracking configuration.
  * Package-level Mongo collection names are fixed literals here (no env override).
  * Main gateway rows: `ai-actions`; bad requests: `bad-requests` (see constants below).
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.resolveActivityTrackingConfig = resolveActivityTrackingConfig;
 const ACTIVITY_COLLECTION_NAME = 'ai-actions';
 const BAD_REQUESTS_COLLECTION_NAME = 'bad-requests';
-function resolveActivityTrackingConfig() {
+export function resolveActivityTrackingConfig() {
     // Collection names are intentionally hardcoded at package level.
     return {
         mongoUri: '',

package/dist-cjs/content-normalizer/content-normalizer.cjs

@@ -1,4 +1,3 @@
-"use strict";
 /**
  * Content Normalizer
  *
@@ -6,10 +5,6 @@
  * Fixes the "[object Object]" bug by properly handling objects.
  * Preserves both rawText and parsedContent for downstream consumers.
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.normalizeContent = normalizeContent;
-exports.isEmptyContent = isEmptyContent;
-exports.getResponseDiagnostics = getResponseDiagnostics;
 /**
  * Extracts content from router response, checking multiple possible locations
  *
@@ -187,7 +182,7 @@ function determineContentType(value, parsedContent) {
  * @param response - Router response object
  * @returns Normalized content with metadata
  */
-function normalizeContent(response, logger) {
+export function normalizeContent(response, logger) {
     // Extract content value from response
     const contentValue = extractContentValue(response);
     // CRITICAL: Check if router already converted object to "[object Object]" string
@@ -375,7 +370,7 @@ function normalizeContent(response, logger) {
  * @param normalized - Normalized content result
  * @returns True if content is empty
  */
-function isEmptyContent(normalized) {
+export function isEmptyContent(normalized) {
     return !normalized.content || normalized.content.trim().length === 0;
 }
 /**
@@ -385,7 +380,7 @@ function isEmptyContent(normalized) {
  * @param response - Router response object
  * @returns Diagnostic information
  */
-function getResponseDiagnostics(response) {
+export function getResponseDiagnostics(response) {
     return {
         responseKeys: Object.keys(response),
         hasMessage: !!(response?.message),

package/dist-cjs/content-normalizer/index.cjs

@@ -1,12 +1,6 @@
-"use strict";
 /**
  * Content Normalizer Module
  *
  * Exports all public APIs for content normalization
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.getResponseDiagnostics = exports.isEmptyContent = exports.normalizeContent = void 0;
-var content_normalizer_js_1 = require("./content-normalizer.cjs");
-Object.defineProperty(exports, "normalizeContent", { enumerable: true, get: function () { return content_normalizer_js_1.normalizeContent; } });
-Object.defineProperty(exports, "isEmptyContent", { enumerable: true, get: function () { return content_normalizer_js_1.isEmptyContent; } });
-Object.defineProperty(exports, "getResponseDiagnostics", { enumerable: true, get: function () { return content_normalizer_js_1.getResponseDiagnostics; } });
+export { normalizeContent, isEmptyContent, getResponseDiagnostics } from './content-normalizer.js';

package/dist-cjs/content-normalizer/types.cjs

@@ -1,5 +1,4 @@
-"use strict";
 /**
  * Type definitions for Content Normalizer
  */
-Object.defineProperty(exports, "__esModule", { value: true });
+export {};