@aoagents/ao-web 0.2.2

package/dist-server/terminal-websocket.js

@@ -0,0 +1,375 @@
+/**
+ * Terminal server that manages ttyd instances for tmux sessions.
+ *
+ * Runs alongside Next.js. Spawns a ttyd process per session on demand,
+ * each on a unique port. The dashboard embeds ttyd via iframe.
+ *
+ * ttyd handles all the hard parts: xterm.js, WebSocket, ANSI rendering,
+ * cursor positioning, resize, input — battle-tested and correct.
+ *
+ * TODO: Add authentication middleware to verify:
+ *   - User is authenticated
+ *   - User owns the requested session
+ *   - Rate limiting for terminal access
+ */
+import { spawn } from "node:child_process";
+import { createServer, request } from "node:http";
+import { createCorrelationId } from "@aoagents/ao-core";
+import { findTmux, resolveTmuxSession, validateSessionId } from "./tmux-utils.js";
+import { createObserverContext, inferProjectId } from "./terminal-observability.js";
+/** Cached full path to tmux binary */
+const TMUX = findTmux();
+console.log(`[Terminal] Using tmux: ${TMUX}`);
+const instances = new Map();
+const metrics = {
+    activeInstances: 0,
+    totalSpawns: 0,
+    totalErrors: 0,
+    totalReused: 0,
+};
+const availablePorts = new Set(); // Pool of recycled ports
+let nextPort = 7800; // Start ttyd instances from port 7800
+const MAX_PORT = 7900; // Prevent unbounded port allocation
+const { config: observabilityConfig, observer } = createObserverContext("terminal-websocket");
+function 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(observabilityConfig, input.sessionId) : undefined,
+        sessionId: input.sessionId,
+        reason: input.reason,
+        data: input.data,
+        level: input.outcome === "failure" ? "error" : "info",
+    });
+}
+/**
+ * Check if ttyd is ready to accept connections by making a test request.
+ * Returns a promise that resolves when ttyd is ready or rejects after timeout.
+ * Properly cancels pending timeouts and requests to prevent memory leaks.
+ */
+function waitForTtyd(port, sessionId, timeoutMs = 3000) {
+    const startTime = Date.now();
+    let timeoutId = null;
+    let pendingReq = null;
+    let settled = false;
+    return new Promise((resolve, reject) => {
+        const cleanup = () => {
+            settled = true;
+            if (timeoutId) {
+                clearTimeout(timeoutId);
+                timeoutId = null;
+            }
+            if (pendingReq) {
+                pendingReq.destroy();
+                pendingReq = null;
+            }
+        };
+        const checkReady = () => {
+            if (settled)
+                return;
+            if (Date.now() - startTime > timeoutMs) {
+                cleanup();
+                reject(new Error(`ttyd did not become ready within ${timeoutMs}ms`));
+                return;
+            }
+            const req = request({
+                hostname: "localhost",
+                port,
+                path: `/${sessionId}/`,
+                method: "GET",
+                timeout: 500,
+            }, (_res) => {
+                // Any response (even 404) means ttyd is listening
+                cleanup();
+                resolve();
+            });
+            pendingReq = req;
+            req.on("timeout", () => {
+                if (settled)
+                    return;
+                req.destroy();
+                pendingReq = null;
+                // Schedule retry but track the timeout ID
+                timeoutId = setTimeout(checkReady, 100);
+            });
+            req.on("error", () => {
+                if (settled)
+                    return;
+                pendingReq = null;
+                // Connection refused or other error - ttyd not ready yet, retry
+                timeoutId = setTimeout(checkReady, 100);
+            });
+            req.end();
+        };
+        checkReady();
+    });
+}
+/**
+ * Spawn or reuse a ttyd instance for a tmux session.
+ *
+ * @param sessionId - User-facing session ID (used for base-path and URL)
+ * @param tmuxSessionName - Actual tmux session name (may be hash-prefixed)
+ */
+function getOrSpawnTtyd(sessionId, tmuxSessionName) {
+    const existing = instances.get(sessionId);
+    if (existing) {
+        metrics.totalReused += 1;
+        recordWebsocketMetric({
+            metric: "websocket_connect",
+            outcome: "success",
+            sessionId,
+            data: { reused: true, port: existing.port },
+        });
+        return existing;
+    }
+    // Allocate port: reuse from pool if available, otherwise increment
+    let port;
+    if (availablePorts.size > 0) {
+        // Reuse a recycled port
+        port = availablePorts.values().next().value;
+        availablePorts.delete(port);
+    }
+    else {
+        // Allocate new port
+        if (nextPort >= MAX_PORT) {
+            throw new Error(`Port exhaustion: reached maximum of ${MAX_PORT - 7800} terminal instances`);
+        }
+        port = nextPort++;
+    }
+    console.log(`[Terminal] Spawning ttyd for ${tmuxSessionName} on port ${port}`);
+    metrics.totalSpawns += 1;
+    metrics.lastSpawnAt = new Date().toISOString();
+    // Enable mouse mode for scrollback support
+    const mouseProc = spawn(TMUX, ["set-option", "-t", tmuxSessionName, "mouse", "on"]);
+    mouseProc.on("error", (err) => {
+        console.error(`[Terminal] Failed to set mouse mode for ${tmuxSessionName}:`, err.message);
+    });
+    // Hide the green status bar for cleaner appearance
+    const statusProc = spawn(TMUX, ["set-option", "-t", tmuxSessionName, "status", "off"]);
+    statusProc.on("error", (err) => {
+        console.error(`[Terminal] Failed to hide status bar for ${tmuxSessionName}:`, err.message);
+    });
+    // Use user-facing sessionId for base-path (matches URL the dashboard uses)
+    // Use tmuxSessionName for tmux attach (may be hash-prefixed)
+    const proc = spawn("ttyd", [
+        "--writable",
+        "--port",
+        String(port),
+        "--base-path",
+        `/${sessionId}`,
+        TMUX,
+        "attach-session",
+        "-t",
+        tmuxSessionName,
+    ], {
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    proc.stdout?.on("data", (data) => {
+        console.log(`[Terminal] ttyd ${sessionId}: ${data.toString().trim()}`);
+    });
+    proc.stderr?.on("data", (data) => {
+        console.log(`[Terminal] ttyd ${sessionId}: ${data.toString().trim()}`);
+    });
+    // Use once() for cleanup handlers to prevent race condition when both exit and error fire
+    proc.once("exit", (code) => {
+        console.log(`[Terminal] ttyd ${sessionId} exited with code ${code}`);
+        // Only delete if this is still the current instance (prevents race with error handler)
+        const current = instances.get(sessionId);
+        if (current?.process === proc) {
+            instances.delete(sessionId);
+            metrics.activeInstances = instances.size;
+            // Only recycle port on clean exit (code 0), not on errors
+            // Failed ttyd processes may leave ports in TIME_WAIT state
+            if (code === 0) {
+                availablePorts.add(port);
+            }
+        }
+        recordWebsocketMetric({
+            metric: "websocket_disconnect",
+            outcome: code === 0 ? "success" : "failure",
+            sessionId,
+            reason: `ttyd_exit:${code}`,
+            data: { port },
+        });
+    });
+    proc.once("error", (err) => {
+        console.error(`[Terminal] ttyd ${sessionId} error:`, err.message);
+        // Only delete if this is still the current instance (prevents race with exit handler)
+        const current = instances.get(sessionId);
+        if (current?.process === proc) {
+            instances.delete(sessionId);
+            metrics.activeInstances = instances.size;
+            // Don't recycle port on error - may still be in use or TIME_WAIT
+        }
+        metrics.totalErrors += 1;
+        metrics.lastErrorAt = new Date().toISOString();
+        metrics.lastErrorReason = err.message;
+        recordWebsocketMetric({
+            metric: "websocket_error",
+            outcome: "failure",
+            sessionId,
+            reason: err.message,
+            data: { port },
+        });
+        // Kill any running process
+        try {
+            proc.kill();
+        }
+        catch {
+            // Ignore kill errors if process already dead
+        }
+    });
+    const instance = { sessionId, port, process: proc };
+    instances.set(sessionId, instance);
+    metrics.activeInstances = instances.size;
+    recordWebsocketMetric({
+        metric: "websocket_connect",
+        outcome: "success",
+        sessionId,
+        data: { reused: false, port },
+    });
+    return instance;
+}
+// Simple HTTP API for the dashboard to request terminal URLs
+const server = createServer(async (req, res) => {
+    const url = new URL(req.url ?? "/", "http://localhost");
+    // CORS for dashboard - allow requests from the same host as the dashboard
+    // TODO: Replace with proper session-based authentication
+    const origin = req.headers.origin;
+    if (origin && origin !== "null") {
+        // Extract hostname from origin and compare with request host
+        try {
+            const originUrl = new URL(origin);
+            const requestHost = req.headers.host;
+            // Allow if origin hostname matches request host (supports remote deployments)
+            if (requestHost && originUrl.hostname === requestHost.split(":")[0]) {
+                res.setHeader("Access-Control-Allow-Origin", origin);
+            }
+        }
+        catch {
+            // Invalid origin URL, don't set CORS header
+        }
+    }
+    else {
+        // Allow null origin (file:// or local HTML files)
+        res.setHeader("Access-Control-Allow-Origin", "*");
+    }
+    res.setHeader("Access-Control-Allow-Methods", "GET, OPTIONS");
+    res.setHeader("Access-Control-Allow-Headers", "Content-Type");
+    if (req.method === "OPTIONS") {
+        res.writeHead(204);
+        res.end();
+        return;
+    }
+    // GET /terminal?session=ao-1 → returns { url, port }
+    if (url.pathname === "/terminal") {
+        const sessionId = url.searchParams.get("session");
+        if (!sessionId) {
+            res.writeHead(400, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "Missing session parameter" }));
+            recordWebsocketMetric({
+                metric: "websocket_error",
+                outcome: "failure",
+                reason: "Missing session parameter",
+            });
+            return;
+        }
+        // Validate session ID to prevent path traversal and injection
+        if (!validateSessionId(sessionId)) {
+            res.writeHead(400, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "Invalid session ID" }));
+            recordWebsocketMetric({
+                metric: "websocket_error",
+                outcome: "failure",
+                sessionId,
+                reason: "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) {
+            res.writeHead(404, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "Session not found" }));
+            recordWebsocketMetric({
+                metric: "websocket_error",
+                outcome: "failure",
+                sessionId,
+                reason: "Session not found",
+            });
+            return;
+        }
+        // Spawn ttyd and wait for it to be ready (catch port exhaustion and startup failures)
+        try {
+            const instance = getOrSpawnTtyd(sessionId, tmuxSessionId);
+            await waitForTtyd(instance.port, sessionId);
+            // Use the request host to construct the terminal URL (supports remote access)
+            const host = req.headers.host ?? "localhost";
+            const protocol = req.headers["x-forwarded-proto"] ?? "http";
+            res.writeHead(200, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({
+                url: `${protocol}://${host.split(":")[0]}:${instance.port}/${sessionId}/`,
+                port: instance.port,
+                sessionId,
+            }));
+        }
+        catch (err) {
+            const errorMsg = err instanceof Error ? err.message : String(err);
+            console.error(`[Terminal] Failed to start terminal for ${sessionId}:`, errorMsg);
+            metrics.totalErrors += 1;
+            metrics.lastErrorAt = new Date().toISOString();
+            metrics.lastErrorReason = errorMsg;
+            recordWebsocketMetric({
+                metric: "websocket_error",
+                outcome: "failure",
+                sessionId,
+                reason: errorMsg,
+            });
+            res.writeHead(503, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "Failed to start terminal" }));
+        }
+        return;
+    }
+    // GET /health
+    if (url.pathname === "/health") {
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({
+            instances: Object.fromEntries([...instances.entries()].map(([id, inst]) => [id, { port: inst.port }])),
+            metrics,
+        }));
+        return;
+    }
+    res.writeHead(404);
+    res.end("Not found");
+});
+const PORT = parseInt(process.env.TERMINAL_PORT ?? "14800", 10);
+server.listen(PORT, () => {
+    console.log(`[Terminal] Server listening on port ${PORT}`);
+});
+// Graceful shutdown — kill all ttyd instances
+function shutdown(signal) {
+    console.log(`[Terminal] Received ${signal}, shutting down...`);
+    for (const [, instance] of instances) {
+        instance.process.kill();
+    }
+    server.close(() => {
+        console.log("[Terminal] Server closed");
+        process.exit(0);
+    });
+    // Force exit after 5s if graceful shutdown hangs
+    // Use unref() so this timer doesn't prevent process exit if server closes quickly
+    const forceExitTimer = setTimeout(() => {
+        console.error("[Terminal] Forced shutdown after timeout");
+        process.exit(1);
+    }, 5000);
+    forceExitTimer.unref();
+}
+process.on("SIGINT", () => shutdown("SIGINT"));
+process.on("SIGTERM", () => shutdown("SIGTERM"));

package/dist-server/tmux-utils.js

@@ -0,0 +1,89 @@
+/**
+ * Shared tmux utilities for terminal servers.
+ *
+ * Extracted from direct-terminal-ws.ts and terminal-websocket.ts
+ * so the logic can be properly unit tested.
+ */
+import { execFileSync } from "node:child_process";
+/** 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}-/;
+/**
+ * Validate a session ID format.
+ * Prevents path traversal, shell injection, and other attacks.
+ */
+export function validateSessionId(sessionId) {
+    return SESSION_ID_PATTERN.test(sessionId);
+}
+/**
+ * Find full path to tmux binary.
+ *
+ * Checks common installation locations because node-pty's posix_spawnp
+ * doesn't reliably inherit PATH, and some Node.js environments (e.g.,
+ * launched from GUI apps) have minimal PATH.
+ *
+ * @param execFn - Injectable execFileSync for testing. Defaults to child_process.execFileSync.
+ */
+export function findTmux(execFn = execFileSync) {
+    const candidates = [
+        "/opt/homebrew/bin/tmux", // macOS ARM (Homebrew)
+        "/usr/local/bin/tmux", // macOS Intel (Homebrew)
+        "/usr/bin/tmux", // Linux
+    ];
+    for (const p of candidates) {
+        try {
+            execFn(p, ["-V"], { timeout: 5000 });
+            return p;
+        }
+        catch {
+            continue;
+        }
+    }
+    return "tmux"; // Fall back to bare name
+}
+/**
+ * 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:
+ *
+ * 1. Tries exact match first 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}`).
+ *
+ * @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.
+ * @returns The actual tmux session name, or null if not found
+ */
+export function resolveTmuxSession(sessionId, tmuxPath, execFn = execFileSync) {
+    // 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 {
+        execFn(tmuxPath, ["has-session", "-t", `=${sessionId}`], { timeout: 5000 });
+        return sessionId;
+    }
+    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".
+    try {
+        const output = execFn(tmuxPath, ["list-sessions", "-F", "#{session_name}"], {
+            timeout: 5000,
+            encoding: "utf8",
+        });
+        const sessions = output.split("\n").filter(Boolean);
+        const match = sessions.find((s) => HASH_PREFIX_PATTERN.test(s) && s.substring(13) === sessionId);
+        if (match) {
+            return match;
+        }
+    }
+    catch {
+        // tmux not running or no sessions
+    }
+    return null;
+}

package/next.config.js

@@ -0,0 +1,33 @@
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  transpilePackages: [
+    "@aoagents/ao-core",
+    "@aoagents/ao-plugin-agent-claude-code",
+    "@aoagents/ao-plugin-agent-opencode",
+    "@aoagents/ao-plugin-runtime-tmux",
+    "@aoagents/ao-plugin-scm-github",
+    "@aoagents/ao-plugin-tracker-github",
+    "@aoagents/ao-plugin-tracker-linear",
+    "@aoagents/ao-plugin-workspace-worktree",
+  ],
+  async headers() {
+    return [
+      {
+        source: "/sw.js",
+        headers: [
+          { key: "Cache-Control", value: "no-cache, no-store, must-revalidate" },
+          { key: "Service-Worker-Allowed", value: "/" },
+        ],
+      },
+    ];
+  },
+};
+
+// Only load bundle analyzer when ANALYZE=true (dev-only dependency)
+let config = nextConfig;
+if (process.env.ANALYZE === "true") {
+  const { default: bundleAnalyzer } = await import("@next/bundle-analyzer");
+  config = bundleAnalyzer({ enabled: true })(nextConfig);
+}
+
+export default config;

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@aoagents/ao-web",
+  "version": "0.2.2",
+  "description": "Web dashboard for agent-orchestrator",
+  "type": "module",
+  "files": [
+    ".next/server",
+    ".next/static",
+    ".next/*.json",
+    ".next/BUILD_ID",
+    "dist-server",
+    "next.config.js"
+  ],
+  "scripts": {
+    "dev": "concurrently \"npm:dev:next\" \"npm:dev:terminal\" \"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",
+    "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",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "rm -rf .next dist-server",
+    "screenshot": "tsx e2e/screenshot.ts",
+    "screenshot:install": "npx playwright install chromium"
+  },
+  "dependencies": {
+    "@aoagents/ao-core": "workspace:*",
+    "@aoagents/ao-plugin-agent-claude-code": "workspace:*",
+    "@aoagents/ao-plugin-agent-opencode": "workspace:*",
+    "@aoagents/ao-plugin-runtime-tmux": "workspace:*",
+    "@aoagents/ao-plugin-scm-github": "workspace:*",
+    "@aoagents/ao-plugin-tracker-github": "workspace:*",
+    "@aoagents/ao-plugin-tracker-linear": "workspace:*",
+    "@aoagents/ao-plugin-workspace-worktree": "workspace:*",
+    "@xterm/addon-fit": "^0.11.0",
+    "@xterm/addon-web-links": "^0.12.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"
+  },
+  "optionalDependencies": {
+    "node-pty": "^1.1.0"
+  },
+  "devDependencies": {
+    "@next/bundle-analyzer": "^15.1.0",
+    "@tailwindcss/postcss": "^4.0.0",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.1.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@types/ws": "^8.18.1",
+    "@vitejs/plugin-react": "^4.3.0",
+    "@vitest/coverage-v8": "^2.1.0",
+    "concurrently": "^9.2.1",
+    "jsdom": "^25.0.0",
+    "node-gyp": "^12.2.0",
+    "playwright": "^1.49.0",
+    "tailwindcss": "^4.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0",
+    "vitest": "^2.1.0"
+  }
+}