stageflow 0.32.0 → 0.35.0

package/dist/browser/liveViewTickets.d.ts

@@ -0,0 +1,46 @@
+export type LiveViewMode = "view" | "control";
+export type LiveViewTarget = {
+    scope: string;
+    runId: string;
+    stageId: string;
+};
+export type LiveViewGrant = LiveViewTarget & {
+    mode: LiveViewMode;
+};
+export type LiveViewTicketRequest = LiveViewGrant & {
+    callerId?: string | null;
+};
+export type LiveViewCredential = LiveViewGrant & {
+    credential: string;
+    callerId: string | null;
+};
+export interface LiveViewTicketService {
+    /** One-use, short-lived; bound to scope, run, stage and mode. */
+    issue(request: LiveViewTicketRequest): {
+        ticket: string;
+        expiresAt: number;
+    };
+    /** Spends the ticket whatever the outcome; refused when unknown, expired, reused or for another target. */
+    redeem(ticket: string, target: LiveViewTarget): LiveViewCredential | undefined;
+    /** Looks up a live-view credential for the same target; undefined when unknown, expired or revoked. */
+    resolve(credential: string, target: LiveViewTarget): LiveViewCredential | undefined;
+    /** Invalidates tickets and credentials of one stage; `mode` limits it to that mode. */
+    revoke(runId: string, stageId: string, mode?: LiveViewMode): void;
+    /** Whether a live credential of the stage exists. */
+    hasCredentials(runId: string, stageId: string): boolean;
+    /** Invalidates tickets and credentials of every stage of a run. */
+    revokeRun(runId: string): void;
+    /** Invalidates every ticket and credential. */
+    revokeAll(): void;
+    /** Listeners receive the credentials that were just invalidated. */
+    onRevoked(listener: (credentials: readonly string[]) => void): () => void;
+}
+export declare const LIVE_VIEW_TICKET_TTL_MS = 60000;
+export declare const LIVE_VIEW_CREDENTIAL_TTL_MS: number;
+export type LiveViewTicketServiceOptions = {
+    now?: () => number;
+    randomToken?: () => string;
+    ticketTtlMs?: number;
+    credentialTtlMs?: number;
+};
+export declare function createLiveViewTicketService(options?: LiveViewTicketServiceOptions): LiveViewTicketService;

package/dist/browser/liveViewTickets.js

@@ -0,0 +1,122 @@
+import { randomBytes } from "node:crypto";
+export const LIVE_VIEW_TICKET_TTL_MS = 60_000;
+export const LIVE_VIEW_CREDENTIAL_TTL_MS = 24 * 60 * 60_000;
+function sameTarget(a, b) {
+    return a.scope === b.scope && a.runId === b.runId && a.stageId === b.stageId;
+}
+export function createLiveViewTicketService(options = {}) {
+    const now = options.now ?? Date.now;
+    const randomToken = options.randomToken ?? (() => randomBytes(32).toString("base64url"));
+    const ticketTtlMs = options.ticketTtlMs ?? LIVE_VIEW_TICKET_TTL_MS;
+    const credentialTtlMs = options.credentialTtlMs ?? LIVE_VIEW_CREDENTIAL_TTL_MS;
+    const tickets = new Map();
+    const credentials = new Map();
+    const listeners = new Set();
+    function sweep() {
+        const at = now();
+        for (const [key, entry] of tickets)
+            if (entry.expiresAt <= at)
+                tickets.delete(key);
+        for (const [key, entry] of credentials)
+            if (entry.expiresAt <= at)
+                credentials.delete(key);
+    }
+    function revokeWhere(matches) {
+        for (const [key, entry] of tickets)
+            if (matches(entry))
+                tickets.delete(key);
+        const revoked = [];
+        for (const [key, entry] of credentials) {
+            if (!matches(entry))
+                continue;
+            credentials.delete(key);
+            revoked.push(key);
+        }
+        if (revoked.length === 0)
+            return;
+        for (const listener of [...listeners]) {
+            try {
+                listener(revoked);
+            }
+            catch {
+                // a failing listener must not block revocation
+            }
+        }
+    }
+    return {
+        issue(request) {
+            sweep();
+            const ticket = randomToken();
+            const expiresAt = now() + ticketTtlMs;
+            tickets.set(ticket, {
+                scope: request.scope,
+                runId: request.runId,
+                stageId: request.stageId,
+                mode: request.mode,
+                callerId: request.callerId ?? null,
+                expiresAt,
+            });
+            return { ticket, expiresAt };
+        },
+        redeem(ticket, target) {
+            const entry = tickets.get(ticket);
+            if (entry === undefined)
+                return undefined;
+            tickets.delete(ticket);
+            if (entry.expiresAt <= now() || !sameTarget(entry, target))
+                return undefined;
+            const credential = randomToken();
+            credentials.set(credential, { ...entry, expiresAt: now() + credentialTtlMs });
+            return {
+                credential,
+                scope: entry.scope,
+                runId: entry.runId,
+                stageId: entry.stageId,
+                mode: entry.mode,
+                callerId: entry.callerId,
+            };
+        },
+        resolve(credential, target) {
+            const entry = credentials.get(credential);
+            if (entry === undefined)
+                return undefined;
+            if (entry.expiresAt <= now()) {
+                credentials.delete(credential);
+                return undefined;
+            }
+            if (!sameTarget(entry, target))
+                return undefined;
+            return {
+                credential,
+                scope: entry.scope,
+                runId: entry.runId,
+                stageId: entry.stageId,
+                mode: entry.mode,
+                callerId: entry.callerId,
+            };
+        },
+        revoke(runId, stageId, mode) {
+            revokeWhere((entry) => entry.runId === runId && entry.stageId === stageId && (mode === undefined || entry.mode === mode));
+        },
+        hasCredentials(runId, stageId) {
+            sweep();
+            for (const entry of credentials.values()) {
+                if (entry.runId === runId && entry.stageId === stageId)
+                    return true;
+            }
+            return false;
+        },
+        revokeRun(runId) {
+            revokeWhere((entry) => entry.runId === runId);
+        },
+        revokeAll() {
+            revokeWhere(() => true);
+        },
+        onRevoked(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+    };
+}

package/dist/browser/localBrowserHost.d.ts

@@ -1,10 +1,20 @@
 import { type BrowserHost } from "./browserHost.js";
+export declare const DENY_PERMISSION_PROMPTS_ARG = "--deny-permission-prompts";
 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;
+    /** `relay` only when the process also serves the live view routes; default `none`. */
+    liveView?: "relay" | "none";
+    /** Whether an Xvfb binary is installed; default searches `PATH` for an executable `Xvfb`. */
+    xvfbProbe?: () => boolean;
+    /** Host config `browser.launch_args`; applied only to sessions that launch Chrome, after the Host's own switches. */
+    launchArgs?: readonly string[];
+    /** Host config `browser.executable_path`; applied only to sessions that launch Chrome. */
+    executablePath?: string;
 };
+export declare function defaultXvfbProbe(platform?: NodeJS.Platform, hostEnv?: Record<string, string | undefined>): boolean;
 export declare function defaultSocketRoot(platform: NodeJS.Platform): string;
 export declare function createLocalBrowserHost(options?: LocalBrowserHostOptions): BrowserHost;

package/dist/browser/localBrowserHost.js

@@ -1,3 +1,4 @@
+import { accessSync, constants } from "node:fs";
 import { mkdir, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
@@ -5,7 +6,24 @@ import { globalStageflowHome } from "../project/globalHome.js";
 import { shortHash, } from "./browserHost.js";
 const MAX_SOCKET_PATH_BYTES = 103;
 const MAX_SESSION_NAME_LENGTH = 48;
+export const DENY_PERMISSION_PROMPTS_ARG = "--deny-permission-prompts";
+const HOST_LAUNCH_ARGS = [DENY_PERMISSION_PROMPTS_ARG];
 const DISPLAY_VARS = ["DISPLAY", "WAYLAND_DISPLAY", "XAUTHORITY"];
+export function defaultXvfbProbe(platform = process.platform, hostEnv = process.env) {
+    const dirs = (hostEnv.PATH ?? "").split(platform === "win32" ? ";" : ":");
+    for (const dir of dirs) {
+        if (dir === "")
+            continue;
+        try {
+            accessSync(path.join(dir, "Xvfb"), constants.X_OK);
+            return true;
+        }
+        catch {
+            continue;
+        }
+    }
+    return false;
+}
 export function defaultSocketRoot(platform) {
     const uid = typeof process.getuid === "function" ? process.getuid() : "u";
     const base = platform === "win32" ? os.tmpdir() : "/tmp";
@@ -24,14 +42,22 @@ function sessionNameForProfileStage(profile, runId, stageId) {
     return `${plain.slice(0, room)}-${suffix}`;
 }
 const OPEN_ANCHOR_TIMEOUT_MS = 60_000;
-function hasDisplay(platform, hostEnv) {
+function displayKind(platform, hostEnv, xvfbProbe) {
     if (platform !== "linux")
-        return true;
-    return Boolean(hostEnv.DISPLAY || hostEnv.WAYLAND_DISPLAY);
+        return "local_window";
+    if (hostEnv.DISPLAY || hostEnv.WAYLAND_DISPLAY)
+        return "local_window";
+    return xvfbProbe() ? "virtual_display" : "headless_only";
 }
 export function createLocalBrowserHost(options = {}) {
     const platform = options.platform ?? process.platform;
     const hostEnv = options.hostEnv ?? process.env;
+    const display = displayKind(platform, hostEnv, options.xvfbProbe ?? (() => defaultXvfbProbe(platform, hostEnv)));
+    const launchArgs = [
+        ...HOST_LAUNCH_ARGS,
+        ...(options.launchArgs ?? []).filter((arg) => !HOST_LAUNCH_ARGS.includes(arg)),
+    ];
+    const executablePath = options.executablePath;
     async function build(input) {
         const socketRoot = options.socketRoot ?? defaultSocketRoot(platform);
         const socketDir = path.join(socketRoot, shortHash(input.identity, 8));
@@ -52,7 +78,12 @@ export function createLocalBrowserHost(options = {}) {
             AGENT_BROWSER_CONFIG: emptyConfigPath,
         };
         input.set(env);
-        if (input.headed && platform === "linux") {
+        if (input.launches) {
+            env.AGENT_BROWSER_ARGS = launchArgs.join(",");
+            if (executablePath !== undefined)
+                env.AGENT_BROWSER_EXECUTABLE_PATH = executablePath;
+        }
+        if (input.headed && platform === "linux" && display === "local_window") {
             for (const name of DISPLAY_VARS) {
                 const value = hostEnv[name];
                 if (value)
@@ -63,16 +94,21 @@ export function createLocalBrowserHost(options = {}) {
     }
     function headedFor(request) {
         return (request.humanLogin === true ||
-            ((request.browser.headed ?? true) && hasDisplay(platform, hostEnv)));
+            ((request.browser.headed ?? true) && display !== "headless_only"));
     }
     async function profileBrowserEnv(request) {
         const { profile } = request;
+        const profileDir = profile.profileDir;
+        if (profileDir === undefined) {
+            throw new Error(`profile "${profile.key.name}" has no folder; the local browser host needs one`);
+        }
         return build({
-            identity: `profile:${profile.key.scope}/${profile.key.name}:${profile.profileDir}`,
+            identity: `profile:${profile.key.scope}/${profile.key.name}:${profileDir}`,
             session: sessionNameForProfile(profile.key.scope, profile.key.name),
             headed: headedFor(request),
+            launches: true,
             set: (env) => {
-                env.AGENT_BROWSER_PROFILE = profile.profileDir;
+                env.AGENT_BROWSER_PROFILE = profileDir;
             },
         });
     }
@@ -86,7 +122,15 @@ export function createLocalBrowserHost(options = {}) {
         }
         return address;
     }
+    const capabilities = {
+        display,
+        liveView: options.liveView ?? "none",
+        attach: "host_launched",
+        profilePersistence: "host_volume",
+        gracefulCloseRequired: true,
+    };
     return {
+        capabilities,
         async ensureProfileBrowser(request) {
             const wantHeaded = headedFor(request);
             let previous = request.previous;
@@ -130,6 +174,7 @@ export function createLocalBrowserHost(options = {}) {
                     identity: `stage:${request.runId}/${request.stageId}`,
                     session: sessionNameForProfileStage(profile, request.runId, request.stageId),
                     headed: headedFor(request),
+                    launches: false,
                     set: (env) => {
                         env.AGENT_BROWSER_CDP = cdp;
                         env.AGENT_BROWSER_PIN_TAB = "1";
@@ -141,6 +186,7 @@ export function createLocalBrowserHost(options = {}) {
                 identity,
                 session: `sf-t-${shortHash(identity, 12)}`,
                 headed: headedFor(request),
+                launches: true,
                 set: (env) => {
                     if (browser.allow_domains && browser.allow_domains.length > 0) {
                         env.AGENT_BROWSER_ALLOWED_DOMAINS = browser.allow_domains.join(",");

package/dist/browser/ownerScope.d.ts

@@ -0,0 +1,10 @@
+export type RunOwnerRef = {
+    runId: string;
+};
+/** Maps a run to the owner scope its profiles, leases, audit records, sandboxes and live view belong to. */
+export type OwnerScopeResolver = (run?: RunOwnerRef) => string;
+/** The only resolver today: every run belongs to the single local owner. */
+export declare const localOwnerScope: OwnerScopeResolver;
+export declare function runOwnerScope(support: {
+    ownerScope?: OwnerScopeResolver;
+}, run?: RunOwnerRef): string;

package/dist/browser/ownerScope.js

@@ -0,0 +1,6 @@
+import { LOCAL_BROWSER_SCOPE } from "./profileStore.js";
+/** The only resolver today: every run belongs to the single local owner. */
+export const localOwnerScope = () => LOCAL_BROWSER_SCOPE;
+export function runOwnerScope(support, run) {
+    return (support.ownerScope ?? localOwnerScope)(run);
+}

package/dist/browser/profileStore.d.ts

@@ -5,8 +5,11 @@ export interface ProfileKey {
 }
 export interface ProfileHandle {
     key: ProfileKey;
-    profileDir: string;
-    stateDir: string;
+    /** Folder of a Host-local profile; absent for a volume or provider profile. */
+    profileDir?: string;
+    stateDir?: string;
+    /** Provider-neutral reference of a volume profile; the orchestrator maps it to real storage. */
+    volumeRef?: string;
 }
 export interface ProfileStore {
     open(key: ProfileKey): Promise<ProfileHandle>;

package/dist/browser/profileStore.js

@@ -1,8 +1,6 @@
-// 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.
+// TODO(multi-tenant): this fixed scope is the single local owner. Only ownerScope.ts (`localOwnerScope`) and
+// tests read it; everything else takes a scope as input. A hosted service supplies an OwnerScopeResolver
+// from the authenticated user, never from YAML. See docs/browser-internals.md, "Multi-tenant to-do list".
 export const LOCAL_BROWSER_SCOPE = "local";
 export class InvalidProfileKeyError extends Error {
     code = "invalid_profile_key";

package/dist/browser/sandboxOrchestrator.d.ts

@@ -0,0 +1,60 @@
+export type SandboxLabels = {
+    scope: string;
+    runId: string;
+    stageId?: string;
+    profile?: string;
+};
+export type SandboxRef = {
+    /** Stable reference chosen by the adapter; opaque to the core. */
+    id: string;
+    /** The one place adapter data lives; only the issuing adapter reads it. */
+    adapter: {
+        id: string;
+        version: number;
+        data?: unknown;
+    };
+};
+/**
+ * Reserved seam for restricting what a sandbox may reach. No implementation
+ * enforces it yet; adapters that cannot enforce a policy must reject it with
+ * `not_supported` rather than ignore it. A hard `allow_domains` guarantee
+ * (private network plus filtering proxy) lands here later.
+ */
+export type SandboxEgressPolicy = {
+    allowDomains?: string[];
+    adapter?: {
+        id: string;
+        version: number;
+        data?: unknown;
+    };
+};
+export type SandboxStartRequest = {
+    labels: SandboxLabels;
+    profile?: {
+        scope: string;
+        name: string;
+    };
+    egress?: SandboxEgressPolicy;
+};
+export type SandboxStatus = "running" | "stopped" | "dead";
+export type SandboxInfo = {
+    ref: SandboxRef;
+    labels: SandboxLabels;
+    status: SandboxStatus;
+    /** Present while the sandbox is running. */
+    attachAddress?: string;
+};
+export type SandboxErrorClass = "unavailable" | "out_of_capacity" | "not_authorized" | "not_supported" | "failed";
+export declare class SandboxError extends Error {
+    readonly errorClass: SandboxErrorClass;
+    constructor(errorClass: SandboxErrorClass, message: string);
+}
+export interface BrowserSandboxOrchestrator {
+    start(request: SandboxStartRequest): Promise<SandboxInfo>;
+    /** Closes the browser cleanly (flushing profile state) without releasing the sandbox. */
+    stopGracefully(ref: SandboxRef): Promise<void>;
+    listByLabel(labels: Partial<SandboxLabels>): Promise<SandboxInfo[]>;
+    inspect(ref: SandboxRef): Promise<SandboxInfo | undefined>;
+    /** Idempotent: releasing an unknown or already released sandbox succeeds. */
+    release(ref: SandboxRef): Promise<void>;
+}

package/dist/browser/sandboxOrchestrator.js

@@ -0,0 +1,8 @@
+export class SandboxError extends Error {
+    errorClass;
+    constructor(errorClass, message) {
+        super(message);
+        this.errorClass = errorClass;
+        this.name = "SandboxError";
+    }
+}

package/dist/browser/sessionApiSandboxOrchestrator.d.ts

@@ -0,0 +1,34 @@
+import { type BrowserSandboxOrchestrator } from "./sandboxOrchestrator.js";
+export type SessionApiState = "active" | "flushed" | "failed";
+export type SessionApiSession = {
+    id: string;
+    state: SessionApiState;
+    connect_url?: string;
+    region: string;
+    metadata: Record<string, string>;
+};
+export type SessionApiFailure = "unauthorized" | "quota_exceeded" | "unavailable" | "rejected";
+export declare class SessionApiError extends Error {
+    readonly failure: SessionApiFailure;
+    constructor(failure: SessionApiFailure, message: string);
+}
+/**
+ * The HTTP session API a managed browser provider exposes, reduced to the five calls an
+ * orchestrator needs. A real provider adapter implements this against the vendor SDK; the
+ * tests record the calls and answer from memory.
+ */
+export interface SessionApiClient {
+    createSession(input: {
+        metadata: Record<string, string>;
+        persistContext?: string;
+    }): Promise<SessionApiSession>;
+    getSession(id: string): Promise<SessionApiSession | undefined>;
+    listSessions(): Promise<SessionApiSession[]>;
+    flushSession(id: string): Promise<void>;
+    deleteSession(id: string): Promise<void>;
+}
+export type SessionApiSandboxOrchestratorOptions = {
+    client: SessionApiClient;
+    adapterId?: string;
+};
+export declare function createSessionApiSandboxOrchestrator(options: SessionApiSandboxOrchestratorOptions): BrowserSandboxOrchestrator;

package/dist/browser/sessionApiSandboxOrchestrator.js

@@ -0,0 +1,108 @@
+import { SandboxError, } from "./sandboxOrchestrator.js";
+export class SessionApiError extends Error {
+    failure;
+    constructor(failure, message) {
+        super(message);
+        this.failure = failure;
+        this.name = "SessionApiError";
+    }
+}
+const ADAPTER_VERSION = 1;
+const LABEL_PREFIX = "stageflow.";
+const LABEL_KEYS = [
+    ["scope", "scope"],
+    ["runId", "run"],
+    ["stageId", "stage"],
+    ["profile", "profile"],
+];
+function toMetadata(labels) {
+    const metadata = {};
+    for (const [key, name] of LABEL_KEYS) {
+        const value = labels[key];
+        if (value !== undefined)
+            metadata[`${LABEL_PREFIX}${name}`] = value;
+    }
+    return metadata;
+}
+function fromMetadata(metadata) {
+    const labels = {};
+    for (const [key, name] of LABEL_KEYS) {
+        const value = metadata[`${LABEL_PREFIX}${name}`];
+        if (value !== undefined)
+            labels[key] = value;
+    }
+    return labels;
+}
+function statusOf(state) {
+    if (state === "active")
+        return "running";
+    return state === "flushed" ? "stopped" : "dead";
+}
+function mapError(err) {
+    if (err instanceof SandboxError)
+        return err;
+    if (err instanceof SessionApiError) {
+        const byFailure = {
+            unauthorized: "not_authorized",
+            quota_exceeded: "out_of_capacity",
+            unavailable: "unavailable",
+            rejected: "failed",
+        };
+        return new SandboxError(byFailure[err.failure], err.message);
+    }
+    return new SandboxError("failed", err instanceof Error ? err.message : String(err));
+}
+export function createSessionApiSandboxOrchestrator(options) {
+    const { client } = options;
+    const adapterId = options.adapterId ?? "session-api";
+    function infoOf(session) {
+        const status = statusOf(session.state);
+        return {
+            ref: { id: session.id, adapter: { id: adapterId, version: ADAPTER_VERSION, data: { region: session.region } } },
+            labels: fromMetadata(session.metadata),
+            status,
+            ...(status === "running" && session.connect_url !== undefined ? { attachAddress: session.connect_url } : {}),
+        };
+    }
+    async function guard(call) {
+        try {
+            return await call();
+        }
+        catch (err) {
+            throw mapError(err);
+        }
+    }
+    return {
+        async start(request) {
+            if (request.egress !== undefined) {
+                throw new SandboxError("not_supported", "this adapter cannot enforce an egress policy");
+            }
+            const session = await guard(() => client.createSession({
+                metadata: toMetadata(request.labels),
+                ...(request.profile !== undefined ? { persistContext: `${request.profile.scope}/${request.profile.name}` } : {}),
+            }));
+            return infoOf(session);
+        },
+        async stopGracefully(ref) {
+            await guard(async () => {
+                if ((await client.getSession(ref.id)) !== undefined)
+                    await client.flushSession(ref.id);
+            });
+        },
+        async listByLabel(labels) {
+            const wanted = toMetadata(labels);
+            const sessions = await guard(() => client.listSessions());
+            return sessions
+                .filter((s) => Object.entries(wanted).every(([key, value]) => s.metadata[key] === value))
+                .filter((s) => Object.keys(s.metadata).some((key) => key.startsWith(LABEL_PREFIX)))
+                .map(infoOf);
+        },
+        async inspect(ref) {
+            const session = await guard(() => client.getSession(ref.id));
+            return session === undefined ? undefined : infoOf(session);
+        },
+        async release(ref) {
+            await guard(() => client.deleteSession(ref.id));
+        },
+    };
+}

package/dist/browser/stageBrowserEnv.d.ts

@@ -2,7 +2,13 @@ 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 hostLaunchOptions(): {
+    launchArgs: string[];
+    executablePath?: string;
+};
 export declare function defaultStageBrowserSupport(): StageBrowserSupport;
+/** Browser support for a process that serves the live view routes (`sf ui`, `sf mcp`). */
+export declare function consoleStageBrowserSupport(): 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,
@@ -11,6 +17,7 @@ export declare function defaultStageBrowserSupport(): StageBrowserSupport;
 export declare function resolveStageBrowserEnv(support: StageBrowserSupport, input: {
     runId: string;
     stageId: string;
+    scope: string;
     runDir: string;
     browser: StageBrowserConfig | undefined;
     /** Attempt the login check result belongs to; defaults to 1. */