@juspay/neurolink 4.0.0 → 4.1.1

package/dist/mcp/session-manager.js

@@ -0,0 +1,400 @@
+/**
+ * NeuroLink MCP Session Management System
+ * Enables continuous tool calling with persistent state across executions
+ * Based on patterns from Cline's session management implementation
+ */
+import { v4 as uuidv4 } from "uuid";
+import { SessionPersistence, initializeSessionPersistence, } from "./session-persistence.js";
+/**
+ * Session Manager for maintaining state across tool executions
+ * Implements session lifecycle management with automatic cleanup
+ */
+export class SessionManager {
+    sessions = new Map();
+    sessionCounter = 0;
+    stats = {
+        activeSessions: 0,
+        totalSessionsCreated: 0,
+        totalSessionsExpired: 0,
+        averageSessionDuration: 0,
+        averageToolsPerSession: 0,
+        peakConcurrentSessions: 0,
+        lastCleanup: Date.now(),
+    };
+    cleanupInterval = null;
+    defaultTTL = 3600000; // 1 hour default
+    cleanupIntervalMs = 300000; // 5 minutes
+    persistence = null;
+    persistenceEnabled = false;
+    constructor(defaultTTL, cleanupIntervalMs, autoCleanup = true, enablePersistence = true) {
+        if (defaultTTL) {
+            this.defaultTTL = defaultTTL;
+        }
+        if (cleanupIntervalMs) {
+            this.cleanupIntervalMs = cleanupIntervalMs;
+        }
+        if (autoCleanup) {
+            this.startAutoCleanup();
+        }
+        this.persistenceEnabled = enablePersistence;
+    }
+    /**
+     * Initialize session manager with persistence
+     */
+    async initialize(persistenceOptions) {
+        if (this.persistenceEnabled && !this.persistence) {
+            this.persistence = await initializeSessionPersistence(this.sessions, persistenceOptions);
+            if (process.env.NEUROLINK_DEBUG === "true") {
+                console.log("[SessionManager] Persistence layer initialized");
+            }
+        }
+    }
+    /**
+     * Create a new session
+     *
+     * @param context Execution context for the session
+     * @param options Session configuration options
+     * @returns Created session
+     */
+    createSession(context, options = {}) {
+        const sessionId = options.metadata?.tags?.includes("custom-id") && context.sessionId
+            ? context.sessionId
+            : this.generateSessionId();
+        const now = Date.now();
+        const ttl = options.ttl || this.defaultTTL;
+        const session = {
+            id: sessionId,
+            context: {
+                ...context,
+                sessionId, // Ensure context has the session ID
+            },
+            toolHistory: [],
+            state: new Map(),
+            metadata: options.metadata || {},
+            createdAt: now,
+            lastActivity: now,
+            expiresAt: now + ttl,
+        };
+        this.sessions.set(sessionId, session);
+        this.updateStats("create");
+        // Save to disk if persistence is enabled
+        if (this.persistence) {
+            this.persistence.saveSession(sessionId, session).catch(console.error);
+        }
+        if (process.env.NEUROLINK_DEBUG === "true") {
+            console.log(`[SessionManager] Created session ${sessionId} with TTL ${ttl}ms`);
+        }
+        return session;
+    }
+    /**
+     * Get an existing session
+     *
+     * @param sessionId Session identifier
+     * @param extend Whether to extend the session's expiration
+     * @returns Session if found and not expired
+     */
+    getSession(sessionId, extend = true) {
+        let session = this.sessions.get(sessionId) || null;
+        // For sync compatibility, skip disk loading in getSession
+        // Use async getSessionAsync() for full persistence features
+        if (!session) {
+            return null;
+        }
+        // Check if expired
+        if (session.expiresAt < Date.now()) {
+            this.removeSession(sessionId);
+            return null;
+        }
+        // Update activity and optionally extend expiration
+        session.lastActivity = Date.now();
+        if (extend) {
+            const ttl = session.expiresAt - session.createdAt;
+            session.expiresAt = Date.now() + ttl;
+            // Save updated expiration to disk
+            if (this.persistence) {
+                this.persistence.saveSession(sessionId, session).catch(console.error);
+            }
+        }
+        return session;
+    }
+    /**
+     * Update session with new tool result
+     *
+     * @param sessionId Session identifier
+     * @param toolResult Result from tool execution
+     * @returns Updated session or null if not found
+     */
+    updateSession(sessionId, toolResult) {
+        const session = this.getSession(sessionId);
+        if (!session) {
+            return null;
+        }
+        // Add to tool history
+        session.toolHistory.push(toolResult);
+        session.lastActivity = Date.now();
+        // Update stats
+        this.updateStats("update", session);
+        // Save to disk if persistence is enabled
+        if (this.persistence) {
+            this.persistence.saveSession(sessionId, session).catch(console.error);
+        }
+        if (process.env.NEUROLINK_DEBUG === "true") {
+            console.log(`[SessionManager] Updated session ${sessionId} with tool result`);
+        }
+        return session;
+    }
+    /**
+     * Set session state value
+     *
+     * @param sessionId Session identifier
+     * @param key State key
+     * @param value State value
+     * @returns Updated session or null if not found
+     */
+    setSessionState(sessionId, key, value) {
+        const session = this.getSession(sessionId);
+        if (!session) {
+            return null;
+        }
+        session.state.set(key, value);
+        session.lastActivity = Date.now();
+        // Save to disk if persistence is enabled
+        if (this.persistence) {
+            this.persistence.saveSession(sessionId, session).catch(console.error);
+        }
+        return session;
+    }
+    /**
+     * Get session state value
+     *
+     * @param sessionId Session identifier
+     * @param key State key
+     * @returns State value or undefined
+     */
+    getSessionState(sessionId, key) {
+        const session = this.getSession(sessionId, false);
+        return session?.state.get(key);
+    }
+    /**
+     * Remove a session
+     *
+     * @param sessionId Session identifier
+     * @returns True if session was removed
+     */
+    removeSession(sessionId) {
+        const session = this.sessions.get(sessionId);
+        if (!session) {
+            return false;
+        }
+        this.sessions.delete(sessionId);
+        this.updateStats("remove", session);
+        // Delete from disk if persistence is enabled (fire-and-forget)
+        if (this.persistence) {
+            this.persistence.deleteSession(sessionId).catch(console.error);
+        }
+        if (process.env.NEUROLINK_DEBUG === "true") {
+            console.log(`[SessionManager] Removed session ${sessionId}`);
+        }
+        return true;
+    }
+    /**
+     * Clean up expired sessions
+     *
+     * @returns Number of sessions cleaned up
+     */
+    async cleanup() {
+        const now = Date.now();
+        let cleaned = 0;
+        for (const [sessionId, session] of this.sessions) {
+            if (session.expiresAt < now) {
+                this.removeSession(sessionId);
+                cleaned++;
+            }
+        }
+        this.stats.lastCleanup = now;
+        if (cleaned > 0 && process.env.NEUROLINK_DEBUG === "true") {
+            console.log(`[SessionManager] Cleaned up ${cleaned} expired sessions`);
+        }
+        return cleaned;
+    }
+    /**
+     * Get an existing session with async persistence loading
+     *
+     * @param sessionId Session identifier
+     * @param extend Whether to extend the session's expiration
+     * @returns Session if found and not expired, or null
+     */
+    async getSessionAsync(sessionId, extend = true) {
+        let session = this.sessions.get(sessionId) || null;
+        // If not in memory and persistence is enabled, try loading from disk
+        if (!session && this.persistence) {
+            try {
+                session = await this.persistence.loadSession(sessionId);
+                if (session) {
+                    // Add to memory cache
+                    this.sessions.set(sessionId, session);
+                    if (process.env.NEUROLINK_DEBUG === "true") {
+                        console.log(`[SessionManager] Loaded session ${sessionId} from persistence`);
+                    }
+                }
+            }
+            catch (error) {
+                if (process.env.NEUROLINK_DEBUG === "true") {
+                    console.log(`[SessionManager] Failed to load session ${sessionId} from persistence:`, error);
+                }
+            }
+        }
+        if (!session) {
+            return null;
+        }
+        // Check if session has expired
+        if (session.expiresAt < Date.now()) {
+            this.sessions.delete(sessionId);
+            if (this.persistence) {
+                this.persistence.deleteSession(sessionId).catch(console.error);
+            }
+            return null;
+        }
+        // Extend session if requested
+        if (extend && session.expiresAt > Date.now()) {
+            // Calculate remaining TTL and extend by the same amount
+            const remainingTtl = session.expiresAt - Date.now();
+            const originalTtl = session.expiresAt - session.createdAt;
+            if (originalTtl > 0) {
+                session.expiresAt = Date.now() + originalTtl;
+                if (this.persistence) {
+                    this.persistence.saveSession(sessionId, session).catch(console.error);
+                }
+            }
+        }
+        session.lastActivity = Date.now();
+        return session;
+    }
+    /**
+     * Get all active sessions
+     *
+     * @returns Array of active sessions
+     */
+    async getActiveSessions() {
+        await this.cleanup(); // Clean up first
+        return Array.from(this.sessions.values());
+    }
+    /**
+     * Get session statistics
+     *
+     * @returns Session statistics
+     */
+    getStats() {
+        return { ...this.stats };
+    }
+    /**
+     * Clear all sessions
+     */
+    clearAll() {
+        const count = this.sessions.size;
+        this.sessions.clear();
+        this.stats.totalSessionsExpired += count;
+        this.stats.activeSessions = 0;
+        if (process.env.NEUROLINK_DEBUG === "true") {
+            console.log(`[SessionManager] Cleared all ${count} sessions`);
+        }
+    }
+    /**
+     * Start automatic cleanup interval
+     *
+     * @private
+     */
+    startAutoCleanup() {
+        if (this.cleanupInterval) {
+            return;
+        }
+        this.cleanupInterval = setInterval(async () => {
+            await this.cleanup();
+        }, this.cleanupIntervalMs);
+        if (process.env.NEUROLINK_DEBUG === "true") {
+            console.log(`[SessionManager] Started auto-cleanup with ${this.cleanupIntervalMs}ms interval`);
+        }
+    }
+    /**
+     * Stop automatic cleanup interval
+     */
+    stopAutoCleanup() {
+        if (this.cleanupInterval) {
+            clearInterval(this.cleanupInterval);
+            this.cleanupInterval = null;
+            if (process.env.NEUROLINK_DEBUG === "true") {
+                console.log("[SessionManager] Stopped auto-cleanup");
+            }
+        }
+    }
+    /**
+     * Generate unique session ID
+     *
+     * @private
+     */
+    generateSessionId() {
+        this.sessionCounter++;
+        return `nlsess-${Date.now()}-${this.sessionCounter}-${uuidv4().substring(0, 8)}`;
+    }
+    /**
+     * Update statistics
+     *
+     * @private
+     */
+    updateStats(action, session) {
+        switch (action) {
+            case "create":
+                this.stats.totalSessionsCreated++;
+                this.stats.activeSessions = this.sessions.size;
+                if (this.sessions.size > this.stats.peakConcurrentSessions) {
+                    this.stats.peakConcurrentSessions = this.sessions.size;
+                }
+                break;
+            case "update":
+                if (session) {
+                    // Update average tools per session
+                    const totalTools = Array.from(this.sessions.values()).reduce((sum, s) => sum + s.toolHistory.length, 0);
+                    this.stats.averageToolsPerSession =
+                        this.sessions.size > 0 ? totalTools / this.sessions.size : 0;
+                }
+                break;
+            case "remove":
+                this.stats.totalSessionsExpired++;
+                this.stats.activeSessions = this.sessions.size;
+                if (session) {
+                    // Update average session duration
+                    const duration = session.lastActivity - session.createdAt;
+                    const totalDuration = this.stats.averageSessionDuration *
+                        (this.stats.totalSessionsExpired - 1) +
+                        duration;
+                    this.stats.averageSessionDuration =
+                        totalDuration / this.stats.totalSessionsExpired;
+                }
+                break;
+        }
+    }
+}
+/**
+ * Default session manager instance
+ */
+export const defaultSessionManager = new SessionManager();
+/**
+ * Utility function to create session with default manager
+ *
+ * @param context Execution context
+ * @param options Session options
+ * @returns Created session
+ */
+export async function createSession(context, options) {
+    return defaultSessionManager.createSession(context, options);
+}
+/**
+ * Utility function to get session with default manager
+ *
+ * @param sessionId Session identifier
+ * @param extend Whether to extend expiration
+ * @returns Session or null
+ */
+export async function getSession(sessionId, extend) {
+    return defaultSessionManager.getSession(sessionId, extend);
+}

package/dist/mcp/session-persistence.d.ts

@@ -0,0 +1,93 @@
+/**
+ * NeuroLink Session Persistence Layer
+ * Provides file-based persistence for sessions with atomic writes and recovery
+ */
+import type { OrchestratorSession } from "./session-manager.js";
+/**
+ * Persistence options
+ */
+export interface PersistenceOptions {
+    directory?: string;
+    snapshotInterval?: number;
+    retentionPeriod?: number;
+    enableChecksum?: boolean;
+    maxRetries?: number;
+}
+/**
+ * Session Persistence Manager
+ * Handles saving and loading sessions to/from disk with recovery mechanisms
+ */
+export declare class SessionPersistence {
+    private directory;
+    private snapshotInterval;
+    private retentionPeriod;
+    private enableChecksum;
+    private maxRetries;
+    private snapshotTimer;
+    private sessionMap;
+    constructor(sessionMap: Map<string, OrchestratorSession>, options?: PersistenceOptions);
+    /**
+     * Initialize persistence layer
+     */
+    initialize(): Promise<void>;
+    /**
+     * Ensure sessions directory exists
+     */
+    private ensureDirectory;
+    /**
+     * Calculate checksum for data integrity
+     */
+    private calculateChecksum;
+    /**
+     * Serialize session to JSON with metadata
+     */
+    private serializeSession;
+    /**
+     * Deserialize session from JSON
+     */
+    private deserializeSession;
+    /**
+     * Save single session with atomic write
+     */
+    saveSession(sessionId: string, session: OrchestratorSession): Promise<boolean>;
+    /**
+     * Load single session from disk
+     */
+    loadSession(sessionId: string): Promise<OrchestratorSession | null>;
+    /**
+     * Load all sessions from disk on startup
+     */
+    loadSessions(): Promise<void>;
+    /**
+     * Save all active sessions (snapshot)
+     */
+    saveAllSessions(): Promise<void>;
+    /**
+     * Delete session file
+     */
+    deleteSession(sessionId: string): Promise<void>;
+    /**
+     * Clean up old session files
+     */
+    cleanupOldSessions(): Promise<void>;
+    /**
+     * Start periodic snapshot timer
+     */
+    private startSnapshotTimer;
+    /**
+     * Stop snapshot timer
+     */
+    stopSnapshotTimer(): void;
+    /**
+     * Shutdown persistence layer
+     */
+    shutdown(): Promise<void>;
+}
+/**
+ * Default session persistence instance
+ */
+export declare let defaultSessionPersistence: SessionPersistence | null;
+/**
+ * Initialize default session persistence
+ */
+export declare function initializeSessionPersistence(sessionMap: Map<string, OrchestratorSession>, options?: PersistenceOptions): Promise<SessionPersistence>;