@moxxy/plugin-browser 0.27.0

package/src/sidecar/dispatch.ts

@@ -0,0 +1,314 @@
+/**
+ * JSON-RPC dispatch table for the sidecar. Each `method` here corresponds
+ * one-to-one with the wire-format methods documented in `sidecar.ts`.
+ */
+
+import { assertPublicUrl } from '../ssrf-guard.js';
+import { importPlaywright, launchWithAutoInstall } from './install.js';
+import {
+  badParams,
+  errMsg,
+  SidecarError,
+  type BrowserKind,
+  type PlaywrightHandle,
+  type Reply,
+  type Req,
+} from './types.js';
+
+/**
+ * Ceiling on screenshot/capture waits inside the sidecar so a page whose render
+ * is wedged fails the op cleanly instead of blocking the serial request queue
+ * indefinitely (the parent has its own per-call timeout as a backstop, but
+ * bounding it here drains the queue head sooner). Generous enough for a slow
+ * full-page screenshot; well under the parent ceiling.
+ */
+const SCREENSHOT_TIMEOUT_MS = 30_000;
+/** Hard ceiling on viewport / screenshot-clip dimensions, matching Chromium's
+ *  max texture/screenshot size — bounds allocation from a malformed surface
+ *  message (e.g. width:1e9). */
+const MAX_DIMENSION = 16_384;
+
+export interface SidecarState {
+  handle: PlaywrightHandle | null;
+  /**
+   * Set after a successful auto-install of browser binaries so the next
+   * tool result can carry a `notice` letting the user/model know the
+   * one-time download happened. Cleared once the notice has been
+   * delivered (handed to the reply once, then forgotten).
+   */
+  pendingInstallNotice: string | null;
+}
+
+async function ensurePlaywright(
+  state: SidecarState,
+  opts: { browser?: BrowserKind; headless?: boolean },
+): Promise<PlaywrightHandle> {
+  if (state.handle) return state.handle;
+  const pw = await importPlaywright();
+  const which = opts.browser ?? 'chromium';
+  const browserType = pw[which];
+  const { handle, installNotice } = await launchWithAutoInstall(browserType, which, opts.headless ?? true);
+  state.handle = handle;
+  if (installNotice) state.pendingInstallNotice = installNotice;
+  return state.handle;
+}
+
+export async function teardown(state: SidecarState): Promise<void> {
+  if (!state.handle) return;
+  try {
+    await state.handle.context.close();
+    await state.handle.browser.close();
+  } catch {
+    /* ignore */
+  }
+  state.handle = null;
+}
+
+export async function dispatch(state: SidecarState, req: Req): Promise<Reply> {
+  try {
+    return await dispatchInner(state, req);
+  } catch (err) {
+    return {
+      id: req.id,
+      ok: false,
+      error: { message: errMsg(err), kind: err instanceof SidecarError ? err.kind : 'unknown' },
+    };
+  }
+}
+
+async function dispatchInner(state: SidecarState, req: Req): Promise<Reply> {
+  switch (req.method) {
+    case 'init': {
+      const opts = (req.params ?? {}) as { browser?: BrowserKind; headless?: boolean };
+      await ensurePlaywright(state, opts);
+      return { id: req.id, ok: true, result: { ready: true } };
+    }
+    case 'goto': {
+      const { url, waitUntil, timeoutMs } = (req.params ?? {}) as {
+        url: string;
+        waitUntil?: 'load' | 'domcontentloaded' | 'networkidle';
+        timeoutMs?: number;
+      };
+      if (!url) throw badParams('url is required');
+      // Defence-in-depth: the parent already runs the full SSRF guard before
+      // sending this RPC, but the sidecar is a distinct process driven over
+      // JSON-RPC, so re-check here rather than trust the caller to have
+      // validated. Blocks file:// / javascript: schemes AND loopback/private/
+      // link-local (incl. 169.254.169.254 metadata)/CGNAT targets, resolving
+      // hostnames. Runs BEFORE ensurePlaywright so a blocked URL never
+      // launches (or auto-installs) a browser.
+      try {
+        // fail-closed: the browser resolves names with Chromium's own resolver,
+        // so a name node:dns can't vet must not pass through un-checked.
+        await assertPublicUrl(url, 'goto', { failClosed: true });
+      } catch (err) {
+        return { id: req.id, ok: false, error: { message: errMsg(err), kind: 'navigation' } };
+      }
+      const h = await ensurePlaywright(state, {});
+      try {
+        await h.page.goto(url, { waitUntil: waitUntil ?? 'domcontentloaded', timeout: timeoutMs ?? 30_000 });
+      } catch (err) {
+        return { id: req.id, ok: false, error: { message: errMsg(err), kind: 'navigation' } };
+      }
+      return { id: req.id, ok: true, result: { url: h.page.url() } };
+    }
+    case 'click': {
+      const h = await ensurePlaywright(state, {});
+      const { selector, timeoutMs } = (req.params ?? {}) as { selector: string; timeoutMs?: number };
+      if (!selector) throw badParams('selector is required');
+      await h.page.click(selector, { timeout: timeoutMs ?? 10_000 });
+      return { id: req.id, ok: true };
+    }
+    case 'fill': {
+      const h = await ensurePlaywright(state, {});
+      const { selector, value, timeoutMs } = (req.params ?? {}) as {
+        selector: string;
+        value: string;
+        timeoutMs?: number;
+      };
+      if (!selector) throw badParams('selector is required');
+      await h.page.fill(selector, value ?? '', { timeout: timeoutMs ?? 10_000 });
+      return { id: req.id, ok: true };
+    }
+    case 'text': {
+      const h = await ensurePlaywright(state, {});
+      const { selector } = (req.params ?? {}) as { selector?: string };
+      if (selector) {
+        const text = await h.page.textContent(selector);
+        return { id: req.id, ok: true, result: text ?? '' };
+      }
+      // Whole-document text via evaluate
+      const text = (await h.page.evaluate('document.body ? document.body.innerText : ""')) as string;
+      return { id: req.id, ok: true, result: text };
+    }
+    case 'html': {
+      const h = await ensurePlaywright(state, {});
+      const html = await h.page.content();
+      return { id: req.id, ok: true, result: html };
+    }
+    case 'screenshot': {
+      const h = await ensurePlaywright(state, {});
+      const { fullPage } = (req.params ?? {}) as { fullPage?: boolean };
+      const buf = await h.page.screenshot({ fullPage: fullPage ?? false, timeout: SCREENSHOT_TIMEOUT_MS });
+      return { id: req.id, ok: true, result: { mediaType: 'image/png', base64: buf.toString('base64') } };
+    }
+    case 'frame': {
+      // Combined live-view frame for the browser SURFACE: a JPEG screenshot
+      // plus the current url + viewport size, so the renderer can map clicks
+      // back onto the page. One round-trip per frame.
+      const h = await ensurePlaywright(state, {});
+      // quality 70 (was 55) + the context's deviceScaleFactor:2 = legible text in
+      // the live view. Reports the CSS viewport size (the image is 2× that) so the
+      // renderer keeps mapping clicks in CSS coords.
+      const buf = await h.page.screenshot({ type: 'jpeg', quality: 70, timeout: SCREENSHOT_TIMEOUT_MS });
+      const vp = h.page.viewportSize() ?? { width: 1280, height: 720 };
+      return {
+        id: req.id,
+        ok: true,
+        result: {
+          mediaType: 'image/jpeg',
+          base64: buf.toString('base64'),
+          url: h.page.url(),
+          width: vp.width,
+          height: vp.height,
+        },
+      };
+    }
+    case 'mouse': {
+      const { x, y, count } = (req.params ?? {}) as { x: number; y: number; count?: number };
+      // Parity with `key`/`eval`: validate before launching/driving the page so
+      // a malformed surface message (missing/NaN coords) surfaces a clean
+      // `badParams` instead of an opaque Playwright throw from click(undefined).
+      if (!Number.isFinite(x) || !Number.isFinite(y)) throw badParams('x and y must be finite numbers');
+      const h = await ensurePlaywright(state, {});
+      await h.page.mouse.click(x, y, { clickCount: Math.min(3, Math.max(1, count ?? 1)) });
+      return { id: req.id, ok: true, result: { url: h.page.url() } };
+    }
+    case 'mousemove': {
+      // Hover: drives the page's pointer so :hover styles / tooltips render in
+      // the polled frame. Cheap; the surface throttles how often it sends these.
+      const { x, y } = (req.params ?? {}) as { x: number; y: number };
+      if (!Number.isFinite(x) || !Number.isFinite(y)) throw badParams('x and y must be finite numbers');
+      const h = await ensurePlaywright(state, {});
+      await h.page.mouse.move(x, y);
+      return { id: req.id, ok: true };
+    }
+    case 'setviewport': {
+      // Resize the page to the pane so the live view fills the container instead
+      // of being letterboxed at the default 1280×720.
+      const { width, height } = (req.params ?? {}) as { width: number; height: number };
+      if (!Number.isFinite(width) || !Number.isFinite(height) || width < 1 || height < 1) {
+        throw badParams('width and height must be positive finite numbers');
+      }
+      // Clamp to Chromium's max so a malformed surface message (width:1e9) can't
+      // trigger a multi-GB allocation / opaque Playwright throw.
+      if (width > MAX_DIMENSION || height > MAX_DIMENSION) {
+        throw badParams(`width and height must be <= ${MAX_DIMENSION}`);
+      }
+      const h = await ensurePlaywright(state, {});
+      await h.page.setViewportSize({ width: Math.round(width), height: Math.round(height) });
+      return { id: req.id, ok: true };
+    }
+    case 'back':
+    case 'forward':
+    case 'reload': {
+      const h = await ensurePlaywright(state, {});
+      try {
+        if (req.method === 'back') await h.page.goBack();
+        else if (req.method === 'forward') await h.page.goForward();
+        else await h.page.reload();
+      } catch (err) {
+        // No history to go to is not an error worth failing the surface over.
+        return { id: req.id, ok: false, error: { message: errMsg(err), kind: 'navigation' } };
+      }
+      return { id: req.id, ok: true, result: { url: h.page.url() } };
+    }
+    case 'key': {
+      const h = await ensurePlaywright(state, {});
+      const { key } = (req.params ?? {}) as { key: string };
+      if (!key) throw badParams('key is required');
+      // A single printable char is typed (inserts it); a named key is pressed.
+      if (key.length === 1) await h.page.keyboard.type(key);
+      else await h.page.keyboard.press(key);
+      return { id: req.id, ok: true };
+    }
+    case 'scroll': {
+      const h = await ensurePlaywright(state, {});
+      const { dy } = (req.params ?? {}) as { dy: number };
+      await h.page.mouse.wheel(0, dy ?? 0);
+      return { id: req.id, ok: true };
+    }
+    case 'zoom': {
+      // Page zoom for the surface (⌘+/⌘−). CSS `zoom` is the cheapest faithful
+      // way to scale a screenshot-streamed page; clamped to a sane range.
+      const { factor } = (req.params ?? {}) as { factor: number };
+      const f = Number.isFinite(factor) ? Math.min(5, Math.max(0.25, factor)) : 1;
+      const h = await ensurePlaywright(state, {});
+      await h.page.evaluate(`document.documentElement.style.zoom=String(${f})`);
+      return { id: req.id, ok: true };
+    }
+    case 'capture': {
+      // Sharp PNG of a region the user dragged — attached to the chat composer so
+      // the agent SEES the area ("change this to …"). Coords are CSS px; the
+      // context's deviceScaleFactor:2 makes the PNG 2× → crisp.
+      const { x, y, width, height } = (req.params ?? {}) as {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+      };
+      if (![x, y, width, height].every((n) => Number.isFinite(n)) || width < 1 || height < 1) {
+        throw badParams('x, y, width, height must be finite; width/height positive');
+      }
+      // Bound the clip so an enormous (or hostile, viewport-multiplied) region
+      // can't request a multi-GB screenshot allocation.
+      if (width > MAX_DIMENSION || height > MAX_DIMENSION) {
+        throw badParams(`clip width and height must be <= ${MAX_DIMENSION}`);
+      }
+      const h = await ensurePlaywright(state, {});
+      const buf = await h.page.screenshot({ type: 'png', clip: { x, y, width, height }, timeout: SCREENSHOT_TIMEOUT_MS });
+      return { id: req.id, ok: true, result: { mediaType: 'image/png', base64: buf.toString('base64') } };
+    }
+    case 'pick': {
+      // Identify the element at (x,y) so the user can hand it to the agent
+      // ("change this XXX to YYY"). Returns a best-effort CSS selector + a short
+      // text snippet; the agent's browser_session tool can act on the selector.
+      const { x, y } = (req.params ?? {}) as { x: number; y: number };
+      if (!Number.isFinite(x) || !Number.isFinite(y)) throw badParams('x and y must be finite numbers');
+      const h = await ensurePlaywright(state, {});
+      const expr =
+        `(() => { const x=${x}, y=${y}; const el=document.elementFromPoint(x,y);` +
+        ` if(!el) return null;` +
+        ` const sel=(e)=>{ if(e.id) return '#'+CSS.escape(e.id); const p=[]; let n=e;` +
+        ` while(n && n.nodeType===1 && n!==document.body){ let s=n.tagName.toLowerCase();` +
+        ` if(n.classList && n.classList.length) s+='.'+Array.from(n.classList).slice(0,2).map(c=>CSS.escape(c)).join('.');` +
+        ` const par=n.parentElement; if(par){ const same=Array.from(par.children).filter(c=>c.tagName===n.tagName);` +
+        ` if(same.length>1) s+=':nth-of-type('+(same.indexOf(n)+1)+')'; } p.unshift(s); n=n.parentElement; }` +
+        ` return p.join(' > '); };` +
+        ` return { selector: sel(el), tag: el.tagName.toLowerCase(), text: (el.textContent||'').replace(/\\s+/g,' ').trim().slice(0,140) }; })()`;
+      const info = await h.page.evaluate(expr);
+      return { id: req.id, ok: true, result: info };
+    }
+    case 'eval': {
+      const h = await ensurePlaywright(state, {});
+      const { expression } = (req.params ?? {}) as { expression: string };
+      if (!expression) throw badParams('expression is required');
+      const value = await h.page.evaluate(expression);
+      return { id: req.id, ok: true, result: value };
+    }
+    case 'url': {
+      const h = await ensurePlaywright(state, {});
+      return { id: req.id, ok: true, result: h.page.url() };
+    }
+    case 'close': {
+      await teardown(state);
+      return { id: req.id, ok: true };
+    }
+    default:
+      return {
+        id: req.id,
+        ok: false,
+        error: { message: `unknown method: ${req.method}`, kind: 'runtime' },
+      };
+  }
+}

package/src/sidecar/install.ts

@@ -0,0 +1,283 @@
+/**
+ * Playwright lifecycle: import, launch, and one-shot auto-install of the
+ * per-browser binary. Keeps the dispatch layer free of node:child_process
+ * + Playwright-import noise.
+ */
+
+import { spawn } from 'node:child_process';
+import { assertPublicUrl } from '../ssrf-guard.js';
+import { SidecarError } from './types.js';
+import type { BrowserKind, BrowserType, PageHandle, PlaywrightHandle } from './types.js';
+
+export interface LaunchResult {
+  handle: PlaywrightHandle;
+  /** Set when the browser binary was auto-downloaded during this launch. */
+  installNotice: string | null;
+}
+
+export async function importPlaywright(): Promise<{
+  chromium: BrowserType;
+  firefox: BrowserType;
+  webkit: BrowserType;
+}> {
+  try {
+    return (await import('playwright')) as never;
+  } catch (err) {
+    const underlying = err instanceof Error ? err.message : String(err);
+    // Distinguish "the npm package isn't installed" (recoverable — the surface
+    // can offer a one-click install, see `installPlaywrightPackage`) from any
+    // other import failure. The `kind` rides the JSON-RPC reply so the browser
+    // surface shows an "Install" affordance instead of a dead-end error.
+    throw new SidecarError(
+      `Playwright is not installed. Run \`pnpm add playwright\` (or \`npm i playwright\`) and then \`npx playwright install\` in the moxxy install dir.\n` +
+        `Underlying: ${underlying}`,
+      isModuleNotFound(underlying) ? 'needs-install' : 'init',
+    );
+  }
+}
+
+/** True when an import failure is "the `playwright` package can't be found"
+ *  (vs. a load/runtime error inside an installed package). */
+function isModuleNotFound(message: string): boolean {
+  return (
+    /cannot find (package|module) ['"]?playwright/i.test(message) ||
+    /ERR_MODULE_NOT_FOUND/i.test(message) ||
+    /failed to resolve ['"]?playwright/i.test(message)
+  );
+}
+
+export interface InstallPlaywrightOptions {
+  /** Directory whose `node_modules` should receive `playwright` — the CLI
+   *  install root (e.g. `<userData>/cli`). `npm` runs with this as its cwd. */
+  readonly rootDir: string;
+  /** Which browser engine binary to download after the npm package lands. */
+  readonly browser?: BrowserKind;
+  /** Per-line progress (npm/npx stdout+stderr) for streaming to the UI. */
+  readonly onProgress?: (line: string) => void;
+  readonly signal?: AbortSignal;
+}
+
+/**
+ * Install the `playwright` npm package into `rootDir`, then download the browser
+ * engine binary — the two halves the desktop browser surface needs. Driven by
+ * the surface AFTER the user consents (the download is ~200MB). Streams progress
+ * via `onProgress`; resolves on success, rejects with the failing step's output.
+ *
+ * Lives next to {@link importPlaywright} (which reports the `needs-install` that
+ * triggers this) but is invoked in the RUNNER process — `rootDir`'s node_modules
+ * is the one the sidecar later imports `playwright` from.
+ */
+/** Pin the npm install to this range so the one-click installer fetches a
+ *  vetted, deterministic version (matching the package's `playwright`
+ *  peerDependency) rather than whatever "latest" resolves to. */
+const PLAYWRIGHT_VERSION_RANGE = '^1.40.0';
+
+export async function installPlaywrightPackage(opts: InstallPlaywrightOptions): Promise<void> {
+  const which = opts.browser ?? 'chromium';
+  opts.onProgress?.(
+    `Installing the playwright npm package (${PLAYWRIGHT_VERSION_RANGE}) into ${opts.rootDir}…`,
+  );
+  // `--save-exact false` keeps the range; the explicit version pin (vs bare
+  // "playwright") stops a hijacked registry "latest" from being pulled.
+  await runProcess(
+    'npm',
+    ['install', '--no-fund', '--no-audit', `playwright@${PLAYWRIGHT_VERSION_RANGE}`],
+    opts,
+  );
+  opts.onProgress?.(`Downloading the ${which} browser engine (~150MB, one-time)…`);
+  await runProcess('npx', ['playwright', 'install', which], opts);
+  opts.onProgress?.('Playwright installed.');
+}
+
+/** Spawn a child, forward its output to `onProgress`, resolve on exit-0. */
+function runProcess(cmd: string, args: string[], opts: InstallPlaywrightOptions): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (opts.signal?.aborted) return reject(new Error('install aborted'));
+    const child = spawn(cmd, args, { cwd: opts.rootDir, stdio: ['ignore', 'pipe', 'pipe'] });
+    let tail = '';
+    const onChunk = (chunk: Buffer): void => {
+      const text = chunk.toString('utf8');
+      for (const line of text.split(/\r?\n/)) if (line.trim()) opts.onProgress?.(line);
+      tail = (tail + text).slice(-4000);
+    };
+    child.stdout.on('data', onChunk);
+    child.stderr.on('data', onChunk);
+    const onAbort = (): void => {
+      child.kill();
+    };
+    opts.signal?.addEventListener('abort', onAbort, { once: true });
+    child.once('error', (err) => {
+      opts.signal?.removeEventListener('abort', onAbort);
+      reject(err);
+    });
+    child.once('close', (code) => {
+      opts.signal?.removeEventListener('abort', onAbort);
+      if (code === 0) resolve();
+      else
+        reject(
+          new Error(`\`${cmd} ${args.join(' ')}\` failed (exit ${code}): ${tail.trim() || '(no output)'}`),
+        );
+    });
+  });
+}
+
+/**
+ * Try to launch the browser. If the binary isn't downloaded yet
+ * (Playwright distinguishes the npm install from the per-browser
+ * binary download), run `npx playwright install <which>` once and
+ * retry. The install can take 30s–2min on the first run depending on
+ * connection; we surface progress on stderr (parent forwards to the
+ * logger) and return a one-shot notice for the first tool response.
+ */
+export async function launchWithAutoInstall(
+  browserType: BrowserType,
+  which: BrowserKind,
+  headless: boolean,
+): Promise<LaunchResult> {
+  try {
+    return { handle: await launchOnce(browserType, headless), installNotice: null };
+  } catch (err) {
+    if (!isMissingBrowserError(err)) throw err;
+    process.stderr.write(
+      `moxxy-browser: ${which} binary missing, running \`npx playwright install ${which}\` ` +
+        `(one-time, ~150MB). This may take a minute…\n`,
+    );
+    try {
+      await runPlaywrightInstall(which);
+    } catch (installErr) {
+      const msg = installErr instanceof Error ? installErr.message : String(installErr);
+      throw new SidecarError(
+        `Playwright browser auto-install failed: ${msg}. ` +
+          `Run \`npx playwright install ${which}\` manually in the moxxy dir.`,
+        'init',
+      );
+    }
+    process.stderr.write(`moxxy-browser: install complete, retrying launch\n`);
+    return {
+      handle: await launchOnce(browserType, headless),
+      installNotice: `Auto-installed Playwright ${which} browser (~150MB, one-time).`,
+    };
+  }
+}
+
+async function launchOnce(browserType: BrowserType, headless: boolean): Promise<PlaywrightHandle> {
+  const browser = await browserType.launch({ headless });
+  // deviceScaleFactor: 2 so the live-view / region screenshots are captured at
+  // Retina density — a 1× capture upscaled into a HiDPI pane is what made the
+  // surface look blurry. Costs ~2× the screenshot bytes; worth it for crisp text.
+  const context = (await browser.newContext({ deviceScaleFactor: 2 })) as PlaywrightHandle['context'];
+  await installNavigationSsrfGuard(context);
+  const page = (await context.newPage()) as unknown as PageHandle;
+  return { browser, context, page };
+}
+
+/**
+ * Block navigations to private/loopback origins for the lifetime of the
+ * context. The goto RPC is validated in the parent AND in dispatch, but a
+ * page reached via a legitimate public goto can then redirect or
+ * script-navigate itself to e.g. http://169.254.169.254/ — those navigations
+ * never pass through the RPC layer, so we intercept them here. Navigation
+ * requests (top-level + iframes, which covers HTTP redirect hops too) go
+ * through the same `assertPublicUrl` guard as web_fetch; everything else is
+ * passed through untouched so ordinary page loads don't pay a DNS round-trip
+ * per subresource.
+ *
+ * Residual risk: by default SUBRESOURCE requests (img/fetch/script) from a
+ * loaded page are NOT filtered — a hostile page can fire blind GET/POSTs at
+ * internal services as side effects (the browser's same-origin policy stops it
+ * READING the responses, but the request still lands). Opt into filtering every
+ * request — at the cost of a (cached) DNS resolution per distinct host — by
+ * setting `MOXXY_BROWSER_FILTER_SUBRESOURCES=1`.
+ */
+async function installNavigationSsrfGuard(context: PlaywrightHandle['context']): Promise<void> {
+  if (typeof context.route !== 'function') {
+    // Loose projection: tests pass a stub without route(). But a REAL Playwright
+    // context always has route(), so if a production context ever reaches here
+    // the in-page navigation guard is silently absent — make that loud on stderr
+    // (the parent forwards it to the logger) instead of failing open invisibly.
+    process.stderr.write(
+      'moxxy-browser: WARNING context.route() unavailable — in-page navigation SSRF guard NOT installed\n',
+    );
+    return;
+  }
+  const filterSubresources = process.env.MOXXY_BROWSER_FILTER_SUBRESOURCES === '1';
+  // Cache per-host guard verdicts so the opt-in subresource path doesn't pay a
+  // DNS round-trip per request (pages fire dozens at the same few hosts).
+  // Bounded so a page referencing thousands of distinct hosts can't grow it
+  // without limit (oldest entries evicted; re-resolved on next sight).
+  const verdictCache = new Map<string, boolean>();
+  const MAX_VERDICT_CACHE = 2048;
+  const remember = (host: string, blocked: boolean): void => {
+    if (verdictCache.size >= MAX_VERDICT_CACHE) {
+      const oldest = verdictCache.keys().next().value;
+      if (oldest !== undefined) verdictCache.delete(oldest);
+    }
+    verdictCache.set(host, blocked);
+  };
+  await context.route('**/*', async (route) => {
+    const request = route.request();
+    const isNav = request.isNavigationRequest();
+    if (!isNav && !filterSubresources) return route.continue();
+    const url = request.url();
+    let host = '';
+    try {
+      host = new URL(url).host;
+    } catch {
+      // Unparseable URL — only the navigation path needs a hard verdict.
+      if (isNav) return route.abort('blockedbyclient');
+      return route.continue();
+    }
+    // Navigations are always re-checked live (cheap, and the cache is keyed by
+    // host so a vetted host stays vetted). Subresources consult the cache first.
+    const cached = !isNav ? verdictCache.get(host) : undefined;
+    if (cached === true) return route.abort('blockedbyclient');
+    if (cached === false) return route.continue();
+    try {
+      // fail-closed: an unresolvable name must not navigate the browser (whose
+      // resolver may differ from node:dns).
+      await assertPublicUrl(
+        url,
+        isNav ? 'browser_session navigation' : 'browser_session subresource',
+        { failClosed: true },
+      );
+      remember(host, false);
+    } catch {
+      remember(host, true);
+      return route.abort('blockedbyclient');
+    }
+    return route.continue();
+  });
+}
+
+function isMissingBrowserError(err: unknown): boolean {
+  if (!(err instanceof Error)) return false;
+  // Playwright's "Executable doesn't exist at …" launch error fires
+  // when the npm package is installed but the per-browser binary
+  // hasn't been downloaded. The message stays stable across versions.
+  return /Executable doesn'?t exist at/i.test(err.message);
+}
+
+/**
+ * Run `npx playwright install <which>` and stream its output to the
+ * sidecar's stderr so the operator can watch progress. Resolves on
+ * exit-0; rejects with the tail of stderr otherwise.
+ */
+function runPlaywrightInstall(which: BrowserKind): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const child = spawn('npx', ['playwright', 'install', which], {
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    let stderrTail = '';
+    child.stdout.on('data', (chunk: Buffer) => process.stderr.write(chunk));
+    child.stderr.on('data', (chunk: Buffer) => {
+      process.stderr.write(chunk);
+      stderrTail += chunk.toString('utf8');
+      if (stderrTail.length > 4000) stderrTail = stderrTail.slice(-4000);
+    });
+    child.once('error', (err) => reject(err));
+    child.once('close', (code) => {
+      if (code === 0) resolve();
+      else reject(new Error(`exit ${code}: ${stderrTail.trim() || '(no stderr)'}`));
+    });
+  });
+}

package/src/sidecar/types.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it } from 'vitest';
+import { badParams, SidecarError } from './types.js';
+
+/**
+ * `SidecarError` is the typed carrier that lets `dispatch` map a thrown error
+ * onto the wire reply's `error.kind` without the old untyped `(e as Error &
+ * { kind? }).kind = …` double-cast. These cover the carrier itself; the mapping
+ * is exercised end-to-end in dispatch.test.ts.
+ */
+describe('SidecarError carrier', () => {
+  it('is a real Error carrying message + kind', () => {
+    const err = new SidecarError('boom', 'init');
+    expect(err).toBeInstanceOf(Error);
+    expect(err).toBeInstanceOf(SidecarError);
+    expect(err.message).toBe('boom');
+    expect(err.kind).toBe('init');
+    expect(err.name).toBe('SidecarError');
+  });
+
+  it('badParams produces a runtime-kind SidecarError', () => {
+    const err = badParams('selector is required');
+    expect(err).toBeInstanceOf(SidecarError);
+    expect(err.message).toBe('selector is required');
+    expect(err.kind).toBe('runtime');
+  });
+});