@yolo-labs/yolobridge 0.9.0 → 0.10.0

package/dist/api-client.js

@@ -201,6 +201,38 @@ export async function postReadOutputReply(cfg, workspaceId, attachmentId, reques
     });
     return Boolean(body?.resolved);
 }
+/**
+ * `POST .../yolobridge/events {type:'output-chunk'}` — one batch of live PTY
+ * output (docs/YOLOBRIDGE_PLAN.md, "Live terminal streaming").
+ *
+ * Sent ONLY while the server has an unexpired `output-stream-start` lease
+ * outstanding, i.e. only while a browser is actually watching the tile. A
+ * daemon with no viewer sends none of these at all — see attach-cmd.ts's
+ * stream controller.
+ *
+ * Authenticated with the WORKSPACE-SCOPED credential like every other
+ * post-attach call (Boundary B refuses an account token here), and the bytes
+ * are relayed in memory by the server onto the workspace's own event stream —
+ * never logged, never written to Mongo, never appended to the resumable event
+ * buffer. This is the operator's live screen; it can contain anything they
+ * typed.
+ *
+ * `droppedBytes` is how many bytes were SKIPPED immediately before `data`
+ * (see output-stream.ts). Non-zero means the viewer must treat its screen as
+ * unreliable and re-seed — it is not a diagnostic counter, it is part of the
+ * protocol.
+ */
+export async function postOutputChunk(cfg, workspaceId, attachmentId, chunk) {
+    const body = await postEvent(cfg, workspaceId, {
+        attachmentId,
+        type: 'output-chunk',
+        streamId: chunk.streamId,
+        seq: chunk.seq,
+        data: chunk.data,
+        droppedBytes: chunk.droppedBytes,
+    });
+    return Boolean(body?.relayed);
+}
 async function postEvent(cfg, workspaceId, payload) {
     const fetchImpl = cfg.fetchImpl ?? fetch;
     const res = await fetchImpl(`${base(cfg)}/v1/workspaces/${workspaceId}/yolobridge/events`, {

package/dist/attach-cmd.js

@@ -22,7 +22,8 @@ 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 } from './local-agent.js';
+import { deliverPromptToLocalAgent, captureLocalAgentOutput, onLocalAgentData } 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';
 import { loadAuth, saveAuth, loadAttachment, saveAttachment, clearAttachment, } from './config-store.js';
@@ -83,6 +84,8 @@ export async function runAttachDaemon(deps) {
     const refreshBufferMs = deps.refreshBufferMs ?? DEFAULT_REFRESH_BUFFER_MS;
     const authBaseUrl = deps.authBaseUrl ?? process.env.YOLOBRIDGE_AUTH_URL ?? DEFAULT_AUTH_URL;
     const doRefresh = deps.refreshAccessToken ?? refreshAccessTokenApi;
+    const subscribeAgentOutput = deps.subscribeAgentOutput ?? onLocalAgentData;
+    const flushIntervalMs = deps.outputFlushIntervalMs ?? DEFAULT_FLUSH_INTERVAL_MS;
     /**
      * THE ACCOUNT identity. Full-account bearer from `yolo-bridge login`, and the
      * ONLY thing `ensureFreshToken` may write to. Used for exactly one call —
@@ -594,6 +597,110 @@ export async function runAttachDaemon(deps) {
         clearAttachment(env, io);
         return { ok: true, reason: 'stopped' };
     }
+    let outputStream;
+    function stopOutputStream() {
+        const session = outputStream;
+        if (!session)
+            return;
+        outputStream = undefined;
+        try {
+            session.unsubscribe();
+        }
+        catch { /* best effort */ }
+        timers.clearInterval(session.flushHandle);
+        // Anything still queued belongs to a streamId that no longer exists.
+        session.buffer.reset();
+    }
+    async function flushOutputStream(session) {
+        if (outputStream !== session)
+            return;
+        // Lease check FIRST, before any work: this tick is the only thing that
+        // ever notices a lapsed grant, and it must notice it even when the buffer
+        // is empty.
+        if (now() >= session.leaseUntilMs) {
+            stopOutputStream();
+            return;
+        }
+        if (session.posting)
+            return;
+        const batch = session.buffer.drain();
+        if (!batch)
+            return;
+        const bytes = Buffer.byteLength(batch.data, 'utf-8');
+        session.posting = true;
+        try {
+            await apiClient.postOutputChunk(scopedCfg(), workspaceId, attachmentId, {
+                streamId: session.streamId,
+                seq: session.seq,
+                data: batch.data,
+                droppedBytes: batch.droppedBytes,
+            });
+            if (outputStream === session)
+                session.seq += 1;
+        }
+        catch (err) {
+            // These bytes are GONE — re-queueing them would reorder the stream
+            // behind whatever the PTY produced while the POST was in flight, and an
+            // out-of-order terminal frame is worse than an acknowledged hole. Fold
+            // them (plus any gap this batch was already carrying) into the next
+            // batch's `droppedBytes` so the viewer re-seeds instead of trusting a
+            // screen that silently lost a frame.
+            if (outputStream === session)
+                session.buffer.noteDropped(bytes + batch.droppedBytes);
+            // Out-of-band, never `log`: this fires mid-session while the local
+            // agent's TUI owns stdout (connection-state.ts's module header). The
+            // detail carries the transport error only — NEVER the PTY bytes.
+            noteConnection('degraded', {
+                detail: `output chunk relay failed: ${err instanceof Error ? err.message : String(err)}`,
+            });
+        }
+        finally {
+            if (outputStream === session)
+                session.posting = false;
+        }
+    }
+    /**
+     * Honour an `output-stream-start` frame.
+     *
+     * Same `streamId` → this is a LEASE RENEWAL (the server re-sends while
+     * demand persists); keep the tap, the buffer and the sequence exactly as
+     * they are, so a renewal is invisible to the viewer.
+     *
+     * Different `streamId` → a NEW episode (the previous one was stopped, or
+     * this daemon reconnected and the server re-granted). Tear the old one down
+     * first: its queued bytes describe a screen the viewer is no longer showing.
+     */
+    function startOrRenewOutputStream(streamId, leaseMs) {
+        if (!streamId)
+            return;
+        const existing = outputStream;
+        if (existing && existing.streamId === streamId) {
+            existing.leaseUntilMs = now() + leaseMs;
+            return;
+        }
+        stopOutputStream();
+        const buffer = new OutputStreamBuffer(deps.outputStreamOptions);
+        const session = {
+            streamId,
+            seq: 0,
+            buffer,
+            unsubscribe: () => { },
+            flushHandle: undefined,
+            leaseUntilMs: now() + leaseMs,
+            posting: false,
+        };
+        outputStream = session;
+        // Subscribe AFTER the session exists so a synchronous first chunk can't
+        // land on a half-built one.
+        session.unsubscribe = subscribeAgentOutput((data) => {
+            if (outputStream !== session)
+                return;
+            buffer.push(data);
+        });
+        session.flushHandle = timers.setInterval(() => {
+            void flushOutputStream(session);
+        }, flushIntervalMs);
+    }
     let heartbeat;
     let attempt = 0;
     /** Set when a proactive refresh (see ensureFreshToken) fails while a
@@ -737,6 +844,12 @@ export async function runAttachDaemon(deps) {
                                     }));
                                     break;
                                 }
+                                case 'output-stream-start':
+                                    startOrRenewOutputStream(action.streamId, action.leaseMs);
+                                    break;
+                                case 'output-stream-stop':
+                                    stopOutputStream();
+                                    break;
                                 case 'detached':
                                     noteConnection('detached');
                                     sawDetached = true;
@@ -765,6 +878,11 @@ export async function runAttachDaemon(deps) {
             }
             heartbeat?.stop();
             heartbeat = undefined;
+            // The grant died with the connection that carried it. A reconnect gets a
+            // FRESH `output-stream-start` (new streamId) if demand still exists —
+            // never a silent resumption of the old one, which is what keeps a
+            // reconnect from splicing two episodes' bytes into one screen.
+            stopOutputStream();
             if (sawDetached || sawGone) {
                 clearAttachment(env, io);
                 return { ok: true, reason: 'detached-by-server' };
@@ -781,6 +899,11 @@ export async function runAttachDaemon(deps) {
     }
     finally {
         heartbeat?.stop();
+        // Belt and braces for every path out of the loop (a break, a throw, a
+        // stop signal): no code path may leave a live PTY tap or flush timer
+        // behind, or the daemon would keep streaming with nobody watching — the
+        // exact failure this whole mechanism exists to prevent.
+        stopOutputStream();
     }
     if (scopedRefreshFailed) {
         // OUT-OF-BAND ONLY — no `log()` here, unlike the account-token path below.

package/dist/frame-actions.js

@@ -7,6 +7,13 @@
  * reconnecting" — is unit-testable without a live stream or a real
  * daemon loop.
  */
+/** Lease to assume when a server sends `output-stream-start` without one (or
+ *  with a nonsense value). Deliberately short — an unknown lease is a reason to
+ *  be conservative, not generous. */
+export const FALLBACK_OUTPUT_STREAM_LEASE_MS = 30_000;
+/** Upper bound on a server-supplied lease. A buggy or hostile server cannot
+ *  talk this daemon into streaming for an hour on one frame. */
+export const MAX_OUTPUT_STREAM_LEASE_MS = 5 * 60_000;
 export function actionForFrame(frame) {
     const data = (frame.data ?? {});
     switch (frame.event) {
@@ -26,6 +33,20 @@ export function actionForFrame(frame) {
                 attachmentId: String(data.attachmentId ?? ''),
                 requestId: String(data.requestId ?? ''),
             };
+        case 'output-stream-start': {
+            const raw = typeof data.leaseMs === 'number' ? data.leaseMs : NaN;
+            const leaseMs = Number.isFinite(raw) && raw > 0
+                ? Math.min(raw, MAX_OUTPUT_STREAM_LEASE_MS)
+                : FALLBACK_OUTPUT_STREAM_LEASE_MS;
+            return {
+                kind: 'output-stream-start',
+                attachmentId: String(data.attachmentId ?? ''),
+                streamId: String(data.streamId ?? ''),
+                leaseMs,
+            };
+        }
+        case 'output-stream-stop':
+            return { kind: 'output-stream-stop', attachmentId: String(data.attachmentId ?? '') };
         case 'detached':
             return { kind: 'detached', attachmentId: String(data.attachmentId ?? '') };
         default:

package/dist/local-agent.js

@@ -95,6 +95,32 @@ function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
 let current;
+const rawDataListeners = new Set();
+/**
+ * Register a raw-output tap. Returns an unsubscribe that is safe to call more
+ * than once.
+ */
+export function onLocalAgentData(listener) {
+    rawDataListeners.add(listener);
+    return () => {
+        rawDataListeners.delete(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) {
+    if (rawDataListeners.size === 0)
+        return;
+    for (const listener of rawDataListeners) {
+        try {
+            listener(data);
+        }
+        catch {
+            // A broken tap degrades the remote view, never the local session.
+        }
+    }
+}
 function sanitizeEnv(env) {
     const out = {};
     for (const [k, v] of Object.entries(env)) {
@@ -354,6 +380,7 @@ 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);
     });
     if (inStream && typeof inStream.on === 'function') {
         const stdinListener = (data) => {

package/dist/output-stream.js

@@ -0,0 +1,251 @@
+/**
+ * Volume control for the daemon→server live output stream
+ * (docs/YOLOBRIDGE_PLAN.md, "Live terminal streaming").
+ *
+ * PURE — no timers, no network, no PTY. `attach-cmd.ts` owns the flush tick
+ * and the POST; this file owns the only question that is genuinely hard:
+ * **what do we send, and what do we refuse to send, when the PTY produces
+ * more than the link (or the operator's bandwidth budget) can carry?**
+ *
+ * PTY output is bursty and can be enormous — a build log, `yes`, a `cat` of a
+ * multi-megabyte file. Relaying it verbatim would turn one careless command on
+ * the operator's laptop into an unbounded upload and an unbounded fan-out onto
+ * the workspace event bus. Three independent bounds, each doing a different
+ * job:
+ *
+ *   1. **`maxQueueBytes`** — the standing backlog. When the producer outruns
+ *      the drain the queue is trimmed from the FRONT (oldest first), because
+ *      on a terminal the newest bytes are the ones the viewer needs: they are
+ *      what is on screen right now. The trimmed byte count is REMEMBERED, not
+ *      forgotten (see `droppedBytes`).
+ *   2. **`maxBatchBytes`** — the size of any single POST, so one flush can
+ *      never produce a request the server has to buffer megabytes for.
+ *   3. **`maxBytesPerSecond`** — a token bucket over the whole stream. This is
+ *      the one that actually caps sustained cost; the other two bound a single
+ *      moment. A full bucket is allowed as a one-second burst, so ordinary
+ *      agent output (which is bursty but small) is never throttled at all.
+ *
+ * **A drop is always MARKED, never silent.** `drain()` returns the number of
+ * bytes skipped alongside the data that follows them, and the viewer renders
+ * an explicit gap marker and re-seeds from the poll route. That matters
+ * specifically because this is a TERMINAL: dropping bytes out of a stream of
+ * cursor-addressing escapes does not degrade gracefully into "slightly less
+ * text", it produces a screen that is confidently wrong. Telling the viewer
+ * "there is a hole here" is what lets it recover instead of lying.
+ *
+ * Byte lengths are UTF-8 (`Buffer.byteLength`), because that is what actually
+ * crosses the wire — not `String.length`, which under-counts every non-ASCII
+ * character an agent's box-drawing/emoji output is full of.
+ */
+/** Default flush cadence, owned by the caller — exported here so the tuning
+ *  constants that describe one mechanism live together. Short enough that
+ *  output reads as live, long enough that a chatty PTY costs ~12 POSTs/second
+ *  rather than one per `onData`. */
+export const DEFAULT_FLUSH_INTERVAL_MS = 80;
+/** ~192 KiB/s sustained. Comfortably above a fast agent's real output rate
+ *  (a streaming LLM response is a few KiB/s), far below what `cat`ting a
+ *  large file would produce. */
+export const DEFAULT_MAX_BYTES_PER_SECOND = 192 * 1024;
+/** One POST never carries more than this. At the default flush interval this
+ *  is also well above the per-tick share of the rate cap, so it only ever
+ *  binds on the very first tick after an idle period (when the token bucket
+ *  is full). */
+export const DEFAULT_MAX_BATCH_BYTES = 32 * 1024;
+/** Standing backlog cap. Two seconds of rate-capped output — enough to ride
+ *  out one slow POST without dropping anything, small enough that a runaway
+ *  producer can never grow the daemon's heap. */
+export const DEFAULT_MAX_QUEUE_BYTES = 384 * 1024;
+/**
+ * Longest prefix of `s` whose UTF-8 encoding is at most `maxBytes`, plus the
+ * remainder.
+ *
+ * Never splits a surrogate pair: a JS string is UTF-16, and cutting between
+ * the halves of an astral character (an emoji in an agent's output) produces a
+ * lone surrogate, which `JSON.stringify` escapes into a value the server
+ * decodes back as U+FFFD — a permanently corrupted character rather than one
+ * that reassembles on the far side. Splitting only at code-point boundaries
+ * makes the two halves concatenate back into exactly the original text.
+ *
+ * Fast path for pure ASCII (`byteLength === length`), which is the
+ * overwhelming majority of terminal output; the walk is only paid for when a
+ * chunk actually contains multibyte characters AND is large enough to need
+ * splitting.
+ */
+export function splitByUtf8Bytes(s, maxBytes) {
+    if (maxBytes <= 0)
+        return { head: '', tail: s };
+    const total = Buffer.byteLength(s, 'utf-8');
+    if (total <= maxBytes)
+        return { head: s, tail: '' };
+    if (total === s.length) {
+        // Pure ASCII — one byte per UTF-16 code unit, so the cut is exact.
+        return { head: s.slice(0, maxBytes), tail: s.slice(maxBytes) };
+    }
+    let bytes = 0;
+    let i = 0;
+    while (i < s.length) {
+        const code = s.codePointAt(i);
+        const units = code > 0xffff ? 2 : 1;
+        const size = code < 0x80 ? 1 : code < 0x800 ? 2 : code < 0x10000 ? 3 : 4;
+        if (bytes + size > maxBytes)
+            break;
+        bytes += size;
+        i += units;
+    }
+    return { head: s.slice(0, i), tail: s.slice(i) };
+}
+/**
+ * Bounded, rate-limited FIFO of PTY output awaiting relay.
+ *
+ * Holds JS strings rather than Buffers because that is what `node-pty` hands
+ * us and what the JSON body carries — converting to bytes and back would add
+ * two encodes per chunk for no gain, and the only place byte counts matter
+ * (the caps) can measure them on demand.
+ */
+export class OutputStreamBuffer {
+    maxQueueBytes;
+    maxBatchBytes;
+    maxBytesPerSecond;
+    now;
+    chunks = [];
+    queuedBytesValue = 0;
+    droppedBytes = 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. */
+    tokens;
+    lastRefillAt;
+    constructor(opts = {}) {
+        this.maxQueueBytes = opts.maxQueueBytes ?? DEFAULT_MAX_QUEUE_BYTES;
+        this.maxBatchBytes = opts.maxBatchBytes ?? DEFAULT_MAX_BATCH_BYTES;
+        this.maxBytesPerSecond = opts.maxBytesPerSecond ?? DEFAULT_MAX_BYTES_PER_SECOND;
+        this.now = opts.now ?? Date.now;
+        this.tokens = this.maxBytesPerSecond;
+        this.lastRefillAt = this.now();
+    }
+    get queuedBytes() {
+        return this.queuedBytesValue;
+    }
+    /** Bytes skipped so far and not yet reported to the viewer. */
+    get pendingDroppedBytes() {
+        return this.droppedBytes;
+    }
+    /**
+     * Enqueue raw PTY output, trimming the OLDEST bytes if that pushes the
+     * backlog past `maxQueueBytes`.
+     *
+     * A single chunk larger than the whole cap is itself trimmed from its front,
+     * so `push` can never leave the queue over the bound no matter what one
+     * `onData` delivers.
+     */
+    push(chunk) {
+        if (!chunk)
+            return;
+        this.chunks.push(chunk);
+        this.queuedBytesValue += Buffer.byteLength(chunk, 'utf-8');
+        this.trim();
+    }
+    /**
+     * Record bytes that were LOST rather than queued — today, a batch whose POST
+     * failed after `drain()` had already handed the bytes over. Reporting them
+     * as a gap is the honest outcome: they are gone, and the viewer's screen is
+     * missing them either way. Re-queueing them instead would reorder the stream
+     * behind whatever arrived while the POST was in flight, which on a terminal
+     * is worse than an acknowledged hole.
+     */
+    noteDropped(bytes) {
+        if (bytes > 0)
+            this.droppedBytes += bytes;
+    }
+    trim() {
+        while (this.queuedBytesValue > this.maxQueueBytes && this.chunks.length > 0) {
+            const overflow = this.queuedBytesValue - this.maxQueueBytes;
+            const oldest = this.chunks[0];
+            const oldestBytes = Buffer.byteLength(oldest, 'utf-8');
+            if (oldestBytes <= overflow) {
+                this.chunks.shift();
+                this.queuedBytesValue -= oldestBytes;
+                this.droppedBytes += oldestBytes;
+                continue;
+            }
+            // Partially trim the oldest chunk: drop exactly the overflow off its
+            // front (at a code-point boundary) and keep the rest.
+            const { head } = splitByUtf8Bytes(oldest, overflow);
+            const dropped = Buffer.byteLength(head, 'utf-8');
+            const kept = oldest.slice(head.length);
+            this.chunks[0] = kept;
+            this.queuedBytesValue -= dropped;
+            this.droppedBytes += 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.
+            if (dropped === 0) {
+                // Cannot make progress (a single code point wider than the overflow):
+                // drop the whole chunk rather than spin.
+                this.chunks.shift();
+                this.queuedBytesValue -= oldestBytes;
+                this.droppedBytes += oldestBytes;
+            }
+        }
+    }
+    refill() {
+        const at = this.now();
+        const elapsedMs = at - this.lastRefillAt;
+        if (elapsedMs <= 0)
+            return;
+        this.lastRefillAt = at;
+        this.tokens = Math.min(this.maxBytesPerSecond, this.tokens + (this.maxBytesPerSecond * elapsedMs) / 1000);
+    }
+    /**
+     * Take the next batch to relay, or `null` when there is nothing to send
+     * right now (empty queue with no gap to report, or the rate cap is spent).
+     *
+     * Spending the rate cap is deliberately NOT an error and does not itself
+     * drop anything: the bytes stay queued and go out on a later tick. They are
+     * only dropped if the producer keeps running long enough to overflow
+     * `maxQueueBytes` — which is exactly the "genuinely more output than we will
+     * ever relay" case, and is reported as a gap when it happens.
+     */
+    drain() {
+        this.refill();
+        const allowance = Math.min(this.maxBatchBytes, Math.floor(this.tokens));
+        if (allowance <= 0)
+            return null;
+        let taken = '';
+        let takenBytes = 0;
+        while (this.chunks.length > 0 && takenBytes < allowance) {
+            const chunk = this.chunks[0];
+            const chunkBytes = Buffer.byteLength(chunk, 'utf-8');
+            if (takenBytes + chunkBytes <= allowance) {
+                taken += chunk;
+                takenBytes += chunkBytes;
+                this.chunks.shift();
+                this.queuedBytesValue -= chunkBytes;
+                continue;
+            }
+            const { head, tail } = splitByUtf8Bytes(chunk, allowance - takenBytes);
+            if (!head)
+                break; // next code point doesn't fit — leave it for the next tick
+            const headBytes = Buffer.byteLength(head, 'utf-8');
+            taken += head;
+            takenBytes += headBytes;
+            this.chunks[0] = tail;
+            this.queuedBytesValue -= headBytes;
+            break;
+        }
+        const droppedBytes = this.droppedBytes;
+        if (takenBytes === 0 && droppedBytes === 0)
+            return null;
+        this.droppedBytes = 0;
+        this.tokens -= takenBytes;
+        return { data: taken, droppedBytes };
+    }
+    /** Forget everything queued. Used when a stream ends — those bytes belong to
+     *  a `streamId` that no longer exists, and carrying them into the next
+     *  stream would splice one session's screen into another's. */
+    reset() {
+        this.chunks = [];
+        this.queuedBytesValue = 0;
+        this.droppedBytes = 0;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yolo-labs/yolobridge",
-  "version": "0.9.0",
+  "version": "0.10.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",