@aoagents/ao-web 0.3.0 → 0.4.0

package/dist-server/mux-websocket.js

@@ -2,46 +2,77 @@
  * 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.
+ * Session updates are delivered via polling of Next.js /api/sessions/patches
+ * every 3s, then broadcast to all subscribed clients via WebSocket.
  */
 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.
+ * Manages polling of session patches from Next.js /api/sessions/patches.
+ * Broadcasts to all subscribed callbacks.
+ * Lazily starts polling on first subscriber, stops when the last one leaves.
  */
 export class SessionBroadcaster {
     subscribers = new Set();
-    abortController = null;
-    reconnectTimer = null;
+    errorSubscribers = new Set();
+    intervalId = null;
+    polling = false;
     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 to session patches and errors. Returns an unsubscribe function.
+     * Sends an immediate snapshot to the new subscriber, then polling updates.
      */
-    subscribe(callback) {
+    subscribe(callback, onError) {
         const wasEmpty = this.subscribers.size === 0;
         this.subscribers.add(callback);
+        if (onError)
+            this.errorSubscribers.add(onError);
         // Immediately send a one-off snapshot to just this new subscriber
-        void this.fetchSnapshot().then((sessions) => {
-            if (sessions && this.subscribers.has(callback)) {
-                callback(sessions);
+        void this.fetchSnapshot().then((result) => {
+            if (result.sessions && this.subscribers.has(callback)) {
+                try {
+                    callback(result.sessions);
+                }
+                catch {
+                    // Isolate subscriber errors so one bad subscriber doesn't break others
+                }
+            }
+            else if (result.error && onError && this.errorSubscribers.has(onError)) {
+                try {
+                    onError(result.error);
+                }
+                catch {
+                    // Isolate subscriber errors
+                }
             }
         });
-        // Start the shared SSE connection if this is the first subscriber
+        // Start polling if this is the first subscriber
         if (wasEmpty) {
-            void this.connect();
+            this.intervalId = setInterval(() => {
+                if (this.polling)
+                    return;
+                this.polling = true;
+                void this.fetchSnapshot()
+                    .then((result) => {
+                    if (result.sessions && this.intervalId !== null)
+                        this.broadcast(result.sessions);
+                    else if (result.error && this.intervalId !== null)
+                        this.broadcastError(result.error);
+                })
+                    .finally(() => {
+                    this.polling = false;
+                });
+            }, 3000);
         }
         return () => {
             this.subscribers.delete(callback);
+            if (onError)
+                this.errorSubscribers.delete(onError);
             if (this.subscribers.size === 0) {
                 this.disconnect();
             }
@@ -57,99 +88,45 @@ export class SessionBroadcaster {
             }
         }
     }
-    /** 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);
+    broadcastError(error) {
+        for (const callback of this.errorSubscribers) {
             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;
+                callback(error);
             }
-            catch {
-                clearTimeout(timeoutId);
-                return null;
+            catch (err) {
+                console.error("[MuxServer] Session error subscriber threw:", err);
             }
         }
-        catch {
-            return null;
-        }
     }
-    /** Open a persistent SSE connection and stream events to all subscribers. */
-    async connect() {
-        if (this.abortController)
-            return;
+    /** One-shot HTTP fetch of the current session list. */
+    async fetchSnapshot() {
         const controller = new AbortController();
-        this.abortController = controller;
-        const { signal } = controller;
+        const timeoutId = setTimeout(() => controller.abort(), 4000);
         try {
-            const res = await fetch(`${this.baseUrl}/api/events`, {
-                signal,
-                headers: { Accept: "text/event-stream" },
+            const res = await fetch(`${this.baseUrl}/api/sessions/patches`, {
+                signal: controller.signal,
             });
-            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
-                    }
-                }
+            clearTimeout(timeoutId);
+            if (!res.ok) {
+                const msg = `Session fetch failed: HTTP ${res.status}`;
+                console.warn(`[SessionBroadcaster] ${msg}`);
+                return { sessions: null, error: msg };
             }
+            const data = (await res.json());
+            return { sessions: data.sessions ?? null, error: null };
         }
         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);
+            clearTimeout(timeoutId);
+            const msg = err instanceof Error ? err.message : String(err);
+            console.warn("[SessionBroadcaster] fetchSnapshot error:", msg);
+            return { sessions: null, error: msg };
         }
     }
     disconnect() {
-        if (this.reconnectTimer) {
-            clearTimeout(this.reconnectTimer);
-            this.reconnectTimer = null;
+        if (this.intervalId !== null) {
+            clearInterval(this.intervalId);
+            this.intervalId = null;
         }
-        this.abortController?.abort();
-        this.abortController = null;
     }
 }
 let ptySpawn;
@@ -162,6 +139,7 @@ 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 WS_BUFFER_HIGH_WATERMARK = 64 * 1024; // 64KB
 const MAX_REATTACH_ATTEMPTS = 3;
 /**
  * TerminalManager manages PTY processes independently of WebSocket connections.
@@ -173,21 +151,29 @@ class TerminalManager {
     constructor(tmuxPath) {
         this.TMUX = tmuxPath ?? findTmux();
     }
+    terminalKey(id, projectId) {
+        return projectId ? `${projectId}:${id}` : id;
+    }
     /**
      * Open/attach to a terminal. If already open, just return.
      * If has subscribers but PTY crashed, re-attach.
      */
-    open(id) {
+    open(id, projectId, tmuxName) {
         // Validate and resolve
         if (!validateSessionId(id)) {
             throw new Error(`Invalid session ID: ${id}`);
         }
-        const tmuxSessionId = resolveTmuxSession(id, this.TMUX);
+        // Use provided tmuxName, or reuse from existing terminal entry, or resolve
+        const key = this.terminalKey(id, projectId);
+        const existing = this.terminals.get(key);
+        const tmuxSessionId = tmuxName ??
+            existing?.tmuxSessionId ??
+            resolveTmuxSession(id, this.TMUX, undefined, undefined, projectId);
         if (!tmuxSessionId) {
             throw new Error(`Session not found: ${id}`);
         }
         // Get or create terminal entry
-        let terminal = this.terminals.get(id);
+        let terminal = this.terminals.get(key);
         if (!terminal) {
             terminal = {
                 id,
@@ -199,7 +185,7 @@ class TerminalManager {
                 bufferBytes: 0,
                 reattachAttempts: 0,
             };
-            this.terminals.set(id, terminal);
+            this.terminals.set(key, terminal);
         }
         // If PTY is already attached, we're done
         if (terminal.pty) {
@@ -271,7 +257,7 @@ class TerminalManager {
                 terminal.reattachAttempts += 1;
                 console.log(`[MuxServer] Re-attaching to ${id} (attempt ${terminal.reattachAttempts}/${MAX_REATTACH_ATTEMPTS})`);
                 try {
-                    this.open(id);
+                    this.open(id, projectId);
                     terminal.reattachAttempts = 0; // reset on successful attach
                     return; // re-attached — don't notify exit
                 }
@@ -293,8 +279,8 @@ class TerminalManager {
     /**
      * Write data to the PTY if attached
      */
-    write(id, data) {
-        const terminal = this.terminals.get(id);
+    write(id, data, projectId) {
+        const terminal = this.terminals.get(this.terminalKey(id, projectId));
         if (terminal?.pty) {
             terminal.pty.write(data);
         }
@@ -302,8 +288,8 @@ class TerminalManager {
     /**
      * Resize the PTY if attached
      */
-    resize(id, cols, rows) {
-        const terminal = this.terminals.get(id);
+    resize(id, cols, rows, projectId) {
+        const terminal = this.terminals.get(this.terminalKey(id, projectId));
         if (terminal?.pty) {
             terminal.pty.resize(cols, rows);
         }
@@ -313,10 +299,11 @@ class TerminalManager {
      * Automatically opens the terminal if needed.
      * @param onExit - called when the PTY exits and cannot be re-attached
      */
-    subscribe(id, callback, onExit) {
+    subscribe(id, projectId, callback, onExit) {
         // Ensure terminal is open
-        this.open(id);
-        const terminal = this.terminals.get(id);
+        this.open(id, projectId);
+        const key = this.terminalKey(id, projectId);
+        const terminal = this.terminals.get(key);
         if (!terminal) {
             throw new Error(`Failed to open terminal: ${id}`);
         }
@@ -335,15 +322,15 @@ class TerminalManager {
                     terminal.pty.kill();
                     terminal.pty = null;
                 }
-                this.terminals.delete(id);
+                this.terminals.delete(key);
             }
         };
     }
     /**
      * Get buffered data for a terminal
      */
-    getBuffer(id) {
-        const terminal = this.terminals.get(id);
+    getBuffer(id, projectId) {
+        const terminal = this.terminals.get(this.terminalKey(id, projectId));
         if (!terminal)
             return "";
         return terminal.buffer.join("");
@@ -400,60 +387,75 @@ export function createMuxWebSocket(tmuxPath) {
                 }
                 else if (msg.ch === "terminal") {
                     const { id, type } = msg;
+                    const projectId = "projectId" in msg ? msg.projectId : undefined;
+                    const subscriptionKey = projectId ? `${projectId}:${id}` : id;
                     try {
                         if (type === "open") {
                             // Validate session exists
-                            terminalManager.open(id);
+                            terminalManager.open(id, projectId, "tmuxName" in msg ? msg.tmuxName : undefined);
                             // Send opened confirmation (idempotent — safe to send on re-open)
-                            const openedMsg = { ch: "terminal", id, type: "opened" };
+                            const openedMsg = {
+                                ch: "terminal",
+                                id,
+                                type: "opened",
+                                ...(projectId && { projectId }),
+                            };
                             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)) {
+                            if (!subscriptions.has(subscriptionKey)) {
                                 // Send buffered history to catch up the new subscriber
-                                const buffer = terminalManager.getBuffer(id);
+                                const buffer = terminalManager.getBuffer(id, projectId);
                                 if (buffer) {
                                     const bufferMsg = {
                                         ch: "terminal",
                                         id,
                                         type: "data",
                                         data: buffer,
+                                        ...(projectId && { projectId }),
                                     };
                                     ws.send(JSON.stringify(bufferMsg));
                                 }
-                                const unsub = terminalManager.subscribe(id, (data) => {
+                                const unsub = terminalManager.subscribe(id, projectId, (data) => {
                                     const dataMsg = {
                                         ch: "terminal",
                                         id,
                                         type: "data",
                                         data,
+                                        ...(projectId && { projectId }),
                                     };
                                     if (ws.readyState === WebSocket.OPEN) {
                                         ws.send(JSON.stringify(dataMsg));
                                     }
                                 }, (exitCode) => {
-                                    const exitedMsg = { ch: "terminal", id, type: "exited", code: exitCode };
+                                    const exitedMsg = {
+                                        ch: "terminal",
+                                        id,
+                                        type: "exited",
+                                        code: exitCode,
+                                        ...(projectId && { projectId }),
+                                    };
                                     if (ws.readyState === WebSocket.OPEN) {
                                         ws.send(JSON.stringify(exitedMsg));
                                     }
                                 });
-                                subscriptions.set(id, unsub);
+                                subscriptions.set(subscriptionKey, unsub);
                             }
                         }
                         else if (type === "data" && "data" in msg) {
-                            terminalManager.write(id, msg.data);
+                            terminalManager.write(id, msg.data, projectId);
                         }
                         else if (type === "resize" && "cols" in msg && "rows" in msg) {
-                            terminalManager.resize(id, msg.cols, msg.rows);
+                            terminalManager.resize(id, msg.cols, msg.rows, projectId);
                         }
                         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);
+                            const unsub = subscriptions.get(subscriptionKey);
                             if (unsub) {
                                 unsub();
-                                subscriptions.delete(id);
+                                subscriptions.delete(subscriptionKey);
                             }
                         }
                     }
@@ -464,6 +466,7 @@ export function createMuxWebSocket(tmuxPath) {
                                 id,
                                 type: "error",
                                 message: err instanceof Error ? err.message : String(err),
+                                ...(projectId && { projectId }),
                             };
                             ws.send(JSON.stringify(errorMsg));
                         }
@@ -472,10 +475,19 @@ export function createMuxWebSocket(tmuxPath) {
                 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));
+                            if (ws.readyState !== WebSocket.OPEN)
+                                return;
+                            if (ws.bufferedAmount > WS_BUFFER_HIGH_WATERMARK) {
+                                console.warn("[MuxServer] Skipping session snapshot — socket backpressured");
+                                return;
                             }
+                            const snapMsg = { ch: "sessions", type: "snapshot", sessions };
+                            ws.send(JSON.stringify(snapMsg));
+                        }, (error) => {
+                            if (ws.readyState !== WebSocket.OPEN)
+                                return;
+                            const errMsg = { ch: "sessions", type: "error", error };
+                            ws.send(JSON.stringify(errMsg));
                         });
                     }
                 }

package/dist-server/tmux-utils.js

@@ -5,10 +5,74 @@
  * so the logic can be properly unit tested.
  */
 import { execFileSync } from "node:child_process";
+import { readdirSync, existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
 /** Session ID validation regex — alphanumeric, hyphens, underscores only */
 export const SESSION_ID_PATTERN = /^[a-zA-Z0-9_-]+$/;
 /** Hash prefix pattern — 12-char lowercase hex, as generated by generateConfigHash */
 const HASH_PREFIX_PATTERN = /^[a-f0-9]{12}-/;
+/**
+ * StorageKey pattern — either bare 12-hex hash or `{hash}-{projectName}`
+ * wrapped form. The wrapped suffix comes from `basename(projectPath)` on
+ * disk so it can contain any character a filesystem path component allows
+ * (spaces, unicode, etc.); we only require that something non-empty
+ * follows the `-` separator. Security: storageKey is passed to
+ * `execFileSync` which bypasses the shell, so arbitrary characters are
+ * safe in the argv.
+ */
+const STORAGE_KEY_PATTERN = /^[a-f0-9]{12}(-.+)?$/;
+const defaultFs = {
+    // Only return subdirectory names. `readdirSync` without withFileTypes
+    // includes plain files, so a stray file like `aabbccddeef0` would pass
+    // STORAGE_KEY_PATTERN and trigger an unnecessary existsSync probe.
+    readdir: (p) => readdirSync(p, { withFileTypes: true })
+        .filter((e) => e.isDirectory())
+        .map((e) => e.name),
+    exists: (p) => existsSync(p),
+    homedir,
+};
+/**
+ * Find every storageKey that owns a given sessionId by scanning the AO
+ * base directory for projects whose `sessions/{sessionId}` file exists.
+ *
+ * This is the authoritative disambiguation step: tmux names alone are
+ * ambiguous when storageKey can take either the bare-hash or wrapped
+ * `{hash}-{projectName}` form. The on-disk session record is unique per
+ * storageKey so it tells us exactly which tmux name to expect.
+ *
+ * Returns all candidates (not just the first). Multiple projects can
+ * share a sessionId like `app-1`, and the caller must probe each until
+ * it finds a live tmux session — otherwise a stale metadata dir from
+ * one project could shadow the live session of another.
+ */
+function findStorageKeysForSession(sessionId, fs, projectId) {
+    const aoBase = join(fs.homedir(), ".agent-orchestrator");
+    let entries;
+    try {
+        entries = fs.readdir(aoBase);
+    }
+    catch {
+        return [];
+    }
+    const matches = [];
+    const projectMatches = [];
+    for (const entry of entries) {
+        if (!STORAGE_KEY_PATTERN.test(entry))
+            continue;
+        const sessionFile = join(aoBase, entry, "sessions", sessionId);
+        if (fs.exists(sessionFile)) {
+            const unwrappedProjectId = entry.slice(13); // Strip "{hash}-" prefix when present.
+            if (projectId && (entry === projectId || unwrappedProjectId === projectId)) {
+                projectMatches.push(entry);
+            }
+            else {
+                matches.push(entry);
+            }
+        }
+    }
+    return [...projectMatches, ...matches];
+}
 /**
  * Validate a session ID format.
  * Prevents path traversal, shell injection, and other attacks.
@@ -45,20 +109,29 @@ export function findTmux(execFn = execFileSync) {
 /**
  * Resolve a user-facing session ID to its actual tmux session name.
  *
- * The hash-based architecture prefixes tmux session names with a config hash
- * (e.g., "8474d6f29887-ao-15" for user-facing "ao-15"). This function:
+ * ao-core names tmux sessions as `{storageKey}-{sessionId}`, where
+ * storageKey is either `{12-hex}` (bare hash) or `{12-hex}-{projectName}`
+ * (legacy wrapped format). This function:
  *
- * 1. Tries exact match first using tmux's `=` prefix syntax to prevent
+ * 1. Tries exact match using tmux's `=` prefix syntax to prevent
  *    prefix matching (where "ao-1" would incorrectly match "ao-15").
- * 2. Falls back to listing all sessions and finding one with a 12-char hex
- *    prefix followed by the exact session ID (e.g., `{12-hex}-{sessionId}`).
+ * 2. Looks up the storageKey owning this sessionId on disk (under
+ *    `~/.agent-orchestrator/{storageKey}/sessions/{sessionId}`) and asks
+ *    tmux whether the exact `{storageKey}-{sessionId}` session exists.
+ *    The on-disk check is authoritative — it avoids ambiguous suffix
+ *    matches where a bare session like `{hash}-my-app-1` could be
+ *    mistaken for a lookup of `app-1`.
+ * 3. Falls back to listing sessions and matching a hash-prefixed name
+ *    whose remainder equals the sessionId (bare-hash only), so behavior
+ *    stays correct even if the on-disk session record is absent.
  *
  * @param sessionId - User-facing session ID (e.g., "ao-15")
  * @param tmuxPath - Full path to tmux binary
  * @param execFn - Injectable execFileSync for testing. Defaults to child_process.execFileSync.
+ * @param fs - Injectable filesystem adapter for testing.
  * @returns The actual tmux session name, or null if not found
  */
-export function resolveTmuxSession(sessionId, tmuxPath, execFn = execFileSync) {
+export function resolveTmuxSession(sessionId, tmuxPath, execFn = execFileSync, fs = defaultFs, projectId) {
     // Try exact match first using = prefix for exact matching (e.g., "ao-orchestrator")
     // Without =, tmux uses prefix matching: "ao-1" would match "ao-15"
     try {
@@ -68,9 +141,26 @@ export function resolveTmuxSession(sessionId, tmuxPath, execFn = execFileSync) {
     catch {
         // Not an exact match
     }
-    // Search for hash-prefixed tmux session (e.g., "8474d6f29887-ao-15" for "ao-15")
-    // Validate the 12-char hex prefix to avoid ambiguous suffix matches where
-    // "hash-my-app-1" could falsely match a lookup for "app-1".
+    // Authoritative path: find candidate storageKeys on disk, then verify
+    // each exact tmux session name with has-session. This is unambiguous
+    // even when the storageKey is wrapped (`{hash}-{projectName}`). Walk
+    // every candidate so a stale metadata dir in one project can't shadow
+    // the live session of another project with the same sessionId.
+    for (const storageKey of findStorageKeysForSession(sessionId, fs, projectId)) {
+        const tmuxName = `${storageKey}-${sessionId}`;
+        try {
+            execFn(tmuxPath, ["has-session", "-t", `=${tmuxName}`], { timeout: 5000 });
+            return tmuxName;
+        }
+        catch {
+            // Session dir exists but tmux session doesn't — try next candidate
+        }
+    }
+    // Fallback: list sessions and match the bare-hash form only. We
+    // intentionally do NOT match by trailing suffix here — that would cause
+    // `app-1` to falsely resolve a distinct session `{hash}-my-app-1`. If a
+    // wrapped-storageKey session isn't findable on disk above, it's safer
+    // to return null than to guess.
     try {
         const output = execFn(tmuxPath, ["list-sessions", "-F", "#{session_name}"], {
             timeout: 5000,

package/next.config.js

@@ -1,5 +1,11 @@
+import path from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
 /** @type {import('next').NextConfig} */
 const nextConfig = {
+  outputFileTracingRoot: path.join(__dirname, "../.."),
   transpilePackages: [
     "@aoagents/ao-core",
     "@aoagents/ao-plugin-agent-claude-code",