@open-mercato/web-research-browser 0.7.1-develop.7194.1.ab4fc81f82

package/dist/playwright.js

@@ -0,0 +1,143 @@
+import { spawn } from "node:child_process";
+import { assertPublicUrl } from "@open-mercato/web-research";
+import { SidecarError } from "./protocol.js";
+function isModuleNotFound(message) {
+  return /cannot find (package|module) ['"]?playwright/i.test(message) || /ERR_MODULE_NOT_FOUND/i.test(message) || /failed to resolve ['"]?playwright/i.test(message);
+}
+async function importChromium() {
+  try {
+    const playwright = await import("playwright");
+    return playwright.chromium;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new SidecarError(
+      `Playwright could not be loaded even though it is a dependency of this package \u2014 reinstall dependencies. Underlying: ${message}`,
+      isModuleNotFound(message) ? "needs-install" : "init"
+    );
+  }
+}
+function isMissingBrowserError(error) {
+  return error instanceof Error && /Executable doesn'?t exist at/i.test(error.message);
+}
+const INSTALL_TIMEOUT_MS = 10 * 6e4;
+const defaultInstallRunner = async (onProgress) => new Promise((resolve, reject) => {
+  const child = spawn("npx", ["playwright", "install", "chromium"], { stdio: ["ignore", "pipe", "pipe"] });
+  let tail = "";
+  const collect = (chunk) => {
+    tail = `${tail}${chunk.toString("utf8")}`.slice(-4e3);
+  };
+  child.stdout?.on("data", collect);
+  child.stderr?.on("data", collect);
+  const timer = setTimeout(() => {
+    child.kill("SIGKILL");
+    reject(new Error(`\`npx playwright install chromium\` exceeded ${INSTALL_TIMEOUT_MS}ms`));
+  }, INSTALL_TIMEOUT_MS);
+  child.once("error", (error) => {
+    clearTimeout(timer);
+    reject(error);
+  });
+  child.once("close", (code) => {
+    clearTimeout(timer);
+    if (code === 0) {
+      onProgress("chromium install complete");
+      resolve();
+      return;
+    }
+    reject(new Error(`\`npx playwright install chromium\` failed (exit ${code}): ${tail.trim()}`));
+  });
+});
+async function launchChromium(browserType, options, deps = {}) {
+  try {
+    return await browserType.launch(options);
+  } catch (error) {
+    if (isSandboxFailure(error)) {
+      throw new SidecarError(
+        `Chromium could not start its sandbox, and this adapter renders untrusted pages so it will not run without one. Fix the container (run as a non-root user, or grant SYS_ADMIN, or enable user namespaces), or accept the risk explicitly with ${SANDBOX_OPT_OUT_ENV}=1. Underlying: ${error instanceof Error ? error.message : String(error)}`,
+        "init"
+      );
+    }
+    if (!isMissingBrowserError(error)) throw error;
+    const onProgress = deps.onProgress ?? (() => {
+    });
+    onProgress("chromium binary missing, running `npx playwright install chromium` (one-time, ~150MB)");
+    try {
+      await (deps.install ?? defaultInstallRunner)(onProgress);
+    } catch (installError) {
+      const detail = installError instanceof Error ? installError.message : String(installError);
+      throw new SidecarError(
+        `Playwright browser auto-install failed: ${detail}. Run \`npx playwright install chromium\` manually.`,
+        "init"
+      );
+    }
+    return await browserType.launch(options);
+  }
+}
+const MAX_VERDICT_CACHE = 2048;
+async function installNavigationGuard(context, options = {}) {
+  if (typeof context.route !== "function") {
+    options.warn?.("context.route() unavailable \u2014 in-page navigation SSRF guard NOT installed");
+    return;
+  }
+  const filterSubresources = options.filterSubresources ?? false;
+  const verdicts = /* @__PURE__ */ new Map();
+  const remember = (host, blocked) => {
+    if (verdicts.size >= MAX_VERDICT_CACHE) {
+      const oldest = verdicts.keys().next().value;
+      if (oldest !== void 0) verdicts.delete(oldest);
+    }
+    verdicts.set(host, blocked);
+  };
+  await context.route("**/*", async (route) => {
+    const request = route.request();
+    const isNavigation = request.isNavigationRequest();
+    if (!isNavigation && !filterSubresources) return route.continue();
+    const url = request.url();
+    let host;
+    try {
+      host = new URL(url).host;
+    } catch {
+      return isNavigation ? route.abort("blockedbyclient") : route.continue();
+    }
+    const cached = isNavigation ? void 0 : verdicts.get(host);
+    if (cached === true) return route.abort("blockedbyclient");
+    if (cached === false) return route.continue();
+    try {
+      await assertPublicUrl(url, isNavigation ? "browser navigation" : "browser subresource", {
+        failClosed: true
+      });
+      remember(host, false);
+    } catch {
+      remember(host, true);
+      return route.abort("blockedbyclient");
+    }
+    return route.continue();
+  });
+}
+const LAUNCH_ARGS = [
+  "--disable-blink-features=AutomationControlled",
+  "--disable-dev-shm-usage"
+];
+const SANDBOX_OPT_OUT_ENV = "OM_WEB_RESEARCH_BROWSER_NO_SANDBOX";
+function resolveLaunchArgs(env = process.env) {
+  return env[SANDBOX_OPT_OUT_ENV] === "1" ? [...LAUNCH_ARGS, "--no-sandbox"] : [...LAUNCH_ARGS];
+}
+function isSandboxDisabled(env = process.env) {
+  return env[SANDBOX_OPT_OUT_ENV] === "1";
+}
+function isSandboxFailure(error) {
+  if (!(error instanceof Error)) return false;
+  return /running as root without --no-sandbox/i.test(error.message) || /No usable sandbox/i.test(error.message) || /clone helper|namespace sandbox|SUID sandbox/i.test(error.message);
+}
+const DEFAULT_USER_AGENT = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36";
+export {
+  DEFAULT_USER_AGENT,
+  LAUNCH_ARGS,
+  SANDBOX_OPT_OUT_ENV,
+  importChromium,
+  installNavigationGuard,
+  isSandboxDisabled,
+  isSandboxFailure,
+  launchChromium,
+  resolveLaunchArgs
+};
+//# sourceMappingURL=playwright.js.map

package/dist/playwright.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/playwright.ts"],
+  "sourcesContent": ["import { spawn } from 'node:child_process'\nimport { assertPublicUrl } from '@open-mercato/web-research'\nimport { SidecarError } from './protocol'\n\n/**\n * Structural projections of the Playwright surface we touch.\n *\n * Playwright is a real dependency of this package \u2014 installing the adapter gets\n * you the tooling it needs \u2014 but it is still reached through a dynamic import\n * inside the sidecar, so the app and MCP processes never load it. The types stay\n * structural for the same reason: nothing here should pull the SDK into a bundle\n * that only ever spawns the child.\n */\nexport type PageHandle = {\n  goto(url: string, options?: { waitUntil?: string; timeout?: number }): Promise<unknown>\n  content(): Promise<string>\n  url(): string\n  close(): Promise<void>\n}\n\nexport type ContextHandle = {\n  newPage(): Promise<unknown>\n  close(): Promise<void>\n  route?(pattern: string, handler: (route: RouteHandle) => Promise<void> | void): Promise<void>\n}\n\nexport type RouteHandle = {\n  request(): { url(): string; isNavigationRequest(): boolean }\n  abort(reason?: string): Promise<void>\n  continue(): Promise<void>\n}\n\nexport type BrowserHandle = {\n  newContext(options?: Record<string, unknown>): Promise<ContextHandle>\n  close(): Promise<void>\n}\n\nexport type BrowserType = {\n  launch(options?: { headless?: boolean; args?: string[] }): Promise<BrowserHandle>\n}\n\nfunction isModuleNotFound(message: string): boolean {\n  return (\n    /cannot find (package|module) ['\"]?playwright/i.test(message) ||\n    /ERR_MODULE_NOT_FOUND/i.test(message) ||\n    /failed to resolve ['\"]?playwright/i.test(message)\n  )\n}\n\nexport async function importChromium(): Promise<BrowserType> {\n  try {\n    const playwright = (await import('playwright')) as unknown as { chromium: BrowserType }\n    return playwright.chromium\n  } catch (error) {\n    const message = error instanceof Error ? error.message : String(error)\n    // Playwright is a dependency of this package, so a module-not-found here\n    // means a broken install (hoisting, a pruned image layer), not a missing opt-in.\n    throw new SidecarError(\n      `Playwright could not be loaded even though it is a dependency of this package \u2014 reinstall dependencies. Underlying: ${message}`,\n      isModuleNotFound(message) ? 'needs-install' : 'init',\n    )\n  }\n}\n\n/**\n * Playwright's launch error when the npm package is installed but the browser\n * binary was never downloaded. The wording has been stable across 1.x, and it is\n * the only signal Playwright gives for this case.\n */\nfunction isMissingBrowserError(error: unknown): boolean {\n  return error instanceof Error && /Executable doesn'?t exist at/i.test(error.message)\n}\n\n/** Generous, but bounded \u2014 an unbounded install hangs the sidecar forever. */\nconst INSTALL_TIMEOUT_MS = 10 * 60_000\n\nexport type InstallRunner = (onProgress: (line: string) => void) => Promise<void>\n\nconst defaultInstallRunner: InstallRunner = async (onProgress) =>\n  new Promise((resolve, reject) => {\n    const child = spawn('npx', ['playwright', 'install', 'chromium'], { stdio: ['ignore', 'pipe', 'pipe'] })\n    let tail = ''\n    const collect = (chunk: Buffer): void => {\n      tail = `${tail}${chunk.toString('utf8')}`.slice(-4000)\n    }\n    child.stdout?.on('data', collect)\n    child.stderr?.on('data', collect)\n\n    const timer = setTimeout(() => {\n      child.kill('SIGKILL')\n      reject(new Error(`\\`npx playwright install chromium\\` exceeded ${INSTALL_TIMEOUT_MS}ms`))\n    }, INSTALL_TIMEOUT_MS)\n\n    child.once('error', (error) => {\n      clearTimeout(timer)\n      reject(error)\n    })\n    child.once('close', (code) => {\n      clearTimeout(timer)\n      if (code === 0) {\n        onProgress('chromium install complete')\n        resolve()\n        return\n      }\n      reject(new Error(`\\`npx playwright install chromium\\` failed (exit ${code}): ${tail.trim()}`))\n    })\n  })\n\n/**\n * Launches Chromium, downloading the binary once if it is missing.\n *\n * Installing the npm package does not fetch the ~150MB browser, so an operator\n * who enables this tier would otherwise hit a launch failure with no obvious\n * remedy. One retry only \u2014 a second failure is a real fault, not a cold cache.\n */\nexport async function launchChromium(\n  browserType: BrowserType,\n  options: { headless?: boolean; args?: string[] },\n  deps: { install?: InstallRunner; onProgress?: (line: string) => void } = {},\n): Promise<BrowserHandle> {\n  try {\n    return await browserType.launch(options)\n  } catch (error) {\n    // Deliberately not retried without the sandbox. Falling back silently would\n    // mean the security posture depends on whether a container happened to be\n    // configured, with nobody told which one they got.\n    if (isSandboxFailure(error)) {\n      throw new SidecarError(\n        `Chromium could not start its sandbox, and this adapter renders untrusted pages so it will not run without one. ` +\n          `Fix the container (run as a non-root user, or grant SYS_ADMIN, or enable user namespaces), ` +\n          `or accept the risk explicitly with ${SANDBOX_OPT_OUT_ENV}=1. Underlying: ${error instanceof Error ? error.message : String(error)}`,\n        'init',\n      )\n    }\n    if (!isMissingBrowserError(error)) throw error\n    const onProgress = deps.onProgress ?? (() => {})\n    onProgress('chromium binary missing, running `npx playwright install chromium` (one-time, ~150MB)')\n    try {\n      await (deps.install ?? defaultInstallRunner)(onProgress)\n    } catch (installError) {\n      const detail = installError instanceof Error ? installError.message : String(installError)\n      throw new SidecarError(\n        `Playwright browser auto-install failed: ${detail}. Run \\`npx playwright install chromium\\` manually.`,\n        'init',\n      )\n    }\n    return await browserType.launch(options)\n  }\n}\n\nconst MAX_VERDICT_CACHE = 2048\n\n/**\n * Blocks private-origin navigations for the life of the context.\n *\n * The parent and the sidecar both vet the URL before a `goto`, but a page reached\n * through a legitimate public navigation can redirect or script-navigate itself\n * to a metadata endpoint, and those hops never pass through the RPC layer.\n *\n * Fails closed: Chromium resolves names with its own resolver, so a hostname\n * `node:dns` cannot vet must not be allowed through on the assumption it is dead.\n */\nexport async function installNavigationGuard(\n  context: ContextHandle,\n  options: { filterSubresources?: boolean; warn?: (message: string) => void } = {},\n): Promise<void> {\n  if (typeof context.route !== 'function') {\n    options.warn?.('context.route() unavailable \u2014 in-page navigation SSRF guard NOT installed')\n    return\n  }\n  const filterSubresources = options.filterSubresources ?? false\n  const verdicts = new Map<string, boolean>()\n  const remember = (host: string, blocked: boolean): void => {\n    if (verdicts.size >= MAX_VERDICT_CACHE) {\n      const oldest = verdicts.keys().next().value\n      if (oldest !== undefined) verdicts.delete(oldest)\n    }\n    verdicts.set(host, blocked)\n  }\n\n  await context.route('**/*', async (route) => {\n    const request = route.request()\n    const isNavigation = request.isNavigationRequest()\n    if (!isNavigation && !filterSubresources) return route.continue()\n\n    const url = request.url()\n    let host: string\n    try {\n      host = new URL(url).host\n    } catch {\n      return isNavigation ? route.abort('blockedbyclient') : route.continue()\n    }\n\n    const cached = isNavigation ? undefined : verdicts.get(host)\n    if (cached === true) return route.abort('blockedbyclient')\n    if (cached === false) return route.continue()\n\n    try {\n      await assertPublicUrl(url, isNavigation ? 'browser navigation' : 'browser subresource', {\n        failClosed: true,\n      })\n      remember(host, false)\n    } catch {\n      remember(host, true)\n      return route.abort('blockedbyclient')\n    }\n    return route.continue()\n  })\n}\n\n/**\n * Launch flags aimed at not announcing automation. Playwright's defaults set\n * `navigator.webdriver` and a headless UA, which the SERP endpoints this adapter\n * exists to reach specifically look for.\n *\n * `--disable-dev-shm-usage` is a sizing workaround, not a security control: it\n * makes Chromium write shared memory to /tmp instead of a container's small\n * /dev/shm. The sandbox is deliberately NOT disabled here \u2014 see\n * {@link resolveLaunchArgs}.\n */\nexport const LAUNCH_ARGS = [\n  '--disable-blink-features=AutomationControlled',\n  '--disable-dev-shm-usage',\n]\n\nexport const SANDBOX_OPT_OUT_ENV = 'OM_WEB_RESEARCH_BROWSER_NO_SANDBOX'\n\n/**\n * Launch flags for this process, sandbox included unless an operator opted out.\n *\n * This adapter exists to render pages chosen by a search engine or a model, so\n * the renderer is by definition parsing hostile input. `--no-sandbox` turns a\n * renderer compromise into code running as whatever user the app runs as, which\n * is the one mitigation Chromium provides for exactly this threat.\n *\n * It used to be on unconditionally because the sandbox needs privileges a\n * root-in-Docker container does not grant by default. That is a container\n * problem with container fixes (run as a non-root user, or grant `SYS_ADMIN`, or\n * enable user namespaces); silently shipping every deployment the insecure\n * variant to spare those is the wrong trade. The opt-out stays available for\n * environments that genuinely cannot, and it is loud.\n */\nexport function resolveLaunchArgs(env: NodeJS.ProcessEnv = process.env): string[] {\n  return env[SANDBOX_OPT_OUT_ENV] === '1' ? [...LAUNCH_ARGS, '--no-sandbox'] : [...LAUNCH_ARGS]\n}\n\nexport function isSandboxDisabled(env: NodeJS.ProcessEnv = process.env): boolean {\n  return env[SANDBOX_OPT_OUT_ENV] === '1'\n}\n\n/**\n * Chromium's refusal when it cannot set up its sandbox. The wording differs\n * between the root check and the namespace failure, so both shapes are matched.\n */\nexport function isSandboxFailure(error: unknown): boolean {\n  if (!(error instanceof Error)) return false\n  return (\n    /running as root without --no-sandbox/i.test(error.message) ||\n    /No usable sandbox/i.test(error.message) ||\n    /clone helper|namespace sandbox|SUID sandbox/i.test(error.message)\n  )\n}\n\nexport const DEFAULT_USER_AGENT =\n  'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36'\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/protocol.js

@@ -0,0 +1,28 @@
+class SidecarError extends Error {
+  constructor(message, kind = "runtime") {
+    super(message);
+    this.name = "SidecarError";
+    this.kind = kind;
+  }
+}
+function encodeLine(value) {
+  return `${JSON.stringify(value)}
+`;
+}
+function decodeLine(line) {
+  try {
+    return JSON.parse(line);
+  } catch {
+    return null;
+  }
+}
+function isReply(value) {
+  return typeof value === "object" && value !== null && typeof value.id === "string" && typeof value.ok === "boolean";
+}
+export {
+  SidecarError,
+  decodeLine,
+  encodeLine,
+  isReply
+};
+//# sourceMappingURL=protocol.js.map

package/dist/protocol.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/protocol.ts"],
+  "sourcesContent": ["export type SidecarErrorKind = 'init' | 'needs-install' | 'navigation' | 'runtime' | 'timeout' | 'unknown'\n\nexport type SidecarRequest = {\n  readonly id: string\n  readonly method: string\n  readonly params?: Record<string, unknown>\n}\n\nexport type SidecarReply =\n  | { readonly id: string; readonly ok: true; readonly result?: unknown }\n  | {\n      readonly id: string\n      readonly ok: false\n      readonly error: { readonly message: string; readonly kind: SidecarErrorKind }\n    }\n\nexport class SidecarError extends Error {\n  readonly kind: SidecarErrorKind\n\n  constructor(message: string, kind: SidecarErrorKind = 'runtime') {\n    super(message)\n    this.name = 'SidecarError'\n    this.kind = kind\n  }\n}\n\n/**\n * Line-delimited JSON, one object per line, correlated by `id`. Deliberately not\n * JSON-RPC 2.0: the surface is four methods over a pipe we own both ends of, and\n * an `ok` discriminant is easier to narrow than presence-of-`error`.\n */\nexport function encodeLine(value: SidecarRequest | SidecarReply): string {\n  return `${JSON.stringify(value)}\\n`\n}\n\nexport function decodeLine(line: string): unknown {\n  try {\n    return JSON.parse(line)\n  } catch {\n    return null\n  }\n}\n\nexport function isReply(value: unknown): value is SidecarReply {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    typeof (value as { id?: unknown }).id === 'string' &&\n    typeof (value as { ok?: unknown }).ok === 'boolean'\n  )\n}\n"],
+  "mappings": "AAgBO,MAAM,qBAAqB,MAAM;AAAA,EAGtC,YAAY,SAAiB,OAAyB,WAAW;AAC/D,UAAM,OAAO;AACb,SAAK,OAAO;AACZ,SAAK,OAAO;AAAA,EACd;AACF;AAOO,SAAS,WAAW,OAA8C;AACvE,SAAO,GAAG,KAAK,UAAU,KAAK,CAAC;AAAA;AACjC;AAEO,SAAS,WAAW,MAAuB;AAChD,MAAI;AACF,WAAO,KAAK,MAAM,IAAI;AAAA,EACxB,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAEO,SAAS,QAAQ,OAAuC;AAC7D,SACE,OAAO,UAAU,YACjB,UAAU,QACV,OAAQ,MAA2B,OAAO,YAC1C,OAAQ,MAA2B,OAAO;AAE9C;",
+  "names": []
+}

package/dist/sidecar.js

@@ -0,0 +1,79 @@
+import { createState, dispatch, teardown } from "./dispatch.js";
+import { decodeLine, encodeLine } from "./protocol.js";
+const state = createState();
+function write(reply) {
+  try {
+    process.stdout.write(encodeLine(reply));
+  } catch {
+  }
+}
+const chains = /* @__PURE__ */ new Map();
+function chainKey(request) {
+  const leaseId = request.params?.leaseId;
+  return typeof leaseId === "string" ? leaseId : "__global__";
+}
+function enqueue(line) {
+  const parsed = decodeLine(line);
+  if (typeof parsed !== "object" || parsed === null) return;
+  const request = parsed;
+  if (typeof request.id !== "string" || typeof request.method !== "string") return;
+  const key = chainKey(request);
+  const previous = chains.get(key) ?? Promise.resolve();
+  const next = previous.then(async () => {
+    write(await dispatch(state, request));
+  }).catch((error) => {
+    write({
+      id: request.id,
+      ok: false,
+      error: { message: error instanceof Error ? error.message : String(error), kind: "unknown" }
+    });
+  }).finally(() => {
+    if (chains.get(key) === next) chains.delete(key);
+  });
+  chains.set(key, next);
+}
+async function shutdownAndExit(code) {
+  try {
+    await teardown(state);
+  } catch {
+  }
+  process.exit(code);
+}
+function startParentWatchdog() {
+  const parentPid = process.ppid;
+  if (!parentPid || parentPid <= 1) return;
+  const interval = setInterval(() => {
+    try {
+      process.kill(parentPid, 0);
+    } catch (error) {
+      if (error.code === "ESRCH") {
+        clearInterval(interval);
+        void shutdownAndExit(0);
+      }
+    }
+  }, 2e3);
+  interval.unref?.();
+}
+function main() {
+  let buffer = "";
+  process.stdin.setEncoding("utf8");
+  process.stdin.on("data", (chunk) => {
+    buffer += chunk;
+    let newline = buffer.indexOf("\n");
+    while (newline !== -1) {
+      const line = buffer.slice(0, newline);
+      buffer = buffer.slice(newline + 1);
+      if (line.trim()) enqueue(line);
+      newline = buffer.indexOf("\n");
+    }
+  });
+  process.stdin.on("end", () => void shutdownAndExit(0));
+  process.stdout.on("error", () => void shutdownAndExit(0));
+  startParentWatchdog();
+}
+if (process.env.OM_WEB_RESEARCH_SIDECAR_TEST !== "1") main();
+export {
+  enqueue,
+  main
+};
+//# sourceMappingURL=sidecar.js.map

package/dist/sidecar.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/sidecar.ts"],
+  "sourcesContent": ["/**\n * Playwright sidecar entry point.\n *\n * Runs as a child process so Playwright never enters the app or MCP bundle and a\n * crashed browser cannot take the server down. Speaks line-delimited JSON on\n * stdio; every request is serialized per lease so a `goto` cannot race a\n * `release` on the same context.\n */\n\nimport { createState, dispatch, teardown, type SidecarState } from './dispatch'\nimport { decodeLine, encodeLine, type SidecarReply, type SidecarRequest } from './protocol'\n\nconst state: SidecarState = createState()\n\nfunction write(reply: SidecarReply): void {\n  try {\n    process.stdout.write(encodeLine(reply))\n  } catch {\n    // stdout is gone; the parent will time the call out and reap us.\n  }\n}\n\n/** Per-lease chains: work on different contexts proceeds concurrently. */\nconst chains = new Map<string, Promise<void>>()\n\nfunction chainKey(request: SidecarRequest): string {\n  const leaseId = request.params?.leaseId\n  return typeof leaseId === 'string' ? leaseId : '__global__'\n}\n\nexport function enqueue(line: string): void {\n  const parsed = decodeLine(line)\n  if (typeof parsed !== 'object' || parsed === null) return\n  const request = parsed as SidecarRequest\n  if (typeof request.id !== 'string' || typeof request.method !== 'string') return\n\n  const key = chainKey(request)\n  const previous = chains.get(key) ?? Promise.resolve()\n  const next: Promise<void> = previous\n    .then(async () => {\n      write(await dispatch(state, request))\n    })\n    .catch((error: unknown) => {\n      write({\n        id: request.id,\n        ok: false,\n        error: { message: error instanceof Error ? error.message : String(error), kind: 'unknown' },\n      })\n    })\n    .finally(() => {\n      // Every render takes a fresh lease id, so without this the map grows one\n      // settled promise per request for the life of the process. Only the tail is\n      // dropped; a later request on the same lease owns the entry by then.\n      if (chains.get(key) === next) chains.delete(key)\n    })\n  chains.set(key, next)\n}\n\nasync function shutdownAndExit(code: number): Promise<void> {\n  try {\n    await teardown(state)\n  } catch {\n    // Exiting regardless.\n  }\n  process.exit(code)\n}\n\n/**\n * A SIGKILL'd parent produces no stdin EOF, so without this poll a Chromium can\n * outlive the server that spawned it and leak memory until the box is restarted.\n */\nfunction startParentWatchdog(): void {\n  const parentPid = process.ppid\n  if (!parentPid || parentPid <= 1) return\n  const interval = setInterval(() => {\n    try {\n      process.kill(parentPid, 0)\n    } catch (error) {\n      if ((error as NodeJS.ErrnoException).code === 'ESRCH') {\n        clearInterval(interval)\n        void shutdownAndExit(0)\n      }\n      // EPERM means it exists but we may not signal it \u2014 still alive.\n    }\n  }, 2000)\n  interval.unref?.()\n}\n\nexport function main(): void {\n  let buffer = ''\n  process.stdin.setEncoding('utf8')\n  process.stdin.on('data', (chunk: string) => {\n    buffer += chunk\n    let newline = buffer.indexOf('\\n')\n    while (newline !== -1) {\n      const line = buffer.slice(0, newline)\n      buffer = buffer.slice(newline + 1)\n      if (line.trim()) enqueue(line)\n      newline = buffer.indexOf('\\n')\n    }\n  })\n  process.stdin.on('end', () => void shutdownAndExit(0))\n  process.stdout.on('error', () => void shutdownAndExit(0))\n  startParentWatchdog()\n}\n\n// Guarded so tests can import the module without starting the stdio loop.\nif (process.env.OM_WEB_RESEARCH_SIDECAR_TEST !== '1') main()\n"],
+  "mappings": "AASA,SAAS,aAAa,UAAU,gBAAmC;AACnE,SAAS,YAAY,kBAA0D;AAE/E,MAAM,QAAsB,YAAY;AAExC,SAAS,MAAM,OAA2B;AACxC,MAAI;AACF,YAAQ,OAAO,MAAM,WAAW,KAAK,CAAC;AAAA,EACxC,QAAQ;AAAA,EAER;AACF;AAGA,MAAM,SAAS,oBAAI,IAA2B;AAE9C,SAAS,SAAS,SAAiC;AACjD,QAAM,UAAU,QAAQ,QAAQ;AAChC,SAAO,OAAO,YAAY,WAAW,UAAU;AACjD;AAEO,SAAS,QAAQ,MAAoB;AAC1C,QAAM,SAAS,WAAW,IAAI;AAC9B,MAAI,OAAO,WAAW,YAAY,WAAW,KAAM;AACnD,QAAM,UAAU;AAChB,MAAI,OAAO,QAAQ,OAAO,YAAY,OAAO,QAAQ,WAAW,SAAU;AAE1E,QAAM,MAAM,SAAS,OAAO;AAC5B,QAAM,WAAW,OAAO,IAAI,GAAG,KAAK,QAAQ,QAAQ;AACpD,QAAM,OAAsB,SACzB,KAAK,YAAY;AAChB,UAAM,MAAM,SAAS,OAAO,OAAO,CAAC;AAAA,EACtC,CAAC,EACA,MAAM,CAAC,UAAmB;AACzB,UAAM;AAAA,MACJ,IAAI,QAAQ;AAAA,MACZ,IAAI;AAAA,MACJ,OAAO,EAAE,SAAS,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK,GAAG,MAAM,UAAU;AAAA,IAC5F,CAAC;AAAA,EACH,CAAC,EACA,QAAQ,MAAM;AAIb,QAAI,OAAO,IAAI,GAAG,MAAM,KAAM,QAAO,OAAO,GAAG;AAAA,EACjD,CAAC;AACH,SAAO,IAAI,KAAK,IAAI;AACtB;AAEA,eAAe,gBAAgB,MAA6B;AAC1D,MAAI;AACF,UAAM,SAAS,KAAK;AAAA,EACtB,QAAQ;AAAA,EAER;AACA,UAAQ,KAAK,IAAI;AACnB;AAMA,SAAS,sBAA4B;AACnC,QAAM,YAAY,QAAQ;AAC1B,MAAI,CAAC,aAAa,aAAa,EAAG;AAClC,QAAM,WAAW,YAAY,MAAM;AACjC,QAAI;AACF,cAAQ,KAAK,WAAW,CAAC;AAAA,IAC3B,SAAS,OAAO;AACd,UAAK,MAAgC,SAAS,SAAS;AACrD,sBAAc,QAAQ;AACtB,aAAK,gBAAgB,CAAC;AAAA,MACxB;AAAA,IAEF;AAAA,EACF,GAAG,GAAI;AACP,WAAS,QAAQ;AACnB;AAEO,SAAS,OAAa;AAC3B,MAAI,SAAS;AACb,UAAQ,MAAM,YAAY,MAAM;AAChC,UAAQ,MAAM,GAAG,QAAQ,CAAC,UAAkB;AAC1C,cAAU;AACV,QAAI,UAAU,OAAO,QAAQ,IAAI;AACjC,WAAO,YAAY,IAAI;AACrB,YAAM,OAAO,OAAO,MAAM,GAAG,OAAO;AACpC,eAAS,OAAO,MAAM,UAAU,CAAC;AACjC,UAAI,KAAK,KAAK,EAAG,SAAQ,IAAI;AAC7B,gBAAU,OAAO,QAAQ,IAAI;AAAA,IAC/B;AAAA,EACF,CAAC;AACD,UAAQ,MAAM,GAAG,OAAO,MAAM,KAAK,gBAAgB,CAAC,CAAC;AACrD,UAAQ,OAAO,GAAG,SAAS,MAAM,KAAK,gBAAgB,CAAC,CAAC;AACxD,sBAAoB;AACtB;AAGA,IAAI,QAAQ,IAAI,iCAAiC,IAAK,MAAK;",
+  "names": []
+}

package/jest.config.cjs

@@ -0,0 +1,31 @@
+/** @type {import('jest').Config} */
+const base = require('../../jest.config.base.cjs')
+
+module.exports = {
+  ...base,
+  testEnvironment: 'node',
+  watchman: false,
+  rootDir: '.',
+  moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json'],
+  moduleNameMapper: {
+    '^@open-mercato/web-research/(.*)$': '<rootDir>/../web-research/src/$1',
+    '^@open-mercato/web-research$': '<rootDir>/../web-research/src/index.ts',
+    '^@open-mercato/web-research-serp$': '<rootDir>/../web-research-serp/src/index.ts',
+  },
+  // Shared transformer rather than plain ts-jest: `client.ts` reads
+  // `import.meta.url` to locate the sidecar script, which a CJS test transform
+  // cannot parse. This is the same transformer the CLI and enterprise use.
+  transform: {
+    '^.+\\.(t|j)sx?$': [
+      '<rootDir>/../../scripts/jest-mikroorm-transformer.cjs',
+      {
+        tsconfig: {
+          rootDir: '.',
+          ignoreDeprecations: '6.0',
+        },
+      },
+    ],
+  },
+  testMatch: ['<rootDir>/src/**/__tests__/**/*.test.(ts|tsx)'],
+  passWithNoTests: true,
+}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@open-mercato/web-research-browser",
+  "version": "0.7.1-develop.7194.1.ab4fc81f82",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "bin": {
+    "om-web-research-sidecar": "./dist/sidecar.js"
+  },
+  "openMercato": {
+    "webResearchAdapter": {
+      "id": "browser"
+    }
+  },
+  "scripts": {
+    "build": "node build.mjs",
+    "watch": "node watch.mjs",
+    "test": "jest --config jest.config.cjs",
+    "typecheck": "tsc --noEmit"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./dist/index.js"
+    },
+    "./*.ts": {
+      "types": "./src/*.ts",
+      "default": "./dist/*.js"
+    },
+    "./*": {
+      "types": [
+        "./src/*.ts"
+      ],
+      "default": "./dist/*.js"
+    }
+  },
+  "peerDependencies": {
+    "@open-mercato/web-research": "^0.6.0"
+  },
+  "dependencies": {
+    "@open-mercato/web-research-serp": "0.7.1-develop.7194.1.ab4fc81f82",
+    "playwright": "^1.40.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@open-mercato/web-research": "0.7.1-develop.7194.1.ab4fc81f82",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^26.0.1",
+    "esbuild": "^0.28.1",
+    "glob": "^13.0.6",
+    "jest": "^30.4.2",
+    "ts-jest": "^29.4.11",
+    "typescript": "^6.0.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/open-mercato/open-mercato",
+    "directory": "packages/web-research-browser"
+  },
+  "stableVersion": "0.7.0"
+}

package/src/__tests__/browser.test.ts

@@ -0,0 +1,242 @@
+import { PassThrough } from 'node:stream'
+import { createTestContext, describeAdapterContract } from '@open-mercato/web-research/testing'
+import { browserAdapterModule, createBrowserAdapter } from '../adapter'
+import { Sidecar, type SidecarStream, type SpawnFn } from '../client'
+import { decodeLine, encodeLine, type SidecarRequest } from '../protocol'
+
+const SERP_HTML = `
+<div class="result">
+  <a class="result__a" href="https://example.com/one">Rendered result</a>
+  <div class="result__snippet">Rendered snippet.</div>
+</div>`
+
+type FakeChild = SidecarStream & {
+  written: string[]
+  emitExit(code: number | null): void
+  emitStdinError(error: NodeJS.ErrnoException): void
+  killed: NodeJS.Signals[]
+}
+
+/**
+ * Scripted child process. Playwright is never imported by these tests — the
+ * point is the parent-side protocol, not the browser.
+ */
+function makeFakeSpawn(
+  respond: (request: SidecarRequest) => Record<string, unknown> | 'silent' | Error,
+): { spawnFn: SpawnFn; children: FakeChild[] } {
+  const children: FakeChild[] = []
+  const spawnFn: SpawnFn = () => {
+    const stdout = new PassThrough({ encoding: 'utf8' })
+    const stderr = new PassThrough({ encoding: 'utf8' })
+    const exitHandlers: Array<(code: number | null) => void> = []
+    const stdinErrorHandlers: Array<(error: NodeJS.ErrnoException) => void> = []
+    const child: FakeChild = {
+      written: [],
+      killed: [],
+      stdin: {
+        on(event: 'error', handler: (error: NodeJS.ErrnoException) => void) {
+          stdinErrorHandlers.push(handler)
+          return child.stdin
+        },
+        write(chunk: string) {
+          child.written.push(chunk)
+          const request = decodeLine(chunk.trim()) as SidecarRequest
+          const reply = respond(request)
+          if (reply === 'silent') return true
+          if (reply instanceof Error) {
+            stdout.write(
+              encodeLine({ id: request.id, ok: false, error: { message: reply.message, kind: 'runtime' } }),
+            )
+            return true
+          }
+          stdout.write(encodeLine({ id: request.id, ok: true, result: reply }))
+          return true
+        },
+      },
+      stdout,
+      stderr,
+      once(_event, handler) {
+        exitHandlers.push(handler)
+        return child
+      },
+      kill(signal) {
+        child.killed.push((signal ?? 'SIGTERM') as NodeJS.Signals)
+        return true
+      },
+      emitExit(code) {
+        for (const handler of exitHandlers.splice(0)) handler(code)
+      },
+      emitStdinError(error) {
+        for (const handler of stdinErrorHandlers) handler(error)
+      },
+    }
+    children.push(child)
+    return child
+  }
+  return { spawnFn, children }
+}
+
+const sidecarWith = (spawnFn: SpawnFn, overrides: Partial<Record<string, number>> = {}) =>
+  new Sidecar('/fake/sidecar.js', spawnFn, overrides.callTimeoutMs ?? 500, overrides.closeTimeoutMs ?? 50, 4)
+
+describe('sidecar client protocol', () => {
+  it('correlates a reply to its request', async () => {
+    const { spawnFn } = makeFakeSpawn(() => ({ pong: true }))
+    await expect(sidecarWith(spawnFn).call('ping')).resolves.toEqual({ pong: true })
+  })
+
+  it('surfaces a sidecar error as a typed rejection', async () => {
+    const { spawnFn } = makeFakeSpawn(() => new Error('navigation blocked'))
+    await expect(sidecarWith(spawnFn).call('render', { url: 'https://x' })).rejects.toThrow('navigation blocked')
+  })
+
+  // A child that has died leaves its stdin pipe broken, and Node reports that
+  // asynchronously on the stream rather than throwing from write(). Unhandled,
+  // it escapes the adapter and the call throws where the contract promises an
+  // outcome — which is exactly how this surfaced on a runner with no browser.
+  it('turns a broken sidecar pipe into a typed rejection, not an unhandled error', async () => {
+    const { spawnFn, children } = makeFakeSpawn(() => 'silent')
+    const sidecar = sidecarWith(spawnFn)
+    const call = sidecar.call('render', { url: 'https://x' })
+    const epipe: NodeJS.ErrnoException = Object.assign(new Error('write EPIPE'), { code: 'EPIPE' })
+    children[0].emitStdinError(epipe)
+    children[0].emitExit(1)
+    await expect(call).rejects.toThrow(/exited unexpectedly/)
+  })
+
+  it('times a silent call out instead of hanging forever', async () => {
+    const { spawnFn } = makeFakeSpawn(() => 'silent')
+    await expect(sidecarWith(spawnFn).call('render')).rejects.toThrow(/timed out/)
+  })
+
+  it('rejects one aborted call without disturbing the others', async () => {
+    const { spawnFn } = makeFakeSpawn((request) => (request.method === 'slow' ? 'silent' : { ok: true }))
+    const sidecar = sidecarWith(spawnFn)
+    const controller = new AbortController()
+
+    const aborted = sidecar.call('slow', {}, controller.signal)
+    controller.abort()
+
+    await expect(aborted).rejects.toThrow(/aborted/)
+    await expect(sidecar.call('ping')).resolves.toEqual({ ok: true })
+  })
+
+  it('degrades to a clean busy error rather than piling up unbounded work', async () => {
+    const { spawnFn } = makeFakeSpawn(() => 'silent')
+    const sidecar = sidecarWith(spawnFn)
+    const inflight = [0, 1, 2, 3].map(() => sidecar.call('slow').catch(() => 'settled'))
+
+    await expect(sidecar.call('one-too-many')).rejects.toThrow(/busy/)
+    await Promise.all(inflight)
+  })
+
+  it('rejects every pending call when the child dies, with the stderr tail', async () => {
+    const { spawnFn, children } = makeFakeSpawn(() => 'silent')
+    const sidecar = sidecarWith(spawnFn)
+    const pending = sidecar.call('render')
+    children[0].stderr.write('playwright: Executable does not exist\n')
+    await new Promise((resolve) => setImmediate(resolve))
+    children[0].emitExit(1)
+
+    await expect(pending).rejects.toThrow(/exited unexpectedly/)
+  })
+
+  // Regression: a child that dies mid-line leaves a JSON fragment behind. If the
+  // buffer is not cleared on respawn it prefixes the next spawn's first reply,
+  // which then fails to parse and hangs that call for the full timeout.
+  it('clears a partial line so the next spawn is not poisoned', async () => {
+    const { spawnFn, children } = makeFakeSpawn(() => ({ ok: true }))
+    const sidecar = sidecarWith(spawnFn)
+    await sidecar.call('ping')
+
+    children[0].stdout.write('{"id":"truncated","ok":tr')
+    await new Promise((resolve) => setImmediate(resolve))
+    children[0].emitExit(1)
+
+    await expect(sidecar.call('ping')).resolves.toEqual({ ok: true })
+    expect(children).toHaveLength(2)
+  })
+
+  it('escalates to SIGKILL when the child ignores a close', async () => {
+    const { spawnFn, children } = makeFakeSpawn(() => 'silent')
+    const sidecar = sidecarWith(spawnFn)
+    await sidecar.call('ping').catch(() => undefined)
+
+    await sidecar.close()
+
+    expect(children[0].killed).toContain('SIGTERM')
+    expect(children[0].killed).toContain('SIGKILL')
+  })
+})
+
+describe('browser adapter', () => {
+  const options = (extra: Record<string, unknown> = {}) => ({
+    sidecar: { sidecarPath: '/fake/sidecar.js', callTimeoutMs: 500, closeTimeoutMs: 50, ...extra },
+  })
+
+  // Participation is the policy row's job; the scheduler never puts a browser
+  // adapter in a normal wave, so it is reachable only via escalation.
+  it('is ready without per-adapter opt-in, since the policy row governs it', () => {
+    expect(createBrowserAdapter({}).readiness().ready).toBe(true)
+  })
+
+  it('parses a browser-rendered SERP with the shared engine profiles', async () => {
+    const { spawnFn } = makeFakeSpawn((request) =>
+      request.method === 'render' ? { url: 'https://html.duckduckgo.com/html/', html: SERP_HTML } : {},
+    )
+    const adapter = createBrowserAdapter(options({ spawnFn }))
+
+    const outcome = await adapter.search({ query: 'x', limit: 5 }, createTestContext())
+
+    expect(outcome.status).toBe('ok')
+    if (outcome.status !== 'ok') return
+    expect(outcome.results[0]).toMatchObject({
+      url: 'https://example.com/one',
+      title: 'Rendered result',
+      snippet: 'Rendered snippet.',
+    })
+  })
+
+  it('releases the lease even when the render fails', async () => {
+    const { spawnFn, children } = makeFakeSpawn((request) =>
+      request.method === 'render' ? new Error('nav failed') : {},
+    )
+    const adapter = createBrowserAdapter(options({ spawnFn }))
+
+    await adapter.search({ query: 'x', limit: 5 }, createTestContext())
+
+    const methods = children[0].written.map((line) => (decodeLine(line.trim()) as SidecarRequest).method)
+    expect(methods).toContain('release')
+  })
+
+  it('reports blocked when even a rendered page yields nothing', async () => {
+    const { spawnFn } = makeFakeSpawn(() => ({ url: 'https://x', html: '<html><body>nope</body></html>' }))
+    const adapter = createBrowserAdapter(options({ spawnFn }))
+
+    const outcome = await adapter.search({ query: 'x', limit: 5 }, createTestContext())
+
+    expect(outcome.status).toBe('blocked')
+  })
+
+  it('renders a page into readable text for fetch', async () => {
+    const html = `<html><head><title>Doc</title></head><body><article><p>${'word '.repeat(80)}</p></article></body></html>`
+    const { spawnFn } = makeFakeSpawn((request) =>
+      request.method === 'render' ? { url: 'https://example.com/a', html } : {},
+    )
+    const adapter = createBrowserAdapter(options({ spawnFn }))
+
+    const outcome = await adapter.fetch?.({ url: 'https://example.com/a' }, createTestContext())
+
+    expect(outcome).toMatchObject({ status: 'ok', page: { title: 'Doc', renderedWith: 'browser' } })
+  })
+})
+
+describeAdapterContract(
+  browserAdapterModule,
+  {
+    configuredOptions: {
+      sidecar: { sidecarPath: '/fake/sidecar.js', callTimeoutMs: 200, closeTimeoutMs: 50 },
+    },
+  },
+  { describe, it, expect: expect as never },
+)