wb-browser-runtime 0.6.1 → 0.7.0

package/lib/session-manager.js

@@ -0,0 +1,101 @@
+// Per-name session cache with in-flight create dedup.
+//
+// Today the slice enqueue is global (one chain, all sessions serialized),
+// so concurrent ensures for the same name never happen — the second caller
+// always sees the cache populated. Once slice dispatch moves to per-session
+// chains (see Phase 4), two concurrent slices for "vendor-x" would both
+// race bbCreateSession and burn two Browserbase sessions. Deduping the
+// in-flight promise here fixes that race up-front, so the per-session
+// chain change in Phase 4 is a one-liner in main.js instead of a recursive
+// bug hunt later.
+//
+// The manager is creation-logic-free on purpose: callers hand an async
+// factory to `ensure()`, which is invoked at most once per name. The
+// factory is responsible for its own cleanup on throw — on rejection the
+// in-flight entry is dropped so a subsequent caller can retry.
+
+export class SessionManager {
+  constructor() {
+    this._sessions = new Map();
+    this._inFlight = new Map();
+    this._chains = new Map();
+  }
+
+  get size() {
+    return this._sessions.size;
+  }
+
+  has(name) {
+    return this._sessions.has(name);
+  }
+
+  get(name) {
+    return this._sessions.get(name);
+  }
+
+  delete(name) {
+    return this._sessions.delete(name);
+  }
+
+  entries() {
+    return this._sessions.entries();
+  }
+
+  values() {
+    return this._sessions.values();
+  }
+
+  // Match Map's default iterator (yields [name, info] pairs) so callers can
+  // write `for (const [name, info] of manager)` the same way they would
+  // against the underlying Map.
+  [Symbol.iterator]() {
+    return this._sessions.entries();
+  }
+
+  // Serialize work against a single session name (so two slices against
+  // the same Playwright page don't race), but let distinct names run in
+  // parallel. Before this, the entry point held a single global promise
+  // chain — two slices against "vendor-a" and "vendor-b" serialized even
+  // though they touch disjoint browsers. The in-flight-create dedup in
+  // `ensure()` is what makes per-session parallelism safe here: two
+  // concurrent slices for the same name still share one bbCreateSession.
+  //
+  // `fn` should return a promise; errors propagate to the returned
+  // promise and don't poison the next link in the chain.
+  enqueueOn(name, fn) {
+    const prev = this._chains.get(name) ?? Promise.resolve();
+    const next = prev.catch(() => {}).then(fn);
+    this._chains.set(name, next);
+    return next;
+  }
+
+  // Resolve once every currently-queued chain has settled. Used by
+  // shutdown to wait for in-flight slices before closing browsers and
+  // releasing Browserbase sessions. Only observes chains that exist at
+  // call time — later enqueues aren't awaited, which is the correct
+  // behavior for shutdown (the main loop stops accepting messages first).
+  async drainAll() {
+    const chains = Array.from(this._chains.values());
+    await Promise.allSettled(chains);
+  }
+
+  async ensure(name, createFn) {
+    if (this._sessions.has(name)) return this._sessions.get(name);
+    const inFlight = this._inFlight.get(name);
+    if (inFlight) return inFlight;
+    // Only set the cached entry after createFn returns successfully — a
+    // failure inside createFn (e.g. startRecording throws) must not leave
+    // a half-constructed SessionInfo visible to iterators like shutdown().
+    const p = (async () => {
+      const info = await createFn();
+      this._sessions.set(name, info);
+      return info;
+    })();
+    this._inFlight.set(name, p);
+    try {
+      return await p;
+    } finally {
+      this._inFlight.delete(name);
+    }
+  }
+}

package/lib/stub-page.js

@@ -0,0 +1,112 @@
+// Minimal in-memory fake of the Playwright `Page` API that the verbs
+// exercise. Every method the verb registry touches is stubbed here; tests
+// configure return values via the factory's options and assert against the
+// recorded `calls` log.
+//
+// Intentionally does NOT simulate real browser behavior — a verb that
+// would throw against a real page (e.g. `fill` on a non-existent selector)
+// resolves cleanly here. Tests asserting error paths use options like
+// `handles: { "#nope": null }` to wire explicit misses.
+
+export function createStubPage(opts = {}) {
+  const calls = [];
+  let currentUrl = opts.initialUrl ?? "about:blank";
+
+  const screenshotBuf =
+    opts.screenshotBuf ?? Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a]);
+  const extractResult = opts.extractResult ?? [];
+  const evalResult = opts.evalResult ?? null;
+  // handles: selector -> { textContent } | null (null = selector not found).
+  // Missing keys (undefined) also count as "not found" so tests only need
+  // to wire what matters.
+  const handles = opts.handles ?? {};
+
+  const record = (call) => {
+    calls.push(call);
+    return call;
+  };
+
+  return {
+    calls,
+    _setUrl(u) {
+      currentUrl = u;
+    },
+    url() {
+      return currentUrl;
+    },
+
+    async goto(url, options) {
+      record({ verb: "goto", url, options });
+      currentUrl = url;
+    },
+    async fill(selector, value, options) {
+      record({ verb: "fill", selector, value, options });
+    },
+    async click(selector, options) {
+      record({ verb: "click", selector, options });
+    },
+    async press(selector, key, options) {
+      record({ verb: "press", selector, key, options });
+    },
+    async waitForSelector(selector, options) {
+      record({ verb: "waitForSelector", selector, options });
+    },
+    async screenshot(options) {
+      record({ verb: "screenshot", options });
+      return screenshotBuf;
+    },
+    async $$eval(selector, fn, fieldSpec) {
+      record({ verb: "$$eval", selector, fieldSpec });
+      return extractResult;
+    },
+    async $(selector) {
+      record({ verb: "$", selector });
+      const h = handles[selector];
+      if (h == null) return null;
+      return {
+        async textContent() {
+          return h.textContent ?? null;
+        },
+      };
+    },
+    async evaluate(script) {
+      record({ verb: "evaluate", script });
+      return evalResult;
+    },
+  };
+}
+
+// Capture JSON frames written via lib/io.js `send` during a test. Returns
+// a disposer that restores `process.stdout.write`. Non-JSON writes pass
+// through, so node:test's own reporter output (spec/tap/text) is still
+// visible. Use inside a test with `t.after(disposer)`.
+export function captureSendFrames() {
+  const real = process.stdout.write.bind(process.stdout);
+  const frames = [];
+  process.stdout.write = (chunk, encoding, cb) => {
+    const str = typeof chunk === "string" ? chunk : chunk?.toString?.();
+    // Single JSON line ending in \n matches the shape of lib/io.js send()
+    // writes. Non-JSON or multi-line writes fall through to the real stdout
+    // so node:test's reporter output isn't swallowed.
+    if (
+      str &&
+      str.startsWith("{") &&
+      str.endsWith("\n") &&
+      str.indexOf("\n") === str.length - 1
+    ) {
+      try {
+        frames.push(JSON.parse(str.trim()));
+        if (typeof encoding === "function") encoding();
+        else if (typeof cb === "function") cb();
+        return true;
+      } catch {
+        // Fall through to real write — wasn't actually a send() frame.
+      }
+    }
+    return real(chunk, encoding, cb);
+  };
+  const dispose = () => {
+    process.stdout.write = real;
+  };
+  return { frames, dispose };
+}

package/lib/util.js

@@ -0,0 +1,33 @@
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+
+// Resolve `candidate` inside `dir`, rejecting traversal and absolute paths.
+// Returns null when the resolved path escapes `dir` (or is `dir` itself).
+// Used by the screenshot verb and substitution artifact reads — anywhere
+// runbook-author-controlled strings could compose with a trusted directory
+// into an arbitrary filesystem write.
+export function resolveInside(dir, candidate) {
+  const resolvedDir = path.resolve(dir);
+  const resolved = path.resolve(resolvedDir, candidate);
+  const rel = path.relative(resolvedDir, resolved);
+  if (rel === "" || rel.startsWith("..") || path.isAbsolute(rel)) return null;
+  return resolved;
+}
+
+export function sanitizeArtifactName(s) {
+  // Keep author-chosen names readable but safe as filenames. Drop anything
+  // that could escape the artifacts dir (slashes, NULs, etc.).
+  return String(s).replace(/[^A-Za-z0-9_.-]+/g, "_").slice(0, 200);
+}
+
+export function autoArtifactName(blockIndex) {
+  const rand = randomUUID().replace(/-/g, "").slice(0, 8);
+  const n = Number.isFinite(blockIndex) ? blockIndex : 0;
+  return `cell-${n}-${rand}`;
+}
+
+export function redact(value) {
+  if (typeof value !== "string") return "";
+  if (value.length <= 4) return "***";
+  return `${value.slice(0, 2)}***`;
+}

package/package.json

@@ -1,19 +1,24 @@
 {
   "name": "wb-browser-runtime",
-  "version": "0.6.1",
-  "description": "Browser sidecar runtime for wb — Browserbase + Playwright over the wb-sidecar/1 line-framed JSON protocol.",
+  "version": "0.7.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"
   },
   "type": "module",
   "engines": {
-    "node": ">=18"
+    "node": ">=24"
+  },
+  "scripts": {
+    "test": "node --test"
   },
   "dependencies": {
     "playwright-core": "^1.49.0"
   },
   "files": [
     "bin",
+    "lib",
+    "verbs",
     "vendor",
     "README.md"
   ]

package/verbs/assert.js

@@ -0,0 +1,23 @@
+export default {
+  name: "assert",
+  primaryKey: "selector",
+  async execute(page, args) {
+    const sel = args.selector;
+    const handle = await page.$(sel);
+    if (!handle) throw new Error(`assert: selector not found: ${sel}`);
+    if (args.text_contains) {
+      const txt = (await handle.textContent()) ?? "";
+      if (!txt.includes(args.text_contains)) {
+        throw new Error(
+          `assert: text "${args.text_contains}" not in ${sel} (got "${txt.slice(0, 80)}")`,
+        );
+      }
+    }
+    if (args.url_contains && !page.url().includes(args.url_contains)) {
+      throw new Error(
+        `assert: url does not contain "${args.url_contains}" (got ${page.url()})`,
+      );
+    }
+    return `${sel}`;
+  },
+};

package/verbs/click.js

@@ -0,0 +1,8 @@
+export default {
+  name: "click",
+  primaryKey: "selector",
+  async execute(page, args) {
+    await page.click(args.selector, { timeout: args.timeout ?? 10_000 });
+    return `${args.selector}`;
+  },
+};

package/verbs/eval.js

@@ -0,0 +1,20 @@
+export default {
+  name: "eval",
+  primaryKey: "script",
+  async execute(page, args, ctx) {
+    // Wrap the script in an async IIFE so authors can write function-body
+    // style: top-level `return X` works, top-level `await X` works, and
+    // multi-statement scripts read like the `(async () => { ... })()`
+    // pattern people already write into runbooks. Trade-off: bare-expression
+    // scripts (`script: "1 + 1"`) no longer return their value — authors
+    // must say `return 1 + 1` explicitly. That migration is intentional —
+    // multi-line scripts are the common case and "must add `return`" is a
+    // clearer rule than "single expressions vs. statement bodies behave
+    // differently."
+    const wrapped = `(async () => { ${args.script} })()`;
+    const result = await page.evaluate(wrapped);
+    console.log(JSON.stringify(result, null, 2));
+    if (ctx) ctx.lastResult = result;
+    return `script ran`;
+  },
+};

package/verbs/extract.js

@@ -0,0 +1,38 @@
+export default {
+  name: "extract",
+  primaryKey: "selector",
+  async execute(page, args, ctx) {
+    // Pull structured rows out of the page. Each `field` entry is either:
+    //   string                   — CSS selector relative to row, take textContent
+    //   { selector, attr }       — CSS selector relative to row, take attribute
+    //   { selector, text: true } — explicit textContent (default)
+    const rowSelector = args.selector;
+    const fields = args.fields ?? {};
+    const items = await page.$$eval(
+      rowSelector,
+      (rows, fieldSpec) =>
+        rows.map((row) => {
+          const out = {};
+          for (const [name, spec] of Object.entries(fieldSpec)) {
+            const sel = typeof spec === "string" ? spec : spec.selector;
+            const attr = typeof spec === "string" ? null : spec.attr ?? null;
+            const el = sel ? row.querySelector(sel) : row;
+            if (!el) {
+              out[name] = null;
+              continue;
+            }
+            out[name] = attr
+              ? el.getAttribute(attr)
+              : (el.textContent || "").trim();
+          }
+          return out;
+        }),
+      fields,
+    );
+    // Emit as JSON to stdout so wb captures it in step.complete.stdout.
+    // Pretty-printed for readability when a runbook surfaces the output.
+    console.log(JSON.stringify(items, null, 2));
+    if (ctx) ctx.lastResult = items;
+    return `${rowSelector} → ${items.length} rows`;
+  },
+};

package/verbs/fill.js

@@ -0,0 +1,13 @@
+import { redact } from "../lib/util.js";
+
+export default {
+  name: "fill",
+  primaryKey: "selector",
+  async execute(page, args) {
+    // Don't echo the value into the summary — could be a credential.
+    await page.fill(args.selector, String(args.value ?? ""), {
+      timeout: args.timeout ?? 10_000,
+    });
+    return `${args.selector} = «${redact(args.value)}»`;
+  },
+};

package/verbs/goto.js

@@ -0,0 +1,10 @@
+export default {
+  name: "goto",
+  primaryKey: "url",
+  async execute(page, args) {
+    const url = args.url ?? "";
+    const waitUntil = args.wait_until ?? "domcontentloaded";
+    await page.goto(url, { waitUntil, timeout: args.timeout ?? 30_000 });
+    return `→ ${page.url()}`;
+  },
+};

package/verbs/index.js

@@ -0,0 +1,70 @@
+// Verb registry. Each verb module exports a default { name, primaryKey,
+// execute(page, args, ctx) } object. The registry is the single source of
+// truth for the SUPPORTS list (shipped in the ready frame), the default-key
+// lookup used by the bare-string arg form, and the dispatch table consumed
+// by runVerb.
+//
+// Adding a verb: drop a new file next to these, import it here, append to
+// VERBS. SUPPORTS/DEFAULT_KEYS/VERB_REGISTRY all derive automatically — no
+// third list to keep in sync.
+
+import gotoVerb from "./goto.js";
+import fillVerb from "./fill.js";
+import clickVerb from "./click.js";
+import pressVerb from "./press.js";
+import waitForVerb from "./wait_for.js";
+import screenshotVerb from "./screenshot.js";
+import extractVerb from "./extract.js";
+import assertVerb from "./assert.js";
+import evalVerb from "./eval.js";
+import saveVerb from "./save.js";
+
+const VERBS = [
+  gotoVerb,
+  fillVerb,
+  clickVerb,
+  pressVerb,
+  waitForVerb,
+  screenshotVerb,
+  extractVerb,
+  assertVerb,
+  evalVerb,
+  saveVerb,
+];
+
+export const VERB_REGISTRY = Object.fromEntries(VERBS.map((v) => [v.name, v]));
+export const SUPPORTS = VERBS.map((v) => v.name);
+
+export function verbName(verb) {
+  if (!verb || typeof verb !== "object") return String(verb);
+  return Object.keys(verb)[0] || "verb";
+}
+
+export function defaultKey(name) {
+  return VERB_REGISTRY[name]?.primaryKey ?? "value";
+}
+
+// Most verbs accept either a bare string ("goto: https://...") or a
+// structured object ("goto: { url: ..., wait_until: ... }"). This pulls the
+// canonical field out of either shape.
+export function arg(value, primaryKey) {
+  if (typeof value === "string") return { [primaryKey]: value };
+  if (value && typeof value === "object") return value;
+  return {};
+}
+
+// Dispatch a single verb. `expand` is injected by the caller so the
+// substitution/secrets machinery stays in the entry point (where env policy
+// and the artifact cache live) instead of leaking into this module.
+export async function runVerb(page, verb, index, ctx, expand) {
+  const name = verbName(verb);
+  const handler = VERB_REGISTRY[name];
+  if (!handler) throw new Error(`unsupported verb: ${name}`);
+  const raw = verb[name];
+  const args = expand(
+    arg(raw, handler.primaryKey),
+    ctx?.secrets,
+    ctx?.artifactCache,
+  );
+  return handler.execute(page, args, { ...ctx, index });
+}

package/verbs/press.js

@@ -0,0 +1,9 @@
+export default {
+  name: "press",
+  primaryKey: "key",
+  async execute(page, args) {
+    const target = args.selector ?? "body";
+    await page.press(target, args.key, { timeout: args.timeout ?? 5_000 });
+    return `${target} ⌨ ${args.key}`;
+  },
+};

package/verbs/save.js

@@ -0,0 +1,55 @@
+import path from "node:path";
+import { promises as fsPromises } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { send } from "../lib/io.js";
+import { sanitizeArtifactName, autoArtifactName } from "../lib/util.js";
+
+export default {
+  name: "save",
+  primaryKey: "name",
+  async execute(_page, args, ctx) {
+    // Persist a JSON artifact into $WB_ARTIFACTS_DIR so later cells can read
+    // it and wb can upload it. Captures the previous verb's output unless
+    // the author provides an explicit `value:`.
+    const artifactsDir = (process.env.WB_ARTIFACTS_DIR || "").trim();
+    if (!artifactsDir) {
+      throw new Error(
+        "save: $WB_ARTIFACTS_DIR is not set — run this workbook via `wb run` (wb exports the dir for you)",
+      );
+    }
+    const explicitValue = args.value !== undefined;
+    const payload = explicitValue ? args.value : ctx?.lastResult;
+    if (payload === undefined) {
+      throw new Error(
+        "save: no value provided and no prior extract/eval result to capture",
+      );
+    }
+    const name =
+      typeof args.name === "string" && args.name.trim().length > 0
+        ? sanitizeArtifactName(args.name)
+        : autoArtifactName(ctx?.blockIndex ?? ctx?.index ?? 0);
+    const filename = name.endsWith(".json") ? name : `${name}.json`;
+    const full = path.join(artifactsDir, filename);
+    await fsPromises.mkdir(artifactsDir, { recursive: true });
+    // Atomic write: serialize to .tmp, then rename. Announce the artifact
+    // AFTER rename so a partial write can never be seen by wb's uploader.
+    const serialized = JSON.stringify(payload, null, 2);
+    const tmp = `${full}.${process.pid}.${randomUUID().slice(0, 8)}.tmp`;
+    try {
+      await fsPromises.writeFile(tmp, serialized, "utf8");
+      await fsPromises.rename(tmp, full);
+    } catch (e) {
+      try {
+        await fsPromises.unlink(tmp);
+      } catch {}
+      throw e;
+    }
+    send({
+      type: "slice.artifact_saved",
+      filename,
+      path: full,
+      bytes: Buffer.byteLength(serialized),
+    });
+    return `→ ${filename}`;
+  },
+};

package/verbs/screenshot.js

@@ -0,0 +1,48 @@
+import path from "node:path";
+import { promises as fsPromises } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { resolveInside } from "../lib/util.js";
+
+export default {
+  name: "screenshot",
+  primaryKey: "path",
+  async execute(page, args) {
+    // Always resolve inside $WB_ARTIFACTS_DIR (or cwd when unset). Absolute
+    // paths and traversals are rejected — screenshots are controlled by
+    // runbook authors whose content we don't want to grant arbitrary-write.
+    const requested = args.path ?? `screenshot-${Date.now()}.png`;
+    const artifactsDir = (process.env.WB_ARTIFACTS_DIR || "").trim() || ".";
+    if (path.isAbsolute(requested)) {
+      throw new Error(
+        `screenshot: absolute paths are not allowed (got ${requested})`,
+      );
+    }
+    const full = resolveInside(artifactsDir, requested);
+    if (!full) {
+      throw new Error(
+        `screenshot: path escapes artifacts dir (got ${requested})`,
+      );
+    }
+    await fsPromises.mkdir(path.dirname(full), { recursive: true });
+    // Atomic write via tmp + rename so a crash mid-capture can't leave a
+    // truncated PNG that's already been announced via slice.artifact_saved
+    // and uploaded to R2. We capture to a Buffer (with `type` derived from
+    // the requested extension) and write it ourselves — passing a `.tmp`
+    // path directly to Playwright fails because it infers format from the
+    // file extension and rejects unknown ones.
+    const ext = path.extname(full).toLowerCase();
+    const type = ext === ".jpg" || ext === ".jpeg" ? "jpeg" : "png";
+    const tmp = `${full}.${process.pid}.${randomUUID().slice(0, 8)}.tmp`;
+    try {
+      const buf = await page.screenshot({ type, fullPage: !!args.full_page });
+      await fsPromises.writeFile(tmp, buf);
+      await fsPromises.rename(tmp, full);
+    } catch (e) {
+      try {
+        await fsPromises.unlink(tmp);
+      } catch {}
+      throw e;
+    }
+    return `→ ${requested}`;
+  },
+};

package/verbs/wait_for.js

@@ -0,0 +1,13 @@
+export default {
+  name: "wait_for",
+  primaryKey: "selector",
+  async execute(page, args) {
+    const selector = args.selector;
+    const state = args.state ?? "visible";
+    await page.waitForSelector(selector, {
+      state,
+      timeout: args.timeout ?? 15_000,
+    });
+    return `${selector} (${state})`;
+  },
+};