loreli 0.0.0 → 1.0.0

package/packages/tmux/src/index.js

@@ -0,0 +1,452 @@
+import { execFile as execFileCb, execFileSync } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const execFile = promisify(execFileCb);
+
+/**
+ * Clean, modern, ESM Node.js wrapper for tmux with pane-level control.
+ *
+ * Every method maps ~1:1 to a tmux CLI command using `node:child_process`.
+ * Zero npm dependencies.
+ *
+ * Sessions created via {@link Tmux#create} are tracked in an in-memory
+ * set so they can be batch-killed via {@link Tmux#cleanup}. For crash
+ * recovery where in-memory state is lost, {@link Tmux#prune} queries
+ * tmux directly by session-name prefix.
+ *
+ * @example
+ * ```js
+ * import { Tmux } from 'loreli/tmux';
+ *
+ * const tmux = new Tmux();
+ *
+ * // First agent IS the session's initial window — no garbage default window.
+ * const paneId = await tmux.create('my-session', { cwd: '/tmp', command: './run.sh' });
+ * await tmux.send(paneId, 'echo hello');
+ * const output = await tmux.capture(paneId);
+ *
+ * // Subsequent agents join as additional windows.
+ * const pane2 = await tmux.window('my-session', { cwd: '/tmp', command: './run2.sh' });
+ * ```
+ */
+export class Tmux {
+  /** @type {Set<string>} Sessions created by this instance. */
+  #sessions = new Set();
+
+  /**
+   * Check whether tmux is available on PATH without throwing.
+   *
+   * @returns {boolean} True if the tmux binary is reachable.
+   */
+  static available() {
+    try {
+      execFileSync('which', ['tmux'], { stdio: 'ignore' });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Execute a tmux command and return trimmed stdout.
+   *
+   * @param {string[]} args - Arguments to pass to the tmux binary.
+   * @returns {Promise<string>} Trimmed stdout from the command.
+   * @throws {Error} When the tmux command exits with non-zero status.
+   */
+  async #exec(args) {
+    try {
+      const { stdout } = await execFile('tmux', args);
+      return stdout.trimEnd();
+    } catch (err) {
+      throw new Error(err.stderr?.trim() || err.message);
+    }
+  }
+
+  // ── Session Management ──────────────────────────────────
+
+  /**
+   * Create a new detached tmux session.
+   *
+   * When `opts.command` is provided, it becomes the initial window's
+   * process — no empty default window is created. This lets tmux
+   * auto-destroy the session when all windows die, preventing orphans.
+   *
+   * When called without a command, a bare session with an empty default
+   * window is created (useful for test sessions with specific dimensions).
+   *
+   * @param {string} name - The session name.
+   * @param {object} [opts] - Session options.
+   * @param {number} [opts.width] - Initial window width (tmux -x flag).
+   * @param {number} [opts.height] - Initial window height (tmux -y flag).
+   * @param {string} [opts.cwd] - Working directory for the initial window.
+   * @param {string} [opts.command] - Command for the initial window.
+   * @returns {Promise<string|void>} Pane ID when command is provided, void otherwise.
+   * @throws {Error} When a session with the same name already exists.
+   */
+  async create(name, opts = {}) {
+    if (await this.has(name)) {
+      throw new Error(`Session "${name}" already exists`);
+    }
+
+    const args = ['new-session', '-d', '-s', name];
+
+    if (opts.width) args.push('-x', String(opts.width));
+    if (opts.height) args.push('-y', String(opts.height));
+
+    if (opts.command) {
+      args.push('-P', '-F', '#{pane_id}');
+      if (opts.cwd) args.push('-c', opts.cwd);
+      args.push(opts.command);
+      const paneId = await this.#exec(args);
+      this.#sessions.add(name);
+      return paneId;
+    }
+
+    if (opts.cwd) args.push('-c', opts.cwd);
+    await this.#exec(args);
+    this.#sessions.add(name);
+  }
+
+  /**
+   * Kill (destroy) a tmux session.
+   *
+   * @param {string} name - The session name to kill.
+   * @returns {Promise<void>}
+   * @throws {Error} When the session does not exist.
+   */
+  async kill(name) {
+    await this.#exec(['kill-session', '-t', name]);
+    this.#sessions.delete(name);
+  }
+
+  /**
+   * List all active tmux session names.
+   *
+   * @returns {Promise<string[]>} Array of session name strings.
+   */
+  async list() {
+    try {
+      const output = await this.#exec(['list-sessions', '-F', '#{session_name}']);
+      if (!output) return [];
+      return output.split('\n').filter(Boolean);
+    } catch {
+      // tmux returns error when no server is running
+      return [];
+    }
+  }
+
+  /**
+   * Check whether a session with the given name exists.
+   *
+   * @param {string} name - The session name to check.
+   * @returns {Promise<boolean>} True if the session exists.
+   */
+  async has(name) {
+    try {
+      await this.#exec(['has-session', '-t', name]);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Return session names created by this Tmux instance.
+   *
+   * @returns {string[]} Array of tracked session names.
+   */
+  owned() {
+    return [...this.#sessions];
+  }
+
+  /**
+   * Kill all sessions created by this instance. Best-effort — errors
+   * on individual sessions are swallowed so one stuck session does
+   * not prevent others from being cleaned. Clears the tracking set.
+   *
+   * @returns {Promise<void>}
+   */
+  async cleanup() {
+    for (const name of this.#sessions) {
+      try { await this.kill(name); } catch { /* session may already be gone */ }
+    }
+    this.#sessions.clear();
+  }
+
+  /**
+   * Kill all tmux sessions whose name starts with the given prefix.
+   * Queries tmux directly — does not rely on in-memory tracking.
+   *
+   * This is the crash-recovery / manual-reset path. It is destructive:
+   * any matching session is killed regardless of whether its agents are
+   * still doing useful work. For graceful lifecycle cleanup, prefer
+   * {@link Tmux#cleanup} which targets only sessions this instance created.
+   *
+   * @param {string} [prefix='loreli'] - Session name prefix to match.
+   * @returns {Promise<string[]>} Names of sessions that were killed.
+   */
+  async prune(prefix = 'loreli') {
+    const all = await this.list();
+    const targets = all.filter(function matches(n) { return n.startsWith(prefix); });
+    const killed = [];
+
+    for (const name of targets) {
+      try {
+        await this.kill(name);
+        killed.push(name);
+      } catch { /* session may have died between list and kill */ }
+    }
+
+    return killed;
+  }
+
+  // ── Stale Session Detection ─────────────────────────────
+
+  /**
+   * Check whether a session exists but was not created by this instance.
+   *
+   * A session is stale when it survives from a previous MCP server
+   * process. The current Tmux instance has no record of it because
+   * in-memory tracking is per-process. Stale sessions contain agent
+   * panes running with outdated environment variables (API keys,
+   * budgets, tokens) — spawning new agents into them inherits the
+   * old environment from the tmux server.
+   *
+   * @param {string} name - Session name to check.
+   * @returns {Promise<boolean>} True when the session exists and is unowned.
+   */
+  async stale(name) {
+    if (this.#sessions.has(name)) return false;
+    return this.has(name);
+  }
+
+  /**
+   * Destroy a stale session and report what was killed.
+   *
+   * Only acts on sessions not owned by this instance. Owned sessions
+   * are left untouched — this prevents accidental self-destruction
+   * during a start re-run within the same process.
+   *
+   * @param {string} name - Session name to reap.
+   * @returns {Promise<{killed: boolean, panes: number}>} Whether the
+   *   session was destroyed and how many panes it contained.
+   */
+  async reap(name) {
+    if (this.#sessions.has(name)) return { killed: false, panes: 0 };
+    if (!await this.has(name)) return { killed: false, panes: 0 };
+
+    let paneCount = 0;
+    try {
+      // -s lists panes across ALL windows in the session, not just the active one
+      const fmt = '#{pane_id}';
+      const output = await this.#exec(['list-panes', '-s', '-t', name, '-F', fmt]);
+      paneCount = output.split('\n').filter(Boolean).length;
+    } catch { /* session may be in a bad state — kill it anyway */ }
+
+    await this.kill(name);
+    return { killed: true, panes: paneCount };
+  }
+
+  // ── Pane Management ─────────────────────────────────────
+
+  /**
+   * Create a new window in the session and return its pane ID.
+   *
+   * Each agent gets its own full-size window instead of splitting an
+   * existing one. This avoids the `no space for new pane` error that
+   * occurs when too many agents share a single window via split-window.
+   *
+   * When `opts.command` is provided, it becomes the window's shell
+   * command — the process runs directly without an intermediate shell.
+   * This avoids issues with `.zshrc` prompts or other shell
+   * initialization that can intercept the first send-keys input.
+   *
+   * @param {string} session - The target session name.
+   * @param {object} [opts] - Window options.
+   * @param {string} [opts.cwd] - Working directory for the new window.
+   * @param {string} [opts.command] - Shell command to run directly.
+   * @returns {Promise<string>} The new pane ID (e.g. "%3").
+   */
+  async window(session, opts = {}) {
+    const args = ['new-window', '-d', '-P', '-F', '#{pane_id}', '-t', session];
+
+    if (opts.cwd) args.push('-c', opts.cwd);
+    if (opts.command) args.push(opts.command);
+
+    return this.#exec(args);
+  }
+
+  /**
+   * Split the current window into a new pane.
+   *
+   * @param {string} session - The target session name.
+   * @param {object} [opts] - Split options.
+   * @param {string} [opts.cwd] - Working directory for the new pane.
+   * @param {boolean} [opts.vertical] - Split vertically instead of horizontally.
+   * @returns {Promise<string>} The new pane ID (e.g. "%3").
+   */
+  async split(session, opts = {}) {
+    const args = ['split-window', '-d', '-P', '-F', '#{pane_id}', '-t', session];
+
+    if (opts.vertical) args.push('-h');
+    if (opts.cwd) args.push('-c', opts.cwd);
+
+    return this.#exec(args);
+  }
+
+  /**
+   * Send text to a pane followed by Enter.
+   *
+   * Text and Enter are sent as separate operations with a brief delay.
+   * TUI applications (Claude Code, Cursor Agent) run in raw TTY mode
+   * and process keystrokes via an async event loop. When send-keys
+   * delivers text + Enter in a single call, both arrive in one PTY
+   * read buffer. The TUI's event loop processes them in a single tick,
+   * causing Enter to be consumed by the text rendering pipeline instead
+   * of triggering "submit". Splitting into two calls guarantees Enter
+   * arrives in a separate stdin data event.
+   *
+   * @param {string} target - Pane ID or session:window.pane target.
+   * @param {string} text - The text to send.
+   * @returns {Promise<void>}
+   */
+  async send(target, text) {
+    await this.#exec(['send-keys', '-t', target, text]);
+    await new Promise(function settle(r) { setTimeout(r, 200); });
+    await this.#exec(['send-keys', '-t', target, 'Enter']);
+  }
+
+  /**
+   * Send raw key sequences to a pane without appending Enter.
+   *
+   * Useful for TUI navigation (arrow keys, Escape, Tab) where an
+   * automatic Enter would confirm the wrong selection. Each argument
+   * is a tmux key name: `Down`, `Up`, `Enter`, `Escape`, etc.
+   *
+   * @param {string} target - Pane ID or session:window.pane target.
+   * @param {...string} keys - One or more tmux key names to send.
+   * @returns {Promise<void>}
+   */
+  async keys(target, ...keys) {
+    await this.#exec(['send-keys', '-t', target, ...keys]);
+  }
+
+  /**
+   * Capture the visible content of a pane.
+   *
+   * Uses -J to join wrapped lines for clean output.
+   *
+   * @param {string} target - Pane ID or session:window.pane target.
+   * @param {number} [lines=500] - Number of history lines to capture.
+   * @returns {Promise<string>} The captured pane content.
+   */
+  async capture(target, lines = 500) {
+    return this.#exec([
+      'capture-pane', '-p', '-J', '-t', target, '-S', `-${lines}`
+    ]);
+  }
+
+  /**
+   * List panes in a session with metadata.
+   *
+   * @param {string} session - The session name.
+   * @returns {Promise<Array<{id: string, pid: string, active: boolean, title: string}>>}
+   */
+  async panes(session) {
+    const fmt = '#{pane_id}:#{pane_pid}:#{pane_active}:#{pane_title}';
+    const output = await this.#exec(['list-panes', '-t', session, '-F', fmt]);
+
+    return output.split('\n').filter(Boolean).map(function parsePane(line) {
+      const [id, pid, active, title] = line.split(':');
+      return { id, pid, active: active === '1', title: title ?? '' };
+    });
+  }
+
+  /**
+   * Check whether a pane's process is still running.
+   *
+   * Uses list-panes with a filter to reliably detect if the specific
+   * pane exists and is not dead. display-message can silently fall back
+   * to the active pane when the target no longer exists.
+   *
+   * @param {string} target - Pane ID.
+   * @returns {Promise<boolean>} True if the pane is alive.
+   */
+  async alive(target) {
+    try {
+      const output = await this.#exec([
+        'list-panes', '-a', '-F', '#{pane_id}:#{pane_dead}',
+        '-f', `#{==:#{pane_id},${target}}`
+      ]);
+
+      if (!output) return false;
+      const [, dead] = output.split(':');
+      return dead !== '1';
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Query the current foreground command running in a pane.
+   *
+   * Uses `pane_current_command` which reports the process name
+   * occupying the pane (e.g. 'zsh', 'claude', 'codex').
+   *
+   * @param {string} target - Pane ID.
+   * @returns {Promise<string>} Process name, or empty string if unknown.
+   */
+  async command(target) {
+    try {
+      return await this.#exec([
+        'display-message', '-t', target, '-p', '#{pane_current_command}'
+      ]);
+    } catch {
+      return '';
+    }
+  }
+
+  /**
+   * List all panes across all windows in a session.
+   *
+   * Unlike {@link Tmux#panes} which targets the current window,
+   * this uses `-s` to enumerate every pane in every window of the
+   * session. Essential for garbage collection and session-wide
+   * orphan detection.
+   *
+   * @param {string} session - The session name.
+   * @returns {Promise<Array<{id: string, pid: string, dead: boolean, title: string}>>}
+   */
+  async allPanes(session) {
+    const fmt = '#{pane_id}:#{pane_pid}:#{pane_dead}:#{pane_title}';
+    const output = await this.#exec(['list-panes', '-s', '-t', session, '-F', fmt]);
+
+    return output.split('\n').filter(Boolean).map(function parsePane(line) {
+      const [id, pid, dead, title] = line.split(':');
+      return { id, pid, dead: dead === '1', title: title ?? '' };
+    });
+  }
+
+  /**
+   * Kill a specific pane.
+   *
+   * @param {string} target - Pane ID to kill.
+   * @returns {Promise<void>}
+   */
+  async killPane(target) {
+    await this.#exec(['kill-pane', '-t', target]);
+  }
+
+  /**
+   * Set a pane option.
+   *
+   * @param {string} target - Pane ID.
+   * @param {string} option - The tmux option name (e.g. 'remain-on-exit').
+   * @param {string} value - The option value (e.g. 'on').
+   * @returns {Promise<void>}
+   */
+  async set(target, option, value) {
+    await this.#exec(['set-option', '-p', '-t', target, option, value]);
+  }
+}