agentgui 1.0.596 → 1.0.598

package/lib/checkpoint-manager.js

@@ -0,0 +1,182 @@
+/**
+ * Checkpoint Manager
+ * Handles session recovery by loading checkpoints and injecting into resume flow
+ * Ensures idempotency and prevents duplicate event replay
+ */
+
+class CheckpointManager {
+  constructor(queries) {
+    this.queries = queries;
+    this._injectedSessions = new Set(); // Track which sessions already had checkpoints injected
+    this._pendingCheckpoints = new Map(); // Store checkpoints to inject on subscribe: { conversationId -> checkpoint }
+  }
+
+  /**
+   * Load checkpoint for a session (all events + chunks from previous session)
+   * Used when resuming after interruption
+   */
+  loadCheckpoint(previousSessionId) {
+    if (!previousSessionId) return null;
+
+    try {
+      const session = this.queries.getSession(previousSessionId);
+      if (!session) return null;
+
+      const events = this.queries.getSessionEvents(previousSessionId);
+      const chunks = this.queries.getChunksSinceSeq(previousSessionId, -1);
+
+      return {
+        sessionId: previousSessionId,
+        conversationId: session.conversationId,
+        events: events || [],
+        chunks: chunks || [],
+        lastSequence: chunks.length > 0 ? Math.max(...chunks.map(c => c.sequence)) : -1
+      };
+    } catch (e) {
+      console.error(`[checkpoint] Failed to load checkpoint for session ${previousSessionId}:`, e.message);
+      return null;
+    }
+  }
+
+  /**
+   * Inject checkpoint events into the new session
+   * Marks them with resumeOrigin to prevent replay
+   * Returns the next sequence number to use
+   */
+  injectCheckpointEvents(newSessionId, checkpoint, broadcastFn) {
+    if (!checkpoint || !checkpoint.events || checkpoint.events.length === 0) {
+      return -1;
+    }
+
+    // Prevent double-injection for same session
+    const injectionKey = `${newSessionId}:checkpoint`;
+    if (this._injectedSessions.has(injectionKey)) {
+      console.log(`[checkpoint] Session ${newSessionId} already had checkpoint injected, skipping`);
+      return checkpoint.lastSequence;
+    }
+
+    let sequenceStart = checkpoint.lastSequence + 1;
+
+    try {
+      // Broadcast each checkpoint event as if it's arriving now
+      for (const evt of checkpoint.events) {
+        // Skip internal session management events
+        if (evt.type === 'session.created') continue;
+
+        // Re-broadcast with resume markers
+        broadcastFn({
+          ...evt,
+          resumeOrigin: 'checkpoint',
+          originalSessionId: checkpoint.sessionId,
+          newSessionId: newSessionId,
+          timestamp: Date.now()
+        });
+      }
+
+      // Mark this session as having been injected
+      this._injectedSessions.add(injectionKey);
+
+      console.log(
+        `[checkpoint] Injected ${checkpoint.events.length} events from session ` +
+        `${checkpoint.sessionId} into new session ${newSessionId}`
+      );
+
+      return sequenceStart;
+    } catch (e) {
+      console.error(`[checkpoint] Failed to inject checkpoint events:`, e.message);
+      return checkpoint.lastSequence;
+    }
+  }
+
+  /**
+   * Copy checkpoint chunks to new session with modified sequence
+   * Ensures chunks are marked as injected to distinguish from new streaming
+   */
+  copyCheckpointChunks(oldSessionId, newSessionId, startSequence = 0) {
+    try {
+      const chunks = this.queries.getChunksSinceSeq(oldSessionId, -1);
+      if (!chunks || chunks.length === 0) return 0;
+
+      let copiedCount = 0;
+
+      for (let i = 0; i < chunks.length; i++) {
+        const chunk = chunks[i];
+        const newSequence = startSequence + i;
+
+        try {
+          this.queries.createChunk(
+            newSessionId,
+            chunk.conversationId,
+            newSequence,
+            chunk.type,
+            { ...chunk.data, resumeOrigin: 'checkpoint' }
+          );
+          copiedCount++;
+        } catch (e) {
+          console.error(`[checkpoint] Failed to copy chunk ${i}:`, e.message);
+        }
+      }
+
+      console.log(`[checkpoint] Copied ${copiedCount} chunks from ${oldSessionId} to ${newSessionId}`);
+      return startSequence + copiedCount;
+    } catch (e) {
+      console.error(`[checkpoint] Failed to copy checkpoint chunks:`, e.message);
+      return startSequence;
+    }
+  }
+
+  /**
+   * Clean up: mark previous session as properly resumed
+   * Prevents re-resuming the same interrupted session multiple times
+   */
+  markSessionResumed(previousSessionId) {
+    try {
+      this.queries.updateSession(previousSessionId, {
+        status: 'resumed',
+        completed_at: Date.now()
+      });
+      console.log(`[checkpoint] Marked session ${previousSessionId} as resumed`);
+    } catch (e) {
+      console.error(`[checkpoint] Failed to mark session as resumed:`, e.message);
+    }
+  }
+
+  /**
+   * Clear injected sessions cache (call on server restart)
+   */
+  reset() {
+    this._injectedSessions.clear();
+  }
+
+  /**
+   * Store a checkpoint to be injected when client subscribes
+   * (Used during server startup when no clients are connected yet)
+   */
+  storeCheckpointForDelay(conversationId, checkpoint) {
+    if (checkpoint && checkpoint.events && checkpoint.events.length > 0) {
+      this._pendingCheckpoints.set(conversationId, checkpoint);
+      console.log(`[checkpoint] Stored checkpoint for ${conversationId} to inject on subscribe (${checkpoint.events.length} events, ${checkpoint.chunks.length} chunks)`);
+    }
+  }
+
+  /**
+   * Get and remove a pending checkpoint (called when client subscribes)
+   */
+  getPendingCheckpoint(conversationId) {
+    const checkpoint = this._pendingCheckpoints.get(conversationId);
+    if (checkpoint) {
+      this._pendingCheckpoints.delete(conversationId);
+      console.log(`[checkpoint] Retrieved pending checkpoint for ${conversationId}`);
+    }
+    return checkpoint;
+  }
+
+  /**
+   * Check if there's a pending checkpoint for a conversation
+   */
+  hasPendingCheckpoint(conversationId) {
+    return this._pendingCheckpoints.has(conversationId);
+  }
+}
+
+export default CheckpointManager;

package/package.json

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

package/server.js

@@ -26,6 +26,7 @@ import { startAll as startACPTools, stopAll as stopACPTools, getStatus as getACP
 import { installGMAgentConfigs } from './lib/gm-agent-configs.js';
 import * as toolManager from './lib/tool-manager.js';
 import { pm2Manager } from './lib/pm2-manager.js';
+import CheckpointManager from './lib/checkpoint-manager.js';
 
 
 process.on('uncaughtException', (err, origin) => {
@@ -294,6 +295,7 @@ const rateLimitState = new Map();
 const activeProcessesByRunId = new Map();
 const activeProcessesByConvId = new Map(); // Store process handles by conversationId for steering
 const acpQueries = queries;
+const checkpointManager = new CheckpointManager(queries);
 const STUCK_AGENT_THRESHOLD_MS = 600000;
 const NO_PID_GRACE_PERIOD_MS = 60000;
 const DEFAULT_RATE_LIMIT_COOLDOWN_MS = 60000;
@@ -4240,6 +4242,38 @@ wsRouter.onLegacy((data, ws) => {
       conversationId: data.conversationId,
       timestamp: Date.now()
     }));
+
+    // Inject pending checkpoint events if this is a conversation subscription
+    if (data.conversationId && checkpointManager.hasPendingCheckpoint(data.conversationId)) {
+      const checkpoint = checkpointManager.getPendingCheckpoint(data.conversationId);
+      if (checkpoint) {
+        console.log(`[checkpoint] Injecting ${checkpoint.events.length} events to client for ${data.conversationId}`);
+
+        // Get the session to use for the injection
+        const latestSession = queries.getLatestSession(data.conversationId);
+        if (latestSession) {
+          // Send streaming_resumed event first
+          ws.send(JSON.stringify({
+            type: 'streaming_resumed',
+            sessionId: latestSession.id,
+            conversationId: data.conversationId,
+            resumeFrom: checkpoint.sessionId,
+            eventCount: checkpoint.events.length,
+            chunkCount: checkpoint.chunks.length,
+            timestamp: Date.now()
+          }));
+
+          // Inject each checkpoint event
+          checkpointManager.injectCheckpointEvents(latestSession.id, checkpoint, (evt) => {
+            ws.send(JSON.stringify({
+              ...evt,
+              sessionId: latestSession.id,
+              conversationId: data.conversationId
+            }));
+          });
+        }
+      }
+    }
   } else if (data.type === 'unsubscribe') {
     if (data.sessionId) {
       ws.subscriptions.delete(data.sessionId);
@@ -4543,8 +4577,14 @@ async function resumeInterruptedStreams() {
     for (let i = 0; i < toResume.length; i++) {
       const conv = toResume[i];
       try {
-        const staleSessions = [...queries.getSessionsByStatus(conv.id, 'active'), ...queries.getSessionsByStatus(conv.id, 'pending')];
-        for (const s of staleSessions) {
+        // Find previous incomplete sessions to load checkpoint from
+        const previousSessions = [...queries.getSessionsByStatus(conv.id, 'active'), ...queries.getSessionsByStatus(conv.id, 'pending')];
+        const previousSessionId = previousSessions.length > 0 ? previousSessions[0].id : null;
+
+        // Load checkpoint from previous session
+        const checkpoint = previousSessionId ? checkpointManager.loadCheckpoint(previousSessionId) : null;
+
+        for (const s of previousSessions) {
           queries.updateSession(s.id, { status: 'interrupted', error: 'Server restarted, resuming', completed_at: Date.now() });
         }
 
@@ -4556,7 +4596,8 @@ async function resumeInterruptedStreams() {
         queries.createEvent('session.created', {
           sessionId: session.id,
           resumeReason: 'server_restart',
-          claudeSessionId: conv.claudeSessionId
+          claudeSessionId: conv.claudeSessionId,
+          checkpointFrom: previousSessionId
         }, conv.id, session.id);
 
         activeExecutions.set(conv.id, {
@@ -4572,11 +4613,19 @@ async function resumeInterruptedStreams() {
           conversationId: conv.id,
           agentId: conv.agentType,
           resumed: true,
+          checkpointAvailable: !!checkpoint,
           timestamp: Date.now()
         });
 
+        // Store checkpoint to inject when client subscribes (not now, since no clients connected yet)
+        if (checkpoint) {
+          checkpointManager.storeCheckpointForDelay(conv.id, checkpoint);
+          checkpointManager.markSessionResumed(previousSessionId);
+          console.log(`[RESUME] Checkpoint stored for ${conv.id}, will inject on next client subscribe`);
+        }
+
         const messageId = lastMsg?.id || null;
-        console.log(`[RESUME] Resuming conv ${conv.id} (claude session: ${conv.claudeSessionId})`);
+        console.log(`[RESUME] Resuming conv ${conv.id} (claude session: ${conv.claudeSessionId}) with checkpoint=${!!checkpoint}`);
 
         try {
           await processMessageWithStreaming(conv.id, messageId, session.id, promptText, conv.agentType, conv.model, conv.subAgent);

package/static/js/client.js

@@ -3284,3 +3284,122 @@ document.addEventListener('DOMContentLoaded', async () => {
 if (typeof module !== 'undefined' && module.exports) {
   module.exports = AgentGUIClient;
 }
+  // PHASE 2: Generate unique request ID
+  _generateRequestId() {
+    return ++this._currentRequestId;
+  }
+
+  // PHASE 2: Make a load request with tracking
+  _makeLoadRequest(conversationId) {
+    const requestId = this._generateRequestId();
+    const abortController = new AbortController();
+    
+    // Cancel previous request for this conversation if exists
+    const prev = this._loadInProgress[conversationId];
+    if (prev?.abortController) {
+      prev.abortController.abort();
+    }
+    
+    this._loadInProgress[conversationId] = {
+      requestId,
+      abortController,
+      timestamp: Date.now(),
+      conversationId
+    };
+    
+    return { requestId, abortController };
+  }
+
+  // PHASE 2: Verify request is current before rendering
+  _isCurrentRequest(conversationId, requestId) {
+    const current = this._loadInProgress[conversationId];
+    return current?.requestId === requestId;
+  }
+
+  // PHASE 3: Queue WebSocket message based on priority
+  _queueWebSocketMessage(data) {
+    const highPriorityTypes = ['conversation_deleted', 'all_conversations_deleted'];
+    
+    if (highPriorityTypes.includes(data.type)) {
+      this._highPriorityQueue.push(data);
+    } else {
+      this._lowPriorityQueue.push(data);
+    }
+  }
+
+  // PHASE 3: Process queued WebSocket messages
+  _drainMessageQueues() {
+    // Process high-priority first (deletions)
+    while (this._highPriorityQueue.length > 0) {
+      const msg = this._highPriorityQueue.shift();
+      this._processWebSocketMessageDirect(msg);
+    }
+    
+    // Then process low-priority (metadata)
+    while (this._lowPriorityQueue.length > 0) {
+      const msg = this._lowPriorityQueue.shift();
+      this._processWebSocketMessageDirect(msg);
+    }
+  }
+
+  // PHASE 3: Direct WebSocket message processing (extracted from switch)
+  _processWebSocketMessageDirect(data) {
+    switch (data.type) {
+      case 'streaming_start':
+        this.handleStreamingStart(data).catch(e => console.error('handleStreamingStart error:', e));
+        break;
+      case 'streaming_progress':
+        this.handleStreamingProgress(data);
+        break;
+      case 'streaming_complete':
+        this.handleStreamingComplete(data);
+        break;
+      case 'streaming_error':
+        this.handleStreamingError(data);
+        break;
+      case 'conversation_created':
+        this.handleConversationCreated(data);
+        break;
+      case 'conversation_deleted':
+        this.handleConversationDeleted(data);
+        break;
+      case 'all_conversations_deleted':
+        this.handleAllConversationsDeleted(data);
+        break;
+      case 'message_created':
+        this.handleMessageCreated(data);
+        break;
+      case 'conversation_updated':
+        this.handleConversationUpdated(data);
+        break;
+      case 'message_updated':
+        this.handleMessageUpdated(data);
+        break;
+      default:
+        // Other types handled elsewhere
+        break;
+    }
+  }
+
+  // PHASE 4: Track streaming event sequence
+  _recordStreamingSequence(sessionId, sequence) {
+    this._lastProcessedSequence[sessionId] = sequence;
+  }
+
+  // PHASE 4: Verify streaming event is current and in-order
+  _isValidStreamingEvent(event) {
+    // Must be for current session
+    if (event.sessionId !== this.state.currentSession?.id) {
+      return false;
+    }
+    
+    // Check sequence number
+    const lastSeq = this._lastProcessedSequence[event.sessionId] || -1;
+    if (event.sequence !== undefined && event.sequence <= lastSeq) {
+      return false; // Duplicate or out-of-order
+    }
+    
+    return true;
+  }
+
+

package/static/js/request-manager.js

@@ -0,0 +1,138 @@
+/**
+ * Request Manager - Phase 2: Request Lifetime Management
+ * Tracks in-flight requests with unique IDs, enables cancellation on navigation
+ * Prevents race conditions where older requests complete after newer ones
+ */
+
+class RequestManager {
+  constructor() {
+    this._requestId = 0;
+    this._inflightRequests = new Map(); // requestId -> { conversationId, abortController, timestamp, priority }
+    this._activeLoadId = null; // Track which request is currently being rendered
+  }
+
+  /**
+   * Start a new load request for a conversation
+   * Returns a request token that must be verified before rendering
+   */
+  startLoadRequest(conversationId, priority = 'normal') {
+    const requestId = ++this._requestId;
+    const abortController = new AbortController();
+
+    this._inflightRequests.set(requestId, {
+      conversationId,
+      abortController,
+      timestamp: Date.now(),
+      priority,
+      status: 'pending'
+    });
+
+    return {
+      requestId,
+      abortSignal: abortController.signal,
+      cancel: () => this._cancelRequest(requestId),
+      verify: () => this._verifyRequest(requestId, conversationId)
+    };
+  }
+
+  /**
+   * Mark request as completed (allows rendering)
+   */
+  completeRequest(requestId) {
+    const req = this._inflightRequests.get(requestId);
+    if (req) {
+      req.status = 'completed';
+      this._activeLoadId = requestId;
+    }
+  }
+
+  /**
+   * Verify request is still valid before rendering
+   * Returns true only if this is the most recent request for this conversation
+   */
+  _verifyRequest(requestId, conversationId) {
+    const req = this._inflightRequests.get(requestId);
+
+    // Request not found or cancelled
+    if (!req) return false;
+
+    // Request is for different conversation
+    if (req.conversationId !== conversationId) return false;
+
+    // Find all requests for this conversation
+    const allForConv = Array.from(this._inflightRequests.entries())
+      .filter(([_, r]) => r.conversationId === conversationId && r.status === 'completed')
+      .sort((a, b) => b[0] - a[0]); // Sort by requestId descending (newest first)
+
+    // This request is the newest completed one for this conversation
+    return allForConv.length > 0 && allForConv[0][0] === requestId;
+  }
+
+  /**
+   * Cancel a request (aborts any pending network operations)
+   */
+  _cancelRequest(requestId) {
+    const req = this._inflightRequests.get(requestId);
+    if (req) {
+      req.status = 'cancelled';
+      req.abortController.abort();
+    }
+  }
+
+  /**
+   * Cancel all pending requests for a conversation
+   */
+  cancelConversationRequests(conversationId) {
+    for (const [id, req] of this._inflightRequests.entries()) {
+      if (req.conversationId === conversationId && req.status !== 'completed') {
+        this._cancelRequest(id);
+      }
+    }
+  }
+
+  /**
+   * Cancel all in-flight requests
+   */
+  cancelAllRequests() {
+    for (const [id, req] of this._inflightRequests.entries()) {
+      if (req.status !== 'completed') {
+        this._cancelRequest(id);
+      }
+    }
+  }
+
+  /**
+   * Clean up old requests to prevent memory leak
+   */
+  cleanup() {
+    const now = Date.now();
+    const maxAge = 60000; // Keep requests for 60 seconds
+
+    for (const [id, req] of this._inflightRequests.entries()) {
+      if (now - req.timestamp > maxAge) {
+        this._inflightRequests.delete(id);
+      }
+    }
+  }
+
+  /**
+   * Get debug info about in-flight requests
+   */
+  getDebugInfo() {
+    return {
+      activeLoadId: this._activeLoadId,
+      inflightRequests: Array.from(this._inflightRequests.entries()).map(([id, req]) => ({
+        requestId: id,
+        conversationId: req.conversationId,
+        timestamp: req.timestamp,
+        status: req.status,
+        priority: req.priority,
+        age: Date.now() - req.timestamp
+      }))
+    };
+  }
+}
+
+if (typeof window !== 'undefined') {
+  window.RequestManager = new RequestManager();
+}