agentgui 1.0.695 → 1.0.696

package/CLAUDE.md

@@ -18,6 +18,8 @@ server.js              HTTP server + WebSocket + all API routes (raw http.create
 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/acp-server-machine.js  XState v5 machine per ACP tool: stopped/starting/running/crashed/restarting 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)
@@ -41,9 +43,28 @@ static/js/syntax-highlighter.js  Code syntax highlighting
 static/js/voice.js               Voice input/output
 static/js/features.js            View toggle, drag-drop upload, model progress indicator
 static/js/tools-manager.js       Tool install/update UI
+static/js/ws-machine.js          XState v5 WS connection machine: disconnected/connecting/connected/reconnecting
+static/js/conv-machine.js        XState v5 per-conversation UI machine: idle/streaming/queued
+static/lib/xstate.umd.min.js     XState v5 browser bundle (UMD, served locally from node_modules)
 static/templates/                 31 HTML template fragments for event rendering
 ```
 
+## XState State Machines
+
+XState v5 machines provide formal state tracking alongside (not replacing) the existing Map-based execution tracking. The machines are authoritative for state validation; the Maps remain as the operational data store.
+
+**Server machines** (ESM, `lib/`):
+- `execution-machine.js`: One actor per conversation. States: idle → streaming → draining (queue drain) → streaming → idle. Also rate_limited state. `execMachine.send(convId, event)` API. `conv.get` and `conv.full` WS responses include `executionState` field.
+- `acp-server-machine.js`: One actor per ACP tool (opencode/kilo/codex). States: stopped → starting → running ↔ crashed → restarting. Used by `acp-sdk-manager.js` to track health and drive restart backoff.
+
+**Client machines** (browser UMD, `static/js/`):
+- `ws-machine.js`: Wraps WebSocketManager. States: disconnected/connecting/connected/reconnecting. Actor accessible as `wsManager._wsActor`. State readable via `wsManager.connectionState`.
+- `conv-machine.js`: One actor per conversation. States: idle/streaming/queued. API exposed as `window.convMachineAPI`. All actors in `window.__convMachines` Map for debug.
+
+**XState browser loading**: UMD bundle at `static/lib/xstate.umd.min.js` (copied from `node_modules/xstate/dist/xstate.umd.min.js` during npm install). Loaded as `defer` script before ws-machine.js and conv-machine.js. Exposes `window.XState` global.
+
+**Integration pattern**: Machines augment existing state (Maps, Set, booleans). They receive events at the same points the Maps are mutated. Machine state does NOT replace Map checks in server logic — both run in parallel, machine is the formal model.
+
 ## Key Details
 
 - Express is used only for file upload (`/api/upload/:conversationId`) and fsbrowse file browser (`/files/:conversationId`). All other routes use raw `http.createServer` with manual routing.

package/lib/acp-sdk-manager.js

@@ -3,7 +3,8 @@ import path from 'path';
 import os from 'os';
 import fs from 'fs';
 import { fileURLToPath } from 'url';
-import pRetry, { AbortError } from 'p-retry';
+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, '..');
@@ -17,11 +18,10 @@ const ACP_TOOLS = [
 
 const HEALTH_INTERVAL_MS = 30000;
 const STARTUP_GRACE_MS = 5000;
-const MAX_RESTARTS = 10;
-const RESTART_WINDOW_MS = 300000;
 const IDLE_TIMEOUT_MS = 120000;
 
 const processes = new Map();
+const idleTimers = new Map();
 let healthTimer = null;
 let shuttingDown = false;
 
@@ -34,172 +34,174 @@ function resolveCommand(tool) {
   return { 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));
+}
+
+function clearIdleTimer(toolId) {
+  const t = idleTimers.get(toolId);
+  if (t) { clearTimeout(t); idleTimers.delete(toolId); }
+}
+
+function stopTool(toolId) {
+  const proc = processes.get(toolId);
+  if (!proc) return;
+  log(toolId + ' stopping');
+  clearIdleTimer(toolId);
+  try { proc.kill('SIGTERM'); } catch (_) {}
+  setTimeout(() => { try { proc.kill('SIGKILL'); } catch (_) {} }, 5000);
+  processes.delete(toolId);
+  acpMachine.send(toolId, { type: 'STOPPED' });
+}
+
 function startProcess(tool) {
   if (shuttingDown) return null;
-  const existing = processes.get(tool.id);
-  if (existing?.process && !existing.process.killed) return existing;
-
   const resolved = resolveCommand(tool);
-  const entry = {
-    id: tool.id,
-    port: tool.port,
-    startedAt: Date.now(),
-    lastUsed: Date.now(),
-    lastHealthCheck: 0,
-    healthy: false,
-    process: null,
-    pid: null,
-    restarts: [],
-    idleTimer: null,
-    providerInfo: null,
-    _stopping: false
-  };
-
+  let proc;
   try {
-    entry.process = spawn(resolved.bin, resolved.args, {
+    proc = spawn(resolved.bin, resolved.args, {
       stdio: ['ignore', 'pipe', 'pipe'],
-      detached: false
+      detached: false,
     });
-    entry.pid = entry.process.pid;
-
-    entry.process.on('close', (code) => {
-      entry.healthy = false;
-      if (shuttingDown || entry._stopping) return;
-      log(tool.id + ' exited code ' + code);
-      const window = Date.now() - RESTART_WINDOW_MS;
-      entry.restarts = entry.restarts.filter(t => t > window);
-      if (entry.restarts.length >= MAX_RESTARTS) { log(tool.id + ' max restarts reached'); return; }
-      const attempt = entry.restarts.length;
-      entry.restarts.push(Date.now());
-      const delay = Math.min(1000 * Math.pow(2, attempt), 30000);
-      setTimeout(() => { if (!shuttingDown) startProcess(tool); }, delay);
-    });
-
-    processes.set(tool.id, entry);
-    log(tool.id + ' started port ' + tool.port + ' pid ' + entry.pid);
-    setTimeout(() => checkHealth(tool.id), STARTUP_GRACE_MS);
-    resetIdleTimer(tool.id);
   } catch (err) {
     log(tool.id + ' spawn failed: ' + err.message);
+    acpMachine.send(tool.id, { type: 'CRASHED' });
+    scheduleRestart(tool);
+    return null;
   }
 
-  return entry;
-}
+  processes.set(tool.id, proc);
+  acpMachine.send(tool.id, { type: 'START' });
+  acpMachine.send(tool.id, { type: 'STARTED', process: proc, pid: proc.pid });
 
-function resetIdleTimer(toolId) {
-  const entry = processes.get(toolId);
-  if (!entry) return;
-  entry.lastUsed = Date.now();
-  if (entry.idleTimer) clearTimeout(entry.idleTimer);
-  entry.idleTimer = setTimeout(() => stopTool(toolId), IDLE_TIMEOUT_MS);
-}
+  log(tool.id + ' started port ' + tool.port + ' pid ' + proc.pid);
 
-function stopTool(toolId) {
-  const entry = processes.get(toolId);
-  if (!entry) return;
-  log(toolId + ' idle, stopping to free RAM');
-  entry._stopping = true;
-  if (entry.idleTimer) clearTimeout(entry.idleTimer);
-  try { entry.process.kill('SIGTERM'); } catch (_) {}
-  setTimeout(() => { try { entry.process.kill('SIGKILL'); } catch (_) {} }, 5000);
-  processes.delete(toolId);
+  proc.on('close', (code) => {
+    processes.delete(tool.id);
+    if (shuttingDown) return;
+    log(tool.id + ' exited code ' + code);
+    acpMachine.send(tool.id, { type: 'CRASHED' });
+    const snap = acpMachine.snapshot(tool.id);
+    if (snap?.value === 'stopped') { log(tool.id + ' max restarts reached'); return; }
+    scheduleRestart(tool);
+  });
+
+  setTimeout(() => checkHealth(tool.id, tool.port), STARTUP_GRACE_MS);
+  resetIdleTimer(tool.id);
+  return proc;
 }
 
-async function checkHealth(toolId) {
-  const entry = processes.get(toolId);
-  if (!entry || shuttingDown) return;
+function scheduleRestart(tool) {
+  if (shuttingDown) return;
+  const delay = acpMachine.getBackoffDelay(tool.id);
+  setTimeout(() => {
+    if (!shuttingDown) startProcess(tool);
+  }, delay);
+}
 
+async function checkHealth(toolId, port) {
+  if (shuttingDown) return;
+  const snap = acpMachine.snapshot(toolId);
+  if (!snap || snap.value === 'stopped' || snap.value === 'idle_stopping') return;
+  const p = port || ACP_TOOLS.find(t => t.id === toolId)?.port;
+  if (!p) return;
   try {
-    const res = await fetch('http://127.0.0.1:' + entry.port + '/provider', {
-      signal: AbortSignal.timeout(3000)
+    const res = await fetch('http://127.0.0.1:' + p + '/provider', {
+      signal: AbortSignal.timeout(3000),
     });
-    entry.healthy = res.ok;
     if (res.ok) {
-      entry.providerInfo = await res.json();
+      const providerInfo = await res.json();
+      acpMachine.send(toolId, { type: 'HEALTHY', providerInfo });
+    } else {
+      acpMachine.send(toolId, { type: 'UNHEALTHY' });
     }
   } catch (_) {
-    entry.healthy = false;
+    acpMachine.send(toolId, { type: 'UNHEALTHY' });
   }
-  entry.lastHealthCheck = Date.now();
 }
 
 export async function ensureRunning(agentId) {
   const tool = ACP_TOOLS.find(t => t.id === agentId);
   if (!tool) return null;
-  let entry = processes.get(agentId);
-  if (entry?.healthy) { resetIdleTimer(agentId); return entry.port; }
-  if (!entry || entry._stopping) {
-    entry = startProcess(tool);
-    if (!entry) return null;
+  if (acpMachine.isHealthy(agentId)) { resetIdleTimer(agentId); return tool.port; }
+  const snap = acpMachine.snapshot(agentId);
+  if (!snap || snap.value === 'stopped' || snap.value === 'crashed') {
+    startProcess(tool);
   }
-  try {
-    await pRetry(async () => {
-      if (shuttingDown) throw new AbortError('shutting down');
-      await checkHealth(agentId);
-      if (!processes.get(agentId)?.healthy) throw new Error('not healthy yet');
-    }, { retries: 20, minTimeout: 500, maxTimeout: 500, factor: 1 });
-    resetIdleTimer(agentId);
-    return tool.port;
-  } catch {
-    return null;
+  for (let i = 0; i < 20; i++) {
+    await new Promise(r => setTimeout(r, 500));
+    if (shuttingDown) return null;
+    if (acpMachine.isHealthy(agentId)) { resetIdleTimer(agentId); return tool.port; }
   }
+  return null;
 }
 
-export function touch(agentId) {
-  const entry = processes.get(agentId);
-  if (entry) resetIdleTimer(agentId);
-}
+export function touch(agentId) { resetIdleTimer(agentId); }
 
 export async function startAll() {
   log('ACP tools available (on-demand start)');
   healthTimer = setInterval(() => {
-    for (const [id] of processes) checkHealth(id);
+    for (const tool of ACP_TOOLS) {
+      const snap = acpMachine.snapshot(tool.id);
+      if (snap && (snap.value === 'running' || snap.value === 'starting')) {
+        checkHealth(tool.id, tool.port);
+      }
+    }
   }, HEALTH_INTERVAL_MS);
 }
 
 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, entry] of processes) {
-    if (entry.idleTimer) clearTimeout(entry.idleTimer);
-    log('stopping ' + id + ' pid ' + entry.pid);
+  for (const [id, proc] of processes) {
+    log('stopping ' + id + ' pid ' + proc.pid);
     kills.push(new Promise(resolve => {
-      const t = setTimeout(() => { try { entry.process.kill('SIGKILL'); } catch (_) {} resolve(); }, 5000);
-      entry.process.on('close', () => { clearTimeout(t); resolve(); });
-      try { entry.process.kill('SIGTERM'); } catch (_) {}
+      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');
 }
 
 export function getStatus() {
   return ACP_TOOLS.map(tool => {
-    const e = processes.get(tool.id);
+    const snap = acpMachine.snapshot(tool.id);
+    const ctx = snap?.context || {};
     return {
       id: tool.id,
       port: tool.port,
-      running: !!e,
-      healthy: e?.healthy || false,
-      pid: e?.pid,
-      uptime: e ? Date.now() - e.startedAt : 0,
-      restartCount: e?.restarts.length || 0,
-      idleMs: e ? Date.now() - e.lastUsed : 0,
-      providerInfo: e?.providerInfo || null,
+      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,
     };
   });
 }
 
 export function getPort(agentId) {
-  const e = processes.get(agentId);
-  return e?.healthy ? e.port : null;
+  return acpMachine.isHealthy(agentId) ? (ACP_TOOLS.find(t => t.id === agentId)?.port || null) : null;
 }
 
 export function getRunningPorts() {
   const ports = {};
-  for (const [id, e] of processes) if (e.healthy) ports[id] = e.port;
+  for (const tool of ACP_TOOLS) {
+    if (acpMachine.isHealthy(tool.id)) ports[tool.id] = tool.port;
+  }
   return ports;
 }
 
@@ -216,7 +218,7 @@ export async function queryModels(agentId) {
   if (!port) return [];
   try {
     const res = await fetch('http://127.0.0.1:' + port + '/models', {
-      signal: AbortSignal.timeout(3000)
+      signal: AbortSignal.timeout(3000),
     });
     if (!res.ok) return [];
     const data = await res.json();
@@ -225,6 +227,5 @@ export async function queryModels(agentId) {
 }
 
 export function isAvailable(agentId) {
-  const tool = ACP_TOOLS.find(t => t.id === agentId);
-  return !!tool;
+  return !!ACP_TOOLS.find(t => t.id === agentId);
 }

package/lib/acp-server-machine.js

@@ -0,0 +1,166 @@
+import { createMachine, createActor, assign } from 'xstate';
+
+const MAX_RESTARTS = 10;
+const RESTART_WINDOW_MS = 300000;
+
+function calcBackoff(restarts) {
+  return Math.min(1000 * Math.pow(2, restarts.length), 30000);
+}
+
+function purgeOldRestarts(restarts) {
+  const window = Date.now() - RESTART_WINDOW_MS;
+  return restarts.filter(t => t > window);
+}
+
+const machine = createMachine({
+  id: 'acp-server',
+  initial: 'stopped',
+  context: {
+    process: null,
+    pid: null,
+    healthy: false,
+    restarts: [],
+    lastHealthCheck: 0,
+    providerInfo: null,
+    startedAt: null,
+    lastUsed: null,
+    idleDeadline: null,
+  },
+  states: {
+    stopped: {
+      entry: assign({ process: null, pid: null, healthy: false }),
+      on: {
+        START: 'starting',
+      },
+    },
+    starting: {
+      entry: assign(({ event }) => ({
+        process: event.process || null,
+        pid: event.pid || null,
+        startedAt: Date.now(),
+        lastUsed: Date.now(),
+        healthy: false,
+      })),
+      on: {
+        HEALTHY: {
+          target: 'running',
+          actions: assign(({ event }) => ({
+            healthy: true,
+            lastHealthCheck: Date.now(),
+            providerInfo: event.providerInfo || null,
+          })),
+        },
+        CRASHED: 'crashed',
+        STOP: 'idle_stopping',
+      },
+    },
+    running: {
+      entry: assign({ healthy: true }),
+      on: {
+        UNHEALTHY: {
+          actions: assign({ healthy: false, lastHealthCheck: Date.now() }),
+        },
+        HEALTHY: {
+          actions: assign(({ event }) => ({
+            healthy: true,
+            lastHealthCheck: Date.now(),
+            providerInfo: event.providerInfo || null,
+          })),
+        },
+        TOUCH: {
+          actions: assign({ lastUsed: Date.now() }),
+        },
+        CRASHED: 'crashed',
+        STOP: 'idle_stopping',
+        IDLE_TIMEOUT: 'idle_stopping',
+      },
+    },
+    crashed: {
+      entry: assign({ healthy: false }),
+      always: [
+        {
+          guard: ({ context }) => {
+            const recent = purgeOldRestarts(context.restarts);
+            return recent.length >= MAX_RESTARTS;
+          },
+          target: 'stopped',
+        },
+        { target: 'restarting' },
+      ],
+    },
+    restarting: {
+      entry: assign(({ context }) => ({
+        restarts: [...purgeOldRestarts(context.restarts), Date.now()],
+        process: null,
+        pid: null,
+        healthy: false,
+      })),
+      on: {
+        STARTED: {
+          target: 'starting',
+          actions: assign(({ event }) => ({
+            process: event.process,
+            pid: event.pid,
+            startedAt: Date.now(),
+          })),
+        },
+        STOP: 'stopped',
+      },
+    },
+    idle_stopping: {
+      entry: assign({ healthy: false }),
+      on: {
+        STOPPED: {
+          target: 'stopped',
+          actions: assign({ process: null, pid: null }),
+        },
+      },
+    },
+  },
+});
+
+const actors = new Map();
+
+export function getOrCreate(toolId) {
+  if (actors.has(toolId)) return actors.get(toolId);
+  const actor = createActor(machine);
+  actor.start();
+  actors.set(toolId, actor);
+  return actor;
+}
+
+export function get(toolId) {
+  return actors.get(toolId) || null;
+}
+
+export function send(toolId, event) {
+  const actor = getOrCreate(toolId);
+  actor.send(event);
+  return actor.getSnapshot();
+}
+
+export function snapshot(toolId) {
+  const actor = actors.get(toolId);
+  return actor ? actor.getSnapshot() : null;
+}
+
+export function isRunning(toolId) {
+  const s = snapshot(toolId);
+  return s ? s.value === 'running' : false;
+}
+
+export function isHealthy(toolId) {
+  const s = snapshot(toolId);
+  return s ? (s.value === 'running' && s.context.healthy) : false;
+}
+
+export function getBackoffDelay(toolId) {
+  const s = snapshot(toolId);
+  if (!s) return 1000;
+  return calcBackoff(purgeOldRestarts(s.context.restarts));
+}
+
+export function stopAll() {
+  for (const [, actor] of actors) actor.stop();
+  actors.clear();
+}

package/lib/execution-machine.js

@@ -0,0 +1,147 @@
+import { createMachine, createActor, assign } from 'xstate';
+
+const machine = createMachine({
+  id: 'conv-execution',
+  initial: 'idle',
+  context: {
+    pid: null,
+    proc: null,
+    sessionId: null,
+    startTime: null,
+    lastActivity: null,
+    queue: [],
+    nextItem: null,
+  },
+  states: {
+    idle: {
+      entry: assign({ pid: null, proc: null, sessionId: null, nextItem: null }),
+      on: {
+        START: {
+          target: 'streaming',
+          actions: assign(({ event }) => ({
+            sessionId: event.sessionId,
+            startTime: Date.now(),
+            lastActivity: Date.now(),
+            pid: null,
+            proc: null,
+          })),
+        },
+      },
+    },
+    streaming: {
+      on: {
+        SET_PID: { actions: assign(({ event }) => ({ pid: event.pid, lastActivity: Date.now() })) },
+        SET_PROC: { actions: assign(({ event }) => ({ proc: event.proc, lastActivity: Date.now() })) },
+        ACTIVITY: { actions: assign({ lastActivity: Date.now() }) },
+        ENQUEUE: {
+          actions: assign(({ context, event }) => ({
+            queue: [...context.queue, event.item],
+          })),
+        },
+        COMPLETE: [
+          {
+            guard: ({ context }) => context.queue.length > 0,
+            target: 'draining',
+          },
+          { target: 'idle' },
+        ],
+        CANCEL: {
+          target: 'idle',
+          actions: assign({ queue: [] }),
+        },
+        RATE_LIMITED: {
+          target: 'rate_limited',
+          actions: assign(({ event }) => ({
+            rateLimitRetryAt: event.retryAt,
+            rateLimitCooldownMs: event.cooldownMs,
+            rateLimitRetryCount: event.retryCount,
+            rateLimitMessageId: event.messageId,
+            rateLimitContent: event.content,
+            rateLimitAgentId: event.agentId,
+            rateLimitModel: event.model,
+            rateLimitSubAgent: event.subAgent,
+          })),
+        },
+      },
+    },
+    rate_limited: {
+      on: {
+        RETRY: {
+          target: 'streaming',
+          actions: assign(({ event }) => ({
+            sessionId: event.sessionId,
+            startTime: Date.now(),
+            lastActivity: Date.now(),
+            pid: null,
+            proc: null,
+            rateLimitRetryAt: null,
+          })),
+        },
+        CANCEL: {
+          target: 'idle',
+          actions: assign({ queue: [] }),
+        },
+      },
+    },
+    draining: {
+      always: {
+        target: 'streaming',
+        actions: assign(({ context }) => {
+          const [next, ...rest] = context.queue;
+          return {
+            pid: null,
+            proc: null,
+            sessionId: null,
+            queue: rest,
+            nextItem: next,
+          };
+        }),
+      },
+    },
+  },
+});
+
+const actors = new Map();
+
+export function getOrCreate(convId) {
+  if (actors.has(convId)) return actors.get(convId);
+  const actor = createActor(machine);
+  actor.start();
+  actors.set(convId, actor);
+  return actor;
+}
+
+export function get(convId) {
+  return actors.get(convId) || null;
+}
+
+export function remove(convId) {
+  const actor = actors.get(convId);
+  if (actor) { actor.stop(); actors.delete(convId); }
+}
+
+export function snapshot(convId) {
+  const actor = actors.get(convId);
+  return actor ? actor.getSnapshot() : null;
+}
+
+export function isStreaming(convId) {
+  const s = snapshot(convId);
+  return s ? s.value === 'streaming' || s.value === 'rate_limited' : false;
+}
+
+export function getContext(convId) {
+  const s = snapshot(convId);
+  return s ? s.context : null;
+}
+
+export function send(convId, event) {
+  const actor = getOrCreate(convId);
+  actor.send(event);
+  return actor.getSnapshot();
+}
+
+export function stopAll() {
+  for (const [, actor] of actors) actor.stop();
+  actors.clear();
+}