stageflow 0.32.0 → 0.35.0

package/dist/browser/fakeLiveViewRelay.js

@@ -0,0 +1,94 @@
+const REPLAYED = ["status", "tabs", "url", "frame"];
+export function createFakeLiveViewRelay() {
+    const sessions = [];
+    return {
+        sessions,
+        async open(_request) {
+            const subscribers = new Set();
+            const latest = new Map();
+            const input = [];
+            const answers = [];
+            const openDialogs = new Map();
+            const session = {
+                input,
+                answers,
+                closed: false,
+                reopens: 0,
+                reopenResult: { ok: true },
+                emit(message) {
+                    if (message.type === "dialog") {
+                        const dialog = message.data;
+                        openDialogs.set(dialog.id, { dialog, answered: false });
+                    }
+                    else if (message.type === "dialog_closed") {
+                        openDialogs.delete(message.data.id);
+                    }
+                    else if (message.type !== "closed" && message.type !== "retarget") {
+                        latest.set(message.type, message);
+                    }
+                    for (const subscriber of subscribers)
+                        subscriber(message);
+                },
+                subscribe(subscriber) {
+                    for (const type of REPLAYED) {
+                        if (type === "frame") {
+                            for (const { dialog } of openDialogs.values())
+                                subscriber({ type: "dialog", data: dialog });
+                        }
+                        const message = latest.get(type);
+                        if (message !== undefined)
+                            subscriber(message);
+                    }
+                    subscribers.add(subscriber);
+                    return () => {
+                        subscribers.delete(subscriber);
+                    };
+                },
+                async sendInput(events) {
+                    if (session.closed)
+                        return { ok: false, reason: "closed" };
+                    input.push(...events);
+                    return { ok: true, accepted: events.length };
+                },
+                async answerDialog(answer) {
+                    if (session.closed)
+                        return { ok: false, reason: "closed" };
+                    if (typeof answer?.id !== "string" ||
+                        typeof answer.accept !== "boolean" ||
+                        (answer.promptText !== undefined && typeof answer.promptText !== "string")) {
+                        return { ok: false, reason: "invalid" };
+                    }
+                    const open = openDialogs.get(answer.id);
+                    if (open === undefined || open.answered)
+                        return { ok: false, reason: "no_dialog" };
+                    if (!open.dialog.answerable)
+                        return { ok: false, reason: "not_answerable" };
+                    open.answered = true;
+                    answers.push(answer);
+                    return { ok: true };
+                },
+                async reopenTab() {
+                    if (session.closed)
+                        return { ok: false, reason: "closed" };
+                    session.reopens += 1;
+                    return session.reopenResult;
+                },
+                clearFrame() {
+                    latest.delete("frame");
+                },
+                async close() {
+                    if (session.closed)
+                        return;
+                    session.closed = true;
+                    for (const subscriber of subscribers) {
+                        subscriber({ type: "closed", data: { reason: "closed" } });
+                    }
+                    subscribers.clear();
+                    openDialogs.clear();
+                },
+            };
+            sessions.push(session);
+            return session;
+        },
+    };
+}

package/dist/browser/fakeLiveViewSource.d.ts

@@ -0,0 +1,6 @@
+import type { LiveViewSource } from "./liveViewSource.js";
+export declare function createFakeLiveViewSource(options?: {
+    embedOrigin?: string;
+    ttlMs?: number;
+    now?: () => number;
+}): LiveViewSource;

package/dist/browser/fakeLiveViewSource.js

@@ -0,0 +1,16 @@
+export function createFakeLiveViewSource(options = {}) {
+    const embedOrigin = options.embedOrigin ?? "https://viewer.example";
+    const ttlMs = options.ttlMs ?? 60_000;
+    const now = options.now ?? Date.now;
+    let counter = 0;
+    return {
+        async viewerAddress(request) {
+            counter += 1;
+            return {
+                url: `${embedOrigin}/view/${encodeURIComponent(request.sandboxId)}?t=${counter}`,
+                embedOrigin,
+                expiresAt: now() + ttlMs,
+            };
+        },
+    };
+}

package/dist/browser/fakeRemoteBrowserHost.d.ts

@@ -1,2 +1,3 @@
 import { type BrowserHost } from "./browserHost.js";
-export declare function createFakeRemoteBrowserHost(address: string): BrowserHost;
+import type { BrowserHostCapabilityRecord } from "./hostCapabilities.js";
+export declare function createFakeRemoteBrowserHost(address: string, capabilities?: BrowserHostCapabilityRecord): BrowserHost;

package/dist/browser/fakeRemoteBrowserHost.js

@@ -1,6 +1,7 @@
 import { shortHash, } from "./browserHost.js";
-export function createFakeRemoteBrowserHost(address) {
+export function createFakeRemoteBrowserHost(address, capabilities = { attach: "cdp" }) {
     return {
+        capabilities,
         async ensureProfileBrowser(request) {
             return {
                 cdpAddress: address,

package/dist/browser/fakeSandboxOrchestrator.d.ts

@@ -0,0 +1,9 @@
+import type { BrowserSandboxOrchestrator } from "./sandboxOrchestrator.js";
+export type FakeSandboxOrchestrator = BrowserSandboxOrchestrator & {
+    readonly gracefulStops: readonly string[];
+    readonly releases: readonly string[];
+};
+export declare function createFakeSandboxOrchestrator(options?: {
+    adapterId?: string;
+    address?: (n: number) => string;
+}): FakeSandboxOrchestrator;

package/dist/browser/fakeSandboxOrchestrator.js

@@ -0,0 +1,44 @@
+export function createFakeSandboxOrchestrator(options = {}) {
+    const adapterId = options.adapterId ?? "fake";
+    const addressOf = options.address ?? ((n) => `ws://127.0.0.1:${9000 + n}/devtools/browser/fake-${n}`);
+    const sandboxes = new Map();
+    const gracefulStops = [];
+    const releases = [];
+    let counter = 0;
+    return {
+        gracefulStops,
+        releases,
+        async start(request) {
+            counter += 1;
+            const info = {
+                ref: { id: `sbx-${counter}`, adapter: { id: adapterId, version: 1 } },
+                labels: { ...request.labels },
+                status: "running",
+                attachAddress: addressOf(counter),
+            };
+            sandboxes.set(info.ref.id, info);
+            return structuredClone(info);
+        },
+        async stopGracefully(ref) {
+            const info = sandboxes.get(ref.id);
+            if (info === undefined)
+                return;
+            gracefulStops.push(ref.id);
+            info.status = "stopped";
+            delete info.attachAddress;
+        },
+        async listByLabel(labels) {
+            return [...sandboxes.values()]
+                .filter((info) => Object.entries(labels).every(([key, value]) => value === undefined || info.labels[key] === value))
+                .map((info) => structuredClone(info));
+        },
+        async inspect(ref) {
+            const info = sandboxes.get(ref.id);
+            return info === undefined ? undefined : structuredClone(info);
+        },
+        async release(ref) {
+            if (sandboxes.delete(ref.id))
+                releases.push(ref.id);
+        },
+    };
+}

package/dist/browser/gateHandoff.d.ts

@@ -16,8 +16,6 @@ export declare function parseGateHandoff(value: unknown): GateHandoff | undefine
 /** Reads the Host-owned fields off a stored or live wait request; unknown shapes yield nothing. */
 export declare function parseHostGateContext(value: unknown): HostGateContext;
 export declare function browserSite(browser: StageBrowserConfig): string | undefined;
-/** What the Host stamps on every gate of a browser stage; the agent cannot supply it. */
-export declare function hostGateContextFor(browser: StageBrowserConfig | undefined): HostGateContext | undefined;
 /**
  * Overwrites (or, for stages without a browser, strips) the Host-owned keys of
  * a wait request. Non-object requests pass through unchanged.

package/dist/browser/gateHandoff.js

@@ -7,6 +7,8 @@ export function parseGateHandoff(value) {
     if (record.kind === "local_window")
         return { kind: "local_window" };
     if (record.kind === "live_view" && typeof record.url === "string") {
+        if (isRootRelativePath(record.url))
+            return { kind: "live_view", url: record.url };
         try {
             const url = new URL(record.url);
             if (url.protocol === "https:" || url.protocol === "http:") {
@@ -19,6 +21,9 @@ export function parseGateHandoff(value) {
     }
     return undefined;
 }
+function isRootRelativePath(value) {
+    return value.startsWith("/") && !value.startsWith("//") && !value.includes("\\");
+}
 /** Reads the Host-owned fields off a stored or live wait request; unknown shapes yield nothing. */
 export function parseHostGateContext(value) {
     if (value === null || typeof value !== "object" || Array.isArray(value)) {
@@ -57,17 +62,6 @@ export function browserSite(browser) {
         return hostOf(browser.login_url);
     return undefined;
 }
-/** What the Host stamps on every gate of a browser stage; the agent cannot supply it. */
-export function hostGateContextFor(browser) {
-    if (browser === undefined)
-        return undefined;
-    const site = browserSite(browser);
-    return {
-        handoff: { kind: "local_window" },
-        ...(site !== undefined ? { site } : {}),
-        ...(browser.profile !== undefined ? { profile: browser.profile } : {}),
-    };
-}
 /**
  * Overwrites (or, for stages without a browser, strips) the Host-owned keys of
  * a wait request. Non-object requests pass through unchanged.

package/dist/browser/hostCapabilities.d.ts

@@ -0,0 +1,23 @@
+export type DisplayCapability = "local_window" | "virtual_display" | "headless_only";
+export type LiveViewKind = "none" | "relay" | "provider_view";
+export type ViewerInput = "interactive" | "view_only" | "unsupported";
+export type AttachStyle = "cdp" | "host_launched" | "unsupported";
+export type ProfilePersistence = "host_volume" | "provider_managed" | "none";
+export type DialogHandling = "relay_handled" | "provider_handled" | "unsupported";
+export type PopupHandling = "relay_retarget" | "provider_handled" | "unsupported";
+export type BrowserHostCapabilities = {
+    display: DisplayCapability;
+    liveView: LiveViewKind;
+    viewerInput: ViewerInput;
+    attach: AttachStyle;
+    profilePersistence: ProfilePersistence;
+    gracefulCloseRequired: boolean;
+    hardAllowlist: boolean;
+    dialogs: DialogHandling;
+    popups: PopupHandling;
+    permissionPolicy: boolean;
+};
+/** Every field is optional; an unset field reads as its conservative default. */
+export type BrowserHostCapabilityRecord = Partial<BrowserHostCapabilities>;
+export declare const DEFAULT_BROWSER_HOST_CAPABILITIES: Readonly<BrowserHostCapabilities>;
+export declare function resolveBrowserHostCapabilities(record?: BrowserHostCapabilityRecord): BrowserHostCapabilities;

package/dist/browser/hostCapabilities.js

@@ -0,0 +1,23 @@
+export const DEFAULT_BROWSER_HOST_CAPABILITIES = {
+    display: "headless_only",
+    liveView: "none",
+    viewerInput: "unsupported",
+    attach: "unsupported",
+    profilePersistence: "none",
+    gracefulCloseRequired: false,
+    hardAllowlist: false,
+    dialogs: "unsupported",
+    popups: "unsupported",
+    permissionPolicy: false,
+};
+export function resolveBrowserHostCapabilities(record) {
+    const resolved = { ...DEFAULT_BROWSER_HOST_CAPABILITIES };
+    if (record === undefined)
+        return resolved;
+    const target = resolved;
+    for (const [key, value] of Object.entries(record)) {
+        if (value !== undefined && key in DEFAULT_BROWSER_HOST_CAPABILITIES)
+            target[key] = value;
+    }
+    return resolved;
+}

package/dist/browser/humanLogin.d.ts

@@ -4,7 +4,7 @@ export type DisplayProbe = () => {
     hasDisplay: boolean;
     docker: boolean;
 };
-export declare const NO_SCREEN_MESSAGE = "A visible browser is needed for login, but this Host has no screen. A live view handoff is not available yet.";
+export declare const NO_SCREEN_MESSAGE = "A visible browser is needed for login, but this Host has no screen and no live view.";
 export declare const DOCKER_HINT = " This Host runs in Docker: run the login stage on a machine with a screen, or log in there first and reuse the profile.";
 /**
  * A human login stage is a stage with a `browser` whose after-phase verify
@@ -15,4 +15,4 @@ export declare function isHumanLoginStage(dag: Pick<ResolvedPipelineDag, "nodes"
 export declare function loginPageUrl(browser: StageBrowserConfig): string | undefined;
 export declare function defaultDisplayProbe(platform?: NodeJS.Platform, env?: Record<string, string | undefined>): ReturnType<DisplayProbe>;
 export declare function noScreenError(docker: boolean): Error;
-export declare function humanLoginPromptBlock(url: string | undefined): string;
+export declare function humanLoginPromptBlock(url: string | undefined, handoff?: "local_window" | "live_view"): string;

package/dist/browser/humanLogin.js

@@ -1,5 +1,5 @@
 import { existsSync } from "node:fs";
-export const NO_SCREEN_MESSAGE = "A visible browser is needed for login, but this Host has no screen. A live view handoff is not available yet.";
+export const NO_SCREEN_MESSAGE = "A visible browser is needed for login, but this Host has no screen and no live view.";
 export const DOCKER_HINT = " This Host runs in Docker: run the login stage on a machine with a screen, or log in there first and reuse the profile.";
 /**
  * A human login stage is a stage with a `browser` whose after-phase verify
@@ -23,7 +23,16 @@ export function defaultDisplayProbe(platform = process.platform, env = process.e
 export function noScreenError(docker) {
     return new Error(`${NO_SCREEN_MESSAGE}${docker ? DOCKER_HINT : ""}`);
 }
-export function humanLoginPromptBlock(url) {
+export function humanLoginPromptBlock(url, handoff = "local_window") {
+    if (handoff === "live_view") {
+        return [
+            "## Human login",
+            "",
+            `The Host has opened ${url !== undefined ? JSON.stringify(url) : "the login page"} in a browser the operator can see through the live view shown in the console in this gate.`,
+            "Do not type credentials and do not drive the browser. Call ask_operator with kind confirm: ask the operator to log in through the live view and confirm when done. Leave the browser open.",
+            "After the operator accepts, emit the envelope. The Host re-checks the login itself; if it still sees a logged-out session, this stage runs again.",
+        ].join("\n");
+    }
     return [
         "## Human login",
         "",

package/dist/browser/liveViewPersisted.d.ts

@@ -0,0 +1,11 @@
+import type { LiveViewSessionRequest } from "./liveViewRelay.js";
+/**
+ * Rebuilds a relay request from what the Host persisted (the stage env and, for a
+ * stage with a profile, the run's anchor), so a live view survives a Host restart.
+ */
+export declare function readLiveViewSessionRequest(input: {
+    runDir: string;
+    runId: string;
+    stageId: string;
+    profile?: string;
+}): Promise<LiveViewSessionRequest | undefined>;

package/dist/browser/liveViewPersisted.js

@@ -0,0 +1,22 @@
+import { readPersistedAnchor } from "./anchor.js";
+import { readStagePersistedBrowserEnv } from "./stageBrowserEnv.js";
+/**
+ * Rebuilds a relay request from what the Host persisted (the stage env and, for a
+ * stage with a profile, the run's anchor), so a live view survives a Host restart.
+ */
+export async function readLiveViewSessionRequest(input) {
+    const env = await readStagePersistedBrowserEnv(input.runDir, input.stageId);
+    if (env === undefined)
+        return undefined;
+    const anchor = input.profile !== undefined
+        ? await readPersistedAnchor(input.runDir, input.profile)
+        : undefined;
+    return {
+        runId: input.runId,
+        stageId: input.stageId,
+        env,
+        ...(anchor !== undefined
+            ? { anchorEnv: anchor.anchorEnv, cdpAddress: anchor.cdpAddress }
+            : {}),
+    };
+}

package/dist/browser/liveViewRelay.d.ts

@@ -0,0 +1,76 @@
+import type { BrowserEnv } from "./browserHost.js";
+export type LiveViewMessage = {
+    type: "frame" | "status" | "tabs" | "url" | "retarget" | "closed" | "dialog" | "dialog_closed";
+    data: unknown;
+};
+export type LiveViewInputEvent = Record<string, unknown> & {
+    type: string;
+};
+export type LiveViewSubscriber = (message: LiveViewMessage) => void;
+export type LiveViewInputRejection = "closed" | "not_array" | "batch_too_large" | "rate_limited" | "invalid_event" | "upstream_unavailable";
+/** A rejected batch forwards nothing. */
+export type LiveViewInputResult = {
+    ok: true;
+    accepted: number;
+} | {
+    ok: false;
+    reason: LiveViewInputRejection;
+};
+export type LiveViewDialogKind = "alert" | "confirm" | "prompt" | "beforeunload";
+/** Untrusted page text: plain text only, never HTML, never logged. */
+export type LiveViewDialog = {
+    id: string;
+    kind: LiveViewDialogKind;
+    message: string;
+    defaultPrompt: string;
+    targetId: string;
+    /** False for alert and beforeunload: agent-browser accepts them within milliseconds. */
+    answerable: boolean;
+};
+export type LiveViewDialogCloseResult = "accepted" | "dismissed" | "timeout" | "closed_by_page";
+export type LiveViewDialogAnswer = {
+    id: string;
+    accept: boolean;
+    promptText?: string;
+};
+export type LiveViewDialogRejection = "no_dialog" | "not_answerable" | "invalid" | "closed";
+export type LiveViewDialogResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: LiveViewDialogRejection;
+};
+export type LiveViewReopenRejection = "closed" | "no_tab" | "upstream_unavailable" | "rate_limited" | "failed";
+export type LiveViewReopenResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: LiveViewReopenRejection;
+};
+export type LiveViewSessionRequest = {
+    runId: string;
+    stageId: string;
+    /** The stage's persisted browser env; the relay never changes it. */
+    env: BrowserEnv;
+    /** The run's shared browser anchor env, when the stage has a profile. */
+    anchorEnv?: BrowserEnv;
+    /** The browser's CDP address when the Host already holds it; else the relay reads it from the env or the session. */
+    cdpAddress?: string;
+};
+export interface LiveViewSession {
+    /** Replays the cached status, tabs, url, any open dialog and last frame to the new subscriber first. Returns an unsubscribe function. */
+    subscribe(subscriber: LiveViewSubscriber): () => void;
+    /** Forwards one ordered batch of input events, all or nothing. */
+    sendInput(events: readonly LiveViewInputEvent[]): Promise<LiveViewInputResult>;
+    /** Answers the open confirm or prompt with that id; one answer per dialog. */
+    answerDialog(answer: LiveViewDialogAnswer): Promise<LiveViewDialogResult>;
+    /** Replaces the stage's current tab with a fresh one at the same URL (same browser context); the old tab closes only after the new one streams. */
+    reopenTab(): Promise<LiveViewReopenResult>;
+    /** Drops the cached frame so a re-target does not replay a stale page. */
+    clearFrame(): void;
+    /** Idempotent; subscribers receive a `closed` message. */
+    close(): Promise<void>;
+}
+export interface LiveViewRelay {
+    open(request: LiveViewSessionRequest): Promise<LiveViewSession>;
+}

package/dist/browser/liveViewRelay.js

@@ -0,0 +1 @@
+export {};

package/dist/browser/liveViewSessions.d.ts

@@ -0,0 +1,25 @@
+import type { LiveViewRelay, LiveViewSession, LiveViewSessionRequest } from "./liveViewRelay.js";
+export declare const LIVE_VIEW_SESSION_GRACE_MS = 5000;
+export type LiveViewLease = {
+    session: LiveViewSession;
+    release(): void;
+};
+export interface LiveViewSessionManager {
+    /** Opens the one relay session of (run, stage) on first use; undefined when the stage has no browser to show. */
+    acquire(runId: string, stageId: string): Promise<LiveViewLease | undefined>;
+    /** The open session, if any; never opens one. */
+    peek(runId: string, stageId: string): LiveViewSession | undefined;
+    closeStage(runId: string, stageId: string): Promise<void>;
+    closeRun(runId: string): Promise<void>;
+    /** Closes every session and cancels every grace timer. */
+    dispose(): Promise<void>;
+}
+export type LiveViewSessionManagerOptions = {
+    relay: LiveViewRelay;
+    /** Rebuilds the relay request from persisted state; undefined when the stage has no browser. */
+    request: (runId: string, stageId: string) => Promise<LiveViewSessionRequest | undefined>;
+    graceMs?: number;
+    setTimer?: (fn: () => void, ms: number) => unknown;
+    clearTimer?: (handle: unknown) => void;
+};
+export declare function createLiveViewSessionManager(options: LiveViewSessionManagerOptions): LiveViewSessionManager;

package/dist/browser/liveViewSessions.js

@@ -0,0 +1,139 @@
+export const LIVE_VIEW_SESSION_GRACE_MS = 5_000;
+function keyOf(runId, stageId) {
+    return `${runId}\0${stageId}`;
+}
+export function createLiveViewSessionManager(options) {
+    const graceMs = options.graceMs ?? LIVE_VIEW_SESSION_GRACE_MS;
+    const setTimer = options.setTimer ??
+        ((fn, ms) => {
+            const handle = setTimeout(fn, ms);
+            handle.unref();
+            return handle;
+        });
+    const clearTimer = options.clearTimer ?? ((handle) => clearTimeout(handle));
+    const entries = new Map();
+    const closing = new Map();
+    function track(entry, closer) {
+        const key = keyOf(entry.runId, entry.stageId);
+        const set = closing.get(key) ?? new Set();
+        closing.set(key, set);
+        const tracked = closer.finally(() => {
+            set.delete(tracked);
+            if (set.size === 0 && closing.get(key) === set)
+                closing.delete(key);
+        });
+        set.add(tracked);
+        return tracked;
+    }
+    async function settled(match) {
+        const pending = [];
+        for (const [key, set] of closing)
+            if (match(key))
+                pending.push(...set);
+        await Promise.all(pending);
+    }
+    function stopTimer(entry) {
+        if (entry.timer === undefined)
+            return;
+        clearTimer(entry.timer);
+        entry.timer = undefined;
+    }
+    function closeEntry(entry) {
+        stopTimer(entry);
+        return track(entry, (async () => {
+            const session = await entry.opening.catch(() => undefined);
+            await session?.close().catch(() => undefined);
+        })());
+    }
+    function open(runId, stageId) {
+        const key = keyOf(runId, stageId);
+        const entry = { runId, stageId, refs: 0 };
+        entry.opening = (async () => {
+            const request = await options.request(runId, stageId);
+            if (request === undefined)
+                return undefined;
+            const session = await options.relay.open(request);
+            entry.session = session;
+            session.subscribe((message) => {
+                if (message.type === "closed" && entries.get(key) === entry)
+                    entries.delete(key);
+            });
+            return session;
+        })();
+        entries.set(key, entry);
+        entry.opening.then((session) => {
+            if (session === undefined && entries.get(key) === entry)
+                entries.delete(key);
+        }, () => {
+            if (entries.get(key) === entry)
+                entries.delete(key);
+        });
+        return entry;
+    }
+    return {
+        async acquire(runId, stageId) {
+            const entry = entries.get(keyOf(runId, stageId)) ?? open(runId, stageId);
+            stopTimer(entry);
+            entry.refs += 1;
+            let session;
+            try {
+                session = await entry.opening;
+            }
+            catch (err) {
+                entry.refs -= 1;
+                throw err;
+            }
+            if (session === undefined) {
+                entry.refs -= 1;
+                return undefined;
+            }
+            let released = false;
+            return {
+                session,
+                release() {
+                    if (released)
+                        return;
+                    released = true;
+                    entry.refs -= 1;
+                    if (entry.refs > 0 || entries.get(keyOf(runId, stageId)) !== entry)
+                        return;
+                    stopTimer(entry);
+                    entry.timer = setTimer(() => {
+                        entry.timer = undefined;
+                        if (entry.refs > 0 || entries.get(keyOf(runId, stageId)) !== entry)
+                            return;
+                        entries.delete(keyOf(runId, stageId));
+                        void track(entry, session.close().catch(() => undefined));
+                    }, graceMs);
+                },
+            };
+        },
+        peek(runId, stageId) {
+            return entries.get(keyOf(runId, stageId))?.session;
+        },
+        async closeStage(runId, stageId) {
+            const key = keyOf(runId, stageId);
+            const entry = entries.get(key);
+            if (entry !== undefined) {
+                entries.delete(key);
+                void closeEntry(entry);
+            }
+            await settled((k) => k === key);
+        },
+        async closeRun(runId) {
+            const doomed = [...entries.values()].filter((entry) => entry.runId === runId);
+            for (const entry of doomed) {
+                entries.delete(keyOf(entry.runId, entry.stageId));
+                void closeEntry(entry);
+            }
+            await settled((k) => k.startsWith(`${runId}\0`));
+        },
+        async dispose() {
+            const doomed = [...entries.values()];
+            entries.clear();
+            for (const entry of doomed)
+                void closeEntry(entry);
+            await settled(() => true);
+        },
+    };
+}

package/dist/browser/liveViewSource.d.ts

@@ -0,0 +1,25 @@
+import type { BrowserSandboxOrchestrator } from "./sandboxOrchestrator.js";
+export type LiveViewSourceRequest = {
+    runId: string;
+    stageId: string;
+    /** Opaque sandbox reference of the stage's browser. */
+    sandboxId: string;
+};
+export type LiveViewAddress = {
+    /** Short-lived and per-session. Never store it in a gate, run file, log or audit record. */
+    url: string;
+    /** Origin the console must allow to embed the viewer. */
+    embedOrigin: string;
+    expiresAt: number;
+};
+export interface LiveViewSource {
+    viewerAddress(request: LiveViewSourceRequest): Promise<LiveViewAddress>;
+}
+export type SandboxIdResolver = (input: {
+    scope: string;
+    runId: string;
+    stageId: string;
+    profile?: string;
+}) => Promise<string | undefined>;
+/** Finds the stage's sandbox by the labels every orchestrator stamps on it. */
+export declare function sandboxIdFromLabels(orchestrator: Pick<BrowserSandboxOrchestrator, "listByLabel">): SandboxIdResolver;

package/dist/browser/liveViewSource.js

@@ -0,0 +1,7 @@
+/** Finds the stage's sandbox by the labels every orchestrator stamps on it. */
+export function sandboxIdFromLabels(orchestrator) {
+    return async ({ scope, runId, profile }) => {
+        const found = await orchestrator.listByLabel({ scope, runId, ...(profile !== undefined ? { profile } : {}) });
+        return found.find((info) => info.status === "running")?.ref.id;
+    };
+}