@yolo-labs/yolobridge 0.1.0

package/dist/cli.js

@@ -0,0 +1,353 @@
+#!/usr/bin/env node
+/**
+ * `yolo-bridge` — YoloBridge local daemon CLI (docs/YOLOBRIDGE_PLAN.md,
+ * Implementation Plan → build-order step 5).
+ *
+ * Subcommands:
+ *   yolo-bridge login                 — device-authorization flow (login-cmd.ts)
+ *   yolo-bridge workspaces            — list selectable workspaces (workspaces-cmd.ts)
+ *   yolo-bridge attach [workspaceId]  — attach + hold the SSE stream (attach-cmd.ts)
+ *                                        (omit the id for an interactive picker)
+ *   yolo-bridge detach                — DELETE the current attachment (detach-cmd.ts)
+ *   yolo-bridge status                — print local login/attach state (status-cmd.ts)
+ *
+ * Base URLs default to this repo's real hostnames (CLAUDE.md → Project
+ * Overview): common-api `https://api.yolo.studio`, auth-service
+ * `https://auth.yololabs.ai`. Override with YOLOBRIDGE_API_URL /
+ * YOLOBRIDGE_AUTH_URL for local dev against a different environment.
+ */
+import { fileURLToPath } from 'node:url';
+import { realpathSync } from 'node:fs';
+import { runLogin } from './login-cmd.js';
+import { runAttachFromDisk, pickWorkspaceFromDisk } from './attach-cmd.js';
+import { runDetach } from './detach-cmd.js';
+import { getStatus, formatStatus } from './status-cmd.js';
+import { startLocalAgent, stopLocalAgent, DEFAULT_AGENT_BIN } from './local-agent.js';
+import { runListWorkspaces, formatWorkspacesTable } from './workspaces-cmd.js';
+const DEFAULT_API_URL = 'https://api.yolo.studio';
+const DEFAULT_AUTH_URL = 'https://auth.yololabs.ai';
+function apiUrl() {
+    return process.env.YOLOBRIDGE_API_URL || DEFAULT_API_URL;
+}
+function authUrl() {
+    return process.env.YOLOBRIDGE_AUTH_URL || DEFAULT_AUTH_URL;
+}
+// Mongo ObjectId shape: 24 hex chars. A workspace name could theoretically
+// collide with this (unlikely, but possible), in which case the id-shaped
+// value wins — same tradeoff the rest of this codebase's id-or-slug lookups
+// make, and matches user expectation: someone who types a raw id wants that
+// exact workspace, not a name lookup that happens to match the same string.
+const OBJECT_ID_RE = /^[0-9a-f]{24}$/i;
+/**
+ * Resolves an `attach` positional argument that may be a raw workspace id OR
+ * a workspace NAME. An id-shaped value is used as-is (no network round trip
+ * — unchanged behavior for every existing caller). Anything else is treated
+ * as a name and resolved via the same `GET .../workspaces/selectable` list
+ * `yolo-bridge workspaces` and the interactive picker already use — a
+ * case-insensitive exact match. Zero or multiple matches is a clear error
+ * (never a silent first-match guess); multiple matches lists the candidate
+ * ids so the caller can disambiguate with the id form instead.
+ */
+export async function resolveWorkspaceIdOrName(value, deps, 
+// Injectable for tests (same convention as attach-cmd.ts's RefreshTokenFn)
+// — avoids mocking module-level network calls to exercise the pure
+// matching/error logic below.
+listWorkspacesFn = runListWorkspaces) {
+    if (OBJECT_ID_RE.test(value))
+        return { ok: true, workspaceId: value };
+    const listed = await listWorkspacesFn({ commonApiBaseUrl: deps.commonApiBaseUrl });
+    if (!listed.ok) {
+        return { ok: false, message: listed.message };
+    }
+    const needle = value.toLowerCase();
+    const matches = listed.workspaces.filter((w) => (w.name || '').toLowerCase() === needle);
+    if (matches.length === 0) {
+        return {
+            ok: false,
+            message: `no workspace named "${value}" found (run \`yolo-bridge workspaces\` to see your workspaces)`,
+        };
+    }
+    if (matches.length > 1) {
+        const candidates = matches.map((w) => `${w.id} [${w.status}]`).join(', ');
+        return { ok: false, message: `multiple workspaces are named "${value}" — attach by id instead: ${candidates}` };
+    }
+    return { ok: true, workspaceId: matches[0].id };
+}
+function printHelp() {
+    process.stdout.write([
+        'Usage: yolo-bridge <command> [args]',
+        '',
+        'Commands:',
+        '  login                  Device-authorization login against auth-service.',
+        '  workspaces             List your own workspaces (id, name, status) that can be attached to.',
+        '  attach [workspace]     Attach this machine to a workspace and hold the daemon loop open.',
+        '                         Accepts either a raw workspace id or its NAME (case-insensitive',
+        '                         exact match against `yolo-bridge workspaces`); an ambiguous or',
+        '                         unmatched name errors instead of guessing. Omit it entirely to pick',
+        '                         interactively from `yolo-bridge workspaces`.',
+        '    [--label <name>]     Operator-facing host label (reported to the workspace).',
+        '    [--agent <binary>]   Local coding-agent binary to spawn (default: $YOLOBRIDGE_AGENT_BIN or "claude").',
+        '  detach                 Detach the current workspace attachment.',
+        '  status                 Print local login/attach state.',
+        '  --help                 Print this help.',
+        '',
+        `API base:   ${apiUrl()} (override: YOLOBRIDGE_API_URL)`,
+        `Auth base:  ${authUrl()} (override: YOLOBRIDGE_AUTH_URL)`,
+        `Agent bin:  ${DEFAULT_AGENT_BIN} (override: --agent or YOLOBRIDGE_AGENT_BIN)`,
+        '',
+    ].join('\n'));
+}
+async function cmdLogin() {
+    const result = await runLogin({ authBaseUrl: authUrl() });
+    if (result.ok)
+        return 0;
+    process.stderr.write(`yolo-bridge login: ${result.message}\n`);
+    return 1;
+}
+/**
+ * Parses `attach`'s argv into its recognized `--label <name>` / `--agent
+ * <binary>` flag pairs plus a leftover positional workspaceId — consuming
+ * each flag's value together with the flag itself *before* deciding what's
+ * left over for the positional, so e.g. `attach --label laptop` doesn't
+ * mistake "laptop" for a workspace id (it should still fall through to the
+ * interactive picker). An unrecognized `--something` is a hard error rather
+ * than being silently swallowed as some other flag's value.
+ */
+export function parseAttachArgs(args) {
+    let workspaceId;
+    let hostLabel;
+    let agentBin;
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === '--label' || a === '--agent') {
+            const value = args[i + 1];
+            if (value === undefined || value.startsWith('--')) {
+                return { error: `${a} requires a value` };
+            }
+            if (a === '--label')
+                hostLabel = value;
+            else
+                agentBin = value;
+            i++;
+            continue;
+        }
+        if (a.startsWith('--')) {
+            return { error: `unrecognized option '${a}'` };
+        }
+        if (workspaceId === undefined) {
+            workspaceId = a;
+        }
+    }
+    return { workspaceId, hostLabel, agentBin };
+}
+async function cmdAttach(args) {
+    const parsed = parseAttachArgs(args);
+    if ('error' in parsed) {
+        process.stderr.write(`yolo-bridge attach: ${parsed.error}\n`);
+        process.stderr.write('Usage: yolo-bridge attach [workspaceId] [--label <name>] [--agent <binary>]\n');
+        return 64;
+    }
+    let workspaceId = parsed.workspaceId;
+    const hostLabel = parsed.hostLabel;
+    const agentBin = parsed.agentBin;
+    if (workspaceId) {
+        const resolved = await resolveWorkspaceIdOrName(workspaceId, { commonApiBaseUrl: apiUrl() });
+        if (!resolved.ok) {
+            process.stderr.write(`yolo-bridge attach: ${resolved.message}\n`);
+            return 64;
+        }
+        workspaceId = resolved.workspaceId;
+    }
+    if (!workspaceId) {
+        // No positional id — fall back to an interactive picker over the
+        // caller's own `GET .../workspaces/selectable` list instead of just
+        // failing (nobody has a raw workspace ObjectId memorized).
+        const pick = await pickWorkspaceFromDisk({ commonApiBaseUrl: apiUrl() });
+        if (!pick.ok) {
+            switch (pick.reason) {
+                case 'not-logged-in':
+                    process.stderr.write('yolo-bridge attach: not logged in — run `yolo-bridge login` first.\n');
+                    break;
+                case 'no-workspaces':
+                    process.stderr.write('yolo-bridge attach: no workspaces found for your account.\n');
+                    break;
+                case 'no-selection':
+                    process.stderr.write('yolo-bridge attach: no workspace selected.\n');
+                    break;
+                case 'list-failed':
+                    process.stderr.write(`yolo-bridge attach: ${pick.message}\n`);
+                    break;
+            }
+            process.stderr.write('Usage: yolo-bridge attach [workspaceId] [--label <name>] [--agent <binary>]\n');
+            return 64;
+        }
+        workspaceId = pick.workspaceId;
+    }
+    let stopRequested = false;
+    let localAgentExited = false;
+    const onSignal = () => {
+        if (stopRequested)
+            return;
+        stopRequested = true;
+        process.stdout.write('\nyolo-bridge: caught interrupt, detaching...\n');
+    };
+    process.on('SIGINT', onSignal);
+    process.on('SIGTERM', onSignal);
+    // Spawns the local coding agent under a real PTY right away — this
+    // command is what launches the user's local session (see
+    // docs/YOLOBRIDGE_PLAN.md's "⚠ Not yet functional" section). The PTY's
+    // output streams live to this process's own stdout and this process's
+    // stdin is piped into the PTY, so the terminal running `attach` is a
+    // live view onto the exact session remote prompts land in.
+    startLocalAgent({
+        agentBin,
+        onExit: ({ exitCode, signal }) => {
+            localAgentExited = true;
+            stopRequested = true;
+            process.stdout.write(`\nyolo-bridge: local agent exited (code=${exitCode}${signal ? `, signal=${signal}` : ''}), detaching...\n`);
+            // Fire-and-forget: don't wait on the SSE loop to unwind on its own
+            // (it only re-checks shouldStop() at loop boundaries) to report the
+            // status change — tell the server immediately so the tile flips to
+            // `stopped` right away instead of riding out the heartbeat
+            // staleness window (~90s, Decision Q2). The daemon loop below still
+            // exits promptly too, via `shouldStop`.
+            runDetach({ commonApiBaseUrl: apiUrl() }).catch(() => undefined);
+        },
+    });
+    const result = await runAttachFromDisk({
+        workspaceId,
+        commonApiBaseUrl: apiUrl(),
+        hostLabel,
+        shouldStop: () => stopRequested,
+    });
+    process.removeListener('SIGINT', onSignal);
+    process.removeListener('SIGTERM', onSignal);
+    // Whatever ended the attach loop — local Ctrl+C, a server-initiated
+    // `detached` frame, or the agent process exiting on its own — also ends
+    // the PTY session `attach` spawned. Safe no-op if it already exited.
+    stopLocalAgent();
+    if (!result.ok) {
+        if (result.reason === 'not-logged-in') {
+            process.stderr.write('yolo-bridge attach: not logged in — run `yolo-bridge login` first.\n');
+        }
+        else {
+            process.stderr.write(`yolo-bridge attach: ${result.message}\n`);
+        }
+        // Codex-found gap: `refresh-failed` can fire on a RECONNECT cycle, well
+        // after the initial `apiClient.attach` created the server-side
+        // attachment and saved attachment.json — this early return used to skip
+        // the runDetach() cleanup below (guarded on `result.ok`), leaving a
+        // permanent stale attachment behind (the tile never flips to `stopped`,
+        // and a later `attach` piles on a second one instead of replacing it).
+        // Best-effort and safe even when `refresh-failed` happened on the VERY
+        // FIRST refresh (before any attach ever succeeded, so nothing is
+        // attached): runDetach() reads local attachment.json first and returns
+        // a harmless `not-attached` when there's nothing to clean up. The
+        // refresh-buffer window (proactive refresh starts 5min before expiry —
+        // see DEFAULT_REFRESH_BUFFER_MS in attach-cmd.ts) means the token used
+        // to reach that point is usually still valid for one more request, so
+        // this detach call has a real chance of succeeding rather than just
+        // failing the same way the refresh did.
+        if (result.reason === 'refresh-failed') {
+            await runDetach({ commonApiBaseUrl: apiUrl() }).catch(() => undefined);
+        }
+        return 1;
+    }
+    if (stopRequested && !localAgentExited) {
+        // Local Ctrl+C stop (the agent-exit path above already detached):
+        // best-effort tell the server we're leaving too, so the tile flips to
+        // stopped promptly instead of waiting out the heartbeat staleness
+        // window.
+        await runDetach({ commonApiBaseUrl: apiUrl() }).catch(() => undefined);
+    }
+    process.stdout.write(`yolo-bridge: stopped (${result.reason}).\n`);
+    return 0;
+}
+async function cmdDetach() {
+    const result = await runDetach({ commonApiBaseUrl: apiUrl() });
+    if (result.ok) {
+        process.stdout.write('Detached.\n');
+        return 0;
+    }
+    process.stderr.write(`yolo-bridge detach: ${result.message}\n`);
+    return result.reason === 'not-logged-in' || result.reason === 'not-attached' ? 1 : 1;
+}
+function cmdStatus() {
+    process.stdout.write(`${formatStatus(getStatus())}\n`);
+    return 0;
+}
+async function cmdWorkspaces() {
+    const result = await runListWorkspaces({ commonApiBaseUrl: apiUrl() });
+    if (!result.ok) {
+        if (result.reason === 'not-logged-in') {
+            process.stderr.write('yolo-bridge workspaces: not logged in — run `yolo-bridge login` first.\n');
+        }
+        else {
+            process.stderr.write(`yolo-bridge workspaces: ${result.message}\n`);
+        }
+        return 1;
+    }
+    process.stdout.write(`${formatWorkspacesTable(result.workspaces)}\n`);
+    return 0;
+}
+async function main() {
+    const [, , cmd, ...rest] = process.argv;
+    switch (cmd) {
+        case 'login':
+            return cmdLogin();
+        case 'workspaces':
+            return cmdWorkspaces();
+        case 'attach':
+            return cmdAttach(rest);
+        case 'detach':
+            return cmdDetach();
+        case 'status':
+            return cmdStatus();
+        case '--help':
+        case '-h':
+        case undefined:
+            printHelp();
+            return cmd === undefined ? 64 : 0;
+        default:
+            process.stderr.write(`yolo-bridge: unknown command '${cmd}'\n`);
+            printHelp();
+            return 64;
+    }
+}
+// Guard direct execution vs. being imported (e.g. by cli.test.ts to reach
+// `parseAttachArgs`) — without this, importing this module would run `main`
+// against whatever process's argv happened to be doing the importing.
+//
+// `process.argv[1]` is the RAW path used to invoke node — for a bin entry
+// invoked via a symlink (exactly how `npm link` and every real
+// `npm install -g` set up a package's bin — never a plain copy), that's the
+// symlink's own path, unresolved. `import.meta.url`, on the other hand, is
+// resolved by Node's ESM loader THROUGH any symlink to the real underlying
+// file. Comparing the two directly therefore NEVER matches under a symlinked
+// invocation — this shipped broken: `yolo-bridge` on PATH (via `npm link` or
+// a real global install) silently did nothing, exit 0, no output, because
+// `main()` never ran. Only `node dist/cli.js <path-to-the-real-file>` (never
+// how an installed CLI is actually invoked) happened to pass. Fixed by
+// realpath-resolving argv[1] before comparing, so both sides refer to the
+// same underlying file regardless of how many symlinks sit in between.
+function resolveRealpath(p) {
+    if (!p)
+        return undefined;
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return p; // argv[1] should always exist as a real file when actually running; fall back rather than throw
+    }
+}
+const isMainModule = fileURLToPath(import.meta.url) === resolveRealpath(process.argv[1]);
+if (isMainModule) {
+    main()
+        .then((code) => {
+        process.exitCode = code;
+    })
+        .catch((err) => {
+        process.stderr.write(`yolo-bridge: unexpected error: ${err instanceof Error ? err.stack || err.message : String(err)}\n`);
+        process.exitCode = 1;
+    });
+}

package/dist/config-store.js

@@ -0,0 +1,99 @@
+/**
+ * Local on-disk state for the YoloBridge daemon: the device-flow auth
+ * tokens from `yolo-bridge login`, and the current attachment record from
+ * `yolo-bridge attach`. Config dir choice (docs/YOLOBRIDGE_PLAN.md's
+ * historical §1.1 already named this location for the superseded design;
+ * kept for this build too): `~/.config/yolobridge/`.
+ *
+ *   ~/.config/yolobridge/auth.json        — device-flow token pair
+ *   ~/.config/yolobridge/attachment.json  — current workspace attachment
+ *
+ * Both files are written with mode 0600 (best-effort — not enforced on
+ * every platform) since `auth.json` holds a live Bearer-equivalent
+ * credential. Follows the same injectable-I/O pattern as
+ * `packages/yolo-cli/src/auth-context.ts` (`ReadFileImpl`) so callers can
+ * unit test against an in-memory stub instead of the real filesystem.
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+export const defaultIO = {
+    readFile(filePath) {
+        try {
+            return fs.readFileSync(filePath, 'utf-8');
+        }
+        catch {
+            return undefined;
+        }
+    },
+    writeFile(filePath, contents) {
+        fs.mkdirSync(path.dirname(filePath), { recursive: true });
+        fs.writeFileSync(filePath, contents, { mode: 0o600 });
+    },
+    removeFile(filePath) {
+        try {
+            fs.unlinkSync(filePath);
+        }
+        catch {
+            /* already gone — fine */
+        }
+    },
+};
+export function configDir(env = process.env) {
+    const home = env.HOME || os.homedir();
+    return path.join(home, '.config', 'yolobridge');
+}
+function authPath(env) {
+    return path.join(configDir(env), 'auth.json');
+}
+function attachmentPath(env) {
+    return path.join(configDir(env), 'attachment.json');
+}
+export function loadAuth(env = process.env, io = defaultIO) {
+    const raw = io.readFile(authPath(env));
+    if (!raw)
+        return undefined;
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.accessToken === 'string' &&
+            typeof parsed.refreshToken === 'string' &&
+            typeof parsed.tokenType === 'string' &&
+            typeof parsed.expiresAtMs === 'number') {
+            return parsed;
+        }
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function saveAuth(auth, env = process.env, io = defaultIO) {
+    io.writeFile(authPath(env), `${JSON.stringify(auth, null, 2)}\n`);
+}
+export function clearAuth(env = process.env, io = defaultIO) {
+    io.removeFile(authPath(env));
+}
+export function loadAttachment(env = process.env, io = defaultIO) {
+    const raw = io.readFile(attachmentPath(env));
+    if (!raw)
+        return undefined;
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.workspaceId === 'string' &&
+            typeof parsed.tileId === 'string' &&
+            typeof parsed.attachmentId === 'string' &&
+            typeof parsed.attachedAt === 'string') {
+            return parsed;
+        }
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function saveAttachment(attachment, env = process.env, io = defaultIO) {
+    io.writeFile(attachmentPath(env), `${JSON.stringify(attachment, null, 2)}\n`);
+}
+export function clearAttachment(env = process.env, io = defaultIO) {
+    io.removeFile(attachmentPath(env));
+}

package/dist/detach-cmd.js

@@ -0,0 +1,37 @@
+/**
+ * `yolo-bridge detach` — calls `DELETE /attach/:attachmentId` and clears
+ * the locally stored attachment record.
+ *
+ * Note on "stops the daemon loop" (build-order step 5's requirement):
+ * this command and a running `yolo-bridge attach` daemon are typically
+ * two SEPARATE OS processes (attach runs in the foreground holding the
+ * SSE connection). `detach` doesn't reach into that other process
+ * directly — instead it relies on the real server behavior already
+ * implemented in `yolobridge-service.ts`'s `detachDaemon`: the DELETE
+ * writes a `detached` SSE frame onto the held stream before closing it
+ * (`writeFrame(held.res, 'detached', ...)`). The running attach daemon's
+ * frame dispatcher (frame-actions.ts → attach-cmd.ts) treats that frame
+ * as a clean stop signal and exits its own loop. So `detach` from a
+ * second terminal really does stop the daemon loop, just via the
+ * existing server round trip rather than an OS-level signal. Ctrl+C on
+ * the attach process itself is the separate, local stop path (wired in
+ * cli.ts).
+ */
+import { detach as apiDetach } from './api-client.js';
+import { loadAuth, loadAttachment, clearAttachment } from './config-store.js';
+export async function runDetach(deps) {
+    const auth = loadAuth(deps.env, deps.io);
+    if (!auth)
+        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 found.' };
+    try {
+        await apiDetach({ commonApiBaseUrl: deps.commonApiBaseUrl, accessToken: auth.accessToken, fetchImpl: deps.fetchImpl }, attachment.workspaceId, attachment.attachmentId);
+    }
+    catch (err) {
+        return { ok: false, reason: 'error', message: err instanceof Error ? err.message : String(err) };
+    }
+    clearAttachment(deps.env, deps.io);
+    return { ok: true };
+}

package/dist/device-auth.js

@@ -0,0 +1,149 @@
+/**
+ * OAuth device-authorization flow client against auth-service
+ * (`auth/src/routes/auth.routes.ts:145-146`, controller in
+ * `auth/src/controllers/AuthController.ts` — `initiateDeviceFlow` /
+ * `pollDeviceFlow`). Field names below were read directly off that
+ * controller, not guessed or ported from yolomax (whose source is gone):
+ *
+ *   POST /api/v1/auth/device/code   → { device_code, user_code,
+ *     verification_uri, verification_url, expires_in, interval }
+ *   POST /api/v1/auth/device/token  body { device_code } →
+ *     200 { access_token, refresh_token, token_type, expires_in, expires_at }
+ *     4xx { error: { message, statusCode } } — `message` is one of
+ *       'authorization_pending' | 'access_denied' | 'expired_token'
+ *       | 'Invalid device code' | 'Invalid device code state'
+ *
+ * NOTE (discrepancy from docs/YOLOBRIDGE_PLAN.md): the plan's Architecture
+ * section says login "opens the browser to the verification URL with the
+ * code pre-filled". The actual `initiateDeviceFlow` controller returns a
+ * bare `verification_uri` (`${FRONTEND_URL}/device`, no query string) —
+ * there is no code-prefill parameter in the real response. The CLI below
+ * prints the user_code alongside the URL and expects the user to type it
+ * in manually, same as GitHub's device flow UX. If prefill lands later on
+ * the webapp `/device` page, this client doesn't need to change — it just
+ * won't benefit from it.
+ */
+export class DeviceAuthError extends Error {
+}
+function normalizeBase(authBaseUrl) {
+    return authBaseUrl.replace(/\/+$/, '');
+}
+export async function requestDeviceCode(authBaseUrl, fetchImpl = fetch) {
+    const res = await fetchImpl(`${normalizeBase(authBaseUrl)}/api/v1/auth/device/code`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: '{}',
+    });
+    const body = await safeJson(res);
+    if (!res.ok) {
+        throw new DeviceAuthError(`device/code failed: ${res.status} ${extractErrorMessage(body)}`);
+    }
+    if (typeof body?.device_code !== 'string' ||
+        typeof body?.user_code !== 'string' ||
+        typeof body?.verification_uri !== 'string') {
+        throw new DeviceAuthError('device/code returned an unexpected shape (missing device_code/user_code/verification_uri)');
+    }
+    return {
+        deviceCode: body.device_code,
+        userCode: body.user_code,
+        verificationUri: body.verification_uri,
+        expiresInSec: typeof body.expires_in === 'number' ? body.expires_in : 600,
+        intervalSec: typeof body.interval === 'number' ? body.interval : 5,
+    };
+}
+export async function pollDeviceToken(authBaseUrl, deviceCode, fetchImpl = fetch) {
+    const res = await fetchImpl(`${normalizeBase(authBaseUrl)}/api/v1/auth/device/token`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ device_code: deviceCode }),
+    });
+    const body = await safeJson(res);
+    if (res.ok) {
+        if (typeof body?.access_token !== 'string' ||
+            typeof body?.refresh_token !== 'string' ||
+            typeof body?.token_type !== 'string') {
+            return { status: 'error', message: 'device/token returned 200 with an unexpected shape' };
+        }
+        const expiresInSec = typeof body.expires_in === 'number' ? body.expires_in : 3600;
+        const expiresAtMs = typeof body.expires_at === 'number' ? body.expires_at : Date.now() + expiresInSec * 1000;
+        return {
+            status: 'authorized',
+            tokens: {
+                accessToken: body.access_token,
+                refreshToken: body.refresh_token,
+                tokenType: body.token_type,
+                expiresInSec,
+                expiresAtMs,
+            },
+        };
+    }
+    const message = extractErrorMessage(body);
+    if (message === 'authorization_pending')
+        return { status: 'pending' };
+    if (message === 'access_denied')
+        return { status: 'denied' };
+    if (message === 'expired_token')
+        return { status: 'expired' };
+    return { status: 'error', message: message || `device/token failed: ${res.status}` };
+}
+/**
+ * `POST /api/v1/auth/refresh` — used to proactively rotate the daemon's
+ * access token before it expires (see attach-cmd.ts). Field names read
+ * directly off `auth/src/controllers/AuthController.ts:995` (`refreshToken`)
+ * and `auth/src/services/TokenService.ts`'s `TokenPair` interface — NOTE
+ * this is a *different* shape from the device-flow endpoints above:
+ *
+ *   request  body { refresh_token }                              (snake_case)
+ *   response 200  { tokens: { accessToken, refreshToken,
+ *                             expiresIn } }                       (camelCase,
+ *     no token_type, no absolute expiry — this route hands back the same
+ *     `TokenPair` shape `res.json({ tokens })` serializes with no
+ *     case-conversion middleware in front of it)
+ *   4xx  { error: { message, statusCode } } — same errorHandler as the
+ *     device-flow routes, so `extractErrorMessage` below is reused as-is.
+ *
+ * Unauthenticated (no `authenticate` middleware on this route) — the
+ * refresh token in the body is the credential.
+ */
+export async function refreshAccessToken(authBaseUrl, refreshToken, fetchImpl = fetch) {
+    const res = await fetchImpl(`${normalizeBase(authBaseUrl)}/api/v1/auth/refresh`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ refresh_token: refreshToken }),
+    });
+    const body = await safeJson(res);
+    if (!res.ok) {
+        return { status: 'failed', message: extractErrorMessage(body) || `refresh failed: ${res.status}` };
+    }
+    const tokens = body?.tokens;
+    if (typeof tokens?.accessToken !== 'string' ||
+        typeof tokens?.refreshToken !== 'string' ||
+        typeof tokens?.expiresIn !== 'number') {
+        return { status: 'failed', message: 'refresh returned an unexpected shape (missing tokens.accessToken/refreshToken/expiresIn)' };
+    }
+    return {
+        status: 'ok',
+        tokens: {
+            accessToken: tokens.accessToken,
+            refreshToken: tokens.refreshToken,
+            expiresInSec: tokens.expiresIn,
+            expiresAtMs: Date.now() + tokens.expiresIn * 1000,
+        },
+    };
+}
+async function safeJson(res) {
+    try {
+        return await res.json();
+    }
+    catch {
+        return undefined;
+    }
+}
+/** auth-service's errorHandler shape is `{ error: { message, statusCode } }`. */
+function extractErrorMessage(body) {
+    if (typeof body?.error?.message === 'string')
+        return body.error.message;
+    if (typeof body?.error === 'string')
+        return body.error;
+    return '';
+}

package/dist/frame-actions.js

@@ -0,0 +1,34 @@
+/**
+ * Pure mapping from a parsed `SseFrame` (sse-frame-parser.ts) to a typed
+ * action the attach daemon should take. Kept separate from the actual
+ * network/process-lifecycle glue in attach-cmd.ts so the dispatch logic
+ * itself — "a `prompt` frame means deliver-then-log, a `read-output`
+ * frame means capture-then-reply, a `detached` frame means stop
+ * reconnecting" — is unit-testable without a live stream or a real
+ * daemon loop.
+ */
+export function actionForFrame(frame) {
+    const data = (frame.data ?? {});
+    switch (frame.event) {
+        case 'connected':
+            return {
+                kind: 'connected',
+                attachmentId: String(data.attachmentId ?? ''),
+                workspaceId: String(data.workspaceId ?? ''),
+            };
+        case 'ping':
+            return { kind: 'ping' };
+        case 'prompt':
+            return { kind: 'prompt', attachmentId: String(data.attachmentId ?? ''), prompt: String(data.prompt ?? '') };
+        case 'read-output':
+            return {
+                kind: 'read-output',
+                attachmentId: String(data.attachmentId ?? ''),
+                requestId: String(data.requestId ?? ''),
+            };
+        case 'detached':
+            return { kind: 'detached', attachmentId: String(data.attachmentId ?? '') };
+        default:
+            return { kind: 'unknown', event: frame.event };
+    }
+}