stageflow 0.27.0 → 0.31.0

package/dist/browser/browserTeardown.js

@@ -0,0 +1,235 @@
+import { execFile } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { readFile, readdir, rm, rmdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+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 { stageProfileLock } from "./stageProfileLock.js";
+import { BROWSER_ANCHOR_FILENAME, anchorDir, readPersistedAnchor, } from "./anchor.js";
+export const BROWSER_OWNER_FILENAME = "owner.json";
+/** Written once a stage's tab and session are closed; cleared when its env is resolved again. */
+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 defaultBrowserRunner = (args, env, options) => new Promise((resolve) => {
+    execFile("agent-browser", args, {
+        env: { PATH: process.env.PATH ?? "", HOME: process.env.HOME ?? "", ...env },
+        timeout: options?.timeoutMs ?? CLOSE_COMMAND_TIMEOUT_MS,
+    }, (err, stdout) => {
+        const code = err?.code;
+        resolve({
+            code: err ? (typeof code === "number" ? code : 1) : 0,
+            stdout: String(stdout ?? ""),
+        });
+    });
+});
+export async function writeSessionOwner(owner) {
+    const dir = owner.env.AGENT_BROWSER_SOCKET_DIR;
+    if (!dir)
+        return;
+    await writeFile(path.join(dir, BROWSER_OWNER_FILENAME), `${JSON.stringify(owner)}\n`, { mode: 0o600 });
+}
+function pidAlive(pidFile) {
+    try {
+        const pid = Number.parseInt(readFileSync(pidFile, "utf8").trim(), 10);
+        if (!Number.isInteger(pid) || pid <= 0)
+            return false;
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === "EPERM";
+    }
+}
+function daemonGone(dir, session) {
+    if (existsSync(path.join(dir, `${session}.sock`)))
+        return false;
+    const pidFile = path.join(dir, `${session}.pid`);
+    return !existsSync(pidFile) || !pidAlive(pidFile);
+}
+async function removeSessionFiles(dir, session) {
+    let names;
+    try {
+        names = await readdir(dir);
+    }
+    catch {
+        return;
+    }
+    for (const name of names) {
+        if (name.startsWith(`${session}.`) || name === BROWSER_OWNER_FILENAME) {
+            await rm(path.join(dir, name), { force: true });
+        }
+    }
+    await rmdir(dir).catch(() => undefined);
+    await rmdir(path.dirname(dir)).catch(() => undefined);
+}
+/**
+ * Gracefully closes the session with the exact env it was launched with, waits
+ * (bounded) for the daemon to disappear, then removes the leftover socket-dir
+ * files. Never signals Chrome: a hard kill loses cookie persistence.
+ */
+// TODO(multi-tenant): teardown and the orphan sweep assume a local agent-browser runner and a local socket root.
+// A remote BrowserHost (sandbox or provider) needs its own close and sweep path.
+export async function closeBrowserSession(env, options = {}) {
+    const runner = options.runner ?? defaultBrowserRunner;
+    try {
+        await runner(["close"], env);
+    }
+    catch {
+        // close of an already-gone session is not an error
+    }
+    const dir = env.AGENT_BROWSER_SOCKET_DIR;
+    const session = env.AGENT_BROWSER_SESSION;
+    if (!dir || !session)
+        return { gone: true };
+    const deadline = Date.now() + (options.closeWaitMs ?? DEFAULT_CLOSE_WAIT_MS);
+    while (!daemonGone(dir, session)) {
+        if (Date.now() >= deadline)
+            return { gone: false };
+        await new Promise((r) => setTimeout(r, POLL_MS));
+    }
+    await removeSessionFiles(dir, session);
+    return { gone: true };
+}
+async function readEnvFile(file) {
+    try {
+        return await readPersistedBrowserEnv(file);
+    }
+    catch {
+        return undefined;
+    }
+}
+function closeOptions(support) {
+    return {
+        ...(support.runner !== undefined ? { runner: support.runner } : {}),
+        ...(support.closeWaitMs !== undefined
+            ? { closeWaitMs: support.closeWaitMs }
+            : {}),
+    };
+}
+/**
+ * Closes one stage's tab (when it is attached to a shared browser) and then
+ * its session. Chrome, the lease and the other stages stay up. No-op for
+ * stages that never resolved a browser env.
+ */
+export function teardownStageBrowser(support, input) {
+    const key = `${input.runDir}\0${input.stageId}`;
+    const running = stageTeardowns.get(key);
+    if (running !== undefined)
+        return running;
+    const promise = teardownStageBrowserOnce(support, input).finally(() => {
+        stageTeardowns.delete(key);
+    });
+    stageTeardowns.set(key, promise);
+    return promise;
+}
+const stageTeardowns = new Map();
+async function readNavigationPolicy(file) {
+    try {
+        const raw = JSON.parse(await readFile(file, "utf8"));
+        if (typeof raw.runId !== "string" ||
+            typeof raw.stageId !== "string" ||
+            !Array.isArray(raw.allow_domains)) {
+            return undefined;
+        }
+        return {
+            runId: raw.runId,
+            stageId: raw.stageId,
+            ...(typeof raw.profile === "string" ? { profile: raw.profile } : {}),
+            allow_domains: raw.allow_domains.filter((d) => typeof d === "string"),
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+async function auditAndClearPolicy(support, input) {
+    const file = path.join(stageDir(input.runDir, input.stageId), BROWSER_POLICY_FILENAME);
+    const policy = await readNavigationPolicy(file);
+    if (policy === undefined)
+        return;
+    await auditStageNavigations(policy, input.events, support.audit).catch(() => undefined);
+    await rm(file, { force: true }).catch(() => undefined);
+}
+async function teardownStageBrowserOnce(support, input) {
+    const env = await readEnvFile(path.join(stageDir(input.runDir, input.stageId), BROWSER_ENV_FILENAME));
+    if (env === undefined)
+        return;
+    await auditAndClearPolicy(support, input);
+    const closedMarker = path.join(stageDir(input.runDir, input.stageId), BROWSER_CLOSED_FILENAME);
+    // A second close would re-attach to the shared browser and could close another stage's tab.
+    if (existsSync(closedMarker))
+        return;
+    if (env.AGENT_BROWSER_CDP !== undefined) {
+        // With the pinned tab as the current tab, `tab close` closes only this stage's tab.
+        await (support.runner ?? defaultBrowserRunner)(["tab", "close"], env).catch(() => undefined);
+    }
+    const { gone } = await closeBrowserSession(env, closeOptions(support));
+    if (gone)
+        await writeFile(closedMarker, "{}\n").catch(() => undefined);
+}
+/** Gracefully closes every anchor browser the run started. */
+export function closeRunAnchors(support, run) {
+    const running = anchorTeardowns.get(run.runDir);
+    if (running !== undefined)
+        return running;
+    const promise = closeRunAnchorsOnce(support, run).finally(() => {
+        anchorTeardowns.delete(run.runDir);
+    });
+    anchorTeardowns.set(run.runDir, promise);
+    return promise;
+}
+const anchorTeardowns = new Map();
+async function closeRunAnchorsOnce(support, run) {
+    let names = [];
+    try {
+        names = await readdir(path.join(run.runDir, "browser"));
+    }
+    catch {
+        return;
+    }
+    for (const name of names) {
+        const anchor = await readPersistedAnchor(run.runDir, name);
+        if (anchor === undefined)
+            continue;
+        const { gone } = await closeBrowserSession(anchor.anchorEnv, closeOptions(support)).catch(() => ({ gone: false }));
+        if (gone) {
+            await rm(path.join(anchorDir(run.runDir, name), BROWSER_ANCHOR_FILENAME), {
+                force: true,
+            }).catch(() => undefined);
+        }
+    }
+}
+/**
+ * Run end, cancel, abandon or failure: closes stage sessions and tabs, then
+ * the run's anchors, then releases the run's profile leases. `only` closes
+ * just those stages and leaves anchor and leases alone.
+ */
+export async function teardownRunBrowsers(support, run, only) {
+    let ids = [];
+    try {
+        ids = await readdir(path.join(run.runDir, "stages"));
+    }
+    catch {
+        // no stage dirs: nothing to close
+    }
+    for (const stageId of ids) {
+        if (only !== undefined && !only(stageId))
+            continue;
+        const { events, ...base } = run;
+        await teardownStageBrowser(support, {
+            ...base,
+            stageId,
+            ...(events !== undefined ? { events: () => events(stageId) } : {}),
+        }).catch(() => undefined);
+    }
+    if (only === undefined) {
+        await closeRunAnchors(support, run).catch(() => undefined);
+        await stageProfileLock(support)
+            .releaseOwner({ runId: run.runId })
+            .catch(() => undefined);
+    }
+}

package/dist/browser/fakeRemoteBrowserHost.d.ts

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

package/dist/browser/fakeRemoteBrowserHost.js

@@ -0,0 +1,34 @@
+import { shortHash, } from "./browserHost.js";
+export function createFakeRemoteBrowserHost(address) {
+    return {
+        async ensureProfileBrowser(request) {
+            return {
+                cdpAddress: address,
+                anchorEnv: {
+                    AGENT_BROWSER_CDP: address,
+                    AGENT_BROWSER_SESSION: `sf-r-${shortHash(`${request.profile.key.scope}/${request.profile.key.name}`, 12)}`,
+                    AGENT_BROWSER_IDLE_TIMEOUT_MS: "0",
+                },
+                restarted: false,
+            };
+        },
+        async profileBrowserEnv(request) {
+            return {
+                AGENT_BROWSER_CDP: address,
+                AGENT_BROWSER_SESSION: `sf-r-${shortHash(`${request.profile.key.scope}/${request.profile.key.name}`, 12)}`,
+                AGENT_BROWSER_IDLE_TIMEOUT_MS: "0",
+            };
+        },
+        async stageEnv(request) {
+            const identity = `${request.runId}/${request.stageId}`;
+            const env = {
+                AGENT_BROWSER_CDP: request.cdpAddress ?? address,
+                AGENT_BROWSER_SESSION: `sf-r-${shortHash(identity, 12)}`,
+                AGENT_BROWSER_IDLE_TIMEOUT_MS: "0",
+            };
+            if (request.profile !== undefined)
+                env.AGENT_BROWSER_PIN_TAB = "1";
+            return env;
+        },
+    };
+}

package/dist/browser/gateHandoff.d.ts

@@ -0,0 +1,25 @@
+import type { StageBrowserConfig } from "../types/stage.js";
+export type GateHandoff = {
+    kind: "local_window";
+} | {
+    kind: "live_view";
+    url: string;
+};
+/** Host-owned fields on a gate prompt for stages with a `browser`. Never a path. */
+export type HostGateContext = {
+    handoff?: GateHandoff;
+    site?: string;
+    profile?: string;
+};
+export declare const HOST_GATE_KEYS: readonly ["handoff", "site", "profile"];
+export declare function parseGateHandoff(value: unknown): GateHandoff | undefined;
+/** 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.
+ */
+export declare function stampGateRequest(request: unknown, context: HostGateContext | undefined): unknown;

package/dist/browser/gateHandoff.js

@@ -0,0 +1,83 @@
+export const HOST_GATE_KEYS = ["handoff", "site", "profile"];
+export function parseGateHandoff(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        return undefined;
+    }
+    const record = value;
+    if (record.kind === "local_window")
+        return { kind: "local_window" };
+    if (record.kind === "live_view" && typeof record.url === "string") {
+        try {
+            const url = new URL(record.url);
+            if (url.protocol === "https:" || url.protocol === "http:") {
+                return { kind: "live_view", url: record.url };
+            }
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return undefined;
+}
+/** 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)) {
+        return {};
+    }
+    const record = value;
+    const handoff = parseGateHandoff(record.handoff);
+    return {
+        ...(handoff !== undefined ? { handoff } : {}),
+        ...(typeof record.site === "string" && record.site !== ""
+            ? { site: record.site }
+            : {}),
+        ...(typeof record.profile === "string" && record.profile !== ""
+            ? { profile: record.profile }
+            : {}),
+    };
+}
+function hostOf(url) {
+    try {
+        return new URL(url).hostname || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function browserSite(browser) {
+    if (browser.check !== undefined) {
+        const host = hostOf(browser.check.url);
+        if (host !== undefined)
+            return host;
+    }
+    const first = browser.allow_domains?.[0];
+    if (first !== undefined)
+        return first.replace(/^\*\./, "");
+    if (browser.login_url !== undefined)
+        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.
+ */
+export function stampGateRequest(request, context) {
+    if (request === null || typeof request !== "object" || Array.isArray(request)) {
+        return request;
+    }
+    const next = { ...request };
+    for (const key of HOST_GATE_KEYS)
+        delete next[key];
+    return context === undefined ? next : { ...next, ...context };
+}

package/dist/browser/humanLogin.d.ts

@@ -0,0 +1,18 @@
+import type { ResolvedPipelineDag } from "../types/pipeline.js";
+import type { StageBrowserConfig } from "../types/stage.js";
+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 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
+ * contains a `browser_login` item. The Host opens the login page in a visible
+ * window and the agent only asks the operator to confirm.
+ */
+export declare function isHumanLoginStage(dag: Pick<ResolvedPipelineDag, "nodes"> | undefined, stageId: string, browser: StageBrowserConfig | undefined): boolean;
+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;

package/dist/browser/humanLogin.js

@@ -0,0 +1,34 @@
+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 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
+ * contains a `browser_login` item. The Host opens the login page in a visible
+ * window and the agent only asks the operator to confirm.
+ */
+export function isHumanLoginStage(dag, stageId, browser) {
+    if (browser === undefined || dag === undefined)
+        return false;
+    const node = dag.nodes.find((n) => n.id === stageId);
+    return node?.completion?.checks.some((c) => c.type === "browser_login") === true;
+}
+export function loginPageUrl(browser) {
+    return browser.login_url ?? browser.check?.url;
+}
+export function defaultDisplayProbe(platform = process.platform, env = process.env) {
+    const docker = existsSync("/.dockerenv") || Boolean(env.container) || env.STAGEFLOW_IN_DOCKER === "1";
+    const hasDisplay = platform !== "linux" || Boolean(env.DISPLAY || env.WAYLAND_DISPLAY);
+    return { hasDisplay, docker };
+}
+export function noScreenError(docker) {
+    return new Error(`${NO_SCREEN_MESSAGE}${docker ? DOCKER_HINT : ""}`);
+}
+export function humanLoginPromptBlock(url) {
+    return [
+        "## Human login",
+        "",
+        `The Host has opened ${url !== undefined ? JSON.stringify(url) : "the login page"} in a visible browser window on the operator's screen.`,
+        "Do not type credentials and do not drive the browser. Call ask_operator with kind confirm: ask the operator to log in in that window 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");
+}

package/dist/browser/keyProvider.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Supplies a Host-held secret for protecting browser state at rest. Not wired
+ * to agent-browser: its key only covers its own restore/state files, never the
+ * Chrome profile directory.
+ */
+export interface KeyProvider {
+    getKey(): Promise<string>;
+}
+export declare function localKeyFilePath(): string;
+export declare function createLocalKeyProvider(file?: string): KeyProvider;

package/dist/browser/keyProvider.js

@@ -0,0 +1,39 @@
+import { randomBytes } from "node:crypto";
+import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { globalStageflowHome } from "../project/globalHome.js";
+export function localKeyFilePath() {
+    return path.join(globalStageflowHome(), "browser", "browser.key");
+}
+// TODO(multi-tenant): nothing in the runtime calls a KeyProvider yet, so browser.key is never created outside tests.
+// A service needs a per-tenant key (KMS) and a decision on what it encrypts; the agent-browser key does not protect the Chrome profile.
+export function createLocalKeyProvider(file) {
+    return {
+        async getKey() {
+            const target = file ?? localKeyFilePath();
+            try {
+                const existing = (await readFile(target, "utf8")).trim();
+                if (existing.length > 0) {
+                    await chmod(target, 0o600);
+                    return existing;
+                }
+            }
+            catch (err) {
+                if (err.code !== "ENOENT")
+                    throw err;
+            }
+            await mkdir(path.dirname(target), { recursive: true, mode: 0o700 });
+            const key = randomBytes(32).toString("hex");
+            try {
+                await writeFile(target, `${key}\n`, { mode: 0o600, flag: "wx" });
+            }
+            catch (err) {
+                if (err.code === "EEXIST") {
+                    return (await readFile(target, "utf8")).trim();
+                }
+                throw err;
+            }
+            return key;
+        },
+    };
+}

package/dist/browser/localBrowserHost.d.ts

@@ -0,0 +1,10 @@
+import { type BrowserHost } from "./browserHost.js";
+export type LocalBrowserHostOptions = {
+    platform?: NodeJS.Platform;
+    /** Read only for display detection; never for AGENT_BROWSER_* settings. */
+    hostEnv?: Record<string, string | undefined>;
+    socketRoot?: string;
+    emptyConfigPath?: string;
+};
+export declare function defaultSocketRoot(platform: NodeJS.Platform): string;
+export declare function createLocalBrowserHost(options?: LocalBrowserHostOptions): BrowserHost;

package/dist/browser/localBrowserHost.js

@@ -0,0 +1,152 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { globalStageflowHome } from "../project/globalHome.js";
+import { shortHash, } from "./browserHost.js";
+const MAX_SOCKET_PATH_BYTES = 103;
+const MAX_SESSION_NAME_LENGTH = 48;
+const DISPLAY_VARS = ["DISPLAY", "WAYLAND_DISPLAY", "XAUTHORITY"];
+export function defaultSocketRoot(platform) {
+    const uid = typeof process.getuid === "function" ? process.getuid() : "u";
+    const base = platform === "win32" ? os.tmpdir() : "/tmp";
+    return path.join(base, `sfb-${uid}`);
+}
+function sessionNameForProfile(scope, name) {
+    const plain = `sf-${name}`;
+    if (plain.length <= MAX_SESSION_NAME_LENGTH)
+        return plain;
+    return `${plain.slice(0, MAX_SESSION_NAME_LENGTH - 7)}-${shortHash(`${scope}/${name}`, 6)}`;
+}
+function sessionNameForProfileStage(profile, runId, stageId) {
+    const suffix = shortHash(`${runId}/${stageId}`, 6);
+    const plain = `sf-${profile.key.name}`;
+    const room = MAX_SESSION_NAME_LENGTH - suffix.length - 1;
+    return `${plain.slice(0, room)}-${suffix}`;
+}
+const OPEN_ANCHOR_TIMEOUT_MS = 60_000;
+function hasDisplay(platform, hostEnv) {
+    if (platform !== "linux")
+        return true;
+    return Boolean(hostEnv.DISPLAY || hostEnv.WAYLAND_DISPLAY);
+}
+export function createLocalBrowserHost(options = {}) {
+    const platform = options.platform ?? process.platform;
+    const hostEnv = options.hostEnv ?? process.env;
+    async function build(input) {
+        const socketRoot = options.socketRoot ?? defaultSocketRoot(platform);
+        const socketDir = path.join(socketRoot, shortHash(input.identity, 8));
+        const socketPathBytes = Buffer.byteLength(path.join(socketDir, `${input.session}.sock`));
+        if (socketPathBytes > MAX_SOCKET_PATH_BYTES) {
+            throw new Error(`browser socket path is ${socketPathBytes} bytes (limit ${MAX_SOCKET_PATH_BYTES})`);
+        }
+        await mkdir(socketDir, { recursive: true, mode: 0o700 });
+        const emptyConfigPath = options.emptyConfigPath ??
+            path.join(globalStageflowHome(), "browser", "agent-browser.empty.json");
+        await mkdir(path.dirname(emptyConfigPath), { recursive: true, mode: 0o700 });
+        await writeFile(emptyConfigPath, "{}\n", { mode: 0o600 });
+        const env = {
+            AGENT_BROWSER_SESSION: input.session,
+            AGENT_BROWSER_SOCKET_DIR: socketDir,
+            AGENT_BROWSER_HEADED: input.headed ? "1" : "0",
+            AGENT_BROWSER_IDLE_TIMEOUT_MS: "0",
+            AGENT_BROWSER_CONFIG: emptyConfigPath,
+        };
+        input.set(env);
+        if (input.headed && platform === "linux") {
+            for (const name of DISPLAY_VARS) {
+                const value = hostEnv[name];
+                if (value)
+                    env[name] = value;
+            }
+        }
+        return env;
+    }
+    function headedFor(request) {
+        return (request.humanLogin === true ||
+            ((request.browser.headed ?? true) && hasDisplay(platform, hostEnv)));
+    }
+    async function profileBrowserEnv(request) {
+        const { profile } = request;
+        return build({
+            identity: `profile:${profile.key.scope}/${profile.key.name}:${profile.profileDir}`,
+            session: sessionNameForProfile(profile.key.scope, profile.key.name),
+            headed: headedFor(request),
+            set: (env) => {
+                env.AGENT_BROWSER_PROFILE = profile.profileDir;
+            },
+        });
+    }
+    async function readCdpAddress(request, env) {
+        const got = await request.runner(["get", "cdp-url"], env, {
+            timeoutMs: OPEN_ANCHOR_TIMEOUT_MS,
+        });
+        const address = (got.stdout ?? "").trim();
+        if (got.code !== 0 || !/^wss?:\/\//.test(address)) {
+            throw new Error("could not read the shared browser address (agent-browser get cdp-url)");
+        }
+        return address;
+    }
+    return {
+        async ensureProfileBrowser(request) {
+            const wantHeaded = headedFor(request);
+            let previous = request.previous;
+            if (previous !== undefined &&
+                wantHeaded &&
+                previous.anchorEnv.AGENT_BROWSER_HEADED !== "1") {
+                await request.runner(["close"], previous.anchorEnv).catch(() => undefined);
+                previous = undefined;
+            }
+            if (previous !== undefined) {
+                // Any command relaunches a dead anchor, so reading the address is the liveness probe.
+                const cdpAddress = await readCdpAddress(request, previous.anchorEnv);
+                return {
+                    cdpAddress,
+                    anchorEnv: previous.anchorEnv,
+                    restarted: cdpAddress !== previous.cdpAddress,
+                };
+            }
+            const anchorEnv = await profileBrowserEnv(request);
+            const opened = await request.runner(["open", "about:blank"], anchorEnv, {
+                timeoutMs: OPEN_ANCHOR_TIMEOUT_MS,
+            });
+            if (opened.code !== 0)
+                throw new Error("could not start the shared browser");
+            const cdpAddress = await readCdpAddress(request, anchorEnv);
+            return {
+                cdpAddress,
+                anchorEnv,
+                restarted: request.previous !== undefined,
+            };
+        },
+        profileBrowserEnv,
+        async stageEnv(request) {
+            const { browser, profile } = request;
+            if (profile !== undefined) {
+                if (request.cdpAddress === undefined) {
+                    throw new Error("a stage with a browser profile needs the shared browser address");
+                }
+                const cdp = request.cdpAddress;
+                return build({
+                    identity: `stage:${request.runId}/${request.stageId}`,
+                    session: sessionNameForProfileStage(profile, request.runId, request.stageId),
+                    headed: headedFor(request),
+                    set: (env) => {
+                        env.AGENT_BROWSER_CDP = cdp;
+                        env.AGENT_BROWSER_PIN_TAB = "1";
+                    },
+                });
+            }
+            const identity = `stage:${request.runId}/${request.stageId}`;
+            return build({
+                identity,
+                session: `sf-t-${shortHash(identity, 12)}`,
+                headed: headedFor(request),
+                set: (env) => {
+                    if (browser.allow_domains && browser.allow_domains.length > 0) {
+                        env.AGENT_BROWSER_ALLOWED_DOMAINS = browser.allow_domains.join(",");
+                    }
+                },
+            });
+        },
+    };
+}

package/dist/browser/localProfileLock.d.ts

@@ -0,0 +1,2 @@
+import { type ProfileLock, type ProfileLockOptions } from "./profileLock.js";
+export declare function createLocalProfileLock(options?: ProfileLockOptions): ProfileLock;