tmux-agent 0.1.0

package/src/lib/codex/spawn.ts

@@ -0,0 +1,305 @@
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { tmuxExec } from "../tmux/exec";
+
+export type CodexSpawnMeta = {
+  window_id: string;
+  action: "add_column" | "add_row" | "simple_split";
+  column?: number;
+  total_panes: number;
+  source?: string;
+};
+
+export type CodexSpawnResult = {
+  createdPaneId: string;
+  meta: CodexSpawnMeta;
+};
+
+type PaneLayoutRow = {
+  paneId: string;
+  left: number;
+  top: number;
+  path: string;
+};
+
+type Column = {
+  left: number;
+  count: number;
+  topPaneId: string;
+  topPath: string;
+  topTop: number;
+  bottomPaneId: string;
+  bottomPath: string;
+  bottomTop: number;
+};
+
+function parseNumber(value: string): number {
+  const num = Number(value);
+  return Number.isFinite(num) ? num : 0;
+}
+
+async function getWindowId(paneId: string): Promise<string> {
+  const result = await tmuxExec(["display-message", "-p", "-t", paneId, "#{window_id}"]);
+  const windowId = result.stdout.trim();
+  if (!windowId) {
+    throw new Error(`unable to resolve window_id from pane ${paneId}`);
+  }
+  return windowId;
+}
+
+async function getPaneCurrentPath(paneId: string): Promise<string> {
+  const result = await tmuxExec([
+    "display-message",
+    "-p",
+    "-t",
+    paneId,
+    "#{pane_current_path}"
+  ]);
+  return result.stdout.trim() || process.cwd();
+}
+
+async function listPaneLayout(windowId: string): Promise<PaneLayoutRow[]> {
+  const result = await tmuxExec([
+    "list-panes",
+    "-t",
+    windowId,
+    "-F",
+    "#{pane_id}|#{pane_left}|#{pane_top}|#{pane_current_path}"
+  ]);
+  const rows: PaneLayoutRow[] = [];
+  for (const line of result.stdout.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed) {
+      continue;
+    }
+    const [paneId, leftRaw, topRaw, panePath] = trimmed.split("|");
+    if (!paneId) {
+      continue;
+    }
+    rows.push({
+      paneId,
+      left: parseNumber(leftRaw),
+      top: parseNumber(topRaw),
+      path: (panePath ?? "").trim()
+    });
+  }
+  rows.sort((a, b) => (a.left !== b.left ? a.left - b.left : a.top - b.top));
+  return rows;
+}
+
+function buildColumns(rows: PaneLayoutRow[]): Column[] {
+  const columns: Column[] = [];
+  const byLeft = new Map<number, Column>();
+
+  for (const row of rows) {
+    let col = byLeft.get(row.left);
+    if (!col) {
+      col = {
+        left: row.left,
+        count: 0,
+        topPaneId: row.paneId,
+        topPath: row.path,
+        topTop: row.top,
+        bottomPaneId: row.paneId,
+        bottomPath: row.path,
+        bottomTop: row.top
+      };
+      byLeft.set(row.left, col);
+      columns.push(col);
+    }
+
+    col.count += 1;
+    if (row.top < col.topTop) {
+      col.topTop = row.top;
+      col.topPaneId = row.paneId;
+      col.topPath = row.path;
+    }
+    if (row.top > col.bottomTop) {
+      col.bottomTop = row.top;
+      col.bottomPaneId = row.paneId;
+      col.bottomPath = row.path;
+    }
+  }
+
+  columns.sort((a, b) => a.left - b.left);
+  return columns;
+}
+
+function resolveReadyFile(): string | null {
+  const dir = (process.env.CODEX_PANE_READY_DIR || process.env.TMPDIR || os.tmpdir()).trim();
+  if (!dir) {
+    return null;
+  }
+  const safeDir = dir.replace(/\/+$/, "");
+  const name = `codex_pane_ready_${process.pid}_${Date.now()}_${Math.random()
+    .toString(16)
+    .slice(2)}`;
+  return path.join(safeDir, name);
+}
+
+async function waitForReadyFile(filePath: string): Promise<void> {
+  const maxTries = parseNumber(process.env.CODEX_PANE_READY_MAX_TRIES || "120");
+  const sleepMs = parseNumber(process.env.CODEX_PANE_READY_SLEEP_MS || "50");
+
+  for (let i = 0; i < Math.max(1, maxTries); i += 1) {
+    try {
+      await fs.stat(filePath);
+      try {
+        await fs.rm(filePath, { force: true });
+      } catch {
+        // ignore
+      }
+      return;
+    } catch {
+      // keep waiting
+    }
+    await new Promise((resolve) => setTimeout(resolve, Math.max(0, sleepMs)));
+  }
+}
+
+async function splitWindow(
+  args: string[],
+  readyFile: string | null
+): Promise<{ paneId: string; readyUsed: boolean }> {
+  if (readyFile) {
+    try {
+      const result = await tmuxExec([
+        ...args,
+        "-e",
+        `CODEX_PANE_READY_FILE=${readyFile}`
+      ]);
+      return { paneId: result.stdout.trim(), readyUsed: true };
+    } catch {
+      // fall through
+    }
+  }
+  const result = await tmuxExec(args);
+  return { paneId: result.stdout.trim(), readyUsed: false };
+}
+
+export async function codexSpawn(
+  originPaneId: string,
+  options: { forceSimpleSplit?: boolean } = {}
+): Promise<CodexSpawnResult> {
+  const windowId = await getWindowId(originPaneId);
+  const layout = await listPaneLayout(windowId);
+  const totalPanes = layout.length;
+
+  const readyFile = resolveReadyFile();
+
+  if (options.forceSimpleSplit) {
+    const originPath = await getPaneCurrentPath(originPaneId);
+    const { paneId, readyUsed } = await splitWindow(
+      ["split-window", "-d", "-P", "-F", "#{pane_id}", "-t", originPaneId, "-c", originPath],
+      readyFile
+    );
+    if (!paneId) {
+      throw new Error("failed to create new pane");
+    }
+    if (readyUsed && readyFile) {
+      await waitForReadyFile(readyFile);
+    }
+    return {
+      createdPaneId: paneId,
+      meta: {
+        window_id: windowId,
+        action: "simple_split",
+        total_panes: totalPanes + 1,
+        source: "force-simple-split"
+      }
+    };
+  }
+
+  const columns = buildColumns(layout);
+  const colCount = columns.length;
+  if (colCount === 0) {
+    throw new Error(`no panes detected in window ${windowId}`);
+  }
+  if (colCount > 3) {
+    throw new Error("window has more than 3 columns; refusing to add pane");
+  }
+  if (columns[0].count !== 1) {
+    throw new Error(
+      `leftmost column has ${columns[0].count} panes; expected 1`
+    );
+  }
+  if (totalPanes >= 7) {
+    throw new Error("window already at max panes (1+3+3)");
+  }
+
+  if (colCount < 3) {
+    if (colCount === 2 && columns[1].count !== 1) {
+      throw new Error("right column already split; refusing to add a third column");
+    }
+    const target = columns[colCount - 1];
+    const { paneId, readyUsed } = await splitWindow(
+      [
+        "split-window",
+        "-h",
+        "-d",
+        "-P",
+        "-F",
+        "#{pane_id}",
+        "-t",
+        target.topPaneId,
+        "-c",
+        target.topPath
+      ],
+      readyFile
+    );
+    if (!paneId) {
+      throw new Error("failed to create new pane");
+    }
+    if (readyUsed && readyFile) {
+      await waitForReadyFile(readyFile);
+    }
+    return {
+      createdPaneId: paneId,
+      meta: {
+        window_id: windowId,
+        action: "add_column",
+        column: colCount + 1,
+        total_panes: totalPanes + 1
+      }
+    };
+  }
+
+  if (columns[1].count >= 3 && columns[2].count >= 3) {
+    throw new Error("columns 2 and 3 are full; refusing to add pane");
+  }
+
+  const targetColumnIndex = columns[1].count < 3 ? 1 : 2;
+  const targetColumn = columns[targetColumnIndex];
+  const { paneId, readyUsed } = await splitWindow(
+    [
+      "split-window",
+      "-v",
+      "-d",
+      "-P",
+      "-F",
+      "#{pane_id}",
+      "-t",
+      targetColumn.bottomPaneId,
+      "-c",
+      targetColumn.bottomPath
+    ],
+    readyFile
+  );
+  if (!paneId) {
+    throw new Error("failed to create new pane");
+  }
+  if (readyUsed && readyFile) {
+    await waitForReadyFile(readyFile);
+  }
+  return {
+    createdPaneId: paneId,
+    meta: {
+      window_id: windowId,
+      action: "add_row",
+      column: targetColumnIndex + 1,
+      total_panes: totalPanes + 1
+    }
+  };
+}
+

package/src/lib/contracts/types.ts

@@ -0,0 +1,30 @@
+export type WindowStatus = "active" | "inactive";
+export type PaneStatus = "active" | "idle" | "dead";
+
+export type WindowInfo = {
+  widx: number;
+  wid: string;
+  status: WindowStatus;
+  name: string;
+};
+
+export type PaneInfo = {
+  idx: number;
+  id: string;
+  pid?: number;
+  status: PaneStatus;
+  command: string;
+  title: string;
+  windowId?: string;
+};
+
+export type ResolvedWindow = {
+  widx: number;
+  wid: string;
+  name: string;
+};
+
+export type ResolvedPane = {
+  idx?: number;
+  id: string;
+};

package/src/lib/fs/safeRm.ts

@@ -0,0 +1,32 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+
+function resolvePath(input: string): string {
+  return path.resolve(input);
+}
+
+export async function safeRemove(
+  targetPath: string,
+  allowedRoot: string
+): Promise<boolean> {
+  const resolvedTarget = resolvePath(targetPath);
+  const resolvedRoot = resolvePath(allowedRoot);
+
+  const relative = path.relative(resolvedRoot, resolvedTarget);
+  if (!relative || relative === "" || relative === ".") {
+    throw new Error("refuse to remove allowed root");
+  }
+  if (relative.startsWith("..") || path.isAbsolute(relative)) {
+    throw new Error("path is outside allowed_root");
+  }
+
+  try {
+    await fs.rm(resolvedTarget, { recursive: true, force: true });
+    return true;
+  } catch (error: unknown) {
+    if (error instanceof Error && (error as NodeJS.ErrnoException).code === "ENOENT") {
+      return false;
+    }
+    throw error;
+  }
+}

package/src/lib/io/readStdin.ts

@@ -0,0 +1,11 @@
+export async function readStdin(): Promise<string> {
+  return await new Promise((resolve, reject) => {
+    let data = "";
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (chunk) => {
+      data += chunk;
+    });
+    process.stdin.on("end", () => resolve(data));
+    process.stdin.on("error", (error) => reject(error));
+  });
+}

package/src/lib/output/format.ts

@@ -0,0 +1,105 @@
+import type { PaneInfo, WindowInfo } from "../contracts/types";
+
+const TITLE_SEPARATOR = " \u00b7 ";
+
+type TableColumn = {
+  header: string;
+  values: string[];
+};
+
+function buildTable(columns: TableColumn[]): string {
+  const widths = columns.map((col) =>
+    Math.max(col.header.length, ...col.values.map((value) => value.length))
+  );
+  const header = columns
+    .map((col, index) => col.header.padEnd(widths[index]))
+    .join("  ");
+  const rows = columns[0].values.map((_, rowIndex) =>
+    columns
+      .map((col, colIndex) => col.values[rowIndex].padEnd(widths[colIndex]))
+      .join("  ")
+  );
+  return [header, ...rows].join("\n");
+}
+
+export function formatWindowStatus(status: WindowInfo["status"]): string {
+  return status === "active" ? "[Active]" : "[Idle]";
+}
+
+export function formatPaneStatus(status: PaneInfo["status"]): string {
+  if (status === "active") {
+    return "[Active]";
+  }
+  if (status === "dead") {
+    return "[Dead]";
+  }
+  return "[Idle]";
+}
+
+export function formatCommandTitle(command: string, title: string): string {
+  if (title) {
+    if (!command) {
+      return title;
+    }
+    return `${command}${TITLE_SEPARATOR}${title}`;
+  }
+  return command;
+}
+
+export function formatWindowTable(windows: WindowInfo[]): string {
+  return buildTable([
+    {
+      header: "WIDX",
+      values: windows.map((window) => String(window.widx))
+    },
+    {
+      header: "WID",
+      values: windows.map((window) => window.wid)
+    },
+    {
+      header: "STATUS",
+      values: windows.map((window) => formatWindowStatus(window.status))
+    },
+    {
+      header: "NAME",
+      values: windows.map((window) => window.name)
+    }
+  ]);
+}
+
+export function formatPaneTable(panes: PaneInfo[]): string {
+  return buildTable([
+    {
+      header: "IDX",
+      values: panes.map((pane) => String(pane.idx))
+    },
+    {
+      header: "ID",
+      values: panes.map((pane) => pane.id)
+    },
+    {
+      header: "STATUS",
+      values: panes.map((pane) => formatPaneStatus(pane.status))
+    },
+    {
+      header: "COMMAND/TITLE",
+      values: panes.map((pane) => formatCommandTitle(pane.command, pane.title))
+    }
+  ]);
+}
+
+export function formatJson(data: unknown): string {
+  return JSON.stringify(data);
+}
+
+export function ensureErrorPrefix(message: string): string {
+  const trimmed = message.trim();
+  if (!trimmed) {
+    return "Error: unknown error";
+  }
+  if (trimmed.toLowerCase().startsWith("error:")) {
+    const rest = trimmed.slice(trimmed.indexOf(":") + 1);
+    return `Error:${rest}`;
+  }
+  return `Error: ${trimmed}`;
+}

package/src/lib/proc/lsof.ts

@@ -0,0 +1,44 @@
+import { spawn } from "node:child_process";
+
+export async function listOpenFiles(pid: number): Promise<string[]> {
+  return await new Promise<string[]>((resolve, reject) => {
+    const child = spawn("lsof", ["-p", String(pid), "-Fn"]);
+    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(error);
+    });
+
+    child.on("close", (code) => {
+      const exitCode = code ?? 0;
+      if (exitCode !== 0) {
+        reject(new Error(stderr.trim() || stdout.trim() || `lsof exited with ${exitCode}`));
+        return;
+      }
+      const paths: string[] = [];
+      for (const line of stdout.split(/\r?\n/)) {
+        if (!line.startsWith("n")) {
+          continue;
+        }
+        const path = line.slice(1);
+        if (path) {
+          paths.push(path);
+        }
+      }
+      resolve(paths);
+    });
+  });
+}

package/src/lib/proc/ps.ts

@@ -0,0 +1,70 @@
+import { spawn } from "node:child_process";
+
+export type ProcessEntry = {
+  pid: number;
+  ppid: number;
+  tty: string;
+  command: string;
+};
+
+function parseLine(line: string): ProcessEntry | null {
+  const trimmed = line.trim();
+  if (!trimmed) {
+    return null;
+  }
+  const match = trimmed.match(/^(\d+)\s+(\d+)\s+(\S+)\s+(.*)$/);
+  if (!match) {
+    return null;
+  }
+  const pid = Number(match[1]);
+  const ppid = Number(match[2]);
+  if (!Number.isFinite(pid) || !Number.isFinite(ppid)) {
+    return null;
+  }
+  return {
+    pid,
+    ppid,
+    tty: match[3],
+    command: match[4]
+  };
+}
+
+export async function listProcesses(): Promise<ProcessEntry[]> {
+  return await new Promise<ProcessEntry[]>((resolve, reject) => {
+    const child = spawn("ps", ["-axo", "pid=,ppid=,tty=,command=", "-ww"]);
+    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(error);
+    });
+
+    child.on("close", (code) => {
+      const exitCode = code ?? 0;
+      if (exitCode !== 0) {
+        reject(new Error(stderr.trim() || stdout.trim() || `ps exited with ${exitCode}`));
+        return;
+      }
+      const entries: ProcessEntry[] = [];
+      for (const line of stdout.split(/\r?\n/)) {
+        const parsed = parseLine(line);
+        if (parsed) {
+          entries.push(parsed);
+        }
+      }
+      resolve(entries);
+    });
+  });
+}

package/src/lib/targeting/errors.ts

@@ -0,0 +1,25 @@
+import type { PaneInfo, WindowInfo } from "../contracts/types";
+
+export type TargetKind = "pane" | "window";
+export type TargetErrorKind = "not_found" | "ambiguous" | "invalid";
+
+export class TargetResolutionError extends Error {
+  readonly targetKind: TargetKind;
+  readonly kind: TargetErrorKind;
+  readonly target: string;
+  readonly candidates?: Array<PaneInfo | WindowInfo>;
+
+  constructor(options: {
+    targetKind: TargetKind;
+    kind: TargetErrorKind;
+    target: string;
+    message: string;
+    candidates?: Array<PaneInfo | WindowInfo>;
+  }) {
+    super(options.message);
+    this.targetKind = options.targetKind;
+    this.kind = options.kind;
+    this.target = options.target;
+    this.candidates = options.candidates;
+  }
+}