n8n-mcp 2.18.9 → 2.19.0

package/dist/http-server-single-session.d.ts

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import express from 'express';
 import { InstanceContext } from './types/instance-context';
+import { SessionRestoreHook, SessionState, SessionLifecycleEvents } from './types/session-restoration';
 export declare class SingleSessionHTTPServer {
     private transports;
     private servers;
@@ -13,7 +14,19 @@ export declare class SingleSessionHTTPServer {
     private sessionTimeout;
     private authToken;
     private cleanupTimer;
-    constructor();
+    private onSessionNotFound?;
+    private sessionRestorationTimeout;
+    private sessionEvents?;
+    private sessionRestorationRetries;
+    private sessionRestorationRetryDelay;
+    constructor(options?: {
+        sessionTimeout?: number;
+        onSessionNotFound?: SessionRestoreHook;
+        sessionRestorationTimeout?: number;
+        sessionEvents?: SessionLifecycleEvents;
+        sessionRestorationRetries?: number;
+        sessionRestorationRetryDelay?: number;
+    });
     private startSessionCleanup;
     private cleanupExpiredSessions;
     private removeSession;
@@ -24,6 +37,11 @@ export declare class SingleSessionHTTPServer {
     private updateSessionAccess;
     private switchSessionContext;
     private performContextSwitch;
+    private timeout;
+    private emitEvent;
+    private restoreSessionWithRetry;
+    private createSession;
+    private generateSessionId;
     private getSessionMetrics;
     private loadAuthToken;
     private validateEnvironment;
@@ -44,5 +62,10 @@ export declare class SingleSessionHTTPServer {
             sessionIds: string[];
         };
     };
+    getActiveSessions(): string[];
+    getSessionState(sessionId: string): SessionState | null;
+    getAllSessionStates(): SessionState[];
+    manuallyRestoreSession(sessionId: string, instanceContext: InstanceContext): boolean;
+    manuallyDeleteSession(sessionId: string): boolean;
 }
 //# sourceMappingURL=http-server-single-session.d.ts.map

package/dist/http-server-single-session.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"http-server-single-session.d.ts","sourceRoot":"","sources":["../src/http-server-single-session.ts"],"names":[],"mappings":";AAMA,OAAO,OAAO,MAAM,SAAS,CAAC;AAoB9B,OAAO,EAAE,eAAe,EAA2B,MAAM,0BAA0B,CAAC;AA+CpF,qBAAa,uBAAuB;IAElC,OAAO,CAAC,UAAU,CAA8D;IAChF,OAAO,CAAC,OAAO,CAA0D;IACzE,OAAO,CAAC,eAAe,CAAsE;IAC7F,OAAO,CAAC,eAAe,CAA4D;IACnF,OAAO,CAAC,kBAAkB,CAAyC;IACnE,OAAO,CAAC,OAAO,CAAwB;IACvC,OAAO,CAAC,cAAc,CAAwB;IAC9C,OAAO,CAAC,aAAa,CAAM;IAC3B,OAAO,CAAC,cAAc,CAAkB;IACxC,OAAO,CAAC,SAAS,CAAuB;IACxC,OAAO,CAAC,YAAY,CAA+B;;IAcnD,OAAO,CAAC,mBAAmB;IAmB3B,OAAO,CAAC,sBAAsB;YAqChB,aAAa;IAsB3B,OAAO,CAAC,qBAAqB;IAO7B,OAAO,CAAC,gBAAgB;IAkBxB,OAAO,CAAC,gBAAgB;IASxB,OAAO,CAAC,sBAAsB;IAkC9B,OAAO,CAAC,mBAAmB;YASb,oBAAoB;YAwBpB,oBAAoB;IAwBlC,OAAO,CAAC,iBAAiB;IAsBzB,OAAO,CAAC,aAAa;IA2BrB,OAAO,CAAC,mBAAmB;IAoDrB,aAAa,CACjB,GAAG,EAAE,OAAO,CAAC,OAAO,EACpB,GAAG,EAAE,OAAO,CAAC,QAAQ,EACrB,eAAe,CAAC,EAAE,eAAe,GAChC,OAAO,CAAC,IAAI,CAAC;YAmOF,eAAe;IA8C7B,OAAO,CAAC,SAAS;IAQX,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAgnBtB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAkD/B,cAAc,IAAI;QAChB,MAAM,EAAE,OAAO,CAAC;QAChB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,QAAQ,CAAC,EAAE;YACT,KAAK,EAAE,MAAM,CAAC;YACd,MAAM,EAAE,MAAM,CAAC;YACf,OAAO,EAAE,MAAM,CAAC;YAChB,GAAG,EAAE,MAAM,CAAC;YACZ,UAAU,EAAE,MAAM,EAAE,CAAC;SACtB,CAAC;KACH;CA8BF"}
+{"version":3,"file":"http-server-single-session.d.ts","sourceRoot":"","sources":["../src/http-server-single-session.ts"],"names":[],"mappings":";AAMA,OAAO,OAAO,MAAM,SAAS,CAAC;AAoB9B,OAAO,EAAE,eAAe,EAA2B,MAAM,0BAA0B,CAAC;AACpF,OAAO,EAAE,kBAAkB,EAAE,YAAY,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AA+CvG,qBAAa,uBAAuB;IAElC,OAAO,CAAC,UAAU,CAA8D;IAChF,OAAO,CAAC,OAAO,CAA0D;IACzE,OAAO,CAAC,eAAe,CAAsE;IAC7F,OAAO,CAAC,eAAe,CAA4D;IACnF,OAAO,CAAC,kBAAkB,CAAyC;IACnE,OAAO,CAAC,OAAO,CAAwB;IACvC,OAAO,CAAC,cAAc,CAAwB;IAC9C,OAAO,CAAC,aAAa,CAAM;IAC3B,OAAO,CAAC,cAAc,CAAkB;IACxC,OAAO,CAAC,SAAS,CAAuB;IACxC,OAAO,CAAC,YAAY,CAA+B;IAGnD,OAAO,CAAC,iBAAiB,CAAC,CAAqB;IAC/C,OAAO,CAAC,yBAAyB,CAAS;IAG1C,OAAO,CAAC,aAAa,CAAC,CAAyB;IAG/C,OAAO,CAAC,yBAAyB,CAAS;IAC1C,OAAO,CAAC,4BAA4B,CAAS;gBAEjC,OAAO,GAAE;QACnB,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,iBAAiB,CAAC,EAAE,kBAAkB,CAAC;QACvC,yBAAyB,CAAC,EAAE,MAAM,CAAC;QACnC,aAAa,CAAC,EAAE,sBAAsB,CAAC;QACvC,yBAAyB,CAAC,EAAE,MAAM,CAAC;QACnC,4BAA4B,CAAC,EAAE,MAAM,CAAC;KAClC;IA6BN,OAAO,CAAC,mBAAmB;IAmB3B,OAAO,CAAC,sBAAsB;YAiEhB,aAAa;IAsB3B,OAAO,CAAC,qBAAqB;IAO7B,OAAO,CAAC,gBAAgB;IAwBxB,OAAO,CAAC,gBAAgB;IAwBxB,OAAO,CAAC,sBAAsB;IAkC9B,OAAO,CAAC,mBAAmB;YAmBb,oBAAoB;YAwBpB,oBAAoB;IA6BlC,OAAO,CAAC,OAAO;YAkBD,SAAS;YAkCT,uBAAuB;IAmGrC,OAAO,CAAC,aAAa;IA+IrB,OAAO,CAAC,iBAAiB;IAwBzB,OAAO,CAAC,iBAAiB;IAsBzB,OAAO,CAAC,aAAa;IA2BrB,OAAO,CAAC,mBAAmB;IAoDrB,aAAa,CACjB,GAAG,EAAE,OAAO,CAAC,OAAO,EACpB,GAAG,EAAE,OAAO,CAAC,QAAQ,EACrB,eAAe,CAAC,EAAE,eAAe,GAChC,OAAO,CAAC,IAAI,CAAC;YA4WF,eAAe;IA8C7B,OAAO,CAAC,SAAS;IAQX,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAgnBtB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAkD/B,cAAc,IAAI;QAChB,MAAM,EAAE,OAAO,CAAC;QAChB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,QAAQ,CAAC,EAAE;YACT,KAAK,EAAE,MAAM,CAAC;YACd,MAAM,EAAE,MAAM,CAAC;YACf,OAAO,EAAE,MAAM,CAAC;YAChB,GAAG,EAAE,MAAM,CAAC;YACZ,UAAU,EAAE,MAAM,EAAE,CAAC;SACtB,CAAC;KACH;IA4CD,iBAAiB,IAAI,MAAM,EAAE;IAsB7B,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI;IA4CvD,mBAAmB,IAAI,YAAY,EAAE;IAkCrC,sBAAsB,CAAC,SAAS,EAAE,MAAM,EAAE,eAAe,EAAE,eAAe,GAAG,OAAO;IAyEpF,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;CA+ClD"}

package/dist/http-server-single-session.js

@@ -35,7 +35,7 @@ function extractMultiTenantHeaders(req) {
     };
 }
 class SingleSessionHTTPServer {
-    constructor() {
+    constructor(options = {}) {
         this.transports = {};
         this.servers = {};
         this.sessionMetadata = {};
@@ -47,6 +47,14 @@ class SingleSessionHTTPServer {
         this.authToken = null;
         this.cleanupTimer = null;
         this.validateEnvironment();
+        this.onSessionNotFound = options.onSessionNotFound;
+        this.sessionRestorationTimeout = options.sessionRestorationTimeout || 5000;
+        this.sessionEvents = options.sessionEvents;
+        this.sessionRestorationRetries = options.sessionRestorationRetries ?? 0;
+        this.sessionRestorationRetryDelay = options.sessionRestorationRetryDelay || 100;
+        if (options.sessionTimeout) {
+            this.sessionTimeout = options.sessionTimeout;
+        }
         this.startSessionCleanup();
     }
     startSessionCleanup() {
@@ -79,7 +87,28 @@ class SingleSessionHTTPServer {
                 logger_1.logger.debug('Cleaned orphaned session context', { sessionId });
             }
         }
+        for (const sessionId in this.transports) {
+            if (!this.sessionMetadata[sessionId]) {
+                logger_1.logger.warn('Orphaned transport detected, cleaning up', { sessionId });
+                this.removeSession(sessionId, 'orphaned_transport').catch(err => {
+                    logger_1.logger.error('Error cleaning orphaned transport', { sessionId, error: err });
+                });
+            }
+        }
+        for (const sessionId in this.servers) {
+            if (!this.sessionMetadata[sessionId]) {
+                logger_1.logger.warn('Orphaned server detected, cleaning up', { sessionId });
+                delete this.servers[sessionId];
+                logger_1.logger.debug('Cleaned orphaned server', { sessionId });
+            }
+        }
         for (const sessionId of expiredSessions) {
+            this.emitEvent('onSessionExpired', sessionId).catch(err => {
+                logger_1.logger.error('Failed to emit onSessionExpired event (non-blocking)', {
+                    sessionId,
+                    error: err instanceof Error ? err.message : String(err)
+                });
+            });
             this.removeSession(sessionId, 'expired');
         }
         if (expiredSessions.length > 0) {
@@ -111,7 +140,16 @@ class SingleSessionHTTPServer {
         return this.getActiveSessionCount() < MAX_SESSIONS;
     }
     isValidSessionId(sessionId) {
-        return Boolean(sessionId && sessionId.length > 0);
+        if (!sessionId || typeof sessionId !== 'string') {
+            return false;
+        }
+        if (!/^[a-zA-Z0-9_-]+$/.test(sessionId)) {
+            return false;
+        }
+        if (sessionId.length > 100) {
+            return false;
+        }
+        return true;
     }
     sanitizeErrorForClient(error) {
         const isProduction = process.env.NODE_ENV === 'production';
@@ -138,6 +176,12 @@ class SingleSessionHTTPServer {
     updateSessionAccess(sessionId) {
         if (this.sessionMetadata[sessionId]) {
             this.sessionMetadata[sessionId].lastAccess = new Date();
+            this.emitEvent('onSessionAccessed', sessionId).catch(err => {
+                logger_1.logger.error('Failed to emit onSessionAccessed event (non-blocking)', {
+                    sessionId,
+                    error: err instanceof Error ? err.message : String(err)
+                });
+            });
         }
     }
     async switchSessionContext(sessionId, newContext) {
@@ -169,6 +213,211 @@ class SingleSessionHTTPServer {
             }
         }
     }
+    timeout(ms) {
+        return new Promise((_, reject) => {
+            setTimeout(() => {
+                const error = new Error(`Operation timed out after ${ms}ms`);
+                error.name = 'TimeoutError';
+                reject(error);
+            }, ms);
+        });
+    }
+    async emitEvent(eventName, ...args) {
+        const handler = this.sessionEvents?.[eventName];
+        if (!handler)
+            return;
+        try {
+            await Promise.resolve(handler(...args));
+        }
+        catch (error) {
+            logger_1.logger.error(`Session event handler failed: ${eventName}`, {
+                error: error instanceof Error ? error.message : String(error),
+                sessionId: args[0]
+            });
+        }
+    }
+    async restoreSessionWithRetry(sessionId) {
+        if (!this.onSessionNotFound) {
+            throw new Error('onSessionNotFound hook not configured');
+        }
+        const maxRetries = this.sessionRestorationRetries;
+        const retryDelay = this.sessionRestorationRetryDelay;
+        const overallTimeout = this.sessionRestorationTimeout;
+        const startTime = Date.now();
+        for (let attempt = 0; attempt <= maxRetries; attempt++) {
+            try {
+                const remainingTime = overallTimeout - (Date.now() - startTime);
+                if (remainingTime <= 0) {
+                    const error = new Error(`Session restoration timed out after ${overallTimeout}ms`);
+                    error.name = 'TimeoutError';
+                    throw error;
+                }
+                if (attempt > 0) {
+                    logger_1.logger.debug('Retrying session restoration', {
+                        sessionId,
+                        attempt: attempt,
+                        maxRetries: maxRetries,
+                        remainingTime: remainingTime + 'ms'
+                    });
+                }
+                const context = await Promise.race([
+                    this.onSessionNotFound(sessionId),
+                    this.timeout(remainingTime)
+                ]);
+                if (attempt > 0) {
+                    logger_1.logger.info('Session restoration succeeded after retry', {
+                        sessionId,
+                        attempts: attempt + 1
+                    });
+                }
+                return context;
+            }
+            catch (error) {
+                if (error instanceof Error && error.name === 'TimeoutError') {
+                    logger_1.logger.error('Session restoration timeout (no retry)', {
+                        sessionId,
+                        timeout: overallTimeout
+                    });
+                    throw error;
+                }
+                if (attempt === maxRetries) {
+                    logger_1.logger.error('Session restoration failed after all retries', {
+                        sessionId,
+                        attempts: attempt + 1,
+                        error: error instanceof Error ? error.message : String(error)
+                    });
+                    throw error;
+                }
+                logger_1.logger.warn('Session restoration failed, will retry', {
+                    sessionId,
+                    attempt: attempt + 1,
+                    maxRetries: maxRetries,
+                    error: error instanceof Error ? error.message : String(error),
+                    nextRetryIn: retryDelay + 'ms'
+                });
+                await new Promise(resolve => setTimeout(resolve, retryDelay));
+            }
+        }
+        throw new Error('Unexpected state in restoreSessionWithRetry');
+    }
+    createSession(instanceContext, sessionId, waitForConnection = false) {
+        const id = sessionId || this.generateSessionId(instanceContext);
+        if (this.transports[id]) {
+            logger_1.logger.debug('Session already exists, skipping creation (idempotent)', {
+                sessionId: id
+            });
+            return waitForConnection ? Promise.resolve(id) : id;
+        }
+        if (sessionId && !this.isValidSessionId(sessionId)) {
+            logger_1.logger.error('Invalid session ID format during creation', { sessionId });
+            throw new Error('Invalid session ID format');
+        }
+        if (!this.sessionMetadata[id]) {
+            this.sessionMetadata[id] = {
+                lastAccess: new Date(),
+                createdAt: new Date()
+            };
+            this.sessionContexts[id] = instanceContext;
+        }
+        const server = new server_1.N8NDocumentationMCPServer(instanceContext);
+        const transport = new streamableHttp_js_1.StreamableHTTPServerTransport({
+            sessionIdGenerator: () => id,
+            onsessioninitialized: (initializedSessionId) => {
+                logger_1.logger.info('Session initialized during explicit creation', {
+                    sessionId: initializedSessionId
+                });
+            }
+        });
+        this.transports[id] = transport;
+        this.servers[id] = server;
+        transport.onclose = () => {
+            if (transport.sessionId) {
+                logger_1.logger.info('Transport closed during createSession, cleaning up', {
+                    sessionId: transport.sessionId
+                });
+                this.removeSession(transport.sessionId, 'transport_closed').catch(err => {
+                    logger_1.logger.error('Error during transport close cleanup', {
+                        sessionId: transport.sessionId,
+                        error: err instanceof Error ? err.message : String(err)
+                    });
+                });
+            }
+        };
+        transport.onerror = (error) => {
+            if (transport.sessionId) {
+                logger_1.logger.error('Transport error during createSession', {
+                    sessionId: transport.sessionId,
+                    error: error.message
+                });
+                this.removeSession(transport.sessionId, 'transport_error').catch(err => {
+                    logger_1.logger.error('Error during transport error cleanup', { error: err });
+                });
+            }
+        };
+        const initializeSession = async () => {
+            try {
+                await server.initialized;
+                await server.connect(transport);
+                if (waitForConnection) {
+                    logger_1.logger.info('Session created and connected successfully', {
+                        sessionId: id,
+                        hasInstanceContext: !!instanceContext,
+                        instanceId: instanceContext?.instanceId
+                    });
+                }
+                else {
+                    logger_1.logger.info('Session created successfully (connecting server to transport)', {
+                        sessionId: id,
+                        hasInstanceContext: !!instanceContext,
+                        instanceId: instanceContext?.instanceId
+                    });
+                }
+            }
+            catch (err) {
+                logger_1.logger.error('Failed to connect server to transport in createSession', {
+                    sessionId: id,
+                    error: err instanceof Error ? err.message : String(err),
+                    waitForConnection
+                });
+                await this.removeSession(id, 'connection_failed').catch(cleanupErr => {
+                    logger_1.logger.error('Error during connection failure cleanup', { error: cleanupErr });
+                });
+                throw err;
+            }
+            this.emitEvent('onSessionCreated', id, instanceContext).catch(eventErr => {
+                logger_1.logger.error('Failed to emit onSessionCreated event (non-blocking)', {
+                    sessionId: id,
+                    error: eventErr instanceof Error ? eventErr.message : String(eventErr)
+                });
+            });
+            return id;
+        };
+        if (waitForConnection) {
+            return initializeSession();
+        }
+        initializeSession().catch(error => {
+            logger_1.logger.error('Async session creation failed in manual restore flow', {
+                sessionId: id,
+                error: error instanceof Error ? error.message : String(error)
+            });
+        });
+        return id;
+    }
+    generateSessionId(instanceContext) {
+        const isMultiTenantEnabled = process.env.ENABLE_MULTI_TENANT === 'true';
+        const sessionStrategy = process.env.MULTI_TENANT_SESSION_STRATEGY || 'instance';
+        if (isMultiTenantEnabled && sessionStrategy === 'instance' && instanceContext?.instanceId) {
+            const configHash = (0, crypto_1.createHash)('sha256')
+                .update(JSON.stringify({
+                url: instanceContext.n8nApiUrl,
+                instanceId: instanceContext.instanceId
+            }))
+                .digest('hex')
+                .substring(0, 8);
+            return `instance-${instanceContext.instanceId}-${configHash}-${(0, uuid_1.v4)()}`;
+        }
+        return (0, uuid_1.v4)();
+    }
     getSessionMetrics() {
         const now = Date.now();
         let expiredCount = 0;
@@ -350,29 +599,142 @@ class SingleSessionHTTPServer {
                     this.updateSessionAccess(sessionId);
                 }
                 else {
-                    const errorDetails = {
-                        hasSessionId: !!sessionId,
-                        isInitialize: isInitialize,
-                        sessionIdValid: sessionId ? this.isValidSessionId(sessionId) : false,
-                        sessionExists: sessionId ? !!this.transports[sessionId] : false
-                    };
-                    logger_1.logger.warn('handleRequest: Invalid request - no session ID and not initialize', errorDetails);
-                    let errorMessage = 'Bad Request: No valid session ID provided and not an initialize request';
-                    if (sessionId && !this.isValidSessionId(sessionId)) {
-                        errorMessage = 'Bad Request: Invalid session ID format';
+                    if (sessionId) {
+                        if (!this.isValidSessionId(sessionId)) {
+                            logger_1.logger.warn('handleRequest: Invalid session ID format rejected', {
+                                sessionId: sessionId.substring(0, 20)
+                            });
+                            res.status(400).json({
+                                jsonrpc: '2.0',
+                                error: {
+                                    code: -32602,
+                                    message: 'Invalid session ID format'
+                                },
+                                id: req.body?.id || null
+                            });
+                            return;
+                        }
+                        if (this.onSessionNotFound) {
+                            logger_1.logger.info('Attempting session restoration', { sessionId });
+                            try {
+                                const restoredContext = await this.restoreSessionWithRetry(sessionId);
+                                if (restoredContext === null || restoredContext === undefined) {
+                                    logger_1.logger.info('Session restoration declined by hook', {
+                                        sessionId,
+                                        returnValue: restoredContext === null ? 'null' : 'undefined'
+                                    });
+                                    res.status(400).json({
+                                        jsonrpc: '2.0',
+                                        error: {
+                                            code: -32000,
+                                            message: 'Session not found or expired'
+                                        },
+                                        id: req.body?.id || null
+                                    });
+                                    return;
+                                }
+                                const validation = (0, instance_context_1.validateInstanceContext)(restoredContext);
+                                if (!validation.valid) {
+                                    logger_1.logger.error('Invalid context returned from restoration hook', {
+                                        sessionId,
+                                        errors: validation.errors
+                                    });
+                                    res.status(400).json({
+                                        jsonrpc: '2.0',
+                                        error: {
+                                            code: -32000,
+                                            message: 'Invalid session context'
+                                        },
+                                        id: req.body?.id || null
+                                    });
+                                    return;
+                                }
+                                logger_1.logger.info('Session restoration successful, creating session', {
+                                    sessionId,
+                                    instanceId: restoredContext.instanceId
+                                });
+                                await this.createSession(restoredContext, sessionId, true);
+                                if (!this.transports[sessionId]) {
+                                    logger_1.logger.error('Session creation failed after restoration', { sessionId });
+                                    res.status(500).json({
+                                        jsonrpc: '2.0',
+                                        error: {
+                                            code: -32603,
+                                            message: 'Session creation failed'
+                                        },
+                                        id: req.body?.id || null
+                                    });
+                                    return;
+                                }
+                                this.emitEvent('onSessionRestored', sessionId, restoredContext).catch(err => {
+                                    logger_1.logger.error('Failed to emit onSessionRestored event (non-blocking)', {
+                                        sessionId,
+                                        error: err instanceof Error ? err.message : String(err)
+                                    });
+                                });
+                                transport = this.transports[sessionId];
+                                logger_1.logger.info('Using restored session transport', { sessionId });
+                            }
+                            catch (error) {
+                                if (error instanceof Error && error.name === 'TimeoutError') {
+                                    logger_1.logger.error('Session restoration timeout', {
+                                        sessionId,
+                                        timeout: this.sessionRestorationTimeout
+                                    });
+                                    res.status(408).json({
+                                        jsonrpc: '2.0',
+                                        error: {
+                                            code: -32000,
+                                            message: 'Session restoration timeout'
+                                        },
+                                        id: req.body?.id || null
+                                    });
+                                    return;
+                                }
+                                logger_1.logger.error('Session restoration failed', {
+                                    sessionId,
+                                    error: error instanceof Error ? error.message : String(error)
+                                });
+                                res.status(500).json({
+                                    jsonrpc: '2.0',
+                                    error: {
+                                        code: -32603,
+                                        message: 'Session restoration failed'
+                                    },
+                                    id: req.body?.id || null
+                                });
+                                return;
+                            }
+                        }
+                        else {
+                            logger_1.logger.warn('Session not found and no restoration hook configured', {
+                                sessionId
+                            });
+                            res.status(400).json({
+                                jsonrpc: '2.0',
+                                error: {
+                                    code: -32000,
+                                    message: 'Session not found or expired'
+                                },
+                                id: req.body?.id || null
+                            });
+                            return;
+                        }
                     }
-                    else if (sessionId && !this.transports[sessionId]) {
-                        errorMessage = 'Bad Request: Session not found or expired';
+                    else {
+                        logger_1.logger.warn('handleRequest: Invalid request - no session ID and not initialize', {
+                            isInitialize
+                        });
+                        res.status(400).json({
+                            jsonrpc: '2.0',
+                            error: {
+                                code: -32000,
+                                message: 'Bad Request: No valid session ID provided and not an initialize request'
+                            },
+                            id: req.body?.id || null
+                        });
+                        return;
                     }
-                    res.status(400).json({
-                        jsonrpc: '2.0',
-                        error: {
-                            code: -32000,
-                            message: errorMessage
-                        },
-                        id: req.body?.id || null
-                    });
-                    return;
                 }
                 logger_1.logger.info('handleRequest: Handling request with transport', {
                     sessionId: isInitialize ? 'new' : sessionId,
@@ -1018,6 +1380,117 @@ class SingleSessionHTTPServer {
             }
         };
     }
+    getActiveSessions() {
+        return Object.keys(this.sessionMetadata);
+    }
+    getSessionState(sessionId) {
+        const metadata = this.sessionMetadata[sessionId];
+        if (!metadata) {
+            return null;
+        }
+        const instanceContext = this.sessionContexts[sessionId];
+        const expiresAt = new Date(metadata.lastAccess.getTime() + this.sessionTimeout);
+        return {
+            sessionId,
+            instanceContext: instanceContext || {
+                n8nApiUrl: process.env.N8N_API_URL,
+                n8nApiKey: process.env.N8N_API_KEY,
+                instanceId: process.env.N8N_INSTANCE_ID
+            },
+            createdAt: metadata.createdAt,
+            lastAccess: metadata.lastAccess,
+            expiresAt,
+            metadata: instanceContext?.metadata
+        };
+    }
+    getAllSessionStates() {
+        const sessionIds = this.getActiveSessions();
+        const states = [];
+        for (const sessionId of sessionIds) {
+            const state = this.getSessionState(sessionId);
+            if (state) {
+                states.push(state);
+            }
+        }
+        return states;
+    }
+    manuallyRestoreSession(sessionId, instanceContext) {
+        try {
+            if (!this.isValidSessionId(sessionId)) {
+                logger_1.logger.error('Invalid session ID format in manual restoration', { sessionId });
+                return false;
+            }
+            const validation = (0, instance_context_1.validateInstanceContext)(instanceContext);
+            if (!validation.valid) {
+                logger_1.logger.error('Invalid instance context in manual restoration', {
+                    sessionId,
+                    errors: validation.errors
+                });
+                return false;
+            }
+            this.sessionMetadata[sessionId] = {
+                lastAccess: new Date(),
+                createdAt: new Date()
+            };
+            this.sessionContexts[sessionId] = instanceContext;
+            const creationResult = this.createSession(instanceContext, sessionId, false);
+            Promise.resolve(creationResult).catch(error => {
+                logger_1.logger.error('Async session creation failed in manual restoration', {
+                    sessionId,
+                    error: error instanceof Error ? error.message : String(error)
+                });
+                delete this.sessionMetadata[sessionId];
+                delete this.sessionContexts[sessionId];
+            });
+            logger_1.logger.info('Session manually restored', {
+                sessionId,
+                instanceId: instanceContext.instanceId
+            });
+            return true;
+        }
+        catch (error) {
+            logger_1.logger.error('Failed to manually restore session', {
+                sessionId,
+                error: error instanceof Error ? error.message : String(error)
+            });
+            return false;
+        }
+    }
+    manuallyDeleteSession(sessionId) {
+        if (!this.sessionMetadata[sessionId]) {
+            logger_1.logger.debug('Session not found for manual deletion', { sessionId });
+            return false;
+        }
+        try {
+            if (this.transports[sessionId]) {
+                this.transports[sessionId].close().catch(error => {
+                    logger_1.logger.warn('Error closing transport during manual deletion', {
+                        sessionId,
+                        error: error instanceof Error ? error.message : String(error)
+                    });
+                });
+            }
+            this.emitEvent('onSessionDeleted', sessionId).catch(err => {
+                logger_1.logger.error('Failed to emit onSessionDeleted event (non-blocking)', {
+                    sessionId,
+                    error: err instanceof Error ? err.message : String(err)
+                });
+            });
+            delete this.transports[sessionId];
+            delete this.servers[sessionId];
+            delete this.sessionMetadata[sessionId];
+            delete this.sessionContexts[sessionId];
+            logger_1.logger.info('Session manually deleted', { sessionId });
+            return true;
+        }
+        catch (error) {
+            logger_1.logger.error('Error during manual session deletion', {
+                sessionId,
+                error: error instanceof Error ? error.message : String(error)
+            });
+            return false;
+        }
+    }
 }
 exports.SingleSessionHTTPServer = SingleSessionHTTPServer;
 if (require.main === module) {