agentgui 1.0.689 → 1.0.691

package/acp-queries.js

@@ -1,182 +0,0 @@
-import { randomUUID } from 'crypto';
-const gid = (p) => `${p}-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
-const uuid = () => randomUUID();
-const iso = (t) => new Date(t).toISOString();
-const j = (o) => JSON.stringify(o);
-const jp = (s) => { try { return JSON.parse(s); } catch { return {}; } };
-
-export function createACPQueries(db, prep) {
-  return {
-    createThread(metadata = {}) {
-      const id = uuid(), now = Date.now();
-      prep('INSERT INTO conversations (id, agentId, title, created_at, updated_at, status, metadata) VALUES (?, ?, ?, ?, ?, ?, ?)').run(id, 'unknown', null, now, now, 'idle', j(metadata));
-      return { thread_id: id, created_at: iso(now), updated_at: iso(now), metadata, status: 'idle' };
-    },
-    getThread(tid) {
-      const r = prep('SELECT * FROM conversations WHERE id = ?').get(tid);
-      if (!r) return null;
-      return { thread_id: r.id, created_at: iso(r.created_at), updated_at: iso(r.updated_at), metadata: jp(r.metadata), status: r.status || 'idle' };
-    },
-    patchThread(tid, upd) {
-      const t = this.getThread(tid);
-      if (!t) throw new Error('Thread not found');
-      const now = Date.now(), meta = upd.metadata !== undefined ? upd.metadata : t.metadata, stat = upd.status !== undefined ? upd.status : t.status;
-      prep('UPDATE conversations SET metadata = ?, status = ?, updated_at = ? WHERE id = ?').run(j(meta), stat, now, tid);
-      return { thread_id: tid, created_at: t.created_at, updated_at: iso(now), metadata: meta, status: stat };
-    },
-    deleteThread(tid) {
-      const pr = prep('SELECT COUNT(*) as count FROM run_metadata WHERE thread_id = ? AND status = ?').get(tid, 'pending');
-      if (pr && pr.count > 0) throw new Error('Cannot delete thread with pending runs');
-      db.transaction(() => {
-        prep('DELETE FROM thread_states WHERE thread_id = ?').run(tid);
-        prep('DELETE FROM checkpoints WHERE thread_id = ?').run(tid);
-        prep('DELETE FROM run_metadata WHERE thread_id = ?').run(tid);
-        prep('DELETE FROM sessions WHERE conversationId = ?').run(tid);
-        prep('DELETE FROM messages WHERE conversationId = ?').run(tid);
-        prep('DELETE FROM chunks WHERE conversationId = ?').run(tid);
-        prep('DELETE FROM events WHERE conversationId = ?').run(tid);
-        prep('DELETE FROM conversations WHERE id = ?').run(tid);
-      })();
-      return true;
-    },
-    saveThreadState(tid, cid, sd) {
-      const id = gid('state'), now = Date.now();
-      prep('INSERT INTO thread_states (id, thread_id, checkpoint_id, state_data, created_at) VALUES (?, ?, ?, ?, ?)').run(id, tid, cid, j(sd), now);
-      return { id, thread_id: tid, checkpoint_id: cid, created_at: iso(now) };
-    },
-    getThreadState(tid, cid = null) {
-      const r = cid ? prep('SELECT * FROM thread_states WHERE thread_id = ? AND checkpoint_id = ? ORDER BY created_at DESC LIMIT 1').get(tid, cid) : prep('SELECT * FROM thread_states WHERE thread_id = ? ORDER BY created_at DESC LIMIT 1').get(tid);
-      if (!r) return null;
-      const sd = jp(r.state_data);
-      return { checkpoint: { checkpoint_id: r.checkpoint_id }, values: sd.values || {}, messages: sd.messages || [], metadata: sd.metadata || {} };
-    },
-    getThreadHistory(tid, lim = 50, off = 0) {
-      const tot = prep('SELECT COUNT(*) as count FROM thread_states WHERE thread_id = ?').get(tid).count;
-      const rows = prep('SELECT * FROM thread_states WHERE thread_id = ? ORDER BY created_at DESC LIMIT ? OFFSET ?').all(tid, lim, off);
-      const states = rows.map(r => { const sd = jp(r.state_data); return { checkpoint: { checkpoint_id: r.checkpoint_id }, values: sd.values || {}, messages: sd.messages || [], metadata: sd.metadata || {} }; });
-      return { states, total: tot, limit: lim, offset: off, hasMore: off + lim < tot };
-    },
-    copyThread(stid) {
-      const st = this.getThread(stid);
-      if (!st) throw new Error('Source thread not found');
-      const ntid = uuid(), now = Date.now();
-      db.transaction(() => {
-        prep('INSERT INTO conversations (id, agentId, title, created_at, updated_at, status, metadata, workingDirectory) SELECT ?, agentId, title || \' (copy)\', ?, ?, status, metadata, workingDirectory FROM conversations WHERE id = ?').run(ntid, now, now, stid);
-        const cps = prep('SELECT * FROM checkpoints WHERE thread_id = ? ORDER BY sequence ASC').all(stid);
-        cps.forEach(cp => prep('INSERT INTO checkpoints (id, thread_id, checkpoint_name, sequence, created_at) VALUES (?, ?, ?, ?, ?)').run(uuid(), ntid, cp.checkpoint_name, cp.sequence, now));
-        const sts = prep('SELECT * FROM thread_states WHERE thread_id = ? ORDER BY created_at ASC').all(stid);
-        sts.forEach(s => prep('INSERT INTO thread_states (id, thread_id, checkpoint_id, state_data, created_at) VALUES (?, ?, ?, ?, ?)').run(gid('state'), ntid, s.checkpoint_id, s.state_data, now));
-        const msgs = prep('SELECT * FROM messages WHERE conversationId = ? ORDER BY created_at ASC').all(stid);
-        msgs.forEach(m => prep('INSERT INTO messages (id, conversationId, role, content, created_at) VALUES (?, ?, ?, ?, ?)').run(gid('msg'), ntid, m.role, m.content, now));
-      })();
-      return this.getThread(ntid);
-    },
-    createCheckpoint(tid, name = null) {
-      const id = uuid(), now = Date.now();
-      const ms = prep('SELECT MAX(sequence) as max FROM checkpoints WHERE thread_id = ?').get(tid);
-      const seq = (ms?.max ?? -1) + 1;
-      prep('INSERT INTO checkpoints (id, thread_id, checkpoint_name, sequence, created_at) VALUES (?, ?, ?, ?, ?)').run(id, tid, name, seq, now);
-      return { checkpoint_id: id, thread_id: tid, checkpoint_name: name, sequence: seq, created_at: iso(now) };
-    },
-    getCheckpoint(cid) {
-      const r = prep('SELECT * FROM checkpoints WHERE id = ?').get(cid);
-      if (!r) return null;
-      return { checkpoint_id: r.id, thread_id: r.thread_id, checkpoint_name: r.checkpoint_name, sequence: r.sequence, created_at: iso(r.created_at) };
-    },
-    listCheckpoints(tid, lim = 50, off = 0) {
-      const tot = prep('SELECT COUNT(*) as count FROM checkpoints WHERE thread_id = ?').get(tid).count;
-      const rows = prep('SELECT * FROM checkpoints WHERE thread_id = ? ORDER BY sequence DESC LIMIT ? OFFSET ?').all(tid, lim, off);
-      const cps = rows.map(r => ({ checkpoint_id: r.id, thread_id: r.thread_id, checkpoint_name: r.checkpoint_name, sequence: r.sequence, created_at: iso(r.created_at) }));
-      return { checkpoints: cps, total: tot, limit: lim, offset: off, hasMore: off + lim < tot };
-    },
-    createRun(aid, tid = null, inp = null, cfg = null, wh = null) {
-      const rid = uuid(), now = Date.now(), mid = gid('runmeta');
-      let atid = tid;
-      if (!tid) {
-        atid = uuid();
-        prep('INSERT INTO conversations (id, agentId, title, created_at, updated_at, status, metadata) VALUES (?, ?, ?, ?, ?, ?, ?)').run(atid, aid, 'Stateless Run', now, now, 'idle', '{"stateless":true}');
-      }
-      prep('INSERT INTO sessions (id, conversationId, status, started_at, completed_at, response, error) VALUES (?, ?, ?, ?, ?, ?, ?)').run(rid, atid, 'pending', now, null, null, null);
-      prep('INSERT INTO run_metadata (id, run_id, thread_id, agent_id, status, input, config, webhook_url, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)').run(mid, rid, tid, aid, 'pending', inp ? j(inp) : null, cfg ? j(cfg) : null, wh, now, now);
-      return { run_id: rid, thread_id: tid, agent_id: aid, status: 'pending', created_at: iso(now), updated_at: iso(now) };
-    },
-    getRun(rid) {
-      const r = prep('SELECT * FROM run_metadata WHERE run_id = ?').get(rid);
-      if (!r) return null;
-      return { run_id: r.run_id, thread_id: r.thread_id, agent_id: r.agent_id, status: r.status, created_at: iso(r.created_at), updated_at: iso(r.updated_at) };
-    },
-    updateRunStatus(rid, stat) {
-      const now = Date.now();
-      prep('UPDATE run_metadata SET status = ?, updated_at = ? WHERE run_id = ?').run(stat, now, rid);
-      prep('UPDATE sessions SET status = ? WHERE id = ?').run(stat, rid);
-      return this.getRun(rid);
-    },
-    cancelRun(rid) {
-      const r = this.getRun(rid);
-      if (!r) throw new Error('Run not found');
-      if (['success', 'error', 'cancelled'].includes(r.status)) throw new Error('Run already completed or cancelled');
-      return this.updateRunStatus(rid, 'cancelled');
-    },
-    deleteRun(rid) {
-      db.transaction(() => {
-        prep('DELETE FROM chunks WHERE sessionId = ?').run(rid);
-        prep('DELETE FROM events WHERE sessionId = ?').run(rid);
-        prep('DELETE FROM run_metadata WHERE run_id = ?').run(rid);
-        prep('DELETE FROM sessions WHERE id = ?').run(rid);
-      })();
-      return true;
-    },
-    getThreadRuns(tid, lim = 50, off = 0) {
-      const tot = prep('SELECT COUNT(*) as count FROM run_metadata WHERE thread_id = ?').get(tid).count;
-      const rows = prep('SELECT * FROM run_metadata WHERE thread_id = ? ORDER BY created_at DESC LIMIT ? OFFSET ?').all(tid, lim, off);
-      const runs = rows.map(r => ({ run_id: r.run_id, thread_id: r.thread_id, agent_id: r.agent_id, status: r.status, created_at: iso(r.created_at), updated_at: iso(r.updated_at) }));
-      return { runs, total: tot, limit: lim, offset: off, hasMore: off + lim < tot };
-    },
-    searchThreads(flt = {}) {
-      const { metadata, status, dateRange, limit = 50, offset = 0 } = flt;
-      let wh = "status != 'deleted'", prm = [];
-      if (status) { wh += ' AND status = ?'; prm.push(status); }
-      if (dateRange?.start) { wh += ' AND created_at >= ?'; prm.push(new Date(dateRange.start).getTime()); }
-      if (dateRange?.end) { wh += ' AND created_at <= ?'; prm.push(new Date(dateRange.end).getTime()); }
-      if (metadata) { for (const [k, v] of Object.entries(metadata)) { wh += ' AND metadata LIKE ?'; prm.push(`%"${k}":"${v}"%`); } }
-      const tot = prep(`SELECT COUNT(*) as count FROM conversations WHERE ${wh}`).get(...prm).count;
-      const rows = prep(`SELECT * FROM conversations WHERE ${wh} ORDER BY updated_at DESC LIMIT ? OFFSET ?`).all(...prm, limit, offset);
-      const ths = rows.map(r => ({ thread_id: r.id, created_at: iso(r.created_at), updated_at: iso(r.updated_at), metadata: jp(r.metadata), status: r.status || 'idle' }));
-      return { threads: ths, total: tot, limit, offset, hasMore: offset + limit < tot };
-    },
-    searchAgents(agents, flt = {}) {
-      const { name, version, capabilities, limit = 50, offset = 0 } = flt;
-      let results = agents;
-      if (name) {
-        const n = name.toLowerCase();
-        results = results.filter(a => a.name.toLowerCase().includes(n) || a.id.toLowerCase().includes(n));
-      }
-      if (capabilities) {
-        results = results.filter(a => {
-          const desc = this.getAgentDescriptor ? this.getAgentDescriptor(a.id) : null;
-          if (!desc) return false;
-          const caps = desc.specs?.capabilities || {};
-          if (capabilities.streaming !== undefined && !caps.streaming) return false;
-          if (capabilities.threads !== undefined && caps.threads !== capabilities.threads) return false;
-          if (capabilities.interrupts !== undefined && caps.interrupts !== capabilities.interrupts) return false;
-          return true;
-        });
-      }
-      const total = results.length;
-      const paginated = results.slice(offset, offset + limit);
-      const agents_list = paginated.map(a => ({ agent_id: a.id, name: a.name, version: version || '1.0.0', path: a.path }));
-      return { agents: agents_list, total, limit, offset, hasMore: offset + limit < total };
-    },
-    searchRuns(flt = {}) {
-      const { agent_id, thread_id, status, limit = 50, offset = 0 } = flt;
-      let wh = '1=1', prm = [];
-      if (agent_id) { wh += ' AND agent_id = ?'; prm.push(agent_id); }
-      if (thread_id) { wh += ' AND thread_id = ?'; prm.push(thread_id); }
-      if (status) { wh += ' AND status = ?'; prm.push(status); }
-      const tot = prep(`SELECT COUNT(*) as count FROM run_metadata WHERE ${wh}`).get(...prm).count;
-      const rows = prep(`SELECT * FROM run_metadata WHERE ${wh} ORDER BY created_at DESC LIMIT ? OFFSET ?`).all(...prm, limit, offset);
-      const runs = rows.map(r => ({ run_id: r.run_id, thread_id: r.thread_id, agent_id: r.agent_id, status: r.status, created_at: iso(r.created_at), updated_at: iso(r.updated_at) }));
-      return { runs, total: tot, limit, offset, hasMore: offset + limit < tot };
-    }
-  };
-}

package/build-portable.js

@@ -1,197 +0,0 @@
-import fs from 'fs';
-import path from 'path';
-import os from 'os';
-import { fileURLToPath } from 'url';
-import { execSync } from 'child_process';
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const src = __dirname;
-const out = path.join(src, '..', 'wagentgui');
-const nm = path.join(src, 'node_modules');
-
-function log(msg) { console.log('[BUILD] ' + msg); }
-
-function rmrf(dir) {
-  if (!fs.existsSync(dir)) return;
-  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
-    const fp = path.join(dir, entry.name);
-    if (entry.isDirectory()) fs.rmSync(fp, { recursive: true, force: true });
-    else fs.unlinkSync(fp);
-  }
-}
-
-function copyDir(from, to) {
-  if (!fs.existsSync(from)) return;
-  fs.mkdirSync(to, { recursive: true });
-  for (const entry of fs.readdirSync(from, { withFileTypes: true })) {
-    const s = path.join(from, entry.name);
-    const d = path.join(to, entry.name);
-    if (entry.isDirectory()) copyDir(s, d);
-    else fs.copyFileSync(s, d);
-  }
-}
-
-function copyFile(from, to) {
-  fs.mkdirSync(path.dirname(to), { recursive: true });
-  fs.copyFileSync(from, to);
-}
-
-function sizeOf(dir) {
-  if (!fs.existsSync(dir)) return 0;
-  let sz = 0;
-  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
-    const fp = path.join(dir, e.name);
-    sz += e.isDirectory() ? sizeOf(fp) : fs.statSync(fp).size;
-  }
-  return sz;
-}
-
-log('Output: ' + out);
-rmrf(out);
-fs.mkdirSync(out, { recursive: true });
-
-log('Compiling Windows executable...');
-execSync(
-  `"${path.join(os.homedir(), '.bun', 'bin', 'bun')}" build --compile --target=bun-windows-x64 --outfile="${path.join(out, 'agentgui.exe')}" "${path.join(src, 'portable-entry.js')}"`,
-  { stdio: 'inherit', cwd: src }
-);
-
-const exeSize = fs.statSync(path.join(out, 'agentgui.exe')).size;
-const buf = Buffer.alloc(2);
-const fd = fs.openSync(path.join(out, 'agentgui.exe'), 'r');
-fs.readSync(fd, buf, 0, 2, 0);
-fs.closeSync(fd);
-if (buf[0] !== 0x4D || buf[1] !== 0x5A) throw new Error('Output exe is not a valid PE file (bad MZ magic)');
-log(`Exe compiled: ${Math.round(exeSize / 1024 / 1024)}MB (valid PE)`);
-
-log('Copying static files...');
-copyDir(path.join(src, 'static'), path.join(out, 'static'));
-
-const destNm = path.join(out, 'node_modules');
-
-function collectDeps(pkgName, visited = new Set()) {
-  if (visited.has(pkgName)) return;
-  visited.add(pkgName);
-  const pkgJson = path.join(nm, pkgName, 'package.json');
-  if (!fs.existsSync(pkgJson)) return;
-  const p = JSON.parse(fs.readFileSync(pkgJson, 'utf8'));
-  for (const dep of Object.keys(p.dependencies || {})) collectDeps(dep, visited);
-  return visited;
-}
-
-function copyPkg(pkgName) {
-  const src2 = path.join(nm, pkgName);
-  const dest2 = path.join(destNm, pkgName);
-  if (!fs.existsSync(src2) || fs.existsSync(dest2)) return;
-  copyDir(src2, dest2);
-}
-
-log('Copying runtime JS deps (express, fsbrowse, busboy, ws, better-sqlite3 trees)...');
-const runtimeRoots = ['express', 'fsbrowse', 'busboy', 'ws', 'better-sqlite3'];
-const allDeps = new Set();
-for (const root of runtimeRoots) collectDeps(root, allDeps);
-for (const dep of allDeps) copyPkg(dep);
-log(`Copied ${allDeps.size} runtime dep packages`);
-
-log('Copying @huggingface/transformers (dist + win32 natives)...');
-const hfSrc = path.join(nm, '@huggingface', 'transformers');
-const hfDest = path.join(destNm, '@huggingface', 'transformers');
-copyFile(path.join(hfSrc, 'package.json'), path.join(hfDest, 'package.json'));
-copyDir(path.join(hfSrc, 'dist'), path.join(hfDest, 'dist'));
-const hfNmSrc = path.join(hfSrc, 'node_modules');
-const hfNmDest = path.join(hfDest, 'node_modules');
-const onnxNestedSrc = path.join(hfNmSrc, 'onnxruntime-node');
-const onnxRootSrc = path.join(nm, 'onnxruntime-node');
-const hfOnnxSrc = fs.existsSync(onnxNestedSrc) ? onnxNestedSrc : onnxRootSrc;
-const hfOnnxDest = path.join(hfNmDest, 'onnxruntime-node');
-copyFile(path.join(hfOnnxSrc, 'package.json'), path.join(hfOnnxDest, 'package.json'));
-copyDir(path.join(hfOnnxSrc, 'dist'), path.join(hfOnnxDest, 'dist'));
-copyDir(path.join(hfOnnxSrc, 'lib'), path.join(hfOnnxDest, 'lib'));
-copyDir(path.join(hfOnnxSrc, 'bin', 'napi-v3', 'win32', 'x64'), path.join(hfOnnxDest, 'bin', 'napi-v3', 'win32', 'x64'));
-const onnxCommonNestedSrc = path.join(hfNmSrc, 'onnxruntime-common');
-const onnxCommonRootSrc = path.join(nm, 'onnxruntime-common');
-const onnxCommonSrc = fs.existsSync(onnxCommonNestedSrc) ? onnxCommonNestedSrc : onnxCommonRootSrc;
-copyDir(onnxCommonSrc, path.join(hfNmDest, 'onnxruntime-common'));
-
-log('Copying webtalk...');
-copyDir(path.join(nm, 'webtalk'), path.join(destNm, 'webtalk'));
-
-log('Copying audio-decode...');
-copyDir(path.join(nm, 'audio-decode'), path.join(destNm, 'audio-decode'));
-const audioDeps = new Set();
-collectDeps('audio-decode', audioDeps);
-for (const dep of audioDeps) copyPkg(dep);
-
-log('Copying ACP tools (opencode, kilo, gemini) for portable...');
-const acpNativeTools = [
-  { wrapper: 'opencode-ai', platformPrefix: 'opencode-windows-x64' },
-  { wrapper: '@kilocode/cli', platformPrefix: '@kilocode/cli-windows-x64' },
-];
-for (const tool of acpNativeTools) {
-  const wrapperSrc = path.join(nm, tool.wrapper);
-  if (fs.existsSync(wrapperSrc)) copyDir(wrapperSrc, path.join(destNm, tool.wrapper));
-  for (const suffix of ['', '-baseline']) {
-    const platPkg = tool.platformPrefix + suffix;
-    const platSrc = path.join(nm, platPkg);
-    if (fs.existsSync(platSrc)) {
-      copyDir(platSrc, path.join(destNm, platPkg));
-      log(`  ${platPkg} (${Math.round(sizeOf(platSrc) / 1024 / 1024)}MB)`);
-    }
-  }
-}
-const geminiSrc = path.join(nm, '@google', 'gemini-cli');
-if (fs.existsSync(geminiSrc)) {
-  copyDir(geminiSrc, path.join(destNm, '@google', 'gemini-cli'));
-  const geminiDeps = new Set();
-  collectDeps('@google/gemini-cli', geminiDeps);
-  for (const dep of geminiDeps) copyPkg(dep);
-  log(`  gemini-cli + ${geminiDeps.size} deps`);
-}
-
-log('Copying @anthropic-ai/claude-code ripgrep (win32)...');
-const claudeSrc = path.join(nm, '@anthropic-ai', 'claude-code');
-const claudeDest = path.join(destNm, '@anthropic-ai', 'claude-code');
-copyFile(path.join(claudeSrc, 'package.json'), path.join(claudeDest, 'package.json'));
-copyDir(path.join(claudeSrc, 'vendor', 'ripgrep', 'x64-win32'), path.join(claudeDest, 'vendor', 'ripgrep', 'x64-win32'));
-
-log('Creating data directory...');
-fs.mkdirSync(path.join(out, 'data'), { recursive: true });
-
-if (process.env.NO_BUNDLE_MODELS === 'true') {
-  log('Skipping model bundling (NO_BUNDLE_MODELS=true) - models will download on first use');
-} else {
-  log('Bundling AI models...');
-    // Get models from AnEntrypoint/models or local cache
-  let modelsDir = process.env.MODELS_SOURCE_DIR || path.join(os.homedir(), '.gmgui', 'models');
-  
-  // If models not present and we're in CI, clone from GitHub
-  if (!fs.existsSync(modelsDir) && process.env.CI) {
-    console.log('[BUILD] Models not found, cloning from GitHub...');
-    const ciModelsDir = path.join(os.tmpdir(), 'models-clone');
-    try {
-      execSync(`git clone https://github.com/AnEntrypoint/models.git "${ciModelsDir}" --depth 1`, { stdio: 'inherit' });
-      modelsDir = ciModelsDir;
-    } catch (e) {
-      console.error('[BUILD] Failed to clone models from GitHub:', e.message);
-    }
-  }
-  if (fs.existsSync(modelsDir)) {
-    copyDir(modelsDir, path.join(out, 'models'));
-    log(`Models bundled: ${Math.round(sizeOf(path.join(out, 'models')) / 1024 / 1024)}MB`);
-  } else {
-    log(`WARNING: No models found at ${modelsDir} - portable build will download on first use`);
-  }
-}
-
-fs.writeFileSync(path.join(out, 'README.txt'),
-  '# AgentGUI Portable\n\nDouble-click agentgui.exe to start.\nWeb interface: http://localhost:3000/gm/\nData stored in data/ folder. Fully self-contained.\n');
-
-const totalMB = Math.round(sizeOf(out) / 1024 / 1024);
-log(`Build complete! Total: ${totalMB}MB  Output: ${out}`);
-
-// Output the build directory path for GitHub Actions
-if (process.env.GITHUB_OUTPUT) {
-  const outPath = path.resolve(out);
-  fs.appendFileSync(process.env.GITHUB_OUTPUT, `portable-path=${outPath}\n`);
-  log(`GitHub Actions output: portable-path=${outPath}`);
-}

package/docs/SYNC_TO_DISPLAY_REPORT.md

@@ -1,279 +0,0 @@
-# AgentGUI Sync-to-Display Architecture Report
-
-## Executive Summary
-
-The sync-to-display system handles real-time synchronization of execution state from server to client display. Current implementation has been improved through multiple fixes, particularly for queue display consistency and steering support. This document consolidates the architecture and identifies remaining optimization opportunities.
-
-## Architecture Overview
-
-### 1. Broadcast System (server.js:4269-4317)
-
-**BROADCAST_TYPES** - Global broadcast events sent to ALL connected clients:
-- `message_created`, `conversation_created/updated/deleted`
-- `queue_status`, `queue_updated`
-- `streaming_start`, `streaming_progress`, `streaming_complete`, `streaming_error`
-- `rate_limit_hit`, `rate_limit_clear`
-- Tool-related events (`tool_*`, `tools_*`)
-- Voice/speech events
-- PM2 monitoring events
-
-**broadcastSync()** function (line 4288):
-```
-1. Check if event.type is in BROADCAST_TYPES
-2. If broadcast: send to ALL syncClients
-3. If targeted: send to sessionId or conversationId subscribers only
-4. Also dispatch to SSE stream handlers if active
-```
-
-### 2. Client-Side Message Reception (static/js/client.js)
-
-**handleWsMessage()** routes events by type:
-```javascript
-case 'message_created': handleMessageCreated(data)
-case 'queue_status': handleQueueStatus(data)
-case 'streaming_start': handleStreamingStart(data)
-case 'streaming_progress': handleStreamingProgress(data)
-```
-
-### 3. Display Rendering Layers
-
-**Layer 1: Message Rendering** (handleMessageCreated)
-- Checks if message already exists (prevents duplicates)
-- For user messages: finds optimistic message, updates it
-- For assistant messages: skips if streaming (handled by chunks)
-
-**Layer 2: Streaming Progress** (handleStreamingProgress)
-- Adds chunks to queue
-- Batches rendering via StreamingRenderer
-- Handles thinking blocks directly
-
-**Layer 3: Queue Indicator** (fetchAndRenderQueue)
-- Polls via `q.ls` RPC every interval
-- Displays queued items in yellow control blocks
-- Renders with Edit/Delete/Steer buttons
-
-**Layer 4: Conversation State** (handleConversationUpdated)
-- Updates isStreaming flag
-- Refreshes UI based on new state
-
-## Recent Fixes & Status
-
-### Fixed Issues
-
-✅ **Queue Message Duplication** (commit fbfd1ad)
-- Problem: Queued messages appeared as both user prompt + queue item
-- Solution: Skip optimistic message when conversation is streaming
-- Impact: Clean queue display, no duplication
-
-✅ **Steering Support** (commit 81d83af)
-- Problem: Steering showed "Process not available" error
-- Solution: Keep stdin open (supportsStdin=true, closeStdin=false)
-- Impact: Users can send follow-up prompts during execution
-
-✅ **Chunk Rendering Race** (Session 3a)
-- Problem: Early chunks missed before polling started
-- Solution: Immediate chunk fetch on streaming_start
-- Impact: No missing initial output
-
-✅ **Dark Mode Selection** (fsbrowse)
-- Problem: Selection states hard to see in dark mode
-- Solution: Theme-aware colors for hover/focus
-- Impact: Better visual feedback in both themes
-
-### Remaining Consistency Issues
-
-⚠️ **Queue State Sync Timing**
-- Queue created on server via enqueue()
-- message_created broadcast may arrive before queue is populated
-- Client fetchAndRenderQueue() polls but timing is unpredictable
-- No atomic operation ensuring client sees both message and queue
-
-⚠️ **Multiple Sources of Truth**
-- Server: database, active execution map, queue map
-- Client: message list, streaming set, queue indicator
-- Conversation state: isStreaming flag can desync if connection drops
-- No single authoritative state object
-
-⚠️ **Optimistic Message Updates**
-- Client creates optimistic "sending" message on submit
-- Server creates actual message and broadcasts
-- handleMessageCreated() finds and updates optimistic message
-- If network is slow, both may briefly exist
-
-⚠️ **Queue Execution Transition**
-- Queue items don't explicitly transition to executed
-- Client must poll queue indicator to see it disappear
-- No event indicating "queue item now executing"
-- Confusing UX when queue suddenly empties
-
-## Data Flow Examples
-
-### Normal Execution (Ctrl+Enter with no active stream)
-
-```
-User input: "Write a function"
-    ↓
-startExecution()
-    → _showOptimisticMessage(pendingId, content)  // yellow "sending..." message
-    ↓
-streamToConversation() → msg.stream RPC
-    ↓
-Server: msg.stream handler
-    → createMessage(p.id, 'user', prompt)
-    → broadcastSync({ type: 'message_created', ... })
-    → startExecution() -> streaming_start broadcast
-    ↓
-Client: message_created event
-    → handleMessageCreated()
-    → Finds optimistic message by ID
-    → Updates it (removes "sending" style, adds timestamp)
-    ↓
-Client: streaming_start event
-    → Disables input, shows "thinking..."
-    → Subscribes to session
-    → Starts chunk polling
-```
-
-### Queue Case (Ctrl+Enter while streaming) - NOW FIXED
-
-```
-User input: "Now add subtraction" during execution
-    ↓
-startExecution()
-    → isStreaming = true
-    → SKIP _showOptimisticMessage ✓ (FIXED)
-    ↓
-streamToConversation() → msg.stream RPC
-    ↓
-Server: msg.stream handler
-    → createMessage(p.id, 'user', prompt)
-    → broadcastSync({ type: 'message_created', ... })
-    → activeExecutions.has(p.id) = true
-    → enqueue(p.id, prompt, ...)
-    → broadcastSync({ type: 'queue_status', ... })
-    ↓
-Client: message_created event
-    → handleMessageCreated()
-    → Message is not in current conversation display
-    → Emit event but don't render
-    ↓
-Client: queue_status event
-    → handleQueueStatus()
-    → fetchAndRenderQueue()
-    → Displays in yellow queue indicator ✓
-    ↓
-Result: Message only in queue, no duplication ✓
-```
-
-### Steering (Ctrl+Enter + Steer button during execution)
-
-```
-User clicks Steer button on queued message
-    ↓
-Client: conv.steer RPC with JSON-RPC format
-    ↓
-Server: conv.steer handler
-    → Finds active process stdin
-    → Writes JSON-RPC prompt request
-    → Removes from queue (optional)
-    ↓
-Claude Code: Receives JSON-RPC on stdin
-    → Processes prompt immediately
-    → Continues execution with new direction
-    ↓
-Client: receives streaming_progress chunks
-    → Renders new content below existing output
-```
-
-## Consistency Guarantees
-
-### What IS Consistent
-- Messages don't duplicate (handled in handleMessageCreated)
-- Streaming chunks are ordered (via session ID subscription)
-- Queue items maintain order (FIFO in server queue map)
-- Tool installations tracked atomically (per-tool in database)
-
-### What IS NOT Guaranteed
-- Client queue display and server queue state may briefly desync
-- If connection drops mid-queue, client state becomes stale
-- No explicit confirmation that user message was queued
-- Queue item execution not signaled with explicit event
-
-## Recommendations for Further Improvement
-
-### Priority 1: Explicit Queue Lifecycle
-Add dedicated broadcast events:
-```javascript
-'message_queued'        // Sent when msg added to queue
-'queue_item_executing'  // Sent when queue item becomes active
-'queue_item_completed'  // Sent when queue item finished
-```
-
-### Priority 2: Atomic State Snapshots
-Periodically broadcast conversation state:
-```javascript
-{
-  type: 'conversation_state',
-  conversationId,
-  state: {
-    isStreaming: boolean,
-    messageCount: number,
-    queueLength: number,
-    lastMessageId: string,
-    lastUpdate: timestamp
-  }
-}
-```
-
-### Priority 3: Deterministic Client State Machine
-Each conversation has explicit state mode:
-```javascript
-state = {
-  mode: 'IDLE' | 'STREAMING' | 'QUEUED',
-  messages: [],
-  queue: [],
-  isTransitioning: boolean  // true when queue→execute
-}
-```
-
-### Priority 4: Connection Recovery
-After reconnect, fetch complete conversation state:
-```javascript
-await wsClient.rpc('conv.sync', { id: conversationId })
-// Returns: { messages, queue, isStreaming, chunks }
-```
-
-## Testing Matrix
-
-| Scenario | Before Fix | After Fix | Status |
-|----------|-----------|-----------|--------|
-| Ctrl+Enter (not streaming) | ✓ Works | ✓ Works | ✓ OK |
-| Ctrl+Enter (streaming) | ✗ Duplicate | ✓ Single queue item | ✓ FIXED |
-| Queue indicator updates | ⚠️ Polling | ⚠️ Polling | ⚠️ Could improve |
-| Steering works | ✗ "Not available" | ✓ Works | ✓ FIXED |
-| Multiple queued items | ⚠️ Order unclear | ⚠️ Order unclear | ⚠️ OK but could confirm |
-| Page reload with queue | ✗ Queue lost | ✓ Persisted | ✓ OK |
-| Network disconnect | ⚠️ State stale | ⚠️ State stale | ⚠️ Could improve |
-
-## Files Modified in Latest Session
-
-1. **lib/claude-runner.js** - Steering support
-   - Changed `supportsStdin: false` → `true`
-   - Changed `closeStdin: true` → `false`
-   - Removed positional prompt argument
-
-2. **static/js/client.js** - Queue display fix
-   - Skip optimistic message when streaming
-   - Skip confirm/fail handlers for queued messages
-
-3. **static/index.html** - Hamburger animation
-   - Added `transition: none` to .sidebar
-
-4. **fsbrowse/public/style.css** - Dark mode colors
-   - Improved hover states
-   - Theme-aware modal focus colors
-
-## Conclusion
-
-The sync-to-display system is now more consistent with the queue display fix and steering support. The architecture handles the primary use cases well, but could benefit from explicit lifecycle events and atomic state snapshots for guaranteed consistency. The current implementation is pragmatic and performant, trading off some guarantees for simplicity and responsiveness.
-