@astermind/cybernetic-chatbot-client 2.2.36 → 2.2.48

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

@@ -4,13 +4,14 @@ import 'path';
 // src/ApiClient.ts
 // HTTP client for AsterMind backend API
 /**
- * Map backend source format to client Source interface
+ * Map backend source format to client Source interface.
+ * Handles both canonical (title/score) and legacy (heading/no-score) field names.
  */
 function mapSource(raw) {
     return {
-        title: raw.title,
-        snippet: raw.content,
-        relevance: raw.score,
+        title: raw.title || raw.heading || 'Document',
+        snippet: raw.content || '',
+        relevance: raw.score ?? 0,
         documentId: raw.documentId,
         fullContent: raw.fullContent,
         downloadUrl: raw.downloadUrl,
@@ -48,9 +49,10 @@ class ApiClient {
             throw new Error(error.message || `HTTP ${response.status}: ${response.statusText}`);
         }
         const data = await response.json();
-        // Map backend source format to client Source interface
+        // Normalize response: accept both 'reply' (canonical) and 'answer' (legacy)
         return {
             ...data,
+            reply: data.reply || data.answer || '',
             sources: (data.sources || []).map(mapSource)
         };
     }
@@ -126,7 +128,8 @@ class ApiClient {
         }
     }
     /**
-     * Get general documents for caching
+     * Get general documents for caching.
+     * Normalizes field names from both canonical (title) and legacy (name) formats.
      */
     async getGeneralDocs(since) {
         const params = new URLSearchParams();
@@ -143,10 +146,16 @@ class ApiClient {
             throw new Error(`HTTP ${response.status}`);
         }
         const data = await response.json();
-        return data.documents;
+        // Normalize: accept both 'title' (canonical) and 'name' (legacy on-prem)
+        return (data.documents || []).map((doc) => ({
+            id: doc.id,
+            title: doc.title || doc.name || 'Untitled',
+            updatedAt: doc.updatedAt || doc.updated_at || new Date().toISOString(),
+        }));
     }
     /**
-     * Get API status, quota, and system settings
+     * Get API status, quota, and system settings.
+     * Normalizes response from both canonical and legacy backend formats.
      */
     async getStatus() {
         const response = await fetch(`${this.baseUrl}/api/external/status`, {
@@ -157,7 +166,38 @@ class ApiClient {
         if (!response.ok) {
             throw new Error(`HTTP ${response.status}`);
         }
-        return response.json();
+        const data = await response.json();
+        // Normalize: accept both canonical (apiKey) and legacy (key) structures
+        const apiKeyData = data.apiKey || data.key || {};
+        const scopes = apiKeyData.scopes || apiKeyData.permissions || ['chat'];
+        // Normalize quota: accept both canonical (perMinute/perDay) and legacy structures
+        const quota = data.quota || {};
+        const perMinute = quota.perMinute || {
+            limit: apiKeyData.rateLimit?.limit || quota.rateLimitPerMinute || 30,
+            remaining: apiKeyData.rateLimit?.remaining ?? quota.rateLimitPerMinute ?? 30,
+        };
+        const perDay = quota.perDay || {
+            limit: quota.rateLimitPerDay || perMinute.limit * 60 * 24,
+            remaining: quota.rateLimitPerDay || perMinute.limit * 60 * 24,
+        };
+        // Normalize systemSettings: accept both canonical and legacy (system) structures
+        const settings = data.systemSettings || data.system || {};
+        const cacheRetentionHours = settings.cacheRetentionHours ??
+            (settings.cacheRetentionDays ? settings.cacheRetentionDays * 24 : undefined);
+        return {
+            status: data.status || 'active',
+            apiKey: {
+                id: apiKeyData.id || '',
+                scopes,
+            },
+            quota: { perMinute, perDay },
+            systemSettings: {
+                cacheRetentionHours: cacheRetentionHours ?? 720,
+                maintenanceMode: settings.maintenanceMode ?? false,
+                maintenanceMessage: settings.maintenanceMessage,
+                forceOfflineClients: settings.forceOfflineClients ?? false,
+            },
+        };
     }
     /**
      * Health check (no auth required)
@@ -1013,6 +1053,595 @@ class CyberneticOfflineStorage {
     }
 }
 
+// src/WebSocketTransport.ts
+// WebSocket transport for streaming chat via SaaS WebSocket API (chatws.astermind.ai)
+/**
+ * WebSocket transport for streaming chat.
+ *
+ * Maps the chat-handler Lambda WebSocket protocol to the client's StreamCallbacks:
+ *   Server typing  → ignored (UI has its own indicator)
+ *   Server chunk   → onToken(content)
+ *   Server done    → onSources(sources) + onComplete(response)
+ *   Server error   → onError(error)
+ *
+ * Connection is lazy — established on the first chatStream() call.
+ * Reuses the same connection across multiple messages.
+ * Reconnects with exponential backoff on close/error.
+ */
+class WebSocketTransport {
+    constructor(wsUrl, apiKey, options) {
+        this.ws = null;
+        this.state = 'disconnected';
+        this.reconnectAttempts = 0;
+        this.connectionPromise = null;
+        // Active streaming request tracking
+        this.activeCallbacks = null;
+        this.activeFullText = '';
+        // Cleanup handler reference
+        this.beforeUnloadHandler = null;
+        // Promise callbacks for the active stream
+        this._resolveStream = null;
+        this._rejectStream = null;
+        this.wsUrl = wsUrl;
+        this.apiKey = apiKey;
+        this.maxReconnectAttempts = options?.maxReconnectAttempts ?? 3;
+        this.reconnectDelay = options?.reconnectDelay ?? 1000;
+        this.connectionTimeout = options?.connectionTimeout ?? 10000;
+    }
+    /**
+     * Current transport state
+     */
+    getState() {
+        return this.state;
+    }
+    /**
+     * Whether the WebSocket is currently connected
+     */
+    isConnected() {
+        return this.state === 'connected' && this.ws?.readyState === WebSocket.OPEN;
+    }
+    /**
+     * Connect to the WebSocket endpoint.
+     * Appends the API key as a query parameter for authentication.
+     * Returns a promise that resolves when the connection is open.
+     */
+    connect() {
+        // Already connected
+        if (this.isConnected()) {
+            return Promise.resolve();
+        }
+        // Connection already in progress
+        if (this.connectionPromise) {
+            return this.connectionPromise;
+        }
+        this.state = 'connecting';
+        this.connectionPromise = new Promise((resolve, reject) => {
+            try {
+                // Build URL with API key
+                const separator = this.wsUrl.includes('?') ? '&' : '?';
+                const fullUrl = `${this.wsUrl}${separator}apiKey=${encodeURIComponent(this.apiKey)}`;
+                const ws = new WebSocket(fullUrl);
+                this.ws = ws;
+                // Connection timeout
+                const timeout = setTimeout(() => {
+                    if (ws.readyState !== WebSocket.OPEN) {
+                        ws.close();
+                        this.state = 'error';
+                        this.connectionPromise = null;
+                        reject(new Error('WebSocket connection timed out'));
+                    }
+                }, this.connectionTimeout);
+                ws.onopen = () => {
+                    clearTimeout(timeout);
+                    this.state = 'connected';
+                    this.reconnectAttempts = 0;
+                    this.connectionPromise = null;
+                    this.registerCleanup();
+                    resolve();
+                };
+                ws.onmessage = (event) => {
+                    this.handleMessage(event);
+                };
+                ws.onerror = () => {
+                    clearTimeout(timeout);
+                    this.state = 'error';
+                    this.connectionPromise = null;
+                    // The close event fires after error, which will trigger reconnect
+                };
+                ws.onclose = (event) => {
+                    clearTimeout(timeout);
+                    const wasConnected = this.state === 'connected';
+                    this.state = 'disconnected';
+                    this.connectionPromise = null;
+                    this.unregisterCleanup();
+                    // If we had an active request, report the error
+                    if (this.activeCallbacks) {
+                        this.activeCallbacks.onError?.({
+                            code: 'WS_ERROR',
+                            message: event.reason || `WebSocket closed (code: ${event.code})`
+                        });
+                        this.clearActiveRequest();
+                    }
+                    // Reject if we were trying to connect
+                    if (!wasConnected) {
+                        reject(new Error(event.reason || `WebSocket closed (code: ${event.code})`));
+                    }
+                };
+            }
+            catch (error) {
+                this.state = 'error';
+                this.connectionPromise = null;
+                reject(error);
+            }
+        });
+        return this.connectionPromise;
+    }
+    /**
+     * Stream a chat message over WebSocket.
+     *
+     * Sends: { type: "sendMessage", message, sessionId?, wordLimit?, context? }
+     * Receives: typing → chunk × N → done (with sources and metadata)
+     */
+    async chatStream(message, options) {
+        const { sessionId, context, wordLimit, onToken, onSources, onComplete, onError } = options;
+        // Ensure connection is established (lazy connect)
+        try {
+            await this.connect();
+        }
+        catch (error) {
+            onError?.({
+                code: 'WS_ERROR',
+                message: `Failed to connect: ${error instanceof Error ? error.message : String(error)}`
+            });
+            throw error;
+        }
+        if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+            const err = { code: 'WS_ERROR', message: 'WebSocket not connected' };
+            onError?.(err);
+            throw new Error(err.message);
+        }
+        // Set up active request tracking
+        this.activeCallbacks = { onToken, onSources, onComplete, onError };
+        this.activeFullText = '';
+        this.activeSessionId = sessionId;
+        // Build and send the message
+        const payload = {
+            type: 'sendMessage',
+            message,
+        };
+        if (sessionId)
+            payload.sessionId = sessionId;
+        if (wordLimit)
+            payload.wordLimit = wordLimit;
+        if (context)
+            payload.context = context;
+        // Return a promise that resolves when done/error is received
+        return new Promise((resolve, reject) => {
+            // Store resolve/reject so handleMessage can call them
+            this._resolveStream = resolve;
+            this._rejectStream = reject;
+            this.ws.send(JSON.stringify(payload));
+        });
+    }
+    /**
+     * Disconnect and clean up the WebSocket connection
+     */
+    disconnect() {
+        this.unregisterCleanup();
+        if (this.ws) {
+            // Remove handlers to avoid triggering reconnect
+            this.ws.onclose = null;
+            this.ws.onerror = null;
+            this.ws.onmessage = null;
+            this.ws.close();
+            this.ws = null;
+        }
+        this.state = 'disconnected';
+        this.connectionPromise = null;
+        this.clearActiveRequest();
+    }
+    /**
+     * Attempt reconnection with exponential backoff.
+     * Used internally after connection loss.
+     */
+    async reconnect() {
+        if (this.reconnectAttempts >= this.maxReconnectAttempts) {
+            this.state = 'error';
+            throw new Error(`Max reconnection attempts (${this.maxReconnectAttempts}) exceeded`);
+        }
+        const delay = this.reconnectDelay * Math.pow(2, this.reconnectAttempts);
+        this.reconnectAttempts++;
+        console.log(`[Cybernetic WS] Reconnecting in ${delay}ms (attempt ${this.reconnectAttempts}/${this.maxReconnectAttempts})`);
+        await new Promise(resolve => setTimeout(resolve, delay));
+        // Ensure old connection is cleaned up
+        if (this.ws) {
+            this.ws.onclose = null;
+            this.ws.onerror = null;
+            this.ws.close();
+            this.ws = null;
+        }
+        return this.connect();
+    }
+    // ==================== INTERNAL ====================
+    /**
+     * Handle incoming WebSocket messages from the chat-handler Lambda.
+     *
+     * Protocol:
+     *   { type: 'typing', status: boolean }    → ignored
+     *   { type: 'chunk', content: string }      → onToken(content)
+     *   { type: 'done', sessionId, sources, metadata, messageId } → onSources + onComplete
+     *   { type: 'error', error: string }        → onError
+     */
+    handleMessage(event) {
+        if (!this.activeCallbacks)
+            return;
+        try {
+            const data = JSON.parse(event.data);
+            switch (data.type) {
+                case 'typing':
+                    // Ignored — the chatbot-template manages its own typing indicator
+                    break;
+                case 'chunk':
+                    if (data.content) {
+                        this.activeFullText += data.content;
+                        this.activeCallbacks.onToken?.(data.content);
+                    }
+                    break;
+                case 'done': {
+                    // Map sources from chat-handler format to client Source format
+                    const sources = this.mapSources(data.sources || []);
+                    // Emit sources
+                    this.activeCallbacks.onSources?.(sources);
+                    // Build complete response
+                    const response = {
+                        reply: this.activeFullText,
+                        confidence: 'high',
+                        sources,
+                        offline: false,
+                        sessionId: data.sessionId || this.activeSessionId,
+                    };
+                    this.activeCallbacks.onComplete?.(response);
+                    this._resolveStream?.();
+                    this.clearActiveRequest();
+                    break;
+                }
+                case 'error': {
+                    const err = {
+                        code: 'WS_ERROR',
+                        message: data.error || 'Unknown WebSocket error'
+                    };
+                    this.activeCallbacks.onError?.(err);
+                    this._rejectStream?.(new Error(err.message));
+                    this.clearActiveRequest();
+                    break;
+                }
+                default:
+                    // Unknown message type — log and ignore
+                    console.warn('[Cybernetic WS] Unknown message type:', data.type);
+                    break;
+            }
+        }
+        catch (error) {
+            console.error('[Cybernetic WS] Failed to parse message:', error, event.data);
+        }
+    }
+    /**
+     * Map sources from the chat-handler WebSocket format to the client Source interface.
+     *
+     * Chat-handler sends: { heading, content, score, documentId, documentName }
+     * Client expects:      { title, snippet, relevance, documentId, documentName }
+     */
+    mapSources(wsSources) {
+        if (!Array.isArray(wsSources))
+            return [];
+        return wsSources.map((s) => ({
+            title: s.title || s.heading || s.documentName || 'Document',
+            snippet: s.content || '',
+            relevance: s.score ?? 0,
+            documentId: s.documentId,
+            documentName: s.documentName,
+            sourceType: s.sourceType || 'document',
+            chunkId: s.chunkId,
+        }));
+    }
+    /**
+     * Clear active request state after completion or error
+     */
+    clearActiveRequest() {
+        this.activeCallbacks = null;
+        this.activeFullText = '';
+        this._resolveStream = null;
+        this._rejectStream = null;
+    }
+    /**
+     * Register a beforeunload handler to close the WebSocket on page unload
+     */
+    registerCleanup() {
+        if (typeof window !== 'undefined' && !this.beforeUnloadHandler) {
+            this.beforeUnloadHandler = () => this.disconnect();
+            window.addEventListener('beforeunload', this.beforeUnloadHandler);
+        }
+    }
+    /**
+     * Remove the beforeunload handler
+     */
+    unregisterCleanup() {
+        if (typeof window !== 'undefined' && this.beforeUnloadHandler) {
+            window.removeEventListener('beforeunload', this.beforeUnloadHandler);
+            this.beforeUnloadHandler = null;
+        }
+    }
+}
+
+// src/config.ts
+// Configuration loading and validation
+/** Default API URL when not specified */
+const DEFAULT_API_URL = 'https://api.astermind.ai';
+/**
+ * Derive WebSocket URL from API URL for known SaaS domains.
+ * Maps REST API domains to their WebSocket counterparts:
+ *   chatapi.astermind.ai     → wss://chatws.astermind.ai
+ *   chatapi-dev.astermind.ai → wss://chatws-dev.astermind.ai
+ *   api.astermind.ai         → wss://chatws.astermind.ai
+ *
+ * Returns undefined for non-SaaS (on-prem) URLs.
+ */
+function deriveWsUrl(apiUrl) {
+    try {
+        const url = new URL(apiUrl);
+        // chatapi[-env].astermind.ai → chatws[-env].astermind.ai
+        const match = url.hostname.match(/^chatapi(-[\w]+)?\.astermind\.ai$/);
+        if (match) {
+            const envSuffix = match[1] || '';
+            return `wss://chatws${envSuffix}.astermind.ai`;
+        }
+        // api.astermind.ai → chatws.astermind.ai (default SaaS)
+        if (url.hostname === 'api.astermind.ai') {
+            return 'wss://chatws.astermind.ai';
+        }
+    }
+    catch {
+        // Invalid URL, no WS derivation
+    }
+    return undefined;
+}
+/**
+ * Try to load wsUrl from environment or globals.
+ * Returns the first found wsUrl or undefined.
+ */
+function loadWsUrl() {
+    // Vite env var
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const importMeta = globalThis.import?.meta?.env;
+        if (importMeta?.VITE_ASTERMIND_RAG_WS_URL) {
+            return importMeta.VITE_ASTERMIND_RAG_WS_URL;
+        }
+    }
+    catch { /* not available */ }
+    // Node.js / CRA env var
+    if (typeof process !== 'undefined' && process.env) {
+        if (process.env.ASTERMIND_RAG_WS_URL)
+            return process.env.ASTERMIND_RAG_WS_URL;
+        if (process.env.REACT_APP_ASTERMIND_RAG_WS_URL)
+            return process.env.REACT_APP_ASTERMIND_RAG_WS_URL;
+    }
+    // SSR-injected config
+    if (typeof window !== 'undefined') {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const injected = window.__ASTERMIND_CONFIG__;
+        if (injected?.wsUrl)
+            return injected.wsUrl;
+        // Global config object
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const globalConfig = window.astermindConfig;
+        if (globalConfig?.wsUrl)
+            return globalConfig.wsUrl;
+    }
+    // Script data attribute
+    if (typeof document !== 'undefined') {
+        const script = document.querySelector('script[data-astermind-ws-url]');
+        if (script) {
+            const wsUrl = script.getAttribute('data-astermind-ws-url');
+            if (wsUrl)
+                return wsUrl;
+        }
+    }
+    return undefined;
+}
+/**
+ * Resolve the WebSocket URL for a given config.
+ * Priority: explicit wsUrl → env var → auto-derived from apiUrl
+ */
+function resolveWsUrl(config) {
+    // Explicit wsUrl takes priority
+    if (config.wsUrl)
+        return config.wsUrl;
+    // Don't auto-detect if transport is forced to REST
+    if (config.transport === 'rest')
+        return undefined;
+    // Try environment / globals
+    const envWsUrl = loadWsUrl();
+    if (envWsUrl)
+        return envWsUrl;
+    // Auto-derive from apiUrl for known SaaS domains
+    return deriveWsUrl(config.apiUrl);
+}
+/**
+ * Validate configuration
+ */
+function validateConfig(config) {
+    if (!config || typeof config !== 'object') {
+        throw new Error('Config must be an object');
+    }
+    const c = config;
+    if (!c.apiUrl || typeof c.apiUrl !== 'string') {
+        throw new Error('apiUrl is required and must be a string');
+    }
+    if (!c.apiKey || typeof c.apiKey !== 'string') {
+        throw new Error('apiKey is required and must be a string');
+    }
+    if (!c.apiKey.startsWith('am_')) {
+        throw new Error('apiKey must start with "am_"');
+    }
+    return true;
+}
+/**
+ * Load config from Node.js process.env (for bundlers that replace process.env)
+ */
+function loadFromProcessEnv() {
+    // Check if process.env exists (Node.js or bundler-injected)
+    if (typeof process === 'undefined' || !process.env) {
+        return null;
+    }
+    // Check for ASTERMIND_RAG_* env vars (non-prefixed, for Node.js/server environments)
+    const apiKey = process.env.ASTERMIND_RAG_API_KEY;
+    const apiUrl = process.env.ASTERMIND_RAG_API_SERVER_URL;
+    if (apiKey) {
+        return {
+            apiKey,
+            apiUrl: apiUrl || DEFAULT_API_URL,
+            _source: 'env'
+        };
+    }
+    // Check for CRA-style REACT_APP_* env vars
+    const craApiKey = process.env.REACT_APP_ASTERMIND_RAG_API_KEY;
+    const craApiUrl = process.env.REACT_APP_ASTERMIND_RAG_API_SERVER_URL;
+    if (craApiKey) {
+        return {
+            apiKey: craApiKey,
+            apiUrl: craApiUrl || DEFAULT_API_URL,
+            _source: 'env'
+        };
+    }
+    return null;
+}
+/**
+ * Load config from Vite's import.meta.env (browser environment)
+ * Note: This only works at build time when Vite replaces the variables
+ */
+function loadFromViteEnv() {
+    // Check for window.__ASTERMIND_CONFIG__ (SSR-injected config)
+    if (typeof window !== 'undefined') {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const injected = window.__ASTERMIND_CONFIG__;
+        if (injected && typeof injected === 'object' && injected.apiKey) {
+            return {
+                ...injected,
+                apiUrl: injected.apiUrl || DEFAULT_API_URL,
+                _source: 'vite'
+            };
+        }
+    }
+    // Check for Vite's import.meta.env (replaced at build time)
+    // Note: TypeScript doesn't know about import.meta.env, so we use a try-catch
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const importMeta = globalThis.import?.meta?.env;
+        if (importMeta) {
+            const apiKey = importMeta.VITE_ASTERMIND_RAG_API_KEY;
+            const apiUrl = importMeta.VITE_ASTERMIND_RAG_API_SERVER_URL;
+            if (apiKey) {
+                return {
+                    apiKey,
+                    apiUrl: apiUrl || DEFAULT_API_URL,
+                    _source: 'vite'
+                };
+            }
+        }
+    }
+    catch {
+        // import.meta not available in this environment
+    }
+    return null;
+}
+/**
+ * Load config from window.astermindConfig global object
+ */
+function loadFromGlobalObject() {
+    if (typeof window === 'undefined') {
+        return null;
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const globalConfig = window.astermindConfig;
+    if (globalConfig && typeof globalConfig === 'object' && globalConfig.apiKey) {
+        return {
+            ...globalConfig,
+            apiUrl: globalConfig.apiUrl || DEFAULT_API_URL,
+            _source: 'window'
+        };
+    }
+    return null;
+}
+/**
+ * Load config from script tag data attributes
+ */
+function loadFromScriptAttributes() {
+    if (typeof window === 'undefined' || typeof document === 'undefined') {
+        return null;
+    }
+    const script = document.querySelector('script[data-astermind-key]');
+    if (script) {
+        const apiKey = script.getAttribute('data-astermind-key');
+        if (apiKey) {
+            return {
+                apiKey,
+                apiUrl: script.getAttribute('data-astermind-url') || DEFAULT_API_URL,
+                _source: 'data-attr'
+            };
+        }
+    }
+    return null;
+}
+/**
+ * Load config using priority-based fallback chain:
+ * 1. Environment variables (process.env - for bundlers/Node.js)
+ * 2. Vite environment variables (import.meta.env or window.__ASTERMIND_CONFIG__)
+ * 3. Global object (window.astermindConfig)
+ * 4. Script data attributes (data-astermind-key, data-astermind-url)
+ *
+ * @param options - Configuration options
+ * @param options.throwOnMissingKey - If true (default), throws when no API key found. If false, returns null and logs a warning.
+ * @returns Configuration object or null if not found and throwOnMissingKey is false
+ */
+function loadConfig(options = {}) {
+    const { throwOnMissingKey = true } = options;
+    // Priority 1: Environment variables (Node.js/bundler)
+    const envConfig = loadFromProcessEnv();
+    if (envConfig) {
+        return envConfig;
+    }
+    // Priority 2: Vite environment variables / SSR-injected config
+    const viteConfig = loadFromViteEnv();
+    if (viteConfig) {
+        return viteConfig;
+    }
+    // Priority 3: Global object (window.astermindConfig)
+    const globalConfig = loadFromGlobalObject();
+    if (globalConfig) {
+        validateConfig(globalConfig);
+        return globalConfig;
+    }
+    // Priority 4: Script data attributes
+    const scriptConfig = loadFromScriptAttributes();
+    if (scriptConfig) {
+        return scriptConfig;
+    }
+    // No config found
+    if (throwOnMissingKey) {
+        throw new Error('AsterMind API key is required. Configure using one of these methods:\n' +
+            '  1. Set VITE_ASTERMIND_RAG_API_KEY environment variable (Vite)\n' +
+            '  2. Set REACT_APP_ASTERMIND_RAG_API_KEY environment variable (CRA)\n' +
+            '  3. Set window.astermindConfig = { apiKey: "am_...", apiUrl: "..." }\n' +
+            '  4. Add data-astermind-key attribute to your script tag\n' +
+            '  5. Pass apiKey directly to createClient() or CyberneticClient constructor');
+    }
+    else {
+        console.warn('[AsterMind] No API key found. Chatbot will not function until configured.');
+        return null;
+    }
+}
+
 // src/license/base64url.ts
 // Base64URL encoding/decoding utilities for JWT handling
 /**
@@ -1648,6 +2277,7 @@ async function createLicenseManager(config) {
  */
 class CyberneticClient {
     constructor(config) {
+        this.wsTransport = null;
         this.status = 'connecting';
         this.lastError = null;
         // Maintenance mode tracking (ADR-200)
@@ -1662,10 +2292,15 @@ class CyberneticClient {
         this.omegaRAG = null;
         // Track if offline warning has been shown
         this.offlineWarningShown = false;
+        // Resolve WebSocket URL (explicit → env → auto-derived from apiUrl)
+        const wsUrl = resolveWsUrl(config);
+        const transport = config.transport ?? 'auto';
         // Apply defaults
         this.config = {
             apiUrl: config.apiUrl,
             apiKey: config.apiKey,
+            wsUrl,
+            transport,
             fallback: {
                 enabled: config.fallback?.enabled ?? true,
                 cacheMaxAge: config.fallback?.cacheMaxAge ?? 86400000, // 24 hours
@@ -1708,6 +2343,11 @@ class CyberneticClient {
         }).catch(() => {
             // License verification errors are handled internally
         });
+        // Initialize WebSocket transport if configured and not forced to REST
+        if (wsUrl && transport !== 'rest' && typeof WebSocket !== 'undefined') {
+            this.wsTransport = new WebSocketTransport(wsUrl, config.apiKey, config.websocket);
+            console.log(`[Cybernetic] WebSocket transport enabled: ${wsUrl}`);
+        }
         // Monitor connection status
         this.monitorConnection();
         // Pre-cache documents on init if enabled
@@ -2086,6 +2726,60 @@ class CyberneticClient {
             callbacks.onComplete?.(response);
             return;
         }
+        // Try WebSocket transport first (if available and not forced to REST)
+        if (this.wsTransport && this.config.transport !== 'rest') {
+            try {
+                await this.wsTransport.chatStream(message, {
+                    sessionId: options?.sessionId,
+                    context: options?.context,
+                    onToken: callbacks.onToken,
+                    onSources: callbacks.onSources,
+                    onComplete: (response) => {
+                        this.setStatus('online');
+                        // Process through license manager
+                        const processedReply = this.licenseManager.processResponse(response.reply);
+                        callbacks.onComplete?.({
+                            ...response,
+                            reply: processedReply
+                        });
+                    },
+                    onError: (error) => {
+                        // 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);
+                        }
+                        else {
+                            // 'websocket' mode — no fallback
+                            const normalizedError = this.normalizeError(error);
+                            this.config.onError(normalizedError);
+                            callbacks.onError?.(normalizedError);
+                        }
+                    }
+                });
+                return;
+            }
+            catch (error) {
+                if (this.config.transport === 'websocket') {
+                    // Forced WebSocket mode — don't fall back
+                    const normalizedError = this.normalizeError(error);
+                    this.lastError = normalizedError;
+                    this.config.onError(normalizedError);
+                    callbacks.onError?.(normalizedError);
+                    return;
+                }
+                // 'auto' mode: fall through to SSE
+                console.warn('[Cybernetic] WebSocket connect failed, using SSE fallback');
+            }
+        }
+        // REST+SSE path (on-prem, or fallback from WebSocket)
+        await this.streamViaSSE(message, callbacks, options);
+    }
+    /**
+     * Stream chat via REST+SSE (original transport).
+     * Used as the primary transport for on-prem, or as fallback for SaaS WebSocket failures.
+     */
+    async streamViaSSE(message, callbacks, options) {
         try {
             await this.apiClient.chatStream(message, {
                 sessionId: options?.sessionId,
@@ -2169,6 +2863,16 @@ class CyberneticClient {
         await this.cache.clear();
         this.localRAG.reset();
     }
+    /**
+     * Clean up all resources (WebSocket connection, caches, event listeners).
+     * Call this when the client is no longer needed to prevent memory leaks.
+     */
+    destroy() {
+        if (this.wsTransport) {
+            this.wsTransport.disconnect();
+            this.wsTransport = null;
+        }
+    }
     /**
      * Manually check if backend is reachable
      */
@@ -2479,185 +3183,6 @@ class CyberneticClient {
     }
 }
 
-// src/config.ts
-// Configuration loading and validation
-/** Default API URL when not specified */
-const DEFAULT_API_URL = 'https://api.astermind.ai';
-/**
- * Validate configuration
- */
-function validateConfig(config) {
-    if (!config || typeof config !== 'object') {
-        throw new Error('Config must be an object');
-    }
-    const c = config;
-    if (!c.apiUrl || typeof c.apiUrl !== 'string') {
-        throw new Error('apiUrl is required and must be a string');
-    }
-    if (!c.apiKey || typeof c.apiKey !== 'string') {
-        throw new Error('apiKey is required and must be a string');
-    }
-    if (!c.apiKey.startsWith('am_')) {
-        throw new Error('apiKey must start with "am_"');
-    }
-    return true;
-}
-/**
- * Load config from Node.js process.env (for bundlers that replace process.env)
- */
-function loadFromProcessEnv() {
-    // Check if process.env exists (Node.js or bundler-injected)
-    if (typeof process === 'undefined' || !process.env) {
-        return null;
-    }
-    // Check for ASTERMIND_RAG_* env vars (non-prefixed, for Node.js/server environments)
-    const apiKey = process.env.ASTERMIND_RAG_API_KEY;
-    const apiUrl = process.env.ASTERMIND_RAG_API_SERVER_URL;
-    if (apiKey) {
-        return {
-            apiKey,
-            apiUrl: apiUrl || DEFAULT_API_URL,
-            _source: 'env'
-        };
-    }
-    // Check for CRA-style REACT_APP_* env vars
-    const craApiKey = process.env.REACT_APP_ASTERMIND_RAG_API_KEY;
-    const craApiUrl = process.env.REACT_APP_ASTERMIND_RAG_API_SERVER_URL;
-    if (craApiKey) {
-        return {
-            apiKey: craApiKey,
-            apiUrl: craApiUrl || DEFAULT_API_URL,
-            _source: 'env'
-        };
-    }
-    return null;
-}
-/**
- * Load config from Vite's import.meta.env (browser environment)
- * Note: This only works at build time when Vite replaces the variables
- */
-function loadFromViteEnv() {
-    // Check for window.__ASTERMIND_CONFIG__ (SSR-injected config)
-    if (typeof window !== 'undefined') {
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        const injected = window.__ASTERMIND_CONFIG__;
-        if (injected && typeof injected === 'object' && injected.apiKey) {
-            return {
-                ...injected,
-                apiUrl: injected.apiUrl || DEFAULT_API_URL,
-                _source: 'vite'
-            };
-        }
-    }
-    // Check for Vite's import.meta.env (replaced at build time)
-    // Note: TypeScript doesn't know about import.meta.env, so we use a try-catch
-    try {
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        const importMeta = globalThis.import?.meta?.env;
-        if (importMeta) {
-            const apiKey = importMeta.VITE_ASTERMIND_RAG_API_KEY;
-            const apiUrl = importMeta.VITE_ASTERMIND_RAG_API_SERVER_URL;
-            if (apiKey) {
-                return {
-                    apiKey,
-                    apiUrl: apiUrl || DEFAULT_API_URL,
-                    _source: 'vite'
-                };
-            }
-        }
-    }
-    catch {
-        // import.meta not available in this environment
-    }
-    return null;
-}
-/**
- * Load config from window.astermindConfig global object
- */
-function loadFromGlobalObject() {
-    if (typeof window === 'undefined') {
-        return null;
-    }
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const globalConfig = window.astermindConfig;
-    if (globalConfig && typeof globalConfig === 'object' && globalConfig.apiKey) {
-        return {
-            ...globalConfig,
-            apiUrl: globalConfig.apiUrl || DEFAULT_API_URL,
-            _source: 'window'
-        };
-    }
-    return null;
-}
-/**
- * Load config from script tag data attributes
- */
-function loadFromScriptAttributes() {
-    if (typeof window === 'undefined' || typeof document === 'undefined') {
-        return null;
-    }
-    const script = document.querySelector('script[data-astermind-key]');
-    if (script) {
-        const apiKey = script.getAttribute('data-astermind-key');
-        if (apiKey) {
-            return {
-                apiKey,
-                apiUrl: script.getAttribute('data-astermind-url') || DEFAULT_API_URL,
-                _source: 'data-attr'
-            };
-        }
-    }
-    return null;
-}
-/**
- * Load config using priority-based fallback chain:
- * 1. Environment variables (process.env - for bundlers/Node.js)
- * 2. Vite environment variables (import.meta.env or window.__ASTERMIND_CONFIG__)
- * 3. Global object (window.astermindConfig)
- * 4. Script data attributes (data-astermind-key, data-astermind-url)
- *
- * @param options - Configuration options
- * @param options.throwOnMissingKey - If true (default), throws when no API key found. If false, returns null and logs a warning.
- * @returns Configuration object or null if not found and throwOnMissingKey is false
- */
-function loadConfig(options = {}) {
-    const { throwOnMissingKey = true } = options;
-    // Priority 1: Environment variables (Node.js/bundler)
-    const envConfig = loadFromProcessEnv();
-    if (envConfig) {
-        return envConfig;
-    }
-    // Priority 2: Vite environment variables / SSR-injected config
-    const viteConfig = loadFromViteEnv();
-    if (viteConfig) {
-        return viteConfig;
-    }
-    // Priority 3: Global object (window.astermindConfig)
-    const globalConfig = loadFromGlobalObject();
-    if (globalConfig) {
-        validateConfig(globalConfig);
-        return globalConfig;
-    }
-    // Priority 4: Script data attributes
-    const scriptConfig = loadFromScriptAttributes();
-    if (scriptConfig) {
-        return scriptConfig;
-    }
-    // No config found
-    if (throwOnMissingKey) {
-        throw new Error('AsterMind API key is required. Configure using one of these methods:\n' +
-            '  1. Set VITE_ASTERMIND_RAG_API_KEY environment variable (Vite)\n' +
-            '  2. Set REACT_APP_ASTERMIND_RAG_API_KEY environment variable (CRA)\n' +
-            '  3. Set window.astermindConfig = { apiKey: "am_...", apiUrl: "..." }\n' +
-            '  4. Add data-astermind-key attribute to your script tag\n' +
-            '  5. Pass apiKey directly to createClient() or CyberneticClient constructor');
-    }
-    else {
-        console.warn('[AsterMind] No API key found. Chatbot will not function until configured.');
-        return null;
-    }
-}
-
 // src/agentic/SiteMapDiscovery.ts
 // Multi-source sitemap discovery and merging for agentic navigation
 // Zero-config mode: automatically discovers routes on any site