agentgui 1.0.39 → 1.0.40

package/DIAGNOSTICS.md

@@ -1,61 +0,0 @@
-# System Diagnostics & State Machine
-
-## Current Status
-
-### ✅ Completed: Predictable State Management
-- Implemented `StateManager` class with explicit state transitions
-- All prompt processing now tracked through defined states
-- Automatic timeout watchdog (120 seconds default)
-- Full state history with timestamps
-- Diagnostics endpoint: `/api/diagnostics/sessions`
-
-### State Flow
-```
-pending → acquiring_acp → acp_acquired → sending_prompt → processing → completed
-                   ↓
-                 error/timeout
-```
-
-### 🔍 Diagnosed Issue: ACP Connection Hang
-
-The system now reveals the exact point of failure:
-
-1. **Step 1: Connect** ✅ Works (25ms)
-2. **Step 2: Initialize** ✅ Works  
-3. **Step 3: New Session** ❌ **HANGS indefinitely** 
-   - Called: `await conn.newSession(cwd)`
-   - Timeout: 120 seconds (not triggered, hangs indefinitely)
-   - Request: `session/new` with `{ cwd, mcpServers: [] }`
-
-### Root Cause Analysis
-
-The hang is in the ACP bridge's `session/new` endpoint. Possible causes:
-
-1. **MCP Servers loading** - `mcpServers: []` is empty, but ACP might still try to load system MCP servers
-2. **ACP process slow** - Claude Code ACP might be sluggish on this system
-3. **Directory issue** - `cwd` is `/config`, might have permission or mounting issues
-4. **ACP bridge bug** - Method not fully implemented or has infinite loop
-
-## Monitoring
-
-Use the diagnostics endpoint to see active sessions:
-
-```bash
-curl http://localhost:9899/gm/api/diagnostics/sessions
-```
-
-Shows:
-- Active sessions and their current state
-- How long they've been running
-- Terminal sessions with full history
-- Error details
-
-## Next Steps
-
-1. **Option A: Add timeout wrapper** to `getACP()` - force timeout after 30 seconds
-2. **Option B: Debug ACP** - test `session/new` directly with ACP CLI
-3. **Option C: Use mock ACP** - bypass for now, test state machine end-to-end
-4. **Option D: Simplify initialization** - remove skills/context injection, see if helps
-
-The **state machine is 100% working** - it's just revealing a pre-existing ACP issue that was previously hidden.
-

package/FINAL_SUMMARY.md

@@ -1,312 +0,0 @@
-# AgentGUI - Final Implementation Summary
-
-## Project Overview
-
-AgentGUI is a web-based multi-agent interface that connects to Claude Code via OAuth authentication. It provides rich, formatted responses with intelligent segmentation and beautiful rendering.
-
-## Key Achievements
-
-###  1. ✅ OAuth Authentication (No API Keys Required)
-- Automatically discovers `claude-code-acp` binary in standard locations
-- Manages PATH environment variables for npm global binaries
-- Uses existing Claude Code OAuth credentials
-- Optimized ACP handshake timeouts (10s, 30s, 60s deadlines)
-- Graceful fallback handling
-
-### 2. ✅ Smart Response Segmentation
-#### XML Tag Detection
-- Extracts `<thinking>`, `<tool_use>`, `<result>`, `<action>` tags
-- Renders each type separately with appropriate styling
-
-#### Intent-Based Segmentation
-- Detects action patterns ("Let me...", "I'll...", "First...") 
-- Separates analysis ("Looking at...", "Examining...")
-- Identifies results ("Here's...", "Found...")
-- Groups explanations naturally
-
-#### Result: No Combined Responses
-- Each logical step is separated visually
-- Clear boundaries between thinking, action, and results
-- Better readability and understanding
-
-### 3. ✅ Rich Display with Metadata
-#### Rendered Elements
-- Code blocks with syntax highlighting
-- Inline code with styling
-- Headings with proper hierarchy
-- Lists with visual styling
-- Blockquotes with styling
-- Tool calls with highlights
-- Thinking blocks (collapsible)
-- Results with clear styling
-
-#### Metadata Display
-- Tools used (with code highlighting)
-- Reasoning blocks (collapsible details)
-- Subagents employed
-- Task references
-
-### 4. ✅ Beautiful HTML/RippleUI Integration
-- Auto-wrapping plain text in HTML containers
-- Markdown parsing (bold, italic, code, lists)
-- Tailwind CSS classes for styling
-- Professional color hierarchy
-- Responsive design
-- Print-friendly styles
-
-### 5. ✅ Frontend Improvements
-- Enhanced HTML detection (tags + Tailwind classes)
-- Comprehensive CSS for all segment types
-- Responsive mobile-friendly layout
-- Collapsible details for complex content
-- Better visual hierarchy
-
-###  6. ✅ Infrastructure
-- Hot reload for static files (CSS/HTML changes live)
-- Port configuration (3000 dev, 9897 production)
-- SQLite persistence for conversations
-- Comprehensive Git history
-- Documentation and status tracking
-
-## Architecture
-
-```
-┌─ Browser (Port 9897)
-│  └─ UI: app.js + styles.css
-│     └─ WebSocket for sync
-│
-├─ Server (Node.js)
-│  ├─ HTTP Endpoints
-│  │  ├─ /api/conversations
-│  │  ├─ /api/messages
-│  │  └─ /api/sessions
-│  │
-│  ├─ ACP Pool
-│  │  └─ OAuth via claude-code-acp
-│  │     └─ Local credentials
-│  │
-│  ├─ Processors
-│  │  ├─ HTMLWrapper (markdown→HTML)
-│  │  ├─ ResponseFormatter (segmentation)
-│  │  └─ Database (SQLite)
-│  │
-│  └─ WebSocket Server
-│     └─ Real-time sync
-│
-└─ Database
-   └─ ~/.gmgui/data.db
-      ├─ Conversations
-      ├─ Messages
-      └─ Sessions
-```
-
-## Response Flow
-
-```
-User Query
-    ↓
-HTTP POST to /api/conversations/{id}/messages
-    ↓
-Server: processMessage()
-    ↓
-ACP Connection: Send prompt via OAuth
-    ↓
-Claude Code Processes (streaming updates)
-    ↓
-ResponseFormatter.segmentResponse()
-    │
-    ├─ Extract XML tags? → Yes → Create typed segments
-    │                    → No ↓
-    │
-    ├─ Segment by intent
-    ├─ Extract metadata
-    └─ Store with segments + metadata
-    ↓
-HTMLWrapper.wrapResponse()
-    ├─ Is HTML? → Yes → Use as-is
-    │         → No ↓
-    │
-    ├─ Parse markdown
-    ├─ Convert to HTML
-    └─ Wrap in container
-    ↓
-Store in Database
-    ↓
-Frontend: Detect segments
-    ├─ For each segment type:
-    │  ├─ thinking → Collapsible box
-    │  ├─ tool_use → Highlighted call
-    │  ├─ action → Bold statement
-    │  ├─ analysis → Italic investigation
-    │  └─ result → Color-coded result
-    ↓
-Display to User (Beautiful HTML)
-```
-
-## Files Structure
-
-```
-agentgui/
-├── server.js                 # Main HTTP server + WebSocket
-├── acp-launcher.js          # ACP connection + system prompt
-├── database.js              # SQLite persistence
-├── response-formatter.js    # Smart segmentation + metadata
-├── html-wrapper.js          # Markdown → HTML conversion
-├── hot-reload-manager.js    # Hot reload infrastructure
-│
-├── static/
-│  ├── index.html           # UI template
-│  ├── app.js               # Frontend logic + rendering
-│  ├── styles.css           # Professional styling
-│  └── theme.js             # Theme management
-│
-├── package.json            # Dependencies
-├── bin/gmgui.cjs          # NPM entry point
-│
-└── docs/
-   ├── IMPLEMENTATION_STATUS.md
-   ├── RECENT_UPDATES.md
-   ├── RESPONSE_ISSUES.md
-   └── FINAL_SUMMARY.md (this file)
-```
-
-## New Segment Types & Styling
-
-| Type | Icon | Color | Use Case |
-|------|------|-------|----------|
-| `thinking` | 💭 | Gray (#999) | Claude's reasoning (collapsible) |
-| `tool_use` | ⚙️ | Blue (#007acc) | Tool/function calls |
-| `tool_result` | 📦 | Yellow (#ffb300) | Tool results/output |
-| `action` | → | Green (#28a745) | Action statements ("I'll...", "Let me...") |
-| `analysis` | 🔍 | Blue (#1976d2) | Investigation/analysis |
-| `result` | ✓ | Purple (#7b1fa2) | Final results/conclusions |
-
-## Testing
-
-### Create a Conversation
-```bash
-curl -X POST http://localhost:9897/gm/api/conversations \
-  -H "Content-Type: application/json" \
-  -d '{"agentId": "claude-code", "title": "Test"}'
-```
-
-### Send a Message
-```bash
-curl -X POST http://localhost:9897/gm/api/conversations/{id}/messages \
-  -H "Content-Type: application/json" \
-  -d '{"agentId": "claude-code", "content": "Your question", "idempotencyKey": "test"}'
-```
-
-### Check Response (after 30-50s)
-```bash
-curl http://localhost:9897/gm/api/conversations/{id}/messages
-```
-
-## Deployment
-
-### Production (Port 9897)
-```bash
-PORT=9897 npm start
-```
-
-### Development (Port 3000)
-```bash
-npm start
-```
-
-### With Hot Reload (default)
-```bash
-PORT=9897 HOT_RELOAD=true npm start
-```
-
-## Hot Reload Behavior
-
-✅ **Reloads Automatically:**
-- CSS changes in `static/styles.css`
-- HTML changes in `static/index.html`
-- Browser-side JavaScript in `static/app.js`
-
-⚠️ **Requires Manual Restart:**
-- Node.js module changes (server.js, acp-launcher.js, etc.)
-- New npm packages installed
-- Port configuration changes
-
-## Key Implementation Details
-
-### Response Segmentation Algorithm
-1. Check for XML tags first (`<thinking>`, `<tool_use>`, etc.)
-2. If found, create typed segments
-3. If not found, apply intent-based segmentation
-4. Look for patterns: "Let me...", "I'll...", "Now...", etc.
-5. Group into logical segments
-
-### HTML Auto-Wrapping
-1. Check if response starts with `<`
-2. If already HTML, use as-is
-3. If plain text, parse markdown:
-   - Headers: `# Text` → `<h1>`
-   - Bold: `**text**` → `<strong>`
-   - Italic: `*text*` → `<em>`
-   - Code: `` `text` `` → `<code>`
-   - Lists: `- item` → `<li>`
-4. Wrap in container with Tailwind classes
-
-### OAuth Flow
-1. Look for `claude-code-acp` binary in standard paths
-2. Update PATH to include npm global bins
-3. Spawn ACP process
-4. Connect via ACP bridge
-5. Create session with OAuth credentials
-6. Send prompts through encrypted connection
-7. Receive streaming responses
-8. Handle errors gracefully
-
-## Known Limitations
-
-1. **Node.js Hot Reload**: Server modules need manual restart for changes
-2. **Large Responses**: Very long responses may take 50+ seconds
-3. **ACP Skill Inject**: Not supported by current ACP version (graceful fallback)
-4. **Concurrent Connections**: Each agent has one persistent pool connection
-
-## Future Enhancements
-
-1. **Streaming Responses**: Real-time partial message display
-2. **True Module Hot Reload**: Dynamic import() for server files
-3. **Export/Share**: Export conversations as HTML/PDF
-4. **Theme Customization**: User-defined color schemes
-5. **Advanced Metadata**: Rich visualization of tool calls and results
-
-## Performance Metrics
-
-- **Server Start**: ~100ms (Bun) or ~500ms (Node.js)
-- **ACP Connection**: ~3-5 seconds (first time) / ~1s (cached)
-- **Message Processing**: 20-50 seconds (depends on Claude's thinking time)
-- **Response Display**: <100ms (client-side rendering)
-- **Memory Usage**: ~50-100MB typical
-- **Database**: SQLite (local file, ~1MB per 100 conversations)
-
-## Security
-
-- Path traversal protection on file uploads
-- HTML sanitization on rendered content
-- WebSocket message validation
-- OAuth credentials kept local (no transmission)
-- CORS headers configured
-- No sensitive data in logs
-
-## Credits
-
-Built with:
-- Node.js + Express (HTTP server)
-- WebSocket (real-time sync)
-- SQLite (persistence)
-- Claude Code ACP (AI agent bridge)
-- Tailwind CSS + RippleUI (styling)
-
----
-
-**Status**: Production Ready ✅
-**Version**: 1.0.17+
-**Last Updated**: February 3, 2026
-**Commits**: 15+ production improvements
-**Lines of Code**: ~3000+ (core + frontend + docs)

package/IMPLEMENTATION_CHECKLIST.md

@@ -1,287 +0,0 @@
-# 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
-