@aoagents/ao-web 0.2.4 → 0.3.0

package/dist-server/mux-websocket.js

@@ -0,0 +1,516 @@
+/**
+ * Multiplexed WebSocket server for terminal multiplexing.
+ * Manages multiple terminal connections over a single persistent WebSocket.
+ *
+ * Session updates are delivered via a single shared SSE connection from this
+ * process to Next.js /api/events, then broadcast to all subscribed clients.
+ * This replaces per-client HTTP polling and makes session updates event-driven.
+ */
+import { WebSocketServer, WebSocket } from "ws";
+import { homedir, userInfo } from "node:os";
+import { spawn } from "node:child_process";
+import { findTmux, resolveTmuxSession, validateSessionId } from "./tmux-utils.js";
+/**
+ * Manages a single shared SSE connection to Next.js /api/events.
+ * Broadcasts session patches to all subscribed callbacks.
+ * Lazily connects on first subscriber, disconnects when the last one leaves.
+ */
+export class SessionBroadcaster {
+    subscribers = new Set();
+    abortController = null;
+    reconnectTimer = null;
+    baseUrl;
+    constructor(nextPort) {
+        this.baseUrl = `http://localhost:${nextPort}`;
+    }
+    /**
+     * Subscribe to session patches. Returns an unsubscribe function.
+     * Sends an immediate snapshot to the new subscriber, then live SSE pushes.
+     */
+    subscribe(callback) {
+        const wasEmpty = this.subscribers.size === 0;
+        this.subscribers.add(callback);
+        // Immediately send a one-off snapshot to just this new subscriber
+        void this.fetchSnapshot().then((sessions) => {
+            if (sessions && this.subscribers.has(callback)) {
+                callback(sessions);
+            }
+        });
+        // Start the shared SSE connection if this is the first subscriber
+        if (wasEmpty) {
+            void this.connect();
+        }
+        return () => {
+            this.subscribers.delete(callback);
+            if (this.subscribers.size === 0) {
+                this.disconnect();
+            }
+        };
+    }
+    broadcast(sessions) {
+        for (const callback of this.subscribers) {
+            try {
+                callback(sessions);
+            }
+            catch (err) {
+                console.error("[MuxServer] Session broadcast subscriber threw:", err);
+            }
+        }
+    }
+    /** One-shot HTTP fetch of the current session list for immediate delivery. */
+    async fetchSnapshot() {
+        try {
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), 4000);
+            try {
+                const res = await fetch(`${this.baseUrl}/api/sessions/patches`, {
+                    signal: controller.signal,
+                });
+                clearTimeout(timeoutId);
+                if (!res.ok)
+                    return null;
+                const data = (await res.json());
+                return data.sessions ?? null;
+            }
+            catch {
+                clearTimeout(timeoutId);
+                return null;
+            }
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Open a persistent SSE connection and stream events to all subscribers. */
+    async connect() {
+        if (this.abortController)
+            return;
+        const controller = new AbortController();
+        this.abortController = controller;
+        const { signal } = controller;
+        try {
+            const res = await fetch(`${this.baseUrl}/api/events`, {
+                signal,
+                headers: { Accept: "text/event-stream" },
+            });
+            if (!res.ok || !res.body) {
+                throw new Error(`SSE connect failed: ${res.status}`);
+            }
+            const reader = res.body.getReader();
+            const decoder = new TextDecoder();
+            let buffer = "";
+            while (!signal.aborted) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                buffer += decoder.decode(value, { stream: true });
+                const lines = buffer.split("\n");
+                buffer = lines.pop() ?? "";
+                for (const line of lines) {
+                    if (!line.startsWith("data: "))
+                        continue;
+                    try {
+                        const event = JSON.parse(line.slice(6));
+                        if (event.type === "snapshot" && event.sessions) {
+                            this.broadcast(event.sessions);
+                        }
+                    }
+                    catch {
+                        // ignore malformed events
+                    }
+                }
+            }
+        }
+        catch (err) {
+            if (signal.aborted)
+                return; // intentional disconnect, not an error
+            console.warn("[MuxServer] SSE connection lost:", err instanceof Error ? err.message : err);
+        }
+        finally {
+            // Only clear our own controller — a concurrent connect() may have already
+            // set a new one (e.g. disconnect() → subscribe() → connect() in the same tick).
+            if (this.abortController === controller) {
+                this.abortController = null;
+            }
+        }
+        // Reconnect with backoff if there are still subscribers
+        if (this.subscribers.size > 0) {
+            console.log("[MuxServer] SSE reconnecting in 5s");
+            this.reconnectTimer = setTimeout(() => {
+                this.reconnectTimer = null;
+                if (this.subscribers.size > 0)
+                    void this.connect();
+            }, 5000);
+        }
+    }
+    disconnect() {
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        this.abortController?.abort();
+        this.abortController = null;
+    }
+}
+let ptySpawn;
+/* eslint-enable @typescript-eslint/consistent-type-imports */
+try {
+    const nodePty = await import("node-pty");
+    ptySpawn = nodePty.spawn;
+}
+catch (err) {
+    console.warn("[MuxServer] node-pty not available — mux server will be disabled.", err);
+}
+const RING_BUFFER_MAX = 50 * 1024; // 50KB max per terminal
+const MAX_REATTACH_ATTEMPTS = 3;
+/**
+ * TerminalManager manages PTY processes independently of WebSocket connections.
+ * A single manager instance is shared across all mux connections.
+ */
+class TerminalManager {
+    terminals = new Map();
+    TMUX;
+    constructor(tmuxPath) {
+        this.TMUX = tmuxPath ?? findTmux();
+    }
+    /**
+     * Open/attach to a terminal. If already open, just return.
+     * If has subscribers but PTY crashed, re-attach.
+     */
+    open(id) {
+        // Validate and resolve
+        if (!validateSessionId(id)) {
+            throw new Error(`Invalid session ID: ${id}`);
+        }
+        const tmuxSessionId = resolveTmuxSession(id, this.TMUX);
+        if (!tmuxSessionId) {
+            throw new Error(`Session not found: ${id}`);
+        }
+        // Get or create terminal entry
+        let terminal = this.terminals.get(id);
+        if (!terminal) {
+            terminal = {
+                id,
+                tmuxSessionId,
+                pty: null,
+                subscribers: new Set(),
+                exitCallbacks: new Set(),
+                buffer: [],
+                bufferBytes: 0,
+                reattachAttempts: 0,
+            };
+            this.terminals.set(id, terminal);
+        }
+        // If PTY is already attached, we're done
+        if (terminal.pty) {
+            return tmuxSessionId;
+        }
+        // Enable mouse mode
+        const mouseProc = spawn(this.TMUX, ["set-option", "-t", tmuxSessionId, "mouse", "on"]);
+        mouseProc.on("error", (err) => {
+            console.error(`[MuxServer] Failed to set mouse mode for ${tmuxSessionId}:`, err.message);
+        });
+        // Hide the status bar
+        const statusProc = spawn(this.TMUX, ["set-option", "-t", tmuxSessionId, "status", "off"]);
+        statusProc.on("error", (err) => {
+            console.error(`[MuxServer] Failed to hide status bar for ${tmuxSessionId}:`, err.message);
+        });
+        // Build environment
+        const homeDir = process.env.HOME || homedir();
+        const currentUser = process.env.USER || userInfo().username;
+        const env = {
+            HOME: homeDir,
+            SHELL: process.env.SHELL || "/bin/bash",
+            USER: currentUser,
+            PATH: process.env.PATH || "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin",
+            TERM: "xterm-256color",
+            LANG: process.env.LANG || "en_US.UTF-8",
+            TMPDIR: process.env.TMPDIR || "/tmp",
+        };
+        if (!ptySpawn) {
+            throw new Error("node-pty not available");
+        }
+        // Spawn PTY
+        const pty = ptySpawn(this.TMUX, ["attach-session", "-t", tmuxSessionId], {
+            name: "xterm-256color",
+            cols: 80,
+            rows: 24,
+            cwd: homeDir,
+            env,
+        });
+        terminal.pty = pty;
+        // Wire up data events
+        pty.onData((data) => {
+            // Push to all subscribers — isolate each callback so a throw in one
+            // (e.g. a closed ws.send) doesn't abort the loop or skip the buffer.
+            for (const callback of terminal.subscribers) {
+                try {
+                    callback(data);
+                }
+                catch (err) {
+                    console.error("[MuxServer] Subscriber callback threw:", err);
+                }
+            }
+            // Append to ring buffer
+            terminal.buffer.push(data);
+            terminal.bufferBytes += Buffer.byteLength(data, "utf8");
+            // Trim buffer if over limit
+            while (terminal.bufferBytes > RING_BUFFER_MAX && terminal.buffer.length > 0) {
+                const removed = terminal.buffer.shift() ?? "";
+                terminal.bufferBytes -= Buffer.byteLength(removed, "utf8");
+            }
+        });
+        // Handle PTY exit
+        pty.onExit(({ exitCode }) => {
+            console.log(`[MuxServer] PTY exited for ${id} with code ${exitCode}`);
+            terminal.pty = null;
+            // Re-attach if subscribers are still present, up to MAX_REATTACH_ATTEMPTS.
+            // The cap prevents an unbounded respawn loop when the PTY crashes immediately
+            // after every attach (e.g. resource exhaustion or a broken tmux session).
+            if (terminal.subscribers.size > 0 && terminal.reattachAttempts < MAX_REATTACH_ATTEMPTS) {
+                terminal.reattachAttempts += 1;
+                console.log(`[MuxServer] Re-attaching to ${id} (attempt ${terminal.reattachAttempts}/${MAX_REATTACH_ATTEMPTS})`);
+                try {
+                    this.open(id);
+                    terminal.reattachAttempts = 0; // reset on successful attach
+                    return; // re-attached — don't notify exit
+                }
+                catch (err) {
+                    console.error(`[MuxServer] Failed to re-attach ${id}:`, err);
+                }
+            }
+            else if (terminal.reattachAttempts >= MAX_REATTACH_ATTEMPTS) {
+                console.error(`[MuxServer] Max re-attach attempts reached for ${id}, giving up`);
+            }
+            // Notify subscribers that the terminal has exited (re-attach failed or no subscribers)
+            for (const cb of terminal.exitCallbacks) {
+                cb(exitCode);
+            }
+        });
+        console.log(`[MuxServer] Opened terminal ${id} (tmux: ${tmuxSessionId})`);
+        return tmuxSessionId;
+    }
+    /**
+     * Write data to the PTY if attached
+     */
+    write(id, data) {
+        const terminal = this.terminals.get(id);
+        if (terminal?.pty) {
+            terminal.pty.write(data);
+        }
+    }
+    /**
+     * Resize the PTY if attached
+     */
+    resize(id, cols, rows) {
+        const terminal = this.terminals.get(id);
+        if (terminal?.pty) {
+            terminal.pty.resize(cols, rows);
+        }
+    }
+    /**
+     * Subscribe to terminal data. Returns unsubscribe function.
+     * Automatically opens the terminal if needed.
+     * @param onExit - called when the PTY exits and cannot be re-attached
+     */
+    subscribe(id, callback, onExit) {
+        // Ensure terminal is open
+        this.open(id);
+        const terminal = this.terminals.get(id);
+        if (!terminal) {
+            throw new Error(`Failed to open terminal: ${id}`);
+        }
+        // Add subscriber
+        terminal.subscribers.add(callback);
+        if (onExit)
+            terminal.exitCallbacks.add(onExit);
+        // Return unsubscribe function
+        return () => {
+            terminal.subscribers.delete(callback);
+            if (onExit)
+                terminal.exitCallbacks.delete(onExit);
+            // Kill PTY and clean up when the last subscriber leaves
+            if (terminal.subscribers.size === 0) {
+                if (terminal.pty) {
+                    terminal.pty.kill();
+                    terminal.pty = null;
+                }
+                this.terminals.delete(id);
+            }
+        };
+    }
+    /**
+     * Get buffered data for a terminal
+     */
+    getBuffer(id) {
+        const terminal = this.terminals.get(id);
+        if (!terminal)
+            return "";
+        return terminal.buffer.join("");
+    }
+}
+/**
+ * Create a mux WebSocket server (noServer mode).
+ * Returns the WebSocketServer instance for manual upgrade routing.
+ */
+export function createMuxWebSocket(tmuxPath) {
+    if (!ptySpawn) {
+        console.warn("[MuxServer] node-pty not available — mux WebSocket will be disabled");
+        return null;
+    }
+    const terminalManager = new TerminalManager(tmuxPath);
+    const nextPort = process.env.PORT || "3000";
+    const broadcaster = new SessionBroadcaster(nextPort);
+    const wss = new WebSocketServer({ noServer: true });
+    wss.on("connection", (ws) => {
+        console.log("[MuxServer] New mux connection");
+        const subscriptions = new Map();
+        let sessionUnsubscribe = null;
+        let missedPongs = 0;
+        const MAX_MISSED_PONGS = 3;
+        // Heartbeat: send native WebSocket ping every 15s.
+        // Browsers automatically respond to native pings with pong frames —
+        // no application-level code is needed on the client side.
+        const heartbeatInterval = setInterval(() => {
+            if (ws.readyState === WebSocket.OPEN) {
+                // Send the ping first so it counts as a sent-but-unanswered probe
+                ws.ping();
+                missedPongs += 1;
+                if (missedPongs >= MAX_MISSED_PONGS) {
+                    console.log("[MuxServer] Too many missed pongs, terminating connection");
+                    ws.terminate();
+                }
+            }
+        }, 15_000);
+        // Native pong resets the missed counter
+        ws.on("pong", () => {
+            missedPongs = 0;
+        });
+        /**
+         * Handle incoming messages
+         */
+        ws.on("message", (data) => {
+            try {
+                const msg = JSON.parse(data.toString("utf8"));
+                if (msg.ch === "system") {
+                    if (msg.type === "ping") {
+                        const pong = { ch: "system", type: "pong" };
+                        ws.send(JSON.stringify(pong));
+                    }
+                }
+                else if (msg.ch === "terminal") {
+                    const { id, type } = msg;
+                    try {
+                        if (type === "open") {
+                            // Validate session exists
+                            terminalManager.open(id);
+                            // Send opened confirmation (idempotent — safe to send on re-open)
+                            const openedMsg = { ch: "terminal", id, type: "opened" };
+                            ws.send(JSON.stringify(openedMsg));
+                            // Subscribe and send history buffer only for new subscribers.
+                            // Skipping the buffer on re-open prevents duplicate output when
+                            // MuxProvider re-sends open for all terminals on reconnect.
+                            if (!subscriptions.has(id)) {
+                                // Send buffered history to catch up the new subscriber
+                                const buffer = terminalManager.getBuffer(id);
+                                if (buffer) {
+                                    const bufferMsg = {
+                                        ch: "terminal",
+                                        id,
+                                        type: "data",
+                                        data: buffer,
+                                    };
+                                    ws.send(JSON.stringify(bufferMsg));
+                                }
+                                const unsub = terminalManager.subscribe(id, (data) => {
+                                    const dataMsg = {
+                                        ch: "terminal",
+                                        id,
+                                        type: "data",
+                                        data,
+                                    };
+                                    if (ws.readyState === WebSocket.OPEN) {
+                                        ws.send(JSON.stringify(dataMsg));
+                                    }
+                                }, (exitCode) => {
+                                    const exitedMsg = { ch: "terminal", id, type: "exited", code: exitCode };
+                                    if (ws.readyState === WebSocket.OPEN) {
+                                        ws.send(JSON.stringify(exitedMsg));
+                                    }
+                                });
+                                subscriptions.set(id, unsub);
+                            }
+                        }
+                        else if (type === "data" && "data" in msg) {
+                            terminalManager.write(id, msg.data);
+                        }
+                        else if (type === "resize" && "cols" in msg && "rows" in msg) {
+                            terminalManager.resize(id, msg.cols, msg.rows);
+                        }
+                        else if (type === "close") {
+                            // Unsubscribe this client only — TerminalManager is shared across
+                            // all mux connections so we must not kill the PTY here.
+                            const unsub = subscriptions.get(id);
+                            if (unsub) {
+                                unsub();
+                                subscriptions.delete(id);
+                            }
+                        }
+                    }
+                    catch (err) {
+                        if (ws.readyState === WebSocket.OPEN) {
+                            const errorMsg = {
+                                ch: "terminal",
+                                id,
+                                type: "error",
+                                message: err instanceof Error ? err.message : String(err),
+                            };
+                            ws.send(JSON.stringify(errorMsg));
+                        }
+                    }
+                }
+                else if (msg.ch === "subscribe") {
+                    if (msg.topics.includes("sessions") && !sessionUnsubscribe) {
+                        sessionUnsubscribe = broadcaster.subscribe((sessions) => {
+                            if (ws.readyState === WebSocket.OPEN) {
+                                const snapMsg = { ch: "sessions", type: "snapshot", sessions };
+                                ws.send(JSON.stringify(snapMsg));
+                            }
+                        });
+                    }
+                }
+            }
+            catch (err) {
+                console.error("[MuxServer] Failed to parse message:", err);
+                const errorMsg = {
+                    ch: "system",
+                    type: "error",
+                    message: "Invalid message format",
+                };
+                if (ws.readyState === WebSocket.OPEN) {
+                    ws.send(JSON.stringify(errorMsg));
+                }
+            }
+        });
+        /**
+         * Handle connection close
+         */
+        ws.on("close", () => {
+            console.log("[MuxServer] Mux connection closed");
+            clearInterval(heartbeatInterval);
+            sessionUnsubscribe?.();
+            sessionUnsubscribe = null;
+            for (const unsub of subscriptions.values()) {
+                unsub();
+            }
+            subscriptions.clear();
+        });
+        // In the ws library, "error" is always followed by "close", so the close
+        // handler below handles all cleanup.  Log the error here and nothing more.
+        ws.on("error", (err) => {
+            console.error("[MuxServer] WebSocket error:", err.message);
+        });
+    });
+    console.log("[MuxServer] Mux WebSocket server created (noServer mode)");
+    return wss;
+}

package/dist-server/start-all.js

@@ -77,8 +77,6 @@ function resolveNextBin() {
 // Start Next.js production server
 const port = process.env["PORT"] || "3000";
 spawnProcess("next", resolveNextBin(), ["start", "-p", port]);
-// Start terminal WebSocket server (auto-restart on crash)
-spawnProcess("terminal", "node", [resolve(__dirname, "terminal-websocket.js")], { restart: true });
 // Start direct terminal WebSocket server (auto-restart on crash)
 spawnProcess("direct-terminal", "node", [resolve(__dirname, "direct-terminal-ws.js")], { restart: true });
 // Graceful shutdown — send SIGTERM to children and wait for them to exit

package/next.config.js

@@ -3,6 +3,7 @@ const nextConfig = {
   transpilePackages: [
     "@aoagents/ao-core",
     "@aoagents/ao-plugin-agent-claude-code",
+    "@aoagents/ao-plugin-agent-codex",
     "@aoagents/ao-plugin-agent-opencode",
     "@aoagents/ao-plugin-runtime-tmux",
     "@aoagents/ao-plugin-scm-github",
@@ -10,6 +11,10 @@ const nextConfig = {
     "@aoagents/ao-plugin-tracker-linear",
     "@aoagents/ao-plugin-workspace-worktree",
   ],
+  serverExternalPackages: [
+    "yaml",
+    "zod",
+  ],
   async headers() {
     return [
       {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aoagents/ao-web",
-  "version": "0.2.4",
+  "version": "0.3.0",
   "description": "Web dashboard for agent-orchestrator",
   "type": "module",
   "files": [
@@ -14,21 +14,23 @@
   "dependencies": {
     "@xterm/addon-fit": "^0.11.0",
     "@xterm/addon-web-links": "^0.12.0",
+    "@xterm/xterm": "^6.0.0",
     "next": "^15.1.0",
     "next-themes": "^0.4.6",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "server-only": "^0.0.1",
     "ws": "^8.19.0",
-    "xterm": "^5.3.0",
-    "@aoagents/ao-core": "0.2.2",
-    "@aoagents/ao-plugin-runtime-tmux": "0.2.2",
-    "@aoagents/ao-plugin-tracker-github": "0.2.2",
-    "@aoagents/ao-plugin-tracker-linear": "0.2.2",
-    "@aoagents/ao-plugin-workspace-worktree": "0.2.2",
-    "@aoagents/ao-plugin-scm-github": "0.2.2",
-    "@aoagents/ao-plugin-agent-claude-code": "0.2.2",
-    "@aoagents/ao-plugin-agent-opencode": "0.2.2"
+    "@aoagents/ao-core": "0.3.0",
+    "@aoagents/ao-plugin-agent-claude-code": "0.3.0",
+    "@aoagents/ao-plugin-agent-codex": "0.3.0",
+    "@aoagents/ao-plugin-agent-opencode": "0.3.0",
+    "@aoagents/ao-plugin-agent-cursor": "0.1.1",
+    "@aoagents/ao-plugin-runtime-tmux": "0.3.0",
+    "@aoagents/ao-plugin-scm-github": "0.3.0",
+    "@aoagents/ao-plugin-tracker-github": "0.3.0",
+    "@aoagents/ao-plugin-tracker-linear": "0.3.0",
+    "@aoagents/ao-plugin-workspace-worktree": "0.3.0"
   },
   "optionalDependencies": {
     "node-pty": "^1.1.0"
@@ -47,24 +49,25 @@
     "jsdom": "^25.0.0",
     "node-gyp": "^12.2.0",
     "playwright": "^1.49.0",
+    "rimraf": "^6.0.0",
     "tailwindcss": "^4.0.0",
     "tsx": "^4.19.0",
     "typescript": "^5.7.0",
     "vitest": "^2.1.0"
   },
   "scripts": {
-    "dev": "concurrently \"npm:dev:next\" \"npm:dev:terminal\" \"npm:dev:direct-terminal\"",
+    "dev": "concurrently \"npm:dev:next\" \"npm:dev:direct-terminal\"",
     "dev:next": "next dev -p ${PORT:-3000}",
-    "dev:terminal": "tsx watch server/terminal-websocket.ts",
-    "dev:direct-terminal": "tsx watch server/direct-terminal-ws.ts",
+    "dev:direct-terminal": "node scripts/dev-direct-terminal.mjs",
+    "prebuild": "rimraf .next dist-server",
     "build": "next build && tsc -p tsconfig.server.json",
     "start": "next start",
     "start:all": "node dist-server/start-all.js",
-    "dev:optimized": "next build && tsc -p tsconfig.server.json && node dist-server/start-all.js",
+    "dev:optimized": "rimraf .next dist-server && next build && tsc -p tsconfig.server.json && node dist-server/start-all.js",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",
-    "clean": "rm -rf .next dist-server",
+    "clean": "rimraf .next dist-server",
     "screenshot": "tsx e2e/screenshot.ts",
     "screenshot:install": "npx playwright install chromium"
   }