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);

// Linux: the tmux server lives in the cgroup of whatever started it — the
// dashboard's systemd unit, or the terminal/IDE scope a dev server runs in —
// and dies when that cgroup is stopped (an update's restart under a unit
// without KillMode=process, systemd-oomd, closing that app). So the FIRST
// session, which starts the server, is created inside a transient scope of
// its own: panes end only on Quit (`quit.js`) or with the machine. `--scope`
// runs tmux as a child, so it keeps this process's environment.
const realScopeImpl = (args) =>
  execFileSync(
    "systemd-run",
    [
      "--user",
      "--scope",
      "--quiet",
      "--collect",
      "--description=AgentHub tmux server",
      "--",
      "tmux",
      ...args,
    ],
    EXEC_OPTS
  );
let scopeImpl = realScopeImpl;

// Whether this tmux takes `=name` targets: true for tmux itself, false for
// psmux (the WinGet `tmux` on Windows), null until a live session has shown
// which. A fake exec in a test is real tmux unless it says otherwise.
let exactTargets = null;

function __setExecImpl(fn, { exact = true } = {}) {
  execImpl = fn;
  scopeImpl = null; // a fake tmux never starts a real scope

  exactTargets = exact;
  listed = null;
}
function __setScopeImpl(fn) {
  scopeImpl = fn;
}
function __reset() {
  execImpl = (args) => execFileSync("tmux", args, EXEC_OPTS);
  scopeImpl = realScopeImpl;
  exactTargets = null;
  listed = null;
}

// The `list-sessions` answer, shared for LIST_TTL_MS. Every open dashboard
// polls GET /api/run, and each synchronous spawn forks this whole process —
// measured 2,247 calls, 60 s of a 90 s run blocked, at 10 browsers. A session
// this process creates or kills clears it, so only a pane that exits on its
// own can read as live for up to a second. "No server" (exit 1) is an answer
// too and is shared; any other failure is not.
const LIST_TTL_MS = 1000;
let listed = null; // { at, out } | { at, err }
function listOutput() {
  if (listed && Date.now() - listed.at < LIST_TTL_MS) {
    if (listed.err) throw listed.err;
    return listed.out;
  }
  try {
    const out = String(execImpl(["list-sessions", "-F", "#{session_name}"]));
    listed = { at: Date.now(), out };
    return out;
  } catch (err) {
    listed = err.status === 1 || err.code === "ENOENT" ? { at: Date.now(), err } : null;
    throw err;
  }
}

/**
 * Probe once, on a session that exists: `=name` failing where the bare name
 * answers means this tmux has no exact-match syntax (psmux answers
 * "no server running on session '=name'"), so every target there is the bare
 * name. Until a session exists to ask, tmux's own syntax.
 */
function exact() {
  if (exactTargets !== null) return exactTargets;
  let first;
  try {
    first = String(execImpl(["list-sessions", "-F", "#{session_name}"]))
      .split("\n")
      .map((x) => x.trim())
      .find(Boolean);
  } catch {
    return true;
  }
  if (!first) return true;
  const answers = (t) => {
    try {
      execImpl(["has-session", "-t", t]);
      return true;
    } catch {
      return false;
    }
  };
  if (answers(`=${first}`)) exactTargets = true;
  else if (answers(first)) exactTargets = false;
  return exactTargets ?? true;
}

// 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).
// psmux has neither form and names a session by its bare name.
const session = (name) => (exact() ? `=${name}` : name);
const pane = (name) => (exact() ? `=${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] : [];
  listed = null;
  const args = ["new-session", "-d", "-s", name, "-c", cwd, ...envFlags(env), ...cmd];
  if (scopeImpl && process.platform === "linux" && !serverPid()) {
    try {
      scopeImpl(args);
    } catch {
      // No user manager (SSH without linger, no systemd): the plain start.
      if (!hasSession(name)) execImpl(args);
    }
  } else {
    execImpl(args);
  }
  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) {
  // tmux runs `;`-separated commands from ONE argv (each tmux call is a
  // synchronous spawn on the event loop), stopping at the first that fails —
  // so the options every tmux knows go first, in their own call. psmux (no
  // `=name` targets) is not known to chain, so it gets one call per option.
  const run = (...cmds) => {
    if (exact()) return execImpl(cmds.flatMap((c, i) => (i ? [";", ...c] : c)));
    for (const c of cmds) execImpl(c);
  };
  run(
    ["set-option", "-t", pane(name), "mouse", "on"],
    ["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 {
    run(
      ["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.
      [
        "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) {
  listed = null;
  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 = listOutput();
  } catch {
    return [];
  }
  return out
    .split("\n")
    .map((s) => s.trim())
    .filter((s) => s && s.startsWith(prefix));
}

/**
 * Every live session name from ONE `list-sessions` — what a poll asks instead
 * of a synchronous has-session per name, each of which blocks the event loop
 * (and so every terminal keystroke) for a whole tmux spawn. Empty when no
 * server runs (tmux exits 1) or tmux is not installed; null when the call
 * itself failed (EAGAIN/ENOMEM under memory pressure), which proves nothing
 * about the panes — a caller must not read that as "every pane is gone".
 */
function liveSessions() {
  try {
    return new Set(
      listOutput()
        .split("\n")
        .map((s) => s.trim())
        .filter(Boolean)
    );
  } catch (err) {
    return err.status === 1 || err.code === "ENOENT" ? new Set() : null;
  }
}

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 = {
  __setScopeImpl,
  session,
  pane,
  hasSession,
  newSession,
  enableMouse,
  paneCommand,
  sendCommand,
  sendText,
  pasteText,
  killSession,
  listSessions,
  liveSessions,
  isTmuxAvailable,
  clientVersion,
  serverVersion,
  serverPid,
  __setExecImpl,
  __reset,
};