agent-relay-orchestrator 0.11.2 → 0.11.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-orchestrator",
-  "version": "0.11.2",
+  "version": "0.11.3",
   "description": "Agent Relay orchestrator — manages agent lifecycle across hosts",
   "type": "module",
   "bin": {
@@ -16,12 +16,12 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@xterm/addon-serialize": "0.14.0",
-    "@xterm/headless": "6.0.0",
     "agent-relay-sdk": "0.2.2"
   },
   "devDependencies": {
-    "@types/bun": "latest"
+    "@types/bun": "latest",
+    "@xterm/addon-serialize": "0.14.0",
+    "@xterm/headless": "6.0.0"
   },
   "peerDependencies": {
     "typescript": "^5"

package/src/api.ts

@@ -577,13 +577,12 @@ function startTerminalSocket(ws: TerminalSocket): void {
   }
 }
 
-// Backfill comes from a server-side headless emulator (see terminal-stream.ts): the
-// snapshot's `content` is a SerializeAddon repaint that restores the exact grid, scrollback,
-// cursor, and SGR state when written to the client's xterm. The client and server run the
-// same emulator over the same byte stream, so the backfill is correct by construction — no
-// stabilization, trailing-newline strip, or cursor-park needed. Live bytes that arrive
-// before the snapshot are already baked into it, so we discard the queue and only forward
-// bytes that arrive after.
+// Backfill comes straight from tmux's own grid (see terminal-stream.ts): the snapshot's
+// `content` is a `capture-pane -e` repaint of the current screen (styled, cursor parked).
+// tmux is the real emulator and never drifts, so the repaint is byte-faithful and live
+// relative deltas then apply identically on the client. Live bytes that arrive before the
+// snapshot are already on tmux's grid (and thus in the capture), so we discard the queue
+// and only forward bytes that arrive after.
 async function syncAndBackfill(ws: TerminalSocket, cols?: number, rows?: number): Promise<void> {
   if (ws.data.syncTimer) {
     clearTimeout(ws.data.syncTimer);

package/src/terminal-stream.ts

@@ -8,15 +8,16 @@
 // to raw bytes, coalesce on a short window, and broadcast. No screen-scraping, no
 // full-buffer repaint — the client just writes the byte stream to xterm.
 //
-// Backfill: a *server-side headless xterm.js* (`@xterm/headless`) per session consumes
-// the same byte stream the browser does, so it holds an authoritative, correctly-rendered
-// grid. On viewer attach we `SerializeAddon.serialize()` that emulator into a byte-perfect
-// repaint. This is the xterm.js-maintainer-blessed pattern for "live attach to a running
-// terminal" — it replaces the fragile capture-pane reconstruction (which had to guess how
-// Claude's purely-relative cursor model maps onto a freshly-seeded grid, and ghosted when
-// it was even one row off). Correctness is now by construction: the server runs the same
-// emulator as the client, parsing the same bytes. tmux control mode does not replay the
-// pre-attach screen, so we seed the headless emulator once from a capture-pane snapshot.
+// Backfill: tmux control mode does not replay the pre-attach screen, so on viewer
+// attach we repaint from tmux's *own* grid via `capture-pane -e` (styled, current
+// screen only — no scrollback, exactly what `tmux attach` shows) and park the cursor
+// where tmux has it. tmux is the real terminal emulator: its grid never drifts, so the
+// repaint is byte-faithful by definition, and subsequent live relative-cursor deltas
+// apply identically on the client (which now mirrors tmux exactly). We deliberately do
+// NOT keep a server-side @xterm/headless mirror: seeding such an emulator mid-stream
+// from a snapshot and then feeding it Claude's purely-relative deltas accumulates error
+// (the seed is never byte-perfect), which ghosted the screen into a staircase. tmux's
+// grid is the only authoritative source, so we read it directly.
 //
 // Input/resize: written as plain command lines to the control client's stdin
 // (`send-keys -H <hex>`, `resize-window`), so a keystroke costs no process spawn.
@@ -24,9 +25,7 @@
 // its separate `tmux send-keys` calls and is unaffected — control mode is just
 // another observing client.
 
-import { Terminal } from "@xterm/headless";
-import { SerializeAddon } from "@xterm/addon-serialize";
-import { captureTerminal, sessionLiveness, tmuxCommand, tmuxSocketForSession, type TerminalSnapshot } from "./spawn";
+import { captureConsistent, sessionLiveness, tmuxCommand, tmuxSocketForSession, type TerminalSnapshot } from "./spawn";
 import type { OrchestratorConfig } from "./config";
 
 const FLUSH_MS = Math.max(0, Number(process.env.AGENT_RELAY_TERMINAL_FLUSH_MS) || 6);
@@ -35,6 +34,23 @@ const BACKPRESSURE_MAX_BYTES = Math.max(
   1 << 20,
   Number(process.env.AGENT_RELAY_TERMINAL_BACKPRESSURE_MAX_BYTES) || 8 << 20,
 );
+// After a resize the TUI repaints asynchronously; let tmux's grid settle before we
+// capture, so the backfill is the post-resize frame, not a half-reflowed one.
+const RESIZE_SETTLE_MS = Math.max(0, Number(process.env.AGENT_RELAY_TERMINAL_RESIZE_SETTLE_MS) || 90);
+// Live deltas are relative-cursor moves; replaying them onto a client seeded mid-stream
+// from a capture-pane snapshot can drift (lost scroll-region/SGR/wrap state → doubled
+// statusline, faded suggestion rendered solid, cursor off by a row). We can't transfer
+// full emulator state, so we periodically re-stamp tmux's authoritative grid in place to
+// snap the client back. Debounce after output settles; cap so continuous "thinking"
+// streams still correct. 0 disables the corrector.
+const RESYNC_DEBOUNCE_MS = Math.max(0, Number(process.env.AGENT_RELAY_TERMINAL_RESYNC_DEBOUNCE_MS) || 120);
+const RESYNC_MAX_INTERVAL_MS = Math.max(0, Number(process.env.AGENT_RELAY_TERMINAL_RESYNC_MAX_INTERVAL_MS) || 350);
+// On attach we include this many lines of tmux scrollback ABOVE the current screen so the
+// viewer can scroll back through pre-attach history (the client lands on the live screen;
+// the history sits in its scroll buffer). This is a one-time per-attach paint, so it's
+// fine to be large; the live resync corrector only ever repaints the current screen, so it
+// never disturbs this history. 0 = current screen only.
+const BACKFILL_SCROLLBACK_LINES = Math.max(0, Number(process.env.AGENT_RELAY_TERMINAL_BACKFILL_SCROLLBACK) || 1000);
 
 export interface TerminalStreamSubscriber {
   onData(bytes: Uint8Array): void;
@@ -55,7 +71,10 @@ export interface TerminalStreamHandle {
 
 const DEFAULT_COLS = 80;
 const DEFAULT_ROWS = 24;
-const TERMINAL_SCROLLBACK = Math.max(0, Number(process.env.AGENT_RELAY_TERMINAL_SCROLLBACK) || 1000);
+const TERMINAL_DEBUG = process.env.AGENT_RELAY_TERMINAL_DEBUG === "1";
+function tdbg(...args: unknown[]): void {
+  if (TERMINAL_DEBUG) console.error("[term-debug]", ...args);
+}
 
 // --- Pure protocol helpers (unit-tested) ---
 
@@ -120,6 +139,44 @@ export function encodeSendKeysHex(bytes: Uint8Array): string {
     .join(" ");
 }
 
+// Build a client repaint from tmux's current-screen grid: lay the rows out top-down
+// (explicit CRLF so it's independent of the client's convertEol), then park the cursor
+// where tmux has it so the next live relative delta continues from the right cell.
+export function buildScreenRepaint(content: string, cursorX?: number, cursorY?: number): string {
+  let out = content.replace(/\n$/, "").replace(/\n/g, "\r\n");
+  if (cursorX != null && cursorY != null && Number.isFinite(cursorX) && Number.isFinite(cursorY)) {
+    out += `\x1b[${cursorY + 1};${cursorX + 1}H`;
+  }
+  return out;
+}
+
+// Build an in-place authoritative repaint that overwrites the client grid with tmux's
+// current screen WITHOUT a full-screen clear (so it can run mid-stream as a drift
+// corrector without flicker). Each row is absolute-positioned, SGR-reset, and erased
+// (`\x1b[2K`) before its styled cells are written, so any drift — a doubled statusline, a
+// suggestion stuck solid instead of faded, leftover cells — is stamped out. The cursor is
+// re-parked at tmux's true position and visibility restored. Wrapped in cursor-hide/show
+// so the multi-row paint doesn't visibly skitter the cursor across the screen.
+export function buildInPlaceRepaint(
+  content: string,
+  rows: number,
+  cursor: { cursorX?: number; cursorY?: number; visible?: boolean } = {},
+): string {
+  const lines = content.replace(/\n$/, "").split("\n");
+  const height = Number.isFinite(rows) && rows > 0 ? Math.trunc(rows) : lines.length;
+  let out = "\x1b[?25l\x1b[m";
+  for (let i = 0; i < height; i++) {
+    out += `\x1b[${i + 1};1H\x1b[m\x1b[2K`;
+    if (lines[i]) out += lines[i];
+  }
+  out += "\x1b[m";
+  if (cursor.cursorX != null && cursor.cursorY != null && Number.isFinite(cursor.cursorX) && Number.isFinite(cursor.cursorY)) {
+    out += `\x1b[${cursor.cursorY + 1};${cursor.cursorX + 1}H`;
+  }
+  out += cursor.visible === false ? "\x1b[?25l" : "\x1b[?25h";
+  return out;
+}
+
 // --- Shared session stream ---
 
 class SessionStream {
@@ -130,11 +187,14 @@ class SessionStream {
   private flushTimer: ReturnType<typeof setTimeout> | null = null;
   private lineBuf = "";
   private closed = false;
-  // Server-side emulator mirroring the client's view, for byte-perfect serialize() backfill.
-  private term: Terminal | null = null;
-  private serializer: SerializeAddon | null = null;
+  // Last size we resized the pane to / reported to viewers (tmux is the source of truth;
+  // these are just for redundant-resize avoidance and debug logging).
   private termCols = DEFAULT_COLS;
   private termRows = DEFAULT_ROWS;
+  // Drift corrector: re-stamp tmux's authoritative grid after live deltas settle.
+  private resyncTimer: ReturnType<typeof setTimeout> | null = null;
+  private resyncCapTimer: ReturnType<typeof setTimeout> | null = null;
+  private resyncDirty = false;
 
   constructor(
     private readonly session: string,
@@ -149,22 +209,20 @@ class SessionStream {
     this.socket = socket;
     // Pin the window size before attaching so the control client can't reflow the
     // pane (default window-size would shrink it to the new client's 80x24).
-    const snapshot = this.safeBackfill();
+    const dims = this.paneDims();
+    if (dims.cols) this.termCols = dims.cols;
+    if (dims.rows) this.termRows = dims.rows;
     Bun.spawnSync(tmuxCommand(socket, "set-window-option", "-t", this.session, "window-size", "manual"), {
       stdin: "ignore",
       stdout: "ignore",
       stderr: "ignore",
     });
-    if (snapshot?.cols && snapshot?.rows) {
+    if (dims.cols && dims.rows) {
       Bun.spawnSync(
-        tmuxCommand(socket, "resize-window", "-t", this.session, "-x", String(snapshot.cols), "-y", String(snapshot.rows)),
+        tmuxCommand(socket, "resize-window", "-t", this.session, "-x", String(dims.cols), "-y", String(dims.rows)),
         { stdin: "ignore", stdout: "ignore", stderr: "ignore" },
       );
     }
-    // Build the headless emulator at the pane size and seed it with the current screen.
-    // tmux control mode only streams output emitted *after* attach, so without this seed
-    // the emulator would start blank and miss everything already on screen.
-    this.initTerm(snapshot);
     try {
       this.proc = Bun.spawn(tmuxCommand(socket, "-C", "attach-session", "-t", this.session), {
         stdin: "pipe",
@@ -238,9 +296,12 @@ class SessionStream {
     }
     this.pending = [];
     this.pendingBytes = 0;
-    // Keep the server-side emulator in lockstep with what subscribers receive, so a
-    // serialize() backfill always reflects exactly the bytes already streamed live.
-    this.term?.write(merged);
+    this.broadcast(merged);
+    // Live deltas just went out; schedule an authoritative resync to correct any drift.
+    this.scheduleResync();
+  }
+
+  private broadcast(bytes: Uint8Array): void {
     for (const sub of [...this.subscribers]) {
       if (sub.bufferedAmount && sub.bufferedAmount() > BACKPRESSURE_MAX_BYTES) {
         this.removeSubscriber(sub);
@@ -250,71 +311,141 @@ class SessionStream {
         continue;
       }
       try {
-        sub.onData(merged);
+        sub.onData(bytes);
       } catch {}
     }
   }
 
-  private safeBackfill(): TerminalSnapshot | null {
-    try {
-      return captureTerminal(this.session, this.config);
-    } catch {
-      return null;
+  // Schedule a drift-correcting resync: a trailing debounce fires once output settles,
+  // and a capped interval guarantees correction during continuous output.
+  private scheduleResync(): void {
+    if (RESYNC_DEBOUNCE_MS <= 0 || this.subscribers.size === 0) return;
+    this.resyncDirty = true;
+    if (this.resyncTimer) clearTimeout(this.resyncTimer);
+    this.resyncTimer = setTimeout(() => this.doResync(), RESYNC_DEBOUNCE_MS);
+    if (!this.resyncCapTimer && RESYNC_MAX_INTERVAL_MS > 0) {
+      this.resyncCapTimer = setTimeout(() => this.doResync(), RESYNC_MAX_INTERVAL_MS);
     }
   }
 
-  // Build the headless emulator and seed it with the current screen + cursor. The seed
-  // snapshot's (content, cursor) are captured consistently (see captureConsistent), so the
-  // emulator's cursor matches where the TUI's next relative delta continues from.
-  private initTerm(snapshot: TerminalSnapshot | null): void {
-    const cols = snapshot?.cols && snapshot.cols >= 1 ? snapshot.cols : DEFAULT_COLS;
-    const rows = snapshot?.rows && snapshot.rows >= 1 ? snapshot.rows : DEFAULT_ROWS;
-    this.termCols = cols;
-    this.termRows = rows;
-    this.term = new Terminal({ cols, rows, scrollback: TERMINAL_SCROLLBACK, allowProposedApi: true });
-    this.serializer = new SerializeAddon();
-    this.term.loadAddon(this.serializer);
-    if (snapshot?.content) {
-      // Strip the single trailing newline capture-pane appends; then park the cursor where
-      // tmux has it so the seeded emulator state is byte-faithful to the live pane.
-      let seed = snapshot.content.replace(/\n$/, "");
-      if (snapshot.cursorX != null && snapshot.cursorY != null) {
-        seed += `\x1b[${snapshot.cursorY + 1};${snapshot.cursorX + 1}H`;
-      }
-      this.term.write(seed);
+  private doResync(): void {
+    if (this.resyncTimer) {
+      clearTimeout(this.resyncTimer);
+      this.resyncTimer = null;
+    }
+    if (this.resyncCapTimer) {
+      clearTimeout(this.resyncCapTimer);
+      this.resyncCapTimer = null;
     }
+    if (!this.resyncDirty || this.closed) return;
+    this.resyncDirty = false;
+    if (this.subscribers.size === 0) return;
+    const repaint = this.resyncRepaint();
+    if (!repaint) return;
+    this.broadcast(repaint);
+    tdbg(`resync ${this.session} bytes=${repaint.length} viewers=${this.subscribers.size}`);
   }
 
-  // Resolve once the emulator has parsed everything written so far (write() is async),
-  // so serialize() can't miss the most recent live chunk.
-  private flushTerm(): Promise<void> {
-    return new Promise((resolve) => {
-      if (!this.term) return resolve();
-      this.term.write("", () => resolve());
-    });
+  // Build an in-place authoritative repaint from tmux's grid: absolute-position each row,
+  // reset SGR + clear it, then write tmux's styled cells. This overwrites any drift (a
+  // doubled statusline, a solid-instead-of-faded suggestion, stale cells) without a
+  // full-screen clear flash, and re-parks the cursor at tmux's true position/visibility.
+  private resyncRepaint(): Uint8Array | null {
+    const body = this.readScreen();
+    if (!body) return null;
+    const cursor = this.readCursorState();
+    const rows = this.paneDims().rows ?? this.termRows;
+    return new TextEncoder().encode(buildInPlaceRepaint(body, rows, cursor));
+  }
+
+  // Read tmux's authoritative current-screen grid (styled, no scrollback) plus a
+  // consistent cursor position, and turn it into a client repaint. capture-pane reads
+  // tmux's real emulator grid, so it's always internally coherent; captureConsistent
+  // guards the (content, cursor) read against a mid-render cursor move.
+  private captureScreen(): { content: string; cursorX?: number; cursorY?: number } {
+    const { content, cursor } = captureConsistent(
+      () => this.readBackfill(),
+      () => this.readCursor(),
+    );
+    return { content: buildScreenRepaint(content, cursor.cursorX, cursor.cursorY), ...cursor };
+  }
+
+  // Backfill capture: current screen plus scrollback history above it (cursor is
+  // viewport-relative, so it still parks on the live screen). Falls back to screen-only.
+  private readBackfill(): string {
+    if (BACKFILL_SCROLLBACK_LINES <= 0) return this.readScreen();
+    const r = Bun.spawnSync(
+      tmuxCommand(this.socket, "capture-pane", "-p", "-e", "-S", `-${BACKFILL_SCROLLBACK_LINES}`, "-t", this.session),
+      { stdin: "ignore", stdout: "pipe", stderr: "ignore" },
+    );
+    return r.exitCode === 0 ? r.stdout.toString("utf8") : this.readScreen();
+  }
+
+  // Current-screen-only capture (no scrollback) — used by the live resync corrector so it
+  // overwrites just the visible grid and leaves the client's scroll-back history intact.
+  private readScreen(): string {
+    const r = Bun.spawnSync(
+      tmuxCommand(this.socket, "capture-pane", "-p", "-e", "-t", this.session),
+      { stdin: "ignore", stdout: "pipe", stderr: "ignore" },
+    );
+    return r.exitCode === 0 ? r.stdout.toString("utf8") : "";
   }
 
-  // Serialize the emulator into a byte-perfect repaint. When the viewer's dimensions are
-  // given, resize both the tmux pane (so the TUI re-renders at the viewer's width) and the
-  // emulator to match. No stabilization needed: the serialize output puts the client in the
-  // emulator's exact state, and subsequent live deltas apply identically to both.
+  private readCursor(): { cursorX?: number; cursorY?: number } {
+    const r = Bun.spawnSync(
+      tmuxCommand(this.socket, "display-message", "-p", "-t", this.session, "#{cursor_x} #{cursor_y}"),
+      { stdin: "ignore", stdout: "pipe", stderr: "ignore" },
+    );
+    const [x, y] = r.stdout.toString().trim().split(/\s+/).map(Number);
+    return {
+      ...(Number.isFinite(x) ? { cursorX: x } : {}),
+      ...(Number.isFinite(y) ? { cursorY: y } : {}),
+    };
+  }
+
+  // Cursor position plus visibility (cursor_flag), so a resync repaint restores whether
+  // the TUI had the cursor shown or hidden rather than guessing.
+  private readCursorState(): { cursorX?: number; cursorY?: number; visible?: boolean } {
+    const r = Bun.spawnSync(
+      tmuxCommand(this.socket, "display-message", "-p", "-t", this.session, "#{cursor_x} #{cursor_y} #{cursor_flag}"),
+      { stdin: "ignore", stdout: "pipe", stderr: "ignore" },
+    );
+    const [x, y, flag] = r.stdout.toString().trim().split(/\s+/);
+    const cx = Number(x);
+    const cy = Number(y);
+    return {
+      ...(Number.isFinite(cx) ? { cursorX: cx } : {}),
+      ...(Number.isFinite(cy) ? { cursorY: cy } : {}),
+      ...(flag === "0" || flag === "1" ? { visible: flag === "1" } : {}),
+    };
+  }
+
+  // Repaint a freshly-attached (or resumed/refreshed) viewer from tmux's current grid.
+  // When the viewer's dimensions are given we resize the tmux pane first so the TUI
+  // re-renders at the viewer's width, let it settle, then capture the post-resize frame.
   async backfill(cols?: number, rows?: number): Promise<TerminalSnapshot> {
+    let resized = false;
     if (Number.isFinite(cols) && Number.isFinite(rows) && (cols as number) >= 10 && (rows as number) >= 5) {
       const c = Math.trunc(cols as number);
       const r = Math.trunc(rows as number);
-      Bun.spawnSync(
-        tmuxCommand(this.socket, "resize-window", "-t", this.session, "-x", String(c), "-y", String(r)),
-        { stdin: "ignore", stdout: "ignore", stderr: "ignore" },
-      );
-      if (this.term && (c !== this.termCols || r !== this.termRows)) {
-        this.term.resize(c, r);
+      if (c !== this.termCols || r !== this.termRows) {
+        Bun.spawnSync(
+          tmuxCommand(this.socket, "resize-window", "-t", this.session, "-x", String(c), "-y", String(r)),
+          { stdin: "ignore", stdout: "ignore", stderr: "ignore" },
+        );
         this.termCols = c;
         this.termRows = r;
+        resized = true;
       }
     }
-    await this.flushTerm();
-    const content = this.serializer?.serialize() ?? "";
+    if (resized && RESIZE_SETTLE_MS > 0) await Bun.sleep(RESIZE_SETTLE_MS);
+    const { content } = this.captureScreen();
+    // Report tmux's actual pane size (authoritative) back to the viewer.
+    const dims = this.paneDims();
+    if (dims.cols) this.termCols = dims.cols;
+    if (dims.rows) this.termRows = dims.rows;
     const live = sessionLiveness(this.session);
+    tdbg(`backfill ${this.session} req=${cols}x${rows} term=${this.termCols}x${this.termRows} contentLen=${content.length} viewers=${this.subscribers.size}`);
     return {
       session: this.session,
       content,
@@ -334,7 +465,28 @@ class SessionStream {
   resize(cols: number, rows: number): void {
     if (this.closed || !this.proc) return;
     if (!Number.isFinite(cols) || !Number.isFinite(rows) || cols < 10 || rows < 5) return;
-    this.command(`resize-window -t "${this.session}" -x ${Math.trunc(cols)} -y ${Math.trunc(rows)}`);
+    const c = Math.trunc(cols);
+    const r = Math.trunc(rows);
+    this.command(`resize-window -t "${this.session}" -x ${c} -y ${r}`);
+    this.termCols = c;
+    this.termRows = r;
+    tdbg(`resize ${this.session} -> ${c}x${r} viewers=${this.subscribers.size}`);
+  }
+
+  private paneDims(): { cols?: number; rows?: number } {
+    try {
+      const out = Bun.spawnSync(
+        tmuxCommand(this.socket, "display-message", "-p", "-t", this.session, "#{pane_width} #{pane_height}"),
+        { stdin: "ignore", stdout: "pipe", stderr: "ignore" },
+      ).stdout.toString().trim();
+      const [w, h] = out.split(/\s+/).map(Number);
+      return {
+        ...(w !== undefined && Number.isFinite(w) && w > 0 ? { cols: w } : {}),
+        ...(h !== undefined && Number.isFinite(h) && h > 0 ? { rows: h } : {}),
+      };
+    } catch {
+      return {};
+    }
   }
 
   private command(line: string): void {
@@ -348,10 +500,12 @@ class SessionStream {
 
   addSubscriber(sub: TerminalStreamSubscriber): void {
     this.subscribers.add(sub);
+    tdbg(`attach ${this.session} viewers=${this.subscribers.size} term=${this.termCols}x${this.termRows}`);
   }
 
   removeSubscriber(sub: TerminalStreamSubscriber): void {
     if (!this.subscribers.delete(sub)) return;
+    tdbg(`detach ${this.session} viewers=${this.subscribers.size}`);
     if (this.subscribers.size === 0) this.destroy();
   }
 
@@ -374,15 +528,18 @@ class SessionStream {
       clearTimeout(this.flushTimer);
       this.flushTimer = null;
     }
+    if (this.resyncTimer !== null) {
+      clearTimeout(this.resyncTimer);
+      this.resyncTimer = null;
+    }
+    if (this.resyncCapTimer !== null) {
+      clearTimeout(this.resyncCapTimer);
+      this.resyncCapTimer = null;
+    }
     try {
       this.proc?.kill();
     } catch {}
     this.proc = null;
-    try {
-      this.term?.dispose();
-    } catch {}
-    this.term = null;
-    this.serializer = null;
     this.onEmpty();
   }
 }