@someonegg/agent-hub 0.0.0-stage → 0.7.0

package/dist/server/server/interaction/tmux-service.js

@@ -0,0 +1,334 @@
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { lstat } from "node:fs/promises";
+import { createConnection } from "node:net";
+import { setTimeout as delay } from "node:timers/promises";
+import { normalizeMessage } from "./message.js";
+import { ownedSocket, tmuxTarget, validTmuxSessionName } from "./tmux-target.js";
+import { InteractionTransportError, } from "./transport.js";
+export const MAX_TERMINAL_PREVIEW_BYTES = 256_000;
+const DEFAULT_TIMEOUT_MS = 5_000;
+const MAX_COMMAND_OUTPUT_BYTES = 64 * 1024;
+export class TmuxInteractionService {
+    runner;
+    timeoutMs;
+    #queues = new Map();
+    constructor(runner = new SpawnTmuxCommandRunner(), timeoutMs = DEFAULT_TIMEOUT_MS) {
+        this.runner = runner;
+        this.timeoutMs = timeoutMs;
+    }
+    #queries = new Map();
+    async connect(attempt) {
+        const binding = await this.resolveTarget(attempt);
+        if (!binding)
+            throw disconnected();
+        return binding;
+    }
+    resolveTarget(attempt) {
+        if (!attempt.valid ||
+            !attempt.socketPath.startsWith("/") ||
+            !validTmuxSessionName(attempt.sessionName))
+            return Promise.resolve(null);
+        const { socketPath, sessionName } = attempt;
+        let query = this.#queries.get(socketPath);
+        if (!query) {
+            query = this.#query(socketPath);
+            this.#queries.set(socketPath, query);
+            // Share only in-flight observations, never completed results.
+            void query.then(() => this.#queries.delete(socketPath), () => this.#queries.delete(socketPath));
+        }
+        return query.then((sessions) => sessions.has(sessionName) ? { socketPath, sessionName } : null);
+    }
+    #waiting = [];
+    #active = 0;
+    async #query(socketPath) {
+        while (this.#active >= 8)
+            await new Promise((resolve) => this.#waiting.push(resolve));
+        this.#active++;
+        try {
+            return await this.#querySessions(socketPath);
+        }
+        finally {
+            this.#active--;
+            this.#waiting.shift()?.();
+        }
+    }
+    async #querySessions(socketPath) {
+        try {
+            await validateSocket(socketPath);
+        }
+        catch (error) {
+            if (error instanceof InteractionTransportError && error.code === "disconnected")
+                return new Set();
+            throw error;
+        }
+        let result;
+        try {
+            result = await this.runner.run(socketPath, ["list-sessions", "-F", "#{session_name}"], undefined, this.timeoutMs);
+        }
+        catch (error) {
+            if (error instanceof InteractionTransportError &&
+                error.code === "command_failed" &&
+                !(await socketListening(socketPath, this.timeoutMs)))
+                return new Set();
+            throw error;
+        }
+        return new Set(result.stdout.split("\n").filter(Boolean));
+    }
+    killSession(binding, assertAvailable = () => { }) {
+        return this.#serialize(binding, async () => {
+            await this.#revalidate(binding);
+            assertAvailable();
+            await this.#run(binding, ["kill-session", "-t", tmuxTarget(binding.sessionName)]);
+        });
+    }
+    sendMessage(binding, message, assertAvailable = () => { }) {
+        const normalized = normalizeMessage(message);
+        return this.#serialize(binding, async () => {
+            await this.#revalidate(binding);
+            assertAvailable();
+            const bufferName = `ahub-${process.pid}-${randomUUID()}`;
+            let bufferMayExist = true;
+            try {
+                await this.#run(binding, ["load-buffer", "-b", bufferName, "-"], normalized);
+                assertAvailable();
+                await this.#run(binding, [
+                    "paste-buffer",
+                    "-p",
+                    "-d",
+                    "-b",
+                    bufferName,
+                    "-t",
+                    tmuxTarget(binding.sessionName),
+                ]);
+                bufferMayExist = false;
+                assertAvailable();
+                await this.#run(binding, ["send-keys", "-t", tmuxTarget(binding.sessionName), "Enter"]);
+            }
+            finally {
+                if (bufferMayExist) {
+                    try {
+                        await this.#run(binding, ["delete-buffer", "-b", bufferName]);
+                    }
+                    catch {
+                        // Preserve the original failure; the buffer may not exist or may already be deleted.
+                    }
+                }
+            }
+        });
+    }
+    sendKeys(binding, steps, assertAvailable = () => { }) {
+        return this.#serialize(binding, async () => {
+            for (const step of steps) {
+                if (step.delayMs > 0)
+                    await delay(step.delayMs);
+                await this.#revalidate(binding);
+                assertAvailable();
+                await this.#run(binding, [
+                    "send-keys",
+                    "-t",
+                    tmuxTarget(binding.sessionName),
+                    ...step.keys,
+                ]);
+            }
+        });
+    }
+    captureTerminal(binding, assertAvailable = () => { }) {
+        return this.#serialize(binding, async () => {
+            const result = await this.#capture(binding, ["capture-pane", "-p", "-t", tmuxTarget(binding.sessionName)], assertAvailable);
+            return { content: result.stdout, truncated: result.truncated === true };
+        });
+    }
+    /** Read cursor and screen in one tmux command queue; discard moving or truncated captures. */
+    captureTerminalWithCursor(binding) {
+        return this.#serialize(binding, async () => {
+            const target = tmuxTarget(binding.sessionName);
+            const position = [
+                "display-message",
+                "-p",
+                "-t",
+                target,
+                "#{cursor_x},#{cursor_y},#{pane_width},#{pane_height}",
+            ];
+            const result = await this.#capture(binding, [
+                ...position,
+                ";",
+                "capture-pane",
+                "-p",
+                "-t",
+                target,
+                ";",
+                ...position,
+            ]);
+            if (result.truncated)
+                return null;
+            const lines = result.stdout.split("\n");
+            if (lines.pop() !== "")
+                return null;
+            const before = lines.shift();
+            const after = lines.pop();
+            if (!before || before !== after || !/^\d+,\d+,\d+,\d+$/.test(before))
+                return null;
+            const [cursorX, cursorY, width, height] = before.split(",").map(Number);
+            if (![cursorX, cursorY, width, height].every(Number.isSafeInteger) ||
+                width <= 0 ||
+                height <= 0 ||
+                cursorX >= width ||
+                cursorY >= height ||
+                lines.length !== height)
+                return null;
+            return { content: lines.join("\n"), cursorX, cursorY };
+        });
+    }
+    async #capture(binding, args, assertAvailable = () => { }) {
+        if (!binding.socketPath.startsWith("/") || !validTmuxSessionName(binding.sessionName))
+            throw disconnected();
+        await validateSocket(binding.socketPath);
+        assertAvailable();
+        try {
+            return await this.runner.run(binding.socketPath, args, undefined, this.timeoutMs, {
+                maxOutputBytes: MAX_TERMINAL_PREVIEW_BYTES,
+                truncateStart: true,
+            });
+        }
+        catch (error) {
+            // Only confirmed absence replaces the capture error; failed probes prove nothing.
+            const target = await this.resolveTarget({ valid: true, ordinal: 0, ...binding }).catch(() => undefined);
+            if (target === null)
+                throw disconnected();
+            throw error;
+        }
+    }
+    /** Query errors never establish that the selected session exited. */
+    async inspect(binding) {
+        return (await this.resolveTarget({ valid: true, ordinal: 0, ...binding })) ? "alive" : "exited";
+    }
+    async #revalidate(binding) {
+        if (!(await this.resolveTarget({ valid: true, ordinal: 0, ...binding })))
+            throw disconnected();
+    }
+    async #run(binding, args, input) {
+        await this.runner.run(binding.socketPath, args, input, this.timeoutMs);
+    }
+    #serialize(binding, operation) {
+        const key = `${binding.socketPath}\0${binding.sessionName}`;
+        const previous = this.#queues.get(key) ?? Promise.resolve();
+        const current = previous.catch(() => undefined).then(operation);
+        const settled = current.then(() => undefined, () => undefined);
+        this.#queues.set(key, settled);
+        void settled.finally(() => {
+            if (this.#queues.get(key) === settled)
+                this.#queues.delete(key);
+        });
+        return current;
+    }
+}
+async function validateSocket(socketPath) {
+    try {
+        if (!ownedSocket(await lstat(socketPath)))
+            throw new InteractionTransportError("command_failed", "Unsafe tmux socket");
+    }
+    catch (error) {
+        if (error instanceof InteractionTransportError)
+            throw error;
+        if (error.code === "ENOENT")
+            throw disconnected();
+        throw error;
+    }
+}
+function disconnected() {
+    return new InteractionTransportError("disconnected", "tmux target is not connected");
+}
+export class SpawnTmuxCommandRunner {
+    run(socketPath, args, input, timeoutMs, options) {
+        return new Promise((resolve, reject) => {
+            const child = spawn("tmux", ["-S", socketPath, ...args], {
+                shell: false,
+                stdio: ["pipe", "pipe", "pipe"],
+            });
+            let stdout = Buffer.alloc(0);
+            const stderr = [];
+            let outputBytes = 0;
+            let truncated = false;
+            let settled = false;
+            const finish = (callback) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                callback();
+            };
+            const timer = setTimeout(() => {
+                child.kill("SIGKILL");
+                finish(() => reject(new InteractionTransportError("timeout", "tmux operation timed out; the result is unknown")));
+            }, timeoutMs);
+            const collectStdout = (chunk) => {
+                if (options?.truncateStart) {
+                    stdout = Buffer.concat([stdout, chunk]);
+                    if (stdout.byteLength > options.maxOutputBytes) {
+                        stdout = trimLeadingPartialUtf8(stdout.subarray(stdout.byteLength - options.maxOutputBytes));
+                        truncated = true;
+                    }
+                    return;
+                }
+                outputBytes += chunk.byteLength;
+                if (outputBytes <= MAX_COMMAND_OUTPUT_BYTES)
+                    stdout = Buffer.concat([stdout, chunk]);
+                else
+                    child.kill("SIGKILL");
+            };
+            const collectStderr = (chunk) => {
+                outputBytes += chunk.byteLength;
+                if (outputBytes <= MAX_COMMAND_OUTPUT_BYTES)
+                    stderr.push(chunk);
+                else
+                    child.kill("SIGKILL");
+            };
+            child.stdout.on("data", collectStdout);
+            child.stderr.on("data", collectStderr);
+            child.once("error", (error) => finish(() => reject(new InteractionTransportError("command_failed", error.message))));
+            child.stdin.once("error", (error) => finish(() => reject(new InteractionTransportError("command_failed", error.message))));
+            child.once("close", (code) => finish(() => {
+                if (outputBytes > MAX_COMMAND_OUTPUT_BYTES || code !== 0) {
+                    reject(new InteractionTransportError("command_failed", Buffer.concat(stderr).toString("utf8").trim() || "tmux command failed"));
+                    return;
+                }
+                resolve({ stdout: stdout.toString("utf8"), truncated });
+            }));
+            if (input === undefined)
+                child.stdin.end();
+            else
+                child.stdin.end(input, "utf8");
+        });
+    }
+}
+function trimLeadingPartialUtf8(buffer) {
+    let start = 0;
+    while (start < buffer.byteLength && (buffer[start] & 0xc0) === 0x80)
+        start += 1;
+    return buffer.subarray(start);
+}
+// A refused connection establishes a stopped server even when tmux left its socket file.
+// Timeouts, permissions and other socket failures remain unknown.
+function socketListening(path, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        const socket = createConnection({ path });
+        socket.setTimeout(timeoutMs);
+        socket.once("connect", () => {
+            socket.destroy();
+            resolve(true);
+        });
+        socket.once("timeout", () => {
+            socket.destroy();
+            reject(new InteractionTransportError("timeout", "Socket validation timed out"));
+        });
+        socket.once("error", (error) => {
+            socket.destroy();
+            if (error.code === "ECONNREFUSED" || error.code === "ENOENT")
+                resolve(false);
+            else
+                reject(error);
+        });
+    });
+}
+//# sourceMappingURL=tmux-service.js.map

package/dist/server/server/interaction/tmux-target.js

@@ -0,0 +1,13 @@
+/** Hub sessions have exactly one window and pane; topology is a user contract. */
+export function validTmuxSessionName(value) {
+    return /^ahub-[a-fA-F0-9]{8}-(?:[a-fA-F0-9]{4}-){3}[a-fA-F0-9]{12}$/.test(value);
+}
+/** A trailing colon disambiguates session names for both session and pane commands. */
+export function tmuxTarget(sessionName) {
+    return `=${sessionName}:`;
+}
+/** Only unix sockets owned by the current user may be controlled. */
+export function ownedSocket(stats) {
+    return stats.isSocket() && typeof process.getuid === "function" && stats.uid === process.getuid();
+}
+//# sourceMappingURL=tmux-target.js.map

package/dist/server/server/interaction/transport.js

@@ -0,0 +1,9 @@
+export class InteractionTransportError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "InteractionTransportError";
+    }
+}
+//# sourceMappingURL=transport.js.map

package/dist/server/server/main.js

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+import { commandLineHelp, loadConfig } from "./config.js";
+import { createAhub } from "./create-hub.js";
+import { createApiRouter } from "./http/api-router.js";
+import { startServer } from "./http/create-server.js";
+import { createTerminalPreviewWebSocket } from "./http/terminal-preview-websocket.js";
+import { uploadDirectory } from "./http/upload-routes.js";
+import { UploadStore } from "./uploads/store.js";
+import { packageVersion } from "./version.js";
+async function main() {
+    const command = loadConfig();
+    if (command.kind === "help") {
+        console.log(commandLineHelp());
+        return;
+    }
+    if (command.kind === "version") {
+        console.log(await packageVersion());
+        return;
+    }
+    const { config } = command;
+    const uploads = new UploadStore(await uploadDirectory(config.uploadDirectory));
+    await uploads.initialize();
+    const hub = await createAhub({
+        agents: config.agents,
+        socket: config.tmuxSocket,
+        claudeReadyScript: config.claudeReadyScript,
+        interactionEnabled: config.interactionEnabled,
+        uploads,
+    });
+    const server = await startServer(config, createApiRouter({ ...hub, uploads }), hub.close, createTerminalPreviewWebSocket(hub.interaction));
+    const address = server.address();
+    const port = typeof address === "object" && address ? address.port : config.port;
+    const host = config.host.includes(":") ? `[${config.host}]` : config.host;
+    const protocol = config.tls.enabled ? "https" : "http";
+    const mutualTls = config.tls.enabled && config.tls.certificateAuthorityPath
+        ? " (client certificates required)"
+        : "";
+    console.log(`Agent Hub listening on ${protocol}://${host}:${port}${mutualTls}`);
+    function close() {
+        server.close((error) => {
+            if (error) {
+                console.error("Failed to stop Agent Hub");
+                process.exitCode = 1;
+            }
+        });
+    }
+    process.once("SIGINT", close);
+    process.once("SIGTERM", close);
+}
+main().catch((error) => {
+    console.error(error instanceof Error ? error.message : "Failed to start Agent Hub");
+    process.exitCode = 1;
+});
+//# sourceMappingURL=main.js.map