AgentHub/server/lib/tmux.js

/**
 * @file tmux.js
 * @description Thin wrapper around the `tmux` CLI for the terminal-run
 * feature. Every dashboard-managed session is named `agenthub-lane-<id>` (see
 * `pty-run.js`) so a real terminal can attach to the exact same session with
 * `tmux attach -t agenthub-lane-<id>` (or `agenthub lanes shell`). Never builds a
 * shell string — every call is `execFileSync("tmux", [...argv])` with an
 * explicit argument array (matches this repo's rule for git in worktree.js).
 * No call composes a shell command line at all, `sendCommand` included: it
 * takes over an idle pane with `respawn-pane -- <argv>` rather than typing a
 * quoted line into that pane's shell, which keeps an API key passed in `env`
 * out of the pane's rendered text, its scrollback and the user's shell history.
 * `sendText` is the one primitive that does send keystrokes — a pane running an
 * interactive chat program that reads stdin as a message, not a shell.
 * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
 */

const { execFileSync } = require("node:child_process");

// Test seam: swap the exec implementation so unit tests never invoke a real
// tmux binary. Mirrors run-spawner.js's __injectChildForTest/__reset style.
// stderr is ignored, not inherited: every caller already wraps these in
// try/catch and treats failure as "no session" — piping tmux's own
// "error connecting to ..." noise to the process's stderr just spams the
// journal on every poll while no tmux server is running yet.
const EXEC_OPTS = { encoding: "utf8", stdio: ["pipe", "pipe", "ignore"] };
let execImpl = (args) => execFileSync("tmux", args, EXEC_OPTS);

function __setExecImpl(fn) {
  execImpl = fn;
}
function __reset() {
  execImpl = (args) => execFileSync("tmux", args, EXEC_OPTS);
}

// tmux resolves a bare `-t agenthub-lane-1` by PREFIX when no exact match
// exists, so it would hit `agenthub-lane-12` once lane 1's session is gone —
// and killSession would kill the wrong lane. `=` forces an exact match; pane
// and option targets need the trailing `:` (tmux 3.4 rejects `=name` there).
const session = (name) => `=${name}`;
const pane = (name) => `=${name}:`;

function hasSession(name) {
  try {
    execImpl(["has-session", "-t", session(name)]);
    return true;
  } catch {
    return false;
  }
}

/** The running tmux server's pid, or null when none answers. */
function serverPid() {
  try {
    const pid = String(execImpl(["display-message", "-p", "#{pid}"])).trim();
    return /^\d+$/.test(pid) ? pid : null;
  } catch {
    return null;
  }
}

/** `-e NAME=value` pairs for tmux, in a stable order. */
function envFlags(env) {
  const flags = [];
  for (const [key, value] of Object.entries(env || {})) flags.push("-e", `${key}=${value}`);
  return flags;
}

/**
 * Create a detached tmux session running `argv` as the pane's command. Throws
 * if tmux itself fails to start (caller decides how to surface that).
 *
 * `env` becomes tmux `-e NAME=value` pairs, which tmux puts in the pane's own
 * environment (tmux >= 3.2). The dashboard uses it for AGENTHUB_LANE_ID so a `agenthub`
 * call from inside the pane knows exactly which lane it belongs to instead of
 * guessing from cwd — see resolveLaneArg in bin/agenthub.js.
 */
function newSession({ name, cwd, argv, env }) {
  // No argv = tmux's own default shell (a Windows Terminal pane).
  const cmd = argv.length ? ["--", ...argv] : [];
  execImpl(["new-session", "-d", "-s", name, "-c", cwd, ...envFlags(env), ...cmd]);
  try {
    enableMouse(name);
  } catch (err) {
    // The pane's command exited at once (a CLI that refuses the terminal tmux
    // gives it, say) and tmux closed the session with it: say that, not the
    // "Command failed: tmux set-option …" that hid the real problem.
    if (hasSession(name)) throw err;
    throw Object.assign(
      new Error(
        `the session's command exited as soon as it started: ${argv[0] || "the default shell"}`
      ),
      { code: "EPANEEXITED" }
    );
  }
}

// Without this the pane has no scrollbar/drag scroll at all — wheel events
// just pass through to the running program instead of entering tmux's own
// copy-mode scrollback. xterm.js forwards tmux's mouse-tracking escapes
// automatically once mouse mode is on, so no client-side change is needed.
// Called on every attach (not just at creation) so a session started before
// this option existed — or before a server restart picked up the change —
// still gets it; `set-option` is idempotent, so re-running it is harmless.
// The status bar goes off here too: the dashboard's tab bar already names the
// pane, and tmux's green line only eats a row of the terminal.
function enableMouse(name) {
  execImpl(["set-option", "-t", pane(name), "mouse", "on"]);
  execImpl(["set-option", "-t", pane(name), "status", "off"]);
  // A draggable scrollbar beside the pane (mouse mode makes it drag). Only a
  // tmux SERVER of 3.7+ knows the option; an older one refuses it, which is
  // fine — the pane just has none (`/agenthub-doctor` says how to upgrade).
  try {
    execImpl(["set-option", "-t", pane(name), "pane-scrollbars", "on"]);
    // tmux's default (`fg=white,bg=black,width=1`) is a one-column track in
    // ANSI black — the terminal theme's border colour, almost the background —
    // so it reads as no scrollbar at all. Bright slider. ONE column: tmux 3.7c
    // reserves `width` columns but paints only the first, so a second one is
    // never cleared and shows stale cells — a ghost second scrollbar.
    execImpl([
      "set-option",
      "-t",
      pane(name),
      "pane-scrollbars-style",
      "fg=brightwhite,bg=black,width=1,pad=0",
    ]);
  } catch {
    /* tmux < 3.7 */
  }
}

/**
 * The command currently running in the session's active pane (`bash`, `zsh`,
 * `claude`, …). Null when tmux can't answer — callers treat that as "unknown,
 * don't touch the pane".
 */
function paneCommand(name) {
  try {
    return (
      execImpl(["display-message", "-p", "-t", pane(name), "#{pane_current_command}"]).trim() ||
      null
    );
  } catch {
    return null;
  }
}

/**
 * Run `argv` in an existing session's pane. Only ever called when the pane sits
 * at a shell prompt (see `paneCommand`), so what `-k` kills is an idle shell.
 *
 * `respawn-pane` and not `send-keys`, because `env` may carry a secret — an AI
 * Router's API key, which Codex reads from the variable its `env_key` names.
 * Typing it would put a `KEY='sk-live-…' codex …` line into the pane's rendered
 * text, which the dashboard streams to every attached browser, into the tmux
 * scrollback, and into the user's shell history. `-e` hands the value to the
 * tmux server through argv instead, exactly as `newSession` already does, and
 * the pane never renders it. Running argv directly also means no shell to quote
 * for, so the whole class of quoting bugs goes with it.
 */
function sendCommand(name, argv, env, cwd) {
  execImpl([
    "respawn-pane",
    "-k",
    "-t",
    pane(name),
    ...(cwd ? ["-c", cwd] : []),
    ...envFlags(env),
    "--",
    ...argv,
  ]);
}

/**
 * Type a literal line of plain text into an existing pane and press Enter —
 * for a program that reads stdin as a message rather than a shell command
 * (an interactive `claude`/`codex` chat pane), where `sendCommand`'s POSIX
 * quoting and `KEY=value ` env prefix would show up as literal punctuation in
 * the message instead of being interpreted. `text` must be single-line: `-l`
 * sends it as one literal keystroke burst, so an embedded newline would submit
 * only the first line and leave the rest sitting unsent in the input box.
 */
function sendText(name, text) {
  execImpl(["send-keys", "-t", pane(name), "-l", text]);
  execImpl(["send-keys", "-t", pane(name), "Enter"]);
}

/**
 * Paste `text` into the pane as one bracketed paste, then press Enter. Unlike
 * `sendText` it may span lines: the text goes into a named buffer through an
 * argv element (`set-buffer -- <text>`), never a shell, and `-d` deletes the
 * buffer after the paste so a prompt does not linger in tmux's buffer list.
 */
function pasteText(name, text) {
  const buf = `agenthub-paste-${name}`;
  execImpl(["set-buffer", "-b", buf, "--", text]);
  execImpl(["paste-buffer", "-p", "-d", "-b", buf, "-t", pane(name)]);
  execImpl(["send-keys", "-t", pane(name), "Enter"]);
}

/** Idempotent — a session that's already gone is not an error. */
function killSession(name) {
  try {
    execImpl(["kill-session", "-t", session(name)]);
  } catch {
    /* already gone */
  }
}

/** Session names starting with `prefix`. Empty array if tmux has no server running at all. */
function listSessions(prefix) {
  let out;
  try {
    out = execImpl(["list-sessions", "-F", "#{session_name}"]);
  } catch {
    return [];
  }
  return out
    .split("\n")
    .map((s) => s.trim())
    .filter((s) => s && s.startsWith(prefix));
}

function isTmuxAvailable() {
  return clientVersion() !== null;
}

/** The tmux binary's version (`3.7c`, `next-3.8`), null when it is absent. */
function clientVersion() {
  try {
    return execImpl(["-V"])
      .trim()
      .replace(/^tmux\s+/, "");
  } catch {
    return null;
  }
}

/** The RUNNING server's version, null when none runs. A server started before
 *  an upgrade keeps its old version until every tmux session has closed. */
function serverVersion() {
  try {
    return execImpl(["display-message", "-p", "#{version}"]).trim() || null;
  } catch {
    return null;
  }
}

module.exports = {
  hasSession,
  newSession,
  enableMouse,
  paneCommand,
  sendCommand,
  sendText,
  pasteText,
  killSession,
  listSessions,
  isTmuxAvailable,
  clientVersion,
  serverVersion,
  serverPid,
  __setExecImpl,
  __reset,
};