Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

14.7 KB
Raw Blame
/**
 * One terminal session: a pty plus the daemon's authoritative view of its screen.
 *
 * The important idea is that the *server* owns the emulator: every pty byte is fed into a
 * headless xterm here, so the daemon always knows the full screen, cursor and title.
 * Clients are then just views that can come and go — which is what makes reload/reattach,
 * plain-text capture and multi-device viewing possible at all. A client-only emulator
 * would lose all of that the moment the tab closes.
 *
 * Sessions deliberately run in-process rather than in a forked terminal worker. A worker
 * would keep pty parsing off the daemon's event loop under heavy build output, but costs
 * an IPC protocol and a second process to supervise. Worth doing when this is under load,
 * not on day one — the seam (this module is the only thing that touches node-pty) is where
 * that split would go.
 */
import os from "node:os";
import path from "node:path";
import { randomUUID } from "node:crypto";
import xterm, { type Terminal } from "@xterm/headless";
import type { IPty } from "node-pty";
import { loadNodePty } from "./pty-module.js";
import { defaultTerminalShell, shellArgs } from "./shell.js";
import { TerminalInputModeTracker } from "./input-mode.js";
import { ensureSpawnHelperExecutable } from "../terminal/spawn-helper.js";
import {
  captureLines,
  renderRestoreAnsi,
  type CaptureLinesOptions,
  type CaptureLinesResult,
} from "./snapshot.js";
import {
  applyTerminalSize,
  releaseTerminalSize,
  type TerminalSizeState,
} from "./size-ownership.js";

const { Terminal: HeadlessTerminal } = xterm;

const DEFAULT_COLS = 80;
const DEFAULT_ROWS = 24;
const SCROLLBACK_LINES = 5000;
const TITLE_DEBOUNCE_MS = 150;
const EXIT_OUTPUT_LINE_LIMIT = 12;

/**
 * Answers to capability queries. A headless emulator has no display to ask, so the daemon
 * answers on its behalf — without this, anything that probes the terminal (nvim, less,
 * fzf, some prompts) waits for a reply that never comes and appears to hang on startup.
 */
const OSC_COLOR_QUERY_RESPONSES = new Map<number, string>([
  [10, "rgb:e6e6/e6e6/e6e6"], // foreground
  [11, "rgb:1414/1717/1a1a"], // background
  [12, "rgb:e6e6/e6e6/e6e6"], // cursor
]);

export interface TerminalExitInfo {
  exitCode: number;
  signal: number | null;
  lastOutputLines: string[];
}

export interface CreateTerminalSessionOptions {
  id?: string;
  /** Absolute working directory (already resolved and validated by the manager). */
  cwd: string;
  /** Owning user id — a shell is the most privileged thing this server hands out. */
  ownerUserId: string;
  /**
   * Stable per-user display number (tmux-style), assigned by the manager at creation. It
   * travels with the terminal for its whole life — UI numbering must never depend on list
   * position, which changes under user-reordered tabs.
   */
  seq?: number;
  name?: string;
  shell?: string;
  cols?: number;
  rows?: number;
  env?: Record<string, string>;
  /**
   * Where a pushed bundle's node-pty assets live (the hmr capability's assetsDir);
   * absent falls back to the packaged require (see pty-module.ts).
   */
  assets?: () => string | null;
}

export interface TerminalSessionInfo {
  id: string;
  seq: number;
  name: string;
  cwd: string;
  ownerUserId: string;
  title: string | null;
  cols: number;
  rows: number;
  pid: number;
  createdAt: string;
  alive: boolean;
  exit: TerminalExitInfo | null;
}

export type TerminalOutputListener = (data: string) => void;
export type TerminalExitListener = (info: TerminalExitInfo) => void;
export type TerminalTitleListener = (title: string | null) => void;

/**
 * Environment for the pty. `TERM`/`COLORTERM` are what make colour and 256-colour output
 * work at all; the rest of the parent environment is inherited so the shell behaves like the
 * user's own (PATH, proxies, language).
 */
function buildTerminalEnv(
  extra: Record<string, string> | undefined,
  cwd: string,
): Record<string, string> {
  const env: Record<string, string> = {};
  for (const [key, value] of Object.entries(process.env)) {
    if (typeof value === "string") env[key] = value;
  }
  Object.assign(env, extra ?? {});
  env.TERM = "xterm-256color";
  env.COLORTERM = "truecolor";
  env.ADELIE_TERMINAL = "1";
  env.PWD = cwd;
  // Inherited from the server process; a pty is not that server and these would point the
  // shell (and anything it starts) at the wrong runtime.
  delete env.NODE_OPTIONS;
  return env;
}

export class TerminalSession {
  readonly id: string;
  readonly seq: number;
  readonly cwd: string;
  readonly ownerUserId: string;
  readonly createdAt = new Date();

  private name: string;
  private readonly terminal: Terminal;
  private readonly ptyProcess: IPty;
  private readonly inputMode = new TerminalInputModeTracker();
  private readonly outputListeners = new Set<TerminalOutputListener>();
  private readonly exitListeners = new Set<TerminalExitListener>();
  private readonly titleListeners = new Set<TerminalTitleListener>();

  private title: string | null = null;
  private pendingTitle: string | null = null;
  private titleTimer: ReturnType<typeof setTimeout> | null = null;
  private sizeState: TerminalSizeState;
  private exitInfo: TerminalExitInfo | null = null;
  private disposed = false;

  constructor(options: CreateTerminalSessionOptions) {
    this.id = options.id ?? randomUUID();
    this.seq = options.seq ?? 1;
    this.cwd = options.cwd;
    this.ownerUserId = options.ownerUserId;
    this.name = options.name ?? (path.basename(options.cwd) || "terminal");

    const cols = clampDimension(options.cols, DEFAULT_COLS, 1000);
    const rows = clampDimension(options.rows, DEFAULT_ROWS, 500);
    this.sizeState = { ownerId: null, cols, rows };

    this.terminal = new HeadlessTerminal({
      cols,
      rows,
      scrollback: SCROLLBACK_LINES,
      allowProposedApi: true,
    });

    const shell = options.shell ?? defaultTerminalShell();
    // Before the first spawn on macOS: node-pty's prebuilt spawn-helper ships without an
    // exec bit, and posix_spawnp refuses it (see spawn-helper.ts).
    ensureSpawnHelperExecutable();
    this.ptyProcess = loadNodePty(options.assets).spawn(shell, shellArgs(shell), {
      name: "xterm-256color",
      cols,
      rows,
      cwd: options.cwd,
      env: buildTerminalEnv(options.env, options.cwd),
    });

    this.registerCapabilityResponders();

    this.terminal.onTitleChange((next) => {
      this.pendingTitle = next.trim() || null;
      if (this.titleTimer) return;
      // A shell that writes the title on every prompt would otherwise fan out an event per
      // keystroke to every attached client.
      this.titleTimer = setTimeout(() => {
        this.titleTimer = null;
        if (this.pendingTitle === this.title) return;
        this.title = this.pendingTitle;
        for (const listener of [...this.titleListeners]) safely(() => listener(this.title));
      }, TITLE_DEBOUNCE_MS);
    });

    this.ptyProcess.onData((chunk) => {
      this.inputMode.feed(chunk);
      // Publish only once the emulator has consumed the chunk (`write` parses async).
      // Publishing eagerly opens a gap where a client attaches after the publication but
      // before the parse: the snapshot it restores from lacks the bytes AND its output
      // subscription started too late — the chunk is simply lost to that client. Ordering
      // behind the write callback makes every byte either part of the snapshot or
      // delivered through the subscription, never neither.
      this.terminal.write(chunk, () => {
        for (const listener of [...this.outputListeners]) safely(() => listener(chunk));
      });
    });

    this.ptyProcess.onExit(({ exitCode, signal }) => {
      // The screen is still readable after the shell exits, so the tail is captured and the
      // session is kept (briefly) by the manager — a reload right after `exit` shows what
      // happened instead of an empty box. Capture must wait for the emulator to drain its
      // async write queue, or the final burst of output is missing from the tail.
      const finalize = (): void => {
        if (this.exitInfo) return;
        this.exitInfo = {
          exitCode,
          signal: signal ?? null,
          lastOutputLines: this.disposed
            ? []
            : lastNonEmptyLines(this.terminal, EXIT_OUTPUT_LINE_LIMIT),
        };
        for (const listener of [...this.exitListeners]) safely(() => listener(this.exitInfo!));
      };
      if (this.disposed) return finalize(); // a disposed emulator accepts no more writes
      this.terminal.write("", finalize);
    });
  }

  /** DA1 / DSR / OSC colour queries — see OSC_COLOR_QUERY_RESPONSES. */
  private registerCapabilityResponders(): void {
    this.terminal.parser.registerCsiHandler({ final: "c" }, (params) => {
      if (params.length === 0 || (params.length === 1 && params[0] === 0)) {
        this.ptyProcess.write("\x1b[?62;4;22c"); // VT220 + sixel-less, matching a modern xterm
        return true;
      }
      return false;
    });
    this.terminal.parser.registerCsiHandler({ final: "n" }, (params) => {
      if (params.length !== 1) return false;
      if (params[0] === 5) {
        this.ptyProcess.write("\x1b[0n"); // device OK
        return true;
      }
      if (params[0] === 6) {
        const buffer = this.terminal.buffer.active;
        this.ptyProcess.write(`\x1b[${buffer.cursorY + 1};${buffer.cursorX + 1}R`);
        return true;
      }
      return false;
    });
    this.terminal.parser.registerCsiHandler({ prefix: "?", final: "n" }, (params) => {
      if (params.length !== 1 || params[0] !== 6) return false;
      const buffer = this.terminal.buffer.active;
      this.ptyProcess.write(`\x1b[?${buffer.cursorY + 1};${buffer.cursorX + 1}R`);
      return true;
    });
    for (const [code, response] of OSC_COLOR_QUERY_RESPONSES) {
      this.terminal.parser.registerOscHandler(code, (data) => {
        if (data.trim() !== "?") return false;
        this.ptyProcess.write(`\x1b]${code};${response}\x1b\\`);
        return true;
      });
    }
  }

  get alive(): boolean {
    return this.exitInfo === null && !this.disposed;
  }

  get exit(): TerminalExitInfo | null {
    return this.exitInfo;
  }

  info(): TerminalSessionInfo {
    return {
      id: this.id,
      seq: this.seq,
      name: this.name,
      cwd: this.cwd,
      ownerUserId: this.ownerUserId,
      title: this.title,
      cols: this.sizeState.cols,
      rows: this.sizeState.rows,
      pid: this.ptyProcess.pid,
      createdAt: this.createdAt.toISOString(),
      alive: this.alive,
      exit: this.exitInfo,
    };
  }

  rename(name: string): void {
    const trimmed = name.trim();
    if (trimmed) this.name = trimmed;
  }

  write(data: string): void {
    if (!this.alive) return;
    this.ptyProcess.write(data);
  }

  /**
   * Applies a size request under the claim/update ownership rule, resizing both the pty and
   * the daemon's emulator so snapshots keep matching what the shell laid out.
   */
  resize(request: {
    connectionId: string;
    cols: number;
    rows: number;
    intent: "claim" | "update";
  }): boolean {
    const cols = clampDimension(request.cols, DEFAULT_COLS, 1000);
    const rows = clampDimension(request.rows, DEFAULT_ROWS, 500);
    const decision = applyTerminalSize(this.sizeState, { ...request, cols, rows });
    this.sizeState = decision.state;
    if (!decision.apply || !this.alive) return false;
    this.terminal.resize(cols, rows);
    try {
      this.ptyProcess.resize(cols, rows);
    } catch {
      // The pty can exit between the alive check and here; the exit path handles teardown.
    }
    return true;
  }

  releaseSize(connectionId: string): void {
    this.sizeState = releaseTerminalSize(this.sizeState, connectionId);
  }

  get size(): { cols: number; rows: number } {
    return { cols: this.sizeState.cols, rows: this.sizeState.rows };
  }

  /** The attach payload: the whole screen as an ANSI stream (see snapshot.ts). */
  restoreStream(options: { scrollbackLines?: number } = {}): string {
    return renderRestoreAnsi(this.terminal, {
      ...options,
      inputModePreamble: this.inputMode.preamble(),
    });
  }

  capture(options: CaptureLinesOptions = {}): CaptureLinesResult {
    return captureLines(this.terminal, options);
  }

  onOutput(listener: TerminalOutputListener): () => void {
    this.outputListeners.add(listener);
    return () => this.outputListeners.delete(listener);
  }

  onExit(listener: TerminalExitListener): () => void {
    this.exitListeners.add(listener);
    return () => this.exitListeners.delete(listener);
  }

  onTitleChange(listener: TerminalTitleListener): () => void {
    this.titleListeners.add(listener);
    return () => this.titleListeners.delete(listener);
  }

  kill(signal?: string): void {
    if (!this.alive) return;
    try {
      this.ptyProcess.kill(signal);
    } catch {
      // Already gone.
    }
  }

  dispose(): void {
    if (this.disposed) return;
    if (this.titleTimer) clearTimeout(this.titleTimer);
    // Order matters: kill() no-ops once `disposed` flips `alive` to false, so the polite
    // SIGHUP has to go out first (that ordering bug once left every shell running after
    // server shutdown — only the test process exiting hid it).
    this.kill();
    this.disposed = true;
    // SIGHUP is also advisory: a server started under `nohup` has HUP ignored, children
    // inherit that, and the hangup silently does nothing. Disposal is final — escalate.
    if (process.platform !== "win32" && this.exitInfo === null) {
      try {
        this.ptyProcess.kill("SIGKILL");
      } catch {
        // Already gone.
      }
    }
    this.outputListeners.clear();
    this.exitListeners.clear();
    this.titleListeners.clear();
    this.terminal.dispose();
  }
}

function clampDimension(value: number | undefined, fallback: number, max: number): number {
  if (typeof value !== "number" || !Number.isFinite(value)) return fallback;
  return Math.min(Math.max(Math.trunc(value), 1), max);
}

function lastNonEmptyLines(terminal: Terminal, limit: number): string[] {
  const buffer = terminal.buffer.active;
  const total = buffer.baseY + terminal.rows;
  const lines: string[] = [];
  for (let y = total - 1; y >= 0 && lines.length < limit; y -= 1) {
    const text = buffer.getLine(y)?.translateToString(true) ?? "";
    if (text.trim() === "" && lines.length === 0) continue; // skip the blank tail
    lines.push(text);
  }
  return lines.reverse();
}

function safely(fn: () => void): void {
  try {
    fn();
  } catch {
    // One bad listener must not take down the pty pump.
  }
}

/** Home-directory expansion for the API's `cwd` (the UI sends `~`). */
export function expandHomePath(input: string): string {
  if (input === "~") return os.homedir();
  if (input.startsWith("~/")) return path.join(os.homedir(), input.slice(2));
  return input;
}