agentgui 1.0.715 → 1.0.716

package/CLAUDE.md

@@ -16,17 +16,28 @@ Server starts on `http://localhost:3000`, redirects to `/gm/`.
 ```
 server.js              HTTP server + WebSocket + all API routes (raw http.createServer)
 database.js            SQLite setup (WAL mode), schema, query functions
-lib/claude-runner.js   Agent framework - spawns CLI processes, parses stream-json output
-lib/acp-manager.js     ACP tool lifecycle - auto-starts opencode/kilo HTTP servers, restart on crash
-lib/execution-machine.js   XState v5 machine per conversation: idle/streaming/draining/rate_limited states
+lib/claude-runner.js   Agent framework - AgentRunner/AgentRegistry classes, direct protocol execution
+lib/acp-runner.js      ACP JSON-RPC session lifecycle (init, session/new, prompt, drain)
+lib/acp-protocol.js    ACP session/update message normalization (shared by all ACP agents)
+lib/agent-registry-configs.js  Agent registration configs (Claude Code, OpenCode, Gemini, 10+ ACP agents)
+lib/agent-descriptors.js  Data-driven ACP agent descriptor builder
+lib/acp-sdk-manager.js ACP tool lifecycle - on-demand start opencode/kilo/codex, health checks, idle timeout
 lib/acp-server-machine.js  XState v5 machine per ACP tool: stopped/starting/running/crashed/restarting states
+lib/execution-machine.js   XState v5 machine per conversation: idle/streaming/draining/rate_limited states
 lib/ws-protocol.js     WebSocket RPC router (WsRouter class)
 lib/ws-optimizer.js    Per-client priority queue for WS event batching
-lib/ws-handlers-conv.js  Conversation/message/queue RPC handlers (~70 methods total)
+lib/ws-handlers-conv.js  Conversation CRUD, chunks, cancel, steer, inject RPC handlers
+lib/ws-handlers-msg.js   Message send/stream/list RPC handlers + execution start/enqueue
+lib/ws-handlers-queue.js Queue list/delete/update RPC handlers
 lib/ws-handlers-session.js  Session/agent RPC handlers
 lib/ws-handlers-run.js  Thread/run RPC handlers
-lib/ws-handlers-util.js  Utility RPC handlers (speech, auth, git, tools)
-lib/tool-manager.js    Tool detection, installation, version checking
+lib/ws-handlers-util.js  Utility RPC handlers (speech, auth, git, tools, voice)
+lib/ws-handlers-oauth.js  Gemini + Codex OAuth WS RPC handlers
+lib/ws-handlers-scripts.js  npm script run/stop WS RPC handlers
+lib/tool-manager.js    Tool facade - re-exports from tool-version, tool-spawner, tool-provisioner
+lib/tool-version.js    Version detection for CLI tools and plugins (data-driven framework paths)
+lib/tool-spawner.js    npm/bun install/update spawn with timeout and heartbeat
+lib/tool-provisioner.js  Auto-provisioning and periodic update checking
 lib/speech.js          Speech-to-text and text-to-speech via @huggingface/transformers
 bin/gmgui.cjs          CLI entry point (npx agentgui / bun x agentgui)
 static/index.html      Main HTML shell
@@ -169,7 +180,9 @@ Current tools:
 - `cli-agent-browser`: bin=`agent-browser`, pkg=`agent-browser` — uses `-V` flag (not `--version`) for version detection
 - `gm-cc`, `gm-oc`, `gm-gc`, `gm-kilo`, `gm-codex`: plugin tools
 
-**binMap gotcha:** `checkCliInstalled()` and `getCliVersion()` both have a `binMap` object. Any new CLI tool must be added to BOTH. `agent-browser` uses `-V` (not `--version`) — a `versionFlag` override handles this.
+**BIN_MAP gotcha:** `lib/tool-version.js` has a single `BIN_MAP` constant shared by `checkCliInstalled()` and `getCliVersion()`. Any new CLI tool must be added there. `agent-browser` uses `-V` (not `--version`) — a `versionFlag` override handles this.
+
+**Framework paths:** `lib/tool-version.js` uses a `FRAMEWORK_PATHS` data table instead of per-framework if/else chains. Each framework entry defines pluginDir, versionFile, parseVersion, and optional markerFile/fallbackInstalled. Adding a new framework means adding one entry to this table.
 
 **Background provisioning:** `autoProvision()` runs at startup, checks/installs missing tools (~10s). `startPeriodicUpdateCheck()` runs every 6 hours in background to check for updates. Both broadcast tool status via WebSocket so UI stays in sync.
 

package/lib/acp-protocol.js

@@ -0,0 +1,91 @@
+function normalizeContentBlock(content) {
+  if (typeof content === 'string') return { type: 'text', text: content };
+  if (content.type === 'text' && content.text) return content;
+  if (content.text) return { type: 'text', text: content.text };
+  if (content.content) {
+    const inner = content.content;
+    if (typeof inner === 'string') return { type: 'text', text: inner };
+    if (inner.type === 'text' && inner.text) return inner;
+    return { type: 'text', text: JSON.stringify(inner) };
+  }
+  return { type: 'text', text: JSON.stringify(content) };
+}
+
+function extractToolResultContent(updateContent) {
+  const parts = [];
+  if (!updateContent || !Array.isArray(updateContent)) return '';
+  for (const item of updateContent) {
+    if (item.type === 'content' && item.content) {
+      const inner = item.content;
+      if (inner.type === 'text' && inner.text) parts.push(inner.text);
+      else if (inner.type === 'resource' && inner.resource) parts.push(inner.resource.text || JSON.stringify(inner.resource));
+      else parts.push(JSON.stringify(inner));
+    } else if (item.type === 'diff') {
+      parts.push(item.oldText
+        ? `--- ${item.path}\n+++ ${item.path}\n${item.oldText}\n---\n${item.newText}`
+        : `+++ ${item.path}\n${item.newText}`);
+    } else if (item.type === 'terminal') {
+      parts.push(`[Terminal: ${item.terminalId}]`);
+    }
+  }
+  return parts.join('\n');
+}
+
+function handleSessionUpdate(params) {
+  const update = params.update || {};
+  const sid = params.sessionId;
+
+  if (update.sessionUpdate === 'agent_message_chunk' && update.content) {
+    return { type: 'assistant', message: { role: 'assistant', content: [normalizeContentBlock(update.content)] }, session_id: sid };
+  }
+
+  if (update.sessionUpdate === 'tool_call') {
+    return {
+      type: 'assistant',
+      message: { role: 'assistant', content: [{ type: 'tool_use', id: update.toolCallId, name: update.title || update.kind || 'tool', kind: update.kind || 'other', input: update.rawInput || update.input || {} }] },
+      session_id: sid
+    };
+  }
+
+  if (update.sessionUpdate === 'tool_call_update') {
+    const isError = update.status === 'failed';
+    const isCompleted = update.status === 'completed';
+    if (!isCompleted && !isError) {
+      return { type: 'tool_status', tool_use_id: update.toolCallId, status: update.status, kind: update.kind || 'other', locations: update.locations || [], session_id: sid };
+    }
+    const content = extractToolResultContent(update.content) || (update.rawOutput ? JSON.stringify(update.rawOutput) : '');
+    return { type: 'user', message: { role: 'user', content: [{ type: 'tool_result', tool_use_id: update.toolCallId, content, is_error: isError }] }, session_id: sid };
+  }
+
+  if (update.sessionUpdate === 'usage_update') {
+    return { type: 'usage', usage: { used: update.used, size: update.size, cost: update.cost }, session_id: sid };
+  }
+
+  if (update.sessionUpdate === 'plan') {
+    return { type: 'plan', entries: update.entries || [], session_id: sid };
+  }
+
+  return null;
+}
+
+export function createACPProtocolHandler() {
+  return function(message, context) {
+    if (!message || typeof message !== 'object') return null;
+
+    if (message.method === 'session/update') {
+      return handleSessionUpdate(message.params || {});
+    }
+
+    if (message.id && message.result && message.result.stopReason) {
+      return { type: 'result', result: '', stopReason: message.result.stopReason, usage: message.result.usage, session_id: context.sessionId };
+    }
+
+    if (message.method === 'error' || message.error) {
+      return { type: 'error', error: message.error || message.params || { message: 'Unknown error' } };
+    }
+
+    return null;
+  };
+}
+
+export const acpProtocolHandler = createACPProtocolHandler();

package/lib/acp-runner.js

@@ -0,0 +1,136 @@
+import { spawn } from 'child_process';
+import { spawnSync } from 'child_process';
+
+const isWindows = process.platform === 'win32';
+
+function getSpawnOptions(cwd) {
+  const options = { cwd, windowsHide: true };
+  if (isWindows) options.shell = true;
+  options.env = { ...process.env };
+  delete options.env.CLAUDECODE;
+  return options;
+}
+
+function resolveCommand(command, npxPackage) {
+  const whichCmd = isWindows ? 'where' : 'which';
+  const check = spawnSync(whichCmd, [command], { encoding: 'utf-8', timeout: 3000 });
+  if (check.status === 0 && (check.stdout || '').trim()) return { cmd: command, prefixArgs: [] };
+  if (npxPackage) {
+    if (spawnSync(whichCmd, ['npx'], { encoding: 'utf-8', timeout: 3000 }).status === 0) return { cmd: 'npx', prefixArgs: ['--yes', npxPackage] };
+    if (spawnSync(whichCmd, ['bun'], { encoding: 'utf-8', timeout: 3000 }).status === 0) return { cmd: 'bun', prefixArgs: ['x', npxPackage] };
+  }
+  return { cmd: command, prefixArgs: [] };
+}
+
+export function runACPOnce(agent, prompt, cwd, config = {}) {
+  return new Promise((resolve, reject) => {
+    const { timeout = 300000, onEvent = null, onError = null } = config;
+    let cmd, args;
+    if (agent.requiresAdapter && agent.adapterCommand) { cmd = agent.adapterCommand; args = [...agent.adapterArgs]; }
+    else { const resolved = resolveCommand(agent.command, agent.npxPackage); cmd = resolved.cmd; args = [...resolved.prefixArgs, ...agent.buildArgs(prompt, config)]; }
+    const spawnOpts = getSpawnOptions(cwd);
+    if (Object.keys(agent.spawnEnv).length > 0) spawnOpts.env = { ...spawnOpts.env, ...agent.spawnEnv };
+    const proc = spawn(cmd, args, spawnOpts);
+    if (config.onPid) { try { config.onPid(proc.pid); } catch (_) {} }
+    if (config.onProcess) { try { config.onProcess(proc); } catch (_) {} }
+    const outputs = [];
+    let timedOut = false, sessionId = null, requestId = 0, initialized = false, stderrText = '';
+    const timeoutHandle = setTimeout(() => { timedOut = true; proc.kill(); reject(new Error(`${agent.name} ACP timeout after ${timeout}ms`)); }, timeout);
+
+    const handleMessage = (message) => {
+      const normalized = agent.protocolHandler(message, { sessionId, initialized });
+      if (!normalized) { if (message.id === 1 && message.result) initialized = true; return; }
+      outputs.push(normalized);
+      if (normalized.session_id) sessionId = normalized.session_id;
+      if (onEvent) { try { onEvent(normalized); } catch (e) { console.error(`[${agent.id}] onEvent error: ${e.message}`); } }
+    };
+
+    proc.stdout.on('error', () => {});
+    proc.stderr.on('error', () => {});
+    let buffer = '';
+    proc.stdout.on('data', (chunk) => {
+      if (timedOut) return;
+      buffer += chunk.toString();
+      const lines = buffer.split('\n'); buffer = lines.pop();
+      for (const line of lines) { if (line.trim()) { try { handleMessage(JSON.parse(line)); } catch (e) { console.error(`[${agent.id}] JSON parse error:`, line.substring(0, 100)); } } }
+    });
+    proc.stderr.on('data', (chunk) => { const t = chunk.toString(); stderrText += t; console.error(`[${agent.id}] stderr:`, t); if (onError) { try { onError(t); } catch (_) {} } });
+
+    proc.stdin.on('error', () => {});
+    proc.stdin.write(JSON.stringify({ jsonrpc: '2.0', id: ++requestId, method: 'initialize', params: { protocolVersion: 1, clientCapabilities: { fs: { readTextFile: true, writeTextFile: true }, terminal: true }, clientInfo: { name: 'agentgui', title: 'AgentGUI', version: '1.0.0' } } }) + '\n');
+
+    let sessionCreated = false;
+    const checkInitAndSend = () => {
+      if (initialized && !sessionCreated) {
+        sessionCreated = true;
+        const sp = { cwd, mcpServers: [] };
+        if (config.model) sp.model = config.model;
+        if (config.subAgent) sp.agent = config.subAgent;
+        if (config.systemPrompt) sp.systemPrompt = config.systemPrompt;
+        proc.stdin.write(JSON.stringify({ jsonrpc: '2.0', id: ++requestId, method: 'session/new', params: sp }) + '\n');
+      } else if (!initialized) { setTimeout(checkInitAndSend, 100); }
+    };
+
+    let promptId = null, completed = false, draining = false;
+    const enhancedHandler = (message) => {
+      if (message.id && message.result && message.result.sessionId) {
+        sessionId = message.result.sessionId;
+        promptId = ++requestId;
+        proc.stdin.write(JSON.stringify({ jsonrpc: '2.0', id: promptId, method: 'session/prompt', params: { sessionId, prompt: [{ type: 'text', text: prompt }] } }) + '\n');
+        return;
+      }
+      if (message.id === promptId && message.result && message.result.stopReason) {
+        completed = true; draining = true; clearTimeout(timeoutHandle);
+        setTimeout(() => { draining = false; try { proc.kill(); } catch (_) {} resolve({ outputs, sessionId }); }, 1000);
+        return;
+      }
+      if (message.id === promptId && message.error) {
+        completed = true; draining = true; clearTimeout(timeoutHandle); handleMessage(message);
+        setTimeout(() => { draining = false; try { proc.kill(); } catch (_) {} reject(new Error(message.error.message || 'ACP prompt error')); }, 1000);
+        return;
+      }
+      handleMessage(message);
+    };
+
+    buffer = '';
+    proc.stdout.removeAllListeners('data');
+    proc.stdout.on('data', (chunk) => {
+      if (timedOut || (completed && !draining)) return;
+      buffer += chunk.toString();
+      const lines = buffer.split('\n'); buffer = lines.pop();
+      for (const line of lines) {
+        if (line.trim()) {
+          try { const m = JSON.parse(line); if (m.id === 1 && m.result) initialized = true; enhancedHandler(m); }
+          catch (e) { console.error(`[${agent.id}] JSON parse error:`, line.substring(0, 100)); }
+        }
+      }
+    });
+    setTimeout(checkInitAndSend, 200);
+
+    proc.on('close', (code) => {
+      clearTimeout(timeoutHandle);
+      if (timedOut || completed) return;
+      if (buffer.trim()) { try { const m = JSON.parse(buffer.trim()); if (m.id === 1 && m.result) initialized = true; enhancedHandler(m); } catch (_) {} }
+      if (code === 0 || outputs.length > 0) resolve({ outputs, sessionId });
+      else { const err = new Error(`${agent.name} ACP exited with code ${code}${stderrText ? `: ${stderrText.substring(0, 200)}` : ''}`); err.isPrematureEnd = true; err.exitCode = code; err.stderrText = stderrText; reject(err); }
+    });
+    proc.on('error', (err) => { clearTimeout(timeoutHandle); reject(err); });
+  });
+}
+
+export async function runACPWithRetry(agent, prompt, cwd, config = {}, _retryCount = 0) {
+  const maxRetries = config.maxRetries ?? 1;
+  try { return await runACPOnce(agent, prompt, cwd, config); }
+  catch (err) {
+    const isEmptyExit = err.isPrematureEnd || (err.message && err.message.includes('ACP exited with code'));
+    const isBinaryError = err.code === 'ENOENT' || (err.message && err.message.includes('ENOENT'));
+    if ((isEmptyExit || isBinaryError) && _retryCount < maxRetries) {
+      const delay = Math.min(1000 * Math.pow(2, _retryCount), 5000);
+      console.error(`[${agent.id}] ACP attempt ${_retryCount + 1} failed: ${err.message}. Retrying in ${delay}ms...`);
+      await new Promise(r => setTimeout(r, delay));
+      return runACPWithRetry(agent, prompt, cwd, config, _retryCount + 1);
+    }
+    if (err.isPrematureEnd) { const premErr = new Error(err.message); premErr.isPrematureEnd = true; premErr.exitCode = err.exitCode; premErr.stderrText = err.stderrText; throw premErr; }
+    throw err;
+  }
+}

package/lib/acp-sdk-manager.js

@@ -3,45 +3,31 @@ import path from 'path';
 import os from 'os';
 import fs from 'fs';
 import { fileURLToPath } from 'url';
-import { AbortError } from 'p-retry';
 import * as acpMachine from './acp-server-machine.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const projectRoot = path.resolve(__dirname, '..');
 const isWindows = os.platform() === 'win32';
-
 const ACP_TOOLS = [
   { id: 'opencode', cmd: 'opencode', args: ['acp'], port: 18100, npxPkg: 'opencode-ai' },
   { id: 'kilo', cmd: 'kilo', args: ['acp'], port: 18101, npxPkg: '@kilocode/cli' },
   { id: 'codex', cmd: 'codex', args: ['acp'], port: 18102, npxPkg: '@openai/codex' },
 ];
-
-const HEALTH_INTERVAL_MS = 30000;
-const STARTUP_GRACE_MS = 5000;
-const IDLE_TIMEOUT_MS = 120000;
-
-const processes = new Map();
-const idleTimers = new Map();
-let healthTimer = null;
-let shuttingDown = false;
-
+const HEALTH_INTERVAL_MS = 30000, STARTUP_GRACE_MS = 5000, IDLE_TIMEOUT_MS = 120000;
+const processes = new Map(), idleTimers = new Map();
+let healthTimer = null, shuttingDown = false;
 function log(msg) { console.log('[ACP-SDK] ' + msg); }
 
 function resolveCommand(tool) {
-  const ext = isWindows ? '.cmd' : '';
-  const localBin = path.join(projectRoot, 'node_modules', '.bin', tool.cmd + ext);
-  if (fs.existsSync(localBin)) return { bin: localBin, args: tool.args };
-  return { bin: tool.cmd, args: tool.args };
+  const localBin = path.join(projectRoot, 'node_modules', '.bin', tool.cmd + (isWindows ? '.cmd' : ''));
+  return fs.existsSync(localBin) ? { bin: localBin, args: tool.args } : { bin: tool.cmd, args: tool.args };
 }
 
 function resetIdleTimer(toolId) {
   acpMachine.send(toolId, { type: 'TOUCH' });
   const existing = idleTimers.get(toolId);
   if (existing) clearTimeout(existing);
-  idleTimers.set(toolId, setTimeout(() => {
-    acpMachine.send(toolId, { type: 'IDLE_TIMEOUT' });
-    stopTool(toolId);
-  }, IDLE_TIMEOUT_MS));
+  idleTimers.set(toolId, setTimeout(() => { acpMachine.send(toolId, { type: 'IDLE_TIMEOUT' }); stopTool(toolId); }, IDLE_TIMEOUT_MS));
 }
 
 function clearIdleTimer(toolId) {
@@ -112,18 +98,10 @@ async function checkHealth(toolId, port) {
   const p = port || ACP_TOOLS.find(t => t.id === toolId)?.port;
   if (!p) return;
   try {
-    const res = await fetch('http://127.0.0.1:' + p + '/provider', {
-      signal: AbortSignal.timeout(3000),
-    });
-    if (res.ok) {
-      const providerInfo = await res.json();
-      acpMachine.send(toolId, { type: 'HEALTHY', providerInfo });
-    } else {
-      acpMachine.send(toolId, { type: 'UNHEALTHY' });
-    }
-  } catch (_) {
-    acpMachine.send(toolId, { type: 'UNHEALTHY' });
-  }
+    const res = await fetch('http://127.0.0.1:' + p + '/provider', { signal: AbortSignal.timeout(3000) });
+    if (res.ok) acpMachine.send(toolId, { type: 'HEALTHY', providerInfo: await res.json() });
+    else acpMachine.send(toolId, { type: 'UNHEALTHY' });
+  } catch (_) { acpMachine.send(toolId, { type: 'UNHEALTHY' }); }
 }
 
 export async function ensureRunning(agentId) {
@@ -160,16 +138,14 @@ export async function stopAll() {
   shuttingDown = true;
   if (healthTimer) { clearInterval(healthTimer); healthTimer = null; }
   for (const toolId of idleTimers.keys()) clearIdleTimer(toolId);
-  const kills = [];
-  for (const [id, proc] of processes) {
+  await Promise.all([...processes].map(([id, proc]) => {
     log('stopping ' + id + ' pid ' + proc.pid);
-    kills.push(new Promise(resolve => {
+    return new Promise(resolve => {
       const t = setTimeout(() => { try { proc.kill('SIGKILL'); } catch (_) {} resolve(); }, 5000);
       proc.on('close', () => { clearTimeout(t); resolve(); });
       try { proc.kill('SIGTERM'); } catch (_) {}
-    }));
-  }
-  await Promise.all(kills);
+    });
+  }));
   processes.clear();
   acpMachine.stopAll();
   log('all stopped');
@@ -179,17 +155,7 @@ export function getStatus() {
   return ACP_TOOLS.map(tool => {
     const snap = acpMachine.snapshot(tool.id);
     const ctx = snap?.context || {};
-    return {
-      id: tool.id,
-      port: tool.port,
-      running: snap?.value === 'running' || snap?.value === 'starting',
-      healthy: ctx.healthy || false,
-      pid: ctx.pid,
-      uptime: ctx.startedAt ? Date.now() - ctx.startedAt : 0,
-      restartCount: ctx.restarts?.length || 0,
-      idleMs: ctx.lastUsed ? Date.now() - ctx.lastUsed : 0,
-      providerInfo: ctx.providerInfo || null,
-    };
+    return { id: tool.id, port: tool.port, running: snap?.value === 'running' || snap?.value === 'starting', healthy: ctx.healthy || false, pid: ctx.pid, uptime: ctx.startedAt ? Date.now() - ctx.startedAt : 0, restartCount: ctx.restarts?.length || 0, idleMs: ctx.lastUsed ? Date.now() - ctx.lastUsed : 0, providerInfo: ctx.providerInfo || null };
   });
 }
 
@@ -199,33 +165,23 @@ export function getPort(agentId) {
 
 export function getRunningPorts() {
   const ports = {};
-  for (const tool of ACP_TOOLS) {
-    if (acpMachine.isHealthy(tool.id)) ports[tool.id] = tool.port;
-  }
+  for (const tool of ACP_TOOLS) { if (acpMachine.isHealthy(tool.id)) ports[tool.id] = tool.port; }
   return ports;
 }
 
 export async function restart(agentId) {
   const tool = ACP_TOOLS.find(t => t.id === agentId);
   if (!tool) return false;
-  stopTool(agentId);
-  startProcess(tool);
-  return true;
+  stopTool(agentId); startProcess(tool); return true;
 }
 
 export async function queryModels(agentId) {
   const port = await ensureRunning(agentId);
   if (!port) return [];
   try {
-    const res = await fetch('http://127.0.0.1:' + port + '/models', {
-      signal: AbortSignal.timeout(3000),
-    });
-    if (!res.ok) return [];
-    const data = await res.json();
-    return data.models || [];
+    const res = await fetch('http://127.0.0.1:' + port + '/models', { signal: AbortSignal.timeout(3000) });
+    return res.ok ? ((await res.json()).models || []) : [];
   } catch (_) { return []; }
 }
 
-export function isAvailable(agentId) {
-  return !!ACP_TOOLS.find(t => t.id === agentId);
-}
+export function isAvailable(agentId) { return !!ACP_TOOLS.find(t => t.id === agentId); }