wb-browser-runtime 0.6.0 → 0.7.0

package/lib/http.js

@@ -0,0 +1,63 @@
+import { log } from "./io.js";
+
+export async function safeText(res) {
+  try {
+    return (await res.text()).slice(0, 200);
+  } catch {
+    return "<unreadable>";
+  }
+}
+
+// Retry transient network + 5xx/429 failures with short exponential backoff.
+// Each attempt gets its own AbortController + timeout; caller-passed signals
+// are not plumbed through since we don't have a cancellation story above this
+// layer. Non-retryable statuses (4xx except 429) are returned immediately for
+// the caller to handle.
+//
+// `bodyFactory`, when set, is invoked per attempt to produce a fresh body —
+// required for streaming uploads where the previous attempt consumed the
+// stream. Takes precedence over opts.body.
+export async function retryableFetch(
+  url,
+  opts = {},
+  label,
+  { timeoutMs = 30_000, bodyFactory = null } = {},
+) {
+  const delays = [100, 500];
+  let lastErr = null;
+  let lastRes = null;
+  for (let attempt = 0; attempt <= delays.length; attempt++) {
+    if (attempt > 0) {
+      await new Promise((r) => setTimeout(r, delays[attempt - 1]));
+      const prev = lastRes
+        ? `status=${lastRes.status}`
+        : `err=${lastErr?.message || lastErr}`;
+      log(`[retry] ${label} attempt ${attempt + 1}/3 (${prev})`);
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+      const fetchOpts = { ...opts, signal: controller.signal };
+      if (bodyFactory) {
+        fetchOpts.body = bodyFactory();
+        // undici requires duplex: "half" for streaming (non-Buffer, non-string)
+        // request bodies. Omitting it throws at request time.
+        fetchOpts.duplex = "half";
+      }
+      const res = await fetch(url, fetchOpts);
+      if (res.ok) return res;
+      if (res.status === 429 || (res.status >= 500 && res.status < 600)) {
+        lastRes = res;
+        continue;
+      }
+      return res;
+    } catch (e) {
+      lastErr = e;
+      continue;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  if (lastRes) return lastRes;
+  throw lastErr;
+}

package/lib/io.js

@@ -0,0 +1,56 @@
+// Line-framed JSON protocol I/O. `send` writes a single frame to stdout;
+// `log*` helpers write diagnostic output to stderr, filtered by
+// `WB_LOG_LEVEL` (trace|debug|info|warn|error, default info).
+//
+// `log()` (unqualified) is info-level for back-compat — existing call
+// sites don't need to be reclassified. New verbose output should use
+// `logDebug` / `logTrace` so it can be silenced by default. Warn/error
+// helpers exist so a single grep finds all the paths that will always
+// surface.
+
+const LOG_LEVELS = { trace: 0, debug: 1, info: 2, warn: 3, error: 4 };
+
+function resolveLevel() {
+  const raw = (process.env.WB_LOG_LEVEL || "info").trim().toLowerCase();
+  const level = LOG_LEVELS[raw];
+  if (level === undefined) {
+    process.stderr.write(
+      `[warn] WB_LOG_LEVEL=${raw} is not valid (trace|debug|info|warn|error); defaulting to info\n`,
+    );
+    return LOG_LEVELS.info;
+  }
+  return level;
+}
+
+// Resolved once at module load — sidecar boots, runs, exits. If we ever
+// need live reconfiguration, swap this for a getter that re-reads env.
+const CURRENT_LEVEL = resolveLevel();
+
+export function send(obj) {
+  process.stdout.write(JSON.stringify(obj) + "\n");
+}
+
+function emit(level, args) {
+  if (LOG_LEVELS[level] < CURRENT_LEVEL) return;
+  process.stderr.write(args.join(" ") + "\n");
+}
+
+export function logTrace(...args) {
+  emit("trace", args);
+}
+
+export function logDebug(...args) {
+  emit("debug", args);
+}
+
+export function log(...args) {
+  emit("info", args);
+}
+
+export function logWarn(...args) {
+  emit("warn", args);
+}
+
+export function logError(...args) {
+  emit("error", args);
+}

package/lib/providers/browser-use.js

@@ -0,0 +1,133 @@
+// browser-use cloud provider.
+//
+// Two differences vs. Browserbase worth knowing:
+//   1. `POST /api/v3/browsers` returns `cdpUrl` AND `liveUrl` in one call —
+//      no separate debug fetch. We stash liveUrl on the allocated handle so
+//      getLiveUrl() is a sync property read, and the timing buckets in
+//      slice.session_started stay shaped the same way (just with ~0ms
+//      connect-phase fetch on this vendor).
+//   2. Stealth + proxies are on by default (proxyCountryCode defaults to
+//      "us"); no Scale-plan gate. Set BROWSER_USE_PROXY_COUNTRY=null to
+//      disable the proxy, or to e.g. "gb" to route elsewhere.
+//
+// Release uses PATCH with action:"stop" (the documented update-session
+// endpoint). "Unused time automatically refunded if the session ran less
+// than 1 hour" per their docs, so early teardown on sidecar shutdown is
+// real savings, not just quota cleanup.
+//
+// Not yet wired: customProxy, browserScreenWidth/Height, allowResizing,
+// enableRecording (we have our own rrweb + screencast pipeline; enabling
+// theirs would double-record).
+
+import { retryableFetch, safeText } from "../http.js";
+import { log } from "../io.js";
+
+const BU_BASE = "https://api.browser-use.com/api/v3";
+
+export function createBrowserUseProvider() {
+  return {
+    name: "browser-use",
+
+    async allocate({ profile, sessionName: _sessionName } = {}) {
+      const apiKey = process.env.BROWSER_USE_API_KEY;
+      if (!apiKey) {
+        throw new Error("BROWSER_USE_API_KEY must be set");
+      }
+
+      // Profile id is an opaque UUID from the human-driven `profile.sh`
+      // bootstrap, baked into the runbook frontmatter by whatever generates
+      // it (UI editor, codegen, hand-authored). The slice envelope carries
+      // it through; this provider just forwards.
+      const profileId = profile ?? null;
+
+      const body = {};
+      if (profileId) body.profileId = profileId;
+
+      // Pass-through knobs. Only include when the operator set them — server
+      // defaults (proxy=us, timeout=60min) are better behaved than anything
+      // we'd invent here.
+      const proxyCountry = process.env.BROWSER_USE_PROXY_COUNTRY;
+      if (proxyCountry !== undefined) {
+        // Explicit "null" string disables the proxy entirely.
+        body.proxyCountryCode =
+          proxyCountry.toLowerCase() === "null" ? null : proxyCountry;
+      }
+      const timeoutMin = Number.parseInt(
+        process.env.BROWSER_USE_TIMEOUT_MIN || "",
+        10,
+      );
+      if (Number.isFinite(timeoutMin) && timeoutMin > 0) {
+        body.timeout = timeoutMin;
+      }
+
+      log(
+        `[bu] session create profile=${profileId ?? "<none>"} proxy=${body.proxyCountryCode ?? "<default>"} timeout=${body.timeout ?? "<default>"}m`,
+      );
+
+      const res = await retryableFetch(
+        `${BU_BASE}/browsers`,
+        {
+          method: "POST",
+          headers: {
+            "X-Browser-Use-API-Key": apiKey,
+            "Content-Type": "application/json",
+          },
+          body: JSON.stringify(body),
+        },
+        "bu.create",
+      );
+      if (!res.ok) {
+        throw new Error(
+          `browser-use create failed (${res.status}): ${await safeText(res)}`,
+        );
+      }
+      const created = await res.json();
+      if (!created.cdpUrl) {
+        throw new Error(
+          `browser-use create returned no cdpUrl (status=${created.status ?? "?"}); session unusable`,
+        );
+      }
+      return {
+        sid: created.id,
+        cdpUrl: created.cdpUrl,
+        // Stashed so getLiveUrl() below is a property read, not a round-trip.
+        _liveUrl: created.liveUrl ?? null,
+      };
+    },
+
+    async getLiveUrl(allocated) {
+      return allocated._liveUrl;
+    },
+
+    async release(sid) {
+      const apiKey = process.env.BROWSER_USE_API_KEY;
+      try {
+        const res = await retryableFetch(
+          `${BU_BASE}/browsers/${sid}`,
+          {
+            method: "PATCH",
+            headers: {
+              "X-Browser-Use-API-Key": apiKey,
+              "Content-Type": "application/json",
+            },
+            body: JSON.stringify({ action: "stop" }),
+          },
+          "bu.release",
+        );
+        if (!res.ok) {
+          // retryableFetch returns 4xx silently (only 5xx/429 are retried).
+          // Surface non-2xx loudly — a 400/404 here means the session is
+          // still alive and quota is still burning, which is the bug we
+          // were silently masking before.
+          log(
+            `[bu] release session ${sid} returned HTTP ${res.status}: ${await safeText(res)}`,
+          );
+          return;
+        }
+        log(`[bu] released session ${sid}`);
+      } catch (e) {
+        log(`[bu] release session ${sid} failed: ${e.message}`);
+      }
+    },
+  };
+}

package/lib/providers/browserbase.js

@@ -0,0 +1,120 @@
+// Browserbase provider. Three REST calls wrapped behind the provider
+// interface (allocate / getLiveUrl / release). Extracted from the sidecar
+// entry point so browser-use (and future vendors) can slot in via the same
+// shape without the verb/recording pipeline caring which chromium it's
+// driving.
+
+import { retryableFetch, safeText } from "../http.js";
+import { log } from "../io.js";
+
+const BB_BASE = "https://api.browserbase.com";
+
+function envBool(v) {
+  return v === "1" || (typeof v === "string" && v.toLowerCase() === "true");
+}
+
+export function createBrowserbaseProvider() {
+  return {
+    name: "browserbase",
+
+    async allocate({ profile, sessionName: _sessionName } = {}) {
+      const apiKey = process.env.BROWSERBASE_API_KEY;
+      const projectId = process.env.BROWSERBASE_PROJECT_ID;
+      if (!apiKey || !projectId) {
+        throw new Error(
+          "BROWSERBASE_API_KEY and BROWSERBASE_PROJECT_ID must be set",
+        );
+      }
+
+      if (profile) {
+        // Browserbase has "contexts" as its cross-session persistence concept
+        // but wb doesn't thread them yet. Log so operators see the `profile:`
+        // field arrived but had no effect — easier to debug than silent drop.
+        log(
+          `[bb] profile="${profile}" ignored — browserbase vendor has no profile binding yet`,
+        );
+      }
+
+      // 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; flip per vendor when the target sits behind
+      // Cloudflare / similar bot detection.
+      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 retryableFetch(
+        `${BB_BASE}/v1/sessions`,
+        {
+          method: "POST",
+          headers: {
+            "X-BB-API-Key": apiKey,
+            "Content-Type": "application/json",
+          },
+          body: JSON.stringify(body),
+        },
+        "bb.create",
+      );
+      if (!res.ok) {
+        throw new Error(
+          `Browserbase create failed (${res.status}): ${await safeText(res)}`,
+        );
+      }
+      const created = await res.json();
+      return { sid: created.id, cdpUrl: created.connectUrl };
+    },
+
+    async getLiveUrl(allocated) {
+      const apiKey = process.env.BROWSERBASE_API_KEY;
+      const res = await retryableFetch(
+        `${BB_BASE}/v1/sessions/${allocated.sid}/debug`,
+        { headers: { "X-BB-API-Key": apiKey } },
+        "bb.debug",
+      );
+      if (!res.ok) {
+        throw new Error(
+          `Browserbase debug fetch failed (${res.status}): ${await safeText(res)}`,
+        );
+      }
+      const body = await res.json();
+      return body.debuggerFullscreenUrl;
+    },
+
+    async release(sid) {
+      const apiKey = process.env.BROWSERBASE_API_KEY;
+      const projectId = process.env.BROWSERBASE_PROJECT_ID;
+      try {
+        const res = await retryableFetch(
+          `${BB_BASE}/v1/sessions/${sid}`,
+          {
+            method: "POST",
+            headers: {
+              "X-BB-API-Key": apiKey,
+              "Content-Type": "application/json",
+            },
+            body: JSON.stringify({ projectId, status: "REQUEST_RELEASE" }),
+          },
+          "bb.release",
+        );
+        if (!res.ok) {
+          log(
+            `[bb] release session ${sid} returned HTTP ${res.status}: ${await safeText(res)}`,
+          );
+          return;
+        }
+        log(`[bb] released session ${sid}`);
+      } catch (e) {
+        log(`[bb] release session ${sid} failed: ${e.message}`);
+      }
+    },
+  };
+}

package/lib/providers/index.js

@@ -0,0 +1,43 @@
+// Browser-session provider boundary.
+//
+// All vendor-specific work (session allocation, live-preview URL, release)
+// lives behind a provider. Everything else in the sidecar — verbs, recording,
+// session cache, substitutions — runs against a Playwright Page and doesn't
+// care which vendor handed us the CDP endpoint.
+//
+// Provider interface:
+//   {
+//     name: string,
+//     async allocate({ profile, sessionName }) -> { sid, cdpUrl, ...opaque },
+//     async getLiveUrl(allocated) -> string,
+//     async release(sid) -> void,
+//   }
+//
+// Two-phase allocate/getLiveUrl split exists so vendors that return the live
+// URL in the same call as session create (browser-use) can just stash it on
+// the `allocated` object and return it synchronously from getLiveUrl —
+// while vendors that require a second round-trip (browserbase) preserve
+// today's timing buckets (allocate_ms vs. connect_ms in slice.session_started).
+//
+// Vendor selection is a single env var, resolved once at sidecar boot:
+//   WB_BROWSER_VENDOR=browserbase (default)
+//   WB_BROWSER_VENDOR=browser-use (future)
+
+import { createBrowserbaseProvider } from "./browserbase.js";
+import { createBrowserUseProvider } from "./browser-use.js";
+
+export function getProvider() {
+  const raw = (process.env.WB_BROWSER_VENDOR || "browserbase")
+    .trim()
+    .toLowerCase();
+  switch (raw) {
+    case "browserbase":
+      return createBrowserbaseProvider();
+    case "browser-use":
+      return createBrowserUseProvider();
+    default:
+      throw new Error(
+        `WB_BROWSER_VENDOR="${raw}" is not a known vendor (expected: browserbase | browser-use)`,
+      );
+  }
+}