wb-browser-runtime 0.10.0 → 0.12.0

package/README.md

@@ -33,8 +33,8 @@ specific run.
 
 ## Vendor selection
 
-`WB_BROWSER_VENDOR` — `browserbase` (default) or `browser-use`. Resolved once
-at sidecar boot; there is no per-slice override.
+`WB_BROWSER_VENDOR` — `browserbase` (default), `browser-use`, or `local`.
+Resolved once at sidecar boot; there is no per-slice override.
 
 ### Browserbase (default)
 
@@ -55,6 +55,40 @@ Profile (auth state) is selected per-runbook via the `profile_id:` field on a
 default when the browser block omits `profile_id:`; a per-runbook `profile_id:`
 always wins over the env var.
 
+### local
+
+`WB_BROWSER_VENDOR=local` drives a host-installed Playwright Chromium directly
+— no API keys, no network calls, no per-session cost. Use for dev iteration
+when you'd otherwise burn vendor minutes on broken selectors.
+
+| Env var                              | Default      | Purpose                                              |
+|--------------------------------------|--------------|------------------------------------------------------|
+| `WB_BROWSER_LOCAL_HEADLESS`          | `1`          | Set `0`/`false` for a visible browser window.        |
+| `WB_BROWSER_LOCAL_EXECUTABLE_PATH`   | *(unset)*    | Absolute path to a Chrome/Chromium binary. Overrides Playwright's bundled download. |
+| `WB_BROWSER_LOCAL_CHANNEL`           | *(unset)*    | Playwright channel name (`chrome`, `msedge`, `chrome-beta`, ...) for an OS-installed browser. Mutually exclusive with `EXECUTABLE_PATH`. |
+
+Trade-offs vs cloud vendors:
+
+- **No live URL.** `slice.session_started.live_url` is `null` — no remote
+  inspector, no Loom-style live preview. Use a non-headless run with
+  `WB_BROWSER_LOCAL_HEADLESS=0` if you want to watch.
+- **No persistent profile.** Each run starts with a clean Chromium state.
+  Cloud-side "profile" features (auth-state binding) aren't available.
+- **No resume after pause.** If a workbook hits a `wait` fence that suspends
+  the sidecar, the in-process Chromium dies with it. On `wb resume` the
+  local provider re-allocates a fresh browser. Cloud vendors can keep the
+  session alive for resume.
+
+First-time install:
+
+```bash
+npx playwright install chromium
+```
+
+If you skip this, `allocate()` fails with a hint pointing back at the
+install command. Or set `WB_BROWSER_LOCAL_EXECUTABLE_PATH` /
+`WB_BROWSER_LOCAL_CHANNEL` to use a system browser without the download.
+
 ## Profiles
 
 Some vendors expose persistent browser profiles — cookies, localStorage, saved
@@ -212,6 +246,40 @@ When `WB_ARTIFACTS_UPLOAD_URL` is set (template supports `{run_id}` and
 produced it completes. Auth reuses `WB_RECORDING_UPLOAD_SECRET`
 (`Authorization: Bearer <…>`); failures are logged and non-fatal.
 
+### Auto-captured downloads
+
+The sidecar attaches a context-level `download` listener at session
+start, so any file the browser downloads — clicked attachments, redirect
+chains that end in a binary, popup-driven Save As — is saved to
+`$WB_ARTIFACTS_DIR` automatically and emitted as a `slice.artifact_saved`
+frame (with `source: "download"` and a `provenance` block: source URL,
+page URL, the verb that was running, suggested filename). No verb call
+required. For cloud-provider browsers, Playwright streams the bytes back
+over CDP, so the file always lands on the sidecar machine where the
+artifacts dir + uploader live.
+
+Filename collisions in a single session get `-2`, `-3`, … suffixed
+(Playwright's `download.saveAs()` blindly overwrites, so we apply the
+suffixing ourselves).
+
+There is no size cap — `download.saveAs()` only resolves once the bytes
+are fully streamed, so a hung download trips the cell's own timeout
+(default 120s slice deadline; bump via `WB_SLICE_DEADLINE_MS`) and
+surfaces as a normal cell failure.
+
+To filter, set `WB_BROWSER_DOWNLOAD_EXTENSIONS` to a comma-separated
+list (case-insensitive, leading dots ignored):
+
+```yaml
+env:
+  WB_BROWSER_DOWNLOAD_EXTENSIONS: pdf,xlsx,csv,docx
+```
+
+When an allowlist is set, non-matching downloads are cancelled and
+emitted as `slice.download_skipped` (with `reason:
+"extension_not_in_allowlist"`) so the operator sees what was discarded.
+Unset = capture everything.
+
 ## Protocol
 
 Line-framed JSON, one message per line, on stdin/stdout. `stderr` is treated as

package/bin/wb-browser-runtime.js

@@ -34,6 +34,12 @@ import {
   loadRecordingConfig,
 } from "../lib/recording-manager.js";
 import { getProvider } from "../lib/providers/index.js";
+import {
+  attachConsoleBuffer,
+  captureFailureDiagnostics,
+  classifyError,
+} from "../lib/failure.js";
+import { installDownloadCapture } from "../lib/download-capture.js";
 import { SUPPORTS, runVerb, verbName } from "../verbs/index.js";
 
 const VERSION = "0.8.0";
@@ -56,7 +62,7 @@ if (recording.enabled) {
 
 const sessions = new SessionManager();
 
-async function ensureSession(name, { profile } = {}) {
+async function ensureSession(name, { profile, restoreSession } = {}) {
   return sessions.ensure(name, async () => {
     // Vendors charge for the session the moment allocate() returns; if
     // anything after this point throws (getLiveUrl, CDP connect, newContext,
@@ -69,32 +75,67 @@ async function ensureSession(name, { profile } = {}) {
     // against a cold vendor region, but the live-URL fetch and
     // newContext/newPage can each stall independently.
     const t0 = Date.now();
-    const allocated = await provider.allocate({ profile, sessionName: name });
+    const restored =
+      restoreSession &&
+      restoreSession.vendor === provider.name &&
+      restoreSession.cdpUrl;
+    const allocated = restored
+      ? {
+          sid: restoreSession.sid,
+          cdpUrl: restoreSession.cdpUrl,
+          _liveUrl: restoreSession.liveUrl ?? null,
+          _restored: true,
+        }
+      : await provider.allocate({ profile, sessionName: name });
     const tAllocated = Date.now();
     let browser = null;
     try {
-      const liveUrl = await provider.getLiveUrl(allocated);
-      browser = await chromium.connectOverCDP(allocated.cdpUrl);
+      const liveUrl = allocated._liveUrl ?? (await provider.getLiveUrl(allocated));
+      // Local provider returns a pre-built Browser via `_browser` (no CDP
+      // round-trip — chromium is already launched in-process). Cloud
+      // providers return a `cdpUrl` we connect to. Restored sessions
+      // always reconnect via CDP.
+      browser =
+        allocated._browser ??
+        (await chromium.connectOverCDP(allocated.cdpUrl));
       const tConnected = Date.now();
-      const context = browser.contexts()[0] ?? (await browser.newContext());
+      // acceptDownloads is true by default for Playwright-launched contexts,
+      // but we set it explicitly so the listener installed below isn't a
+      // no-op against a vendor-provided context that opted out.
+      const context =
+        browser.contexts()[0] ??
+        (await browser.newContext({ acceptDownloads: true }));
       const page = context.pages()[0] ?? (await context.newPage());
+      const consoleBuffer = attachConsoleBuffer(page);
       const tPageReady = Date.now();
 
       const info = {
         sid: allocated.sid,
+        cdpUrl: allocated.cdpUrl,
+        vendor: provider.name,
         browser,
         context,
         page,
         liveUrl,
         recording: null,
+        consoleBuffer,
+        // Updated by handleSlice's verb loop so the download listener
+        // can attach `verb_index`/`verb_name` provenance to artifacts
+        // captured while a verb is running. Null between slices.
+        currentVerb: null,
       };
 
+      // Install the always-on download listener now, before any slice
+      // runs, so a download fired by the very first verb is captured.
+      installDownloadCapture(context, () => info.currentVerb);
+
       send({
         type: "slice.session_started",
         session: name,
         session_id: allocated.sid,
         live_url: liveUrl,
         vendor: provider.name,
+        restored: Boolean(restored),
         started_at: new Date().toISOString(),
         timings: {
           allocate_ms: tAllocated - t0,
@@ -107,12 +148,12 @@ async function ensureSession(name, { profile } = {}) {
       await recording.start(info, name);
       return info;
     } catch (e) {
-      if (browser) {
+      if (browser && !allocated._restored) {
         try {
           await browser.close();
         } catch {}
       }
-      await provider.release(allocated.sid);
+      if (!allocated._restored) await provider.release(allocated.sid);
       throw e;
     }
   });
@@ -252,13 +293,18 @@ async function handleSlice(msg) {
     const verbs = Array.isArray(msg.verbs) ? msg.verbs : [];
     const sessionName = msg.session || "default";
     const restore = msg.restore || null;
+    const restoreSession = restore?.state?.session || null;
 
     let session;
     try {
-      session = await ensureSession(sessionName, { profile: msg.profile });
+      session = await ensureSession(sessionName, {
+        profile: msg.profile,
+        restoreSession,
+      });
     } catch (e) {
       send({
         type: "slice.failed",
+        code: classifyError(e, "session"),
         error: `session start failed: ${scrubSecrets(e.message, sliceCtx.secrets)}`,
       });
       return;
@@ -280,6 +326,7 @@ async function handleSlice(msg) {
       if (Date.now() >= sliceDeadline) {
         send({
           type: "slice.failed",
+          code: "SLICE_TIMEOUT",
           error: `slice exceeded deadline (${sliceDeadlineMs}ms); aborted before verb index ${i} of ${verbs.length}`,
         });
         return;
@@ -287,6 +334,12 @@ async function handleSlice(msg) {
       const v = verbs[i];
       const name = verbName(v);
       const verbStart = Date.now();
+      // Tell the passive download listener which verb to blame for any
+      // download that fires during this iteration. Cleared in `finally`
+      // so a download arriving between verbs (rare, but possible during
+      // a settle/redirect) records as "no current verb" instead of
+      // sticking the previous one's name on it.
+      session.currentVerb = { index: i, name };
       try {
         const summary = await runVerb(session.page, v, i, sliceCtx, expand);
         // Pause-sentinel escape hatch: a verb signals a mid-slice halt by
@@ -311,7 +364,17 @@ async function handleSlice(msg) {
             // descriptor and handed back on resume. The verb can stash
             // whatever it needs here; we always ensure verb_index is set
             // so the dispatcher can compute startAt on re-entry.
-            sidecar_state: { ...(pauseMeta.sidecar_state || {}), verb_index: i },
+            sidecar_state: {
+              ...(pauseMeta.sidecar_state || {}),
+              verb_index: i,
+              session: {
+                vendor: session.vendor,
+                name: sessionName,
+                sid: session.sid,
+                cdpUrl: session.cdpUrl,
+                liveUrl: session.liveUrl,
+              },
+            },
           });
           return;
         }
@@ -325,26 +388,44 @@ async function handleSlice(msg) {
       } catch (e) {
         const duration_ms = Date.now() - verbStart;
         const clean = scrubSecrets(e.message, sliceCtx.secrets);
+        const code = classifyError(e, name);
+        const diagnostics = await captureFailureDiagnostics({
+          page: session.page,
+          artifactsDir: (process.env.WB_ARTIFACTS_DIR || "").trim() || null,
+          verbIndex: i,
+          consoleBuffer: session.consoleBuffer,
+          scrubSecrets,
+          secrets: sliceCtx.secrets,
+        });
         send({
           type: "verb.failed",
           verb: name,
           verb_index: i,
+          code,
           error: clean,
           duration_ms,
+          screenshot_path: diagnostics.screenshot_path,
+          console_tail: diagnostics.console_tail,
         });
         send({
           type: "slice.failed",
+          code,
           error: `verb ${name} (index ${i}): ${clean}`,
         });
         return;
       }
     }
+    // Slice ended cleanly — clear the listener's "currently running verb"
+    // pointer so a stray late-arriving download doesn't get stamped with
+    // the last verb's name.
+    session.currentVerb = null;
     send({ type: "slice.complete" });
   } catch (e) {
     log(`[slice] unhandled: ${e.stack || e.message}`);
     try {
       send({
         type: "slice.failed",
+        code: classifyError(e, "sidecar"),
         error: `sidecar error: ${scrubSecrets(e.message, sliceCtx.secrets)}`,
       });
     } catch {}
@@ -391,6 +472,32 @@ async function shutdown() {
   process.exit(0);
 }
 
+async function suspend() {
+  if (shuttingDown) return;
+  shuttingDown = true;
+  // Flush recordings while CDP is still connected, but intentionally leave
+  // browser contexts and vendor sessions open. The operator needs the live
+  // inspector after wb exits 42, and wb resume reconnects using the persisted
+  // cdpUrl/liveUrl in sidecar_state.
+  for (const [name, info] of sessions) {
+    try {
+      await recording.flush(info, name);
+    } catch (e) {
+      log(`[suspend] flush recording ${name}: ${e.message}`);
+      try {
+        send({
+          type: "slice.recording.failed",
+          session: name,
+          run_id: recording.runId,
+          reason: `suspend_finalize_error: ${e.message}`,
+        });
+      } catch {}
+    }
+  }
+  log("[suspend] leaving browser session alive for external resume");
+  process.exit(0);
+}
+
 // --- Main loop --------------------------------------------------------------
 
 const rl = readline.createInterface({ input: process.stdin, terminal: false });
@@ -426,6 +533,15 @@ async function drainAndShutdown() {
   await shutdown();
 }
 
+async function drainAndSuspend() {
+  try {
+    await sessions.drainAll();
+  } catch (e) {
+    log(`[suspend] drain failed: ${e.message}`);
+  }
+  await suspend();
+}
+
 rl.on("line", (line) => {
   const trimmed = line.trim();
   if (!trimmed) return;
@@ -453,6 +569,9 @@ rl.on("line", (line) => {
     case "shutdown":
       drainAndShutdown();
       break;
+    case "suspend":
+      drainAndSuspend();
+      break;
     default:
       log(`[warn] unknown message type: ${msg.type}`);
   }

package/lib/download-capture.js

@@ -0,0 +1,180 @@
+// download-capture — passive capture of any file the browser downloads
+// during a session, regardless of which verb (or page redirect, or popup)
+// triggered it.
+//
+// The runbook author doesn't have to predict downloads. We attach a
+// `download` listener to the BrowserContext at session start; every file
+// the browser saves lands in `$WB_ARTIFACTS_DIR` and gets announced via a
+// `slice.artifact_saved` frame so wb's existing R2 uploader picks it up
+// for free. Provenance (page URL, source URL, which verb was running, ts)
+// rides along on the frame so the run-page event feed can show *why* a
+// given file appeared.
+//
+// Filtering: if WB_BROWSER_DOWNLOAD_EXTENSIONS is set, only files whose
+// extension matches the allowlist are kept. Skipped downloads still get a
+// `slice.download_skipped` frame so the operator sees what was discarded
+// (rare in practice — `download` events fire on real attachments, not
+// inline analytics pings — but useful when a SPA emits noisy JSON blobs).
+//
+// Big files: there is no size cap. R2 is bottomless and the runbook's own
+// timeout governs hung downloads — `download.saveAs()` only resolves once
+// bytes are fully streamed, so a stuck download will trip the cell deadline
+// and surface as a normal cell failure.
+//
+// Cloud vs local: `download.saveAs(absPath)` works for both. Playwright
+// streams the bytes back over CDP for cloud-attached browsers, so the file
+// always lands on the sidecar machine where $WB_ARTIFACTS_DIR lives.
+
+import path from "node:path";
+import { promises as fsPromises } from "node:fs";
+import { send, log, logWarn } from "./io.js";
+import {
+  uniquePathInside,
+  parseExtensionAllowlist,
+  extensionAllowed,
+} from "./util.js";
+
+// Marker that the explicit (future) `download:` gating verb sets on a
+// Download object once it's claimed it. The passive listener checks for
+// this and skips, so the same file isn't saved twice.
+export const HANDLED_MARK = Symbol.for("wb.download.handled");
+
+// Sentinel filename used when Playwright reports an empty suggestedFilename
+// (rare, but theoretically possible for downloads with no Content-
+// Disposition header and an empty URL path).
+const FALLBACK_NAME = "download.bin";
+
+// Install the always-on download listener on `context`. Returns a no-op
+// when WB_ARTIFACTS_DIR isn't set — without an artifacts dir there's
+// nowhere to put the file, and bailing here is preferable to inventing a
+// temp dir that wb's uploader doesn't watch.
+//
+// `getCurrentVerb()` is a callback the entry point updates each iteration
+// of the slice loop, so the listener can attach `verb_index` / `verb_name`
+// to the announcement without the slice loop having to reach back into
+// this module.
+export function installDownloadCapture(context, getCurrentVerb) {
+  const artifactsDir = (process.env.WB_ARTIFACTS_DIR || "").trim();
+  if (!artifactsDir) {
+    log("[download-capture] WB_ARTIFACTS_DIR not set; auto-capture disabled");
+    return;
+  }
+  const allowlist = parseExtensionAllowlist(
+    process.env.WB_BROWSER_DOWNLOAD_EXTENSIONS,
+  );
+  if (allowlist) {
+    log(
+      `[download-capture] enabled; extension allowlist: ${[...allowlist].join(",")}`,
+    );
+  } else {
+    log("[download-capture] enabled; capturing all downloads");
+  }
+
+  context.on("download", (download) => {
+    captureOne({ download, artifactsDir, allowlist, getCurrentVerb }).catch(
+      (e) => {
+        // Never let a failed capture take down the slice — emit a frame
+        // so the operator sees the failure, then drop it.
+        logWarn(`[download-capture] ${e.stack || e.message}`);
+        try {
+          send({
+            type: "slice.download_failed",
+            error: String(e.message || e),
+            url: safeUrl(download),
+            suggested_filename: safeSuggested(download),
+          });
+        } catch {}
+      },
+    );
+  });
+}
+
+async function captureOne({
+  download,
+  artifactsDir,
+  allowlist,
+  getCurrentVerb,
+}) {
+  if (download[HANDLED_MARK]) return;
+
+  const suggested = safeSuggested(download);
+  const sourceUrl = safeUrl(download);
+  const pageUrl = (() => {
+    try {
+      return download.page().url();
+    } catch {
+      return null;
+    }
+  })();
+  const verb = (typeof getCurrentVerb === "function" && getCurrentVerb()) || {};
+
+  if (!extensionAllowed(suggested, allowlist)) {
+    send({
+      type: "slice.download_skipped",
+      reason: "extension_not_in_allowlist",
+      suggested_filename: suggested,
+      url: sourceUrl,
+      page_url: pageUrl,
+      verb_index: verb.index ?? null,
+      verb_name: verb.name ?? null,
+      ts: Date.now(),
+    });
+    // Cancel the download so Playwright doesn't keep the temp file alive.
+    try {
+      await download.cancel();
+    } catch {}
+    return;
+  }
+
+  await fsPromises.mkdir(artifactsDir, { recursive: true });
+  const target = uniquePathInside(artifactsDir, suggested);
+  if (!target) {
+    throw new Error(
+      `download-capture: refusing to save "${suggested}" — resolves outside $WB_ARTIFACTS_DIR`,
+    );
+  }
+
+  await download.saveAs(target);
+
+  let bytes = null;
+  try {
+    bytes = (await fsPromises.stat(target)).size;
+  } catch {
+    // saveAs resolved successfully so the file should exist; if stat fails
+    // we still announce, just without size. Better partial info than no
+    // event at all.
+  }
+
+  send({
+    type: "slice.artifact_saved",
+    filename: path.basename(target),
+    path: target,
+    bytes,
+    source: "download",
+    provenance: {
+      url: sourceUrl,
+      suggested_filename: suggested,
+      page_url: pageUrl,
+      verb_index: verb.index ?? null,
+      verb_name: verb.name ?? null,
+      ts: Date.now(),
+    },
+  });
+}
+
+function safeSuggested(download) {
+  try {
+    const s = download.suggestedFilename();
+    return s && s.trim() ? s : FALLBACK_NAME;
+  } catch {
+    return FALLBACK_NAME;
+  }
+}
+
+function safeUrl(download) {
+  try {
+    return download.url();
+  } catch {
+    return null;
+  }
+}

package/lib/failure.js

@@ -0,0 +1,99 @@
+// Failure-event helpers — classifier + screenshot/console capture.
+//
+// `verb.failed` and `slice.failed` carry a stable `code` field so agents can
+// switch on category instead of regex-matching English. Verb failures also
+// snapshot a screenshot (best-effort) and the recent console buffer so
+// post-hoc debugging doesn't depend on a single line of stderr.
+//
+// All capture is best-effort: a failed screenshot or a missing artifacts dir
+// must NOT prevent the failure event from emitting.
+
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+
+const MAX_CONSOLE_ENTRIES = 50;
+const MAX_LINE_CHARS = 512;
+
+// Map a verb-execution error to a stable code. Order matters: an explicit
+// `err.code` (e.g. set by a provider for AUTH_FAILED) wins over inference.
+export function classifyError(err, verbName) {
+  if (err && typeof err.code === "string" && err.code) return err.code;
+  if (!err) return "INTERNAL_ERROR";
+  const name = err.name || "";
+  const msg = String(err.message || "");
+  if (name === "TimeoutError") {
+    if (verbName === "goto") return "NAV_TIMEOUT";
+    if (/load\s*state|networkidle|navigation|wait\s+for\s+url/i.test(msg)) {
+      return "NAV_TIMEOUT";
+    }
+    return "SELECTOR_NOT_FOUND";
+  }
+  if (verbName === "eval" || verbName === "extract") return "SCRIPT_ERROR";
+  return "INTERNAL_ERROR";
+}
+
+// Attach console + pageerror listeners to a Page. Returns the buffer object
+// (FIFO-capped) so callers can stash it next to the Page (e.g. on the
+// SessionManager `info`). Calling twice on the same Page would double-record;
+// callers are expected to only invoke once per page.
+export function attachConsoleBuffer(page) {
+  const buffer = [];
+  const push = (entry) => {
+    const text = String(entry.text ?? "");
+    buffer.push({
+      type: entry.type,
+      text: text.length > MAX_LINE_CHARS ? text.slice(0, MAX_LINE_CHARS) : text,
+      at: entry.at ?? Date.now(),
+    });
+    while (buffer.length > MAX_CONSOLE_ENTRIES) buffer.shift();
+  };
+  page.on("console", (msg) => {
+    push({ type: msg.type(), text: msg.text() });
+  });
+  page.on("pageerror", (err) => {
+    push({ type: "pageerror", text: err?.message ?? String(err) });
+  });
+  return buffer;
+}
+
+// Snapshot console buffer (with secret scrubbing) and capture a screenshot.
+// Returns `{ screenshot_path, console_tail }`. Both fields may be null/empty;
+// caller decides whether to attach them to the failure event.
+export async function captureFailureDiagnostics({
+  page,
+  artifactsDir,
+  verbIndex,
+  consoleBuffer,
+  scrubSecrets,
+  secrets,
+}) {
+  const out = { screenshot_path: null, console_tail: [] };
+
+  if (Array.isArray(consoleBuffer)) {
+    const scrub = typeof scrubSecrets === "function" ? scrubSecrets : null;
+    out.console_tail = consoleBuffer.map((entry) => ({
+      type: entry.type,
+      text: scrub ? scrub(entry.text, secrets) : String(entry.text),
+      at: entry.at,
+    }));
+  }
+
+  if (page && artifactsDir) {
+    try {
+      const filename = `wb-failure-${verbIndex}-${Date.now()}.png`;
+      const fullPath = path.join(artifactsDir, filename);
+      const tmp = `${fullPath}.${process.pid}.${randomUUID().slice(0, 8)}.tmp`;
+      const buf = await page.screenshot({ type: "png" });
+      await fs.mkdir(path.dirname(fullPath), { recursive: true });
+      await fs.writeFile(tmp, buf);
+      await fs.rename(tmp, fullPath);
+      out.screenshot_path = filename;
+    } catch {
+      // Screenshot capture is best-effort; don't let a Page crash or a
+      // permission error mask the underlying verb failure.
+    }
+  }
+
+  return out;
+}

package/lib/providers/browser-use.js

@@ -77,15 +77,22 @@ export function createBrowserUseProvider() {
         "bu.create",
       );
       if (!res.ok) {
-        throw new Error(
+        const err = new Error(
           `browser-use create failed (${res.status}): ${await safeText(res)}`,
         );
+        err.code =
+          res.status === 401 || res.status === 403
+            ? "AUTH_FAILED"
+            : "SESSION_ALLOCATE_FAILED";
+        throw err;
       }
       const created = await res.json();
       if (!created.cdpUrl) {
-        throw new Error(
+        const err = new Error(
           `browser-use create returned no cdpUrl (status=${created.status ?? "?"}); session unusable`,
         );
+        err.code = "SESSION_ALLOCATE_FAILED";
+        throw err;
       }
       return {
         sid: created.id,

package/lib/providers/browserbase.js

@@ -65,9 +65,14 @@ export function createBrowserbaseProvider() {
         "bb.create",
       );
       if (!res.ok) {
-        throw new Error(
+        const err = new Error(
           `Browserbase create failed (${res.status}): ${await safeText(res)}`,
         );
+        err.code =
+          res.status === 401 || res.status === 403
+            ? "AUTH_FAILED"
+            : "SESSION_ALLOCATE_FAILED";
+        throw err;
       }
       const created = await res.json();
       return { sid: created.id, cdpUrl: created.connectUrl };
@@ -81,9 +86,14 @@ export function createBrowserbaseProvider() {
         "bb.debug",
       );
       if (!res.ok) {
-        throw new Error(
+        const err = new Error(
           `Browserbase debug fetch failed (${res.status}): ${await safeText(res)}`,
         );
+        err.code =
+          res.status === 401 || res.status === 403
+            ? "AUTH_FAILED"
+            : "SESSION_ALLOCATE_FAILED";
+        throw err;
       }
       const body = await res.json();
       return body.debuggerFullscreenUrl;

package/lib/providers/index.js

@@ -21,10 +21,12 @@
 //
 // Vendor selection is a single env var, resolved once at sidecar boot:
 //   WB_BROWSER_VENDOR=browserbase (default)
-//   WB_BROWSER_VENDOR=browser-use (future)
+//   WB_BROWSER_VENDOR=browser-use
+//   WB_BROWSER_VENDOR=local      — host-installed Chromium (dev iteration)
 
 import { createBrowserbaseProvider } from "./browserbase.js";
 import { createBrowserUseProvider } from "./browser-use.js";
+import { createLocalProvider } from "./local.js";
 
 export function getProvider() {
   const raw = (process.env.WB_BROWSER_VENDOR || "browserbase")
@@ -35,9 +37,11 @@ export function getProvider() {
       return createBrowserbaseProvider();
     case "browser-use":
       return createBrowserUseProvider();
+    case "local":
+      return createLocalProvider();
     default:
       throw new Error(
-        `WB_BROWSER_VENDOR="${raw}" is not a known vendor (expected: browserbase | browser-use)`,
+        `WB_BROWSER_VENDOR="${raw}" is not a known vendor (expected: browserbase | browser-use | local)`,
       );
   }
 }

package/lib/providers/local.js

@@ -0,0 +1,120 @@
+// Local provider — drives a host-installed Playwright Chromium directly
+// instead of going to a cloud vendor. Use for dev iteration without
+// Browserbase / browser-use cost or latency. Selected via
+// WB_BROWSER_VENDOR=local.
+//
+// Differences from cloud providers:
+//   1. allocate() launches a real Chromium via `playwright-core`'s
+//      chromium.launch() and returns a pre-built Browser handle in
+//      `_browser`. The entry point checks for it and skips the
+//      connectOverCDP step that cloud providers require.
+//   2. getLiveUrl() returns null — there's no public live-inspector URL
+//      for a locally-launched browser. The Rust side just renders the
+//      "session started" line without a clickable URL.
+//   3. release() is a no-op. The shutdown path already does
+//      `info.browser.close()` on every cached session, which terminates
+//      the local Chromium process.
+//   4. Profile binding is not supported (logged + ignored). For persistent
+//      auth across runs use a vendor with profile support, or pin
+//      WB_BROWSER_LOCAL_EXECUTABLE_PATH at a Chrome instance with a
+//      pre-warmed user-data-dir (advanced; not the supported path).
+//
+// Resume-after-pause: not supported. The Browser is process-local memory
+// and dies with the sidecar; on resume the sidecar re-allocates a fresh
+// session. This matches the dev-iteration use case (you're running the
+// runbook end-to-end, not pausing on a real wait fence).
+
+import { chromium } from "playwright-core";
+import { log } from "../io.js";
+
+// Truthiness for env knobs that default to ON. "0" / "false" / "no" / "off"
+// disables; anything else enables. Mirrors the convention used elsewhere.
+function isOff(v) {
+  if (v === undefined || v === null) return false;
+  const s = String(v).trim().toLowerCase();
+  return s === "0" || s === "false" || s === "no" || s === "off";
+}
+
+export function createLocalProvider() {
+  return {
+    name: "local",
+
+    async allocate({ profile, sessionName: _sessionName } = {}) {
+      if (profile) {
+        log(
+          `[local] profile="${profile}" ignored — local vendor has no profile binding. ` +
+            `Use a cloud vendor or persist auth via WB_BROWSER_LOCAL_EXECUTABLE_PATH on a pre-warmed Chrome.`,
+        );
+      }
+
+      // Headless ON by default; flip with WB_BROWSER_LOCAL_HEADLESS=0 for
+      // visible-window dev. Operators debugging a brittle workbook can flip
+      // to headed without touching the runbook.
+      const headless = !isOff(process.env.WB_BROWSER_LOCAL_HEADLESS);
+
+      // executablePath: explicit override for system Chrome / Chromium.
+      // channel: "chrome" / "msedge" / "chrome-beta" — Playwright's named
+      // channels for OS-installed browsers (no separate download). At most
+      // one of executablePath / channel should be set; if both arrive,
+      // executablePath wins (Playwright honors it).
+      const executablePath =
+        process.env.WB_BROWSER_LOCAL_EXECUTABLE_PATH || undefined;
+      const channel = process.env.WB_BROWSER_LOCAL_CHANNEL || undefined;
+
+      log(
+        `[local] launching chromium headless=${headless}` +
+          ` executablePath=${executablePath ?? "<bundled>"}` +
+          ` channel=${channel ?? "<none>"}`,
+      );
+
+      let browser;
+      try {
+        browser = await chromium.launch({
+          headless,
+          executablePath,
+          channel,
+        });
+      } catch (e) {
+        // Most common cause: Playwright's chromium binary not installed.
+        // playwright-core ships the API but no browser; the user runs
+        // `npx playwright install chromium` once to fetch it. Surface the
+        // hint inline so this isn't a guessing game on first run.
+        const err = new Error(
+          `local browser launch failed: ${e.message}\n` +
+            `Hint: install Chromium with \`npx playwright install chromium\`, ` +
+            `or set WB_BROWSER_LOCAL_EXECUTABLE_PATH / WB_BROWSER_LOCAL_CHANNEL to use a system browser.`,
+        );
+        err.code = "SESSION_ALLOCATE_FAILED";
+        throw err;
+      }
+
+      // sid is for telemetry only — there's no remote session to release.
+      // Format: `local-<ms>-<rand>` so it's distinguishable from vendor sids
+      // in callback streams and logs.
+      const sid = `local-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+
+      return {
+        sid,
+        // No CDP URL — the entry point sees `_browser` and skips the
+        // connectOverCDP path that cloud providers go through.
+        cdpUrl: null,
+        // Stashed so getLiveUrl() is a sync property read like browser-use.
+        _liveUrl: null,
+        _browser: browser,
+      };
+    },
+
+    async getLiveUrl(_allocated) {
+      // No public inspector URL for local Chromium. Returning null tells
+      // the Rust side to render the "session started" line without a link.
+      return null;
+    },
+
+    async release(_sid) {
+      // Browser teardown happens in the entry-point shutdown loop via
+      // `info.browser.close()`, which kills the local Chromium process.
+      // Cloud providers need a separate vendor REST call here; local
+      // doesn't.
+    },
+  };
+}

package/lib/stub-page.js

@@ -73,6 +73,22 @@ export function createStubPage(opts = {}) {
       record({ verb: "evaluate", script });
       return evalResult;
     },
+    async waitForLoadState(state, options) {
+      record({ verb: "waitForLoadState", state, options });
+    },
+    getByText(text, options) {
+      record({ verb: "getByText", text, options });
+      const locator = {
+        first() {
+          return {
+            async click(opts) {
+              record({ verb: "getByText.first.click", text, options: opts });
+            },
+          };
+        },
+      };
+      return locator;
+    },
   };
 }
 

package/lib/util.js

@@ -1,5 +1,6 @@
 import path from "node:path";
 import { randomUUID } from "node:crypto";
+import { existsSync } from "node:fs";
 
 // Resolve `candidate` inside `dir`, rejecting traversal and absolute paths.
 // Returns null when the resolved path escapes `dir` (or is `dir` itself).
@@ -14,6 +15,63 @@ export function resolveInside(dir, candidate) {
   return resolved;
 }
 
+// Collision-safe path inside `dir`. Returns the first path of the form
+// `<base><ext>`, `<base>-2<ext>`, `<base>-3<ext>`, ... that doesn't already
+// exist on disk. Playwright's `download.saveAs(path)` blindly overwrites,
+// so this is the only thing standing between two same-named downloads
+// (e.g. two `report.pdf` saves in one session) silently clobbering each
+// other. Returns null if `name` would resolve outside `dir`.
+//
+// The check is racy (two concurrent downloads with the same suggestedName
+// can both observe the same free slot before either writes) — acceptable
+// here because downloads in a single session serialize through the same
+// page in practice, and a stray collision would just produce one
+// overwritten file rather than corrupting state.
+export function uniquePathInside(dir, name) {
+  const safe = sanitizeArtifactName(name);
+  const first = resolveInside(dir, safe);
+  if (!first) return null;
+  if (!existsSync(first)) return first;
+  const ext = path.extname(safe);
+  const base = ext ? safe.slice(0, -ext.length) : safe;
+  for (let n = 2; n < 1000; n++) {
+    const candidate = resolveInside(dir, `${base}-${n}${ext}`);
+    if (!candidate) return null;
+    if (!existsSync(candidate)) return candidate;
+  }
+  // Fallback: append a random suffix. 1000 collisions on the same name in
+  // one session is unrealistic, but we'd rather degrade than throw.
+  const rand = randomUUID().slice(0, 8);
+  return resolveInside(dir, `${base}-${rand}${ext}`);
+}
+
+// Parse a comma-separated extension allowlist from raw env (e.g.
+// "pdf, xlsx,CSV"). Returns a Set of lowercase extensions without leading
+// dots, or null when the input is empty/unset (callers treat null as "no
+// filter — capture everything").
+export function parseExtensionAllowlist(raw) {
+  if (raw == null) return null;
+  const s = String(raw).trim();
+  if (!s) return null;
+  const parts = s
+    .split(",")
+    .map((x) => x.trim().toLowerCase().replace(/^\./, ""))
+    .filter(Boolean);
+  if (parts.length === 0) return null;
+  return new Set(parts);
+}
+
+// Match a filename against an extension allowlist. `null` allowlist means
+// no filter (anything passes). Files with no extension never pass a
+// non-null allowlist — the caller wanted a specific set, an unknown blob
+// isn't it.
+export function extensionAllowed(filename, allowlist) {
+  if (!allowlist) return true;
+  const ext = path.extname(String(filename || "")).toLowerCase().replace(/^\./, "");
+  if (!ext) return false;
+  return allowlist.has(ext);
+}
+
 export function sanitizeArtifactName(s) {
   // Keep author-chosen names readable but safe as filenames. Drop anything
   // that could escape the artifacts dir (slashes, NULs, etc.).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wb-browser-runtime",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "Browser sidecar runtime for wb — Playwright over CDP (Browserbase, browser-use) via the wb-sidecar/1 line-framed JSON protocol.",
   "bin": {
     "wb-browser-runtime": "bin/wb-browser-runtime.js"

package/verbs/click.js

@@ -2,7 +2,29 @@ export default {
   name: "click",
   primaryKey: "selector",
   async execute(page, args) {
-    await page.click(args.selector, { timeout: args.timeout ?? 10_000 });
-    return `${args.selector}`;
+    const timeout = args.timeout ?? 10_000;
+    try {
+      await page.click(args.selector, { timeout });
+      return `${args.selector}`;
+    } catch (err) {
+      // Text-fallback: when the selector times out (typically a brittle
+      // class/id rename), retry against visible text. We DELIBERATELY
+      // re-throw the ORIGINAL error if the fallback also fails — the
+      // selector failure is the actionable signal for error classification
+      // upstream; the fallback's failure would obscure it.
+      const isTimeout = err && err.name === "TimeoutError";
+      if (isTimeout && args.text_fallback) {
+        try {
+          await page
+            .getByText(args.text_fallback, { exact: false })
+            .first()
+            .click({ timeout });
+          return `${args.selector} (via text="${args.text_fallback}")`;
+        } catch {
+          throw err;
+        }
+      }
+      throw err;
+    }
   },
 };

package/verbs/index.js

@@ -13,6 +13,7 @@ import fillVerb from "./fill.js";
 import clickVerb from "./click.js";
 import pressVerb from "./press.js";
 import waitForVerb from "./wait_for.js";
+import waitForNetworkIdleVerb from "./wait_for_network_idle.js";
 import screenshotVerb from "./screenshot.js";
 import extractVerb from "./extract.js";
 import assertVerb from "./assert.js";
@@ -28,6 +29,7 @@ const VERBS = [
   clickVerb,
   pressVerb,
   waitForVerb,
+  waitForNetworkIdleVerb,
   screenshotVerb,
   extractVerb,
   assertVerb,

package/verbs/wait_for_network_idle.js

@@ -0,0 +1,51 @@
+// Wait until the page reports "networkidle" — at most one in-flight request
+// for >=500ms. SPA flows that don't have a stable selector to wait on need
+// this; otherwise the next verb fires before async XHRs settle and reads
+// stale DOM.
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+// Parse "30s" / "2m" / "500ms" / 5000 / "5000" into ms. Anything malformed
+// falls back to the default — the sidecar would rather time out at a known
+// bound than throw on a typo.
+function parseTimeoutMs(value) {
+  if (value == null) return DEFAULT_TIMEOUT_MS;
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value !== "string") return DEFAULT_TIMEOUT_MS;
+  const trimmed = value.trim();
+  if (trimmed === "") return DEFAULT_TIMEOUT_MS;
+  const m = trimmed.match(/^(\d+(?:\.\d+)?)\s*(ms|s|m|h)?$/i);
+  if (!m) {
+    const asNum = Number(trimmed);
+    return Number.isFinite(asNum) ? asNum : DEFAULT_TIMEOUT_MS;
+  }
+  const n = Number(m[1]);
+  const unit = (m[2] || "ms").toLowerCase();
+  switch (unit) {
+    case "ms":
+      return n;
+    case "s":
+      return n * 1000;
+    case "m":
+      return n * 60_000;
+    case "h":
+      return n * 3_600_000;
+    default:
+      return DEFAULT_TIMEOUT_MS;
+  }
+}
+
+export default {
+  name: "wait_for_network_idle",
+  primaryKey: "timeout",
+  async execute(page, args) {
+    const raw = args.timeout;
+    const timeout = parseTimeoutMs(raw);
+    await page.waitForLoadState("networkidle", { timeout });
+    const summary =
+      typeof raw === "string" && raw.trim() !== ""
+        ? `network idle (timeout=${raw.trim()})`
+        : `network idle (timeout=${timeout}ms)`;
+    return summary;
+  },
+};