tmux-agent 0.1.0

package/src/lib/targeting/resolvePaneTarget.ts

@@ -0,0 +1,106 @@
+import type { PaneInfo, ResolvedPane } from "../contracts/types";
+import { TargetResolutionError } from "./errors";
+
+function isNumeric(value: string): boolean {
+  return /^\d+$/.test(value);
+}
+
+const COMPOSITE_REGEX = /^(@[^%]+)(%[^%]+)$/;
+
+export function resolvePaneTarget(
+  panes: PaneInfo[],
+  target: string,
+  options: { windowId?: string } = {}
+): ResolvedPane {
+  const compositeMatch = target.match(COMPOSITE_REGEX);
+  if (compositeMatch) {
+    const [, windowId, paneId] = compositeMatch;
+    const matches = panes.filter((pane) => pane.id === paneId);
+    const inWindow = matches.find((pane) => pane.windowId === windowId);
+    if (!inWindow) {
+      throw new TargetResolutionError({
+        targetKind: "pane",
+        kind: "invalid",
+        target,
+        message: `pane ${paneId} is not in window ${windowId}`
+      });
+    }
+    return { id: inWindow.id, idx: inWindow.idx };
+  }
+
+  if (target.startsWith("%")) {
+    const matches = panes.filter((pane) => pane.id === target);
+    if (matches.length === 0) {
+      throw new TargetResolutionError({
+        targetKind: "pane",
+        kind: "not_found",
+        target,
+        message: `pane target "${target}" not found`
+      });
+    }
+    return { id: matches[0].id, idx: matches[0].idx };
+  }
+
+  if (!options.windowId) {
+    throw new TargetResolutionError({
+      targetKind: "pane",
+      kind: "invalid",
+      target,
+      message: "window scope is required for IDX/keyword targets"
+    });
+  }
+
+  const scoped = panes.filter((pane) => pane.windowId === options.windowId);
+
+  if (isNumeric(target)) {
+    const idx = Number(target);
+    const matches = scoped.filter((pane) => pane.idx === idx);
+    if (matches.length === 0) {
+      throw new TargetResolutionError({
+        targetKind: "pane",
+        kind: "not_found",
+        target,
+        message: `pane target "${target}" not found`
+      });
+    }
+    if (matches.length > 1) {
+      throw new TargetResolutionError({
+        targetKind: "pane",
+        kind: "ambiguous",
+        target,
+        message: `target "${target}" matched ${matches.length} panes; use IDX or %pane_id`,
+        candidates: matches
+      });
+    }
+    return { id: matches[0].id, idx: matches[0].idx };
+  }
+
+  const query = target.toLowerCase();
+  const matches = scoped.filter((pane) => {
+    return (
+      pane.command.toLowerCase().includes(query) ||
+      pane.title.toLowerCase().includes(query)
+    );
+  });
+
+  if (matches.length === 0) {
+    throw new TargetResolutionError({
+      targetKind: "pane",
+      kind: "not_found",
+      target,
+      message: `pane target "${target}" not found`
+    });
+  }
+
+  if (matches.length > 1) {
+    throw new TargetResolutionError({
+      targetKind: "pane",
+      kind: "ambiguous",
+      target,
+      message: `target "${target}" matched ${matches.length} panes; use IDX or %pane_id`,
+      candidates: matches
+    });
+  }
+
+  return { id: matches[0].id, idx: matches[0].idx };
+}

package/src/lib/targeting/resolveWindowTarget.ts

@@ -0,0 +1,45 @@
+import type { ResolvedWindow, WindowInfo } from "../contracts/types";
+import { TargetResolutionError } from "./errors";
+
+function isNumeric(value: string): boolean {
+  return /^\d+$/.test(value);
+}
+
+export function resolveWindowTarget(
+  windows: WindowInfo[],
+  target: string
+): ResolvedWindow {
+  let matches: WindowInfo[] = [];
+
+  if (target.startsWith("@")) {
+    matches = windows.filter((window) => window.wid === target);
+  } else if (isNumeric(target)) {
+    const index = Number(target);
+    matches = windows.filter((window) => window.widx === index);
+  } else {
+    const query = target.toLowerCase();
+    matches = windows.filter((window) => window.name.toLowerCase().includes(query));
+  }
+
+  if (matches.length === 0) {
+    throw new TargetResolutionError({
+      targetKind: "window",
+      kind: "not_found",
+      target,
+      message: `window target "${target}" not found`
+    });
+  }
+
+  if (matches.length > 1) {
+    throw new TargetResolutionError({
+      targetKind: "window",
+      kind: "ambiguous",
+      target,
+      message: `target "${target}" matched ${matches.length} windows; use WIDX or @window_id`,
+      candidates: matches
+    });
+  }
+
+  const match = matches[0];
+  return { widx: match.widx, wid: match.wid, name: match.name };
+}

package/src/lib/targeting/scope.ts

@@ -0,0 +1,76 @@
+import type { ResolvedWindow } from "../contracts/types";
+import { snapshotWindows } from "../tmux/snapshotWindows";
+import { tmuxExec } from "../tmux/exec";
+import { TargetResolutionError } from "./errors";
+import { resolveWindowTarget } from "./resolveWindowTarget";
+
+export type SessionScope = {
+  session: string;
+  source: "explicit" | "tmux" | "unique";
+};
+
+export async function resolveSessionScope(
+  sessionArg?: string,
+  env: NodeJS.ProcessEnv = process.env
+): Promise<SessionScope> {
+  if (sessionArg) {
+    return { session: sessionArg, source: "explicit" };
+  }
+
+  if (env.TMUX) {
+    const result = await tmuxExec([
+      "display-message",
+      "-p",
+      "#{session_name}"
+    ]);
+    const session = result.stdout.trim();
+    if (!session) {
+      throw new Error("unable to resolve current session");
+    }
+    return { session, source: "tmux" };
+  }
+
+  const result = await tmuxExec(["list-sessions", "-F", "#{session_name}"]);
+  const sessions = result.stdout
+    .trim()
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean);
+
+  if (sessions.length === 0) {
+    throw new Error("no tmux sessions found");
+  }
+
+  if (sessions.length > 1) {
+    throw new Error("default session is ambiguous; use --session <name>");
+  }
+
+  return { session: sessions[0], source: "unique" };
+}
+
+export async function resolveWindowScope(
+  session: string,
+  windowTarget?: string
+): Promise<ResolvedWindow> {
+  const windows = await snapshotWindows(session);
+  if (windows.length === 0) {
+    throw new Error(`session ${session} has no windows`);
+  }
+
+  if (windowTarget) {
+    return resolveWindowTarget(windows, windowTarget);
+  }
+
+  const active = windows.find((window) => window.status === "active");
+  if (!active) {
+    throw new TargetResolutionError({
+      targetKind: "window",
+      kind: "not_found",
+      target: "active",
+      message: "no active window found",
+      candidates: windows
+    });
+  }
+
+  return { widx: active.widx, wid: active.wid, name: active.name };
+}

package/src/lib/tmux/capturePane.ts

@@ -0,0 +1,21 @@
+import { tmuxExec } from "./exec";
+
+export async function capturePane(
+  paneId: string,
+  lines: number
+): Promise<string> {
+  const args = ["capture-pane", "-p", "-t", paneId];
+  if (Number.isFinite(lines) && lines > 0) {
+    args.push("-S", `-${lines}`);
+  }
+  const result = await tmuxExec(args);
+  return result.stdout.replace(/\r?\n$/, "");
+}
+
+export function splitLines(text: string): string[] {
+  const lines = text.split(/\r?\n/);
+  if (lines.length && lines[lines.length - 1] === "") {
+    lines.pop();
+  }
+  return lines;
+}

package/src/lib/tmux/exec.ts

@@ -0,0 +1,90 @@
+import { spawn } from "node:child_process";
+
+export type TmuxExecOptions = {
+  input?: string;
+  env?: NodeJS.ProcessEnv;
+};
+
+export type TmuxExecResult = {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+};
+
+export class TmuxExecError extends Error {
+  readonly stdout: string;
+  readonly stderr: string;
+  readonly exitCode: number;
+
+  constructor(message: string, result: TmuxExecResult) {
+    super(message);
+    this.stdout = result.stdout;
+    this.stderr = result.stderr;
+    this.exitCode = result.exitCode;
+  }
+}
+
+function getServerArgs(env: NodeJS.ProcessEnv): string[] {
+  const server = env.AGENT_TMUX_SERVER || env.AGENT_TMUX_SOCKET;
+  if (!server) {
+    return [];
+  }
+  return ["-L", server];
+}
+
+export async function tmuxExec(
+  args: string[],
+  options: TmuxExecOptions = {}
+): Promise<TmuxExecResult> {
+  const baseEnv = options.env ?? process.env;
+  const serverArgs = getServerArgs(baseEnv);
+  const env = serverArgs.length > 0 ? { ...baseEnv } : baseEnv;
+  if (serverArgs.length > 0 && "TMUX" in env) {
+    delete env.TMUX;
+  }
+  const finalArgs = [...serverArgs, ...args];
+
+  return await new Promise<TmuxExecResult>((resolve, reject) => {
+    const child = spawn("tmux", finalArgs, { env });
+    let stdout = "";
+    let stderr = "";
+
+    if (child.stdout) {
+      child.stdout.on("data", (data) => {
+        stdout += data.toString();
+      });
+    }
+
+    if (child.stderr) {
+      child.stderr.on("data", (data) => {
+        stderr += data.toString();
+      });
+    }
+
+    child.on("error", (error) => {
+      reject(
+        new TmuxExecError(error.message, {
+          stdout,
+          stderr,
+          exitCode: 1
+        })
+      );
+    });
+
+    child.on("close", (code) => {
+      const exitCode = code ?? 0;
+      const result = { stdout, stderr, exitCode };
+      if (exitCode === 0) {
+        resolve(result);
+        return;
+      }
+      const message = stderr.trim() || stdout.trim() || `tmux exited with ${exitCode}`;
+      reject(new TmuxExecError(message, result));
+    });
+
+    if (options.input !== undefined) {
+      child.stdin?.write(options.input);
+      child.stdin?.end();
+    }
+  });
+}

package/src/lib/tmux/paneOps.ts

@@ -0,0 +1,35 @@
+import { tmuxExec } from "./exec";
+
+export type PaneCreateResult = {
+  id: string;
+  idx: number;
+};
+
+export async function paneSpawn(
+  windowId: string
+): Promise<PaneCreateResult> {
+  const args = [
+    "split-window",
+    "-P",
+    "-F",
+    "#{pane_id}\t#{pane_index}",
+    "-t",
+    windowId,
+    "-d"
+  ];
+  const result = await tmuxExec(args);
+  const [id, idxRaw] = result.stdout.trim().split("\t");
+
+  return {
+    id,
+    idx: Number(idxRaw)
+  };
+}
+
+export async function paneTitle(paneId: string, title: string): Promise<void> {
+  await tmuxExec(["select-pane", "-t", paneId, "-T", title]);
+}
+
+export async function paneKill(paneId: string): Promise<void> {
+  await tmuxExec(["kill-pane", "-t", paneId]);
+}

package/src/lib/tmux/paste.ts

@@ -0,0 +1,20 @@
+import { tmuxExec } from "./exec";
+
+function createBufferName(): string {
+  const rand = Math.random().toString(36).slice(2, 10);
+  return `__agent_tmux_${process.pid}_${Date.now()}_${rand}`;
+}
+
+export async function pasteText(paneId: string, text: string): Promise<void> {
+  const bufferName = createBufferName();
+  await tmuxExec(["load-buffer", "-b", bufferName, "-"], { input: text });
+  try {
+    await tmuxExec(["paste-buffer", "-p", "-d", "-b", bufferName, "-t", paneId]);
+  } finally {
+    try {
+      await tmuxExec(["delete-buffer", "-b", bufferName]);
+    } catch {
+      // ignore best-effort cleanup failures
+    }
+  }
+}

package/src/lib/tmux/sendKeys.ts

@@ -0,0 +1,72 @@
+import { tmuxExec } from "./exec";
+import { pasteText } from "./paste";
+
+export type SendMode = "text" | "keys";
+
+export type SendKeysResult = {
+  mode: SendMode;
+  text: string;
+  enter: boolean;
+};
+
+export type SendKeysOptions = {
+  noEnter?: boolean;
+  enterDelayMs?: number;
+};
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export function parseKeyExpression(input: string): string | null {
+  const trimmed = input.trim();
+  if (!trimmed) {
+    return null;
+  }
+  if (trimmed.toLowerCase() === "enter") {
+    return "Enter";
+  }
+  const ctrlMatch = trimmed.match(/^Ctrl\+([A-Za-z])$/);
+  if (ctrlMatch) {
+    return `C-${ctrlMatch[1].toLowerCase()}`;
+  }
+  return null;
+}
+
+export function classifySendInput(
+  input: string,
+  noEnter: boolean
+): { mode: SendMode; tmuxKey?: string; enter: boolean } {
+  const tmuxKey = parseKeyExpression(input);
+  if (tmuxKey) {
+    return { mode: "keys", tmuxKey, enter: false };
+  }
+  return { mode: "text", enter: !noEnter };
+}
+
+export async function sendKeys(
+  paneId: string,
+  input: string,
+  options: SendKeysOptions = {}
+): Promise<SendKeysResult> {
+  const { mode, tmuxKey, enter } = classifySendInput(
+    input,
+    options.noEnter ?? false
+  );
+
+  if (mode === "keys" && tmuxKey) {
+    await tmuxExec(["send-keys", "-t", paneId, tmuxKey]);
+    return { mode, text: input, enter };
+  }
+
+  await pasteText(paneId, input);
+  if (enter) {
+    const enterDelayMs = options.enterDelayMs ?? 0;
+    if (enterDelayMs > 0) {
+      await sleep(enterDelayMs);
+    }
+    await tmuxExec(["send-keys", "-t", paneId, "Enter"]);
+  }
+
+  return { mode: "text", text: input, enter };
+}

package/src/lib/tmux/session.ts

@@ -0,0 +1,27 @@
+import { tmuxExec } from "./exec";
+
+export async function resolveSessionId(sessionName: string): Promise<string> {
+  const result = await tmuxExec([
+    "list-sessions",
+    "-F",
+    "#{session_name}\t#{session_id}"
+  ]);
+  const lines = result.stdout.trim().split(/\r?\n/).filter(Boolean);
+  let fallbackId: string | undefined;
+  for (const line of lines) {
+    const [name, id] = line.split("\t");
+    if (name === sessionName && id) {
+      return id;
+    }
+    if (!fallbackId && id && name.endsWith(sessionName)) {
+      const prefix = name.slice(0, name.length - sessionName.length);
+      if (/^\d+-$/.test(prefix)) {
+        fallbackId = id;
+      }
+    }
+  }
+  if (fallbackId) {
+    return fallbackId;
+  }
+  throw new Error(`can't find session: ${sessionName}`);
+}

package/src/lib/tmux/snapshotPanes.ts

@@ -0,0 +1,52 @@
+import type { PaneInfo } from "../contracts/types";
+import { tmuxExec } from "./exec";
+import { resolveSessionId } from "./session";
+
+export type SnapshotPanesOptions = {
+  session?: string;
+  windowId?: string;
+};
+
+export async function snapshotPanes(options: SnapshotPanesOptions): Promise<PaneInfo[]> {
+  const sessionId = options.session
+    ? await resolveSessionId(options.session)
+    : undefined;
+  const args: string[] = ["list-panes"];
+  if (options.windowId) {
+    args.push("-t", options.windowId);
+  } else {
+    args.push("-a");
+  }
+  args.push(
+    "-F",
+    "#{session_id}\t#{pane_index}\t#{pane_id}\t#{pane_pid}\t#{pane_current_command}\t#{pane_title}\t#{pane_active}\t#{pane_dead}\t#{window_id}"
+  );
+  const result = await tmuxExec(args);
+  const lines = result.stdout.trim().split(/\r?\n/).filter(Boolean);
+  return lines
+    .map((line) => {
+      const [lineSessionId, idxRaw, id, pidRaw, command, title, activeRaw, deadRaw, windowId] =
+        line.split("\t");
+      const idx = Number(idxRaw);
+      const pidValue = Number(pidRaw);
+      const pid = Number.isFinite(pidValue) ? pidValue : undefined;
+      let status: PaneInfo["status"] = "idle";
+      if (deadRaw === "1") {
+        status = "dead";
+      } else if (activeRaw === "1") {
+        status = "active";
+      }
+      return {
+        sessionId: lineSessionId,
+        idx,
+        id,
+        pid,
+        command,
+        title,
+        status,
+        windowId
+      };
+    })
+    .filter((pane) => (sessionId ? pane.sessionId === sessionId : true))
+    .map(({ sessionId: _sessionId, ...pane }) => pane);
+}

package/src/lib/tmux/snapshotWindows.ts

@@ -0,0 +1,23 @@
+import type { WindowInfo } from "../contracts/types";
+import { tmuxExec } from "./exec";
+import { resolveSessionId } from "./session";
+
+export async function snapshotWindows(session: string): Promise<WindowInfo[]> {
+  const sessionId = await resolveSessionId(session);
+  const result = await tmuxExec([
+    "list-windows",
+    "-a",
+    "-F",
+    "#{session_id}\t#{window_index}\t#{window_id}\t#{window_name}\t#{window_active}"
+  ]);
+  const lines = result.stdout.trim().split(/\r?\n/).filter(Boolean);
+  return lines
+    .map((line) => {
+      const [lineSessionId, widxRaw, wid, name, activeRaw] = line.split("\t");
+      const widx = Number(widxRaw);
+      const status: WindowInfo["status"] = activeRaw === "1" ? "active" : "inactive";
+      return { sessionId: lineSessionId, widx, wid, name, status };
+    })
+    .filter((window) => window.sessionId === sessionId)
+    .map(({ sessionId: _sessionId, ...window }) => window);
+}

package/src/lib/tmux/windowOps.ts

@@ -0,0 +1,43 @@
+import { tmuxExec } from "./exec";
+
+export type WindowCreateResult = {
+  wid: string;
+  widx: number;
+  name: string;
+  paneId: string;
+};
+
+export async function windowNew(
+  session: string,
+  name: string
+): Promise<WindowCreateResult> {
+  const args = [
+    "new-window",
+    "-P",
+    "-F",
+    "#{window_id}\t#{window_index}\t#{window_name}\t#{pane_id}",
+    "-t",
+    session,
+    "-n",
+    name
+  ];
+  const result = await tmuxExec(args);
+  const [wid, widxRaw, windowName, paneId] = result.stdout.trim().split("\t");
+  return {
+    wid,
+    widx: Number(widxRaw),
+    name: windowName || name,
+    paneId
+  };
+}
+
+export async function windowRename(
+  windowId: string,
+  name: string
+): Promise<void> {
+  await tmuxExec(["rename-window", "-t", windowId, name]);
+}
+
+export async function windowKill(windowId: string): Promise<void> {
+  await tmuxExec(["kill-window", "-t", windowId]);
+}