tmuxes 0.1.7 → 0.1.9

package/server/src/targets.ts

@@ -0,0 +1,152 @@
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { isValidHostAlias, parseHostSpec } from './validate.js';
+import { isWindows } from './platform.js';
+import { listWslDistros } from './wsl.js';
+import { winShell } from './winshell/manager.js';
+import { log } from './logger.js';
+
+export interface Target {
+  /** Stable, URL-safe id used in REST paths and the WS query. */
+  id: string;
+  kind: 'local' | 'ssh' | 'wsl' | 'winlocal';
+  label: string;
+  /** ssh destination host or config-alias (ssh targets only). */
+  host?: string;
+  /** ssh user (undefined when a ~/.ssh/config alias supplies it). */
+  user?: string;
+  /** ssh port (undefined when default / config supplies it). */
+  port?: number;
+  /** WSL distro name (wsl targets only). */
+  distro?: string;
+  /** Launchable shells (winlocal target only). */
+  shells?: { id: string; label: string }[];
+}
+
+/** Native Windows shells (PowerShell/cmd via ConPTY). Enabled on Windows, or
+ *  anywhere via TMUXES_FAKE_WINSHELL for testing the path on Linux/macOS. */
+const WINSHELL_ENABLED = isWindows || !!process.env.TMUXES_FAKE_WINSHELL;
+
+function winlocalTarget(): Target {
+  return {
+    id: 'winlocal',
+    kind: 'winlocal',
+    label: isWindows ? 'Windows (local)' : 'Local shell (fake)',
+    shells: winShell.listShells(),
+  };
+}
+
+const ID_RE = /^[A-Za-z0-9._-]{1,128}$/;
+
+export function isValidTargetId(id: unknown): id is string {
+  return typeof id === 'string' && ID_RE.test(id);
+}
+
+function slug(s: string): string {
+  return s.replace(/[^A-Za-z0-9._-]/g, '-');
+}
+
+const LOCAL: Target = { id: 'local', kind: 'local', label: 'Local' };
+
+/** Best-effort, read-only parse of ~/.ssh/config Host aliases (no wildcards). */
+function parseSshConfig(): Target[] {
+  const path = join(homedir(), '.ssh', 'config');
+  let text: string;
+  try {
+    text = readFileSync(path, 'utf8');
+  } catch {
+    return []; // no config file is normal
+  }
+
+  const targets: Target[] = [];
+  const seen = new Set<string>();
+  for (const rawLine of text.split('\n')) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith('#')) continue;
+    const m = /^Host\s+(.+)$/i.exec(line);
+    if (!m) continue;
+    for (const token of m[1].split(/\s+/)) {
+      // Skip wildcard / negated patterns — they aren't concrete hosts.
+      if (token.includes('*') || token.includes('?') || token.startsWith('!')) continue;
+      if (!isValidHostAlias(token) || seen.has(token)) continue;
+      seen.add(token);
+      targets.push({ id: `cfg-${slug(token)}`, kind: 'ssh', label: token, host: token });
+    }
+  }
+  return targets;
+}
+
+/** Parse the TMUXES_HOSTS="alice@web1,bob@db2:2222" override. */
+function parseEnvHosts(): Target[] {
+  const env = process.env.TMUXES_HOSTS;
+  if (!env) return [];
+  const targets: Target[] = [];
+  for (const part of env.split(',')) {
+    const spec = parseHostSpec(part);
+    if (!spec) {
+      log.warn(`ignoring invalid TMUXES_HOSTS entry: ${part.trim()}`);
+      continue;
+    }
+    const label = `${spec.user ? `${spec.user}@` : ''}${spec.host}${spec.port ? `:${spec.port}` : ''}`;
+    targets.push({
+      id: `env-${slug(label)}`,
+      kind: 'ssh',
+      label,
+      host: spec.host,
+      user: spec.user,
+      port: spec.port,
+    });
+  }
+  return targets;
+}
+
+function sshTargets(): Target[] {
+  const all = [...parseEnvHosts(), ...parseSshConfig()];
+  const byId = new Map<string, Target>();
+  for (const t of all) if (!byId.has(t.id)) byId.set(t.id, t);
+  return [...byId.values()];
+}
+
+/** The synchronous part of the target list (everything except WSL discovery). */
+function baseTargets(): Target[] {
+  const base: Target[] = [];
+  if (WINSHELL_ENABLED) base.push(winlocalTarget());
+  // Windows has no native tmux; its "local" machine is reached through WSL.
+  if (!isWindows) base.push(LOCAL);
+  return [...base, ...sshTargets()];
+}
+
+// Cache so the (async, Windows-only) WSL discovery doesn't run on the WS
+// upgrade path. The client always GETs /api/targets first, which refreshes it.
+let cachedTargets: Target[] = baseTargets();
+
+/** Recompute the full target list, including WSL distros on Windows. */
+export async function refreshTargets(): Promise<Target[]> {
+  if (isWindows) {
+    const distros = await listWslDistros();
+    const wsl: Target[] = distros.map((name) => ({
+      id: `wsl-${slug(name)}`,
+      kind: 'wsl',
+      label: name,
+      distro: name,
+    }));
+    cachedTargets = [winlocalTarget(), ...wsl, ...sshTargets()];
+  } else {
+    cachedTargets = baseTargets();
+  }
+  return cachedTargets;
+}
+
+export function listTargets(): Target[] {
+  return cachedTargets;
+}
+
+export function getTarget(id: string): Target | undefined {
+  return cachedTargets.find((t) => t.id === id);
+}
+
+/** ssh destination string: "user@host" or just the config alias / host. */
+export function sshDestination(t: Target): string {
+  return t.user ? `${t.user}@${t.host}` : `${t.host}`;
+}

package/server/src/tmux/builder.ts

@@ -0,0 +1,198 @@
+import { createHash } from 'node:crypto';
+import { mkdirSync } from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { config } from '../config.js';
+import { sshDestination, type Target } from '../targets.js';
+import { isWindows } from '../platform.js';
+
+/**
+ * Single-quote a string for a POSIX shell. Needed ONLY for the remote ssh path:
+ * ssh concatenates the remote command words with spaces and re-parses them
+ * through the remote login shell, so each tmux arg must survive that re-parse.
+ * Local commands use pure argv (no shell) and need no quoting.
+ */
+export function sshQuote(arg: string): string {
+  return `'${arg.replace(/'/g, `'\\''`)}'`;
+}
+
+/** Local tmux management/attach argv — passed straight to spawn (shell:false). */
+export function localTmux(sub: string[]): string[] {
+  return ['tmux', ...sub];
+}
+
+function sshControlDir(): string | null {
+  // OpenSSH connection sharing avoids repeated TCP/auth handshakes for sidebar
+  // polling and file operations. Windows OpenSSH accepts the config but fails
+  // at runtime on mux sockets, so Windows management uses an app-owned SSH
+  // session instead of ControlMaster.
+  if (isWindows) return null;
+
+  const uid = process.getuid?.() ?? 'user';
+  const dir = join(tmpdir(), `tmuxes-ssh-${uid}`);
+  try {
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+  } catch {
+    return null;
+  }
+  return dir;
+}
+
+export function sshControlPath(t: Target): string | null {
+  const dir = sshControlDir();
+  if (!dir) return null;
+  const key = `${sshDestination(t)}:${t.port ?? 22}:${t.id}`;
+  return join(dir, createHash('sha1').update(key).digest('hex'));
+}
+
+function sshMultiplexArgs(t: Target): string[] {
+  const path = sshControlPath(t);
+  if (!path) return [];
+
+  return [
+    '-o',
+    'ControlMaster=auto',
+    '-o',
+    `ControlPath=${path}`,
+    '-o',
+    `ControlPersist=${config.ssh.controlPersist}`,
+  ];
+}
+
+export function sshClientArgs(
+  t: Target,
+  opts: { tty?: boolean; batchMode?: boolean; connectTimeout: number; multiplex?: boolean },
+): string[] {
+  const portArgs = t.port ? ['-p', String(t.port)] : [];
+  return [
+    'ssh',
+    ...(opts.tty ? ['-tt'] : []),
+    ...(opts.batchMode ? ['-o', 'BatchMode=yes'] : []),
+    '-o',
+    `ConnectTimeout=${opts.connectTimeout}`,
+    ...(opts.multiplex === false ? ['-o', 'ControlMaster=no'] : sshMultiplexArgs(t)),
+    ...portArgs,
+    sshDestination(t),
+  ];
+}
+
+/**
+ * Remote tmux argv via the system ssh binary.
+ * - tty:false (management) → BatchMode + short ConnectTimeout so it fails fast
+ *   and never hangs on a prompt. Remote args are sshQuote'd.
+ * - tty:true (interactive attach) → -tt forces a remote PTY (and SIGWINCH
+ *   propagation). BatchMode is left default so host-key/agent prompts surface
+ *   in the terminal. tmuxes does not force ServerAliveInterval; users can set
+ *   keepalives in ~/.ssh/config if their site allows them. Remote args are NOT
+ *   quoted here: this argv is handed to a PTY where the remote command words go
+ *   to ssh as separate argv elements and our inputs are already allowlist-
+ *   validated.
+ */
+export function remoteTmux(
+  t: Target,
+  sub: string[],
+  opts: { tty: boolean; multiplex?: boolean },
+): string[] {
+  if (opts.tty) {
+    return [
+      ...sshClientArgs(t, {
+        tty: true,
+        connectTimeout: config.ssh.connectTimeoutTty,
+        multiplex: opts.multiplex,
+      }),
+      'tmux',
+      ...sub,
+    ];
+  }
+
+  return [
+    ...sshClientArgs(t, {
+      batchMode: true,
+      connectTimeout: config.ssh.connectTimeoutMgmt,
+      multiplex: opts.multiplex,
+    }),
+    'tmux',
+    ...sub.map(sshQuote),
+  ];
+}
+
+/**
+ * tmux inside a WSL distro (Windows host). We use `--exec` (NOT `--`): `--`
+ * runs the command through the distro's login shell, which would re-parse tmux
+ * format strings (`#{...}` is a comment, `|` a pipe) and mangle them; `--exec`
+ * execs the binary directly with no shell, so argv maps straight through with
+ * no quoting — like the local path. The interactive case sets TERM via `env`
+ * because WSL does not inherit the Windows TERM.
+ */
+export function wslTmux(distro: string, sub: string[], opts: { tty: boolean }): string[] {
+  const prefix = opts.tty ? ['env', 'TERM=xterm-256color', 'tmux'] : ['tmux'];
+  return ['wsl.exe', '-d', distro, '--exec', ...prefix, ...sub];
+}
+
+/**
+ * Build a non-PTY argv to run an ARBITRARY command on a target (tmux, ls, cat,
+ * display-message, …). Same transport rules as management tmux: local runs the
+ * argv directly, wsl uses `--exec` (no shell), ssh uses BatchMode + sshQuote.
+ */
+export function commandArgv(
+  t: Target,
+  argv: string[],
+  opts: { multiplex?: boolean } = {},
+): { file: string; args: string[] } {
+  let full: string[];
+  if (t.kind === 'local') {
+    full = argv;
+  } else if (t.kind === 'wsl') {
+    full = ['wsl.exe', '-d', t.distro ?? '', '--exec', ...argv];
+  } else {
+    full = [
+      ...sshClientArgs(t, {
+        batchMode: true,
+        connectTimeout: config.ssh.connectTimeoutMgmt,
+        multiplex: opts.multiplex,
+      }),
+      ...argv.map(sshQuote),
+    ];
+  }
+  return { file: full[0], args: full.slice(1) };
+}
+
+/** Build a management argv (no PTY) for a local / ssh / wsl target. */
+export function managementArgv(
+  t: Target,
+  sub: string[],
+  opts: { multiplex?: boolean } = {},
+): { file: string; args: string[] } {
+  return commandArgv(t, ['tmux', ...sub], opts);
+}
+
+/**
+ * Build the create-a-new-session argv, always starting in the user's HOME:
+ * - local → tmux `-c <homedir>` (explicit, regardless of the server's cwd),
+ * - wsl   → `wsl --cd ~` runs the command from the distro's home; tmux inherits,
+ * - ssh   → the remote command already runs from the remote `$HOME`; tmux inherits.
+ * `sub` is the new-session subcommand (named or auto-named `-P` form).
+ */
+export function newSessionArgv(
+  t: Target,
+  sub: string[],
+  opts: { multiplex?: boolean } = {},
+): { file: string; args: string[] } {
+  if (t.kind === 'local') {
+    return { file: 'tmux', args: [...sub, '-c', homedir()] };
+  }
+  if (t.kind === 'wsl') {
+    return { file: 'wsl.exe', args: ['-d', t.distro ?? '', '--cd', '~', '--exec', 'tmux', ...sub] };
+  }
+  return commandArgv(t, ['tmux', ...sub], opts);
+}
+
+/** Build an interactive attach argv (run inside a PTY) for a local / ssh / wsl target. */
+export function attachArgv(t: Target, session: string): { file: string; args: string[] } {
+  const sub = ['new-session', '-A', '-s', session]; // NO -d: the PTY supplies the terminal
+  let argv: string[];
+  if (t.kind === 'local') argv = localTmux(sub);
+  else if (t.kind === 'wsl') argv = wslTmux(t.distro ?? '', sub, { tty: true });
+  else argv = remoteTmux(t, sub, { tty: true });
+  return { file: argv[0], args: argv.slice(1) };
+}

package/server/src/tmux/formats.ts

@@ -0,0 +1,95 @@
+/** tmux -F format strings + parsers.
+ *
+ *  tmux ESCAPES control characters in -F output (e.g. 0x1f comes back as the
+ *  literal text "\037"), so we cannot use a control byte as a separator. We use
+ *  a printable "|" and place the only free-form field (the name) LAST, then
+ *  rejoin the remainder — robust even if a name itself contains "|", because
+ *  the leading numeric fields never do. */
+
+import { AGENT_OPTION, parseAgentValue, type AgentKind, type AgentState, type AttentionReason } from '../agentState.js';
+
+const SEP = '|';
+
+export const SESSION_FORMAT = [
+  '#{session_windows}',
+  '#{session_attached}',
+  '#{session_created}',
+  '#{session_activity}', // epoch from tmux; kept for display/debug
+  `#{${AGENT_OPTION}}`, // agent hook state: "<kind>:<state>:<reason>:<event>:<nonce>"
+  '#{session_name}', // free-form → must be last
+].join(SEP);
+
+export const WINDOW_FORMAT = [
+  '#{window_index}',
+  '#{window_panes}',
+  '#{window_active}',
+  '#{window_name}', // free-form → must be last
+].join(SEP);
+
+export interface SessionInfo {
+  name: string;
+  windows: number;
+  attached: boolean;
+  /** unix epoch seconds */
+  created: number;
+  /** unix epoch seconds from tmux; kept for display/debug. */
+  lastActivity: number;
+  /** Recognized agent whose hooks are driving status. */
+  agentKind?: AgentKind;
+  /** Agent lifecycle state from official hooks. */
+  agentState?: AgentState;
+  /** Why this session is asking for attention, when known. */
+  attentionReason?: AttentionReason;
+  /** Hook event that last updated the state. */
+  agentEvent?: string;
+  /** Monotonic-ish event token for client edge detection. */
+  agentNonce?: string;
+}
+
+export interface WindowInfo {
+  index: number;
+  name: string;
+  panes: number;
+  active: boolean;
+}
+
+export function parseSessions(stdout: string): SessionInfo[] {
+  return stdout
+    .split('\n')
+    .filter((l) => l.length > 0)
+    .map((line) => {
+      const parts = line.split(SEP);
+      const agent = parseAgentValue(parts[4] || '');
+      return {
+        windows: Number(parts[0]) || 0,
+        attached: Number(parts[1]) > 0,
+        created: Number(parts[2]) || 0,
+        lastActivity: Number(parts[3]) || 0,
+        ...agent,
+        name: parts.slice(5).join(SEP), // name may legitimately contain "|"
+      };
+    })
+    .filter((s) => s.name);
+}
+
+export function parseWindows(stdout: string): WindowInfo[] {
+  return stdout
+    .split('\n')
+    .filter((l) => l.length > 0)
+    .map((line) => {
+      const parts = line.split(SEP);
+      return {
+        index: Number(parts[0]) || 0,
+        panes: Number(parts[1]) || 0,
+        active: Number(parts[2]) > 0,
+        name: parts.slice(3).join(SEP),
+      };
+    });
+}
+
+/** stderr patterns that mean "no sessions" rather than a real error. */
+const EMPTY_RE = /no server running|no sessions|error connecting to/i;
+
+export function isEmptySessionsError(stderr: string): boolean {
+  return EMPTY_RE.test(stderr);
+}

package/server/src/tmux/sessions.ts

@@ -0,0 +1,204 @@
+import { managementArgv, newSessionArgv } from './builder.js';
+import type { Target } from '../targets.js';
+import { runTargetCommand } from '../targetCommand.js';
+import {
+  AGENT_OPTION,
+  agentValue,
+  agentInitialValue,
+  parseAgentValue,
+} from '../agentState.js';
+import { augmentAgentCommand } from '../agentHooks.js';
+import { classifyAgentTerminalError } from '../agentOutput.js';
+import {
+  SESSION_FORMAT,
+  WINDOW_FORMAT,
+  parseSessions,
+  parseWindows,
+  isEmptySessionsError,
+  type SessionInfo,
+  type WindowInfo,
+} from './formats.js';
+import { isValidSessionName } from '../validate.js';
+
+export type LaunchAgent = 'claude' | 'codex';
+
+/** A management error carrying the HTTP status the router should return. */
+export class TmuxError extends Error {
+  constructor(
+    public status: number,
+    message: string,
+  ) {
+    super(message);
+    this.name = 'TmuxError';
+  }
+}
+
+// Hard ceiling so a wedged ssh can never hang a request (ssh also has ConnectTimeout).
+const REMOTE_TIMEOUT_MS = 15_000;
+
+function timeoutFor(target: Target): number | undefined {
+  // Bound ssh (network) and wsl (possible cold start) so a request can't hang.
+  return target.kind === 'local' ? undefined : REMOTE_TIMEOUT_MS;
+}
+
+async function run(target: Target, sub: string[]) {
+  return runTargetCommand(target, (opts) => managementArgv(target, sub, opts), {
+    timeoutMs: timeoutFor(target),
+  });
+}
+
+function firstStderrLine(stderr: string): string {
+  return stderr.trim().split('\n')[0] || 'command failed';
+}
+
+export async function listSessions(target: Target): Promise<SessionInfo[]> {
+  const r = await run(target, ['list-sessions', '-F', SESSION_FORMAT]);
+  if (r.code === 0) return reconcileAgentTerminalErrors(target, parseSessions(r.stdout));
+  // "no server running" / "no sessions" is the normal empty case.
+  if (isEmptySessionsError(r.stderr)) return [];
+  throw new TmuxError(502, firstStderrLine(r.stderr));
+}
+
+async function reconcileAgentTerminalErrors(
+  target: Target,
+  sessions: SessionInfo[],
+): Promise<SessionInfo[]> {
+  return Promise.all(sessions.map((session) => reconcileAgentTerminalError(target, session)));
+}
+
+async function reconcileAgentTerminalError(
+  target: Target,
+  session: SessionInfo,
+): Promise<SessionInfo> {
+  if (!session.agentKind || session.agentState !== 'running') return session;
+
+  const pane = await run(target, ['capture-pane', '-t', session.name, '-p', '-S', '-20']);
+  if (pane.code !== 0) return session;
+
+  const event = classifyAgentTerminalError(pane.stdout, session.agentKind);
+  if (!event) return session;
+
+  const value = agentValue(session.agentKind, 'idle', 'error', event, String(Date.now()));
+  const set = await run(target, ['set-option', '-t', session.name, '-q', AGENT_OPTION, value]);
+  if (set.code !== 0) return session;
+
+  const snapshot = parseAgentValue(value);
+  return snapshot ? { ...session, ...snapshot } : session;
+}
+
+export async function createSession(
+  target: Target,
+  opts: { name?: string; command?: string },
+): Promise<{ name: string }> {
+  let name = opts.name;
+
+  // New sessions always start in the user's home directory (newSessionArgv).
+  if (name) {
+    if (!isValidSessionName(name)) throw new TmuxError(400, 'invalid session name');
+    const sessionName = name;
+    const r = await runTargetCommand(
+      target,
+      (opts) => newSessionArgv(target, ['new-session', '-d', '-s', sessionName], opts),
+      { timeoutMs: timeoutFor(target) },
+    );
+    if (r.code !== 0) {
+      if (/duplicate session/i.test(r.stderr)) {
+        throw new TmuxError(409, `session "${name}" already exists`);
+      }
+      throw new TmuxError(502, firstStderrLine(r.stderr));
+    }
+  } else {
+    // Let tmux assign a numeric name and report it back.
+    const r = await runTargetCommand(
+      target,
+      (opts) => newSessionArgv(target, ['new-session', '-d', '-P', '-F', '#{session_name}'], opts),
+      { timeoutMs: timeoutFor(target) },
+    );
+    if (r.code !== 0) throw new TmuxError(502, firstStderrLine(r.stderr));
+    name = r.stdout.trim();
+  }
+
+  if (opts.command && opts.command.length > 0) {
+    const augmented = augmentAgentCommand(opts.command);
+    if (augmented.kind) {
+      await run(target, [
+        'set-option',
+        '-t',
+        name,
+        '-q',
+        AGENT_OPTION,
+        agentInitialValue(augmented.kind),
+      ]);
+    }
+    // Type the command literally, then press Enter. Two send-keys calls so the
+    // command text can never be misparsed as a key name.
+    await run(target, ['send-keys', '-t', name, '-l', augmented.command]);
+    await run(target, ['send-keys', '-t', name, 'Enter']);
+  }
+
+  return { name };
+}
+
+export async function launchAgentInSession(
+  target: Target,
+  name: string,
+  agent: LaunchAgent,
+): Promise<void> {
+  const augmented = augmentAgentCommand(agent);
+  if (!augmented.kind) throw new TmuxError(400, 'unsupported agent');
+
+  const set = await run(target, [
+    'set-option',
+    '-t',
+    name,
+    '-q',
+    AGENT_OPTION,
+    agentInitialValue(augmented.kind),
+  ]);
+  if (set.code !== 0) {
+    if (/can't find session|session not found|no server running/i.test(set.stderr)) {
+      throw new TmuxError(404, `session "${name}" not found`);
+    }
+    throw new TmuxError(502, firstStderrLine(set.stderr));
+  }
+
+  const send = await run(target, ['send-keys', '-t', name, '-l', augmented.command]);
+  if (send.code !== 0) throw new TmuxError(502, firstStderrLine(send.stderr));
+  const enter = await run(target, ['send-keys', '-t', name, 'Enter']);
+  if (enter.code !== 0) throw new TmuxError(502, firstStderrLine(enter.stderr));
+}
+
+export async function renameSession(
+  target: Target,
+  name: string,
+  newName: string,
+): Promise<void> {
+  if (!isValidSessionName(newName)) throw new TmuxError(400, 'invalid new session name');
+  const r = await run(target, ['rename-session', '-t', name, newName]);
+  if (r.code === 0) return;
+  if (/can't find session|session not found/i.test(r.stderr)) {
+    throw new TmuxError(404, `session "${name}" not found`);
+  }
+  if (/duplicate session/i.test(r.stderr)) {
+    throw new TmuxError(409, `session "${newName}" already exists`);
+  }
+  throw new TmuxError(502, firstStderrLine(r.stderr));
+}
+
+export async function killSession(target: Target, name: string): Promise<void> {
+  const r = await run(target, ['kill-session', '-t', name]);
+  if (r.code === 0) return;
+  if (/can't find session|session not found|no server running/i.test(r.stderr)) {
+    throw new TmuxError(404, `session "${name}" not found`);
+  }
+  throw new TmuxError(502, firstStderrLine(r.stderr));
+}
+
+export async function listWindows(target: Target, name: string): Promise<WindowInfo[]> {
+  const r = await run(target, ['list-windows', '-t', name, '-F', WINDOW_FORMAT]);
+  if (r.code === 0) return parseWindows(r.stdout);
+  if (/can't find session|session not found|no server running/i.test(r.stderr)) {
+    throw new TmuxError(404, `session "${name}" not found`);
+  }
+  throw new TmuxError(502, firstStderrLine(r.stderr));
+}