@parall/daemon 1.34.0 → 1.35.0

package/dist/clip-runtime/browser-viewer-streamer.js

@@ -0,0 +1,595 @@
+import { spawn } from 'node:child_process';
+import { findFreePort, formatErrorForLog, sleep } from './subprocess.js';
+const BB_VIEWER_HEALTH_TIMEOUT_MS = 10_000;
+const BB_VIEWER_COMMAND_TIMEOUT_MS = 15_000;
+// A streamer whose session never received a stream.answer is abandoned: the
+// client vanished mid-handshake (hard tab close before its session id arrived)
+// and can never send a scoped stream.close. Reap it so the bb-viewer process +
+// CDP screencast don't park until the next stream.start. The handshake
+// (answer follows start by seconds once the client has the offer) finishes
+// far inside this window even on a cold pod.
+const BB_VIEWER_UNANSWERED_REAP_MS = 90_000;
+// Grace between SIGTERM and the SIGKILL escalation in killChild.
+const BB_VIEWER_TERM_GRACE_MS = 5_000;
+export class BrowserViewerStreamer {
+    host;
+    // Live bb-viewer (WebRTC streamer) subprocess per profile. One per profile;
+    // see StreamerState. Cleaned up on stream.close, stopProfile, resetProfile,
+    // and stop().
+    streamers = new Map();
+    // Set by shutdown(): an in-flight spawnStreamer has no map entry yet, so a
+    // shutdown during its health poll would otherwise let the bb-viewer child
+    // survive daemon stop (on BYOC nothing else reaps it).
+    stopping = false;
+    constructor(host) {
+        this.host = host;
+    }
+    /**
+     * Handle a viewer control command for a profile. Throws on any failure (the
+     * supervisor maps a throw to a `{error:{message}}` reply); never returns a
+     * partial result. `data.input` / `data.turn` / `data.session_id` come from
+     * MachineBrowserProfileViewerData.
+     */
+    async handleViewerCommand(profileId, sessionId, command, input, turn) {
+        if (!profileId)
+            throw new Error('browser profile id is required');
+        switch (command) {
+            case 'stream.start':
+                return this.viewerStreamStart(profileId, sessionId, turn);
+            case 'stream.answer':
+                return this.viewerStreamAnswer(profileId, sessionId, input);
+            case 'stream.close':
+                return this.viewerStreamClose(profileId, sessionId, input);
+            case 'stream.switch':
+                return this.viewerStreamSwitch(profileId, sessionId, input);
+            case 'close':
+                return this.viewerCloseTab(profileId, sessionId, input);
+            case 'tab_list':
+            case 'tab_new':
+            case 'open':
+            case 'reload':
+            case 'back':
+            case 'forward':
+                return this.viewerForwardNav(profileId, sessionId, command, input);
+            default:
+                throw new Error(`unknown viewer command: ${command}`);
+        }
+    }
+    /**
+     * stream.start — spawn a FRESH bb-viewer for this profile (killing any prior
+     * one), resolve the profile's account-scoped page-target CDP ws URL, and run
+     * the streamer's `connect` command. Records sessionId on the streamer entry.
+     */
+    async viewerStreamStart(profileId, sessionId, turn) {
+        // Fresh streamer per stream.start: a leftover viewer would still hold the
+        // single-viewer slot inside bb-viewer (connect cleans up its prior viewer,
+        // but we also want a clean process + sessionId per server-side session).
+        this.killProfileStreamer(profileId);
+        // Wrap the bb-browser CDP resolution in the same auto-recovery the agent
+        // invoke path uses: a disconnected Chrome/CDP restarts bb-browser + retries
+        // rather than failing the viewer outright.
+        const cdpUrl = await this.host.withDaemonRecovery(() => this.resolveAccountPageCdpUrl(profileId), `viewer stream.start ${profileId}`);
+        // CDP screencast only emits frames for the tab Chrome is compositing (the
+        // foreground tab of its window). With multiple account tabs the streamed
+        // target is often backgrounded → 0 frames → black viewer. Activate it first.
+        await this.bringTargetToFront(cdpUrl);
+        const streamer = await this.spawnStreamer(profileId, sessionId, turn);
+        try {
+            const result = await this.streamerCommand(streamer, 'connect', { cdpUrl });
+            // Tell the client the EXACT tab being streamed so it targets nav commands
+            // (open/back/forward/reload) at the same tab — no client-side guessing.
+            streamer.streamedTabId = targetIdFromCdpUrl(cdpUrl);
+            // Reap an abandoned (never-answered) streamer — identity-checked so a
+            // kill/respawn in the meantime is never affected. unref: the timer must
+            // not hold the daemon process open.
+            const reapTimer = setTimeout(() => {
+                const current = this.streamers.get(profileId);
+                if (current === streamer && !current.answered) {
+                    this.host.log.warn(`[bb-viewer] no stream.answer for ${profileId} within ${BB_VIEWER_UNANSWERED_REAP_MS / 1000}s; reaping abandoned streamer`);
+                    this.killProfileStreamer(profileId);
+                }
+            }, BB_VIEWER_UNANSWERED_REAP_MS);
+            reapTimer.unref?.();
+            return { ...result, streamed_tab_id: streamer.streamedTabId };
+        }
+        catch (err) {
+            // connect failed → don't leave a dead/idle streamer parked on the profile.
+            this.killProfileStreamer(profileId);
+            throw err;
+        }
+    }
+    /**
+     * stream.answer — apply the client's WebRTC answer to the profile's streamer.
+     * Rejects if the streamer's sessionId no longer matches (a stale viewer
+     * session from a superseded stream.start).
+     */
+    async viewerStreamAnswer(profileId, sessionId, input) {
+        const streamer = this.streamers.get(profileId);
+        if (!streamer)
+            throw new Error('no active viewer streamer for profile');
+        if (streamer.sessionId !== sessionId)
+            throw new Error('stale viewer session');
+        // Mark BEFORE the (up to 15s) bb-viewer await: an answer accepted near the
+        // reap deadline must not be torn down mid-processing by the timer. A failed
+        // answer leaves the streamer un-reaped, which is fine — the client surfaces
+        // the error and the next stream.start replaces the streamer anyway.
+        streamer.answered = true;
+        return this.streamerCommand(streamer, 'answer', input ?? {});
+    }
+    /**
+     * stream.close — best-effort stop the streamer, then kill + remove it. A
+     * stale session's close (independent HTTP legs can arrive out of order after
+     * a retry) must NOT tear down a successor session's live streamer, so a
+     * mismatched sessionId is ignored. An EMPTY sessionId gets the same stale
+     * treatment — a client closed mid-handshake never received a session id, and
+     * its unscoped close racing the next session's stream.start would kill that
+     * session's live streamer (React StrictMode's dev double-mount exercises
+     * exactly this ordering). The only unscoped close is an explicit
+     * `{force:true}` input, reserved for a server-initiated admin disconnect.
+     */
+    async viewerStreamClose(profileId, sessionId, input) {
+        const streamer = this.streamers.get(profileId);
+        if (streamer) {
+            const force = input?.force === true;
+            if (!force && streamer.sessionId !== sessionId) {
+                return { ok: true, stale: true };
+            }
+            try {
+                await this.streamerCommand(streamer, 'stop', {});
+            }
+            catch (err) {
+                this.host.log.warn(`[bb-viewer] stop command failed for ${profileId} (killing anyway): ${formatErrorForLog(err)}`);
+            }
+            this.killProfileStreamer(profileId);
+        }
+        return { ok: true };
+    }
+    /**
+     * stream.switch — point the existing streamer at a different account-scoped
+     * tab. input {tab} is the bb-browser short tab id / target id. Guarded by
+     * sessionId like stream.answer: a superseded session must not steer the
+     * current streamer, and an EMPTY sessionId is rejected the same way — every
+     * real caller has its session id by the time it can switch (it arrives with
+     * the stream.start response), so a session-less switch is by definition not
+     * the current viewer.
+     */
+    async viewerStreamSwitch(profileId, sessionId, input) {
+        const streamer = this.streamers.get(profileId);
+        if (!streamer)
+            throw new Error('no active viewer streamer for profile');
+        if (!sessionId || streamer.sessionId !== sessionId)
+            throw new Error('stale viewer session');
+        const tab = input?.tab;
+        if (tab === undefined || tab === null || tab === '') {
+            throw new Error('stream.switch requires input.tab');
+        }
+        const cdpUrl = await this.host.withDaemonRecovery(() => this.resolveAccountPageCdpUrl(profileId, tab), `viewer stream.switch ${profileId}`);
+        // Foreground the new tab so Chrome composites it (see viewerStreamStart).
+        await this.bringTargetToFront(cdpUrl);
+        const result = await this.streamerCommand(streamer, 'switch', { cdpUrl });
+        streamer.streamedTabId = targetIdFromCdpUrl(cdpUrl);
+        return { ...result, streamed_tab_id: streamer.streamedTabId };
+    }
+    /**
+     * close — close an account tab via bb-browser, then, if the closed tab was
+     * the one being streamed, re-point the streamer at the profile's next active
+     * tab. Without the re-switch the streamer stays bound to a destroyed CDP
+     * target and the viewer goes black. Returns `streamed_tab_id` when a
+     * re-switch happened so the client can adopt the new active tab.
+     */
+    async viewerCloseTab(profileId, sessionId, input) {
+        // Resolve the client's ref to the canonical full target id BEFORE closing:
+        // streamedTabId stores the full id, so comparing the raw input (possibly a
+        // short `tab` ref) would close the right tab but skip the re-switch and
+        // leave the stream on a destroyed target. A ref-less close pins to the
+        // account's active tab, matching viewerForwardNav's ref-less behavior.
+        const ref = viewerTabRef(input ?? {});
+        const closedTargetId = ref !== undefined
+            ? await this.accountTabTargetId(profileId, ref)
+            : await this.accountActivePageTargetId(profileId);
+        const result = await this.viewerForwardNav(profileId, sessionId, 'close', {
+            ...(input ?? {}),
+            tabId: closedTargetId,
+        });
+        const streamer = this.streamers.get(profileId);
+        if (!streamer || !streamer.streamedTabId || streamer.streamedTabId !== closedTargetId) {
+            return result;
+        }
+        const cdpUrl = await this.host.withDaemonRecovery(() => this.resolveAccountPageCdpUrl(profileId), `viewer close re-switch ${profileId}`);
+        await this.bringTargetToFront(cdpUrl);
+        const sw = await this.streamerCommand(streamer, 'switch', { cdpUrl });
+        streamer.streamedTabId = targetIdFromCdpUrl(cdpUrl);
+        return { ...result, ...sw, streamed_tab_id: streamer.streamedTabId };
+    }
+    /**
+     * Bring a CDP page target to the foreground via Chrome's DevTools HTTP
+     * endpoint (`/json/activate/{targetId}`, same host:port as the CDP ws). Chrome
+     * does not composite backgrounded tabs, so `Page.startScreencast` on a
+     * background tab yields zero frames (black viewer). Best-effort: a failure
+     * must not block the stream. host:port + targetId are parsed from the cdpUrl
+     * (`ws://host:port/devtools/page/<targetId>`) to avoid an extra /status call.
+     */
+    async bringTargetToFront(cdpUrl) {
+        const m = /^ws:\/\/([^/]+)\/devtools\/page\/(.+)$/.exec(cdpUrl);
+        if (!m)
+            return;
+        const [, hostPort, targetId] = m;
+        try {
+            const resp = await fetch(`http://${hostPort}/json/activate/${targetId}`, {
+                method: 'GET',
+                signal: AbortSignal.timeout(5_000),
+            });
+            if (!resp.ok) {
+                this.host.log.warn(`[bb-viewer] activate target ${targetId} returned ${resp.status} (continuing)`);
+            }
+        }
+        catch (err) {
+            this.host.log.warn(`[bb-viewer] activate target ${targetId} failed (continuing): ${formatErrorForLog(err)}`);
+        }
+    }
+    /**
+     * Forward a navigation command (tab_list/tab_new/open/reload/back/forward/
+     * close) to bb-browser scoped to the profile's account. This lets the human
+     * in the live viewer navigate and handle OAuth popups directly. Reuses the
+     * same account-scoped sendCommand path the agent invokes use.
+     *
+     * SECURITY — the `account` field alone does NOT scope tab addressing:
+     * bb-browser's ensurePageTarget resolves a client-supplied tab/tabId against
+     * EVERY page target in the shared Chrome (all accounts), and tab_list
+     * returns every tab with `account` as a mere annotation (verified in
+     * @pinixai/bb-browser-pro@0.15.0 dist/daemon.js ensurePageTarget/tab_list).
+     * On a multi-profile host that would let one profile's viewer list,
+     * navigate, and close other profiles' logged-in tabs. So before forwarding:
+     * (a) any tab ref must resolve through accountTabTargetId, which throws on
+     * tabs the profile's account does not own; (b) ref-less tab-addressed
+     * commands are pinned to the profile's own active tab instead of
+     * bb-browser's account-blind global current tab; (c) tab_list output is
+     * filtered to the profile's own rows; and (d) open/tab_new URLs must be
+     * http(s)/about:blank — file:// or chrome:// would read the host
+     * filesystem / browser internals straight into the video stream.
+     */
+    async viewerForwardNav(profileId, sessionId, command, input) {
+        // Takeover isolation: when a live streamer exists, mutating nav/tab
+        // commands must come from ITS session — a superseded viewer tab (older or
+        // missing session id) must not keep steering the profile after a newer
+        // stream.start took over. Read-only tab_list stays unscoped. With no live
+        // streamer there is no takeover to protect (server-side profile authz
+        // already gates the caller).
+        if (command !== 'tab_list') {
+            const streamer = this.streamers.get(profileId);
+            if (streamer && streamer.sessionId !== sessionId) {
+                throw new Error('stale viewer session');
+            }
+        }
+        return this.host.withDaemonRecovery(async () => {
+            await this.host.ensureAccount(profileId);
+            const request = { ...(input ?? {}) };
+            if (command === 'open' || command === 'tab_new') {
+                assertViewerNavigableUrl(request.url);
+            }
+            const ref = viewerTabRef(request);
+            if (ref !== undefined) {
+                request.tabId = await this.accountTabTargetId(profileId, ref);
+                delete request.tab;
+            }
+            else if (REFLESS_PIN_NAV.has(command)) {
+                // `open` without a ref creates a tab inside the account context
+                // (bb-browser createTabInContext) — safe without pinning.
+                request.tabId = await this.accountActivePageTargetId(profileId);
+            }
+            const result = await this.host.sendBrowserCommand({
+                ...request,
+                method: command,
+                account: profileId,
+            });
+            return command === 'tab_list' ? filterTabListToAccount(result, profileId) : result;
+        }, `viewer ${command} ${profileId}`);
+    }
+    /**
+     * Resolve `ws://<cdpHost>:<cdpPort>/devtools/page/<targetId>` for a PAGE
+     * target owned by THIS profile's account — NOT bb-browser's global current
+     * tab (which `getCurrentTabCdpUrl`/`getTabCdpUrl` in the bundled daemon use
+     * via `cdp.currentTargetId`, an account-blind global; see daemon.js
+     * line ~10389/10410). When `tabRef` is given (stream.switch) we resolve that
+     * specific account tab; otherwise the profile's active page tab.
+     *
+     * Evidence from the installed @pinixai/bb-browser-pro@0.15.0 dist/daemon.js:
+     *  - GET /status (handleStatus, line ~1659-1668) returns `cdpHost` + `cdpPort`
+     *    — the CDP host/port the daemon's Chrome listens on.
+     *  - The CDP page ws URL format is `ws://<cdp.host>:<cdp.port>/devtools/page/<page.id>`
+     *    (getCurrentTabCdpUrl, line ~10392), where `page.id` is the full CDP
+     *    targetId (getTargets maps `t.targetId` → `.id`, line ~2461-2466).
+     *  - tab_list (command handler, line ~1041-1059) returns per-tab
+     *    `{ tabId: t.id, tab: <shortId>, account: <accountName>, url, ... }`, so
+     *    `tabId` is exactly the full targetId for the devtools URL and `account`
+     *    is the per-tab attribution we filter on (reused by findAccountTabOnHost).
+     */
+    async resolveAccountPageCdpUrl(profileId, tabRef) {
+        await this.host.ensureAccount(profileId);
+        const { host, port } = await this.host.cdpEndpoint();
+        const targetId = tabRef !== undefined
+            ? await this.accountTabTargetId(profileId, tabRef)
+            : await this.accountActivePageTargetId(profileId);
+        return `ws://${host}:${port}/devtools/page/${targetId}`;
+    }
+    /**
+     * Full CDP targetId of the profile account's active page tab (the owned tab
+     * Chrome marks active, else the first owned tab). If the account owns no
+     * page tab yet, open `about:blank` for it first (mirrors the agent-invoke
+     * path's "always give a fresh account an owned tab" rule).
+     */
+    async accountActivePageTargetId(profileId) {
+        let targetId = await this.firstAccountPageTargetId(profileId);
+        if (targetId !== undefined)
+            return targetId;
+        await this.host.sendBrowserCommand({
+            method: 'tab_new',
+            account: profileId,
+            url: 'about:blank',
+        });
+        targetId = await this.firstAccountPageTargetId(profileId);
+        if (targetId === undefined) {
+            throw new Error(`no page tab found for profile account ${profileId}`);
+        }
+        return targetId;
+    }
+    /**
+     * Full CDP targetId (`tabId`) of the account's active page tab: the owned tab
+     * Chrome marks `active` when it belongs to this account, else the first owned
+     * tab (the global active flag is account-blind — another profile's tab may
+     * hold it, which must not leak here).
+     */
+    async firstAccountPageTargetId(profileId) {
+        const tabs = await this.accountTabs(profileId);
+        let firstOwned;
+        for (const t of tabs) {
+            if (t.account !== profileId)
+                continue;
+            const tabId = t.tabId;
+            if (typeof tabId !== 'string' || !tabId)
+                continue;
+            if (t.active === true)
+                return tabId;
+            firstOwned ??= tabId;
+        }
+        return firstOwned;
+    }
+    /**
+     * Full CDP targetId for a specific account tab, addressed by the bb-browser
+     * short tab id (`tab`) or full target id (`tabId`). Used by stream.switch.
+     */
+    async accountTabTargetId(profileId, tabRef) {
+        const ref = String(tabRef);
+        const tabs = await this.accountTabs(profileId);
+        for (const t of tabs) {
+            if (t.account !== profileId)
+                continue;
+            const tabId = typeof t.tabId === 'string' ? t.tabId : undefined;
+            const shortTab = t.tab === undefined ? undefined : String(t.tab);
+            if ((tabId && tabId === ref) || (shortTab && shortTab === ref)) {
+                if (!tabId)
+                    break;
+                return tabId;
+            }
+        }
+        throw new Error(`tab ${ref} not found for profile account ${profileId}`);
+    }
+    /** `tab_list {account}` rows, typed to the fields we read (tabId/tab/account/active). */
+    async accountTabs(profileId) {
+        const list = await this.host.sendBrowserCommand({ method: 'tab_list', account: profileId });
+        return Array.isArray(list.tabs)
+            ? list.tabs
+            : [];
+    }
+    // ---- bb-viewer streamer lifecycle ----
+    /**
+     * Spawn a bb-viewer streamer for the profile and wait until healthy. Binary
+     * is PRLL_BB_VIEWER_BIN (our image sets it to /usr/local/bin/bb-viewer),
+     * defaulting to `bb-viewer` on PATH — we NEVER download it. A free port is
+     * allocated per streamer. Stores the entry in `this.streamers` once healthy.
+     */
+    async spawnStreamer(profileId, sessionId, turn) {
+        if (this.stopping)
+            throw new Error('viewer streamer is shutting down');
+        const bin = process.env.PRLL_BB_VIEWER_BIN ?? 'bb-viewer';
+        const port = await findFreePort();
+        const args = ['--api-only', '--port', String(port)];
+        if (turn?.url) {
+            args.push('--turn-url', turn.url, '--turn-user', turn.username ?? '', '--turn-cred', turn.credential ?? '');
+        }
+        // Do NOT inherit the daemon's full env: it carries the machine key
+        // (PRLL_API_KEY = mck_) plus provider/cloud creds that bb-viewer must never
+        // see. bb-viewer only talks to a localhost CDP ws URL + its own HTTP port
+        // (via flags/commands), so a minimal allowlist is sufficient.
+        const streamerEnv = {};
+        for (const key of ['PATH', 'HOME', 'LANG', 'LC_ALL', 'TMPDIR', 'DISPLAY']) {
+            const val = process.env[key];
+            if (val !== undefined)
+                streamerEnv[key] = val;
+        }
+        this.host.log.info(`[bb-viewer] spawning for profile ${profileId} on port ${port}`);
+        const child = spawn(bin, args, { stdio: ['ignore', 'pipe', 'pipe'], env: streamerEnv });
+        // Capture spawn failure (ENOENT/EACCES) so startup fails through the normal
+        // path instead of crashing the daemon on an unhandled 'error' event.
+        let childError = null;
+        child.once('error', (err) => {
+            childError = err;
+        });
+        // A streamer that dies AFTER passing health (bb-viewer crash) must not
+        // leave a stale entry behind — later stream.answer/switch would hammer a
+        // dead port until the next stream.start. Only clear the entry if it still
+        // points at THIS child (killProfileStreamer deletes first, and a respawn
+        // may have replaced it).
+        child.once('exit', () => {
+            const current = this.streamers.get(profileId);
+            if (current?.child === child) {
+                this.streamers.delete(profileId);
+                this.host.log.warn(`[bb-viewer] streamer for ${profileId} exited; cleared stale entry`);
+            }
+        });
+        child.stdout?.on('data', (chunk) => {
+            const text = chunk.toString('utf8').trim();
+            if (text)
+                this.host.log.info(`[bb-viewer] ${text}`);
+        });
+        child.stderr?.on('data', (chunk) => {
+            const text = chunk.toString('utf8').trim();
+            if (text)
+                this.host.log.warn(`[bb-viewer] ${text}`);
+        });
+        const deadline = Date.now() + BB_VIEWER_HEALTH_TIMEOUT_MS;
+        while (Date.now() < deadline) {
+            if (this.stopping) {
+                this.killChild(child, 'streamer for stopping daemon');
+                throw new Error('viewer streamer is shutting down');
+            }
+            if (childError) {
+                throw childError;
+            }
+            if (child.exitCode !== null || child.signalCode !== null) {
+                throw new Error('bb-viewer exited during startup');
+            }
+            try {
+                const resp = await fetch(`http://127.0.0.1:${port}/health`, {
+                    signal: AbortSignal.timeout(2_000),
+                });
+                if (resp.ok) {
+                    const streamer = { child, port, sessionId };
+                    this.streamers.set(profileId, streamer);
+                    this.host.log.info(`[bb-viewer] ready for profile ${profileId} on port ${port}`);
+                    return streamer;
+                }
+            }
+            catch {
+                /* not up yet */
+            }
+            await sleep(200);
+        }
+        this.killChild(child, 'unhealthy streamer');
+        throw new Error('bb-viewer did not become healthy in time');
+    }
+    /**
+     * SIGTERM with a SIGKILL escalation: a bb-viewer that hangs or ignores TERM
+     * would otherwise outlive its teardown holding the port + CDP session (the
+     * shell-level pattern-kill only exists on the hosted pod, not BYOC). The
+     * escalation timer is unref'd so it never holds the daemon open; it is
+     * cleared on exit. Caveat: a daemon process that exits immediately after
+     * shutdown() abandons the timer — acceptable, the TERM was still sent.
+     */
+    killChild(child, label) {
+        if (child.exitCode !== null || child.signalCode !== null)
+            return;
+        try {
+            child.kill('SIGTERM');
+        }
+        catch {
+            return; /* already gone */
+        }
+        const killTimer = setTimeout(() => {
+            if (child.exitCode === null && child.signalCode === null) {
+                this.host.log.warn(`[bb-viewer] ${label} ignored SIGTERM; escalating to SIGKILL`);
+                try {
+                    child.kill('SIGKILL');
+                }
+                catch {
+                    /* already gone */
+                }
+            }
+        }, BB_VIEWER_TERM_GRACE_MS);
+        killTimer.unref?.();
+        child.once('exit', () => clearTimeout(killTimer));
+    }
+    /**
+     * POST a command to the profile's bb-viewer `/command` endpoint. Parses the
+     * `{result}` / `{error:{message}}` envelope (bb-viewer api.go) and returns
+     * the inner result, throwing the error message on failure.
+     */
+    async streamerCommand(streamer, method, params) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), BB_VIEWER_COMMAND_TIMEOUT_MS);
+        try {
+            const resp = await fetch(`http://127.0.0.1:${streamer.port}/command`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ method, params }),
+                signal: controller.signal,
+            });
+            const text = await resp.text();
+            const parsed = (text ? JSON.parse(text) : {});
+            if (parsed.error) {
+                throw new Error(parsed.error.message || `bb-viewer ${method} failed`);
+            }
+            if (!resp.ok) {
+                throw new Error(`bb-viewer ${method} returned ${resp.status}: ${text}`);
+            }
+            return parsed.result ?? {};
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /** Kill + remove the profile's bb-viewer streamer, if any. Idempotent. */
+    killProfileStreamer(profileId) {
+        const streamer = this.streamers.get(profileId);
+        if (!streamer)
+            return;
+        this.streamers.delete(profileId);
+        this.killChild(streamer.child, `streamer for ${profileId}`);
+    }
+    /**
+     * Tear down every profile streamer and refuse new spawns (daemon stop).
+     * Idempotent.
+     */
+    shutdown() {
+        this.stopping = true;
+        for (const profileId of [...this.streamers.keys()]) {
+            this.killProfileStreamer(profileId);
+        }
+    }
+}
+/** Extract the full CDP target id from a `ws://host:port/devtools/page/<id>` URL. */
+function targetIdFromCdpUrl(cdpUrl) {
+    return /\/devtools\/page\/(.+)$/.exec(cdpUrl)?.[1];
+}
+/**
+ * Tab-addressed nav commands that, when called WITHOUT an explicit tab ref,
+ * must be pinned to the profile's own active tab — bb-browser would otherwise
+ * fall back to its account-blind global current tab (another profile's).
+ */
+const REFLESS_PIN_NAV = new Set(['reload', 'back', 'forward', 'close']);
+/** Client-supplied tab reference (full target id preferred, short id fallback). */
+function viewerTabRef(request) {
+    for (const key of ['tabId', 'tab']) {
+        const v = request[key];
+        if ((typeof v === 'string' && v !== '') || typeof v === 'number')
+            return String(v);
+    }
+    return undefined;
+}
+const VIEWER_NAVIGABLE_PROTOCOLS = new Set(['http:', 'https:']);
+/** open/tab_new URL gate: http(s) or about:blank only (see viewerForwardNav). */
+function assertViewerNavigableUrl(raw) {
+    // Presence/emptiness is bb-browser's contract to enforce ("Missing url").
+    if (raw === undefined || raw === null || raw === '')
+        return;
+    if (typeof raw !== 'string')
+        throw new Error('url must be a string');
+    if (raw === 'about:blank')
+        return;
+    let parsed;
+    try {
+        parsed = new URL(raw);
+    }
+    catch {
+        throw new Error(`invalid url: ${raw}`);
+    }
+    if (!VIEWER_NAVIGABLE_PROTOCOLS.has(parsed.protocol)) {
+        throw new Error(`url scheme not allowed in the live viewer: ${parsed.protocol.replace(/:$/, '')}`);
+    }
+}
+/** tab_list rows are account-annotated but unfiltered — keep only the profile's own. */
+function filterTabListToAccount(result, account) {
+    const tabs = Array.isArray(result.tabs) ? result.tabs : [];
+    const owned = tabs.filter((t) => t?.account === account);
+    return { ...result, tabs: owned, activeIndex: owned.findIndex((t) => t?.active === true) };
+}

package/dist/clip-runtime/subprocess.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Child-subprocess plumbing shared by the bb-browser daemon manager
+ * (browser-profile-manager.ts) and the bb-viewer streamer
+ * (browser-viewer-streamer.ts). Moved verbatim out of
+ * browser-profile-manager.ts when the viewer block was split into its own
+ * file.
+ */
+export declare function formatErrorForLog(err: unknown): string;
+export declare function findFreePort(): Promise<number>;
+export declare function sleep(ms: number): Promise<void>;
+//# sourceMappingURL=subprocess.d.ts.map

package/dist/clip-runtime/subprocess.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subprocess.d.ts","sourceRoot":"","sources":["../../src/clip-runtime/subprocess.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AAEH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAGtD;AAED,wBAAsB,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC,CAgBpD;AAED,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/C"}

package/dist/clip-runtime/subprocess.js

@@ -0,0 +1,33 @@
+import * as net from 'node:net';
+/**
+ * Child-subprocess plumbing shared by the bb-browser daemon manager
+ * (browser-profile-manager.ts) and the bb-viewer streamer
+ * (browser-viewer-streamer.ts). Moved verbatim out of
+ * browser-profile-manager.ts when the viewer block was split into its own
+ * file.
+ */
+export function formatErrorForLog(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return message.replace(/\s+/g, ' ').slice(0, 300);
+}
+export async function findFreePort() {
+    return new Promise((resolve, reject) => {
+        const server = net.createServer();
+        server.unref();
+        server.on('error', reject);
+        server.listen(0, '127.0.0.1', () => {
+            const address = server.address();
+            server.close(() => {
+                if (address && typeof address === 'object') {
+                    resolve(address.port);
+                }
+                else {
+                    reject(new Error('failed to allocate free port'));
+                }
+            });
+        });
+    });
+}
+export function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/supervisor.d.ts

@@ -27,7 +27,7 @@ export declare class DaemonSupervisor {
     private readonly children;
     private readonly spawningAgents;
     private readonly pendingWorkspaceSetup;
-    private readonly browserProfileLifecycleQueues;
+    private readonly browserProfileOpQueues;
     private readonly workspaceSetupRetryTimers;
     private readonly cancelledSpawns;
     private ws;
@@ -69,6 +69,15 @@ export declare class DaemonSupervisor {
     private handleFilesystemBrowse;
     private handleBrowserProfileLifecycle;
     private enqueueBrowserProfileLifecycle;
+    private enqueueBrowserProfileOp;
+    /**
+     * Handle one viewer control command and reply via REST. Always answers the
+     * request/reply bridge exactly once ({result} on success, {error:{message}}
+     * on failure) and never throws into the WS event loop — mirrors
+     * handleFilesystemBrowse. Serialized per profile by enqueueBrowserProfileViewer.
+     */
+    private handleBrowserProfileViewer;
+    private enqueueBrowserProfileViewer;
     private handleClipSync;
     private reconcileMachineClips;
     private reconcileMachineClipsNow;