@juspay/neurolink 9.15.0 → 9.16.0

package/dist/mcp/mcpCircuitBreaker.js

@@ -4,6 +4,7 @@
  * Provides fault tolerance and prevents cascading failures
  */
 import { EventEmitter } from "events";
+import { trace } from "@opentelemetry/api";
 import { mcpLogger } from "../utils/logger.js";
 /**
  * MCPCircuitBreaker
@@ -53,6 +54,17 @@ export class MCPCircuitBreaker extends EventEmitter {
                 this.halfOpenCalls >= this.config.halfOpenMaxCalls) {
                 throw new Error(`Circuit breaker '${this.name}' is half-open but call limit reached`);
             }
+            // NLK-GAP-009: Record half-open test event when executing in half-open state
+            if (this.state === "half-open") {
+                const activeSpan = trace.getActiveSpan();
+                if (activeSpan) {
+                    activeSpan.addEvent("circuit.half_open_test", {
+                        "circuit.name": this.name,
+                        "circuit.half_open_call": this.halfOpenCalls + 1,
+                        "circuit.half_open_max_calls": this.config.halfOpenMaxCalls,
+                    });
+                }
+            }
             // Execute operation with timeout
             const result = await Promise.race([
                 operation(),
@@ -145,6 +157,18 @@ export class MCPCircuitBreaker extends EventEmitter {
         const oldState = this.state;
         this.state = newState;
         this.lastStateChange = new Date();
+        // NLK-GAP-009: Record state transition on active OTel span
+        const activeSpan = trace.getActiveSpan();
+        if (activeSpan) {
+            activeSpan.addEvent("circuit.state_change", {
+                "circuit.name": this.name,
+                "circuit.from_state": oldState,
+                "circuit.to_state": newState,
+                "circuit.reason": reason.slice(0, 128),
+                "circuit.failure_count": this.callHistory.filter((c) => !c.success)
+                    .length,
+            });
+        }
         // Reset counters based on state
         if (newState === "half-open") {
             this.halfOpenCalls = 0;

package/dist/mcp/mcpClientFactory.js

@@ -15,6 +15,8 @@ import { globalCircuitBreakerManager } from "./mcpCircuitBreaker.js";
 import { withHTTPRetry, DEFAULT_HTTP_RETRY_CONFIG, } from "./httpRetryHandler.js";
 import { globalRateLimiterManager } from "./httpRateLimiter.js";
 import { NeuroLinkOAuthProvider, InMemoryTokenStorage } from "./auth/index.js";
+import { tracers } from "../telemetry/tracers.js";
+import { SpanStatusCode } from "@opentelemetry/api";
 /**
  * MCPClientFactory
  * Factory class for creating MCP clients with different transports
@@ -36,6 +38,13 @@ export class MCPClientFactory {
      */
     static async createClient(config, timeout = 10000) {
         const startTime = Date.now();
+        const span = tracers.mcp.startSpan("neurolink.mcp.client.create", {
+            attributes: {
+                "mcp.server_id": config.id,
+                "mcp.transport": config.transport,
+                "mcp.timeout_ms": timeout,
+            },
+        });
         try {
             mcpLogger.info(`[MCPClientFactory] Creating client for ${config.id}`, {
                 transport: config.transport,
@@ -94,6 +103,7 @@ export class MCPClientFactory {
                 duration: Date.now() - startTime,
                 capabilities: result.capabilities,
             });
+            span.setStatus({ code: SpanStatusCode.OK });
             return {
                 ...result,
                 success: true,
@@ -103,12 +113,18 @@ export class MCPClientFactory {
         catch (error) {
             const errorMessage = error instanceof Error ? error.message : String(error);
             mcpLogger.error(`[MCPClientFactory] Failed to create client for ${config.id}:`, error);
+            // NLK-GAP-004 fix: Record both exception AND error status on span
+            span.recordException(error instanceof Error ? error : new Error(errorMessage));
+            span.setStatus({ code: SpanStatusCode.ERROR, message: errorMessage });
             return {
                 success: false,
                 error: errorMessage,
                 duration: Date.now() - startTime,
             };
         }
+        finally {
+            span.end();
+        }
     }
     /**
      * Internal client creation logic

package/dist/mcp/toolDiscoveryService.js

@@ -8,6 +8,10 @@ import { mcpLogger } from "../utils/logger.js";
 import { globalCircuitBreakerManager } from "./mcpCircuitBreaker.js";
 import { isObject, isNullish } from "../utils/typeUtils.js";
 import { validateToolName, validateToolDescription, } from "../utils/parameterValidation.js";
+import { withTimeout } from "../utils/errorHandling.js";
+import { SpanKind, SpanStatusCode } from "@opentelemetry/api";
+import { tracers } from "../telemetry/tracers.js";
+const mcpTracer = tracers.mcp;
 /**
  * ToolDiscoveryService
  * Handles automatic tool discovery and registration from external MCP servers
@@ -336,13 +340,35 @@ export class ToolDiscoveryService extends EventEmitter {
             });
             // Execute tool with circuit breaker protection
             const result = await circuitBreaker.execute(async () => {
-                const timeout = options.timeout || 30000;
-                const executePromise = client.callTool({
-                    name: toolName,
-                    arguments: parameters,
+                return mcpTracer.startActiveSpan("neurolink.mcp.callTool", {
+                    kind: SpanKind.CLIENT,
+                    attributes: {
+                        "mcp.server_id": serverId,
+                        "mcp.tool_name": toolName,
+                        "mcp.timeout_ms": options.timeout || 30000,
+                    },
+                }, async (callSpan) => {
+                    try {
+                        const timeout = options.timeout || 30000;
+                        const callResult = await withTimeout(client.callTool({
+                            name: toolName,
+                            arguments: parameters,
+                        }), timeout, new Error(`Tool execution timeout: ${toolName}`));
+                        callSpan.setStatus({ code: SpanStatusCode.OK });
+                        return callResult;
+                    }
+                    catch (err) {
+                        callSpan.setStatus({
+                            code: SpanStatusCode.ERROR,
+                            message: err.message,
+                        });
+                        callSpan.recordException(err);
+                        throw err;
+                    }
+                    finally {
+                        callSpan.end();
+                    }
                 });
-                const timeoutPromise = this.createTimeoutPromise(timeout, `Tool execution timeout: ${toolName}`);
-                return await Promise.race([executePromise, timeoutPromise]);
             });
             const duration = Date.now() - startTime;
             // Update tool statistics

package/dist/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/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
      */