stageflow 0.32.0 → 0.35.0

package/dist/browser/anchor.d.ts

@@ -5,6 +5,8 @@ export declare const BROWSER_ANCHOR_FILENAME = "anchor.json";
 export type PersistedAnchor = ProfileBrowser & {
     runId: string;
     profile: string;
+    /** Owner scope the profile was opened in; absent in anchors written before it was persisted. */
+    scope?: string;
     /** Bumped each time the anchor was replaced after the first start. */
     restarts: number;
 };

package/dist/browser/anchor.js

@@ -101,9 +101,10 @@ export function ensureRunProfileBrowser(support, input) {
             anchorEnv: result.anchorEnv,
             runId: input.runId,
             profile: input.profile.key.name,
+            scope: input.profile.key.scope,
             restarts: (stored?.restarts ?? 0) + (stored !== undefined && changed ? 1 : 0),
         };
-        if (changed) {
+        if (changed || stored?.scope === undefined) {
             const dir = anchorDir(input.runDir, input.profile.key.name);
             const file = path.join(dir, BROWSER_ANCHOR_FILENAME);
             const tmp = `${file}.${process.pid}.tmp`;

package/dist/browser/auditSink.d.ts

@@ -1,3 +1,4 @@
+import type { LiveViewMode } from "./liveViewTickets.js";
 /** Records carry names, ids and hosts only: never paths, URLs with queries, or cookie values. */
 export type AuditRecord = {
     event: "profile_created";
@@ -25,6 +26,13 @@ export type AuditRecord = {
     stageId: string;
     profile?: string;
     reason: string;
+} | {
+    event: "live_view_opened" | "live_view_closed";
+    scope: string;
+    runId: string;
+    stageId: string;
+    mode: LiveViewMode;
+    callerId: string | null;
 };
 export interface AuditSink {
     record(entry: AuditRecord): Promise<void>;

package/dist/browser/browserHost.d.ts

@@ -2,6 +2,8 @@ import type { StageBrowserConfig } from "../types/stage.js";
 import type { ProfileLock } from "./profileLock.js";
 import type { AuditSink } from "./auditSink.js";
 import type { ProfileHandle, ProfileStore } from "./profileStore.js";
+import type { BrowserHostCapabilityRecord } from "./hostCapabilities.js";
+import type { OwnerScopeResolver } from "./ownerScope.js";
 export type BrowserEnv = Record<string, string>;
 export type BrowserStageRequest = {
     runId: string;
@@ -31,12 +33,30 @@ export type ProfileBrowserResult = ProfileBrowser & {
     /** True when a previous anchor existed but its address changed or it was replaced. */
     restarted: boolean;
 };
+export type ProfileBrowserRelease = {
+    scope: string;
+    runId: string;
+    profile: string;
+};
 export interface BrowserHost {
+    /** What this host can do; read through `resolveBrowserHostCapabilities` so unset fields get safe defaults. */
+    readonly capabilities?: BrowserHostCapabilityRecord;
     /**
      * Starts or reuses the one browser for (run, profile) and returns its CDP
      * address. Callers serialize per (run, profile) and persist the result.
      */
     ensureProfileBrowser(request: ProfileBrowserRequest): Promise<ProfileBrowserResult>;
+    /**
+     * Closes the run's shared browser for a profile gracefully (bounded) and releases
+     * what hosts it. Only hosts whose browser lives outside the Host's own sockets implement it.
+     */
+    releaseProfileBrowser?(request: ProfileBrowserRelease): Promise<void>;
+    /** At Host start: releases browsers of runs that are no longer live; returns what it released. */
+    sweepOrphans?(input: {
+        isRunLive: (runId: string) => Promise<boolean>;
+    }): Promise<{
+        released: string[];
+    }>;
     /** Env of one stage's agent-browser session; with a profile it attaches to `cdpAddress` in its own tab. */
     stageEnv(request: BrowserStageRequest): Promise<BrowserEnv>;
     /** Env of the session that owns the profile's browser (anchor, or `sf browser login`). */
@@ -72,6 +92,8 @@ export type StageBrowserSupport = {
     socketRoot?: string;
     /** Defaults to the local audit log in the Stageflow home. */
     audit?: AuditSink;
+    /** Owner scope of a run; defaults to the fixed local owner. Chosen by the Host, never by YAML. */
+    ownerScope?: OwnerScopeResolver;
     /** Host-blocked sites; defaults to `browser.blocked_sites` from Host config. */
     blockedSites?: readonly string[];
     /** Screen detection for human login stages; defaults to the real Host. */
@@ -79,6 +101,13 @@ export type StageBrowserSupport = {
         hasDisplay: boolean;
         docker: boolean;
     };
+    /** Awaited (bounded) before a stage's or run's browser is torn down; stageId absent means the whole run. */
+    beforeTeardown?: (input: {
+        runId: string;
+        stageId?: string;
+    }) => Promise<void> | void;
+    /** Upper bound for `beforeTeardown`; teardown proceeds when it is exceeded. */
+    beforeTeardownWaitMs?: number;
 };
 export declare const BROWSER_ENV_PREFIX = "AGENT_BROWSER_";
 export declare function shortHash(value: string, length: number): string;

package/dist/browser/browserSweep.d.ts

@@ -1,9 +1,11 @@
-import type { BrowserRunner } from "./browserHost.js";
+import type { BrowserHost, BrowserRunner } from "./browserHost.js";
 export type BrowserSweepOptions = {
     isRunLive: (runId: string) => Promise<boolean>;
     socketRoot?: string;
     runner?: BrowserRunner;
     closeWaitMs?: number;
+    /** A host whose browsers live outside the local sockets sweeps them itself (containers, by label). */
+    host?: BrowserHost;
 };
 /**
  * At Host start: close sessions whose run is gone or terminal, clean leftover
@@ -11,4 +13,5 @@ export type BrowserSweepOptions = {
  */
 export declare function sweepOrphanBrowserSessions(options: BrowserSweepOptions): Promise<{
     closed: string[];
+    released: string[];
 }>;

package/dist/browser/browserSweep.js

@@ -20,6 +20,13 @@ async function readOwner(dir) {
  * files, and leave sessions of live or waiting runs alone.
  */
 export async function sweepOrphanBrowserSessions(options) {
+    const { closed } = await sweepLocalSessions(options);
+    // Stage sessions are closed first; the host then releases the browsers they were attached to.
+    const swept = await (options.host?.sweepOrphans?.({ isRunLive: options.isRunLive }) ?? Promise.resolve({ released: [] }))
+        .catch(() => ({ released: [] }));
+    return { closed, released: swept.released };
+}
+async function sweepLocalSessions(options) {
     const root = options.socketRoot ?? defaultSocketRoot(process.platform);
     const closed = [];
     let dirs;

package/dist/browser/browserTeardown.d.ts

@@ -3,6 +3,7 @@ import { type BrowserEnv, type BrowserRunner, type StageBrowserSupport } from ".
 export declare const BROWSER_OWNER_FILENAME = "owner.json";
 /** Written once a stage's tab and session are closed; cleared when its env is resolved again. */
 export declare const BROWSER_CLOSED_FILENAME = "browser-closed.json";
+export declare const DEFAULT_BEFORE_TEARDOWN_WAIT_MS = 5000;
 export type BrowserSessionOwner = {
     runId: string;
     stageId: string;

package/dist/browser/browserTeardown.js

@@ -6,6 +6,7 @@ import { readPersistedBrowserEnv } from "./persistedEnv.js";
 import { stageDir } from "../runstore/paths.js";
 import { auditStageNavigations } from "./navigationAudit.js";
 import { BROWSER_ENV_FILENAME, BROWSER_POLICY_FILENAME, } from "./browserHost.js";
+import { runOwnerScope } from "./ownerScope.js";
 import { stageProfileLock } from "./stageProfileLock.js";
 import { BROWSER_ANCHOR_FILENAME, anchorDir, readPersistedAnchor, } from "./anchor.js";
 export const BROWSER_OWNER_FILENAME = "owner.json";
@@ -14,6 +15,7 @@ export const BROWSER_CLOSED_FILENAME = "browser-closed.json";
 const DEFAULT_CLOSE_WAIT_MS = 10_000;
 const POLL_MS = 50;
 const CLOSE_COMMAND_TIMEOUT_MS = 20_000;
+export const DEFAULT_BEFORE_TEARDOWN_WAIT_MS = 5_000;
 export const defaultBrowserRunner = (args, env, options) => new Promise((resolve) => {
     execFile("agent-browser", args, {
         env: { PATH: process.env.PATH ?? "", HOME: process.env.HOME ?? "", ...env },
@@ -102,6 +104,21 @@ async function readEnvFile(file) {
         return undefined;
     }
 }
+async function runBeforeTeardown(support, input) {
+    if (support.beforeTeardown === undefined)
+        return;
+    const hook = support.beforeTeardown;
+    let timer;
+    const bound = new Promise((resolve) => {
+        timer = setTimeout(resolve, support.beforeTeardownWaitMs ?? DEFAULT_BEFORE_TEARDOWN_WAIT_MS);
+    });
+    try {
+        await Promise.race([Promise.resolve().then(() => hook(input)).catch(() => undefined), bound]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
 function closeOptions(support) {
     return {
         ...(support.runner !== undefined ? { runner: support.runner } : {}),
@@ -155,6 +172,7 @@ async function auditAndClearPolicy(support, input) {
     await rm(file, { force: true }).catch(() => undefined);
 }
 async function teardownStageBrowserOnce(support, input) {
+    await runBeforeTeardown(support, { runId: input.runId, stageId: input.stageId });
     const env = await readEnvFile(path.join(stageDir(input.runDir, input.stageId), BROWSER_ENV_FILENAME));
     if (env === undefined)
         return;
@@ -195,8 +213,18 @@ async function closeRunAnchorsOnce(support, run) {
         const anchor = await readPersistedAnchor(run.runDir, name);
         if (anchor === undefined)
             continue;
-        const { gone } = await closeBrowserSession(anchor.anchorEnv, closeOptions(support)).catch(() => ({ gone: false }));
-        if (gone) {
+        const { gone: sessionGone } = await closeBrowserSession(anchor.anchorEnv, closeOptions(support)).catch(() => ({ gone: false }));
+        // Anchors written before the scope was persisted fall back to the run owner's scope.
+        const released = support.host.releaseProfileBrowser === undefined ||
+            (await support.host
+                .releaseProfileBrowser({
+                scope: anchor.scope ?? runOwnerScope(support, { runId: anchor.runId }),
+                runId: anchor.runId,
+                profile: name,
+            })
+                .then(() => true)
+                .catch(() => false));
+        if (sessionGone && released) {
             await rm(path.join(anchorDir(run.runDir, name), BROWSER_ANCHOR_FILENAME), {
                 force: true,
             }).catch(() => undefined);
@@ -209,6 +237,8 @@ async function closeRunAnchorsOnce(support, run) {
  * just those stages and leaves anchor and leases alone.
  */
 export async function teardownRunBrowsers(support, run, only) {
+    if (only === undefined)
+        await runBeforeTeardown(support, { runId: run.runId });
     let ids = [];
     try {
         ids = await readdir(path.join(run.runDir, "stages"));

package/dist/browser/containerBrowserEndpoint.d.ts

@@ -0,0 +1,11 @@
+export interface BrowserEndpointClient {
+    /** The browser-level debugging address behind an `http(s)://ip:port` endpoint, or undefined while nothing answers. */
+    resolve(endpoint: string): Promise<string | undefined>;
+    /** Asks the browser to close itself over the debugging protocol (this flushes the profile); resolves once it hung up or the bound passed. */
+    closeBrowser(cdpAddress: string, timeoutMs: number): Promise<void>;
+}
+export declare function endpointOf(cdpAddress: string): string;
+export declare function createCdpEndpointClient(options?: {
+    WebSocketImpl?: typeof WebSocket;
+    fetchImpl?: typeof fetch;
+}): BrowserEndpointClient;

package/dist/browser/containerBrowserEndpoint.js

@@ -0,0 +1,57 @@
+const PROBE_TIMEOUT_MS = 2_000;
+export function endpointOf(cdpAddress) {
+    const url = new URL(cdpAddress);
+    url.protocol = url.protocol === "wss:" ? "https:" : "http:";
+    return `${url.protocol}//${url.host}`;
+}
+export function createCdpEndpointClient(options = {}) {
+    const doFetch = options.fetchImpl ?? globalThis.fetch;
+    return {
+        async resolve(endpoint) {
+            const base = endpoint.startsWith("ws") ? endpointOf(endpoint) : endpoint.replace(/\/+$/, "");
+            try {
+                const res = await doFetch(`${base}/json/version`, { signal: AbortSignal.timeout(PROBE_TIMEOUT_MS) });
+                if (!res.ok)
+                    return undefined;
+                const body = (await res.json());
+                if (typeof body.webSocketDebuggerUrl !== "string")
+                    return undefined;
+                const advertised = new URL(body.webSocketDebuggerUrl);
+                const origin = new URL(base);
+                advertised.protocol = origin.protocol === "https:" ? "wss:" : "ws:";
+                advertised.host = origin.host;
+                return advertised.toString();
+            }
+            catch {
+                return undefined;
+            }
+        },
+        closeBrowser(cdpAddress, timeoutMs) {
+            const Impl = options.WebSocketImpl ?? globalThis.WebSocket;
+            return new Promise((resolve) => {
+                let ws;
+                try {
+                    ws = new Impl(cdpAddress);
+                }
+                catch {
+                    resolve();
+                    return;
+                }
+                const timer = setTimeout(done, timeoutMs);
+                function done() {
+                    clearTimeout(timer);
+                    try {
+                        ws.close();
+                    }
+                    catch {
+                        // already closed
+                    }
+                    resolve();
+                }
+                ws.onopen = () => ws.send(JSON.stringify({ id: 1, method: "Browser.close" }));
+                ws.onclose = done;
+                ws.onerror = done;
+            });
+        },
+    };
+}

package/dist/browser/containerBrowserHost.d.ts

@@ -0,0 +1,24 @@
+import { type BrowserHost } from "./browserHost.js";
+import { type BrowserEndpointClient } from "./containerBrowserEndpoint.js";
+import type { BrowserHostCapabilityRecord } from "./hostCapabilities.js";
+import { type LocalBrowserHostOptions } from "./localBrowserHost.js";
+import type { BrowserSandboxOrchestrator } from "./sandboxOrchestrator.js";
+export type ContainerBrowserHostOptions = {
+    orchestrator: BrowserSandboxOrchestrator;
+    /** `relay` only when the process also serves the live view routes; default `none`. */
+    liveView?: "relay" | "provider_view" | "none";
+    /** Capabilities the orchestrator behind this host adds or overrides (for example a view-only viewer). */
+    capabilities?: BrowserHostCapabilityRecord;
+    /** Builds stage session envs (socket dir, session name, config file); defaults to a local host. */
+    base?: BrowserHost;
+    local?: LocalBrowserHostOptions;
+    endpoint?: BrowserEndpointClient;
+    /** Upper bound for a new container's debugging endpoint to answer. */
+    startTimeoutMs?: number;
+    /** Upper bound for a graceful browser close to take effect before the orchestrator stops the container. */
+    closeWaitMs?: number;
+    pollMs?: number;
+    /** Resolves a non-IP attach host; Chrome refuses debugging requests addressed by name. */
+    resolveHost?: (hostname: string) => Promise<string>;
+};
+export declare function createContainerBrowserHost(options: ContainerBrowserHostOptions): BrowserHost;

package/dist/browser/containerBrowserHost.js

@@ -0,0 +1,147 @@
+import { lookup } from "node:dns/promises";
+import { isIP } from "node:net";
+import { createCdpEndpointClient, endpointOf, } from "./containerBrowserEndpoint.js";
+import { createLocalBrowserHost } from "./localBrowserHost.js";
+const DEFAULT_START_TIMEOUT_MS = 30_000;
+const DEFAULT_CLOSE_WAIT_MS = 10_000;
+const DEFAULT_POLL_MS = 250;
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+async function defaultResolveHost(hostname) {
+    return (await lookup(hostname)).address;
+}
+export function createContainerBrowserHost(options) {
+    const { orchestrator } = options;
+    const client = options.endpoint ?? createCdpEndpointClient();
+    const base = options.base ?? createLocalBrowserHost(options.local);
+    const startTimeoutMs = options.startTimeoutMs ?? DEFAULT_START_TIMEOUT_MS;
+    const closeWaitMs = options.closeWaitMs ?? DEFAULT_CLOSE_WAIT_MS;
+    const pollMs = options.pollMs ?? DEFAULT_POLL_MS;
+    const resolveHost = options.resolveHost ?? defaultResolveHost;
+    async function ipEndpoint(attachAddress) {
+        const url = new URL(attachAddress);
+        let host = url.hostname.replace(/^\[|\]$/g, "");
+        if (host === "localhost")
+            host = "127.0.0.1";
+        else if (isIP(host) === 0)
+            host = await resolveHost(host);
+        const secure = url.protocol === "wss:" || url.protocol === "https:";
+        const printable = isIP(host) === 6 ? `[${host}]` : host;
+        return `${secure ? "https" : "http"}://${printable}${url.port !== "" ? `:${url.port}` : ""}`;
+    }
+    async function reach(info) {
+        if (info.status !== "running" || info.attachAddress === undefined)
+            return undefined;
+        return client.resolve(await ipEndpoint(info.attachAddress));
+    }
+    async function waitFor(done, timeoutMs) {
+        const deadline = Date.now() + timeoutMs;
+        for (;;) {
+            if (await done())
+                return true;
+            if (Date.now() >= deadline)
+                return false;
+            await sleep(pollMs);
+        }
+    }
+    async function closeAndRelease(info) {
+        const address = await reach(info).catch(() => undefined);
+        if (address !== undefined) {
+            await client.closeBrowser(address, closeWaitMs).catch(() => undefined);
+            const gone = await waitFor(async () => (await reach(info).catch(() => undefined)) === undefined, closeWaitMs);
+            if (!gone)
+                await orchestrator.stopGracefully(info.ref).catch(() => undefined);
+        }
+        await orchestrator.release(info.ref);
+    }
+    async function anchorEnvFor(request, cdpAddress) {
+        const env = await base.stageEnv({
+            runId: request.runId,
+            stageId: `anchor:${request.profile.key.name}`,
+            browser: request.browser,
+            profile: request.profile,
+            cdpAddress,
+        });
+        delete env.AGENT_BROWSER_PIN_TAB;
+        return env;
+    }
+    const capabilities = {
+        display: "virtual_display",
+        liveView: options.liveView ?? "none",
+        attach: "cdp",
+        profilePersistence: "host_volume",
+        gracefulCloseRequired: true,
+        ...options.capabilities,
+    };
+    return {
+        capabilities,
+        async ensureProfileBrowser(request) {
+            const { profile, previous } = request;
+            const labels = { scope: profile.key.scope, runId: request.runId, profile: profile.key.name };
+            if (previous !== undefined) {
+                const alive = await client.resolve(endpointOf(previous.cdpAddress)).catch(() => undefined);
+                if (alive === previous.cdpAddress) {
+                    return { cdpAddress: previous.cdpAddress, anchorEnv: previous.anchorEnv, restarted: false };
+                }
+            }
+            let adopted;
+            for (const info of await orchestrator.listByLabel(labels)) {
+                const address = adopted === undefined ? await reach(info).catch(() => undefined) : undefined;
+                if (address !== undefined)
+                    adopted = { address, info };
+                else
+                    await closeAndRelease(info).catch(() => undefined);
+            }
+            let cdpAddress;
+            if (adopted !== undefined) {
+                cdpAddress = adopted.address;
+            }
+            else {
+                const info = await orchestrator.start({
+                    labels,
+                    profile: { scope: profile.key.scope, name: profile.key.name },
+                });
+                let ready;
+                await waitFor(async () => {
+                    const current = info.attachAddress !== undefined ? info : await orchestrator.inspect(info.ref);
+                    ready = current !== undefined ? await reach(current).catch(() => undefined) : undefined;
+                    return ready !== undefined;
+                }, startTimeoutMs);
+                if (ready === undefined) {
+                    await orchestrator.release(info.ref).catch(() => undefined);
+                    throw new Error("the container browser did not answer on its debugging port in time");
+                }
+                cdpAddress = ready;
+            }
+            return {
+                cdpAddress,
+                anchorEnv: await anchorEnvFor(request, cdpAddress),
+                restarted: previous !== undefined && previous.cdpAddress !== cdpAddress,
+            };
+        },
+        async releaseProfileBrowser(request) {
+            const found = await orchestrator.listByLabel({
+                scope: request.scope,
+                runId: request.runId,
+                profile: request.profile,
+            });
+            for (const info of found)
+                await closeAndRelease(info);
+        },
+        async sweepOrphans(input) {
+            const released = [];
+            for (const info of await orchestrator.listByLabel({})) {
+                if (await input.isRunLive(info.labels.runId).catch(() => true))
+                    continue;
+                await closeAndRelease(info);
+                released.push(info.ref.id);
+            }
+            return { released };
+        },
+        async profileBrowserEnv() {
+            throw new Error("the container browser host has no profile folder; `sf browser login` needs the local host");
+        },
+        stageEnv(request) {
+            return base.stageEnv(request);
+        },
+    };
+}

package/dist/browser/dockerSandboxOrchestrator.d.ts

@@ -0,0 +1,26 @@
+import { type BrowserSandboxOrchestrator } from "./sandboxOrchestrator.js";
+export type DockerCliResult = {
+    code: number;
+    stdout: string;
+    stderr: string;
+};
+export type DockerCliRunner = (args: string[]) => Promise<DockerCliResult>;
+export type DockerSandboxOptions = {
+    image: string;
+    command?: string[];
+    debugPort?: number;
+    shmSize?: string;
+    memory?: string;
+    pidsLimit?: number;
+    user?: string;
+    tmpfs?: string[];
+    stopTimeoutSeconds?: number;
+    profileMountPath?: string;
+    run?: DockerCliRunner;
+};
+export declare const defaultDockerCliRunner: DockerCliRunner;
+/**
+ * Development only: shells out to the local container CLI. It needs a runtime
+ * socket on the machine running it, so it must never run inside a Stageflow container.
+ */
+export declare function createDockerSandboxOrchestrator(options: DockerSandboxOptions): BrowserSandboxOrchestrator;

package/dist/browser/dockerSandboxOrchestrator.js

@@ -0,0 +1,142 @@
+import { execFile } from "node:child_process";
+import { SandboxError, } from "./sandboxOrchestrator.js";
+const LABEL_PREFIX = "stageflow.";
+const MARKER = `${LABEL_PREFIX}sandbox=1`;
+const LABEL_KEYS = {
+    scope: `${LABEL_PREFIX}scope`,
+    runId: `${LABEL_PREFIX}run`,
+    stageId: `${LABEL_PREFIX}stage`,
+    profile: `${LABEL_PREFIX}profile`,
+};
+export const defaultDockerCliRunner = (args) => new Promise((resolve) => {
+    execFile("docker", args, { timeout: 120_000, maxBuffer: 16 * 1024 * 1024 }, (err, stdout, stderr) => {
+        const code = err === null ? 0 : typeof err.code === "number" ? err.code : 1;
+        resolve({ code, stdout: String(stdout), stderr: err !== null && stderr === "" ? err.message : String(stderr) });
+    });
+});
+function volumeName(scope, name) {
+    const safe = (v) => v.replace(/[^A-Za-z0-9_.-]/g, "_");
+    return `sf-profile-${safe(scope)}-${safe(name)}`;
+}
+function statusOf(raw) {
+    if (raw === "running" || raw === "restarting" || raw === "paused")
+        return "running";
+    if (raw === "dead")
+        return "dead";
+    return "stopped";
+}
+function isMissing(result) {
+    return /no such (container|object)/i.test(result.stderr);
+}
+/**
+ * Development only: shells out to the local container CLI. It needs a runtime
+ * socket on the machine running it, so it must never run inside a Stageflow container.
+ */
+export function createDockerSandboxOrchestrator(options) {
+    const run = options.run ?? defaultDockerCliRunner;
+    const debugPort = options.debugPort ?? 9222;
+    const stopTimeout = options.stopTimeoutSeconds ?? 10;
+    const profileMount = options.profileMountPath ?? "/profile";
+    function toInfo(entry) {
+        const raw = entry.Config?.Labels ?? {};
+        const labels = { scope: raw[LABEL_KEYS.scope] ?? "", runId: raw[LABEL_KEYS.runId] ?? "" };
+        if (raw[LABEL_KEYS.stageId] !== undefined)
+            labels.stageId = raw[LABEL_KEYS.stageId];
+        if (raw[LABEL_KEYS.profile] !== undefined)
+            labels.profile = raw[LABEL_KEYS.profile];
+        const status = statusOf(entry.State?.Status);
+        const info = { ref: { id: entry.Id, adapter: { id: "docker", version: 1 } }, labels, status };
+        const binding = entry.NetworkSettings?.Ports?.[`${debugPort}/tcp`]?.[0];
+        if (status === "running" && binding?.HostPort !== undefined) {
+            info.attachAddress = `http://127.0.0.1:${binding.HostPort}`;
+        }
+        return info;
+    }
+    async function inspectMany(ids) {
+        if (ids.length === 0)
+            return [];
+        const result = await run(["inspect", ...ids]);
+        if (result.code !== 0) {
+            if (isMissing(result))
+                return [];
+            throw new SandboxError("unavailable", `docker inspect failed: ${result.stderr.trim()}`);
+        }
+        return JSON.parse(result.stdout).map(toInfo);
+    }
+    return {
+        async start(request) {
+            if (request.egress !== undefined) {
+                throw new SandboxError("not_supported", "the docker development orchestrator cannot enforce an egress policy");
+            }
+            const args = [
+                "run",
+                "-d",
+                "--init",
+                "--read-only",
+                "--cap-drop",
+                "ALL",
+                "--security-opt",
+                "no-new-privileges",
+                "--pids-limit",
+                String(options.pidsLimit ?? 512),
+                "--memory",
+                options.memory ?? "1g",
+                "--label",
+                MARKER,
+                "-p",
+                `127.0.0.1::${debugPort}`,
+            ];
+            for (const mount of options.tmpfs ?? ["/tmp"])
+                args.push("--tmpfs", mount);
+            if (options.user !== undefined)
+                args.push("--user", options.user);
+            if (options.shmSize !== undefined)
+                args.push("--shm-size", options.shmSize);
+            for (const [key, label] of Object.entries(LABEL_KEYS)) {
+                const value = request.labels[key];
+                if (value !== undefined)
+                    args.push("--label", `${label}=${value}`);
+            }
+            if (request.profile !== undefined) {
+                args.push("-v", `${volumeName(request.profile.scope, request.profile.name)}:${profileMount}`);
+            }
+            args.push(options.image, ...(options.command ?? []));
+            const started = await run(args);
+            if (started.code !== 0) {
+                throw new SandboxError("unavailable", `docker run failed: ${started.stderr.trim()}`);
+            }
+            const id = started.stdout.trim().split("\n").pop() ?? "";
+            const [info] = await inspectMany([id]);
+            if (info === undefined)
+                throw new SandboxError("failed", "container vanished after start");
+            return info;
+        },
+        async stopGracefully(ref) {
+            const result = await run(["stop", "-t", String(stopTimeout), ref.id]);
+            if (result.code !== 0 && !isMissing(result)) {
+                throw new SandboxError("failed", `docker stop failed: ${result.stderr.trim()}`);
+            }
+        },
+        async listByLabel(labels) {
+            const args = ["ps", "-a", "--no-trunc", "--format", "{{.ID}}", "--filter", `label=${MARKER}`];
+            for (const [key, label] of Object.entries(LABEL_KEYS)) {
+                const value = labels[key];
+                if (value !== undefined)
+                    args.push("--filter", `label=${label}=${value}`);
+            }
+            const listed = await run(args);
+            if (listed.code !== 0)
+                throw new SandboxError("unavailable", `docker ps failed: ${listed.stderr.trim()}`);
+            return inspectMany(listed.stdout.split("\n").map((l) => l.trim()).filter((l) => l !== ""));
+        },
+        async inspect(ref) {
+            return (await inspectMany([ref.id]))[0];
+        },
+        async release(ref) {
+            const result = await run(["rm", "-f", "-v", ref.id]);
+            if (result.code !== 0 && !isMissing(result)) {
+                throw new SandboxError("failed", `docker rm failed: ${result.stderr.trim()}`);
+            }
+        },
+    };
+}

package/dist/browser/fakeLiveViewRelay.d.ts

@@ -0,0 +1,15 @@
+import type { LiveViewDialogAnswer, LiveViewInputEvent, LiveViewMessage, LiveViewRelay, LiveViewReopenResult, LiveViewSession } from "./liveViewRelay.js";
+export type FakeLiveViewSession = LiveViewSession & {
+    /** Feeds a message as if it came from the browser's stream. */
+    emit(message: LiveViewMessage): void;
+    readonly input: readonly LiveViewInputEvent[];
+    readonly answers: readonly LiveViewDialogAnswer[];
+    readonly closed: boolean;
+    readonly reopens: number;
+    /** Result the next reopenTab() returns; defaults to ok. */
+    reopenResult: LiveViewReopenResult;
+};
+export type FakeLiveViewRelay = LiveViewRelay & {
+    readonly sessions: readonly FakeLiveViewSession[];
+};
+export declare function createFakeLiveViewRelay(): FakeLiveViewRelay;