@x12i/ai-gateway 9.3.4 → 9.4.0

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

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;
+}
+/** 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 (includes billing mirror). */
-function pickActivixCompletionRoutingMetadata(response, billing) {
+/** 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,7 +369,14 @@ export class ActivityManager {
                             exponentialBackoff: false
                         }
                     }
-                });
+                };
+                if (config.autoCost !== undefined && config.autoCost !== false) {
+                    activixOptions.autoCost =
+                        config.autoCost === true
+                            ? { enabled: true, overwriteOuterCost: false }
+                            : { enabled: true, overwriteOuterCost: false, ...config.autoCost };
+                }
+                this.activix = config.customTracker ?? new Activix(activixOptions);
                 this.initPromise = this.activix
                     .init()
                     .then(() => {
@@ -939,8 +930,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 +940,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,

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.js

@@ -265,7 +265,18 @@ 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 templateRendering = mergeTemplateRenderOptions(defaultTemplateRendering, config.templateRendering);
     const instructionsBlockOverrides = {

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
  */
@@ -91,6 +91,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 +106,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.

package/dist/gateway-utils.js

@@ -434,6 +434,50 @@ export function resolveCostCompletionForActivity(routerResponse, tokens) {
     }
     return resolveActivityCostCompletion(tokens, costUsd);
 }
+/** Record shape for {@link CostCalculator.calculateFromRecord} (router + merged config + usage). */
+export function buildGatewayPricingRecord(routerResponse, tokens, mergedConfig) {
+    const base = routerResponse != null && typeof routerResponse === 'object'
+        ? { ...routerResponse }
+        : {};
+    const meta = base.metadata != null && typeof base.metadata === 'object'
+        ? { ...base.metadata }
+        : {};
+    const routing = pickInvokeRoutingMetadataSlice(routerResponse, mergedConfig);
+    return {
+        ...base,
+        usage: {
+            promptTokens: tokens.prompt,
+            completionTokens: tokens.completion,
+            totalTokens: tokens.total
+        },
+        tokens,
+        metadata: {
+            ...meta,
+            tokens,
+            ...(routing.provider ? { provider: routing.provider } : {}),
+            ...(routing.modelUsed
+                ? { modelUsed: routing.modelUsed, model: routing.modelUsed }
+                : {})
+        },
+        ...(mergedConfig != null ? { config: mergedConfig } : {})
+    };
+}
+export function mapAiCostResultToResolvedActivityCost(base, result) {
+    if (result.unknownModel) {
+        return base.costStatus ? base : { ...base, costStatus: 'unpriced' };
+    }
+    if (typeof result.cost !== 'number' || !Number.isFinite(result.cost)) {
+        return base;
+    }
+    if (!result.isAuthoritative && result.source === 'estimate-fallback') {
+        return base.costStatus ? base : { ...base, costStatus: 'unpriced' };
+    }
+    return {
+        cost: result.cost,
+        costStatus: 'priced',
+        ...(result.breakdown ? { costBreakdown: result.breakdown } : {})
+    };
+}
 /**
  * Router cost passthrough, then optional @x12i/ai-tools catalog pricing when still unpriced.
  */
@@ -452,37 +496,114 @@ export async function resolveCostCompletionWithAiTools(routerResponse, tokens, o
     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 } : {})
-            };
-        }
+        const record = buildGatewayPricingRecord(routerResponse, tokens, options.mergedConfig);
+        const result = await options.calculator.calculateFromRecord(record);
+        return mapAiCostResultToResolvedActivityCost(base, result);
     }
     catch {
-        // Keep router/gateway unpriced fallback
+        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,
+                usedModel: modelUsed
+            });
+            return mapAiCostResultToResolvedActivityCost(base, result);
+        }
+        catch {
+            return base;
+        }
     }
-    return base;
+}
+function applyBillingToTraceAttempt(attempt, billing) {
+    if (billing.costStatus === 'priced' || billing.costStatus === 'unpriced') {
+        attempt.costStatus = billing.costStatus;
+    }
+    if (typeof billing.cost === 'number' && Number.isFinite(billing.cost)) {
+        attempt.costUsd = billing.cost;
+    }
+    if (billing.costBreakdown) {
+        attempt.costBreakdown = billing.costBreakdown;
+    }
+}
+function buildTraceAttemptPricingRecord(attempt, mergedConfig) {
+    const tokens = attempt.usage?.tokens ?? { prompt: 0, completion: 0, total: 0 };
+    return buildGatewayPricingRecord({
+        metadata: {
+            provider: attempt.routing.provider,
+            modelUsed: attempt.modelUsed,
+            region: attempt.routing.region,
+            tokens
+        }
+    }, tokens, mergedConfig);
+}
+/**
+ * Trace-mode summary: final token usage + resolved billing (after catalog pricing when applicable).
+ */
+export function buildTraceUsageSummary(tokens, billing, maxTokensRequested) {
+    if (!hasNonZeroTokenUsage(tokens) && !billing.costStatus) {
+        return undefined;
+    }
+    const summary = { tokens };
+    if (maxTokensRequested !== undefined) {
+        summary.maxTokensRequested = maxTokensRequested;
+    }
+    if (billing.costStatus === 'priced' && typeof billing.cost === 'number') {
+        summary.costUsd = billing.cost;
+        summary.cost = billing.cost;
+    }
+    if (billing.costStatus) {
+        summary.costStatus = billing.costStatus;
+    }
+    if (billing.costBreakdown) {
+        summary.costBreakdown = billing.costBreakdown;
+    }
+    return summary;
+}
+/**
+ * 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 async function enrichTraceAttemptsWithBilling(attempts, finalBilling, options) {
+    if (!attempts.length)
+        return;
+    let lastOkIdx = -1;
+    for (let i = attempts.length - 1; i >= 0; i--) {
+        if (attempts[i].ok) {
+            lastOkIdx = i;
+            break;
+        }
+    }
+    if (lastOkIdx >= 0) {
+        applyBillingToTraceAttempt(attempts[lastOkIdx], finalBilling);
+    }
+    if (options?.calculateCost === false || !options?.calculator) {
+        return;
+    }
+    await Promise.all(attempts.map(async (attempt, idx) => {
+        if (!attempt.ok || idx === lastOkIdx)
+            return;
+        const tokens = attempt.usage?.tokens;
+        if (!tokens || !hasNonZeroTokenUsage(tokens))
+            return;
+        if (attempt.costStatus === 'priced' && typeof attempt.costUsd === 'number')
+            return;
+        const slice = await resolveCostCompletionWithAiTools(buildTraceAttemptPricingRecord(attempt, options.mergedConfig), tokens, options);
+        applyBillingToTraceAttempt(attempt, slice);
+    }));
 }
 /**
  * Stable routing facts for gateway response metadata (router metadata + merged config fallbacks).

package/dist/gateway.js

@@ -9,7 +9,7 @@ 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, resolveCostCompletionWithAiTools, tryExtractRouterLikePayloadFromErrorChain } from './gateway-utils.js';
+import { attachGatewayInvokeRejectionMetadata, buildInvokeRejectionMetadata, capActivityFullResponsePayload, DEFAULT_ACTIVITY_FULL_RESPONSE_MAX_CHARS, extractCostUsdFromRouterResponse, extractTokenUsageFromRouterResponse, mergeConfig, pickEffectiveModelConfigForMetadata, pickInvokeRoutingMetadataSlice, pickTraceMergedRouterConfig, resolveCostCompletionWithAiTools, buildTraceUsageSummary, enrichTraceAttemptsWithBilling, 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';
@@ -567,6 +567,16 @@ export class AIGateway {
             const routingMetadataSlice = pickInvokeRoutingMetadataSlice(routerResponse, mergedConfig);
             const effectiveModelConfig = pickEffectiveModelConfigForMetadata(mergedConfig);
             const traceMergedRouterSnapshot = traceEnabled ? pickTraceMergedRouterConfig(mergedConfig) : undefined;
+            if (traceEnabled && traceAttempts) {
+                await enrichTraceAttemptsWithBilling(traceAttempts, costCompletion, {
+                    mergedConfig,
+                    calculator: aiTools?.calculator ?? null,
+                    calculateCost: this.config.aiTools?.calculateCost
+                });
+            }
+            const traceUsageSummary = traceEnabled
+                ? buildTraceUsageSummary(tokens, costCompletion, routingMetadataSlice.maxTokensRequested)
+                : undefined;
             const enhancedResponse = {
                 content: content,
                 parsedContent: parsedContent,
@@ -597,6 +607,7 @@ export class AIGateway {
                             retryCount: traceRetryCount,
                             fallbackCount: traceFallbackCount,
                             attempts: traceAttempts,
+                            ...(traceUsageSummary !== undefined ? { usage: traceUsageSummary } : {}),
                             ...(traceMergedRouterSnapshot !== undefined
                                 ? { mergedRouterConfig: traceMergedRouterSnapshot }
                                 : {})

package/dist/index.d.ts

@@ -16,8 +16,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 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, resolveCostCompletionWithAiTools, hasNonZeroTokenUsage } from './gateway-utils.js';
+export type { GatewayConfig, ProviderModelRef, ModelConfig, RetryConfig, ChatRequest, AIInvokeRequest, AIRequest, GatewayActionType, GatewayInvokeRejectionMetadata, GatewayTraceRequestIds, GatewayTraceAttempt, GatewayTraceUsageSummary, GatewayTraceMergedConfig, EnhancedLLMResponse, InstructionMetadata, ValidationRule, TemplateRenderOptions, SmartInputConfig, SmartInputRenderOptions } from './types.js';
+export { attachGatewayInvokeRejectionMetadata, buildInvokeRejectionMetadata, tryExtractRouterLikePayloadFromErrorChain, pickRequestIdsFromRouterLike, resolveActivityCostCompletion, resolveCostCompletionForActivity, resolveCostCompletionWithAiTools, buildGatewayPricingRecord, mapAiCostResultToResolvedActivityCost, buildTraceUsageSummary, enrichTraceAttemptsWithBilling, 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';
@@ -29,7 +29,8 @@ export { GATEWAY_DUAL_MEMORY_ROOTS, buildMemoryResolutionRootFromWorkingMemory,
 export type { GatewayDualMemoryRoot } from './memory-path-resolution.js';
 export type { UsageTier } from './types.js';
 export { Activix } from '@x12i/activix';
-export type { ActivixRunContext, FindByRunContextCriteria, GetJobActivitiesInput, GetJobActivitiesResult } from '@x12i/activix';
+export type { ActivixRunContext, ActivixAutoCostOptions, ActivixCostShape, FindByRunContextCriteria, GetJobActivitiesInput, GetJobActivitiesResult } from '@x12i/activix';
+export { normalizeToActivixCostShape } from '@x12i/activix';
 export { ActivityManager, ensureGatewayRequestIdentity } from './activity-manager.js';
 export type { ActivityIdentity } from './types.js';
 export { activityIdentityToLogMeta, withActivityIdentity, gatewayLogDebug } from './gateway-log-meta.js';

package/dist/index.js

@@ -17,7 +17,7 @@ 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, resolveCostCompletionWithAiTools, hasNonZeroTokenUsage } from './gateway-utils.js';
+export { attachGatewayInvokeRejectionMetadata, buildInvokeRejectionMetadata, tryExtractRouterLikePayloadFromErrorChain, pickRequestIdsFromRouterLike, resolveActivityCostCompletion, resolveCostCompletionForActivity, resolveCostCompletionWithAiTools, buildGatewayPricingRecord, mapAiCostResultToResolvedActivityCost, buildTraceUsageSummary, enrichTraceAttemptsWithBilling, 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';
@@ -26,6 +26,7 @@ export { GATEWAY_DUAL_MEMORY_ROOTS, buildMemoryResolutionRootFromWorkingMemory,
 // (x-models was previously used for RPM/TPM tracking but is no longer integrated)
 // Re-export activity tracking primitives (Activix)
 export { Activix } from '@x12i/activix';
+export { normalizeToActivixCostShape } from '@x12i/activix';
 export { ActivityManager, ensureGatewayRequestIdentity } from './activity-manager.js';
 export { activityIdentityToLogMeta, withActivityIdentity, gatewayLogDebug } from './gateway-log-meta.js';
 // Re-export logging (@x12i/logxer)
@@ -39,22 +40,5 @@ export { DEFAULT_RATE_LIMIT_MIN_INTERVAL_MS, DEFAULT_RATE_LIMIT_ENABLED } from '
 export { validateAIRequest, validateJSON, extractJSON, validateResponse, diagnoseRequest, diagnoseResponse, supportsJSONMode, createTestAIRequest, createValidationTestCases, runValidationTests, formatDiagnostic, assertValidAIRequest } from './troubleshooting-helper.js';
 // Export object types library
 export { OBJECT_TYPES_LIBRARY, getObjectType, getObjectTypesForAgent } from './object-types-library.js';
-// Re-export outputs library integration functions
+// Object-types library stubs (optional @x12i/outputs-library integration; see object-types-library-integration.ts)
 export { initializeObjectTypesLibrary, getObjectTypesLibrary, resetObjectTypesLibrary } from './object-types-library-integration.js';
-// Re-export outputs library types and utilities for convenience
-// Note: Since we use dynamic imports for the outputs library, these types may not be available
-// at compile time if the package isn't installed. Users can import directly from
-// @x12i/outputs-library if they need these types or utilities.
-//
-// Recommended: Import types and utilities directly from @x12i/outputs-library:
-//   import type { ClassificationOutput } from '@x12i/outputs-library/types';
-//   import { ResponseParser } from '@x12i/outputs-library/parsers';
-//   import type { ObjectTypesLibrary, FlexMdSupport } from '@x12i/outputs-library';
-//
-// The gateway integrates with the outputs library internally via dynamic imports,
-// so these re-exports are optional and mainly for convenience.
-//
-// For outputs-library v3.3.1+ with flex-md support:
-//   - ObjectTypesLibrary class with flex-md methods (getFlexMdTemplate, getFlexMdFormatSpec, etc.)
-//   - FlexMdSupport type for object type definitions
-//   - All flex-md methods are available on the library instance returned by getObjectTypesLibrary()

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,13 +375,15 @@ 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 */
@@ -1009,6 +1038,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).