agentgui 1.0.1118 → 1.0.1120

package/.gm/prd.yml

@@ -1,15 +1,10 @@
 - 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: 'Deep investigation this session established: (1) opencode acp --port serves REST+SSE (POST /session, POST /session/{id}/message, GET /event) -- LIVE confirmed via Explore agent''s GET /doc fetch. (2) This is a STRUCTURALLY DIFFERENT event shape than the stdio ACP JSON-RPC ''session/update'' notifications lib/acp-protocol.js''s acpProtocolHandler parses (opencode SSE emits ''session.updated''/''message.part.updated'' REST-shaped events, not ACP method=''session/update'' RPC notifications) -- consolidating requires a NEW event-normalizer for the SSE shape, not a reuse of acpProtocolHandler, and acpProtocolHandler is shared live-critical code for 14 other registered agents (gemini, goose, openhands, augment, cline, kimi, qwen, mistral, kiro, fast-agent, hermes, etc) so a wrong rewrite risks breaking all of them. (3) kilo''s exact SSE/event shape was NOT live-verified in this session (Bash tool backgrounding could not keep a kilo acp --port process alive across tool-call boundaries in this environment -- two attempts, both times the process was gone with zero log output on the next read).'
-  description: 'This row requires a dedicated focused session with a live, running opencode instance to iterate the SSE event-normalizer against real traffic (not guessable from static analysis) -- do NOT attempt a blind rewrite of claude-runner-acp.js''s runACP against unverified event-shape assumptions. Concrete next steps for that session: (1) spawn opencode acp --port in a way that survives across dispatches (e.g. via the gm skill''s exec_js/background-convert primitives, or a supervised child in server.js itself, rather than raw shell backgrounding), (2) POST /session + /session/{id}/message with a real prompt, (3) capture actual GET /event SSE frames, (4) write a NEW lib/acp-http-protocol.js normalizer mapping those frames to the same internal event shape acpProtocolHandler produces (assistant/tool_use/tool_result/result), (5) add an opt-in per-agent transport flag (e.g. tool.transport:''http-sse'') so opencode/kilo can migrate independently of the 12 other stdio-based ACP agents which must keep working unchanged, (6) only delete stdio spawn code for a given agent after its HTTP path is proven equivalent via side-by-side witness (same prompt, same final assistant text, over both transports).'
-  status: pending
-- id: aaa-codex-app-server-client
-  subject: Build a WebSocket app-server client for codex so Codex CLI is a genuinely working ACP-class agent again
-  witness: 'codex --help / codex app-server --help live output (this session): app-server exposes --remote ws://host:port style connections and its own --ws-auth capability-token/signed-bearer-token modes -- structurally different from the stdio JSON-RPC (claude-runner-acp.js) and HTTP-polling (acp-sdk-manager.js) transports this codebase already has clients for'
-  description: 'Implement lib/claude-runner-codex-appserver.js: spawn `codex app-server daemon` (or the correct non-daemon invocation per `codex app-server --help`), speak its WebSocket protocol (JSON-RPC-over-WS per the --remote ws:// contract, generate-ts/generate-json-schema subcommands can emit the exact schema), wire it into claude-runner-agents.js''s codex registration in place of the disabled acp stdio path, and into acp-sdk-manager.js if health/model discovery is meaningful for it. Read `codex app-server generate-json-schema` output first to get the real RPC method/param shapes rather than guessing.'
+  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 and committed (sha d211f32cbd): chat-persistence extracted to site/app/js/chat-persistence.js via createChatPersistence(state, helpers) factory, live-witnessed via browser verb round-tripping a seeded localStorage chat through reload with zero page errors. Established working pattern for remaining slices: factory function closing over the shared `state` object + helper functions, called once at app.js module load, destructured to the SAME local names so every existing call site is untouched.'
-  description: '3 slices remain, cut in this order (per the original extraction-contract row): (2) keyboard shortcuts (SHORTCUTS array line ~628 renumbered after slice 1''s ~70-line removal, + global keydown handler, closes over render()/navTo()/state.showShortcuts/gPending/arm-timers -- more coupled than persistence, verify the escape-ladder order documented in AGENTS.md still holds after the cut), (3) hash-routing (HASH_KEYS/readHash/buildHash/writeHash/navTo, closes over render()), (4) settings/history (largest remaining, ~900 lines, most view()-tree coupling -- do last). After each cut: node --check both files, restart live server, browser-witness hasApp:true + zero page/console errors + the specific behavior moved (e.g. shortcuts overlay opens on ''?'', hash round-trips on navTo), commit that ONE slice, then start the next -- never batch.'
+  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.'
+  description: 'Slice 2 (shortcuts) needs a dedicated pass: enumerate the full dependency list precisely (grep every identifier referenced inside the keydown handler + SHORTCUTS array + focusComposer/focusSearch/focusFilter), decide whether those ~10 functions move WITH the shortcuts module (turning it into a larger cut than ''just shortcuts'') or stay in app.js and get passed in (a large helpers object) -- this decision should be made deliberately, not improvised mid-edit. Slices 3 (hash-routing) and 4 (settings/history) still queued after. Do not attempt slice 2 without first re-reading the live current line numbers (they shift after every extraction) and re-running the same live-witness discipline (node --check, live browser reload+interaction witness, single-slice commit) slice 1 used.'
   status: pending

package/lib/acp-http-protocol.js

@@ -0,0 +1,95 @@
+// Normalizes opencode's REST+SSE event shape (POST /session, POST
+// /session/{id}/message, GET /global/event) into the SAME internal event
+// shape lib/acp-protocol.js's acpProtocolHandler produces for the stdio ACP
+// JSON-RPC transport (assistant/tool_use/tool_result/result), so a caller can
+// switch transports without caring which one produced the event.
+//
+// Live-captured event shapes this maps (opencode 1.2.15, acp --port, SSE
+// frames from GET /global/event during a real session/message round trip):
+//   {payload:{type:'message.part.updated', properties:{part:{type:'text',text,...}}}}
+//   {payload:{type:'message.part.updated', properties:{part:{type:'reasoning',text,...}}}}
+//   {payload:{type:'message.updated', properties:{info:{role,finish,...}}}}
+//   {payload:{type:'session.status', properties:{status:{type:'busy'|'idle'}}}}
+//   {payload:{type:'session.idle', properties:{...}}}
+
+function normalizePart(part, sessionId) {
+  if (!part || typeof part !== 'object') return null;
+  // 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') {
+    return {
+      type: 'assistant',
+      message: { role: 'assistant', content: [{ type: 'tool_use', id: part.id, name: part.tool || part.name || 'tool', input: part.input || part.args || {} }] },
+      session_id: sessionId,
+    };
+  }
+  // reasoning/step-start/step-finish parts carry no user-facing content in
+  // agentgui's chat surface today - dropped (return null), same as the stdio
+  // path drops ACP updates it doesn't recognize.
+  return null;
+}
+
+// A `message.part.updated` frame's `part` carries NO role of its own - live
+// capture confirmed the part's role lives on the earlier `message.updated`
+// frame for the SAME messageID (the prompt echo arrives as a role:"user"
+// message.updated immediately before its own message.part.updated). Each
+// createACPHttpProtocolHandler() call keeps its own messageId->role map so a
+// caller with one handler per session never leaks state across sessions.
+export function createACPHttpProtocolHandler() {
+  const roleByMessageId = new Map();
+
+  return function (frame, context) {
+    if (!frame || typeof frame !== 'object') return null;
+    const payload = frame.payload;
+    if (!payload || typeof payload !== 'object') return null;
+    const sid = context?.sessionId;
+
+    if (payload.type === 'message.updated') {
+      const info = payload.properties?.info;
+      if (!info) return null;
+      if (info.id) roleByMessageId.set(info.id, info.role);
+      if (info.role === 'assistant' && info.finish) {
+        return { type: 'result', result: '', stopReason: info.finish, usage: info.tokens ? { used: info.tokens.total } : undefined, session_id: info.sessionID || sid };
+      }
+      return null;
+    }
+
+    if (payload.type === 'message.part.updated') {
+      const part = payload.properties?.part;
+      if (!part) return null;
+      // The user's own prompt echoes back as a part on their own message -
+      // only forward parts belonging to an assistant-role message.
+      const role = part.messageID ? roleByMessageId.get(part.messageID) : undefined;
+      if (role === 'user') return null;
+      return normalizePart(part, sid);
+    }
+
+    if (payload.type === 'session.status' && payload.properties?.status?.type === 'error') {
+      return { type: 'error', error: payload.properties.status };
+    }
+
+    return null;
+  };
+}
+
+export const acpHttpProtocolHandler = createACPHttpProtocolHandler();
+
+// Parse one SSE "data: {...}\n\n" frame (or a raw chunk containing several)
+// into an array of parsed JSON payloads. opencode's /global/event stream
+// uses the standard `data: <json>\n\n` SSE framing (live-confirmed).
+export function parseSSEChunk(chunk) {
+  const out = [];
+  for (const block of chunk.split('\n\n')) {
+    const line = block.trim();
+    if (!line.startsWith('data:')) continue;
+    const jsonText = line.slice(5).trim();
+    if (!jsonText) continue;
+    try { out.push(JSON.parse(jsonText)); } catch { /* partial frame, skip */ }
+  }
+  return out;
+}

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/ws-handlers/agents.js

@@ -60,6 +60,30 @@ export function register(router, deps) {
     return { ok: !!ok };
   });
 
+  // TEMPORARY diagnostic route (aaa-consolidate-acp-http-routing): exercises
+  // AgentRunner.runACP's new transport:'http' branch through the server's own
+  // long-lived process (a one-shot exec_js dispatch's process dies with the
+  // dispatch, killing acp-sdk-manager's non-detached child opencode with it -
+  // this route proves the real production caller shape instead). Remove once
+  // the side-by-side stdio-vs-http witness passes and this row resolves.
+  router.handle('_diag.runAcpHttp', async (p) => {
+    const agent = registry.get(p?.id || 'opencode');
+    if (!agent) err(404, 'unknown agent');
+    const prevTransport = agent.transport;
+    agent.transport = p?.transport === 'stdio' ? undefined : 'http';
+    const events = [];
+    try {
+      const result = await agent.runACP(p?.prompt || 'reply with exactly the word PONG', process.cwd(), {
+        timeout: 40000, onEvent: (e) => events.push(e),
+      });
+      return { ok: true, result, events };
+    } catch (e) {
+      return { ok: false, error: e.message, events };
+    } finally {
+      agent.transport = prevTransport;
+    }
+  });
+
   router.handle('agent.subagents', async (p) => {
     if (!p.id) err(400, 'Missing agent id');
     if (p.id === 'claude-code' || p.id === 'cli-claude') {

package/package.json

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