@juspay/neurolink 9.30.0 → 9.31.1

package/dist/client/core/modules/ToolsManager.js

@@ -0,0 +1,499 @@
+/**
+ * Tools Manager Module
+ *
+ * Handles all tool registration, discovery, and execution for AI providers.
+ * Extracted from BaseProvider to follow Single Responsibility Principle.
+ *
+ * Responsibilities:
+ * - Tool registration (direct, custom, MCP, external MCP)
+ * - Tool discovery and aggregation
+ * - Tool creation from definitions and schemas
+ * - Tool executor setup
+ * - Session context management for MCP tools
+ * - Event emission wrapping for tool execution
+ *
+ * @module core/modules/ToolsManager
+ */
+import { tool as createAISDKTool, jsonSchema } from "ai";
+import { z } from "zod";
+import { tracers, ATTR, withSpan } from "../../telemetry/index.js";
+import { SpanStatusCode } from "@opentelemetry/api";
+import { logger } from "../../utils/logger.js";
+import { getKeyCount } from "../../utils/transformationUtils.js";
+import { convertJsonSchemaToZod } from "../../utils/schemaConversion.js";
+/**
+ * ToolsManager class - Handles all tool management operations
+ */
+export class ToolsManager {
+    providerName;
+    directTools;
+    neurolink;
+    utilities;
+    // Tool storage
+    mcpTools;
+    customTools;
+    toolExecutor;
+    // Session context
+    sessionId;
+    userId;
+    constructor(providerName, directTools, neurolink, utilities) {
+        this.providerName = providerName;
+        this.directTools = directTools;
+        this.neurolink = neurolink;
+        this.utilities = utilities;
+        this.mcpTools = {};
+    }
+    /**
+     * Set session context for MCP tools
+     */
+    setSessionContext(sessionId, userId) {
+        this.sessionId = sessionId;
+        this.userId = userId;
+    }
+    /**
+     * Set up tool executor for a provider to enable actual tool execution
+     * @param sdk - The NeuroLinkSDK instance for tool execution
+     * @param functionTag - Function name for logging
+     */
+    setupToolExecutor(sdk, functionTag) {
+        const span = tracers.sdk.startSpan("neurolink.tools.register", {
+            attributes: {
+                [ATTR.NL_PROVIDER]: this.providerName,
+                "tools.custom_count": sdk.customTools.size,
+            },
+        });
+        try {
+            // Store custom tools for use in getAllTools()
+            this.customTools = sdk.customTools;
+            this.toolExecutor = sdk.executeTool.bind(sdk);
+            logger.debug(`[${functionTag}] Setting up tool executor for provider`, {
+                providerName: this.providerName,
+                availableCustomTools: sdk.customTools.size,
+                customToolsStored: !!this.customTools,
+                toolExecutorStored: !!this.toolExecutor,
+            });
+            // Note: Tool execution will be handled through getAllTools() -> AI SDK tools
+            // The custom tools are converted to AI SDK format in getAllTools() method
+            span.setStatus({ code: SpanStatusCode.OK });
+        }
+        catch (error) {
+            span.setStatus({
+                code: SpanStatusCode.ERROR,
+                message: error instanceof Error ? error.message : String(error),
+            });
+            if (error instanceof Error) {
+                span.recordException(error);
+            }
+            throw error;
+        }
+        finally {
+            span.end();
+        }
+    }
+    /**
+     * Get all available tools - direct tools are ALWAYS available
+     * MCP tools are added when available (without blocking)
+     */
+    async getAllTools() {
+        return withSpan({
+            name: "neurolink.tools.getAll",
+            tracer: tracers.sdk,
+            attributes: {
+                [ATTR.NL_PROVIDER]: this.providerName,
+            },
+        }, async (span) => {
+            // Start with wrapped direct tools that emit events
+            const tools = {};
+            // Wrap direct tools with event emission
+            await this.processDirectTools(tools);
+            const directCount = Object.keys(tools).length;
+            span.setAttribute("tools.direct_count", directCount);
+            logger.debug(`[ToolsManager] getAllTools called for ${this.providerName}`, {
+                directToolsCount: getKeyCount(this.directTools),
+            });
+            // Process all tool types using dedicated helper methods
+            await this.processCustomTools(tools);
+            const customCount = Object.keys(tools).length - directCount;
+            span.setAttribute("tools.custom_count", customCount);
+            await this.processExternalMCPTools(tools);
+            const externalCount = Object.keys(tools).length - directCount - customCount;
+            span.setAttribute("tools.external_mcp_count", externalCount);
+            await this.processMCPTools(tools);
+            const totalCount = Object.keys(tools).length;
+            span.setAttribute(ATTR.NL_TOOL_COUNT, totalCount);
+            // Record tool names for debugging (truncated)
+            const toolNames = Object.keys(tools);
+            span.setAttribute("tools.names", toolNames.slice(0, 20).join(",") +
+                (toolNames.length > 20 ? `...+${toolNames.length - 20}` : ""));
+            // Log a compact summary instead of full tool list
+            logger.debug(`[ToolsManager] getAllTools complete: ${toolNames.length} tools available`, {
+                provider: this.providerName,
+                toolCount: toolNames.length,
+                toolNames: toolNames.length <= 10
+                    ? toolNames
+                    : [
+                        ...toolNames.slice(0, 10),
+                        `... and ${toolNames.length - 10} more`,
+                    ],
+            });
+            return tools;
+        });
+    }
+    /**
+     * Get direct tools (built-in agent tools)
+     */
+    getDirectTools() {
+        return this.directTools;
+    }
+    /**
+     * Get MCP tools
+     */
+    getMCPTools() {
+        return this.mcpTools;
+    }
+    /**
+     * Get custom tools
+     */
+    getCustomTools() {
+        return this.customTools;
+    }
+    /**
+     * Process direct tools with event emission wrapping
+     */
+    async processDirectTools(tools) {
+        if (!this.directTools || Object.keys(this.directTools).length === 0) {
+            return;
+        }
+        logger.debug(`[ToolsManager] Loading ${Object.keys(this.directTools).length} direct tools`);
+        for (const [toolName, directTool] of Object.entries(this.directTools)) {
+            // Wrap the direct tool's execute function with event emission
+            if (directTool &&
+                typeof directTool === "object" &&
+                "execute" in directTool) {
+                const originalExecute = directTool.execute;
+                // Create a new tool with wrapped execute function
+                tools[toolName] = {
+                    ...directTool,
+                    execute: async (params) => {
+                        // 🔧 EMIT TOOL START EVENT - Bedrock-compatible format
+                        if (this.neurolink?.getEventEmitter) {
+                            const emitter = this.neurolink.getEventEmitter();
+                            emitter.emit("tool:start", { tool: toolName, input: params });
+                        }
+                        try {
+                            const result = await originalExecute(params);
+                            // 🔧 EMIT TOOL END EVENT - Bedrock-compatible format
+                            if (this.neurolink?.getEventEmitter) {
+                                const emitter = this.neurolink.getEventEmitter();
+                                emitter.emit("tool:end", { tool: toolName, result });
+                            }
+                            return result;
+                        }
+                        catch (error) {
+                            // 🔧 EMIT TOOL END EVENT FOR ERROR - Bedrock-compatible format
+                            if (this.neurolink?.getEventEmitter) {
+                                const emitter = this.neurolink.getEventEmitter();
+                                const errorMsg = error instanceof Error ? error.message : String(error);
+                                emitter.emit("tool:end", { tool: toolName, error: errorMsg });
+                            }
+                            throw error;
+                        }
+                    },
+                };
+            }
+            else {
+                // Fallback: include tool as-is if it doesn't have execute function
+                tools[toolName] = directTool;
+            }
+        }
+        // Direct tools processing complete — count already logged at start
+    }
+    /**
+     * Process custom tools from setupToolExecutor
+     */
+    async processCustomTools(tools) {
+        if (!this.customTools || this.customTools.size === 0) {
+            return;
+        }
+        logger.debug(`[ToolsManager] Loading ${this.customTools.size} custom tools from setupToolExecutor`);
+        for (const [toolName, toolDef] of this.customTools.entries()) {
+            // Validate tool definition has required execute function
+            const toolInfo = toolDef ||
+                {};
+            if (toolInfo && typeof toolInfo.execute === "function") {
+                const tool = await this.createCustomToolFromDefinition(toolName, toolInfo);
+                if (tool && !tools[toolName]) {
+                    tools[toolName] = tool;
+                }
+            }
+        }
+        // Custom tools processing complete — count already logged at start
+    }
+    /**
+     * Process MCP tools integration
+     */
+    async processMCPTools(tools) {
+        // MCP tools loading simplified - removed functionCalling dependency
+        if (!this.mcpTools) {
+            // Set empty tools object - MCP tools are handled at a higher level
+            this.mcpTools = {};
+        }
+        // Add MCP tools if available, but don't overwrite existing direct tools
+        // Direct tools (Zod-based) take precedence over MCP tools (JSON Schema)
+        if (this.mcpTools) {
+            for (const [name, tool] of Object.entries(this.mcpTools)) {
+                if (!tools[name]) {
+                    tools[name] = tool;
+                }
+            }
+        }
+    }
+    /**
+     * Process external MCP tools
+     */
+    async processExternalMCPTools(tools) {
+        if (!this.neurolink ||
+            typeof this.neurolink.getExternalMCPTools !== "function") {
+            return;
+        }
+        try {
+            const externalTools = await this.neurolink.getExternalMCPTools();
+            let addedCount = 0;
+            for (const tool of externalTools) {
+                const mcpTool = await this.createExternalMCPTool(tool);
+                if (mcpTool && !tools[tool.name]) {
+                    tools[tool.name] = mcpTool;
+                    addedCount++;
+                }
+            }
+            logger.debug(`[ToolsManager] External MCP tools loaded`, {
+                found: externalTools.length,
+                added: addedCount,
+            });
+        }
+        catch (error) {
+            logger.error(`[ToolsManager] Failed to load external MCP tools for ${this.providerName}:`, error);
+            // Not an error - external tools are optional
+        }
+    }
+    /**
+     * Create a custom tool from tool definition
+     */
+    async createCustomToolFromDefinition(toolName, toolInfo) {
+        try {
+            let finalSchema;
+            let originalInputSchema;
+            // Prioritize parameters (Zod), then inputSchema (Zod or JSON Schema)
+            if (toolInfo.parameters &&
+                this.utilities?.isZodSchema?.(toolInfo.parameters)) {
+                finalSchema = toolInfo.parameters;
+            }
+            else if (toolInfo.inputSchema &&
+                this.utilities?.isZodSchema?.(toolInfo.inputSchema)) {
+                finalSchema = toolInfo.inputSchema;
+            }
+            else if (toolInfo.inputSchema &&
+                typeof toolInfo.inputSchema === "object") {
+                // Use original JSON Schema with jsonSchema() wrapper - NO CONVERSION!
+                originalInputSchema = toolInfo.inputSchema;
+                finalSchema = jsonSchema(originalInputSchema);
+            }
+            else if (toolInfo.parameters &&
+                typeof toolInfo.parameters === "object") {
+                finalSchema = convertJsonSchemaToZod(toolInfo.parameters);
+            }
+            else {
+                finalSchema = z.object({});
+            }
+            return createAISDKTool({
+                description: toolInfo.description || `Tool ${toolName}`,
+                inputSchema: finalSchema, // AI SDK v6 uses inputSchema (not parameters)
+                execute: async (params) => {
+                    const customToolSpan = tracers.sdk.startSpan("neurolink.tools.execute_custom", {
+                        attributes: {
+                            "tool.name": toolName,
+                            "tool.type": "custom",
+                        },
+                    });
+                    const startTime = Date.now();
+                    let executionId;
+                    try {
+                        // Route through NeuroLink.executeTool() when available for MCP enhancement support
+                        // (cache, middleware, annotations, circuit breaker, routing)
+                        if (this.toolExecutor) {
+                            // Per-tool timeout and retries flow through the customTools map
+                            // (set at registration via ToolRegistrationOptions).
+                            // The execute wrapper in registerTool already enforces timeouts,
+                            // but we also forward them to toolExecutor for MCP-level handling.
+                            const toolTimeoutMs = toolInfo.timeoutMs;
+                            const toolMaxRetries = toolInfo.maxRetries;
+                            const hasRegistrationOptions = toolTimeoutMs !== undefined || toolMaxRetries !== undefined;
+                            const result = await this.toolExecutor(toolName, params, hasRegistrationOptions
+                                ? {
+                                    ...(toolTimeoutMs !== undefined && {
+                                        timeout: toolTimeoutMs,
+                                    }),
+                                    ...(toolMaxRetries !== undefined && {
+                                        maxRetries: toolMaxRetries,
+                                    }),
+                                }
+                                : undefined);
+                            const convertedResult = this.utilities?.convertToolResult
+                                ? await this.utilities.convertToolResult(result)
+                                : result;
+                            const endTime = Date.now();
+                            customToolSpan.setAttribute("tool.duration_ms", endTime - startTime);
+                            let errorResult = undefined;
+                            if (convertedResult &&
+                                typeof convertedResult === "object" &&
+                                "isError" in convertedResult &&
+                                convertedResult.isError) {
+                                try {
+                                    errorResult = JSON.stringify(convertedResult);
+                                }
+                                catch (error) {
+                                    logger.error(`Failed to serialize error result for ${toolName}`, error);
+                                }
+                            }
+                            customToolSpan.setAttribute("tool.result.status", errorResult ? "error" : "success");
+                            customToolSpan.setStatus({ code: SpanStatusCode.OK });
+                            return convertedResult;
+                        }
+                        // Fallback: direct execution (standalone usage without NeuroLink SDK)
+                        if (this.neurolink?.emitToolStart) {
+                            executionId = this.neurolink.emitToolStart(toolName, params, startTime);
+                        }
+                        const result = await toolInfo.execute(params);
+                        const convertedResult = this.utilities?.convertToolResult
+                            ? await this.utilities.convertToolResult(result)
+                            : result;
+                        const endTime = Date.now();
+                        let errorResult = undefined;
+                        if (convertedResult &&
+                            typeof convertedResult === "object" &&
+                            "isError" in convertedResult &&
+                            convertedResult.isError) {
+                            try {
+                                errorResult = JSON.stringify(convertedResult);
+                            }
+                            catch (error) {
+                                logger.error(`Failed to serialize error result for ${toolName}`, error);
+                            }
+                        }
+                        // Emit tool end event (success or handled error)
+                        if (this.neurolink?.emitToolEnd) {
+                            this.neurolink.emitToolEnd(toolName, convertedResult, errorResult, startTime, endTime, executionId);
+                        }
+                        customToolSpan.setAttribute("tool.duration_ms", endTime - startTime);
+                        customToolSpan.setAttribute("tool.result.status", errorResult ? "error" : "success");
+                        customToolSpan.setStatus({ code: SpanStatusCode.OK });
+                        return convertedResult;
+                    }
+                    catch (error) {
+                        const endTime = Date.now();
+                        const errorMsg = error instanceof Error ? error.message : String(error);
+                        // Emit tool end event (error) — only for fallback path
+                        // When toolExecutor is used, executeTool() handles event emission
+                        if (!this.toolExecutor && this.neurolink?.emitToolEnd) {
+                            this.neurolink.emitToolEnd(toolName, undefined, // no result
+                            errorMsg, startTime, endTime, executionId);
+                            logger.debug(`Custom tool error: ${toolName} (${endTime - startTime}ms)`, { error: errorMsg });
+                        }
+                        customToolSpan.setAttribute("tool.duration_ms", endTime - startTime);
+                        customToolSpan.setAttribute("tool.result.status", "error");
+                        customToolSpan.recordException(error instanceof Error ? error : new Error(errorMsg));
+                        customToolSpan.setStatus({
+                            code: SpanStatusCode.ERROR,
+                            message: errorMsg,
+                        });
+                        throw error;
+                    }
+                    finally {
+                        customToolSpan.end();
+                    }
+                },
+            });
+        }
+        catch (toolCreationError) {
+            logger.error(`Failed to create tool: ${toolName}`, toolCreationError);
+            return null;
+        }
+    }
+    /**
+     * Create an external MCP tool
+     */
+    async createExternalMCPTool(tool) {
+        try {
+            // Use original JSON Schema from MCP tool if available, otherwise use permissive schema
+            let finalSchema;
+            if (tool.inputSchema && typeof tool.inputSchema === "object") {
+                // Clone and fix the schema for OpenAI strict mode compatibility
+                const originalSchema = tool.inputSchema;
+                const fixedSchema = this.utilities?.fixSchemaForOpenAIStrictMode
+                    ? this.utilities.fixSchemaForOpenAIStrictMode(originalSchema)
+                    : originalSchema;
+                finalSchema = jsonSchema(fixedSchema);
+            }
+            else {
+                finalSchema = this.utilities?.createPermissiveZodSchema
+                    ? this.utilities.createPermissiveZodSchema()
+                    : z.object({});
+            }
+            return createAISDKTool({
+                description: tool.description || `External MCP tool ${tool.name}`,
+                inputSchema: finalSchema, // AI SDK v6 uses inputSchema (not parameters)
+                execute: async (params) => {
+                    // Emit tool start event
+                    if (this.neurolink?.getEventEmitter) {
+                        const emitter = this.neurolink.getEventEmitter();
+                        emitter.emit("tool:start", { tool: tool.name, input: params });
+                    }
+                    // Execute via NeuroLink's direct tool execution
+                    if (this.neurolink &&
+                        typeof this.neurolink.executeExternalMCPTool === "function") {
+                        try {
+                            const result = await this.neurolink.executeExternalMCPTool(tool.serverId || "unknown", tool.name, params);
+                            // Emit tool end event (success)
+                            if (this.neurolink?.getEventEmitter) {
+                                const emitter = this.neurolink.getEventEmitter();
+                                emitter.emit("tool:end", { tool: tool.name, result });
+                            }
+                            return result;
+                        }
+                        catch (mcpError) {
+                            // Emit tool end event (error)
+                            if (this.neurolink?.getEventEmitter) {
+                                const emitter = this.neurolink.getEventEmitter();
+                                const errorMsg = mcpError instanceof Error
+                                    ? mcpError.message
+                                    : String(mcpError);
+                                emitter.emit("tool:end", { tool: tool.name, error: errorMsg });
+                            }
+                            logger.error(`External MCP tool failed: ${tool.name}`, {
+                                serverId: tool.serverId,
+                                error: mcpError instanceof Error
+                                    ? mcpError.message
+                                    : String(mcpError),
+                            });
+                            throw mcpError;
+                        }
+                    }
+                    else {
+                        const error = `Cannot execute external MCP tool: NeuroLink executeExternalMCPTool not available`;
+                        // Emit tool end event (error - no executor)
+                        if (this.neurolink?.getEventEmitter) {
+                            const emitter = this.neurolink.getEventEmitter();
+                            emitter.emit("tool:end", { tool: tool.name, error });
+                        }
+                        logger.error(error);
+                        throw new Error(error);
+                    }
+                },
+            });
+        }
+        catch (toolCreationError) {
+            logger.error(`Failed to create external MCP tool: ${tool.name}`, toolCreationError);
+            return null;
+        }
+    }
+}