@yolo-labs/yolobridge 0.20.0 → 0.22.0

package/dist/api-client.js

@@ -303,3 +303,24 @@ export async function finalizeShare(cfg, workspaceId, attachmentId, assetId) {
     const body = (await res.json());
     return { assetId: body?.asset?.assetId ?? assetId };
 }
+/**
+ * Phase 3, optional: write an already-shared asset into ANOTHER tile's session
+ * pod, so the agent there can open it as a real file.
+ *
+ * Only DELIVERY crosses to another tile. The asset itself stays on this
+ * attachment's tile — the server enforces that, and nothing here can ask
+ * otherwise.
+ */
+export async function deliverShare(cfg, workspaceId, attachmentId, assetId, targetTileId) {
+    const fetchImpl = cfg.fetchImpl ?? fetch;
+    const res = await fetchImpl(`${base(cfg)}/v1/workspaces/${workspaceId}/yolobridge/attach/${attachmentId}/deliver`, {
+        method: 'POST',
+        headers: { ...authHeaders(cfg), 'Content-Type': 'application/json' },
+        body: JSON.stringify({ assetId, targetTileId }),
+    });
+    if (!res.ok) {
+        const { message, code } = await parseErrorBody(res);
+        throw new YoloBridgeApiError(message, res.status, code);
+    }
+    return (await res.json());
+}

package/dist/cli.js

@@ -22,7 +22,7 @@ import { realpathSync, existsSync, readFileSync } from 'node:fs';
 import { hostname } from 'node:os';
 import { runLogin } from './login-cmd.js';
 import { runAttachFromDisk, pickWorkspaceFromDisk } from './attach-cmd.js';
-import { runShare } from './share-cmd.js';
+import { runShare, runDeliver } from './share-cmd.js';
 import { runAllow } from './approved-paths.js';
 import { runDetach } from './detach-cmd.js';
 import { getStatus, formatStatus } from './status-cmd.js';
@@ -106,6 +106,10 @@ function printHelp() {
         '                         The daemon\'s own working directory is always allowed.',
         '  share <path>           Share a local file with the attached workspace, so a cloud',
         '                         agent can see it. Push only — nothing reads your disk remotely.',
+        '    [--to <tileId>]      Also write it into that tile\'s session, so its agent can open it.',
+        '  deliver <assetId>      Write an ALREADY-shared file into a tile\'s session, without',
+        '    --to <tileId>        uploading it again. This is the retry path when a share',
+        '                         uploaded fine but the delivery failed.',
         '  status                 Print local login/attach state.',
         '  version                Print the installed yolo-bridge version (also --version, -v).',
         '  --help                 Print this help.',
@@ -439,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
@@ -447,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;
@@ -566,6 +583,22 @@ function cmdStatus() {
     process.stdout.write(`${formatStatus(getStatus())}\n`);
     return 0;
 }
+async function cmdDeliver(args) {
+    const assetId = args.find((a) => !a.startsWith('-') && a !== args[args.indexOf('--to') + 1]);
+    const toIdx = args.indexOf('--to');
+    const targetTileId = toIdx >= 0 ? args[toIdx + 1] : undefined;
+    if (!assetId || !targetTileId) {
+        process.stderr.write('yolo-bridge deliver: usage — yolo-bridge deliver <assetId> --to <tileId>\n');
+        return 64;
+    }
+    const result = await runDeliver(assetId, targetTileId, { commonApiBaseUrl: apiUrl() });
+    if (!result.ok) {
+        process.stderr.write(`yolo-bridge deliver: ${result.message}\n`);
+        return 1;
+    }
+    process.stdout.write(`${result.path}\n`);
+    return 0;
+}
 function cmdAllow(args) {
     const result = runAllow(args);
     if (!result.ok) {
@@ -581,13 +614,22 @@ async function cmdShare(args) {
         process.stderr.write('yolo-bridge share: a file path is required.\n\n  yolo-bridge share ./cut.mp4\n');
         return 64;
     }
-    const result = await runShare(rawPath, { commonApiBaseUrl: apiUrl() });
+    // `--to <tileId>` also writes the file into that tile's session pod.
+    const toIdx = args.indexOf('--to');
+    const targetTileId = toIdx >= 0 ? args[toIdx + 1] : undefined;
+    if (toIdx >= 0 && (!targetTileId || targetTileId.startsWith('-'))) {
+        process.stderr.write('yolo-bridge share: `--to` needs a tile id.\n');
+        return 64;
+    }
+    const result = await runShare(rawPath, { commonApiBaseUrl: apiUrl(), targetTileId });
     if (!result.ok) {
         // Every one of these is an operator-actionable condition, not a bug, so it
         // prints as a sentence with no stack trace.
         process.stderr.write(`yolo-bridge share: ${result.message}\n`);
         return 1;
     }
+    if (result.deliveredPath)
+        process.stdout.write(`${result.deliveredPath}\n`);
     return 0;
 }
 async function cmdWorkspaces() {
@@ -646,6 +688,8 @@ async function main() {
             return cmdDetach();
         case 'allow':
             return cmdAllow(rest);
+        case 'deliver':
+            return cmdDeliver(rest);
         case 'share':
             return cmdShare(rest);
         case 'status':

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/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);
     }

package/dist/local-mcp-tools.js

@@ -25,7 +25,7 @@
  * Do not write a message here claiming more than that.
  */
 import { checkPathApproved } from './approved-paths.js';
-import { runShare, describeShareFailure } from './share-cmd.js';
+import { runShare, runDeliver, describeShareFailure } from './share-cmd.js';
 /** Namespaced so it can never collide with a forwarded cloud tool name. */
 export const SHARE_FILE_TOOL = 'yolobridge_share_file';
 export const LOCAL_TOOL_DEFINITIONS = [
@@ -41,8 +41,30 @@ export const LOCAL_TOOL_DEFINITIONS = [
                     type: 'string',
                     description: 'Path to the local file to send. Must be inside an approved directory.',
                 },
+                assetId: {
+                    type: 'string',
+                    description: 'Optional. Deliver an ALREADY-shared asset instead of uploading again — use this to '
+                        + 'retry a delivery that failed after a successful upload. Requires targetTileId; '
+                        + '`path` is ignored when this is given.',
+                },
+                targetTileId: {
+                    type: 'string',
+                    description: 'Optional. A tile in this workspace to ALSO write the file into, so the agent running '
+                        + 'there can open it directly. Use studio_list_tiles to find the id. Omit to leave the '
+                        + 'file in the workspace only.',
+                },
             },
-            required: ['path'],
+            // TWO CALL SHAPES, so `path` cannot be unconditionally required:
+            //   { path }                  — share a local file
+            //   { assetId, targetTileId } — deliver one already shared, no re-upload
+            // A schema-aware client validates before dispatching, so requiring `path`
+            // outright made the retry form unreachable no matter what the handler
+            // accepted. (codex P1, gpt-5.6-sol — the unit tests call the handler
+            // directly and never saw it.)
+            anyOf: [
+                { required: ['path'] },
+                { required: ['assetId', 'targetTileId'] },
+            ],
             additionalProperties: false,
         },
     },
@@ -82,6 +104,24 @@ export async function runLocalToolCall(msg, ctx) {
     if (name !== SHARE_FILE_TOOL) {
         return isNotification ? undefined : toolResult(id, `Unknown local tool: ${String(name)}`, true);
     }
+    const targetTileId = typeof args.targetTileId === 'string' && args.targetTileId ? args.targetTileId : undefined;
+    const retryAssetId = typeof args.assetId === 'string' && args.assetId ? args.assetId : undefined;
+    // Delivery-only retry: the bytes are already in the workspace, so there is no
+    // path to approve and nothing to read from disk.
+    if (retryAssetId) {
+        if (!targetTileId) {
+            return isNotification ? undefined : toolResult(id, '`targetTileId` is required when retrying delivery of an assetId.', true);
+        }
+        const redeliver = await (ctx.deliverImpl ?? runDeliver)(retryAssetId, targetTileId, {
+            commonApiBaseUrl: ctx.commonApiBaseUrl,
+            expectedWorkspaceId: ctx.workspaceId,
+        });
+        if (isNotification)
+            return undefined;
+        return redeliver.ok
+            ? toolResult(id, `Delivered asset ${retryAssetId} to tile ${targetTileId} at ${redeliver.path}.`)
+            : toolResult(id, redeliver.message, true);
+    }
     const rawPath = typeof args.path === 'string' ? args.path : '';
     if (!rawPath)
         return isNotification ? undefined : toolResult(id, 'A `path` is required.', true);
@@ -93,6 +133,7 @@ export async function runLocalToolCall(msg, ctx) {
         // Property 2: open what the check RESOLVED, not what the caller passed.
         const result = await (ctx.shareImpl ?? runShare)(check.resolvedPath, {
             commonApiBaseUrl: ctx.commonApiBaseUrl,
+            targetTileId,
             // The approval was checked against THIS workspace. The attachment on disk
             // can have been replaced by a second `attach` since the proxy started, so
             // bind the upload to the same workspace or refuse. (codex P2.)
@@ -103,7 +144,12 @@ export async function runLocalToolCall(msg, ctx) {
             return undefined;
         if (!result.ok)
             return toolResult(id, result.message, true);
-        return toolResult(id, `Shared as asset ${result.assetId}. It is now visible in the cloud workspace.`);
+        // When it was delivered, the PATH is the useful half — it is what the
+        // target agent needs to be told in order to open the file.
+        return toolResult(id, result.deliveredPath
+            ? `Shared as asset ${result.assetId} and written into tile ${targetTileId} at ${result.deliveredPath}. `
+                + 'Tell that tile\'s agent to open that path.'
+            : `Shared as asset ${result.assetId}. It is now visible in the cloud workspace.`);
     }
     catch (err) {
         return isNotification ? undefined : toolResult(id, describeShareFailure(err), true);

package/dist/share-cmd.js

@@ -15,7 +15,7 @@
 import { createReadStream } from 'node:fs';
 import { stat } from 'node:fs/promises';
 import path from 'node:path';
-import { presignShare, finalizeShare, YoloBridgeApiError, } from './api-client.js';
+import { presignShare, finalizeShare, deliverShare, YoloBridgeApiError, } from './api-client.js';
 import { loadAuth, loadAttachment } from './config-store.js';
 /**
  * Mirrors common-api's `MAX_ASSET_BYTES`. The server is authoritative and
@@ -147,7 +147,22 @@ export async function shareFile(rawPath, deps) {
     }
     const finalized = await finalizeShare(cfg, deps.workspaceId, deps.attachmentId, presigned.assetId);
     write(`Shared ${file.filename} → ${finalized.assetId}`);
-    return finalized;
+    if (!deps.targetTileId)
+        return finalized;
+    // The upload has ALREADY SUCCEEDED. If delivery fails the file is genuinely
+    // in the workspace, so say that rather than reporting a flat failure and
+    // inviting a re-upload of something already there.
+    try {
+        const delivered = await deliverShare(cfg, deps.workspaceId, deps.attachmentId, finalized.assetId, deps.targetTileId);
+        write(`Delivered to ${deps.targetTileId} at ${delivered.path}`);
+        return { ...finalized, deliveredPath: delivered.path };
+    }
+    catch (err) {
+        const why = err instanceof YoloBridgeApiError ? err.message : err?.message || 'unknown error';
+        throw new ShareError(`${file.filename} was uploaded (asset ${finalized.assetId}) but could not be delivered to `
+            + `${deps.targetTileId}: ${why}. The file IS in the workspace — retry the DELIVERY only, with `
+            + `\`yolo-bridge deliver ${finalized.assetId} --to ${deps.targetTileId}\`, rather than sharing it again.`);
+    }
 }
 /** Turn an API error into something the operator can act on. */
 export function describeShareFailure(err) {
@@ -174,6 +189,44 @@ export function describeShareFailure(err) {
  * the config store rather than from daemon memory — the same credential the
  * running daemon uses, and the only one the upload routes accept (Boundary B).
  */
+/**
+ * The preconditions every daemon-credentialed command shares: logged in,
+ * attached, attached to the EXPECTED workspace, and holding a scoped token.
+ *
+ * Factored out so `runShare` and `runDeliver` cannot drift apart on which
+ * checks they perform or what they say when one fails.
+ */
+function resolveShareIdentity(deps) {
+    if (!loadAuth(deps.env, deps.io)) {
+        return { ok: false, reason: 'not-logged-in', message: 'Not logged in — run `yolo-bridge login` first.' };
+    }
+    const attachment = loadAttachment(deps.env, deps.io);
+    if (!attachment) {
+        return { ok: false, reason: 'not-attached', message: 'No active attachment — run `yolo-bridge attach` first.' };
+    }
+    if (deps.expectedWorkspaceId && attachment.workspaceId !== deps.expectedWorkspaceId) {
+        return {
+            ok: false,
+            reason: 'workspace-changed',
+            message: 'This machine is now attached to a different workspace than the one this request was '
+                + 'authorised against. Nothing was sent. Re-run `yolo-bridge attach` or retry.',
+        };
+    }
+    if (!attachment.scopedToken) {
+        return {
+            ok: false,
+            reason: 'no-scoped-credential',
+            message: 'No workspace-scoped credential is stored for this attachment, so files cannot be shared '
+                + 'from this machine. Run `yolo-bridge attach` to reconnect.',
+        };
+    }
+    return {
+        ok: true,
+        cfg: { commonApiBaseUrl: deps.commonApiBaseUrl, accessToken: attachment.scopedToken, fetchImpl: deps.fetchImpl },
+        workspaceId: attachment.workspaceId,
+        attachmentId: attachment.attachmentId,
+    };
+}
 export async function runShare(rawPath, deps) {
     // Same precondition ordering as detach: `auth.json` is what makes this a
     // set-up machine, and its absence has a far better remedy to offer than a
@@ -210,14 +263,37 @@ export async function runShare(rawPath, deps) {
         fetchImpl: deps.fetchImpl,
     };
     try {
-        const { assetId } = await shareFile(rawPath, {
+        const { assetId, deliveredPath } = await shareFile(rawPath, {
             cfg,
             workspaceId: attachment.workspaceId,
             attachmentId: attachment.attachmentId,
+            targetTileId: deps.targetTileId,
             fetchImpl: deps.fetchImpl,
             write: deps.write,
         });
-        return { ok: true, assetId };
+        return { ok: true, assetId, ...(deliveredPath ? { deliveredPath } : {}) };
+    }
+    catch (err) {
+        return { ok: false, reason: 'error', message: describeShareFailure(err) };
+    }
+}
+/**
+ * Deliver an ALREADY-SHARED asset into a tile's session, without re-uploading.
+ *
+ * WHY THIS EXISTS: `shareFile` tells the operator, after a delivery failure,
+ * that the file IS in the workspace and to retry the delivery rather than the
+ * upload. That instruction was false until this existed — every entry point
+ * began with a fresh presign, so the only available "retry" duplicated the
+ * asset. (codex P2, gpt-5.6-sol.) An error message must name a recovery the
+ * caller can actually perform.
+ */
+export async function runDeliver(assetId, targetTileId, deps) {
+    const preflight = await resolveShareIdentity(deps);
+    if (!preflight.ok)
+        return preflight;
+    try {
+        const delivered = await deliverShare(preflight.cfg, preflight.workspaceId, preflight.attachmentId, assetId, targetTileId);
+        return { ok: true, path: delivered.path };
     }
     catch (err) {
         return { ok: false, reason: 'error', message: describeShareFailure(err) };

package/package.json

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