@x12i/ai-gateway 9.3.5 → 9.5.2

package/dist-cjs/gateway-utils.cjs

@@ -55,6 +55,21 @@ async function substituteGatewayDefaultModel(merged, request, config, logger, me
     });
     applyGatewayDefaultToMerged(merged, defaults, config);
 }
+/**
+ * True when any caller-controlled config source set `maxTokens` (Optimixer should not override).
+ */
+export function isMaxTokensExplicitlySet(request, config) {
+    const useInternalDefaults = request.useInternalDefaults;
+    const internalDefaults = useInternalDefaults === 'skill'
+        ? config.internalSystemActions?.internalSkill
+        : useInternalDefaults === 'audit'
+            ? config.internalSystemActions?.skillAudit
+            : undefined;
+    return (request.config?.maxTokens !== undefined ||
+        request.modelConfig?.maxTokens !== undefined ||
+        internalDefaults?.maxTokens !== undefined ||
+        config.maxTokens !== undefined);
+}
 /**
  * Merges config with defaults
  * Supports using internal system action defaults (internalSkill or skillAudit) when useInternalDefaults is set
@@ -175,12 +190,10 @@ export async function mergeConfig(request, config, logger, mergeOptions) {
     if (!merged.model) {
         await substituteGatewayDefaultModel(merged, request, config, logger, mergeOptions, 'no_model_provided');
     }
-    // Auto-get maxTokens from flex-md if not explicitly set in ANY config source
-    // Check all possible sources: request.config, internalDefaults, gateway config
-    const maxTokensExplicitlySet = request.config?.maxTokens !== undefined ||
-        internalDefaults?.maxTokens !== undefined ||
-        config.maxTokens !== undefined;
-    if (!maxTokensExplicitlySet && merged.model && merged.provider) {
+    const maxTokensExplicitlySet = isMaxTokensExplicitlySet(request, config);
+    const optimixerWillPredict = config.optimixer?.enabled === true && !maxTokensExplicitlySet;
+    // Auto-get maxTokens from flex-md when Optimixer is not handling adaptive max_tokens.
+    if (!optimixerWillPredict && !maxTokensExplicitlySet && merged.model && merged.provider) {
         // Try to get maxTokens from flex-md
         try {
             const flexMdMaxTokens = await getModelMaxTokensFromFlexMd(merged.provider, merged.model);
@@ -219,7 +232,7 @@ export async function mergeConfig(request, config, logger, mergeOptions) {
             });
         }
     }
-    else if (!merged.maxTokens) {
+    else if (!merged.maxTokens && !optimixerWillPredict) {
         // If maxTokens wasn't set and wasn't auto-detected, use fallback
         // This should rarely happen, but handle edge cases
         merged.maxTokens = 2000;
@@ -228,7 +241,15 @@ export async function mergeConfig(request, config, logger, mergeOptions) {
             model: merged.model,
             provider: merged.provider,
             maxTokens: merged.maxTokens,
-            maxTokensExplicitlySet
+            maxTokensExplicitlySet,
+            optimixerWillPredict
+        });
+    }
+    else if (optimixerWillPredict) {
+        logger.debug('Deferring maxTokens to Optimixer predictAiMaxTokens', {
+            jobId: request.identity.jobId,
+            model: merged.model,
+            provider: merged.provider
         });
     }
     else {
@@ -434,6 +455,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 +517,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;
+        }
+    }
+}
+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 base;
+    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).
@@ -693,3 +835,30 @@ export function capActivityFullResponsePayload(payload, maxChars = DEFAULT_ACTIV
         _preview: serialized.slice(0, maxChars)
     };
 }
+export function resolveFinishReasonFromRouterResponse(response) {
+    if (response == null || typeof response !== 'object')
+        return undefined;
+    const r = response;
+    const meta = r.metadata != null && typeof r.metadata === 'object' ? r.metadata : undefined;
+    const candidates = [
+        r.finishReason,
+        r.finish_reason,
+        meta?.finishReason,
+        meta?.finish_reason
+    ];
+    for (const c of candidates) {
+        if (typeof c === 'string' && c.trim())
+            return c.trim();
+    }
+    return undefined;
+}
+export function buildOptimixerActualUsage(tokens, response, latencyMs) {
+    const finishReason = resolveFinishReasonFromRouterResponse(response);
+    return {
+        promptTokens: tokens.prompt,
+        completionTokens: tokens.completion,
+        totalTokens: tokens.total,
+        ...(finishReason ? { finishReason } : {}),
+        latencyMs
+    };
+}

package/dist-cjs/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 {};

package/dist-cjs/gateway.cjs

@@ -7,9 +7,9 @@ import { validateChatRequest, validateAIRequest } from './gateway-validation.js'
 import { ensureGatewayRequestIdentity } from './activity-manager.js';
 import { initializeGatewayComponents } from './gateway-config.js';
 import { buildMessages } from './message-builder.js';
-import { extractJsonFromFlexMd } from './flex-md-loader.js';
+import { extractJsonFromFlexMd, getModelMaxTokensFromFlexMd } 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, buildOptimixerActualUsage, buildTraceUsageSummary, enrichTraceAttemptsWithBilling, isMaxTokensExplicitlySet, 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';
@@ -45,6 +45,7 @@ export class AIGateway {
     config;
     logger;
     activityManager;
+    optimixerManager;
     messageBuilderConfig;
     defaultModelConfig = {};
     _autoRegisterDone = false;
@@ -56,6 +57,7 @@ export class AIGateway {
         this.logger = components.logger;
         this.router = components.router;
         this.activityManager = components.activityManager;
+        this.optimixerManager = components.optimixerManager;
         this.messageBuilderConfig = components.messageBuilderConfig;
         this.defaultModelConfig = components.defaultModelConfig ?? {};
         setGatewayRuntimeClients({
@@ -93,6 +95,7 @@ export class AIGateway {
             await autoRegisterProviders(this.router, this.logger);
             this._autoRegisterDone = true;
         }
+        const optimixerPrediction = await this.applyAdaptiveMaxTokensIfEnabled(request, mergedConfig, messages);
         // Start activity tracking if available
         let activity = undefined;
         if (this.activityManager) {
@@ -166,6 +169,9 @@ export class AIGateway {
                     });
                 }
             }
+            if (optimixerPrediction) {
+                await this.optimixerManager?.completePrediction(optimixerPrediction.requestId, buildOptimixerActualUsage(tokensChat, response, Date.now() - startTime));
+            }
             warnIfSuccessfulInvokeReportsZeroUsageOrCost(this.logger, request.identity, {
                 tokens: enhancedResponse.metadata.tokens,
                 costUsd: enhancedResponse.metadata.costUsd,
@@ -279,6 +285,7 @@ export class AIGateway {
             await autoRegisterProviders(this.router, this.logger);
             this._autoRegisterDone = true;
         }
+        const optimixerPrediction = await this.applyAdaptiveMaxTokensIfEnabled(request, mergedConfig, messages);
         // Start activity tracking if available
         let activity = undefined;
         if (this.activityManager) {
@@ -567,6 +574,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 +614,7 @@ export class AIGateway {
                             retryCount: traceRetryCount,
                             fallbackCount: traceFallbackCount,
                             attempts: traceAttempts,
+                            ...(traceUsageSummary !== undefined ? { usage: traceUsageSummary } : {}),
                             ...(traceMergedRouterSnapshot !== undefined
                                 ? { mergedRouterConfig: traceMergedRouterSnapshot }
                                 : {})
@@ -643,6 +661,9 @@ export class AIGateway {
                     });
                 }
             }
+            if (optimixerPrediction) {
+                await this.optimixerManager?.completePrediction(optimixerPrediction.requestId, buildOptimixerActualUsage(tokens, routerResponse, Date.now() - startTime));
+            }
             warnIfSuccessfulInvokeReportsZeroUsageOrCost(this.logger, request.identity, {
                 tokens: enhancedResponse.metadata.tokens,
                 costUsd: enhancedResponse.metadata.costUsd,
@@ -676,6 +697,52 @@ export class AIGateway {
             throw err;
         }
     }
+    async applyAdaptiveMaxTokensIfEnabled(request, mergedConfig, messages) {
+        if (!this.optimixerManager?.isEnabled() || isMaxTokensExplicitlySet(request, this.config)) {
+            return undefined;
+        }
+        const prediction = await this.optimixerManager.predictMaxTokens({
+            request,
+            mergedConfig,
+            messages
+        });
+        if (prediction) {
+            let maxTokens = prediction.recommendedMaxTokens;
+            const useCeiling = this.config.optimixer?.useFlexMdCeiling !== false;
+            if (useCeiling && mergedConfig?.model && mergedConfig?.provider) {
+                try {
+                    const ceiling = await getModelMaxTokensFromFlexMd(mergedConfig.provider, mergedConfig.model);
+                    if (typeof ceiling === 'number' && ceiling > 0 && maxTokens > ceiling) {
+                        maxTokens = ceiling;
+                    }
+                }
+                catch {
+                    // Non-blocking: use uncapped prediction
+                }
+            }
+            mergedConfig.maxTokens = maxTokens;
+            request._mergedRouterConfig = mergedConfig;
+            this.logger.debug('Applied Optimixer recommended max_tokens', {
+                aiRequestId: request.aiRequestId,
+                recommendedMaxTokens: prediction.recommendedMaxTokens,
+                maxTokens,
+                confidence: prediction.confidence,
+                requestId: prediction.requestId
+            });
+            return prediction;
+        }
+        if (mergedConfig?.maxTokens === undefined && mergedConfig?.model && mergedConfig?.provider) {
+            try {
+                const flexMdMaxTokens = await getModelMaxTokensFromFlexMd(mergedConfig.provider, mergedConfig.model);
+                mergedConfig.maxTokens = flexMdMaxTokens && flexMdMaxTokens > 0 ? flexMdMaxTokens : 2000;
+            }
+            catch {
+                mergedConfig.maxTokens = 2000;
+            }
+            request._mergedRouterConfig = mergedConfig;
+        }
+        return undefined;
+    }
     /**
      * Build simple messages from request (instructions and prompt as literal template text; no registry).
      */

package/dist-cjs/gateway.d.ts

@@ -15,6 +15,7 @@ export declare class AIGateway {
     private config;
     private logger;
     private activityManager?;
+    private optimixerManager?;
     private messageBuilderConfig?;
     private defaultModelConfig;
     private _autoRegisterDone;
@@ -28,6 +29,7 @@ export declare class AIGateway {
      * Invoke AI request (with structured output support)
      */
     invoke<TContent = unknown>(request: AIInvokeRequest): Promise<EnhancedLLMResponse<TContent>>;
+    private applyAdaptiveMaxTokensIfEnabled;
     /**
      * Build simple messages from request (instructions and prompt as literal template text; no registry).
      */

package/dist-cjs/index.cjs

@@ -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,7 +26,9 @@ 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 { OptimixerManager } from './optimixer-manager.js';
 export { activityIdentityToLogMeta, withActivityIdentity, gatewayLogDebug } from './gateway-log-meta.js';
 // Re-export logging (@x12i/logxer)
 export { createLogxer, DebugLogAbstract } from '@x12i/logxer';
@@ -39,22 +41,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-cjs/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,8 +29,10 @@ 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 { OptimixerManager } from './optimixer-manager.js';
 export type { ActivityIdentity } from './types.js';
 export { activityIdentityToLogMeta, withActivityIdentity, gatewayLogDebug } from './gateway-log-meta.js';
 export { createLogxer, DebugLogAbstract } from '@x12i/logxer';