stageflow 0.25.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/artifactCommand.js

@@ -1,9 +1,9 @@
 import { writeFileSync } from "node:fs";
-import path from "node:path";
 import { readRunArtifact } from "../mcp/readArtifact.js";
 import { globalStageflowHome } from "../project/globalHome.js";
-import { createRunStore } from "../runstore/createStore.js";
-import { isInsideDir } from "../runstore/workspaceLayout.js";
+import { createRunStoreAfterHostEnsure, } from "../runstore/createStore.js";
+import { ensureGlobalService, } from "../server/ensureGlobalService.js";
+import { resolveSafeOutPath } from "./resolveSafeOutPath.js";
 export const ARTIFACT_USAGE = `Usage:
   sf artifact read --run <runId> --path <relPath> [--out <file>]`;
 const defaultIo = {
@@ -60,18 +60,6 @@ function parseArtifactArgs(args) {
     }
     return { help, subcommand, runId, artifactPath, outPath };
 }
-function resolveSafeOutPath(outPath, cwd) {
-    const segments = outPath.split(/[/\\]/);
-    if (segments.some((segment) => segment === "..")) {
-        throw new Error("path must not contain .. segments");
-    }
-    const resolved = path.resolve(cwd, outPath);
-    const cwdResolved = path.resolve(cwd);
-    if (!isInsideDir(resolved, cwdResolved)) {
-        throw new Error("output path must resolve under the current working directory");
-    }
-    return resolved;
-}
 export async function runArtifactCommand(args, options = {}) {
     const cwd = options.cwd ?? process.cwd();
     const out = { ...defaultIo, ...options.io };
@@ -99,7 +87,12 @@ export async function runArtifactCommand(args, options = {}) {
         out.error(ARTIFACT_USAGE);
         return 1;
     }
-    const store = createRunStore({ rootDir: globalStageflowHome() });
+    const opened = await createRunStoreAfterHostEnsure({ rootDir: globalStageflowHome() }, () => ensureGlobalService());
+    if (!opened.ok) {
+        out.error(opened.message);
+        return 1;
+    }
+    const store = opened.store;
     try {
         const contents = await readRunArtifact(store, parsed.runId, parsed.artifactPath);
         if (parsed.outPath !== undefined) {

package/dist/cli/backupCommand.d.ts

@@ -0,0 +1,9 @@
+export declare const BACKUP_USAGE = "Usage:\n  sf backup [--out <file>] [--db-only] [--no-credentials] [--include-a2a-artifacts] [--json]\n\nCreates a consistent snapshot of the Stageflow store. Default archives include\nprovider credentials (mode 0600) and must be treated as secrets.\nDefault --out is under $STAGEFLOW_HOME/backups/.";
+export type BackupCommandIo = {
+    log: (line: string) => void;
+    error: (line: string) => void;
+};
+export declare function runBackupCommand(args: string[], options?: {
+    cwd?: string;
+    io?: Partial<BackupCommandIo>;
+}): Promise<number>;

package/dist/cli/backupCommand.js

@@ -0,0 +1,111 @@
+import { globalStageflowHome } from "../project/globalHome.js";
+import { BackupError, createBackup, defaultBackupOutPath, } from "../runstore/backup.js";
+import { createRunStoreAfterHostEnsure, } from "../runstore/createStore.js";
+import { ensureGlobalService } from "../server/ensureGlobalService.js";
+export const BACKUP_USAGE = `Usage:
+  sf backup [--out <file>] [--db-only] [--no-credentials] [--include-a2a-artifacts] [--json]
+
+Creates a consistent snapshot of the Stageflow store. Default archives include
+provider credentials (mode 0600) and must be treated as secrets.
+Default --out is under $STAGEFLOW_HOME/backups/.`;
+const defaultIo = {
+    log: (line) => console.log(line),
+    error: (line) => console.error(line),
+};
+function parseBackupArgs(args) {
+    let help = false;
+    let outPath;
+    let dbOnly = false;
+    let noCredentials = false;
+    let includeA2aArtifacts = false;
+    let json = false;
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === "--help" || arg === "-h") {
+            help = true;
+        }
+        else if (arg === "--out") {
+            const value = args[++i];
+            if (value === undefined || value.length === 0) {
+                throw new Error("Missing value for --out");
+            }
+            outPath = value;
+        }
+        else if (arg === "--db-only") {
+            dbOnly = true;
+        }
+        else if (arg === "--no-credentials") {
+            noCredentials = true;
+        }
+        else if (arg === "--include-a2a-artifacts") {
+            includeA2aArtifacts = true;
+        }
+        else if (arg === "--json") {
+            json = true;
+        }
+        else if (arg?.startsWith("-")) {
+            throw new Error(`Unknown flag: ${arg}`);
+        }
+        else {
+            throw new Error(`Unexpected argument: ${arg}`);
+        }
+    }
+    return { help, outPath, dbOnly, noCredentials, includeA2aArtifacts, json };
+}
+export async function runBackupCommand(args, options = {}) {
+    const out = { ...defaultIo, ...options.io };
+    let parsed;
+    try {
+        parsed = parseBackupArgs(args);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        out.error(message);
+        out.error(BACKUP_USAGE);
+        return 1;
+    }
+    if (parsed.help) {
+        out.error(BACKUP_USAGE);
+        return 0;
+    }
+    const home = globalStageflowHome();
+    const opened = await createRunStoreAfterHostEnsure({ rootDir: home }, () => ensureGlobalService());
+    if (!opened.ok) {
+        out.error(opened.message);
+        return 1;
+    }
+    const store = opened.store;
+    try {
+        const result = await createBackup({
+            store,
+            homeDir: home,
+            outPath: parsed.outPath ??
+                defaultBackupOutPath(home, new Date(), parsed.dbOnly),
+            dbOnly: parsed.dbOnly,
+            noCredentials: parsed.noCredentials,
+            includeA2aArtifacts: parsed.includeA2aArtifacts,
+        });
+        if (!parsed.dbOnly && !parsed.noCredentials) {
+            out.error("warning: backup may contain provider credentials — treat the file as a secret");
+        }
+        if (parsed.json) {
+            out.log(JSON.stringify(result));
+        }
+        else {
+            out.log(`Wrote ${result.path} (${result.bytes} bytes, sha256=${result.sha256})`);
+        }
+        return 0;
+    }
+    catch (err) {
+        if (err instanceof BackupError) {
+            out.error(`${err.code}: ${err.message}`);
+            return 1;
+        }
+        const message = err instanceof Error ? err.message : String(err);
+        out.error(message);
+        return 1;
+    }
+    finally {
+        await store.close();
+    }
+}

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