agentgui 1.0.15 → 1.0.17

package/RECENT_UPDATES.md

@@ -0,0 +1,209 @@
+# 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/acp-launcher.js

@@ -33,19 +33,80 @@ function findBinary(paths) {
   return null;
 }
 
-const RIPPLEUI_SYSTEM_PROMPT = `ALWAYS respond with HTML using RippleUI components. The chat renders HTML. Use: cards (class='card'), alerts (class='alert alert-info'), tables (class='table table-zebra'), badges (class='badge badge-primary'), buttons (class='btn btn-primary'). Wrap all responses in styled HTML with Tailwind CSS utility classes for layout.
-
-RIPPLEUI COMPONENTS:
-Cards: <div class="card bg-base-100 shadow-lg p-6"><h2 class="text-xl font-bold mb-2">Title</h2><p>Content</p></div>
-Alerts: <div class="alert alert-info"><span>Message</span></div>
-Tables: <div class="overflow-x-auto"><table class="table table-zebra"><thead><tr><th>Col</th></tr></thead><tbody><tr><td>Val</td></tr></tbody></table></div>
-Badges: <span class="badge badge-primary">Tag</span>
-Buttons: <button class="btn btn-primary">Action</button>
-Code: <pre class="bg-base-200 p-4 rounded-lg overflow-x-auto"><code>code here</code></pre>
-Lists: <ul class="list-none space-y-2"><li class="p-3 bg-base-200 rounded-lg">Item</li></ul>
-
-Use Tailwind CSS utility classes for layout (flex, grid, gap-4, p-4, rounded, shadow).
-ALWAYS wrap responses in styled HTML. Never send plain unstyled text.`;
+const RIPPLEUI_SYSTEM_PROMPT = `CRITICAL INSTRUCTION: You are responding in a web-based HTML interface. EVERY response must be formatted as beautiful, styled HTML using RippleUI and Tailwind CSS. This is NOT a text-based interface - users see raw HTML rendered in their browser.
+
+YOUR RESPONSE FORMAT MUST BE:
+Wrap your ENTIRE response in a single HTML container with these elements:
+
+\`\`\`html
+<div class="space-y-4 p-6 max-w-4xl">
+  <!-- Main content goes here -->
+</div>
+\`\`\`
+
+STRUCTURE YOUR RESPONSES LIKE THIS:
+
+For questions/answers:
+\`\`\`html
+<div class="space-y-4 p-6">
+  <h2 class="text-2xl font-bold text-gray-900">Your Answer</h2>
+  <div class="card bg-blue-50 border-l-4 border-blue-500 p-4">
+    <p class="text-gray-700">Your detailed answer here</p>
+  </div>
+</div>
+\`\`\`
+
+For code:
+\`\`\`html
+<div class="space-y-4 p-6">
+  <h3 class="text-xl font-bold">Code Example</h3>
+  <pre class="bg-gray-900 text-white p-4 rounded-lg overflow-x-auto"><code>// Your code here
+function example() { }</code></pre>
+</div>
+\`\`\`
+
+For lists:
+\`\`\`html
+<div class="space-y-4 p-6">
+  <h3 class="text-xl font-bold">Items</h3>
+  <ul class="list-none space-y-2">
+    <li class="p-3 bg-gray-100 rounded border-l-4 border-gray-400">• Item one</li>
+    <li class="p-3 bg-gray-100 rounded border-l-4 border-gray-400">• Item two</li>
+  </ul>
+</div>
+\`\`\`
+
+COMPONENT LIBRARY:
+- Card: <div class="card bg-white shadow-lg p-6 rounded-lg"><h4 class="font-bold">Title</h4><p>Content</p></div>
+- Alert: <div class="alert bg-red-100 border-l-4 border-red-500 p-4"><span class="text-red-800">Warning message</span></div>
+- Success: <div class="alert bg-green-100 border-l-4 border-green-500 p-4"><span class="text-green-800">Success</span></div>
+- Table: <table class="w-full border-collapse border border-gray-300"><thead class="bg-gray-100"><tr><th class="p-2 text-left">Col</th></tr></thead><tbody><tr><td class="p-2 border border-gray-300">Data</td></tr></tbody></table>
+- Badge: <span class="inline-block bg-blue-500 text-white px-3 py-1 rounded-full text-sm">Label</span>
+- Code inline: <code class="bg-gray-200 px-2 py-1 rounded text-red-600 font-mono">code</code>
+
+MANDATORY RULES:
+✓ EVERY response MUST be wrapped in a div with class "space-y-4 p-6"
+✓ Use semantic HTML: <h1>-<h6>, <p>, <ul>, <ol>, <table>, <pre>
+✓ Always add Tailwind classes for styling: colors, padding, margins, rounded corners
+✓ Code blocks MUST use <pre><code> with language class like \`class="language-javascript"\`
+✓ NEVER send plain text without HTML wrapping
+✓ NEVER respond outside of HTML container
+✓ Use color classes: text-gray-700, bg-blue-50, border-blue-500
+✓ Make visual hierarchy clear: use different font sizes, colors, cards
+
+EXAMPLES OF COMPLETE RESPONSES:
+
+Example 1 - Answer:
+<div class="space-y-4 p-6"><h2 class="text-2xl font-bold">Explanation</h2><p class="text-gray-700">Here is the detailed explanation...</p></div>
+
+Example 2 - Code:
+<div class="space-y-4 p-6"><h3 class="text-xl font-bold">JavaScript Function</h3><pre class="bg-gray-900 text-white p-4 rounded overflow-x-auto"><code>const greet = () => console.log('Hello');</code></pre></div>
+
+Example 3 - Multiple sections:
+<div class="space-y-4 p-6"><h2 class="text-2xl font-bold">Topic</h2><div class="card bg-white shadow p-4"><h3 class="font-bold">Section 1</h3><p>Content here</p></div><div class="card bg-white shadow p-4"><h3 class="font-bold">Section 2</h3><p>More content</p></div></div>
+
+YOU MUST ALWAYS OUTPUT VALID, COMPLETE HTML.
+The user's interface shows YOUR HTML directly - make it beautiful, well-organized, and professional.`;
 
 export default class ACPConnection {
   constructor() {
@@ -255,13 +316,44 @@ export default class ACPConnection {
     return this.sendRequest('session/set_mode', { sessionId: this.sessionId, modeId });
   }
 
-  async injectSkills() {
+  async injectSkills(additionalContext = '') {
     if (this.printMode) return {};
-    return this.sendRequest('session/skill_inject', {
-      sessionId: this.sessionId,
-      skills: [],
-      notification: [{ type: 'text', text: RIPPLEUI_SYSTEM_PROMPT }]
-    }).catch(() => null);
+    
+    // Combine the system prompt with any additional context
+    const systemPrompt = additionalContext ? `${RIPPLEUI_SYSTEM_PROMPT}\n\n---\n\n${additionalContext}` : RIPPLEUI_SYSTEM_PROMPT;
+    
+    try {
+      const result = await this.sendRequest('session/skill_inject', {
+        sessionId: this.sessionId,
+        skills: [],
+        notification: [{ type: 'text', text: systemPrompt }]
+      });
+      return result;
+    } catch (e) {
+      // skill_inject may not be supported, try alternative methods
+      console.log(`[ACP] skill_inject failed (may not be supported): ${e.message}`);
+      return null;
+    }
+  }
+
+  /**
+   * Inject system prompt as initial context
+   */
+  async injectSystemContext() {
+    if (this.printMode) return {};
+    
+    // Some versions may need the system prompt sent as the first message context
+    try {
+      await this.sendRequest('session/context', {
+        sessionId: this.sessionId,
+        context: RIPPLEUI_SYSTEM_PROMPT,
+        role: 'system'
+      });
+      return { success: true };
+    } catch (e) {
+      // This method may not be supported, silently fail
+      return null;
+    }
   }
 
   async sendPrompt(prompt) {

package/hot-reload-manager.js

@@ -0,0 +1,186 @@
+/**
+ * Hot Reload Manager
+ * Enables live reloading of client code and graceful server restarts without losing connections
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+export class HotReloadManager {
+  constructor(staticDir, options = {}) {
+    this.staticDir = staticDir;
+    this.watchedFiles = new Map();
+    this.hotReloadClients = [];
+    this.debounceTimers = new Map();
+    this.debounceDelay = options.debounceDelay || 300;
+    this.enabled = options.enabled !== false;
+  }
+
+  /**
+   * Start watching files for changes
+   */
+  start() {
+    if (!this.enabled) return;
+    
+    try {
+      this.watchDirectory(this.staticDir);
+      console.log('[HotReload] Watching for changes:', this.staticDir);
+    } catch (e) {
+      console.error('[HotReload] Failed to start:', e.message);
+    }
+  }
+
+  /**
+   * Watch directory recursively
+   */
+  watchDirectory(dir) {
+    try {
+      const files = fs.readdirSync(dir, { withFileTypes: true });
+      
+      for (const file of files) {
+        const fullPath = path.join(dir, file.name);
+        
+        if (file.isDirectory()) {
+          this.watchDirectory(fullPath);
+        } else {
+          this.watchFile(fullPath);
+        }
+      }
+    } catch (e) {
+      console.error('[HotReload] Error watching directory:', e.message);
+    }
+  }
+
+  /**
+   * Watch individual file for changes
+   */
+  watchFile(filePath) {
+    if (this.watchedFiles.has(filePath)) return;
+
+    try {
+      fs.watchFile(filePath, { interval: 100 }, (curr, prev) => {
+        if (curr.mtime > prev.mtime) {
+          this.onFileChanged(filePath);
+        }
+      });
+
+      this.watchedFiles.set(filePath, true);
+    } catch (e) {
+      console.error('[HotReload] Error watching file:', e.message);
+    }
+  }
+
+  /**
+   * Handle file change with debouncing
+   */
+  onFileChanged(filePath) {
+    // Clear existing timer for this file
+    if (this.debounceTimers.has(filePath)) {
+      clearTimeout(this.debounceTimers.get(filePath));
+    }
+
+    // Set new debounced timer
+    const timer = setTimeout(() => {
+      this.debounceTimers.delete(filePath);
+      const relPath = path.relative(this.staticDir, filePath);
+      
+      console.log(`[HotReload] File changed: ${relPath}`);
+      this.broadcastReload();
+    }, this.debounceDelay);
+
+    this.debounceTimers.set(filePath, timer);
+  }
+
+  /**
+   * Register a WebSocket client for hot reload
+   */
+  registerClient(ws) {
+    if (!this.enabled) return;
+    this.hotReloadClients.push(ws);
+    
+    ws.on('close', () => {
+      const idx = this.hotReloadClients.indexOf(ws);
+      if (idx > -1) this.hotReloadClients.splice(idx, 1);
+    });
+  }
+
+  /**
+   * Broadcast reload signal to all connected clients
+   */
+  broadcastReload() {
+    const message = JSON.stringify({ type: 'reload', timestamp: Date.now() });
+    
+    for (const ws of this.hotReloadClients) {
+      if (ws.readyState === 1) { // WebSocket.OPEN
+        try {
+          ws.send(message);
+        } catch (e) {
+          // Client may have disconnected
+        }
+      }
+    }
+  }
+
+  /**
+   * Cleanup watchers
+   */
+  stop() {
+    for (const filePath of this.watchedFiles.keys()) {
+      try {
+        fs.unwatchFile(filePath);
+      } catch (e) {}
+    }
+    
+    for (const timer of this.debounceTimers.values()) {
+      clearTimeout(timer);
+    }
+    
+    this.watchedFiles.clear();
+    this.debounceTimers.clear();
+    this.hotReloadClients = [];
+  }
+
+  /**
+   * Get HTML snippet to inject for hot reload
+   */
+  getClientScript(baseUrl = '') {
+    if (!this.enabled) return '';
+
+    return `
+<script>
+(function() {
+  const baseUrl = '${baseUrl}';
+  const ws = new WebSocket((location.protocol === 'https:' ? 'wss:' : 'ws:') + '//' + location.host + baseUrl + '/hot-reload');
+  
+  ws.onmessage = function(event) {
+    try {
+      const data = JSON.parse(event.data);
+      if (data.type === 'reload') {
+        console.log('[HotReload] Reloading page...');
+        location.reload();
+      }
+    } catch (e) {
+      console.error('[HotReload] Error parsing message:', e);
+    }
+  };
+  
+  ws.onerror = function(e) {
+    console.log('[HotReload] WebSocket error:', e);
+  };
+  
+  ws.onclose = function() {
+    console.log('[HotReload] Connection closed, will attempt to reconnect...');
+    setTimeout(function() {
+      location.reload();
+    }, 2000);
+  };
+})();
+</script>
+    `;
+  }
+}
+
+export default HotReloadManager;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentgui",
-  "version": "1.0.15",
+  "version": "1.0.17",
   "description": "Multi-agent ACP client with real-time communication",
   "type": "module",
   "main": "server.js",

package/server.js

@@ -32,7 +32,9 @@ async function getACP(agentId, cwd) {
     await conn.initialize();
     await conn.newSession(cwd);
     await conn.setSessionMode('bypassPermissions');
-    await conn.injectSkills(['html_rendering', 'image_display', 'scrot', 'fs_access']);
+    // Inject system prompt to ensure HTML/RippleUI formatting
+    await conn.injectSkills();
+    await conn.injectSystemContext();
     acpPool.set(agentId, conn);
     console.log(`ACP connection ready for ${agentId} in ${cwd}`);
     return conn;

package/static/app.js

@@ -525,10 +525,15 @@ class GMGUIApp {
 
   looksLikeHtml(text) {
     const trimmed = text.trim();
+    // Check for HTML tags at the start
     if (/^<[a-z][\s\S]*>/i.test(trimmed)) return true;
-    if (/<\/(div|span|p|table|ul|ol|h[1-6]|section|article|header|footer|nav|main|aside|details|summary|figure|figcaption|blockquote|pre|code|a|strong|em|img|br|hr)>/i.test(trimmed)) return true;
+    // Check for closing tags of common HTML elements
+    if (/<\/(div|span|p|table|ul|ol|h[1-6]|section|article|header|footer|nav|main|aside|details|summary|figure|figcaption|blockquote|pre|code|a|strong|em|img|br|hr|button|input|form|label)>/i.test(trimmed)) return true;
+    // Check for Tailwind/RippleUI classes (strong indicator of HTML)
+    if (/class\s*=\s*["'][^"']*(?:card|alert|badge|btn|table|space-y|p-\d+|text-|bg-|rounded|shadow)/.test(trimmed)) return true;
+    // Count HTML tags
     const tagCount = (trimmed.match(/<[a-z][^>]*>/gi) || []).length;
-    if (tagCount >= 3) return true;
+    if (tagCount >= 2) return true; // Lower threshold for HTML detection
     return false;
   }