arcane-agents 0.1.0

package/dist/server/server/tmux/tmuxAdapter.js

@@ -0,0 +1,338 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TmuxAdapter = void 0;
+const node_child_process_1 = require("node:child_process");
+const node_util_1 = require("node:util");
+const execFileAsync = (0, node_util_1.promisify)(node_child_process_1.execFile);
+class TmuxAdapter {
+    sessionName;
+    sessionClipboardConfigured = false;
+    constructor(sessionName) {
+        this.sessionName = sessionName;
+    }
+    async spawnWorker(input) {
+        const target = `${this.sessionName}:${input.windowName}`;
+        const commandLine = input.command.map(shellQuote).join(" ");
+        const env = `ARCANE_AGENTS_WORKER_ID=${input.workerId}`;
+        if (await this.hasSession()) {
+            await this.runTmux([
+                "new-window",
+                "-d",
+                "-t",
+                this.sessionName,
+                "-n",
+                input.windowName,
+                "-c",
+                input.projectPath,
+                "-e",
+                env,
+                commandLine
+            ]);
+        }
+        else {
+            await this.runTmux([
+                "new-session",
+                "-d",
+                "-s",
+                this.sessionName,
+                "-n",
+                input.windowName,
+                "-c",
+                input.projectPath,
+                "-e",
+                env,
+                commandLine
+            ]);
+        }
+        await this.ensureSessionClipboardDefaults();
+        await this.setWindowMetadata(target, {
+            "@arcane_agents_managed": "1",
+            "@arcane_agents_worker_id": input.workerId,
+            "@arcane_agents_project_id": input.projectId,
+            "@arcane_agents_runtime_id": input.runtimeId,
+            "@arcane_agents_runtime_label": input.runtimeLabel,
+            "@arcane_agents_project_path": input.projectPath
+        });
+        const [, , paneOutput] = await Promise.all([
+            this.runTmux(["set-option", "-w", "-t", target, "automatic-rename", "off"]),
+            this.runTmux(["set-option", "-w", "-t", target, "allow-rename", "off"]),
+            this.runTmux(["list-panes", "-t", target, "-F", "#{pane_id}"])
+        ]);
+        const pane = firstLine(paneOutput);
+        if (!pane) {
+            throw new Error(`Unable to resolve tmux pane for ${target}.`);
+        }
+        return {
+            session: this.sessionName,
+            window: input.windowName,
+            pane
+        };
+    }
+    async stop(ref, options) {
+        if (options?.background) {
+            void this.stopGracefully(ref).catch(() => undefined);
+            return;
+        }
+        await this.stopGracefully(ref);
+    }
+    async ensureSessionClipboardDefaults() {
+        if (this.sessionClipboardConfigured) {
+            return;
+        }
+        if (!(await this.hasSession())) {
+            return;
+        }
+        const copyCommand = await detectClipboardCopyCommand();
+        if (!copyCommand) {
+            this.sessionClipboardConfigured = true;
+            return;
+        }
+        await Promise.all([
+            this.runTmux(["set-option", "-t", this.sessionName, "set-clipboard", "external"]),
+            this.runTmux(["set-option", "-t", this.sessionName, "copy-command", copyCommand])
+        ]).catch(() => undefined);
+        this.sessionClipboardConfigured = true;
+    }
+    async windowExists(ref) {
+        try {
+            await this.runTmux(["has-session", "-t", this.target(ref)]);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async listManagedWindows() {
+        if (!(await this.hasSession())) {
+            return [];
+        }
+        const output = await this.runTmux([
+            "list-panes",
+            "-a",
+            "-F",
+            "#{window_name}\t#{pane_id}\t#{@arcane_agents_managed}\t#{@arcane_agents_worker_id}\t#{@arcane_agents_project_id}\t#{@arcane_agents_runtime_id}\t#{@arcane_agents_runtime_label}\t#{@arcane_agents_project_path}"
+        ]);
+        const seenWindows = new Set();
+        const windows = [];
+        for (const line of output.split("\n")) {
+            if (!line.trim()) {
+                continue;
+            }
+            const [window, pane, managedFlag, workerId, projectId, runtimeId, runtimeLabel, projectPath] = line.split("\t");
+            if (managedFlag !== "1") {
+                continue;
+            }
+            if (seenWindows.has(window)) {
+                continue;
+            }
+            seenWindows.add(window);
+            windows.push({
+                window,
+                pane,
+                workerId: normalizeOption(workerId),
+                projectId: normalizeOption(projectId),
+                runtimeId: normalizeOption(runtimeId),
+                runtimeLabel: normalizeOption(runtimeLabel),
+                projectPath: normalizeOption(projectPath)
+            });
+        }
+        return windows;
+    }
+    async openInExternalTerminal(ref, workerId) {
+        const target = this.target(ref);
+        const live = await this.windowExists(ref);
+        if (!live) {
+            throw new Error(`Cannot open terminal: tmux target '${target}' is not available.`);
+        }
+        const externalSession = createExternalSessionName(workerId);
+        const externalWindowTarget = `${externalSession}:${ref.window}`;
+        await this.runTmux(["has-session", "-t", externalSession])
+            .then(async () => {
+            await this.runTmux(["kill-session", "-t", externalSession]);
+        })
+            .catch(() => undefined);
+        try {
+            await this.runTmux(["new-session", "-d", "-t", ref.session, "-s", externalSession]);
+            await this.runTmux(["select-window", "-t", externalWindowTarget]);
+        }
+        catch (error) {
+            await this.runTmux(["kill-session", "-t", externalSession]).catch(() => undefined);
+            throw error;
+        }
+        await new Promise((resolve, reject) => {
+            const guardCommand = `tmux has-session -t ${shellQuote(externalSession)} >/dev/null 2>&1 || exit 0; exec tmux attach-session -t ${shellQuote(externalSession)}`;
+            const child = (0, node_child_process_1.spawn)("xdg-terminal-exec", ["sh", "-lc", guardCommand], {
+                detached: true,
+                stdio: "ignore"
+            });
+            child.once("error", (error) => {
+                const reason = error instanceof Error ? error.message : String(error);
+                reject(new Error(`Failed to launch external terminal via xdg-terminal-exec: ${reason}`));
+            });
+            child.once("spawn", () => {
+                child.unref();
+                resolve();
+            });
+        });
+    }
+    async sendInput(ref, text, options) {
+        const target = this.target(ref);
+        const exists = await this.windowExists(ref);
+        if (!exists) {
+            throw new Error(`Cannot send input: tmux target '${target}' is not available.`);
+        }
+        const normalizedText = text.replace(/\r\n?/g, "\n");
+        if (normalizedText.length > 0) {
+            const lines = normalizedText.split("\n");
+            for (let index = 0; index < lines.length; index += 1) {
+                const line = lines[index] ?? "";
+                if (line.length > 0) {
+                    await this.runTmux(["send-keys", "-t", target, "-l", line]);
+                }
+                if (index < lines.length - 1) {
+                    await this.runTmux(["send-keys", "-t", target, "Enter"]);
+                }
+            }
+        }
+        if (options?.submit ?? true) {
+            await this.runTmux(["send-keys", "-t", target, "Enter"]);
+        }
+    }
+    async capturePane(ref, lines = 30) {
+        return this.runTmux(["capture-pane", "-t", this.target(ref), "-p", "-S", `-${Math.max(1, lines)}`]);
+    }
+    async getPaneState(ref) {
+        const output = await this.runTmux([
+            "list-panes",
+            "-t",
+            this.target(ref),
+            "-F",
+            "#{pane_current_command}\t#{pane_dead}\t#{pane_current_path}"
+        ]);
+        const [currentCommand = "", deadFlag = "0", currentPath = ""] = firstLine(output).split("\t");
+        return {
+            currentCommand,
+            isDead: deadFlag === "1",
+            currentPath: currentPath.trim().length > 0 ? currentPath : undefined
+        };
+    }
+    async hasSession() {
+        try {
+            await this.runTmux(["has-session", "-t", this.sessionName]);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    target(ref) {
+        return `${ref.session}:${ref.window}`;
+    }
+    async runTmux(args) {
+        const { stdout } = await execFileAsync("tmux", args, {
+            maxBuffer: 1024 * 1024
+        });
+        return stdout.trimEnd();
+    }
+    async setWindowMetadata(target, metadata) {
+        await Promise.all(Object.entries(metadata).map(([key, value]) => this.runTmux(["set-option", "-w", "-t", target, key, value])));
+    }
+    async stopGracefully(ref) {
+        const target = this.target(ref);
+        const exists = await this.windowExists(ref);
+        if (!exists) {
+            return;
+        }
+        await this.runTmux(["send-keys", "-t", target, "C-c"]).catch(() => undefined);
+        await delay(220);
+        const paneInfo = await this.runTmux([
+            "list-panes",
+            "-t",
+            target,
+            "-F",
+            "#{pane_pid}\t#{pane_current_command}\t#{pane_dead}"
+        ]).catch(() => "");
+        const [panePidText = "", paneCommand = "", paneDeadFlag = "1"] = firstLine(paneInfo).split("\t");
+        const panePid = Number.parseInt(panePidText, 10);
+        const currentCommand = paneCommand.trim().toLowerCase();
+        const paneDead = paneDeadFlag === "1";
+        if (!paneDead && Number.isFinite(panePid) && panePid > 1 && currentCommand !== "bash" && currentCommand !== "zsh") {
+            await terminateProcessGroup(panePid).catch(() => undefined);
+            await delay(90);
+        }
+        await this.runTmux(["kill-window", "-t", target]).catch(() => undefined);
+    }
+}
+exports.TmuxAdapter = TmuxAdapter;
+function firstLine(input) {
+    const [line = ""] = input.split("\n");
+    return line;
+}
+function shellQuote(value) {
+    if (value.length === 0) {
+        return "''";
+    }
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+function delay(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+function createExternalSessionName(workerId) {
+    const safeId = workerId.toLowerCase().replace(/[^a-z0-9]/g, "").slice(0, 12) || "worker";
+    const stamp = Date.now().toString(36);
+    return `arcane-agents-ext-${safeId}-${stamp}`;
+}
+function normalizeOption(value) {
+    if (!value || value.trim().length === 0) {
+        return undefined;
+    }
+    return value;
+}
+async function detectClipboardCopyCommand() {
+    const candidates = clipboardCandidatesForPlatform(process.platform);
+    for (const candidate of candidates) {
+        if (await commandExists(candidate.binary)) {
+            return candidate.command;
+        }
+    }
+    return undefined;
+}
+function clipboardCandidatesForPlatform(platform) {
+    if (platform === "darwin") {
+        return [{ binary: "pbcopy", command: "pbcopy" }];
+    }
+    if (platform === "win32") {
+        return [{ binary: "clip.exe", command: "clip.exe" }];
+    }
+    return [
+        { binary: "wl-copy", command: "wl-copy" },
+        { binary: "xclip", command: "xclip -selection clipboard -in" },
+        { binary: "xsel", command: "xsel --clipboard --input" }
+    ];
+}
+async function commandExists(binary) {
+    const locator = process.platform === "win32" ? "where" : "which";
+    try {
+        await execFileAsync(locator, [binary], {
+            maxBuffer: 1024 * 64
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function terminateProcessGroup(panePid) {
+    const { stdout } = await execFileAsync("ps", ["-o", "pgid=", "-p", String(panePid)], {
+        maxBuffer: 1024 * 64
+    });
+    const pgid = Number.parseInt(stdout.trim(), 10);
+    if (!Number.isFinite(pgid) || pgid <= 1) {
+        return;
+    }
+    await execFileAsync("kill", ["-TERM", `-${pgid}`], { maxBuffer: 1024 * 64 }).catch(() => undefined);
+    await delay(120);
+    await execFileAsync("kill", ["-KILL", `-${pgid}`], { maxBuffer: 1024 * 64 }).catch(() => undefined);
+}

package/dist/server/server/utils/appRoot.js

@@ -0,0 +1,40 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveAppRoot = resolveAppRoot;
+exports.setAppRoot = setAppRoot;
+exports.resolveAppPath = resolveAppPath;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const appRootEnvKey = "ARCANE_AGENTS_APP_ROOT";
+function isLikelyAppRoot(candidateRoot) {
+    return (node_fs_1.default.existsSync(node_path_1.default.join(candidateRoot, "package.json")) &&
+        node_fs_1.default.existsSync(node_path_1.default.join(candidateRoot, "assets")));
+}
+function resolveAppRoot() {
+    const envRoot = process.env[appRootEnvKey];
+    if (envRoot && envRoot.trim().length > 0) {
+        return node_path_1.default.resolve(envRoot);
+    }
+    const candidates = [
+        node_path_1.default.resolve(__dirname, "../../.."),
+        node_path_1.default.resolve(__dirname, "../../../.."),
+        node_path_1.default.resolve(process.cwd())
+    ];
+    for (const candidate of candidates) {
+        if (isLikelyAppRoot(candidate)) {
+            return candidate;
+        }
+    }
+    return node_path_1.default.resolve(process.cwd());
+}
+function setAppRoot(appRoot) {
+    const resolved = node_path_1.default.resolve(appRoot);
+    process.env[appRootEnvKey] = resolved;
+    return resolved;
+}
+function resolveAppPath(...segments) {
+    return node_path_1.default.join(resolveAppRoot(), ...segments);
+}

package/dist/server/server/utils/path.js

@@ -0,0 +1,20 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveUserPath = resolveUserPath;
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+function expandHomePath(inputPath) {
+    if (inputPath === "~") {
+        return node_os_1.default.homedir();
+    }
+    if (inputPath.startsWith("~/")) {
+        return node_path_1.default.join(node_os_1.default.homedir(), inputPath.slice(2));
+    }
+    return inputPath;
+}
+function resolveUserPath(inputPath) {
+    return node_path_1.default.resolve(expandHomePath(inputPath));
+}

package/dist/server/server/ws/realtimeHub.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RealtimeHub = void 0;
+class RealtimeHub {
+    clients = new Set();
+    addClient(socket) {
+        this.clients.add(socket);
+        socket.on("close", () => {
+            this.clients.delete(socket);
+        });
+        socket.on("error", () => {
+            this.clients.delete(socket);
+        });
+    }
+    sendTo(socket, event) {
+        if (socket.readyState !== socket.OPEN) {
+            return;
+        }
+        try {
+            socket.send(JSON.stringify(event));
+        }
+        catch {
+            this.clients.delete(socket);
+            socket.terminate();
+        }
+    }
+    broadcast(event) {
+        const payload = JSON.stringify(event);
+        for (const socket of this.clients) {
+            if (socket.readyState !== socket.OPEN) {
+                this.clients.delete(socket);
+                continue;
+            }
+            try {
+                socket.send(payload);
+            }
+            catch {
+                this.clients.delete(socket);
+                socket.terminate();
+            }
+        }
+    }
+}
+exports.RealtimeHub = RealtimeHub;

package/dist/server/server/ws/realtimeHub.test.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_events_1 = require("node:events");
+const vitest_1 = require("vitest");
+const realtimeHub_1 = require("./realtimeHub");
+class FakeSocket extends node_events_1.EventEmitter {
+    OPEN = 1;
+    readyState = this.OPEN;
+    send = vitest_1.vi.fn();
+    terminate = vitest_1.vi.fn();
+}
+const sampleEvent = {
+    type: "worker-removed",
+    workerId: "worker-1"
+};
+(0, vitest_1.describe)("RealtimeHub", () => {
+    (0, vitest_1.it)("does not throw when sendTo targets a stale socket", () => {
+        const hub = new realtimeHub_1.RealtimeHub();
+        const socket = new FakeSocket();
+        socket.send.mockImplementation(() => {
+            throw new Error("stale socket");
+        });
+        hub.addClient(socket);
+        (0, vitest_1.expect)(() => hub.sendTo(socket, sampleEvent)).not.toThrow();
+        (0, vitest_1.expect)(socket.terminate).toHaveBeenCalledTimes(1);
+    });
+    (0, vitest_1.it)("does not throw when broadcast encounters stale sockets", () => {
+        const hub = new realtimeHub_1.RealtimeHub();
+        const failingSocket = new FakeSocket();
+        const healthySocket = new FakeSocket();
+        failingSocket.send.mockImplementation(() => {
+            throw new Error("socket closed mid-send");
+        });
+        hub.addClient(failingSocket);
+        hub.addClient(healthySocket);
+        (0, vitest_1.expect)(() => hub.broadcast(sampleEvent)).not.toThrow();
+        (0, vitest_1.expect)(failingSocket.terminate).toHaveBeenCalledTimes(1);
+        (0, vitest_1.expect)(healthySocket.send).toHaveBeenCalledTimes(1);
+        hub.broadcast(sampleEvent);
+        (0, vitest_1.expect)(failingSocket.send).toHaveBeenCalledTimes(1);
+        (0, vitest_1.expect)(healthySocket.send).toHaveBeenCalledTimes(2);
+    });
+});

package/dist/server/server/ws/terminalBridge.js

@@ -0,0 +1,153 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TerminalBridge = void 0;
+const pty = __importStar(require("node-pty"));
+class TerminalBridge {
+    workers;
+    options;
+    constructor(workers, options = {}) {
+        this.workers = workers;
+        this.options = options;
+    }
+    connect(workerId, socket) {
+        const worker = this.workers.getWorker(workerId);
+        if (!worker) {
+            socket.send(JSON.stringify({ type: "error", message: `Unknown agent '${workerId}'.` }));
+            socket.close();
+            return;
+        }
+        const tmuxTarget = `${worker.tmuxRef.session}:${worker.tmuxRef.window}`;
+        const env = {
+            ...process.env,
+            TERM: "xterm-256color"
+        };
+        let terminal;
+        let ready = false;
+        socket.on("message", (raw) => {
+            const incoming = rawDataToString(raw);
+            const control = parseResizeMessage(incoming);
+            if (control) {
+                const cols = Math.max(20, control.cols);
+                const rows = Math.max(5, control.rows);
+                if (!terminal) {
+                    try {
+                        terminal = pty.spawn("tmux", ["attach-session", "-t", tmuxTarget], {
+                            name: "xterm-256color",
+                            cols,
+                            rows,
+                            cwd: worker.projectPath,
+                            env
+                        });
+                    }
+                    catch (error) {
+                        const detail = error instanceof Error ? error.message : String(error);
+                        console.error(`[arcane-agents] terminal bridge failed to spawn pty for ${workerId}: ${detail}`);
+                        socket.close(1011, "Failed to attach terminal");
+                        return;
+                    }
+                    terminal.onData((chunk) => {
+                        if (socket.readyState === socket.OPEN) {
+                            socket.send(chunk);
+                        }
+                    });
+                    terminal.onExit(() => {
+                        if (socket.readyState === socket.OPEN) {
+                            socket.close();
+                        }
+                    });
+                    ready = true;
+                }
+                else {
+                    terminal.resize(cols, rows);
+                }
+                return;
+            }
+            if (!ready) {
+                return;
+            }
+            if (isLikelySubmittedInput(incoming)) {
+                this.options.onSubmittedInput?.(worker.id);
+            }
+            terminal.write(incoming);
+        });
+        const cleanup = () => {
+            terminal?.kill();
+        };
+        socket.on("close", cleanup);
+        socket.on("error", cleanup);
+    }
+}
+exports.TerminalBridge = TerminalBridge;
+function parseResizeMessage(value) {
+    if (!value.startsWith("{")) {
+        return undefined;
+    }
+    try {
+        const parsed = JSON.parse(value);
+        if (parsed.type !== "resize") {
+            return undefined;
+        }
+        if (typeof parsed.cols !== "number" || typeof parsed.rows !== "number") {
+            return undefined;
+        }
+        return {
+            type: "resize",
+            cols: parsed.cols,
+            rows: parsed.rows
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+function rawDataToString(raw) {
+    if (typeof raw === "string") {
+        return raw;
+    }
+    if (Array.isArray(raw)) {
+        return Buffer.concat(raw).toString("utf8");
+    }
+    if (raw instanceof Buffer) {
+        return raw.toString("utf8");
+    }
+    if (raw instanceof ArrayBuffer) {
+        return Buffer.from(raw).toString("utf8");
+    }
+    return Buffer.from(raw).toString("utf8");
+}
+function isLikelySubmittedInput(text) {
+    return text.includes("\r") || text.includes("\n");
+}

package/dist/server/shared/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });