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

/** `-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 }) {
  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", pane(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", 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() {
  try {
    execImpl(["-V"]);
    return true;
  } catch {
    return false;
  }
}

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