agentgui 1.0.38 → 1.0.39

package/database.js

@@ -89,6 +89,21 @@ function initSchema() {
     );
 
     CREATE INDEX IF NOT EXISTS idx_idempotency_created ON idempotencyKeys(created_at);
+
+    CREATE TABLE IF NOT EXISTS stream_updates (
+      id TEXT PRIMARY KEY,
+      sessionId TEXT NOT NULL,
+      conversationId TEXT NOT NULL,
+      updateType TEXT NOT NULL,
+      content TEXT NOT NULL,
+      sequence INTEGER NOT NULL,
+      created_at INTEGER NOT NULL,
+      FOREIGN KEY (sessionId) REFERENCES sessions(id),
+      FOREIGN KEY (conversationId) REFERENCES conversations(id)
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_stream_updates_session ON stream_updates(sessionId);
+    CREATE INDEX IF NOT EXISTS idx_stream_updates_created ON stream_updates(created_at);
   `);
 }
 
@@ -596,6 +611,55 @@ export const queries = {
     }
 
     return imported;
+  },
+
+  createStreamUpdate(sessionId, conversationId, updateType, content) {
+    const id = generateId('upd');
+    const now = Date.now();
+
+    // Use transaction to ensure atomic sequence number assignment
+    const transaction = db.transaction(() => {
+      const maxSequence = db.prepare(
+        'SELECT MAX(sequence) as max FROM stream_updates WHERE sessionId = ?'
+      ).get(sessionId);
+      const sequence = (maxSequence?.max || -1) + 1;
+
+      db.prepare(
+        `INSERT INTO stream_updates (id, sessionId, conversationId, updateType, content, sequence, created_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?)`
+      ).run(id, sessionId, conversationId, updateType, JSON.stringify(content), sequence, now);
+
+      return sequence;
+    });
+
+    const sequence = transaction();
+
+    return {
+      id,
+      sessionId,
+      conversationId,
+      updateType,
+      content,
+      sequence,
+      created_at: now
+    };
+  },
+
+  getSessionStreamUpdates(sessionId) {
+    const stmt = db.prepare(
+      `SELECT id, sessionId, conversationId, updateType, content, sequence, created_at
+       FROM stream_updates WHERE sessionId = ? ORDER BY sequence ASC`
+    );
+    const rows = stmt.all(sessionId);
+    return rows.map(row => ({
+      ...row,
+      content: JSON.parse(row.content)
+    }));
+  },
+
+  clearSessionStreamUpdates(sessionId) {
+    const stmt = db.prepare('DELETE FROM stream_updates WHERE sessionId = ?');
+    stmt.run(sessionId);
   }
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentgui",
-  "version": "1.0.38",
+  "version": "1.0.39",
   "description": "Multi-agent ACP client with real-time communication",
   "type": "module",
   "main": "server.js",

package/server.js

@@ -10,6 +10,8 @@ import ACPConnection from './acp-launcher.js';
 import { ResponseFormatter } from './response-formatter.js';
 import { HTMLWrapper } from './html-wrapper.js';
 import { SessionStateStore } from './state-manager.js';
+import { StreamHandler } from './stream-handler.js';
+import { StateValidator } from './state-validator.js';
 
 // Debug logging to file
 const debugLog = (msg) => {
@@ -253,6 +255,38 @@ const server = http.createServer(async (req, res) => {
       return;
     }
 
+    const streamUpdatesMatch = routePath.match(/^\/api\/sessions\/([^/]+)\/stream-updates$/);
+    if (streamUpdatesMatch && req.method === 'GET') {
+      const sessionId = streamUpdatesMatch[1];
+      const updates = queries.getSessionStreamUpdates(sessionId);
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ sessionId, updates, count: updates.length }));
+      return;
+    }
+
+    const stateRecoveryMatch = routePath.match(/^\/api\/sessions\/([^/]+)\/state-recovery$/);
+    if (stateRecoveryMatch && req.method === 'GET') {
+      const sessionId = stateRecoveryMatch[1];
+      const state = StateValidator.getSessionState(sessionId);
+      if (!state) {
+        res.writeHead(404, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'Session not found' }));
+        return;
+      }
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify(state));
+      return;
+    }
+
+    const stateValidationMatch = routePath.match(/^\/api\/sessions\/([^/]+)\/validate$/);
+    if (stateValidationMatch && req.method === 'GET') {
+      const sessionId = stateValidationMatch[1];
+      const validation = StateValidator.validateSession(sessionId);
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify(validation));
+      return;
+    }
+
     if (routePath === '/api/import/claude-code' && req.method === 'GET') {
       const result = queries.importClaudeCodeConversations();
       res.writeHead(200, { 'Content-Type': 'application/json' });
@@ -360,13 +394,13 @@ function serveFile(filePath, res) {
 }
 
 /**
- * Process a user message through the Claude Code ACP with explicit state tracking
- * This is now fully predictable with no hidden failures
+ * Process a user message through the Claude Code ACP with real-time streaming
+ * Updates are persisted to database and broadcast to clients immediately
  */
 async function processMessage(conversationId, messageId, sessionId, content, agentId, folderContext) {
   // Create state manager for this session
   const stateManager = sessionStateStore.create(sessionId, conversationId, messageId, 120000);
-  
+
   try {
     console.log(`[processMessage] Starting: conversationId=${conversationId}, sessionId=${sessionId}`);
     console.log(`[processMessage] Initial state: ${stateManager.getState()}`);
@@ -379,35 +413,26 @@ async function processMessage(conversationId, messageId, sessionId, content, age
 
     const cwd = folderContext?.path || '/config';
     const actualAgentId = agentId || 'claude-code';
-    
+
     try {
       const conn = await getACP(actualAgentId, cwd);
-      
+
       // STATE: ACQUIRING_ACP → ACP_ACQUIRED
       stateManager.transition(stateManager.constructor.STATES.ACP_ACQUIRED, {
         reason: 'ACP connection established',
         data: { acpConnectionTime: Date.now() }
       });
 
+      // Create stream handler for real-time persistence and broadcasting
+      const streamHandler = new StreamHandler(sessionId, conversationId, broadcastSync);
       let fullText = '';
-      const blocks = [];
-      const updateChunks = [];
 
-      // Setup response accumulation
+      // Setup response streaming
       conn.onUpdate = (params) => {
+        streamHandler.handleUpdate(params, BASE_URL);
         const u = params.update;
-        if (!u) return;
-        const kind = u.sessionUpdate;
-        if (kind === 'agent_message_chunk' && u.content?.text) {
+        if (u?.sessionUpdate === 'agent_message_chunk' && u.content?.text) {
           fullText += u.content.text;
-          updateChunks.push({ type: 'text', content: u.content.text, timestamp: Date.now() });
-        } else if (kind === 'html_content' && u.content?.html) {
-          blocks.push({ type: 'html', html: u.content.html, title: u.content.title, id: u.content.id });
-          updateChunks.push({ type: 'html', content: u.content.html, title: u.content.title, timestamp: Date.now() });
-        } else if (kind === 'image_content' && u.content?.path) {
-          const imageUrl = BASE_URL + '/api/image/' + encodeURIComponent(u.content.path);
-          blocks.push({ type: 'image', path: u.content.path, url: imageUrl, title: u.content.title, alt: u.content.alt });
-          updateChunks.push({ type: 'image', path: u.content.path, url: imageUrl, title: u.content.title, timestamp: Date.now() });
         }
       };
 
@@ -427,61 +452,64 @@ async function processMessage(conversationId, messageId, sessionId, content, age
         data: { promptSentTime: Date.now(), responseReceivedTime: Date.now() }
       });
 
-      console.log(`[processMessage] ACP returned: stopReason=${result?.stopReason}, fullText=${fullText.length} chars`);
+      console.log(`[processMessage] ACP returned: stopReason=${result?.stopReason}, streamUpdates=${streamHandler.getUpdateCount()}`);
 
-      // Format response
+      // Use full text if available, otherwise use result
       let responseText = fullText || result?.result || (result?.stopReason ? `Completed: ${result.stopReason}` : 'No response.');
-      
-      // Wrap response in HTML if needed
+
+      // Only wrap plain text in HTML - don't wrap if already HTML
       const isHTML = responseText.trim().startsWith('<');
       if (!isHTML) {
         responseText = HTMLWrapper.wrapResponse(responseText);
       }
-      
+
       // Segment and format
       const segments = ResponseFormatter.segmentResponse(responseText);
       const metadata = ResponseFormatter.extractMetadata(responseText);
-      
-      const messageContent = blocks.length > 0 ? { 
-        text: responseText, 
-        blocks,
-        segments,
-        metadata,
-        updateChunks,
-        isHTML: true
-      } : {
+      const blocks = streamHandler.getBlocks();
+
+      const messageContent = {
         text: responseText,
+        blocks: blocks.length > 0 ? blocks : undefined,
         segments,
         metadata,
-        updateChunks,
+        streamUpdatesCount: streamHandler.getUpdateCount(),
         isHTML: true
       };
 
-      // Save response to database
+      // Save consolidated response to database
       const assistantMessage = queries.createMessage(conversationId, 'assistant', messageContent);
-      queries.updateSession(sessionId, { status: 'completed', response: { text: responseText, messageId: assistantMessage.id }, completed_at: Date.now() });
+      queries.updateSession(sessionId, {
+        status: 'completed',
+        response: { text: responseText, messageId: assistantMessage.id },
+        completed_at: Date.now()
+      });
       queries.createEvent('session.completed', { messageId: assistantMessage.id }, conversationId, sessionId);
 
-      // Broadcast to connected clients
-      broadcastSync({ type: 'session_updated', sessionId, status: 'completed', message: assistantMessage });
+      // Broadcast final consolidated response
+      broadcastSync({
+        type: 'session_updated',
+        sessionId,
+        status: 'completed',
+        message: assistantMessage
+      });
 
       // STATE: PROCESSING → COMPLETED
       stateManager.transition(stateManager.constructor.STATES.COMPLETED, {
         reason: 'Response successfully generated and saved',
         data: {
-          fullText,
-          blocks,
           responseLength: responseText.length,
-          messageId: assistantMessage.id
+          messageId: assistantMessage.id,
+          streamUpdates: streamHandler.getUpdateCount()
         }
       });
 
-      console.log(`[processMessage] ✅ Session completed: ${stateManager.getSummary().duration}`);
+      console.log(`[processMessage] ✅ Session completed with ${streamHandler.getUpdateCount()} stream updates: ${stateManager.getSummary().duration}`);
 
     } catch (acpError) {
       console.error(`[processMessage] ACP Error: ${acpError.message}`);
       console.error(`[processMessage] Stack: ${acpError.stack}`);
-      
+
       // STATE: → ERROR
       stateManager.transition(stateManager.constructor.STATES.ERROR, {
         reason: `ACP error: ${acpError.message}`,
@@ -546,16 +574,70 @@ wss.on('connection', (ws, req) => {
   } else if (wsPath === '/sync') {
     syncClients.add(ws);
     ws.isAlive = true;
-    ws.send(JSON.stringify({ type: 'sync_connected' }));
+    ws.subscriptions = new Set();
+    ws.clientId = `client-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+
+    ws.send(JSON.stringify({
+      type: 'sync_connected',
+      clientId: ws.clientId,
+      timestamp: Date.now()
+    }));
+
+    ws.on('message', (msg) => {
+      try {
+        const data = JSON.parse(msg);
+        if (data.type === 'subscribe') {
+          ws.subscriptions.add(data.sessionId);
+          // On subscribe, send current state for recovery
+          const state = StateValidator.getSessionState(data.sessionId);
+          if (state) {
+            ws.send(JSON.stringify({
+              type: 'state_snapshot',
+              sessionId: data.sessionId,
+              state,
+              timestamp: Date.now()
+            }));
+          }
+        } else if (data.type === 'unsubscribe') {
+          ws.subscriptions.delete(data.sessionId);
+        } else if (data.type === 'recovery_request') {
+          // Client asking to recover from a checkpoint
+          const state = StateValidator.getSessionState(data.sessionId);
+          if (state) {
+            ws.send(JSON.stringify({
+              type: 'recovery_response',
+              sessionId: data.sessionId,
+              state,
+              timestamp: Date.now()
+            }));
+          }
+        }
+      } catch (e) {
+        console.error('WebSocket message parse error:', e.message);
+      }
+    });
+
     ws.on('pong', () => { ws.isAlive = true; });
-    ws.on('close', () => { syncClients.delete(ws); });
+    ws.on('close', () => {
+      syncClients.delete(ws);
+      console.log(`[WebSocket] Client ${ws.clientId} disconnected`);
+    });
   }
 });
 
 function broadcastSync(event) {
   const data = JSON.stringify(event);
   for (const ws of syncClients) {
-    if (ws.readyState === 1) ws.send(data);
+    if (ws.readyState === 1) {
+      // CRITICAL: Only send if client subscribed to this session
+      if (event.sessionId) {
+        if (!ws.subscriptions || !ws.subscriptions.has(event.sessionId)) {
+          continue;
+        }
+      }
+      // Send immediately - no buffering
+      ws.send(data);
+    }
   }
 }
 

package/state-validator.js

@@ -0,0 +1,150 @@
+import { queries } from './database.js';
+import crypto from 'crypto';
+
+export class StateValidator {
+  /**
+   * Validates data consistency by checking:
+   * 1. Sequence numbers are consecutive (no gaps)
+   * 2. Stream updates match database
+   * 3. Final message matches aggregated stream updates
+   */
+  static validateSession(sessionId) {
+    try {
+      const session = queries.getSession(sessionId);
+      if (!session) return { valid: false, error: 'Session not found' };
+
+      const updates = queries.getSessionStreamUpdates(sessionId);
+
+      // Check 1: Sequence continuity
+      const sequenceGaps = [];
+      for (let i = 0; i < updates.length - 1; i++) {
+        if (updates[i + 1].sequence !== updates[i].sequence + 1) {
+          sequenceGaps.push({ expected: updates[i].sequence + 1, actual: updates[i + 1].sequence });
+        }
+      }
+
+      if (sequenceGaps.length > 0) {
+        return {
+          valid: false,
+          error: 'Sequence gaps detected',
+          gaps: sequenceGaps
+        };
+      }
+
+      // Check 2: Stream update count matches
+      const textUpdates = updates.filter(u => u.updateType === 'text');
+      const htmlUpdates = updates.filter(u => u.updateType === 'html');
+      const imageUpdates = updates.filter(u => u.updateType === 'image');
+
+      // Check 3: Sequence starts at 0
+      if (updates.length > 0 && updates[0].sequence !== 0) {
+        return {
+          valid: false,
+          error: 'Sequence should start at 0',
+          firstSequence: updates[0].sequence
+        };
+      }
+
+      return {
+        valid: true,
+        sessionId,
+        updateCount: updates.length,
+        textCount: textUpdates.length,
+        htmlCount: htmlUpdates.length,
+        imageCount: imageUpdates.length,
+        latestSequence: updates.length > 0 ? updates[updates.length - 1].sequence : -1,
+        checkpoint: this.createChecksum(updates)
+      };
+    } catch (err) {
+      return {
+        valid: false,
+        error: err.message
+      };
+    }
+  }
+
+  /**
+   * Creates checksum of stream updates for integrity verification
+   */
+  static createChecksum(updates) {
+    const data = updates
+      .map(u => `${u.sequence}:${u.updateType}:${u.created_at}`)
+      .join('|');
+    return crypto.createHash('sha256').update(data).digest('hex');
+  }
+
+  /**
+   * Verifies checksum hasn't changed (data integrity)
+   */
+  static verifyChecksum(updates, expectedChecksum) {
+    return this.createChecksum(updates) === expectedChecksum;
+  }
+
+  /**
+   * Gets current state for client recovery
+   */
+  static getSessionState(sessionId) {
+    const session = queries.getSession(sessionId);
+    if (!session) return null;
+
+    const updates = queries.getSessionStreamUpdates(sessionId);
+    const validation = this.validateSession(sessionId);
+
+    return {
+      session: {
+        id: session.id,
+        conversationId: session.conversationId,
+        status: session.status,
+        started_at: session.started_at,
+        completed_at: session.completed_at
+      },
+      updates: updates.map(u => ({
+        sequence: u.sequence,
+        updateType: u.updateType,
+        content: u.content,
+        created_at: u.created_at
+      })),
+      validation,
+      checkpoint: validation.checkpoint,
+      recoveryPoint: {
+        lastSequence: updates.length > 0 ? updates[updates.length - 1].sequence : -1,
+        totalUpdates: updates.length,
+        timestamp: Date.now()
+      }
+    };
+  }
+
+  /**
+   * Validates incoming update against current state
+   */
+  static validateUpdate(sessionId, incomingUpdate, lastKnownSequence) {
+    const updates = queries.getSessionStreamUpdates(sessionId);
+    const maxSequence = updates.length > 0 ? updates[updates.length - 1].sequence : -1;
+
+    // Check if this is the next expected sequence
+    const expectedSequence = maxSequence + 1;
+    if (incomingUpdate.sequence !== expectedSequence) {
+      return {
+        valid: false,
+        error: 'Sequence out of order',
+        expected: expectedSequence,
+        received: incomingUpdate.sequence,
+        action: 'FETCH_MISSING_UPDATES'
+      };
+    }
+
+    // Check for duplicates (same sequence already exists)
+    if (updates.some(u => u.sequence === incomingUpdate.sequence)) {
+      return {
+        valid: false,
+        error: 'Duplicate update detected',
+        sequence: incomingUpdate.sequence,
+        action: 'IGNORE_DUPLICATE'
+      };
+    }
+
+    return { valid: true, sequence: expectedSequence };
+  }
+}
+
+export default StateValidator;

package/static/sync-manager.js

@@ -0,0 +1,273 @@
+/**
+ * Sync Manager - Handles real-time synchronization with automatic reconnection
+ * Guarantees: No lost data, perfect recovery, consistent state
+ */
+class SyncManager {
+  constructor() {
+    this.ws = null;
+    this.clientId = null;
+    this.subscriptions = new Map();
+    this.reconnectAttempts = 0;
+    this.maxReconnectAttempts = 10;
+    this.reconnectDelay = 1000;
+    this.isConnected = false;
+    this.handlers = new Map();
+    this.lastCheckpoint = new Map();
+  }
+
+  /**
+   * Connect to sync server with automatic reconnection
+   */
+  connect() {
+    return new Promise((resolve, reject) => {
+      const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
+      const url = `${protocol}//${window.location.host}${window.__BASE_URL || '/gm'}/sync`;
+
+      try {
+        this.ws = new WebSocket(url);
+
+        this.ws.onopen = () => {
+          console.log('[SyncManager] Connected to server');
+          this.isConnected = true;
+          this.reconnectAttempts = 0;
+          this.emit('connected', { clientId: this.clientId });
+
+          // Resubscribe to all previously subscribed sessions
+          for (const [sessionId, handlers] of this.subscriptions) {
+            this.subscribe(sessionId, handlers.onUpdate, handlers.onRecover);
+          }
+
+          resolve();
+        };
+
+        this.ws.onmessage = (event) => {
+          this.handleMessage(JSON.parse(event.data));
+        };
+
+        this.ws.onclose = () => {
+          console.log('[SyncManager] Disconnected from server');
+          this.isConnected = false;
+          this.attemptReconnect();
+        };
+
+        this.ws.onerror = (error) => {
+          console.error('[SyncManager] WebSocket error:', error);
+          reject(error);
+        };
+      } catch (err) {
+        console.error('[SyncManager] Failed to create WebSocket:', err);
+        reject(err);
+      }
+    });
+  }
+
+  /**
+   * Handle incoming messages
+   */
+  handleMessage(message) {
+    const { type, sessionId, clientId } = message;
+
+    if (type === 'sync_connected') {
+      this.clientId = message.clientId;
+      console.log(`[SyncManager] Assigned client ID: ${this.clientId}`);
+    } else if (type === 'state_snapshot') {
+      // Received state after subscription
+      console.log(`[SyncManager] Received state snapshot for ${sessionId}`);
+      this.lastCheckpoint.set(sessionId, message.state.checkpoint);
+
+      const handlers = this.subscriptions.get(sessionId);
+      if (handlers?.onRecover) {
+        handlers.onRecover(message.state);
+      }
+    } else if (type === 'recovery_response') {
+      // Received full state recovery
+      console.log(`[SyncManager] Received recovery response for ${sessionId}`);
+      this.lastCheckpoint.set(sessionId, message.state.checkpoint);
+
+      const handlers = this.subscriptions.get(sessionId);
+      if (handlers?.onRecover) {
+        handlers.onRecover(message.state);
+      }
+    } else if (type === 'stream_update') {
+      // Real-time update from server
+      this.lastCheckpoint.set(sessionId, message.timestamp);
+
+      const handlers = this.subscriptions.get(sessionId);
+      if (handlers?.onUpdate) {
+        try {
+          handlers.onUpdate(message);
+        } catch (err) {
+          console.error(`[SyncManager] Error in update handler: ${err.message}`);
+        }
+      }
+    }
+  }
+
+  /**
+   * Subscribe to session updates with callbacks
+   * @param {string} sessionId
+   * @param {Function} onUpdate - Called for each real-time update
+   * @param {Function} onRecover - Called with full state on subscribe/reconnect
+   */
+  subscribe(sessionId, onUpdate, onRecover) {
+    if (!this.subscriptions.has(sessionId)) {
+      this.subscriptions.set(sessionId, { onUpdate, onRecover });
+    }
+
+    if (this.isConnected && this.ws?.readyState === WebSocket.OPEN) {
+      this.ws.send(JSON.stringify({
+        type: 'subscribe',
+        sessionId
+      }));
+    }
+  }
+
+  /**
+   * Unsubscribe from session
+   */
+  unsubscribe(sessionId) {
+    this.subscriptions.delete(sessionId);
+    this.lastCheckpoint.delete(sessionId);
+
+    if (this.isConnected && this.ws?.readyState === WebSocket.OPEN) {
+      this.ws.send(JSON.stringify({
+        type: 'unsubscribe',
+        sessionId
+      }));
+    }
+  }
+
+  /**
+   * Request recovery from a specific checkpoint
+   * Called when client detects missing data
+   */
+  requestRecovery(sessionId) {
+    console.log(`[SyncManager] Requesting recovery for ${sessionId}`);
+
+    if (this.isConnected && this.ws?.readyState === WebSocket.OPEN) {
+      this.ws.send(JSON.stringify({
+        type: 'recovery_request',
+        sessionId
+      }));
+    } else {
+      // If not connected, recover when connection is restored
+      this.connect().then(() => {
+        this.ws.send(JSON.stringify({
+          type: 'recovery_request',
+          sessionId
+        }));
+      });
+    }
+  }
+
+  /**
+   * Verify data consistency by querying server
+   */
+  async validateSession(sessionId) {
+    const baseUrl = window.__BASE_URL || '/gm';
+    try {
+      const response = await fetch(`${baseUrl}/api/sessions/${sessionId}/validate`);
+      const validation = await response.json();
+      return validation;
+    } catch (err) {
+      console.error(`[SyncManager] Validation failed: ${err.message}`);
+      return null;
+    }
+  }
+
+  /**
+   * Fetch full state for recovery
+   */
+  async fetchSessionState(sessionId) {
+    const baseUrl = window.__BASE_URL || '/gm';
+    try {
+      const response = await fetch(`${baseUrl}/api/sessions/${sessionId}/state-recovery`);
+      if (!response.ok) return null;
+      return await response.json();
+    } catch (err) {
+      console.error(`[SyncManager] Failed to fetch session state: ${err.message}`);
+      return null;
+    }
+  }
+
+  /**
+   * Automatic reconnection with exponential backoff
+   */
+  attemptReconnect() {
+    if (this.reconnectAttempts >= this.maxReconnectAttempts) {
+      console.error('[SyncManager] Max reconnection attempts reached');
+      this.emit('reconnect_failed');
+      return;
+    }
+
+    this.reconnectAttempts++;
+    const delay = this.reconnectDelay * Math.pow(2, this.reconnectAttempts - 1);
+    console.log(`[SyncManager] Reconnecting in ${delay}ms (attempt ${this.reconnectAttempts}/${this.maxReconnectAttempts})`);
+
+    setTimeout(() => {
+      this.connect().catch(err => {
+        console.error('[SyncManager] Reconnection failed:', err);
+        this.attemptReconnect();
+      });
+    }, delay);
+  }
+
+  /**
+   * Detect missing updates by checking sequence gaps
+   */
+  detectMissingUpdates(updates) {
+    const gaps = [];
+    for (let i = 0; i < updates.length - 1; i++) {
+      if (updates[i + 1].sequence !== updates[i].sequence + 1) {
+        gaps.push({
+          expected: updates[i].sequence + 1,
+          actual: updates[i + 1].sequence
+        });
+      }
+    }
+    return gaps;
+  }
+
+  /**
+   * Register event listener
+   */
+  on(event, callback) {
+    if (!this.handlers.has(event)) {
+      this.handlers.set(event, []);
+    }
+    this.handlers.get(event).push(callback);
+  }
+
+  /**
+   * Emit event
+   */
+  emit(event, data) {
+    const callbacks = this.handlers.get(event) || [];
+    for (const callback of callbacks) {
+      try {
+        callback(data);
+      } catch (err) {
+        console.error(`[SyncManager] Error in ${event} handler: ${err.message}`);
+      }
+    }
+  }
+
+  /**
+   * Close connection gracefully
+   */
+  disconnect() {
+    this.subscriptions.clear();
+    this.lastCheckpoint.clear();
+    if (this.ws) {
+      this.ws.close();
+      this.ws = null;
+    }
+  }
+}
+
+// Export as global for browser use
+if (typeof window !== 'undefined') {
+  window.SyncManager = SyncManager;
+}
+
+export default SyncManager;

package/stream-handler.js

@@ -0,0 +1,101 @@
+import { queries } from './database.js';
+import { StateValidator } from './state-validator.js';
+
+export class StreamHandler {
+  constructor(sessionId, conversationId, broadcastFn) {
+    this.sessionId = sessionId;
+    this.conversationId = conversationId;
+    this.broadcastFn = broadcastFn;
+    this.updateCount = 0;
+    this.sequence = -1;
+    this.hasText = false;
+    this.hasBlocks = false;
+    this.blocks = [];
+    this.stateCheckpoint = StateValidator.getSessionState(sessionId);
+  }
+
+  handleUpdate(params, baseUrl) {
+    const u = params.update;
+    if (!u) return;
+
+    const kind = u.sessionUpdate;
+    if (kind === 'agent_message_chunk' && u.content?.text) {
+      this.hasText = true;
+      const update = {
+        type: 'text',
+        content: u.content.text,
+        timestamp: Date.now()
+      };
+      this.persistAndBroadcast('text', update, baseUrl);
+    } else if (kind === 'html_content' && u.content?.html) {
+      this.hasBlocks = true;
+      const update = {
+        type: 'html',
+        html: u.content.html,
+        title: u.content.title,
+        id: u.content.id,
+        timestamp: Date.now()
+      };
+      this.blocks.push({ type: 'html', html: u.content.html, title: u.content.title, id: u.content.id });
+      this.persistAndBroadcast('html', update, baseUrl);
+    } else if (kind === 'image_content' && u.content?.path) {
+      this.hasBlocks = true;
+      const imageUrl = baseUrl + '/api/image/' + encodeURIComponent(u.content.path);
+      const update = {
+        type: 'image',
+        path: u.content.path,
+        url: imageUrl,
+        title: u.content.title,
+        alt: u.content.alt,
+        timestamp: Date.now()
+      };
+      this.blocks.push({ type: 'image', path: u.content.path, url: imageUrl, title: u.content.title, alt: u.content.alt });
+      this.persistAndBroadcast('image', update, baseUrl);
+    }
+  }
+
+  persistAndBroadcast(updateType, update, baseUrl) {
+    try {
+      // CRITICAL: Database write MUST complete before broadcast
+      // This guarantees database is source of truth
+      const persistedUpdate = queries.createStreamUpdate(this.sessionId, this.conversationId, updateType, update);
+      this.sequence = persistedUpdate.sequence;
+      this.updateCount++;
+
+      // Validate consistency after write
+      const validation = StateValidator.validateSession(this.sessionId);
+      if (!validation.valid) {
+        console.error(`[StreamHandler] State validation failed after update:`, validation);
+        // Log but continue - database is still source of truth
+      }
+
+      // CRITICAL: Broadcast happens AFTER database write confirms
+      // This ensures clients see data that's already persisted
+      this.broadcastFn({
+        type: 'stream_update',
+        sessionId: this.sessionId,
+        conversationId: this.conversationId,
+        updateType,
+        update: persistedUpdate.content,
+        sequence: this.sequence,
+        persisted: true,
+        timestamp: persistedUpdate.created_at,
+        validation: validation.valid ? undefined : { error: validation.error }
+      });
+    } catch (err) {
+      console.error(`[StreamHandler] Error persisting update: ${err.message}`);
+      // On persistence failure, do NOT broadcast - maintain consistency
+      throw err;
+    }
+  }
+
+  getBlocks() {
+    return this.blocks;
+  }
+
+  getUpdateCount() {
+    return this.updateCount;
+  }
+}
+
+export default StreamHandler;