@juspay/neurolink 9.30.0 → 9.31.1

package/dist/neurolink.js

@@ -6,9 +6,11 @@
  * Uses real MCP infrastructure for tool discovery and execution.
  */
 // Load environment variables from .env file (critical for SDK usage)
-import { config as dotenvConfig } from "dotenv";
+// Suppress dotenv v17 stdout banner — it pollutes CLI JSON output
 try {
-    dotenvConfig(); // Load .env from current working directory
+    process.env.DOTENV_CONFIG_QUIET = process.env.DOTENV_CONFIG_QUIET ?? "true";
+    const { config: dotenvConfig } = await import("dotenv");
+    dotenvConfig({ quiet: true });
 }
 catch {
     // Environment variables should be set externally in production
@@ -43,7 +45,6 @@ import { directToolsServer } from "./mcp/servers/agent/directToolsServer.js";
 import { inferAnnotations, isSafeToRetry } from "./mcp/toolAnnotations.js";
 import { MCPToolRegistry } from "./mcp/toolRegistry.js";
 import { initializeHippocampus, } from "./memory/hippocampusInitializer.js";
-import { initializeMem0 } from "./memory/mem0Initializer.js";
 import { createMemoryRetrievalTools } from "./memory/memoryRetrievalTools.js";
 import { getMetricsAggregator, MetricsAggregator, } from "./observability/metricsAggregator.js";
 import { SpanStatus, SpanType } from "./observability/types/spanTypes.js";
@@ -56,6 +57,7 @@ import { AuthenticationError, AuthorizationError, InvalidModelError, } from "./t
 import { getConversationMessages, storeConversationTurn, } from "./utils/conversationMemory.js";
 // Enhanced error handling imports
 import { CircuitBreaker, ERROR_CODES, ErrorFactory, isAbortError, isRetriableError, logStructuredError, NeuroLinkError, withRetry, withTimeout, } from "./utils/errorHandling.js";
+import { CircuitBreakerOpenError } from "./types/circuitBreakerErrors.js";
 // Factory processing imports
 import { createCleanStreamOptions, enhanceTextGenerationOptions, processFactoryOptions, processStreamingFactoryOptions, validateFactoryConfig, } from "./utils/factoryProcessing.js";
 import { logger, mcpLogger } from "./utils/logger.js";
@@ -112,6 +114,22 @@ function classifyMcpErrorMessage(text) {
     }
     return "unknown";
 }
+function mcpCategoryToErrorCategory(mcpCategory) {
+    switch (mcpCategory) {
+        case "not_found":
+            return ErrorCategory.VALIDATION;
+        case "permission_denied":
+            return ErrorCategory.PERMISSION;
+        case "timeout":
+            return ErrorCategory.TIMEOUT;
+        case "rate_limited":
+            return ErrorCategory.RESOURCE;
+        case "validation_error":
+            return ErrorCategory.VALIDATION;
+        case "unknown":
+            return ErrorCategory.EXECUTION;
+    }
+}
 /**
  * Check if an error is a non-retryable provider error that should immediately
  * stop the retry/fallback chain. These errors represent permanent failures
@@ -166,6 +184,7 @@ function isNonRetryableProviderError(error) {
 const metricsTraceContextStorage = new AsyncLocalStorage();
 export class NeuroLink {
     mcpInitialized = false;
+    mcpSkipped = false;
     mcpInitPromise = null;
     emitter = new EventEmitter();
     toolRegistry;
@@ -210,13 +229,15 @@ export class NeuroLink {
      */
     emitToolEndEvent(toolName, startTime, success, result, error) {
         // Emit tool end event (NeuroLink format - enhanced with result/error)
+        // Serialize error to string for consumer compatibility (event listeners
+        // commonly check `typeof event.error === "string"`).
         this.emitter.emit("tool:end", {
             toolName,
             responseTime: Date.now() - startTime,
             success,
             timestamp: Date.now(),
             result: result, // Enhanced: include actual result
-            error: error, // Enhanced: include error if present
+            error: error ? error.message : undefined, // Emit as string, not Error object
         });
     }
     // Conversation memory support
@@ -227,9 +248,6 @@ export class NeuroLink {
     enableOrchestration;
     // HITL (Human-in-the-Loop) support
     hitlManager;
-    // Mem0 memory instance and config for conversation context
-    mem0Instance;
-    mem0Config;
     // Accumulated cost in USD across all generate() calls on this instance
     _sessionCostUsd = 0;
     // File Reference Registry for lazy on-demand file processing
@@ -312,35 +330,6 @@ export class NeuroLink {
         }
         return await callback();
     }
-    /**
-     * Simple sync config setup for mem0
-     */
-    initializeMem0Config() {
-        const config = this.conversationMemoryConfig?.conversationMemory;
-        if (!config?.mem0Enabled) {
-            return false;
-        }
-        this.mem0Config = config.mem0Config;
-        return true;
-    }
-    /**
-     * Async initialization called during generate/stream
-     */
-    async ensureMem0Ready() {
-        if (this.mem0Instance !== undefined) {
-            return this.mem0Instance;
-        }
-        if (!this.initializeMem0Config()) {
-            this.mem0Instance = null;
-            return null;
-        }
-        if (!this.mem0Config) {
-            this.mem0Instance = null;
-            return null;
-        }
-        this.mem0Instance = await initializeMem0(this.mem0Config);
-        return this.mem0Instance;
-    }
     initializeMemoryConfig() {
         const memory = this.conversationMemoryConfig?.conversationMemory?.memory;
         if (!memory?.enabled) {
@@ -696,6 +685,12 @@ export class NeuroLink {
                         };
                     }
                     catch (error) {
+                        // Known limitation: this non-throwing error path returns
+                        // { success: false } without recording errorCategories in
+                        // toolExecutionMetrics. These are internal file-tool failures
+                        // (low frequency), so the risk of metric gaps is minimal.
+                        // A full fix would require access to the metrics map here,
+                        // which is not available in the registration closure.
                         return {
                             success: false,
                             error: error instanceof Error ? error.message : String(error),
@@ -793,6 +788,12 @@ export class NeuroLink {
                         return await toolDef.execute(params);
                     }
                     catch (error) {
+                        // Known limitation: this non-throwing error path returns
+                        // { success: false } without recording errorCategories in
+                        // toolExecutionMetrics. These are internal memory-tool failures
+                        // (low frequency), so the risk of metric gaps is minimal.
+                        // A full fix would require access to the metrics map here,
+                        // which is not available in the registration closure.
                         return {
                             success: false,
                             error: error instanceof Error ? error.message : String(error),
@@ -816,27 +817,6 @@ ${memoryContext}
 
 Current user's request: ${currentInput}`;
     }
-    /** Extract memory context from search results */
-    extractMemoryContext(memories) {
-        return memories
-            .map((m) => m.memory || "")
-            .filter(Boolean)
-            .join("\n");
-    }
-    /** Store conversation turn in mem0 */
-    async storeMem0ConversationTurn(mem0, userContent, aiResponse, userId, metadata) {
-        // Store both user message and AI response for better context extraction
-        const conversationTurn = [
-            { role: "user", content: userContent },
-            { role: "assistant", content: aiResponse },
-        ];
-        await mem0.add(conversationTurn, {
-            user_id: userId,
-            metadata,
-            infer: true,
-            async_mode: true,
-        });
-    }
     /**
      * Retrieve condensed memory for a user.
      * Returns the input text enhanced with memory context, or unchanged if no memory.
@@ -913,7 +893,7 @@ Current user's request: ${currentInput}`;
         try {
             this.externalServerManager = new ExternalServerManager({
                 maxServers: 20,
-                defaultTimeout: 30000, // Increased from 15s to 30s for proxy latency (e.g., LiteLLM)
+                defaultTimeout: Math.max(10000, Number(process.env.MCP_CLIENT_TIMEOUT) || 60000),
                 enableAutoRestart: true,
                 enablePerformanceMonitoring: true,
             }, {
@@ -1120,8 +1100,9 @@ Current user's request: ${currentInput}`;
      * Uses isolated async context to prevent hanging
      */
     async initializeMCP() {
-        // Skip if already initialized — prevents redundant re-init on every generate call
-        if (this.mcpInitialized) {
+        // Skip if already initialized or explicitly skipped — prevents redundant
+        // re-init on every generate call.
+        if (this.mcpInitialized || this.mcpSkipped) {
             return;
         }
         // Deduplicate concurrent initialization attempts — if an init is already
@@ -1130,6 +1111,21 @@ Current user's request: ${currentInput}`;
         if (this.mcpInitPromise) {
             return this.mcpInitPromise;
         }
+        // Environment-level kill switch — skip MCP-specific initialization on cold
+        // start but always ensure providers are registered exactly once.
+        if (process.env.NEUROLINK_SKIP_MCP === "true") {
+            this.mcpInitPromise = (async () => {
+                await this.initializeProviderRegistryInternal();
+                this.mcpSkipped = true;
+            })();
+            try {
+                await this.mcpInitPromise;
+            }
+            finally {
+                this.mcpInitPromise = null;
+            }
+            return;
+        }
         this.mcpInitPromise = this.performMCPInitializationOnce();
         try {
             await this.mcpInitPromise;
@@ -2247,30 +2243,6 @@ Current user's request: ${currentInput}`;
                     }
                     // Set session and user IDs from context for Langfuse spans and execute with proper async scoping
                     return await this.setLangfuseContextFromOptions(options, async () => {
-                        if (this.conversationMemoryConfig?.conversationMemory
-                            ?.mem0Enabled &&
-                            options.context?.userId) {
-                            try {
-                                const mem0 = await this.ensureMem0Ready();
-                                if (!mem0) {
-                                    logger.debug("Mem0 not available, continuing without memory retrieval");
-                                }
-                                else {
-                                    const memories = await mem0.search(options.input.text, {
-                                        user_id: options.context.userId,
-                                        limit: 5,
-                                    });
-                                    if (memories && memories.length > 0) {
-                                        // Enhance the input with memory context
-                                        const memoryContext = this.extractMemoryContext(memories);
-                                        options.input.text = this.formatMemoryContext(memoryContext, options.input.text);
-                                    }
-                                }
-                            }
-                            catch (error) {
-                                logger.warn("Mem0 memory retrieval failed:", error);
-                            }
-                        }
                         const startTime = Date.now();
                         // Apply orchestration if enabled and no specific provider/model requested
                         if (this.enableOrchestration &&
@@ -2485,7 +2457,7 @@ Current user's request: ${currentInput}`;
                             generateResult.analytics.cost > 0) {
                             this._sessionCostUsd += generateResult.analytics.cost;
                         }
-                        this.scheduleGenerateMem0Storage(options, originalPrompt, generateResult);
+                        this.scheduleGenerateMemoryStorage(options, originalPrompt, generateResult);
                         // Set completion span attributes
                         generateSpan.setAttribute("neurolink.output_length", generateResult.content?.length || 0);
                         generateSpan.setAttribute("neurolink.tokens.input", generateResult.usage?.input || 0);
@@ -2535,27 +2507,9 @@ Current user's request: ${currentInput}`;
         });
     }
     /**
-     * Schedule non-blocking Mem0 memory storage after generate completes.
+     * Schedule non-blocking memory storage after generate completes.
      */
-    scheduleGenerateMem0Storage(options, originalPrompt, generateResult) {
-        if (this.conversationMemoryConfig?.conversationMemory?.mem0Enabled &&
-            options.context?.userId &&
-            generateResult.content.trim()) {
-            setImmediate(async () => {
-                try {
-                    const mem0 = await this.ensureMem0Ready();
-                    if (mem0) {
-                        await this.storeMem0ConversationTurn(mem0, originalPrompt ?? "", generateResult.content.trim(), options.context?.userId, {
-                            timestamp: new Date().toISOString(),
-                            type: "conversation_turn_generate",
-                        });
-                    }
-                }
-                catch (error) {
-                    logger.warn("Mem0 memory storage failed:", error);
-                }
-            });
-        }
+    scheduleGenerateMemoryStorage(options, originalPrompt, generateResult) {
         // Memory storage
         if (this.conversationMemoryConfig?.conversationMemory?.memory?.enabled &&
             options.context?.userId &&
@@ -4095,7 +4049,7 @@ Current user's request: ${currentInput}`;
                 // Set session and user IDs from context for Langfuse spans and execute with proper async scoping
                 return await this.setLangfuseContextFromOptions(options, async () => {
                     try {
-                        // Prepare options: init memory, MCP, Mem0, orchestration, Ollama auto-disable, tool detection
+                        // Prepare options: init memory, MCP, orchestration, Ollama auto-disable, tool detection
                         const { enhancedOptions, factoryResult } = await this.prepareStreamOptions(options, streamId, startTime, hrTimeStart);
                         const { stream: mcpStream, provider: providerName, usage: streamUsage, model: streamModel, analytics: streamAnalytics, } = await this.createMCPStream(enhancedOptions);
                         // Update span with resolved provider name
@@ -4291,7 +4245,7 @@ Current user's request: ${currentInput}`;
         }); // end metricsTraceContextStorage.run
     }
     /**
-     * Prepare stream options: initialize memory, MCP, Mem0 retrieval, orchestration,
+     * Prepare stream options: initialize memory, MCP, retrieval, orchestration,
      * Ollama tool auto-disable, factory processing, and tool detection.
      */
     async prepareStreamOptions(options, streamId, startTime, hrTimeStart) {
@@ -4299,31 +4253,6 @@ Current user's request: ${currentInput}`;
         await this.initializeConversationMemoryForGeneration(streamId, startTime, hrTimeStart);
         // Initialize MCP
         await this.initializeMCP();
-        if (this.conversationMemoryConfig?.conversationMemory?.mem0Enabled &&
-            options.context?.userId) {
-            try {
-                const mem0 = await this.ensureMem0Ready();
-                if (!mem0) {
-                    // Continue without memories if mem0 is not available
-                    logger.debug("Mem0 not available, continuing without memory retrieval");
-                }
-                else {
-                    const memories = await mem0.search(options.input.text, {
-                        user_id: options.context.userId,
-                        limit: 5,
-                    });
-                    if (memories && memories.length > 0) {
-                        // Enhance the input with memory context
-                        const memoryContext = this.extractMemoryContext(memories);
-                        options.input.text = this.formatMemoryContext(memoryContext, options.input.text);
-                    }
-                }
-            }
-            catch (error) {
-                // Non-blocking: Log error but continue with streaming
-                logger.warn("Mem0 memory retrieval failed:", error);
-            }
-        }
         // Memory retrieval
         if (this.conversationMemoryConfig?.conversationMemory?.memory?.enabled &&
             options.context?.userId) {
@@ -4538,11 +4467,16 @@ Current user's request: ${currentInput}`;
                     disableToolCache: enhancedOptions.disableToolCache,
                 }),
             }, "NeuroLink.fallbackStream");
-            // Get conversation messages for context (same as primary stream)
-            const conversationMessages = await getConversationMessages(this.conversationMemory, {
-                prompt: enhancedOptions.input.text,
-                context: enhancedOptions.context,
-            });
+            // Prefer the caller-supplied / compacted conversation messages that were
+            // threaded through options.  Only fall back to memory when no explicit
+            // history was provided — this preserves caller-supplied empty arrays
+            // (which signal "no prior context") and avoids resurrecting stale memory.
+            const conversationMessages = enhancedOptions.conversationMessages !== undefined
+                ? enhancedOptions.conversationMessages
+                : await getConversationMessages(this.conversationMemory, {
+                    prompt: enhancedOptions.input.text,
+                    context: enhancedOptions.context,
+                });
             const fallbackResult = await fallbackProvider.stream({
                 ...enhancedOptions,
                 model: fallbackRoute.model,
@@ -4581,7 +4515,7 @@ Current user's request: ${currentInput}`;
     }
     /**
      * Store conversation memory after stream consumption is complete (called from finally block).
-     * Handles both conversation memory storage and Mem0 background storage.
+     * Handles conversation memory storage in the background.
      */
     async storeStreamConversationMemory(params) {
         const { enhancedOptions, providerName, originalPrompt, accumulatedContent, startTime, eventSequence, } = params;
@@ -4635,24 +4569,6 @@ Current user's request: ${currentInput}`;
                 });
             }
         }
-        if (this.conversationMemoryConfig?.conversationMemory?.mem0Enabled &&
-            enhancedOptions.context?.userId &&
-            accumulatedContent.trim()) {
-            setImmediate(async () => {
-                try {
-                    const mem0 = await this.ensureMem0Ready();
-                    if (mem0) {
-                        await this.storeMem0ConversationTurn(mem0, originalPrompt ?? "", accumulatedContent.trim(), enhancedOptions.context?.userId, {
-                            timestamp: new Date().toISOString(),
-                            type: "conversation_turn_stream",
-                        });
-                    }
-                }
-                catch (error) {
-                    logger.warn("Mem0 memory storage failed:", error);
-                }
-            });
-        }
         if (this.conversationMemoryConfig?.conversationMemory?.memory?.enabled &&
             enhancedOptions.context?.userId &&
             accumulatedContent?.trim()) {
@@ -4717,12 +4633,24 @@ Current user's request: ${currentInput}`;
         const enhancedSystemPrompt = options.skipToolPromptInjection
             ? options.systemPrompt || ""
             : this.createToolAwareSystemPrompt(options.systemPrompt, availableTools);
-        // Get conversation messages for context
-        let conversationMessages = await getConversationMessages(this.conversationMemory, {
-            ...options,
-            prompt: options.input.text,
-            context: options.context,
-        });
+        // Get conversation messages for context.
+        // If the caller already supplied conversationMessages (e.g. proxy routes
+        // forwarding a multi-turn Claude request), honour them — including an
+        // explicit empty array, which signals "no prior context". Otherwise fall
+        // back to the conversation memory store (interactive CLI / SDK sessions).
+        const hasCallerConversationHistory = options.conversationMessages !== undefined;
+        const resolvedConversationMessages = hasCallerConversationHistory
+            ? options.conversationMessages
+            : await getConversationMessages(this.conversationMemory, {
+                ...options,
+                prompt: options.input.text,
+                context: options.context,
+            });
+        // Make the resolved messages the single source of truth so downstream
+        // consumers (compaction, fallback streams) reuse them instead of
+        // reloading from conversationMemory.
+        options.conversationMessages = resolvedConversationMessages;
+        let conversationMessages = resolvedConversationMessages;
         // Pre-generation budget check for streaming
         const streamBudget = checkContextBudget({
             provider: providerName,
@@ -4736,7 +4664,7 @@ Current user's request: ${currentInput}`;
         const streamMessageCount = conversationMessages?.length || 0;
         const streamCompactionSessionId = this.getCompactionSessionId(options);
         if (streamBudget.shouldCompact &&
-            this.conversationMemory &&
+            (hasCallerConversationHistory || this.conversationMemory) &&
             streamMessageCount >
                 (this.lastCompactionMessageCount.get(streamCompactionSessionId) ?? 0)) {
             const compactor = new ContextCompactor({
@@ -4749,6 +4677,10 @@ Current user's request: ${currentInput}`;
             if (compactionResult.compacted) {
                 const repairedResult = repairToolPairs(compactionResult.messages);
                 conversationMessages = repairedResult.messages;
+                // Keep options.conversationMessages in sync so downstream consumers
+                // (e.g. handleStreamFallback) use the compacted history rather than
+                // re-reading from conversationMemory.
+                options.conversationMessages = conversationMessages;
                 this.lastCompactionMessageCount.set(streamCompactionSessionId, conversationMessages.length);
             }
             // POST-COMPACTION BUDGET RE-CHECK (mirrors tryMCPGeneration / directProviderGeneration)
@@ -4768,6 +4700,9 @@ Current user's request: ${currentInput}`;
                     overagePercent: Math.round((postCompactBudget.usageRatio - 1.0) * 100),
                 });
                 conversationMessages = emergencyContentTruncation(conversationMessages, postCompactBudget.availableInputTokens, postCompactBudget.breakdown, providerName);
+                // Keep options in sync after emergency truncation so fallback paths
+                // use the truncated history.
+                options.conversationMessages = conversationMessages;
                 const finalBudget = checkContextBudget({
                     provider: providerName,
                     model: options.model,
@@ -5291,7 +5226,7 @@ Current user's request: ${currentInput}`;
      * @param name - Unique name for the tool
      * @param tool - Tool in MCPExecutableTool format (unified MCP protocol type)
      */
-    registerTool(name, tool) {
+    registerTool(name, tool, options) {
         this.invalidateToolCache(); // Invalidate cache when a tool is registered
         // Emit tool registration start event
         this.emitter.emit("tools-register:start", {
@@ -5340,8 +5275,46 @@ Current user's request: ${currentInput}`;
                     return fallbackSchema;
                 })(),
             };
+            // Wrap execute with per-tool timeout if specified at registration.
+            // Uses AbortSignal.timeout() composed with any parent signal from the AI SDK.
+            // This ensures the timeout works regardless of the execution path
+            // (direct executeTool() or AI SDK generateText() tool calling).
+            if (options?.timeout !== undefined &&
+                options.timeout > 0 &&
+                Number.isFinite(options.timeout)) {
+                const originalExecute = convertedTool.execute;
+                const toolTimeout = options.timeout;
+                const toolName = name;
+                convertedTool.execute = async (...args) => {
+                    const timeoutSignal = AbortSignal.timeout(toolTimeout);
+                    // Compose with any parent abortSignal from ToolExecutionOptions
+                    const execOptions = args[1];
+                    const parentSignal = execOptions?.abortSignal;
+                    const composedSignal = parentSignal
+                        ? AbortSignal.any([parentSignal, timeoutSignal])
+                        : timeoutSignal;
+                    // Replace the abortSignal in execution options
+                    const augmentedContext = {
+                        ...execOptions,
+                        abortSignal: composedSignal,
+                    };
+                    return Promise.race([
+                        originalExecute(args[0], augmentedContext),
+                        new Promise((_, reject) => {
+                            composedSignal.addEventListener("abort", () => {
+                                if (timeoutSignal.aborted) {
+                                    reject(new Error(`Tool '${toolName}' timed out after ${toolTimeout}ms (configured at registration)`));
+                                }
+                                else {
+                                    reject(new DOMException("The operation was aborted", "AbortError"));
+                                }
+                            }, { once: true });
+                        }),
+                    ]);
+                };
+            }
             // SMART DEFAULTS: Use utility to eliminate boilerplate creation
-            const mcpServerInfo = createCustomToolServerInfo(name, convertedTool);
+            const mcpServerInfo = createCustomToolServerInfo(name, convertedTool, options?.timeout, options?.maxRetries);
             // Register with toolRegistry using MCPServerInfo directly
             this.toolRegistry.registerServer(mcpServerInfo);
             // Emit tool registration success event
@@ -5349,6 +5322,7 @@ Current user's request: ${currentInput}`;
                 toolName: name,
                 success: true,
                 timestamp: Date.now(),
+                timeoutMs: options?.timeout,
             });
         }
         catch (error) {
@@ -5520,7 +5494,11 @@ Current user's request: ${currentInput}`;
             toolMap.set(tool.name, {
                 name: tool.name,
                 description: tool.description || "",
-                inputSchema: tool.inputSchema || tool.parameters || {},
+                inputSchema: typeof tool.inputSchema === "object" && tool.inputSchema !== null
+                    ? tool.inputSchema
+                    : typeof tool.parameters === "object" && tool.parameters !== null
+                        ? tool.parameters
+                        : {},
                 execute: async (params, context) => {
                     // CONTEXT MERGING: Combine all available contexts for maximum information
                     const storedContext = this.toolExecutionContext || {};
@@ -5567,12 +5545,14 @@ Current user's request: ${currentInput}`;
         const fileTools = this.cachedFileTools;
         for (const [toolName, toolDef] of Object.entries(fileTools)) {
             if (!toolMap.has(toolName)) {
-                // eslint-disable-next-line @typescript-eslint/no-explicit-any
-                const toolParams = toolDef.parameters;
+                const toolDefRecord = toolDef;
+                const toolParams = toolDefRecord.inputSchema ?? toolDefRecord.parameters;
                 toolMap.set(toolName, {
                     name: toolName,
                     description: toolDef.description || `File tool: ${toolName}`,
-                    inputSchema: toolParams ?? { type: "object", properties: {} },
+                    inputSchema: typeof toolParams === "object" && toolParams !== null
+                        ? toolParams
+                        : { type: "object", properties: {} },
                     execute: async (params) => {
                         return await toolDef.execute(params, {
                             toolCallId: `file-tool-${Date.now()}`,
@@ -5671,6 +5651,12 @@ Current user's request: ${currentInput}`;
         const functionTag = "NeuroLink.executeTool";
         const executionStartTime = Date.now();
         // === MCP ENHANCEMENT: RequestBatcher — batch programmatic tool calls ===
+        // LIMITATION: When the request batcher is enabled, per-tool timeout and retry
+        // settings (from registration options or call-site options) are NOT applied.
+        // The batcher uses its own hardcoded defaults for timeout and retry behavior.
+        // Use `bypassBatcher: true` to ensure per-tool timeout/retry is respected.
+        // Additionally, note that executeToolInternal's safe-tool retry logic may still
+        // trigger even when maxRetries is set to 0, since it operates independently.
         if (this.mcpToolBatcher && !options?.bypassBatcher) {
             return this.mcpToolBatcher.execute(toolName, params);
         }
@@ -5735,19 +5721,27 @@ Current user's request: ${currentInput}`;
                     timestamp: executionStartTime,
                     input: params, // Enhanced: add input parameters
                 });
-                // Set default options
+                // NL-004: Use composite key (serverId.toolName) to avoid cross-server collisions
+                // Fetch toolInfo early so per-tool timeout is available for finalOptions
+                const toolInfo = this.toolRegistry.getToolInfo(toolName);
+                // Set default options — per-tool values from registration take precedence over global defaults.
+                // When not explicitly set at registration, global defaults are preserved for backward compatibility.
+                const registeredTimeout = toolInfo?.tool?.timeoutMs;
+                const registeredMaxRetries = toolInfo?.tool?.maxRetries;
                 const finalOptions = {
-                    timeout: options?.timeout || TOOL_TIMEOUTS.EXECUTION_DEFAULT_MS, // 30 second default timeout
-                    maxRetries: options?.maxRetries || RETRY_ATTEMPTS.DEFAULT, // Default 2 retries for retriable errors
-                    retryDelayMs: options?.retryDelayMs || RETRY_DELAYS.BASE_MS, // 1 second delay between retries
-                    authContext: options?.authContext, // Pass through authentication context
-                    disableToolCache: options?.disableToolCache, // Pass through cache bypass flag
+                    timeout: options?.timeout ??
+                        registeredTimeout ??
+                        TOOL_TIMEOUTS.EXECUTION_DEFAULT_MS,
+                    maxRetries: options?.maxRetries ??
+                        registeredMaxRetries ??
+                        RETRY_ATTEMPTS.DEFAULT,
+                    retryDelayMs: options?.retryDelayMs || RETRY_DELAYS.BASE_MS,
+                    authContext: options?.authContext,
+                    disableToolCache: options?.disableToolCache,
                 };
                 // 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
@@ -5763,6 +5757,7 @@ Current user's request: ${currentInput}`;
                         failedExecutions: 0,
                         averageExecutionTime: 0,
                         lastExecutionTime: 0,
+                        errorCategories: {},
                     });
                 }
                 const metrics = this.toolExecutionMetrics.get(toolName);
@@ -5823,14 +5818,18 @@ Current user's request: ${currentInput}`;
                         memoryDelta,
                         circuitBreakerState: circuitBreaker?.getState(),
                     });
-                    // Emit tool end event using the helper method
-                    this.emitToolEndEvent(toolName, executionStartTime, true, result);
                     // Set span success attributes
                     // Check if result has isError flag (MCP tool error result)
-                    const isToolError = result &&
-                        typeof result === "object" &&
-                        "isError" in result &&
-                        result.isError === true;
+                    // Also detect toolRegistry-wrapped errors that return { success: false }
+                    const resultObj = result && typeof result === "object"
+                        ? result
+                        : undefined;
+                    const isToolError = (resultObj &&
+                        "isError" in resultObj &&
+                        resultObj.isError === true) ||
+                        (resultObj &&
+                            "success" in resultObj &&
+                            resultObj.success === false);
                     // 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
@@ -5885,7 +5884,29 @@ Current user's request: ${currentInput}`;
                             code: SpanStatusCode.ERROR,
                             message: `MCP tool returned isError: ${errorText.substring(0, 200)}`,
                         });
+                        if (metrics) {
+                            metrics.failedExecutions++;
+                            const prevSuccessful = metrics.successfulExecutions;
+                            metrics.successfulExecutions = Math.max(0, metrics.successfulExecutions - 1);
+                            // Recompute averageExecutionTime: back out this execution's duration
+                            // which was incorrectly included as a success
+                            if (prevSuccessful > 1) {
+                                metrics.averageExecutionTime =
+                                    (metrics.averageExecutionTime * prevSuccessful -
+                                        executionTime) /
+                                        (prevSuccessful - 1);
+                            }
+                            else {
+                                // No remaining successful executions, reset to 0
+                                metrics.averageExecutionTime = 0;
+                            }
+                            const mappedCategory = mcpCategoryToErrorCategory(errorCategory);
+                            metrics.errorCategories[mappedCategory] =
+                                (metrics.errorCategories[mappedCategory] || 0) + 1;
+                        }
                     }
+                    // Emit tool end event AFTER isError check so success flag is correct
+                    this.emitToolEndEvent(toolName, executionStartTime, !isToolError, result);
                     toolSpan.setAttribute("tool.result.status", isToolError ? "error" : "success");
                     toolSpan.setAttribute("tool.duration_ms", executionTime);
                     return result;
@@ -5896,6 +5917,51 @@ Current user's request: ${currentInput}`;
                         metrics.failedExecutions++;
                     }
                     const executionTime = Date.now() - executionStartTime;
+                    // Circuit breaker open: return a structured non-retryable isError result
+                    // so the AI model understands the tool is temporarily unavailable.
+                    // Log at warn (not error) since this is expected circuit breaker behavior.
+                    if (error instanceof CircuitBreakerOpenError) {
+                        mcpLogger.warn(`[${functionTag}] Tool blocked by circuit breaker: ${toolName}`, {
+                            toolName,
+                            breakerState: error.breakerState,
+                            retryAfter: error.retryAfter,
+                            retryAfterMs: error.retryAfterMs,
+                            failureCount: error.failureCount,
+                            executionTime,
+                        });
+                        if (metrics) {
+                            const category = ErrorCategory.EXECUTION;
+                            metrics.errorCategories[category] =
+                                (metrics.errorCategories[category] || 0) + 1;
+                        }
+                        // Emit tool end event for circuit breaker open
+                        this.emitToolEndEvent(toolName, executionStartTime, false, undefined);
+                        toolSpan.setAttribute("tool.result.status", "circuit_breaker_open");
+                        toolSpan.setAttribute("tool.duration_ms", executionTime);
+                        toolSpan.setAttribute("tool.circuit_breaker.state", error.breakerState);
+                        toolSpan.setAttribute("tool.circuit_breaker.retry_after_ms", error.retryAfterMs);
+                        toolSpan.setAttribute("tool.circuit_breaker.failure_count", error.failureCount);
+                        toolSpan.setStatus({
+                            code: SpanStatusCode.ERROR,
+                            message: `Circuit breaker open for ${toolName}: ${error.message}`,
+                        });
+                        // Return an isError tool result so the AI can inform the user
+                        // instead of throwing, which would cause a generic retry
+                        return {
+                            isError: true,
+                            content: [
+                                {
+                                    type: "text",
+                                    text: `TOOL TEMPORARILY UNAVAILABLE: "${toolName}" has been disabled after ` +
+                                        `${error.failureCount} failures. ` +
+                                        `This is a circuit breaker protection — do NOT retry this tool. ` +
+                                        `It will become available again after ${Math.ceil(error.retryAfterMs / 1000)} seconds ` +
+                                        `(at ${error.retryAfter}). ` +
+                                        `Instead, inform the user that the operation failed and suggest trying again later.`,
+                                },
+                            ],
+                        };
+                    }
                     // Create structured error
                     let structuredError;
                     if (error instanceof NeuroLinkError) {
@@ -5925,10 +5991,17 @@ Current user's request: ${currentInput}`;
                     else {
                         structuredError = ErrorFactory.toolExecutionFailed(toolName, new Error(String(error)));
                     }
-                    // ADD: Centralized error event emission
-                    this.emitter.emit("error", structuredError);
-                    // Emit tool end event using the helper method
+                    if (metrics) {
+                        const category = structuredError.category || ErrorCategory.EXECUTION;
+                        metrics.errorCategories[category] =
+                            (metrics.errorCategories[category] || 0) + 1;
+                    }
+                    // Emit tool end event BEFORE the error event.
+                    // Node.js EventEmitter throws on unhandled 'error' events,
+                    // which would prevent tool:end from being emitted.
                     this.emitToolEndEvent(toolName, executionStartTime, false, undefined, structuredError);
+                    // Centralized error event emission
+                    this.emitter.emit("error", structuredError);
                     // Add execution context to structured error
                     structuredError = new NeuroLinkError({
                         ...structuredError,
@@ -6742,6 +6815,7 @@ Current user's request: ${currentInput}`;
         for (const [toolName, toolMetrics] of this.toolExecutionMetrics.entries()) {
             metrics[toolName] = {
                 ...toolMetrics,
+                errorCategories: { ...toolMetrics.errorCategories },
                 successRate: toolMetrics.totalExecutions > 0
                     ? toolMetrics.successfulExecutions / toolMetrics.totalExecutions
                     : 0,
@@ -6836,6 +6910,21 @@ Current user's request: ${currentInput}`;
                 issues.push("High average execution time");
                 recommendations.push("Optimize tool performance or increase timeout");
             }
+            if (metrics && metrics.errorCategories) {
+                const categories = metrics.errorCategories;
+                if (categories[ErrorCategory.TIMEOUT] > 0) {
+                    issues.push(`Timeout errors: ${categories[ErrorCategory.TIMEOUT]}`);
+                    recommendations.push("Consider increasing the tool timeout configuration");
+                }
+                if (categories[ErrorCategory.VALIDATION] > 0) {
+                    issues.push(`Validation errors: ${categories[ErrorCategory.VALIDATION]}`);
+                    recommendations.push("Review input schemas and parameter validation");
+                }
+                if (categories[ErrorCategory.NETWORK] > 0) {
+                    issues.push(`Network errors: ${categories[ErrorCategory.NETWORK]}`);
+                    recommendations.push("Check network connectivity and endpoint availability");
+                }
+            }
             tools[toolName] = {
                 name: toolName,
                 isHealthy,
@@ -6844,6 +6933,9 @@ Current user's request: ${currentInput}`;
                     successRate,
                     averageExecutionTime: metrics?.averageExecutionTime || 0,
                     lastExecutionTime: metrics?.lastExecutionTime || 0,
+                    errorCategories: metrics?.errorCategories
+                        ? { ...metrics.errorCategories }
+                        : {},
                 },
                 circuitBreaker: {
                     state: circuitBreaker?.getState() || "closed",