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 `ccam-lane-<id>` (see
 * `pty-run.js`) so a real terminal can attach to the exact same session with
 * `tmux attach -t ccam-lane-<id>` (or `ccam 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).
 * The one place a command line is composed is `sendCommand`, which types into
 * an existing pane's shell: there the shell IS the consumer, so every argument
 * is POSIX single-quoted first and sent with `send-keys -l` (literal).
 * @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.
let execImpl = (args) => execFileSync("tmux", args, { encoding: "utf8" });

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

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

/** `-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 CCAM_LANE_ID so a `ccam`
 * call from inside the pane knows exactly which lane it belongs to instead of
 * guessing from cwd — see resolveLaneArg in bin/ccam.js.
 */
function newSession({ name, cwd, argv, env }) {
  execImpl(["new-session", "-d", "-s", name, "-c", cwd, ...envFlags(env), "--", ...argv]);
  enableMouse(name);
}

// 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.
function enableMouse(name) {
  execImpl(["set-option", "-t", name, "mouse", "on"]);
}

/**
 * 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", name, "#{pane_current_command}"]).trim() || null
    );
  } catch {
    return null;
  }
}

/** POSIX single-quote escaping — the pane is a shell, so argv must be quoted. */
function shellQuote(arg) {
  return `'${String(arg).replace(/'/g, `'\\''`)}'`;
}

/**
 * Type `argv` into an existing session's pane and press Enter. Only ever
 * called when the pane sits at a shell prompt (see `paneCommand`); `-l` sends
 * the string literally so no character is read as a tmux key name.
 *
 * `env` rides along as a shell assignment prefix on the SAME line — tmux's own
 * `-e` applies only at session creation, and a shell that is already running
 * takes its environment from the command line. The name is never quoted (bash
 * only recognizes an assignment when the `=` is unquoted); the value is.
 */
function sendCommand(name, argv, env) {
  const prefix = Object.entries(env || {})
    .map(([key, value]) => `${key}=${shellQuote(value)} `)
    .join("");
  execImpl(["send-keys", "-t", name, "-l", prefix + argv.map(shellQuote).join(" ")]);
  execImpl(["send-keys", "-t", name, "Enter"]);
}

/** Idempotent — a session that's already gone is not an error. */
function killSession(name) {
  try {
    execImpl(["kill-session", "-t", 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() {
  try {
    execImpl(["-V"]);
    return true;
  } catch {
    return false;
  }
}

module.exports = {
  hasSession,
  newSession,
  enableMouse,
  paneCommand,
  sendCommand,
  killSession,
  listSessions,
  isTmuxAvailable,
  __setExecImpl,
  __reset,
};