@juspay/neurolink 9.25.2 → 9.26.0

package/dist/lib/neurolink.js

@@ -64,8 +64,48 @@ import { BinaryTaskClassifier } from "./utils/taskClassifier.js";
 // Transformation utilities
 import { extractToolNames, optimizeToolForCollection, transformAvailableTools, transformParamsForLogging, transformToolExecutions, transformToolExecutionsForMCP, transformToolsForMCP, transformToolsToDescriptions, transformToolsToExpectedFormat, } from "./utils/transformationUtils.js";
 import { isNonNullObject } from "./utils/typeUtils.js";
+import { resolveModel } from "./utils/modelAliasResolver.js";
 import { getWorkflow } from "./workflow/core/workflowRegistry.js";
 import { runWorkflow } from "./workflow/core/workflowRunner.js";
+/**
+ * NL-002: Classify MCP error messages into categories for AI disambiguation.
+ * Returns a human-readable error category based on error message content.
+ */
+function classifyMcpErrorMessage(text) {
+    const lower = text.toLowerCase();
+    if (lower.includes("not found") ||
+        lower.includes("404") ||
+        lower.includes("does not exist") ||
+        lower.includes("no such")) {
+        return "not_found";
+    }
+    if (lower.includes("permission") ||
+        lower.includes("forbidden") ||
+        lower.includes("403") ||
+        lower.includes("unauthorized") ||
+        lower.includes("401") ||
+        lower.includes("access denied")) {
+        return "permission_denied";
+    }
+    if (lower.includes("timeout") ||
+        lower.includes("timed out") ||
+        lower.includes("deadline exceeded")) {
+        return "timeout";
+    }
+    if (lower.includes("rate limit") ||
+        lower.includes("429") ||
+        lower.includes("too many requests") ||
+        lower.includes("throttl")) {
+        return "rate_limited";
+    }
+    if (lower.includes("invalid") ||
+        lower.includes("validation") ||
+        lower.includes("bad request") ||
+        lower.includes("400")) {
+        return "validation_error";
+    }
+    return "unknown";
+}
 /**
  * Check if an error is a non-retryable provider error that should immediately
  * stop the retry/fallback chain. These errors represent permanent failures
@@ -129,6 +169,16 @@ export class NeuroLink {
     // Cache for available tools to improve performance
     toolCache = null;
     toolCacheDuration;
+    // NL-004: Model alias/deprecation configuration
+    modelAliasConfig;
+    // Compaction watermark: prevents re-triggering compaction on already-compacted messages
+    // Per-session map to avoid cross-session pollution in server mode
+    lastCompactionMessageCount = new Map();
+    /** Extract sessionId from options context for compaction watermark keying */
+    getCompactionSessionId(options) {
+        return (options.context
+            ?.sessionId || "__default__");
+    }
     // Enhanced error handling support
     toolCircuitBreakers = new Map();
     toolExecutionMetrics = new Map();
@@ -375,6 +425,10 @@ export class NeuroLink {
         this.observabilityConfig = config?.observability;
         // Initialize orchestration setting
         this.enableOrchestration = config?.enableOrchestration ?? false;
+        // NL-004: Initialize model alias configuration
+        if (config?.modelAliasConfig) {
+            this.modelAliasConfig = config.modelAliasConfig;
+        }
         logger.setEventEmitter(this.emitter);
         // Read tool cache duration from environment variables, with a default
         const cacheDurationEnv = process.env.NEUROLINK_TOOL_CACHE_DURATION;
@@ -2053,9 +2107,12 @@ Current user's request: ${currentInput}`;
                 try {
                     const originalPrompt = this._extractOriginalPrompt(optionsOrPrompt);
                     // Convert string prompt to full options
+                    // Shallow-copy caller's object to avoid mutating their original reference
                     const options = typeof optionsOrPrompt === "string"
                         ? { input: { text: optionsOrPrompt } }
-                        : optionsOrPrompt;
+                        : { ...optionsOrPrompt };
+                    // NL-004: Resolve model aliases/deprecations before processing
+                    options.model = resolveModel(options.model, this.modelAliasConfig);
                     // Set span attributes for observability
                     generateSpan.setAttribute("neurolink.provider", options.provider || "default");
                     generateSpan.setAttribute("neurolink.model", options.model || "default");
@@ -2141,6 +2198,10 @@ Current user's request: ${currentInput}`;
                                 });
                                 // Use orchestrated options
                                 Object.assign(options, orchestratedOptions);
+                                // Re-resolve model alias in case orchestration returned an alias
+                                if (orchestratedOptions.model) {
+                                    options.model = resolveModel(options.model, this.modelAliasConfig);
+                                }
                             }
                             catch (error) {
                                 logger.warn("Orchestration failed, continuing with original options", {
@@ -2328,6 +2389,8 @@ Current user's request: ${currentInput}`;
                             audio: textResult.audio,
                             video: textResult.video,
                             ppt: textResult.ppt,
+                            // NL-007: Copy retry metadata from MCP generation path
+                            ...(textResult.retries && { retries: textResult.retries }),
                         };
                         // Accumulate session cost for budget tracking
                         if (generateResult.analytics?.cost &&
@@ -2342,6 +2405,8 @@ Current user's request: ${currentInput}`;
                         generateSpan.setAttribute("neurolink.finish_reason", generateResult.finishReason || "unknown");
                         generateSpan.setAttribute("neurolink.result_provider", generateResult.provider || "unknown");
                         generateSpan.setAttribute("neurolink.result_model", generateResult.model || "unknown");
+                        // NL-007: Expose retry count in OTel span
+                        generateSpan.setAttribute("generate.retry_count", generateResult.retries?.count || 0);
                         generateSpan.setStatus({ code: SpanStatusCode.OK });
                         return generateResult;
                     });
@@ -2694,6 +2759,8 @@ Current user's request: ${currentInput}`;
             options.prompt.trim() === "") {
             throw new Error("GenerateText options must include prompt as a non-empty string");
         }
+        // NL-004: Resolve model aliases/deprecations before processing
+        options.model = resolveModel(options.model, this.modelAliasConfig);
         // Use internal generation method directly
         return await this.generateTextInternal(options);
     }
@@ -3038,6 +3105,9 @@ Current user's request: ${currentInput}`;
      */
     async performMCPGenerationRetries(options, generateInternalId, generateInternalStartTime, generateInternalHrTimeStart, functionTag) {
         const maxMcpRetries = RETRY_ATTEMPTS.QUICK;
+        // NL-007: Track retry metadata for observability
+        const retryErrors = [];
+        let retryCount = 0;
         const maxAttempts = maxMcpRetries + 1;
         for (let attempt = 1; attempt <= maxAttempts; attempt++) {
             if (options.abortSignal?.aborted) {
@@ -3054,7 +3124,12 @@ Current user's request: ${currentInput}`;
                         contentLength: mcpResult.content?.length || 0,
                         toolsUsed: mcpResult.toolsUsed?.length || 0,
                         toolExecutions: mcpResult.toolExecutions?.length || 0,
+                        retryCount,
                     });
+                    // NL-007: Attach retry metadata to result
+                    if (retryCount > 0) {
+                        mcpResult.retries = { count: retryCount, errors: retryErrors };
+                    }
                     return mcpResult;
                 }
                 else {
@@ -3072,9 +3147,19 @@ Current user's request: ${currentInput}`;
                     logger.debug(`[${functionTag}] AbortError detected on attempt ${attempt}, stopping retries`);
                     throw error;
                 }
+                // NL-007: Record retry error for observability
+                retryCount++;
+                const errMsg = error instanceof Error ? error.message : String(error);
+                const errCode = error instanceof NeuroLinkError
+                    ? error.code
+                    : error instanceof Error
+                        ? error.name
+                        : "UNKNOWN";
+                retryErrors.push({ code: errCode, message: errMsg.substring(0, 500) });
                 logger.debug(`[${functionTag}] MCP generation failed on attempt ${attempt}/${maxAttempts}`, {
-                    error: error instanceof Error ? error.message : String(error),
+                    error: errMsg,
                     willRetry: attempt < maxAttempts,
+                    retryCount,
                 });
                 // Check for non-retryable errors — skip remaining retries immediately
                 // NoSuchToolError / InvalidToolArgumentsError from Vercel AI SDK are never
@@ -3162,6 +3247,11 @@ Current user's request: ${currentInput}`;
                 : options.provider;
             // Get available tools
             let availableTools = await this.getAllAvailableTools();
+            // NL-001: Filter out tools with OPEN circuit breakers
+            const { tools: circuitBreakerFilteredTools, unavailableTools } = this.toolRegistry.getAvailableTools(this.toolCircuitBreakers);
+            // Intersect: keep only tools that pass both getAllAvailableTools and circuit breaker filtering
+            const cbFilteredNames = new Set(circuitBreakerFilteredTools.map((t) => t.name));
+            availableTools = availableTools.filter((t) => cbFilteredNames.has(t.name));
             // Apply per-call tool filtering for system prompt tool descriptions
             availableTools = this.applyToolInfoFiltering(availableTools, options);
             const targetTool = availableTools.find((t) => t.name.includes("SuccessRateSRByTime") ||
@@ -3169,6 +3259,8 @@ Current user's request: ${currentInput}`;
             logger.debug("Available tools for AI prompt generation", {
                 toolsCount: availableTools.length,
                 toolNames: availableTools.map((t) => t.name),
+                unavailableToolsCount: unavailableTools.length,
+                unavailableTools: unavailableTools,
                 hasTargetTool: !!targetTool,
                 targetToolDetails: targetTool
                     ? {
@@ -3178,10 +3270,15 @@ Current user's request: ${currentInput}`;
                     }
                     : null,
             });
+            // NL-001: Inject system note about unavailable tools
+            let circuitBreakerNote = "";
+            if (unavailableTools.length > 0) {
+                circuitBreakerNote = `\n\nNOTE: The following tools are temporarily unavailable due to repeated failures: ${unavailableTools.join(", ")}. Do not attempt to call these tools.`;
+            }
             // Create tool-aware system prompt (skip if skipToolPromptInjection is true)
             const enhancedSystemPrompt = options.skipToolPromptInjection
-                ? options.systemPrompt || ""
-                : this.createToolAwareSystemPrompt(options.systemPrompt, availableTools);
+                ? (options.systemPrompt || "") + circuitBreakerNote
+                : this.createToolAwareSystemPrompt(options.systemPrompt, availableTools) + circuitBreakerNote;
             logger.debug("Tool-aware system prompt created", {
                 requestId,
                 originalPromptLength: options.systemPrompt?.length || 0,
@@ -3260,7 +3357,12 @@ Current user's request: ${currentInput}`;
                 conversationMessageCount: conversationMessages?.length || 0,
                 shouldCompact: budgetResult.shouldCompact,
             });
-            if (budgetResult.shouldCompact && this.conversationMemory) {
+            const messageCount = conversationMessages?.length || 0;
+            const compactionSessionId = this.getCompactionSessionId(options);
+            if (budgetResult.shouldCompact &&
+                this.conversationMemory &&
+                messageCount >
+                    (this.lastCompactionMessageCount.get(compactionSessionId) ?? 0)) {
                 logger.info("[NeuroLink] Context budget exceeded, triggering auto-compaction", {
                     usageRatio: budgetResult.usageRatio,
                     estimatedTokens: budgetResult.estimatedInputTokens,
@@ -3277,6 +3379,7 @@ Current user's request: ${currentInput}`;
                 if (compactionResult.compacted) {
                     const repairedResult = repairToolPairs(compactionResult.messages);
                     conversationMessages = repairedResult.messages;
+                    this.lastCompactionMessageCount.set(compactionSessionId, conversationMessages.length);
                     logger.info("[NeuroLink] Context compacted successfully", {
                         stagesUsed: compactionResult.stagesUsed,
                         tokensSaved: compactionResult.tokensSaved,
@@ -3495,12 +3598,24 @@ Current user's request: ${currentInput}`;
                         ? Object.values(options.tools)
                         : undefined,
                 });
-                if (budgetCheck.shouldCompact && this.conversationMemory) {
-                    const compactor = new ContextCompactor({ provider: providerName });
-                    const compactionResult = await compactor.compact(conversationMessages, budgetCheck.availableInputTokens, undefined, options.context?.requestId);
+                const dpgMessageCount = conversationMessages?.length || 0;
+                const dpgCompactionSessionId = this.getCompactionSessionId(options);
+                if (budgetCheck.shouldCompact &&
+                    this.conversationMemory &&
+                    dpgMessageCount >
+                        (this.lastCompactionMessageCount.get(dpgCompactionSessionId) ?? 0)) {
+                    const compactor = new ContextCompactor({
+                        provider: providerName,
+                        summarizationProvider: this.conversationMemoryConfig?.conversationMemory
+                            ?.summarizationProvider,
+                        summarizationModel: this.conversationMemoryConfig?.conversationMemory
+                            ?.summarizationModel,
+                    });
+                    const compactionResult = await compactor.compact(conversationMessages, budgetCheck.availableInputTokens, this.conversationMemoryConfig?.conversationMemory, options.context?.requestId);
                     if (compactionResult.compacted) {
                         const repairedResult = repairToolPairs(compactionResult.messages);
                         conversationMessages = repairedResult.messages;
+                        this.lastCompactionMessageCount.set(dpgCompactionSessionId, conversationMessages.length);
                     }
                     // POST-COMPACTION BUDGET RE-CHECK (BUG-003 fix)
                     const postCompactBudget = checkContextBudget({
@@ -3782,6 +3897,8 @@ Current user's request: ${currentInput}`;
      * @throws {Error} When conversation memory operations fail (if enabled)
      */
     async stream(options) {
+        // Shallow-copy caller's object to avoid mutating their original reference
+        options = { ...options };
         // Set metrics trace context for parent-child span linking
         const metricsTraceId = crypto.randomUUID().replace(/-/g, "");
         const metricsParentSpanId = crypto
@@ -3806,6 +3923,8 @@ Current user's request: ${currentInput}`;
             });
             const spanStartTime = Date.now();
             try {
+                // NL-004: Resolve model aliases/deprecations before processing
+                options.model = resolveModel(options.model, this.modelAliasConfig);
                 const startTime = Date.now();
                 const hrTimeStart = process.hrtime.bigint();
                 const streamId = `neurolink-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
@@ -4110,6 +4229,10 @@ Current user's request: ${currentInput}`;
                 });
                 // Use orchestrated options
                 Object.assign(options, orchestratedOptions);
+                // Re-resolve model alias in case orchestration returned an alias
+                if (orchestratedOptions.model) {
+                    options.model = resolveModel(options.model, this.modelAliasConfig);
+                }
             }
             catch (error) {
                 logger.warn("Stream orchestration failed, continuing with original options", {
@@ -4488,12 +4611,60 @@ Current user's request: ${currentInput}`;
             currentPrompt: options.input.text,
             toolDefinitions: availableTools,
         });
-        if (streamBudget.shouldCompact && this.conversationMemory) {
-            const compactor = new ContextCompactor({ provider: providerName });
-            const compactionResult = await compactor.compact(conversationMessages, streamBudget.availableInputTokens, undefined, options.context?.requestId);
+        const streamMessageCount = conversationMessages?.length || 0;
+        const streamCompactionSessionId = this.getCompactionSessionId(options);
+        if (streamBudget.shouldCompact &&
+            this.conversationMemory &&
+            streamMessageCount >
+                (this.lastCompactionMessageCount.get(streamCompactionSessionId) ?? 0)) {
+            const compactor = new ContextCompactor({
+                provider: providerName,
+                summarizationProvider: this.conversationMemoryConfig?.conversationMemory
+                    ?.summarizationProvider,
+                summarizationModel: this.conversationMemoryConfig?.conversationMemory?.summarizationModel,
+            });
+            const compactionResult = await compactor.compact(conversationMessages, streamBudget.availableInputTokens, this.conversationMemoryConfig?.conversationMemory, options.context?.requestId);
             if (compactionResult.compacted) {
                 const repairedResult = repairToolPairs(compactionResult.messages);
                 conversationMessages = repairedResult.messages;
+                this.lastCompactionMessageCount.set(streamCompactionSessionId, conversationMessages.length);
+            }
+            // POST-COMPACTION BUDGET RE-CHECK (mirrors tryMCPGeneration / directProviderGeneration)
+            const postCompactBudget = checkContextBudget({
+                provider: providerName,
+                model: options.model,
+                maxTokens: options.maxTokens,
+                systemPrompt: enhancedSystemPrompt,
+                conversationMessages: conversationMessages,
+                currentPrompt: options.input.text,
+                toolDefinitions: availableTools,
+            });
+            if (!postCompactBudget.withinBudget) {
+                logger.warn("[NeuroLink] Stream: post-compaction still over budget, emergency truncation", {
+                    estimatedTokens: postCompactBudget.estimatedInputTokens,
+                    availableTokens: postCompactBudget.availableInputTokens,
+                    overagePercent: Math.round((postCompactBudget.usageRatio - 1.0) * 100),
+                });
+                conversationMessages = emergencyContentTruncation(conversationMessages, postCompactBudget.availableInputTokens, postCompactBudget.breakdown, providerName);
+                const finalBudget = checkContextBudget({
+                    provider: providerName,
+                    model: options.model,
+                    maxTokens: options.maxTokens,
+                    systemPrompt: enhancedSystemPrompt,
+                    conversationMessages: conversationMessages,
+                    currentPrompt: options.input.text,
+                    toolDefinitions: availableTools,
+                });
+                if (!finalBudget.withinBudget) {
+                    throw new ContextBudgetExceededError(`Stream context exceeds model budget after all compaction stages. ` +
+                        `Estimated: ${finalBudget.estimatedInputTokens} tokens, ` +
+                        `Budget: ${finalBudget.availableInputTokens} tokens.`, {
+                        estimatedTokens: finalBudget.estimatedInputTokens,
+                        availableTokens: finalBudget.availableInputTokens,
+                        stagesUsed: compactionResult.stagesUsed,
+                        breakdown: finalBudget.breakdown,
+                    });
+                }
             }
         }
         // 🔧 FIX: Pass enhanced system prompt to real streaming
@@ -5416,11 +5587,15 @@ Current user's request: ${currentInput}`;
                 // Track memory usage for tool execution
                 const { MemoryManager } = await import("./utils/performance.js");
                 const startMemory = MemoryManager.getMemoryUsageMB();
+                // NL-004: Use composite key (serverId.toolName) to avoid cross-server collisions
+                const toolInfo = this.toolRegistry.getToolInfo(toolName);
+                const breakerServerId = externalTool?.serverId || toolInfo?.tool?.serverId || "unknown";
+                const breakerKey = `${breakerServerId}.${toolName}`;
                 // Get or create circuit breaker for this tool
-                if (!this.toolCircuitBreakers.has(toolName)) {
-                    this.toolCircuitBreakers.set(toolName, new CircuitBreaker(CIRCUIT_BREAKER.FAILURE_THRESHOLD, CIRCUIT_BREAKER_RESET_MS));
+                if (!this.toolCircuitBreakers.has(breakerKey)) {
+                    this.toolCircuitBreakers.set(breakerKey, new CircuitBreaker(CIRCUIT_BREAKER.FAILURE_THRESHOLD, CIRCUIT_BREAKER_RESET_MS));
                 }
-                const circuitBreaker = this.toolCircuitBreakers.get(toolName);
+                const circuitBreaker = this.toolCircuitBreakers.get(breakerKey);
                 // Initialize metrics for this tool if not exists
                 if (!this.toolExecutionMetrics.has(toolName)) {
                     this.toolExecutionMetrics.set(toolName, {
@@ -5497,6 +5672,61 @@ Current user's request: ${currentInput}`;
                         typeof result === "object" &&
                         "isError" in result &&
                         result.isError === true;
+                    // NL-001: Count isError:true results as circuit breaker failures
+                    // This ensures tools that return error results (not just thrown errors) are tracked
+                    // TODO(NL-009): This records a failure AFTER the circuit breaker already recorded
+                    // success inside `circuitBreaker.execute()`. The correct fix is to check `isToolError`
+                    // inside the execute callback and throw before returning, so the breaker never sees
+                    // success. Deferred because moving the check inside the callback requires restructuring
+                    // the retry/timeout wrapper chain and is high-risk for a hot-path change.
+                    if (isToolError && circuitBreaker) {
+                        // Record a failure by executing a rejected promise through the breaker
+                        try {
+                            await circuitBreaker.execute(async () => {
+                                throw new Error(`Tool ${toolName} returned isError:true`);
+                            });
+                        }
+                        catch {
+                            // Expected — we intentionally triggered the failure recording
+                        }
+                        mcpLogger.debug(`[${functionTag}] Circuit breaker failure recorded for isError result`, {
+                            toolName,
+                            circuitBreakerState: circuitBreaker.getState(),
+                            circuitBreakerFailures: circuitBreaker.getFailureCount(),
+                        });
+                    }
+                    // NL-002 + NL-003: Format and capture MCP error results
+                    if (isToolError) {
+                        const resultObj = result;
+                        const contentArr = resultObj.content;
+                        const errorText = contentArr
+                            ?.filter((c) => c.type === "text" && c.text)
+                            .map((c) => c.text)
+                            .join(" ") ||
+                            (typeof resultObj.error === "string"
+                                ? resultObj.error
+                                : "Unknown error");
+                        const errorCategory = classifyMcpErrorMessage(errorText);
+                        const prefix = `[TOOL_ERROR: ${toolName} failed (${errorCategory})] `;
+                        // NL-002: Clone content array to avoid mutating shared objects, then prefix error
+                        if (contentArr && Array.isArray(contentArr)) {
+                            const clonedContent = contentArr.map((c) => ({ ...c }));
+                            for (const content of clonedContent) {
+                                if (content.type === "text" && content.text) {
+                                    content.text = prefix + content.text;
+                                    break; // Only prefix the first text content
+                                }
+                            }
+                            resultObj.content = clonedContent;
+                        }
+                        // NL-003: Capture error details in span attributes for telemetry
+                        toolSpan.setAttribute("tool.error.message", errorText.substring(0, 500));
+                        toolSpan.setAttribute("tool.error.category", errorCategory);
+                        toolSpan.setStatus({
+                            code: SpanStatusCode.ERROR,
+                            message: `MCP tool returned isError: ${errorText.substring(0, 200)}`,
+                        });
+                    }
                     toolSpan.setAttribute("tool.result.status", isToolError ? "error" : "success");
                     toolSpan.setAttribute("tool.duration_ms", executionTime);
                     return result;
@@ -6214,6 +6444,15 @@ Current user's request: ${currentInput}`;
         }
         return metrics;
     }
+    /**
+     * NL-004: Set model alias/deprecation configuration.
+     * Models in the alias map will be warned, redirected, or blocked based on their action.
+     * @param config - Model alias configuration with aliases map
+     */
+    setModelAliasConfig(config) {
+        this.modelAliasConfig = config;
+        logger.info(`[ModelAlias] Configured ${Object.keys(config.aliases).length} model aliases`);
+    }
     /**
      * Get circuit breaker status for all tools
      * @returns Object with circuit breaker status for each tool
@@ -6257,9 +6496,17 @@ Current user's request: ${currentInput}`;
         // Get all tool names from toolRegistry
         const allTools = await this.toolRegistry.listTools();
         const allToolNames = new Set(allTools.map((tool) => tool.name));
+        // Build a lookup from tool name to serverId for composite breaker keys
+        const toolServerIdMap = new Map();
+        for (const tool of allTools) {
+            if (!toolServerIdMap.has(tool.name)) {
+                toolServerIdMap.set(tool.name, tool.serverId || "unknown");
+            }
+        }
         for (const toolName of allToolNames) {
             const metrics = this.toolExecutionMetrics.get(toolName);
-            const circuitBreaker = this.toolCircuitBreakers.get(toolName);
+            const breakerKey = `${toolServerIdMap.get(toolName) || "unknown"}.${toolName}`;
+            const circuitBreaker = this.toolCircuitBreakers.get(breakerKey);
             const successRate = metrics
                 ? metrics.totalExecutions > 0
                     ? metrics.successfulExecutions / metrics.totalExecutions
@@ -6410,6 +6657,7 @@ Current user's request: ${currentInput}`;
                 retriable: false,
             });
         }
+        this.lastCompactionMessageCount.delete(sessionId);
         return await this.conversationMemory.clearSession(sessionId);
     }
     /**
@@ -6428,6 +6676,7 @@ Current user's request: ${currentInput}`;
                 retriable: false,
             });
         }
+        this.lastCompactionMessageCount.clear();
         await this.conversationMemory.clearAllSessions();
     }
     /**
@@ -6870,6 +7119,8 @@ Current user's request: ${currentInput}`;
      */
     async dispose() {
         logger.debug("[NeuroLink] Starting disposal of resources...");
+        // Clear per-session compaction watermarks
+        this.lastCompactionMessageCount.clear();
         const cleanupErrors = [];
         try {
             // 1. Flush and shutdown OpenTelemetry
@@ -7014,8 +7265,21 @@ Current user's request: ${currentInput}`;
         if (!messages || messages.length === 0) {
             return null;
         }
-        const compactor = new ContextCompactor(config);
-        const targetTokens = Math.floor(messages.length * 100); // Rough target
+        const compactor = new ContextCompactor({
+            ...config,
+            summarizationProvider: config?.summarizationProvider ??
+                this.conversationMemoryConfig?.conversationMemory
+                    ?.summarizationProvider,
+            summarizationModel: config?.summarizationModel ??
+                this.conversationMemoryConfig?.conversationMemory?.summarizationModel,
+        });
+        // Use actual context window to determine target, not arbitrary heuristic
+        const budgetInfo = checkContextBudget({
+            provider: config?.provider || "openai",
+            conversationMessages: messages,
+        });
+        // Target 60% of available input tokens — leave room for new messages
+        const targetTokens = Math.floor(budgetInfo.availableInputTokens * 0.6);
         const result = await compactor.compact(messages, targetTokens, this.conversationMemoryConfig?.conversationMemory);
         if (result.compacted) {
             repairToolPairs(result.messages);

package/dist/lib/providers/googleAiStudio.js

@@ -1,17 +1,17 @@
 import { createGoogleGenerativeAI } from "@ai-sdk/google";
 import { embed, embedMany, streamText, } from "ai";
 import { ErrorCategory, ErrorSeverity, GoogleAIModels, } from "../constants/enums.js";
-import { estimateTokens } from "../utils/tokenEstimation.js";
 import { BaseProvider } from "../core/baseProvider.js";
 import { DEFAULT_MAX_STEPS } from "../core/constants.js";
 import { streamAnalyticsCollector } from "../core/streamAnalytics.js";
+import { ATTR, tracers, withClientSpan } from "../telemetry/index.js";
 import { AuthenticationError, NetworkError, ProviderError, RateLimitError, } from "../types/errors.js";
 import { ERROR_CODES, NeuroLinkError } from "../utils/errorHandling.js";
 import { logger } from "../utils/logger.js";
 import { isGemini3Model } from "../utils/modelDetection.js";
-import { tracers, ATTR, withClientSpan } from "../telemetry/index.js";
 import { composeAbortSignals, createTimeoutController, TimeoutError, } from "../utils/timeout.js";
-import { buildNativeToolDeclarations, buildNativeConfig, computeMaxSteps, collectStreamChunks, extractTextFromParts, executeNativeToolCalls, handleMaxStepsTermination, pushModelResponseToHistory, sanitizeToolsForGemini, } from "./googleNativeGemini3.js";
+import { estimateTokens } from "../utils/tokenEstimation.js";
+import { buildNativeConfig, buildNativeToolDeclarations, collectStreamChunks, computeMaxSteps, executeNativeToolCalls, extractTextFromParts, handleMaxStepsTermination, pushModelResponseToHistory, sanitizeToolsForGemini, } from "./googleNativeGemini3.js";
 // Google AI Live API types now imported from ../types/providerSpecific.js
 // Import proper types for multimodal message handling
 // Create Google GenAI client
@@ -626,9 +626,12 @@ export class GoogleAIStudioProvider extends BaseProvider {
                         // Add model response with ALL parts (including thoughtSignature) to history
                         pushModelResponseToHistory(currentContents, chunkResult.rawResponseParts, chunkResult.stepFunctionCalls);
                         const functionResponses = await executeNativeToolCalls("[GoogleAIStudio]", chunkResult.stepFunctionCalls, executeMap, failedTools, allToolCalls, { abortSignal: composedSignal });
-                        // Add function responses to history
+                        // Add function responses to history — the @google/genai SDK
+                        // only accepts "user" and "model" as valid roles in contents.
+                        // Function/tool responses must use role: "user" (matching the
+                        // SDK's own automaticFunctionCalling implementation).
                         currentContents.push({
-                            role: "function",
+                            role: "user",
                             parts: functionResponses,
                         });
                     }
@@ -776,9 +779,12 @@ export class GoogleAIStudioProvider extends BaseProvider {
                         // This is critical for Gemini 3 - it requires thought signatures in subsequent turns
                         pushModelResponseToHistory(currentContents, chunkResult.rawResponseParts, chunkResult.stepFunctionCalls);
                         const functionResponses = await executeNativeToolCalls("[GoogleAIStudio]", chunkResult.stepFunctionCalls, executeMap, failedTools, allToolCalls, { toolExecutions, abortSignal: composedSignal });
-                        // Add function responses to history
+                        // Add function responses to history — the @google/genai SDK
+                        // only accepts "user" and "model" as valid roles in contents.
+                        // Function/tool responses must use role: "user" (matching the
+                        // SDK's own automaticFunctionCalling implementation).
                         currentContents.push({
-                            role: "function",
+                            role: "user",
                             parts: functionResponses,
                         });
                     }

package/dist/lib/types/configTypes.d.ts

@@ -27,6 +27,7 @@ export type NeurolinkConstructorConfig = {
     hitl?: HITLConfig;
     toolRegistry?: MCPToolRegistry;
     observability?: ObservabilityConfig;
+    modelAliasConfig?: import("./generateTypes.js").ModelAliasConfig;
 };
 /**
  * Provider-specific configuration
@@ -117,6 +118,8 @@ export type ToolConfig = {
     maxToolsPerProvider?: number;
     /** Whether MCP tools should be enabled */
     enableMCPTools?: boolean;
+    /** Whether the bash command execution tool should be enabled (opt-in, defaults to false) */
+    enableBashTool?: boolean;
 };
 /**
  * Backup metadata information

package/dist/lib/types/contextTypes.d.ts

@@ -2,10 +2,9 @@
  * Context Types for NeuroLink - Factory Pattern Implementation
  * Provides type-safe context integration for AI generation
  */
-import type { JsonObject } from "./common.js";
 import type { ExecutionContext } from "../types/tools.js";
+import type { JsonObject } from "./common.js";
 import type { ChatMessage, ConversationMemoryConfig } from "./conversation.js";
-import type { CompactionStage } from "../context/contextCompactor.js";
 /**
  * Base context type for all AI operations
  */
@@ -173,6 +172,8 @@ export declare class ContextConverter {
     private static inferProvider;
     private static extractCustomData;
 }
+/** Stages available in the compaction pipeline. */
+export type CompactionStage = "prune" | "deduplicate" | "summarize" | "truncate";
 /** Result of multi-stage context compaction. */
 export type CompactionResult = {
     compacted: boolean;
@@ -447,6 +448,8 @@ export type SummarizeConfig = {
     model?: string;
     keepRecentRatio?: number;
     memoryConfig?: Partial<ConversationMemoryConfig>;
+    /** Target token budget — when set, split uses token counting instead of message count */
+    targetTokens?: number;
 };
 /** Result of structured LLM summarization (Stage 3). */
 export type SummarizeResult = {