tmux-agent 0.1.0

package/dist/cli/index.js

@@ -0,0 +1,365 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const format_1 = require("../lib/output/format");
+const errors_1 = require("../lib/targeting/errors");
+const windowLs_1 = require("./commands/windowLs");
+const snapshot_1 = require("./commands/snapshot");
+const find_1 = require("./commands/find");
+const send_1 = require("./commands/send");
+const read_1 = require("./commands/read");
+const windowNew_1 = require("./commands/windowNew");
+const windowRename_1 = require("./commands/windowRename");
+const windowKill_1 = require("./commands/windowKill");
+const paneSpawn_1 = require("./commands/paneSpawn");
+const paneTitle_1 = require("./commands/paneTitle");
+const paneKill_1 = require("./commands/paneKill");
+const send_2 = require("./commands/codex/send");
+const sessionInfo_1 = require("./commands/codex/sessionInfo");
+const forkHome_1 = require("./commands/codex/forkHome");
+const spawn_1 = require("./commands/codex/spawn");
+const select_1 = require("./commands/ui/select");
+function writeLine(stream, text) {
+    if (!text.endsWith("\n")) {
+        stream.write(`${text}\n`);
+        return;
+    }
+    stream.write(text);
+}
+function formatError(error) {
+    if (error instanceof errors_1.TargetResolutionError) {
+        const base = (0, format_1.ensureErrorPrefix)(error.message);
+        if (error.kind === "ambiguous" && error.candidates?.length) {
+            if (error.targetKind === "pane") {
+                return `${base}\n${(0, format_1.formatPaneTable)(error.candidates)}`;
+            }
+            return `${base}\n${(0, format_1.formatWindowTable)(error.candidates)}`;
+        }
+        return base;
+    }
+    if (error instanceof Error) {
+        return (0, format_1.ensureErrorPrefix)(error.message);
+    }
+    return (0, format_1.ensureErrorPrefix)(String(error));
+}
+function parseOptionalBoolean(value) {
+    if (value === undefined) {
+        return true;
+    }
+    if (typeof value === "boolean") {
+        return value;
+    }
+    const normalized = value.trim().toLowerCase();
+    return normalized !== "false";
+}
+function parseNonNegativeNumber(optionName) {
+    return (value) => {
+        const num = Number(value);
+        if (!Number.isFinite(num) || num < 0) {
+            throw new Error(`invalid --${optionName}`);
+        }
+        return num;
+    };
+}
+function buildProgram() {
+    const program = new commander_1.Command();
+    program
+        .name("agent-tmux")
+        .description("LLM-friendly tmux control plane CLI for windows/panes.")
+        .exitOverride()
+        .configureOutput({
+        writeErr: () => undefined
+    });
+    const window = program.command("window");
+    window.command("ls")
+        .option("--json [boolean]", "output json", parseOptionalBoolean, false)
+        .option("--session <session>", "tmux session name")
+        .action(async (options) => {
+        const output = await (0, windowLs_1.windowLs)({ json: options.json, session: options.session });
+        if (output) {
+            writeLine(process.stdout, output);
+        }
+    });
+    window.command("new")
+        .argument("<name>")
+        .option("--json [boolean]", "output json", parseOptionalBoolean, false)
+        .option("--session <session>", "tmux session name")
+        .option("--command <command>", "initial command to run (or '-' to read from stdin)")
+        .action(async (name, options) => {
+        const output = await (0, windowNew_1.windowNewCommand)(name, {
+            json: options.json,
+            session: options.session,
+            command: options.command
+        });
+        if (output) {
+            writeLine(process.stdout, output);
+        }
+    });
+    window.command("rename")
+        .argument("<windowTarget>")
+        .argument("<name>")
+        .option("--json [boolean]", "output json", parseOptionalBoolean, false)
+        .option("--session <session>", "tmux session name")
+        .action(async (target, name, options) => {
+        const output = await (0, windowRename_1.windowRenameCommand)(target, name, {
+            json: options.json,
+            session: options.session
+        });
+        if (output) {
+            writeLine(process.stdout, output);
+        }
+    });
+    window.command("kill")
+        .argument("<windowTarget>")
+        .option("--json [boolean]", "output json", parseOptionalBoolean, false)
+        .option("--session <session>", "tmux session name")
+        .action(async (target, options) => {
+        const output = await (0, windowKill_1.windowKillCommand)(target, {
+            json: options.json,
+            session: options.session
+        });
+        if (output) {
+            writeLine(process.stdout, output);
+        }
+    });
+    const pane = program.command("pane");
+    pane.command("spawn")
+        .argument("<command>")
+        .option("--json [boolean]", "output json", parseOptionalBoolean, false)
+        .option("--session <session>", "tmux session name")
+        .option("--window <window>", "tmux window target")
+        .option("--title <title>", "pane title")
+        .action(async (command, options) => {
+        const output = await (0, paneSpawn_1.paneSpawnCommand)(command, {
+            json: options.json,
+            session: options.session,
+            window: options.window,
+            title: options.title
+        });
+        if (output) {
+            writeLine(process.stdout, output);
+        }
+    });
+    pane.command("title")
+        .argument("<paneTarget>")
+        .argument("<title>")
+        .option("--json [boolean]", "output json", parseOptionalBoolean, false)
+        .option("--session <session>", "tmux session name")
+        .option("--window <window>", "tmux window target")
+        .action(async (target, title, options) => {
+        const output = await (0, paneTitle_1.paneTitleCommand)(target, title, {
+            json: options.json,
+            session: options.session,
+            window: options.window
+        });
+        if (output) {
+            writeLine(process.stdout, output);
+        }
+    });
+    pane.command("kill")
+        .argument("<paneTarget>")
+        .option("--json [boolean]", "output json", parseOptionalBoolean, false)
+        .option("--session <session>", "tmux session name")
+        .option("--window <window>", "tmux window target")
+        .action(async (target, options) => {
+        const output = await (0, paneKill_1.paneKillCommand)(target, {
+            json: options.json,
+            session: options.session,
+            window: options.window
+        });
+        if (output) {
+            writeLine(process.stdout, output);
+        }
+    });
+    program.command("snapshot")
+        .option("--json [boolean]", "output json", parseOptionalBoolean, false)
+        .option("--session <session>", "tmux session name")
+        .option("--window <window>", "tmux window target")
+        .action(async (options) => {
+        const output = await (0, snapshot_1.snapshot)({
+            json: options.json,
+            session: options.session,
+            window: options.window
+        });
+        if (output) {
+            writeLine(process.stdout, output);
+        }
+    });
+    program.command("find")
+        .argument("<query>")
+        .option("--json [boolean]", "output json", parseOptionalBoolean, false)
+        .option("--session <session>", "tmux session name")
+        .option("--window <window>", "tmux window target")
+        .action(async (query, options) => {
+        const output = await (0, find_1.find)(query, {
+            json: options.json,
+            session: options.session,
+            window: options.window
+        });
+        if (output) {
+            writeLine(process.stdout, output);
+        }
+    });
+    program.command("send")
+        .argument("<paneTarget>")
+        .argument("<text>")
+        .option("--json [boolean]", "output json", parseOptionalBoolean, false)
+        .option("--session <session>", "tmux session name")
+        .option("--window <window>", "tmux window target")
+        .option("--no-enter [boolean]", "do not submit Enter", parseOptionalBoolean, false)
+        .option("--enter-delay-ms <ms>", "delay before submitting Enter", parseNonNegativeNumber("enter-delay-ms"))
+        .action(async (target, text, options) => {
+        const output = await (0, send_1.send)(target, text, {
+            json: options.json,
+            session: options.session,
+            window: options.window,
+            noEnter: options.noEnter,
+            enterDelayMs: options.enterDelayMs
+        });
+        if (output) {
+            writeLine(process.stdout, output);
+        }
+    });
+    program.command("read")
+        .argument("<paneTarget>")
+        .option("--json [boolean]", "output json", parseOptionalBoolean, false)
+        .option("--session <session>", "tmux session name")
+        .option("--window <window>", "tmux window target")
+        .option("--lines <n>", "lines to capture", parseNonNegativeNumber("lines"))
+        .action(async (target, options) => {
+        const output = await (0, read_1.read)(target, {
+            json: options.json,
+            session: options.session,
+            window: options.window,
+            lines: options.lines
+        });
+        if (output) {
+            writeLine(process.stdout, output);
+        }
+    });
+    const codex = program.command("codex");
+    codex.command("send")
+        .argument("<paneTarget>")
+        .argument("<text>")
+        .option("--json [boolean]", "output json", parseOptionalBoolean, false)
+        .option("--session <session>", "tmux session name")
+        .option("--window <window>", "tmux window target")
+        .option("--submit <key>", "submit key (default Enter; use 'none' to disable)")
+        .option("--submit-delay-ms <ms>", "delay before submitting", parseNonNegativeNumber("submit-delay-ms"))
+        .option("--post-delay-ms <ms>", "delay after submit", parseNonNegativeNumber("post-delay-ms"))
+        .option("--capture-tail <n>", "capture tail lines (prints captured tail when not --json)", parseNonNegativeNumber("capture-tail"))
+        .action(async (target, text, options) => {
+        const output = await (0, send_2.codexSendCommand)(target, text, {
+            json: options.json,
+            session: options.session,
+            window: options.window,
+            submit: options.submit,
+            submitDelayMs: options.submitDelayMs,
+            postDelayMs: options.postDelayMs,
+            captureTail: options.captureTail
+        });
+        if (output) {
+            writeLine(process.stdout, output);
+        }
+    });
+    codex.command("session-info")
+        .argument("<paneTarget>")
+        .option("--json [boolean]", "output json", parseOptionalBoolean, false)
+        .option("--session <session>", "tmux session name")
+        .option("--window <window>", "tmux window target")
+        .action(async (target, options) => {
+        const output = await (0, sessionInfo_1.codexSessionInfoCommand)(target, {
+            json: options.json,
+            session: options.session,
+            window: options.window
+        });
+        if (output) {
+            writeLine(process.stdout, output);
+        }
+    });
+    const forkHome = codex.command("fork-home");
+    forkHome.command("prepare")
+        .option("--json [boolean]", "output json", parseOptionalBoolean, false)
+        .option("--parent-rollout <path>", "parent rollout path")
+        .option("--fork-home <path>", "fork CODEX_HOME path")
+        .option("--parent-codex-home <path>", "parent CODEX_HOME override")
+        .option("--run-id <id>", "run id for naming")
+        .option("--copy-config [boolean]", "copy config.toml", parseOptionalBoolean)
+        .option("--spec <spec>", "read json spec from stdin (use '-')")
+        .action(async (options) => {
+        const output = await (0, forkHome_1.codexForkHomePrepareCommand)({
+            json: options.json,
+            parentRollout: options.parentRollout,
+            forkHome: options.forkHome,
+            parentCodexHome: options.parentCodexHome,
+            runId: options.runId,
+            copyConfig: options.copyConfig,
+            spec: options.spec
+        });
+        if (output) {
+            writeLine(process.stdout, output);
+        }
+    });
+    forkHome.command("cleanup")
+        .option("--json [boolean]", "output json", parseOptionalBoolean, false)
+        .option("--path <path>", "path to remove")
+        .option("--allowed-root <root>", "allowed root guard")
+        .option("--spec <spec>", "read json spec from stdin (use '-')")
+        .action(async (options) => {
+        const output = await (0, forkHome_1.codexForkHomeCleanupCommand)({
+            json: options.json,
+            path: options.path,
+            allowedRoot: options.allowedRoot,
+            spec: options.spec
+        });
+        if (output) {
+            writeLine(process.stdout, output);
+        }
+    });
+    codex.command("spawn")
+        .option("--json [boolean]", "output json", parseOptionalBoolean, false)
+        .option("--origin <paneTarget>", "origin pane target")
+        .option("--session <session>", "tmux session name")
+        .option("--window <window>", "tmux window target")
+        .option("--force-simple-split [boolean]", "force fallback split", parseOptionalBoolean, false)
+        .action(async (options) => {
+        const output = await (0, spawn_1.codexSpawnCommand)({
+            json: options.json,
+            origin: options.origin,
+            session: options.session,
+            window: options.window,
+            forceSimpleSplit: options.forceSimpleSplit
+        });
+        if (output) {
+            writeLine(process.stdout, output);
+        }
+    });
+    const ui = program.command("ui");
+    ui.command("select")
+        .requiredOption("--spec <spec>", "read json spec from stdin (use '-')")
+        .option("--json [boolean]", "output json", parseOptionalBoolean, false)
+        .action(async (options) => {
+        const output = await (0, select_1.uiSelectCommand)({ json: options.json, spec: options.spec });
+        if (output) {
+            writeLine(process.stdout, output);
+        }
+    });
+    return program;
+}
+async function run() {
+    const argv = process.argv.slice(2);
+    if (argv.length === 0) {
+        throw new Error("missing command");
+    }
+    const program = buildProgram();
+    await program.parseAsync(process.argv);
+}
+run().catch((error) => {
+    if (error instanceof commander_1.CommanderError && error.exitCode === 0) {
+        return;
+    }
+    const message = formatError(error);
+    writeLine(process.stderr, message);
+    process.exitCode = 1;
+});

package/dist/cli/parse.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseOptions = parseOptions;
+function parseOptions(argv, spec) {
+    const options = {};
+    const positionals = [];
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--") {
+            positionals.push(...argv.slice(i + 1));
+            break;
+        }
+        if (arg.startsWith("--")) {
+            const [rawKey, inlineValue] = arg.split("=");
+            const key = rawKey.slice(2);
+            const specType = spec[key];
+            if (!specType) {
+                throw new Error(`unknown option --${key}`);
+            }
+            if (specType === "boolean") {
+                options[key] = inlineValue ? inlineValue !== "false" : true;
+                continue;
+            }
+            if (inlineValue !== undefined) {
+                options[key] = inlineValue;
+                continue;
+            }
+            const next = argv[i + 1];
+            if (!next || next.startsWith("--")) {
+                throw new Error(`missing value for --${key}`);
+            }
+            options[key] = next;
+            i += 1;
+            continue;
+        }
+        positionals.push(arg);
+    }
+    return { options, positionals };
+}

package/dist/lib/codex/forkHome.js

@@ -0,0 +1,101 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.prepareForkHome = prepareForkHome;
+exports.cleanupForkHome = cleanupForkHome;
+const node_fs_1 = require("node:fs");
+const node_path_1 = __importDefault(require("node:path"));
+const safeRm_1 = require("../fs/safeRm");
+function resolvePath(value) {
+    return node_path_1.default.resolve(value);
+}
+function defaultCodexHome() {
+    const env = process.env.CODEX_HOME?.trim();
+    if (env) {
+        return resolvePath(env);
+    }
+    return resolvePath(node_path_1.default.join(process.env.HOME || "", ".codex"));
+}
+async function copyOrSymlink(src, dst) {
+    try {
+        await node_fs_1.promises.stat(src);
+    }
+    catch {
+        return "missing";
+    }
+    try {
+        await node_fs_1.promises.mkdir(node_path_1.default.dirname(dst), { recursive: true });
+        try {
+            await node_fs_1.promises.unlink(dst);
+        }
+        catch {
+            // ignore
+        }
+        await node_fs_1.promises.symlink(src, dst);
+        return "symlink";
+    }
+    catch {
+        try {
+            await node_fs_1.promises.copyFile(src, dst);
+            return "copy";
+        }
+        catch {
+            return "failed";
+        }
+    }
+}
+function resolveForkRolloutPath(parentCodexHome, parentRolloutPath, forkHome, runId) {
+    try {
+        const relative = node_path_1.default.relative(parentCodexHome, parentRolloutPath);
+        if (!relative.startsWith("..") && !node_path_1.default.isAbsolute(relative)) {
+            return node_path_1.default.join(forkHome, relative);
+        }
+    }
+    catch {
+        // ignore
+    }
+    return node_path_1.default.join(forkHome, "sessions", `rollout-${runId}.jsonl`);
+}
+async function prepareForkHome(options) {
+    const parentCodexHome = resolvePath(options.parentCodexHome || defaultCodexHome());
+    const parentRolloutPath = resolvePath(options.parentRolloutPath);
+    const forkHome = resolvePath(options.forkHome);
+    const runId = options.runId?.trim() || String(process.pid);
+    const copyConfig = options.copyConfig ?? true;
+    const stat = await node_fs_1.promises.stat(parentRolloutPath);
+    if (!stat.isFile()) {
+        throw new Error(`parent_rollout_path is not a file: ${parentRolloutPath}`);
+    }
+    await node_fs_1.promises.mkdir(forkHome, { recursive: true });
+    let copiedConfig = false;
+    if (copyConfig) {
+        const configPath = node_path_1.default.join(parentCodexHome, "config.toml");
+        try {
+            await node_fs_1.promises.copyFile(configPath, node_path_1.default.join(forkHome, "config.toml"));
+            copiedConfig = true;
+        }
+        catch {
+            copiedConfig = false;
+        }
+    }
+    const authStrategy = await copyOrSymlink(node_path_1.default.join(parentCodexHome, "auth.json"), node_path_1.default.join(forkHome, "auth.json"));
+    const credentialsStrategy = await copyOrSymlink(node_path_1.default.join(parentCodexHome, ".credentials.json"), node_path_1.default.join(forkHome, ".credentials.json"));
+    const forkRolloutPath = resolveForkRolloutPath(parentCodexHome, parentRolloutPath, forkHome, runId);
+    await node_fs_1.promises.mkdir(node_path_1.default.dirname(forkRolloutPath), { recursive: true });
+    await node_fs_1.promises.copyFile(parentRolloutPath, forkRolloutPath);
+    return {
+        action: "prepare",
+        parent_rollout_path: parentRolloutPath,
+        fork_home: forkHome,
+        fork_rollout_path: forkRolloutPath,
+        copied_config: copiedConfig,
+        auth_strategy: authStrategy,
+        credentials_strategy: credentialsStrategy
+    };
+}
+async function cleanupForkHome(pathToRemove, allowedRoot) {
+    const removed = await (0, safeRm_1.safeRemove)(pathToRemove, allowedRoot);
+    return { action: "cleanup", removed };
+}

package/dist/lib/codex/isCodexPane.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isCodexPane = isCodexPane;
+const ps_1 = require("../proc/ps");
+const CODEX_PATTERN = /codex/i;
+function matchesCodex(value) {
+    return CODEX_PATTERN.test(value);
+}
+function hasCodexDescendant(processes, rootPid) {
+    const byParent = new Map();
+    for (const process of processes) {
+        const list = byParent.get(process.ppid);
+        if (list) {
+            list.push(process);
+        }
+        else {
+            byParent.set(process.ppid, [process]);
+        }
+    }
+    const queue = [rootPid];
+    const visited = new Set();
+    while (queue.length) {
+        const current = queue.shift();
+        if (current === undefined || visited.has(current)) {
+            continue;
+        }
+        visited.add(current);
+        const children = byParent.get(current);
+        if (!children) {
+            continue;
+        }
+        for (const child of children) {
+            if (matchesCodex(child.command)) {
+                return true;
+            }
+            queue.push(child.pid);
+        }
+    }
+    return false;
+}
+async function isCodexPane(pane) {
+    if (matchesCodex(pane.command) || matchesCodex(pane.title)) {
+        return true;
+    }
+    if (!pane.pid || !Number.isFinite(pane.pid)) {
+        return false;
+    }
+    try {
+        const processes = await (0, ps_1.listProcesses)();
+        return hasCodexDescendant(processes, pane.pid);
+    }
+    catch {
+        return false;
+    }
+}

package/dist/lib/codex/send.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.codexSend = codexSend;
+const capturePane_1 = require("../tmux/capturePane");
+const exec_1 = require("../tmux/exec");
+const paste_1 = require("../tmux/paste");
+const sendKeys_1 = require("../tmux/sendKeys");
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function normalizeTmuxKey(key) {
+    const parsed = (0, sendKeys_1.parseKeyExpression)(key);
+    return parsed ?? key;
+}
+async function codexSend(paneId, input, options = {}) {
+    const submitKey = options.submitKey?.trim() ?? "";
+    const submitDelayMs = Math.max(0, options.submitDelayMs ?? 0);
+    const postDelayMs = Math.max(0, options.postDelayMs ?? 0);
+    const captureTailLines = options.captureTailLines;
+    const tmuxKey = (0, sendKeys_1.parseKeyExpression)(input);
+    if (tmuxKey) {
+        await (0, exec_1.tmuxExec)(["send-keys", "-t", paneId, tmuxKey]);
+        if (postDelayMs > 0) {
+            await sleep(postDelayMs);
+        }
+        const capture_tail = captureTailLines && captureTailLines > 0
+            ? await (0, capturePane_1.capturePane)(paneId, captureTailLines)
+            : undefined;
+        return {
+            mode: "keys",
+            ...(capture_tail ? { capture_tail } : {})
+        };
+    }
+    await (0, paste_1.pasteText)(paneId, input);
+    if (submitKey) {
+        if (submitDelayMs > 0) {
+            await sleep(submitDelayMs);
+        }
+        await (0, exec_1.tmuxExec)(["send-keys", "-t", paneId, normalizeTmuxKey(submitKey)]);
+    }
+    if (postDelayMs > 0) {
+        await sleep(postDelayMs);
+    }
+    const capture_tail = captureTailLines && captureTailLines > 0
+        ? await (0, capturePane_1.capturePane)(paneId, captureTailLines)
+        : undefined;
+    return {
+        mode: "text",
+        ...(submitKey
+            ? {
+                submit: submitKey,
+                submit_delay_ms: submitDelayMs
+            }
+            : {}),
+        ...(postDelayMs > 0 ? { post_delay_ms: postDelayMs } : {}),
+        ...(capture_tail ? { capture_tail } : {})
+    };
+}