stageflow 0.27.0 → 0.31.0

package/dist/agent/providerAuth.d.ts

@@ -25,12 +25,16 @@ export type ProvidersListResult = {
     via: "pi";
     providers: ProviderSummary[];
 };
-export type PiHomeDetectResult = {
-    piHomeUsable: boolean;
+export type ProvidersDetectResult = {
     credentialSource?: CredentialSource;
     provisional: boolean;
     source: CredentialSource;
+    authConfigured: boolean;
+    cursorSdkReady: boolean;
+    cursorApiKeyConfigured: boolean;
 };
+/** @deprecated Use ProvidersDetectResult */
+export type PiHomeDetectResult = ProvidersDetectResult;
 export type ProviderAuthRuntime = {
     getProviders(): readonly Provider[];
     getProvider(providerId: string): Provider | undefined;
@@ -84,7 +88,7 @@ export type OauthLoginResult = {
 };
 export declare function loginWithOauth(cwd: string, providerId: string, interaction: AuthInteraction, ctx?: ProviderAuthContext): Promise<OauthLoginResult>;
 export declare function logoutProvider(cwd: string, providerId: string, ctx?: ProviderAuthContext): Promise<ProviderAuthStatus>;
-export declare function detectPiHome(cwd: string): PiHomeDetectResult;
+export declare function detectPiHome(cwd: string): ProvidersDetectResult;
 export declare function getCredentialSourceSettings(cwd: string): {
     credentialSource?: CredentialSource;
     binding: {

package/dist/agent/providerAuth.js

@@ -1,5 +1,6 @@
 import { CredentialSynchronizationError, ModelRuntime, } from "@earendil-works/pi-coding-agent";
-import { isUsableAuthFile, parseCredentialSource, piHomeAuthPath, resolveCredentialBinding, writeCredentialSourceToContext, } from "../runtime/credentialBinding.js";
+import { parseCredentialSource, resolveCredentialBinding, writeCredentialSourceToContext, isUsableAuthFile, } from "../runtime/credentialBinding.js";
+import { getCursorHostStatus } from "./cursorProvider.js";
 import { readPersistedCredentialSourceFromContext, } from "../runtime/settingsFile.js";
 import { resolveProjectContext } from "../project/resolveProjectContext.js";
 export function makeMutationLock() {
@@ -251,10 +252,11 @@ export function detectPiHome(cwd) {
     const binding = resolveCredentialBinding(projectCtx);
     const persisted = readPersistedCredentialSourceFromContext(projectCtx);
     return {
-        piHomeUsable: isUsableAuthFile(piHomeAuthPath()),
         ...(persisted !== undefined ? { credentialSource: persisted } : {}),
         provisional: binding.provisional,
         source: binding.source,
+        authConfigured: isUsableAuthFile(binding.authPath),
+        ...getCursorHostStatus(),
     };
 }
 export function getCredentialSourceSettings(cwd) {
@@ -272,7 +274,7 @@ export function getCredentialSourceSettings(cwd) {
 export function setCredentialSource(cwd, credentialSource) {
     const parsed = parseCredentialSource(credentialSource);
     if (parsed === undefined) {
-        throw new ProviderAuthError('credentialSource must be "pi_home" or "sf_owned"', 400);
+        throw new ProviderAuthError('credentialSource must be "sf_owned"', 400);
     }
     const projectCtx = resolveProjectContext(cwd);
     writeCredentialSourceToContext(projectCtx, parsed);

package/dist/agent/streamLogRedact.d.ts

@@ -1,2 +1,8 @@
 /** Scrub secret-shaped substrings and registered values before text is persisted. */
 export declare function redactSecrets(text: string): string;
+/** Like redactSecrets plus cookie/storage/header shapes; for browser stages only. */
+export declare function redactBrowserSecrets(text: string): string;
+/** Tool/message previews of browser stages can carry cookie or token values. */
+export declare function redactBrowserActivityEvent<T extends {
+    event: string;
+}>(event: T): T;

package/dist/agent/streamLogRedact.js

@@ -1,6 +1,28 @@
-import { redactString } from "../logging/redact.js";
+import { BROWSER_STAGE_PATTERNS, redact, redactString, } from "../logging/redact.js";
 import { getNamedSecrets } from "../logging/namedSecrets.js";
 /** Scrub secret-shaped substrings and registered values before text is persisted. */
 export function redactSecrets(text) {
     return redactString(text, { namedSecrets: getNamedSecrets() });
 }
+/** Like redactSecrets plus cookie/storage/header shapes; for browser stages only. */
+export function redactBrowserSecrets(text) {
+    return redactString(text, {
+        patterns: BROWSER_STAGE_PATTERNS,
+        namedSecrets: getNamedSecrets(),
+    });
+}
+const BROWSER_REDACTED_EVENTS = new Set([
+    "message",
+    "tool_start",
+    "tool_end",
+    "tool_progress",
+]);
+/** Tool/message previews of browser stages can carry cookie or token values. */
+export function redactBrowserActivityEvent(event) {
+    if (!BROWSER_REDACTED_EVENTS.has(event.event))
+        return event;
+    return redact(event, {
+        patterns: BROWSER_STAGE_PATTERNS,
+        namedSecrets: getNamedSecrets(),
+    });
+}

package/dist/browser/anchor.d.ts

@@ -0,0 +1,27 @@
+import { type ProfileBrowser, type ProfileBrowserResult, type StageBrowserSupport } from "./browserHost.js";
+import type { ProfileHandle } from "./profileStore.js";
+import type { StageBrowserConfig } from "../types/stage.js";
+export declare const BROWSER_ANCHOR_FILENAME = "anchor.json";
+export type PersistedAnchor = ProfileBrowser & {
+    runId: string;
+    profile: string;
+    /** Bumped each time the anchor was replaced after the first start. */
+    restarts: number;
+};
+export declare function anchorDir(runDir: string, profileName: string): string;
+export declare function readPersistedAnchor(runDir: string, profileName: string): Promise<PersistedAnchor | undefined>;
+/**
+ * One shared browser per (run, profile). Concurrent callers in this process
+ * share one promise; other processes serialize on a lock dir. The anchor and
+ * its CDP address are persisted so stages, resume workers and the sweep reuse
+ * them; a dead anchor is restarted and the address refreshed.
+ */
+export declare function ensureRunProfileBrowser(support: StageBrowserSupport, input: {
+    runId: string;
+    runDir: string;
+    browser: StageBrowserConfig;
+    profile: ProfileHandle;
+    humanLogin?: boolean;
+}): Promise<ProfileBrowserResult & {
+    persisted: PersistedAnchor;
+}>;

package/dist/browser/anchor.js

@@ -0,0 +1,127 @@
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { defaultBrowserRunner, writeSessionOwner } from "./browserTeardown.js";
+export const BROWSER_ANCHOR_FILENAME = "anchor.json";
+const ANCHOR_LOCK_DIRNAME = "anchor.lock";
+const LOCK_POLL_MS = 25;
+const LOCK_WAIT_MS = 120_000;
+export function anchorDir(runDir, profileName) {
+    return path.join(runDir, "browser", profileName);
+}
+export async function readPersistedAnchor(runDir, profileName) {
+    try {
+        const parsed = JSON.parse(await readFile(path.join(anchorDir(runDir, profileName), BROWSER_ANCHOR_FILENAME), "utf8"));
+        if (typeof parsed.cdpAddress === "string" &&
+            parsed.anchorEnv !== undefined &&
+            typeof parsed.anchorEnv === "object") {
+            return parsed;
+        }
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            return undefined;
+    }
+    return undefined;
+}
+function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === "EPERM";
+    }
+}
+/** Cross-process mutex: atomic mkdir, stale when the recorded pid is gone. */
+async function withFileLock(dir, fn) {
+    await mkdir(dir, { recursive: true });
+    const lock = path.join(dir, ANCHOR_LOCK_DIRNAME);
+    const deadline = Date.now() + LOCK_WAIT_MS;
+    for (;;) {
+        try {
+            await mkdir(lock);
+            await writeFile(path.join(lock, "pid"), String(process.pid));
+            break;
+        }
+        catch (err) {
+            if (err.code !== "EEXIST")
+                throw err;
+            let holder = 0;
+            try {
+                holder = Number.parseInt(await readFile(path.join(lock, "pid"), "utf8"), 10);
+            }
+            catch {
+                // holder is between mkdir and pid write
+            }
+            if (holder > 0 && holder !== process.pid && !pidAlive(holder)) {
+                await rm(lock, { recursive: true, force: true });
+                continue;
+            }
+            if (Date.now() >= deadline)
+                throw new Error("timed out waiting for the shared browser lock");
+            await new Promise((r) => setTimeout(r, LOCK_POLL_MS));
+        }
+    }
+    try {
+        return await fn();
+    }
+    finally {
+        await rm(lock, { recursive: true, force: true }).catch(() => undefined);
+    }
+}
+const inflight = new Map();
+/**
+ * One shared browser per (run, profile). Concurrent callers in this process
+ * share one promise; other processes serialize on a lock dir. The anchor and
+ * its CDP address are persisted so stages, resume workers and the sweep reuse
+ * them; a dead anchor is restarted and the address refreshed.
+ */
+export function ensureRunProfileBrowser(support, input) {
+    const key = `${input.runDir}\0${input.profile.key.name}\0${input.humanLogin === true ? "h" : ""}`;
+    const existing = inflight.get(key);
+    if (existing !== undefined)
+        return existing;
+    const promise = withFileLock(anchorDir(input.runDir, input.profile.key.name), async () => {
+        const stored = await readPersistedAnchor(input.runDir, input.profile.key.name);
+        const result = await support.host.ensureProfileBrowser({
+            runId: input.runId,
+            browser: input.browser,
+            profile: input.profile,
+            runner: support.runner ?? defaultBrowserRunner,
+            ...(input.humanLogin === true ? { humanLogin: true } : {}),
+            ...(stored !== undefined
+                ? { previous: { cdpAddress: stored.cdpAddress, anchorEnv: stored.anchorEnv } }
+                : {}),
+        });
+        const changed = stored === undefined ||
+            stored.cdpAddress !== result.cdpAddress ||
+            JSON.stringify(stored.anchorEnv) !== JSON.stringify(result.anchorEnv);
+        const persisted = {
+            cdpAddress: result.cdpAddress,
+            anchorEnv: result.anchorEnv,
+            runId: input.runId,
+            profile: input.profile.key.name,
+            restarts: (stored?.restarts ?? 0) + (stored !== undefined && changed ? 1 : 0),
+        };
+        if (changed) {
+            const dir = anchorDir(input.runDir, input.profile.key.name);
+            const file = path.join(dir, BROWSER_ANCHOR_FILENAME);
+            const tmp = `${file}.${process.pid}.tmp`;
+            await writeFile(tmp, `${JSON.stringify(persisted, null, 2)}\n`, { mode: 0o600 });
+            await rename(tmp, file);
+            await writeSessionOwner({
+                runId: input.runId,
+                stageId: `anchor:${input.profile.key.name}`,
+                runDir: input.runDir,
+                env: result.anchorEnv,
+                anchor: true,
+                profile: input.profile.key.name,
+            }).catch(() => undefined);
+        }
+        return { ...result, restarted: stored !== undefined && changed, persisted };
+    }).finally(() => {
+        inflight.delete(key);
+    });
+    inflight.set(key, promise);
+    return promise;
+}

package/dist/browser/auditSink.d.ts

@@ -0,0 +1,38 @@
+/** Records carry names, ids and hosts only: never paths, URLs with queries, or cookie values. */
+export type AuditRecord = {
+    event: "profile_created";
+    scope: string;
+    profile: string;
+} | {
+    event: "profile_deleted";
+    scope: string;
+    profile: string;
+} | {
+    event: "profile_used";
+    scope: string;
+    profile: string;
+    runId: string;
+    stageId: string;
+} | {
+    event: "navigation_outside_allowlist";
+    runId: string;
+    stageId: string;
+    profile?: string;
+    host: string;
+} | {
+    event: "allowlist_unverified";
+    runId: string;
+    stageId: string;
+    profile?: string;
+    reason: string;
+};
+export interface AuditSink {
+    record(entry: AuditRecord): Promise<void>;
+}
+export declare function localAuditLogPath(): string;
+export declare function createLocalAuditSink(file?: string): AuditSink;
+export declare function createMemoryAuditSink(): AuditSink & {
+    records: AuditRecord[];
+};
+/** Audit must never break a run. */
+export declare function safeAudit(sink: AuditSink | undefined, entry: AuditRecord): Promise<void>;

package/dist/browser/auditSink.js

@@ -0,0 +1,34 @@
+import { appendFile, chmod, mkdir } from "node:fs/promises";
+import path from "node:path";
+import { globalStageflowHome } from "../project/globalHome.js";
+export function localAuditLogPath() {
+    return path.join(globalStageflowHome(), "browser", "audit.jsonl");
+}
+export function createLocalAuditSink(file) {
+    return {
+        async record(entry) {
+            const target = file ?? localAuditLogPath();
+            await mkdir(path.dirname(target), { recursive: true, mode: 0o700 });
+            await appendFile(target, `${JSON.stringify({ at: new Date().toISOString(), ...entry })}\n`, { mode: 0o600 });
+            await chmod(target, 0o600).catch(() => undefined);
+        },
+    };
+}
+export function createMemoryAuditSink() {
+    const records = [];
+    return {
+        records,
+        async record(entry) {
+            records.push(entry);
+        },
+    };
+}
+/** Audit must never break a run. */
+export async function safeAudit(sink, entry) {
+    try {
+        await (sink ?? createLocalAuditSink()).record(entry);
+    }
+    catch {
+        // best-effort
+    }
+}

package/dist/browser/browserHost.d.ts

@@ -0,0 +1,86 @@
+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";
+export type BrowserEnv = Record<string, string>;
+export type BrowserStageRequest = {
+    runId: string;
+    stageId: string;
+    browser: StageBrowserConfig;
+    profile?: ProfileHandle;
+    /** A human must see and use this browser; headless fallback does not apply. */
+    humanLogin?: boolean;
+    /** Required for a stage with a profile: the shared browser's CDP address. */
+    cdpAddress?: string;
+};
+/** The shared browser of one (run, profile): its CDP address and the env that owns it. */
+export type ProfileBrowser = {
+    cdpAddress: string;
+    anchorEnv: BrowserEnv;
+};
+export type ProfileBrowserRequest = {
+    runId: string;
+    browser: StageBrowserConfig;
+    profile: ProfileHandle;
+    humanLogin?: boolean;
+    runner: BrowserRunner;
+    /** Persisted anchor from an earlier call; reused when still alive, else restarted. */
+    previous?: ProfileBrowser;
+};
+export type ProfileBrowserResult = ProfileBrowser & {
+    /** True when a previous anchor existed but its address changed or it was replaced. */
+    restarted: boolean;
+};
+export interface BrowserHost {
+    /**
+     * 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>;
+    /** 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`). */
+    profileBrowserEnv(request: Omit<BrowserStageRequest, "stageId" | "cdpAddress"> & {
+        profile: ProfileHandle;
+    }): Promise<BrowserEnv>;
+}
+/** Runs `agent-browser <args>` with exactly `env` (plus PATH). Injectable for tests. */
+export type BrowserRunner = (args: string[], env: BrowserEnv, 
+/** Per-call limit; the default runner allows 20 s. */
+options?: {
+    timeoutMs?: number;
+}) => Promise<{
+    code: number | null;
+    stdout?: string;
+}>;
+export type StageBrowserSupport = {
+    host: BrowserHost;
+    profiles: ProfileStore;
+    runner?: BrowserRunner;
+    /** Profile lock; defaults to the local lock-file implementation. */
+    locks?: ProfileLock;
+    /** Poll interval while a stage waits for a busy profile. */
+    lockPollMs?: number;
+    /** Upper bound for waiting on the daemon to exit after `close`. */
+    closeWaitMs?: number;
+    /** Login-check bounds; defaults suit real browsers. */
+    loginCheck?: {
+        waitMs?: number;
+        settleMs?: number;
+    };
+    /** Root holding per-session socket dirs; defaults to the local host's root. */
+    socketRoot?: string;
+    /** Defaults to the local audit log in the Stageflow home. */
+    audit?: AuditSink;
+    /** 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. */
+    display?: () => {
+        hasDisplay: boolean;
+        docker: boolean;
+    };
+};
+export declare const BROWSER_ENV_PREFIX = "AGENT_BROWSER_";
+export declare function shortHash(value: string, length: number): string;
+export declare const BROWSER_ENV_FILENAME = "browser-env.json";
+export declare const BROWSER_POLICY_FILENAME = "browser-policy.json";

package/dist/browser/browserHost.js

@@ -0,0 +1,7 @@
+import { createHash } from "node:crypto";
+export const BROWSER_ENV_PREFIX = "AGENT_BROWSER_";
+export function shortHash(value, length) {
+    return createHash("sha256").update(value).digest("hex").slice(0, length);
+}
+export const BROWSER_ENV_FILENAME = "browser-env.json";
+export const BROWSER_POLICY_FILENAME = "browser-policy.json";

package/dist/browser/browserSweep.d.ts

@@ -0,0 +1,14 @@
+import type { BrowserRunner } from "./browserHost.js";
+export type BrowserSweepOptions = {
+    isRunLive: (runId: string) => Promise<boolean>;
+    socketRoot?: string;
+    runner?: BrowserRunner;
+    closeWaitMs?: number;
+};
+/**
+ * At Host start: close sessions whose run is gone or terminal, clean leftover
+ * files, and leave sessions of live or waiting runs alone.
+ */
+export declare function sweepOrphanBrowserSessions(options: BrowserSweepOptions): Promise<{
+    closed: string[];
+}>;

package/dist/browser/browserSweep.js

@@ -0,0 +1,54 @@
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import { BROWSER_OWNER_FILENAME, closeBrowserSession, } from "./browserTeardown.js";
+import { defaultSocketRoot } from "./localBrowserHost.js";
+import { rmdir } from "node:fs/promises";
+async function readOwner(dir) {
+    try {
+        const parsed = JSON.parse(await readFile(path.join(dir, BROWSER_OWNER_FILENAME), "utf8"));
+        if (typeof parsed.runId === "string" && parsed.env?.AGENT_BROWSER_SESSION) {
+            return parsed;
+        }
+    }
+    catch {
+        // unreadable owner: treated as ownerless below
+    }
+    return undefined;
+}
+/**
+ * At Host start: close sessions whose run is gone or terminal, clean leftover
+ * files, and leave sessions of live or waiting runs alone.
+ */
+export async function sweepOrphanBrowserSessions(options) {
+    const root = options.socketRoot ?? defaultSocketRoot(process.platform);
+    const closed = [];
+    let dirs;
+    try {
+        dirs = await readdir(root);
+    }
+    catch {
+        return { closed };
+    }
+    const owners = [];
+    for (const name of dirs) {
+        const owner = await readOwner(path.join(root, name));
+        if (owner !== undefined)
+            owners.push(owner);
+    }
+    // Stage sessions attach to the anchor, so they go first.
+    owners.sort((x, y) => Number(x.anchor === true) - Number(y.anchor === true));
+    for (const owner of owners) {
+        if (await options.isRunLive(owner.runId).catch(() => true))
+            continue;
+        const { gone } = await closeBrowserSession(owner.env, {
+            ...(options.runner !== undefined ? { runner: options.runner } : {}),
+            ...(options.closeWaitMs !== undefined
+                ? { closeWaitMs: options.closeWaitMs }
+                : {}),
+        });
+        if (gone)
+            closed.push(owner.env.AGENT_BROWSER_SESSION);
+    }
+    await rmdir(root).catch(() => undefined);
+    return { closed };
+}

package/dist/browser/browserTeardown.d.ts

@@ -0,0 +1,56 @@
+import type { StageLogEvent } from "../runstore/port.js";
+import { type BrowserEnv, type BrowserRunner, type StageBrowserSupport } from "./browserHost.js";
+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 type BrowserSessionOwner = {
+    runId: string;
+    stageId: string;
+    runDir: string;
+    env: BrowserEnv;
+    /** The run's shared browser for `profile`; stage sessions attach to it. */
+    anchor?: true;
+    profile?: string;
+};
+export declare const defaultBrowserRunner: BrowserRunner;
+export declare function writeSessionOwner(owner: BrowserSessionOwner): Promise<void>;
+/**
+ * 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.
+ */
+export declare function closeBrowserSession(env: BrowserEnv, options?: {
+    runner?: BrowserRunner;
+    closeWaitMs?: number;
+}): Promise<{
+    gone: boolean;
+}>;
+/**
+ * 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 declare function teardownStageBrowser(support: StageBrowserSupport, input: StageTeardownInput): Promise<void>;
+type StageEvents = () => Promise<StageLogEvent[]>;
+type StageTeardownInput = {
+    runId: string;
+    runDir: string;
+    stageId: string;
+    /** Reads the stage's persisted tool activity for the soft allowlist audit. */
+    events?: StageEvents;
+};
+/** Gracefully closes every anchor browser the run started. */
+export declare function closeRunAnchors(support: StageBrowserSupport, run: {
+    runDir: string;
+}): Promise<void>;
+/**
+ * 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 declare function teardownRunBrowsers(support: StageBrowserSupport, run: {
+    runId: string;
+    runDir: string;
+    events?: (stageId: string) => Promise<StageLogEvent[]>;
+}, only?: (stageId: string) => boolean): Promise<void>;
+export {};