@juspay/neurolink 7.14.1 → 7.14.3

package/dist/lib/mcp/contracts/mcpContract.d.ts

@@ -2,15 +2,16 @@
  * MCP Contract - Core Type Definitions
  * Industry standard camelCase interfaces for maximum flexibility
  */
+import type { StandardRecord } from "../../types/typeAliases.js";
 /**
  * Generic execution context for MCP operations
  * All properties optional for maximum flexibility
  */
-export interface ExecutionContext<T = Record<string, unknown>> {
+export interface ExecutionContext<T = StandardRecord> {
     sessionId?: string;
     userId?: string;
     config?: T;
-    metadata?: Record<string, unknown>;
+    metadata?: StandardRecord;
     cacheOptions?: CacheOptions;
     fallbackOptions?: FallbackOptions;
     timeoutMs?: number;
@@ -41,14 +42,14 @@ export interface ToolInfo {
     description?: string;
     category?: string;
     serverId?: string;
-    inputSchema?: Record<string, unknown>;
-    outputSchema?: Record<string, unknown>;
+    inputSchema?: StandardRecord;
+    outputSchema?: StandardRecord;
     [key: string]: unknown;
 }
 /**
  * Discovered MCP server/plugin definition
  */
-export interface DiscoveredMcp<TTools = Record<string, unknown>> {
+export interface DiscoveredMcp<TTools = StandardRecord> {
     metadata: McpMetadata;
     tools?: TTools;
     capabilities?: string[];
@@ -68,20 +69,6 @@ export interface McpMetadata {
     repository?: string;
     category?: string;
 }
-/**
- * Tool definition schema
- */
-export interface ToolDefinition {
-    description?: string;
-    inputSchema?: Record<string, unknown>;
-    outputSchema?: Record<string, unknown>;
-    category?: string;
-    examples?: Array<{
-        input: Record<string, unknown>;
-        output: Record<string, unknown>;
-        description?: string;
-    }>;
-}
 /**
  * Tool execution result
  */

package/dist/lib/mcp/externalServerManager.d.ts

@@ -11,6 +11,7 @@ import { ToolDiscoveryService } from "./toolDiscoveryService.js";
 import type { ExternalMCPServerInstance, ExternalMCPServerHealth, ExternalMCPConfigValidation, ExternalMCPOperationResult, ExternalMCPManagerConfig, ExternalMCPToolInfo } from "../types/externalMcp.js";
 import type { MCPServerInfo } from "../types/mcpTypes.js";
 import type { JsonObject } from "../types/common.js";
+import type { ServerLoadResult } from "../types/typeAliases.js";
 export declare class ExternalServerManager extends EventEmitter {
     private servers;
     private config;
@@ -26,10 +27,7 @@ export declare class ExternalServerManager extends EventEmitter {
      * @param configPath Optional path to config file (defaults to .mcp-config.json in cwd)
      * @returns Promise resolving to number of servers loaded
      */
-    loadMCPConfiguration(configPath?: string): Promise<{
-        serversLoaded: number;
-        errors: string[];
-    }>;
+    loadMCPConfiguration(configPath?: string): Promise<ServerLoadResult>;
     /**
      * Validate external MCP server configuration
      */

package/dist/lib/mcp/externalServerManager.js

@@ -12,11 +12,12 @@ import { MCPClientFactory } from "./mcpClientFactory.js";
 import { ToolDiscoveryService } from "./toolDiscoveryService.js";
 import { toolRegistry } from "./toolRegistry.js";
 import { detectCategory } from "../utils/mcpDefaults.js";
+import { isObject, isNonNullObject } from "../utils/typeUtils.js";
 /**
  * Type guard to validate if an object can be safely used as Record<string, JsonValue>
  */
 function isValidJsonRecord(value) {
-    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    if (!isObject(value)) {
         return false;
     }
     const record = value;
@@ -35,7 +36,7 @@ function isValidJsonRecord(value) {
                 typeof item === "boolean" ||
                 item === null);
         }
-        if (typeof val === "object" && val !== null) {
+        if (isNonNullObject(val)) {
             return isValidJsonRecord(val);
         }
         return false;
@@ -51,14 +52,13 @@ function safeMetadataConversion(metadata) {
  * Type guard to validate external MCP server configuration
  */
 function isValidExternalMCPServerConfig(config) {
-    if (typeof config !== "object" || config === null) {
+    if (!isNonNullObject(config)) {
         return false;
     }
     const record = config;
     return (typeof record.command === "string" &&
         (record.args === undefined || Array.isArray(record.args)) &&
-        (record.env === undefined ||
-            (typeof record.env === "object" && record.env !== null)) &&
+        (record.env === undefined || isNonNullObject(record.env)) &&
         (record.transport === undefined || typeof record.transport === "string") &&
         (record.timeout === undefined || typeof record.timeout === "number") &&
         (record.retries === undefined || typeof record.retries === "number") &&
@@ -68,8 +68,7 @@ function isValidExternalMCPServerConfig(config) {
             typeof record.autoRestart === "boolean") &&
         (record.cwd === undefined || typeof record.cwd === "string") &&
         (record.url === undefined || typeof record.url === "string") &&
-        (record.metadata === undefined ||
-            (typeof record.metadata === "object" && record.metadata !== null)));
+        (record.metadata === undefined || isNonNullObject(record.metadata)));
 }
 export class ExternalServerManager extends EventEmitter {
     servers = new Map();
@@ -150,7 +149,7 @@ export class ExternalServerManager extends EventEmitter {
                         args: Array.isArray(serverConfig.args)
                             ? serverConfig.args
                             : [],
-                        env: typeof serverConfig.env === "object" && serverConfig.env !== null
+                        env: isNonNullObject(serverConfig.env)
                             ? serverConfig.env
                             : {},
                         timeout: typeof serverConfig.timeout === "number"

package/dist/lib/mcp/factory.d.ts

@@ -3,7 +3,6 @@
  * Factory-First Architecture: MCP servers create tools for internal orchestration
  * Compatible with MCP patterns for seamless integration
  */
-import { z } from "zod";
 import type { ExecutionContext } from "./contracts/mcpContract.js";
 /**
  * MCP Server Categories for organization and discovery
@@ -71,19 +70,64 @@ export interface ToolResult {
     };
 }
 /**
- * MCP Tool Interface - Standard compatible with NeuroLink enhancements
+ * MCP Tool Interface - Standalone definition to avoid confusion with ToolDefinition execute signature
+ */
+/**
+ * NeuroLink MCP Tool Interface - Standardized tool definition for MCP integration
+ *
+ * This interface defines the contract for all tools in the NeuroLink ecosystem,
+ * ensuring consistent execution patterns and metadata handling across different
+ * MCP servers and tool implementations.
+ *
+ * Key features:
+ * - Promise-based execution with ToolResult return type
+ * - Rich context support for session management and permissions
+ * - Optional schema validation for input/output
+ * - Comprehensive metadata support for tool discovery
+ *
+ * @example
+ * ```typescript
+ * const calculatorTool: NeuroLinkMCPTool = {
+ *   name: "calculator",
+ *   description: "Performs basic arithmetic operations",
+ *   category: "math",
+ *   inputSchema: z.object({ a: z.number(), b: z.number(), op: z.string() }),
+ *   async execute(params, context) {
+ *     const { a, b, op } = params as { a: number; b: number; op: string };
+ *     const result = op === "add" ? a + b : a - b;
+ *     return { success: true, data: result };
+ *   }
+ * };
+ * ```
  */
 export interface NeuroLinkMCPTool {
+    /** Unique tool identifier for MCP registration and execution */
     name: string;
+    /** Human-readable description of tool functionality */
     description: string;
-    execute: (params: unknown, context: NeuroLinkExecutionContext) => Promise<ToolResult>;
-    inputSchema?: z.ZodSchema;
-    outputSchema?: z.ZodSchema;
-    isImplemented?: boolean;
+    /** Optional category for tool organization and discovery */
     category?: string;
+    /** Optional input schema for parameter validation (Zod or JSON Schema) */
+    inputSchema?: unknown;
+    /** Optional output schema for result validation */
+    outputSchema?: unknown;
+    /** Implementation status flag for development tracking */
+    isImplemented?: boolean;
+    /** Required permissions for tool execution in secured environments */
     permissions?: string[];
+    /** Tool version for compatibility and update management */
     version?: string;
+    /** Additional metadata for tool information and capabilities */
     metadata?: Record<string, unknown>;
+    /**
+     * Tool execution function with standardized signature
+     *
+     * @param params - Input parameters for the tool (validated against inputSchema if provided)
+     * @param context - Execution context with session, user, and environment information
+     * @returns Promise resolving to ToolResult with success status, data, and metadata
+     * @throws ValidationError if parameters fail validation
+     */
+    execute: (params: unknown, context: NeuroLinkExecutionContext) => Promise<ToolResult>;
 }
 /**
  * MCP Server Interface - Standard compatible
@@ -145,7 +189,8 @@ export interface MCPServerConfig {
  */
 export declare function createMCPServer(config: MCPServerConfig): NeuroLinkMCPServer;
 /**
- * Utility function to validate tool interface
+ * Utility function to validate tool interface using centralized validation
+ * Ensures proper async patterns and type safety
  */
 export declare function validateTool(tool: NeuroLinkMCPTool): boolean;
 /**
@@ -159,3 +204,12 @@ export declare function getServerInfo(server: NeuroLinkMCPServer): {
     toolCount: number;
     capabilities: string[];
 };
+/**
+ * Async utility function to validate all tools in a server
+ * Ensures all registered tools follow proper async patterns
+ */
+export declare function validateServerTools(server: NeuroLinkMCPServer): Promise<{
+    isValid: boolean;
+    invalidTools: string[];
+    errors: string[];
+}>;

package/dist/lib/mcp/factory.js

@@ -4,6 +4,7 @@
  * Compatible with MCP patterns for seamless integration
  */
 import { z } from "zod";
+import { validateMCPTool, ValidationError, createValidationSummary, } from "../utils/parameterValidation.js";
 /**
  * Input validation schemas
  */
@@ -27,7 +28,7 @@ const ServerConfigSchema = z.object({
     ])
         .optional(),
     visibility: z.enum(["public", "private", "organization"]).optional(),
-    metadata: z.record(z.any()).optional(),
+    metadata: z.record(z.unknown()).optional(),
     dependencies: z.array(z.string()).optional(),
     capabilities: z.array(z.string()).optional(),
 });
@@ -76,9 +77,11 @@ export function createMCPServer(config) {
         tools: {},
         // Tool registration method
         registerTool(tool) {
-            // Validate tool has required fields
-            if (!tool.name || !tool.description || !tool.execute) {
-                throw new Error(`Invalid tool: name, description, and execute are required`);
+            // Comprehensive tool validation using centralized utilities
+            const validation = validateMCPTool(tool);
+            if (!validation.isValid) {
+                const summary = createValidationSummary(validation);
+                throw new ValidationError(`Invalid tool '${tool.name}': ${summary}`, "tool", "VALIDATION_FAILED", validation.suggestions);
             }
             // Check for duplicate tool names
             if (this.tools[tool.name]) {
@@ -105,28 +108,13 @@ export function createMCPServer(config) {
     return server;
 }
 /**
- * Utility function to validate tool interface
+ * Utility function to validate tool interface using centralized validation
+ * Ensures proper async patterns and type safety
  */
 export function validateTool(tool) {
     try {
-        // Check required fields
-        if (!tool.name || typeof tool.name !== "string") {
-            return false;
-        }
-        if (!tool.description || typeof tool.description !== "string") {
-            return false;
-        }
-        if (!tool.execute || typeof tool.execute !== "function") {
-            return false;
-        }
-        // Validate optional schemas if present
-        if (tool.inputSchema && !(tool.inputSchema instanceof z.ZodSchema)) {
-            return false;
-        }
-        if (tool.outputSchema && !(tool.outputSchema instanceof z.ZodSchema)) {
-            return false;
-        }
-        return true;
+        const validation = validateMCPTool(tool);
+        return validation.isValid;
     }
     catch (error) {
         return false;
@@ -145,4 +133,29 @@ export function getServerInfo(server) {
         capabilities: server.capabilities || [],
     };
 }
+/**
+ * Async utility function to validate all tools in a server
+ * Ensures all registered tools follow proper async patterns
+ */
+export async function validateServerTools(server) {
+    const invalidTools = [];
+    const errors = [];
+    for (const [toolName, tool] of Object.entries(server.tools)) {
+        try {
+            if (!validateTool(tool)) {
+                invalidTools.push(toolName);
+                errors.push(`Tool '${toolName}' does not follow proper async patterns`);
+            }
+        }
+        catch (error) {
+            invalidTools.push(toolName);
+            errors.push(`Tool '${toolName}' validation failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    return {
+        isValid: invalidTools.length === 0,
+        invalidTools,
+        errors,
+    };
+}
 // Types are already exported above via export interface declarations

package/dist/lib/mcp/mcpClientFactory.d.ts

@@ -72,7 +72,8 @@ export declare class MCPClientFactory {
      */
     private static extractCapabilities;
     /**
-     * Create a timeout promise
+     * Create a timeout promise with AbortController support
+     * Provides consistent async timeout patterns across the factory
      */
     private static createTimeoutPromise;
     /**

package/dist/lib/mcp/mcpClientFactory.js

@@ -9,7 +9,7 @@ import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
 import { WebSocketClientTransport } from "@modelcontextprotocol/sdk/client/websocket.js";
 import { spawn } from "child_process";
 import { mcpLogger } from "../utils/logger.js";
-import { globalCircuitBreakerManager, } from "./mcpCircuitBreaker.js";
+import { globalCircuitBreakerManager } from "./mcpCircuitBreaker.js";
 /**
  * MCPClientFactory
  * Factory class for creating MCP clients with different transports
@@ -73,7 +73,11 @@ export class MCPClientFactory {
      */
     static async createClientInternal(config, timeout) {
         // Create transport
-        const { transport, process } = await this.createTransport(config);
+        const transportResult = await this.createTransport(config);
+        // Extract transport and process with necessary type assertions
+        // Note: Type assertions required due to TransportResult using 'unknown' to avoid circular imports
+        const transport = transportResult.transport;
+        const process = transportResult.process;
         try {
             // Create client
             const client = new Client(this.NEUROLINK_IMPLEMENTATION, {
@@ -140,10 +144,12 @@ export class MCPClientFactory {
         // Spawn the process
         const childProcess = spawn(config.command, config.args || [], {
             stdio: ["pipe", "pipe", "pipe"],
-            env: {
+            env: Object.fromEntries(Object.entries({
                 ...process.env,
                 ...config.env,
-            },
+            })
+                .filter(([, value]) => value !== undefined)
+                .map(([k, v]) => [k, String(v)])),
             cwd: config.cwd,
         });
         // Handle process errors
@@ -157,14 +163,32 @@ export class MCPClientFactory {
                 }
             });
         });
-        // Wait for process to be ready or fail
-        await Promise.race([
-            new Promise((resolve) => setTimeout(resolve, 1000)), // Give process time to start
-            processErrorPromise,
-        ]);
+        // Wait for process to be ready or fail using AbortController for better async patterns
+        const processStartupController = new AbortController();
+        const processStartupTimeout = setTimeout(() => {
+            processStartupController.abort();
+        }, 1000);
+        try {
+            await Promise.race([
+                new Promise((resolve) => {
+                    const checkReady = () => {
+                        if (processStartupController.signal.aborted) {
+                            resolve(); // Timeout reached, continue
+                        }
+                        else {
+                            setTimeout(checkReady, 100);
+                        }
+                    };
+                    checkReady();
+                }),
+                processErrorPromise,
+            ]);
+        }
+        finally {
+            clearTimeout(processStartupTimeout);
+        }
         // Check if process is still running
-        if (childProcess.killed ||
-            childProcess.exitCode !== null) {
+        if (childProcess.killed || childProcess.exitCode !== null) {
             throw new Error("Process failed to start or exited immediately");
         }
         // Create transport
@@ -174,7 +198,9 @@ export class MCPClientFactory {
             env: Object.fromEntries(Object.entries({
                 ...process.env,
                 ...config.env,
-            }).filter(([, value]) => value !== undefined)),
+            })
+                .filter(([, value]) => value !== undefined)
+                .map(([key, value]) => [key, String(value)])),
             cwd: config.cwd,
         });
         return { transport, process: childProcess };
@@ -250,7 +276,7 @@ export class MCPClientFactory {
                 capabilities: this.DEFAULT_CAPABILITIES,
             };
         }
-        catch (error) {
+        catch {
             // If listing tools fails, try a simpler ping
             mcpLogger.debug("[MCPClientFactory] Tool listing failed, server may not support tools yet");
             return {
@@ -267,17 +293,25 @@ export class MCPClientFactory {
         // This can be enhanced when MCP servers provide more detailed capability info
         return {
             ...this.DEFAULT_CAPABILITIES,
-            tools: serverInfo.tools ? {} : undefined,
+            ...(serverInfo.tools ? { tools: {} } : {}),
         };
     }
     /**
-     * Create a timeout promise
+     * Create a timeout promise with AbortController support
+     * Provides consistent async timeout patterns across the factory
      */
-    static createTimeoutPromise(timeout, message) {
+    static createTimeoutPromise(timeout, message, abortSignal) {
         return new Promise((_, reject) => {
-            setTimeout(() => {
+            const timeoutId = setTimeout(() => {
                 reject(new Error(message));
             }, timeout);
+            // Support abortion for better async cleanup
+            if (abortSignal) {
+                abortSignal.addEventListener("abort", () => {
+                    clearTimeout(timeoutId);
+                    reject(new Error(`Operation aborted: ${message}`));
+                });
+            }
         });
     }
     /**
@@ -299,17 +333,30 @@ export class MCPClientFactory {
         catch (error) {
             errors.push(`Transport close error: ${error instanceof Error ? error.message : String(error)}`);
         }
-        // Kill process if exists
+        // Kill process if exists with proper async cleanup
         if (process && !process.killed) {
             try {
                 process.kill("SIGTERM");
-                // Force kill after 5 seconds
-                setTimeout(() => {
-                    if (!process.killed) {
-                        mcpLogger.warn("[MCPClientFactory] Force killing process");
-                        process.kill("SIGKILL");
-                    }
-                }, 5000);
+                // Use Promise-based approach for force kill timeout
+                await new Promise((resolve) => {
+                    const forceKillTimeout = setTimeout(() => {
+                        if (!process.killed) {
+                            mcpLogger.warn("[MCPClientFactory] Force killing process");
+                            try {
+                                process.kill("SIGKILL");
+                            }
+                            catch (killError) {
+                                mcpLogger.debug("[MCPClientFactory] Error in force kill:", killError);
+                            }
+                        }
+                        resolve();
+                    }, 5000);
+                    // If process exits gracefully before timeout, clear the force kill
+                    process.on("exit", () => {
+                        clearTimeout(forceKillTimeout);
+                        resolve();
+                    });
+                });
             }
             catch (error) {
                 errors.push(`Process kill error: ${error instanceof Error ? error.message : String(error)}`);
@@ -339,7 +386,7 @@ export class MCPClientFactory {
                 try {
                     await client.listTools();
                 }
-                catch (error) {
+                catch {
                     // Tool listing failure doesn't necessarily mean connection failure
                     mcpLogger.debug("[MCPClientFactory] Tool listing failed during test, but connection may be valid");
                 }

package/dist/lib/mcp/registry.d.ts

@@ -16,7 +16,7 @@ export interface McpRegistry {
  * Maintains backward compatibility with existing code
  */
 export declare class MCPRegistry implements McpRegistry {
-    plugins: Map<string, DiscoveredMcp<Record<string, unknown>>>;
+    plugins: Map<string, DiscoveredMcp<import("../types/typeAliases.js").StandardRecord>>;
     /**
      * Register a plugin
      */

package/dist/lib/mcp/toolDiscoveryService.d.ts

@@ -144,7 +144,7 @@ export declare class ToolDiscoveryService extends EventEmitter {
      */
     private validateParameterType;
     /**
-     * Validate tool output
+     * Validate tool output with enhanced type safety
      */
     private validateToolOutput;
     /**

package/dist/lib/mcp/toolDiscoveryService.js

@@ -5,7 +5,9 @@
  */
 import { EventEmitter } from "events";
 import { mcpLogger } from "../utils/logger.js";
-import { globalCircuitBreakerManager, } from "./mcpCircuitBreaker.js";
+import { globalCircuitBreakerManager } from "./mcpCircuitBreaker.js";
+import { isObject, isString, isBoolean, isNullish, } from "../utils/typeUtils.js";
+import { validateToolName, validateToolDescription, } from "../utils/parameterValidation.js";
 /**
  * ToolDiscoveryService
  * Handles automatic tool discovery and registration from external MCP servers
@@ -227,15 +229,15 @@ export class ToolDiscoveryService extends EventEmitter {
     validateTool(toolInfo) {
         const errors = [];
         const warnings = [];
-        // Basic validation
-        if (!toolInfo.name || toolInfo.name.trim().length === 0) {
-            errors.push("Tool name is required");
+        // Use centralized validation for name
+        const nameError = validateToolName(toolInfo.name);
+        if (nameError) {
+            errors.push(nameError.message);
         }
-        if (toolInfo.name && !/^[a-zA-Z][a-zA-Z0-9_-]*$/.test(toolInfo.name)) {
-            errors.push("Tool name must start with a letter and contain only letters, numbers, underscores, and hyphens");
-        }
-        if (!toolInfo.description || toolInfo.description.trim().length === 0) {
-            warnings.push("Tool description is empty");
+        // Use centralized validation for description
+        const descriptionError = validateToolDescription(toolInfo.description);
+        if (descriptionError) {
+            warnings.push(descriptionError.message);
         }
         if (!toolInfo.serverId) {
             errors.push("Server ID is required");
@@ -440,19 +442,48 @@ export class ToolDiscoveryService extends EventEmitter {
         }
     }
     /**
-     * Validate tool output
+     * Validate tool output with enhanced type safety
      */
     validateToolOutput(result) {
-        // Basic output validation
-        if (!result) {
-            throw new Error("Tool returned no result");
-        }
-        // Check for error indicators
-        if (result.error) {
-            throw new Error(`Tool execution error: ${result.error}`);
+        // Check for null/undefined results
+        if (isNullish(result)) {
+            throw new Error("Tool returned null or undefined result");
+        }
+        // Enhanced error detection for object results
+        if (isObject(result)) {
+            // Check for explicit error property
+            if (result.error !== undefined) {
+                const errorMessage = isString(result.error)
+                    ? result.error
+                    : "Tool execution failed with error";
+                throw new Error(`Tool execution error: ${errorMessage}`);
+            }
+            // Check for boolean error flag
+            if (isBoolean(result.isError) && result.isError === true) {
+                const errorDetail = isString(result.message)
+                    ? `: ${result.message}`
+                    : "";
+                throw new Error(`Tool execution failed${errorDetail}`);
+            }
+            // Check for common error status patterns
+            if (isString(result.status) &&
+                (result.status === "error" || result.status === "failed")) {
+                const errorDetail = isString(result.message) || isString(result.reason)
+                    ? `: ${result.message || result.reason}`
+                    : "";
+                throw new Error(`Tool execution failed${errorDetail}`);
+            }
+            // Check for success: false pattern
+            if (isBoolean(result.success) && result.success === false) {
+                const errorDetail = isString(result.message) || isString(result.error)
+                    ? `: ${result.message || result.error}`
+                    : "";
+                throw new Error(`Tool execution unsuccessful${errorDetail}`);
+            }
         }
-        if (result.isError === true) {
-            throw new Error("Tool execution failed");
+        // Validate that string results are not empty
+        if (isString(result) && result.trim() === "") {
+            throw new Error("Tool returned empty string result");
         }
     }
     /**

package/dist/lib/mcp/toolRegistry.d.ts

@@ -43,7 +43,29 @@ export declare class MCPToolRegistry extends MCPRegistry {
     registerServer(serverInfo: MCPServerInfo, context?: ExecutionContext): Promise<void>;
     registerServer(serverId: string, serverConfig?: unknown, context?: ExecutionContext): Promise<void>;
     /**
-     * Execute a tool with enhanced context
+     * Execute a tool with enhanced context and automatic result wrapping
+     *
+     * This method handles both raw return values and ToolResult objects:
+     * - Raw values (primitives, objects) are automatically wrapped in ToolResult format
+     * - Existing ToolResult objects are enhanced with execution metadata
+     * - All results include execution timing and context information
+     *
+     * @param toolName - Name of the tool to execute
+     * @param args - Parameters to pass to the tool execution function
+     * @param context - Execution context with session, user, and environment info
+     * @returns Promise resolving to ToolResult object with data, metadata, and usage info
+     * @throws Error if tool is not found or execution fails
+     *
+     * @example
+     * ```typescript
+     * // Tool that returns raw value
+     * const result = await toolRegistry.executeTool("calculator", { a: 5, b: 3, op: "add" });
+     * // result.data === 8, result.metadata contains execution info
+     *
+     * // Tool that returns ToolResult
+     * const result = await toolRegistry.executeTool("complexTool", { input: "test" });
+     * // result is enhanced ToolResult with additional metadata
+     * ```
      */
     executeTool<T = unknown>(toolName: string, args?: unknown, context?: ExecutionContext): Promise<T>;
     /**