@webcrawl/mcp 1.4.2 → 1.4.4

package/dist/core/interact/driver.js

@@ -0,0 +1,384 @@
+/**
+ * Browser driver for interact runs. Node-only: called from workflow steps.
+ *
+ * Two backends share one step runner (STEP_SCRIPT):
+ * - sandbox: Chromium inside a Vercel Sandbox, reached by sandboxId so any
+ *   step invocation (on any function instance) can reattach.
+ * - local:   Chromium on this machine for dev (INTERACT_LOCAL_PLAYWRIGHT=true).
+ *            Only works while steps run in the same long-lived process
+ *            (Local World / `next dev`).
+ */
+import { execFile, spawn } from "node:child_process";
+import { existsSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { Sandbox } from "@vercel/sandbox";
+import { CDP_PORT, SETUP_SCRIPT, STEP_SCRIPT, STEP_SCRIPT_PATH, VM_ROOT, WAIT_FOR_CDP_SCRIPT, chromeArgs, parseStepOutput, } from "./vm.js";
+import { startRemoteSession, stopRemoteSession } from "./remote.js";
+import { WARM_SANDBOX_TIMEOUT_MS, WARM_TTL_MS } from "../engine/session.js";
+const snapshotId = () => process.env.WEBCRAWL_INTERACT_SNAPSHOT_ID || process.env.INTERACT_SNAPSHOT_ID || "";
+const localMode = () => process.env.INTERACT_LOCAL_PLAYWRIGHT === "true";
+/**
+ * True when some browser backend can run. Checked before starting a run so we never fake success.
+ * On Vercel (VERCEL=1) the OIDC token is not in env at request time: it arrives in the
+ * `x-vercel-oidc-token` request header, which @vercel/sandbox reads via @vercel/oidc.
+ */
+export function interactBrowserAvailable() {
+    if (localMode())
+        return true;
+    return Boolean(process.env.VERCEL === "1" ||
+        process.env.VERCEL_OIDC_TOKEN ||
+        (process.env.VERCEL_TOKEN && process.env.VERCEL_TEAM_ID && process.env.VERCEL_PROJECT_ID));
+}
+export function interactBackend() {
+    if (localMode())
+        return "local";
+    return interactBrowserAvailable() ? "sandbox" : "none";
+}
+/* ----------------------------- sandbox backend ---------------------------- */
+async function sh(sandbox, script, sudo = true) {
+    const r = await sandbox.runCommand({ cmd: "bash", args: ["-lc", script], sudo });
+    return { exitCode: r.exitCode, stdout: await r.stdout(), stderr: await r.stderr() };
+}
+const SANDBOX_RESOURCES = { vcpus: 2 };
+/**
+ * Boots from the prebuilt snapshot (Chromium + Playwright already installed,
+ * see scripts/build-interact-snapshot.ts). If the snapshot is unset, expired
+ * or deleted, falls back to a cold VM and runs the full setup.
+ */
+async function createBrowserSandbox(timeoutMs) {
+    const snap = snapshotId();
+    if (snap) {
+        try {
+            const sandbox = await Sandbox.create({
+                source: { type: "snapshot", snapshotId: snap },
+                timeout: timeoutMs,
+                resources: SANDBOX_RESOURCES,
+            });
+            return { sandbox, fromSnapshot: true };
+        }
+        catch (err) {
+            console.warn("[interact] snapshot boot failed, using cold setup", {
+                snapshotId: snap,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    const sandbox = await Sandbox.create({ runtime: "node22", timeout: timeoutMs, resources: SANDBOX_RESOURCES });
+    return { sandbox, fromSnapshot: false };
+}
+async function startSandboxBrowser(opts) {
+    const { sandbox, fromSnapshot } = await createBrowserSandbox(opts.timeoutMs);
+    try {
+        if (!fromSnapshot) {
+            const setup = await sh(sandbox, SETUP_SCRIPT);
+            if (setup.exitCode !== 0)
+                throw new Error(`Browser setup failed: ${(setup.stderr || setup.stdout).slice(-300)}`);
+        }
+        // Always write the current step runner so a snapshot built from older code
+        // never runs a stale copy. It is a few KB, so this costs one round trip.
+        await sandbox.writeFiles([{ path: STEP_SCRIPT_PATH, content: Buffer.from(STEP_SCRIPT) }]);
+        const exe = (await sh(sandbox, `cat ${VM_ROOT}/chrome-path`)).stdout.trim().split("\n").pop();
+        if (!exe)
+            throw new Error("Browser binary not found in sandbox");
+        await sandbox.runCommand({ cmd: exe, args: chromeArgs({ userAgent: opts.userAgent, proxy: opts.proxy }), detached: true, sudo: true });
+        const ready = await sh(sandbox, WAIT_FOR_CDP_SCRIPT, false);
+        if (ready.exitCode !== 0)
+            throw new Error("Browser did not start");
+        return { kind: "sandbox", sandboxId: sandbox.sandboxId };
+    }
+    catch (err) {
+        await sandbox.stop().catch(() => { });
+        throw err;
+    }
+}
+/** True when the sandbox's Chromium still answers on CDP (warm reconnect check). */
+async function sandboxChromeAlive(sandbox) {
+    const ping = await sh(sandbox, `curl -sf -m 3 http://127.0.0.1:${CDP_PORT}/json/version >/dev/null && echo alive`, false);
+    return ping.exitCode === 0 && ping.stdout.includes("alive");
+}
+/**
+ * Warm reconnect: fetch the sandbox this domain solved its challenge in, verify
+ * Chromium still lives, and reuse it (same IP, same UA, same cleared cookies).
+ * Returns null when no warm entry exists or the sandbox is gone (cold boot).
+ */
+async function startWarmSandboxBrowser(domain) {
+    if (!domain)
+        return null;
+    const { getWarmSession } = await import("../engine/session.js");
+    let warm;
+    try {
+        warm = await getWarmSession(domain);
+    }
+    catch {
+        return null;
+    }
+    if (!warm || !warm.sandboxId)
+        return null;
+    try {
+        const sandbox = await Sandbox.get({ sandboxId: warm.sandboxId });
+        if (!(await sandboxChromeAlive(sandbox))) {
+            await sandbox.stop().catch(() => { });
+            return null;
+        }
+        // Refresh the step runner in case this instance ships newer code.
+        await sandbox.writeFiles([{ path: STEP_SCRIPT_PATH, content: Buffer.from(STEP_SCRIPT) }]).catch(() => { });
+        console.info("[stealth] warm reconnect", { domain, sandboxId: warm.sandboxId });
+        return { kind: "sandbox", sandboxId: warm.sandboxId };
+    }
+    catch {
+        return null;
+    }
+}
+/* ------------------------------ local backend ----------------------------- */
+/**
+ * Path to a real, user-installed Chrome when one exists, else null.
+ * Anti-bot vendors (DataDome, Akamai) fingerprint the automation build of
+ * Chromium and serve degraded pages to it, while the same engine driving a
+ * real installed Chrome gets full content — practitioner reports confirm
+ * this on DataDome-protected sites. Priority: explicit env override, then
+ * the standard per-OS install locations.
+ */
+export function installedChromePath() {
+    if (process.env.INTERACT_CHROME_PATH)
+        return process.env.INTERACT_CHROME_PATH;
+    const candidates = [];
+    if (process.platform === "darwin") {
+        candidates.push("/Applications/Google Chrome.app/Contents/MacOS/Google Chrome", `${process.env.HOME || ""}/Applications/Google Chrome.app/Contents/MacOS/Google Chrome`);
+    }
+    else if (process.platform === "win32") {
+        candidates.push(`${process.env["ProgramFiles"] || "C:\\Program Files"}\\Google\\Chrome\\Application\\chrome.exe`, `${process.env["ProgramFiles(x86)"] || "C:\\Program Files (x86)"}\\Google\\Chrome\\Application\\chrome.exe`);
+    }
+    else {
+        candidates.push("/usr/bin/google-chrome", "/usr/bin/google-chrome-stable", "/usr/bin/chromium-browser", "/usr/bin/chromium", "/snap/bin/chromium");
+    }
+    for (const p of candidates) {
+        try {
+            if (existsSync(p))
+                return p;
+        }
+        catch {
+            /* not installed here */
+        }
+    }
+    return null;
+}
+async function resolveLocalPlaywright() {
+    const candidates = [
+        process.env.WC_PLAYWRIGHT,
+        path.join(process.cwd(), "node_modules/playwright/index.mjs"),
+        path.join(process.cwd(), "../node_modules/playwright/index.mjs"),
+    ].filter(Boolean);
+    for (const p of candidates) {
+        try {
+            const mod = (await import(/* webpackIgnore: true */ p));
+            // Prefer a real installed Chrome over playwright's bundled automation
+            // Chromium (see installedChromePath); fall back to the bundle when the
+            // host has no Chrome (CI, containers, minimal servers).
+            const chrome = installedChromePath() || mod.chromium.executablePath();
+            return { playwright: p, chrome };
+        }
+        catch {
+            /* try next */
+        }
+    }
+    throw new Error("Local browser unavailable: install playwright or set WC_PLAYWRIGHT");
+}
+async function startLocalBrowser(opts) {
+    const { playwright, chrome } = await resolveLocalPlaywright();
+    const port = 9300 + Math.floor(Math.random() * 600);
+    const dir = mkdtempSync(path.join(tmpdir(), "wc-interact-"));
+    const args = chromeArgs({ userAgent: opts.userAgent, proxy: opts.proxy })
+        .map((a) => (a.startsWith("--remote-debugging-port=") ? `--remote-debugging-port=${port}` : a))
+        .map((a) => (a.startsWith("--user-data-dir=") ? `--user-data-dir=${dir}/profile` : a));
+    args.unshift("--disable-crash-reporter", "--disable-breakpad");
+    const child = spawn(chrome, args, { detached: true, stdio: "ignore" });
+    child.unref();
+    const cdp = `http://127.0.0.1:${port}`;
+    // A cold first launch (new profile) can take over 10s on macOS.
+    for (let i = 0; i < 75; i++) {
+        try {
+            const r = await fetch(`${cdp}/json/version`);
+            if (r.ok)
+                break;
+        }
+        catch {
+            /* not up yet */
+        }
+        if (i === 74) {
+            try {
+                process.kill(child.pid);
+            }
+            catch { /* gone */ }
+            throw new Error("Local browser did not start");
+        }
+        await new Promise((r) => setTimeout(r, 200));
+    }
+    const scriptPath = path.join(dir, "step.mjs");
+    writeFileSync(scriptPath, STEP_SCRIPT);
+    return { kind: "local", cdp, pid: child.pid, scriptPath, playwright };
+}
+/* ------------------------------ remote backend ---------------------------- */
+/**
+ * A place to run STEP_SCRIPT without starting Chromium: the provider hosts the
+ * browser. Local Playwright when installed (dev), else a sandbox VM.
+ */
+async function startStepRunner(timeoutMs) {
+    if (localMode()) {
+        const { playwright } = await resolveLocalPlaywright();
+        const dir = mkdtempSync(path.join(tmpdir(), "wc-remote-"));
+        const scriptPath = path.join(dir, "step.mjs");
+        writeFileSync(scriptPath, STEP_SCRIPT);
+        return { kind: "local", scriptPath, playwright };
+    }
+    const { sandbox, fromSnapshot } = await createBrowserSandbox(timeoutMs);
+    try {
+        if (!fromSnapshot) {
+            const setup = await sh(sandbox, SETUP_SCRIPT);
+            if (setup.exitCode !== 0)
+                throw new Error(`Step runner setup failed: ${(setup.stderr || setup.stdout).slice(-300)}`);
+        }
+        await sandbox.writeFiles([{ path: STEP_SCRIPT_PATH, content: Buffer.from(STEP_SCRIPT) }]);
+        return { kind: "sandbox", sandboxId: sandbox.sandboxId };
+    }
+    catch (err) {
+        await sandbox.stop().catch(() => { });
+        throw err;
+    }
+}
+async function startRemoteBrowser(provider, timeoutMs) {
+    // Both start in parallel; the provider bills from session start, so stop it if the runner fails.
+    const [session, runner] = await Promise.allSettled([startRemoteSession({ provider, timeoutMs }), startStepRunner(timeoutMs)]);
+    if (session.status === "fulfilled" && runner.status === "fulfilled") {
+        const s = session.value;
+        return {
+            kind: "remote",
+            provider,
+            sessionId: s.sessionId,
+            cdpUrl: s.cdpUrl,
+            ...(s.cdpHeaders ? { cdpHeaders: s.cdpHeaders } : {}),
+            startedAt: s.startedAt,
+            runner: runner.value,
+        };
+    }
+    if (session.status === "fulfilled")
+        await stopRemoteSession(session.value);
+    if (runner.status === "fulfilled")
+        await stopRunner(runner.value);
+    const reason = session.status === "rejected" ? session.reason : runner.reason;
+    throw reason instanceof Error ? reason : new Error(String(reason));
+}
+async function stopRunner(runner) {
+    if (runner.kind === "local")
+        return;
+    try {
+        const sandbox = await Sandbox.get({ sandboxId: runner.sandboxId });
+        await sandbox.stop();
+    }
+    catch {
+        /* already stopped or expired */
+    }
+}
+/* --------------------------------- public --------------------------------- */
+export async function startBrowser(opts = {}) {
+    if (opts.remote)
+        return startRemoteBrowser(opts.remote, opts.timeoutMs ?? 5 * 60_000);
+    if (localMode())
+        return startLocalBrowser(opts);
+    if (!interactBrowserAvailable())
+        throw new Error("browser_unavailable");
+    // Warm reconnect first: a sandbox that already solved this domain's bot check
+    // keeps its IP / UA / cleared cookies — reusing it skips boot + re-solve.
+    // Never warm-reconnect when proxying: the warm sandbox egresses direct.
+    if (opts.domain && !opts.proxy) {
+        const warm = await startWarmSandboxBrowser(opts.domain).catch(() => null);
+        if (warm)
+            return warm;
+    }
+    return startSandboxBrowser({
+        // Long VM timeout headroom so the sandbox can stay warm after this call.
+        timeoutMs: Math.max(opts.timeoutMs ?? 5 * 60_000, WARM_SANDBOX_TIMEOUT_MS),
+        userAgent: opts.userAgent,
+        proxy: opts.proxy,
+    });
+}
+function runLocalStep(scriptPath, playwright, cdp, action, extraEnv = {}) {
+    return new Promise((resolve) => {
+        execFile(process.execPath, [scriptPath, JSON.stringify(action)], {
+            env: { ...process.env, WC_PLAYWRIGHT: playwright, WC_CDP: cdp, ...extraEnv },
+            // A stealth fetchMany reads many documents in one step.
+            timeout: action.type === "fetchMany" ? 300_000 : 45_000,
+            maxBuffer: 16 * 1024 * 1024,
+        }, (_err, stdout, stderr) => resolve(parseStepOutput(String(stdout ?? ""), String(stderr ?? ""))));
+    });
+}
+async function runSandboxStep(sandboxId, action, env) {
+    const sandbox = await Sandbox.get({ sandboxId });
+    const r = await sandbox.runCommand({ cmd: "node", args: [STEP_SCRIPT_PATH, JSON.stringify(action)], sudo: true, ...(env ? { env } : {}) });
+    return parseStepOutput(await r.stdout(), await r.stderr());
+}
+export async function runBrowserStep(handle, action) {
+    if (handle.kind === "local")
+        return runLocalStep(handle.scriptPath, handle.playwright, handle.cdp, action);
+    if (handle.kind === "remote") {
+        // The provider's browser carries its own fingerprint; overriding it would undo that.
+        const remoteAction = { ...action, keepFingerprint: true, lightweight: true };
+        const headerEnv = handle.cdpHeaders ? { WC_CDP_HEADERS: JSON.stringify(handle.cdpHeaders) } : {};
+        return handle.runner.kind === "local"
+            ? runLocalStep(handle.runner.scriptPath, handle.runner.playwright, handle.cdpUrl, remoteAction, headerEnv)
+            : runSandboxStep(handle.runner.sandboxId, remoteAction, { WC_CDP: handle.cdpUrl, ...headerEnv });
+    }
+    return runSandboxStep(handle.sandboxId, action);
+}
+/**
+ * Stops the browser. For a remote provider, returns what the session cost (null
+ * when unknown). With `keepWarm`, a sandbox browser is left running and
+ * registered (domain + sandboxId + UA) so the next call reconnects to it via
+ * `Sandbox.get` instead of cold-booting — the caller must pass `domain`.
+ * Evicted warm entries (over the cap) are stopped here so idle compute
+ * does not linger.
+ */
+export async function stopBrowser(handle, opts = {}) {
+    if (handle.kind === "local") {
+        try {
+            process.kill(handle.pid);
+        }
+        catch {
+            /* already gone */
+        }
+        return null;
+    }
+    if (handle.kind === "remote") {
+        const [cost] = await Promise.all([stopRemoteSession(handle), stopRunner(handle.runner)]);
+        return cost;
+    }
+    if (opts.keepWarm && opts.domain) {
+        const { saveWarmSession } = await import("../engine/session.js");
+        try {
+            const evicted = await saveWarmSession({
+                domain: opts.domain,
+                sandboxId: handle.sandboxId,
+                userAgent: opts.userAgent ?? "",
+                cookieHeader: opts.cookieHeader ?? "",
+                expiresAt: Date.now() + WARM_TTL_MS,
+            });
+            await Promise.all(evicted.map(async (id) => {
+                try {
+                    const sandbox = await Sandbox.get({ sandboxId: id });
+                    await sandbox.stop();
+                }
+                catch {
+                    /* already stopped */
+                }
+            }));
+            console.info("[stealth] kept warm", { domain: opts.domain, sandboxId: handle.sandboxId, evicted: evicted.length });
+            return null;
+        }
+        catch {
+            /* registry unavailable — fall through to full stop */
+        }
+    }
+    await stopRunner(handle);
+    return null;
+}
+export { CDP_PORT };

package/dist/core/interact/remote.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Remote CDP browser providers for stealth fetches.
+ *
+ * A remote provider hosts the browser and hands back a CDP URL. Our step runner
+ * (sandbox or local Node) connects to it over CDP, so STEP_SCRIPT runs unchanged.
+ *
+ * WEBCRAWL_STEALTH_PROVIDER picks one:
+ * - browser-use: BROWSER_USE_API_KEY. Custom Chromium + residential proxy ($5/GB).
+ * - cloudflare:  CLOUDFLARE_ACCOUNT_ID + CLOUDFLARE_BROWSER_TOKEN (Browser Rendering - Edit).
+ *                Cloudflare Browser Run, $0.09 per browser hour, Cloudflare egress IPs.
+ * Only the stealth path (stealthFetch) uses it; /v1/interact keeps the sandbox.
+ */
+export type RemoteProvider = "browser-use" | "cloudflare";
+export interface RemoteSession {
+    provider: RemoteProvider;
+    sessionId: string;
+    cdpUrl: string;
+    /** Headers the CDP websocket needs (Cloudflare wants the bearer token on connect). */
+    cdpHeaders?: Record<string, string>;
+    startedAt: number;
+}
+export interface RemoteSessionCost {
+    /** Provider charge for the session in USD (browser time + proxy traffic). */
+    costUsd: number;
+    proxyMb: number;
+}
+/** Cloudflare Browser Run: $0.09 per browser hour past the included hours. */
+export declare const CLOUDFLARE_BROWSER_HOUR_USD = 0.09;
+/** The configured remote provider, or null when stealth runs on our own browser. */
+export declare function remoteStealthProvider(): RemoteProvider | null;
+/** Starts a remote browser. `timeoutMs` caps how long the provider keeps it (and bills it) if we never stop it. */
+export declare function startRemoteSession(opts?: {
+    provider?: RemoteProvider;
+    timeoutMs: number;
+    fetchImpl?: typeof fetch;
+}): Promise<RemoteSession>;
+/** Stops the session (unused time is refunded) and returns what it cost. Never throws. */
+export declare function stopRemoteSession(session: Pick<RemoteSession, "sessionId"> & Partial<Pick<RemoteSession, "provider" | "startedAt">>, opts?: {
+    fetchImpl?: typeof fetch;
+    now?: number;
+}): Promise<RemoteSessionCost | null>;

package/dist/core/interact/remote.js

@@ -0,0 +1,133 @@
+/**
+ * Remote CDP browser providers for stealth fetches.
+ *
+ * A remote provider hosts the browser and hands back a CDP URL. Our step runner
+ * (sandbox or local Node) connects to it over CDP, so STEP_SCRIPT runs unchanged.
+ *
+ * WEBCRAWL_STEALTH_PROVIDER picks one:
+ * - browser-use: BROWSER_USE_API_KEY. Custom Chromium + residential proxy ($5/GB).
+ * - cloudflare:  CLOUDFLARE_ACCOUNT_ID + CLOUDFLARE_BROWSER_TOKEN (Browser Rendering - Edit).
+ *                Cloudflare Browser Run, $0.09 per browser hour, Cloudflare egress IPs.
+ * Only the stealth path (stealthFetch) uses it; /v1/interact keeps the sandbox.
+ */
+/** Cloudflare Browser Run: $0.09 per browser hour past the included hours. */
+export const CLOUDFLARE_BROWSER_HOUR_USD = 0.09;
+const BROWSER_USE_API = () => (process.env.BROWSER_USE_API_URL || "https://api.browser-use.com/api/v4").replace(/\/+$/, "");
+function cloudflareCreds() {
+    const accountId = (process.env.CLOUDFLARE_ACCOUNT_ID || "").trim();
+    const token = (process.env.CLOUDFLARE_BROWSER_TOKEN || process.env.CLOUDFLARE_API_TOKEN || "").trim();
+    return accountId && token ? { accountId, token } : null;
+}
+const CF_API = (accountId) => `${(process.env.CLOUDFLARE_API_URL || "https://api.cloudflare.com/client/v4").replace(/\/+$/, "")}/accounts/${encodeURIComponent(accountId)}/browser-run`;
+/** The configured remote provider, or null when stealth runs on our own browser. */
+export function remoteStealthProvider() {
+    const name = (process.env.WEBCRAWL_STEALTH_PROVIDER || "").trim().toLowerCase();
+    if (name === "browser-use" && process.env.BROWSER_USE_API_KEY)
+        return "browser-use";
+    if (name === "cloudflare" && cloudflareCreds())
+        return "cloudflare";
+    return null;
+}
+function browserUseHeaders() {
+    return { "X-Browser-Use-API-Key": process.env.BROWSER_USE_API_KEY || "", "Content-Type": "application/json" };
+}
+function num(v) {
+    const n = typeof v === "number" ? v : Number.parseFloat(String(v ?? "0"));
+    return Number.isFinite(n) ? n : 0;
+}
+function errorDetail(body) {
+    const b = (body ?? {});
+    if (typeof b.detail === "string")
+        return b.detail;
+    if (Array.isArray(b.errors) && b.errors[0]?.message)
+        return String(b.errors[0].message);
+    return b.detail ? JSON.stringify(b.detail).slice(0, 200) : "";
+}
+/** Starts a remote browser. `timeoutMs` caps how long the provider keeps it (and bills it) if we never stop it. */
+export async function startRemoteSession(opts = { timeoutMs: 5 * 60_000 }) {
+    const provider = opts.provider ?? "browser-use";
+    return provider === "cloudflare" ? startCloudflareSession(opts) : startBrowserUseSession(opts);
+}
+async function startBrowserUseSession(opts) {
+    const f = opts.fetchImpl ?? fetch;
+    const country = (process.env.BROWSER_USE_PROXY_COUNTRY || "us").trim().toLowerCase();
+    const res = await f(`${BROWSER_USE_API()}/browsers`, {
+        method: "POST",
+        headers: browserUseHeaders(),
+        body: JSON.stringify({
+            timeout: Math.max(1, Math.min(240, Math.ceil(opts.timeoutMs / 60_000))),
+            // "none" turns the residential proxy off (cheaper, weaker against IP reputation checks).
+            proxyCountryCode: country === "none" ? null : country,
+            solveCaptchas: process.env.BROWSER_USE_SOLVE_CAPTCHAS !== "false",
+            metadata: { app: "webcrawl" },
+        }),
+        signal: AbortSignal.timeout(30_000),
+    });
+    const body = (await res.json().catch(() => ({})));
+    if (!res.ok || !body.id || !body.cdpUrl) {
+        const detail = errorDetail(body);
+        throw new Error(`Browser Use session failed (HTTP ${res.status})${detail ? `: ${detail}` : ""}`);
+    }
+    return { provider: "browser-use", sessionId: body.id, cdpUrl: body.cdpUrl, startedAt: Date.now() };
+}
+async function startCloudflareSession(opts) {
+    const creds = cloudflareCreds();
+    if (!creds)
+        throw new Error("Cloudflare Browser Run is not configured");
+    const f = opts.fetchImpl ?? fetch;
+    // keep_alive is how long the session idles before Cloudflare closes it: 10s..20min.
+    const keepAlive = Math.max(10_000, Math.min(1_200_000, opts.timeoutMs));
+    const res = await f(`${CF_API(creds.accountId)}/devtools/browser?keep_alive=${keepAlive}`, {
+        method: "POST",
+        headers: { Authorization: `Bearer ${creds.token}` },
+        signal: AbortSignal.timeout(30_000),
+    });
+    const raw = (await res.json().catch(() => ({})));
+    const body = raw.result ?? raw;
+    if (!res.ok || !body.sessionId) {
+        const detail = errorDetail(raw);
+        throw new Error(`Cloudflare Browser Run session failed (HTTP ${res.status})${detail ? `: ${detail}` : ""}`);
+    }
+    return {
+        provider: "cloudflare",
+        sessionId: body.sessionId,
+        cdpUrl: body.webSocketDebuggerUrl ||
+            `${CF_API(creds.accountId).replace(/^http/, "ws")}/devtools/browser/${encodeURIComponent(body.sessionId)}`,
+        cdpHeaders: { Authorization: `Bearer ${creds.token}` },
+        startedAt: Date.now(),
+    };
+}
+/** Stops the session (unused time is refunded) and returns what it cost. Never throws. */
+export async function stopRemoteSession(session, opts = {}) {
+    const f = opts.fetchImpl ?? fetch;
+    if (session.provider === "cloudflare") {
+        const creds = cloudflareCreds();
+        if (creds) {
+            await f(`${CF_API(creds.accountId)}/devtools/browser/${encodeURIComponent(session.sessionId)}`, {
+                method: "DELETE",
+                headers: { Authorization: `Bearer ${creds.token}` },
+                signal: AbortSignal.timeout(20_000),
+            }).catch(() => null);
+        }
+        // Cloudflare does not report per-session cost; bill browser time (rounded up to a minute).
+        if (!session.startedAt)
+            return null;
+        const minutes = Math.max(1, Math.ceil(((opts.now ?? Date.now()) - session.startedAt) / 60_000));
+        return { costUsd: (minutes / 60) * CLOUDFLARE_BROWSER_HOUR_USD, proxyMb: 0 };
+    }
+    try {
+        const res = await f(`${BROWSER_USE_API()}/browsers/${encodeURIComponent(session.sessionId)}`, {
+            method: "PATCH",
+            headers: browserUseHeaders(),
+            body: JSON.stringify({ action: "stop" }),
+            signal: AbortSignal.timeout(20_000),
+        });
+        if (!res.ok)
+            return null;
+        const body = (await res.json().catch(() => ({})));
+        return { costUsd: num(body.proxyCost) + num(body.browserCost), proxyMb: num(body.proxyUsedMb) };
+    }
+    catch {
+        return null;
+    }
+}

package/dist/core/interact/spans.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Span events streamed from interact / crawl workflow runs and rendered by
+ * the trace view. Kept free of Node APIs so the workflow body and the
+ * browser bundle can both import it.
+ */
+export type SpanStatus = "running" | "ok" | "failed" | "skipped";
+export type SpanKind = "setup" | "open" | "action" | "read" | "map" | "page" | "charge" | "fetch" | "ocr" | "transcribe";
+export interface Span {
+    /** Stable id within a run, e.g. `action-3`. Later events with the same id replace earlier ones. */
+    id: string;
+    kind: SpanKind;
+    label: string;
+    detail?: string;
+    status: SpanStatus;
+    /** Milliseconds since the run started. */
+    startMs: number;
+    durationMs?: number;
+    error?: string;
+}
+export type RunEvent = {
+    type: "run";
+    runId: string;
+    kind: "interact" | "crawl" | "parse";
+    url: string;
+    startedAt: number;
+} | {
+    type: "span";
+    span: Span;
+} | {
+    type: "done";
+    status: "completed" | "failed";
+    error?: string;
+};
+/** Folds a list of events into the latest state of each span, in first-seen order. */
+export declare function foldSpans(events: RunEvent[]): Span[];
+export interface SpanSummary {
+    total: number;
+    ok: number;
+    failed: number;
+    skipped: number;
+    running: number;
+    durationMs: number;
+    /** 1-based index among spans of the given kind, of the first failure. */
+    firstFailedIndex?: number;
+}
+export declare function summarizeSpans(spans: Span[], kind?: SpanKind): SpanSummary;

package/dist/core/interact/spans.js

@@ -0,0 +1,32 @@
+/**
+ * Span events streamed from interact / crawl workflow runs and rendered by
+ * the trace view. Kept free of Node APIs so the workflow body and the
+ * browser bundle can both import it.
+ */
+/** Folds a list of events into the latest state of each span, in first-seen order. */
+export function foldSpans(events) {
+    const order = [];
+    const byId = new Map();
+    for (const e of events) {
+        if (e.type !== "span")
+            continue;
+        if (!byId.has(e.span.id))
+            order.push(e.span.id);
+        byId.set(e.span.id, e.span);
+    }
+    return order.map((id) => byId.get(id));
+}
+export function summarizeSpans(spans, kind) {
+    const list = kind ? spans.filter((s) => s.kind === kind) : spans;
+    let durationMs = 0;
+    let firstFailedIndex;
+    const s = { total: list.length, ok: 0, failed: 0, skipped: 0, running: 0 };
+    list.forEach((span, i) => {
+        s[span.status === "ok" ? "ok" : span.status] += 1;
+        if (span.status === "failed" && firstFailedIndex === undefined)
+            firstFailedIndex = i + 1;
+    });
+    for (const span of spans)
+        durationMs = Math.max(durationMs, span.startMs + (span.durationMs ?? 0));
+    return { ...s, durationMs, firstFailedIndex };
+}

package/dist/core/interact/validate.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Input checks for /v1/interact. Pure functions so they can be unit-tested
+ * and reused by the API route before a workflow run is started.
+ */
+export declare const INTERACT_ACTION_TYPES: readonly ["click", "fill", "type", "hover", "select", "press", "wait", "scroll", "evaluate", "extract"];
+export type InteractActionType = (typeof INTERACT_ACTION_TYPES)[number];
+export declare const MAX_INTERACT_ACTIONS = 20;
+export interface InteractAction {
+    type: InteractActionType;
+    selector?: string;
+    text?: string;
+    value?: string;
+    key?: string;
+    ms?: number;
+    y?: number;
+    script?: string;
+    timeoutMs?: number;
+}
+/** Browser session length: 2 min by default (first minute in the base price), 10 min max. */
+export declare const DEFAULT_SESSION_SECONDS = 120;
+export declare const MAX_SESSION_SECONDS = 600;
+export type ValidateResult = {
+    ok: true;
+    url: string;
+    actions: InteractAction[];
+    sessionSeconds: number;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function normalizeActionType(raw: unknown): InteractActionType | undefined;
+/** Human label used in the trace, e.g. `Click  #submit`. */
+export declare function describeAction(a: InteractAction): string;
+export declare function validateInteractRequest(body: Record<string, unknown>): ValidateResult;