agentgui 1.0.16 → 1.0.18

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,62 +33,80 @@ function findBinary(paths) {
   return null;
 }
 
-const RIPPLEUI_SYSTEM_PROMPT = `CRITICAL: ALWAYS respond with styled HTML using RippleUI components. This is a web-based chat interface that ONLY renders HTML beautifully. NEVER respond with plain text.
-
-FOR EVERY RESPONSE:
-1. Wrap your ENTIRE response in a container div with proper styling
-2. Use semantic HTML (h1-h6 for headings, p for paragraphs, ul/ol for lists)
-3. Format code in <pre><code> blocks with language class
-4. Use cards for organized information blocks
-5. Use alerts for important information
-6. Use tables for tabular data
-7. Style everything with Tailwind CSS classes
-
-RESPONSE STRUCTURE TEMPLATE:
+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-4">
-  <h2 class="text-2xl font-bold">Main Heading</h2>
-  <p class="text-gray-700">Introductory text here.</p>
-  
-  <div class="card bg-base-100 shadow-lg p-4">
-    <h3 class="text-lg font-semibold mb-2">Section Title</h3>
-    <p>Content goes here.</p>
+<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>
-  
-  <pre class="bg-base-200 p-4 rounded-lg overflow-x-auto"><code class="language-javascript">// Code example
-const example = () => { };</code></pre>
-  
-  <ul class="list-none space-y-2 ml-4">
-    <li class="p-2 bg-base-200 rounded">• Item one</li>
-    <li class="p-2 bg-base-200 rounded">• Item two</li>
+</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 REFERENCE:
-- Cards: <div class="card bg-base-100 shadow-lg p-6"><h3 class="font-bold">Title</h3><p>Content</p></div>
-- Alerts: <div class="alert alert-info"><span>Message</span></div>
-- Tables: <table class="table table-zebra"><thead><tr><th>Header</th></tr></thead><tbody><tr><td>Data</td></tr></tbody></table>
-- Badges: <span class="badge badge-primary">Label</span>
-- Code: <pre class="bg-base-200 p-4 rounded-lg overflow-x-auto"><code class="language-{lang}">{code}</code></pre>
-- Lists: <ul class="list-none space-y-2"><li class="p-2 bg-base-200 rounded">Item</li></ul>
-
-REQUIRED FOR ALL RESPONSES:
-✓ Wrap response in HTML (usually a div with space-y-4 for vertical spacing)
-✓ Use Tailwind classes: text-xl, font-bold, p-4, mb-3, rounded-lg, shadow, etc.
-✓ Always use proper semantic HTML tags
-✓ Format code blocks with language class for syntax highlighting
-✓ Use colors: bg-blue-50, text-gray-700, border-blue-200 for visual hierarchy
-✓ NEVER respond with raw text - ALWAYS wrap in HTML container
-
-EXAMPLES OF GOOD RESPONSES:
-- Questions: Wrap answer in a card with bold question and styled answer
-- Code: Use <pre><code> with language class
-- Lists: Use <ul> or <ol> with proper styling
-- Instructions: Use numbered or bulleted lists in cards
-- Explanations: Use cards for each concept, bold headings, clear spacing
-
-Remember: The user sees raw HTML output. Make it beautiful and readable.`;
+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() {

package/html-wrapper.js

@@ -0,0 +1,117 @@
+/**
+ * HTML Wrapper for Claude Responses
+ * Converts plain text/markdown responses into beautiful HTML
+ */
+
+export class HTMLWrapper {
+  /**
+   * Wrap plain text response in HTML with RippleUI styling
+   */
+  static wrapResponse(text) {
+    if (!text || typeof text !== 'string') return text;
+    
+    // If already HTML, return as-is
+    if (text.trim().startsWith('<')) return text;
+    
+    // Parse markdown-style text and convert to HTML
+    const lines = text.split('\n');
+    const html = this.parseMarkdownToHTML(lines);
+    
+    // Wrap in container
+    return `<div class="space-y-4 p-6 max-w-4xl">${html}</div>`;
+  }
+
+  static parseMarkdownToHTML(lines) {
+    let html = '';
+    let inCodeBlock = false;
+    let codeLanguage = 'text';
+    let codeContent = '';
+    let listItems = [];
+    let inList = false;
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+
+      // Code blocks
+      if (line.match(/^```(\w+)?$/)) {
+        if (!inCodeBlock) {
+          // Start code block
+          inCodeBlock = true;
+          codeLanguage = line.match(/```(\w+)?/)?.[1] || 'text';
+          codeContent = '';
+        } else {
+          // End code block
+          inCodeBlock = false;
+          html += `<pre class="bg-gray-900 text-white p-4 rounded-lg overflow-x-auto"><code class="language-${codeLanguage}">${this.escapeHtml(codeContent)}</code></pre>`;
+          codeContent = '';
+        }
+        continue;
+      }
+
+      if (inCodeBlock) {
+        codeContent += (codeContent ? '\n' : '') + line;
+        continue;
+      }
+
+      // Headings
+      if (line.match(/^#+\s/)) {
+        const level = line.match(/^#+/)[0].length;
+        const heading = line.replace(/^#+\s/, '');
+        html += `<h${level} class="text-${level === 1 ? '3xl' : level === 2 ? '2xl' : 'xl'} font-bold text-gray-900 mt-4">${this.escapeHtml(heading)}</h${level}>`;
+        continue;
+      }
+
+      // Lists
+      if (line.match(/^[-*•]\s/) || line.match(/^\d+\.\s/)) {
+        const itemText = line.replace(/^[-*•\d+.]\s+/, '');
+        if (!inList) {
+          inList = true;
+          listItems = [];
+        }
+        listItems.push(itemText);
+        continue;
+      } else if (inList && line.trim()) {
+        // End list
+        html += `<ul class="list-none space-y-2 ml-0"><li class="p-3 bg-gray-100 rounded border-l-4 border-blue-500">${listItems.map(item => `• ${this.escapeHtml(item)}`).join('</li><li class="p-3 bg-gray-100 rounded border-l-4 border-blue-500">')}</li></ul>`;
+        inList = false;
+        listItems = [];
+      }
+
+      // Empty lines
+      if (!line.trim()) {
+        if (!html.endsWith('</p>')) html += '<br>';
+        continue;
+      }
+
+      // Regular paragraphs
+      if (line.trim()) {
+        // Format inline markdown
+        let formatted = this.escapeHtml(line);
+        formatted = formatted.replace(/\*\*(.*?)\*\*/g, '<strong class="font-bold">$1</strong>');
+        formatted = formatted.replace(/\*(.*?)\*/g, '<em class="italic">$1</em>');
+        formatted = formatted.replace(/`([^`]+)`/g, '<code class="bg-gray-200 px-2 py-1 rounded font-mono text-sm">$1</code>');
+        
+        html += `<p class="text-gray-700 leading-relaxed">${formatted}</p>`;
+      }
+    }
+
+    // Close any remaining list
+    if (inList) {
+      html += `<ul class="list-none space-y-2 ml-0"><li class="p-3 bg-gray-100 rounded border-l-4 border-blue-500">${listItems.map(item => `• ${this.escapeHtml(item)}`).join('</li><li class="p-3 bg-gray-100 rounded border-l-4 border-blue-500">')}</li></ul>`;
+    }
+
+    return html;
+  }
+
+  static escapeHtml(text) {
+    if (typeof text !== 'string') return '';
+    return text
+      .replace(/&/g, '&amp;')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;')
+      .replace(/"/g, '&quot;')
+      .replace(/'/g, '&#039;');
+  }
+}
+
+export default HTMLWrapper;

package/package.json

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

package/server.js

@@ -8,6 +8,7 @@ import { execSync } from 'child_process';
 import { queries } from './database.js';
 import ACPConnection from './acp-launcher.js';
 import { ResponseFormatter } from './response-formatter.js';
+import { HTMLWrapper } from './html-wrapper.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const PORT = process.env.PORT || 3000;
@@ -337,7 +338,13 @@ async function processMessage(conversationId, messageId, sessionId, content, age
     const result = await conn.sendPrompt(content);
     conn.onUpdate = null;
 
-    const responseText = fullText || result?.result || (result?.stopReason ? `Completed: ${result.stopReason}` : 'No response.');
+    let responseText = fullText || result?.result || (result?.stopReason ? `Completed: ${result.stopReason}` : 'No response.');
+    
+    // Wrap response in HTML if it's not already
+    const isHTML = responseText.trim().startsWith('<');
+    if (!isHTML) {
+      responseText = HTMLWrapper.wrapResponse(responseText);
+    }
     
     // Segment and format the response for better display
     const segments = ResponseFormatter.segmentResponse(responseText);
@@ -348,12 +355,14 @@ async function processMessage(conversationId, messageId, sessionId, content, age
       blocks,
       segments,
       metadata,
-      updateChunks
+      updateChunks,
+      isHTML: true
     } : {
       text: responseText,
       segments,
       metadata,
-      updateChunks
+      updateChunks,
+      isHTML: true
     };
 
     const assistantMessage = queries.createMessage(conversationId, 'assistant', messageContent);