agentgui 1.0.33 → 1.0.35

package/IMPLEMENTATION_CHECKLIST.md

@@ -0,0 +1,287 @@
+# State Machine Implementation - Checklist & Reference
+
+## ✅ Completed Features
+
+### Core State Machine
+- [x] StateManager class with 9 defined states
+- [x] State transition validation
+- [x] Invalid transition guards (throw errors)
+- [x] State history tracking with timestamps
+- [x] Reason/metadata for each transition
+- [x] Automatic 120-second timeout watchdog
+- [x] Promise-based completion API
+- [x] Terminal state detection
+- [x] State history retrieval
+
+### Session Management
+- [x] SessionStateStore global registry
+- [x] Session creation with ID tracking
+- [x] Session retrieval and validation
+- [x] Active session filtering
+- [x] Terminal session tracking
+- [x] Automatic cleanup (>1 hour)
+- [x] Diagnostic aggregation
+
+### Server Integration
+- [x] Import StateManager in server.js
+- [x] Create global SessionStateStore
+- [x] Rewrite processMessage() to use state machine
+- [x] Add state transitions for each step
+- [x] Implement error handling with state tracking
+- [x] Add getACP() timeout protection (60s)
+- [x] Create /api/diagnostics/sessions endpoint
+- [x] Add comprehensive logging
+
+### Database Fixes
+- [x] Fix message content type handling (stringify objects)
+- [x] Fix session response/error serialization
+- [x] Fix event data JSON handling
+- [x] Fix idempotencyKeys type conversion
+
+### Documentation
+- [x] StateManager code comments
+- [x] Architecture diagrams
+- [x] Usage examples
+- [x] Monitoring guide
+- [x] Diagnostics explanation
+- [x] Issue diagnosis (ACP hang)
+- [x] Next steps guide
+
+---
+
+## 📊 State Machine States
+
+```
+PENDING
+  ↓
+ACQUIRING_ACP  ← Connect to Claude Code ACP
+  ↓
+ACP_ACQUIRED   ← Connection established
+  ↓
+SENDING_PROMPT ← Sending prompt to ACP
+  ↓
+PROCESSING     ← Processing response
+  ↓
+COMPLETED      ← ✅ Success
+
+ERROR          ← ❌ Any step failed (at any point)
+TIMEOUT        ← ❌ Exceeded 120s (automatic)
+CANCELLED      ← Stopped by user
+```
+
+---
+
+## 🔍 Diagnostics Endpoint
+
+**Endpoint**: `GET /api/diagnostics/sessions`
+
+**Response Format**:
+```javascript
+{
+  timestamp: ISO 8601 string,
+  activeSessions: number,
+  terminalSessions: number,
+  totalSessions: number,
+  active: [
+    {
+      sessionId: string,
+      state: string,
+      uptime: milliseconds
+    }
+  ],
+  recentTerminal: [
+    {
+      sessionId: string,
+      conversationId: string,
+      messageId: string,
+      state: 'completed'|'error'|'timeout'|'cancelled',
+      duration: '1234ms',
+      historyLength: number,
+      history: ['0ms: pending (initialized)', ...],
+      data: {
+        fullTextLength: number,
+        blocksCount: number,
+        error: null | string,
+        hasStackTrace: boolean
+      }
+    }
+  ]
+}
+```
+
+---
+
+## 🚀 Usage Examples
+
+### Create a Session
+```javascript
+const stateManager = sessionStateStore.create(
+  sessionId,
+  conversationId,
+  messageId,
+  120000  // timeout in ms
+);
+```
+
+### Transition State
+```javascript
+stateManager.transition(StateManager.STATES.ACQUIRING_ACP, {
+  reason: 'Starting ACP connection',
+  data: {}
+});
+```
+
+### Check Current State
+```javascript
+const state = stateManager.getState();
+// 'pending' | 'acquiring_acp' | 'acp_acquired' | ...
+```
+
+### Get Full History
+```javascript
+const history = stateManager.getHistory();
+// Array of {state, timestamp, reason, details}
+```
+
+### Wait for Completion
+```javascript
+try {
+  const result = await stateManager.waitForCompletion();
+  console.log(`Success in ${result.data.duration}`);
+} catch (err) {
+  console.error(`Failed: ${err.message}`);
+}
+```
+
+### Get Diagnostics
+```javascript
+const diag = sessionStateStore.getDiagnostics();
+console.log(`Active: ${diag.activeSessions}`);
+console.log(`Terminal: ${diag.terminalSessions}`);
+```
+
+---
+
+## 🛡️ Error Handling
+
+### Invalid Transition
+```javascript
+// This will throw!
+stateManager.transition(StateManager.STATES.COMPLETED, {});
+// Error: "Invalid state transition: pending → completed. Valid: [acquiring_acp, cancelled]"
+```
+
+### Session Not Found
+```javascript
+const manager = sessionStateStore.getOrThrow(sessionId);
+// Throws if sessionId doesn't exist
+```
+
+### Timeout
+```javascript
+// After 120 seconds in any non-terminal state:
+// Automatically transitions to TIMEOUT state
+```
+
+---
+
+## 📝 Logging Output
+
+### State Transition Log
+```
+[StateManager] sess-123 transitioned: pending → acquiring_acp (+1ms) | Starting ACP connection
+[StateManager] sess-123 transitioned: acquiring_acp → acp_acquired (+25ms) | ACP connected
+[StateManager] sess-123 transitioned: acp_acquired → sending_prompt (+0ms) | Sending to ACP
+[StateManager] sess-123 transitioned: sending_prompt → processing (+100ms) | Processing response
+[StateManager] sess-123 transitioned: processing → completed (+2145ms) | Response successfully generated
+```
+
+### Process Message Log
+```
+[processMessage] Starting: conversationId=conv-123, sessionId=sess-456
+[processMessage] Initial state: pending
+[getACP] Step 1: Connecting to claude-code...
+[getACP] Step 2: Connected, initializing...
+[getACP] Step 3: Initialized, creating session...
+[getACP] ✅ ACP connection ready for claude-code in /config
+[processMessage] Sending prompt to ACP (45 chars)
+[processMessage] ACP returned: stopReason=end_turn, fullText=12345 chars
+[processMessage] ✅ Session completed: 2567ms
+```
+
+---
+
+## 🔧 Configuration
+
+### Timeouts
+- **Session timeout**: 120 seconds (hardcoded)
+- **ACP timeout**: 60 seconds (hardcoded in getACP)
+- **Session cleanup TTL**: 3600000ms (1 hour)
+
+### Cleanup Schedule
+- Runs every 10 minutes (600000ms)
+- Removes terminal sessions older than 1 hour
+
+### Data Retention
+- Recent terminal sessions: kept in memory indefinitely
+- Cleanup prevents unbounded memory growth
+
+---
+
+## 🐛 Debugging
+
+### See All Active Sessions
+```bash
+curl http://localhost:9899/gm/api/diagnostics/sessions | grep -A 5 "active"
+```
+
+### Find Stuck Sessions
+```bash
+curl http://localhost:9899/gm/api/diagnostics/sessions | grep "acquiring_acp"
+```
+
+### Get Session History
+```bash
+curl http://localhost:9899/gm/api/diagnostics/sessions | grep -A 20 "recentTerminal"
+```
+
+### Follow State Transitions
+```bash
+tail -f server.log | grep "StateManager"
+```
+
+### Find Errors
+```bash
+tail -f server.log | grep -E "ERROR|Stack:|❌"
+```
+
+---
+
+## 📚 Files Modified
+
+| File | Changes | Lines |
+|------|---------|-------|
+| state-manager.js | NEW | 350 |
+| server.js | Modified | +300, -80 |
+| database.js | Fixed | +40 |
+| DIAGNOSTICS.md | NEW | 80 |
+| STATE_MACHINE_SUMMARY.md | NEW | 220 |
+
+---
+
+## ✨ Key Improvements
+
+**Before State Machine**:
+- ❌ Fire-and-forget processing
+- ❌ No visibility into failures
+- ❌ Hangs cause no feedback
+- ❌ Hidden race conditions
+- ❌ Impossible to debug
+
+**After State Machine**:
+- ✅ Every session tracked
+- ✅ Complete visibility
+- ✅ Immediate timeout detection
+- ✅ Explicit error handling
+- ✅ Full audit trail
+

package/bin/gmgui.cjs

@@ -21,9 +21,12 @@ async function gmgui(args = []) {
     const useBun = hasBun();
     const installer = useBun ? 'bun' : 'npm';
 
-    // Ensure dependencies are installed
+    // Ensure dependencies are installed only if node_modules is missing
+    // Skip this for bunx which manages dependencies independently
     const nodeModulesPath = path.join(projectRoot, 'node_modules');
-    if (!fs.existsSync(nodeModulesPath)) {
+    const isBunx = process.env.npm_execpath && process.env.npm_execpath.includes('bunx');
+
+    if (!isBunx && !fs.existsSync(nodeModulesPath)) {
       console.log(`Installing dependencies with ${installer}...`);
       const installResult = spawnSync(installer, ['install'], {
         cwd: projectRoot,
@@ -45,12 +48,17 @@ async function gmgui(args = []) {
         stdio: 'inherit'
       });
 
+      ps.on('error', reject);
+
+      // Keep this process alive indefinitely to keep the server running
+      // The server will handle all actual work; this process just provides the bridge
+      process.stdin.resume();
+
+      // If server exits unexpectedly, log it but keep trying
       ps.on('exit', (code) => {
-        if (code === 0) resolve();
-        else reject(new Error(`Server exited with code ${code}`));
+        console.error(`Server process exited with code ${code}`);
+        // Don't reject or resolve - just keep waiting
       });
-
-      ps.on('error', reject);
     });
   } else {
     throw new Error(`Unknown command: ${command}`);

package/package.json

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

package/static/app.js

@@ -1458,7 +1458,57 @@ class GMGUIApp {
     }
     const content = document.createElement('div');
     content.className = 'html-content';
-    content.innerHTML = this.sanitizeHtml(event.html);
+
+    // Get current theme to apply to HTML content
+    const currentTheme = document.documentElement.getAttribute('data-theme') ||
+                        (window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light');
+
+    // Apply theme-aware CSS for consistent colors in dark/light mode
+    const themeCSS = currentTheme === 'dark'
+      ? `<style>
+           .html-content {
+             color: #f8fafc;
+             background: transparent;
+           }
+           .html-content p { color: #cbd5e1; }
+           .html-content h1, .html-content h2, .html-content h3,
+           .html-content h4, .html-content h5, .html-content h6 {
+             color: #f8fafc;
+           }
+           .html-content a { color: #6366f1; }
+           .html-content code { color: #c7d2fe; background: rgba(0,0,0,0.3); }
+           .html-content pre { background: rgba(0,0,0,0.5); color: #e0e7ff; }
+           .html-content table { border-color: #334155; }
+           .html-content th { background: #1a202c; color: #f8fafc; }
+           .html-content td { border-color: #334155; }
+           .html-content blockquote { border-color: #334155; color: #cbd5e1; }
+           .html-content ul, .html-content ol { color: #cbd5e1; }
+           .html-content li { color: #cbd5e1; }
+        </style>`
+      : `<style>
+           .html-content {
+             color: #1d2129;
+             background: transparent;
+           }
+           .html-content p { color: #475569; }
+           .html-content h1, .html-content h2, .html-content h3,
+           .html-content h4, .html-content h5, .html-content h6 {
+             color: #1d2129;
+           }
+           .html-content a { color: #4f46e5; }
+           .html-content code { color: #6366f1; background: rgba(99,102,241,0.1); }
+           .html-content pre { background: #f3f4f6; color: #1d2129; }
+           .html-content table { border-color: #e5e7eb; }
+           .html-content th { background: #f9fafb; color: #1d2129; }
+           .html-content td { border-color: #e5e7eb; }
+           .html-content blockquote { border-color: #e5e7eb; color: #475569; }
+           .html-content ul, .html-content ol { color: #475569; }
+           .html-content li { color: #475569; }
+        </style>`;
+
+    const enhancedHtml = themeCSS + this.sanitizeHtml(event.html);
+    content.innerHTML = enhancedHtml;
+    content.setAttribute('data-theme', currentTheme);
     wrap.appendChild(content);
     return wrap;
   }