@kabmo-labs/kabmo 0.0.0-stage → 0.1.0

package/src/server/lib/terminal/history.ts

@@ -0,0 +1,206 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Server-side scrollback for a PTY session, plus the replay sanitizer.
+ *
+ * Two failure modes this module exists to prevent, both silent when wrong:
+ *
+ * 1. Trimming must be UTF-8-safe. A byte slice at the cap boundary can land
+ *    inside a multi-byte sequence, and every byte after it decodes as U+FFFD —
+ *    the whole tail of the scrollback turns into replacement characters.
+ * 2. A replayed buffer must not contain terminal *queries*. A live client
+ *    answers `CSI c` (device attributes), `CSI 6n` (cursor position) and
+ *    `OSC 10/11;?` (colors) by writing the reply into the PTY, so replaying a
+ *    query makes those bytes arrive at the shell prompt as stray input. Live
+ *    output is byte-for-byte untouched; only the replay copy is filtered.
+ *
+ * Filtering is streaming: a control sequence split across two PTY reads is
+ * carried into the next chunk instead of being emitted half-parsed.
+ */
+
+const MAX_HISTORY_BYTES = 512 * 1024;
+
+/** Longest partial sequence held back before it is flushed as ordinary data. */
+const MAX_PENDING_BYTES = 128;
+
+const ESC = 0x1b;
+const BEL = 0x07;
+const CSI = 0x5b; // [
+const OSC = 0x5d; // ]
+/** DCS / SOS / PM / APC — string sequences terminated by ST only. */
+const STRING_INTROS: Record<number, true> = { 0x50: true, 0x58: true, 0x5e: true, 0x5f: true };
+
+const EMPTY = new Uint8Array(0);
+
+export interface TerminalHistory {
+  append(chunk: Uint8Array): void;
+  /** The replay buffer. Views into it stay valid until the next `append`. */
+  replay(): Uint8Array;
+  clear(): void;
+}
+
+export function createTerminalHistory(maxBytes = MAX_HISTORY_BYTES): TerminalHistory {
+  let chunks: Uint8Array[] = [];
+  let total = 0;
+  let pending: Uint8Array = EMPTY;
+
+  return {
+    append(chunk) {
+      if (chunk.length === 0) return;
+      const input = pending.length === 0 ? chunk : joinParts([pending, chunk]);
+      const { kept, rest } = sanitizeReplayChunk(input);
+      pending = rest;
+      if (kept.length > 0) {
+        chunks.push(kept);
+        total += kept.length;
+      }
+      // Drop whole chunks first: re-slicing the buffer on every append would
+      // copy up to 512 KiB per PTY read, which a chatty program turns into a
+      // memcpy storm. Only the boundary chunk is trimmed byte-wise.
+      while (total > maxBytes && chunks.length > 1) {
+        total -= chunks[0].length;
+        chunks.shift();
+      }
+      if (total > maxBytes && chunks.length === 1) {
+        chunks[0] = trimUtf8ToBytes(chunks[0], maxBytes);
+        total = chunks[0].length;
+      }
+    },
+    replay() {
+      if (chunks.length === 0) return EMPTY;
+      return chunks.length === 1 ? chunks[0] : joinParts(chunks);
+    },
+    clear() {
+      chunks = [];
+      total = 0;
+      pending = EMPTY;
+    },
+  };
+}
+
+/** Keep the last `maxBytes`, never starting inside a multi-byte sequence. */
+export function trimUtf8ToBytes(bytes: Uint8Array, maxBytes: number): Uint8Array {
+  if (bytes.length <= maxBytes) return bytes;
+  let start = bytes.length - maxBytes;
+  // 10xxxxxx is a continuation byte: step forward to the next sequence start.
+  while (start < bytes.length && (bytes[start] & 0xc0) === 0x80) start += 1;
+  return bytes.subarray(start);
+}
+
+/**
+ * Split `input` into the bytes that may be replayed and the trailing fragment
+ * of an unfinished control sequence. Dropped sequences are queries only.
+ *
+ * The scan for the next ESC is `indexOf`, not a byte-at-a-time loop: this runs
+ * over the whole replay buffer, and a JS loop spends its time on the bytes
+ * between sequences rather than on the sequences themselves. Measured on
+ * 512 KiB: 0.2 ms scanning byte-by-byte against 0.0085 ms with `indexOf`.
+ */
+export function sanitizeReplayChunk(input: Uint8Array): { kept: Uint8Array; rest: Uint8Array } {
+  const parts: Uint8Array[] = [];
+  let from = 0;
+  let dropped = false;
+
+  let i = input.indexOf(ESC);
+  while (i !== -1) {
+    const scan = scanEscape(input, i);
+    if (scan === null) {
+      if (i > from) parts.push(input.subarray(from, i));
+      const rest = input.subarray(i);
+      // A program that opened a string sequence and never closed it must not
+      // swallow the rest of the scrollback: emit the fragment and move on.
+      if (rest.length > MAX_PENDING_BYTES) {
+        parts.push(rest);
+        return { kept: joinParts(parts), rest: EMPTY };
+      }
+      return { kept: joinParts(parts), rest };
+    }
+    if (scan.drop) {
+      if (i > from) parts.push(input.subarray(from, i));
+      from = scan.end;
+      dropped = true;
+    }
+    i = input.indexOf(ESC, scan.end);
+  }
+
+  if (!dropped) return { kept: input, rest: EMPTY };
+  if (from < input.length) parts.push(input.subarray(from));
+  return { kept: joinParts(parts), rest: EMPTY };
+}
+
+interface EscapeScan {
+  /** Index just past the sequence. */
+  end: number;
+  /** True when the sequence is a query the replay must not contain. */
+  drop: boolean;
+}
+
+/** Null means the sequence is not complete within `input`. */
+function scanEscape(input: Uint8Array, start: number): EscapeScan | null {
+  const kind = input[start + 1];
+  if (kind === undefined) return null;
+  if (kind === CSI) return scanCsi(input, start);
+  if (kind === OSC) return scanOsc(input, start);
+  if (STRING_INTROS[kind] === true) return scanString(input, start);
+  // Every other escape is two bytes (ESC c, ESC 7, ESC M, …). Emitting the
+  // pair leaves the remaining bytes identical to the input either way.
+  return { end: start + 2, drop: false };
+}
+
+function scanCsi(input: Uint8Array, start: number): EscapeScan | null {
+  for (let i = start + 2; i < input.length; i += 1) {
+    const byte = input[i];
+    // 0x40–0x7e is the final byte; params/intermediates are below it.
+    if (byte >= 0x40 && byte <= 0x7e) {
+      return { end: i + 1, drop: isCsiQuery(input, start + 2, i) };
+    }
+  }
+  return null;
+}
+
+function isCsiQuery(input: Uint8Array, from: number, final: number): boolean {
+  const finalByte = input[final];
+  if (finalByte === 0x63) return true; // 'c' — DA1/DA2 device-attributes request
+  const params = asciiOf(input, from, final);
+  if (finalByte === 0x6e) return /^\??[56]$/.test(params); // 'n' — DSR / cursor position
+  if (finalByte === 0x70) return params.includes('$') && params.includes('2031'); // DECRQM mode query
+  return false;
+}
+
+function scanOsc(input: Uint8Array, start: number): EscapeScan | null {
+  for (let i = start + 2; i < input.length; i += 1) {
+    const byte = input[i];
+    if (byte === BEL) return { end: i + 1, drop: isOscQuery(input, start + 2, i) };
+    if (byte === ESC && input[i + 1] === 0x5c) return { end: i + 2, drop: isOscQuery(input, start + 2, i) };
+  }
+  return null;
+}
+
+/** Color queries: `OSC 10;?`, `OSC 11;?`, `OSC 12;?` and palette `OSC 4;n;?`. */
+function isOscQuery(input: Uint8Array, from: number, to: number): boolean {
+  const body = asciiOf(input, from, to);
+  const fields = body.split(';');
+  if (!/^(4|10|11|12)$/.test(fields[0])) return false;
+  return fields.length > 1 && fields[fields.length - 1] === '?';
+}
+
+function scanString(input: Uint8Array, start: number): EscapeScan | null {
+  for (let i = start + 2; i < input.length; i += 1) {
+    if (input[i] === ESC && input[i + 1] === 0x5c) return { end: i + 2, drop: false };
+  }
+  return null;
+}
+
+function asciiOf(input: Uint8Array, from: number, to: number): string {
+  let out = '';
+  for (let i = from; i < to; i += 1) out += String.fromCharCode(input[i]);
+  return out;
+}
+
+function joinParts(parts: Uint8Array[]): Uint8Array {
+  if (parts.length === 1) return parts[0];
+  return Buffer.concat(parts);
+}

package/src/server/lib/terminal/liveness.server.ts

@@ -0,0 +1,99 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Which shells are live, and which of them are doing work.
+ *
+ * Split from the registry that mutates them (`runtime.server.ts`) because the
+ * question is asked from outside the socket: the terminal inventory endpoint
+ * ("which shells can this client adopt?"), and the capacity check that runs
+ * before a new shell is created. Both ask it about every session at once, so
+ * both pay for one `ps` rather than one per shell.
+ *
+ * Two kinds of session are deliberately excluded from `countLiveTerminals`: an
+ * exited shell (a corpse with a scrollback nobody is reading) and a shell
+ * sitting at its prompt — the PTY's foreground process group tells them apart
+ * exactly (see `foreground.ts`). Counting idle shells is how a panel that was
+ * restarted or switched a few times pins the budget with nothing running, and
+ * the next attach is refused.
+ *
+ * WINDOWS HAS NO FOREGROUND GROUP, SO THE CAP BOUNDS EVERY LIVE SHELL THERE.
+ * `detectBusyShells` answers "nothing is busy" on Windows because a ConPTY
+ * exposes no `tpgid` — and a cap built on that answer never fires: measured
+ * against the old shape, `countLiveTerminals()` returned 0 with eight shells
+ * open, so `MAX_TERMINALS` was unreachable and a client could open shells
+ * without limit. A bound that never triggers is not a bound, so the two
+ * questions are separated here: `busy` stays "what the platform knows" (the
+ * panel's badge), while the CAP falls back to every running shell when the
+ * platform cannot distinguish idle from busy. That over-counts idle shells on
+ * Windows — a panel reopened a few times reaches the limit sooner — which is
+ * the conservative direction: a refused attach is recoverable, an unbounded
+ * shell count is not.
+ */
+
+import path from 'path';
+import { detectBusyShells, type ShellProcess } from '@/server/lib/terminal/foreground';
+import { snapshotOf } from '@/server/lib/terminal/session.server';
+import { terminalStore } from '@/server/lib/terminal/store';
+import type { TerminalSnapshot } from '@/shared/lib/workspace/terminal/protocol';
+
+/** Overridable so the Windows branch is reachable from a POSIX test. */
+export interface LivenessOptions {
+  platform?: NodeJS.Platform;
+}
+
+/**
+ * True when this platform can tell an idle shell from one running a command.
+ *
+ * Only the distinction is platform-bound; counting running shells is not. The
+ * two answers must not be conflated, because one of them is a UI badge and the
+ * other is a limit.
+ */
+export function distinguishesIdleShells(platform: NodeJS.Platform = process.platform): boolean {
+  return platform !== 'win32';
+}
+
+/** Shells that are actually doing work, which is what the cap budgets. */
+export async function countLiveTerminals(options: LivenessOptions = {}): Promise<number> {
+  const platform = options.platform ?? process.platform;
+  const running: ShellProcess[] = [];
+  for (const session of terminalStore().sessions.values()) {
+    if (session.status !== 'running' || !session.proc) continue;
+    running.push({ id: session.id, pid: session.proc.pid });
+  }
+
+  // No foreground-group question to ask: every live shell occupies a slot.
+  if (!distinguishesIdleShells(platform)) return running.length;
+
+  const busy = await detectBusyShells(running, { platform });
+  return busy.size;
+}
+
+/**
+ * Live terminal summaries, optionally narrowed to one scope, so a client can
+ * adopt a shell it does not have an id for (a reloaded page, a second tab).
+ *
+ * `busy` marks a shell with a foreground command — the panel shows it as
+ * running, and the cap budgets it.
+ */
+export async function listTerminals(root?: string | null, repo?: string | null): Promise<TerminalSnapshot[]> {
+  const scope = root ? (repo && repo !== '.' ? path.join(root, repo) : root) : null;
+  // Resolved once: a scope boundary either ends in a separator already or gets
+  // one, so a sibling directory that merely shares the prefix (`/a/bc`) is not
+  // read as being inside `/a/b`.
+  const scopePrefix = scope && !scope.endsWith(path.sep) ? scope + path.sep : scope;
+
+  const running: ShellProcess[] = [];
+  const out: TerminalSnapshot[] = [];
+  for (const session of terminalStore().sessions.values()) {
+    if (scopePrefix && session.cwd !== scope && !session.cwd.startsWith(scopePrefix)) continue;
+    if (session.status === 'running' && session.proc) {
+      running.push({ id: session.id, pid: session.proc.pid });
+    }
+    out.push(snapshotOf(session));
+  }
+  const busy = await detectBusyShells(running);
+  return out.map((snapshot) => ({ ...snapshot, busy: busy.has(snapshot.id) }));
+}

package/src/server/lib/terminal/runtime.server.ts

@@ -0,0 +1,294 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The terminal registry: creation, attachment, input, resize and reaping.
+ *
+ * One real shell per terminal id, created on the first `attach` (there is no
+ * separate create endpoint to race against), kept alive while clients come and
+ * go, and killed through the process group so the commands it started die with
+ * it. Session mechanics live in `session.server.ts`, the process-wide state in
+ * `store.ts`, and the liveness questions in `liveness.server.ts`.
+ */
+
+import { countLiveTerminals } from '@/server/lib/terminal/liveness.server';
+import {
+  TERMINATION_GRACE_MS,
+  TerminalRuntimeError,
+  closeTerminalStream,
+  createSession,
+  signalGroup,
+  snapshotOf,
+  type AttachRequest,
+  type TerminalSession,
+  type TerminalViewer,
+} from '@/server/lib/terminal/session.server';
+import { terminalStore } from '@/server/lib/terminal/store';
+import { TERMINAL_MAX_INPUT_BYTES, clampTerminalSize, type TerminalSnapshot } from '@/shared/lib/workspace/terminal/protocol';
+
+const MAX_TERMINALS = 8;
+const IDLE_TIMEOUT_MS = 30 * 60 * 1000;
+const IDLE_SWEEP_MS = 60 * 1000;
+/** Quiet period before a resize burst is committed to the PTY. */
+const RESIZE_SETTLE_MS = 120;
+
+export interface TerminalAttachment {
+  snapshot: TerminalSnapshot;
+  /** Retained scrollback, to be sent after the `ready` frame. */
+  replay: Uint8Array;
+}
+
+/** The process-wide state; see `store.ts` for why it is not module-local. */
+const registry = terminalStore();
+const sessions = registry.sessions;
+const resizeTimers = registry.resizeTimers;
+
+/**
+ * Attach `viewer` to `request.id`, creating the shell when the id is unknown.
+ *
+ * Registration and history capture happen in one synchronous block: Bun cannot
+ * interleave a PTY `data` callback inside it, so the viewer can neither miss
+ * output nor receive it twice.
+ */
+export async function attachTerminal(viewer: TerminalViewer, request: AttachRequest): Promise<TerminalAttachment> {
+  const session = await openTerminal(request);
+
+  const replay = session.history.replay();
+  const snapshot = snapshotOf(session);
+  session.viewers.add(viewer);
+  session.lastActivity = Date.now();
+  return { snapshot, replay };
+}
+
+/**
+ * The shell for `request.id`, creating it at most once.
+ *
+ * Creation awaits — cwd resolution, the shell probe, the cap's `ps` — so two
+ * `attach` frames for the same new id both used to pass the `sessions.get`
+ * check and both spawned a shell. The map kept whichever landed last and the
+ * other became unreachable: a PTY plus a detached shell with no record, which
+ * the reaper could never reclaim and the cap never counted. Measured on this
+ * runtime: two concurrent attaches for one id left two shells for one record.
+ * A page reload racing its own reconnect is enough to produce that.
+ *
+ * Sharing the in-flight promise makes the loser await the winner's session
+ * instead of creating a rival. The map lives in `store.ts` beside the records,
+ * because a reload that dropped it would reopen the same race.
+ */
+async function openTerminal(request: AttachRequest): Promise<TerminalSession> {
+  const existing = sessions.get(request.id);
+  if (existing) return existing;
+
+  const inFlight = registry.creating.get(request.id);
+  if (inFlight) return inFlight;
+
+  const entry = createTerminal(request);
+  registry.creating.set(request.id, entry);
+  const release = () => {
+    if (registry.creating.get(request.id) === entry) registry.creating.delete(request.id);
+  };
+  void entry.then(release, release);
+  return entry;
+}
+
+/**
+ * Spawn one shell, register it, and arm the reaper.
+ *
+ * The cap counts *live* shells only. An exited shell is a corpse holding a
+ * scrollback nobody is reading, and letting corpses consume the budget is how
+ * a session that restarted a shell a few times hits the limit with nothing
+ * running: every restart leaves its predecessor behind.
+ */
+async function createTerminal(request: AttachRequest): Promise<TerminalSession> {
+  reclaimExitedTerminals();
+  if ((await countLiveTerminals()) >= MAX_TERMINALS) {
+    throw new TerminalRuntimeError('capacity', `Terminal limit reached (${MAX_TERMINALS} busy shells)`);
+  }
+  const created = await createSession(request);
+  sessions.set(request.id, created);
+  // An exit with nobody watching is the common case for a replaced shell
+  // (restart, repo switch): reap it as soon as it lands instead of leaving
+  // the record for the sweep, which is up to a minute of holding a slot.
+  void created.proc?.exited.then(() => {
+    if (created.viewers.size === 0) forgetTerminal(created.id);
+  });
+  ensureSweeper();
+  return created;
+}
+
+/**
+ * Drop exited shells that nobody is watching.
+ *
+ * Run before a create, not only on the idle sweep: the sweep is a minute away,
+ * and a burst of restarts inside that window would otherwise be rejected while
+ * every corpse in the way is already dead.
+ */
+export function reclaimExitedTerminals(): number {
+  let reclaimed = 0;
+  for (const [id, session] of sessions) {
+    if (session.status !== 'exited') continue;
+    if (session.viewers.size > 0) continue;
+    forgetTerminal(id);
+    reclaimed += 1;
+  }
+  return reclaimed;
+}
+
+export function detachTerminal(viewer: TerminalViewer, id: string): void {
+  const session = sessions.get(id);
+  if (!session) return;
+  session.viewers.delete(viewer);
+  session.lastActivity = Date.now();
+  // The last viewer leaving a finished shell leaves nothing behind worth
+  // keeping: no process to reattach to, and a scrollback nobody will read.
+  if (session.status === 'exited' && session.viewers.size === 0) forgetTerminal(id);
+}
+
+export function writeTerminalInput(id: string, data: Uint8Array): void {
+  const session = sessions.get(id);
+  if (!session || session.status !== 'running') return;
+  if (data.length === 0 || data.length > TERMINAL_MAX_INPUT_BYTES) return;
+  session.lastActivity = Date.now();
+  try {
+    session.term.write(data);
+  } catch {
+    // The PTY closed between the status check and the write.
+  }
+}
+
+export function resizeTerminal(id: string, cols: number, rows: number): void {
+  const session = sessions.get(id);
+  if (!session || session.status !== 'running') return;
+  const size = clampTerminalSize(cols, rows);
+  if (size.cols === session.cols && size.rows === session.rows) return;
+  session.cols = size.cols;
+  session.rows = size.rows;
+  session.lastActivity = Date.now();
+  try {
+    session.term.resize(size.cols, size.rows);
+  } catch {
+    return;
+  }
+  // resize() updates the winsize but never signals the child, so a TUI would
+  // not repaint. Deliver SIGWINCH ourselves.
+  signalGroup(session, 'SIGWINCH');
+}
+
+/**
+ * Debounce for `resizeTerminal`.
+ *
+ * A panel drag produces a burst of sizes — the pointer moves in steps and
+ * xterm's FitAddon refits on every animation frame — and each accepted size
+ * sends SIGWINCH. The shell answers every one of them by redrawing its prompt,
+ * so a single drag used to print the prompt a dozen times (measured: 10
+ * SIGWINCH in one second for one drag).
+ *
+ * Only the trailing size matters: the PTY ends at the final grid either way,
+ * and a repaint of an intermediate size is invisible work. A single timeout is
+ * reused so the burst coalesces into one signal.
+ */
+export function resizeTerminalDebounced(id: string, cols: number, rows: number): void {
+  const pending = resizeTimers.get(id);
+  if (pending) clearTimeout(pending);
+  resizeTimers.set(
+    id,
+    setTimeout(() => {
+      resizeTimers.delete(id);
+      resizeTerminal(id, cols, rows);
+    }, RESIZE_SETTLE_MS),
+  );
+}
+
+/**
+ * Kill the shell for `id`, keeping the record and its viewers: the process exit
+ * is what reports the real exit code, so nothing is synthesized here.
+ *
+ * SIGHUP, not SIGTERM. An interactive shell ignores SIGTERM — verified on
+ * macOS: `kill -TERM` to a zsh process group left it alive indefinitely, while
+ * SIGHUP terminated it in ~150 ms along with its background jobs. SIGHUP is
+ * also the semantically right signal: the terminal is going away.
+ */
+export function closeTerminal(id: string): void {
+  const session = sessions.get(id);
+  if (!session || session.status !== 'running') return;
+  signalGroup(session, 'SIGHUP');
+  setTimeout(() => {
+    if (session.status === 'running') signalGroup(session, 'SIGKILL');
+  }, TERMINATION_GRACE_MS).unref?.();
+}
+
+/**
+ * Drop a session record and release its PTY stream. Used by the idle reaper and
+ * when a client closes a terminal it does not intend to reopen — there are no
+ * viewers left to inform, so a running shell is killed outright.
+ */
+export function forgetTerminal(id: string): void {
+  const session = sessions.get(id);
+  if (!session) return;
+  sessions.delete(id);
+  clearPendingResize(id);
+  // Close each viewer's socket, not just forget it: the record is going away,
+  // so a socket left open would sit on a terminal that can never answer it.
+  for (const viewer of session.viewers) viewer.drop();
+  session.viewers.clear();
+  if (session.status === 'running') signalGroup(session, 'SIGKILL');
+  closeTerminalStream(session);
+}
+
+function clearPendingResize(id: string): void {
+  const pending = resizeTimers.get(id);
+  if (pending) {
+    clearTimeout(pending);
+    resizeTimers.delete(id);
+  }
+}
+
+/**
+ * Kill every shell at process exit. Synchronous by contract — `exit` handlers
+ * cannot await — so it escalates straight to SIGKILL: a detached shell is its
+ * own session and would otherwise outlive the server.
+ */
+export function disposeAllTerminals(): void {
+  clearInterval(registry.sweep);
+  registry.sweep = undefined;
+  for (const [id, session] of sessions) {
+    clearPendingResize(id);
+    session.viewers.clear();
+    signalGroup(session, 'SIGKILL');
+    closeTerminalStream(session);
+  }
+  sessions.clear();
+}
+
+function ensureSweeper(): void {
+  if (registry.sweep !== undefined) return;
+  registry.sweep = setInterval(() => {
+    // Exited shells are reaped on exit and on detach; this catches the one
+    // that finished while a viewer was still attached to it.
+    reclaimExitedTerminals();
+    const now = Date.now();
+    for (const [id, session] of sessions) {
+      // A live shell is only reaped when nobody watches it: an attached
+      // terminal is idle by definition while the user reads its output.
+      if (session.viewers.size > 0) continue;
+      if (now - session.lastActivity < IDLE_TIMEOUT_MS) continue;
+      forgetTerminal(id);
+    }
+  }, IDLE_SWEEP_MS);
+  registry.sweep.unref?.();
+}
+
+/**
+ * Register process-wide cleanup exactly once. A `bun --hot` reload re-evaluates
+ * this module while the shells live on, so the guard keeps a reload from
+ * stacking duplicate signal handlers. It rides the same store as the registry,
+ * which is what makes it survive the reload that would otherwise reset it.
+ */
+if (!registry.cleanupInstalled) {
+  registry.cleanupInstalled = true;
+  process.once('exit', disposeAllTerminals);
+  process.once('SIGINT', disposeAllTerminals);
+  process.once('SIGTERM', disposeAllTerminals);
+}