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

package/.turbo/turbo-build.log

@@ -0,0 +1,2 @@
+[build:web-research-browser] found 7 entry points
+[build:web-research-browser] built successfully

package/build.mjs

@@ -0,0 +1,10 @@
+import { dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { buildPackage } from '../../scripts/build-package.mjs'
+
+const packageDir = dirname(fileURLToPath(import.meta.url))
+
+await buildPackage(packageDir, {
+  name: 'web-research-browser',
+  entryPoints: 'src/**/*.ts',
+})

package/dist/adapter.js

@@ -0,0 +1,162 @@
+import { randomUUID } from "node:crypto";
+import {
+  CONTRACT_VERSION,
+  READY,
+  blocked,
+  classifyPage,
+  defineAdapterModule,
+  extractMainContent,
+  extractTitle,
+  htmlToText,
+  notReady,
+  searchOk
+} from "@open-mercato/web-research";
+import { SERP_PROFILES, extractSerpResults } from "@open-mercato/web-research-serp";
+import { z } from "zod";
+import { createSidecar } from "./client.js";
+import { SidecarError } from "./protocol.js";
+const browserOptionsSchema = z.object({
+  engines: z.array(z.enum(["ddg-html", "ddg-lite"])).min(1).optional(),
+  userAgent: z.string().min(1).optional(),
+  timeoutMs: z.number().int().min(1e3).max(12e4).optional(),
+  sidecar: z.custom((value) => typeof value === "object" && value !== null).optional()
+});
+const DEFAULT_ENGINES = ["ddg-html"];
+const DEFAULT_TIMEOUT_MS = 3e4;
+function isRenderResult(value) {
+  return typeof value === "object" && value !== null && typeof value.html === "string" && typeof value.url === "string";
+}
+function createBrowserAdapter(options) {
+  const engines = options.engines ?? DEFAULT_ENGINES;
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  let sidecar = null;
+  let startupFailure = null;
+  const client = () => {
+    sidecar ??= createSidecar(options.sidecar ?? {});
+    return sidecar;
+  };
+  const render = async (url, deadlineAt, signal) => {
+    const leaseId = randomUUID();
+    const budget = Math.max(1e3, Math.min(timeoutMs, deadlineAt - Date.now()));
+    const active = client();
+    try {
+      const result = await active.call(
+        "render",
+        { url, leaseId, timeoutMs: budget, ...options.userAgent ? { userAgent: options.userAgent } : {} },
+        signal
+      );
+      if (!isRenderResult(result)) throw new Error("sidecar returned a malformed render result");
+      startupFailure = null;
+      return result;
+    } catch (error) {
+      if (error instanceof SidecarError && (error.kind === "init" || error.kind === "needs-install")) {
+        startupFailure = error.message;
+      }
+      throw error;
+    } finally {
+      await active.call("release", { leaseId }).catch(() => void 0);
+    }
+  };
+  return {
+    id: "browser",
+    kind: "browser",
+    capabilities: {
+      search: true,
+      fetch: true,
+      snippets: true,
+      content: true,
+      freshness: true,
+      siteFilter: true,
+      // Roughly two orders of magnitude more expensive than an HTTP read, which
+      // is why the engine only reaches for this after a source reports blocked.
+      cost: "metered"
+    },
+    // Participation is governed solely by the policy row. The scheduler already
+    // keeps `kind: 'browser'` out of normal waves, so an enabled browser adapter
+    // is reached only for escalation — a second per-adapter switch just made the
+    // UI show two toggles meaning different things.
+    /** `heavy` — spawns and pings the sidecar process. */
+    probeCost: "heavy",
+    readiness: () => startupFailure === null ? READY : notReady(startupFailure),
+    async search(request, context) {
+      let lastReason = "no engine produced results";
+      for (const engine of engines) {
+        if (context.signal.aborted) break;
+        const profile = SERP_PROFILES[engine];
+        context.report("started", `rendering ${profile.label} in a browser`);
+        try {
+          const rendered = await render(profile.buildUrl(request), context.deadlineAt, context.signal);
+          const results = extractSerpResults(rendered.html, profile.selector, profile.baseUrl, request.limit);
+          if (results.length > 0) {
+            context.report("ok", `${profile.label} returned ${results.length} result(s)`, {
+              resultCount: results.length
+            });
+            return searchOk(results);
+          }
+          const verdict = classifyPage({
+            status: 200,
+            contentType: "text/html",
+            html: rendered.html,
+            text: ""
+          });
+          lastReason = verdict.verdict === "blocked" ? `${profile.label} served a challenge page even in a browser (${verdict.reason ?? "unknown"})` : `${profile.label} rendered but produced no parseable results`;
+        } catch (error) {
+          lastReason = error instanceof Error ? error.message : String(error);
+        }
+        context.report("blocked", lastReason);
+      }
+      return blocked(lastReason);
+    },
+    async fetch(request, context) {
+      try {
+        const rendered = await render(request.url, context.deadlineAt, context.signal);
+        const text = extractMainContent(rendered.html) || htmlToText(rendered.html);
+        return {
+          status: "ok",
+          page: {
+            url: rendered.url,
+            title: extractTitle(rendered.html),
+            text,
+            contentType: "text/html",
+            status: 200,
+            truncated: false,
+            renderedWith: "browser"
+          }
+        };
+      } catch (error) {
+        return {
+          status: "error",
+          reason: error instanceof Error ? error.message : String(error),
+          retriable: false
+        };
+      }
+    },
+    async healthCheck() {
+      try {
+        await client().call("ping", {});
+        startupFailure = null;
+        return { ok: true };
+      } catch (error) {
+        return { ok: false, detail: error instanceof Error ? error.message : String(error) };
+      }
+    },
+    async dispose() {
+      const active = sidecar;
+      sidecar = null;
+      if (active) await active.close();
+    }
+  };
+}
+const browserAdapterModule = defineAdapterModule({
+  id: "browser",
+  kind: "browser",
+  contractVersion: CONTRACT_VERSION,
+  optionsSchema: browserOptionsSchema,
+  createAdapter: createBrowserAdapter
+});
+export {
+  browserAdapterModule,
+  browserOptionsSchema,
+  createBrowserAdapter
+};
+//# sourceMappingURL=adapter.js.map

package/dist/adapter.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/adapter.ts"],
+  "sourcesContent": ["import { randomUUID } from 'node:crypto'\nimport {\n  CONTRACT_VERSION,\n  READY,\n  blocked,\n  classifyPage,\n  defineAdapterModule,\n  extractMainContent,\n  extractTitle,\n  htmlToText,\n  notReady,\n  searchOk,\n  type FetchOutcome,\n  type SearchAdapter,\n  type SearchOutcome,\n} from '@open-mercato/web-research'\nimport { SERP_PROFILES, extractSerpResults, type SerpEngineId } from '@open-mercato/web-research-serp'\nimport { z } from 'zod'\nimport { createSidecar, type Sidecar, type SidecarOptions } from './client'\nimport { SidecarError } from './protocol'\n\nexport const browserOptionsSchema = z.object({\n  engines: z.array(z.enum(['ddg-html', 'ddg-lite'])).min(1).optional(),\n  userAgent: z.string().min(1).optional(),\n  timeoutMs: z.number().int().min(1000).max(120_000).optional(),\n  sidecar: z.custom<SidecarOptions>((value) => typeof value === 'object' && value !== null).optional(),\n})\n\nexport type BrowserOptions = z.infer<typeof browserOptionsSchema>\n\nconst DEFAULT_ENGINES: readonly SerpEngineId[] = ['ddg-html']\nconst DEFAULT_TIMEOUT_MS = 30_000\n\ntype RenderResult = { url: string; html: string }\n\nfunction isRenderResult(value: unknown): value is RenderResult {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    typeof (value as { html?: unknown }).html === 'string' &&\n    typeof (value as { url?: unknown }).url === 'string'\n  )\n}\n\nexport function createBrowserAdapter(options: BrowserOptions): SearchAdapter {\n  const engines = options.engines ?? DEFAULT_ENGINES\n  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS\n  let sidecar: Sidecar | null = null\n  // Remembered so `readiness()` stops promising a tier that cannot start. It is\n  // sync and I/O-free by contract, so it cannot probe \u2014 but it can report what\n  // the last attempt already proved, instead of letting the scheduler pay the\n  // escalation cost again to rediscover it.\n  let startupFailure: string | null = null\n\n  const client = (): Sidecar => {\n    sidecar ??= createSidecar(options.sidecar ?? {})\n    return sidecar\n  }\n\n  /**\n   * Every render takes its own lease, so concurrent work never shares a cookie jar.\n   *\n   * The budget is the smaller of the configured timeout and whatever the engine\n   * has left: a render that outlives `deadlineAt` keeps a browser context open on\n   * a page nobody is waiting for any more.\n   */\n  const render = async (url: string, deadlineAt: number, signal: AbortSignal): Promise<RenderResult> => {\n    const leaseId = randomUUID()\n    const budget = Math.max(1_000, Math.min(timeoutMs, deadlineAt - Date.now()))\n    const active = client()\n    try {\n      const result = await active.call(\n        'render',\n        { url, leaseId, timeoutMs: budget, ...(options.userAgent ? { userAgent: options.userAgent } : {}) },\n        signal,\n      )\n      if (!isRenderResult(result)) throw new Error('sidecar returned a malformed render result')\n      startupFailure = null\n      return result\n    } catch (error) {\n      if (error instanceof SidecarError && (error.kind === 'init' || error.kind === 'needs-install')) {\n        startupFailure = error.message\n      }\n      throw error\n    } finally {\n      await active.call('release', { leaseId }).catch(() => undefined)\n    }\n  }\n\n  return {\n    id: 'browser',\n    kind: 'browser',\n    capabilities: {\n      search: true,\n      fetch: true,\n      snippets: true,\n      content: true,\n      freshness: true,\n      siteFilter: true,\n      // Roughly two orders of magnitude more expensive than an HTTP read, which\n      // is why the engine only reaches for this after a source reports blocked.\n      cost: 'metered',\n    },\n    // Participation is governed solely by the policy row. The scheduler already\n    // keeps `kind: 'browser'` out of normal waves, so an enabled browser adapter\n    // is reached only for escalation \u2014 a second per-adapter switch just made the\n    // UI show two toggles meaning different things.\n    /** `heavy` \u2014 spawns and pings the sidecar process. */\n    probeCost: 'heavy' as const,\n    readiness: () => (startupFailure === null ? READY : notReady(startupFailure)),\n\n    async search(request, context): Promise<SearchOutcome> {\n      let lastReason = 'no engine produced results'\n\n      for (const engine of engines) {\n        if (context.signal.aborted) break\n        const profile = SERP_PROFILES[engine]\n        context.report('started', `rendering ${profile.label} in a browser`)\n        try {\n          const rendered = await render(profile.buildUrl(request), context.deadlineAt, context.signal)\n          const results = extractSerpResults(rendered.html, profile.selector, profile.baseUrl, request.limit)\n          if (results.length > 0) {\n            context.report('ok', `${profile.label} returned ${results.length} result(s)`, {\n              resultCount: results.length,\n            })\n            return searchOk(results)\n          }\n          const verdict = classifyPage({\n            status: 200,\n            contentType: 'text/html',\n            html: rendered.html,\n            text: '',\n          })\n          lastReason =\n            verdict.verdict === 'blocked'\n              ? `${profile.label} served a challenge page even in a browser (${verdict.reason ?? 'unknown'})`\n              : `${profile.label} rendered but produced no parseable results`\n        } catch (error) {\n          lastReason = error instanceof Error ? error.message : String(error)\n        }\n        context.report('blocked', lastReason)\n      }\n\n      return blocked(lastReason)\n    },\n\n    async fetch(request, context): Promise<FetchOutcome> {\n      try {\n        const rendered = await render(request.url, context.deadlineAt, context.signal)\n        const text = extractMainContent(rendered.html) || htmlToText(rendered.html)\n        return {\n          status: 'ok',\n          page: {\n            url: rendered.url,\n            title: extractTitle(rendered.html),\n            text,\n            contentType: 'text/html',\n            status: 200,\n            truncated: false,\n            renderedWith: 'browser',\n          },\n        }\n      } catch (error) {\n        return {\n          status: 'error',\n          reason: error instanceof Error ? error.message : String(error),\n          retriable: false,\n        }\n      }\n    },\n\n    async healthCheck() {\n      try {\n        await client().call('ping', {})\n        startupFailure = null\n        return { ok: true }\n      } catch (error) {\n        return { ok: false, detail: error instanceof Error ? error.message : String(error) }\n      }\n    },\n\n    async dispose() {\n      const active = sidecar\n      sidecar = null\n      if (active) await active.close()\n    },\n  }\n}\n\nexport const browserAdapterModule = defineAdapterModule({\n  id: 'browser',\n  kind: 'browser',\n  contractVersion: CONTRACT_VERSION,\n  optionsSchema: browserOptionsSchema,\n  createAdapter: createBrowserAdapter,\n})\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/client.js

@@ -0,0 +1,189 @@
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { SidecarError, decodeLine, encodeLine, isReply } from "./protocol.js";
+const DEFAULT_CALL_TIMEOUT_MS = 15e4;
+const DEFAULT_CLOSE_TIMEOUT_MS = 2e3;
+const DEFAULT_MAX_PENDING = 128;
+const SIGKILL_GRACE_MS = 2e3;
+const MAX_STDOUT_BUFFER = 64 * 1024 * 1024;
+const STDERR_RING = 24;
+function defaultSidecarPath() {
+  return path.join(path.dirname(fileURLToPath(import.meta.url)), "sidecar.js");
+}
+function defaultSpawn(scriptPath) {
+  const child = spawn(process.execPath, [scriptPath], {
+    stdio: ["pipe", "pipe", "pipe"]
+  });
+  return child;
+}
+class Sidecar {
+  constructor(sidecarPath, spawnFn, callTimeoutMs, closeTimeoutMs, maxPending) {
+    this.sidecarPath = sidecarPath;
+    this.spawnFn = spawnFn;
+    this.callTimeoutMs = callTimeoutMs;
+    this.closeTimeoutMs = closeTimeoutMs;
+    this.maxPending = maxPending;
+    this.child = null;
+    this.startError = null;
+    this.buffer = "";
+    this.recentStderr = [];
+    this.pending = /* @__PURE__ */ new Map();
+  }
+  ensure() {
+    if (this.child) return;
+    if (this.startError) throw this.startError;
+    try {
+      this.child = this.spawnFn(this.sidecarPath);
+    } catch (error) {
+      this.startError = error instanceof Error ? error : new Error(String(error));
+      throw this.startError;
+    }
+    this.buffer = "";
+    this.recentStderr = [];
+    this.child.stdout.setEncoding?.("utf8");
+    this.child.stdout.on("data", (chunk) => {
+      this.buffer += chunk;
+      let newline = this.buffer.indexOf("\n");
+      while (newline !== -1) {
+        const line = this.buffer.slice(0, newline);
+        this.buffer = this.buffer.slice(newline + 1);
+        if (line.trim()) this.handleLine(line);
+        newline = this.buffer.indexOf("\n");
+      }
+      if (this.buffer.length > MAX_STDOUT_BUFFER) {
+        this.recentStderr.push(`dropped ${this.buffer.length} bytes of un-delimited sidecar output`);
+        this.buffer = "";
+      }
+    });
+    this.child.stdin.on?.("error", (error) => {
+      this.recentStderr.push(`sidecar stdin ${error.code ?? "error"}: ${error.message}`);
+      if (this.recentStderr.length > STDERR_RING) this.recentStderr.shift();
+    });
+    this.child.stderr.setEncoding?.("utf8");
+    this.child.stderr.on("data", (chunk) => {
+      for (const line of chunk.split("\n")) {
+        if (!line.trim()) continue;
+        this.recentStderr.push(line);
+        if (this.recentStderr.length > STDERR_RING) this.recentStderr.shift();
+      }
+    });
+    this.child.once("exit", (code) => {
+      const tail = this.recentStderr.slice(-8).join("\n").trim();
+      const error = new SidecarError(
+        `browser sidecar exited unexpectedly (code=${code ?? "null"})${tail ? `:
+${tail}` : ""}`,
+        "init"
+      );
+      for (const [, entry] of this.pending) {
+        clearTimeout(entry.timer);
+        entry.reject(error);
+      }
+      this.pending.clear();
+      this.child = null;
+    });
+  }
+  handleLine(line) {
+    const parsed = decodeLine(line);
+    if (!isReply(parsed)) return;
+    const entry = this.pending.get(parsed.id);
+    if (!entry) return;
+    this.pending.delete(parsed.id);
+    clearTimeout(entry.timer);
+    if (parsed.ok) {
+      entry.resolve(parsed.result);
+      return;
+    }
+    entry.reject(new SidecarError(parsed.error.message, parsed.error.kind));
+  }
+  async call(method, params = {}, signal) {
+    this.ensure();
+    const child = this.child;
+    if (!child) throw new SidecarError("browser sidecar is not running", "init");
+    if (this.pending.size >= this.maxPending) {
+      throw new SidecarError(`browser sidecar busy (${this.pending.size} in flight)`, "runtime");
+    }
+    const id = randomUUID();
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        signal?.removeEventListener("abort", onAbort);
+        reject(new SidecarError(`browser sidecar call "${method}" timed out`, "timeout"));
+      }, this.callTimeoutMs);
+      timer.unref?.();
+      const onAbort = () => {
+        if (!this.pending.delete(id)) return;
+        clearTimeout(timer);
+        reject(new SidecarError(`browser sidecar call "${method}" was aborted`, "timeout"));
+      };
+      signal?.addEventListener("abort", onAbort, { once: true });
+      this.pending.set(id, {
+        resolve: (value) => {
+          signal?.removeEventListener("abort", onAbort);
+          resolve(value);
+        },
+        reject: (error) => {
+          signal?.removeEventListener("abort", onAbort);
+          reject(error);
+        },
+        timer
+      });
+      try {
+        child.stdin.write(encodeLine({ id, method, params }));
+      } catch (error) {
+        this.pending.delete(id);
+        clearTimeout(timer);
+        signal?.removeEventListener("abort", onAbort);
+        reject(error instanceof Error ? error : new Error(String(error)));
+      }
+    });
+  }
+  async close() {
+    const child = this.child;
+    if (!child) return;
+    try {
+      const closeSignal = AbortSignal.timeout(this.closeTimeoutMs);
+      await this.call("close", {}, closeSignal);
+    } catch {
+    }
+    await new Promise((resolve) => {
+      let settled = false;
+      const done = () => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        resolve();
+      };
+      child.once("exit", done);
+      const timer = setTimeout(() => {
+        try {
+          child.kill("SIGKILL");
+        } catch {
+        }
+        done();
+      }, SIGKILL_GRACE_MS);
+      timer.unref?.();
+      try {
+        child.kill("SIGTERM");
+      } catch {
+        done();
+      }
+    });
+    this.child = null;
+  }
+}
+function createSidecar(options = {}) {
+  return new Sidecar(
+    options.sidecarPath ?? defaultSidecarPath(),
+    options.spawnFn ?? defaultSpawn,
+    options.callTimeoutMs ?? DEFAULT_CALL_TIMEOUT_MS,
+    options.closeTimeoutMs ?? DEFAULT_CLOSE_TIMEOUT_MS,
+    options.maxPending ?? DEFAULT_MAX_PENDING
+  );
+}
+export {
+  Sidecar,
+  createSidecar
+};
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/client.ts"],
+  "sourcesContent": ["import { spawn, type ChildProcessWithoutNullStreams } from 'node:child_process'\nimport { randomUUID } from 'node:crypto'\nimport path from 'node:path'\nimport { fileURLToPath } from 'node:url'\nimport { SidecarError, decodeLine, encodeLine, isReply, type SidecarReply } from './protocol'\n\nexport type SidecarStream = {\n  stdin: { write(chunk: string): unknown; on?(event: 'error', handler: (error: NodeJS.ErrnoException) => void): unknown }\n  stdout: { setEncoding?(encoding: string): unknown; on(event: 'data', handler: (chunk: string) => void): unknown }\n  stderr: { setEncoding?(encoding: string): unknown; on(event: 'data', handler: (chunk: string) => void): unknown }\n  once(event: 'exit', handler: (code: number | null) => void): unknown\n  kill(signal?: NodeJS.Signals): unknown\n}\n\nexport type SpawnFn = (scriptPath: string) => SidecarStream\n\nexport type SidecarOptions = {\n  readonly sidecarPath?: string\n  readonly spawnFn?: SpawnFn\n  readonly callTimeoutMs?: number\n  readonly closeTimeoutMs?: number\n  readonly maxPending?: number\n}\n\nconst DEFAULT_CALL_TIMEOUT_MS = 150_000\n/**\n * Deliberately short and separate from the call timeout: shutdown must not block\n * for minutes on a wedged child before SIGTERM is even attempted.\n */\nconst DEFAULT_CLOSE_TIMEOUT_MS = 2_000\nconst DEFAULT_MAX_PENDING = 128\nconst SIGKILL_GRACE_MS = 2_000\n/** A full-page screenshot or a large DOM fits comfortably; a runaway does not. */\nconst MAX_STDOUT_BUFFER = 64 * 1024 * 1024\nconst STDERR_RING = 24\n\nfunction defaultSidecarPath(): string {\n  return path.join(path.dirname(fileURLToPath(import.meta.url)), 'sidecar.js')\n}\n\nfunction defaultSpawn(scriptPath: string): SidecarStream {\n  const child: ChildProcessWithoutNullStreams = spawn(process.execPath, [scriptPath], {\n    stdio: ['pipe', 'pipe', 'pipe'],\n  })\n  return child as unknown as SidecarStream\n}\n\ntype Pending = {\n  resolve: (value: unknown) => void\n  reject: (error: Error) => void\n  timer: NodeJS.Timeout\n}\n\nexport class Sidecar {\n  private child: SidecarStream | null = null\n  private startError: Error | null = null\n  private buffer = ''\n  private recentStderr: string[] = []\n  private readonly pending = new Map<string, Pending>()\n\n  constructor(\n    private readonly sidecarPath: string,\n    private readonly spawnFn: SpawnFn,\n    private readonly callTimeoutMs: number,\n    private readonly closeTimeoutMs: number,\n    private readonly maxPending: number,\n  ) {}\n\n  private ensure(): void {\n    if (this.child) return\n    if (this.startError) throw this.startError\n    try {\n      this.child = this.spawnFn(this.sidecarPath)\n    } catch (error) {\n      this.startError = error instanceof Error ? error : new Error(String(error))\n      throw this.startError\n    }\n    // Reset per-process state on every spawn. A child that died mid-line would\n    // otherwise leave a JSON fragment that corrupts the next spawn's first\n    // reply \u2014 which then parses as garbage and hangs that call until timeout.\n    this.buffer = ''\n    this.recentStderr = []\n\n    this.child.stdout.setEncoding?.('utf8')\n    this.child.stdout.on('data', (chunk: string) => {\n      this.buffer += chunk\n      let newline = this.buffer.indexOf('\\n')\n      while (newline !== -1) {\n        const line = this.buffer.slice(0, newline)\n        this.buffer = this.buffer.slice(newline + 1)\n        if (line.trim()) this.handleLine(line)\n        newline = this.buffer.indexOf('\\n')\n      }\n      if (this.buffer.length > MAX_STDOUT_BUFFER) {\n        this.recentStderr.push(`dropped ${this.buffer.length} bytes of un-delimited sidecar output`)\n        this.buffer = ''\n      }\n    })\n\n    // A dead child leaves its stdin pipe broken, and Node reports that as an\n    // asynchronous 'error' event (EPIPE) rather than as a throw from write() \u2014\n    // so the try/catch around the write in `call` never sees it. Unhandled, a\n    // stream 'error' escalates past the adapter and the call throws instead of\n    // resolving to an outcome. Recording it keeps the event handled; the 'exit'\n    // handler below is what rejects the calls still in flight.\n    this.child.stdin.on?.('error', (error: NodeJS.ErrnoException) => {\n      this.recentStderr.push(`sidecar stdin ${error.code ?? 'error'}: ${error.message}`)\n      if (this.recentStderr.length > STDERR_RING) this.recentStderr.shift()\n    })\n\n    this.child.stderr.setEncoding?.('utf8')\n    this.child.stderr.on('data', (chunk: string) => {\n      for (const line of chunk.split('\\n')) {\n        if (!line.trim()) continue\n        this.recentStderr.push(line)\n        if (this.recentStderr.length > STDERR_RING) this.recentStderr.shift()\n      }\n    })\n\n    this.child.once('exit', (code) => {\n      const tail = this.recentStderr.slice(-8).join('\\n').trim()\n      const error = new SidecarError(\n        `browser sidecar exited unexpectedly (code=${code ?? 'null'})${tail ? `:\\n${tail}` : ''}`,\n        'init',\n      )\n      for (const [, entry] of this.pending) {\n        clearTimeout(entry.timer)\n        entry.reject(error)\n      }\n      this.pending.clear()\n      this.child = null\n    })\n  }\n\n  private handleLine(line: string): void {\n    const parsed = decodeLine(line)\n    if (!isReply(parsed)) return\n    const entry = this.pending.get(parsed.id)\n    if (!entry) return\n    this.pending.delete(parsed.id)\n    clearTimeout(entry.timer)\n    if (parsed.ok) {\n      entry.resolve(parsed.result)\n      return\n    }\n    entry.reject(new SidecarError(parsed.error.message, parsed.error.kind))\n  }\n\n  async call(method: string, params: Record<string, unknown> = {}, signal?: AbortSignal): Promise<unknown> {\n    this.ensure()\n    const child = this.child\n    if (!child) throw new SidecarError('browser sidecar is not running', 'init')\n    if (this.pending.size >= this.maxPending) {\n      throw new SidecarError(`browser sidecar busy (${this.pending.size} in flight)`, 'runtime')\n    }\n\n    const id = randomUUID()\n    return new Promise<unknown>((resolve, reject) => {\n      const timer = setTimeout(() => {\n        this.pending.delete(id)\n        signal?.removeEventListener('abort', onAbort)\n        reject(new SidecarError(`browser sidecar call \"${method}\" timed out`, 'timeout'))\n      }, this.callTimeoutMs)\n      timer.unref?.()\n\n      // Abort rejects THIS call only. The sidecar is shared, so killing it would\n      // take healthy concurrent leases down with it; a late reply is ignored\n      // because its id is no longer pending.\n      const onAbort = (): void => {\n        if (!this.pending.delete(id)) return\n        clearTimeout(timer)\n        reject(new SidecarError(`browser sidecar call \"${method}\" was aborted`, 'timeout'))\n      }\n      signal?.addEventListener('abort', onAbort, { once: true })\n\n      this.pending.set(id, {\n        resolve: (value) => {\n          signal?.removeEventListener('abort', onAbort)\n          resolve(value)\n        },\n        reject: (error) => {\n          signal?.removeEventListener('abort', onAbort)\n          reject(error)\n        },\n        timer,\n      })\n\n      try {\n        child.stdin.write(encodeLine({ id, method, params }))\n      } catch (error) {\n        this.pending.delete(id)\n        clearTimeout(timer)\n        signal?.removeEventListener('abort', onAbort)\n        reject(error instanceof Error ? error : new Error(String(error)))\n      }\n    })\n  }\n\n  async close(): Promise<void> {\n    const child = this.child\n    if (!child) return\n    try {\n      const closeSignal = AbortSignal.timeout(this.closeTimeoutMs)\n      await this.call('close', {}, closeSignal)\n    } catch {\n      // Wedged or already gone; escalate below.\n    }\n    await new Promise<void>((resolve) => {\n      let settled = false\n      const done = (): void => {\n        if (settled) return\n        settled = true\n        clearTimeout(timer)\n        resolve()\n      }\n      child.once('exit', done)\n      // Armed before the kill so a synchronous exit still finds the timer set.\n      const timer = setTimeout(() => {\n        try {\n          child.kill('SIGKILL')\n        } catch {\n          // Already gone.\n        }\n        done()\n      }, SIGKILL_GRACE_MS)\n      timer.unref?.()\n      try {\n        child.kill('SIGTERM')\n      } catch {\n        done()\n      }\n    })\n    this.child = null\n  }\n}\n\nexport function createSidecar(options: SidecarOptions = {}): Sidecar {\n  return new Sidecar(\n    options.sidecarPath ?? defaultSidecarPath(),\n    options.spawnFn ?? defaultSpawn,\n    options.callTimeoutMs ?? DEFAULT_CALL_TIMEOUT_MS,\n    options.closeTimeoutMs ?? DEFAULT_CLOSE_TIMEOUT_MS,\n    options.maxPending ?? DEFAULT_MAX_PENDING,\n  )\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/dispatch.js

@@ -0,0 +1,161 @@
+import { assertPublicUrl } from "@open-mercato/web-research";
+import {
+  DEFAULT_USER_AGENT,
+  isSandboxDisabled,
+  resolveLaunchArgs,
+  importChromium,
+  installNavigationGuard,
+  launchChromium
+} from "./playwright.js";
+import { SidecarError } from "./protocol.js";
+const LEASE_IDLE_TIMEOUT_MS = 5 * 6e4;
+const DEFAULT_GOTO_TIMEOUT_MS = 3e4;
+const MAX_GOTO_TIMEOUT_MS = 12e4;
+function createState(overrides = {}) {
+  return {
+    browser: null,
+    leases: /* @__PURE__ */ new Map(),
+    filterSubresources: process.env.OM_WEB_RESEARCH_BROWSER_FILTER_SUBRESOURCES === "1",
+    warn: (message) => process.stderr.write(`om-web-research-sidecar: ${message}
+`),
+    now: () => Date.now(),
+    ...overrides
+  };
+}
+async function ensureBrowser(state) {
+  if (state.browser) return state.browser;
+  const chromium = await importChromium();
+  if (isSandboxDisabled()) {
+    state.warn(
+      "SECURITY: Chromium sandbox is disabled by OM_WEB_RESEARCH_BROWSER_NO_SANDBOX=1 \u2014 a renderer compromise reaches this host"
+    );
+  }
+  state.browser = await launchChromium(
+    chromium,
+    { headless: true, args: resolveLaunchArgs() },
+    { onProgress: state.warn, ...state.installRunner ? { install: state.installRunner } : {} }
+  );
+  return state.browser;
+}
+async function openLease(state, leaseId, userAgent) {
+  await reapIdleLeases(state);
+  const existing = state.leases.get(leaseId);
+  if (existing) {
+    existing.touchedAt = state.now();
+    return existing;
+  }
+  const browser = await ensureBrowser(state);
+  const context = await browser.newContext({ userAgent, locale: "en-US" });
+  await installNavigationGuard(context, { filterSubresources: state.filterSubresources, warn: state.warn });
+  const page = await context.newPage();
+  const lease = { context, page, touchedAt: state.now() };
+  state.leases.set(leaseId, lease);
+  return lease;
+}
+async function reapIdleLeases(state) {
+  const cutoff = state.now() - LEASE_IDLE_TIMEOUT_MS;
+  for (const [leaseId, lease] of [...state.leases]) {
+    if (lease.touchedAt > cutoff) continue;
+    state.warn(`reaping lease ${leaseId} idle for over ${LEASE_IDLE_TIMEOUT_MS}ms`);
+    await closeLease(state, leaseId);
+  }
+}
+async function closeLease(state, leaseId) {
+  const lease = state.leases.get(leaseId);
+  if (!lease) return;
+  state.leases.delete(leaseId);
+  try {
+    await lease.context.close();
+  } catch {
+  }
+}
+async function teardown(state) {
+  for (const leaseId of [...state.leases.keys()]) await closeLease(state, leaseId);
+  const browser = state.browser;
+  state.browser = null;
+  if (browser) {
+    try {
+      await browser.close();
+    } catch {
+    }
+  }
+}
+function stringParam(request, key) {
+  const value = request.params?.[key];
+  if (typeof value !== "string" || value.length === 0) {
+    throw new SidecarError(`missing "${key}" parameter`, "runtime");
+  }
+  return value;
+}
+async function dispatchInner(state, request) {
+  switch (request.method) {
+    case "ping":
+      return { id: request.id, ok: true, result: { ready: true } };
+    case "render": {
+      const url = stringParam(request, "url");
+      const leaseId = stringParam(request, "leaseId");
+      try {
+        await assertPublicUrl(url, "browser render", { failClosed: true });
+      } catch (error) {
+        return {
+          id: request.id,
+          ok: false,
+          error: { message: error instanceof Error ? error.message : String(error), kind: "navigation" }
+        };
+      }
+      const userAgent = typeof request.params?.userAgent === "string" ? request.params.userAgent : DEFAULT_USER_AGENT;
+      const timeout = Math.min(
+        typeof request.params?.timeoutMs === "number" ? request.params.timeoutMs : DEFAULT_GOTO_TIMEOUT_MS,
+        MAX_GOTO_TIMEOUT_MS
+      );
+      const waitUntil = typeof request.params?.waitUntil === "string" ? request.params.waitUntil : "domcontentloaded";
+      const lease = await openLease(state, leaseId, userAgent);
+      try {
+        await lease.page.goto(url, { waitUntil, timeout });
+      } catch (error) {
+        return {
+          id: request.id,
+          ok: false,
+          error: { message: error instanceof Error ? error.message : String(error), kind: "navigation" }
+        };
+      }
+      const html = await lease.page.content();
+      return { id: request.id, ok: true, result: { url: lease.page.url(), html } };
+    }
+    case "release":
+      await closeLease(state, stringParam(request, "leaseId"));
+      return { id: request.id, ok: true };
+    case "close":
+      await teardown(state);
+      return { id: request.id, ok: true };
+    default:
+      return {
+        id: request.id,
+        ok: false,
+        error: { message: `unknown method: ${request.method}`, kind: "runtime" }
+      };
+  }
+}
+async function dispatch(state, request) {
+  try {
+    return await dispatchInner(state, request);
+  } catch (error) {
+    return {
+      id: request.id,
+      ok: false,
+      error: {
+        message: error instanceof Error ? error.message : String(error),
+        kind: error instanceof SidecarError ? error.kind : "unknown"
+      }
+    };
+  }
+}
+export {
+  DEFAULT_GOTO_TIMEOUT_MS,
+  LEASE_IDLE_TIMEOUT_MS,
+  createState,
+  dispatch,
+  reapIdleLeases,
+  teardown
+};
+//# sourceMappingURL=dispatch.js.map

package/dist/dispatch.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/dispatch.ts"],
+  "sourcesContent": ["import { assertPublicUrl } from '@open-mercato/web-research'\nimport {\n  DEFAULT_USER_AGENT,\n  isSandboxDisabled,\n  resolveLaunchArgs,\n  importChromium,\n  installNavigationGuard,\n  launchChromium,\n  type InstallRunner,\n  type BrowserHandle,\n  type ContextHandle,\n  type PageHandle,\n} from './playwright'\nimport { SidecarError, type SidecarReply, type SidecarRequest } from './protocol'\n\nexport type Lease = { context: ContextHandle; page: PageHandle; touchedAt: number }\n\n/**\n * How long an untouched lease may live.\n *\n * `release` normally closes a context, but the caller can die between `render`\n * and `release` \u2014 a killed parent, a dropped socket \u2014 and every orphan is a live\n * BrowserContext holding memory for as long as the sidecar runs.\n */\nexport const LEASE_IDLE_TIMEOUT_MS = 5 * 60_000\n\nexport type SidecarState = {\n  browser: BrowserHandle | null\n  leases: Map<string, Lease>\n  filterSubresources: boolean\n  warn: (message: string) => void\n  /** Injectable so a lease-expiry test does not have to wait five minutes. */\n  now: () => number\n  /** Injectable so tests never shell out to `npx playwright install`. */\n  installRunner?: InstallRunner\n}\n\nexport const DEFAULT_GOTO_TIMEOUT_MS = 30_000\nconst MAX_GOTO_TIMEOUT_MS = 120_000\n\nexport function createState(overrides: Partial<SidecarState> = {}): SidecarState {\n  return {\n    browser: null,\n    leases: new Map(),\n    filterSubresources: process.env.OM_WEB_RESEARCH_BROWSER_FILTER_SUBRESOURCES === '1',\n    warn: (message) => process.stderr.write(`om-web-research-sidecar: ${message}\\n`),\n    now: () => Date.now(),\n    ...overrides,\n  }\n}\n\nasync function ensureBrowser(state: SidecarState): Promise<BrowserHandle> {\n  if (state.browser) return state.browser\n  const chromium = await importChromium()\n  if (isSandboxDisabled()) {\n    // Said once per browser, not once per render, but said: this process renders\n    // pages chosen by a search engine or a model with the one mitigation\n    // Chromium offers against a hostile renderer turned off.\n    state.warn(\n      'SECURITY: Chromium sandbox is disabled by OM_WEB_RESEARCH_BROWSER_NO_SANDBOX=1 \u2014 a renderer compromise reaches this host',\n    )\n  }\n  state.browser = await launchChromium(\n    chromium,\n    { headless: true, args: resolveLaunchArgs() },\n    { onProgress: state.warn, ...(state.installRunner ? { install: state.installRunner } : {}) },\n  )\n  return state.browser\n}\n\n/**\n * One BrowserContext per lease. Contexts are Playwright's real isolation boundary\n * (cookies, storage, cache) and cost ~10ms, so two concurrent searches never share\n * a cookie jar the way a single shared page would.\n */\nasync function openLease(state: SidecarState, leaseId: string, userAgent: string): Promise<Lease> {\n  await reapIdleLeases(state)\n  const existing = state.leases.get(leaseId)\n  if (existing) {\n    existing.touchedAt = state.now()\n    return existing\n  }\n  const browser = await ensureBrowser(state)\n  const context = await browser.newContext({ userAgent, locale: 'en-US' })\n  await installNavigationGuard(context, { filterSubresources: state.filterSubresources, warn: state.warn })\n  const page = (await context.newPage()) as unknown as PageHandle\n  const lease: Lease = { context, page, touchedAt: state.now() }\n  state.leases.set(leaseId, lease)\n  return lease\n}\n\n/** Closes leases nobody released. Swept on open, so an idle sidecar stays idle. */\nexport async function reapIdleLeases(state: SidecarState): Promise<void> {\n  const cutoff = state.now() - LEASE_IDLE_TIMEOUT_MS\n  for (const [leaseId, lease] of [...state.leases]) {\n    if (lease.touchedAt > cutoff) continue\n    state.warn(`reaping lease ${leaseId} idle for over ${LEASE_IDLE_TIMEOUT_MS}ms`)\n    await closeLease(state, leaseId)\n  }\n}\n\nasync function closeLease(state: SidecarState, leaseId: string): Promise<void> {\n  const lease = state.leases.get(leaseId)\n  if (!lease) return\n  state.leases.delete(leaseId)\n  try {\n    await lease.context.close()\n  } catch {\n    // A context that already died takes nothing with it.\n  }\n}\n\nexport async function teardown(state: SidecarState): Promise<void> {\n  for (const leaseId of [...state.leases.keys()]) await closeLease(state, leaseId)\n  const browser = state.browser\n  state.browser = null\n  if (browser) {\n    try {\n      await browser.close()\n    } catch {\n      // Best effort; the parent escalates to SIGKILL if we hang.\n    }\n  }\n}\n\nfunction stringParam(request: SidecarRequest, key: string): string {\n  const value = request.params?.[key]\n  if (typeof value !== 'string' || value.length === 0) {\n    throw new SidecarError(`missing \"${key}\" parameter`, 'runtime')\n  }\n  return value\n}\n\nasync function dispatchInner(state: SidecarState, request: SidecarRequest): Promise<SidecarReply> {\n  switch (request.method) {\n    case 'ping':\n      return { id: request.id, ok: true, result: { ready: true } }\n\n    case 'render': {\n      const url = stringParam(request, 'url')\n      const leaseId = stringParam(request, 'leaseId')\n      // Re-checked here, in a distinct process from the caller, and BEFORE\n      // Playwright is imported \u2014 a blocked URL never launches a browser.\n      try {\n        await assertPublicUrl(url, 'browser render', { failClosed: true })\n      } catch (error) {\n        return {\n          id: request.id,\n          ok: false,\n          error: { message: error instanceof Error ? error.message : String(error), kind: 'navigation' },\n        }\n      }\n\n      const userAgent = typeof request.params?.userAgent === 'string' ? request.params.userAgent : DEFAULT_USER_AGENT\n      const timeout = Math.min(\n        typeof request.params?.timeoutMs === 'number' ? request.params.timeoutMs : DEFAULT_GOTO_TIMEOUT_MS,\n        MAX_GOTO_TIMEOUT_MS,\n      )\n      const waitUntil = typeof request.params?.waitUntil === 'string' ? request.params.waitUntil : 'domcontentloaded'\n\n      const lease = await openLease(state, leaseId, userAgent)\n      try {\n        await lease.page.goto(url, { waitUntil, timeout })\n      } catch (error) {\n        return {\n          id: request.id,\n          ok: false,\n          error: { message: error instanceof Error ? error.message : String(error), kind: 'navigation' },\n        }\n      }\n      const html = await lease.page.content()\n      return { id: request.id, ok: true, result: { url: lease.page.url(), html } }\n    }\n\n    case 'release':\n      await closeLease(state, stringParam(request, 'leaseId'))\n      return { id: request.id, ok: true }\n\n    case 'close':\n      await teardown(state)\n      return { id: request.id, ok: true }\n\n    default:\n      return {\n        id: request.id,\n        ok: false,\n        error: { message: `unknown method: ${request.method}`, kind: 'runtime' },\n      }\n  }\n}\n\nexport async function dispatch(state: SidecarState, request: SidecarRequest): Promise<SidecarReply> {\n  try {\n    return await dispatchInner(state, request)\n  } catch (error) {\n    return {\n      id: request.id,\n      ok: false,\n      error: {\n        message: error instanceof Error ? error.message : String(error),\n        kind: error instanceof SidecarError ? error.kind : 'unknown',\n      },\n    }\n  }\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/index.js

@@ -0,0 +1,18 @@
+import {
+  browserAdapterModule,
+  browserOptionsSchema,
+  createBrowserAdapter
+} from "./adapter.js";
+import { Sidecar, createSidecar } from "./client.js";
+import { SidecarError } from "./protocol.js";
+import { browserAdapterModule as browserAdapterModule2 } from "./adapter.js";
+export {
+  Sidecar,
+  SidecarError,
+  browserAdapterModule,
+  browserOptionsSchema,
+  createBrowserAdapter,
+  createSidecar,
+  browserAdapterModule2 as default
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/index.ts"],
+  "sourcesContent": ["export {\n  browserAdapterModule,\n  browserOptionsSchema,\n  createBrowserAdapter,\n  type BrowserOptions,\n} from './adapter'\nexport { Sidecar, createSidecar, type SidecarOptions, type SidecarStream, type SpawnFn } from './client'\nexport { SidecarError, type SidecarErrorKind, type SidecarReply, type SidecarRequest } from './protocol'\n\nexport { browserAdapterModule as default } from './adapter'\n"],
+  "mappings": "AAAA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,OAEK;AACP,SAAS,SAAS,qBAA4E;AAC9F,SAAS,oBAAmF;AAE5F,SAAiC,wBAAxBA,6BAAuC;",
+  "names": ["browserAdapterModule"]
+}