agentgui 1.0.38 → 1.0.40

package/CONVERSATION_DISPLAY_FIX.md

@@ -1,125 +0,0 @@
-# Conversation Display Issue
-
-## Problem
-Imported Claude Code conversations are not visible in the UI when opening the application, even though they exist in the database (83 conversations found).
-
-## Root Cause Analysis
-
-Possible issues:
-1. **Conversations not loading on page load** - fetchConversations() may fail silently
-2. **Rendering issue** - chatList element may not be rendering properly
-3. **CSS hiding** - Conversations may be present but hidden (display:none, opacity:0)
-4. **Empty state** - renderChatHistory() shows "No chats yet" because this.conversations is empty
-5. **Filter/agent selection** - Conversations filtered by agent selection not matching
-
-## Investigation Steps
-
-### Check 1: Network Request
-- Open browser DevTools (F12)
-- Network tab: Look for `/api/conversations` request
-- Should return 83 conversations with agent IDs
-
-### Check 2: Console Errors
-- Console tab: Look for any JavaScript errors
-- Look for "fetchConversations:" logs
-
-### Check 3: DOM Elements
-- Elements tab: Inspect #chatList
-- Check if it has children
-- Check CSS display property (should be visible)
-
-### Check 4: Data Binding
-- Console: `app.conversations.size` - should show 83
-- Console: `app.conversations` - should contain conversation objects
-
-## Solution Areas
-
-### Frontend (static/app.js)
-
-1. **Add logging to fetchConversations()**
-   - Log when fetch starts/completes
-   - Log number of conversations received
-   - Log any errors
-
-2. **Add logging to renderChatHistory()**
-   - Log conversations.size
-   - Log if condition triggers "No chats yet"
-
-3. **Force initial render**
-   - Ensure renderChatHistory() is called after fetchConversations()
-   - Add retry logic if conversations empty on first load
-
-### Server (server.js)
-
-1. **Verify /api/conversations endpoint**
-   - Check it returns all conversations
-   - Verify no filtering happening
-   - Check response format
-
-2. **Verify import endpoint**
-   - Check /api/import/claude-code works
-   - Ensure conversations are created with proper agentId
-
-## Implementation
-
-Add debug logging to identify where conversations are lost:
-
-```javascript
-async fetchConversations() {
-  try {
-    const res = await fetch(BASE_URL + '/api/conversations');
-    const data = await res.json();
-    console.log('fetchConversations response:', data);
-    console.log('Conversations count:', data.conversations?.length);
-    
-    if (data.conversations) {
-      this.conversations.clear();
-      data.conversations.forEach(c => {
-        console.log('Adding conversation:', c.id, c.title);
-        this.conversations.set(c.id, c);
-      });
-      console.log('Final conversations.size:', this.conversations.size);
-    }
-  } catch (e) {
-    console.error('fetchConversations error:', e);
-  }
-}
-
-renderChatHistory() {
-  const list = document.getElementById('chatList');
-  if (!list) {
-    console.error('chatList element not found!');
-    return;
-  }
-  
-  console.log('renderChatHistory - conversations.size:', this.conversations.size);
-  
-  if (this.conversations.size === 0) {
-    console.warn('No conversations to display');
-    list.innerHTML = '<p>No chats yet</p>';
-    return;
-  }
-  
-  // ... rest of rendering
-}
-```
-
-## Expected Behavior
-
-1. Page loads
-2. fetchConversations() retrieves 83 conversations from API
-3. conversations Map populated with all 83 items
-4. renderChatHistory() iterates over conversations
-5. Chat list displays 83 conversation items
-6. User can click to view any conversation
-
-## Testing
-
-```bash
-# Verify conversations in database
-curl http://localhost:9897/gm/api/conversations | python3 -m json.tool | grep -c '"id"'
-
-# Verify a conversation has messages (pick one)
-curl http://localhost:9897/gm/api/conversations/CONV_ID/messages
-```
-

package/DEBUG_GUIDE.md

@@ -1,136 +0,0 @@
-# Debug Guide - Conversation Display Issue
-
-## Problem
-Imported Claude Code conversations (83 total) are not visible in the chat list when the application loads, despite being stored in the database and returned by the API.
-
-## API Status - ✅ VERIFIED
-- Server is running on `http://localhost:9897`
-- API endpoint `/api/conversations` returns 83 conversations
-- Response structure is correct with proper ID, agentId, title, created_at, updated_at, status fields
-
-## Debug Logging Added
-We've added comprehensive debug logging to trace the initialization flow. The logging will help identify where conversations are being lost.
-
-### Enhanced Logging Points:
-1. **Init sequence** - Logs each step of initialization
-2. **fetchConversations** - Logs API request, response status, data received
-3. **renderAll** - Logs conversation count before rendering
-4. **renderChatHistory** - Logs final conversation count and whether empty state is shown
-
-## How to Debug
-
-### Step 1: Open the Application
-1. Open your web browser
-2. Navigate to: `http://localhost:9897/gm/`
-3. Press **F12** to open Developer Tools
-4. Go to the **Console** tab
-
-### Step 2: Look for Debug Logs
-Watch for logs starting with `[DEBUG]`. You should see:
-
-```
-[DEBUG] Init: Starting initialization
-[DEBUG] Init: Fetched home
-[DEBUG] Init: Fetched agents, count: X
-[DEBUG] Init: Auto-imported Claude Code conversations
-[DEBUG] fetchConversations: Starting fetch from http://localhost:9897/gm/api/conversations
-[DEBUG] fetchConversations: Response status: 200
-[DEBUG] fetchConversations response count: 83
-[DEBUG] fetchConversations response data: {...}
-[DEBUG] fetchConversations: Cleared conversations map
-[DEBUG] Loaded conversations, total: 83
-[DEBUG] First few conversation IDs: [...]
-[DEBUG] Init: Fetched conversations, count: 83
-[DEBUG] Init: About to renderAll with 83 conversations
-[DEBUG] renderAll: Called with 83 conversations
-[DEBUG] renderChatHistory - conversations.size: 83
-[DEBUG] renderChatHistory - sorted conversations count: 83
-[DEBUG] Init: renderAll completed
-```
-
-### Step 3: Analyze the Logs
-
-Check these specific values:
-
-| Log | Expected | Issue If Different |
-|-----|----------|-------------------|
-| `response count: 83` | 83 | API not returning conversations |
-| `Loaded conversations, total: 83` | 83 | Data not being added to map |
-| `About to renderAll with 83 conversations` | 83 | Conversations lost between fetch and render |
-| `renderChatHistory - conversations.size: 83` | 83 | Size changes between renderAll and renderChatHistory |
-| `No conversations to display - showing empty state` | Should NOT appear | renderChatHistory shows empty when size > 0 |
-
-### Step 4: Check Browser State
-In the Console, type:
-```javascript
-// Check if conversations were loaded into the app
-app.conversations.size
-
-// Check the actual conversations
-app.conversations
-
-// Check first conversation
-Array.from(app.conversations.values())[0]
-
-// Check if BASE_URL is correct
-BASE_URL
-```
-
-### Step 5: Check Network Tab
-1. Go to **Network** tab in DevTools
-2. Filter for `/api/conversations` request
-3. Check:
-   - Request Status: Should be 200
-   - Response body: Should contain array of 83 conversations
-   - Response headers: Should show correct content-type
-
-## Possible Issues and Solutions
-
-### Issue 1: API returns 0 conversations
-**Symptom**: `response count: 0`
-- Check: Is the database populated?
-- Command: `sqlite3 /config/workspace/agentgui/data/gmgui.db "SELECT COUNT(*) FROM conversations;"`
-- Fix: Import conversations or check database connection
-
-### Issue 2: API returns data but conversations.size is 0
-**Symptom**: `response count: 83` but `Loaded conversations, total: 0`
-- Likely cause: Data structure mismatch or forEach not working
-- Fix: Check if data.conversations is an array
-- Check: Are the conversation objects being created properly?
-
-### Issue 3: Conversations loaded but renderChatHistory shows empty
-**Symptom**: `About to renderAll with 83 conversations` but `No conversations to display`
-- Likely cause: Something clears conversations.map between renderAll and renderChatHistory
-- Check: Look for any handleSyncEvent calls that might clear or reset conversations
-- Fix: Add logging to sync event handlers
-
-### Issue 4: Conversations load but don't display in UI
-**Symptom**: All debug logs show 83 conversations, but chat list still shows "No chats yet"
-- Likely cause: CSS hiding, DOM structure issue, or rendering issue
-- Check: Look at HTML element with id="chatList" - is it hidden?
-- Check: Are chat items being created in the DOM?
-- Solution: Open Elements tab and expand chatList to see if items exist
-
-## Next Steps After Debugging
-
-1. **Identify the root cause** using the logs above
-2. **Document which log shows the problem**
-3. **Implement the appropriate fix**:
-   - If API issue: Fix server endpoint
-   - If data structure issue: Fix response parsing
-   - If sync issue: Fix sync event handlers
-   - If UI issue: Fix CSS or rendering logic
-4. **Verify fix** with the debug logs
-5. **Commit changes** to git
-
-## File Locations
-- Frontend code: `/config/workspace/agentgui/static/app.js`
-- Server code: `/config/workspace/agentgui/server.js`
-- Database: `/config/workspace/agentgui/data/gmgui.db`
-- API responses return from: `/api/conversations` endpoint in server.js
-
-## Important Notes
-- Hot reload is enabled for CSS/HTML/frontend JS
-- Debug logs will auto-reload in browser when app.js changes
-- Check DevTools console IMMEDIATELY after loading the page
-- Some logs may scroll off - use DevTools console filter to search for `[DEBUG]`

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)