@yolo-labs/yolobridge 0.10.0 → 0.11.0

package/dist/api-client.js

@@ -191,13 +191,23 @@ export async function postHeartbeat(cfg, workspaceId, attachmentId) {
     const body = await postEvent(cfg, workspaceId, { attachmentId, type: 'heartbeat' });
     return Boolean(body?.recorded);
 }
-export async function postReadOutputReply(cfg, workspaceId, attachmentId, requestId, output, busy) {
+export async function postReadOutputReply(cfg, workspaceId, attachmentId, requestId, output, busy, extra) {
     const body = await postEvent(cfg, workspaceId, {
         attachmentId,
         type: 'read-output-reply',
         requestId,
         output,
         busy,
+        ...(extra?.cols && extra?.rows ? { cols: extra.cols, rows: extra.rows } : {}),
+        ...(extra?.raw
+            ? {
+                raw: extra.raw.data,
+                epoch: extra.raw.epoch,
+                baseOffset: extra.raw.baseOffset,
+                endOffset: extra.raw.endOffset,
+                truncated: extra.raw.truncated,
+            }
+            : {}),
     });
     return Boolean(body?.resolved);
 }
@@ -230,6 +240,9 @@ export async function postOutputChunk(cfg, workspaceId, attachmentId, chunk) {
         seq: chunk.seq,
         data: chunk.data,
         droppedBytes: chunk.droppedBytes,
+        ...(chunk.epoch ? { epoch: chunk.epoch } : {}),
+        ...(typeof chunk.startOffset === 'number' ? { startOffset: chunk.startOffset } : {}),
+        ...(chunk.cols && chunk.rows ? { cols: chunk.cols, rows: chunk.rows } : {}),
     });
     return Boolean(body?.relayed);
 }

package/dist/attach-cmd.js

@@ -22,7 +22,7 @@ import { SseFrameParser } from './sse-frame-parser.js';
 import { actionForFrame } from './frame-actions.js';
 import { startHeartbeat, defaultTimers } from './heartbeat.js';
 import { nextBackoffMs } from './reconnect.js';
-import { deliverPromptToLocalAgent, captureLocalAgentOutput, onLocalAgentData } from './local-agent.js';
+import { deliverPromptToLocalAgent, captureLocalAgentOutput, onLocalAgentData, takeRawSeed as takeRawSeedFromAgent, primeRawStream as primeRawStreamFromAgent, getLocalAgentGeometry, } from './local-agent.js';
 import { OutputStreamBuffer, DEFAULT_FLUSH_INTERVAL_MS, } from './output-stream.js';
 import * as apiClient from './api-client.js';
 import { refreshAccessToken as refreshAccessTokenApi } from './device-auth.js';
@@ -85,6 +85,9 @@ export async function runAttachDaemon(deps) {
     const authBaseUrl = deps.authBaseUrl ?? process.env.YOLOBRIDGE_AUTH_URL ?? DEFAULT_AUTH_URL;
     const doRefresh = deps.refreshAccessToken ?? refreshAccessTokenApi;
     const subscribeAgentOutput = deps.subscribeAgentOutput ?? onLocalAgentData;
+    const takeRawSeed = deps.takeRawSeed ?? takeRawSeedFromAgent;
+    const primeRawStream = deps.primeRawStream ?? primeRawStreamFromAgent;
+    const getGeometry = deps.getAgentGeometry ?? getLocalAgentGeometry;
     const flushIntervalMs = deps.outputFlushIntervalMs ?? DEFAULT_FLUSH_INTERVAL_MS;
     /**
      * THE ACCOUNT identity. Full-account bearer from `yolo-bridge login`, and the
@@ -629,11 +632,16 @@ export async function runAttachDaemon(deps) {
         const bytes = Buffer.byteLength(batch.data, 'utf-8');
         session.posting = true;
         try {
+            const geometry = getGeometry();
             await apiClient.postOutputChunk(scopedCfg(), workspaceId, attachmentId, {
                 streamId: session.streamId,
                 seq: session.seq,
                 data: batch.data,
                 droppedBytes: batch.droppedBytes,
+                epoch: session.epoch,
+                startOffset: batch.startOffset,
+                cols: geometry?.cols,
+                rows: geometry?.rows,
             });
             if (outputStream === session)
                 session.seq += 1;
@@ -679,7 +687,16 @@ export async function runAttachDaemon(deps) {
             return;
         }
         stopOutputStream();
+        // Prime from the raw ring, atomically with taking the tap below. The seed
+        // the viewer fetches is a SEPARATE round trip that can land either side of
+        // this moment, so the stream deliberately starts BEHIND it: overlapping
+        // bytes are trimmed by the viewer using their absolute offsets, whereas a
+        // hole would cost a re-seed. Overlap is free; a gap is not.
+        const prime = primeRawStream();
         const buffer = new OutputStreamBuffer(deps.outputStreamOptions);
+        buffer.setBaseOffset(prime.startOffset);
+        if (prime.data)
+            buffer.push(prime.data);
         const session = {
             streamId,
             seq: 0,
@@ -688,13 +705,22 @@ export async function runAttachDaemon(deps) {
             flushHandle: undefined,
             leaseUntilMs: now() + leaseMs,
             posting: false,
+            epoch: prime.epoch,
         };
         outputStream = session;
         // Subscribe AFTER the session exists so a synchronous first chunk can't
         // land on a half-built one.
-        session.unsubscribe = subscribeAgentOutput((data) => {
+        session.unsubscribe = subscribeAgentOutput((data, meta) => {
             if (outputStream !== session)
                 return;
+            if (meta && meta.epoch !== session.epoch) {
+                // The local agent was respawned under us. Everything queued describes a
+                // screen that no longer exists; rebase onto the new session's offsets
+                // and let the viewer notice the epoch change and re-seed.
+                buffer.reset();
+                buffer.setBaseOffset(meta.startOffset);
+                session.epoch = meta.epoch;
+            }
             buffer.push(data);
         });
         session.flushHandle = timers.setInterval(() => {
@@ -837,8 +863,28 @@ export async function runAttachDaemon(deps) {
                                     break;
                                 case 'read-output': {
                                     const captured = await captureOutput();
+                                    // Taken AFTER the (async) capture and synchronously, so
+                                    // `endOffset` names the exact byte position this reply leaves
+                                    // the viewer at. Anything the PTY produces from here on
+                                    // carries a higher offset and is spliced on by the viewer;
+                                    // anything already inside `raw.data` is trimmed by the same
+                                    // arithmetic. That is what makes seed and tap non-atomic in
+                                    // WALL CLOCK yet exactly-once in effect.
+                                    const raw = action.mode === 'raw' ? takeRawSeed() : undefined;
                                     await apiClient
-                                        .postReadOutputReply(scopedCfg(), workspaceId, attachmentId, action.requestId, captured.output, captured.busy)
+                                        .postReadOutputReply(scopedCfg(), workspaceId, attachmentId, action.requestId, captured.output, captured.busy, {
+                                        cols: raw?.cols ?? captured.cols,
+                                        rows: raw?.rows ?? captured.rows,
+                                        raw: raw
+                                            ? {
+                                                epoch: raw.epoch,
+                                                baseOffset: raw.baseOffset,
+                                                endOffset: raw.endOffset,
+                                                data: raw.data,
+                                                truncated: raw.truncated,
+                                            }
+                                            : undefined,
+                                    })
                                         .catch((err) => noteConnection('degraded', {
                                         detail: `read-output reply failed: ${err instanceof Error ? err.message : String(err)}`,
                                     }));

package/dist/frame-actions.js

@@ -32,6 +32,9 @@ export function actionForFrame(frame) {
                 kind: 'read-output',
                 attachmentId: String(data.attachmentId ?? ''),
                 requestId: String(data.requestId ?? ''),
+                // Anything unrecognized (including an absent field, which is what a
+                // server predating raw seeding sends) means the old screen dump.
+                mode: data.mode === 'raw' ? 'raw' : 'screen',
             };
         case 'output-stream-start': {
             const raw = typeof data.leaseMs === 'number' ? data.leaseMs : NaN;

package/dist/local-agent.js

@@ -32,7 +32,9 @@
  * module at all, so nothing there needed to change.
  */
 import { createRequire } from 'node:module';
+import { randomUUID } from 'node:crypto';
 import * as pty from 'node-pty';
+import { splitByUtf8Bytes } from './output-stream.js';
 // `@xterm/headless`'s published CJS bundle is a heavily minified/webpacked
 // single file — `cjs-module-lexer` (Node ESM's static CJS-named-export
 // detector) can't find `Terminal` on it, so a plain
@@ -45,8 +47,8 @@ const require = createRequire(import.meta.url);
 const { Terminal } = require('@xterm/headless');
 /** Default agent binary: overridable via `--agent` (cli.ts) or this env var. */
 export const DEFAULT_AGENT_BIN = process.env.YOLOBRIDGE_AGENT_BIN || 'claude';
-const DEFAULT_COLS = 120;
-const DEFAULT_ROWS = 40;
+export const DEFAULT_COLS = 120;
+export const DEFAULT_ROWS = 40;
 /** How recently the PTY must have produced output to be considered "busy". */
 const DEFAULT_BUSY_WINDOW_MS = 2_000;
 /**
@@ -109,18 +111,177 @@ export function onLocalAgentData(listener) {
 /** Fan a PTY chunk out to every tap. A throwing tap must never break the
  *  human's own view of the session, which is the very next thing that would
  *  happen if this propagated out of the `onData` handler. */
-function fanOutRawData(data) {
+function fanOutRawData(data, meta) {
     if (rawDataListeners.size === 0)
         return;
     for (const listener of rawDataListeners) {
         try {
-            listener(data);
+            listener(data, meta);
         }
         catch {
             // A broken tap degrades the remote view, never the local session.
         }
     }
 }
+// ─── The raw replay ring (docs/YOLOBRIDGE_PLAN.md, "Live terminal streaming")
+//
+// ⚠️ WHY THIS EXISTS AT ALL, given `serializeTerminalBuffer` already produces a
+// perfectly good screen dump.
+//
+// A line dump is the right primitive for a STATIC snapshot (`read_tile_output`
+// still uses it). It is the WRONG primitive for resuming a LIVE stream, and
+// the difference is not cosmetic. A dump carries the glyphs and their colours
+// and nothing else: not the cursor position, not the scroll region (DECSTBM),
+// not whether the alternate screen is active, not the saved cursor, not
+// autowrap mode. A real TUI — Claude Code, codex, anything with a spinner or a
+// redrawn prompt box — repaints using RELATIVE moves (`\x1b[A`, `\x1b[K`, a
+// bare `\r`). Seed a viewer from a dump and every one of those moves is applied
+// from the wrong origin, so redraws land on the wrong rows: text drawn on top
+// of other text, prompt boxes marching down the screen. That is a state
+// reconstruction bug, and the only fix that does not have a next instance is
+// to stop reconstructing state.
+//
+// So: keep the last `RAW_RING_MAX_BYTES` of the RAW PTY byte stream and replay
+// those bytes into the viewer's terminal. The viewer's xterm then parses
+// exactly what the daemon's terminal parsed and arrives at exactly the same
+// state — no cursor inference, no mode inference, no seam to get wrong.
+//
+// Every byte is stamped with an absolute offset, which is what makes the seed
+// and the tap safe to be two independent, racing operations: overlap is
+// deduplicated by offset and a hole is detected by offset. Neither is possible
+// with `seq`, which only orders what was actually sent.
+/**
+ * Raw PTY bytes retained for seeding a viewer. 256 KiB.
+ *
+ * The number is chosen for what it has to CONTAIN, not for memory: a viewer
+ * seeded mid-session needs the bytes back to (at least) the TUI's most recent
+ * full repaint, and a repainting agent redraws its whole screen many times per
+ * minute — a 120×40 full repaint with colour is on the order of 10-30 KiB, so
+ * this holds many of them. It is also comfortably under the server's 5 MB JSON
+ * body limit, since the whole ring can travel in one seed reply.
+ */
+export const RAW_RING_MAX_BYTES = 256 * 1024;
+/**
+ * How much of the ring is replayed into a NEW streaming episode's queue.
+ *
+ * The tap and the seed are separate round trips, so a viewer's seed can end at
+ * an offset slightly before (or after) the point the tap starts at. Priming
+ * the episode with a recent tail guarantees the stream covers the seam from
+ * below; the viewer trims the duplicate prefix by offset. 64 KiB is ~1000×
+ * more than one HTTP round trip's worth of agent output, and a miss is not
+ * fatal anyway — it reads as a gap and costs one extra re-seed.
+ */
+export const RAW_STREAM_PRIME_BYTES = 64 * 1024;
+function newRawRing() {
+    return { epoch: randomUUID(), chunks: [], bytes: 0, baseOffset: 0, endOffset: 0 };
+}
+let rawRing = newRawRing();
+/** Append to the ring and return where the chunk landed. Synchronous and
+ *  called from `onData`, so a tap and a seed taken in the same tick can never
+ *  disagree about the offset. */
+function pushRaw(data) {
+    const startOffset = rawRing.endOffset;
+    const bytes = Buffer.byteLength(data, 'utf-8');
+    rawRing.chunks.push(data);
+    rawRing.bytes += bytes;
+    rawRing.endOffset += bytes;
+    trimRawRing();
+    return { epoch: rawRing.epoch, startOffset };
+}
+/** Drop from the FRONT until the ring is within its cap, advancing
+ *  `baseOffset` by exactly what was dropped. Cuts only at code-point
+ *  boundaries (`splitByUtf8Bytes`) so a replayed tail is never a lone
+ *  surrogate. */
+function trimRawRing() {
+    while (rawRing.bytes > RAW_RING_MAX_BYTES && rawRing.chunks.length > 0) {
+        const overflow = rawRing.bytes - RAW_RING_MAX_BYTES;
+        const oldest = rawRing.chunks[0];
+        const oldestBytes = Buffer.byteLength(oldest, 'utf-8');
+        if (oldestBytes <= overflow) {
+            rawRing.chunks.shift();
+            rawRing.bytes -= oldestBytes;
+            rawRing.baseOffset += oldestBytes;
+            continue;
+        }
+        const { head, tail } = splitByUtf8Bytes(oldest, overflow);
+        const droppedBytes = Buffer.byteLength(head, 'utf-8');
+        if (droppedBytes === 0) {
+            // A single code point wider than the overflow — drop the chunk rather
+            // than spin.
+            rawRing.chunks.shift();
+            rawRing.bytes -= oldestBytes;
+            rawRing.baseOffset += oldestBytes;
+            continue;
+        }
+        rawRing.chunks[0] = tail;
+        rawRing.bytes -= droppedBytes;
+        rawRing.baseOffset += droppedBytes;
+    }
+}
+/**
+ * Take the current replay tail plus the PTY's grid size, as ONE synchronous
+ * observation.
+ *
+ * Atomic by construction: nothing can interleave between reading the ring and
+ * reading the offsets, so `endOffset` is exactly the position a viewer reaches
+ * by writing `data`. Bytes the PTY produces after this call carry offsets
+ * ≥ `endOffset` and are therefore either spliced on cleanly or (if they were
+ * already in `data`) trimmed away by the viewer — never lost, never applied
+ * twice.
+ */
+export function takeRawSeed() {
+    if (!current)
+        return undefined;
+    return {
+        epoch: rawRing.epoch,
+        baseOffset: rawRing.baseOffset,
+        endOffset: rawRing.endOffset,
+        data: rawRing.chunks.join(''),
+        cols: current.cols,
+        rows: current.rows,
+        truncated: rawRing.baseOffset > 0,
+    };
+}
+export function primeRawStream(maxBytes = RAW_STREAM_PRIME_BYTES) {
+    const all = rawRing.chunks.join('');
+    const total = Buffer.byteLength(all, 'utf-8');
+    if (total <= maxBytes) {
+        return { epoch: rawRing.epoch, startOffset: rawRing.baseOffset, data: all };
+    }
+    const { head, tail } = splitByUtf8Bytes(all, total - maxBytes);
+    return {
+        epoch: rawRing.epoch,
+        startOffset: rawRing.baseOffset + Buffer.byteLength(head, 'utf-8'),
+        data: tail,
+    };
+}
+/** The PTY's grid, which the tile must render at EXACTLY (it cannot be
+ *  resized — the human at the keyboard is watching the same PTY). */
+export function getLocalAgentGeometry() {
+    if (!current)
+        return undefined;
+    return { cols: current.cols, rows: current.rows };
+}
+/** The same recent-activity heuristic `captureLocalAgentOutput` reports, without
+ *  paying for a buffer serialization. */
+export function isLocalAgentBusy() {
+    if (!current)
+        return false;
+    return Date.now() - current.lastOutputAt < current.busyWindowMs;
+}
+/** Test seam: forget the ring and start a fresh epoch. */
+export function __resetRawRing() {
+    rawRing = newRawRing();
+}
+/**
+ * Test seam: the daemon's OWN headless terminal — the thing a remote viewer
+ * must end up cell-for-cell identical to. Exposed only so a test can assert
+ * that equality directly (glyphs, attributes AND cursor position) instead of
+ * eyeballing a serialized dump, which cannot see cursor drift at all.
+ */
+export function __getLocalAgentTerminal() {
+    return current?.term;
+}
 function sanitizeEnv(env) {
     const out = {};
     for (const [k, v] of Object.entries(env)) {
@@ -362,9 +523,16 @@ export function startLocalAgent(opts = {}) {
         env: sanitizeEnv(opts.env ?? process.env),
     });
     const term = new Terminal({ cols, rows, allowProposedApi: true });
+    // A NEW PTY is a new byte stream: everything retained belongs to a screen
+    // that no longer exists, and offsets restart. The fresh `epoch` is what a
+    // viewer keyed to the old one sees, and it re-seeds rather than splicing two
+    // sessions' bytes together.
+    rawRing = newRawRing();
     const state = {
         ptyProcess,
         term,
+        cols,
+        rows,
         lastOutputAt: Date.now(),
         busyWindowMs,
         readinessQuietMs,
@@ -380,7 +548,11 @@ export function startLocalAgent(opts = {}) {
         state.lastOutputAt = Date.now();
         outStream.write(data);
         state.writeChain = state.writeChain.then(() => new Promise((resolve) => term.write(data, () => resolve())));
-        fanOutRawData(data);
+        // Ring FIRST, then the taps, with the offset the ring assigned — a tap and
+        // a `takeRawSeed()` taken in the same tick must agree on where this chunk
+        // sits, or the viewer's dedupe/gap logic is reasoning about two different
+        // coordinate systems.
+        fanOutRawData(data, pushRaw(data));
     });
     if (inStream && typeof inStream.on === 'function') {
         const stdinListener = (data) => {
@@ -401,7 +573,7 @@ export function startLocalAgent(opts = {}) {
             current = undefined;
         opts.onExit?.({ exitCode, signal });
     });
-    return { stop: stopLocalAgent };
+    return { stop: stopLocalAgent, cols, rows };
 }
 /**
  * Real bug (found 2026-08-23 chasing a report that `attach` never fully
@@ -615,5 +787,8 @@ export async function captureLocalAgentOutput() {
     await current.writeChain;
     const output = serializeTerminalBuffer(current.term);
     const busy = Date.now() - current.lastOutputAt < current.busyWindowMs;
-    return { output, busy };
+    // The grid the screen above was laid out FOR. A viewer that renders it at
+    // any other width re-wraps every long line — the dump has no width of its
+    // own, only the one the PTY composed it at.
+    return { output, busy, cols: current.cols, rows: current.rows };
 }

package/dist/output-stream.js

@@ -110,6 +110,13 @@ export class OutputStreamBuffer {
     chunks = [];
     queuedBytesValue = 0;
     droppedBytes = 0;
+    /** Absolute offset of the first byte still queued (== `writeOffset` when the
+     *  queue is empty). Advanced by everything that LEAVES the queue, whether it
+     *  was drained or trimmed, so it always names the next byte a viewer has not
+     *  been offered. */
+    headOffset = 0;
+    /** Absolute offset one past the last byte ever pushed. */
+    writeOffset = 0;
     /** Token bucket, in bytes. Starts FULL so the first burst after an idle
      *  period (the common case — a viewer opens the tile and the agent starts
      *  talking) is never throttled. */
@@ -122,6 +129,22 @@ export class OutputStreamBuffer {
         this.now = opts.now ?? Date.now;
         this.tokens = this.maxBytesPerSecond;
         this.lastRefillAt = this.now();
+        this.headOffset = opts.startOffset ?? 0;
+        this.writeOffset = this.headOffset;
+    }
+    /**
+     * Rebase this buffer onto a new absolute byte position. Only meaningful on
+     * an EMPTY buffer — it is called when a streaming episode starts (priming
+     * from local-agent.ts's raw ring) and when the PTY session underneath is
+     * replaced, both of which discard whatever was queued first.
+     */
+    setBaseOffset(offset) {
+        this.headOffset = offset;
+        this.writeOffset = offset;
+    }
+    /** Absolute offset of the next byte a viewer has not been offered yet. */
+    get nextOffset() {
+        return this.headOffset;
     }
     get queuedBytes() {
         return this.queuedBytesValue;
@@ -142,7 +165,9 @@ export class OutputStreamBuffer {
         if (!chunk)
             return;
         this.chunks.push(chunk);
-        this.queuedBytesValue += Buffer.byteLength(chunk, 'utf-8');
+        const pushed = Buffer.byteLength(chunk, 'utf-8');
+        this.queuedBytesValue += pushed;
+        this.writeOffset += pushed;
         this.trim();
     }
     /**
@@ -166,6 +191,7 @@ export class OutputStreamBuffer {
                 this.chunks.shift();
                 this.queuedBytesValue -= oldestBytes;
                 this.droppedBytes += oldestBytes;
+                this.headOffset += oldestBytes;
                 continue;
             }
             // Partially trim the oldest chunk: drop exactly the overflow off its
@@ -176,6 +202,7 @@ export class OutputStreamBuffer {
             this.chunks[0] = kept;
             this.queuedBytesValue -= dropped;
             this.droppedBytes += dropped;
+            this.headOffset += dropped;
             // `splitByUtf8Bytes` can stop just SHORT of `overflow` when the next
             // code point straddles the boundary; loop again rather than assuming one
             // pass is enough.
@@ -185,6 +212,7 @@ export class OutputStreamBuffer {
                 this.chunks.shift();
                 this.queuedBytesValue -= oldestBytes;
                 this.droppedBytes += oldestBytes;
+                this.headOffset += oldestBytes;
             }
         }
     }
@@ -211,6 +239,7 @@ export class OutputStreamBuffer {
         const allowance = Math.min(this.maxBatchBytes, Math.floor(this.tokens));
         if (allowance <= 0)
             return null;
+        const startOffset = this.headOffset;
         let taken = '';
         let takenBytes = 0;
         while (this.chunks.length > 0 && takenBytes < allowance) {
@@ -238,7 +267,8 @@ export class OutputStreamBuffer {
             return null;
         this.droppedBytes = 0;
         this.tokens -= takenBytes;
-        return { data: taken, droppedBytes };
+        this.headOffset += takenBytes;
+        return { data: taken, droppedBytes, startOffset };
     }
     /** Forget everything queued. Used when a stream ends — those bytes belong to
      *  a `streamId` that no longer exists, and carrying them into the next
@@ -247,5 +277,6 @@ export class OutputStreamBuffer {
         this.chunks = [];
         this.queuedBytesValue = 0;
         this.droppedBytes = 0;
+        this.headOffset = this.writeOffset;
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yolo-labs/yolobridge",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "YoloBridge — local coding-agent daemon that attaches a user's own Claude Code/Codex session to a YOLO Studio workspace as a first-class tile (docs/YOLOBRIDGE_PLAN.md, build-order Phase 5).",
   "license": "MIT",
   "type": "module",