@juspay/neurolink 9.26.2 → 9.28.0

package/dist/neurolink.d.ts

@@ -9,11 +9,12 @@ import { type CompactionConfig, type CompactionResult } from "./context/contextC
 import { ConversationMemoryManager } from "./core/conversationMemoryManager.js";
 import type { RedisConversationMemoryManager } from "./core/redisConversationMemoryManager.js";
 import { ExternalServerManager } from "./mcp/externalServerManager.js";
+import type { MCPToolAnnotations } from "./mcp/toolAnnotations.js";
 import { MCPToolRegistry } from "./mcp/toolRegistry.js";
 import type { MetricsSummary, TraceView } from "./observability/metricsAggregator.js";
 import type { SpanData } from "./observability/types/spanTypes.js";
 import type { JsonObject, NeuroLinkEvents, TypedEventEmitter } from "./types/common.js";
-import type { NeurolinkConstructorConfig } from "./types/configTypes.js";
+import type { MCPEnhancementsConfig, NeurolinkConstructorConfig } from "./types/configTypes.js";
 import type { ChatMessage } from "./types/conversation.js";
 import type { ExternalMCPOperationResult, ExternalMCPServerInstance, ExternalMCPToolInfo } from "./types/externalMcp.js";
 import type { GenerateOptions, GenerateResult } from "./types/generateTypes.js";
@@ -36,6 +37,13 @@ export declare class NeuroLink {
     private lastCompactionMessageCount;
     /** Extract sessionId from options context for compaction watermark keying */
     private getCompactionSessionId;
+    private mcpToolResultCache?;
+    private mcpToolRouter?;
+    private mcpToolBatcher?;
+    private mcpEnhancedDiscovery?;
+    private mcpToolMiddlewares;
+    private _disableToolCacheForCurrentRequest;
+    private mcpEnhancementsConfig?;
     private toolCircuitBreakers;
     private toolExecutionMetrics;
     private currentStreamToolExecutions;
@@ -157,6 +165,11 @@ export declare class NeuroLink {
      * Initialize HITL (Human-in-the-Loop) if enabled
      */
     private initializeHITL;
+    /**
+     * Initialize MCP enhancement modules (cache, router, batcher, discovery).
+     * Wires standalone MCP modules into the core SDK execution path.
+     */
+    private initializeMCPEnhancements;
     /**
      * Register file reference tools with the MCP tool registry.
      *
@@ -921,6 +934,25 @@ export declare class NeuroLink {
      * @returns true if the tool was removed, false if it didn't exist
      */
     unregisterTool(name: string): boolean;
+    /**
+     * Register a global tool middleware that runs on every tool execution.
+     * Middleware receives the tool, params, context, and a next() function.
+     * @param middleware - The middleware function to register
+     * @returns this (for chaining)
+     */
+    useToolMiddleware(middleware: import("./mcp/toolIntegration.js").ToolMiddleware): this;
+    /**
+     * Get all registered tool middlewares
+     */
+    getToolMiddlewares(): import("./mcp/toolIntegration.js").ToolMiddleware[];
+    /**
+     * Flush any pending batched tool calls immediately
+     */
+    flushToolBatch(): Promise<void>;
+    /**
+     * Get the current MCP enhancements configuration
+     */
+    getMCPEnhancementsConfig(): MCPEnhancementsConfig | undefined;
     /**
      * Update agentic loop report metadata for a conversation session.
      * Upserts a report entry by reportId — updates existing or adds new.
@@ -996,6 +1028,10 @@ export declare class NeuroLink {
         timeout?: number;
         maxRetries?: number;
         retryDelayMs?: number;
+        /** Disable tool result caching for this call */
+        disableToolCache?: boolean;
+        /** Bypass the request batcher for this call */
+        bypassBatcher?: boolean;
         authContext?: {
             userId?: string;
             sessionId?: string;
@@ -1004,9 +1040,18 @@ export declare class NeuroLink {
         };
     }): Promise<T>;
     /**
-     * Internal tool execution method (extracted for better error handling)
+     * Internal tool execution method with MCP enhancements wired in:
+     * - ToolCache: check/store cached results for non-destructive tools
+     * - ToolRouter: route to best server when same tool exists on multiple servers
+     * - Annotations: skip cache for destructive tools, retry safe tools on failure
+     * - Middleware: apply global middleware chain before execution
      */
     private executeToolInternal;
+    /**
+     * Get tool annotations for execution decisions (cache, retry).
+     * Checks cached tool list first, falls back to inference from tool name.
+     */
+    private getToolAnnotationsForExecution;
     /**
      * Get all available tools including custom and in-memory ones
      * @returns Array of available tools with metadata
@@ -1343,6 +1388,234 @@ export declare class NeuroLink {
      * Called automatically on process exit
      */
     shutdownExternalMCPServers(): Promise<void>;
+    /**
+     * Get the global elicitation manager for interactive tool input
+     * Elicitation allows tools to request additional information from users during execution
+     * @returns The global ElicitationManager instance
+     * @example
+     * ```typescript
+     * const elicitationManager = neurolink.getElicitationManager();
+     *
+     * // Register a handler for confirmations
+     * elicitationManager.registerHandler(async (request) => {
+     *   if (request.type === 'confirmation') {
+     *     const answer = await askUser(request.message);
+     *     return { confirmed: answer === 'yes' };
+     *   }
+     * });
+     * ```
+     */
+    getElicitationManager(): Promise<any>;
+    /**
+     * Register an elicitation handler for interactive tool input
+     * Handlers are called when tools need user input during execution
+     * @param handler - Function to handle elicitation requests
+     * @example
+     * ```typescript
+     * neurolink.registerElicitationHandler(async (request) => {
+     *   switch (request.type) {
+     *     case 'confirmation':
+     *       return { confirmed: await confirmWithUser(request.message) };
+     *     case 'text':
+     *       return { value: await promptUser(request.message) };
+     *     case 'select':
+     *       return { value: await selectFromOptions(request.options) };
+     *   }
+     * });
+     * ```
+     */
+    registerElicitationHandler(handler: (request: unknown) => Promise<unknown>): Promise<void>;
+    /**
+     * Get the multi-server manager for load balancing and coordination
+     * Allows managing multiple MCP servers with failover and load balancing
+     * @returns The global MultiServerManager instance
+     * @example
+     * ```typescript
+     * const multiServer = neurolink.getMultiServerManager();
+     *
+     * // Create a server group with load balancing
+     * await multiServer.createServerGroup('ai-tools', {
+     *   servers: ['openai-server', 'anthropic-server'],
+     *   strategy: 'round-robin'
+     * });
+     * ```
+     */
+    getMultiServerManager(): Promise<any>;
+    /**
+     * Get the enhanced tool discovery service
+     * Provides advanced search, filtering, and compatibility checking for tools
+     * @returns EnhancedToolDiscovery instance
+     * @example
+     * ```typescript
+     * const discovery = neurolink.getEnhancedToolDiscovery();
+     *
+     * // Search for tools by criteria
+     * const results = await discovery.searchTools({
+     *   category: 'data-processing',
+     *   capabilities: ['streaming', 'batch'],
+     *   minReliability: 0.9
+     * });
+     * ```
+     */
+    getEnhancedToolDiscovery(): Promise<any>;
+    /**
+     * Get the MCP registry client for discovering servers from registries
+     * Supports multiple registry sources (official, community, custom)
+     * @returns The global MCPRegistryClient instance
+     * @example
+     * ```typescript
+     * const registryClient = neurolink.getMCPRegistryClient();
+     *
+     * // Search for servers
+     * const servers = await registryClient.searchServers({
+     *   query: 'database',
+     *   categories: ['data', 'storage']
+     * });
+     *
+     * // Get a well-known server config
+     * const githubServer = registryClient.getWellKnownServer('github');
+     * ```
+     */
+    getMCPRegistryClient(): Promise<any>;
+    /**
+     * Expose a NeuroLink agent as an MCP tool
+     * This allows agents to be called by other systems via MCP
+     * @param agent - The agent to expose (must include id, name, description, and execute)
+     * @param options - Exposure configuration options (prefix, defaultAnnotations, etc.)
+     * @returns The exposed tool definition
+     * @example
+     * ```typescript
+     * const agent = {
+     *   id: 'my-agent',
+     *   name: 'My Agent',
+     *   description: 'An agent that processes data',
+     *   execute: async (params) => { ... }
+     * };
+     * const tool = await neurolink.exposeAgentAsTool(agent, {
+     *   prefix: 'agent_'
+     * });
+     * ```
+     */
+    exposeAgentAsTool(agent: {
+        id: string;
+        name: string;
+        description: string;
+        execute: (params: unknown, context?: unknown) => Promise<unknown>;
+    }, options?: {
+        prefix?: string;
+        includeMetadataInDescription?: boolean;
+        wrapWithContext?: boolean;
+        executionTimeout?: number;
+        enableLogging?: boolean;
+    }): Promise<import("./index.js").ExposureResult>;
+    /**
+     * Expose a workflow as an MCP tool
+     * This allows workflows to be called by other systems via MCP
+     * @param workflow - The workflow to expose (must include id, name, description, and execute)
+     * @param options - Exposure configuration options (prefix, defaultAnnotations, etc.)
+     * @returns The exposed tool definition
+     * @example
+     * ```typescript
+     * const workflow = {
+     *   id: 'data-pipeline',
+     *   name: 'Data Pipeline',
+     *   description: 'Runs the data processing pipeline',
+     *   execute: async (params) => { ... }
+     * };
+     * const tool = await neurolink.exposeWorkflowAsTool(workflow, {
+     *   prefix: 'workflow_'
+     * });
+     * ```
+     */
+    exposeWorkflowAsTool(workflow: {
+        id: string;
+        name: string;
+        description: string;
+        execute: (params: unknown, context?: unknown) => Promise<unknown>;
+        steps?: Array<{
+            id: string;
+            name: string;
+            description?: string;
+        }>;
+    }, options?: {
+        prefix?: string;
+        includeMetadataInDescription?: boolean;
+        wrapWithContext?: boolean;
+        executionTimeout?: number;
+        enableLogging?: boolean;
+    }): Promise<import("./index.js").ExposureResult>;
+    /**
+     * Get the tool integration manager for middleware and elicitation
+     * Provides advanced tool wrapping with confirmation, timeout, retry, etc.
+     * @returns The global ToolIntegrationManager instance
+     * @example
+     * ```typescript
+     * const integration = neurolink.getToolIntegrationManager();
+     *
+     * // Register a tool with middleware
+     * integration.registerTool(myTool, {
+     *   timeout: 30000,
+     *   retries: 3,
+     *   requireConfirmation: true
+     * });
+     * ```
+     */
+    getToolIntegrationManager(): Promise<any>;
+    /**
+     * Convert NeuroLink tools to MCP format
+     * Useful for exposing local tools to external MCP clients
+     * @param tools - Array of NeuroLink tool definitions
+     * @param options - Conversion options
+     * @returns Array of MCP-formatted tools
+     * @example
+     * ```typescript
+     * const mcpTools = neurolink.convertToolsToMCPFormat([
+     *   { name: 'myTool', description: 'Does something', execute: async () => {} }
+     * ]);
+     * ```
+     */
+    convertToolsToMCPFormat(tools: Array<{
+        name: string;
+        description: string;
+        execute?: (params: unknown) => unknown;
+    }>, options?: {
+        namespacePrefix?: string;
+    }): Promise<any>;
+    /**
+     * Convert MCP tools to NeuroLink format
+     * Useful for importing tools from external MCP servers
+     * @param tools - Array of MCP tool definitions
+     * @param options - Conversion options
+     * @returns Array of NeuroLink-formatted tools
+     * @example
+     * ```typescript
+     * const neurolinkTools = neurolink.convertToolsFromMCPFormat(externalTools, {
+     *   removeNamespacePrefix: 'external_'
+     * });
+     * ```
+     */
+    convertToolsFromMCPFormat(tools: Array<{
+        name: string;
+        description: string;
+        inputSchema?: unknown;
+    }>, options?: {
+        removeNamespacePrefix?: string;
+    }): Promise<any>;
+    /**
+     * Get tool annotations and safety information
+     * Provides insights about tool behavior, safety levels, and retry-ability
+     * @param toolName - Name of the tool to analyze
+     * @returns Tool annotation summary
+     * @example
+     * ```typescript
+     * const annotations = await neurolink.getToolAnnotations('deleteFile');
+     * // Returns: { destructive: true, requiresConfirmation: true, safeToRetry: false }
+     * ```
+     */
+    getToolAnnotations(toolName: string): Promise<{
+        annotations: MCPToolAnnotations;
+        summary: string;
+    } | null>;
     /**
      * Convert external MCP tools to Vercel AI SDK tool format
      * This allows AI providers to use external tools directly