agentgui 1.0.38 → 1.0.40

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
-

package/IMPLEMENTATION_STATUS.md

@@ -1,189 +0,0 @@
-# AgentGUI Implementation Status
-
-## ✅ Completed Features
-
-### 1. OAuth Authentication
-- ✅ Binary discovery for `claude-code-acp`
-- ✅ Automatic PATH management
-- ✅ Timeout optimization for ACP bridge
-- ✅ Uses local Claude Code credentials (no API key needed)
-
-### 2. Response Formatting Infrastructure
-- ✅ ResponseFormatter module for parsing responses
-- ✅ Segment detection (code, headings, text, lists)
-- ✅ Metadata extraction (tools, thinking, tasks, subagents)
-- ✅ Frontend rendering for segments and metadata
-
-### 3. HTML/RippleUI System
-- ✅ Enhanced system prompt with detailed HTML instructions
-- ✅ HTMLWrapper module for automatic HTML wrapping
-- ✅ Markdown parsing to HTML conversion
-- ✅ Tailwind CSS styling integration
-
-### 4. Frontend Improvements
-- ✅ Enhanced HTML detection (tags + Tailwind classes)
-- ✅ Rich CSS styling for code blocks, metadata, segments
-- ✅ Responsive design for all components
-- ✅ Print-friendly styles
-
-### 5. Infrastructure
-- ✅ Hot reload preparation (HotReloadManager module)
-- ✅ Git version control with comprehensive commit history
-- ✅ Port configuration (3000 dev, 9897 production)
-- ✅ Database persistence
-
-## 🔄 Partially Implemented
-
-### Hot Reload for Node Modules
-- ⚠️ Static files auto-reload: YES (CSS, HTML, JS in browser)
-- ⚠️ Node.js module changes: NO (requires server restart)
-- **Workaround**: Changes to `.js` files in `/config/workspace/agentgui/` require manual server restart
-- **Future**: Implement full ES module reloading
-
-## 📊 Current Architecture
-
-```
-User → Browser (9897)
-  ↓
-Server.js (Node.js)
-  ├→ ACP Pool (connects to claude-code-acp)
-  │  └→ OAuth via local credentials
-  ├→ HTMLWrapper (wraps responses in HTML)
-  ├→ ResponseFormatter (segments & metadata)
-  └→ Database (SQLite)
-```
-
-## 🎯 Current Limitations
-
-1. **System Prompt Not Fully Enforced**
-   - Claude Code's system prompt about HTML responses works partially
-   - Plain text responses are now auto-wrapped by HTMLWrapper
-   - Result: All responses display as HTML regardless of original format
-
-2. **Hot Module Reloading**
-   - Static files (CSS, HTML) reload automatically
-   - JavaScript/Node modules need manual restart
-   - Recommendation: Changes to server logic need restart
-
-3. **ACP Skill Injection**
-   - `session/skill_inject` not supported by current ACP version
-   - Falls back gracefully without error
-   - System prompt still injected via context
-
-## 📋 Next Steps
-
-### For Full HTML Response Enforcement
-1. ✅ Already Done: HTMLWrapper auto-converts plain text to HTML
-2. No further action needed - all responses now display as beautifully formatted HTML
-
-### For True Hot Module Reloading
-1. Implement dynamic `import()` for module reloading
-2. Add module-level cache busting
-3. Handle state preservation during reload
-
-### For Enhanced Display
-1. Add streaming responses (real-time message display)
-2. Add more sophisticated metadata visualization
-3. Add export/sharing functionality
-
-## 🧪 Testing
-
-### Test a Message
-```bash
-CONV=$(curl -s -X POST http://localhost:9897/gm/api/conversations \
-  -H "Content-Type: application/json" \
-  -d '{"agentId": "claude-code", "title": "Test"}' | python3 -c "import sys,json; print(json.load(sys.stdin)['conversation']['id'])")
-
-curl -s -X POST "http://localhost:9897/gm/api/conversations/$CONV/messages" \
-  -H "Content-Type: application/json" \
-  -d '{"agentId": "claude-code", "content": "Your question here", "idempotencyKey": "test-1"}'
-
-# Check response after ~30-50 seconds
-curl -s "http://localhost:9897/gm/api/conversations/$CONV/messages" | python3 -m json.tool
-```
-
-## 📝 Files Structure
-
-```
-agentgui/
-├── server.js                 # Main HTTP server + WebSocket
-├── acp-launcher.js          # ACP connection management + system prompt
-├── database.js              # SQLite persistence
-├── response-formatter.js    # Response parsing & segmentation
-├── html-wrapper.js          # Markdown to HTML conversion
-├── hot-reload-manager.js    # Hot reload infrastructure (prepared)
-├── static/
-│   ├── app.js              # Frontend logic
-│   ├── index.html          # UI template
-│   ├── styles.css          # Comprehensive styling
-│   └── theme.js            # Theme management
-└── package.json            # Dependencies
-```
-
-## 🚀 Running the Server
-
-```bash
-# Development (port 3000)
-npm start
-
-# Production (port 9897)
-PORT=9897 npm start
-
-# With hot reload enabled (default)
-PORT=9897 HOT_RELOAD=true npm start
-
-# To disable hot reload
-PORT=9897 HOT_RELOAD=false npm start
-```
-
-## 💡 Key Implementation Details
-
-### HTML Wrapping Flow
-```
-Claude's plain text response
-  ↓
-HTMLWrapper.wrapResponse()
-  ↓
-Parse markdown syntax
-  ↓
-Convert to HTML with Tailwind classes
-  ↓
-Wrap in container div
-  ↓
-Store as messageContent.text
-  ↓
-Frontend detects HTML (starts with <div)
-  ↓
-Renders with sanitization
-```
-
-### Response Structure
-```json
-{
-  "id": "msg-xxx",
-  "role": "assistant",
-  "content": {
-    "text": "<div class=\"space-y-4 p-6\">...HTML...</div>",
-    "segments": [...],
-    "metadata": {...},
-    "updateChunks": [...],
-    "blocks": [],
-    "isHTML": true
-  }
-}
-```
-
-## ✨ Results
-
-- All responses now display as beautiful, styled HTML
-- Code blocks are properly syntax-highlighted
-- Metadata (tools, thinking, tasks) are rich and interactive
-- System runs on port 9897 for production
-- OAuth authentication works seamlessly
-- Database persists conversations and history
-
----
-
-**Last Updated**: February 3, 2026
-**Version**: 1.0.16+
-**Status**: Production Ready (with auto-HTML wrapping)

package/README.md

@@ -1,213 +0,0 @@
-# GMGUI - Multi-Agent ACP Client
-
-A buildless, hot-reloading web client for managing multiple Claude Agent Protocol (ACP) agents with real-time communication via WebSocket and MessagePack.
-
-**Status**: ✅ Production Ready | **Version**: 1.0.0 | **License**: MIT
-
-## Get Started Now - One Command
-
-```bash
-bunx agentgui
-```
-
-That's it. One command starts the server and opens http://localhost:3000/gm/ in your browser.
-
-**Works anywhere:** Any system with Bun installed.
-
-**Stop anytime:** Press Ctrl+C - clean shutdown.
-
-## Features
-
-- **Multi-Agent Management**: Connect unlimited ACP agents and switch between them instantly
-- **Real-Time Communication**: WebSocket + MessagePack for efficient bidirectional messaging
-- **Desktop Screenshots**: Capture and share desktop screenshots with agents (via scrot)
-- **File Upload/Download**: Upload files for agents to access, download files from conversations
-- **Modern Responsive UI**: Beautiful interface that works on mobile, tablet, and desktop
-- **Conversation History**: Full message history with timestamps
-- **Zero Build Step**: Pure HTML/CSS/JavaScript - no bundling or transpilation
-- **Minimal Dependencies**: Only 1 production dependency (ws)
-
-## How It Works
-
-**Chat Interface**
-- Real-time message display with timestamps
-- Send/receive messages with agents
-- Clear chat history
-
-**File Management**
-- Upload files for agents to access
-- Download files from conversations
-- Files stored automatically
-
-**Desktop Sharing**
-- Capture desktop screenshots
-- Share directly with agents
-
-**Agent Management**
-- Add agents by ID and endpoint
-- View connection status
-- Switch between agents
-
-**Responsive Design**
-- Works on desktop, tablet, and mobile
-- Touch-friendly interface
-- Optimized for all screen sizes
-
-## API Endpoints
-
-### Get Agents
-```
-GET /api/agents
-```
-Response: `{"agents": [...]}`
-
-### Send Message to Agent
-```
-POST /api/agents/{agentId}
-Content-Type: application/json
-
-{"type": "message", "content": "..."}
-```
-
-### Upload Files
-```
-POST /api/upload
-Content-Type: multipart/form-data
-
-file=@path/to/file.txt
-```
-
-### Capture Screenshot
-```
-POST /api/screenshot
-```
-
-### Download File
-```
-GET /uploads/{filename}
-```
-
-## Configuration
-
-### Environment Variables
-- `PORT` (default: 3000) - Server port
-- `UPLOAD_DIR` (default: /tmp/gmgui-conversations) - File storage location
-
-### Data Storage
-
-**Conversation History**: Stored in `~/.gmgui/data.db` (hidden folder in your home directory)
-- Uses SQLite database for persistent storage
-- Auto-created on first run with proper permissions
-- Contains conversations, messages, sessions, and event history
-- Data persists across runs and restarts
-- Private to current user (mode 0644)
-
-**Browser Local Storage**
-- `gmgui-settings` - User preferences and configuration
-
-**Why Hidden Folder?**
-Using `~/.gmgui/` follows Unix conventions:
-- Hidden folders (starting with `.`) keep user directories clean
-- Prevents accidental deletion or modification
-- Private by convention - not visible in casual `ls` output
-- Standard practice for application data (`.config`, `.local`, `.cache`)
-
-## Architecture
-
-### Server (Node.js)
-- HTTP server with static file serving
-- WebSocket server for agent connections
-- File upload/download endpoints
-- Screenshot capture endpoint
-- Agent management
-
-### Client (Browser)
-- Real-time message display
-- File management UI
-- Screenshot capture and preview
-- Agent connection management
-- Settings persistence
-
-### File Structure
-```
-gmgui/
-├── server.js                    # HTTP + WebSocket server
-├── database.js                  # SQLite persistence
-├── acp-launcher.js              # Agent management
-├── bin/gmgui.cjs                # npm entry point
-├── static/
-│   ├── index.html              # Main UI
-│   ├── app.js                  # Frontend logic
-│   ├── styles.css              # Responsive styles
-│   ├── theme.js                # Theme management
-│   └── rippleui.css            # CSS framework
-├── install.sh                   # One-liner installer
-├── package.json                 # Dependencies
-└── README.md                    # This file
-```
-
-## Development
-
-### Enable Hot Reload (during development)
-```bash
-npm run dev
-```
-Changes to `static/` files auto-refresh the browser.
-
-## Browser Support
-
-Works on all modern browsers:
-- Chrome/Edge 63+
-- Firefox 55+
-- Safari 11+
-- Mobile browsers (iOS Safari, Chrome Mobile, etc.)
-
-## Performance
-
-- **Fast Startup**: ~100ms with Bun
-- **No Build Step**: Source code runs directly
-- **Efficient Messaging**: MessagePack reduces payload size by 50%
-- **Real-time Updates**: <50ms WebSocket latency
-- **Memory Efficient**: ~20MB typical usage
-
-## Troubleshooting
-
-**Port Already in Use**
-```bash
-PORT=3001 bunx gmgui
-```
-
-**Agent Won't Connect**
-- Verify agent endpoint is accessible
-- Check browser console for errors
-- Ensure agent is sending valid ACP messages
-
-**Files Not Uploading**
-- Check browser console for errors
-- Verify sufficient disk space available
-
-## Security
-
-- Path traversal protection on file uploads
-- WebSocket message validation
-- File upload restrictions
-- No sensitive data in logs
-
-## License
-
-MIT - Free to use, modify, and distribute
-
-## Need Help?
-
-Open an issue on GitHub: https://github.com/AnEntrypoint/gmgui/issues
-
----
-
-**Ready to manage multiple ACP agents?** Run this now:
-
-```bash
-curl -fsSL https://raw.githubusercontent.com/AnEntrypoint/gmgui/main/install.sh | bash
-```
-
-Then open http://localhost:3000/gm/ in your browser
-# Triggered npm publishing