agentgui 1.0.16 → 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,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/package.json

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