@astermind/cybernetic-chatbot-client 2.2.59 → 2.2.62

package/dist/cybernetic-chatbot-client-full.umd.js

@@ -1377,6 +1377,230 @@
         }
     }
 
+    // src/CyberneticSessionStorage.ts
+    // Session storage manager for persisting chatbot session across page navigations
+    const DEFAULT_CONFIG = {
+        enabled: true,
+        storageKey: 'astermind_session',
+        sessionTtl: 30 * 60 * 1000, // 30 minutes
+        persistMessages: true,
+        maxMessages: 50
+    };
+    /**
+     * Session storage manager for persisting chatbot sessions
+     *
+     * Uses sessionStorage to maintain conversation continuity across
+     * page navigations within the same browser session.
+     */
+    class CyberneticSessionStorage {
+        constructor(config) {
+            this.cachedSession = null;
+            this.config = { ...DEFAULT_CONFIG, ...config };
+            // Load cached session on initialization
+            if (this.config.enabled && this.isAvailable()) {
+                this.cachedSession = this.loadFromStorage();
+            }
+        }
+        /**
+         * Check if sessionStorage is available
+         */
+        isAvailable() {
+            if (typeof window === 'undefined')
+                return false;
+            try {
+                const testKey = '__astermind_test__';
+                window.sessionStorage.setItem(testKey, 'test');
+                window.sessionStorage.removeItem(testKey);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        }
+        /**
+         * Get the current session ID (if valid)
+         */
+        getSessionId() {
+            if (!this.config.enabled)
+                return null;
+            const session = this.getSession();
+            return session?.sessionId ?? null;
+        }
+        /**
+         * Get the full stored session (if valid)
+         */
+        getSession() {
+            if (!this.config.enabled)
+                return null;
+            // Use cached session if available
+            if (this.cachedSession) {
+                if (this.isSessionValid(this.cachedSession)) {
+                    return this.cachedSession;
+                }
+                // Session expired, clear it
+                this.clear();
+                return null;
+            }
+            // Try loading from storage
+            const session = this.loadFromStorage();
+            if (session && this.isSessionValid(session)) {
+                this.cachedSession = session;
+                return session;
+            }
+            return null;
+        }
+        /**
+         * Save/update session ID
+         */
+        saveSessionId(sessionId) {
+            if (!this.config.enabled || !sessionId)
+                return;
+            const existingSession = this.getSession();
+            const session = {
+                sessionId,
+                updatedAt: Date.now(),
+                messages: existingSession?.messages ?? []
+            };
+            this.saveToStorage(session);
+            this.cachedSession = session;
+        }
+        /**
+         * Add a message to the conversation history
+         */
+        addMessage(message) {
+            if (!this.config.enabled || !this.config.persistMessages)
+                return;
+            const session = this.getSession();
+            if (!session)
+                return;
+            const newMessage = {
+                ...message,
+                id: this.generateMessageId(),
+                timestamp: Date.now()
+            };
+            // Add new message and trim if necessary
+            session.messages = session.messages ?? [];
+            session.messages.push(newMessage);
+            // Keep only the most recent messages
+            if (session.messages.length > this.config.maxMessages) {
+                session.messages = session.messages.slice(-this.config.maxMessages);
+            }
+            session.updatedAt = Date.now();
+            this.saveToStorage(session);
+            this.cachedSession = session;
+        }
+        /**
+         * Get conversation messages
+         */
+        getMessages() {
+            if (!this.config.enabled || !this.config.persistMessages)
+                return [];
+            const session = this.getSession();
+            return session?.messages ?? [];
+        }
+        /**
+         * Clear the stored session
+         */
+        clear() {
+            this.cachedSession = null;
+            if (!this.isAvailable())
+                return;
+            try {
+                window.sessionStorage.removeItem(this.config.storageKey);
+            }
+            catch (error) {
+                console.warn('[CyberneticSessionStorage] Failed to clear session:', error);
+            }
+        }
+        /**
+         * Start a new session (clears existing and optionally sets new ID)
+         */
+        startNewSession(sessionId) {
+            this.clear();
+            if (sessionId) {
+                this.saveSessionId(sessionId);
+            }
+        }
+        /**
+         * Check if we have a valid stored session
+         */
+        hasValidSession() {
+            return this.getSession() !== null;
+        }
+        /**
+         * Get session info for debugging/status
+         */
+        getSessionInfo() {
+            const session = this.getSession();
+            if (!session) {
+                return {
+                    hasSession: false,
+                    sessionId: null,
+                    messageCount: 0,
+                    lastUpdated: null,
+                    ttlRemaining: null
+                };
+            }
+            const ttlRemaining = Math.max(0, this.config.sessionTtl - (Date.now() - session.updatedAt));
+            return {
+                hasSession: true,
+                sessionId: session.sessionId,
+                messageCount: session.messages?.length ?? 0,
+                lastUpdated: new Date(session.updatedAt),
+                ttlRemaining
+            };
+        }
+        // ==================== PRIVATE METHODS ====================
+        /**
+         * Check if a session is still valid (not expired)
+         */
+        isSessionValid(session) {
+            const age = Date.now() - session.updatedAt;
+            return age < this.config.sessionTtl;
+        }
+        /**
+         * Load session from sessionStorage
+         */
+        loadFromStorage() {
+            if (!this.isAvailable())
+                return null;
+            try {
+                const stored = window.sessionStorage.getItem(this.config.storageKey);
+                if (!stored)
+                    return null;
+                const session = JSON.parse(stored);
+                // Validate structure
+                if (!session.sessionId || typeof session.updatedAt !== 'number') {
+                    return null;
+                }
+                return session;
+            }
+            catch (error) {
+                console.warn('[CyberneticSessionStorage] Failed to load session:', error);
+                return null;
+            }
+        }
+        /**
+         * Save session to sessionStorage
+         */
+        saveToStorage(session) {
+            if (!this.isAvailable())
+                return;
+            try {
+                window.sessionStorage.setItem(this.config.storageKey, JSON.stringify(session));
+            }
+            catch (error) {
+                console.warn('[CyberneticSessionStorage] Failed to save session:', error);
+            }
+        }
+        /**
+         * Generate a unique message ID
+         */
+        generateMessageId() {
+            return `msg_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+        }
+    }
+
     // src/config.ts
     // Configuration loading and validation
     /** Default API URL when not specified */
@@ -2341,6 +2565,8 @@ LJ5AZXvOhHaXdHzMuYKX5BpK4w7TqbPvJ6QPvKmLKvHh1VKcUJ6mJQgJJw==
                 licenseKey: config.licenseKey,
                 environment: config.environment,
             });
+            // Initialize session storage (auto-loads existing session from browser sessionStorage)
+            this.sessionStorage = new CyberneticSessionStorage(config.session);
             // Verify license asynchronously (non-blocking)
             this.licenseManager.verify().then(() => {
                 // Check client feature after verification
@@ -2641,6 +2867,40 @@ LJ5AZXvOhHaXdHzMuYKX5BpK4w7TqbPvJ6QPvKmLKvHh1VKcUJ6mJQgJJw==
         getOfflineStorage() {
             return this.offlineStorage;
         }
+        // ==================== SESSION PERSISTENCE METHODS (ADR-028) ====================
+        /**
+         * Get stored messages from a previous session for UI restoration.
+         * Call after construction to check for resumable conversations.
+         */
+        getStoredMessages() {
+            return this.sessionStorage.getMessages();
+        }
+        /**
+         * Check if a valid stored session exists that can be resumed.
+         */
+        hasStoredSession() {
+            return this.sessionStorage.hasValidSession();
+        }
+        /**
+         * Get session info for debugging/status display.
+         */
+        getSessionInfo() {
+            return this.sessionStorage.getSessionInfo();
+        }
+        /**
+         * Clear the stored session and start fresh.
+         * Use for "New Conversation" actions.
+         */
+        clearSession() {
+            this.sessionStorage.clear();
+        }
+        /**
+         * Start a new session, clearing any stored data.
+         * Optionally sets a new sessionId immediately.
+         */
+        startNewSession(sessionId) {
+            this.sessionStorage.startNewSession(sessionId);
+        }
         // ==================== CORE METHODS ====================
         /**
          * Send a message to the chatbot
@@ -2654,6 +2914,11 @@ LJ5AZXvOhHaXdHzMuYKX5BpK4w7TqbPvJ6QPvKmLKvHh1VKcUJ6mJQgJJw==
             if (!message || typeof message !== 'string') {
                 return this.createErrorResponse('Message is required', 'none');
             }
+            // Auto-resolve sessionId: explicit option > stored session > none (ADR-028)
+            const resolvedSessionId = options?.sessionId ?? this.sessionStorage.getSessionId() ?? undefined;
+            const resolvedOptions = resolvedSessionId
+                ? { ...options, sessionId: resolvedSessionId }
+                : options;
             // Check maintenance mode before API call (ADR-200)
             const settings = await this.checkSystemStatus();
             if (settings.maintenanceMode || settings.forceOfflineClients) {
@@ -2674,10 +2939,16 @@ LJ5AZXvOhHaXdHzMuYKX5BpK4w7TqbPvJ6QPvKmLKvHh1VKcUJ6mJQgJJw==
             }
             // Try API first
             try {
-                const response = await this.apiWithRetry(message, options);
+                const response = await this.apiWithRetry(message, resolvedOptions);
                 this.setStatus('online');
                 // Process response through license manager (may add warning in production)
                 const processedReply = this.licenseManager.processResponse(response.reply);
+                // Persist session state (ADR-028)
+                if (response.sessionId) {
+                    this.sessionStorage.saveSessionId(response.sessionId);
+                }
+                this.sessionStorage.addMessage({ role: 'user', content: message });
+                this.sessionStorage.addMessage({ role: 'assistant', content: processedReply, confidence: 'high' });
                 return {
                     reply: processedReply,
                     confidence: 'high',
@@ -2723,6 +2994,13 @@ LJ5AZXvOhHaXdHzMuYKX5BpK4w7TqbPvJ6QPvKmLKvHh1VKcUJ6mJQgJJw==
                 });
                 return;
             }
+            // Auto-resolve sessionId: explicit option > stored session > none (ADR-028)
+            const resolvedSessionId = options?.sessionId ?? this.sessionStorage.getSessionId() ?? undefined;
+            const resolvedOptions = resolvedSessionId
+                ? { ...options, sessionId: resolvedSessionId }
+                : options;
+            // Save user message immediately (ADR-028)
+            this.sessionStorage.addMessage({ role: 'user', content: message });
             // Check maintenance mode before API call (ADR-200)
             const settings = await this.checkSystemStatus();
             if (settings.maintenanceMode || settings.forceOfflineClients) {
@@ -2735,14 +3013,19 @@ LJ5AZXvOhHaXdHzMuYKX5BpK4w7TqbPvJ6QPvKmLKvHh1VKcUJ6mJQgJJw==
             if (this.wsTransport && this.config.transport !== 'rest') {
                 try {
                     await this.wsTransport.chatStream(message, {
-                        sessionId: options?.sessionId,
-                        context: options?.context,
+                        sessionId: resolvedOptions?.sessionId,
+                        context: resolvedOptions?.context,
                         onToken: callbacks.onToken,
                         onSources: callbacks.onSources,
                         onComplete: (response) => {
                             this.setStatus('online');
                             // Process through license manager
                             const processedReply = this.licenseManager.processResponse(response.reply);
+                            // Persist session state (ADR-028)
+                            if (response.sessionId) {
+                                this.sessionStorage.saveSessionId(response.sessionId);
+                            }
+                            this.sessionStorage.addMessage({ role: 'assistant', content: processedReply, confidence: 'high' });
                             callbacks.onComplete?.({
                                 ...response,
                                 reply: processedReply
@@ -2752,7 +3035,7 @@ LJ5AZXvOhHaXdHzMuYKX5BpK4w7TqbPvJ6QPvKmLKvHh1VKcUJ6mJQgJJw==
                             // In 'auto' mode, fall back to SSE on WS error
                             if (this.config.transport === 'auto') {
                                 console.warn('[Cybernetic] WebSocket error, falling back to SSE:', error.message);
-                                this.streamViaSSE(message, callbacks, options);
+                                this.streamViaSSE(message, callbacks, resolvedOptions);
                             }
                             else {
                                 // 'websocket' mode — no fallback
@@ -2778,7 +3061,7 @@ LJ5AZXvOhHaXdHzMuYKX5BpK4w7TqbPvJ6QPvKmLKvHh1VKcUJ6mJQgJJw==
                 }
             }
             // REST+SSE path (on-prem, or fallback from WebSocket)
-            await this.streamViaSSE(message, callbacks, options);
+            await this.streamViaSSE(message, callbacks, resolvedOptions);
         }
         /**
          * Stream chat via REST+SSE (original transport).
@@ -2795,6 +3078,11 @@ LJ5AZXvOhHaXdHzMuYKX5BpK4w7TqbPvJ6QPvKmLKvHh1VKcUJ6mJQgJJw==
                         this.setStatus('online');
                         // Process response through license manager (may add warning in production)
                         const processedReply = this.licenseManager.processResponse(data.fullText);
+                        // Persist session state (ADR-028)
+                        if (data.sessionId) {
+                            this.sessionStorage.saveSessionId(data.sessionId);
+                        }
+                        this.sessionStorage.addMessage({ role: 'assistant', content: processedReply, confidence: 'high' });
                         callbacks.onComplete?.({
                             reply: processedReply,
                             confidence: 'high',