agentgui 1.0.38 → 1.0.40

package/RECENT_UPDATES.md

@@ -1,209 +0,0 @@
-# AgentGUI Recent Updates
-
-## Overview
-AgentGUI has been significantly enhanced to use local Claude Code OAuth authentication and provide rich, metadata-aware response rendering.
-
-## Key Changes
-
-### 1. OAuth Authentication via Local Claude Code
-**File**: `acp-launcher.js`, `server.js`
-
-- **Binary Discovery**: Automatically finds `claude-code-acp` in common installation locations
-  - `/config/.gmweb/npm-global/bin/claude-code-acp`
-  - `~/.local/bin/claude-code-acp`
-  - Falls back to PATH if configured
-
-- **PATH Management**: Enhanced environment variable handling to ensure npm global binaries are discoverable
-
-- **Timeout Optimization**:
-  - Initialize: 4s → 10s
-  - Session creation: 4s → 30s
-  - Mode setting: 2s → 10s
-  - Handshake deadline: 5s → 60s
-
-**Benefits**: 
-- Uses existing Claude Code authentication
-- No additional API key setup needed
-- Seamless integration with system auth
-
-### 2. Response Segmentation & Metadata Extraction
-**Files**: `response-formatter.js`, `server.js`, `static/app.js`
-
-#### ResponseFormatter
-- Intelligent parsing of Claude responses into semantic units:
-  - Code blocks (with language detection)
-  - Headings (h1-h6)
-  - Text paragraphs
-  - Blockquotes
-  - Lists
-
-- Metadata extraction:
-  - Tool calls and function names
-  - Thinking/reasoning blocks
-  - Task references
-  - Subagent usage
-
-- Proper formatting with inline code highlighting
-
-#### Frontend Rendering
-- `renderSegment()`: Beautiful display of each segment type
-- `renderMetadata()`: Rich metadata sidebar with:
-  - Tools used (with code highlighting)
-  - Thinking blocks (collapsible details element)
-  - Subagents employed
-  - Tasks referenced
-
-### 3. Rich HTML/RippleUI Responses
-**Files**: `acp-launcher.js`, `static/app.js`
-
-#### System Prompt Enhancement
-Comprehensive instruction set forcing Claude to respond with HTML:
-- RippleUI components (cards, alerts, tables, badges)
-- Tailwind CSS styling
-- Semantic HTML structure
-- Code block formatting with language hints
-- Never raw text - always wrapped HTML
-
-#### HTML Detection Improvement
-- Detects HTML by tags, structure, AND Tailwind classes
-- Lower tag count threshold for detection (2 vs 3)
-- Better recognition of styled components
-
-### 4. Professional CSS Styling
-**File**: `static/styles.css`
-
-Added comprehensive styling for:
-- Code blocks with language-specific colors
-- Inline code with syntax highlighting
-- Markdown formatting (bold, italic, code)
-- Collapsible thinking blocks
-- Metadata sections with visual hierarchy
-- Print-friendly styles
-- Dark mode support
-
-### 5. Hot Reload Infrastructure
-**File**: `hot-reload-manager.js`
-
-Prepared for hot reloading:
-- File watching with debouncing
-- WebSocket-based reload signaling
-- Graceful client-side reloading
-- Ready for future implementation
-
-## System Architecture
-
-### Ports
-- Production: **9897** (via system startup)
-- Development: **3000** (via `npm start`)
-
-### Request Flow
-```
-User Message
-    ↓
-API endpoint (/api/conversations/:id/messages)
-    ↓
-Server (processMessage)
-    ↓
-getACP() - Gets or creates connection
-    ↓
-conn.sendPrompt() - Sends to Claude Code via ACP bridge
-    ↓
-ResponseFormatter.segmentResponse()
-    ↓
-Database storage with segments + metadata
-    ↓
-Frontend display with rich rendering
-```
-
-### Connection Management
-- ACP Pool: Maintains persistent connections per agent
-- OAuth via local Claude Code credentials
-- Graceful error handling and fallback
-- Automatic reconnection
-
-## Display Examples
-
-### Segmented Response
-Plain text becomes:
-```
-[Heading] Problem Analysis
-[Text] Explanation paragraph
-[Code] javascript function example
-[Metadata] Tools used, reasoning blocks
-```
-
-### Metadata Display
-- **Tools Used**: List of functions/tools called
-- **Reasoning**: Collapsible thinking process
-- **Subagents**: External agents employed  
-- **Tasks**: Itemized task list
-
-## Configuration
-
-### Environment Variables
-```bash
-PORT=9897              # Server port (default: 3000)
-BASE_URL=/gm          # Route prefix (default: /gm)
-HOT_RELOAD=false      # Disable hot reload (default: true)
-```
-
-### Database
-- Location: `~/.gmgui/data.db`
-- Persists conversations, messages, sessions
-- Auto-created on first run
-
-## Testing
-
-### Quick Start
-```bash
-npm start              # Start on port 3000
-PORT=9897 npm start   # Start on port 9897
-```
-
-### Test Endpoints
-```bash
-# Get agents
-curl http://localhost:3000/gm/api/agents
-
-# Create conversation
-curl -X POST http://localhost:3000/gm/api/conversations \
-  -H "Content-Type: application/json" \
-  -d '{"agentId": "claude-code", "title": "Test"}'
-
-# Send message
-curl -X POST http://localhost:3000/gm/api/conversations/{id}/messages \
-  -H "Content-Type: application/json" \
-  -d '{"agentId": "claude-code", "content": "Hello"}'
-
-# Get messages
-curl http://localhost:3000/gm/api/conversations/{id}/messages
-```
-
-## Future Enhancements
-
-1. **Full Hot Reloading**: Complete implementation of HotReloadManager
-2. **Streaming Responses**: Real-time message streaming to client
-3. **Task Tracking**: Enhanced task and subagent visualization
-4. **Export Functions**: Share/export conversations as HTML/PDF
-5. **Theme Customization**: Allow user-defined themes
-
-## Files Modified
-
-- `acp-launcher.js` - OAuth and timeout fixes, system prompt
-- `server.js` - Response segmentation, metadata extraction
-- `static/app.js` - Rich rendering, HTML detection
-- `static/styles.css` - Professional styling for all components
-- `response-formatter.js` - NEW: Response parsing and formatting
-- `hot-reload-manager.js` - NEW: Hot reload infrastructure
-
-## Git Commits
-
-1. **Fix OAuth Connection** - Binary discovery and PATH management
-2. **Increase ACP Timeouts** - Proper timeout values for connection establishment
-3. **Rich Response Formatting** - Segmentation and metadata rendering
-4. **Enforce HTML Responses** - System prompt and detection improvements
-
----
-
-**Last Updated**: February 3, 2026
-**Version**: 1.0.15

package/REMOTE_DEBUG_GUIDE.md

@@ -1,225 +0,0 @@
-# Remote Server Debugging Guide
-
-## Issue
-Conversations are not displaying in AgentGUI on remote server (https://buildesk.acc.l-inc.co.za/gm/), even though:
-- ✅ The application loads
-- ✅ The layout works
-- ✅ The sidebar is visible
-
-## Root Cause Analysis
-
-### On Local Server ✅
-- 83 conversations stored in `~/.gmgui/data.db`
-- 68 Claude Code conversations discovered in `~/.claude/projects/`
-- All 68 imported successfully
-- API returns conversations correctly
-- Frontend fetches and displays them
-
-### On Remote Server ❓
-- Unknown database state
-- Unknown Claude Code availability
-- Conversations showing as empty
-
-## Diagnostic Checklist
-
-### 1. Check if API is returning conversations
-
-In browser console:
-```javascript
-fetch('/gm/api/conversations')
-  .then(r => r.json())
-  .then(d => console.log('Conversations from API:', d.conversations?.length || 0))
-```
-
-If this returns 0: **Database is empty or API is failing**
-If this returns > 0: **API is working, issue is in frontend**
-
-### 2. Check frontend state
-
-In browser console:
-```javascript
-// Check if app was initialized
-console.log('app.conversations.size:', app.conversations.size);
-
-// If size is 0, check if fetchConversations was called
-console.log('API returned data:', app.conversations);
-
-// Force a refetch
-await app.fetchConversations();
-console.log('After refetch:', app.conversations.size);
-
-// If still 0, render to see debug info
-app.renderChatHistory();
-```
-
-### 3. Manually trigger import
-
-In browser console:
-```javascript
-// Try to import Claude Code conversations
-await fetch('/gm/api/import/claude-code')
-  .then(r => r.json())
-  .then(d => console.log('Import result:', d));
-```
-
-Then refetch:
-```javascript
-await app.fetchConversations();
-app.renderChatHistory();
-```
-
-### 4. Check Claude Code projects
-
-In terminal on remote server:
-```bash
-# Check if Claude Code directory exists
-ls -la ~/.claude/projects/
-
-# List all projects
-find ~/.claude/projects -name "sessions-index.json" 2>/dev/null | wc -l
-
-# Check first project
-ls -la ~/.claude/projects/ | head
-```
-
-If directory doesn't exist or is empty: **Claude Code hasn't been used on this server**
-
-### 5. Check database directly
-
-In terminal on remote server:
-```bash
-# Check database location (should be ~/.gmgui/data.db)
-ls -lh ~/.gmgui/data.db
-
-# Get conversation count (if Node/better-sqlite3 available)
-node -e "
-const DB = require('better-sqlite3');
-const db = new DB(process.env.HOME + '/.gmgui/data.db');
-const count = db.prepare('SELECT COUNT(*) as c FROM conversations').get();
-console.log('DB Conversations:', count.c);
-db.close();
-"
-```
-
-If file doesn't exist: **Database not initialized**
-If count is 0: **No conversations in database**
-
-## Solutions by Scenario
-
-### Scenario A: API returns 0, Database is empty
-**Problem:** No conversations to display (first time setup)
-**Solution:** 
-1. Import Claude Code conversations (if available)
-2. Or create new conversations
-3. Or import from JSON
-
-### Scenario B: API returns conversations, Frontend shows 0
-**Problem:** Frontend not fetching/displaying properly
-**Solution:**
-1. Check browser console for errors
-2. Check [DEBUG] logs
-3. Try `_debug.forceRefetch()` in console
-4. Check if BASE_URL is set correctly
-
-### Scenario C: Claude Code projects exist but no conversations
-**Problem:** Discovered conversations but not imported
-**Solution:**
-1. Open browser console
-2. Call import endpoint
-3. Call `app.fetchConversations()`
-4. Call `app.renderChatHistory()`
-
-### Scenario D: Conversations exist but frontend won't display
-**Problem:** Rendering issue
-**Solution:**
-1. Check HTML element `#chatList` exists
-2. Check CSS isn't hiding it
-3. Check for JavaScript errors
-4. Test `_debug.forceRefetch()`
-
-## What to Look For in Console
-
-When page loads, should see these logs:
-```
-[DEBUG] Init: Starting initialization
-[DEBUG] Init: BASE_URL = /gm
-[DEBUG] Init: Window width: XXXX
-[DEBUG] Init: Fetched agents, count: X
-[DEBUG] Init: Auto-imported Claude Code conversations
-[DEBUG] fetchConversations: Starting fetch from /gm/api/conversations
-[DEBUG] fetchConversations response count: X
-[DEBUG] Init: Fetched conversations, count: X
-[DEBUG] renderChatHistory - conversations.size: X
-```
-
-If you see `conversations.size: 0` anywhere, that's the issue.
-
-## Commands to Run in Browser Console
-
-```javascript
-// 1. Comprehensive status check
-{
-  api: await fetch('/gm/api/conversations').then(r => r.json()).then(d => d.conversations?.length),
-  app: app.conversations.size,
-  baseUrl: BASE_URL,
-  windowWidth: window.innerWidth,
-  chatList: !!document.getElementById('chatList'),
-  agents: app.agents.size
-}
-
-// 2. Force refetch and render
-await app.fetchConversations();
-app.renderChatHistory();
-window.app.conversations.size
-
-// 3. Check Claude Code availability
-await fetch('/gm/api/discover/claude-code').then(r => r.json()).then(d => console.log('Claude Code available:', d.discovered?.length))
-
-// 4. Manual import
-await fetch('/gm/api/import/claude-code').then(r => r.json()).then(d => console.log('Import:', d))
-```
-
-## Expected Behavior
-
-**After Fix:**
-1. Page loads
-2. Console shows [DEBUG] logs
-3. Page title shows "GMGUI (XX chats)"
-4. Sidebar shows conversation list
-5. Can click conversation to view it
-6. Can create new conversations
-7. Can import Claude Code conversations
-
-## If Still Stuck
-
-1. **Collect information:**
-   - Output of all console commands above
-   - Screenshot of browser console showing all [DEBUG] logs
-   - Output of `echo $HOME` on remote server
-   - Output of `ls -la ~/.claude/projects/` on remote server
-   - Output of `ls -la ~/.gmgui/` on remote server
-
-2. **Share these logs** for remote debugging
-
-3. **Try manual steps:**
-   - In console: `await _debug.forceRefetch()`
-   - Then: `app.renderChatHistory()`
-   - Screenshot result
-
-## Important Notes
-
-- `~/.gmgui/data.db` - AgentGUI database (stores conversations)
-- `~/.claude/projects/` - Claude Code storage (where conversations come from)
-- `/gm/api/conversations` - Endpoint to get all conversations
-- `/gm/api/discover/claude-code` - Find available Claude Code conversations
-- `/gm/api/import/claude-code` - Import Claude Code conversations to AgentGUI
-
-## Performance Tip
-
-If you have lots of conversations (100+), they might load slowly. You can paginate by checking:
-```javascript
-// Check how many are in the list element
-document.getElementById('chatList').children.length
-```
-
-If this is less than the API count, pagination is needed (future enhancement).

package/RESPONSE_ISSUES.md

@@ -1,157 +0,0 @@
-# Response Display Issues & Analysis
-
-## Issue 1: Combined Responses Without Separation
-
-Example from user feedback:
-```
-"Let me start by reading the PRD file to understand what tasks need to be completed.This is a large PRD with many unchecked items across 6 phases. Let me explore the codebase to understand the current state before planning implementation."
-```
-
-**Problem**: Two separate thoughts/steps are combined into one paragraph without proper separation:
-- "Let me start by reading..." (statement of intent)
-- "This is a large PRD..." (observation/analysis)
-
-### Root Cause Analysis
-
-The ResponseFormatter is parsing continuous text as a single segment if it doesn't have explicit markdown formatting. When Claude sends thinking or analysis steps, they may be:
-1. Separated by newlines in the actual response
-2. Separated by periods/punctuation but no blank lines
-3. Represented as separate agent messages but concatenated
-
-### Current Handling
-
-In `response-formatter.js`, the `parseResponse()` function treats consecutive text lines as one segment unless they have markdown markers (# ## etc).
-
-### Fix Needed
-
-1. **Detect step boundaries**: Recognize patterns like:
-   - "Let me..." → New action/step
-   - "I'll..." → New intent
-   - "Now..." → Transition
-   - "Here's..." → Result presentation
-   - "First..." / "Next..." → Sequential steps
-
-2. **Segment by semantic meaning**: Break text into logical paragraphs that represent:
-   - Planning/Analysis
-   - Investigation
-   - Results
-   - Explanations
-
-3. **Add visual separators**: Use cards or dividers between segments
-
-## Issue 2: Tags/JSON Not Rendering
-
-Types of content that should render specially:
-- `<thinking>` tags (Claude's reasoning)
-- `<tool_use>` tags (Tool call indicators)
-- `<result>` tags (Tool results)
-- Metadata blocks
-- Tool output
-
-Example that should render:
-```
-<thinking>
-This problem requires analysis
-</thinking>
-
-<tool_use>
-name: fs_access
-</tool_use>
-```
-
-## Issue 3: Metadata-Rich Content
-
-Elements that need special rendering:
-- Tool names (should be in code styling)
-- Function signatures (should be formatted as code)
-- API responses (should be formatted as JSON blocks)
-- Task lists (should be checkboxes or special formatting)
-- Subagent notifications (should have special styling)
-
-## Solution Architecture
-
-### Enhanced ResponseFormatter
-
-1. **XML Tag Detection**
-   ```javascript
-   detectXMLTags(text)  // Find <thinking>, <tool_use>, <result>, etc.
-   ```
-
-2. **Smart Segmentation**
-   ```javascript
-   segmentByIntent(text)  // Break on "Let me", "I'll", "Now", etc.
-   ```
-
-3. **Special Element Handling**
-   ```javascript
-   renderToolCall(toolData)
-   renderThinking(thoughtText)
-   renderResult(resultData)
-   ```
-
-### Frontend Enhancement
-
-1. **New Segment Types**
-   - `thinking` → Collapsible gray box
-   - `tool_call` → Highlighted with tool name
-   - `tool_result` → Code/result styling
-   - `analysis` → Regular text with better spacing
-   - `action` → Action statement styling
-
-2. **CSS Classes for Each**
-   ```css
-   .segment-thinking { background: #f9f9f9; border-left: 4px solid #999; }
-   .segment-tool_call { background: #f0f8ff; border-left: 4px solid #007acc; }
-   .segment-tool_result { background: #fff9e6; border-left: 4px solid #ffb300; }
-   .segment-action { font-weight: 500; color: #333; margin-top: 1.5rem; }
-   ```
-
-## Implementation Priority
-
-1. **High Priority** (Breaking issues)
-   - Fix response combining (split on semantic boundaries)
-   - Render `<thinking>` blocks separately
-   - Proper code block formatting
-
-2. **Medium Priority** (Display quality)
-   - Tool call highlighting
-   - Tool result formatting
-   - Better metadata display
-
-3. **Low Priority** (Enhancement)
-   - Animated reveals for collapsible sections
-   - Copy-to-clipboard for code blocks
-   - Export formatting
-
-## Files to Modify
-
-1. `response-formatter.js`
-   - Add XML tag detection
-   - Add intent-based segmentation
-   - Add special element parsing
-
-2. `static/app.js`
-   - Add `renderThinkingSegment()`
-   - Add `renderToolCallSegment()`
-   - Add `renderActionSegment()`
-
-3. `static/styles.css`
-   - Add styling for new segment types
-   - Add visual hierarchy
-
-## Testing Strategy
-
-Create test cases with responses like:
-```
-Let me analyze this requirement.
-
-Looking at the code structure, I see...
-
-Now I'll implement the solution.
-```
-
-Should produce:
-- Segment 1: "Let me analyze..." (action/planning)
-- Segment 2: "Looking at..." (analysis)
-- Segment 3: "Now I'll..." (implementation step)
-

package/SIDEBAR_FIX_SUMMARY.md

@@ -1,111 +0,0 @@
-# Conversation Display Fix - Root Cause and Solution
-
-## Problem
-Conversations were not visible in the AgentGUI on the remote server, even though:
-- ✅ API was returning 83 conversations correctly
-- ✅ Database had conversations stored
-- ✅ App.js initialization logic was sound
-
-## Root Cause
-**The sidebar was hidden on narrow/mobile screens due to CSS responsive design.**
-
-### CSS Behavior
-The responsive CSS (at `styles.css` line 1181) applies at screens < 768px:
-```css
-@media (max-width: 768px) {
-  .sidebar {
-    transform: translateX(-100%);  /* Hidden by default */
-    position: absolute;
-  }
-  .sidebar.open {
-    transform: translateX(0);      /* Only visible with .open class */
-  }
-}
-```
-
-### What Was Happening
-1. Page loads on narrow screen (or browser window narrower than 768px)
-2. Conversations ARE fetched and loaded into the app ✅
-3. renderChatHistory() IS called and renders conversation items ✅
-4. BUT: The sidebar is hidden with `transform: translateX(-100%)` by default
-5. Users can't see the conversation list because sidebar is off-screen
-
-## Solution Implemented
-Modified `init()` method in `static/app.js` to:
-
-1. **Detect screen width** on page load
-2. **On mobile/narrow screens (< 768px)**:
-   - Add the `open` class to sidebar
-   - This applies `transform: translateX(0)` which makes sidebar visible
-3. **On desktop screens (≥ 768px)**:
-   - Ensure sidebar doesn't have `open` class
-   - Desktop CSS keeps sidebar visible without the class
-
-```javascript
-const sidebar = document.getElementById('sidebar');
-if (window.innerWidth >= 768 && sidebar) {
-  sidebar.classList.remove('open'); // Desktop: always visible
-} else if (sidebar) {
-  sidebar.classList.add('open');    // Mobile: toggle visibility on
-}
-```
-
-## Additional Improvements Made
-
-### 1. Robust DOM Ready Check
-Wrapped app instantiation in `initializeApp()` function that:
-- Waits for `#chatList` element to be present
-- Retries every 100ms if element not found
-- Prevents errors if app loads before DOM
-
-### 2. Enhanced Error Logging
-Added detailed error checking in `fetchConversations()`:
-- Check HTTP response status
-- Log full error details and stack traces
-- Warn if conversations size becomes 0
-- Log response data for debugging
-
-### 3. Window Width Logging
-Added `[DEBUG] Init: Window width:` log to help diagnose screen size issues
-
-## Testing Checklist
-
-After deploying, verify:
-
-- [ ] Open on desktop (> 768px width) - sidebar should be visible with conversations
-- [ ] Open on mobile/narrow window (< 768px) - sidebar should be hidden but clickable via hamburger icon
-- [ ] Check browser console - should see `[DEBUG]` logs showing:
-  - Window width
-  - Conversation count loaded
-  - chatList innerHTML length
-- [ ] Page title should show "GMGUI (83 chats)" or similar
-- [ ] Clicking conversation item should load it
-- [ ] New conversations should appear immediately
-
-## Files Modified
-- `static/app.js` - Added sidebar visibility logic and improved initialization
-
-## Commit
-```
-fix: Ensure sidebar is visible and conversations display on all screen sizes
-
-- Made DOM ready check more robust with polling
-- Moved app instantiation to safe initialization function
-- Added window width logging to detect screen size issues
-- Auto-open sidebar on mobile/narrow screens (< 768px)
-- Ensure sidebar doesn't have 'open' class on desktop to prevent transform
-- Enhanced fetchConversations error logging and checks
-```
-
-## Browser Compatibility
-- Works on all screen sizes
-- Responsive design preserved
-- Mobile users can click hamburger icon to toggle sidebar
-- Desktop users see full sidebar
-
-## Next Steps if Issue Persists
-1. Check browser console for `[DEBUG]` logs
-2. Verify page title shows conversation count
-3. Check window width log to confirm screen size detection
-4. Verify `#chatList` element exists in DOM (F12 → Elements tab)
-5. Check if any JavaScript errors prevent initialization