@juspay/neurolink 4.0.0 → 4.1.0

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

@@ -2,10 +2,16 @@
  * NeuroLink MCP Tool Orchestration Engine
  * Central orchestrator for coordinated tool execution with pipeline management
  * Coordinates factory, registry, context, and AI tools for seamless operation
+ * Now with semaphore-based race condition prevention
  */
 import type { ToolResult } from "./factory.js";
 import { MCPToolRegistry, type ToolExecutionOptions } from "./tool-registry.js";
 import { ContextManager, type ContextRequest } from "./context-manager.js";
+import { SemaphoreManager } from "./semaphore-manager.js";
+import { SessionManager, type OrchestratorSession, type SessionOptions } from "./session-manager.js";
+import { ErrorManager } from "./error-manager.js";
+import { HealthMonitor, type HealthMonitorOptions } from "./health-monitor.js";
+import { TransportManager, type TransportConfig, type TransportManagerOptions } from "./transport-manager.js";
 /**
  * Pipeline execution options
  */
@@ -67,10 +73,15 @@ export interface TextPipelineResult {
  * Central coordination engine for tool execution, pipelines, and AI operations
  */
 export declare class MCPOrchestrator {
-    private registry;
-    private contextManager;
-    private pipelineCounter;
-    constructor(registry?: MCPToolRegistry, contextManager?: ContextManager);
+    protected registry: MCPToolRegistry;
+    protected contextManager: ContextManager;
+    protected semaphoreManager: SemaphoreManager;
+    protected sessionManager: SessionManager;
+    protected errorManager: ErrorManager;
+    protected healthMonitor: HealthMonitor | null;
+    protected transportManager: TransportManager | null;
+    protected pipelineCounter: number;
+    constructor(registry?: MCPToolRegistry, contextManager?: ContextManager, semaphoreManager?: SemaphoreManager, sessionManager?: SessionManager, errorManager?: ErrorManager);
     /**
      * Initialize with default servers (AI Core)
      */
@@ -84,7 +95,9 @@ export declare class MCPOrchestrator {
      * @param options Execution options
      * @returns Tool execution result
      */
-    executeTool(toolName: string, params: any, contextRequest?: ContextRequest, options?: ToolExecutionOptions): Promise<ToolResult>;
+    executeTool(toolName: string, params: any, contextRequest?: ContextRequest, options?: ToolExecutionOptions & {
+        sessionOptions?: SessionOptions;
+    }): Promise<ToolResult>;
     /**
      * Execute a pipeline of tools with dependency management
      *
@@ -118,10 +131,128 @@ export declare class MCPOrchestrator {
     getStats(): {
         registry: any;
         context: any;
+        session: any;
+        error: any;
+        health?: any;
         orchestrator: {
             pipelinesExecuted: number;
         };
     };
+    /**
+     * Get session by ID
+     *
+     * @param sessionId Session identifier
+     * @param extend Whether to extend session expiration
+     * @returns Session or null if not found
+     */
+    getSession(sessionId: string, extend?: boolean): Promise<OrchestratorSession | null>;
+    /**
+     * Create a new session for continuous tool calling
+     *
+     * @param contextRequest Context creation request
+     * @param sessionOptions Session configuration options
+     * @returns Created session
+     */
+    createSession(contextRequest?: ContextRequest, sessionOptions?: SessionOptions): Promise<OrchestratorSession>;
+    /**
+     * Set session state value
+     *
+     * @param sessionId Session identifier
+     * @param key State key
+     * @param value State value
+     * @returns Success status
+     */
+    setSessionState(sessionId: string, key: string, value: any): Promise<boolean>;
+    /**
+     * Get session state value
+     *
+     * @param sessionId Session identifier
+     * @param key State key
+     * @returns State value or undefined
+     */
+    getSessionState(sessionId: string, key: string): Promise<any>;
+    /**
+     * Get all active sessions
+     *
+     * @returns Array of active sessions
+     */
+    getActiveSessions(): Promise<OrchestratorSession[]>;
+    /**
+     * Clean up expired sessions
+     *
+     * @returns Number of sessions cleaned
+     */
+    cleanupSessions(): Promise<number>;
+    /**
+     * Get error history
+     *
+     * @param filter Optional filter criteria
+     * @returns Filtered error history
+     */
+    getErrorHistory(filter?: Parameters<ErrorManager["getErrorHistory"]>[0]): import("./error-manager.js").ErrorEntry[];
+    /**
+     * Clear error history
+     */
+    clearErrorHistory(): void;
+    /**
+     * Get recovery suggestion for last error
+     *
+     * @param sessionId Optional session ID to get last error from
+     * @returns Recovery suggestion or null
+     */
+    getLastErrorRecovery(sessionId?: string): string | null;
+    /**
+     * Initialize health monitoring
+     *
+     * @param options Health monitor options
+     */
+    initializeHealthMonitor(options?: HealthMonitorOptions): void;
+    /**
+     * Start health monitoring for all registered servers
+     */
+    startHealthMonitoring(): void;
+    /**
+     * Stop health monitoring
+     */
+    stopHealthMonitoring(): void;
+    /**
+     * Register recovery callback for a server
+     *
+     * @param serverId Server ID
+     * @param callback Recovery callback
+     */
+    registerRecoveryCallback(serverId: string, callback: (serverId: string) => Promise<void>): void;
+    /**
+     * Get health status for all servers
+     *
+     * @returns Map of server health status
+     */
+    getHealthStatus(): Map<any, any>;
+    /**
+     * Initialize transport manager for MCP connections
+     *
+     * @param options Transport manager options
+     */
+    initializeTransportManager(options?: TransportManagerOptions): void;
+    /**
+     * Connect to MCP server using specified transport
+     *
+     * @param config Transport configuration
+     * @returns Connected MCP client
+     */
+    connectTransport(config: TransportConfig): Promise<any>;
+    /**
+     * Disconnect from MCP server
+     */
+    disconnectTransport(): Promise<void>;
+    /**
+     * Get transport connection status
+     */
+    getTransportStatus(): import("./transport-manager.js").TransportStatus;
+    /**
+     * Check if transport is connected
+     */
+    isTransportConnected(): boolean;
     /**
      * Execute parallel pipeline with dependency management
      *

package/dist/lib/mcp/orchestrator.js

@@ -2,9 +2,15 @@
  * NeuroLink MCP Tool Orchestration Engine
  * Central orchestrator for coordinated tool execution with pipeline management
  * Coordinates factory, registry, context, and AI tools for seamless operation
+ * Now with semaphore-based race condition prevention
  */
 import { defaultToolRegistry, } from "./tool-registry.js";
 import { defaultContextManager, } from "./context-manager.js";
+import { defaultSemaphoreManager, } from "./semaphore-manager.js";
+import { defaultSessionManager, } from "./session-manager.js";
+import { defaultErrorManager, ErrorCategory, ErrorSeverity, } from "./error-manager.js";
+import { initializeHealthMonitor, } from "./health-monitor.js";
+import { TransportManager, } from "./transport-manager.js";
 import { aiCoreServer } from "./servers/ai-providers/ai-core-server.js";
 /**
  * NeuroLink MCP Tool Orchestrator
@@ -13,10 +19,18 @@ import { aiCoreServer } from "./servers/ai-providers/ai-core-server.js";
 export class MCPOrchestrator {
     registry;
     contextManager;
+    semaphoreManager;
+    sessionManager;
+    errorManager;
+    healthMonitor = null;
+    transportManager = null;
     pipelineCounter = 0;
-    constructor(registry, contextManager) {
+    constructor(registry, contextManager, semaphoreManager, sessionManager, errorManager) {
         this.registry = registry || defaultToolRegistry;
         this.contextManager = contextManager || defaultContextManager;
+        this.semaphoreManager = semaphoreManager || defaultSemaphoreManager;
+        this.sessionManager = sessionManager || defaultSessionManager;
+        this.errorManager = errorManager || defaultErrorManager;
         // Initialize with AI Core Server
         this.initializeDefaultServers();
     }
@@ -47,15 +61,89 @@ export class MCPOrchestrator {
     async executeTool(toolName, params, contextRequest = {}, options = {}) {
         // Create execution context
         const context = this.contextManager.createContext(contextRequest);
+        // Get or create session for continuous tool calling
+        let session = null;
+        if (context.sessionId) {
+            session = await this.sessionManager.getSession(context.sessionId);
+        }
+        if (!session) {
+            // Create new session with options
+            session = await this.sessionManager.createSession(context, options.sessionOptions);
+            // Update context with new session ID
+            context.sessionId = session.id;
+        }
         if (process.env.NEUROLINK_DEBUG === "true") {
             console.log(`[Orchestrator] Executing tool '${toolName}' in session ${context.sessionId}`);
         }
-        // Execute tool through registry
-        const result = await this.registry.executeTool(toolName, params, context);
-        if (process.env.NEUROLINK_DEBUG === "true") {
-            console.log(`[Orchestrator] Tool '${toolName}' execution ${result.success ? "completed" : "failed"}`);
+        // Use semaphore to prevent race conditions for the same tool
+        // Each tool gets its own semaphore key to allow parallel execution of different tools
+        const semaphoreKey = `tool:${toolName}`;
+        const semaphoreResult = await this.semaphoreManager.acquire(semaphoreKey, async () => {
+            try {
+                // Execute tool through registry
+                const result = await this.registry.executeTool(toolName, params, context);
+                if (process.env.NEUROLINK_DEBUG === "true") {
+                    console.log(`[Orchestrator] Tool '${toolName}' execution ${result.success ? "completed" : "failed"}`);
+                }
+                // Record error if tool execution failed
+                if (!result.success && result.error) {
+                    this.errorManager.recordError(result.error, {
+                        category: ErrorCategory.TOOL_ERROR,
+                        severity: ErrorSeverity.HIGH,
+                        sessionId: session.id,
+                        toolName,
+                        parameters: params,
+                        executionContext: context,
+                    });
+                }
+                return result;
+            }
+            catch (error) {
+                // Record unexpected errors
+                const errorEntry = await this.errorManager.recordError(error, {
+                    category: ErrorCategory.TOOL_ERROR,
+                    severity: ErrorSeverity.CRITICAL,
+                    sessionId: session.id,
+                    toolName,
+                    parameters: params,
+                    executionContext: context,
+                });
+                // Return error result
+                return {
+                    success: false,
+                    data: null,
+                    error: errorEntry.error,
+                    usage: {},
+                };
+            }
+        }, context);
+        // Handle semaphore errors
+        if (!semaphoreResult.success) {
+            const errorResult = {
+                success: false,
+                data: null,
+                error: semaphoreResult.error || new Error("Semaphore acquisition failed"),
+                usage: {
+                    executionTime: semaphoreResult.executionTime,
+                    waitTime: semaphoreResult.waitTime,
+                },
+            };
+            // Update session with error result
+            await this.sessionManager.updateSession(session.id, errorResult);
+            return errorResult;
         }
-        return result;
+        const result = semaphoreResult.result;
+        // Update session with tool result
+        await this.sessionManager.updateSession(session.id, result);
+        // Enhance result with session information
+        return {
+            ...result,
+            sessionId: session.id,
+            sessionData: {
+                toolHistory: session.toolHistory.length,
+                state: Object.fromEntries(session.state),
+            },
+        };
     }
     /**
      * Execute a pipeline of tools with dependency management
@@ -95,7 +183,23 @@ export class MCPOrchestrator {
                     const stepId = step.stepId || `step-${stepsExecuted + 1}`;
                     try {
                         console.log(`[Orchestrator] Executing step: ${stepId} (${step.toolName})`);
-                        const stepResult = await this.registry.executeTool(step.toolName, step.params, context);
+                        // Use semaphore for each tool execution in pipeline
+                        const semaphoreKey = `tool:${step.toolName}`;
+                        const semaphoreResult = await this.semaphoreManager.acquire(semaphoreKey, async () => {
+                            return await this.registry.executeTool(step.toolName, step.params, context);
+                        }, context);
+                        const stepResult = semaphoreResult.success
+                            ? semaphoreResult.result
+                            : {
+                                success: false,
+                                data: null,
+                                error: semaphoreResult.error ||
+                                    new Error("Semaphore acquisition failed"),
+                                usage: {
+                                    executionTime: semaphoreResult.executionTime,
+                                    waitTime: semaphoreResult.waitTime,
+                                },
+                            };
                         results.set(stepId, stepResult);
                         stepsExecuted++;
                         if (!stepResult.success) {
@@ -265,13 +369,200 @@ export class MCPOrchestrator {
      * @returns Comprehensive orchestrator statistics
      */
     getStats() {
-        return {
+        const stats = {
             registry: this.registry.getStats(),
             context: this.contextManager.getStats(),
+            session: this.sessionManager.getStats(),
+            error: this.errorManager.getStats(),
             orchestrator: {
                 pipelinesExecuted: this.pipelineCounter,
             },
         };
+        if (this.healthMonitor) {
+            const healthStatus = this.healthMonitor.getHealthStatus();
+            stats.health = {
+                servers: Array.from(healthStatus.entries()).map(([id, health]) => ({
+                    id,
+                    status: health.status,
+                    checkCount: health.checkCount,
+                    errorCount: health.errorCount,
+                    lastSuccessfulCheck: health.lastSuccessfulCheck,
+                })),
+            };
+        }
+        return stats;
+    }
+    /**
+     * Get session by ID
+     *
+     * @param sessionId Session identifier
+     * @param extend Whether to extend session expiration
+     * @returns Session or null if not found
+     */
+    async getSession(sessionId, extend = true) {
+        return this.sessionManager.getSession(sessionId, extend);
+    }
+    /**
+     * Create a new session for continuous tool calling
+     *
+     * @param contextRequest Context creation request
+     * @param sessionOptions Session configuration options
+     * @returns Created session
+     */
+    async createSession(contextRequest = {}, sessionOptions) {
+        const context = this.contextManager.createContext(contextRequest);
+        return this.sessionManager.createSession(context, sessionOptions);
+    }
+    /**
+     * Set session state value
+     *
+     * @param sessionId Session identifier
+     * @param key State key
+     * @param value State value
+     * @returns Success status
+     */
+    async setSessionState(sessionId, key, value) {
+        return this.sessionManager.setSessionState(sessionId, key, value) !== null;
+    }
+    /**
+     * Get session state value
+     *
+     * @param sessionId Session identifier
+     * @param key State key
+     * @returns State value or undefined
+     */
+    async getSessionState(sessionId, key) {
+        return this.sessionManager.getSessionState(sessionId, key);
+    }
+    /**
+     * Get all active sessions
+     *
+     * @returns Array of active sessions
+     */
+    async getActiveSessions() {
+        return this.sessionManager.getActiveSessions();
+    }
+    /**
+     * Clean up expired sessions
+     *
+     * @returns Number of sessions cleaned
+     */
+    async cleanupSessions() {
+        return this.sessionManager.cleanup();
+    }
+    /**
+     * Get error history
+     *
+     * @param filter Optional filter criteria
+     * @returns Filtered error history
+     */
+    getErrorHistory(filter) {
+        return this.errorManager.getErrorHistory(filter);
+    }
+    /**
+     * Clear error history
+     */
+    clearErrorHistory() {
+        this.errorManager.clearHistory();
+    }
+    /**
+     * Get recovery suggestion for last error
+     *
+     * @param sessionId Optional session ID to get last error from
+     * @returns Recovery suggestion or null
+     */
+    getLastErrorRecovery(sessionId) {
+        const filter = sessionId ? { sessionId, limit: 1 } : { limit: 1 };
+        const errors = this.errorManager.getErrorHistory(filter);
+        if (errors.length > 0) {
+            return this.errorManager.getRecoverySuggestion(errors[0]);
+        }
+        return null;
+    }
+    /**
+     * Initialize health monitoring
+     *
+     * @param options Health monitor options
+     */
+    initializeHealthMonitor(options) {
+        this.healthMonitor = initializeHealthMonitor(this.registry, this.errorManager, options);
+    }
+    /**
+     * Start health monitoring for all registered servers
+     */
+    startHealthMonitoring() {
+        if (!this.healthMonitor) {
+            this.initializeHealthMonitor();
+        }
+        this.healthMonitor.startMonitoring();
+    }
+    /**
+     * Stop health monitoring
+     */
+    stopHealthMonitoring() {
+        this.healthMonitor?.stopMonitoring();
+    }
+    /**
+     * Register recovery callback for a server
+     *
+     * @param serverId Server ID
+     * @param callback Recovery callback
+     */
+    registerRecoveryCallback(serverId, callback) {
+        if (!this.healthMonitor) {
+            this.initializeHealthMonitor();
+        }
+        this.healthMonitor.registerRecoveryCallback(serverId, callback);
+    }
+    /**
+     * Get health status for all servers
+     *
+     * @returns Map of server health status
+     */
+    getHealthStatus() {
+        return this.healthMonitor?.getHealthStatus() || new Map();
+    }
+    /**
+     * Initialize transport manager for MCP connections
+     *
+     * @param options Transport manager options
+     */
+    initializeTransportManager(options) {
+        this.transportManager = new TransportManager(this.errorManager, options);
+    }
+    /**
+     * Connect to MCP server using specified transport
+     *
+     * @param config Transport configuration
+     * @returns Connected MCP client
+     */
+    async connectTransport(config) {
+        if (!this.transportManager) {
+            this.initializeTransportManager();
+        }
+        return this.transportManager.connect(config);
+    }
+    /**
+     * Disconnect from MCP server
+     */
+    async disconnectTransport() {
+        await this.transportManager?.disconnect();
+    }
+    /**
+     * Get transport connection status
+     */
+    getTransportStatus() {
+        return (this.transportManager?.getStatus() || {
+            connected: false,
+            type: "stdio",
+            reconnectAttempts: 0,
+        });
+    }
+    /**
+     * Check if transport is connected
+     */
+    isTransportConnected() {
+        return this.transportManager?.isConnected() || false;
     }
     /**
      * Execute parallel pipeline with dependency management
@@ -306,7 +597,23 @@ export class MCPOrchestrator {
                 executing.add(stepId);
                 const step = stepMap.get(stepId);
                 try {
-                    const result = await this.registry.executeTool(step.toolName, step.params, context);
+                    // Use semaphore for parallel execution to prevent race conditions
+                    const semaphoreKey = `tool:${step.toolName}`;
+                    const semaphoreResult = await this.semaphoreManager.acquire(semaphoreKey, async () => {
+                        return await this.registry.executeTool(step.toolName, step.params, context);
+                    }, context);
+                    const result = semaphoreResult.success
+                        ? semaphoreResult.result
+                        : {
+                            success: false,
+                            data: null,
+                            error: semaphoreResult.error ||
+                                new Error("Semaphore acquisition failed"),
+                            usage: {
+                                executionTime: semaphoreResult.executionTime,
+                                waitTime: semaphoreResult.waitTime,
+                            },
+                        };
                     results.set(stepId, result);
                     if (!result.success) {
                         const error = result.error;

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

@@ -67,6 +67,28 @@ export declare class MCPRegistry implements McpRegistry {
         name: string;
         description?: string;
     }>;
+    /**
+     * List all registered server IDs
+     *
+     * Returns an array of server IDs that are currently registered in the MCP registry.
+     * This complements listTools() by providing server-level information, while listTools()
+     * provides tool-level information across all servers.
+     *
+     * @returns Array of registered server identifier strings
+     * @see listTools() for getting detailed tool information from all servers
+     * @see list() for getting complete server metadata objects
+     *
+     * @example
+     * ```typescript
+     * const serverIds = registry.listServers();
+     * // ['ai-core', 'external-api', 'database-connector']
+     *
+     * // Compare with listTools() for comprehensive overview:
+     * const servers = registry.listServers(); // ['server1', 'server2']
+     * const tools = await registry.listTools(); // [{ name: 'tool1', serverId: 'server1' }, ...]
+     * ```
+     */
+    listServers(): string[];
 }
 /**
  * Enhanced MCP Registry implementation with config integration

package/dist/lib/mcp/registry.js

@@ -113,6 +113,30 @@ export class MCPRegistry {
         }));
         return tools;
     }
+    /**
+     * List all registered server IDs
+     *
+     * Returns an array of server IDs that are currently registered in the MCP registry.
+     * This complements listTools() by providing server-level information, while listTools()
+     * provides tool-level information across all servers.
+     *
+     * @returns Array of registered server identifier strings
+     * @see listTools() for getting detailed tool information from all servers
+     * @see list() for getting complete server metadata objects
+     *
+     * @example
+     * ```typescript
+     * const serverIds = registry.listServers();
+     * // ['ai-core', 'external-api', 'database-connector']
+     *
+     * // Compare with listTools() for comprehensive overview:
+     * const servers = registry.listServers(); // ['server1', 'server2']
+     * const tools = await registry.listTools(); // [{ name: 'tool1', serverId: 'server1' }, ...]
+     * ```
+     */
+    listServers() {
+        return Array.from(this.plugins.keys());
+    }
 }
 /**
  * Enhanced MCP Registry implementation with config integration