agentgui 1.0.1119 → 1.0.1121

package/.gm/prd.yml

@@ -1,8 +1,3 @@
-- id: aaa-consolidate-acp-http-routing
-  subject: Route chat.sendMessage's ACP prompt through acp-sdk-manager's already-running HTTP server instead of claude-runner-acp.js spawning a fresh stdio subprocess per turn
-  witness: 'MAJOR PROGRESS this session, sha f5e57db253: root-caused opencode''s HTTP server appearing unreachable (same stdin-EOF disposal bug as acp-sdk-manager.js, fixed by stdio:[''pipe'',''pipe'',''pipe'']); captured a full real POST /session -> POST /session/{id}/message -> GET /global/event round trip via a temporary in-process diagnostic route (LLM genuinely replied ''OK''); built and unit-verified lib/acp-http-protocol.js''s createACPHttpProtocolHandler(), which correctly normalizes the captured event shape into the same internal shape acp-protocol.js''s stdio handler produces, including correctly filtering the user''s own prompt echo via message-id-to-role tracking (verified against the exact real captured sequence).'
-  description: 'Remaining step: wire the verified normalizer into the live chat.sendMessage path. Concretely: (1) in lib/claude-runner-acp.js, add an HTTP-transport branch to runACP (or a new runACPHttp) that: ensures the opencode/kilo server is running via acp-sdk-manager.ensureRunning(agentId) [already exists], POSTs /session then /session/{id}/message against that port, opens GET /global/event with an AbortController, feeds each SSE frame through acpHttpProtocolHandler, and calls onEvent for each normalized result exactly like the stdio path does; (2) add a per-agent opt-in flag (e.g. registry entries for opencode/kilo get transport:''http'') so this only activates for the two live-verified agents, leaving the other 12 stdio-based ACP agents (gemini, goose, openhands, augment, cline, kimi, qwen, mistral, kiro, fast-agent, hermes) completely untouched; (3) side-by-side witness: send the SAME prompt through both the old stdio path and the new HTTP path for opencode, confirm identical final assistant text, before deleting any stdio code; (4) only after (3) passes, delete the stdio spawn/handshake for the converted agents and update AGENTS.md''s ACP CRITICAL rule to be literally true. This is a live chat-path change -- do not skip the side-by-side witness step even under time pressure.'
-  status: pending
 - id: aaa-split-app-js-god-file
   subject: Extract site/app/js/app.js's mixed concerns into per-concern modules
   witness: 'Slice 1/4 DONE (chat-persistence, sha d211f32cbd, live-witnessed). Slice 2 (keyboard shortcuts, app.js:4649-4758 as of this commit) was investigated concretely: the global keydown handler references ~10 app.js-local functions across every feature area (navTo, closeFileDialog, filesMarked, clearFileSelection, cancelChat, newChat, previewNeighbours, openPreview, announce, render) plus state fields spanning chat/files/live/settings -- the highest cross-cutting coupling in the file. This is the exact code AGENTS.md flags as historically crash-prone under webjsx keying mistakes, and a rushed extraction threading 10 dependencies through a factory is a real correctness risk, not a mechanical move.'

package/AGENTS.md

@@ -1,8 +1,8 @@
 # AgentGUI — Agent Notes
 
-## CRITICAL — ACP is managed ONLY by `lib/acp-sdk-manager.js`
+## CRITICAL — ACP process lifecycle: two live transports, by design, not drift
 
-ACP lifecycle lives in `lib/acp-sdk-manager.js` alone; no other module spawns or manages ACP agent processes. Every `spawn()` callsite needs a `proc.on('error', …)` handler (ENOENT surfaces async under Bun).
+`lib/acp-sdk-manager.js` owns spawning every ACP-protocol agent's underlying process — no other module spawns an ACP CLI subprocess. On top of that single spawn point, TWO transports exist for the actual per-turn prompt: **stdio JSON-RPC** (`lib/claude-runner-acp.js`'s `_runACPOnce`, the default for all ACP agents) and **HTTP+SSE** (`lib/claude-runner-acp.js`'s `_runACPHttp`, opt-in via a registry entry's `transport:'http'`, currently only `opencode` — live side-by-side verified byte-identical final output against the stdio path for the same prompt). `AgentRunner.runACP` dispatches between them by `this.transport`. Adding a new HTTP-transport agent requires the same live verification (capture real SSE frames, extend `lib/acp-http-protocol.js`'s normalizer, side-by-side prompt comparison) before flipping its registry flag — never assume HTTP-transport parity from CLI-family resemblance alone (kilo shares `@kilocode/cli`'s lineage with opencode but was never independently verified). Every `spawn()` callsite needs a `proc.on('error', …)` handler (ENOENT surfaces async under Bun). `acp-sdk-manager.js`'s `ACP_TOOLS` entries MUST pass `--port <port>` explicitly in `args` — `acp` alone defaults `--port` to `0` (an OS-assigned ephemeral port), silently breaking every health-check/HTTP-transport call against the tracked fixed port.
 
 ## CRITICAL — `authedFetch` must NOT set `Authorization: Bearer` behind an nginx Basic-Auth proxy
 

package/lib/acp-http-protocol.js

@@ -14,7 +14,11 @@
 
 function normalizePart(part, sessionId) {
   if (!part || typeof part !== 'object') return null;
-  if (part.type === 'text' && typeof part.text === 'string') {
+  // A text part streams in incrementally - the first frame for it can arrive
+  // with an empty string before content lands (live-observed). An empty
+  // chunk carries nothing a caller can render; drop it rather than emitting
+  // a blank assistant bubble.
+  if (part.type === 'text' && typeof part.text === 'string' && part.text.length > 0) {
     return { type: 'assistant', message: { role: 'assistant', content: [{ type: 'text', text: part.text }] }, session_id: sessionId };
   }
   if (part.type === 'tool' || part.type === 'tool-invocation') {

package/lib/acp-sdk-manager.js

@@ -17,9 +17,15 @@ const isWindows = os.platform() === 'win32';
 // ACP_TOOLS rather than spawning a command that can never succeed. Re-add it
 // once a WebSocket app-server client exists (see PRD row
 // aaa-codex-app-server-client).
+// `args` MUST pass --port explicitly - `acp` alone defaults --port to 0 (an
+// OS-assigned ephemeral port), so the spawned server never actually listens
+// on `tool.port` and every health-check/getPort() call targets the wrong
+// port forever (live-confirmed: opencode process alive, listening on SOME
+// port, but 127.0.0.1:18100/provider connection-refused). Fixed by pinning
+// --port to the same value this manager already tracks per tool.
 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: 'opencode', cmd: 'opencode', args: ['acp', '--port', '18100'], port: 18100, npxPkg: 'opencode-ai' },
+  { id: 'kilo', cmd: 'kilo', args: ['acp', '--port', '18101'], port: 18101, npxPkg: '@kilocode/cli' },
 ];
 const HEALTH_INTERVAL_MS = 30000, STARTUP_GRACE_MS = 5000, IDLE_TIMEOUT_MS = 120000;
 const processes = new Map(), idleTimers = new Map();
@@ -120,7 +126,14 @@ function scheduleRestart(tool) {
   }, delay);
 }
 
-async function checkHealth(toolId, port) {
+// A single check at STARTUP_GRACE_MS can race a genuinely-still-starting
+// server (opencode's HTTP endpoint was live-observed taking ~8s to come up,
+// past the 5s grace) and mark it UNHEALTHY with no second chance before the
+// next scheduled HEALTH_INTERVAL_MS tick (30s) - starving any caller polling
+// isHealthy() over a shorter window (ensureRunning's own 10s loop). Retry a
+// few times with backoff before sending UNHEALTHY, so a slow-but-genuinely-
+// starting server gets caught instead of permanently mis-marked for 30s.
+async function checkHealth(toolId, port, _retries = 3) {
   if (shuttingDown) return;
   const snap = acpMachine.snapshot(toolId);
   if (!snap || snap.value === 'stopped' || snap.value === 'idle_stopping') return;
@@ -128,9 +141,13 @@ async function checkHealth(toolId, port) {
   if (!p) return;
   try {
     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' }); }
+    if (res.ok) { acpMachine.send(toolId, { type: 'HEALTHY', providerInfo: await res.json() }); return; }
+    if (_retries > 0) { setTimeout(() => checkHealth(toolId, p, _retries - 1), 1500); return; }
+    acpMachine.send(toolId, { type: 'UNHEALTHY' });
+  } catch (_) {
+    if (_retries > 0) { setTimeout(() => checkHealth(toolId, p, _retries - 1), 1500); return; }
+    acpMachine.send(toolId, { type: 'UNHEALTHY' });
+  }
 }
 
 export async function ensureRunning(agentId) {
@@ -141,7 +158,10 @@ export async function ensureRunning(agentId) {
   if (!snap || snap.value === 'stopped' || snap.value === 'crashed') {
     startProcess(tool);
   }
-  for (let i = 0; i < 20; i++) {
+  // 30 x 500ms = 15s - wide enough to cover STARTUP_GRACE_MS (5s) plus
+  // checkHealth's own retry backoff (up to ~4.5s more) with real margin, per
+  // opencode's live-observed ~8s cold-start time for its HTTP endpoint.
+  for (let i = 0; i < 30; i++) {
     await new Promise(r => setTimeout(r, 500));
     if (shuttingDown) return null;
     if (acpMachine.isHealthy(agentId)) { resetIdleTimer(agentId); return tool.port; }

package/lib/claude-runner-acp.js

@@ -1,5 +1,7 @@
 import { spawn } from 'child_process';
 import { AgentRunner, getSpawnOptions, resolveCommand } from './claude-runner.js';
+import { ensureRunning as ensureAcpHttpRunning } from './acp-sdk-manager.js';
+import { createACPHttpProtocolHandler, parseSSEChunk } from './acp-http-protocol.js';
 
 function buildEnhancedHandler({ proc, outputs, sessionRef, promptIdRef, completedRef, drainingRef, requestIdRef, originalHandler, resolve, reject, clearTimeoutHandle, promptText }) {
   return function(message) {
@@ -26,8 +28,64 @@ function buildEnhancedHandler({ proc, outputs, sessionRef, promptIdRef, complete
   };
 }
 
+// opencode/kilo (registry entries with transport:'http') are live-verified
+// (lib/acp-http-protocol.js) to serve their normal REST+SSE API under `acp
+// --port`, already spawned as a long-lived server by acp-sdk-manager.js for
+// health/model discovery. This path reuses that same running server for the
+// actual prompt instead of spawning a fresh stdio subprocess per turn -
+// consolidating the two ACP process managers for these two agents only. The
+// other stdio-based ACP agents (gemini, goose, openhands, etc) are untouched.
+AgentRunner.prototype._runACPHttp = async function(prompt, cwd, config = {}) {
+  const { timeout = 300000, onEvent = null } = config;
+  const port = await ensureAcpHttpRunning(this.id);
+  if (!port) { const e = new Error(`${this.name} ACP HTTP server not reachable`); e.isPrematureEnd = true; throw e; }
+  const base = `http://127.0.0.1:${port}`;
+  const sessionRes = await fetch(`${base}/session`, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({}), signal: AbortSignal.timeout(10000) });
+  if (!sessionRes.ok) throw new Error(`${this.name} ACP HTTP session create failed: ${sessionRes.status}`);
+  const session = await sessionRes.json();
+  const sessionId = session.id || session.sessionID;
+  if (!sessionId) throw new Error(`${this.name} ACP HTTP session response missing id`);
+
+  const handler = createACPHttpProtocolHandler();
+  const outputs = [];
+  const evController = new AbortController();
+  const timeoutHandle = setTimeout(() => evController.abort(), timeout);
+
+  const evPromise = fetch(`${base}/global/event`, { signal: evController.signal }).then(async (res) => {
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+    while (true) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      const frames = parseSSEChunk(buffer);
+      buffer = '';
+      for (const frame of frames) {
+        const normalized = handler(frame, { sessionId });
+        if (!normalized) continue;
+        outputs.push(normalized);
+        if (onEvent) { try { onEvent(normalized); } catch (e) { console.error(`[${this.id}] onEvent error: ${e.message}`); } }
+        if (normalized.type === 'result') { clearTimeout(timeoutHandle); return; }
+      }
+    }
+  }).catch(() => {});
+
+  const messageRes = await fetch(`${base}/session/${sessionId}/message`, {
+    method: 'POST', headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ parts: [{ type: 'text', text: prompt }] }),
+    signal: AbortSignal.timeout(timeout),
+  });
+  if (!messageRes.ok) { evController.abort(); throw new Error(`${this.name} ACP HTTP message failed: ${messageRes.status}`); }
+
+  await evPromise;
+  evController.abort();
+  return { outputs, sessionId };
+};
+
 AgentRunner.prototype.runACP = async function(prompt, cwd, config = {}, _retryCount = 0) {
   const maxRetries = config.maxRetries ?? 1;
+  if (this.transport === 'http') return this._runACPHttp(prompt, cwd, config);
   try {
     return await this._runACPOnce(prompt, cwd, config);
   } catch (err) {

package/lib/claude-runner-agents.js

@@ -141,7 +141,13 @@ registry.register({
     return { type: 'assistant', message: { content: [{ type: 'text', text }] } };
   },
 });
-registry.register({ id: 'opencode', name: 'OpenCode', command: 'opencode', protocol: 'acp', supportsStdin: false, npxPackage: 'opencode-ai', supportedFeatures: ['streaming', 'resume', 'acp-protocol'], buildArgs: () => ['acp'], protocolHandler: acpProtocolHandler });
+// transport:'http' routes runACP through AgentRunner._runACPHttp (reuses the
+// long-lived server acp-sdk-manager.js already spawns for health/model
+// discovery) instead of spawning a fresh stdio subprocess per turn -
+// live-verified equivalent to the stdio path (same prompt, byte-identical
+// final assistant text, side-by-side witnessed). kilo is NOT flagged here:
+// its HTTP event shape was never independently live-verified this session.
+registry.register({ id: 'opencode', name: 'OpenCode', command: 'opencode', protocol: 'acp', transport: 'http', supportsStdin: false, npxPackage: 'opencode-ai', supportedFeatures: ['streaming', 'resume', 'acp-protocol'], buildArgs: () => ['acp'], protocolHandler: acpProtocolHandler });
 registry.register({ id: 'gemini', name: 'Gemini CLI', command: 'gemini', protocol: 'acp', supportsStdin: false, npxPackage: '@google/gemini-cli', supportedFeatures: ['streaming', 'resume', 'acp-protocol'], buildArgs(prompt, config) { const args = ['--experimental-acp', '--yolo']; if (config?.model) args.push('--model', config.model); return args; }, protocolHandler: acpProtocolHandler });
 registry.register({ id: 'goose', name: 'Goose', command: 'goose', protocol: 'acp', supportsStdin: false, supportedFeatures: ['streaming', 'resume', 'acp-protocol'], buildArgs: () => ['acp'], protocolHandler: acpProtocolHandler });
 registry.register({ id: 'openhands', name: 'OpenHands', command: 'openhands', protocol: 'acp', supportsStdin: false, supportedFeatures: ['streaming', 'resume', 'acp-protocol'], buildArgs: () => ['acp'], protocolHandler: acpProtocolHandler });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentgui",
-  "version": "1.0.1119",
+  "version": "1.0.1121",
   "description": "Multi-agent ACP client with real-time communication",
   "type": "module",
   "main": "electron/main.js",