ompchamber 0.8.0 → 1.0.0

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

@@ -0,0 +1,73 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Is a shell busy, or sitting at its prompt?
+ *
+ * The PTY's foreground process group answers this exactly, and the kernel keeps
+ * it up to date: when a command runs in the foreground the terminal's `tpgid`
+ * becomes that command's group, and when the shell regains control `tpgid`
+ * returns to the shell's own pid. Verified on macOS against a real PTY —
+ * `sleep 30` moved `tpgid` off the shell's pid, `Ctrl+C` and a backgrounded job
+ * both left it on the shell's pid (a background job is by definition not the
+ * foreground job).
+ *
+ * Why it matters: the terminal cap counts *live* shells. "Live" has to mean
+ * "has work in flight", otherwise a panel that was opened, restarted, or
+ * switched a few times pins the budget with shells that are all idle at a
+ * prompt, and the next attach is rejected with nothing actually running.
+ *
+ * Cost is one `ps` call for the whole registry, so this is safe to run on every
+ * attach. It is advisory: any failure resolves to "not busy", because refusing
+ * a shell to save a slot is worse than letting one extra through.
+ */
+
+const PS_TIMEOUT_MS = 1500;
+
+/** `pid` is the shell's process (it is the PTY session leader, so pgid === pid). */
+export interface ShellProcess {
+  id: string;
+  pid: number;
+}
+
+export async function detectBusyShells(shells: ShellProcess[]): Promise<Set<string>> {
+  const busy = new Set<string>();
+  if (shells.length === 0 || process.platform === 'win32') return busy;
+
+  const byPid = new Map<number, string>();
+  for (const shell of shells) byPid.set(shell.pid, shell.id);
+
+  const ps = Bun.spawn(['ps', '-o', 'pid=,tpgid=', '-p', shells.map((s) => s.pid).join(',')], {
+    stdout: 'pipe',
+    stderr: 'ignore',
+  });
+
+  let output = '';
+  try {
+    output = await Promise.race([
+      new Response(ps.stdout).text(),
+      Bun.sleep(PS_TIMEOUT_MS).then(() => ''),
+    ]);
+  } catch {
+    // The pipe died; fall through to the kill and the empty result.
+  }
+  try {
+    ps.kill('SIGKILL');
+  } catch {
+    // Already exited.
+  }
+  void ps.exited.catch(() => {});
+
+  for (const line of output.split('\n')) {
+    const [pidText, tpgidText] = line.trim().split(/\s+/);
+    const pid = Number(pidText);
+    const tpgid = Number(tpgidText);
+    if (!Number.isFinite(pid) || !Number.isFinite(tpgid)) continue;
+    const id = byPid.get(pid);
+    // The shell holds the terminal exactly when it is its own foreground group.
+    if (id !== undefined && tpgid !== pid) busy.add(id);
+  }
+  return busy;
+}

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

@@ -0,0 +1,118 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import { createTerminalHistory, sanitizeReplayChunk, trimUtf8ToBytes } from '@/server/lib/terminal/history';
+
+const decode = (bytes: Uint8Array) => Buffer.from(bytes).toString('utf8');
+const encode = (text: string) => new Uint8Array(Buffer.from(text, 'utf8'));
+
+describe('trimUtf8ToBytes', () => {
+  test('keeps a short buffer whole', () => {
+    const bytes = encode('hello');
+    expect(trimUtf8ToBytes(bytes, 16)).toBe(bytes);
+  });
+
+  test('never starts inside a multi-byte character', () => {
+    // 'é' is 2 bytes, '😀' is 4 — a naive slice at the boundary would leave
+    // continuation bytes at the head and decode the whole tail as U+FFFD.
+    const bytes = encode('ab😀cd');
+    // 8 bytes cut to 5 lands inside the emoji: step forward past it.
+    expect(decode(trimUtf8ToBytes(bytes, 5))).toBe('cd');
+    // Cut to 6 lands exactly on its first byte: the emoji is kept whole.
+    expect(decode(trimUtf8ToBytes(bytes, 6))).toBe('😀cd');
+  });
+
+  test('drops the cut character instead of emitting replacement bytes', () => {
+    const bytes = encode('😀');
+    const trimmed = trimUtf8ToBytes(bytes, 1);
+    expect(decode(trimmed)).toBe('');
+  });
+});
+
+describe('sanitizeReplayChunk', () => {
+  test('keeps ordinary output byte-for-byte', () => {
+    const input = encode('\x1b[31mred\x1b[0m plain\r\n');
+    const { kept, rest } = sanitizeReplayChunk(input);
+    expect(kept).toBe(input);
+    expect(rest.length).toBe(0);
+  });
+
+  test('drops device-attribute and cursor-position queries', () => {
+    const { kept, rest } = sanitizeReplayChunk(encode('a\x1b[c b\x1b[6n c'));
+    expect(decode(kept)).toBe('a b c');
+    expect(rest.length).toBe(0);
+  });
+
+  test('drops color queries in both BEL and ST terminated forms', () => {
+    const { kept } = sanitizeReplayChunk(encode('x\x1b]11;?\x07y\x1b]10;?\x1b\\z'));
+    expect(decode(kept)).toBe('xyz');
+  });
+
+  test('keeps OSC payloads that are not queries', () => {
+    // The window-title sequence a shell emits on every prompt is not a query.
+    const input = encode('\x1b]7;file://host/tmp\x07');
+    expect(sanitizeReplayChunk(input).kept).toBe(input);
+  });
+
+  test('drops a query whose bytes straddle two chunks', () => {
+    // The split is what makes this stateful: neither chunk alone is a complete
+    // query, but their concatenation is one.
+    const history = createTerminalHistory();
+    history.append(encode('abc\x1b['));
+    history.append(encode('c done'));
+    expect(decode(history.replay())).toBe('abc done');
+  });
+
+  test('does not hold back a sequence it can see is not a query', () => {
+    const { kept, rest } = sanitizeReplayChunk(encode('a\x1b[32m'));
+    expect(decode(kept)).toBe('a\x1b[32m');
+    expect(rest.length).toBe(0);
+  });
+});
+
+describe('createTerminalHistory', () => {
+  test('accumulates appended chunks in order', () => {
+    const history = createTerminalHistory();
+    history.append(encode('one '));
+    history.append(encode('two'));
+    expect(decode(history.replay())).toBe('one two');
+  });
+
+  test('trims from the front once the cap is exceeded', () => {
+    const history = createTerminalHistory(16);
+    history.append(encode('aaaaaaaaaa'));
+    history.append(encode('bbbbbbbbbb'));
+    // Whole chunks are dropped, so the retained size lands just under the cap
+    // instead of being re-sliced on every append.
+    expect(decode(history.replay())).toBe('bbbbbbbbbb');
+  });
+
+  test('trims a single oversized chunk at a UTF-8 boundary', () => {
+    const history = createTerminalHistory(5);
+    history.append(encode('ab😀cd'));
+    // A byte-wise cut at offset 3 would land inside the emoji and decode the
+    // rest as U+FFFD; the trim steps forward to the next sequence start.
+    expect(decode(history.replay())).toBe('cd');
+  });
+
+  test('keeps the newest chunks when several are dropped', () => {
+    const history = createTerminalHistory(7);
+    history.append(encode('ab'));
+    history.append(encode('cd'));
+    history.append(encode('ef'));
+    history.append(encode('gh'));
+    // 8 bytes against a 7-byte cap drops the oldest chunk whole.
+    expect(decode(history.replay())).toBe('cdefgh');
+  });
+
+  test('clear empties the replay buffer', () => {
+    const history = createTerminalHistory();
+    history.append(encode('gone'));
+    history.clear();
+    expect(history.replay().length).toBe(0);
+  });
+});

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

@@ -0,0 +1,205 @@
+/**
+ * @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.
+ */
+export function sanitizeReplayChunk(input: Uint8Array): { kept: Uint8Array; rest: Uint8Array } {
+  const parts: Uint8Array[] = [];
+  let from = 0;
+  let i = 0;
+  let dropped = false;
+
+  while (i < input.length) {
+    if (input[i] !== ESC) {
+      i += 1;
+      continue;
+    }
+    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 = 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);
+}