agentgui 1.0.393 → 1.0.395

package/lib/ws-optimizer.js

@@ -1,6 +1,3 @@
-// WebSocket Optimization Module
-// Implements batching, rate limiting, compression, deduplication, priority queuing, and monitoring
-
 import zlib from 'zlib';
 
 const MESSAGE_PRIORITY = {
@@ -13,7 +10,20 @@ function getPriority(eventType) {
   if (MESSAGE_PRIORITY.high.includes(eventType)) return 3;
   if (MESSAGE_PRIORITY.normal.includes(eventType)) return 2;
   if (MESSAGE_PRIORITY.low.includes(eventType)) return 1;
-  return 2; // default to normal
+  return 2;
+}
+
+function getBatchInterval(ws) {
+  const BATCH_BY_TIER = { excellent: 16, good: 32, fair: 50, poor: 100, bad: 200 };
+  const TIER_ORDER = ['excellent', 'good', 'fair', 'poor', 'bad'];
+  const tier = ws.latencyTier || 'good';
+  const trend = ws.latencyTrend;
+  if (trend === 'rising' || trend === 'falling') {
+    const idx = TIER_ORDER.indexOf(tier);
+    if (trend === 'rising' && idx < TIER_ORDER.length - 1) return BATCH_BY_TIER[TIER_ORDER[idx + 1]] || 32;
+    if (trend === 'falling' && idx > 0) return BATCH_BY_TIER[TIER_ORDER[idx - 1]] || 32;
+  }
+  return BATCH_BY_TIER[tier] || 32;
 }
 
 class ClientQueue {
@@ -31,151 +41,76 @@ class ClientQueue {
   }
 
   add(data, priority) {
-    // Deduplication: skip if identical to last message
     if (this.lastMessage === data) return;
     this.lastMessage = data;
-
-    if (priority === 3) {
-      this.highPriority.push(data);
-    } else if (priority === 2) {
-      this.normalPriority.push(data);
-    } else {
-      this.lowPriority.push(data);
-    }
-
-    // High priority: flush immediately
-    if (priority === 3) {
-      this.flushImmediate();
-    } else if (!this.timer) {
-      this.scheduleFlush();
-    }
+    if (priority === 3) this.highPriority.push(data);
+    else if (priority === 2) this.normalPriority.push(data);
+    else this.lowPriority.push(data);
+    if (priority === 3) this.flushImmediate();
+    else if (!this.timer) this.scheduleFlush();
   }
 
   scheduleFlush() {
     const interval = this.ws.latencyTier ? getBatchInterval(this.ws) : 100;
-    this.timer = setTimeout(() => {
-      this.timer = null;
-      this.flush();
-    }, interval);
+    this.timer = setTimeout(() => { this.timer = null; this.flush(); }, interval);
   }
 
   flushImmediate() {
-    if (this.timer) {
-      clearTimeout(this.timer);
-      this.timer = null;
-    }
+    if (this.timer) { clearTimeout(this.timer); this.timer = null; }
     this.flush();
   }
 
   flush() {
     if (this.ws.readyState !== 1) return;
-
     const now = Date.now();
     const windowDuration = now - this.windowStart;
-
-    // Reset rate limit window every second
     if (windowDuration >= 1000) {
       this.messageCount = 0;
       this.bytesSent = 0;
       this.windowStart = now;
       this.rateLimitWarned = false;
     }
-
-    // Collect messages from all priorities (high first)
-    const batch = [
-      ...this.highPriority.splice(0),
-      ...this.normalPriority.splice(0, 10),
-      ...this.lowPriority.splice(0, 5)
-    ];
-
+    const batch = [...this.highPriority.splice(0), ...this.normalPriority.splice(0, 10), ...this.lowPriority.splice(0, 5)];
     if (batch.length === 0) return;
-
-    // Rate limiting: max 100 msg/sec per client
     const messagesThisSecond = this.messageCount + batch.length;
     if (messagesThisSecond > 100) {
       if (!this.rateLimitWarned) {
         console.warn(`[ws-optimizer] Client ${this.ws.clientId} rate limited: ${messagesThisSecond} msg/sec`);
         this.rateLimitWarned = true;
       }
-      // Keep high priority, drop some normal/low
       const allowedCount = 100 - this.messageCount;
-      if (allowedCount <= 0) {
-        // Reschedule remaining
-        this.scheduleFlush();
-        return;
-      }
+      if (allowedCount <= 0) { this.scheduleFlush(); return; }
       batch.splice(allowedCount);
     }
-
-    let payload;
-    if (batch.length === 1) {
-      payload = batch[0];
-    } else {
-      payload = '[' + batch.join(',') + ']';
-    }
-
-    // Compression for large payloads (>1KB)
+    let payload = batch.length === 1 ? batch[0] : '[' + batch.join(',') + ']';
     if (payload.length > 1024) {
       try {
         const compressed = zlib.gzipSync(Buffer.from(payload), { level: 6 });
         if (compressed.length < payload.length * 0.9) {
-          // Send compression hint as separate control message
           this.ws.send(JSON.stringify({ type: '_compressed', encoding: 'gzip' }));
           this.ws.send(compressed);
-          payload = null; // Already sent
+          payload = null;
         }
-      } catch (e) {
-        // Fall back to uncompressed
-      }
+      } catch (e) {}
     }
-
-    if (payload) {
-      this.ws.send(payload);
-    }
-
+    if (payload) this.ws.send(payload);
     this.messageCount += batch.length;
     this.bytesSent += (payload ? payload.length : 0);
-
-    // Monitor: warn if >1MB/sec sustained for 3+ seconds
     if (windowDuration >= 3000 && this.bytesSent > 3 * 1024 * 1024) {
       const mbps = (this.bytesSent / windowDuration * 1000 / 1024 / 1024).toFixed(2);
       console.warn(`[ws-optimizer] Client ${this.ws.clientId} high bandwidth: ${mbps} MB/sec`);
     }
-
-    // If there are remaining low-priority messages, schedule next flush
     if (this.normalPriority.length > 0 || this.lowPriority.length > 0) {
       if (!this.timer) this.scheduleFlush();
     }
   }
 
   drain() {
-    if (this.timer) {
-      clearTimeout(this.timer);
-      this.timer = null;
-    }
+    if (this.timer) { clearTimeout(this.timer); this.timer = null; }
     this.flush();
   }
 }
 
-function getBatchInterval(ws) {
-  const BATCH_BY_TIER = { excellent: 16, good: 32, fair: 50, poor: 100, bad: 200 };
-  const TIER_ORDER = ['excellent', 'good', 'fair', 'poor', 'bad'];
-  const tier = ws.latencyTier || 'good';
-  const trend = ws.latencyTrend;
-
-  if (trend === 'rising' || trend === 'falling') {
-    const idx = TIER_ORDER.indexOf(tier);
-    if (trend === 'rising' && idx < TIER_ORDER.length - 1) {
-      return BATCH_BY_TIER[TIER_ORDER[idx + 1]] || 32;
-    }
-    if (trend === 'falling' && idx > 0) {
-      return BATCH_BY_TIER[TIER_ORDER[idx - 1]] || 32;
-    }
-  }
-
-  return BATCH_BY_TIER[tier] || 32;
-}
-
 class WSOptimizer {
   constructor() {
     this.clientQueues = new Map();
@@ -183,16 +118,13 @@ class WSOptimizer {
 
   sendToClient(ws, event) {
     if (ws.readyState !== 1) return;
-
     let queue = this.clientQueues.get(ws);
     if (!queue) {
       queue = new ClientQueue(ws);
       this.clientQueues.set(ws, queue);
     }
-
     const data = typeof event === 'string' ? event : JSON.stringify(event);
     const priority = typeof event === 'object' ? getPriority(event.type) : 2;
-
     queue.add(data, priority);
   }
 
@@ -205,30 +137,18 @@ class WSOptimizer {
   }
 
   getStats() {
-    const stats = {
-      clients: this.clientQueues.size,
-      totalBytes: 0,
-      totalMessages: 0,
-      highBandwidthClients: []
-    };
-
+    const stats = { clients: this.clientQueues.size, totalBytes: 0, totalMessages: 0, highBandwidthClients: [] };
     for (const [ws, queue] of this.clientQueues.entries()) {
       stats.totalBytes += queue.bytesSent;
       stats.totalMessages += queue.messageCount;
-
       const windowDuration = Date.now() - queue.windowStart;
       if (windowDuration > 0) {
         const mbps = (queue.bytesSent / windowDuration * 1000 / 1024 / 1024);
         if (mbps > 1) {
-          stats.highBandwidthClients.push({
-            clientId: ws.clientId,
-            mbps: mbps.toFixed(2),
-            messages: queue.messageCount
-          });
+          stats.highBandwidthClients.push({ clientId: ws.clientId, mbps: mbps.toFixed(2), messages: queue.messageCount });
         }
       }
     }
-
     return stats;
   }
 }

package/package.json

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

package/.prd

@@ -1,215 +0,0 @@
-# AgentGUI ACP Compliance PRD
-
-## Overview
-Transform AgentGUI into a fully ACP (Agent Connect Protocol) v0.2.3 compliant server.
-
-**Current Status**: 100% ACP compliant - All waves completed
-**All Required Features**: Fully implemented and tested
-
-**Note on "Slash Commands"**: ACP spec contains no slash command concept. This is purely a client-side UI feature outside ACP scope. If user wants slash commands implemented, that would be a separate UI enhancement task.
-
----
-
-## Completion Status
-
-### ✅ WAVE 1: Foundation (COMPLETED)
-- Database schema extended with ACP tables
-- Thread state management implemented
-- Checkpoint system operational
-
-### ✅ WAVE 2: Core ACP APIs (COMPLETED)
-- All 23 ACP endpoints implemented
-- Threads API fully functional
-- Stateless runs supported
-- Agent discovery operational
-
-### ✅ WAVE 3: SSE Streaming & Run Control (COMPLETED)
-- SSE streaming endpoints implemented
-- Run cancellation working
-- Event stream format compliant with ACP spec
-
-### ✅ WAVE 4: UI Fixes & Optimization (COMPLETED - Enhanced)
-- **4.1** Thread Sidebar UI Consistency: Fixed agentId vs agentType inconsistency, sidebar now correctly uses `agentId`, model column confirmed in database, agent/model restore on page reload working
-- **4.2** WebSocket Optimization: Added message deduplication via `wsLastMessages` Map and `createMessageKey()` function, prevents identical consecutive messages, adaptive batching and rate limiting already present
-- **4.3** Duplicate Displays: Removed redundant agent/model from conversation headers (3 locations) and streaming start event, kept authoritative displays in sidebar and input selectors only
-
----
-
-## Additional Enhancements (Non-blocking)
-
-### NICE-TO-HAVE 1: Webhook Callbacks
-- Implement webhook support for run status changes
-- POST to webhook URL when run status changes (pending → active → completed)
-- Retry logic: 3 attempts with exponential backoff
-- Store webhook config in run_metadata table
-- Validate webhook URL format on run creation
-
-### NICE-TO-HAVE 2: Run Interrupts
-- Support interrupt mechanism for agents that implement it
-- Interrupt types: user feedback request, tool approval, configuration needed
-- Store interrupt state in sessions table
-- API endpoints: GET /runs/{id}/interrupts, POST /runs/{id}/resume with interrupt response
-- UI: show interrupt prompt, collect user input, resume run
-
-### NICE-TO-HAVE 3: Enhanced Search & Filtering
-- Full-text search on thread content (messages, agent responses)
-- Filter by agent type, date range, status, metadata fields
-- Search history: recent searches saved per user
-- Autocomplete for search filters
-- Export search results as JSON
-
-### NICE-TO-HAVE 4: Thread Templates
-- Save thread configuration as template
-- Templates include: agent, model, initial prompt, working directory
-- Clone thread from template
-- Share templates between users (if multi-user support added)
-
----
-
-## Testing Requirements (Per Item)
-
-Each implementation item must include:
-1. Execute in plugin:gm:dev: create test run for every endpoint/function
-2. Success paths: valid inputs, expected outputs verified
-3. Error paths: invalid inputs, 404s, 409s, 422s verified
-4. Edge cases: empty results, large payloads, concurrent requests
-5. Integration tests: end-to-end flow (create thread → run → stream → cancel)
-6. Database verification: inspect tables after operations, verify foreign keys
-7. WebSocket verification: subscribe, receive events, verify payload format
-8. SSE verification: curl endpoint, verify event-stream format
-
----
-
-## Acceptance Criteria (All Must Pass)
-
-### Core ACP Compliance
-- [ ] All 23 ACP endpoints implemented and tested
-- [ ] All ACP data models match spec (Thread, ThreadState, Run, Agent, etc.)
-- [ ] Error responses follow ACP format (ErrorResponse schema)
-- [ ] SSE streaming works with curl: `curl -N /threads/{id}/runs/stream`
-- [ ] Stateless runs work without thread context
-- [ ] Run cancellation kills agent process within 5 seconds
-- [ ] Thread copy duplicates all states and checkpoints
-- [ ] Agent descriptors return valid JSON matching AgentACPDescriptor schema
-
-### Database Integrity
-- [ ] No orphaned records after thread/run deletion
-- [ ] Foreign key constraints enforced
-- [ ] Thread status correctly reflects run states
-- [ ] Checkpoint sequences monotonically increase
-- [ ] WAL mode enabled, queries under 100ms for typical operations
-
-### UI Consistency
-- [ ] Sidebar shows correct agent for each conversation
-- [ ] Model selection persists after page reload
-- [ ] No duplicate agent/model displays found
-- [ ] Agent/model changes reflected in database immediately
-
-### WebSocket Optimization
-- [ ] Streaming progress events batched (max 10/100ms)
-- [ ] Only subscribed clients receive messages
-- [ ] No client exceeds 1MB/sec sustained WebSocket traffic
-- [ ] Message deduplication prevents identical consecutive events
-
-### Integration & E2E
-- [ ] Full flow: create thread → start run → stream events → cancel → verify cancelled
-- [ ] Stateless run: create run → stream → complete → verify output
-- [ ] Thread search: create 10 threads → search by metadata → verify correct results
-- [ ] Agent search: search by capability "streaming" → verify all streaming agents returned
-- [ ] Thread copy: create thread with 5 runs → copy → verify new thread has all history
-- [ ] Concurrent runs blocked: start run on thread → start second run → verify 409 conflict
-
----
-
-## Migration Strategy
-
-### Backward Compatibility
-- Existing conversations map to threads (1:1)
-- Existing sessions map to thread runs
-- `/api/conversations/*` endpoints remain functional (alias to `/threads/*`)
-- Old WebSocket message formats supported alongside new ACP formats
-- No breaking changes to current client code
-
-### Rollout Plan
-1. Deploy database schema changes (additive only, no drops)
-2. Deploy new ACP endpoints alongside existing endpoints
-3. Update client to use ACP endpoints where beneficial
-4. Deprecation notice for old endpoints (6 month window)
-5. Remove old endpoints after deprecation period
-
----
-
-## Out of Scope
-
-- Multi-user authentication/authorization
-- Slash command implementation (not in ACP spec, pure client feature)
-- Agent marketplace or discovery service
-- Real-time collaboration on threads
-- Thread branching/forking (beyond simple copy)
-- Custom agent development framework
-- Billing/metering for agent usage
-
----
-
-## Technical Notes
-
-### ACP Terminology Mapping
-- AgentGUI "conversations" = ACP "threads"
-- AgentGUI "sessions" = ACP "runs" (stateful, on a thread)
-- AgentGUI "chunks/events" = ACP "run output stream"
-- AgentGUI "claudeSessionId" = ACP checkpoint ID concept
-
-### Known Gotchas
-- ACP requires UUID format for thread_id, run_id, agent_id (current AgentGUI uses strings)
-- SSE requires newline-delimited format, different from current JSON streaming
-- Run cancellation must handle agents that don't support it gracefully
-- Thread status "idle" means no pending runs; must validate on run creation
-- Webhook URLs must be validated to prevent SSRF attacks
-
-### Performance Targets
-- Thread search: <200ms for 10,000 threads
-- Run creation: <50ms (background processing)
-- SSE streaming: <10ms latency per event
-- WebSocket batch: <100ms accumulation window
-- Database writes: <20ms per transaction
-
----
-
-## Dependencies
-
-**External**:
-- None (all features implemented with existing dependencies)
-
-**Internal**:
-- database.js (extended with new tables/queries)
-- server.js (new route handlers)
-- lib/claude-runner.js (run cancellation support)
-- static/js/client.js (UI consistency fixes)
-- static/js/conversations.js (agent/model persistence)
-- static/js/websocket-manager.js (optimization)
-
-**Configuration**:
-- No new env vars required
-- Existing BASE_URL, PORT, STARTUP_CWD remain unchanged
-
----
-
-## Success Metrics
-
-- ACP compliance score: 0% → 100%
-- API endpoint coverage: 20 → 43 endpoints
-- WebSocket bandwidth: <50% reduction in bytes/sec per client
-- UI consistency issues: 4 identified → 0 remaining
-- Database tables: 5 → 8 (conversations, messages, sessions, events, chunks, thread_states, checkpoints, run_metadata)
-- Test coverage: endpoint tests for all 43 routes, integration tests for all critical flows
-
----
-
-## Timeline Estimate
-
-- Wave 1 (Foundation): 3 parallel tasks = 1 completion cycle
-- Wave 2 (Core APIs): 3 parallel tasks = 1 completion cycle
-- Wave 3 (Streaming): 2 tasks = 1 completion cycle
-- Wave 4 (UI Fixes): 3 tasks = 1 completion cycle
-
-**Total**: 4 completion cycles (waves executed sequentially, items within wave executed in parallel with max 3 concurrent subagents per wave)