@opencraw/driver 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,63 @@
-# Temporary Holding Version
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Open-Craw/OpenCraw/main/docs/assets/opencraw-logo.svg" alt="OpenCraw" width="360">
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @opencraw/driver
+
+[OpenCraw](https://github.com/Open-Craw/OpenCraw/blob/main/README.md)'s engine as a process another language talks
+to. A client in Python, Go, Dart, C#, Rust, Java, Ruby, PHP or C++ starts `opencraw-driver` once, and speaks
+**JSON-RPC 2.0 over its stdin and stdout, one message per line**. It sends recipes, gets every crawl event and
+record as it happens, and answers the recipes' hooks with functions in its own language. This is how the
+OpenCraw packages for other languages work (`docs/research/driver-and-language-packages.md`).
+
+```sh
+npx opencraw-driver   # then write JSON-RPC lines to it
+```
+
+## The conversation
+
+```jsonc
+→ {"jsonrpc":"2.0","id":1,"method":"initialize","params":{"clientName":"opencraw-python","clientVersion":"1.0.0","protocolVersion":"1.1.0"}}
+← {"jsonrpc":"2.0","id":1,"result":{"driverVersion":"0.2.0","protocolVersion":"1.1.0","methods":["initialize","validate","run","cancel","probe","diff","export","shutdown"]}}
+→ {"jsonrpc":"2.0","id":2,"method":"run","params":{"paths":["recipes/"],"hooks":["tidy"]}}
+← {"jsonrpc":"2.0","id":2,"result":{"runId":"run-1"}}
+← {"jsonrpc":"2.0","method":"event","params":{"runId":"run-1","event":{"type":"recipe:start",…}}}
+← {"jsonrpc":"2.0","id":1,"method":"callout","params":{"runId":"run-1","request":{"kind":"hook","name":"tidy","input":" A ",…}}}
+→ {"jsonrpc":"2.0","id":1,"result":{"status":"ok","output":"a"}}
+← {"jsonrpc":"2.0","method":"record","params":{"runId":"run-1","recipeId":"things","key":"…","data":{…}}}
+← {"jsonrpc":"2.0","method":"finished","params":{"runId":"run-1","report":{…}}}
+→ {"jsonrpc":"2.0","id":3,"method":"shutdown"}
+```
+
+| Method | From | Does |
+|---|---|---|
+| `initialize` | client | Must come first. The driver refuses a protocol of another major. |
+| `validate` | client | Loads recipes (`paths` or inline `recipes`) without running them: the inputs that would run, every hook they call, and every problem with its path. |
+| `run` | client | Starts a run and answers its `runId` at once; the crawl goes on in the background. `hooks`, `captchaSolvers` and `accessPlugins` name what the client answers; `accessConfig` and `access` pick the access config and profile; `out` writes records to a file instead of sending them. |
+| `cancel` | client | Stops a run (its crawler is closed); it still ends with `finished`. |
+| `probe` | client | Fetches a page (or renders it, with `browser`) and says where its data lives: the CLI's and MCP's probe, through the same access fields as `run`. |
+| `diff` | client | Compares two runs' JSON Lines files by key: counts, the report a person reads, and the changes up to `limit`. |
+| `export` | client | Writes a run's JSON Lines file in another format (the extension of `out`), with an output recipe's columns. |
+| `shutdown` | client | Closes every run, answers, then exits. Closing stdin does the same. |
+| `event` | driver | Every crawl event, as core reports it. |
+| `record` | driver | Each record, unless the run has `out`. |
+| `finished` | driver | The run is over: its report, or why it could not run. |
+| `callout` | driver | A hook, captcha solver or access plugin the client serves (`request.kind`: `hook`, `captcha`, `access`). The request and its answer are core's [callout contract](../core/README.md): `ok`, `error`, or `pending` with `retryAfterMs`, asked again with the same idempotency key. |
+
+Every answer comes back before the driver stops, even when a client writes its last requests and closes
+stdin at once. Answers may arrive out of order; match them by `id`.
+
+## For client authors
+
+- `schemas/driver-protocol.schema.json` is every message's shape, generated from the protocol's zod
+  contracts. Generate your models from it rather than typing them by hand.
+- `conformance/*.json` are recorded conversations. A client is done when it replays them all against the real
+  driver. See `conformance/README.md`.
+- Errors are JSON-RPC's codes: `-32700` (not JSON), `-32600` (not JSON-RPC), `-32601` (no such method),
+  `-32602` (bad params, the problems listed), `-32000` (a failure to act on: its message says what to do).
+- stdout carries protocol messages only. The driver's own logs go to stderr.
+
+## Development
+
+`smith run lint typecheck test build -p driver`. After changing a contract in `src/protocol/`, run
+`smith run schemas -p driver` to rewrite `schemas/driver-protocol.schema.json`; a test fails until you do.

package/dist/index.esm.js

@@ -0,0 +1,513 @@
+// src/server/serve-driver.use-case.ts
+import { once } from "node:events";
+
+// src/protocol/driver-message.contract.ts
+import { calloutRequestSchema, calloutResponseSchema } from "@opencraw/core";
+import { z } from "zod";
+var PROTOCOL_VERSION = "1.1.0";
+var recipeObject = z.record(z.string(), z.unknown());
+var coreObject = z.record(z.string(), z.unknown());
+var accessFields = {
+  accessConfig: z.string().optional(),
+  access: z.string().optional(),
+  /** Access plugins the client serves: a profile `{ "kind": "plugin", "name": … }` naming one leases through a `callout` to the client. */
+  accessPlugins: z.array(z.string()).optional()
+};
+var recipeSource = {
+  paths: z.array(z.string()).min(1).optional(),
+  recipes: z.array(recipeObject).min(1).optional()
+};
+var initializeParamsSchema = z.strictObject({
+  clientName: z.string().min(1),
+  clientVersion: z.string().min(1),
+  protocolVersion: z.string().regex(/^\d+\.\d+\.\d+$/)
+});
+var initializeResultSchema = z.strictObject({
+  driverVersion: z.string(),
+  protocolVersion: z.string(),
+  methods: z.array(z.string())
+});
+var validateParamsSchema = z.strictObject({ ...recipeSource, only: z.array(z.string()).optional() });
+var issueSchema = z.strictObject({ source: z.string().optional(), recipeId: z.string().optional(), path: z.string(), message: z.string() });
+var validateResultSchema = z.strictObject({
+  ok: z.boolean(),
+  /** The input recipes that would run, when ok. */
+  inputs: z.array(z.string()),
+  /** Every hook the recipes call, which a `run` must serve. */
+  hooks: z.array(z.string()),
+  issues: z.array(issueSchema)
+});
+var runParamsSchema = z.strictObject({
+  ...recipeSource,
+  only: z.array(z.string()).optional(),
+  /** A file to write the records to, its extension naming the format; without it, each record is sent as a `record` notification. */
+  out: z.string().optional(),
+  append: z.boolean().optional(),
+  resume: z.boolean().optional(),
+  dryRun: z.boolean().optional(),
+  parallel: z.number().int().min(1).max(16).optional(),
+  browser: z.strictObject({ headless: z.boolean().optional(), executablePath: z.string().optional(), ignoreHTTPSErrors: z.boolean().optional() }).optional(),
+  /** The hooks the client answers itself: each becomes a `callout` request to the client when a recipe calls it. */
+  hooks: z.array(z.string()).optional(),
+  /** Captcha solvers the client serves, by name: a challenge goes to the client as a `captcha` callout. */
+  captchaSolvers: z.array(z.string()).optional(),
+  ...accessFields
+});
+var runResultSchema = z.strictObject({ runId: z.string() });
+var cancelParamsSchema = z.strictObject({ runId: z.string() });
+var cancelResultSchema = z.strictObject({ cancelled: z.boolean() });
+var probeParamsSchema = z.strictObject({
+  url: z.string().min(1),
+  /** Render the page in Chromium first (for pages built by scripts). */
+  browser: z.boolean().optional(),
+  browserPath: z.string().optional(),
+  insecureTls: z.boolean().optional(),
+  userAgent: z.string().optional(),
+  ...accessFields
+});
+var probeResultSchema = coreObject;
+var diffParamsSchema = z.strictObject({
+  /** The earlier run's JSON Lines file. */
+  previous: z.string().min(1),
+  current: z.string().min(1),
+  /** The fields that identify a record; default: each line's `_key`. */
+  key: z.array(z.string()).optional(),
+  /** Fields left out of the comparison. */
+  ignore: z.array(z.string()).optional(),
+  /** Changes returned at most (default 200); the counts cover all of them. */
+  limit: z.number().int().min(0).optional()
+});
+var diffResultSchema = z.strictObject({
+  added: z.number(),
+  removed: z.number(),
+  changed: z.number(),
+  unchanged: z.number(),
+  /** Set when the current run lost most of the previous run's records. */
+  shrunk: z.strictObject({ previous: z.number(), current: z.number() }).optional(),
+  /** The report a person reads, one line per change. */
+  summary: z.array(z.string()),
+  /** The changes, up to `limit`: each `added`, `removed` or `changed` (with each field's before and after). */
+  changes: z.array(coreObject),
+  /** More changes than `limit` were found. */
+  truncated: z.boolean()
+});
+var exportParamsSchema = z.strictObject({
+  /** A run's JSON Lines file. */
+  records: z.string().min(1),
+  /** The output recipe that gives the columns. */
+  output: z.string().min(1),
+  /** The file to write; its extension names the format, as for `run`. */
+  out: z.string().min(1)
+});
+var exportResultSchema = z.strictObject({ written: z.number(), location: z.string() });
+var shutdownResultSchema = z.strictObject({});
+var eventParamsSchema = z.strictObject({ runId: z.string(), event: z.record(z.string(), z.unknown()) });
+var recordParamsSchema = z.strictObject({ runId: z.string(), recipeId: z.string(), key: z.string().nullable(), data: z.record(z.string(), z.unknown()) });
+var finishedParamsSchema = z.strictObject({
+  runId: z.string(),
+  /** The crawl report (`CrawlReport`), absent when the run could not start. */
+  report: z.record(z.string(), z.unknown()).optional(),
+  /** Why the run could not start, or stopped as a whole. */
+  error: z.string().optional()
+});
+var calloutParamsSchema = z.strictObject({ runId: z.string(), request: calloutRequestSchema });
+var calloutResultSchema = calloutResponseSchema;
+var MESSAGES = {
+  initialize: { direction: "client-to-driver", params: initializeParamsSchema, result: initializeResultSchema },
+  validate: { direction: "client-to-driver", params: validateParamsSchema, result: validateResultSchema },
+  run: { direction: "client-to-driver", params: runParamsSchema, result: runResultSchema },
+  cancel: { direction: "client-to-driver", params: cancelParamsSchema, result: cancelResultSchema },
+  probe: { direction: "client-to-driver", params: probeParamsSchema, result: probeResultSchema },
+  diff: { direction: "client-to-driver", params: diffParamsSchema, result: diffResultSchema },
+  export: { direction: "client-to-driver", params: exportParamsSchema, result: exportResultSchema },
+  shutdown: { direction: "client-to-driver", params: void 0, result: shutdownResultSchema },
+  callout: { direction: "driver-to-client", params: calloutParamsSchema, result: calloutResultSchema },
+  event: { direction: "driver-to-client", params: eventParamsSchema, result: void 0 },
+  record: { direction: "driver-to-client", params: recordParamsSchema, result: void 0 },
+  finished: { direction: "driver-to-client", params: finishedParamsSchema, result: void 0 }
+};
+
+// src/protocol/driver-json-schema.mapper.ts
+import { z as z2 } from "zod";
+var OPTIONS = { target: "draft-2020-12", io: "output", unrepresentable: "any" };
+function driverProtocolJsonSchema() {
+  const defs = {};
+  const methods = {};
+  for (const [name, message] of Object.entries(MESSAGES)) {
+    const entry = { direction: message.direction };
+    if (message.params !== void 0) {
+      defs[`${name}.params`] = z2.toJSONSchema(message.params, OPTIONS);
+      entry.params = { $ref: `#/$defs/${name}.params` };
+    }
+    if (message.result !== void 0) {
+      defs[`${name}.result`] = z2.toJSONSchema(message.result, OPTIONS);
+      entry.result = { $ref: `#/$defs/${name}.result` };
+    }
+    methods[name] = entry;
+  }
+  return {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    $id: "https://opencraw/schemas/driver-protocol.schema.json",
+    title: "OpenCraw driver protocol",
+    description: "JSON-RPC 2.0 over stdio, one message per line. Methods with a result are requests; the rest are notifications.",
+    protocolVersion: PROTOCOL_VERSION,
+    methods,
+    $defs: defs
+  };
+}
+
+// src/record-files/diff-record-files.use-case.ts
+import { diffReport } from "@opencraw/cli";
+import { diffRecords, readRecordsFile } from "@opencraw/core";
+var CHANGE_LIMIT = 200;
+async function diffRecordFiles(params) {
+  const [previous, current] = await Promise.all([readRecordsFile(params.previous), readRecordsFile(params.current)]);
+  const diff = diffRecords(previous, current, { key: params.key, ignore: params.ignore });
+  const limit = params.limit ?? CHANGE_LIMIT;
+  return {
+    added: diff.added,
+    removed: diff.removed,
+    changed: diff.changed,
+    unchanged: diff.unchanged,
+    ...diff.shrunk !== void 0 && { shrunk: diff.shrunk },
+    summary: diffReport(diff),
+    changes: diff.changes.slice(0, limit).map((change) => ({ ...change })),
+    truncated: diff.changes.length > limit
+  };
+}
+
+// src/record-files/export-record-files.use-case.ts
+import { readFile } from "node:fs/promises";
+import { fileSink, outputRecordOf, parseOutputRecipe, readRecordsFile as readRecordsFile2 } from "@opencraw/core";
+async function exportRecordFiles(params) {
+  const output = parseOutputRecipe(JSON.parse(await readFile(params.output, "utf8")), params.output);
+  const stored = await readRecordsFile2(params.records);
+  const sink = fileSink(params.out, { browser: { executablePath: process.env.OPENCRAW_CHROMIUM } });
+  await sink.open(output);
+  for (const line of stored) await sink.write(outputRecordOf(line));
+  const summary = await sink.close();
+  return { written: summary.written, location: summary.location ?? params.out };
+}
+
+// src/session/run-session.use-case.ts
+import { createCrawler, fileSink as fileSink2, RecipeSet } from "@opencraw/core";
+
+// src/callout-bridge/client-hooks.client.ts
+import { accessPluginVia, calloutHook, calloutResponseSchema as calloutResponseSchema2, captchaSolverVia } from "@opencraw/core";
+function clientTransport(label, runId, ask) {
+  return {
+    label,
+    call: async (request) => calloutResponseSchema2.parse(await ask("callout", { runId, request }))
+  };
+}
+function clientHooks(names, runId, ask) {
+  return Object.fromEntries(names.map((name) => [name, calloutHook(name, clientTransport(`client hook ${name}`, runId, ask))]));
+}
+function clientCaptchaSolvers(names, runId, ask) {
+  return names.map((name) => captchaSolverVia(name, clientTransport(`client captcha solver ${name}`, runId, ask)));
+}
+function clientAccessPlugins(names, runId, ask) {
+  return names.map((name) => accessPluginVia(name, clientTransport(`client access plugin ${name}`, runId, ask)));
+}
+
+// src/site-access/resolve-site-access.use-case.ts
+import { resolveAccess } from "@opencraw/cli";
+async function resolveSiteAccess(params, runId, ask, env = process.env) {
+  const file = params.accessConfig ?? env.OPENCRAW_ACCESS;
+  if (file === void 0 && params.access !== void 0) throw new Error(`access profile "${params.access}" needs an access config: give "accessConfig", or set OPENCRAW_ACCESS where the driver runs`);
+  const access = await resolveAccess({ insecureTls: false, access: file, accessProfile: params.access });
+  return { access, accessPlugins: clientAccessPlugins(params.accessPlugins ?? [], runId, ask) };
+}
+
+// src/session/recipe-loading.use-case.ts
+import { loadForRun } from "@opencraw/cli";
+import { hookUses, RecipeBindingError, RecipeValidationError } from "@opencraw/core";
+function sourceOf(params) {
+  if (params.paths === void 0 === (params.recipes === void 0)) throw new Error('give exactly one of "paths" or "recipes"');
+  return params.paths ?? params.recipes ?? [];
+}
+async function loadRecipes(params) {
+  return await loadForRun(sourceOf(params), params.only ?? []);
+}
+function hooksOf(set) {
+  return [...new Set(set.inputs.flatMap((input) => hookUses(input).map((use) => use.name)))].sort((x, y) => x.localeCompare(y));
+}
+async function validateRecipes(params) {
+  try {
+    const set = await loadRecipes(params);
+    return { ok: true, inputs: set.inputs.map((input) => input.id), hooks: hooksOf(set), issues: [] };
+  } catch (error) {
+    if (error instanceof RecipeValidationError) return { ok: false, inputs: [], hooks: [], issues: error.issues.map((issue) => ({ source: error.source, path: issue.path, message: issue.message })) };
+    if (error instanceof RecipeBindingError) return { ok: false, inputs: [], hooks: [], issues: error.issues.map((issue) => ({ recipeId: issue.recipeId, path: issue.path, message: issue.message })) };
+    return { ok: false, inputs: [], hooks: [], issues: [{ path: "", message: error instanceof Error ? error.message : String(error) }] };
+  }
+}
+
+// src/session/streaming-sink.repository.ts
+function streamingSink() {
+  let written = 0;
+  return {
+    open: async () => {
+    },
+    write: async () => {
+      written += 1;
+    },
+    close: async () => ({ written })
+  };
+}
+
+// src/session/run-session.use-case.ts
+function runSessions(notify, ask) {
+  const running = /* @__PURE__ */ new Map();
+  let next = 1;
+  const crawl = async (runId, crawler, set) => {
+    try {
+      const report = await crawler.run(set);
+      notify("finished", { runId, report });
+    } catch (error) {
+      notify("finished", { runId, error: error instanceof Error ? error.message : String(error) });
+    } finally {
+      running.delete(runId);
+      await crawler.close();
+    }
+  };
+  return {
+    start: async (params) => {
+      const loaded = await loadRecipes(params);
+      const set = params.dryRun === true ? new RecipeSet(loaded.output, loaded.inputs.map((input) => ({ ...input, limits: { ...input.limits, maxRecords: 1 } }))) : loaded;
+      const runId = `run-${next++}`;
+      const { access, accessPlugins } = await resolveSiteAccess(params, runId, ask);
+      const crawler = createCrawler({
+        sink: params.out === void 0 ? streamingSink() : fileSink2(params.out, { append: params.append, browser: { executablePath: params.browser?.executablePath } }),
+        hooks: clientHooks(params.hooks ?? [], runId, ask),
+        captchaSolvers: clientCaptchaSolvers(params.captchaSolvers ?? [], runId, ask),
+        access,
+        accessPlugins,
+        profilesDir: process.env.OPENCRAW_PROFILES,
+        parallel: params.parallel,
+        resume: params.resume,
+        debug: params.dryRun,
+        browser: { headless: params.browser?.headless ?? true, executablePath: params.browser?.executablePath, ignoreHTTPSErrors: params.browser?.ignoreHTTPSErrors },
+        onEvent: (event) => {
+          notify("event", { runId, event });
+          if (event.type === "record:emit" && params.out === void 0) notify("record", { runId, recipeId: event.recipeId, key: event.key, data: event.data });
+        }
+      });
+      running.set(runId, crawler);
+      void crawl(runId, crawler, set);
+      return runId;
+    },
+    cancel: async (runId) => {
+      const crawler = running.get(runId);
+      if (crawler === void 0) return false;
+      running.delete(runId);
+      await crawler.close();
+      return true;
+    },
+    closeAll: async () => {
+      const crawlers = running.values().toArray();
+      running.clear();
+      await Promise.all(crawlers.map(async (crawler) => {
+        await crawler.close();
+      }));
+    }
+  };
+}
+
+// src/site-probe/probe-site.use-case.ts
+import { probeUrl } from "@opencraw/cli";
+async function probeSite(params, probeId, ask) {
+  const { access, accessPlugins } = await resolveSiteAccess(params, probeId, ask);
+  const result = await probeUrl(params.url, {
+    browser: params.browser ?? false,
+    browserPath: params.browserPath ?? process.env.OPENCRAW_CHROMIUM,
+    insecureTls: params.insecureTls ?? false,
+    userAgent: params.userAgent,
+    accessConfig: access,
+    accessPlugins
+  });
+  return { ...result };
+}
+
+// src/transport/line-channel.client.ts
+import { createInterface } from "node:readline";
+
+// src/transport/json-rpc.contract.ts
+var RPC_ERRORS = {
+  parse: -32700,
+  invalidRequest: -32600,
+  methodNotFound: -32601,
+  invalidParams: -32602,
+  internal: -32603,
+  /** A failure the caller must act on: the message says what to do. */
+  server: -32e3
+};
+var RpcFailure = class extends Error {
+  code;
+  data;
+  constructor(code, message, data) {
+    super(message);
+    this.name = "RpcFailure";
+    this.code = code;
+    this.data = data;
+  }
+};
+
+// src/transport/line-channel.client.ts
+var isRequestId = (id) => typeof id === "number" || typeof id === "string";
+function openLineChannel(input, output, handle) {
+  const pending = /* @__PURE__ */ new Map();
+  const answering = /* @__PURE__ */ new Set();
+  const track = (answered) => {
+    answering.add(answered);
+    void (async () => {
+      try {
+        await answered;
+      } finally {
+        answering.delete(answered);
+      }
+    })();
+  };
+  let nextId = 1;
+  const write = (message) => {
+    output.write(`${JSON.stringify(message)}
+`);
+  };
+  const fail = (id, error) => {
+    write({ jsonrpc: "2.0", id, error });
+  };
+  const answer = async (message) => {
+    const method = message.method;
+    try {
+      const result = await handle(method, message.params);
+      if (isRequestId(message.id)) write({ jsonrpc: "2.0", id: message.id, result: result ?? null });
+    } catch (error) {
+      if (!isRequestId(message.id)) return;
+      if (error instanceof RpcFailure) fail(message.id, { code: error.code, message: error.message, ...error.data !== void 0 && { data: error.data } });
+      else fail(message.id, { code: RPC_ERRORS.server, message: error instanceof Error ? error.message : String(error) });
+    }
+  };
+  const settle = (message) => {
+    const waiting = typeof message.id === "number" ? pending.get(message.id) : void 0;
+    if (waiting === void 0) return;
+    pending.delete(message.id);
+    if (message.error === void 0) waiting.resolve(message.result);
+    else waiting.reject(new RpcFailure(message.error.code, message.error.message, message.error.data));
+  };
+  const lines = createInterface({ input, crlfDelay: Infinity });
+  lines.on("line", (line) => {
+    if (line.trim() === "") return;
+    let message;
+    try {
+      message = JSON.parse(line);
+    } catch {
+      fail(null, { code: RPC_ERRORS.parse, message: "the line is not JSON" });
+      return;
+    }
+    if (message === null || typeof message !== "object" || message.jsonrpc !== "2.0") {
+      fail(isRequestId(message?.id) ? message.id : null, { code: RPC_ERRORS.invalidRequest, message: "not a JSON-RPC 2.0 message" });
+      return;
+    }
+    if (typeof message.method === "string") track(answer(message));
+    else settle(message);
+  });
+  const closed = new Promise((resolve) => {
+    lines.on("close", () => {
+      for (const waiting of pending.values()) waiting.reject(new Error("the client closed the channel"));
+      pending.clear();
+      resolve();
+    });
+  });
+  return {
+    request: async (method, params) => await new Promise((resolve, reject) => {
+      const id = nextId++;
+      pending.set(id, { resolve, reject });
+      write({ jsonrpc: "2.0", id, method, params });
+    }),
+    notify: (method, params) => {
+      write({ jsonrpc: "2.0", method, params });
+    },
+    closed,
+    drained: async () => {
+      while (answering.size > 0) await Promise.allSettled(answering);
+    }
+  };
+}
+
+// src/server/serve-driver.use-case.ts
+var METHODS = ["initialize", "validate", "run", "cancel", "probe", "diff", "export", "shutdown"];
+var major = (version) => version.split(".", 1)[0];
+function parsed(schema, params) {
+  const result = schema.safeParse(params ?? {});
+  if (!result.success) throw new RpcFailure(RPC_ERRORS.invalidParams, result.error.issues.map((issue) => `${issue.path.join(".") || "(params)"}: ${issue.message}`).join("; "), result.error.issues);
+  return result.data;
+}
+async function serveDriver(input, output, identity) {
+  let initialized = false;
+  const stopping = new AbortController();
+  let probes = 0;
+  const channel = openLineChannel(input, output, async (method, params) => {
+    if (method === "initialize") {
+      const hello = parsed(initializeParamsSchema, params);
+      if (major(hello.protocolVersion) !== major(PROTOCOL_VERSION)) throw new RpcFailure(RPC_ERRORS.server, `this driver speaks protocol ${PROTOCOL_VERSION}; ${hello.clientName} ${hello.clientVersion} asked for ${hello.protocolVersion}: use a client for protocol ${major(PROTOCOL_VERSION)}.x`);
+      initialized = true;
+      const result = { driverVersion: identity.driverVersion, protocolVersion: PROTOCOL_VERSION, methods: METHODS };
+      return result;
+    }
+    if (!METHODS.includes(method)) throw new RpcFailure(RPC_ERRORS.methodNotFound, `no method "${method}": the driver has ${METHODS.join(", ")}`);
+    if (!initialized) throw new RpcFailure(RPC_ERRORS.server, "call initialize first");
+    if (method === "validate") return await validateRecipes(parsed(validateParamsSchema, params));
+    if (method === "run") return { runId: await sessions.start(parsed(runParamsSchema, params)) };
+    if (method === "cancel") return { cancelled: await sessions.cancel(parsed(cancelParamsSchema, params).runId) };
+    if (method === "probe") return await probeSite(parsed(probeParamsSchema, params), `probe-${++probes}`, channel.request);
+    if (method === "diff") return await diffRecordFiles(parsed(diffParamsSchema, params));
+    if (method === "export") return await exportRecordFiles(parsed(exportParamsSchema, params));
+    await sessions.closeAll();
+    setImmediate(() => {
+      stopping.abort();
+    });
+    return {};
+  });
+  const sessions = runSessions(channel.notify, channel.request);
+  await Promise.race([channel.closed, once(stopping.signal, "abort")]);
+  await channel.drained();
+  await sessions.closeAll();
+}
+export {
+  MESSAGES,
+  PROTOCOL_VERSION,
+  RPC_ERRORS,
+  RpcFailure,
+  calloutParamsSchema,
+  calloutResultSchema,
+  cancelParamsSchema,
+  cancelResultSchema,
+  clientAccessPlugins,
+  clientCaptchaSolvers,
+  clientHooks,
+  diffParamsSchema,
+  diffRecordFiles,
+  diffResultSchema,
+  driverProtocolJsonSchema,
+  eventParamsSchema,
+  exportParamsSchema,
+  exportRecordFiles,
+  exportResultSchema,
+  finishedParamsSchema,
+  initializeParamsSchema,
+  initializeResultSchema,
+  openLineChannel,
+  probeParamsSchema,
+  probeResultSchema,
+  probeSite,
+  recordParamsSchema,
+  runParamsSchema,
+  runResultSchema,
+  runSessions,
+  serveDriver,
+  streamingSink,
+  validateParamsSchema,
+  validateRecipes,
+  validateResultSchema
+};
+//# sourceMappingURL=index.esm.js.map