agent-relay-orchestrator 0.11.1 → 0.11.2

package/package.json

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

package/src/api.ts

@@ -1,12 +1,10 @@
 import { closeSync, lstatSync, mkdirSync, openSync, readdirSync, readSync, realpathSync, statSync } from "node:fs";
-import { createHash } from "node:crypto";
 import { basename, dirname, extname, join, relative, resolve } from "node:path";
 import type { ServerWebSocket } from "bun";
 import { proxyArtifactRequest } from "./artifact-proxy";
 import type { OrchestratorConfig } from "./config";
 import type { ProviderProbeCache } from "./provider-probe";
 import { captureSession, captureTerminal, createTerminalGuest, listSessions, sendTerminalInput, resizeTerminal, stopTerminalGuest } from "./spawn";
-import type { TerminalSnapshot } from "./spawn";
 import { acquireTerminalStream, type TerminalStreamHandle, type TerminalStreamSubscriber } from "./terminal-stream";
 import { VERSION, runtimeMetadata } from "./version";
 import { previewWorkspaceMerge, probeWorkspace, workspaceDiff, workspaceGitState } from "./workspace-probe";
@@ -76,26 +74,6 @@ interface TerminalSocketData {
 
 type TerminalSocket = ServerWebSocket<TerminalSocketData>;
 
-export function terminalSnapshotSignature(snapshot: TerminalSnapshot): string {
-  const hash = createHash("sha1");
-  hash.update(snapshot.session);
-  hash.update("\0");
-  hash.update(snapshot.running ? "1" : "0");
-  hash.update("\0");
-  hash.update(snapshot.agentAlive ? "1" : "0");
-  hash.update("\0");
-  hash.update(String(snapshot.cols ?? ""));
-  hash.update("\0");
-  hash.update(String(snapshot.rows ?? ""));
-  hash.update("\0");
-  hash.update(String(snapshot.cursorX ?? ""));
-  hash.update("\0");
-  hash.update(String(snapshot.cursorY ?? ""));
-  hash.update("\0");
-  hash.update(snapshot.content);
-  return hash.digest("hex");
-}
-
 function listDirectories(requestedPath: string | undefined, baseDir: string): DirectoryListing {
   const base = resolve(baseDir);
   const target = resolve(requestedPath || base);
@@ -599,23 +577,13 @@ function startTerminalSocket(ws: TerminalSocket): void {
   }
 }
 
-// How long to wait between stabilization captures, and how many to try. The viewer's
-// resize fires SIGWINCH at the TUI, whose repaint is *asynchronous* — capturing before
-// it lands snapshots a mid-repaint screen with a transient cursor, and the post-capture
-// relative deltas then land offset and stack a ghost frame. We poll until the capture
-// stops changing (or the budget runs out) so we only ever backfill a quiescent screen.
-const BACKFILL_STABILIZE_STEP_MS = Math.max(20, Number(process.env.AGENT_RELAY_TERMINAL_STABILIZE_STEP_MS) || 60);
-const BACKFILL_STABILIZE_MAX_STEPS = Math.max(0, Number(process.env.AGENT_RELAY_TERMINAL_STABILIZE_MAX_STEPS ?? 8));
-
-// Resize the pane to the viewer's dimensions and capture the matching backfill.
-//
-// Claude's TUI streams pure *relative* cursor deltas (no absolute positioning), so the
-// backfill snapshot must reflect a *settled* screen: the cursor we park has to match
-// where the next delta continues from. We stabilize the capture first (see sendBackfill),
-// so by the time we flush, every byte up to the capture is baked into the snapshot. The
-// capture is synchronous (spawnSync), so the queued bytes are all PRE-capture and already
-// in the snapshot — replaying them would double-apply deltas and stack a garbled ghost
-// frame, so we discard the queue here and only forward bytes that arrive after capture.
+// 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.
 async function syncAndBackfill(ws: TerminalSocket, cols?: number, rows?: number): Promise<void> {
   if (ws.data.syncTimer) {
     clearTimeout(ws.data.syncTimer);
@@ -628,46 +596,13 @@ async function syncAndBackfill(ws: TerminalSocket, cols?: number, rows?: number)
   ws.data.ready = true;
 }
 
-// Re-capture until the screen stops changing (or the budget runs out). The first
-// capture resizes the pane to the viewer geometry, which fires SIGWINCH at the TUI
-// whose repaint is asynchronous; capturing before it lands snapshots a mid-repaint
-// screen with a transient cursor, and the post-capture relative deltas then stack a
-// ghost frame. `shouldAbort` lets the caller bail if the socket is torn down mid-poll.
-export async function captureStableSnapshot(
-  capture: (resize: boolean) => TerminalSnapshot,
-  options?: {
-    stepMs?: number;
-    maxSteps?: number;
-    sleep?: (ms: number) => Promise<void>;
-    shouldAbort?: () => boolean;
-  },
-): Promise<TerminalSnapshot | null> {
-  const stepMs = options?.stepMs ?? BACKFILL_STABILIZE_STEP_MS;
-  const maxSteps = options?.maxSteps ?? BACKFILL_STABILIZE_MAX_STEPS;
-  const sleep = options?.sleep ?? ((ms: number) => Bun.sleep(ms));
-  let snapshot = capture(true);
-  let signature = terminalSnapshotSignature(snapshot);
-  for (let i = 0; i < maxSteps; i++) {
-    await sleep(stepMs);
-    if (options?.shouldAbort?.()) return null;
-    const next = capture(false);
-    const nextSignature = terminalSnapshotSignature(next);
-    snapshot = next;
-    if (nextSignature === signature) break;
-    signature = nextSignature;
-  }
-  return snapshot;
-}
-
-// Send a full reset: a control frame with current geometry/status, then the
-// captured scrollback as a raw byte frame. Used on connect, resume, and refresh.
+// Send a full reset: a control frame with current geometry/status, then the serialized
+// emulator state as a raw byte frame. Used on connect, resume, and refresh.
 async function sendBackfill(ws: TerminalSocket, cols?: number, rows?: number): Promise<void> {
   const stream = ws.data.stream;
   if (!stream) return;
-  const snapshot = await captureStableSnapshot((resize) => (resize ? stream.backfill(cols, rows) : stream.backfill()), {
-    shouldAbort: () => ws.data.stream !== stream,
-  });
-  if (!snapshot) return; // socket torn down mid-stabilize
+  const snapshot = await stream.backfill(cols, rows);
+  if (ws.data.stream !== stream) return; // socket torn down mid-backfill
   ws.send(JSON.stringify({
     type: "reset",
     session: snapshot.session,
@@ -675,23 +610,10 @@ async function sendBackfill(ws: TerminalSocket, cols?: number, rows?: number): P
     agentAlive: snapshot.agentAlive,
     cols: snapshot.cols,
     rows: snapshot.rows,
-    cursorX: snapshot.cursorX,
-    cursorY: snapshot.cursorY,
     capturedAt: snapshot.capturedAt,
   }));
   if (snapshot.content) {
-    // Strip the single trailing newline capture-pane appends. Left in, it scrolls xterm
-    // one extra row so the whole screen sits one row too high — and the cursor-park below
-    // then lands a row off, offsetting every relative statusline redraw (bottom-box ghost).
-    let content = snapshot.content.replace(/\n$/, "");
-    // Park the cursor where tmux actually has it (screen-relative). Without this the
-    // cursor sits at the end of the captured text, so the TUI's first relative redraw
-    // (cursor-up + rewrite of its prompt/statusline) lands at the wrong row and stacks
-    // a ghost copy into scrollback.
-    if (snapshot.cursorX != null && snapshot.cursorY != null) {
-      content += `\x1b[${snapshot.cursorY + 1};${snapshot.cursorX + 1}H`;
-    }
-    ws.send(new TextEncoder().encode(content));
+    ws.send(new TextEncoder().encode(snapshot.content));
   }
 }
 

package/src/spawn.ts

@@ -1144,6 +1144,13 @@ function tmuxHasSession(name: string, socketName?: string): boolean {
   return result.exitCode === 0;
 }
 
+// Lightweight liveness for the live terminal stream's backfill metadata — avoids a full
+// capture-pane just to learn whether the pane/agent are still up.
+export function sessionLiveness(name: string): { running: boolean; agentAlive: boolean } {
+  const socketName = tmuxSocketForSession(name);
+  return { running: tmuxHasSession(name, socketName), agentAlive: isSessionAlive(name) };
+}
+
 function tmuxPaneSize(name: string, socketName?: string): { cols?: number; rows?: number } {
   const result = Bun.spawnSync(tmuxCommand(socketName, "display-message", "-p", "-t", name, "#{pane_width} #{pane_height}"), {
     stdin: "ignore",

package/src/terminal-stream.ts

@@ -8,13 +8,25 @@
 // 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.
+//
 // 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.
 // The relay's own injection path (message delivery, /compact, initial prompts) uses
 // its separate `tmux send-keys` calls and is unaffected — control mode is just
 // another observing client.
 
-import { captureTerminal, tmuxCommand, tmuxSocketForSession, type TerminalSnapshot } from "./spawn";
+import { Terminal } from "@xterm/headless";
+import { SerializeAddon } from "@xterm/addon-serialize";
+import { captureTerminal, 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,12 +47,16 @@ export interface TerminalStreamSubscriber {
 }
 
 export interface TerminalStreamHandle {
-  backfill(cols?: number, rows?: number): TerminalSnapshot;
+  backfill(cols?: number, rows?: number): Promise<TerminalSnapshot>;
   write(bytes: Uint8Array): void;
   resize(cols: number, rows: number): void;
   release(): void;
 }
 
+const DEFAULT_COLS = 80;
+const DEFAULT_ROWS = 24;
+const TERMINAL_SCROLLBACK = Math.max(0, Number(process.env.AGENT_RELAY_TERMINAL_SCROLLBACK) || 1000);
+
 // --- Pure protocol helpers (unit-tested) ---
 
 // Decode a tmux control-mode `%output` payload: printable ASCII is literal, every
@@ -114,6 +130,11 @@ 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;
+  private termCols = DEFAULT_COLS;
+  private termRows = DEFAULT_ROWS;
 
   constructor(
     private readonly session: string,
@@ -140,6 +161,10 @@ class SessionStream {
         { 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",
@@ -213,6 +238,9 @@ 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);
     for (const sub of [...this.subscribers]) {
       if (sub.bufferedAmount && sub.bufferedAmount() > BACKPRESSURE_MAX_BYTES) {
         this.removeSubscriber(sub);
@@ -235,18 +263,67 @@ class SessionStream {
     }
   }
 
-  // Capture the priming snapshot. When the viewer's dimensions are given, resize the
-  // tmux window to exactly that size *first* (synchronously) so the captured content
-  // wraps identically to the client's xterm — a width mismatch desyncs every
-  // absolute-positioned redraw the TUI emits and stacks ghost frames into scrollback.
-  backfill(cols?: number, rows?: number): TerminalSnapshot {
+  // 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);
+    }
+  }
+
+  // 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());
+    });
+  }
+
+  // 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.
+  async backfill(cols?: number, rows?: number): Promise<TerminalSnapshot> {
     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(Math.trunc(cols as number)), "-y", String(Math.trunc(rows as number))),
+        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);
+        this.termCols = c;
+        this.termRows = r;
+      }
     }
-    return captureTerminal(this.session, this.config);
+    await this.flushTerm();
+    const content = this.serializer?.serialize() ?? "";
+    const live = sessionLiveness(this.session);
+    return {
+      session: this.session,
+      content,
+      running: live.running,
+      agentAlive: live.agentAlive,
+      cols: this.termCols,
+      rows: this.termRows,
+      capturedAt: Date.now(),
+    };
   }
 
   write(bytes: Uint8Array): void {
@@ -301,6 +378,11 @@ class SessionStream {
       this.proc?.kill();
     } catch {}
     this.proc = null;
+    try {
+      this.term?.dispose();
+    } catch {}
+    this.term = null;
+    this.serializer = null;
     this.onEmpty();
   }
 }