@x12i/ai-gateway 9.4.0 → 9.5.3

package/README.md

@@ -230,6 +230,7 @@ Live tests use `LIVE_TEST_PROVIDER` / `LIVE_TEST_MODEL` (default `openrouter` +
 | [LOGGER_INITIALIZATION.md](./docs/LOGGER_INITIALIZATION.md) | Logxer setup |
 | [flex-md-compliance.md](./docs/flex-md-compliance.md) | Output format levels |
 | [PROMPT_TEMPLATE_USAGE.md](./docs/PROMPT_TEMPLATE_USAGE.md) | Rendrix templates |
+| [upstream-reports/README.md](./docs/upstream-reports/README.md) | Upstream issues (one file per package/gap) |
 | [UPSTREAM_TEMPLATE_RENDERING_AND_PARSER_V4.md](./docs/UPSTREAM_TEMPLATE_RENDERING_AND_PARSER_V4.md) | Parser v4 |
 | [RUNTIME_OBJECTS_OBSERVABILITY.md](./docs/RUNTIME_OBJECTS_OBSERVABILITY.md) | Runtime object keys |
 | [GRAPH_EXECUTION_SUPPORT.md](./docs/GRAPH_EXECUTION_SUPPORT.md) | Graph / node identity |

package/dist/activity-manager.d.ts

@@ -198,6 +198,9 @@ export declare class ActivityManager {
      * @returns Activix instance or undefined if not enabled
      */
     getTracker(): Activix | undefined;
+    /** Await Activix init (no-op when tracking is disabled). */
+    getReadyTracker(): Promise<Activix | undefined>;
+    private logActivixBackendReady;
     /**
      * Get status of activity tracker
      */

package/dist/activity-manager.js

@@ -376,41 +376,24 @@ export class ActivityManager {
                             ? { enabled: true, overwriteOuterCost: false }
                             : { enabled: true, overwriteOuterCost: false, ...config.autoCost };
                 }
-                this.activix = config.customTracker ?? new Activix(activixOptions);
-                this.initPromise = this.activix
-                    .init()
-                    .then(() => {
-                    const ax = this.activix;
-                    if (!ax) {
-                        return;
-                    }
-                    const backend = ax.storageBackend;
-                    const mongoDb = backend === 'database' ? resolveActivixLogsDatabaseName() : undefined;
-                    const mongoUriConfigured = Boolean(resolveActivixMongoUriFromEnv());
-                    this.logger.info('Activity tracking persistence backend ready', {
-                        storageBackend: backend,
-                        mongoDatabase: mongoDb,
-                        mongoUriConfigured,
-                        mainCollection: collectionName,
-                        badRequestsCollection: badRequestsCollectionName,
-                        skillExecutionsCollection: this.skillExecutionsCollectionName,
-                        ...(backend === 'local'
-                            ? {
-                                note: 'Activix is using local playground storage, not MongoDB. The ai-actions collection will not appear in Mongo until URI is set (MONGO_URI or MONGO_LOGS_URI), Activix can ping the database, and at least one activity is written.'
-                            }
-                            : {
-                                note: 'MongoDB stores one document per activity; the ai-actions collection is created on first insert (empty collections may be hidden in some tools until then).'
-                            })
-                    });
-                })
-                    .catch((error) => {
-                    // Init threw — disable tracker so requests are not blocked.
-                    this.logger.warn('Activity tracking enabled but Activix init failed. Activity records will not be persisted.', {
-                        error: error instanceof Error ? error.message : String(error),
-                        hint: 'Set MONGO_URI or MONGO_LOGS_URI and a database name (MONGO_LOGS_DB, MONGO_DB, MONGO_AI_LOGS_DB, or ACTIVIX_DB_NAME). See README: Activity tracking / persistence troubleshooting.'
+                if (config.customTracker) {
+                    this.activix = config.customTracker;
+                    this.initPromise = Promise.resolve().then(() => this.logActivixBackendReady(collectionName, badRequestsCollectionName));
+                }
+                else {
+                    this.initPromise = Activix.create(activixOptions)
+                        .then((ax) => {
+                        this.activix = ax;
+                        this.logActivixBackendReady(collectionName, badRequestsCollectionName);
+                    })
+                        .catch((error) => {
+                        this.logger.warn('Activity tracking enabled but Activix init failed. Activity records will not be persisted.', {
+                            error: error instanceof Error ? error.message : String(error),
+                            hint: 'Set MONGO_URI or MONGO_LOGS_URI and a database name (MONGO_LOGS_DB, MONGO_DB, MONGO_AI_LOGS_DB, or ACTIVIX_DB_NAME). See README: Activity tracking / persistence troubleshooting.'
+                        });
+                        this.activix = undefined;
                     });
-                    this.activix = undefined;
-                });
+                }
                 this.logger.debug('Activity tracking enabled with Activix', {
                     collection: collectionName,
                     badRequestsCollection: badRequestsCollectionName,
@@ -1215,6 +1198,36 @@ export class ActivityManager {
     getTracker() {
         return this.activix;
     }
+    /** Await Activix init (no-op when tracking is disabled). */
+    async getReadyTracker() {
+        if (this.initPromise) {
+            await this.initPromise;
+        }
+        return this.activix;
+    }
+    logActivixBackendReady(collectionName, badRequestsCollectionName) {
+        const ax = this.activix;
+        if (!ax)
+            return;
+        const backend = ax.storageBackend;
+        const mongoDb = backend === 'database' ? resolveActivixLogsDatabaseName() : undefined;
+        const mongoUriConfigured = Boolean(resolveActivixMongoUriFromEnv());
+        this.logger.info('Activity tracking persistence backend ready', {
+            storageBackend: backend,
+            mongoDatabase: mongoDb,
+            mongoUriConfigured,
+            mainCollection: collectionName,
+            badRequestsCollection: badRequestsCollectionName,
+            skillExecutionsCollection: this.skillExecutionsCollectionName,
+            ...(backend === 'local'
+                ? {
+                    note: 'Activix is using local playground storage, not MongoDB. The ai-actions collection will not appear in Mongo until URI is set (MONGO_URI or MONGO_LOGS_URI), Activix can ping the database, and at least one activity is written.'
+                }
+                : {
+                    note: 'MongoDB stores one document per activity; the ai-actions collection is created on first insert (empty collections may be hidden in some tools until then).'
+                })
+        });
+    }
     /**
      * Get status of activity tracker
      */

package/dist/gateway-config.d.ts

@@ -6,6 +6,7 @@ import type { GatewayConfig } from './types.js';
 import type { Logxer } from '@x12i/logxer';
 import { LLMProviderRouter } from '@x12i/ai-providers-router';
 import { ActivityManager } from './activity-manager.js';
+import { OptimixerManager } from './optimixer-manager.js';
 import { UsageTracker } from './usage-tracker.js';
 import type { MessageBuilderConfig } from './message-builder.js';
 import type { TemplateRenderOptions } from '@x12i/rendrix';
@@ -16,6 +17,7 @@ export interface GatewayConfigContext {
     logger: Logxer;
     router: LLMProviderRouter;
     activityManager: ActivityManager;
+    optimixerManager: OptimixerManager;
     usageTracker: UsageTracker;
     messageBuilderConfig: MessageBuilderConfig;
 }
@@ -45,6 +47,7 @@ export declare function initializeGatewayComponents(config: GatewayConfig): {
     logger: Logxer;
     router: LLMProviderRouter;
     activityManager: ActivityManager;
+    optimixerManager: OptimixerManager;
     usageTracker: UsageTracker;
     messageBuilderConfig: MessageBuilderConfig;
     defaultModelConfig: Record<string, unknown>;

package/dist/gateway-config.js

@@ -48,6 +48,7 @@ function getDefaultsDir() {
 import { LLMProviderRouter } from '@x12i/ai-providers-router';
 import { createGatewayLogger } from './logger-factory.js';
 import { ActivityManager } from './activity-manager.js';
+import { OptimixerManager } from './optimixer-manager.js';
 import { UsageTracker } from './usage-tracker.js';
 import { mergeTemplateRenderOptions } from './template-render-merge.js';
 import { GatewayRateLimiter } from './gateway-rate-limiter.js';
@@ -278,6 +279,11 @@ export function initializeGatewayComponents(config) {
                     }
             })
     });
+    const optimixerManager = new OptimixerManager({
+        optimixer: config.optimixer,
+        logger,
+        getActivix: () => activityManager.getReadyTracker()
+    });
     const templateRendering = mergeTemplateRenderOptions(defaultTemplateRendering, config.templateRendering);
     const instructionsBlockOverrides = {
         ...(config.instructionsBlocks ?? {})
@@ -293,6 +299,7 @@ export function initializeGatewayComponents(config) {
         logger,
         router,
         activityManager,
+        optimixerManager,
         usageTracker,
         messageBuilderConfig,
         defaultModelConfig

package/dist/gateway-utils.d.ts

@@ -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
@@ -165,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/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 {
@@ -814,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, buildTraceUsageSummary, enrichTraceAttemptsWithBilling, 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) {
@@ -654,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,
@@ -687,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

@@ -32,6 +32,7 @@ export { Activix } 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

@@ -28,6 +28,7 @@ export { GATEWAY_DUAL_MEMORY_ROOTS, buildMemoryResolutionRootFromWorkingMemory,
 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';

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)
+                });
+            }
+        }
+    }
+}

package/dist/token-estimate.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Lightweight token-size estimates for Optimixer predict inputs.
+ * Uses a chars/4 heuristic (no tiktoken dependency).
+ */
+export declare function estimateTextTokens(text: string): number;
+export declare function estimateMessagesTokenSizes(messages: Array<{
+    role?: string;
+    content?: unknown;
+}>): {
+    inputSize: number;
+    contextSize: number;
+};

package/dist/token-estimate.js

@@ -0,0 +1,30 @@
+/**
+ * Lightweight token-size estimates for Optimixer predict inputs.
+ * Uses a chars/4 heuristic (no tiktoken dependency).
+ */
+export function estimateTextTokens(text) {
+    const trimmed = text.trim();
+    if (!trimmed)
+        return 0;
+    return Math.max(1, Math.ceil(trimmed.length / 4));
+}
+export function estimateMessagesTokenSizes(messages) {
+    let inputSize = 0;
+    let contextSize = 0;
+    for (const message of messages) {
+        const role = typeof message.role === 'string' ? message.role.toLowerCase() : '';
+        const content = typeof message.content === 'string'
+            ? message.content
+            : message.content != null
+                ? JSON.stringify(message.content)
+                : '';
+        const tokens = estimateTextTokens(content);
+        if (role === 'system') {
+            contextSize += tokens;
+        }
+        else {
+            inputSize += tokens;
+        }
+    }
+    return { inputSize, contextSize };
+}