stageflow 0.27.0 → 0.30.0

package/dist/browser/sitePolicy.js

@@ -0,0 +1,61 @@
+export class BlockedSiteError extends Error {
+    code = "browser_site_blocked";
+    constructor(message) {
+        super(message);
+        this.name = "BlockedSiteError";
+    }
+}
+export function normalizeDomain(raw) {
+    return raw
+        .trim()
+        .toLowerCase()
+        .replace(/^\*\./, "")
+        .replace(/^\./, "")
+        .replace(/\.$/, "");
+}
+export function hostOf(urlOrHost) {
+    const text = urlOrHost.trim();
+    if (text.length === 0)
+        return undefined;
+    try {
+        const parsed = new URL(/^[a-z][a-z0-9+.-]*:\/\//i.test(text) ? text : `https://${text}`);
+        return parsed.hostname.toLowerCase().replace(/\.$/, "") || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function within(host, domain) {
+    return host === domain || host.endsWith(`.${domain}`);
+}
+export function isBlockedHost(host, blocked) {
+    const h = normalizeDomain(host);
+    return blocked.map(normalizeDomain).find((d) => d.length > 0 && within(h, d));
+}
+/** Throws when the stage's allow_domains or check URLs touch a Host-blocked site. */
+export function assertBrowserSitesAllowed(stageId, browser, blocked) {
+    if (blocked.length === 0)
+        return;
+    const norm = blocked.map(normalizeDomain).filter((d) => d.length > 0);
+    const fail = (site, where) => {
+        throw new BlockedSiteError(`Stage "${stageId}": browser ${where} "${site}" is blocked by Host policy (browser.blocked_sites)`);
+    };
+    for (const entry of browser.allow_domains ?? []) {
+        const d = normalizeDomain(entry);
+        if (norm.some((b) => within(d, b) || within(b, d)))
+            fail(entry, "allow_domains entry");
+    }
+    const urls = [
+        ["login_url", browser.login_url],
+        ["check.url", browser.check?.url],
+        ["check.logged_in_url", browser.check?.logged_in_url],
+        ...[browser.check?.logged_out_url].flat().map((u) => ["check.logged_out_url", u]),
+    ];
+    for (const [where, url] of urls) {
+        if (!url)
+            continue;
+        const host = hostOf(url);
+        if (host !== undefined && isBlockedHost(host, norm) !== undefined)
+            fail(host, where);
+    }
+}

package/dist/browser/stageBrowserEnv.d.ts

@@ -0,0 +1,22 @@
+import type { StageBrowserConfig } from "../types/stage.js";
+import { BROWSER_ENV_FILENAME, type BrowserEnv, type StageBrowserSupport } from "./browserHost.js";
+export { BROWSER_ENV_FILENAME };
+export declare function readStagePersistedBrowserEnv(runDir: string, stageId: string): Promise<BrowserEnv | undefined>;
+export declare function defaultStageBrowserSupport(): StageBrowserSupport;
+/**
+ * Computed once per stage and persisted in the run dir: agent-browser silently
+ * relaunches the browser when a command's launch env differs from the daemon's,
+ * so every attempt and resume worker must see byte-identical values.
+ */
+export declare function resolveStageBrowserEnv(support: StageBrowserSupport, input: {
+    runId: string;
+    stageId: string;
+    runDir: string;
+    browser: StageBrowserConfig | undefined;
+    /** Attempt the login check result belongs to; defaults to 1. */
+    attempt?: number;
+    /** Human login stage: needs a screen, opens the login page, skips the pre-agent check. */
+    humanLogin?: boolean;
+    /** Resume worker: the operator's window is already open; do not navigate it. */
+    resuming?: boolean;
+}): Promise<BrowserEnv | undefined>;

package/dist/browser/stageBrowserEnv.js

@@ -0,0 +1,147 @@
+import { mkdir, rename, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { loadHostConfig } from "../config/hostConfig.js";
+import { stageDir } from "../runstore/paths.js";
+import { safeAudit } from "./auditSink.js";
+import { assertBrowserSitesAllowed } from "./sitePolicy.js";
+import { BROWSER_ENV_FILENAME, BROWSER_POLICY_FILENAME, } from "./browserHost.js";
+import { ensureRunProfileBrowser } from "./anchor.js";
+import { BROWSER_CLOSED_FILENAME, closeBrowserSession, defaultBrowserRunner, writeSessionOwner, } from "./browserTeardown.js";
+import { defaultDisplayProbe, loginPageUrl, noScreenError } from "./humanLogin.js";
+import { ensureStageLoginCheck, OPEN_COMMAND_TIMEOUT_MS } from "./loginCheck.js";
+import { readPersistedBrowserEnv } from "./persistedEnv.js";
+import { createLocalBrowserHost } from "./localBrowserHost.js";
+import { createLocalProfileStore } from "./localProfileStore.js";
+import { LOCAL_BROWSER_SCOPE } from "./profileStore.js";
+export { BROWSER_ENV_FILENAME };
+export async function readStagePersistedBrowserEnv(runDir, stageId) {
+    return readPersistedBrowserEnv(path.join(stageDir(runDir, stageId), BROWSER_ENV_FILENAME));
+}
+let defaultSupport;
+export function defaultStageBrowserSupport() {
+    defaultSupport ??= {
+        host: createLocalBrowserHost(),
+        profiles: createLocalProfileStore(),
+    };
+    return defaultSupport;
+}
+/**
+ * Computed once per stage and persisted in the run dir: agent-browser silently
+ * relaunches the browser when a command's launch env differs from the daemon's,
+ * so every attempt and resume worker must see byte-identical values.
+ */
+export async function resolveStageBrowserEnv(support, input) {
+    const { browser } = input;
+    if (browser === undefined)
+        return undefined;
+    if (input.humanLogin === true) {
+        const screen = (support.display ?? defaultDisplayProbe)();
+        if (!screen.hasDisplay)
+            throw noScreenError(screen.docker);
+    }
+    if ((browser.allow_domains?.length ?? 0) > 0 ||
+        browser.check !== undefined ||
+        browser.login_url !== undefined) {
+        assertBrowserSitesAllowed(input.stageId, browser, support.blockedSites ?? loadHostConfig().browserBlockedSites);
+    }
+    const dir = stageDir(input.runDir, input.stageId);
+    const file = path.join(dir, BROWSER_ENV_FILENAME);
+    // TODO(multi-tenant): open the profile in the run owner's scope, not the fixed local scope.
+    const profile = browser.profile !== undefined
+        ? await support.profiles.open({
+            scope: LOCAL_BROWSER_SCOPE,
+            name: browser.profile,
+        })
+        : undefined;
+    const anchor = profile !== undefined
+        ? await ensureRunProfileBrowser(support, {
+            runId: input.runId,
+            runDir: input.runDir,
+            browser,
+            profile,
+            ...(input.humanLogin === true ? { humanLogin: true } : {}),
+        })
+        : undefined;
+    const fresh = await support.host.stageEnv({
+        runId: input.runId,
+        stageId: input.stageId,
+        browser,
+        ...(profile !== undefined ? { profile } : {}),
+        ...(anchor !== undefined ? { cdpAddress: anchor.cdpAddress } : {}),
+        ...(input.humanLogin === true ? { humanLogin: true } : {}),
+    });
+    await rm(path.join(dir, BROWSER_CLOSED_FILENAME), { force: true });
+    const persisted = await readPersistedBrowserEnv(file);
+    let env = persisted ?? fresh;
+    const writeEnv = async (value) => {
+        await mkdir(dir, { recursive: true });
+        const tmp = `${file}.${process.pid}.tmp`;
+        await writeFile(tmp, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+        await rename(tmp, file);
+    };
+    if (persisted !== undefined &&
+        anchor !== undefined &&
+        persisted.AGENT_BROWSER_CDP !== anchor.cdpAddress) {
+        // The shared browser was restarted: only the attach address changes. The
+        // old stage daemon is still attached to the dead address, so close it first.
+        await closeBrowserSession(persisted, {
+            ...(support.runner !== undefined ? { runner: support.runner } : {}),
+            ...(support.closeWaitMs !== undefined ? { closeWaitMs: support.closeWaitMs } : {}),
+        }).catch(() => undefined);
+        if (persisted.AGENT_BROWSER_SOCKET_DIR !== undefined) {
+            await mkdir(persisted.AGENT_BROWSER_SOCKET_DIR, { recursive: true, mode: 0o700 });
+        }
+        env = { ...persisted, AGENT_BROWSER_CDP: anchor.cdpAddress };
+        await writeEnv(env);
+    }
+    if (persisted === undefined) {
+        await writeEnv(fresh);
+        if (browser.profile !== undefined) {
+            // TODO(multi-tenant): audit the run owner's scope.
+            await safeAudit(support.audit, {
+                event: "profile_used",
+                scope: LOCAL_BROWSER_SCOPE,
+                profile: browser.profile,
+                runId: input.runId,
+                stageId: input.stageId,
+            });
+        }
+    }
+    if (browser.profile !== undefined && (browser.allow_domains?.length ?? 0) > 0) {
+        await writeFile(path.join(dir, BROWSER_POLICY_FILENAME), `${JSON.stringify({
+            runId: input.runId,
+            stageId: input.stageId,
+            profile: browser.profile,
+            allow_domains: browser.allow_domains,
+        })}\n`, { mode: 0o600 });
+    }
+    await writeSessionOwner({
+        runId: input.runId,
+        stageId: input.stageId,
+        runDir: input.runDir,
+        env,
+    }).catch(() => undefined);
+    if (input.humanLogin === true) {
+        const url = input.resuming === true ? undefined : loginPageUrl(browser);
+        if (url !== undefined) {
+            const opened = await (support.runner ?? defaultBrowserRunner)(["open", url], env, {
+                timeoutMs: OPEN_COMMAND_TIMEOUT_MS,
+            });
+            if (opened.code !== 0) {
+                throw new Error(`could not open the login page ${url}`);
+            }
+        }
+    }
+    else if (browser.check !== undefined) {
+        await ensureStageLoginCheck({
+            runDir: input.runDir,
+            stageId: input.stageId,
+            attempt: input.attempt ?? 1,
+            env,
+            check: browser.check,
+            ...(support.runner !== undefined ? { runner: support.runner } : {}),
+            ...(support.loginCheck !== undefined ? { options: support.loginCheck } : {}),
+        });
+    }
+    return env;
+}

package/dist/browser/stageProfileLock.d.ts

@@ -0,0 +1,17 @@
+import type { StageBrowserSupport } from "./browserHost.js";
+import type { ProfileLock, ProfileLockOwner, RunLiveness } from "./profileLock.js";
+export declare function stageProfileLock(support: StageBrowserSupport): ProfileLock;
+export type ProfileWaitInput = {
+    profile: string;
+    owner: ProfileLockOwner;
+    isRunLive?: RunLiveness;
+    halted?: () => boolean;
+    /** Called when the holder is first seen or changes. */
+    onWaiting?: (holder: ProfileLockOwner) => Promise<void> | void;
+};
+/**
+ * Joins the run's lease on the profile, or takes it, waiting while another run
+ * holds it. The lease is released at run end, never at stage end.
+ */
+export declare function acquireStageProfile(support: StageBrowserSupport, input: ProfileWaitInput): Promise<"acquired" | "halted">;
+export declare function profileWaitingMessage(profile: string, holder: ProfileLockOwner): string;

package/dist/browser/stageProfileLock.js

@@ -0,0 +1,39 @@
+import { createLocalProfileLock } from "./localProfileLock.js";
+import { LOCAL_BROWSER_SCOPE } from "./profileStore.js";
+const DEFAULT_LOCK_POLL_MS = 250;
+let defaultLock;
+export function stageProfileLock(support) {
+    if (support.locks !== undefined)
+        return support.locks;
+    defaultLock ??= createLocalProfileLock();
+    return defaultLock;
+}
+/**
+ * Joins the run's lease on the profile, or takes it, waiting while another run
+ * holds it. The lease is released at run end, never at stage end.
+ */
+export async function acquireStageProfile(support, input) {
+    const locks = stageProfileLock(support);
+    // TODO(multi-tenant): take the scope from the run owner instead of the fixed local scope.
+    const key = { scope: LOCAL_BROWSER_SCOPE, name: input.profile };
+    const pollMs = support.lockPollMs ?? DEFAULT_LOCK_POLL_MS;
+    let announced;
+    for (;;) {
+        const result = await locks.acquire(key, input.owner);
+        if (result.status === "acquired")
+            return "acquired";
+        if (input.halted?.())
+            return "halted";
+        if (announced === undefined || announced.runId !== result.holder.runId) {
+            announced = result.holder;
+            await input.onWaiting?.(result.holder);
+        }
+        if (input.isRunLive !== undefined) {
+            await locks.reclaimStale(input.isRunLive).catch(() => 0);
+        }
+        await new Promise((r) => setTimeout(r, pollMs));
+    }
+}
+export function profileWaitingMessage(profile, holder) {
+    return `waiting for browser profile "${profile}" held by run ${holder.runId}`;
+}

package/dist/cli/browserCommand.d.ts

@@ -0,0 +1,44 @@
+import { type AuditSink } from "../browser/auditSink.js";
+import type { BrowserEnv, BrowserHost, BrowserRunner } from "../browser/browserHost.js";
+import { type DisplayProbe } from "../browser/humanLogin.js";
+import type { ProfileLock, RunLiveness } from "../browser/profileLock.js";
+import { type ProfileStore } from "../browser/profileStore.js";
+export declare const BROWSER_USAGE = "Usage:\n  sf browser profiles [--json]\n  sf browser status <name> [--json]\n  sf browser check <name> --url <url> --logged-in <glob> [--logged-out <glob>]... [--headless] [--json]\n  sf browser login <name> --url <login-url> --logged-in <glob> [--timeout-sec <n>] [--json]\n  sf browser clear <name> [--yes] [--json]\n\nManage saved browser logins (profiles) on this computer. Output never shows profile paths or cookie values.\nExit codes: 0 ok / logged in; 1 error; 2 profile in use by a live run; 3 logged out; 4 unknown; 5 login not completed (timeout or window closed); 130 interrupted.";
+export declare const BROWSER_EXIT: {
+    readonly ok: 0;
+    readonly error: 1;
+    readonly busy: 2;
+    readonly loggedOut: 3;
+    readonly unknown: 4;
+    readonly notCompleted: 5;
+    readonly interrupted: 130;
+};
+export type BrowserCommandDeps = {
+    log: (line: string) => void;
+    error: (line: string) => void;
+    store: ProfileStore;
+    host: BrowserHost;
+    locks: ProfileLock;
+    runner: BrowserRunner;
+    audit?: AuditSink;
+    /** Host-blocked sites; defaults to `browser.blocked_sites` from Host config. */
+    blockedSites?: readonly string[];
+    display: DisplayProbe;
+    /** Liveness of the run holding a profile lock. */
+    isRunLive: RunLiveness;
+    /** True when a daemon session for this env is open. */
+    sessionOpen: (env: BrowserEnv) => boolean;
+    /** profile name -> ISO time of last recorded use (from the audit log). */
+    auditLastUsed: () => Promise<Record<string, string>>;
+    confirm: (question: string) => Promise<boolean>;
+    interactive: boolean;
+    signal?: AbortSignal;
+    sleep: (ms: number) => Promise<void>;
+    closeWaitMs?: number;
+    loginCheck?: {
+        waitMs?: number;
+        settleMs?: number;
+    };
+    loginPollMs?: number;
+};
+export declare function runBrowserCommand(args: string[], deps?: Partial<BrowserCommandDeps>): Promise<number>;