@yolo-labs/yolobridge 0.21.0 → 0.23.0

package/dist/attach-cmd.js

@@ -22,8 +22,8 @@ import { SseFrameParser } from './sse-frame-parser.js';
 import { actionForFrame } from './frame-actions.js';
 import { startHeartbeat, defaultTimers } from './heartbeat.js';
 import { nextBackoffMs, isFatalCredentialRefusal, fatalCredentialRefusalMessage, } from './reconnect.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 { deliverPromptToLocalAgent, captureLocalAgentOutput, onLocalAgentData, takeRawSeed as takeRawSeedFromAgent, primeRawStream as primeRawStreamFromAgent, getLocalAgentGeometry, writeInputToLocalAgent, } from './local-agent.js';
+import { OutputStreamBuffer, DEFAULT_FLUSH_INTERVAL_MS, INTERACTIVE_ECHO_FLUSH_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';
@@ -78,6 +78,7 @@ export async function runAttachDaemon(deps) {
     const log = deps.log ?? ((line) => process.stdout.write(`${line}\n`));
     const clearScreen = deps.clearScreen ?? (() => process.stdout.write('\x1b[2J\x1b[3J\x1b[H'));
     const deliverPrompt = deps.deliverPrompt ?? deliverPromptToLocalAgent;
+    const writeInput = deps.writeInput ?? writeInputToLocalAgent;
     const captureOutput = deps.captureOutput ?? captureLocalAgentOutput;
     const timers = deps.timers ?? defaultTimers;
     const now = deps.now ?? Date.now;
@@ -925,6 +926,27 @@ export async function runAttachDaemon(deps) {
                                 case 'prompt':
                                     await deliverPrompt(action.prompt);
                                     break;
+                                case 'input': {
+                                    // Raw keystrokes from a console client. Written verbatim —
+                                    // no Enter appended, no readiness gate — see
+                                    // `writeInputToLocalAgent`. Nothing logs the bytes.
+                                    writeInput(action.data);
+                                    // The PTY echoes within ~1ms. Without this the echo waits out
+                                    // the 80ms batch window, which buys nothing for a payload
+                                    // this small and spends ~40% of the latency budget that is
+                                    // ours rather than the network's. `flushOutputStream` re-checks
+                                    // that this session is still current, so a stale timer no-ops.
+                                    const echoSession = outputStream;
+                                    if (echoSession) {
+                                        // A plain timer, not `timers`: that seam exists so tests can
+                                        // drive the heartbeat/flush CADENCE, and widening it for a
+                                        // 5ms nudge would touch every existing double. `unref` so a
+                                        // pending echo can never hold the process open at exit.
+                                        const t = setTimeout(() => { void flushOutputStream(echoSession); }, INTERACTIVE_ECHO_FLUSH_MS);
+                                        t.unref?.();
+                                    }
+                                    break;
+                                }
                                 case 'read-output': {
                                     const captured = await captureOutput();
                                     // Taken AFTER the (async) capture and synchronously, so

package/dist/cli.js

@@ -443,6 +443,10 @@ async function cmdAttach(args) {
                 // real `onExit` handler below: stop + detach immediately rather than
                 // let the daemon loop ride out the full heartbeat-staleness window.
                 try {
+                    // Say where Ctrl+C goes BEFORE the agent takes over the screen.
+                    // Without this the operator presses it expecting to quit, nothing
+                    // happens, and there is no way to discover why.
+                    process.stdout.write('yolo-bridge: Ctrl+C goes to the agent · Ctrl-P Ctrl-Q to detach\n');
                     startLocalAgent({
                         agentBin,
                         // Empty unless the MCP block above successfully resolved argv
@@ -451,6 +455,15 @@ async function cmdAttach(args) {
                         // never a launch carrying a flag the binary would reject.
                         agentArgs: agentMcpArgs,
                         cwd: spawnCwd,
+                        // The daemon's only reachable stop key. `process.on('SIGINT')`
+                        // above cannot fire from the keyboard: stdin is in raw mode so the
+                        // tty never turns Ctrl+C into a signal, and Ctrl+C is deliberately
+                        // forwarded to the AGENT instead (interrupting a runaway agent is
+                        // worth more than quitting the daemon). Same teardown either way.
+                        onDetachRequested: () => {
+                            process.stdout.write('\nyolo-bridge: detaching...\n');
+                            onSignal();
+                        },
                         onExit: ({ exitCode, signal }) => {
                             localAgentExited = true;
                             stopRequested = true;

package/dist/detach-sequence.js

@@ -0,0 +1,80 @@
+/**
+ * The detach escape sequence for `yolo-bridge attach`.
+ *
+ * WHY THIS EXISTS. `cli.ts` registers `process.on('SIGINT', …)` as the daemon's
+ * stop path, and `local-agent.ts` puts stdin into RAW MODE so every byte can be
+ * forwarded to the agent's PTY. Raw mode is precisely the mode in which the
+ * tty stops translating `\x03` into SIGINT — so that handler is not merely at
+ * risk of being missed, it is UNREACHABLE from the keyboard for as long as an
+ * agent is attached. The operator presses Ctrl+C expecting to quit, gets
+ * silence, and the teardown never runs.
+ *
+ * ⚠️ THE FIX IS NOT TO GIVE Ctrl+C BACK TO THE DAEMON. Forwarding it to the
+ * agent is the more valuable behaviour by a wide margin — interrupting a
+ * runaway agent is the thing an operator actually needs mid-session, and a
+ * daemon that quit instead would take the agent down with it. So Ctrl+C keeps
+ * going to the agent and the daemon gets its own key.
+ *
+ * `Ctrl-P Ctrl-Q`, following `docker attach`. Chosen because it is vanishingly
+ * rare in agent TUIs: `Ctrl-C`, `Ctrl-D`, `Ctrl-Z` and a lone `Ctrl-Q` are all
+ * in active use by the CLIs this daemon spawns, and stealing any of them would
+ * trade one broken key for another.
+ */
+/** `Ctrl-P` — the prefix. Held back until the next byte decides its meaning. */
+export const DETACH_PREFIX_BYTE = 0x10;
+/** `Ctrl-Q` — only a detach when it IMMEDIATELY follows the prefix. */
+export const DETACH_SUFFIX_BYTE = 0x11;
+/**
+ * Splits a stdin stream into "detach" and "everything else".
+ *
+ * Byte-oriented and chunk-agnostic on purpose: in raw mode each keypress
+ * usually arrives as its own chunk, but nothing guarantees it, so the two
+ * bytes of the sequence may land together or apart and must behave identically
+ * either way.
+ *
+ * ⚠️ A PREFIX FOLLOWED BY ANYTHING ELSE FORWARDS BOTH BYTES. Swallowing the
+ * `Ctrl-P` would silently break it for agents that use it, which is the same
+ * class of bug this whole change exists to fix.
+ */
+export function createDetachSequenceFilter(opts) {
+    let prefixPending = false;
+    let detached = false;
+    return {
+        push(data) {
+            // Once detached, further keystrokes belong to a session that is going
+            // away; forwarding them would race the teardown.
+            if (detached)
+                return;
+            let out = '';
+            for (let i = 0; i < data.length; i++) {
+                const code = data.charCodeAt(i);
+                if (prefixPending) {
+                    prefixPending = false;
+                    if (code === DETACH_SUFFIX_BYTE) {
+                        // Emit whatever preceded the sequence, then stop. The prefix and
+                        // suffix are consumed and never reach the agent.
+                        if (out)
+                            opts.emit(out);
+                        detached = true;
+                        opts.onDetach();
+                        return;
+                    }
+                    // Not the suffix: the prefix was an ordinary keystroke after all.
+                    out += String.fromCharCode(DETACH_PREFIX_BYTE);
+                    // Fall through so THIS byte is handled normally — including the case
+                    // where it is itself another prefix.
+                }
+                if (code === DETACH_PREFIX_BYTE) {
+                    prefixPending = true;
+                    continue;
+                }
+                out += String.fromCharCode(code);
+            }
+            if (out)
+                opts.emit(out);
+        },
+        dispose() {
+            prefixPending = false;
+        },
+    };
+}

package/dist/frame-actions.js

@@ -27,6 +27,10 @@ export function actionForFrame(frame) {
             return { kind: 'ping' };
         case 'prompt':
             return { kind: 'prompt', attachmentId: String(data.attachmentId ?? ''), prompt: String(data.prompt ?? '') };
+        case 'input':
+            // No coercion beyond String(): these are the operator's own keystrokes
+            // and anything clever here would corrupt a control sequence.
+            return { kind: 'input', attachmentId: String(data.attachmentId ?? ''), data: String(data.data ?? '') };
         case 'read-output':
             return {
                 kind: 'read-output',

package/dist/local-agent.js

@@ -33,6 +33,7 @@
  */
 import { createRequire } from 'node:module';
 import { randomUUID } from 'node:crypto';
+import { createDetachSequenceFilter } from './detach-sequence.js';
 import * as pty from 'node-pty';
 import { splitByUtf8Bytes } from './output-stream.js';
 import { AnsiScanner, TerminalModeTracker, buildModePrologue, resolveGroundStart, } from './ansi-replay-state.js';
@@ -737,8 +738,16 @@ export function startLocalAgent(opts = {}) {
         fanOutRawData(data, pushRaw(data));
     });
     if (inStream && typeof inStream.on === 'function') {
+        // Every byte passes through the detach filter on its way to the PTY. It
+        // forwards everything except the `Ctrl-P Ctrl-Q` sequence — including a
+        // lone `Ctrl-P`, which agents use for history and which must not be eaten.
+        const detachFilter = createDetachSequenceFilter({
+            emit: (chunk) => { ptyProcess.write(chunk); },
+            onDetach: () => { opts.onDetachRequested?.(); },
+        });
+        state.detachFilter = detachFilter;
         const stdinListener = (data) => {
-            ptyProcess.write(typeof data === 'string' ? data : data.toString('utf-8'));
+            detachFilter.push(typeof data === 'string' ? data : data.toString('utf-8'));
         };
         if (inStream.isTTY && typeof inStream.setRawMode === 'function') {
             inStream.setRawMode(true);
@@ -818,6 +827,7 @@ function handleLocalResize(state) {
     }
 }
 function teardownStdio(state) {
+    state.detachFilter?.dispose();
     if (state.resizeSource && state.resizeListener && typeof state.resizeSource.removeListener === 'function') {
         state.resizeSource.removeListener('resize', state.resizeListener);
     }
@@ -858,6 +868,38 @@ export function stopLocalAgent() {
         // already dead
     }
 }
+/**
+ * Write raw bytes straight into the PTY, exactly as typed.
+ *
+ * ⚠️ DELIBERATELY NOT `deliverPromptToLocalAgent`. That function is for one
+ * coherent instruction: it waits on a readiness gate, writes the text, pauses,
+ * then writes `\r`. Every one of those is wrong for a keystroke —
+ * a lone `\x03` would get an Enter appended, an arrow-key escape sequence would
+ * be split by the pause, and the readiness gate would block on a prompt that a
+ * mid-session TUI never shows.
+ *
+ * So this does the minimum: if there is a live PTY, write the bytes. No
+ * interpretation, no framing, no Enter.
+ *
+ * ⚠️ NOTHING HERE LOGS `data`. These are the operator's keystrokes on their own
+ * machine — the same rule the output path already follows, and the reason a
+ * console session logs that it opened and closed and never what was typed.
+ *
+ * Returns false when there is no agent to write to, so a caller can say
+ * "nothing is attached" rather than silently swallowing input.
+ */
+export function writeInputToLocalAgent(data) {
+    if (!current || !data)
+        return false;
+    try {
+        current.ptyProcess.write(data);
+        return true;
+    }
+    catch {
+        // The child is gone; onExit will clear `current`.
+        return false;
+    }
+}
 /**
  * Best-effort readiness check before `deliverPromptToLocalAgent` writes
  * into the PTY — docs/YOLOBRIDGE_PLAN.md's "[P1] Blind prompt delivery can

package/dist/output-stream.js

@@ -42,6 +42,21 @@
  *  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;
+/**
+ * Flush delay after a console keystroke, rather than waiting out the batch
+ * window.
+ *
+ * The 80ms above is right for a passive VIEWER: it trades a little liveness for
+ * ~12 POSTs/second instead of one per `onData`. It is wrong for an interactive
+ * session, where a single echoed keystroke IS the entire payload and the batch
+ * saves nothing while costing up to 80ms of a round trip already near 200ms —
+ * measured 2026-08-28, and roughly 40% of the budget that is ours to spend
+ * rather than the network's.
+ *
+ * 5ms is long enough that a burst of keystrokes still coalesces into one POST,
+ * short enough to be invisible next to the ~160ms the network costs.
+ */
+export const INTERACTIVE_ECHO_FLUSH_MS = 5;
 /** ~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. */

package/package.json

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