@parall/daemon 1.34.0 → 1.36.0

package/dist/clip-runtime/browser-state-store.js

@@ -0,0 +1,370 @@
+/**
+ * browser-state-store.ts — S3 externalization of a hosted browser profile's
+ * bb-browser state (design hosted-browser-multitenant §3.2, PR4).
+ *
+ * A hosted browser pod is ephemeral: its Chromium user-data dir (BB_BROWSER_HOME /
+ * `homeDir`, where cookies / localStorage / IndexedDB persist) lives on a pod
+ * `emptyDir` that vanishes on restart. To make the profile durable across pod
+ * restarts we snapshot that dir to S3, so a pod HYDRATES on start and CHECKPOINTS
+ * periodically + on drain. Layout (SSOT shared with the Go controller's
+ * state_store.go): `s3://{bucket}/browser-state/{org_id}/{profile_id}/state.tgz`.
+ *
+ * Correctness under pod churn (the hard part):
+ *   - Integrity: each object carries a sha256 + the generation in metadata. Hydrate
+ *     verifies the checksum; a mismatch is treated as "no state" (start fresh),
+ *     never a crash.
+ *   - Fencing (anti-clobber): a stale/fenced pod (older activation generation) must
+ *     NOT overwrite a newer pod's state. checkpoint() reads the current object's
+ *     generation; if it is newer than ours we abort. The write is additionally a
+ *     conditional PUT (IfMatch on the read ETag / IfNoneMatch on create) so a CAS
+ *     race fails closed (412 → abort).
+ *
+ * Graceful degradation: with no bucket configured (feature not provisioned) the
+ * store is DISABLED — hydrate/checkpoint are no-ops and the pod runs stateless.
+ * Read/credential failures never crash the pod; they degrade to "fresh start" on
+ * hydrate and "checkpoint failed" (logged) on write. Durability is best-effort +
+ * on-close (design §3.2 "simplified durability"): a failed checkpoint is bounded
+ * loss (the delta since the last successful checkpoint), logged at the pod — there
+ * is no controller-side final-checkpoint verify or auto-repair.
+ *
+ * This module is imported ONLY by the browser-pod entrypoint, so @aws-sdk/client-s3
+ * lands only in the parall-browser-pod bundle, never the BYOC daemon bundle.
+ */
+import { spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { mkdirSync } from 'node:fs';
+import { gunzipSync, gzipSync } from 'node:zlib';
+import { GetObjectCommand, HeadObjectCommand, PutObjectCommand, S3Client, } from '@aws-sdk/client-s3';
+/** S3 object user-metadata keys. Lowercase; the Go controller reads them
+ *  case-insensitively (state_store.go metaValue). SSOT — keep in lockstep. */
+const META_GENERATION = 'generation';
+const META_SHA256 = 'sha256';
+const META_FINAL = 'final';
+const STATE_KEY_PREFIX = 'browser-state';
+const STATE_OBJECT = 'state.tgz';
+/**
+ * Chromium user-data cruft excluded from the snapshot: singleton locks (must never
+ * be restored — Chrome recreates them, and a stale lock blocks startup) and
+ * regenerable caches (large, never login state). Login state — Cookies, Local
+ * Storage, IndexedDB, Local State, Login Data — is deliberately NOT excluded.
+ */
+const ARCHIVE_EXCLUDES = [
+    'SingletonLock',
+    'SingletonCookie',
+    'SingletonSocket',
+    'lockfile',
+    '*/Cache/*',
+    '*/Code Cache/*',
+    '*/GPUCache/*',
+    '*/ShaderCache/*',
+    '*/GrShaderCache/*',
+    '*/DawnCache/*',
+    '*/component_crx_cache/*',
+    '*/Crashpad/*',
+];
+/** buildStateKey is the SSOT key layout, mirrored by the Go controller. */
+export function buildStateKey(orgId, profileId) {
+    return `${STATE_KEY_PREFIX}/${orgId}/${profileId}/${STATE_OBJECT}`;
+}
+/** Thrown by a StateBackend.put when a conditional write precondition fails (S3
+ *  412). The store treats it as "lost the CAS race" and aborts the checkpoint. */
+export class PreconditionFailedError extends Error {
+    constructor(message = 'precondition failed') {
+        super(message);
+        this.name = 'PreconditionFailedError';
+    }
+}
+/**
+ * BrowserStateStore orchestrates hydrate/checkpoint over a StateBackend. All
+ * checkpoints (periodic + final) are serialized through a single promise chain so
+ * a drain's final checkpoint can never race an in-flight periodic one.
+ */
+export class BrowserStateStore {
+    cfg;
+    backend;
+    key;
+    chain = Promise.resolve();
+    lastUploadedSha = null;
+    constructor(cfg, backend) {
+        this.cfg = cfg;
+        this.key = buildStateKey(cfg.orgId, cfg.profileId);
+        // Injected backend wins (tests). Otherwise build a live S3 backend iff a
+        // bucket is configured; no bucket → disabled (stateless pod).
+        this.backend = backend ?? (cfg.bucket ? new S3Backend(buildS3Client(cfg), cfg.bucket) : null);
+    }
+    enabled() {
+        return this.backend !== null;
+    }
+    /**
+     * Download + verify + extract the profile's snapshot into homeDir. MUST run
+     * before bb-browser can launch (the pod calls it at startup, before the provider
+     * stream opens). Never throws: any failure (no object, checksum mismatch,
+     * network/cred error) degrades to a fresh start, since a read failure should not
+     * keep the browser from coming up.
+     */
+    async hydrate() {
+        if (!this.backend) {
+            this.cfg.log.info('browser-state: disabled (no bucket) — fresh start, stateless');
+            return { hydrated: false, disabled: true };
+        }
+        try {
+            const head = await this.backend.head(this.key);
+            if (!head) {
+                this.cfg.log.info(`browser-state: no prior snapshot at ${this.key} — fresh start`);
+                return { hydrated: false };
+            }
+            const buf = await this.backend.get(this.key);
+            const expected = head.metadata[META_SHA256];
+            const actual = sha256(buf);
+            if (!expected) {
+                // The object format REQUIRES a sha256 in metadata. A snapshot without it is
+                // unverifiable (corrupt / non-canonical / partial write) — do NOT extract
+                // unchecked content into homeDir. Treat as not-hydratable (fresh start) and,
+                // like a mismatch, do not overwrite the existing object (see
+                // shouldCheckpointAfterHydrate).
+                this.cfg.log.warn(`browser-state: snapshot at ${this.key} is missing the ${META_SHA256} metadata — cannot verify, ignoring snapshot, fresh start`);
+                return { hydrated: false, checksumMismatch: true };
+            }
+            if (expected !== actual) {
+                this.cfg.log.warn(`browser-state: checksum mismatch (expected ${expected.slice(0, 12)}…, got ${actual.slice(0, 12)}…) — ignoring snapshot, fresh start`);
+                return { hydrated: false, checksumMismatch: true };
+            }
+            mkdirSync(this.cfg.homeDir, { recursive: true });
+            await extractArchive(buf, this.cfg.homeDir);
+            this.lastUploadedSha = actual;
+            this.cfg.log.info(`browser-state: hydrated ${buf.length} bytes from ${this.key} (gen=${head.metadata[META_GENERATION] ?? '?'})`);
+            return { hydrated: true };
+        }
+        catch (err) {
+            this.cfg.log.warn(`browser-state: hydrate failed, fresh start: ${errMsg(err)}`);
+            return { hydrated: false, error: err };
+        }
+    }
+    /**
+     * Snapshot homeDir to S3. `final` marks the drain (on-close) checkpoint — the
+     * last best-effort flush before the pod exits. Serialized via the chain so
+     * periodic and final checkpoints never overlap. Never throws — returns a result
+     * the caller logs; a failure is bounded loss, not enforced (simplified durability:
+     * no controller-side verify or auto-repair).
+     */
+    checkpoint(opts) {
+        const run = this.chain.then(() => this.doCheckpoint(opts));
+        // Keep the chain alive regardless of this checkpoint's outcome.
+        this.chain = run.then(() => undefined, () => undefined);
+        return run;
+    }
+    async doCheckpoint({ final }) {
+        if (!this.backend)
+            return { ok: false, disabled: true };
+        try {
+            // Fencing read: if S3 already holds a NEWER generation, we are a stale/fenced
+            // pod and must not clobber it.
+            const head = await this.backend.head(this.key);
+            if (head) {
+                const currentGen = Number.parseInt(head.metadata[META_GENERATION] ?? '', 10);
+                if (Number.isFinite(currentGen) && currentGen > this.cfg.generation) {
+                    this.cfg.log.warn(`browser-state: FENCED — S3 generation ${currentGen} > ours ${this.cfg.generation}; aborting checkpoint (this pod is superseded)`);
+                    return { ok: false, fenced: true };
+                }
+            }
+            const body = await archiveDir(this.cfg.homeDir);
+            const sha = sha256(body);
+            // Skip a redundant PERIODIC upload when nothing changed; a FINAL (drain)
+            // checkpoint always writes — the on-close flush is unconditional so the last
+            // state is guaranteed committed before the pod exits, even if the bytes match
+            // the last periodic upload. (The `final` metadata marker is informational only:
+            // under simplified durability nothing reads it back — there is no controller-
+            // side release-time guard.)
+            if (!final && this.lastUploadedSha !== null && this.lastUploadedSha === sha) {
+                return { ok: true, unchanged: true };
+            }
+            const metadata = {
+                [META_GENERATION]: String(this.cfg.generation),
+                [META_SHA256]: sha,
+                [META_FINAL]: String(final),
+            };
+            try {
+                await this.backend.put(this.key, body, head ? { metadata, ifMatch: head.etag } : { metadata, ifNoneMatch: '*' });
+            }
+            catch (err) {
+                if (err instanceof PreconditionFailedError || isPreconditionFailed(err)) {
+                    this.cfg.log.warn('browser-state: checkpoint lost the conditional-write race (precondition failed); aborting — another pod holds the object');
+                    return { ok: false, raced: true };
+                }
+                throw err;
+            }
+            this.lastUploadedSha = sha;
+            this.cfg.log.info(`browser-state: checkpoint ok (gen=${this.cfg.generation} final=${final} bytes=${body.length})`);
+            return { ok: true };
+        }
+        catch (err) {
+            this.cfg.log.error(`browser-state: checkpoint failed: ${errMsg(err)}`);
+            return { ok: false, error: err };
+        }
+    }
+}
+/** S3Backend is the live StateBackend over @aws-sdk/client-s3. */
+class S3Backend {
+    client;
+    bucket;
+    constructor(client, bucket) {
+        this.client = client;
+        this.bucket = bucket;
+    }
+    async head(key) {
+        try {
+            const r = await this.client.send(new HeadObjectCommand({ Bucket: this.bucket, Key: key }));
+            return { etag: r.ETag ?? '', metadata: lowerKeys(r.Metadata ?? {}) };
+        }
+        catch (err) {
+            // A profile-scoped pod has no s3:ListBucket, so S3 answers a missing object
+            // with 403 rather than 404. Treat both as "no object" — see isAccessDenied.
+            if (isNotFound(err) || isAccessDenied(err))
+                return null;
+            throw err;
+        }
+    }
+    async get(key) {
+        const r = await this.client.send(new GetObjectCommand({ Bucket: this.bucket, Key: key }));
+        const body = r.Body;
+        if (!body?.transformToByteArray) {
+            throw new Error('S3 GetObject returned no readable body');
+        }
+        return Buffer.from(await body.transformToByteArray());
+    }
+    async put(key, body, opts) {
+        try {
+            await this.client.send(new PutObjectCommand({
+                Bucket: this.bucket,
+                Key: key,
+                Body: body,
+                Metadata: opts.metadata,
+                ContentType: 'application/gzip',
+                // Server-side encryption (design §3.2). SSE-S3 (AES256) is universally
+                // available on AWS; bucket default encryption makes this explicit, not
+                // conflicting.
+                ServerSideEncryption: 'AES256',
+                ...(opts.ifMatch ? { IfMatch: opts.ifMatch } : {}),
+                ...(opts.ifNoneMatch ? { IfNoneMatch: opts.ifNoneMatch } : {}),
+            }));
+        }
+        catch (err) {
+            if (isPreconditionFailed(err))
+                throw new PreconditionFailedError(errMsg(err));
+            throw err;
+        }
+    }
+}
+function buildS3Client(cfg) {
+    // Credentials come from the default provider chain — the controller injects
+    // short-lived, profile-scoped STS creds as AWS_* env. forcePathStyle is needed
+    // for MinIO/dev endpoints.
+    return new S3Client({
+        region: cfg.region || undefined,
+        ...(cfg.endpoint ? { endpoint: cfg.endpoint, forcePathStyle: true } : {}),
+    });
+}
+/** sha256 hex of a buffer — the snapshot integrity checksum. */
+export function sha256(buf) {
+    return createHash('sha256').update(buf).digest('hex');
+}
+/**
+ * archiveDir tars a directory (excluding lock/cache cruft) then gzips it in-memory.
+ * Uses the system `tar` (present in the browser-docker image and on dev machines —
+ * no extra npm dep) for the tar, and node:zlib for gzip. Gzip is done by zlib (not
+ * `tar -z`) deliberately: zlib's gzip header has a zeroed mtime, so identical
+ * directory content produces byte-identical archives — which lets a periodic
+ * checkpoint skip a redundant upload when nothing changed. Buffering in memory is
+ * fine for browser state (cookies/localStorage/IndexedDB are small); streaming
+ * multipart upload is a fast-follow if profiles grow large.
+ */
+export async function archiveDir(dir) {
+    const args = ['-cf', '-', '-C', dir];
+    for (const ex of ARCHIVE_EXCLUDES)
+        args.push(`--exclude=${ex}`);
+    args.push('.');
+    const tar = await runTar(args, undefined);
+    return gzipSync(tar);
+}
+/** extractArchive ungzips then untars a buffer into destDir (created if missing). */
+export async function extractArchive(buf, destDir) {
+    mkdirSync(destDir, { recursive: true });
+    await runTar(['-xf', '-', '-C', destDir], gunzipSync(buf));
+}
+/**
+ * runTar spawns the system tar, optionally feeding stdin, and resolves stdout as a
+ * Buffer. Rejects on spawn error or non-zero exit (with captured stderr) so a
+ * partial/failed archive can never be silently uploaded or extracted.
+ */
+function runTar(args, stdin) {
+    return new Promise((resolve, reject) => {
+        const child = spawn('tar', args, { stdio: ['pipe', 'pipe', 'pipe'] });
+        const out = [];
+        const errOut = [];
+        let settled = false;
+        const fail = (err) => {
+            if (settled)
+                return;
+            settled = true;
+            reject(err);
+        };
+        child.once('error', fail); // ENOENT (no tar) etc.
+        child.stdout.on('data', (c) => out.push(c));
+        child.stderr.on('data', (c) => errOut.push(c));
+        child.once('close', (code) => {
+            if (settled)
+                return;
+            settled = true;
+            if (code === 0) {
+                resolve(Buffer.concat(out));
+            }
+            else {
+                reject(new Error(`tar exited ${code}: ${Buffer.concat(errOut).toString('utf8').trim()}`));
+            }
+        });
+        if (stdin !== undefined) {
+            child.stdin.on('error', fail); // EPIPE if tar dies early
+            child.stdin.end(stdin);
+        }
+        else {
+            child.stdin.end();
+        }
+    });
+}
+/** Lowercase metadata keys so lookups are case-insensitive regardless of how the
+ *  SDK/backend canonicalizes them. */
+function lowerKeys(m) {
+    const out = {};
+    for (const [k, v] of Object.entries(m))
+        out[k.toLowerCase()] = v;
+    return out;
+}
+/** A 404 from HeadObject/GetObject — the object does not exist. */
+function isNotFound(err) {
+    const e = err;
+    return e?.name === 'NotFound' || e?.name === 'NoSuchKey' || e?.$metadata?.httpStatusCode === 404;
+}
+/**
+ * A 403 from HeadObject. A profile-scoped pod deliberately lacks s3:ListBucket (the
+ * per-profile tenant-isolation boundary), and S3 answers a MISSING object with 403
+ * (not 404) when the caller can't list the bucket — it won't reveal existence. The
+ * pod still holds s3:GetObject on its own prefix, so an existing object HEADs as 200;
+ * a 403 there therefore means "no object", not a real denial. Treating it as
+ * not-found lets a brand-new profile hydrate fresh AND still checkpoint. This can
+ * never overwrite good state: an existing object never 403s (it 200s), and a
+ * genuinely bad/expired credential 403s the subsequent PutObject too, so the
+ * checkpoint fails — bounded loss, logged at the pod (simplified durability: no
+ * controller-side verify or auto-repair).
+ */
+export function isAccessDenied(err) {
+    const e = err;
+    return e?.name === 'AccessDenied' || e?.$metadata?.httpStatusCode === 403;
+}
+/** A 412 from a conditional write — the IfMatch/IfNoneMatch precondition failed. */
+function isPreconditionFailed(err) {
+    const e = err;
+    return e?.name === 'PreconditionFailed' || e?.$metadata?.httpStatusCode === 412;
+}
+function errMsg(err) {
+    return err instanceof Error ? (err.stack ?? err.message) : String(err);
+}

package/dist/clip-runtime/browser-viewer-streamer.d.ts

@@ -0,0 +1,222 @@
+/** Optional managed TURN relay config carried on a `stream.start` command. */
+export interface ViewerTurnConfig {
+    url: string;
+    username?: string;
+    credential?: string;
+}
+/**
+ * The slice of BrowserProfileManager the viewer streamer depends on: the
+ * account-scoped bb-browser /command path and the daemon lifecycle helpers.
+ * One-directional — the manager constructs the streamer; the streamer never
+ * imports the manager.
+ */
+export interface ViewerStreamerHost {
+    log: {
+        info(msg: string): void;
+        warn(msg: string): void;
+        error(msg: string): void;
+    };
+    /** Account-scoped bb-browser `/command` (BrowserProfileManager.sendCommand). */
+    sendBrowserCommand(request: Record<string, unknown> & {
+        method: string;
+        account?: string;
+    }): Promise<Record<string, unknown>>;
+    ensureAccount(account: string): Promise<boolean>;
+    withDaemonRecovery<T>(operation: () => Promise<T>, label: string): Promise<T>;
+    /** cdpHost/cdpPort from the bb-browser daemon `GET /status`. */
+    cdpEndpoint(): Promise<{
+        host: string;
+        port: number;
+    }>;
+}
+/**
+ * bb-viewer's /command control plane is UNAUTHENTICATED, so on the shared agents
+ * cluster its bind host MUST be loopback — a 0.0.0.0 / pod-IP / typo'd value would
+ * silently re-open it cross-tenant. Only these exact loopback forms are accepted;
+ * anything else is rejected (fail fast) at spawn.
+ */
+export declare function isLoopbackBindHost(host: string): boolean;
+/**
+ * Whether a kick targets the CURRENT live streamer (so its process is torn down). A
+ * kick with no explicit target hits whoever is live; an explicit target tears down the
+ * current streamer ONLY when it matches — a stale/replayed session_id must not kill a
+ * newer live viewer (it is only recorded for straggler rejection). currentSessionId
+ * undefined (no live streamer) → never a current-kill.
+ */
+export declare function kickHitsCurrentSession(requested: string | undefined, currentSessionId: string | undefined): boolean;
+export declare class BrowserViewerStreamer {
+    private readonly host;
+    private readonly streamers;
+    private readonly kickedSessions;
+    private stopping;
+    constructor(host: ViewerStreamerHost);
+    /**
+     * 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.
+     */
+    handleViewerCommand(profileId: string, sessionId: string, command: string, input?: Record<string, unknown>, turn?: ViewerTurnConfig): Promise<Record<string, unknown>>;
+    /**
+     * kick — server-side per-viewer disconnect (design §3.6 PR7). Terminates ONE
+     * viewer's WebRTC session: stop its bb-viewer streamer (killing the process
+     * tears down the peer connection + datachannel) and reject the kicked session's
+     * subsequent commands — while bb-browser + Chromium (the agent's live browser)
+     * keep running. This is explicitly DISTINCT from stopping the pod / profile,
+     * which would kill the agent's browser too; a viewer session is a sub-session of
+     * the profile lease, so a kick does NOT release the lease.
+     *
+     * Targets `input.session_id` if given, else the current streamer's session.
+     * Idempotent: kicking with no live streamer still records the kicked session.
+     */
+    private viewerKick;
+    /**
+     * 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.
+     */
+    private viewerStreamStart;
+    /**
+     * 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).
+     */
+    private viewerStreamAnswer;
+    /**
+     * 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.
+     */
+    private viewerStreamClose;
+    /**
+     * 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.
+     */
+    private viewerStreamSwitch;
+    /**
+     * 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.
+     */
+    private viewerCloseTab;
+    /**
+     * 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.
+     */
+    private bringTargetToFront;
+    /**
+     * 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.
+     */
+    private viewerForwardNav;
+    /**
+     * 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).
+     */
+    private resolveAccountPageCdpUrl;
+    /**
+     * 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).
+     */
+    private accountActivePageTargetId;
+    /**
+     * 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).
+     */
+    private firstAccountPageTargetId;
+    /**
+     * 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.
+     */
+    private accountTabTargetId;
+    /** `tab_list {account}` rows, typed to the fields we read (tabId/tab/account/active). */
+    private accountTabs;
+    /**
+     * 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.
+     */
+    private spawnStreamer;
+    /**
+     * 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.
+     */
+    private killChild;
+    /**
+     * 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.
+     */
+    private streamerCommand;
+    /**
+     * Kill + remove the profile's bb-viewer streamer, if any. Idempotent. Also
+     * clears any kick marker for the profile: a (re)kill establishes a clean
+     * streamer slot, so a subsequent stream.start starts un-kicked. viewerKick
+     * re-records the kicked session AFTER calling this.
+     */
+    killProfileStreamer(profileId: string): void;
+    /**
+     * Tear down every profile streamer and refuse new spawns (daemon stop).
+     * Idempotent.
+     */
+    shutdown(): void;
+}
+//# sourceMappingURL=browser-viewer-streamer.d.ts.map

package/dist/clip-runtime/browser-viewer-streamer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-viewer-streamer.d.ts","sourceRoot":"","sources":["../../src/clip-runtime/browser-viewer-streamer.ts"],"names":[],"mappings":"AAsCA,8EAA8E;AAC9E,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAcD;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE;QAAE,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;IACpF,gFAAgF;IAChF,kBAAkB,CAChB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GACtE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACpC,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACjD,kBAAkB,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAC9E,gEAAgE;IAChE,WAAW,IAAI,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACxD;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAExD;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,gBAAgB,EAAE,MAAM,GAAG,SAAS,GACnC,OAAO,CAGT;AAED,qBAAa,qBAAqB;IAiBpB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAbjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAoC;IAO9D,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA6B;IAI5D,OAAO,CAAC,QAAQ,CAAS;gBAEI,IAAI,EAAE,kBAAkB;IAErD;;;;;OAKG;IACG,mBAAmB,CACvB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,IAAI,CAAC,EAAE,gBAAgB,GACtB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAuCnC;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,UAAU;IAwBlB;;;;OAIG;YACW,iBAAiB;IA+C/B;;;;OAIG;YACW,kBAAkB;IAgBhC;;;;;;;;;;OAUG;YACW,iBAAiB;IAuB/B;;;;;;;;OAQG;YACW,kBAAkB;IAuBhC;;;;;;OAMG;YACW,cAAc;IAiC5B;;;;;;;OAOG;YACW,kBAAkB;IAqBhC;;;;;;;;;;;;;;;;;;;;OAoBG;YACW,gBAAgB;IA6C9B;;;;;;;;;;;;;;;;;;OAkBG;YACW,wBAAwB;IAetC;;;;;OAKG;YACW,yBAAyB;IAevC;;;;;OAKG;YACW,wBAAwB;IAatC;;;OAGG;YACW,kBAAkB;IAehC,yFAAyF;YAC3E,WAAW;IAgBzB;;;;;OAKG;YACW,aAAa;IAiH3B;;;;;;;OAOG;IACH,OAAO,CAAC,SAAS;IAqBjB;;;;OAIG;YACW,eAAe;IA+B7B;;;;;OAKG;IACH,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAQ5C;;;OAGG;IACH,QAAQ,IAAI,IAAI;CAMjB"}