wb-browser-runtime 0.5.0 → 0.5.2

package/README.md

@@ -25,9 +25,27 @@ specific run.
 - `BROWSERBASE_API_KEY`
 - `BROWSERBASE_PROJECT_ID`
 
-Verb arguments support `{{ env.NAME }}` substitution at dispatch time, so any
-secrets your runbook needs (e.g. `HACKERNEWS_PASSWORD`) get pulled from the
-sidecar process env without ever appearing on stdout.
+Verb arguments support two substitutions at dispatch time:
+
+- `{{ env.NAME }}` — reads `process.env.NAME`. Use for static secrets injected via Doppler / the agent's env.
+- `{{ artifacts.NAME }}` — reads `$WB_ARTIFACTS_DIR/NAME.txt` (falling back to `$WB_ARTIFACTS_DIR/NAME`). Use for dynamic values produced by an earlier bash cell — OTPs, magic-link URLs, export IDs, anything polled from an external system mid-run. Each read happens per-verb with no caching, so writes land immediately.
+
+Both forms are redacted in stdout summaries — only the verb name + selector make it into the log.
+
+## Optional: anti-detection
+
+Targets behind Cloudflare / Kasada / DataDome (e.g. Airbase) will reject the
+default Browserbase session fingerprint and serve a non-interactive challenge
+page. Flip either flag on for the affected runs.
+
+| Env var                            | Default | Purpose                                          |
+|------------------------------------|---------|--------------------------------------------------|
+| `BROWSERBASE_ADVANCED_STEALTH`     | *(off)* | Send `browserSettings.advancedStealth: true`. Browserbase Scale-plan-gated — API errors on lower plans. |
+| `BROWSERBASE_PROXIES`              | *(off)* | Send `proxies: true`. Routes through Browserbase residential proxy pool. Incurs extra per-session cost. |
+
+Set `=1` (or `=true`) to enable. `proxies: true` alone clears most Cloudflare
+challenges; add `advancedStealth: true` on top when the target still blocks.
+The sidecar logs the resolved config at session create.
 
 ## Optional: session recording (rrweb + CDP screencast)
 

package/bin/wb-browser-runtime.js

@@ -14,9 +14,13 @@
 //   BROWSERBASE_API_KEY
 //   BROWSERBASE_PROJECT_ID
 //
-// Verb args support `{{ env.NAME }}` substitution, expanded recursively
-// against process.env at dispatch time. Credentials passed this way never
-// hit stdout — only the verb name + selector make it into the summary.
+// Verb args support two substitutions, expanded recursively at dispatch time:
+//   {{ env.NAME }}        → process.env.NAME
+//   {{ artifacts.NAME }}  → contents of $WB_ARTIFACTS_DIR/NAME.txt (or .../NAME)
+// The artifacts form lets an earlier bash cell compute a value — OTP, magic
+// link, export id — and feed it into a later browser verb without a sidecar
+// round-trip. Credentials passed via either form never hit stdout — only the
+// verb name + selector make it into the summary.
 
 import readline from "node:readline";
 import { chromium } from "playwright-core";
@@ -168,15 +172,35 @@ async function bbCreateSession() {
       "BROWSERBASE_API_KEY and BROWSERBASE_PROJECT_ID must be set",
     );
   }
+
+  // Both flags opt-in per session. advancedStealth is Scale-plan-gated on
+  // Browserbase's side; proxies adds residential-IP cost. Default off so a
+  // misconfigured plan doesn't break unrelated runs (HN, Google Sheets, etc.);
+  // flip per vendor when the target sits behind Cloudflare / similar bot
+  // detection (e.g., Airbase).
+  const envBool = (v) => v === "1" || (typeof v === "string" && v.toLowerCase() === "true");
+  const advancedStealth = envBool(process.env.BROWSERBASE_ADVANCED_STEALTH);
+  const proxies = envBool(process.env.BROWSERBASE_PROXIES);
+
+  // keepAlive:false — slice lifetime is tied to wb process; on shutdown
+  // we explicitly REQUEST_RELEASE so quota isn't burned by orphans.
+  const body = { projectId, keepAlive: false };
+  if (advancedStealth) {
+    body.browserSettings = { advancedStealth: true };
+  }
+  if (proxies) {
+    body.proxies = true;
+  }
+
+  log(`[bb] session create advancedStealth=${advancedStealth} proxies=${proxies}`);
+
   const res = await fetch(`${BB_BASE}/v1/sessions`, {
     method: "POST",
     headers: {
       "X-BB-API-Key": apiKey,
       "Content-Type": "application/json",
     },
-    // keepAlive:false — slice lifetime is tied to wb process; on shutdown
-    // we explicitly REQUEST_RELEASE so quota isn't burned by orphans.
-    body: JSON.stringify({ projectId, keepAlive: false }),
+    body: JSON.stringify(body),
   });
   if (!res.ok) {
     throw new Error(
@@ -556,22 +580,44 @@ function sanitize(s) {
   return String(s || "default").replace(/[^A-Za-z0-9_-]+/g, "_");
 }
 
-// --- {{ env.X }} substitution ----------------------------------------------
+// --- {{ env.X }} / {{ artifacts.X }} substitution --------------------------
 
 const ENV_RE = /\{\{\s*env\.([A-Za-z_][A-Za-z0-9_]*)\s*\}\}/g;
+const ARTIFACT_RE = /\{\{\s*artifacts\.([A-Za-z_][A-Za-z0-9_.-]*)\s*\}\}/g;
+
+function readArtifact(name) {
+  const dir = (process.env.WB_ARTIFACTS_DIR || "").trim();
+  if (!dir) {
+    log(`[warn] artifacts.${name} referenced but WB_ARTIFACTS_DIR is not set`);
+    return "";
+  }
+  // Per-verb read (no cache) so a bash cell that writes the artifact between
+  // slices is always picked up by the next browser verb.
+  for (const p of [path.join(dir, `${name}.txt`), path.join(dir, name)]) {
+    try {
+      return readFileSync(p, "utf8").trimEnd();
+    } catch {
+      // try next candidate
+    }
+  }
+  log(`[warn] artifact ${name} not found in ${dir}; leaving placeholder`);
+  return "";
+}
 
 function expand(value) {
   if (typeof value === "string") {
-    return value.replace(ENV_RE, (_, name) => {
-      const v = process.env[name];
-      if (v === undefined) {
-        // Leave the placeholder visible so failures surface in stderr summaries
-        // instead of silently turning into empty strings.
-        log(`[warn] env var ${name} is not set; leaving placeholder`);
-        return "";
-      }
-      return v;
-    });
+    return value
+      .replace(ENV_RE, (_, name) => {
+        const v = process.env[name];
+        if (v === undefined) {
+          // Leave the placeholder visible so failures surface in stderr
+          // summaries instead of silently turning into empty strings.
+          log(`[warn] env var ${name} is not set; leaving placeholder`);
+          return "";
+        }
+        return v;
+      })
+      .replace(ARTIFACT_RE, (_, name) => readArtifact(name));
   }
   if (Array.isArray(value)) return value.map(expand);
   if (value && typeof value === "object") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wb-browser-runtime",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "Browser sidecar runtime for wb — Browserbase + Playwright over the wb-sidecar/1 line-framed JSON protocol.",
   "bin": {
     "wb-browser-runtime": "bin/wb-browser-runtime.js"