@yolo-labs/yolobridge 0.1.0

package/dist/api-client.js

@@ -0,0 +1,136 @@
+/**
+ * Thin HTTP client for the daemon-facing YoloBridge surface
+ * (`common-api/src/routes/yolobridge.ts`, mounted under
+ * `/v1/workspaces/:workspaceId/yolobridge`). Shapes here are read
+ * directly off that route file + `yolobridge-service.ts`, not guessed.
+ */
+export class YoloBridgeApiError extends Error {
+    status;
+    code;
+    constructor(message, status, code) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = 'YoloBridgeApiError';
+    }
+}
+function base(cfg) {
+    return cfg.commonApiBaseUrl.replace(/\/+$/, '');
+}
+function authHeaders(cfg) {
+    return { Authorization: `Bearer ${cfg.accessToken}` };
+}
+async function parseErrorBody(res) {
+    try {
+        const body = (await res.json());
+        return { message: typeof body?.error === 'string' ? body.error : `HTTP ${res.status}`, code: body?.code };
+    }
+    catch {
+        return { message: `HTTP ${res.status}` };
+    }
+}
+export async function attach(cfg, workspaceId, hostLabel) {
+    const fetchImpl = cfg.fetchImpl ?? fetch;
+    const res = await fetchImpl(`${base(cfg)}/v1/workspaces/${workspaceId}/yolobridge/attach`, {
+        method: 'POST',
+        headers: { ...authHeaders(cfg), 'Content-Type': 'application/json' },
+        body: JSON.stringify(hostLabel ? { hostLabel } : {}),
+    });
+    if (!res.ok) {
+        const { message, code } = await parseErrorBody(res);
+        throw new YoloBridgeApiError(`attach failed: ${message}`, res.status, code);
+    }
+    const body = (await res.json());
+    if (typeof body?.tileId !== 'string' || typeof body?.attachmentId !== 'string') {
+        throw new YoloBridgeApiError('attach returned an unexpected shape', res.status);
+    }
+    return { tileId: body.tileId, attachmentId: body.attachmentId };
+}
+/**
+ * `GET /v1/workspaces/selectable` — slim `{id,name,status}` list of the
+ * caller's own non-terminated, non-ephemeral workspaces (capped at 500
+ * server-side), authenticated the same `flexibleAuth` tier as every other
+ * call in this file. There's no membership/role model in this codebase —
+ * a user's workspaces are strictly `{ userId: <them> }` — so this is a
+ * single owner-scoped list, not a "workspaces I can see" query.
+ * (`common-api/src/routes/workspaces.ts`, `WorkspaceService.listSelectable`.)
+ */
+export async function listSelectableWorkspaces(cfg) {
+    const fetchImpl = cfg.fetchImpl ?? fetch;
+    const res = await fetchImpl(`${base(cfg)}/v1/workspaces/selectable`, {
+        method: 'GET',
+        headers: authHeaders(cfg),
+    });
+    if (!res.ok) {
+        const { message, code } = await parseErrorBody(res);
+        throw new YoloBridgeApiError(`list workspaces failed: ${message}`, res.status, code);
+    }
+    const body = (await res.json());
+    if (!Array.isArray(body?.workspaces)) {
+        throw new YoloBridgeApiError('list workspaces returned an unexpected shape', res.status);
+    }
+    const workspaces = [];
+    for (const w of body.workspaces) {
+        if (typeof w?.id !== 'string' || typeof w?.status !== 'string') {
+            throw new YoloBridgeApiError('list workspaces returned an unexpected shape', res.status);
+        }
+        workspaces.push({ id: w.id, name: typeof w.name === 'string' ? w.name : '', status: w.status });
+    }
+    return workspaces;
+}
+export async function detach(cfg, workspaceId, attachmentId) {
+    const fetchImpl = cfg.fetchImpl ?? fetch;
+    const res = await fetchImpl(`${base(cfg)}/v1/workspaces/${workspaceId}/yolobridge/attach/${attachmentId}`, {
+        method: 'DELETE',
+        headers: authHeaders(cfg),
+    });
+    // 204 on success; a 404 (already detached) is treated as success too —
+    // detach is idempotent from the CLI's point of view.
+    if (!res.ok && res.status !== 404) {
+        const { message, code } = await parseErrorBody(res);
+        throw new YoloBridgeApiError(`detach failed: ${message}`, res.status, code);
+    }
+}
+/** Opens the raw `GET /stream` connection. Caller owns reading/parsing `res.body`. */
+export async function openStream(cfg, workspaceId, attachmentId) {
+    const fetchImpl = cfg.fetchImpl ?? fetch;
+    const url = `${base(cfg)}/v1/workspaces/${workspaceId}/yolobridge/stream?attachmentId=${encodeURIComponent(attachmentId)}`;
+    const res = await fetchImpl(url, { method: 'GET', headers: { ...authHeaders(cfg), Accept: 'text/event-stream' } });
+    if (!res.ok || !res.body) {
+        const { message, code } = await parseErrorBody(res);
+        throw new YoloBridgeApiError(`stream open failed: ${message}`, res.status, code);
+    }
+    return res;
+}
+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) {
+    const body = await postEvent(cfg, workspaceId, {
+        attachmentId,
+        type: 'read-output-reply',
+        requestId,
+        output,
+        busy,
+    });
+    return Boolean(body?.resolved);
+}
+async function postEvent(cfg, workspaceId, payload) {
+    const fetchImpl = cfg.fetchImpl ?? fetch;
+    const res = await fetchImpl(`${base(cfg)}/v1/workspaces/${workspaceId}/yolobridge/events`, {
+        method: 'POST',
+        headers: { ...authHeaders(cfg), 'Content-Type': 'application/json' },
+        body: JSON.stringify(payload),
+    });
+    if (!res.ok) {
+        const { message, code } = await parseErrorBody(res);
+        throw new YoloBridgeApiError(`events (${payload.type}) failed: ${message}`, res.status, code);
+    }
+    try {
+        return await res.json();
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/attach-cmd.js

@@ -0,0 +1,299 @@
+/**
+ * `yolo-bridge attach <workspaceId>` — the daemon loop.
+ *
+ * Calls `POST .../yolobridge/attach`, then holds `GET .../yolobridge/stream`
+ * open: parses SSE frames (sse-frame-parser.ts), dispatches them
+ * (frame-actions.ts), reconnects with backoff on disconnect
+ * (reconnect.ts), and posts a heartbeat every ~10s while connected
+ * (heartbeat.ts). All the pure logic lives in those sibling modules and is
+ * unit tested there; this file is the network/process glue that wires
+ * them together, plus a light structural test below driving it through a
+ * fake in-memory SSE stream.
+ *
+ * Sleep/wake-aware resilience: see reconnect.ts's header comment — plain
+ * bounded exponential backoff is implemented; true OS sleep/wake signal
+ * detection is NOT, and is called out there and in the final report as a
+ * deliberate scope cut.
+ */
+import { Readable } from 'node:stream';
+import { StringDecoder } from 'node:string_decoder';
+import * as readline from 'node:readline';
+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 * as apiClient from './api-client.js';
+import { refreshAccessToken as refreshAccessTokenApi } from './device-auth.js';
+import { loadAuth, saveAuth, saveAttachment, clearAttachment } from './config-store.js';
+const DEFAULT_AUTH_URL = 'https://auth.yololabs.ai';
+/** Refresh once the access token has less than this much validity left.
+ * Production access tokens live 24h; 5min gives ample margin against a
+ * slow/retried refresh call before the old token actually 401s. */
+const DEFAULT_REFRESH_BUFFER_MS = 5 * 60_000;
+/** How often to re-check `shouldStop()`/a failed-refresh flag while an SSE
+ * stream is open and blocked on `for await`. The server holds the stream
+ * open indefinitely (keepalive pings only), so without an active poll here
+ * a stop signal would never be noticed until the stream happened to end on
+ * its own — which, by design, it doesn't. Small enough to be prompt,
+ * cheap enough to not matter (a no-op comparison on every tick). */
+const STOP_POLL_INTERVAL_MS = 250;
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+export async function runAttachDaemon(deps) {
+    const { workspaceId, commonApiBaseUrl, hostLabel, auth, env, io, fetchImpl, } = deps;
+    const shouldStop = deps.shouldStop ?? (() => false);
+    const sleep = deps.sleep ?? defaultSleep;
+    const log = deps.log ?? ((line) => process.stdout.write(`${line}\n`));
+    const deliverPrompt = deps.deliverPrompt ?? deliverPromptToLocalAgent;
+    const captureOutput = deps.captureOutput ?? captureLocalAgentOutput;
+    const timers = deps.timers ?? defaultTimers;
+    const now = deps.now ?? Date.now;
+    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 cfg = { commonApiBaseUrl, accessToken: auth.accessToken, fetchImpl };
+    let currentAuth = auth;
+    /**
+     * Proactive refresh (Bug 2 fix): checked before opening/reopening the
+     * stream and on every heartbeat tick while connected, so the daemon
+     * rotates its access token well before the 24h production expiry
+     * instead of degrading into a silent zombie that just starts 401ing.
+     * Updates both the in-memory `cfg`/`currentAuth` used by every
+     * subsequent API call in this process AND the on-disk auth.json (via
+     * `saveAuth`) so a later `status`/restart also sees the fresh token.
+     */
+    async function ensureFreshToken() {
+        if (now() < currentAuth.expiresAtMs - refreshBufferMs)
+            return { ok: true };
+        const result = await doRefresh(authBaseUrl, currentAuth.refreshToken, fetchImpl);
+        if (result.status !== 'ok') {
+            return { ok: false, message: result.message };
+        }
+        currentAuth = {
+            accessToken: result.tokens.accessToken,
+            refreshToken: result.tokens.refreshToken,
+            tokenType: currentAuth.tokenType,
+            expiresAtMs: result.tokens.expiresAtMs,
+        };
+        cfg.accessToken = currentAuth.accessToken;
+        saveAuth(currentAuth, env, io);
+        log('Access token refreshed.');
+        return { ok: true };
+    }
+    // Cover the case where the daemon is (re)started against a token that's
+    // already within the refresh buffer of expiry (e.g. `attach` run right
+    // after a long-down period) — refresh before the very first network
+    // call, not just before subsequent reconnects.
+    const initialRefresh = await ensureFreshToken();
+    if (!initialRefresh.ok) {
+        log(`Token refresh failed: ${initialRefresh.message}`);
+        log('Run `yolo-bridge login` again.');
+        return { ok: false, reason: 'refresh-failed', message: initialRefresh.message };
+    }
+    let attachmentId;
+    let tileId;
+    try {
+        const result = await apiClient.attach(cfg, workspaceId, hostLabel);
+        attachmentId = result.attachmentId;
+        tileId = result.tileId;
+    }
+    catch (err) {
+        return { ok: false, reason: 'attach-failed', message: err instanceof Error ? err.message : String(err) };
+    }
+    saveAttachment({ workspaceId, tileId, attachmentId, attachedAt: new Date().toISOString() }, env, io);
+    log(`Attached. tileId=${tileId} attachmentId=${attachmentId}`);
+    // Codex-found race: if something already asked us to stop WHILE the
+    // initial refresh/attach network round trip above was in flight (e.g. the
+    // local agent process this daemon spawns exits almost immediately), the
+    // caller's own onExit-triggered best-effort detach ran too early — before
+    // this attachment existed anywhere — and found nothing to clean up. The
+    // `while (!shouldStop())` loop below would otherwise exit on its very
+    // first check having never opened a stream, returning `{ ok: true,
+    // reason: 'stopped' }` with the attachment just created above left as a
+    // permanent orphan (the CLI's own post-return cleanup skips it too, since
+    // it believes the onExit path already handled detaching). Catch it here,
+    // right after this call is the one that created it, so there's exactly
+    // one place responsible for cleaning up what it made.
+    if (shouldStop()) {
+        await apiClient.detach(cfg, workspaceId, attachmentId).catch((err) => {
+            log(`Cleanup detach failed: ${err instanceof Error ? err.message : String(err)}`);
+        });
+        clearAttachment(env, io);
+        return { ok: true, reason: 'stopped' };
+    }
+    let heartbeat;
+    let attempt = 0;
+    /** Set when a proactive refresh (see ensureFreshToken) fails while a
+     * stream is open — picked up right after the current for-await unwinds
+     * (forced via the stop-poll below) so the daemon stops instead of
+     * looping forever reconnecting with a dead token. */
+    let refreshFailed;
+    try {
+        while (!shouldStop()) {
+            const preStreamRefresh = await ensureFreshToken();
+            if (!preStreamRefresh.ok) {
+                refreshFailed = preStreamRefresh;
+                break;
+            }
+            let sawDetached = false;
+            try {
+                const res = await apiClient.openStream(cfg, workspaceId, attachmentId);
+                attempt = 0; // reset backoff on a successful connect
+                const parser = new SseFrameParser();
+                const nodeStream = Readable.fromWeb(res.body);
+                // Codex review (2026-08-23, fourth pass): a per-chunk
+                // `chunk.toString('utf-8')` decodes each network chunk in
+                // isolation — if a multibyte UTF-8 character (e.g. in a
+                // non-ASCII prompt) straddles a chunk boundary, each half decodes
+                // independently to a replacement character (U+FFFD), corrupting
+                // the prompt before it ever reaches JSON parsing or the PTY.
+                // `StringDecoder` carries incomplete trailing bytes over to the
+                // next `write()` call, so a split character reassembles correctly
+                // regardless of where the network happened to cut the chunk. Scoped
+                // per-connection (declared here, not outside the `while` loop) —
+                // a new connection can't continue a byte sequence from a previous
+                // one, so fresh decoder state per attempt is correct, matching the
+                // per-connection `parser` right above.
+                const decoder = new StringDecoder('utf-8');
+                // Bug 1 fix: the server holds this stream open indefinitely
+                // (keepalive pings only), so `for await` below never completes on
+                // its own — `shouldStop()` being poll-based (not push-based; see
+                // cli.ts's SIGINT/SIGTERM handler) means it must be actively
+                // polled independent of whether/when the next chunk arrives, and
+                // acted on by tearing the stream down, or a signal during an
+                // active stream is never actually noticed. Same mechanism also
+                // unblocks a mid-stream proactive-refresh failure (`refreshFailed`
+                // above) instead of riding out the connection to its next natural
+                // event.
+                const stopPollHandle = timers.setInterval(() => {
+                    if (shouldStop() || refreshFailed) {
+                        nodeStream.destroy();
+                    }
+                }, STOP_POLL_INTERVAL_MS);
+                try {
+                    for await (const chunk of nodeStream) {
+                        const text = Buffer.isBuffer(chunk) ? decoder.write(chunk) : String(chunk);
+                        for (const frame of parser.push(text)) {
+                            const action = actionForFrame(frame);
+                            switch (action.kind) {
+                                case 'connected':
+                                    log('Stream connected.');
+                                    heartbeat?.stop();
+                                    heartbeat = startHeartbeat(async () => {
+                                        const refreshCheck = await ensureFreshToken();
+                                        if (!refreshCheck.ok) {
+                                            refreshFailed = refreshCheck;
+                                            return;
+                                        }
+                                        await apiClient.postHeartbeat(cfg, workspaceId, attachmentId);
+                                    }, (err) => log(`heartbeat error: ${err instanceof Error ? err.message : String(err)}`), undefined, deps.timers);
+                                    // Send one immediately so status isn't stale for the first ~10s.
+                                    apiClient.postHeartbeat(cfg, workspaceId, attachmentId).catch((err) => log(`initial heartbeat error: ${err instanceof Error ? err.message : String(err)}`));
+                                    break;
+                                case 'ping':
+                                    break;
+                                case 'prompt':
+                                    await deliverPrompt(action.prompt);
+                                    break;
+                                case 'read-output': {
+                                    const captured = await captureOutput();
+                                    await apiClient
+                                        .postReadOutputReply(cfg, workspaceId, attachmentId, action.requestId, captured.output, captured.busy)
+                                        .catch((err) => log(`read-output reply failed: ${err instanceof Error ? err.message : String(err)}`));
+                                    break;
+                                }
+                                case 'detached':
+                                    log('Detached by server.');
+                                    sawDetached = true;
+                                    break;
+                                case 'unknown':
+                                    log(`Unrecognized frame type: ${action.event}`);
+                                    break;
+                            }
+                            if (sawDetached)
+                                break;
+                        }
+                        if (sawDetached)
+                            break;
+                    }
+                }
+                finally {
+                    timers.clearInterval(stopPollHandle);
+                }
+            }
+            catch (err) {
+                log(`Stream error: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            heartbeat?.stop();
+            heartbeat = undefined;
+            if (sawDetached) {
+                clearAttachment(env, io);
+                return { ok: true, reason: 'detached-by-server' };
+            }
+            if (refreshFailed)
+                break;
+            if (shouldStop())
+                break;
+            attempt += 1;
+            const delay = nextBackoffMs(attempt, deps.backoffOpts);
+            log(`Reconnecting in ${delay}ms (attempt ${attempt})...`);
+            await sleep(delay);
+        }
+    }
+    finally {
+        heartbeat?.stop();
+    }
+    if (refreshFailed) {
+        log(`Token refresh failed: ${refreshFailed.message}`);
+        log('Run `yolo-bridge login` again.');
+        return { ok: false, reason: 'refresh-failed', message: refreshFailed.message };
+    }
+    return { ok: true, reason: 'stopped' };
+}
+/** Convenience wrapper: loads auth from disk first (used by cli.ts). */
+export async function runAttachFromDisk(opts) {
+    const auth = loadAuth(opts.env, opts.io);
+    if (!auth)
+        return { ok: false, reason: 'not-logged-in' };
+    return runAttachDaemon({ ...opts, auth });
+}
+function defaultPrompt(question) {
+    return new Promise((resolve) => {
+        const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+        rl.question(question, (answer) => {
+            rl.close();
+            resolve(answer);
+        });
+    });
+}
+export async function pickWorkspaceFromDisk(deps) {
+    const auth = loadAuth(deps.env, deps.io);
+    if (!auth)
+        return { ok: false, reason: 'not-logged-in' };
+    const log = deps.log ?? ((line) => process.stdout.write(`${line}\n`));
+    const prompt = deps.prompt ?? defaultPrompt;
+    const cfg = {
+        commonApiBaseUrl: deps.commonApiBaseUrl,
+        accessToken: auth.accessToken,
+        fetchImpl: deps.fetchImpl,
+    };
+    let workspaces;
+    try {
+        workspaces = await apiClient.listSelectableWorkspaces(cfg);
+    }
+    catch (err) {
+        return { ok: false, reason: 'list-failed', message: err instanceof Error ? err.message : String(err) };
+    }
+    if (workspaces.length === 0)
+        return { ok: false, reason: 'no-workspaces' };
+    log('Select a workspace to attach:');
+    workspaces.forEach((ws, i) => {
+        log(`  ${i + 1}. ${ws.name || '(unnamed)'} [${ws.status}]  ${ws.id}`);
+    });
+    const answer = (await prompt('Enter a number: ')).trim();
+    const index = Number.parseInt(answer, 10);
+    if (!Number.isInteger(index) || index < 1 || index > workspaces.length) {
+        return { ok: false, reason: 'no-selection' };
+    }
+    return { ok: true, workspaceId: workspaces[index - 1].id };
+}

package/dist/browser-open.js

@@ -0,0 +1,46 @@
+/**
+ * Best-effort "open the verification URL in a browser" helper.
+ *
+ * JUDGMENT CALL (plan says either is fine, "your call, note which you
+ * picked"): no `open`/`opener` npm dependency added. Shelling out to the
+ * platform's own opener (`open` on macOS, `xdg-open` on Linux, `start` via
+ * `cmd` on Windows) covers the common case with zero new dependency
+ * surface, and login always prints the URL + code clearly regardless of
+ * whether the spawn succeeds — headless/SSH sessions (a real case for a
+ * CLI daemon meant to run on a dev box) degrade to "copy this URL"
+ * automatically, no separate code path needed.
+ */
+import { spawn as realSpawn } from 'node:child_process';
+export function openBrowserBestEffort(url, spawnImpl = realSpawn) {
+    try {
+        const platform = process.platform;
+        let child;
+        if (platform === 'darwin') {
+            child = spawnImpl('open', [url], { stdio: 'ignore', detached: true });
+        }
+        else if (platform === 'win32') {
+            child = spawnImpl('cmd', ['/c', 'start', '""', url], { stdio: 'ignore', detached: true, shell: true });
+        }
+        else {
+            child = spawnImpl('xdg-open', [url], { stdio: 'ignore', detached: true });
+        }
+        // Codex review (2026-08-23, fourth pass): a missing opener binary (no
+        // `xdg-open` on a minimal/headless Linux box, the common case this
+        // helper is meant to degrade gracefully on) doesn't throw SYNCHRONOUSLY
+        // — spawn() returns a child and emits `error` (e.g. ENOENT) on a later
+        // tick, which this surrounding try/catch cannot catch. An EventEmitter
+        // `error` event with no listener throws and crashes the process, so
+        // login was crashing instead of degrading to "copy this URL" as
+        // intended. Register the listener BEFORE unref() so it's in place for
+        // that later tick.
+        child.on('error', () => {
+            // Best-effort only — the caller always prints the URL, so a failed
+            // spawn (no DISPLAY, missing xdg-open, headless box) is a non-event.
+        });
+        child.unref();
+    }
+    catch {
+        // Best-effort only — the caller always prints the URL, so a failed
+        // spawn (no DISPLAY, missing xdg-open, headless box) is a non-event.
+    }
+}