@mooncompany/uplink-chat 0.5.0

package/public/js/connection.js

@@ -0,0 +1,1231 @@
+// ============================================
+// CONNECTION MODULE
+// WebSocket connection orchestrator
+// Imports WS and API modules
+// ============================================
+
+import { UplinkLogger } from './logger.js';
+import { UplinkCore } from './core.js';
+import { emit as emitEvent } from './event-bus.js';
+import * as ConnectionAPI from './connection-api.js';
+
+const STORAGE_KEY = 'uplink-connection';
+
+// WebSocket configuration
+const config = {
+  maxReconnectAttempts: 10,
+  baseReconnectDelay: 1000,
+  maxReconnectDelay: 30000,
+  heartbeatInterval: 15000,
+  persistentRetryInterval: 60000
+};
+
+// Deduplication for sync messages
+const seenMessageIds = new Set();
+const MAX_SEEN_IDS = 1000;
+const CONTENT_DEDUP_WINDOW_MS = 60000; // 60 second window for content-based dedup
+const recentContentHashes = new Map(); // hash -> timestamp
+
+// Active sync streams for real-time cross-device streaming
+const activeSyncStreams = new Map(); // requestId -> {div, fullResponse, orphanTimer}
+const SYNC_STREAM_ORPHAN_TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes
+
+// Track that a sync stream was used during this processing cycle
+// Prevents SSE from creating a duplicate bubble after WS already handled display
+let syncStreamWasUsed = false;
+
+// WebSocket state now managed by ConnectionWS module
+let ws = null;
+let isConnected = false;
+let connectionListeners = [];
+let isOffline = false;
+let isReconnecting = false;
+
+// Reconnection state
+let reconnectAttempts = 0;
+let reconnectTimer = null;
+let maxRetriesReached = false;
+let persistentRetryTimer = null;
+
+// AbortController for event listeners cleanup
+let eventsAbortController = null;
+
+// Connection mode: 'direct' or 'proxied' (set for debugging)
+window.UPLINK_CONNECTION_MODE = null;
+
+/**
+ * Determine connection mode based on hostname
+ * @returns {string} 'proxied' always
+ * 
+ * NOTE: Uplink's /ws endpoint handles message routing through the channel
+ * layer. The /gateway proxy speaks raw OpenClaw protocol (connect handshake,
+ * req/res/event framing, scopes, device identity) which requires a full
+ * protocol client implementation.
+ * 
+ * TODO: Implement native OpenClaw WebSocket protocol client for direct
+ * gateway-proxy mode. This would eliminate the channel layer overhead
+ * and give true real-time streaming.
+ */
+function getConnectionMode() {
+  return 'proxied';
+}
+
+/**
+ * Build the Gateway WebSocket URL based on connection mode
+ * @param {string} directUrl - The direct Gateway URL (from settings)
+ * @param {string|null} token - The Gateway auth token
+ * @returns {string} The WebSocket URL to use
+ */
+function buildGatewayWsUrl(directUrl, token) {
+  const mode = getConnectionMode();
+  window.UPLINK_CONNECTION_MODE = mode;
+  
+  if (mode === 'direct') {
+    // Use direct connection to Gateway (only works same-origin / localhost)
+    const wsUrl = directUrl.replace(/^http/, 'ws') + '/ws';
+    logger.debug('Connection: Using direct Gateway connection:', wsUrl);
+    return wsUrl;
+  } else {
+    // Use Uplink's WebSocket endpoint
+    const protocol = location.protocol === 'https:' ? 'wss:' : 'ws:';
+    const wsUrl = `${protocol}//${location.host}/ws`;
+    logger.debug('Connection: Using Uplink WebSocket for sync:', wsUrl);
+    return wsUrl;
+  }
+}
+
+/**
+ * Get Gateway settings from settings or localStorage
+ * @returns {{url: string, token: string|null}}
+ */
+function getGatewaySettings() {
+  const settings = JSON.parse(localStorage.getItem('uplink-settings') || '{}');
+  const gatewayUrl = settings.gatewayUrl || 'http://localhost:18789';
+  const token = settings.gatewayToken || window.UPLINK_GATEWAY_TOKEN || null;
+  const wsUrl = buildGatewayWsUrl(gatewayUrl, token);
+  
+  return { url: wsUrl, token };
+}
+
+function init() {
+  // Abort previous event listeners to prevent stacking if init called multiple times
+  if (eventsAbortController) {
+    eventsAbortController.abort();
+  }
+  eventsAbortController = new AbortController();
+  const signal = eventsAbortController.signal;
+
+  loadSettings();
+  addConnectionUI();
+  
+  // Listen for visibility changes to reconnect when tab becomes visible
+  document.addEventListener('visibilitychange', () => {
+    if (document.visibilityState === 'visible' && !isOffline) {
+      // Browser throttles WebSocket events in background tabs.
+      // Server may have killed connection for missed pongs.
+      // Force immediate reconnect if connection is not open.
+      if (!ws || ws.readyState !== WebSocket.OPEN) {
+        logger.debug('Connection: Tab resumed, forcing reconnect');
+        // Clear all state to avoid guards blocking reconnection
+        isConnected = false;
+        isReconnecting = false;
+        reconnectAttempts = 0;
+        maxRetriesReached = false;
+        clearTimeout(reconnectTimer);
+        clearTimeout(persistentRetryTimer);
+        reconnect();
+      }
+    }
+  }, { signal });
+
+  // Listen for online/offline events
+  window.addEventListener('online', handleOnline, { signal });
+  window.addEventListener('offline', handleOffline, { signal });
+
+  // Check initial online state
+  if (!navigator.onLine) {
+    handleOffline();
+  } else {
+    // Run initial health check to verify server connectivity
+    checkServerHealth();
+  }
+
+  logger.debug('Connection: Initialized');
+}
+
+// Check server health and establish WebSocket connection
+async function checkServerHealth() {
+  const isHealthy = await ConnectionAPI.checkServerHealth();
+  if (isHealthy) {
+    // Server is reachable - now establish WebSocket for real-time sync
+    logger.debug('Connection: Server reachable, establishing WebSocket');
+    
+    // Get URL based on connection mode (direct or proxied)
+    const { url: wsUrl } = getGatewaySettings();
+    logger.debug('Connection: Mode =', window.UPLINK_CONNECTION_MODE);
+    
+    // Connect WebSocket for real-time updates
+    connect(wsUrl).catch(err => {
+      logger.error('Connection: Initial WebSocket connection failed', err);
+      updateStatus('disconnected');
+    });
+  } else {
+    updateStatus('disconnected');
+  }
+}
+
+function handleOnline() {
+  logger.debug('Connection: Network came online');
+  isOffline = false;
+  removeOfflineBanner();
+  enableSendButton();
+  
+  // Clear persistent retry timer if running
+  if (persistentRetryTimer) {
+    clearTimeout(persistentRetryTimer);
+    persistentRetryTimer = null;
+  }
+  maxRetriesReached = false;
+  isReconnecting = false;
+  
+  // Reset reconnect attempts and trigger reconnect
+  reconnectAttempts = 0;
+  if (!isConnected) {
+    reconnect();
+  }
+}
+
+function handleOffline() {
+  logger.debug('Connection: Network went offline');
+  isOffline = true;
+  showOfflineBanner();
+  disableSendButton();
+  updateStatus('offline');
+}
+
+function showOfflineBanner() {
+  if (document.getElementById('offline-banner')) return;
+  
+  const banner = document.createElement('div');
+  banner.id = 'offline-banner';
+  banner.innerHTML = `
+    <span class="offline-icon">⚠️</span>
+    <span class="offline-text">You are offline. Some features may be unavailable.</span>
+  `;
+  banner.style.cssText = `
+    position: fixed;
+    top: 0;
+    left: 0;
+    right: 0;
+    background: #f59e0b;
+    color: #1f2937;
+    padding: 12px 16px;
+    text-align: center;
+    font-weight: 500;
+    z-index: 100000;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    gap: 8px;
+    box-shadow: 0 2px 8px rgba(0,0,0,0.2);
+  `;
+  
+  document.body.appendChild(banner);
+}
+
+function removeOfflineBanner() {
+  const banner = document.getElementById('offline-banner');
+  if (banner) {
+    banner.remove();
+  }
+}
+
+function disableSendButton() {
+  const sendBtn = document.getElementById('send-btn');
+  if (sendBtn) {
+    sendBtn.disabled = true;
+  }
+}
+
+function enableSendButton() {
+  const sendBtn = document.getElementById('send-btn');
+  if (sendBtn) {
+    sendBtn.disabled = false;
+  }
+}
+
+// Allowed config keys to prevent localStorage poisoning (H-13)
+const ALLOWED_CONFIG_KEYS = new Set(Object.keys(config));
+
+function loadSettings() {
+  try {
+    const saved = localStorage.getItem(STORAGE_KEY);
+    if (saved) {
+      const parsed = JSON.parse(saved);
+      // Only merge recognized config keys to prevent prototype/config poisoning
+      if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+        for (const key of Object.keys(parsed)) {
+          if (ALLOWED_CONFIG_KEYS.has(key) && typeof parsed[key] === typeof config[key]) {
+            config[key] = parsed[key];
+          }
+        }
+      }
+    }
+  } catch (e) {
+    logger.error('Connection: Failed to load settings', e);
+  }
+}
+
+function addConnectionUI() {
+  // Find status badge and logo
+  const badge = document.getElementById('connectionBadge');
+  const logo = document.getElementById('logoRefresh');
+  
+  // Logo click refreshes chat (fetch from Gateway for main satellite)
+  if (logo) {
+    logo.addEventListener('click', () => {
+      if (window.UplinkSatellites?.refreshHistory) {
+        window.UplinkSatellites.refreshHistory();
+        logger.debug('Connection: Refreshing chat via logo click (Gateway fetch)');
+      } else if (window.UplinkChat?.loadHistory) {
+        window.UplinkChat.loadHistory();
+        logger.debug('Connection: Refreshing chat via logo click (local storage)');
+      }
+    });
+  }
+
+  // Hard refresh button - full page reload bypassing cache
+  const refreshBtn = document.getElementById('refreshBtn');
+  if (refreshBtn) {
+    refreshBtn.addEventListener('click', () => {
+      logger.debug('Connection: Hard refresh triggered');
+      // Clear service worker cache then reload
+      if ('caches' in window) {
+        caches.keys().then(names => {
+          return Promise.all(names.map(name => caches.delete(name)));
+        }).then(() => {
+          window.location.reload();
+        });
+      } else {
+        window.location.reload();
+      }
+    });
+  }
+  
+  // Badge click reconnects if disconnected
+  if (badge) {
+    badge.style.cursor = 'pointer';
+    badge.title = 'Connection status - Click to reconnect';
+    
+    badge.addEventListener('click', () => {
+      if (!isConnected) {
+        reconnect();
+      }
+    });
+  }
+}
+
+function connect(url) {
+  if (ws && ws.readyState === WebSocket.OPEN) {
+    return Promise.resolve(ws);
+  }
+
+  return new Promise((resolve, reject) => {
+    let settled = false; // Track whether the promise has been resolved/rejected
+
+    // Connection timeout — if WS doesn't open in 10s, reject
+    const connectTimeout = setTimeout(() => {
+      logger.warn('Connection: WebSocket connection timed out');
+      if (ws) {
+        try { ws.close(); } catch (e) { /* ignore */ }
+      }
+      if (!settled) {
+        settled = true;
+        reject(new Error('Connection timed out'));
+      }
+    }, 10000);
+
+    try {
+      ws = new WebSocket(url);
+      
+      ws.onopen = () => {
+        clearTimeout(connectTimeout);
+        logger.debug('Connection: WebSocket connected');
+        isConnected = true;
+        reconnectAttempts = 0;
+        isReconnecting = false;  // Clear reconnection state on successful connect
+        updateStatus('connected');
+        enableSendButton();
+        startHeartbeat();
+        notifyListeners('connected');
+        emitEvent('connection:status', { status: 'connected' });
+        if (!settled) {
+          settled = true;
+          resolve(ws);
+        }
+      };
+
+      ws.onclose = (event) => {
+        clearTimeout(connectTimeout);
+        logger.debug('Connection: WebSocket closed', event.code, event.reason);
+        isConnected = false;
+        stopHeartbeat();
+        
+        // Only show disconnected if we're not offline
+        if (!isOffline && navigator.onLine) {
+          updateStatus('disconnected');
+        }
+        notifyListeners('disconnected');
+        emitEvent('connection:status', { status: 'disconnected', code: event.code, reason: event.reason });
+        
+        // Reject the promise if we never connected (so reconnect() can handle it)
+        if (!settled) {
+          settled = true;
+          reject(new Error(`WebSocket closed: ${event.code} ${event.reason || ''}`));
+        } else if (event.code !== 1000) {
+          // Already connected and then lost connection — schedule auto-reconnect
+          scheduleReconnect();
+        }
+      };
+
+      ws.onerror = (error) => {
+        clearTimeout(connectTimeout);
+        logger.error('Connection: WebSocket error', error);
+        updateStatus('error');
+        notifyListeners('error', error);
+        // Note: onerror is always followed by onclose, which handles reject
+      };
+
+      ws.onmessage = (event) => {
+        let data;
+        try {
+          data = JSON.parse(event.data);
+        } catch (e) {
+          // Not JSON, pass through
+          notifyListeners('message', event.data);
+          return;
+        }
+
+        try {
+          let type = data.type;
+          let eventData = data;
+
+          // Unwrap OpenClaw event envelope
+          if (data.type === 'event' && data.event && data.payload) {
+            if (data.event === 'sync') {
+              type = 'sync_message';
+              eventData = data.payload;
+            } else if (data.event === 'sync.thinking') {
+              type = 'sync_thinking';
+              eventData = data.payload;
+            } else if (data.event === 'sync.delta') {
+              type = 'sync_delta';
+              eventData = data.payload;
+            } else if (data.event === 'sync.tool') {
+              type = 'sync_tool';
+              eventData = data.payload;
+            } else if (data.event === 'sync.complete') {
+              type = 'sync_complete';
+              eventData = data.payload;
+            } else if (data.event.startsWith('openclaw.')) {
+              type = `openclaw_${data.event.slice(9)}`;
+              eventData = data.payload;
+            } else {
+              type = data.event;
+              eventData = data.payload;
+            }
+          }
+
+          // Handle webhook notifications
+          if (type === 'notification' && eventData.notification) {
+            showWebhookNotification(eventData.notification);
+          }
+
+          // Handle webhook triggers
+          if (type === 'trigger') {
+            handleWebhookTrigger(eventData.action, eventData.params);
+          }
+
+          // Handle webhook messages (show in chat)
+          if (type === 'webhook_message') {
+            if (window.addMessage) {
+              window.addMessage(`[${eventData.source}] ${eventData.message}`, 'user', null, false);
+              window.addMessage(eventData.response, 'assistant', null, false);
+            }
+          }
+
+          // Handle sync messages (cross-device sync)
+          if (type === 'sync_message') {
+            handleSyncMessage(eventData);
+          }
+
+          // Handle real-time sync streaming events
+          if (type === 'sync_thinking') handleSyncThinking(eventData);
+          if (type === 'sync_delta') handleSyncDelta(eventData);
+          if (type === 'sync_tool') handleSyncTool(eventData);
+          if (type === 'sync_complete') handleSyncComplete(eventData);
+
+          // Handle voice processing status updates
+          if (type === 'voiceStatus') {
+            const voiceStatusEl = document.getElementById('voiceStatus');
+            if (voiceStatusEl && eventData.label) {
+              voiceStatusEl.textContent = eventData.label;
+            }
+          }
+
+          // Handle OpenClaw push messages (from transcript watcher)
+          if (type === 'openclaw_message') {
+            handleOpenClawMessage(eventData);
+          }
+
+          // Handle update notifications
+          if (type === 'update_available') {
+            window.dispatchEvent(new CustomEvent('uplink:ws-message', { detail: eventData }));
+          }
+        } catch (e) {
+          if (window.UplinkLogger) UplinkLogger.error('Connection: Message handler error', e);
+        }
+
+        notifyListeners('message', event.data);
+      };
+
+    } catch (err) {
+      reject(err);
+    }
+  });
+}
+
+function disconnect() {
+  if (ws) {
+    ws.close(1000, 'User disconnect');
+    ws = null;
+  }
+  clearTimeout(reconnectTimer);
+  clearTimeout(persistentRetryTimer);
+  stopHeartbeat();
+  isConnected = false;
+  reconnectAttempts = 0;
+  maxRetriesReached = false;
+  isReconnecting = false;
+}
+
+function reconnect() {
+  clearTimeout(reconnectTimer);  // Prevent duplicate reconnects
+  if (isConnected || isReconnecting) return;
+  
+  // Don't try to reconnect if we're offline
+  if (isOffline || !navigator.onLine) {
+    logger.debug('Connection: Skipping reconnect - network is offline');
+    updateStatus('offline');
+    return;
+  }
+  
+  // Set lock to prevent multiple simultaneous reconnection attempts
+  isReconnecting = true;
+  
+  // Get URL based on connection mode (direct or proxied)
+  const { url: wsUrl } = getGatewaySettings();
+  
+  logger.debug('Connection: Reconnecting to', wsUrl.replace(/token=[^&]+/, 'token=***'));
+  logger.debug('Connection: Mode =', window.UPLINK_CONNECTION_MODE);
+  updateStatus('reconnecting');
+  
+  connect(wsUrl).then(() => {
+    // Clear reconnection state on successful connect
+    isReconnecting = false;
+  }).catch(err => {
+    logger.error('Connection: Reconnect failed', err);
+    isReconnecting = false;
+    scheduleReconnect();
+  });
+}
+
+function scheduleReconnect() {
+  // If we've reached max attempts, switch to persistent retry mode
+  if (reconnectAttempts >= config.maxReconnectAttempts) {
+    if (!maxRetriesReached) {
+      logger.debug('Connection: Max reconnect attempts reached, switching to persistent retry mode');
+      maxRetriesReached = true;
+      updateStatus('failed');
+    }
+    
+    // Keep trying at reduced frequency (once per minute)
+    const persistentDelay = config.persistentRetryInterval;
+    logger.debug(`Connection: Persistent retry in ${persistentDelay/1000}s`);
+    
+    persistentRetryTimer = setTimeout(() => {
+      reconnectAttempts = 0; // Reset to try normal reconnection again
+      reconnect();
+    }, persistentDelay);
+    return;
+  }
+
+  // Exponential backoff with jitter (±30%)
+  const baseDelay = Math.min(
+    config.baseReconnectDelay * Math.pow(2, reconnectAttempts),
+    config.maxReconnectDelay
+  );
+  const delay = Math.round(baseDelay * (1 + Math.random() * 0.3));
+  
+  reconnectAttempts++;
+  logger.debug(`Connection: Reconnect attempt ${reconnectAttempts} in ${Math.round(delay/1000)}s`);
+  
+  // Update status with attempt info
+  updateStatus('reconnecting', { attempt: reconnectAttempts });
+  
+  reconnectTimer = setTimeout(() => {
+    reconnect();
+  }, delay);
+}
+
+let heartbeatTimer = null;
+
+function startHeartbeat() {
+  stopHeartbeat();
+  heartbeatTimer = setInterval(() => {
+    if (ws && ws.readyState === WebSocket.OPEN) {
+      ws.send(JSON.stringify({ type: 'ping' }));
+    }
+  }, config.heartbeatInterval);
+}
+
+function stopHeartbeat() {
+  if (heartbeatTimer) {
+    clearInterval(heartbeatTimer);
+    heartbeatTimer = null;
+  }
+}
+
+function updateStatus(status, extraInfo = null) {
+  const statusEl = document.getElementById('status');
+  const dotEl = document.querySelector('.status-dot');
+  
+  if (!statusEl) return;
+
+  let statusText = {
+    connected: 'Connected',
+    disconnected: 'Disconnected',
+    connecting: 'Connecting...',
+    reconnecting: 'Reconnecting...',
+    offline: 'Offline',
+    error: 'Error',
+    failed: 'Connection failed'
+  }[status] || status;
+
+  // Add attempt info for reconnecting status
+  if (status === 'reconnecting' && extraInfo?.attempt) {
+    statusText = `Reconnecting (${extraInfo.attempt}/${config.maxReconnectAttempts})...`;
+  }
+
+  statusEl.textContent = statusText;
+  
+  if (dotEl) {
+    dotEl.className = 'status-dot ' + status;
+  }
+
+  // Announce status change to screen readers
+  const srRegion = document.getElementById('connection-status-region');
+  if (srRegion) srRegion.textContent = statusText;
+
+  // Banner removed — status dot in header is sufficient
+
+  // Connection mode badge - hidden since we always use proxied mode now
+  // (keeping code for potential future use if we add direct mode option)
+  const modeBadge = document.getElementById('connectionModeBadge');
+  if (modeBadge) {
+    modeBadge.style.display = 'none';
+  }
+
+  // Update connection badge tooltip
+  const badge = document.getElementById('connectionBadge');
+  if (badge) {
+    badge.title = status === 'connected' ? 'Connected' : 'Click to reconnect';
+  }
+}
+
+// Auto-reconnect runs silently in the background.
+// Status dot in header is the only connection indicator.
+
+function onConnection(callback) {
+  connectionListeners.push(callback);
+  return () => {
+    connectionListeners = connectionListeners.filter(cb => cb !== callback);
+  };
+}
+
+function notifyListeners(event, data) {
+  connectionListeners.forEach(cb => {
+    try {
+      cb(event, data);
+    } catch (e) {
+      logger.error('Connection: Listener error', e);
+    }
+  });
+}
+
+// Escape HTML to prevent XSS
+function escapeHtml(str) {
+  if (!str) return '';
+  return String(str)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+// Webhook notification helper
+function showWebhookNotification(notification) {
+  const { title, body, type = 'info' } = notification;
+  
+  // Try to use UplinkNotifications if available
+  if (window.UplinkNotifications?.show) {
+    window.UplinkNotifications.show(body || title, type);
+    return;
+  }
+  
+  // Fallback: create toast notification using safe DOM APIs
+  const toast = document.createElement('div');
+  toast.className = `webhook-toast webhook-toast-${escapeHtml(type)}`;
+  // M-35: Announce webhook notifications to screen readers
+  toast.setAttribute('role', 'alert');
+  toast.setAttribute('aria-live', 'polite');
+  
+  if (title) {
+    const titleEl = document.createElement('strong');
+    titleEl.textContent = title;
+    toast.appendChild(titleEl);
+  }
+  if (body) {
+    const bodyEl = document.createElement('p');
+    bodyEl.textContent = body;
+    toast.appendChild(bodyEl);
+  }
+  toast.style.cssText = `
+    position: fixed;
+    top: 80px;
+    right: 20px;
+    background: var(--bg-secondary, #333);
+    color: var(--text-primary, #fff);
+    padding: 12px 16px;
+    border-radius: 8px;
+    box-shadow: 0 4px 12px rgba(0,0,0,0.3);
+    z-index: 10000;
+    max-width: 300px;
+    animation: slideIn 0.3s ease;
+  `;
+  document.body.appendChild(toast);
+  
+  setTimeout(() => {
+    toast.style.animation = 'slideOut 0.3s ease';
+    setTimeout(() => toast.remove(), 300);
+  }, 5000);
+}
+
+// ===========================================
+// SYNC MESSAGE HANDLING (Cross-Device Sync)
+// ===========================================
+
+/**
+ * Simple hash for content-based deduplication
+ */
+function hashContent(role, content) {
+  let hash = 0;
+  const str = `${role}:${content}`;
+  for (let i = 0; i < str.length; i++) {
+    const char = str.charCodeAt(i);
+    hash = ((hash << 5) - hash) + char;
+    hash = hash & hash; // Convert to 32bit integer
+  }
+  return hash.toString(36);
+}
+
+/**
+ * Clean up old entries from deduplication data structures
+ */
+function cleanupDedup() {
+  // Clean up seenMessageIds if over limit (LRU eviction)
+  if (seenMessageIds.size > MAX_SEEN_IDS) {
+    const toRemove = seenMessageIds.size - MAX_SEEN_IDS;
+    const iterator = seenMessageIds.values();
+    for (let i = 0; i < toRemove; i++) {
+      seenMessageIds.delete(iterator.next().value);
+    }
+  }
+  
+  // Clean up old content hashes
+  const now = Date.now();
+  for (const [hash, timestamp] of recentContentHashes) {
+    if (now - timestamp > CONTENT_DEDUP_WINDOW_MS) {
+      recentContentHashes.delete(hash);
+    }
+  }
+
+  // Hard cap to prevent unbounded growth
+  if (recentContentHashes.size > 1000) {
+    const entries = Array.from(recentContentHashes.entries())
+      .sort((a, b) => a[1] - b[1]);
+    const toRemoveCount = recentContentHashes.size - 500;
+    for (let i = 0; i < toRemoveCount; i++) {
+      recentContentHashes.delete(entries[i][0]);
+    }
+  }
+}
+
+/**
+ * Check if a message is a duplicate
+ */
+function isDuplicateMessage(messageId, role, content, timestamp) {
+  // Check by messageId first
+  if (messageId && seenMessageIds.has(messageId)) {
+    logger.debug('Connection: Duplicate sync message (by ID):', messageId);
+    return true;
+  }
+  
+  // Content-based dedup fallback
+  const contentHash = hashContent(role, content);
+  const existingTimestamp = recentContentHashes.get(contentHash);
+  if (existingTimestamp && Math.abs(timestamp - existingTimestamp) < CONTENT_DEDUP_WINDOW_MS) {
+    logger.debug('Connection: Duplicate sync message (by content):', contentHash);
+    return true;
+  }
+  
+  return false;
+}
+
+/**
+ * Mark a message as seen for deduplication
+ */
+function markMessageSeen(messageId, role, content, timestamp) {
+  if (messageId) {
+    seenMessageIds.add(messageId);
+  }
+  const contentHash = hashContent(role, content);
+  recentContentHashes.set(contentHash, timestamp);
+  cleanupDedup();
+}
+
+// ===========================================
+// SYNC STREAMING HANDLERS (Real-Time Cross-Device Streaming)
+// ===========================================
+
+/**
+ * Check if we should handle a sync streaming event
+ * Returns false if the message is for a different satellite
+ * 
+ * NOTE: We no longer skip sync streams when chatState === 'processing'.
+ * When behind a buffering proxy (e.g. Cloudflare tunnel), the SSE response
+ * from /api/chat gets buffered and arrives all at once. WebSocket sync deltas
+ * arrive in real-time and provide the streaming experience. The SSE handler
+ * in chat.js detects when a sync stream is active and defers to it.
+ */
+function shouldHandleSyncStream(data) {
+  const currentSatellite = window.UplinkSatellites?.getCurrentId?.() || 'main';
+  if (data.satelliteId && data.satelliteId !== currentSatellite) {
+    return false;
+  }
+  return true;
+}
+
+/**
+ * Get or lazily create a sync stream entry
+ */
+function getOrCreateSyncStream(requestId) {
+  let stream = activeSyncStreams.get(requestId);
+  if (!stream) {
+    const div = window.UplinkChat?.createStreamingMessage?.();
+    if (!div) return null;
+
+    syncStreamWasUsed = true;
+    stream = { div, fullResponse: '', orphanTimer: null };
+    // Set orphan timeout to clean up if server crashes mid-stream
+    stream.orphanTimer = setTimeout(() => {
+      logger.warn('Connection: Orphan sync stream cleaned up:', requestId);
+      const orphan = activeSyncStreams.get(requestId);
+      if (orphan) {
+        // Finalize with whatever content we have
+        if (orphan.fullResponse && window.UplinkChat?.finalizeSyncStream) {
+          window.UplinkChat.finalizeSyncStream(orphan.div, orphan.fullResponse);
+        } else if (orphan.div) {
+          orphan.div.classList.remove('streaming');
+        }
+        activeSyncStreams.delete(requestId);
+      }
+    }, SYNC_STREAM_ORPHAN_TIMEOUT_MS);
+    activeSyncStreams.set(requestId, stream);
+  }
+  return stream;
+}
+
+/**
+ * Handle sync.thinking event - create streaming bubble with thinking indicator
+ */
+function handleSyncThinking(data) {
+  if (!shouldHandleSyncStream(data)) return;
+  const { requestId } = data;
+  if (!requestId) return;
+
+  // Hide the typing indicator since we're taking over display via WebSocket
+  if (window.UplinkChat?.hideTyping) {
+    window.UplinkChat.hideTyping();
+  }
+
+  const stream = getOrCreateSyncStream(requestId);
+  if (stream && window.UplinkChat?.updateStreamingMessage) {
+    window.UplinkChat.updateStreamingMessage(stream.div, '\u{1F9E0} Thinking...');
+  }
+}
+
+/**
+ * Handle sync.delta event - accumulate content and update streaming bubble
+ */
+function handleSyncDelta(data) {
+  if (!shouldHandleSyncStream(data)) return;
+  const { requestId, content } = data;
+  if (!requestId || !content) return;
+
+  const stream = getOrCreateSyncStream(requestId);
+  if (!stream) return;
+
+  stream.fullResponse += content;
+  if (window.UplinkChat?.updateStreamingMessage) {
+    window.UplinkChat.updateStreamingMessage(stream.div, stream.fullResponse);
+  }
+}
+
+/**
+ * Handle sync.tool event - show tool usage in streaming bubble
+ */
+function handleSyncTool(data) {
+  if (!shouldHandleSyncStream(data)) return;
+  const { requestId, tool } = data;
+  if (!requestId) return;
+
+  const stream = getOrCreateSyncStream(requestId);
+  if (stream && window.UplinkChat?.updateStreamingMessage) {
+    window.UplinkChat.updateStreamingMessage(stream.div, `\u{1F527} Using ${tool}...`);
+  }
+
+  // Log to activity panel
+  if (tool && window.UplinkDeveloper?.logTool) {
+    window.UplinkDeveloper.logTool(tool);
+  }
+}
+
+/**
+ * Handle sync.complete event - update token usage in activity panel
+ */
+function handleSyncComplete(data) {
+  const { usage } = data;
+  if (usage && window.UplinkDeveloper?.updateTokens) {
+    window.UplinkDeveloper.updateTokens(usage);
+  }
+  // Refresh context tracker after sync complete
+  if (window.UplinkContextTracker?.refresh) {
+    window.UplinkContextTracker.refresh();
+  }
+}
+
+/**
+ * Clear all active sync streams (e.g., when switching satellites)
+ */
+function clearActiveSyncStreams() {
+  for (const [requestId, stream] of activeSyncStreams) {
+    if (stream.orphanTimer) clearTimeout(stream.orphanTimer);
+    if (stream.div) stream.div.classList.remove('streaming');
+  }
+  activeSyncStreams.clear();
+  logger.debug('Connection: Cleared active sync streams');
+}
+
+/**
+ * Handle sync_message WebSocket events (cross-device sync)
+ */
+function handleSyncMessage(data) {
+  const { messageId, role, content, satelliteId, timestamp, requestId } = data;
+
+  // Check if this is for the current satellite
+  const currentSatellite = window.UplinkSatellites?.getCurrentId?.() || 'main';
+  if (satelliteId && satelliteId !== currentSatellite) {
+    logger.debug('Connection: Sync message for different satellite:', satelliteId, 'current:', currentSatellite);
+    return;
+  }
+
+  // Skip assistant sync messages if we're currently processing a request
+  // (the HTTP response will handle adding it - prevents race condition duplicates)
+  // If we're processing AND there's an active sync stream for this requestId,
+  // let it through so it can finalize the stream bubble.
+  // Otherwise skip to avoid duplicate with SSE response.
+  if (role === 'assistant' && window.UplinkCore?.chatState === 'processing') {
+    if (requestId && activeSyncStreams.has(requestId)) {
+      // Let it through - will finalize the sync stream div below
+      logger.debug('Connection: Letting sync message through to finalize stream:', requestId);
+    } else {
+      logger.debug('Connection: Skipping sync message - already processing response');
+      return;
+    }
+  }
+
+  // Check for duplicates
+  if (isDuplicateMessage(messageId, role, content, timestamp)) {
+    return;
+  }
+
+  // Mark as seen
+  markMessageSeen(messageId, role, content, timestamp);
+
+  // If this message has a requestId and we have an active stream for it,
+  // finalize the stream instead of creating a new message bubble
+  if (requestId && activeSyncStreams.has(requestId)) {
+    const stream = activeSyncStreams.get(requestId);
+    if (stream.orphanTimer) clearTimeout(stream.orphanTimer);
+    if (window.UplinkChat?.finalizeSyncStream) {
+      window.UplinkChat.finalizeSyncStream(stream.div, content);
+    }
+    activeSyncStreams.delete(requestId);
+    logger.debug('Connection: Finalized sync stream:', requestId, content.substring(0, 50) + '...');
+    return;
+  }
+
+  // Fall through to existing behavior: display as a full message
+  // (backward compat for clients that missed deltas or old servers without requestId)
+  const type = role === 'user' ? 'user' : 'assistant';
+
+  if (window.UplinkChat?.addMessage) {
+    window.UplinkChat.addMessage(content, type, null, false); // false = don't save again
+    logger.debug('Connection: Displayed sync message:', type, content.substring(0, 50) + '...');
+  } else if (window.addMessage) {
+    window.addMessage(content, type, null, false);
+    logger.debug('Connection: Displayed sync message (fallback):', type);
+  } else {
+    logger.warn('Connection: No addMessage function available for sync message');
+  }
+}
+
+/**
+ * Clear sync deduplication state (e.g., when switching satellites)
+ */
+function clearSyncDedup() {
+  seenMessageIds.clear();
+  recentContentHashes.clear();
+  logger.debug('Connection: Cleared sync deduplication state');
+}
+
+/**
+ * Handle openclaw_message WebSocket events (from transcript watcher)
+ * These have slightly different format than sync_message
+ * DISABLED: sync_message already handles cross-device sync, this causes duplicates
+ */
+function handleOpenClawMessage(data) {
+  // Skip - sync_message handler already covers this
+  logger.debug('Connection: Skipping openclaw_message (handled by sync_message)');
+  return;
+  
+  const { content, role, satelliteId, timestamp } = data;
+  
+  if (!content) return;
+  
+  // Check if this is for the current satellite
+  const currentSatellite = window.UplinkSatellites?.getCurrentId?.() || 'main';
+  if (satelliteId && satelliteId !== currentSatellite) {
+    logger.debug('Connection: OpenClaw message for different satellite:', satelliteId);
+    return;
+  }
+  
+  // Use content-based deduplication (no messageId from transcript watcher)
+  const msgTimestamp = timestamp || Date.now();
+  const msgRole = role || 'assistant';
+  
+  if (isDuplicateMessage(null, msgRole, content, msgTimestamp)) {
+    return;
+  }
+  
+  // Mark as seen
+  markMessageSeen(null, msgRole, content, msgTimestamp);
+  
+  // Display the message
+  const type = msgRole === 'user' ? 'user' : 'assistant';
+  
+  if (window.UplinkChat?.addMessage) {
+    window.UplinkChat.addMessage(content, type, null, false);
+    logger.debug('Connection: Displayed OpenClaw message:', type, content.substring(0, 50) + '...');
+  } else if (window.addMessage) {
+    window.addMessage(content, type, null, false);
+  }
+}
+
+/**
+ * Validate a URL is safe for navigation/audio (blocks javascript:, data:, vbscript:)
+ * @param {string} url - URL to validate
+ * @returns {boolean} - True if URL is safe
+ */
+function isSafeUrl(url) {
+  if (!url || typeof url !== 'string') return false;
+  const trimmed = url.trim().toLowerCase();
+  // Only allow http:, https:, and relative paths
+  if (trimmed.startsWith('http://') || trimmed.startsWith('https://') || trimmed.startsWith('/')) {
+    return true;
+  }
+  return false;
+}
+
+// Webhook trigger handler
+function handleWebhookTrigger(action, params) {
+  switch (action) {
+    case 'sound': {
+      // Play a sound — validate URL to prevent SSRF/exfiltration (C-09)
+      const soundUrl = params.url || '/audio/notification.mp3';
+      if (!isSafeUrl(soundUrl)) {
+        if (window.UplinkLogger?.warn) {
+          window.UplinkLogger.warn('Connection: Blocked unsafe sound URL:', soundUrl);
+        }
+        break;
+      }
+      const audio = new Audio(soundUrl);
+      audio.play().catch(err => {
+        if (window.UplinkLogger?.error) {
+          window.UplinkLogger.error('Connection: Webhook audio playback failed:', err);
+        }
+      });
+      break;
+    }
+    case 'focus':
+      // Focus the window
+      window.focus();
+      break;
+    case 'refresh':
+      // Reload the page
+      location.reload();
+      break;
+    case 'navigate': {
+      // Navigate to URL — validate to prevent open redirect / XSS (C-08)
+      if (params.url && isSafeUrl(params.url)) {
+        window.location.href = params.url;
+      } else if (params.url) {
+        if (window.UplinkLogger?.warn) {
+          window.UplinkLogger.warn('Connection: Blocked unsafe navigate URL:', params.url);
+        }
+      }
+      break;
+    }
+    default:
+      logger.debug('Unknown webhook trigger:', action, params);
+  }
+}
+
+// Cleanup on page unload to prevent dangling connections
+window.addEventListener('beforeunload', disconnect);
+
+// Module init retry state
+let initRetryCount = 0;
+const MAX_INIT_RETRIES = 10;
+let initRetryTimer = null;
+
+function scheduleInitRetry() {
+  if (initRetryCount >= MAX_INIT_RETRIES) {
+    logger.warn('Connection: Max init retries reached, giving up');
+    return;
+  }
+  initRetryCount++;
+  const delay = Math.min(50 * Math.pow(2, initRetryCount), 5000);
+  initRetryTimer = setTimeout(init, delay);
+}
+
+/**
+ * Manual retry - resets all counters and attempts immediate reconnection
+ */
+function manualRetry() {
+  logger.debug('Connection: Manual retry initiated');
+  clearTimeout(reconnectTimer);
+  clearTimeout(persistentRetryTimer);
+  reconnectAttempts = 0;
+  maxRetriesReached = false;
+  isReconnecting = false;
+  reconnect();
+}
+
+/**
+ * Check if there's an active sync stream for a given requestId
+ * Used by chat.js SSE handler to detect WebSocket streaming is active
+ * @param {string} requestId
+ * @returns {boolean}
+ */
+function hasActiveSyncStream(requestId) {
+  return requestId && activeSyncStreams.has(requestId);
+}
+
+/**
+ * Check if a sync stream was used during the current processing cycle
+ * This remains true even after the stream is finalized, so the SSE handler
+ * knows not to create a duplicate bubble
+ * @returns {boolean}
+ */
+function wasSyncStreamUsed() {
+  return syncStreamWasUsed;
+}
+
+/**
+ * Reset the sync stream usage flag (call when starting a new request)
+ */
+function resetSyncStreamUsed() {
+  syncStreamWasUsed = false;
+}
+
+/**
+ * Adopt a sync stream - returns the stream's div and removes it from tracking
+ * The SSE handler takes ownership for finalization
+ * @param {string} requestId
+ * @returns {{ div: HTMLDivElement, fullResponse: string } | null}
+ */
+function adoptSyncStream(requestId) {
+  if (!requestId || !activeSyncStreams.has(requestId)) return null;
+  const stream = activeSyncStreams.get(requestId);
+  if (stream.orphanTimer) clearTimeout(stream.orphanTimer);
+  activeSyncStreams.delete(requestId);
+  return { div: stream.div, fullResponse: stream.fullResponse };
+}
+
+/**
+ * Find any active sync stream (when requestId isn't known yet)
+ * Returns the most recent one
+ * @returns {{ requestId: string, div: HTMLDivElement, fullResponse: string } | null}
+ */
+function findActiveSyncStream() {
+  if (activeSyncStreams.size === 0) return null;
+  // Return the last (most recent) entry
+  let last = null;
+  for (const [requestId, stream] of activeSyncStreams) {
+    last = { requestId, div: stream.div, fullResponse: stream.fullResponse };
+  }
+  return last;
+}
+
+// Export API
+export const UplinkConnection = {
+connect,
+disconnect,
+reconnect,
+manualRetry,
+onConnection,
+isConnected: () => isConnected,
+isReconnecting: () => isReconnecting,
+getReconnectAttempts: () => reconnectAttempts,
+getWebSocket: () => ws,
+config,
+// Sync deduplication
+clearSyncDedup,
+markMessageSeen,
+// Sync streaming
+clearActiveSyncStreams,
+hasActiveSyncStream,
+adoptSyncStream,
+findActiveSyncStream,
+wasSyncStreamUsed,
+resetSyncStreamUsed
+};
+
+// Backward compat: assign to window
+window.UplinkConnection = UplinkConnection;
+
+// Register module
+UplinkCore.registerModule('connection', init);