stageflow 0.27.0 → 0.31.0

package/dist/browser/persistedEnv.js

@@ -0,0 +1,15 @@
+import { readFile } from "node:fs/promises";
+/** Reads a persisted browser env; undefined when absent, throws on other I/O errors. */
+export async function readPersistedBrowserEnv(file) {
+    try {
+        const parsed = JSON.parse(await readFile(file, "utf8"));
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+            return parsed;
+        }
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            throw err;
+    }
+    return undefined;
+}

package/dist/browser/profileLock.d.ts

@@ -0,0 +1,40 @@
+import { type ProfileKey } from "./profileStore.js";
+/**
+ * A profile is leased to a run. `stageId` is informational (the stage that
+ * first took the lease) and never part of identity.
+ */
+export type ProfileLockOwner = {
+    runId: string;
+    stageId?: string;
+};
+export type ProfileLockAcquireResult = {
+    status: "acquired";
+    release(): Promise<void>;
+} | {
+    status: "queued";
+    holder: ProfileLockOwner;
+};
+export type RunLiveness = (runId: string) => Promise<boolean>;
+export interface ProfileLock {
+    /**
+     * Any stage of the holder run joins the lease and succeeds at once. A
+     * profile leased to another run returns `queued` with the holder; callers retry.
+     */
+    acquire(key: ProfileKey, owner: ProfileLockOwner): Promise<ProfileLockAcquireResult>;
+    holder(key: ProfileKey): Promise<ProfileLockOwner | undefined>;
+    /** Releases every lease held by this run (run end, cancel, abandon, failure). */
+    releaseOwner(owner: {
+        runId: string;
+    }): Promise<void>;
+    /** Drops locks whose holder run is no longer live; returns the count dropped. */
+    reclaimStale(isRunLive: RunLiveness): Promise<number>;
+}
+export type ProfileLockOptions = {
+    /** When set, `acquire` reclaims a lock whose holder run is not live. */
+    isRunLive?: RunLiveness;
+};
+export declare function sameOwner(a: ProfileLockOwner, b: ProfileLockOwner): boolean;
+export declare function lockKey(key: ProfileKey): ProfileKey;
+export declare function ownerMatches(held: ProfileLockOwner, target: {
+    runId: string;
+}): boolean;

package/dist/browser/profileLock.js

@@ -0,0 +1,10 @@
+import { validateProfileKey } from "./profileStore.js";
+export function sameOwner(a, b) {
+    return a.runId === b.runId;
+}
+export function lockKey(key) {
+    return validateProfileKey(key);
+}
+export function ownerMatches(held, target) {
+    return held.runId === target.runId;
+}

package/dist/browser/profileStore.d.ts

@@ -0,0 +1,23 @@
+export declare const LOCAL_BROWSER_SCOPE = "local";
+export interface ProfileKey {
+    scope: string;
+    name: string;
+}
+export interface ProfileHandle {
+    key: ProfileKey;
+    profileDir: string;
+    stateDir: string;
+}
+export interface ProfileStore {
+    open(key: ProfileKey): Promise<ProfileHandle>;
+    list(scope: string): Promise<string[]>;
+    delete(key: ProfileKey): Promise<void>;
+    deleteScope(scope: string): Promise<void>;
+}
+export declare class InvalidProfileKeyError extends Error {
+    readonly code = "invalid_profile_key";
+    constructor(message: string);
+}
+export declare function validateProfileName(name: unknown): string;
+export declare function validateProfileScope(scope: unknown): string;
+export declare function validateProfileKey(key: ProfileKey): ProfileKey;

package/dist/browser/profileStore.js

@@ -0,0 +1,39 @@
+// TODO(multi-tenant): this fixed scope is the single local owner. Callers import it instead of
+// receiving a scope from the run, so profiles, locks and CLI commands always use "local".
+// A hosted service must give every run an owner scope (set by the Host from the authenticated
+// user, never from YAML) and pass it down. Find every call site with: grep -rn "LOCAL_BROWSER_SCOPE" src
+// See docs/browser-internals.md, "Known limitations" item 3.
+export const LOCAL_BROWSER_SCOPE = "local";
+export class InvalidProfileKeyError extends Error {
+    code = "invalid_profile_key";
+    constructor(message) {
+        super(message);
+        this.name = "InvalidProfileKeyError";
+    }
+}
+const MAX_SEGMENT_LENGTH = 64;
+const SEGMENT_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+function validateSegment(label, value) {
+    if (typeof value !== "string" || value.length === 0) {
+        throw new InvalidProfileKeyError(`Profile ${label} must be a non-empty string`);
+    }
+    if (value.length > MAX_SEGMENT_LENGTH) {
+        throw new InvalidProfileKeyError(`Profile ${label} must be at most ${MAX_SEGMENT_LENGTH} characters`);
+    }
+    if (!SEGMENT_PATTERN.test(value) || value.includes("..")) {
+        throw new InvalidProfileKeyError(`Profile ${label} "${value}" may only use letters, digits, ".", "_" and "-", must start with a letter or digit, and must not contain ".."`);
+    }
+    return value;
+}
+export function validateProfileName(name) {
+    return validateSegment("name", name);
+}
+export function validateProfileScope(scope) {
+    return validateSegment("scope", scope);
+}
+export function validateProfileKey(key) {
+    return {
+        scope: validateProfileScope(key?.scope),
+        name: validateProfileName(key?.name),
+    };
+}

package/dist/browser/runLiveness.d.ts

@@ -0,0 +1,13 @@
+import type { RunStatus } from "../runstore/port.js";
+import type { RunLiveness } from "./profileLock.js";
+/**
+ * A run is live while it can still use its browser: not yet terminal. Runs
+ * waiting at a gate keep status "running", so they stay live.
+ */
+export declare function createRunLiveness(source: {
+    readRunMeta(runId: string): Promise<{
+        status?: RunStatus;
+    }>;
+}): RunLiveness;
+/** `cli-<pid>-...` runs are live while that process is; undefined for other run ids. */
+export declare function cliRunLive(runId: string): boolean | undefined;

package/dist/browser/runLiveness.js

@@ -0,0 +1,39 @@
+/**
+ * A run is live while it can still use its browser: not yet terminal. Runs
+ * waiting at a gate keep status "running", so they stay live.
+ */
+export function createRunLiveness(source) {
+    return async (runId) => {
+        const cli = cliRunLive(runId);
+        if (cli !== undefined)
+            return cli;
+        try {
+            const status = (await source.readRunMeta(runId)).status;
+            return (status === undefined ||
+                status === "created" ||
+                status === "queued" ||
+                status === "running");
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                return false;
+            if (/not found/i.test(String(err?.message)))
+                return false;
+            throw err;
+        }
+    };
+}
+/** `cli-<pid>-...` runs are live while that process is; undefined for other run ids. */
+export function cliRunLive(runId) {
+    const match = /^cli-(\d+)-/.exec(runId);
+    return match === null ? undefined : pidAlive(Number(match[1]));
+}
+function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === "EPERM";
+    }
+}

package/dist/browser/sitePolicy.d.ts

@@ -0,0 +1,10 @@
+import type { StageBrowserConfig } from "../types/stage.js";
+export declare class BlockedSiteError extends Error {
+    readonly code = "browser_site_blocked";
+    constructor(message: string);
+}
+export declare function normalizeDomain(raw: string): string;
+export declare function hostOf(urlOrHost: string): string | undefined;
+export declare function isBlockedHost(host: string, blocked: readonly string[]): string | undefined;
+/** Throws when the stage's allow_domains or check URLs touch a Host-blocked site. */
+export declare function assertBrowserSitesAllowed(stageId: string, browser: StageBrowserConfig, blocked: readonly string[]): void;

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>;