Capture pane output

import type { Server } from "libtmux";

/**
 * Move text through a tmux buffer, and read what a pane is showing.
 *
 * The half of orchestration that is not making things happen. A named buffer
 * is tmux's own clipboard: anything in it can be pasted into any pane on the
 * server, by this process or by a person at the keyboard, without the text
 * passing through your program a second time.
 */
export async function moveTextThroughABuffer(
  server: Server,
  text: string,
): Promise<{ named: readonly string[]; roundTripped: readonly string[] }> {
  // tmux stores nothing for empty text and reports success, so a buffer whose
  // content is computed has to be checked before it is written — otherwise the
  // name is absent and the next call to read it is what fails.
  if (text === "") throw new Error("tmux holds no empty buffer");

  await server.setBuffer("report", text);
  const roundTripped = await server.showBuffer("report");
  const named = await server.listBuffers();

  // Buffers outlive the program that made them.
  await server.deleteBuffer("report");
  return { named, roundTripped };
}

/**
 * What a pane is showing, scrollback included.
 *
 * `start` counts back from the visible top, so -100 asks for the last hundred
 * lines or as many as exist. A pane that has printed nothing answers with
 * nothing rather than with blank lines.
 */
export async function readPane(server: Server): Promise<readonly string[]> {
  const session = await server.newSession({ name: "capture" });
  const pane = session.activePane;
  if (pane === undefined) throw new Error("a new session always has one pane");
  return pane.capture({ start: -100 });
}

import type { Server } from "libtmux/server";

/**
 * Drive tmux the way an agent does: act, then wait for the result.
 *
 * One control observer carries notifications while commands use the server's
 * engine. Keeping the observer open makes event-driven waits persistent; it
 * does not turn command output into a control-mode protocol.
 */
export async function runAndWait(server: Server, command: string, marker: string): Promise<string> {
  // A connection attaches, so the session has to exist first. On a server with
  // none, `connect()` fails saying exactly that.
  const session = await server.newSession({ name: "agent" });

  await using live = await server.connect({ target: session.id });

  const pane = (await live.snapshot()).sessions.one({ id: session.id }).panes.one();

  // Subscribe before acting. A marker printed between the command and the
  // subscription is one nobody is listening for, and the wait never ends.
  const printed = live
    .subscribe()
    .find(
      (event) => event.kind === "output" && event.paneId === pane.id && event.data.includes(marker),
      { timeoutMs: 30_000 },
    );

  await pane.sendKeys(command);

  const event = await printed;
  if (event === undefined) throw new Error(`${command} never printed ${marker}`);
  return event.kind === "output" ? event.data : "";
}

/**
 * Wait for the server to reach a shape, rather than for one event.
 *
 * `waitFor` reads the server, then re-reads on each notification, so it returns
 * at once when the condition already holds and does not miss a change that
 * lands while it is subscribing.
 */
export async function buildAndSettle(server: Server, windows: readonly string[]): Promise<number> {
  const session = await server.newSession({ name: "settling" });
  await using live = await server.connect({ target: session.id });

  const bound = (await live.snapshot()).sessions.one({ id: session.id });
  for (const name of windows) {
    // eslint-disable-next-line no-await-in-loop -- window order is observable.
    await bound.newWindow({ name });
  }

  const settled = await live.waitFor(
    (snapshot) => windows.every((name) => snapshot.windows.exists({ name })),
    { timeoutMs: 30_000 },
  );

  return settled.windows.count({ session: { is: { id: session.id } } });
}