@loop_ouroboros/mcp-hub-lite 1.1.0 → 1.2.0

package/dist/server/src/services/session/session-manager.js

@@ -3,19 +3,35 @@ import { gateway } from '../gateway.service.js';
 import { logger, LOG_MODULES, formatMcpMessageForLogging, logNotificationMessage } from '../../utils/logger.js';
 import { configManager } from '../../config/config-manager.js';
 import { formatDuration } from '../../utils/format-utils.js';
+import { SessionStateSchema, createEmptySessionStore } from '../../../shared/models/session.model.js';
+import { sessionTrackerService } from '../session-tracker.service.js';
 import { getSessionDebugSetting, getMcpCommDebugSetting } from '../../utils/json-utils.js';
+import * as fs from 'fs';
+import path from 'path';
+import os from 'os';
 /**
- * Lightweight MCP Session Manager with in-memory session management only.
+ * Enhanced MCP Session Manager with comprehensive persistence and lifecycle management.
  *
- * This service manages MCP sessions with basic in-memory storage and automatic
- * cleanup of stale sessions. It provides session isolation through unique
+ * This service manages MCP sessions with full state persistence, automatic cleanup,
+ * and graceful shutdown handling. It provides session isolation through unique
  * server and transport instances per session while maintaining shared resources
  * for efficiency.
  *
- * Key features:
- * - In-memory session storage only (no persistence)
+ * Key features include:
+ * - Session state persistence to disk with individual session files and index
+ * - Dirty tracking with 5-second batch flushing to minimize I/O operations
  * - Automatic cleanup of stale sessions based on configurable timeout (default 30 minutes)
- * - Session ID generation for internal use
+ * - Graceful shutdown handling with SIGTERM/SIGINT signal capture
+ * - Client metadata integration from client tracker service
+ * - Environment variable controlled debugging (SESSION_DEBUG)
+ *
+ * Session storage structure:
+ * ```
+ * ~/.mcp-hub-lite/
+ * └── sessions/
+ *     ├── index.json          # Session index file
+ *     └── {sessionId}.json    # Individual session state files
+ * ```
  *
  * @example
  * ```typescript
@@ -24,10 +40,15 @@ import { getSessionDebugSetting, getMcpCommDebugSetting } from '../../utils/json
  * // Use session.server and session.transport for MCP communication
  * ```
  *
- * @since 2.0.0
+ * @since 1.0.0
  */
 export class McpSessionManager {
     sessions = new Map();
+    sessionStates = new Map();
+    dirtySessions = new Set();
+    sessionsPath;
+    flushTimeout = null; // Replace with one-time delay
+    isInitialized = false;
     get SESSION_TIMEOUT() {
         return configManager.getConfig().security.sessionTimeout;
     }
@@ -35,15 +56,430 @@ export class McpSessionManager {
         return configManager.getConfig().security.sessionFlushInterval;
     }
     constructor() {
+        // Initialize sessions directory path
+        const configPath = process.env.MCP_HUB_CONFIG_PATH ||
+            path.join(os.homedir(), '.mcp-hub-lite', 'config', '.mcp-hub.json');
+        const mcpHubDir = path.dirname(path.dirname(configPath)); // Get ~/.mcp-hub-lite directory
+        this.sessionsPath = path.join(mcpHubDir, 'sessions');
+        logger.info(`Using sessions directory: ${this.sessionsPath}`, LOG_MODULES.SESSION_MANAGER);
         // Start cleanup interval
         setInterval(() => this.cleanup(), this.CLEANUP_INTERVAL);
+        // Register graceful shutdown handler
+        this.registerShutdownHandler();
+        // Initialize by restoring sessions
+        this.restoreSessions().catch((error) => {
+            logger.error('Failed to restore sessions during initialization:', error, LOG_MODULES.SESSION_MANAGER);
+        });
+    }
+    /**
+     * Registers process shutdown handlers for graceful session cleanup.
+     *
+     * This method sets up event listeners for SIGTERM and SIGINT signals to ensure
+     * that all dirty sessions are flushed to disk before the process terminates.
+     * This prevents data loss during unexpected shutdowns or service restarts.
+     *
+     * The shutdown handler performs a final flush of all dirty sessions and
+     * clears any pending flush timeouts to ensure clean termination.
+     *
+     * @returns {void}
+     *
+     * @example
+     * ```typescript
+     * // Called automatically in constructor
+     * sessionManager.registerShutdownHandler();
+     * ```
+     */
+    registerShutdownHandler() {
+        const gracefulShutdown = async () => {
+            logger.info('Shutting down, flushing dirty sessions...', LOG_MODULES.SESSION_MANAGER);
+            try {
+                await this.flushDirtySessions();
+            }
+            catch (error) {
+                logger.error('Error during shutdown flush:', error, LOG_MODULES.SESSION_MANAGER);
+            }
+            if (this.flushTimeout) {
+                clearTimeout(this.flushTimeout);
+            }
+        };
+        process.on('SIGTERM', gracefulShutdown);
+        process.on('SIGINT', gracefulShutdown);
+    }
+    /**
+     * Marks a session as dirty, indicating it needs to be persisted to disk.
+     *
+     * This method adds the session ID to the dirty sessions set and initiates
+     * a delayed batch flush operation with a 5-second timeout. This optimization
+     * prevents excessive I/O operations by batching multiple session updates
+     * that occur in quick succession.
+     *
+     * When the SESSION_DEBUG environment variable is set, detailed logging
+     * is enabled for debugging session persistence behavior.
+     *
+     * @param {string} sessionId - Unique identifier of the session to mark as dirty
+     * @returns {void}
+     *
+     * @example
+     * ```typescript
+     * sessionManager.markAsDirty('my-session-id');
+     * // Session will be flushed to disk within 5 seconds
+     * ```
+     */
+    markAsDirty(sessionId) {
+        this.dirtySessions.add(sessionId);
+        if (getSessionDebugSetting()) {
+            logger.debug(`Session marked as dirty: ${sessionId}`, LOG_MODULES.SESSION_MANAGER);
+        }
+        // Set one-time delayed flush to avoid frequent writes (configurable delay, batch processing)
+        if (!this.flushTimeout) {
+            const flushInterval = configManager.getConfig().security.sessionFlushInterval || 5000;
+            this.flushTimeout = setTimeout(() => {
+                this.flushDirtySessions();
+                this.flushTimeout = null;
+            }, flushInterval);
+        }
+    }
+    /**
+     * Loads the complete session store from disk, including all individual session files.
+     *
+     * This method reads the sessions index file and loads each individual session state
+     * file, validating each session state against the SessionStateSchema. Invalid
+     * session states are skipped with warning logs, ensuring robust recovery from
+     * corrupted data.
+     *
+     * The method creates the sessions directory and index file if they don't exist,
+     * providing a clean initialization path for first-time usage.
+     *
+     * @returns {Promise<SessionStore>} Complete session store with all valid sessions
+     * @throws {Error} If critical I/O operations fail (non-recoverable errors)
+     *
+     * @example
+     * ```typescript
+     * const store = await sessionManager.loadSessionStore();
+     * console.log(`Loaded ${Object.keys(store.sessions).length} sessions`);
+     * ```
+     */
+    async loadSessionStore() {
+        try {
+            if (!fs.existsSync(this.sessionsPath)) {
+                if (getSessionDebugSetting()) {
+                    logger.debug('Sessions directory not found, creating new one', LOG_MODULES.SESSION_MANAGER);
+                }
+                fs.mkdirSync(this.sessionsPath, { recursive: true });
+                return createEmptySessionStore();
+            }
+            const indexPath = path.join(this.sessionsPath, 'index.json');
+            if (!fs.existsSync(indexPath)) {
+                if (getSessionDebugSetting()) {
+                    logger.debug('Sessions index file not found, creating new one', LOG_MODULES.SESSION_MANAGER);
+                }
+                return createEmptySessionStore();
+            }
+            const indexContent = fs.readFileSync(indexPath, 'utf-8');
+            const index = JSON.parse(indexContent);
+            if (!index.sessions || !Array.isArray(index.sessions)) {
+                logger.error('Invalid sessions index file, creating new one', LOG_MODULES.SESSION_MANAGER);
+                return createEmptySessionStore();
+            }
+            const store = createEmptySessionStore();
+            for (const sessionId of index.sessions) {
+                const sessionPath = path.join(this.sessionsPath, `${sessionId}.json`);
+                if (fs.existsSync(sessionPath)) {
+                    try {
+                        const sessionContent = fs.readFileSync(sessionPath, 'utf-8');
+                        const sessionState = JSON.parse(sessionContent);
+                        const validated = SessionStateSchema.parse(sessionState);
+                        store.sessions[sessionId] = validated;
+                    }
+                    catch (error) {
+                        logger.warn(`Failed to load session ${sessionId}:`, error, LOG_MODULES.SESSION_MANAGER);
+                    }
+                }
+            }
+            if (getSessionDebugSetting()) {
+                logger.debug(`Loaded ${Object.keys(store.sessions).length} sessions from store`, LOG_MODULES.SESSION_MANAGER);
+            }
+            return store;
+        }
+        catch (error) {
+            logger.error('Failed to load sessions store:', error, LOG_MODULES.SESSION_MANAGER);
+            return createEmptySessionStore();
+        }
+    }
+    /**
+     * Saves the complete session store to disk, writing individual session files and index.
+     *
+     * This method persists all session states by writing individual JSON files for each
+     * session and updating the sessions index file. The operation is atomic at the
+     * file level, ensuring data integrity even if the process is interrupted.
+     *
+     * @param {SessionStore} store - Complete session store to persist
+     * @returns {Promise<void>} Resolves when all files are successfully written
+     * @throws {Error} If any file write operations fail
+     *
+     * @example
+     * ```typescript
+     * await sessionManager.saveSessionStore(mySessionStore);
+     * console.log('Session store saved successfully');
+     * ```
+     */
+    async saveSessionStore(store) {
+        try {
+            if (!fs.existsSync(this.sessionsPath)) {
+                fs.mkdirSync(this.sessionsPath, { recursive: true });
+            }
+            // Save individual session files
+            for (const [sessionId, state] of Object.entries(store.sessions)) {
+                const sessionPath = path.join(this.sessionsPath, `${sessionId}.json`);
+                fs.writeFileSync(sessionPath, JSON.stringify(state, null, 2));
+            }
+            // Save index file
+            const indexPath = path.join(this.sessionsPath, 'index.json');
+            fs.writeFileSync(indexPath, JSON.stringify({
+                sessions: Object.keys(store.sessions)
+            }, null, 2));
+        }
+        catch (error) {
+            logger.error('Failed to save sessions store:', error, LOG_MODULES.SESSION_MANAGER);
+            throw error;
+        }
+    }
+    /**
+     * Restores all sessions from disk during service startup.
+     *
+     * This method is called automatically during initialization to recover session states
+     * from persistent storage. It loads the session store, validates each session state,
+     * and populates the in-memory session state cache. Invalid sessions are skipped
+     * with warning logs to ensure robust startup even with corrupted data.
+     *
+     * The method ensures idempotent execution by checking the initialization flag,
+     * preventing multiple restoration attempts.
+     *
+     * @returns {Promise<void>} Resolves when all valid sessions are restored
+     *
+     * @example
+     * ```typescript
+     * await sessionManager.restoreSessions();
+     * console.log('Sessions restored from disk');
+     * ```
+     */
+    async restoreSessions() {
+        if (this.isInitialized) {
+            return;
+        }
+        try {
+            logger.info('Restoring sessions from disk...', LOG_MODULES.SESSION_MANAGER);
+            const store = await this.loadSessionStore();
+            let restoredCount = 0;
+            let expiredCount = 0;
+            const now = Date.now();
+            for (const [sessionId, state] of Object.entries(store.sessions)) {
+                try {
+                    // Validate individual session state
+                    const validatedState = SessionStateSchema.parse(state);
+                    // Check if session has expired
+                    if (now - validatedState.lastAccessedAt > this.SESSION_TIMEOUT) {
+                        expiredCount++;
+                        if (getSessionDebugSetting()) {
+                            logger.debug(`Expired session: ${sessionId} (last accessed ${formatDuration(now - validatedState.lastAccessedAt)} ago)`, LOG_MODULES.SESSION_MANAGER);
+                        }
+                    }
+                    else {
+                        restoredCount++;
+                    }
+                    // Always restore to memory - cleanup() will handle deletion
+                    this.sessionStates.set(sessionId, validatedState);
+                    if (getSessionDebugSetting()) {
+                        logger.debug(`Restored session state: ${sessionId}`, LOG_MODULES.SESSION_MANAGER);
+                    }
+                }
+                catch (error) {
+                    logger.warn(`Skipping invalid session state for ${sessionId}:`, error, LOG_MODULES.SESSION_MANAGER);
+                }
+            }
+            this.isInitialized = true;
+            logger.info(`Successfully restored ${restoredCount} valid, ${expiredCount} expired session(s)`, LOG_MODULES.SESSION_MANAGER);
+            // Immediately run cleanup on startup to clean up any expired sessions
+            this.cleanup();
+        }
+        catch (error) {
+            logger.error('Failed to restore sessions:', error, LOG_MODULES.SESSION_MANAGER);
+            // Continue with empty state rather than failing
+            this.isInitialized = true;
+        }
+    }
+    /**
+     * Flushes all dirty sessions to disk in a single batch operation.
+     *
+     * This method collects all sessions marked as dirty, loads the current session store,
+     * updates it with the dirty sessions, and saves the complete store back to disk.
+     * This batch approach minimizes I/O operations and ensures data consistency.
+     *
+     * The method includes comprehensive error handling to prevent partial writes and
+     * maintains detailed logging for debugging and monitoring purposes.
+     *
+     * @returns {Promise<void>} Resolves when all dirty sessions are successfully flushed
+     *
+     * @example
+     * ```typescript
+     * await sessionManager.flushDirtySessions();
+     * console.log('All dirty sessions flushed to disk');
+     * ```
+     */
+    async flushDirtySessions() {
+        if (this.dirtySessions.size === 0) {
+            return;
+        }
+        try {
+            logger.info(`Flushing ${this.dirtySessions.size} dirty session(s) to disk`, LOG_MODULES.SESSION_MANAGER);
+            // Load current store
+            const currentStore = await this.loadSessionStore();
+            const newStore = {
+                ...currentStore,
+                sessions: { ...currentStore.sessions }
+            };
+            // Process all dirty sessions
+            for (const sessionId of this.dirtySessions) {
+                const sessionState = this.sessionStates.get(sessionId);
+                if (sessionState) {
+                    // Session exists - update it
+                    newStore.sessions[sessionId] = sessionState;
+                }
+                else {
+                    // Session does not exist - remove it
+                    delete newStore.sessions[sessionId];
+                    // Also remove the individual session file
+                    const sessionPath = path.join(this.sessionsPath, `${sessionId}.json`);
+                    if (fs.existsSync(sessionPath)) {
+                        fs.unlinkSync(sessionPath);
+                        logger.debug(`Deleted session file: ${sessionId}.json`, LOG_MODULES.SESSION_MANAGER);
+                    }
+                }
+            }
+            await this.saveSessionStore(newStore);
+            const flushedCount = this.dirtySessions.size;
+            this.dirtySessions.clear();
+            logger.info(`Successfully flushed ${flushedCount} session(s)`, LOG_MODULES.SESSION_MANAGER);
+        }
+        catch (error) {
+            logger.error('Failed to flush dirty sessions:', error, LOG_MODULES.SESSION_MANAGER);
+        }
+    }
+    /**
+     * Updates session metadata by retrieving client information from the client tracker service.
+     *
+     * This method fetches current client information including name, version, working directory,
+     * and project context from the client tracker service and returns a partial session state
+     * update object containing only the relevant metadata fields.
+     *
+     * @param {string} sessionId - Unique identifier of the session to update
+     * @returns {Partial<SessionState>} Partial session state with updated client metadata
+     *
+     * @example
+     * ```typescript
+     * const metadata = sessionManager.updateSessionMetadataFromClient('my-session-id');
+     * console.log('Updated client metadata:', metadata);
+     * ```
+     */
+    updateSessionMetadataFromClient(sessionId) {
+        const sessionInfo = sessionTrackerService.getSession(sessionId);
+        return {
+            clientName: sessionInfo?.clientName,
+            clientVersion: sessionInfo?.clientVersion,
+            protocolVersion: sessionInfo?.protocolVersion,
+            capabilities: sessionInfo?.capabilities,
+            cwd: sessionInfo?.cwd,
+            project: sessionInfo?.project,
+            userAgent: sessionInfo?.userAgent,
+            ip: sessionInfo?.ip
+        };
+    }
+    /**
+     * Creates or updates a session state with current metadata and timestamps.
+     *
+     * This method merges existing session state (if any) with current client metadata
+     * from the client tracker service, updates access timestamps, and ensures proper
+     * session state structure. The updated state is stored in memory and marked as dirty
+     * for persistence.
+     *
+     * @param {string} sessionId - Unique identifier of the session to create or update
+     * @returns {SessionState} Complete updated session state object
+     *
+     * @example
+     * ```typescript
+     * const state = sessionManager.upsertSessionState('my-session-id');
+     * console.log('Session state updated:', state);
+     * ```
+     */
+    upsertSessionState(sessionId) {
+        const existing = this.sessionStates.get(sessionId);
+        const now = Date.now();
+        const clientMetadata = this.updateSessionMetadataFromClient(sessionId);
+        const state = {
+            sessionId,
+            clientName: clientMetadata.clientName || existing?.clientName,
+            clientVersion: clientMetadata.clientVersion || existing?.clientVersion,
+            protocolVersion: clientMetadata.protocolVersion || existing?.protocolVersion,
+            capabilities: clientMetadata.capabilities || existing?.capabilities,
+            cwd: clientMetadata.cwd || existing?.cwd,
+            project: clientMetadata.project || existing?.project,
+            userAgent: clientMetadata.userAgent || existing?.userAgent,
+            ip: clientMetadata.ip || existing?.ip,
+            createdAt: existing?.createdAt || now,
+            lastAccessedAt: now,
+            metadata: existing?.metadata || {}
+        };
+        this.sessionStates.set(sessionId, state);
+        this.markAsDirty(sessionId);
+        return state;
+    }
+    /**
+     * Updates session metadata explicitly with provided key-value pairs.
+     *
+     * This method merges the provided metadata object with existing session metadata,
+     * updates the last accessed timestamp, and marks the session as dirty for persistence.
+     * It's useful for storing custom session-specific information that needs to be persisted.
+     *
+     * @param {string} sessionId - Unique identifier of the session to update
+     * @param {Record<string, unknown>} metadata - Key-value pairs to merge into session metadata
+     * @returns {Promise<void>} Resolves when metadata is updated and marked for persistence
+     *
+     * @example
+     * ```typescript
+     * await sessionManager.updateSessionMetadata('my-session-id', {
+     *   userPreferences: { theme: 'dark' },
+     *   lastProject: 'my-project'
+     * });
+     * ```
+     */
+    async updateSessionMetadata(sessionId, metadata) {
+        const existing = this.sessionStates.get(sessionId);
+        if (existing) {
+            const now = Date.now();
+            const updated = {
+                ...existing,
+                lastAccessedAt: now,
+                metadata: {
+                    ...existing.metadata,
+                    ...metadata
+                }
+            };
+            this.sessionStates.set(sessionId, updated);
+            this.markAsDirty(sessionId);
+            if (getSessionDebugSetting()) {
+                logger.debug(`Updated metadata for session: ${sessionId}`, LOG_MODULES.SESSION_MANAGER);
+            }
+        }
     }
     /**
      * Retrieves an existing session or creates a new one if it doesn't exist.
      *
      * This method provides access to active sessions, creating new ones on demand with
      * proper initialization based on the requireInitialize parameter. It updates session
-     * access timestamps.
+     * access timestamps and persists session state changes to ensure data consistency.
+     *
+     * The method includes optimization to prevent excessive timestamp updates for rapid
+     * successive requests by only updating when at least 100ms have passed since the last access.
      *
      * @param {string} sessionId - Unique identifier of the session to retrieve or create
      * @param {boolean} [requireInitialize=true] - Whether to require MCP protocol initialization
@@ -53,28 +489,48 @@ export class McpSessionManager {
      * ```typescript
      * // Get or create session with default initialization
      * const session = await sessionManager.getSession('my-session-id');
+     *
+     * // Get or create session without requiring initialization (for restored sessions)
+     * const restoredSession = await sessionManager.getSession('restored-session-id', false);
      * ```
      */
     async getSession(sessionId, requireInitialize = true) {
         if (getSessionDebugSetting()) {
+            const hasSessionState = this.sessionStates.has(sessionId);
             const hasSessionObject = this.sessions.has(sessionId);
-            logger.debug(`getSession called for ${sessionId} (requireInitialize: ${requireInitialize}). Object exists: ${hasSessionObject}`, LOG_MODULES.SESSION_MANAGER);
+            logger.debug(`getSession called for ${sessionId} (requireInitialize: ${requireInitialize}). State exists: ${hasSessionState}, Object exists: ${hasSessionObject}`, LOG_MODULES.SESSION_MANAGER);
         }
         let session = this.sessions.get(sessionId);
-        if (!session) {
+        // Check if session state exists but session object doesn't (inconsistency case)
+        const hasSessionState = this.sessionStates.has(sessionId);
+        const hasSessionObject = this.sessions.has(sessionId);
+        if (hasSessionState && !hasSessionObject) {
+            // Session state exists but session object is missing - recreate session
+            if (getSessionDebugSetting()) {
+                logger.debug(`Session state exists but session object missing for ${sessionId}, recreating...`, LOG_MODULES.SESSION_MANAGER);
+            }
+            session = await this.createSession(sessionId, requireInitialize);
+            this.sessions.set(sessionId, session);
+        }
+        else if (!session) {
             // Normal case: create new session
             session = await this.createSession(sessionId, requireInitialize);
             this.sessions.set(sessionId, session);
         }
         else {
-            // Ensure transport session state is correctly initialized
+            // Enhanced check: ensure transport session state is correctly initialized
+            // This fixes the "Session not found" error when transport has lost session context
+            const hasRestoredState = this.sessionStates.has(sessionId);
+            const shouldManuallyInitialize = !requireInitialize || hasRestoredState;
+            // Always ensure sessionId is set on transport, regardless of initialization status
+            // This fixes the "Session not found" error for non-initialization requests
             const webTransport = session.transport
                 ._webStandardTransport;
             if (webTransport) {
                 const currentSessionId = webTransport.sessionId;
                 const isInitialized = webTransport._initialized;
                 if (getSessionDebugSetting()) {
-                    logger.debug(`Transport state check - Expected: ${sessionId} (initialized: ${!requireInitialize}), Actual: ${currentSessionId} (initialized: ${isInitialized})`, LOG_MODULES.SESSION_MANAGER);
+                    logger.debug(`Transport state check - Expected: ${sessionId} (initialized: ${shouldManuallyInitialize}), Actual: ${currentSessionId} (initialized: ${isInitialized})`, LOG_MODULES.SESSION_MANAGER);
                 }
                 if (webTransport.sessionId !== sessionId) {
                     logger.warn(`Session ID mismatch detected for ${sessionId}. Resetting transport sessionId.`, LOG_MODULES.SESSION_MANAGER);
@@ -83,7 +539,7 @@ export class McpSessionManager {
                         webTransport._session = sessionId;
                     }
                 }
-                if (!requireInitialize && !webTransport._initialized) {
+                if (shouldManuallyInitialize && !webTransport._initialized) {
                     logger.warn(`Session initialization state mismatch detected for ${sessionId}. Setting initialized flag.`, LOG_MODULES.SESSION_MANAGER);
                     webTransport._initialized = true;
                 }
@@ -92,14 +548,56 @@ export class McpSessionManager {
         const now = Date.now();
         const timeDiff = Math.abs(now - session.lastAccessed);
         // Only update lastAccessed if meaningful time has passed
+        // This prevents excessive updates for rapid successive requests
         if (timeDiff >= 100) {
             session.lastAccessed = now;
+            // Also update and persist session state
+            this.upsertSessionState(sessionId);
         }
         if (getSessionDebugSetting()) {
             logger.debug(`Returning session for ${sessionId}`, LOG_MODULES.SESSION_MANAGER);
         }
         return session;
     }
+    /**
+     * Retrieves all persisted session states for API exposure.
+     *
+     * This method returns an array of all current session states, providing a complete
+     * snapshot of all active sessions and their metadata. It's primarily used by the
+     * web API to expose session information to clients.
+     *
+     * @returns {SessionState[]} Array of all current session states
+     *
+     * @example
+     * ```typescript
+     * const allStates = sessionManager.getAllSessionStates();
+     * console.log(`Total active sessions: ${allStates.length}`);
+     * ```
+     */
+    getAllSessionStates() {
+        return Array.from(this.sessionStates.values());
+    }
+    /**
+     * Retrieves a specific session state by session ID for API exposure.
+     *
+     * This method returns the current state of a specific session or undefined if
+     * the session doesn't exist. It's primarily used by the web API to provide
+     * detailed information about individual sessions.
+     *
+     * @param {string} sessionId - Unique identifier of the session to retrieve
+     * @returns {SessionState | undefined} Session state object or undefined if not found
+     *
+     * @example
+     * ```typescript
+     * const state = sessionManager.getSessionState('my-session-id');
+     * if (state) {
+     *   console.log('Session client:', state.clientName);
+     * }
+     * ```
+     */
+    getSessionState(sessionId) {
+        return this.sessionStates.get(sessionId);
+    }
     /**
      * Checks if a session object exists in the active sessions map.
      *
@@ -110,9 +608,11 @@ export class McpSessionManager {
         return this.sessions.has(sessionId);
     }
     /**
-     * Deletes a session from memory.
+     * Deletes a session and removes it from persistent storage.
      *
-     * This method gracefully closes the session's MCP server and removes it from memory.
+     * This method gracefully closes the session's MCP server, removes it from memory,
+     * and ensures it's removed from persistent storage by marking it as dirty and
+     * performing an immediate flush. It returns true if the session existed and was deleted.
      *
      * @param {string} sessionId - Unique identifier of the session to delete
      * @returns {Promise<boolean>} True if session existed and was deleted, false otherwise
@@ -135,15 +635,30 @@ export class McpSessionManager {
                 logger.error(`Error closing session ${sessionId}:`, e, LOG_MODULES.SESSION_MANAGER);
             }
             this.sessions.delete(sessionId);
-            return true;
         }
-        return false;
+        const existed = this.sessionStates.has(sessionId);
+        if (existed) {
+            this.sessionStates.delete(sessionId);
+            // Mark as dirty to remove from persistence
+            this.markAsDirty(sessionId);
+            // Flush immediately to remove from disk
+            await this.flushDirtySessions();
+        }
+        return existed;
     }
     /**
      * Creates a new MCP session with proper initialization and transport setup.
      *
      * This method sets up a complete MCP session including server, transport, and
-     * communication logging.
+     * communication logging. It handles both fresh sessions and restored sessions,
+     * with special logic for skipping initialization when appropriate.
+     *
+     * Key features:
+     * - Creates StreamableHTTPServerTransport with custom session ID generation
+     * - Sets up comprehensive message logging for debugging
+     * - Handles restored sessions by manually initializing transport state
+     * - Integrates with client tracker service for metadata
+     * - Creates/updates session state and marks as dirty for persistence
      *
      * @param {string} sessionId - Unique identifier for the new session
      * @param {boolean} [requireInitialize=true] - Whether to require MCP protocol initialization
@@ -173,26 +688,46 @@ export class McpSessionManager {
             }
         });
         // Directly set sessionId property to avoid validateSession failure
+        // because WebStandardStreamableHTTPServerTransport only calls sessionIdGenerator during initialize
         const webTransport = transport._webStandardTransport;
         if (webTransport) {
             webTransport.sessionId = sessionId;
+            // Do not set _initialized = true here because it will cause initialize request to fail
+            // _initialized flag will be set as needed in the shouldManuallyInitialize logic
             if (getSessionDebugSetting()) {
                 logger.debug(`Directly set sessionId on transport: ${sessionId}`, LOG_MODULES.SESSION_MANAGER);
             }
         }
-        // For sessions that need to skip initialization, manually set the initialized flag
-        if (!requireInitialize) {
+        // Check if we have a restored state for this session
+        const restoredState = this.sessionStates.get(sessionId);
+        if (restoredState) {
+            logger.info(`Reusing restored session state for: ${sessionId}`, LOG_MODULES.SESSION_MANAGER);
+        }
+        // For restored sessions or when explicitly requested to skip initialization, manually set the initialized flag
+        // This allows sending requests like tools/list directly without needing to initialize first
+        const shouldManuallyInitialize = !requireInitialize || !!restoredState;
+        if (getSessionDebugSetting()) {
+            logger.debug(`shouldManuallyInitialize: ${shouldManuallyInitialize} (!requireInitialize: ${!requireInitialize} || restored: ${!!restoredState})`, LOG_MODULES.SESSION_MANAGER);
+        }
+        if (shouldManuallyInitialize) {
             const webTransport = transport._webStandardTransport;
             if (webTransport) {
                 webTransport.sessionId = sessionId;
                 webTransport._initialized = true;
+                // Ensure session property is also set if it exists
                 if (webTransport._session !== undefined) {
                     webTransport._session = sessionId;
                 }
                 if (getSessionDebugSetting()) {
-                    logger.debug(`Manually initialized transport for session: ${sessionId} (skipInitialize: ${!requireInitialize}`, LOG_MODULES.SESSION_MANAGER);
+                    logger.debug(`Manually initialized transport for session: ${sessionId} (skipInitialize: ${!requireInitialize}, restored: ${!!restoredState})`, LOG_MODULES.SESSION_MANAGER);
+                    logger.debug(`Transport state after manual init - sessionId: ${webTransport.sessionId}, _initialized: ${webTransport._initialized}, _session: ${webTransport._session}`, LOG_MODULES.SESSION_MANAGER);
                 }
             }
+            else {
+                logger.error(`Failed to get _webStandardTransport from transport!`, LOG_MODULES.SESSION_MANAGER);
+                // Even if we can't manually initialize, continue with normal initialization
+                // The transport will be initialized when the first request arrives
+            }
         }
         // Always set up message handler for notifications/message
         transport.onmessage = (message) => {
@@ -222,9 +757,14 @@ export class McpSessionManager {
         const server = gateway.createConnectionServer();
         // Ensure server is fully connected before returning session
         await server.connect(transport);
+        // Note: StreamableHTTPServerTransport's onsessioninitialized callback is triggered
+        // when the first actual request (GET /mcp) arrives, not during connect().
+        // Therefore, we don't need to wait for this event - the transport is ready to receive requests.
         if (getSessionDebugSetting()) {
             logger.debug(`StreamableHTTPServerTransport ready for session: ${sessionId}`, LOG_MODULES.SESSION_MANAGER);
         }
+        // Create/update session state
+        this.upsertSessionState(sessionId);
         logger.info(`MCP session created successfully: ${sessionId}`, LOG_MODULES.SESSION_MANAGER);
         const session = {
             server,
@@ -237,11 +777,14 @@ export class McpSessionManager {
     /**
      * Cleans up stale sessions based on the configured session timeout.
      *
-     * This method is called periodically to identify and close
+     * This method is called periodically (every 60 seconds) to identify and close
      * sessions that haven't been accessed within the configured timeout period
      * (default 30 minutes). It gracefully closes MCP servers and removes sessions
      * from memory to prevent resource leaks.
      *
+     * The method logs detailed information about cleaned sessions and maintains
+     * active session count for monitoring purposes.
+     *
      * @returns {void}
      *
      * @example
@@ -267,8 +810,27 @@ export class McpSessionManager {
                 this.sessions.delete(sessionId);
             }
         }
+        // Cleanup persisted session states
+        const expiredSessionIds = [];
+        for (const [sessionId, session] of this.sessionStates.entries()) {
+            if (now - session.lastAccessedAt > this.SESSION_TIMEOUT) {
+                expiredSessionIds.push(sessionId);
+                cleanedCount++;
+            }
+        }
+        for (const sessionId of expiredSessionIds) {
+            this.sessionStates.delete(sessionId);
+            this.markAsDirty(sessionId);
+            logger.debug(`Marking expired session for deletion: ${sessionId}`, LOG_MODULES.SESSION_MANAGER);
+        }
+        // Immediately flush to delete session files from disk
+        if (expiredSessionIds.length > 0) {
+            this.flushDirtySessions().catch((error) => {
+                logger.error('Failed to flush expired sessions:', error, LOG_MODULES.SESSION_MANAGER);
+            });
+        }
         if (cleanedCount > 0) {
-            logger.info(`Cleaned up ${cleanedCount} stale sessions. Active sessions: ${this.sessions.size}`, LOG_MODULES.SESSION_MANAGER);
+            logger.info(`Cleaned up ${cleanedCount} stale sessions. Active sessions: ${this.sessions.size}, Persisted states: ${this.sessionStates.size}`, LOG_MODULES.SESSION_MANAGER);
         }
     }
 }