@juspay/neurolink 3.0.1 → 4.1.0

package/dist/mcp/session-persistence.js

@@ -0,0 +1,299 @@
+/**
+ * NeuroLink Session Persistence Layer
+ * Provides file-based persistence for sessions with atomic writes and recovery
+ */
+import fs from "fs/promises";
+import path from "path";
+import crypto from "crypto";
+import { existsSync } from "fs";
+/**
+ * Session Persistence Manager
+ * Handles saving and loading sessions to/from disk with recovery mechanisms
+ */
+export class SessionPersistence {
+    directory;
+    snapshotInterval;
+    retentionPeriod;
+    enableChecksum;
+    maxRetries;
+    snapshotTimer = null;
+    sessionMap;
+    constructor(sessionMap, options = {}) {
+        this.sessionMap = sessionMap;
+        this.directory = options.directory || ".neurolink/sessions";
+        this.snapshotInterval = options.snapshotInterval || 30000; // 30 seconds
+        this.retentionPeriod = options.retentionPeriod || 86400000; // 24 hours
+        this.enableChecksum = options.enableChecksum ?? true;
+        this.maxRetries = options.maxRetries || 3;
+    }
+    /**
+     * Initialize persistence layer
+     */
+    async initialize() {
+        // Create sessions directory if it doesn't exist
+        await this.ensureDirectory();
+        // Load existing sessions
+        await this.loadSessions();
+        // Start snapshot timer
+        this.startSnapshotTimer();
+        if (process.env.NEUROLINK_DEBUG === "true") {
+            console.log(`[SessionPersistence] Initialized with directory: ${this.directory}`);
+        }
+    }
+    /**
+     * Ensure sessions directory exists
+     */
+    async ensureDirectory() {
+        await fs.mkdir(this.directory, { recursive: true });
+    }
+    /**
+     * Calculate checksum for data integrity
+     */
+    calculateChecksum(data) {
+        return crypto.createHash("sha256").update(data).digest("hex");
+    }
+    /**
+     * Serialize session to JSON with metadata
+     */
+    serializeSession(session) {
+        // Convert Map to array for JSON serialization
+        const sessionData = {
+            ...session,
+            state: Array.from(session.state.entries()),
+        };
+        let fileData = {
+            session: sessionData,
+            checksum: "",
+            version: "1.0",
+            lastSaved: Date.now(),
+        };
+        if (this.enableChecksum) {
+            // First serialization without checksum
+            const tempJsonData = JSON.stringify(fileData, null, 2);
+            // Calculate checksum based on the first serialization
+            fileData.checksum = this.calculateChecksum(tempJsonData);
+        }
+        // Final serialization with checksum included
+        return JSON.stringify(fileData, null, 2);
+    }
+    /**
+     * Deserialize session from JSON
+     */
+    deserializeSession(data) {
+        try {
+            const fileData = JSON.parse(data);
+            // Verify checksum if enabled
+            if (this.enableChecksum && fileData.checksum) {
+                const tempData = { ...fileData, checksum: "" };
+                const expectedChecksum = this.calculateChecksum(JSON.stringify(tempData, null, 2));
+                if (fileData.checksum !== expectedChecksum) {
+                    console.error("[SessionPersistence] Checksum mismatch, session corrupted");
+                    return null;
+                }
+            }
+            // Convert state array back to Map
+            const session = fileData.session;
+            session.state = new Map(session.state);
+            return session;
+        }
+        catch (error) {
+            console.error("[SessionPersistence] Failed to deserialize session:", error);
+            return null;
+        }
+    }
+    /**
+     * Save single session with atomic write
+     */
+    async saveSession(sessionId, session) {
+        const filename = `${sessionId}.json`;
+        const filepath = path.join(this.directory, filename);
+        const tempPath = `${filepath}.tmp`;
+        let retries = 0;
+        while (retries < this.maxRetries) {
+            try {
+                // Serialize session
+                const data = this.serializeSession(session);
+                // Write to temporary file first (atomic write pattern)
+                await fs.writeFile(tempPath, data, "utf8");
+                // Rename temp file to final location (atomic operation)
+                await fs.rename(tempPath, filepath);
+                if (process.env.NEUROLINK_DEBUG === "true") {
+                    console.log(`[SessionPersistence] Saved session ${sessionId}`);
+                }
+                return true;
+            }
+            catch (error) {
+                retries++;
+                console.error(`[SessionPersistence] Failed to save session (attempt ${retries}):`, error);
+                // Clean up temp file if it exists
+                try {
+                    await fs.unlink(tempPath);
+                }
+                catch {
+                    // Ignore errors when cleaning up temp file
+                }
+                if (retries < this.maxRetries) {
+                    // Exponential backoff
+                    await new Promise((resolve) => setTimeout(resolve, Math.pow(2, retries) * 100));
+                }
+            }
+        }
+        return false;
+    }
+    /**
+     * Load single session from disk
+     */
+    async loadSession(sessionId) {
+        const filename = `${sessionId}.json`;
+        const filepath = path.join(this.directory, filename);
+        try {
+            const data = await fs.readFile(filepath, "utf8");
+            return this.deserializeSession(data);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT") {
+                console.error(`[SessionPersistence] Failed to load session ${sessionId}:`, error);
+            }
+            return null;
+        }
+    }
+    /**
+     * Load all sessions from disk on startup
+     */
+    async loadSessions() {
+        try {
+            const files = await fs.readdir(this.directory);
+            const sessionFiles = files.filter((f) => f.endsWith(".json"));
+            let loaded = 0;
+            let expired = 0;
+            for (const file of sessionFiles) {
+                const sessionId = file.replace(".json", "");
+                const session = await this.loadSession(sessionId);
+                if (session) {
+                    // Check if session is expired
+                    if (session.expiresAt < Date.now()) {
+                        expired++;
+                        // Clean up expired session file
+                        await this.deleteSession(sessionId);
+                    }
+                    else {
+                        // Restore to memory
+                        this.sessionMap.set(sessionId, session);
+                        loaded++;
+                    }
+                }
+            }
+            console.log(`[SessionPersistence] Loaded ${loaded} sessions, cleaned ${expired} expired sessions`);
+        }
+        catch (error) {
+            console.error("[SessionPersistence] Failed to load sessions:", error);
+        }
+    }
+    /**
+     * Save all active sessions (snapshot)
+     */
+    async saveAllSessions() {
+        const sessions = Array.from(this.sessionMap.entries());
+        // Filter out expired sessions and create save promises
+        const savePromises = sessions
+            .filter(([_, session]) => session.expiresAt >= Date.now())
+            .map(async ([sessionId, session]) => {
+            return (await this.saveSession(sessionId, session)) ? 1 : 0;
+        });
+        // Execute all save operations concurrently
+        const results = await Promise.all(savePromises);
+        const saved = results.reduce((sum, result) => sum + result, 0);
+        if (process.env.NEUROLINK_DEBUG === "true") {
+            console.log(`[SessionPersistence] Snapshot: saved ${saved}/${sessions.length} sessions`);
+        }
+    }
+    /**
+     * Delete session file
+     */
+    async deleteSession(sessionId) {
+        const filename = `${sessionId}.json`;
+        const filepath = path.join(this.directory, filename);
+        try {
+            await fs.unlink(filepath);
+            // Keep memory and disk state in sync
+            this.sessionMap.delete(sessionId);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT") {
+                console.error(`[SessionPersistence] Failed to delete session ${sessionId}:`, error);
+            }
+        }
+    }
+    /**
+     * Clean up old session files
+     */
+    async cleanupOldSessions() {
+        try {
+            const files = await fs.readdir(this.directory);
+            const now = Date.now();
+            let cleaned = 0;
+            for (const file of files) {
+                if (!file.endsWith(".json")) {
+                    continue;
+                }
+                const filepath = path.join(this.directory, file);
+                const stats = await fs.stat(filepath);
+                // Remove files older than retention period
+                if (now - stats.mtimeMs > this.retentionPeriod) {
+                    await fs.unlink(filepath);
+                    cleaned++;
+                }
+            }
+            if (cleaned > 0) {
+                console.log(`[SessionPersistence] Cleaned up ${cleaned} old session files`);
+            }
+        }
+        catch (error) {
+            console.error("[SessionPersistence] Cleanup failed:", error);
+        }
+    }
+    /**
+     * Start periodic snapshot timer
+     */
+    startSnapshotTimer() {
+        if (this.snapshotTimer) {
+            clearInterval(this.snapshotTimer);
+        }
+        this.snapshotTimer = setInterval(async () => {
+            await this.saveAllSessions();
+            await this.cleanupOldSessions();
+        }, this.snapshotInterval);
+    }
+    /**
+     * Stop snapshot timer
+     */
+    stopSnapshotTimer() {
+        if (this.snapshotTimer) {
+            clearInterval(this.snapshotTimer);
+            this.snapshotTimer = null;
+        }
+    }
+    /**
+     * Shutdown persistence layer
+     */
+    async shutdown() {
+        this.stopSnapshotTimer();
+        // Final snapshot before shutdown
+        await this.saveAllSessions();
+        console.log("[SessionPersistence] Shutdown complete");
+    }
+}
+/**
+ * Default session persistence instance
+ */
+export let defaultSessionPersistence = null;
+/**
+ * Initialize default session persistence
+ */
+export async function initializeSessionPersistence(sessionMap, options) {
+    if (!defaultSessionPersistence) {
+        defaultSessionPersistence = new SessionPersistence(sessionMap, options);
+        await defaultSessionPersistence.initialize();
+    }
+    return defaultSessionPersistence;
+}

package/dist/mcp/tool-integration.js

@@ -93,7 +93,7 @@ export class MCPToolIntegration {
                 results.push({
                     name: toolInfo.name,
                     description: toolInfo.description || "No description available",
-                    serverId: toolInfo.server || "unknown",
+                    serverId: toolInfo.serverId || "unknown",
                     relevance,
                 });
             }

package/dist/mcp/tool-registry.d.ts

@@ -1,40 +1,38 @@
 /**
  * MCP Tool Registry - Extended Registry with Tool Management
+ * Updated to match industry standard camelCase interfaces
  */
-import type { ExecutionContext } from "./contracts/mcp-contract.js";
+import type { ExecutionContext, ToolInfo } from "./contracts/mcpContract.js";
 import type { ToolResult } from "./factory.js";
 import { MCPRegistry } from "./registry.js";
-export interface ToolInfo {
-    id: string;
-    name: string;
-    description?: string;
-    inputSchema?: any;
-    outputSchema?: any;
-    serverId: string;
-    source: "manual" | "auto" | "default";
-    isImplemented?: boolean;
-    server?: string;
-}
 export type ToolExecutionResult = ToolResult;
+/**
+ * Tool execution options
+ */
+export interface ToolExecutionOptions {
+    timeout?: number;
+    retries?: number;
+    context?: ExecutionContext;
+    preferredSource?: string;
+    fallbackEnabled?: boolean;
+    validateBeforeExecution?: boolean;
+    timeoutMs?: number;
+}
 export declare class MCPToolRegistry extends MCPRegistry {
     private tools;
     private toolExecutionStats;
     /**
-     * Register a server with its tools
-     */
-    registerServer(serverId: string, serverInfo: any): Promise<void>;
-    /**
-     * Unregister a server and its tools
+     * Register a server with its tools (updated signature)
      */
-    unregisterServer(serverId: string): Promise<void>;
+    registerServer(serverId: string, serverConfig?: unknown, context?: ExecutionContext): Promise<void>;
     /**
-     * Execute a tool
+     * Execute a tool with enhanced context
      */
-    executeTool(toolName: string, args: any, context: ExecutionContext): Promise<ToolExecutionResult>;
+    executeTool<T = unknown>(toolName: string, args?: unknown, context?: ExecutionContext): Promise<T>;
     /**
-     * List all available tools
+     * List all available tools (updated signature)
      */
-    listTools(): Promise<ToolInfo[]>;
+    listTools(context?: ExecutionContext): Promise<ToolInfo[]>;
     /**
      * Get tool information
      */
@@ -44,23 +42,46 @@ export declare class MCPToolRegistry extends MCPRegistry {
      */
     private updateStats;
     /**
-     * Get tool execution statistics
+     * Get execution statistics
      */
-    getToolStats(toolName?: string): any;
+    getExecutionStats(): Record<string, {
+        count: number;
+        averageTime: number;
+        totalTime: number;
+    }>;
     /**
-     * Get tool execution statistics
+     * Clear execution statistics
      */
-    getStats(): Promise<any>;
+    clearStats(): void;
     /**
-     * Clear all tools and stats
+     * Get tools by category
      */
-    clear(): void;
+    getToolsByCategory(category: string): ToolInfo[];
+    /**
+     * Check if tool exists
+     */
+    hasTool(toolName: string): boolean;
+    /**
+     * Remove a tool
+     */
+    removeTool(toolName: string): boolean;
+    /**
+     * Get tool count
+     */
+    getToolCount(): number;
+    /**
+     * Get statistics (alias for getExecutionStats)
+     */
+    getStats(): Record<string, {
+        count: number;
+        averageTime: number;
+        totalTime: number;
+    }>;
+    /**
+     * Unregister a server
+     */
+    unregisterServer(serverId: string): boolean;
 }
 export declare const toolRegistry: MCPToolRegistry;
 export declare const defaultToolRegistry: MCPToolRegistry;
-export interface ToolExecutionOptions {
-    preferredSource?: string;
-    fallbackEnabled?: boolean;
-    validateBeforeExecution?: boolean;
-    timeoutMs?: number;
-}
+export type { ToolInfo } from "./contracts/mcpContract.js";

package/dist/mcp/tool-registry.js

@@ -1,5 +1,6 @@
 /**
  * MCP Tool Registry - Extended Registry with Tool Management
+ * Updated to match industry standard camelCase interfaces
  */
 import { MCPRegistry } from "./registry.js";
 import { registryLogger } from "./logging.js";
@@ -7,91 +8,74 @@ export class MCPToolRegistry extends MCPRegistry {
     tools = new Map();
     toolExecutionStats = new Map();
     /**
-     * Register a server with its tools
+     * Register a server with its tools (updated signature)
      */
-    async registerServer(serverId, serverInfo) {
+    async registerServer(serverId, serverConfig, context) {
         registryLogger.info(`Registering server: ${serverId}`);
+        // Convert to DiscoveredMcp format for compatibility
+        const plugin = {
+            metadata: {
+                name: serverId,
+                description: typeof serverConfig === "object" && serverConfig
+                    ? serverConfig.description || "No description"
+                    : "No description",
+            },
+            tools: typeof serverConfig === "object" && serverConfig
+                ? serverConfig.tools
+                : {},
+            configuration: typeof serverConfig === "object" && serverConfig
+                ? serverConfig
+                : {},
+        };
+        // Call the parent register method
+        this.register(plugin);
         // Extract tools from server info if available
-        if (serverInfo.tools) {
-            for (const [toolName, toolDef] of Object.entries(serverInfo.tools)) {
-                const toolId = `${serverId}.${toolName}`;
-                this.tools.set(toolId, {
-                    id: toolId,
-                    name: toolName,
-                    description: toolDef.description,
-                    inputSchema: toolDef.inputSchema,
-                    outputSchema: toolDef.outputSchema,
-                    serverId,
-                    server: serverId, // Backward compatibility alias
-                    source: "manual",
-                    isImplemented: true,
-                });
-            }
-        }
-    }
-    /**
-     * Unregister a server and its tools
-     */
-    async unregisterServer(serverId) {
-        registryLogger.info(`Unregistering server: ${serverId}`);
-        // Remove all tools for this server
-        for (const [toolId, toolInfo] of this.tools) {
-            if (toolInfo.serverId === serverId) {
-                this.tools.delete(toolId);
-                this.toolExecutionStats.delete(toolId);
-            }
+        const tools = plugin.tools || {};
+        for (const [toolName, toolDef] of Object.entries(tools)) {
+            const toolId = `${serverId}.${toolName}`;
+            this.tools.set(toolId, {
+                name: toolName,
+                description: toolDef?.description,
+                inputSchema: toolDef?.inputSchema,
+                outputSchema: toolDef?.outputSchema,
+                serverId,
+                category: toolDef?.category || "general",
+            });
         }
     }
     /**
-     * Execute a tool
+     * Execute a tool with enhanced context
      */
     async executeTool(toolName, args, context) {
         const startTime = Date.now();
         try {
-            const toolInfo = this.getToolInfo(toolName);
-            if (!toolInfo) {
-                throw new Error(`Tool not found: ${toolName}`);
-            }
             registryLogger.info(`Executing tool: ${toolName}`);
-            // Get the plugin that provides this tool
-            const plugin = this.get(toolInfo.serverId);
-            if (!plugin) {
-                throw new Error(`Plugin not found for tool: ${toolName}`);
-            }
-            // Execute through the plugin (stub implementation)
-            const result = {
-                success: true,
-                data: `Tool ${toolInfo.name} executed with args: ${JSON.stringify(args)}`,
+            // Create execution context if not provided
+            const execContext = {
+                sessionId: context?.sessionId || crypto.randomUUID(),
+                userId: context?.userId,
+                ...context,
             };
-            const executionTime = Date.now() - startTime;
-            this.updateStats(toolName, executionTime);
-            return {
-                success: true,
-                data: result,
-                metadata: {
-                    toolName,
-                    executionTime,
-                    timestamp: Date.now(),
-                },
+            // Mock execution for now
+            const result = {
+                result: `Mock execution of ${toolName}`,
+                args,
+                context: execContext,
             };
+            // Update statistics
+            const duration = Date.now() - startTime;
+            this.updateStats(toolName, duration);
+            return result;
         }
         catch (error) {
             registryLogger.error(`Tool execution failed: ${toolName}`, error);
-            return {
-                success: false,
-                error: error instanceof Error ? error : new Error(String(error)),
-                metadata: {
-                    toolName,
-                    executionTime: Date.now() - startTime,
-                    timestamp: Date.now(),
-                },
-            };
+            throw error;
         }
     }
     /**
-     * List all available tools
+     * List all available tools (updated signature)
      */
-    async listTools() {
+    async listTools(context) {
         return Array.from(this.tools.values());
     }
     /**
@@ -108,53 +92,83 @@ export class MCPToolRegistry extends MCPRegistry {
             count: 0,
             totalTime: 0,
         };
-        stats.count++;
+        stats.count += 1;
         stats.totalTime += executionTime;
         this.toolExecutionStats.set(toolName, stats);
     }
     /**
-     * Get tool execution statistics
+     * Get execution statistics
      */
-    getToolStats(toolName) {
-        if (toolName) {
-            const stats = this.toolExecutionStats.get(toolName);
-            return stats
-                ? {
-                    ...stats,
-                    averageTime: stats.totalTime / stats.count,
-                }
-                : null;
-        }
-        // Return all stats
-        const allStats = {};
-        for (const [tool, stats] of this.toolExecutionStats) {
-            allStats[tool] = {
-                ...stats,
+    getExecutionStats() {
+        const result = {};
+        for (const [toolName, stats] of this.toolExecutionStats.entries()) {
+            result[toolName] = {
+                count: stats.count,
+                totalTime: stats.totalTime,
                 averageTime: stats.totalTime / stats.count,
             };
         }
-        return allStats;
+        return result;
     }
     /**
-     * Get tool execution statistics
+     * Clear execution statistics
      */
-    async getStats() {
-        const tools = await this.listTools();
-        return {
-            totalTools: tools.length,
-            totalExecutions: Array.from(this.toolExecutionStats.values()).reduce((acc, stats) => acc + stats.count, 0),
-        };
+    clearStats() {
+        this.toolExecutionStats.clear();
     }
     /**
-     * Clear all tools and stats
+     * Get tools by category
      */
-    clear() {
-        super.clear();
-        this.tools.clear();
-        this.toolExecutionStats.clear();
+    getToolsByCategory(category) {
+        return Array.from(this.tools.values()).filter((tool) => tool.category === category);
+    }
+    /**
+     * Check if tool exists
+     */
+    hasTool(toolName) {
+        return this.tools.has(toolName);
+    }
+    /**
+     * Remove a tool
+     */
+    removeTool(toolName) {
+        const removed = this.tools.delete(toolName);
+        if (removed) {
+            this.toolExecutionStats.delete(toolName);
+            registryLogger.info(`Removed tool: ${toolName}`);
+        }
+        return removed;
+    }
+    /**
+     * Get tool count
+     */
+    getToolCount() {
+        return this.tools.size;
+    }
+    /**
+     * Get statistics (alias for getExecutionStats)
+     */
+    getStats() {
+        return this.getExecutionStats();
+    }
+    /**
+     * Unregister a server
+     */
+    unregisterServer(serverId) {
+        // Remove all tools for this server
+        const removedTools = [];
+        for (const [toolId, tool] of this.tools.entries()) {
+            if (tool.serverId === serverId) {
+                this.tools.delete(toolId);
+                removedTools.push(toolId);
+            }
+        }
+        // Remove from parent registry
+        const removed = this.unregister(serverId);
+        registryLogger.info(`Unregistered server ${serverId}, removed ${removedTools.length} tools`);
+        return removed;
     }
 }
-// Export singleton instance
+// Create default instance
 export const toolRegistry = new MCPToolRegistry();
-// Additional exports for backward compatibility
 export const defaultToolRegistry = toolRegistry;