@juspay/neurolink 4.0.0 → 4.1.0

package/dist/lib/mcp/dynamic-orchestrator.js

@@ -0,0 +1,351 @@
+/**
+ * NeuroLink Dynamic AI-Driven Tool Orchestrator
+ * Enables AI to dynamically select and execute tools based on task requirements
+ * Based on patterns from reference implementations
+ */
+import { MCPOrchestrator } from "./orchestrator.js";
+import { createExecutionContext } from "./context-manager.js";
+import { ErrorCategory, ErrorSeverity } from "./error-manager.js";
+import { aiCoreServer } from "./servers/ai-providers/ai-core-server.js";
+/**
+ * AI prompt templates for tool selection
+ */
+const TOOL_SELECTION_PROMPT = `You are an intelligent tool orchestrator. Analyze the user's request and available tools to determine the best tool to use next.
+
+User Request: {prompt}
+
+Available Tools:
+{tools}
+
+Previous Results:
+{previousResults}
+
+Based on the request and previous results, select the most appropriate tool to use next.
+Respond with a JSON object containing:
+- toolName: The exact name of the tool to use
+- args: An object containing the arguments for the tool
+- reasoning: Brief explanation of why this tool was chosen
+- confidence: A number between 0 and 1 indicating your confidence in this choice
+- shouldContinue: Boolean indicating if more tools should be executed after this one
+
+Example response:
+{
+  "toolName": "search-code",
+  "args": {"query": "function calculateTotal", "path": "/src"},
+  "reasoning": "Need to find the calculateTotal function to understand the calculation logic",
+  "confidence": 0.9,
+  "shouldContinue": true
+}`;
+/**
+ * Dynamic orchestrator with AI-driven tool selection
+ */
+export class DynamicOrchestrator extends MCPOrchestrator {
+    constructor(registry, contextManager, semaphoreManager, sessionManager, errorManager) {
+        super(registry, contextManager, semaphoreManager, sessionManager, errorManager);
+    }
+    defaultOptions = {
+        maxIterations: 10,
+        requireConfidence: 0.7,
+        includeReasoning: true,
+        allowParallel: false,
+    };
+    /**
+     * Execute a dynamic tool chain where AI decides which tools to use
+     *
+     * @param prompt User's task or request
+     * @param contextRequest Context creation request
+     * @param options Dynamic execution options
+     * @returns Dynamic tool chain result
+     */
+    async executeDynamicToolChain(prompt, contextRequest = {}, options = {}) {
+        const startTime = Date.now();
+        const mergedOptions = { ...this.defaultOptions, ...options };
+        const results = [];
+        const decisions = [];
+        let error;
+        let iterations = 0;
+        let session;
+        try {
+            // Create or get session
+            const context = await this.contextManager.createContext(contextRequest);
+            session = await this.sessionManager.createSession(context);
+            // Get available tools
+            const availableTools = await this.registry.listTools(context);
+            const toolsDescription = availableTools
+                .map((tool) => `- ${tool.name}: ${tool.description || "No description"}`)
+                .join("\n");
+            let shouldContinue = true;
+            while (shouldContinue &&
+                iterations < (mergedOptions.maxIterations || 10)) {
+                iterations++;
+                // Prepare context for AI decision
+                const previousResultsSummary = results
+                    .slice(-3) // Last 3 results for context
+                    .map((r, i) => {
+                    const resultData = r.success && r.data ? JSON.stringify(r.data) : "No data";
+                    const summary = resultData.length > 200
+                        ? resultData.slice(0, 200) + "..."
+                        : resultData;
+                    return `Result ${i + 1}: ${summary}`;
+                })
+                    .join("\n");
+                // Get AI decision on next tool
+                const decision = await this.getAIToolDecision(prompt, toolsDescription, previousResultsSummary, mergedOptions.customSystemPrompt);
+                // Add decision to array if includeReasoning is true
+                if (mergedOptions.includeReasoning) {
+                    decisions.push(decision);
+                }
+                // Validate confidence threshold
+                if (decision.confidence < (mergedOptions.requireConfidence || 0.7)) {
+                    if (process.env.NEUROLINK_DEBUG === "true") {
+                        console.log(`[DynamicOrchestrator] Low confidence (${decision.confidence}), stopping execution`);
+                    }
+                    shouldContinue = false;
+                    break;
+                }
+                shouldContinue = decision.shouldContinue;
+                // Execute the selected tool
+                try {
+                    const toolResult = await this.registry.executeTool(decision.toolName, decision.args, context);
+                    results.push({
+                        success: true,
+                        data: toolResult,
+                        metadata: {
+                            toolName: decision.toolName,
+                            executionTime: Date.now() - startTime,
+                        },
+                    });
+                    // Update session with tool result
+                    session.toolHistory.push({
+                        success: true,
+                        data: toolResult,
+                        metadata: {
+                            toolName: decision.toolName,
+                            executionTime: Date.now() - startTime,
+                        },
+                    });
+                }
+                catch (toolError) {
+                    const errorResult = {
+                        success: false,
+                        error: toolError instanceof Error
+                            ? toolError
+                            : new Error(String(toolError)),
+                        metadata: {
+                            toolName: decision.toolName,
+                            executionTime: Date.now() - startTime,
+                        },
+                    };
+                    results.push(errorResult);
+                    session.toolHistory.push(errorResult);
+                    // Let AI decide if it should continue after error
+                    if (!decision.shouldContinue) {
+                        break;
+                    }
+                }
+                // Safety check for infinite loops
+                if (iterations >= (mergedOptions.maxIterations || 10)) {
+                    if (process.env.NEUROLINK_DEBUG === "true") {
+                        console.log(`[DynamicOrchestrator] Reached max iterations (${mergedOptions.maxIterations})`);
+                    }
+                    break;
+                }
+            }
+            // Generate final output based on all results
+            const finalOutput = await this.generateFinalOutput(prompt, results, decisions);
+            return {
+                success: true,
+                iterations,
+                results,
+                decisions: mergedOptions.includeReasoning ? decisions : [],
+                finalOutput,
+                totalDuration: Date.now() - startTime,
+            };
+        }
+        catch (err) {
+            error = err instanceof Error ? err : new Error(String(err));
+            // Record error
+            this.errorManager.recordError(error, {
+                category: ErrorCategory.TOOL_ERROR,
+                severity: ErrorSeverity.HIGH,
+                toolName: "dynamic-orchestrator",
+                sessionId: session?.id,
+            });
+            return {
+                success: false,
+                iterations,
+                results,
+                decisions: mergedOptions.includeReasoning ? decisions : [],
+                error,
+                totalDuration: Date.now() - startTime,
+            };
+        }
+        finally {
+            // Update session activity if session was created
+            if (session) {
+                session.lastActivity = Date.now();
+            }
+        }
+    }
+    /**
+     * Get AI decision on which tool to use next
+     *
+     * @private
+     */
+    async getAIToolDecision(prompt, toolsDescription, previousResults, customSystemPrompt) {
+        const systemPrompt = customSystemPrompt ||
+            TOOL_SELECTION_PROMPT.replace("{prompt}", prompt)
+                .replace("{tools}", toolsDescription)
+                .replace("{previousResults}", previousResults || "None yet");
+        try {
+            // Use AI Core Server to get tool decision
+            const generateTextTool = aiCoreServer.tools["generate-text"];
+            if (!generateTextTool) {
+                throw new Error("generate-text tool not found");
+            }
+            const aiResponse = await generateTextTool.execute({
+                prompt: "Select the next tool to execute based on the context provided.",
+                systemPrompt,
+                provider: "google-ai", // Use fast model for decisions
+                model: "gemini-2.5-flash",
+                temperature: 0.3, // Lower temperature for more consistent decisions
+                maxTokens: 500,
+            }, createExecutionContext());
+            // Parse AI response
+            if (!aiResponse.success) {
+                throw new Error(String(aiResponse.error || "AI generation failed"));
+            }
+            const responseText = aiResponse.data?.text || "";
+            // Extract JSON from response (handle markdown code blocks)
+            const jsonMatch = responseText.match(/```json\n?([\s\S]*?)\n?```/) ||
+                responseText.match(/\{[\s\S]*\}/);
+            if (!jsonMatch) {
+                throw new Error("AI response did not contain valid JSON");
+            }
+            const decision = JSON.parse(jsonMatch[1] || jsonMatch[0]);
+            // Validate decision structure
+            if (!decision.toolName || !decision.args) {
+                throw new Error("Invalid tool decision structure");
+            }
+            return {
+                toolName: decision.toolName,
+                args: decision.args || {},
+                reasoning: decision.reasoning || "No reasoning provided",
+                confidence: decision.confidence || 0.8,
+                shouldContinue: decision.shouldContinue !== false,
+            };
+        }
+        catch (error) {
+            // Fallback decision on error
+            if (process.env.NEUROLINK_DEBUG === "true") {
+                console.error("[DynamicOrchestrator] Error getting AI decision:", error);
+            }
+            return {
+                toolName: "list-tools", // Safe default
+                args: {},
+                reasoning: "Error in AI decision, falling back to tool listing",
+                confidence: 0.5,
+                shouldContinue: false,
+            };
+        }
+    }
+    /**
+     * Generate final output based on all execution results
+     *
+     * @private
+     */
+    async generateFinalOutput(prompt, results, decisions) {
+        // Prepare summary of execution
+        const executionSummary = results
+            .map((r, i) => {
+            const decision = decisions[i];
+            const toolName = r.metadata?.toolName || "unknown";
+            const resultData = r.success && r.data ? JSON.stringify(r.data) : "No data";
+            const resultSummary = resultData.length > 300
+                ? resultData.slice(0, 300) + "..."
+                : resultData;
+            return `Step ${i + 1}: ${toolName}
+Reasoning: ${decision?.reasoning || "N/A"}
+Result: ${r.success ? resultSummary : "Error: " + (r.error instanceof Error ? r.error.message : String(r.error))}`;
+        })
+            .join("\n\n");
+        const summaryPrompt = `Based on the following tool execution results, provide a comprehensive answer to the user's request.
+
+User Request: ${prompt}
+
+Execution Summary:
+${executionSummary}
+
+Provide a clear, concise answer that addresses the user's request based on the tool results.`;
+        try {
+            // Use AI to generate final summary
+            const generateTextTool = aiCoreServer.tools["generate-text"];
+            if (!generateTextTool) {
+                throw new Error("generate-text tool not found");
+            }
+            const aiResponse = await generateTextTool.execute({
+                prompt: summaryPrompt,
+                provider: "google-ai",
+                model: "gemini-2.5-pro",
+                temperature: 0.7,
+                maxTokens: 1000,
+            }, createExecutionContext());
+            if (!aiResponse.success) {
+                throw new Error(String(aiResponse.error || "AI generation failed"));
+            }
+            return aiResponse.data?.text || "";
+        }
+        catch (error) {
+            // Fallback to simple summary
+            return `Executed ${results.length} tools to address your request. ${results.filter((r) => r.success).length} succeeded, ${results.filter((r) => !r.success).length} failed.`;
+        }
+    }
+    /**
+     * Execute parallel dynamic tool chains for complex tasks
+     *
+     * @param prompts Multiple prompts to execute in parallel
+     * @param contextRequest Shared context request
+     * @param options Dynamic execution options
+     * @returns Array of dynamic tool chain results
+     */
+    async executeParallelDynamicChains(prompts, contextRequest = {}, options = {}) {
+        if (!options.allowParallel) {
+            throw new Error("Parallel execution not enabled in options");
+        }
+        // Execute all chains in parallel
+        const promises = prompts.map((prompt) => this.executeDynamicToolChain(prompt, contextRequest, options));
+        return Promise.all(promises);
+    }
+    /**
+     * Get statistics including dynamic execution metrics
+     */
+    getStats() {
+        const baseStats = super.getStats();
+        // Add dynamic orchestrator specific stats
+        return {
+            ...baseStats,
+            dynamicOrchestrator: {
+                // Additional metrics can be added here
+                features: {
+                    aiToolSelection: true,
+                    iterativeExecution: true,
+                    parallelSupport: true,
+                    reasoningCapture: true,
+                },
+            },
+        };
+    }
+}
+/**
+ * Create a dynamic orchestrator instance
+ *
+ * @param registry Tool registry
+ * @param contextManager Context manager
+ * @param semaphoreManager Semaphore manager (optional)
+ * @param sessionManager Session manager (optional)
+ * @param errorManager Error manager (optional)
+ * @returns Dynamic orchestrator instance
+ */
+export function createDynamicOrchestrator(registry, contextManager, semaphoreManager, sessionManager, errorManager) {
+    return new DynamicOrchestrator(registry, contextManager, semaphoreManager, sessionManager, errorManager);
+}

package/dist/lib/mcp/error-manager.d.ts

@@ -0,0 +1,254 @@
+/**
+ * NeuroLink MCP Enhanced Error Handling System
+ * Provides comprehensive error tracking, categorization, and debugging capabilities
+ * Based on error accumulation patterns from Cline
+ */
+import type { NeuroLinkExecutionContext } from "./factory.js";
+/**
+ * Error categories for classification
+ */
+export declare enum ErrorCategory {
+    TOOL_ERROR = "TOOL_ERROR",
+    NETWORK_ERROR = "NETWORK_ERROR",
+    VALIDATION_ERROR = "VALIDATION_ERROR",
+    TIMEOUT_ERROR = "TIMEOUT_ERROR",
+    PERMISSION_ERROR = "PERMISSION_ERROR",
+    CONFIGURATION_ERROR = "CONFIGURATION_ERROR",
+    CONNECTION_ERROR = "CONNECTION_ERROR",
+    UNKNOWN_ERROR = "UNKNOWN_ERROR"
+}
+/**
+ * Error severity levels
+ */
+export declare enum ErrorSeverity {
+    LOW = "LOW",
+    MEDIUM = "MEDIUM",
+    HIGH = "HIGH",
+    CRITICAL = "CRITICAL"
+}
+/**
+ * Enhanced error entry with rich context
+ */
+export interface ErrorEntry {
+    id: string;
+    timestamp: number;
+    category: ErrorCategory;
+    severity: ErrorSeverity;
+    error: Error;
+    context: {
+        sessionId?: string;
+        toolName?: string;
+        parameters?: any;
+        executionContext?: NeuroLinkExecutionContext;
+    };
+    stackTrace?: string;
+    recovery?: {
+        attempted: boolean;
+        successful?: boolean;
+        recovered?: boolean;
+        fallbackUsed?: boolean;
+        nextAction?: string;
+        delay?: number;
+        suggestion?: string;
+    };
+}
+/**
+ * Error statistics
+ */
+export interface ErrorStats {
+    totalErrors: number;
+    errorsByCategory: Record<ErrorCategory, number>;
+    errorsBySeverity: Record<ErrorSeverity, number>;
+    errorRate: number;
+    lastError?: ErrorEntry;
+    mostFrequentError?: {
+        message: string;
+        count: number;
+        category: ErrorCategory;
+    };
+}
+/**
+ * Options for error manager configuration
+ */
+export interface ErrorManagerOptions {
+    maxHistorySize?: number;
+    enableStackTrace?: boolean;
+    autoRecovery?: boolean;
+    errorRateWindow?: number;
+}
+/**
+ * Enhanced Error Manager with accumulation and analysis capabilities
+ */
+export declare class ErrorManager {
+    private errorHistory;
+    private maxHistorySize;
+    private enableStackTrace;
+    private autoRecovery;
+    private errorRateWindow;
+    private errorCounter;
+    private errorFrequency;
+    private categoryCounts;
+    private severityCounts;
+    private errorRecovery;
+    constructor(options?: ErrorManagerOptions);
+    /**
+     * Record an error with context
+     *
+     * @param error The error to record
+     * @param context Additional context about the error
+     * @returns The created error entry
+     */
+    recordError(error: Error | unknown, context?: {
+        category?: ErrorCategory;
+        severity?: ErrorSeverity;
+        sessionId?: string;
+        toolName?: string;
+        parameters?: any;
+        executionContext?: NeuroLinkExecutionContext;
+    }): Promise<ErrorEntry>;
+    /**
+     * Get error history
+     *
+     * @param filter Optional filter criteria
+     * @returns Filtered error history
+     */
+    getErrorHistory(filter?: {
+        category?: ErrorCategory;
+        severity?: ErrorSeverity;
+        sessionId?: string;
+        toolName?: string;
+        since?: number;
+        limit?: number;
+    }): ErrorEntry[];
+    /**
+     * Get error statistics
+     *
+     * @returns Current error statistics
+     */
+    getStats(): ErrorStats;
+    /**
+     * Clear error history
+     */
+    clearHistory(): void;
+    /**
+     * Get recovery suggestions for an error
+     *
+     * @param error The error entry
+     * @returns Recovery suggestion
+     */
+    getRecoverySuggestion(error: ErrorEntry): string;
+    /**
+     * Categorize error based on message and type
+     *
+     * @private
+     */
+    private categorizeError;
+    /**
+     * Determine error severity
+     *
+     * @private
+     */
+    private determineSeverity;
+    /**
+     * Add error to circular buffer
+     *
+     * @private
+     */
+    private addToHistory;
+    /**
+     * Update error statistics
+     *
+     * @private
+     */
+    private updateStatistics;
+    /**
+     * Attempt automatic recovery
+     *
+     * @private
+     */
+    private attemptRecovery;
+    /**
+     * Generate unique error ID
+     *
+     * @private
+     */
+    private generateErrorId;
+    /**
+     * Detect error patterns in recent history
+     *
+     * @param timeWindow Time window to analyze (ms)
+     * @returns Detected patterns with counts and severity
+     */
+    detectPatterns(timeWindow?: number): {
+        patterns: Array<{
+            pattern: string;
+            count: number;
+            errors: ErrorEntry[];
+            severity: ErrorSeverity;
+            recommendation: string;
+        }>;
+        correlations: Array<{
+            error1: string;
+            error2: string;
+            correlation: number;
+        }>;
+    };
+    /**
+     * Detect correlations between errors
+     *
+     * @private
+     */
+    private detectCorrelations;
+    /**
+     * Get error trends over time
+     *
+     * @param bucketSize Time bucket size in ms (default: 1 minute)
+     * @param timeWindow Total time window to analyze
+     * @returns Error counts per time bucket
+     */
+    getErrorTrends(bucketSize?: number, timeWindow?: number): Array<{
+        timestamp: number;
+        count: number;
+        categories: Record<ErrorCategory, number>;
+    }>;
+    /**
+     * Get recovery statistics
+     *
+     * @returns Recovery statistics from error recovery system
+     */
+    getRecoveryStats(): {
+        totalAttempts: number;
+        successfulRecoveries: number;
+        failedRecoveries: number;
+        circuitBreakerStates: Record<string, import("./error-recovery.js").CircuitState>;
+        patternMatches: Record<string, number>;
+    };
+    /**
+     * Reset circuit breaker for specific resource
+     *
+     * @param resourceId Resource identifier (usually tool name)
+     */
+    resetCircuitBreaker(resourceId: string): void;
+    /**
+     * Get error insights and recommendations
+     *
+     * @returns Insights based on error analysis
+     */
+    getInsights(): {
+        criticalIssues: string[];
+        recommendations: string[];
+        healthScore: number;
+    };
+}
+/**
+ * Default error manager instance
+ */
+export declare const defaultErrorManager: ErrorManager;
+/**
+ * Utility function to record error with default manager
+ *
+ * @param error Error to record
+ * @param context Error context
+ * @returns Error entry
+ */
+export declare function recordError(error: Error | unknown, context?: Parameters<ErrorManager["recordError"]>[1]): Promise<ErrorEntry>;