wb-browser-runtime 0.6.1 → 0.10.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,20 +1,42 @@
 {
   "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.10.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"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/workbooks-dev/wb-browser-runtime.git"
+  },
+  "homepage": "https://github.com/workbooks-dev/wb-browser-runtime#readme",
+  "bugs": {
+    "url": "https://github.com/workbooks-dev/wb-browser-runtime/issues"
+  },
+  "license": "MIT",
+  "keywords": [
+    "wb",
+    "workbooks",
+    "playwright",
+    "browser-automation",
+    "browserbase",
+    "cdp"
   ]
 }

package/verbs/announce_artifact.js

@@ -0,0 +1,74 @@
+import path from "node:path";
+import { promises as fsPromises } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { resolveInside } from "../lib/util.js";
+
+// Ergonomic shorthand for attaching a human-readable label to an artifact
+// already in (or about-to-be-in) $WB_ARTIFACTS_DIR. Writes a sidecar JSON
+// at `<path>.meta.json`; the next Artifacts::sync() pass picks it up and
+// attaches the label to the step.artifact_saved callback event. No upload,
+// no network — just filesystem metadata.
+//
+// Usage:
+//   - save:
+//       path: statement.csv
+//   - announce_artifact:
+//       path: statement.csv
+//       label: "April HSBC statement"
+//       description: "Reconciled balance export"
+//
+// The target artifact need not exist yet — callers may pre-write the
+// sidecar in an earlier block and drop the artifact later. The sidecar
+// only takes effect once the artifact is visible to sync().
+export default {
+  name: "announce_artifact",
+  primaryKey: "path",
+  async execute(_page, args) {
+    const rawPath = typeof args.path === "string" ? args.path.trim() : "";
+    if (!rawPath) {
+      throw new Error("announce_artifact: `path` is required");
+    }
+    const label = typeof args.label === "string" ? args.label : "";
+    if (!label) {
+      throw new Error("announce_artifact: `label` is required");
+    }
+    const description =
+      typeof args.description === "string" ? args.description : undefined;
+
+    const artifactsDir = (process.env.WB_ARTIFACTS_DIR || "").trim();
+    if (!artifactsDir) {
+      throw new Error(
+        "announce_artifact: $WB_ARTIFACTS_DIR is not set — run this workbook via `wb run` (wb exports the dir for you)",
+      );
+    }
+    if (path.isAbsolute(rawPath)) {
+      throw new Error(
+        `announce_artifact: absolute paths are not allowed (got ${rawPath})`,
+      );
+    }
+    const full = resolveInside(artifactsDir, rawPath);
+    if (!full) {
+      throw new Error(
+        `announce_artifact: path escapes artifacts dir (got ${rawPath})`,
+      );
+    }
+
+    const payload = { label };
+    if (description !== undefined) payload.description = description;
+    const serialized = JSON.stringify(payload, null, 2);
+
+    const sidecar = `${full}.meta.json`;
+    await fsPromises.mkdir(path.dirname(sidecar), { recursive: true });
+    const tmp = `${sidecar}.${process.pid}.${randomUUID().slice(0, 8)}.tmp`;
+    try {
+      await fsPromises.writeFile(tmp, serialized, "utf8");
+      await fsPromises.rename(tmp, sidecar);
+    } catch (e) {
+      try {
+        await fsPromises.unlink(tmp);
+      } catch {}
+      throw e;
+    }
+    return `→ ${rawPath} (labelled)`;
+  },
+};

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,81 @@
+// 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";
+import pauseForHumanVerb from "./pause_for_human.js";
+import waitForDropVerb from "./wait_for_drop.js";
+import announceArtifactVerb from "./announce_artifact.js";
+
+const VERBS = [
+  gotoVerb,
+  fillVerb,
+  clickVerb,
+  pressVerb,
+  waitForVerb,
+  screenshotVerb,
+  extractVerb,
+  assertVerb,
+  evalVerb,
+  saveVerb,
+  pauseForHumanVerb,
+  waitForDropVerb,
+  announceArtifactVerb,
+];
+
+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,
+  );
+  // Mutate-in-place so writes a verb makes to ctx (e.g. eval setting
+  // ctx.lastResult for a later save to pick up) survive to the next verb.
+  // The spread-copy pattern that used to live here silently dropped those
+  // writes, which broke the documented eval → save pattern.
+  ctx.index = index;
+  return handler.execute(page, args, ctx);
+}

package/verbs/pause_for_human.js

@@ -0,0 +1,60 @@
+// pause_for_human — generalized operator-handoff pause.
+//
+// Unlike side-effecting verbs (click, fill, goto) which return a summary
+// and let the slice loop continue, pause_for_human returns a sentinel
+// `{ __pause: {...} }` shape. The dispatcher in ../bin/wb-browser-runtime.js
+// inspects that shape and emits a `slice.paused` frame instead of a
+// `verb.complete`, which flips the Rust side into its pause-and-exit-42 path
+// (pending descriptor written, checkpoint marked paused, process exits).
+//
+// On `wb resume`, the slice re-enters at verb_index + 1 (the verb that
+// paused is skipped — it has no post-resume work). If the pause carried
+// `actions`, the operator's choice is written to
+// `$WB_ARTIFACTS_DIR/pause_result.json` by the Rust side before the sidecar
+// boots again, so downstream bash/python cells can branch on it via a
+// plain file read.
+
+const VALID_RESUME_MODES = ["operator_click", "poll", "timeout"];
+
+export default {
+  name: "pause_for_human",
+  primaryKey: "message",
+  async execute(_page, args, ctx) {
+    const resumeOn = args.resume_on || "operator_click";
+    if (!VALID_RESUME_MODES.includes(resumeOn)) {
+      throw new Error(
+        `pause_for_human: resume_on must be one of ${VALID_RESUME_MODES.join("|")}, got "${resumeOn}"`,
+      );
+    }
+    // Default action: a single "Resume" button. Authors who want
+    // branching on operator choice provide their own `actions` list.
+    const actions =
+      Array.isArray(args.actions) && args.actions.length > 0
+        ? args.actions
+        : [{ label: "Resume", value: null }];
+
+    // Validate action entries early so malformed YAML doesn't reach the
+    // run page as a broken button set.
+    for (const a of actions) {
+      if (!a || typeof a !== "object" || typeof a.label !== "string") {
+        throw new Error(
+          `pause_for_human: each action must be { label: string, value?: any }; got ${JSON.stringify(a)}`,
+        );
+      }
+    }
+
+    return {
+      __pause: {
+        reason: "pause_for_human",
+        message: args.message || "",
+        context_url: args.context_url || null,
+        resume_on: resumeOn,
+        timeout: args.timeout || null,
+        actions,
+        // Dispatcher wraps this with verb_index at emit time so `wb resume`
+        // knows where to re-enter.
+        sidecar_state: {},
+      },
+    };
+  },
+};

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}`;
+  },
+};