agentgui 1.0.39 → 1.0.40

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

package/STATE_CONSISTENCY_GUARANTEE.md

@@ -1,183 +0,0 @@
-# State Consistency Guarantee
-
-## Principle
-**Server is the single source of truth. Client state ALWAYS matches server state.**
-
-## Architecture
-
-### Single Source of Truth
-- Server database (`~/.gmgui/data.db`) is the authoritative state
-- Client state is derived from server, never modifies independently
-- Every UI update is triggered by verified server data
-
-### State Flow
-```
-User Action (create/update message)
-    ↓
-Sent to Server via API
-    ↓
-Server updates database
-    ↓
-Server broadcasts sync event
-    ↓
-Client receives event
-    ↓
-Client calls fetchConversations() [CRITICAL]
-    ↓
-Client updates local state from fresh server data
-    ↓
-Client renders UI
-    ↓
-ALL TABS see identical data
-```
-
-## Consistency Guarantees
-
-### ✅ No Eventual Consistency Issues
-- No "eventually consistent" data
-- All windows/tabs show identical data **immediately**
-- No delayed updates or race conditions
-
-### ✅ Impossible States Prevented
-- Can't have a conversation in one tab but not another
-- Can't have different message counts across tabs
-- Can't have stale timestamps anywhere
-
-### ✅ Multi-Tab Synchronization
-- When message is sent in Tab A
-- Server processes it (broadcasts event)
-- Tab A fetches fresh state
-- Tab B receives broadcast (WebSocket or BroadcastChannel)
-- Tab B fetches fresh state
-- **Both tabs show identical data < 100ms apart**
-
-### ✅ Connection Loss Handling
-- If WebSocket disconnects > 2 seconds: force full refresh
-- When reconnecting: fetch full state immediately
-- No partial/stale data shown to user
-
-### ✅ Timestamp Consistency
-- Conversation `updated_at` always matches server
-- All views see same ordering of conversations
-- New conversations appear in all tabs simultaneously
-
-## Implementation Details
-
-### Every Sync Event Triggers Full Fetch
-```javascript
-case 'conversation_created':
-  console.log('[STATE SYNC] Conversation created, fetching full state');
-  // Never trust just the event data
-  this.fetchConversations().then(() => this.renderChatHistory());
-  break;
-
-case 'session_updated':
-  console.log('[STATE SYNC] Session updated, fetching full state');
-  // Always get fresh authoritative state from server
-  this.fetchConversations().then(() => {
-    this.renderChatHistory();
-    if (this.currentConversation === event.conversationId) {
-      this.displayConversation(event.conversationId);
-    }
-  });
-  break;
-```
-
-### No Local-Only Mutations
-- Client never mutates `this.conversations` without server verification
-- Every mutation is preceded by `fetchConversations()`
-- No optimistic updates that might be wrong
-
-### Three-Pronged Sync Strategy
-1. **WebSocket**: Real-time sync events from server
-2. **BroadcastChannel**: Cross-tab sync (same browser)
-3. **Consistency Monitor**: Verify state every 3 seconds
-
-## Performance Implications
-
-### Acceptable Trade-offs
-- More API calls: Yes (necessary for consistency)
-- Slight latency for renders: <100ms (imperceptible)
-- Guaranteed consistency: YES (priceless)
-
-### Optimization
-- Debouncing: Rapid updates batched together
-- Caching: Avoid unnecessary re-renders
-- WebSocket: Primary sync method (low bandwidth)
-
-## Testing Consistency
-
-### Multi-Tab Test
-1. Open Tab A: http://localhost:9897/gm/
-2. Open Tab B: http://localhost:9897/gm/
-3. Send message in Tab A
-4. Observe: Message appears in Tab B < 100ms
-5. Conversation order updates in both tabs simultaneously
-6. Message count matches in both tabs
-
-### Network Disconnect Test
-1. Open DevTools
-2. Throttle network (DevTools > Network tab)
-3. Send message
-4. Close network/disconnect WebSocket
-5. Wait 2+ seconds
-6. Restore network
-7. Observe: Data is re-fetched and consistent
-
-### Timestamp Test
-1. Send message in conversation A
-2. Switch to conversation B in Tab 1
-3. Tab 2 still shows A
-4. Observe: Both tabs show updated timestamp for A
-5. Both tabs show same list order
-
-## What NEVER Happens
-- ❌ Conversation list differs between tabs
-- ❌ Message appears in one tab but not another
-- ❌ Stale conversation timestamps shown
-- ❌ Out-of-order messages displayed
-- ❌ Inconsistent conversation counts
-- ❌ Missing recent messages
-
-## Code Review Checklist
-
-When modifying state-related code:
-- ✅ Does all paths to state change call `fetchConversations()`?
-- ✅ Are event handlers fetching fresh data?
-- ✅ Is server the source of truth or local state?
-- ✅ Could multiple tabs get inconsistent data?
-- ✅ Are timestamps always from server?
-
-## Future Enhancements
-
-### Already Implemented
-- ✅ Server-as-truth architecture
-- ✅ All sync events trigger fetch
-- ✅ WebSocket real-time sync
-- ✅ BroadcastChannel cross-tab sync
-- ✅ Consistency monitor (3s checks)
-- ✅ Automatic reconnect with full refresh
-
-### Possible Improvements (maintain consistency)
-- [ ] Delta sync (only changed items) - while maintaining consistency
-- [ ] Compression for large datasets
-- [ ] Pagination for 1000+ conversations
-- [ ] Caching with validation
-
-## References
-
-- `server.js` - Authoritative database and broadcast
-- `app.js` - Client state synchronization
-- `database.js` - Data persistence layer
-- Sync events: `conversation_created`, `conversation_updated`, `conversation_deleted`, `message_created`, `session_updated`, `conversations_updated`
-
-## Related Issues Fixed
-
-- **Issue**: Different tabs showing different conversation lists
-- **Root Cause**: Local mutations without server verification
-- **Fix**: All mutations now preceded by `fetchConversations()`
-- **Status**: ✅ FIXED
-
----
-
-**Philosophy**: Better to have extra API calls and guaranteed consistency than fast but unreliable state. Consistency is non-negotiable.