@juspay/neurolink 9.15.0 → 9.17.0

package/dist/lib/mcp/toolRegistry.js

@@ -10,6 +10,7 @@ import { directAgentTools } from "../agent/directTools.js";
 import { detectCategory, createMCPServerInfo } from "../utils/mcpDefaults.js";
 import { FlexibleToolValidator } from "./flexibleToolValidator.js";
 import { HITLUserRejectedError, HITLTimeoutError } from "../hitl/hitlErrors.js";
+import { withSpan, tracers, ATTR } from "../telemetry/index.js";
 export class MCPToolRegistry extends MCPRegistry {
     tools = new Map();
     toolImplementations = new Map(); // Store actual tool implementations
@@ -227,149 +228,218 @@ export class MCPToolRegistry extends MCPRegistry {
      */
     async executeTool(toolName, args, context) {
         const startTime = Date.now();
-        try {
-            registryLogger.info(`🔧 [TOOL_EXECUTION] Starting execution: ${toolName}`, { args, context });
-            // Try to find the tool by fully-qualified name first
-            let tool = this.tools.get(toolName);
-            registryLogger.info(`🔍 [TOOL_LOOKUP] Direct lookup result for '${toolName}':`, !!tool);
-            // If not found, search for tool by name across all entries (for backward compatibility)
-            let toolId = toolName;
-            if (!tool) {
-                for (const [candidateToolId, toolInfo] of this.tools.entries()) {
-                    if (toolInfo.name === toolName) {
+        // Resolve serverId eagerly for span attributes
+        let preResolvedServerId;
+        const toolEntry = this.tools.get(toolName);
+        if (toolEntry) {
+            preResolvedServerId = toolEntry.serverId;
+        }
+        else {
+            for (const toolInfo of this.tools.values()) {
+                if (toolInfo.name === toolName) {
+                    preResolvedServerId = toolInfo.serverId;
+                    break;
+                }
+            }
+        }
+        return withSpan({
+            name: "neurolink.tool.execute",
+            tracer: tracers.mcp,
+            attributes: {
+                [ATTR.GEN_AI_TOOL_NAME]: toolName,
+                [ATTR.MCP_SERVER_ID]: preResolvedServerId || "builtin",
+            },
+        }, async (span) => {
+            try {
+                registryLogger.info(`🔧 [TOOL_EXECUTION] Starting execution: ${toolName}`, {
+                    hasArgs: args !== undefined,
+                    hasContext: context !== undefined,
+                    sessionId: context?.sessionId,
+                });
+                // Try to find the tool by fully-qualified name first
+                let tool = this.tools.get(toolName);
+                registryLogger.info(`🔍 [TOOL_LOOKUP] Direct lookup result for '${toolName}':`, !!tool);
+                // If not found, search for tool by name across all entries (for backward compatibility)
+                let toolId = toolName;
+                if (!tool) {
+                    const matches = Array.from(this.tools.entries()).filter(([, toolInfo]) => toolInfo.name === toolName);
+                    if (matches.length > 1) {
+                        throw new Error(`Ambiguous tool name '${toolName}'. Use fully-qualified name 'serverId.${toolName}'.`);
+                    }
+                    if (matches.length === 1) {
+                        const [candidateToolId, toolInfo] = matches[0];
                         tool = toolInfo;
                         toolId = candidateToolId;
-                        break;
                     }
                 }
-            }
-            if (!tool) {
-                throw new Error(`Tool '${toolName}' not found in registry`);
-            }
-            // Create execution context if not provided
-            const execContext = {
-                sessionId: context?.sessionId || randomUUID(),
-                userId: context?.userId,
-                ...context,
-            };
-            // Get the tool implementation using the resolved toolId
-            const toolImpl = this.toolImplementations.get(toolId);
-            registryLogger.debug(`Looking for tool '${toolName}' (toolId: '${toolId}'), found: ${!!toolImpl}, type: ${typeof toolImpl?.execute}`);
-            registryLogger.debug(`Available tools:`, Array.from(this.toolImplementations.keys()));
-            if (!toolImpl || typeof toolImpl?.execute !== "function") {
-                throw new Error(`Tool '${toolName}' implementation not found or not executable`);
-            }
-            // HITL Safety Check: Request confirmation if required
-            let finalArgs = args;
-            if (this.hitlManager && this.hitlManager.isEnabled()) {
-                const requiresConfirmation = this.hitlManager.requiresConfirmation(toolName, args);
-                if (requiresConfirmation) {
-                    registryLogger.info(`Tool '${toolName}' requires HITL confirmation`);
-                    try {
-                        const confirmationResult = await this.hitlManager.requestConfirmation(toolName, args, {
-                            serverId: tool.serverId,
-                            sessionId: execContext.sessionId,
-                            userId: execContext.userId,
-                        });
-                        if (!confirmationResult.approved) {
-                            // User rejected the tool execution
-                            throw new HITLUserRejectedError(`Tool execution rejected by user: ${confirmationResult.reason || "No reason provided"}`, toolName, confirmationResult.reason);
+                if (!tool) {
+                    throw new Error(`Tool '${toolName}' not found in registry`);
+                }
+                // Classify tool type for observability
+                const serverId = tool.serverId || "unknown";
+                const toolType = serverId === "direct"
+                    ? "builtin"
+                    : serverId.startsWith("custom-tool-")
+                        ? "custom"
+                        : "mcp";
+                span.setAttribute("tool.type", toolType);
+                span.setAttribute(ATTR.MCP_SERVER_ID, serverId);
+                // Create execution context if not provided
+                const execContext = {
+                    ...context,
+                    sessionId: context?.sessionId ?? randomUUID(),
+                    userId: context?.userId,
+                };
+                // Get the tool implementation using the resolved toolId
+                const toolImpl = this.toolImplementations.get(toolId);
+                registryLogger.debug(`Looking for tool '${toolName}' (toolId: '${toolId}'), found: ${!!toolImpl}, type: ${typeof toolImpl?.execute}`);
+                registryLogger.debug(`Available tools:`, Array.from(this.toolImplementations.keys()));
+                if (!toolImpl || typeof toolImpl?.execute !== "function") {
+                    throw new Error(`Tool '${toolName}' implementation not found or not executable`);
+                }
+                // Capture argument metadata (avoid logging raw values which may contain secrets)
+                let argsStr;
+                try {
+                    argsStr = JSON.stringify(args).slice(0, 4096);
+                }
+                catch {
+                    argsStr = "[unserializable]";
+                }
+                span.setAttribute("tool.arguments_present", args !== undefined);
+                span.setAttribute("tool.arguments_size", argsStr.length);
+                // HITL Safety Check: Request confirmation if required
+                let finalArgs = args;
+                if (this.hitlManager && this.hitlManager.isEnabled()) {
+                    const requiresConfirmation = this.hitlManager.requiresConfirmation(toolName, args);
+                    if (requiresConfirmation) {
+                        registryLogger.info(`Tool '${toolName}' requires HITL confirmation`);
+                        span.addEvent("tool.hitl_requested");
+                        try {
+                            const confirmationResult = await this.hitlManager.requestConfirmation(toolName, args, {
+                                serverId: tool.serverId,
+                                sessionId: execContext.sessionId,
+                                userId: execContext.userId,
+                            });
+                            if (!confirmationResult.approved) {
+                                // User rejected the tool execution
+                                span.addEvent("tool.hitl_rejected");
+                                throw new HITLUserRejectedError(`Tool execution rejected by user: ${confirmationResult.reason || "No reason provided"}`, toolName, confirmationResult.reason);
+                            }
+                            span.addEvent("tool.hitl_approved");
+                            // User approved - use modified arguments if provided
+                            if (confirmationResult.modifiedArguments !== undefined) {
+                                finalArgs = confirmationResult.modifiedArguments;
+                                registryLogger.info(`Tool '${toolName}' arguments modified by user`);
+                            }
+                            registryLogger.info(`Tool '${toolName}' approved for execution (response time: ${confirmationResult.responseTime}ms)`);
                         }
-                        // User approved - use modified arguments if provided
-                        if (confirmationResult.modifiedArguments !== undefined) {
-                            finalArgs = confirmationResult.modifiedArguments;
-                            registryLogger.info(`Tool '${toolName}' arguments modified by user`);
+                        catch (error) {
+                            if (error instanceof HITLTimeoutError) {
+                                // Timeout occurred - user didn't respond in time
+                                registryLogger.warn(`Tool '${toolName}' execution timed out waiting for user confirmation`);
+                                throw error;
+                            }
+                            else if (error instanceof HITLUserRejectedError) {
+                                // User explicitly rejected
+                                registryLogger.info(`Tool '${toolName}' execution rejected by user`);
+                                throw error;
+                            }
+                            else {
+                                // Other HITL error (configuration, system error, etc.)
+                                registryLogger.error(`HITL confirmation failed for tool '${toolName}':`, error);
+                                throw new Error(`HITL confirmation failed: ${error instanceof Error ? error.message : String(error)}`);
+                            }
                         }
-                        registryLogger.info(`Tool '${toolName}' approved for execution (response time: ${confirmationResult.responseTime}ms)`);
                     }
-                    catch (error) {
-                        if (error instanceof HITLTimeoutError) {
-                            // Timeout occurred - user didn't respond in time
-                            registryLogger.warn(`Tool '${toolName}' execution timed out waiting for user confirmation`);
-                            throw error;
-                        }
-                        else if (error instanceof HITLUserRejectedError) {
-                            // User explicitly rejected
-                            registryLogger.info(`Tool '${toolName}' execution rejected by user`);
-                            throw error;
-                        }
-                        else {
-                            // Other HITL error (configuration, system error, etc.)
-                            registryLogger.error(`HITL confirmation failed for tool '${toolName}':`, error);
-                            throw new Error(`HITL confirmation failed: ${error instanceof Error ? error.message : String(error)}`);
-                        }
+                    else {
+                        registryLogger.debug(`Tool '${toolName}' does not require HITL confirmation`);
                     }
                 }
+                // Execute the actual tool (with potentially modified arguments)
+                registryLogger.debug(`Executing tool '${toolName}' with args:`, finalArgs);
+                const toolResult = await toolImpl.execute(finalArgs, execContext);
+                // Properly wrap raw results in ToolResult format
+                let result;
+                // Check if result is already a ToolResult object
+                if (toolResult &&
+                    typeof toolResult === "object" &&
+                    "success" in toolResult &&
+                    typeof toolResult.success === "boolean") {
+                    // Result is already a ToolResult, enhance with metadata
+                    const toolResultObj = toolResult;
+                    result = {
+                        ...toolResultObj,
+                        usage: {
+                            ...(toolResultObj.usage || {}),
+                            executionTime: Date.now() - startTime,
+                        },
+                        metadata: {
+                            ...(toolResultObj.metadata || {}),
+                            toolName,
+                            serverId: tool.serverId,
+                            sessionId: execContext.sessionId,
+                            executionTime: Date.now() - startTime,
+                        },
+                    };
+                }
                 else {
-                    registryLogger.debug(`Tool '${toolName}' does not require HITL confirmation`);
+                    // Result is a raw value, wrap it in ToolResult format
+                    result = {
+                        success: true,
+                        data: toolResult,
+                        usage: {
+                            executionTime: Date.now() - startTime,
+                        },
+                        metadata: {
+                            toolName,
+                            serverId: tool.serverId,
+                            sessionId: execContext.sessionId,
+                            executionTime: Date.now() - startTime,
+                        },
+                    };
                 }
+                // Update statistics
+                const duration = Date.now() - startTime;
+                this.updateStats(toolName, duration);
+                // Record success on span
+                let resultStr;
+                try {
+                    resultStr = JSON.stringify(result.data);
+                }
+                catch {
+                    resultStr = "[unserializable]";
+                }
+                span.setAttribute("tool.result_length", resultStr.length);
+                span.setAttribute("tool.success", true);
+                registryLogger.debug(`Tool '${toolName}' executed successfully in ${duration}ms`);
+                return result;
             }
-            // Execute the actual tool (with potentially modified arguments)
-            registryLogger.debug(`Executing tool '${toolName}' with args:`, finalArgs);
-            const toolResult = await toolImpl.execute(finalArgs, execContext);
-            // Properly wrap raw results in ToolResult format
-            let result;
-            // Check if result is already a ToolResult object
-            if (toolResult &&
-                typeof toolResult === "object" &&
-                "success" in toolResult &&
-                typeof toolResult.success === "boolean") {
-                // Result is already a ToolResult, enhance with metadata
-                const toolResultObj = toolResult;
-                result = {
-                    ...toolResultObj,
-                    usage: {
-                        ...(toolResultObj.usage || {}),
-                        executionTime: Date.now() - startTime,
-                    },
-                    metadata: {
-                        ...(toolResultObj.metadata || {}),
-                        toolName,
-                        serverId: tool.serverId,
-                        sessionId: execContext.sessionId,
-                        executionTime: Date.now() - startTime,
-                    },
-                };
-            }
-            else {
-                // Result is a raw value, wrap it in ToolResult format
-                result = {
-                    success: true,
-                    data: toolResult,
+            catch (error) {
+                registryLogger.error(`Tool execution failed: ${toolName}`, error);
+                // Record failure on span
+                span.setAttribute("tool.success", false);
+                // Rethrow precondition errors (tool not found, not executable)
+                const errMsg = error instanceof Error ? error.message : String(error);
+                if (errMsg.includes("not found in registry") ||
+                    errMsg.includes("not executable")) {
+                    throw error;
+                }
+                // Return runtime execution errors in ToolResult format
+                const errorResult = {
+                    success: false,
+                    data: null,
+                    error: error instanceof Error ? error.message : String(error),
                     usage: {
                         executionTime: Date.now() - startTime,
                     },
                     metadata: {
                         toolName,
-                        serverId: tool.serverId,
-                        sessionId: execContext.sessionId,
-                        executionTime: Date.now() - startTime,
+                        sessionId: context?.sessionId,
                     },
                 };
+                return errorResult;
             }
-            // Update statistics
-            const duration = Date.now() - startTime;
-            this.updateStats(toolName, duration);
-            registryLogger.debug(`Tool '${toolName}' executed successfully in ${duration}ms`);
-            return result;
-        }
-        catch (error) {
-            registryLogger.error(`Tool execution failed: ${toolName}`, error);
-            // Return error in ToolResult format
-            const errorResult = {
-                success: false,
-                data: null,
-                error: error instanceof Error ? error.message : String(error),
-                usage: {
-                    executionTime: Date.now() - startTime,
-                },
-                metadata: {
-                    toolName,
-                    sessionId: context?.sessionId,
-                },
-            };
-            return errorResult;
-        }
+        });
     }
     async listTools(filterOrContext) {
         // FIXED: Return unique tools (avoid duplicates from dual registration)

package/dist/lib/neurolink.d.ts

@@ -95,6 +95,7 @@ import type { BatchOperationResult } from "./types/typeAliases.js";
  */
 export declare class NeuroLink {
     private mcpInitialized;
+    private mcpInitPromise;
     private emitter;
     private toolRegistry;
     private autoDiscoveredServerInfos;
@@ -270,6 +271,11 @@ export declare class NeuroLink {
      * Uses isolated async context to prevent hanging
      */
     private initializeMCP;
+    /**
+     * Actual one-shot MCP initialization logic. Called at most once per
+     * NeuroLink instance lifetime (unless cleanup() resets the flag).
+     */
+    private performMCPInitializationOnce;
     /**
      * Import performance manager with error handling
      */