@aoagents/ao-web 0.2.2

package/dist-server/direct-terminal-ws.js

@@ -0,0 +1,297 @@
+/**
+ * Direct WebSocket terminal server using node-pty.
+ * Connects browser xterm.js directly to tmux sessions via WebSocket.
+ *
+ * This bypasses ttyd and gives us control over terminal initialization,
+ * allowing us to implement the XDA (Extended Device Attributes) handler
+ * that tmux requires for clipboard support.
+ */
+import { createServer } from "node:http";
+import { spawn } from "node:child_process";
+import { WebSocketServer, WebSocket } from "ws";
+import { homedir, userInfo } from "node:os";
+import { createCorrelationId } from "@aoagents/ao-core";
+let ptySpawn;
+/* eslint-enable @typescript-eslint/consistent-type-imports */
+try {
+    const nodePty = await import("node-pty");
+    ptySpawn = nodePty.spawn;
+}
+catch {
+    console.warn("[DirectTerminal] node-pty not available — direct terminal will be disabled.");
+    console.warn("[DirectTerminal] Install it with: npm install node-pty");
+}
+import { findTmux, resolveTmuxSession, validateSessionId } from "./tmux-utils.js";
+import { createObserverContext, inferProjectId } from "./terminal-observability.js";
+/**
+ * Create the direct terminal WebSocket server.
+ * Separated from listen() so tests can control lifecycle.
+ */
+export function createDirectTerminalServer(tmuxPath) {
+    const TMUX = tmuxPath ?? findTmux();
+    const activeSessions = new Map();
+    const { config, observer } = createObserverContext("terminal-direct-websocket");
+    const metrics = {
+        activeConnections: 0,
+        totalConnections: 0,
+        totalDisconnects: 0,
+        totalErrors: 0,
+        lastConnectedAt: null,
+        lastDisconnectedAt: null,
+        lastErrorAt: null,
+        lastDisconnectReason: null,
+        lastErrorReason: null,
+    };
+    const server = createServer((req, res) => {
+        if (req.url === "/health") {
+            res.writeHead(200, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({
+                active: activeSessions.size,
+                sessions: Array.from(activeSessions.keys()),
+                metrics,
+            }));
+            return;
+        }
+        res.writeHead(404);
+        res.end("Not found");
+    });
+    const wss = new WebSocketServer({
+        server,
+        path: "/ws",
+    });
+    const recordWebsocketMetric = (input) => {
+        if (!observer) {
+            return;
+        }
+        const correlationId = createCorrelationId("ws");
+        observer.recordOperation({
+            metric: input.metric,
+            operation: `terminal.websocket.${input.metric}`,
+            outcome: input.outcome,
+            correlationId,
+            projectId: input.sessionId ? inferProjectId(config, input.sessionId) : undefined,
+            sessionId: input.sessionId,
+            reason: input.reason,
+            data: input.data,
+            level: input.outcome === "failure" ? "error" : "info",
+        });
+    };
+    wss.on("connection", (ws, req) => {
+        if (!ptySpawn) {
+            ws.close(1011, "Direct terminal unavailable — node-pty not installed");
+            return;
+        }
+        const url = new URL(req.url ?? "/", "ws://localhost");
+        const sessionId = url.searchParams.get("session");
+        if (!sessionId) {
+            console.error("[DirectTerminal] Missing session parameter");
+            recordWebsocketMetric({
+                metric: "websocket_error",
+                outcome: "failure",
+                reason: "Missing session parameter",
+            });
+            ws.close(1008, "Missing session parameter");
+            return;
+        }
+        // Validate session ID format
+        if (!validateSessionId(sessionId)) {
+            console.error("[DirectTerminal] Invalid session ID:", sessionId);
+            recordWebsocketMetric({
+                metric: "websocket_error",
+                outcome: "failure",
+                sessionId,
+                reason: "Invalid session ID",
+            });
+            ws.close(1008, "Invalid session ID");
+            return;
+        }
+        // Resolve tmux session name: try exact match first, then suffix match
+        // (hash-prefixed sessions like "8474d6f29887-ao-15" are accessed by user-facing ID "ao-15")
+        const tmuxSessionId = resolveTmuxSession(sessionId, TMUX);
+        if (!tmuxSessionId) {
+            console.error("[DirectTerminal] tmux session not found:", sessionId);
+            recordWebsocketMetric({
+                metric: "websocket_error",
+                outcome: "failure",
+                sessionId,
+                reason: "Session not found",
+            });
+            ws.close(1008, "Session not found");
+            return;
+        }
+        console.log(`[DirectTerminal] New connection for session: ${tmuxSessionId}`);
+        // Enable mouse mode for scrollback support
+        const mouseProc = spawn(TMUX, ["set-option", "-t", tmuxSessionId, "mouse", "on"]);
+        mouseProc.on("error", (err) => {
+            console.error(`[DirectTerminal] Failed to set mouse mode for ${tmuxSessionId}:`, err.message);
+        });
+        // Hide the green status bar for cleaner appearance
+        const statusProc = spawn(TMUX, ["set-option", "-t", tmuxSessionId, "status", "off"]);
+        statusProc.on("error", (err) => {
+            console.error(`[DirectTerminal] Failed to hide status bar for ${tmuxSessionId}:`, err.message);
+        });
+        // Build complete environment - node-pty requires proper env setup
+        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",
+        };
+        let pty;
+        try {
+            console.log(`[DirectTerminal] Spawning PTY: tmux attach-session -t ${tmuxSessionId}`);
+            pty = ptySpawn(TMUX, ["attach-session", "-t", tmuxSessionId], {
+                name: "xterm-256color",
+                cols: 80,
+                rows: 24,
+                cwd: homeDir,
+                env,
+            });
+            console.log(`[DirectTerminal] PTY spawned successfully`);
+        }
+        catch (err) {
+            console.error(`[DirectTerminal] Failed to spawn PTY:`, err);
+            recordWebsocketMetric({
+                metric: "websocket_error",
+                outcome: "failure",
+                sessionId,
+                reason: err instanceof Error ? err.message : String(err),
+            });
+            ws.close(1011, `Failed to spawn terminal: ${err instanceof Error ? err.message : String(err)}`);
+            return;
+        }
+        const session = { sessionId, pty, ws };
+        activeSessions.set(sessionId, session);
+        metrics.totalConnections += 1;
+        metrics.activeConnections = activeSessions.size;
+        metrics.lastConnectedAt = new Date().toISOString();
+        recordWebsocketMetric({
+            metric: "websocket_connect",
+            outcome: "success",
+            sessionId,
+            data: { activeConnections: metrics.activeConnections },
+        });
+        let disconnectRecorded = false;
+        const recordDisconnect = (outcome, reason) => {
+            if (disconnectRecorded)
+                return;
+            disconnectRecorded = true;
+            const activeConnections = activeSessions.size;
+            metrics.activeConnections = activeConnections;
+            metrics.totalDisconnects += 1;
+            metrics.lastDisconnectedAt = new Date().toISOString();
+            metrics.lastDisconnectReason = reason;
+            recordWebsocketMetric({
+                metric: "websocket_disconnect",
+                outcome,
+                sessionId,
+                reason,
+                data: { activeConnections },
+            });
+        };
+        // PTY -> WebSocket
+        pty.onData((data) => {
+            if (ws.readyState === WebSocket.OPEN) {
+                ws.send(data);
+            }
+        });
+        // PTY exit
+        pty.onExit(({ exitCode }) => {
+            console.log(`[DirectTerminal] PTY exited for ${sessionId} with code ${exitCode}`);
+            // Guard against stale exits: only delete if this pty is still the active one.
+            // A new connection may have already replaced this session entry.
+            if (activeSessions.get(sessionId)?.pty === pty) {
+                activeSessions.delete(sessionId);
+            }
+            recordDisconnect(exitCode === 0 ? "success" : "failure", `pty_exit:${exitCode}`);
+            if (ws.readyState === WebSocket.OPEN) {
+                ws.close(1000, "Terminal session ended");
+            }
+        });
+        // WebSocket -> PTY
+        ws.on("message", (data) => {
+            const message = data.toString("utf8");
+            // Handle resize messages (sent by xterm.js FitAddon)
+            if (message.startsWith("{")) {
+                try {
+                    const parsed = JSON.parse(message);
+                    if (parsed.type === "resize" && parsed.cols && parsed.rows) {
+                        pty.resize(parsed.cols, parsed.rows);
+                        return;
+                    }
+                }
+                catch {
+                    // Not JSON, treat as terminal input
+                }
+            }
+            // Normal terminal input
+            pty.write(message);
+        });
+        // WebSocket close
+        ws.on("close", () => {
+            console.log(`[DirectTerminal] WebSocket closed for ${sessionId}`);
+            // Guard against stale closes replacing a newer session's entry
+            if (activeSessions.get(sessionId)?.pty === pty) {
+                activeSessions.delete(sessionId);
+            }
+            recordDisconnect("success", "ws_close");
+            pty.kill();
+        });
+        // WebSocket error
+        ws.on("error", (err) => {
+            console.error(`[DirectTerminal] WebSocket error for ${sessionId}:`, err.message);
+            // Guard against stale error handlers replacing a newer session's entry
+            if (activeSessions.get(sessionId)?.pty === pty) {
+                activeSessions.delete(sessionId);
+            }
+            recordDisconnect("failure", `ws_error:${err.message}`);
+            metrics.totalErrors += 1;
+            metrics.lastErrorAt = new Date().toISOString();
+            metrics.lastErrorReason = err.message;
+            recordWebsocketMetric({
+                metric: "websocket_error",
+                outcome: "failure",
+                sessionId,
+                reason: err.message,
+            });
+            pty.kill();
+        });
+    });
+    function shutdown() {
+        for (const [, session] of activeSessions) {
+            session.pty.kill();
+            session.ws.close(1001, "Server shutting down");
+        }
+        server.close();
+    }
+    return { server, wss, activeSessions, shutdown };
+}
+// --- Run as standalone script ---
+// Only start the server when executed directly (not imported by tests)
+const isMainModule = process.argv[1]?.endsWith("direct-terminal-ws.ts") ||
+    process.argv[1]?.endsWith("direct-terminal-ws.js");
+if (isMainModule) {
+    const TMUX = findTmux();
+    console.log(`[DirectTerminal] Using tmux: ${TMUX}`);
+    const { server, shutdown } = createDirectTerminalServer(TMUX);
+    const PORT = parseInt(process.env.DIRECT_TERMINAL_PORT ?? "14801", 10);
+    server.listen(PORT, () => {
+        console.log(`[DirectTerminal] WebSocket server listening on port ${PORT}`);
+    });
+    function handleShutdown(signal) {
+        console.log(`[DirectTerminal] Received ${signal}, shutting down...`);
+        shutdown();
+        const forceExitTimer = setTimeout(() => {
+            console.error("[DirectTerminal] Forced shutdown after timeout");
+            process.exit(1);
+        }, 5000);
+        forceExitTimer.unref();
+    }
+    process.on("SIGINT", () => handleShutdown("SIGINT"));
+    process.on("SIGTERM", () => handleShutdown("SIGTERM"));
+}

package/dist-server/start-all.js

@@ -0,0 +1,113 @@
+/**
+ * Production entry point — starts Next.js + terminal servers.
+ * Used by `ao start` when running from an npm install (no monorepo).
+ * Replaces the dev-only `concurrently` setup.
+ */
+import { spawn } from "node:child_process";
+import { resolve, dirname } from "node:path";
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { createRequire } from "node:module";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+// Resolve paths relative to the package root (one level up from dist-server/)
+const pkgRoot = resolve(__dirname, "..");
+const children = [];
+function log(label, msg) {
+    process.stdout.write(`[${label}] ${msg}\n`);
+}
+function spawnProcess(label, command, args, opts) {
+    let restarts = 0;
+    const maxRestarts = opts?.maxRestarts ?? 3;
+    let slotIndex = -1;
+    function launch() {
+        const child = spawn(command, args, {
+            cwd: pkgRoot,
+            stdio: ["ignore", "pipe", "pipe"],
+            env: process.env,
+        });
+        child.stdout?.on("data", (data) => {
+            for (const line of data.toString().split("\n").filter(Boolean)) {
+                log(label, line);
+            }
+        });
+        child.stderr?.on("data", (data) => {
+            for (const line of data.toString().split("\n").filter(Boolean)) {
+                log(label, line);
+            }
+        });
+        child.on("exit", (code) => {
+            log(label, `exited with code ${code}`);
+            if (!shuttingDown && opts?.restart && code !== 0 && restarts < maxRestarts) {
+                restarts++;
+                log(label, `restarting (attempt ${restarts}/${maxRestarts})`);
+                const replacement = launch();
+                // Replace in-place — slot was assigned on first push
+                children[slotIndex] = replacement;
+            }
+        });
+        // Only push on first launch; restarts replace the existing slot
+        if (slotIndex === -1) {
+            slotIndex = children.length;
+            children.push(child);
+        }
+        return child;
+    }
+    return launch();
+}
+/**
+ * Resolve the `next` CLI binary path.
+ * Tries the local .bin shim first (fast), then falls back to require.resolve (hoisted deps).
+ */
+function resolveNextBin() {
+    const localBin = resolve(pkgRoot, "node_modules", ".bin", "next");
+    if (existsSync(localBin))
+        return localBin;
+    // Hoisted node_modules — resolve the actual next CLI entry
+    const require = createRequire(resolve(pkgRoot, "package.json"));
+    try {
+        const nextPkg = require.resolve("next/package.json");
+        return resolve(dirname(nextPkg), "dist", "bin", "next");
+    }
+    catch {
+        // Last resort — rely on PATH
+        return "next";
+    }
+}
+// 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
+let shuttingDown = false;
+function cleanup() {
+    if (shuttingDown)
+        return;
+    shuttingDown = true;
+    let alive = children.length;
+    if (alive === 0) {
+        process.exit(0);
+        return;
+    }
+    // Force exit after 5s if children don't exit cleanly
+    const forceTimer = setTimeout(() => {
+        log("start-all", "Children did not exit in time, forcing shutdown");
+        process.exit(1);
+    }, 5000);
+    forceTimer.unref();
+    for (const child of children) {
+        child.on("exit", () => {
+            alive--;
+            if (alive <= 0) {
+                clearTimeout(forceTimer);
+                process.exit(0);
+            }
+        });
+        child.kill("SIGTERM");
+    }
+}
+process.on("SIGINT", cleanup);
+process.on("SIGTERM", cleanup);

package/dist-server/terminal-observability.js

@@ -0,0 +1,16 @@
+import { createProjectObserver, loadConfig, resolveProjectIdForSessionId, } from "@aoagents/ao-core";
+export function createObserverContext(surface) {
+    try {
+        const config = loadConfig();
+        return {
+            config,
+            observer: createProjectObserver(config, surface),
+        };
+    }
+    catch {
+        return { config: undefined, observer: undefined };
+    }
+}
+export function inferProjectId(config, sessionId) {
+    return config ? resolveProjectIdForSessionId(config, sessionId) : undefined;
+}