agentgui 1.0.843 → 1.0.845

package/CHANGELOG.md

@@ -1,6 +1,7 @@
 ## [Unreleased]
 
 ### Refactor
+- Extract WebSocket server setup and legacy message handler from server.js to lib/ws-setup.js (77L, createWsSetup factory) and lib/ws-legacy-handlers.js (154L, registerLegacyHandler); server.js reduced from 1077L to 748L; wss.on('connection'), heartbeat interval, hot-reload watcher, subscribe/unsubscribe/terminal/PM2 legacy handlers all moved; unused WebSocketServer, spawn, createRequire imports removed from server.js
 - Extract express upload + fsbrowse setup from server.js to lib/routes-upload.js (79L) exporting createExpressApp; server.js imports createExpressApp and no longer contains Busboy/fsbrowse/express inline code
 - Extract maskKey, getProviderConfigs, saveProviderConfig, buildSystemPrompt, PROVIDER_CONFIGS from server.js to lib/provider-config.js (151L); extract logError, makeCleanupExecution, makeGetModelsForAgent, errLogPath from server.js to lib/server-utils.js (61L); server.js imports all via named imports; cleanupExecution wired after broadcastSync; _debugRoutes receives errLogPath
 - Extract parseBody, acceptsEncoding, compressAndSend, sendJSON from server.js to lib/http-utils.js (43L); server.js imports from new module; zlib import removed from server.js

package/CLAUDE.md

@@ -60,6 +60,7 @@ lib/routes-runs.js     Runs HTTP route handlers (POST /api/runs, runs search, ru
 lib/routes-scripts.js  Scripts/cancel/resume/inject HTTP route handlers (conversation scripts, run-script, stop-script, cancel, resume, inject)
 lib/routes-agent-actions.js  Agent auth and update HTTP route handlers (POST /api/agents/:id/auth, POST /api/agents/:id/update)
 lib/routes-auth-config.js  Auth config HTTP route handlers (GET /api/auth/configs, POST /api/auth/save-config)
+lib/routes-upload.js   Express sub-app: POST /api/upload/:conversationId (Busboy file upload) + GET /files/:conversationId fsbrowse router; createExpressApp(deps) factory
 lib/http-utils.js       HTTP utility functions (parseBody, acceptsEncoding, compressAndSend, sendJSON)
 lib/provider-config.js  Provider config helpers (buildSystemPrompt, maskKey, getProviderConfigs, saveProviderConfig, PROVIDER_CONFIGS)
 lib/server-utils.js     Server utility functions (logError, errLogPath, makeCleanupExecution, makeGetModelsForAgent)

package/lib/ws-legacy-handlers.js

@@ -0,0 +1,154 @@
+import { spawn } from 'child_process';
+import { createRequire } from 'module';
+
+const _req = createRequire(import.meta.url);
+
+export function registerLegacyHandler(wsRouter, { subscriptionIndex, execMachine, activeExecutions, messageQueues, checkpointManager, queries, pm2Manager, pm2Subscribers, getSeq, sendWs, debugLog }) {
+  wsRouter.onLegacy((data, ws) => {
+    try {
+      if (data.type === 'subscribe') {
+        if (data.sessionId) {
+          ws.subscriptions.add(data.sessionId);
+          if (!subscriptionIndex.has(data.sessionId)) subscriptionIndex.set(data.sessionId, new Set());
+          subscriptionIndex.get(data.sessionId).add(ws);
+        }
+        if (data.conversationId) {
+          const key = `conv-${data.conversationId}`;
+          ws.subscriptions.add(key);
+          if (!subscriptionIndex.has(key)) subscriptionIndex.set(key, new Set());
+          subscriptionIndex.get(key).add(ws);
+        }
+        const subTarget = data.sessionId || data.conversationId;
+        debugLog(`[WebSocket] Client ${ws.clientId} subscribed to ${subTarget}`);
+        sendWs(ws, { type: 'subscription_confirmed', sessionId: data.sessionId, conversationId: data.conversationId, timestamp: Date.now() });
+        if (data.conversationId && execMachine.isActive(data.conversationId)) {
+          const ctx = execMachine.getContext(data.conversationId);
+          const execution = activeExecutions.get(data.conversationId);
+          const sessionId = ctx?.sessionId || execution?.sessionId;
+          const conv = queries.getConversation(data.conversationId);
+          const queueLength = execMachine.getQueue(data.conversationId).length || messageQueues.get(data.conversationId)?.length || 0;
+          sendWs(ws, { type: 'streaming_start', sessionId, conversationId: data.conversationId, agentId: conv?.agentType || conv?.agentId || 'claude-code', queueLength, resumed: true, seq: getSeq(), timestamp: Date.now() });
+        }
+        if (data.conversationId && checkpointManager.hasPendingCheckpoint(data.conversationId)) {
+          const checkpoint = checkpointManager.getPendingCheckpoint(data.conversationId);
+          if (checkpoint) {
+            debugLog(`[checkpoint] Injecting ${checkpoint.events.length} events to client for ${data.conversationId}`);
+            const latestSession = queries.getLatestSession(data.conversationId);
+            if (latestSession) {
+              sendWs(ws, { type: 'streaming_resumed', sessionId: latestSession.id, conversationId: data.conversationId, resumeFrom: checkpoint.sessionId, eventCount: checkpoint.events.length, chunkCount: checkpoint.chunks.length, timestamp: Date.now() });
+              checkpointManager.injectCheckpointEvents(latestSession.id, checkpoint, (evt) => {
+                sendWs(ws, { ...evt, sessionId: latestSession.id, conversationId: data.conversationId });
+              });
+            }
+          }
+        }
+      } else if (data.type === 'unsubscribe') {
+        if (data.sessionId) {
+          ws.subscriptions.delete(data.sessionId);
+          const idx = subscriptionIndex.get(data.sessionId);
+          if (idx) { idx.delete(ws); if (idx.size === 0) subscriptionIndex.delete(data.sessionId); }
+        }
+        if (data.conversationId) {
+          const key = `conv-${data.conversationId}`;
+          ws.subscriptions.delete(key);
+          const idx = subscriptionIndex.get(key);
+          if (idx) { idx.delete(ws); if (idx.size === 0) subscriptionIndex.delete(key); }
+        }
+        debugLog(`[WebSocket] Client ${ws.clientId} unsubscribed from ${data.sessionId || data.conversationId}`);
+      } else if (data.type === 'get_subscriptions') {
+        sendWs(ws, { type: 'subscriptions', subscriptions: Array.from(ws.subscriptions), timestamp: Date.now() });
+      } else if (data.type === 'set_voice') {
+        ws.ttsVoiceId = data.voiceId || 'default';
+      } else if (data.type === 'latency_report') {
+        ws.latencyTier = data.quality || 'good';
+        ws.latencyAvg = data.avg || 0;
+        ws.latencyTrend = data.trend || 'stable';
+      } else if (data.type === 'ping') {
+        sendWs(ws, { type: 'pong', requestId: data.requestId, timestamp: Date.now() });
+      } else if (data.type === 'terminal_start') {
+        if (ws.terminalProc) { try { ws.terminalProc.kill(); } catch (_) {} }
+        try {
+          const pty = _req('node-pty');
+          const shell = process.env.SHELL || '/bin/bash';
+          const cwd = data.cwd || process.env.STARTUP_CWD || process.env.HOME || '/';
+          const proc = pty.spawn(shell, [], { name: 'xterm-256color', cols: data.cols || 80, rows: data.rows || 24, cwd, env: { ...process.env, TERM: 'xterm-256color', COLORTERM: 'truecolor' } });
+          ws.terminalProc = proc;
+          ws.terminalPty = true;
+          proc.on('data', (chunk) => { if (ws.readyState === 1) sendWs(ws, { type: 'terminal_output', data: Buffer.from(chunk).toString('base64'), encoding: 'base64' }); });
+          proc.on('exit', (code) => { if (ws.readyState === 1) sendWs(ws, { type: 'terminal_exit', code }); ws.terminalProc = null; });
+          proc.on('error', (err) => { console.error('[TERMINAL] PTY error (contained):', err.message); if (ws.readyState === 1) sendWs(ws, { type: 'terminal_exit', code: 1, error: err.message }); ws.terminalProc = null; });
+          sendWs(ws, { type: 'terminal_started', timestamp: Date.now() });
+        } catch (_e) {
+          console.error('[TERMINAL] Failed to spawn PTY, falling back to pipes:', _e.message);
+          const shell = process.env.SHELL || '/bin/bash';
+          const cwd = data.cwd || process.env.STARTUP_CWD || process.env.HOME || '/';
+          const proc = spawn(shell, ['-i'], { cwd, env: { ...process.env, TERM: 'xterm-256color', COLORTERM: 'truecolor' }, stdio: ['pipe', 'pipe', 'pipe'] });
+          ws.terminalProc = proc;
+          ws.terminalPty = false;
+          proc.stdout.on('data', (chunk) => { if (ws.readyState === 1) sendWs(ws, { type: 'terminal_output', data: chunk.toString('base64'), encoding: 'base64' }); });
+          proc.stderr.on('data', (chunk) => { if (ws.readyState === 1) sendWs(ws, { type: 'terminal_output', data: chunk.toString('base64'), encoding: 'base64' }); });
+          proc.on('exit', (code) => { if (ws.readyState === 1) sendWs(ws, { type: 'terminal_exit', code }); ws.terminalProc = null; });
+          proc.on('error', (err) => { console.error('[TERMINAL] Spawn error (contained):', err.message); if (ws.readyState === 1) sendWs(ws, { type: 'terminal_exit', code: 1, error: err.message }); ws.terminalProc = null; });
+          proc.stdin.on('error', () => {});
+          proc.stdout.on('error', () => {});
+          proc.stderr.on('error', () => {});
+          sendWs(ws, { type: 'terminal_started', timestamp: Date.now() });
+        }
+      } else if (data.type === 'terminal_input') {
+        if (ws.terminalProc) {
+          try {
+            const input = Buffer.from(data.data, 'base64');
+            if (ws.terminalPty) { ws.terminalProc.write(input); }
+            else if (ws.terminalProc.stdin && ws.terminalProc.stdin.writable) { ws.terminalProc.stdin.write(input); }
+          } catch (_) {}
+        }
+      } else if (data.type === 'terminal_resize') {
+        if (ws.terminalProc && ws.terminalPty) {
+          try {
+            const { cols, rows } = data;
+            if (cols && rows && typeof ws.terminalProc.resize === 'function') { ws.terminalProc.resize(cols, rows); }
+          } catch (_) {}
+        }
+      } else if (data.type === 'terminal_stop') {
+        if (ws.terminalProc) { try { ws.terminalProc.kill(); } catch (_) {} ws.terminalProc = null; }
+      } else if (data.type === 'pm2_list') {
+        if (!pm2Manager.connected) {
+          if (ws.readyState === 1) sendWs(ws, { type: 'pm2_unavailable', reason: 'PM2 not connected', timestamp: Date.now() });
+        } else {
+          pm2Manager.listProcesses().then(processes => {
+            if (ws.readyState === 1) {
+              const hasActive = processes.some(p => ['online', 'launching', 'stopping', 'waiting restart'].includes(p.status));
+              sendWs(ws, { type: 'pm2_list_response', processes, hasActive });
+            }
+          }).catch(() => { if (ws.readyState === 1) sendWs(ws, { type: 'pm2_unavailable', reason: 'list failed', timestamp: Date.now() }); });
+        }
+      } else if (data.type === 'pm2_start_monitoring') {
+        pm2Subscribers.add(ws);
+        ws.pm2Subscribed = true;
+        if (!pm2Manager.connected) {
+          if (ws.readyState === 1) sendWs(ws, { type: 'pm2_unavailable', reason: 'PM2 not connected', timestamp: Date.now() });
+        } else {
+          sendWs(ws, { type: 'pm2_monitoring_started' });
+        }
+      } else if (data.type === 'pm2_stop_monitoring') {
+        pm2Subscribers.delete(ws);
+        ws.pm2Subscribed = false;
+        sendWs(ws, { type: 'pm2_monitoring_stopped' });
+      } else if (data.type === 'pm2_start') {
+        pm2Manager.startProcess(data.name).then(result => { sendWs(ws, { type: 'pm2_start_response', name: data.name, ...result }); });
+      } else if (data.type === 'pm2_stop') {
+        pm2Manager.stopProcess(data.name).then(result => { sendWs(ws, { type: 'pm2_stop_response', name: data.name, ...result }); });
+      } else if (data.type === 'pm2_restart') {
+        pm2Manager.restartProcess(data.name).then(result => { sendWs(ws, { type: 'pm2_restart_response', name: data.name, ...result }); });
+      } else if (data.type === 'pm2_delete') {
+        pm2Manager.deleteProcess(data.name).then(result => { sendWs(ws, { type: 'pm2_delete_response', name: data.name, ...result }); });
+      } else if (data.type === 'pm2_logs') {
+        pm2Manager.getLogs(data.name, { lines: data.lines || 100 }).then(result => { sendWs(ws, { type: 'pm2_logs_response', name: data.name, ...result }); });
+      } else if (data.type === 'pm2_flush_logs') {
+        pm2Manager.flushLogs(data.name).then(result => { sendWs(ws, { type: 'pm2_flush_logs_response', name: data.name, ...result }); });
+      } else if (data.type === 'pm2_ping') {
+        pm2Manager.ping().then(result => { sendWs(ws, { type: 'pm2_ping_response', ...result }); });
+      }
+    } catch (err) { console.error('[WS-LEGACY] Handler error (contained):', err.message); }
+  });
+}

package/lib/ws-setup.js

@@ -0,0 +1,77 @@
+import fs from 'fs';
+import path from 'path';
+import { WebSocketServer } from 'ws';
+import { registerLegacyHandler } from './ws-legacy-handlers.js';
+
+export function createWsSetup(server, { BASE_URL, watch, staticDir, _assetCache, htmlState, sendWs, wsRouter, debugLog, subscriptionIndex, syncClients, pm2Subscribers, wsOptimizer, legacyDeps }) {
+  const hotReloadClients = [];
+
+  const wss = new WebSocketServer({ server, perMessageDeflate: false });
+  wss.on('error', (err) => { console.error('[WSS] WebSocket server error (contained):', err.message); });
+
+  wss.on('connection', (ws, req) => {
+    const _pwd = process.env.PASSWORD;
+    if (_pwd) {
+      const url = new URL(req.url, 'http://localhost');
+      const token = url.searchParams.get('token');
+      if (token !== _pwd) { ws.close(4001, 'Unauthorized'); return; }
+    }
+    const wsPath = req.url.split('?')[0];
+    const wsRoute = wsPath.startsWith(BASE_URL) ? wsPath.slice(BASE_URL.length) : wsPath;
+    if (wsRoute === '/hot-reload') {
+      hotReloadClients.push(ws);
+      ws.on('close', () => { const i = hotReloadClients.indexOf(ws); if (i > -1) hotReloadClients.splice(i, 1); });
+    } else if (wsRoute === '/sync') {
+      syncClients.add(ws);
+      ws.isAlive = true;
+      ws.subscriptions = new Set();
+      ws.clientId = `client-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+      sendWs(ws, { type: 'sync_connected', clientId: ws.clientId, timestamp: Date.now() });
+      ws.on('error', (err) => { console.error('[WS] Client error (contained):', ws.clientId, err.message); });
+      ws.on('message', (msg) => { try { wsRouter.onMessage(ws, msg); } catch (e) { console.error('[WS] Message handler error (contained):', e.message); } });
+      ws.on('pong', () => { ws.isAlive = true; });
+      ws.on('close', () => {
+        if (ws.terminalProc) { try { ws.terminalProc.kill(); } catch (_) {} ws.terminalProc = null; }
+        syncClients.delete(ws);
+        wsOptimizer.removeClient(ws);
+        for (const sub of ws.subscriptions) {
+          const idx = subscriptionIndex.get(sub);
+          if (idx) { idx.delete(ws); if (idx.size === 0) subscriptionIndex.delete(sub); }
+        }
+        if (ws.pm2Subscribed) pm2Subscribers.delete(ws);
+        debugLog(`[WebSocket] Client ${ws.clientId} disconnected`);
+      });
+    }
+  });
+
+  registerLegacyHandler(wsRouter, legacyDeps);
+
+  setInterval(() => {
+    syncClients.forEach(ws => {
+      if (!ws.isAlive) { syncClients.delete(ws); wsOptimizer.removeClient(ws); return ws.terminate(); }
+      ws.isAlive = false;
+      ws.ping();
+    });
+  }, 30000);
+
+  if (watch) {
+    const watchedFiles = new Map();
+    try {
+      fs.readdirSync(staticDir).forEach(file => {
+        const fp = path.join(staticDir, file);
+        if (watchedFiles.has(fp)) return;
+        fs.watchFile(fp, { interval: 100 }, (curr, prev) => {
+          if (curr.mtime > prev.mtime) {
+            _assetCache.clear();
+            htmlState.cache = null;
+            htmlState.etag = null;
+            hotReloadClients.forEach(c => { if (c.readyState === 1) c.send(JSON.stringify({ type: 'reload' })); });
+          }
+        });
+        watchedFiles.set(fp, true);
+      });
+    } catch (e) { console.error('Watch error:', e.message); }
+  }
+
+  return { wss, hotReloadClients };
+}

package/package.json

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

package/server.js

@@ -3,10 +3,7 @@ import fs from 'fs';
 import path from 'path';
 import os from 'os';
 import { fileURLToPath } from 'url';
-import { WebSocketServer } from 'ws';
-import { execSync, spawn } from 'child_process';
 import { LRUCache } from 'lru-cache';
-import { createRequire } from 'module';
 import crypto from 'crypto';
 const PKG_VERSION = JSON.parse(fs.readFileSync(new URL('./package.json', import.meta.url), 'utf8')).version;
 import { createExpressApp } from './lib/routes-upload.js';
@@ -35,6 +32,7 @@ import { WSOptimizer } from './lib/ws-optimizer.js';
 import { WsRouter } from './lib/ws-protocol.js';
 import { encode as wsEncode } from './lib/codec.js';
 import { parseBody, acceptsEncoding, compressAndSend, sendJSON } from './lib/http-utils.js';
+import { createWsSetup } from './lib/ws-setup.js';
 const sendWs = (ws, obj) => { if (ws.readyState === 1) ws.send(wsEncode(obj)); };
 import { register as registerConvHandlers } from './lib/ws-handlers-conv.js';
 import { register as registerConvHandlers2 } from './lib/ws-handlers-conv2.js';
@@ -325,72 +323,10 @@ const _assetDeps = { compressAndSend, acceptsEncoding, watch, BASE_URL, PKG_VERS
 function serveFile(filePath, res, req) { return _serveFile(filePath, res, req, _assetDeps); }
 
 let broadcastSeq = 0;
-
-
-
-const wss = new WebSocketServer({
-  server,
-  perMessageDeflate: false  // Disabled: msgpack binary doesn't compress well, and
-                             // synchronous zlib on every frame blocks the event loop.
-                             // HTTP-layer gzip already handles static assets; WS
-                             // streaming events are small and latency-sensitive.
-});
-wss.on('error', (err) => {
-  console.error('[WSS] WebSocket server error (contained):', err.message);
-});
-const hotReloadClients = [];
 const syncClients = new Set();
 const subscriptionIndex = new Map();
 const pm2Subscribers = new Set();
 
-wss.on('connection', (ws, req) => {
-  const _pwd = process.env.PASSWORD;
-  if (_pwd) {
-    const url = new URL(req.url, 'http://localhost');
-    const token = url.searchParams.get('token');
-    if (token !== _pwd) { ws.close(4001, 'Unauthorized'); return; }
-  }
-  const wsPath = req.url.split('?')[0];
-  const wsRoute = wsPath.startsWith(BASE_URL) ? wsPath.slice(BASE_URL.length) : wsPath;
-  if (wsRoute === '/hot-reload') {
-    hotReloadClients.push(ws);
-    ws.on('close', () => { const i = hotReloadClients.indexOf(ws); if (i > -1) hotReloadClients.splice(i, 1); });
-  } else if (wsRoute === '/sync') {
-    syncClients.add(ws);
-    ws.isAlive = true;
-    ws.subscriptions = new Set();
-    ws.clientId = `client-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
-
-    sendWs(ws, ({
-      type: 'sync_connected',
-      clientId: ws.clientId,
-      timestamp: Date.now()
-    }));
-
-    ws.on('error', (err) => {
-      console.error('[WS] Client error (contained):', ws.clientId, err.message);
-    });
-    ws.on('message', (msg) => {
-      try { wsRouter.onMessage(ws, msg); } catch (e) { console.error('[WS] Message handler error (contained):', e.message); }
-    });
-
-    ws.on('pong', () => { ws.isAlive = true; });
-     ws.on('close', () => {
-       if (ws.terminalProc) { try { ws.terminalProc.kill(); } catch(e) {} ws.terminalProc = null; }
-       syncClients.delete(ws);
-       wsOptimizer.removeClient(ws);
-       for (const sub of ws.subscriptions) {
-         const idx = subscriptionIndex.get(sub);
-         if (idx) { idx.delete(ws); if (idx.size === 0) subscriptionIndex.delete(sub); }
-       }
-       if (ws.pm2Subscribed) {
-         pm2Subscribers.delete(ws);
-       }
-       debugLog(`[WebSocket] Client ${ws.clientId} disconnected`);
-     });
-  }
-});
-
 const BROADCAST_TYPES = new Set([
   'message_created', 'conversation_created', 'conversation_updated',
   'conversations_updated', 'conversation_deleted', 'all_conversations_deleted', 'queue_status', 'queue_updated', 'queue_item_dequeued',
@@ -510,281 +446,16 @@ registerOAuthHandlers(wsRouter, {
   codexOAuthState: getCodexOAuthState,
 });
 
-wsRouter.onLegacy((data, ws) => {
-  try {
-  if (data.type === 'subscribe') {
-    if (data.sessionId) {
-      ws.subscriptions.add(data.sessionId);
-      if (!subscriptionIndex.has(data.sessionId)) subscriptionIndex.set(data.sessionId, new Set());
-      subscriptionIndex.get(data.sessionId).add(ws);
-    }
-    if (data.conversationId) {
-      const key = `conv-${data.conversationId}`;
-      ws.subscriptions.add(key);
-      if (!subscriptionIndex.has(key)) subscriptionIndex.set(key, new Set());
-      subscriptionIndex.get(key).add(ws);
-    }
-    const subTarget = data.sessionId || data.conversationId;
-    debugLog(`[WebSocket] Client ${ws.clientId} subscribed to ${subTarget}`);
-    sendWs(ws, ({
-      type: 'subscription_confirmed',
-      sessionId: data.sessionId,
-      conversationId: data.conversationId,
-      timestamp: Date.now()
-    }));
-
-    // Notify client if this conversation has an active streaming execution
-    // Machine is authoritative for streaming state check on subscribe
-    if (data.conversationId && execMachine.isActive(data.conversationId)) {
-      const ctx = execMachine.getContext(data.conversationId);
-      const execution = activeExecutions.get(data.conversationId);
-      const sessionId = ctx?.sessionId || execution?.sessionId;
-      const conv = queries.getConversation(data.conversationId);
-      const queueLength = execMachine.getQueue(data.conversationId).length || messageQueues.get(data.conversationId)?.length || 0;
-      sendWs(ws, ({
-        type: 'streaming_start',
-        sessionId,
-        conversationId: data.conversationId,
-        agentId: conv?.agentType || conv?.agentId || 'claude-code',
-        queueLength,
-        resumed: true,
-        seq: ++broadcastSeq,
-        timestamp: Date.now()
-      }));
-    }
-
-    // Inject pending checkpoint events if this is a conversation subscription
-    if (data.conversationId && checkpointManager.hasPendingCheckpoint(data.conversationId)) {
-      const checkpoint = checkpointManager.getPendingCheckpoint(data.conversationId);
-      if (checkpoint) {
-        debugLog(`[checkpoint] Injecting ${checkpoint.events.length} events to client for ${data.conversationId}`);
-
-        const latestSession = queries.getLatestSession(data.conversationId);
-        if (latestSession) {
-          sendWs(ws, ({
-            type: 'streaming_resumed',
-            sessionId: latestSession.id,
-            conversationId: data.conversationId,
-            resumeFrom: checkpoint.sessionId,
-            eventCount: checkpoint.events.length,
-            chunkCount: checkpoint.chunks.length,
-            timestamp: Date.now()
-          }));
-
-          checkpointManager.injectCheckpointEvents(latestSession.id, checkpoint, (evt) => {
-            sendWs(ws, ({
-              ...evt,
-              sessionId: latestSession.id,
-              conversationId: data.conversationId
-            }));
-          });
-        }
-      }
-    }
-  } else if (data.type === 'unsubscribe') {
-    if (data.sessionId) {
-      ws.subscriptions.delete(data.sessionId);
-      const idx = subscriptionIndex.get(data.sessionId);
-      if (idx) { idx.delete(ws); if (idx.size === 0) subscriptionIndex.delete(data.sessionId); }
-    }
-    if (data.conversationId) {
-      const key = `conv-${data.conversationId}`;
-      ws.subscriptions.delete(key);
-      const idx = subscriptionIndex.get(key);
-      if (idx) { idx.delete(ws); if (idx.size === 0) subscriptionIndex.delete(key); }
-    }
-    debugLog(`[WebSocket] Client ${ws.clientId} unsubscribed from ${data.sessionId || data.conversationId}`);
-  } else if (data.type === 'get_subscriptions') {
-    sendWs(ws, ({
-      type: 'subscriptions',
-      subscriptions: Array.from(ws.subscriptions),
-      timestamp: Date.now()
-    }));
-  } else if (data.type === 'set_voice') {
-    ws.ttsVoiceId = data.voiceId || 'default';
-  } else if (data.type === 'latency_report') {
-    ws.latencyTier = data.quality || 'good';
-    ws.latencyAvg = data.avg || 0;
-    ws.latencyTrend = data.trend || 'stable';
-  } else if (data.type === 'ping') {
-    sendWs(ws, ({
-      type: 'pong',
-      requestId: data.requestId,
-      timestamp: Date.now()
-    }));
-  } else if (data.type === 'terminal_start') {
-    if (ws.terminalProc) {
-      try { ws.terminalProc.kill(); } catch(e) {}
-    }
-    try {
-      const _req = createRequire(import.meta.url);
-      const pty = _req('node-pty');
-      const shell = process.env.SHELL || '/bin/bash';
-      const cwd = data.cwd || process.env.STARTUP_CWD || process.env.HOME || '/';
-      const proc = pty.spawn(shell, [], {
-        name: 'xterm-256color',
-        cols: data.cols || 80,
-        rows: data.rows || 24,
-        cwd: cwd,
-        env: { ...process.env, TERM: 'xterm-256color', COLORTERM: 'truecolor' }
-      });
-      ws.terminalProc = proc;
-      ws.terminalPty = true;
-      proc.on('data', (chunk) => {
-        if (ws.readyState === 1) sendWs(ws, ({ type: 'terminal_output', data: Buffer.from(chunk).toString('base64'), encoding: 'base64' }));
-      });
-      proc.on('exit', (code) => {
-        if (ws.readyState === 1) sendWs(ws, { type: 'terminal_exit', code });
-        ws.terminalProc = null;
-      });
-      proc.on('error', (err) => {
-        console.error('[TERMINAL] PTY error (contained):', err.message);
-        if (ws.readyState === 1) sendWs(ws, { type: 'terminal_exit', code: 1, error: err.message });
-        ws.terminalProc = null;
-      });
-      sendWs(ws, ({ type: 'terminal_started', timestamp: Date.now() }));
-    } catch (e) {
-      console.error('[TERMINAL] Failed to spawn PTY, falling back to pipes:', e.message);
-      const shell = process.env.SHELL || '/bin/bash';
-      const cwd = data.cwd || process.env.STARTUP_CWD || process.env.HOME || '/';
-      const proc = spawn(shell, ['-i'], { cwd, env: { ...process.env, TERM: 'xterm-256color', COLORTERM: 'truecolor' }, stdio: ['pipe', 'pipe', 'pipe'] });
-      ws.terminalProc = proc;
-      ws.terminalPty = false;
-      proc.stdout.on('data', (chunk) => {
-        if (ws.readyState === 1) sendWs(ws, ({ type: 'terminal_output', data: chunk.toString('base64'), encoding: 'base64' }));
-      });
-      proc.stderr.on('data', (chunk) => {
-        if (ws.readyState === 1) sendWs(ws, ({ type: 'terminal_output', data: chunk.toString('base64'), encoding: 'base64' }));
-      });
-      proc.on('exit', (code) => {
-        if (ws.readyState === 1) sendWs(ws, { type: 'terminal_exit', code });
-        ws.terminalProc = null;
-      });
-      proc.on('error', (err) => {
-        console.error('[TERMINAL] Spawn error (contained):', err.message);
-        if (ws.readyState === 1) sendWs(ws, { type: 'terminal_exit', code: 1, error: err.message });
-        ws.terminalProc = null;
-      });
-      proc.stdin.on('error', () => {});
-      proc.stdout.on('error', () => {});
-      proc.stderr.on('error', () => {});
-      sendWs(ws, ({ type: 'terminal_started', timestamp: Date.now() }));
-    }
-  } else if (data.type === 'terminal_input') {
-    if (ws.terminalProc) {
-      try {
-        const input = Buffer.from(data.data, 'base64');
-        if (ws.terminalPty) {
-          ws.terminalProc.write(input);
-        } else if (ws.terminalProc.stdin && ws.terminalProc.stdin.writable) {
-          ws.terminalProc.stdin.write(input);
-        }
-      } catch (e) {}
-    }
-  } else if (data.type === 'terminal_resize') {
-    if (ws.terminalProc && ws.terminalPty) {
-      try {
-        const { cols, rows } = data;
-        if (cols && rows && typeof ws.terminalProc.resize === 'function') {
-          ws.terminalProc.resize(cols, rows);
-        }
-      } catch (e) {}
-    }
-   } else if (data.type === 'terminal_stop') {
-     if (ws.terminalProc) {
-       try { ws.terminalProc.kill(); } catch(e) {}
-       ws.terminalProc = null;
-     }
-    } else if (data.type === 'pm2_list') {
-      if (!pm2Manager.connected) {
-        if (ws.readyState === 1) sendWs(ws, ({ type: 'pm2_unavailable', reason: 'PM2 not connected', timestamp: Date.now() }));
-      } else {
-        pm2Manager.listProcesses().then(processes => {
-          if (ws.readyState === 1) {
-            const hasActive = processes.some(p => ['online','launching','stopping','waiting restart'].includes(p.status));
-            sendWs(ws, { type: 'pm2_list_response', processes, hasActive });
-          }
-        }).catch(() => {
-          if (ws.readyState === 1) sendWs(ws, ({ type: 'pm2_unavailable', reason: 'list failed', timestamp: Date.now() }));
-        });
-      }
-    } else if (data.type === 'pm2_start_monitoring') {
-      pm2Subscribers.add(ws);
-      ws.pm2Subscribed = true;
-      if (!pm2Manager.connected) {
-        if (ws.readyState === 1) sendWs(ws, ({ type: 'pm2_unavailable', reason: 'PM2 not connected', timestamp: Date.now() }));
-      } else {
-        sendWs(ws, { type: 'pm2_monitoring_started' });
-      }
-    } else if (data.type === 'pm2_stop_monitoring') {
-      pm2Subscribers.delete(ws);
-      ws.pm2Subscribed = false;
-      sendWs(ws, { type: 'pm2_monitoring_stopped' });
-    } else if (data.type === 'pm2_start') {
-      pm2Manager.startProcess(data.name).then(result => {
-        sendWs(ws, { type: 'pm2_start_response', name: data.name, ...result });
-      });
-    } else if (data.type === 'pm2_stop') {
-      pm2Manager.stopProcess(data.name).then(result => {
-        sendWs(ws, { type: 'pm2_stop_response', name: data.name, ...result });
-      });
-    } else if (data.type === 'pm2_restart') {
-      pm2Manager.restartProcess(data.name).then(result => {
-        sendWs(ws, { type: 'pm2_restart_response', name: data.name, ...result });
-      });
-    } else if (data.type === 'pm2_delete') {
-      pm2Manager.deleteProcess(data.name).then(result => {
-        sendWs(ws, { type: 'pm2_delete_response', name: data.name, ...result });
-      });
-    } else if (data.type === 'pm2_logs') {
-      pm2Manager.getLogs(data.name, { lines: data.lines || 100 }).then(result => {
-        sendWs(ws, { type: 'pm2_logs_response', name: data.name, ...result });
-      });
-    } else if (data.type === 'pm2_flush_logs') {
-      pm2Manager.flushLogs(data.name).then(result => {
-        sendWs(ws, { type: 'pm2_flush_logs_response', name: data.name, ...result });
-      });
-    } else if (data.type === 'pm2_ping') {
-      pm2Manager.ping().then(result => {
-        sendWs(ws, { type: 'pm2_ping_response', ...result });
-      });
-    }
-
-  } catch (err) { console.error('[WS-LEGACY] Handler error (contained):', err.message); }
+const { wss, hotReloadClients } = createWsSetup(server, {
+  BASE_URL, watch, staticDir, _assetCache, htmlState, sendWs, wsRouter, debugLog,
+  subscriptionIndex, syncClients, pm2Subscribers, wsOptimizer,
+  legacyDeps: {
+    subscriptionIndex, execMachine, activeExecutions, messageQueues,
+    checkpointManager, queries, pm2Manager, pm2Subscribers,
+    getSeq: () => ++broadcastSeq, sendWs, debugLog
+  }
 });
 
-// Heartbeat interval to detect stale connections
-const heartbeatInterval = setInterval(() => {
-  syncClients.forEach(ws => {
-    if (!ws.isAlive) {
-      syncClients.delete(ws);
-      wsOptimizer.removeClient(ws);
-      return ws.terminate();
-    }
-    ws.isAlive = false;
-    ws.ping();
-  });
-}, 30000);
-
-if (watch) {
-  const watchedFiles = new Map();
-  try {
-    fs.readdirSync(staticDir).forEach(file => {
-      const fp = path.join(staticDir, file);
-      if (watchedFiles.has(fp)) return;
-      fs.watchFile(fp, { interval: 100 }, (curr, prev) => {
-        if (curr.mtime > prev.mtime) {
-          _assetCache.clear();
-          htmlState.cache = null;
-          htmlState.etag = null;
-          hotReloadClients.forEach(c => { if (c.readyState === 1) c.send(JSON.stringify({ type: 'reload' })); });
-        }
-      });
-      watchedFiles.set(fp, true);
-    });
-  } catch (e) { console.error('Watch error:', e.message); }
-}
-
 const { killActiveExecutions, recoverStaleSessions, resumeInterruptedStreams, isProcessAlive, markAgentDead, resumeConversation, performAgentHealthCheck } = createRecovery({
   activeExecutions,
   processMessageWithStreaming,