@x12i/ai-gateway 9.3.5 → 9.5.2

package/dist/gateway-utils.js

@@ -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/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/gateway.js

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

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,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/optimixer-manager.d.ts

@@ -0,0 +1,33 @@
+import type { AiMaxTokensActualUsage, AiMaxTokensPredictionResult } from '@x12i/optimixer';
+import type { Activix } from '@x12i/activix';
+import type { Logxer } from '@x12i/logxer';
+import type { ChatRequest, GatewayConfig } from './types.js';
+export type OptimixerGatewayConfig = NonNullable<GatewayConfig['optimixer']>;
+export interface OptimixerManagerConfig {
+    optimixer?: OptimixerGatewayConfig;
+    logger: Logxer;
+    getActivix: () => Promise<Activix | undefined>;
+}
+export type OptimixerMaxTokensContext = {
+    request: ChatRequest;
+    mergedConfig: ChatRequest['config'];
+    messages: Array<{
+        role?: string;
+        content?: unknown;
+    }>;
+};
+export declare class OptimixerManager {
+    private readonly config;
+    private readonly logger;
+    private readonly getActivix;
+    private optimixer?;
+    private initPromise?;
+    private readonly activixCollection;
+    constructor(config: OptimixerManagerConfig);
+    isEnabled(): boolean;
+    private ensureReady;
+    private initialize;
+    predictMaxTokens(ctx: OptimixerMaxTokensContext): Promise<AiMaxTokensPredictionResult | undefined>;
+    completePrediction(requestId: string, actual: AiMaxTokensActualUsage): Promise<void>;
+    shutdown(): Promise<void>;
+}

package/dist/optimixer-manager.js

@@ -0,0 +1,128 @@
+import { Optimixer } from '@x12i/optimixer';
+import { resolveActivityTrackingConfig } from './config/activity-tracking-config.js';
+import { estimateMessagesTokenSizes } from './token-estimate.js';
+function resolveActionTypeId(request) {
+    const identity = request.identity;
+    if (identity?.actionType && String(identity.actionType).trim()) {
+        return String(identity.actionType).trim();
+    }
+    if (request.taskTypeId && String(request.taskTypeId).trim()) {
+        return String(request.taskTypeId).trim();
+    }
+    return 'gateway.invoke';
+}
+function toActivixRunContext(identity) {
+    if (!identity)
+        return undefined;
+    return identity;
+}
+export class OptimixerManager {
+    config;
+    logger;
+    getActivix;
+    optimixer;
+    initPromise;
+    activixCollection;
+    constructor(config) {
+        this.config = config.optimixer;
+        this.logger = config.logger;
+        this.getActivix = config.getActivix;
+        this.activixCollection = resolveActivityTrackingConfig().collectionName;
+    }
+    isEnabled() {
+        return this.config?.enabled === true;
+    }
+    async ensureReady() {
+        if (!this.isEnabled())
+            return undefined;
+        if (this.optimixer)
+            return this.optimixer;
+        if (!this.initPromise) {
+            this.initPromise = this.initialize();
+        }
+        await this.initPromise;
+        return this.optimixer;
+    }
+    async initialize() {
+        const activix = await this.getActivix();
+        if (!activix) {
+            this.logger.warn('Optimixer enabled but Activix is unavailable; adaptive max_tokens disabled', {
+                activixCollection: this.activixCollection
+            });
+            return;
+        }
+        try {
+            this.optimixer = await Optimixer.create({
+                activixClient: activix,
+                activixCollection: this.activixCollection,
+                pipelines: { aiMaxTokens: { enabled: true } },
+                ...(typeof this.config?.warmupLimit === 'number' ? { warmupLimit: this.config.warmupLimit } : {})
+            });
+            this.logger.info('Optimixer initialized for adaptive max_tokens', {
+                activixCollection: this.activixCollection,
+                acceptableRisk: this.config?.acceptableRisk ?? 'medium'
+            });
+        }
+        catch (error) {
+            this.logger.warn('Optimixer initialization failed; adaptive max_tokens disabled', {
+                error: error instanceof Error ? error.message : String(error)
+            });
+            this.optimixer = undefined;
+        }
+    }
+    async predictMaxTokens(ctx) {
+        const optimixer = await this.ensureReady();
+        if (!optimixer)
+            return undefined;
+        const { request, mergedConfig, messages } = ctx;
+        const { inputSize, contextSize } = estimateMessagesTokenSizes(messages);
+        const acceptableRisk = this.config?.acceptableRisk ?? 'medium';
+        try {
+            return await optimixer.predictAiMaxTokens({
+                actionTypeId: resolveActionTypeId(request),
+                inputSize,
+                contextSize,
+                acceptableRisk,
+                runContext: toActivixRunContext(request.identity),
+                provider: typeof mergedConfig?.provider === 'string' ? mergedConfig.provider : undefined,
+                model: typeof mergedConfig?.model === 'string' ? mergedConfig.model : undefined
+            });
+        }
+        catch (error) {
+            this.logger.warn('Optimixer predictAiMaxTokens failed; caller should use fallback max_tokens', {
+                error: error instanceof Error ? error.message : String(error),
+                aiRequestId: request.aiRequestId
+            });
+            return undefined;
+        }
+    }
+    async completePrediction(requestId, actual) {
+        const optimixer = await this.ensureReady();
+        if (!optimixer)
+            return;
+        try {
+            await optimixer.completeAiMaxTokensPrediction({ requestId, actual });
+        }
+        catch (error) {
+            this.logger.warn('Optimixer completeAiMaxTokensPrediction failed (non-blocking)', {
+                requestId,
+                error: error instanceof Error ? error.message : String(error)
+            });
+        }
+    }
+    async shutdown() {
+        const optimixer = this.optimixer;
+        this.optimixer = undefined;
+        this.initPromise = undefined;
+        if (optimixer) {
+            try {
+                await optimixer.close();
+            }
+            catch (error) {
+                this.logger.warn('OptimixerManager shutdown: close failed (non-blocking)', {
+                    error: error instanceof Error ? error.message : String(error)
+                });
+            }
+        }
+    }
+}