@opencraw/driver 0.2.0 → 0.3.0

package/README.md

@@ -17,8 +17,8 @@ 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":1,"method":"initialize","params":{"clientName":"opencraw-python","clientVersion":"1.0.0","protocolVersion":"1.2.0"}}
+← {"jsonrpc":"2.0","id":1,"result":{"driverVersion":"0.2.0","protocolVersion":"1.2.0","methods":["initialize","validate","run","work","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",…}}}
@@ -34,6 +34,7 @@ npx opencraw-driver   # then write JSON-RPC lines to it
 | `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. |
+| `work` | client | Starts a worker pool and answers its `runId` at once. Its windows ask the client for items (`work.next`) and keep the steps marked `keep` between them; `windows` is a count or core's `WindowsPolicy`. Takes the same crawler fields as `run`. |
 | `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`. |
@@ -41,7 +42,9 @@ npx opencraw-driver   # then write JSON-RPC lines to it
 | `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. |
+| `finished` | driver | The run is over: its report (for `work`, the work report), or why it could not run. |
+| `work.next` | driver | A window wants an item: answer `{ "item": { "id", "vars", "recipe"? } }`, holding the answer until there is one, or `{ "item": null }` to end the work. An id already queued or running runs once. |
+| `work.done`, `work.failed` | driver | How an item ended: its report and records, or its outcome (`failure`, `neutral`). |
 | `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

package/dist/index.esm.js

@@ -1,10 +1,10 @@
 // src/server/serve-driver.use-case.ts
-import { once } from "node:events";
+import { once as once2 } 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 PROTOCOL_VERSION = "1.2.0";
 var recipeObject = z.record(z.string(), z.unknown());
 var coreObject = z.record(z.string(), z.unknown());
 var accessFields = {
@@ -54,6 +54,24 @@ var runParamsSchema = z.strictObject({
   ...accessFields
 });
 var runResultSchema = z.strictObject({ runId: z.string() });
+var windowsSchema = z.union([z.number().int().min(1).max(64), z.record(z.string(), z.unknown())]);
+var workParamsSchema = z.strictObject({
+  ...recipeSource,
+  only: z.array(z.string()).optional(),
+  out: z.string().optional(),
+  append: z.boolean().optional(),
+  browser: z.strictObject({ headless: z.boolean().optional(), executablePath: z.string().optional(), ignoreHTTPSErrors: z.boolean().optional() }).optional(),
+  hooks: z.array(z.string()).optional(),
+  captchaSolvers: z.array(z.string()).optional(),
+  ...accessFields,
+  windows: windowsSchema.optional()
+});
+var varValue = z.union([z.string(), z.number(), z.boolean()]);
+var workItemSchema = z.strictObject({
+  id: z.string().min(1),
+  vars: z.record(z.string(), varValue),
+  recipe: z.string().optional()
+});
 var cancelParamsSchema = z.strictObject({ runId: z.string() });
 var cancelResultSchema = z.strictObject({ cancelled: z.boolean() });
 var probeParamsSchema = z.strictObject({
@@ -101,11 +119,16 @@ var exportParamsSchema = z.strictObject({
 });
 var exportResultSchema = z.strictObject({ written: z.number(), location: z.string() });
 var shutdownResultSchema = z.strictObject({});
+var workNextParamsSchema = z.strictObject({ runId: z.string() });
+var workNextResultSchema = z.strictObject({ item: workItemSchema.nullable() });
+var workRecordSchema = z.strictObject({ key: z.string().nullable(), data: z.record(z.string(), z.unknown()) });
+var workDoneParamsSchema = z.strictObject({ runId: z.string(), item: workItemSchema, report: coreObject, records: z.array(workRecordSchema) });
+var workFailedParamsSchema = z.strictObject({ runId: z.string(), item: workItemSchema, report: coreObject, outcome: z.enum(["failure", "neutral"]) });
 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. */
+  /** The crawl report (`CrawlReport`), or for `work` the work report (`WorkReport`); 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()
@@ -113,18 +136,22 @@ var finishedParamsSchema = z.strictObject({
 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 }
+  "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 },
+  "work": { direction: "client-to-driver", params: workParamsSchema, 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 },
+  "work.next": { direction: "driver-to-client", params: workNextParamsSchema, result: workNextResultSchema },
+  "work.done": { direction: "driver-to-client", params: workDoneParamsSchema, result: void 0 },
+  "work.failed": { direction: "driver-to-client", params: workFailedParamsSchema, result: void 0 },
+  "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
@@ -219,6 +246,66 @@ async function resolveSiteAccess(params, runId, ask, env = process.env) {
   return { access, accessPlugins: clientAccessPlugins(params.accessPlugins ?? [], runId, ask) };
 }
 
+// src/work-bridge/client-work-source.client.ts
+import { once } from "node:events";
+function clientWorkSource(runId, ask, notify) {
+  const kept = [];
+  let ended = false;
+  const askClient = async () => {
+    const { item } = workNextResultSchema.parse(await ask("work.next", { runId }));
+    if (item === null) {
+      ended = true;
+      return void 0;
+    }
+    return item;
+  };
+  const keepLate = async (answer) => {
+    try {
+      const item = await answer;
+      if (item !== void 0) kept.push(item);
+    } catch {
+    }
+  };
+  return {
+    next: async (options) => {
+      const waiting = kept.shift();
+      if (waiting !== void 0) return waiting;
+      if (ended) return;
+      const answer = askClient();
+      const signal = options?.signal;
+      if (signal === void 0) return await answer;
+      signal.throwIfAborted();
+      const settled = new AbortController();
+      const answered = (async () => {
+        const item = await answer;
+        return { item };
+      })();
+      const retired = (async () => {
+        try {
+          await once(signal, "abort", { signal: settled.signal });
+          return "retired";
+        } catch {
+          return "answered";
+        }
+      })();
+      try {
+        const first = await Promise.race([answered, retired]);
+        if (first !== "retired" && first !== "answered") return first.item;
+        void keepLate(answer);
+        throw signal.reason instanceof Error ? signal.reason : new Error(String(signal.reason));
+      } finally {
+        settled.abort();
+      }
+    },
+    done: (item, report, records) => {
+      notify("work.done", { runId, item, report, records: records.map((record) => ({ key: record.key, data: record.data })) });
+    },
+    failed: (item, report, outcome) => {
+      notify("work.failed", { runId, item, report, outcome });
+    }
+  };
+}
+
 // src/session/recipe-loading.use-case.ts
 import { loadForRun } from "@opencraw/cli";
 import { hookUses, RecipeBindingError, RecipeValidationError } from "@opencraw/core";
@@ -260,41 +347,53 @@ function streamingSink() {
 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();
-    }
+  const crawlerFor = async (runId, params) => {
+    const { access, accessPlugins } = await resolveSiteAccess(params, runId, ask);
+    return 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 });
+      }
+    });
+  };
+  const track = (runId, crawler, crawling) => {
+    running.set(runId, crawler);
+    void (async () => {
+      try {
+        notify("finished", { runId, report: await crawling() });
+      } 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);
+      const crawler = await crawlerFor(runId, params);
+      track(runId, crawler, async () => await crawler.run(set));
+      return runId;
+    },
+    startWork: async (params) => {
+      const set = await loadRecipes(params);
+      const runId = `run-${next++}`;
+      const crawler = await crawlerFor(runId, params);
+      const windows = params.windows;
+      track(runId, crawler, async () => await crawler.work(set, clientWorkSource(runId, ask, notify), { windows }));
       return runId;
     },
     cancel: async (runId) => {
@@ -435,7 +534,7 @@ function openLineChannel(input, output, handle) {
 }
 
 // src/server/serve-driver.use-case.ts
-var METHODS = ["initialize", "validate", "run", "cancel", "probe", "diff", "export", "shutdown"];
+var METHODS = ["initialize", "validate", "run", "work", "cancel", "probe", "diff", "export", "shutdown"];
 var major = (version) => version.split(".", 1)[0];
 function parsed(schema, params) {
   const result = schema.safeParse(params ?? {});
@@ -458,6 +557,7 @@ async function serveDriver(input, output, identity) {
     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 === "work") return { runId: await sessions.startWork(parsed(workParamsSchema, 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));
@@ -469,7 +569,7 @@ async function serveDriver(input, output, identity) {
     return {};
   });
   const sessions = runSessions(channel.notify, channel.request);
-  await Promise.race([channel.closed, once(stopping.signal, "abort")]);
+  await Promise.race([channel.closed, once2(stopping.signal, "abort")]);
   await channel.drained();
   await sessions.closeAll();
 }
@@ -485,6 +585,7 @@ export {
   clientAccessPlugins,
   clientCaptchaSolvers,
   clientHooks,
+  clientWorkSource,
   diffParamsSchema,
   diffRecordFiles,
   diffResultSchema,
@@ -508,6 +609,12 @@ export {
   streamingSink,
   validateParamsSchema,
   validateRecipes,
-  validateResultSchema
+  validateResultSchema,
+  workDoneParamsSchema,
+  workFailedParamsSchema,
+  workItemSchema,
+  workNextParamsSchema,
+  workNextResultSchema,
+  workParamsSchema
 };
 //# sourceMappingURL=index.esm.js.map

package/dist/main.esm.js

@@ -6,12 +6,12 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
 // src/server/serve-driver.use-case.ts
-import { once } from "node:events";
+import { once as once2 } 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 PROTOCOL_VERSION = "1.2.0";
 var recipeObject = z.record(z.string(), z.unknown());
 var coreObject = z.record(z.string(), z.unknown());
 var accessFields = {
@@ -61,6 +61,24 @@ var runParamsSchema = z.strictObject({
   ...accessFields
 });
 var runResultSchema = z.strictObject({ runId: z.string() });
+var windowsSchema = z.union([z.number().int().min(1).max(64), z.record(z.string(), z.unknown())]);
+var workParamsSchema = z.strictObject({
+  ...recipeSource,
+  only: z.array(z.string()).optional(),
+  out: z.string().optional(),
+  append: z.boolean().optional(),
+  browser: z.strictObject({ headless: z.boolean().optional(), executablePath: z.string().optional(), ignoreHTTPSErrors: z.boolean().optional() }).optional(),
+  hooks: z.array(z.string()).optional(),
+  captchaSolvers: z.array(z.string()).optional(),
+  ...accessFields,
+  windows: windowsSchema.optional()
+});
+var varValue = z.union([z.string(), z.number(), z.boolean()]);
+var workItemSchema = z.strictObject({
+  id: z.string().min(1),
+  vars: z.record(z.string(), varValue),
+  recipe: z.string().optional()
+});
 var cancelParamsSchema = z.strictObject({ runId: z.string() });
 var cancelResultSchema = z.strictObject({ cancelled: z.boolean() });
 var probeParamsSchema = z.strictObject({
@@ -107,11 +125,16 @@ var exportParamsSchema = z.strictObject({
 });
 var exportResultSchema = z.strictObject({ written: z.number(), location: z.string() });
 var shutdownResultSchema = z.strictObject({});
+var workNextParamsSchema = z.strictObject({ runId: z.string() });
+var workNextResultSchema = z.strictObject({ item: workItemSchema.nullable() });
+var workRecordSchema = z.strictObject({ key: z.string().nullable(), data: z.record(z.string(), z.unknown()) });
+var workDoneParamsSchema = z.strictObject({ runId: z.string(), item: workItemSchema, report: coreObject, records: z.array(workRecordSchema) });
+var workFailedParamsSchema = z.strictObject({ runId: z.string(), item: workItemSchema, report: coreObject, outcome: z.enum(["failure", "neutral"]) });
 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. */
+  /** The crawl report (`CrawlReport`), or for `work` the work report (`WorkReport`); 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()
@@ -184,6 +207,66 @@ async function resolveSiteAccess(params, runId, ask, env = process.env) {
   return { access, accessPlugins: clientAccessPlugins(params.accessPlugins ?? [], runId, ask) };
 }
 
+// src/work-bridge/client-work-source.client.ts
+import { once } from "node:events";
+function clientWorkSource(runId, ask, notify) {
+  const kept = [];
+  let ended = false;
+  const askClient = async () => {
+    const { item } = workNextResultSchema.parse(await ask("work.next", { runId }));
+    if (item === null) {
+      ended = true;
+      return void 0;
+    }
+    return item;
+  };
+  const keepLate = async (answer) => {
+    try {
+      const item = await answer;
+      if (item !== void 0) kept.push(item);
+    } catch {
+    }
+  };
+  return {
+    next: async (options) => {
+      const waiting = kept.shift();
+      if (waiting !== void 0) return waiting;
+      if (ended) return;
+      const answer = askClient();
+      const signal = options?.signal;
+      if (signal === void 0) return await answer;
+      signal.throwIfAborted();
+      const settled = new AbortController();
+      const answered = (async () => {
+        const item = await answer;
+        return { item };
+      })();
+      const retired = (async () => {
+        try {
+          await once(signal, "abort", { signal: settled.signal });
+          return "retired";
+        } catch {
+          return "answered";
+        }
+      })();
+      try {
+        const first = await Promise.race([answered, retired]);
+        if (first !== "retired" && first !== "answered") return first.item;
+        void keepLate(answer);
+        throw signal.reason instanceof Error ? signal.reason : new Error(String(signal.reason));
+      } finally {
+        settled.abort();
+      }
+    },
+    done: (item, report, records) => {
+      notify("work.done", { runId, item, report, records: records.map((record) => ({ key: record.key, data: record.data })) });
+    },
+    failed: (item, report, outcome) => {
+      notify("work.failed", { runId, item, report, outcome });
+    }
+  };
+}
+
 // src/session/recipe-loading.use-case.ts
 import { loadForRun } from "@opencraw/cli";
 import { hookUses, RecipeBindingError, RecipeValidationError } from "@opencraw/core";
@@ -225,41 +308,53 @@ function streamingSink() {
 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();
-    }
+  const crawlerFor = async (runId, params) => {
+    const { access, accessPlugins } = await resolveSiteAccess(params, runId, ask);
+    return 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 });
+      }
+    });
+  };
+  const track = (runId, crawler, crawling) => {
+    running.set(runId, crawler);
+    void (async () => {
+      try {
+        notify("finished", { runId, report: await crawling() });
+      } 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);
+      const crawler = await crawlerFor(runId, params);
+      track(runId, crawler, async () => await crawler.run(set));
+      return runId;
+    },
+    startWork: async (params) => {
+      const set = await loadRecipes(params);
+      const runId = `run-${next++}`;
+      const crawler = await crawlerFor(runId, params);
+      const windows = params.windows;
+      track(runId, crawler, async () => await crawler.work(set, clientWorkSource(runId, ask, notify), { windows }));
       return runId;
     },
     cancel: async (runId) => {
@@ -400,7 +495,7 @@ function openLineChannel(input, output, handle) {
 }
 
 // src/server/serve-driver.use-case.ts
-var METHODS = ["initialize", "validate", "run", "cancel", "probe", "diff", "export", "shutdown"];
+var METHODS = ["initialize", "validate", "run", "work", "cancel", "probe", "diff", "export", "shutdown"];
 var major = (version) => version.split(".", 1)[0];
 function parsed(schema, params) {
   const result = schema.safeParse(params ?? {});
@@ -423,6 +518,7 @@ async function serveDriver(input, output, identity) {
     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 === "work") return { runId: await sessions.startWork(parsed(workParamsSchema, 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));
@@ -434,7 +530,7 @@ async function serveDriver(input, output, identity) {
     return {};
   });
   const sessions = runSessions(channel.notify, channel.request);
-  await Promise.race([channel.closed, once(stopping.signal, "abort")]);
+  await Promise.race([channel.closed, once2(stopping.signal, "abort")]);
   await channel.drained();
   await sessions.closeAll();
 }

package/dist/src/callout-bridge/client-hooks.client.d.ts

@@ -1,6 +1,8 @@
 import type { AccessPlugin, CalloutTransport, CaptchaSolver, HookMap } from '@opencraw/core';
 /** Sends one request to the client and waits for its answer: the channel's `request`. */
 export type AskClient = (method: string, params: unknown) => Promise<unknown>;
+/** Sends a notification to the client: the channel's `notify`. */
+export type NotifyClient = (method: string, params: unknown) => void;
 /**
  * A transport whose handler is the client: each call is a `callout` request carrying core's own
  * `CalloutRequest`, and the client answers with a `CalloutResponse`, so `pending` and idempotency keys

package/dist/src/callout-bridge/index.d.ts

@@ -1,3 +1,3 @@
 export { clientAccessPlugins, clientCaptchaSolvers, clientHooks, clientTransport } from './client-hooks.client.js';
-export type { AskClient } from './client-hooks.client.js';
+export type { AskClient, NotifyClient } from './client-hooks.client.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts

@@ -1,12 +1,14 @@
 export { serveDriver } from './server/index.js';
 export type { DriverIdentity } from './server/index.js';
-export { PROTOCOL_VERSION, MESSAGES, driverProtocolJsonSchema, initializeParamsSchema, initializeResultSchema, validateParamsSchema, validateResultSchema, runParamsSchema, runResultSchema, cancelParamsSchema, cancelResultSchema, eventParamsSchema, recordParamsSchema, finishedParamsSchema, calloutParamsSchema, calloutResultSchema, probeParamsSchema, probeResultSchema, diffParamsSchema, diffResultSchema, exportParamsSchema, exportResultSchema, } from './protocol/index.js';
-export type { InitializeParams, InitializeResult, ValidateParams, ValidateResult, RunParams, RunResult, CancelParams, CancelResult, EventParams, RecordParams, FinishedParams, CalloutParams, ProbeParams, DiffParams, DiffResult, ExportParams, ExportResult, } from './protocol/index.js';
+export { PROTOCOL_VERSION, MESSAGES, driverProtocolJsonSchema, initializeParamsSchema, initializeResultSchema, validateParamsSchema, validateResultSchema, runParamsSchema, runResultSchema, cancelParamsSchema, cancelResultSchema, eventParamsSchema, recordParamsSchema, finishedParamsSchema, calloutParamsSchema, calloutResultSchema, probeParamsSchema, probeResultSchema, diffParamsSchema, diffResultSchema, exportParamsSchema, exportResultSchema, workParamsSchema, workItemSchema, workNextParamsSchema, workNextResultSchema, workDoneParamsSchema, workFailedParamsSchema, } from './protocol/index.js';
+export type { InitializeParams, InitializeResult, ValidateParams, ValidateResult, RunParams, RunResult, CancelParams, CancelResult, EventParams, RecordParams, FinishedParams, CalloutParams, ProbeParams, DiffParams, DiffResult, ExportParams, ExportResult, WorkParams, WorkItemMessage, WorkNextResult, WorkDoneParams, WorkFailedParams, } from './protocol/index.js';
 export { openLineChannel, RPC_ERRORS, RpcFailure } from './transport/index.js';
 export type { LineChannel, RequestHandler, RpcError, RpcMessage } from './transport/index.js';
 export { runSessions, validateRecipes, streamingSink } from './session/index.js';
-export type { RunSessions, NotifyClient } from './session/index.js';
+export type { RunSessions } from './session/index.js';
 export { clientHooks, clientCaptchaSolvers, clientAccessPlugins } from './callout-bridge/index.js';
+export type { AskClient, NotifyClient } from './callout-bridge/index.js';
+export { clientWorkSource } from './work-bridge/index.js';
 export { probeSite } from './site-probe/index.js';
 export { diffRecordFiles, exportRecordFiles } from './record-files/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/src/protocol/driver-message.contract.d.ts

@@ -3,7 +3,7 @@ import { z } from 'zod';
  * The driver protocol's version, separate from the package's: a client pins a major and the driver refuses
  * another. Additions (methods, optional fields) raise the minor; anything a client could break on, the major.
  */
-export declare const PROTOCOL_VERSION = "1.1.0";
+export declare const PROTOCOL_VERSION = "1.2.0";
 export declare const initializeParamsSchema: z.ZodObject<{
     clientName: z.ZodString;
     clientVersion: z.ZodString;
@@ -58,6 +58,31 @@ export type RunParams = z.infer<typeof runParamsSchema>;
 export declare const runResultSchema: z.ZodObject<{
     runId: z.ZodString;
 }, z.core.$strict>;
+export declare const workParamsSchema: z.ZodObject<{
+    accessConfig: z.ZodOptional<z.ZodString>;
+    access: z.ZodOptional<z.ZodString>;
+    accessPlugins: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    paths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    recipes: z.ZodOptional<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    only: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    out: z.ZodOptional<z.ZodString>;
+    append: z.ZodOptional<z.ZodBoolean>;
+    browser: z.ZodOptional<z.ZodObject<{
+        headless: z.ZodOptional<z.ZodBoolean>;
+        executablePath: z.ZodOptional<z.ZodString>;
+        ignoreHTTPSErrors: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>;
+    hooks: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    captchaSolvers: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    windows: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>;
+}, z.core.$strict>;
+export type WorkParams = z.infer<typeof workParamsSchema>;
+export declare const workItemSchema: z.ZodObject<{
+    id: z.ZodString;
+    vars: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+    recipe: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type WorkItemMessage = z.infer<typeof workItemSchema>;
 export type RunResult = z.infer<typeof runResultSchema>;
 export declare const cancelParamsSchema: z.ZodObject<{
     runId: z.ZodString;
@@ -114,6 +139,48 @@ export declare const exportResultSchema: z.ZodObject<{
 }, z.core.$strict>;
 export type ExportResult = z.infer<typeof exportResultSchema>;
 export declare const shutdownResultSchema: z.ZodObject<{}, z.core.$strict>;
+/** A window wants its next item. The client may hold the answer until it has one; `null` ends the work. */
+export declare const workNextParamsSchema: z.ZodObject<{
+    runId: z.ZodString;
+}, z.core.$strict>;
+export declare const workNextResultSchema: z.ZodObject<{
+    item: z.ZodNullable<z.ZodObject<{
+        id: z.ZodString;
+        vars: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+        recipe: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type WorkNextResult = z.infer<typeof workNextResultSchema>;
+/** An item succeeded: its report (`RecipeReport`) and its records. */
+export declare const workDoneParamsSchema: z.ZodObject<{
+    runId: z.ZodString;
+    item: z.ZodObject<{
+        id: z.ZodString;
+        vars: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+        recipe: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    report: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    records: z.ZodArray<z.ZodObject<{
+        key: z.ZodNullable<z.ZodString>;
+        data: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type WorkDoneParams = z.infer<typeof workDoneParamsSchema>;
+/** An item failed (`failure`) or came out neither way (`neutral`, such as a captcha it could not pass). */
+export declare const workFailedParamsSchema: z.ZodObject<{
+    runId: z.ZodString;
+    item: z.ZodObject<{
+        id: z.ZodString;
+        vars: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+        recipe: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    report: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    outcome: z.ZodEnum<{
+        failure: "failure";
+        neutral: "neutral";
+    }>;
+}, z.core.$strict>;
+export type WorkFailedParams = z.infer<typeof workFailedParamsSchema>;
 /** Every crawl event, as core reports it (`CrawlEvent`); its shape is core's, versioned with core. */
 export declare const eventParamsSchema: z.ZodObject<{
     runId: z.ZodString;
@@ -226,6 +293,30 @@ export declare const MESSAGES: {
             runId: z.ZodString;
         }, z.core.$strict>;
     };
+    readonly work: {
+        readonly direction: 'client-to-driver';
+        readonly params: z.ZodObject<{
+            accessConfig: z.ZodOptional<z.ZodString>;
+            access: z.ZodOptional<z.ZodString>;
+            accessPlugins: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            paths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            recipes: z.ZodOptional<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+            only: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            out: z.ZodOptional<z.ZodString>;
+            append: z.ZodOptional<z.ZodBoolean>;
+            browser: z.ZodOptional<z.ZodObject<{
+                headless: z.ZodOptional<z.ZodBoolean>;
+                executablePath: z.ZodOptional<z.ZodString>;
+                ignoreHTTPSErrors: z.ZodOptional<z.ZodBoolean>;
+            }, z.core.$strict>>;
+            hooks: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            captchaSolvers: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            windows: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>;
+        }, z.core.$strict>;
+        readonly result: z.ZodObject<{
+            runId: z.ZodString;
+        }, z.core.$strict>;
+    };
     readonly cancel: {
         readonly direction: 'client-to-driver';
         readonly params: z.ZodObject<{
@@ -323,6 +414,53 @@ export declare const MESSAGES: {
             retryAfterMs: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strict>], "status">;
     };
+    readonly 'work.next': {
+        readonly direction: 'driver-to-client';
+        readonly params: z.ZodObject<{
+            runId: z.ZodString;
+        }, z.core.$strict>;
+        readonly result: z.ZodObject<{
+            item: z.ZodNullable<z.ZodObject<{
+                id: z.ZodString;
+                vars: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+                recipe: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>;
+    };
+    readonly 'work.done': {
+        readonly direction: 'driver-to-client';
+        readonly params: z.ZodObject<{
+            runId: z.ZodString;
+            item: z.ZodObject<{
+                id: z.ZodString;
+                vars: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+                recipe: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>;
+            report: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+            records: z.ZodArray<z.ZodObject<{
+                key: z.ZodNullable<z.ZodString>;
+                data: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>;
+        readonly result: undefined;
+    };
+    readonly 'work.failed': {
+        readonly direction: 'driver-to-client';
+        readonly params: z.ZodObject<{
+            runId: z.ZodString;
+            item: z.ZodObject<{
+                id: z.ZodString;
+                vars: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+                recipe: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>;
+            report: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+            outcome: z.ZodEnum<{
+                failure: "failure";
+                neutral: "neutral";
+            }>;
+        }, z.core.$strict>;
+        readonly result: undefined;
+    };
     readonly event: {
         readonly direction: 'driver-to-client';
         readonly params: z.ZodObject<{

package/dist/src/protocol/index.d.ts

@@ -1,4 +1,4 @@
-export { PROTOCOL_VERSION, MESSAGES, initializeParamsSchema, initializeResultSchema, validateParamsSchema, validateResultSchema, runParamsSchema, runResultSchema, cancelParamsSchema, cancelResultSchema, shutdownResultSchema, eventParamsSchema, recordParamsSchema, finishedParamsSchema, calloutParamsSchema, calloutResultSchema, probeParamsSchema, probeResultSchema, diffParamsSchema, diffResultSchema, exportParamsSchema, exportResultSchema, } from './driver-message.contract.js';
-export type { InitializeParams, InitializeResult, ValidateParams, ValidateResult, RunParams, RunResult, CancelParams, CancelResult, EventParams, RecordParams, FinishedParams, CalloutParams, ProbeParams, DiffParams, DiffResult, ExportParams, ExportResult, } from './driver-message.contract.js';
+export { PROTOCOL_VERSION, MESSAGES, initializeParamsSchema, initializeResultSchema, validateParamsSchema, validateResultSchema, runParamsSchema, runResultSchema, cancelParamsSchema, cancelResultSchema, shutdownResultSchema, eventParamsSchema, recordParamsSchema, finishedParamsSchema, calloutParamsSchema, calloutResultSchema, probeParamsSchema, probeResultSchema, diffParamsSchema, diffResultSchema, exportParamsSchema, exportResultSchema, workParamsSchema, workItemSchema, workNextParamsSchema, workNextResultSchema, workDoneParamsSchema, workFailedParamsSchema, } from './driver-message.contract.js';
+export type { InitializeParams, InitializeResult, ValidateParams, ValidateResult, RunParams, RunResult, CancelParams, CancelResult, EventParams, RecordParams, FinishedParams, CalloutParams, ProbeParams, DiffParams, DiffResult, ExportParams, ExportResult, WorkParams, WorkItemMessage, WorkNextResult, WorkDoneParams, WorkFailedParams, } from './driver-message.contract.js';
 export { driverProtocolJsonSchema } from './driver-json-schema.mapper.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/src/session/index.d.ts

@@ -1,5 +1,5 @@
 export { runSessions } from './run-session.use-case.js';
-export type { NotifyClient, RunSessions } from './run-session.use-case.js';
+export type { RunSessions } from './run-session.use-case.js';
 export { validateRecipes, hooksOf, loadRecipes, sourceOf } from './recipe-loading.use-case.js';
 export { streamingSink } from './streaming-sink.repository.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/src/session/run-session.use-case.d.ts

@@ -1,23 +1,23 @@
-import type { AskClient } from '../callout-bridge/index.js';
-import type { RunParams } from '../protocol/index.js';
-/** Sends a notification to the client. */
-export type NotifyClient = (method: string, params: unknown) => void;
+import type { AskClient, NotifyClient } from '../callout-bridge/index.js';
+import type { RunParams, WorkParams } from '../protocol/index.js';
 /** The runs a driver has going, by id, so `cancel` can reach them and `shutdown` close them all. */
 export interface RunSessions {
     start: (params: RunParams) => Promise<string>;
+    startWork: (params: WorkParams) => Promise<string>;
     cancel: (runId: string) => Promise<boolean>;
     closeAll: () => Promise<void>;
 }
 /**
- * Starts and tracks runs. `start` loads and binds the recipes (a bad recipe fails the `run` request
- * itself, with its problems), answers with a run id at once, and crawls in the background: every crawl
- * event goes to the client as an `event` notification, every record as a `record` one unless `out`
- * names a file, and the end as `finished` with the report. A hook the client serves is asked back with
- * a `callout` request, and so are the captcha solvers and access plugins it serves. `cancel` closes the run's crawler, which stops its recipes; the run still ends
- * with `finished`.
+ * Starts and tracks runs and worker pools. `start` and `startWork` load and bind the recipes (a bad
+ * recipe fails the request itself, with its problems), answer with a run id at once, and crawl in the
+ * background: every crawl event goes to the client as an `event` notification, every record as a
+ * `record` one unless `out` names a file, and the end as `finished` with the report. A hook the client
+ * serves is asked back with a `callout` request, and so are the captcha solvers and access plugins it
+ * serves; a worker pool asks the client for its items (`work.next`). `cancel` closes the run's crawler,
+ * which stops its recipes; the run still ends with `finished`.
  *
  * @param notify - The channel's notify.
- * @param ask - The channel's request, for callouts.
+ * @param ask - The channel's request, for callouts and work.
  * @returns The sessions.
  */
 export declare function runSessions(notify: NotifyClient, ask: AskClient): RunSessions;

package/dist/src/work-bridge/client-work-source.client.d.ts

@@ -0,0 +1,17 @@
+import type { WorkSource } from '@opencraw/core';
+import type { AskClient, NotifyClient } from '../callout-bridge/index.js';
+/**
+ * A `WorkSource` whose items come from the client: each window that wants work sends a `work.next`
+ * request, which the client may hold until it has an item, and an answer of `null` ends the work. Each
+ * item's end goes back as `work.done` (with its records) or `work.failed`.
+ *
+ * A window that retires while its request is out (core aborts its `next`) still gets an answer later;
+ * that item is kept and handed to the next window that asks, so nothing the client sent is lost.
+ *
+ * @param runId - The work's run id, sent with every message.
+ * @param ask - The channel's request.
+ * @param notify - The channel's notify.
+ * @returns The source for `crawler.work`.
+ */
+export declare function clientWorkSource(runId: string, ask: AskClient, notify: NotifyClient): WorkSource;
+//# sourceMappingURL=client-work-source.client.d.ts.map

package/dist/src/work-bridge/index.d.ts

@@ -0,0 +1,2 @@
+export { clientWorkSource } from './client-work-source.client.js';
+//# sourceMappingURL=index.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opencraw/driver",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "OpenCraw's driver: the engine over JSON-RPC on stdio, for clients in other languages",
   "license": "MIT",
   "type": "module",
@@ -40,8 +40,8 @@
     "schemas": "node tools/emit-protocol-schema.mjs"
   },
   "dependencies": {
-    "@opencraw/cli": "^0.1.56",
-    "@opencraw/core": "^0.3.0",
+    "@opencraw/cli": "^0.0.1",
+    "@opencraw/core": "^0.0.1",
     "zod": "^4.6.5"
   }
 }

package/schemas/driver-protocol.schema.json

@@ -3,7 +3,7 @@
   "$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": "1.1.0",
+  "protocolVersion": "1.2.0",
   "methods": {
     "initialize": {
       "direction": "client-to-driver",
@@ -32,6 +32,15 @@
         "$ref": "#/$defs/run.result"
       }
     },
+    "work": {
+      "direction": "client-to-driver",
+      "params": {
+        "$ref": "#/$defs/work.params"
+      },
+      "result": {
+        "$ref": "#/$defs/work.result"
+      }
+    },
     "cancel": {
       "direction": "client-to-driver",
       "params": {
@@ -83,6 +92,27 @@
         "$ref": "#/$defs/callout.result"
       }
     },
+    "work.next": {
+      "direction": "driver-to-client",
+      "params": {
+        "$ref": "#/$defs/work.next.params"
+      },
+      "result": {
+        "$ref": "#/$defs/work.next.result"
+      }
+    },
+    "work.done": {
+      "direction": "driver-to-client",
+      "params": {
+        "$ref": "#/$defs/work.done.params"
+      }
+    },
+    "work.failed": {
+      "direction": "driver-to-client",
+      "params": {
+        "$ref": "#/$defs/work.failed.params"
+      }
+    },
     "event": {
       "direction": "driver-to-client",
       "params": {
@@ -335,6 +365,111 @@
       ],
       "additionalProperties": false
     },
+    "work.params": {
+      "$schema": "https://json-schema.org/draft/2020-12/schema",
+      "type": "object",
+      "properties": {
+        "paths": {
+          "minItems": 1,
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "recipes": {
+          "minItems": 1,
+          "type": "array",
+          "items": {
+            "type": "object",
+            "propertyNames": {
+              "type": "string"
+            },
+            "additionalProperties": {}
+          }
+        },
+        "only": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "out": {
+          "type": "string"
+        },
+        "append": {
+          "type": "boolean"
+        },
+        "browser": {
+          "type": "object",
+          "properties": {
+            "headless": {
+              "type": "boolean"
+            },
+            "executablePath": {
+              "type": "string"
+            },
+            "ignoreHTTPSErrors": {
+              "type": "boolean"
+            }
+          },
+          "additionalProperties": false
+        },
+        "hooks": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "captchaSolvers": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "accessConfig": {
+          "type": "string"
+        },
+        "access": {
+          "type": "string"
+        },
+        "accessPlugins": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "windows": {
+          "anyOf": [
+            {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 64
+            },
+            {
+              "type": "object",
+              "propertyNames": {
+                "type": "string"
+              },
+              "additionalProperties": {}
+            }
+          ]
+        }
+      },
+      "additionalProperties": false
+    },
+    "work.result": {
+      "$schema": "https://json-schema.org/draft/2020-12/schema",
+      "type": "object",
+      "properties": {
+        "runId": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "runId"
+      ],
+      "additionalProperties": false
+    },
     "cancel.params": {
       "$schema": "https://json-schema.org/draft/2020-12/schema",
       "type": "object",
@@ -690,6 +825,205 @@
         }
       ]
     },
+    "work.next.params": {
+      "$schema": "https://json-schema.org/draft/2020-12/schema",
+      "type": "object",
+      "properties": {
+        "runId": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "runId"
+      ],
+      "additionalProperties": false
+    },
+    "work.next.result": {
+      "$schema": "https://json-schema.org/draft/2020-12/schema",
+      "type": "object",
+      "properties": {
+        "item": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "id": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "vars": {
+                  "type": "object",
+                  "propertyNames": {
+                    "type": "string"
+                  },
+                  "additionalProperties": {
+                    "type": [
+                      "string",
+                      "number",
+                      "boolean"
+                    ]
+                  }
+                },
+                "recipe": {
+                  "type": "string"
+                }
+              },
+              "required": [
+                "id",
+                "vars"
+              ],
+              "additionalProperties": false
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      },
+      "required": [
+        "item"
+      ],
+      "additionalProperties": false
+    },
+    "work.done.params": {
+      "$schema": "https://json-schema.org/draft/2020-12/schema",
+      "type": "object",
+      "properties": {
+        "runId": {
+          "type": "string"
+        },
+        "item": {
+          "type": "object",
+          "properties": {
+            "id": {
+              "type": "string",
+              "minLength": 1
+            },
+            "vars": {
+              "type": "object",
+              "propertyNames": {
+                "type": "string"
+              },
+              "additionalProperties": {
+                "type": [
+                  "string",
+                  "number",
+                  "boolean"
+                ]
+              }
+            },
+            "recipe": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "id",
+            "vars"
+          ],
+          "additionalProperties": false
+        },
+        "report": {
+          "type": "object",
+          "propertyNames": {
+            "type": "string"
+          },
+          "additionalProperties": {}
+        },
+        "records": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "key": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "data": {
+                "type": "object",
+                "propertyNames": {
+                  "type": "string"
+                },
+                "additionalProperties": {}
+              }
+            },
+            "required": [
+              "key",
+              "data"
+            ],
+            "additionalProperties": false
+          }
+        }
+      },
+      "required": [
+        "runId",
+        "item",
+        "report",
+        "records"
+      ],
+      "additionalProperties": false
+    },
+    "work.failed.params": {
+      "$schema": "https://json-schema.org/draft/2020-12/schema",
+      "type": "object",
+      "properties": {
+        "runId": {
+          "type": "string"
+        },
+        "item": {
+          "type": "object",
+          "properties": {
+            "id": {
+              "type": "string",
+              "minLength": 1
+            },
+            "vars": {
+              "type": "object",
+              "propertyNames": {
+                "type": "string"
+              },
+              "additionalProperties": {
+                "type": [
+                  "string",
+                  "number",
+                  "boolean"
+                ]
+              }
+            },
+            "recipe": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "id",
+            "vars"
+          ],
+          "additionalProperties": false
+        },
+        "report": {
+          "type": "object",
+          "propertyNames": {
+            "type": "string"
+          },
+          "additionalProperties": {}
+        },
+        "outcome": {
+          "type": "string",
+          "enum": [
+            "failure",
+            "neutral"
+          ]
+        }
+      },
+      "required": [
+        "runId",
+        "item",
+        "report",
+        "outcome"
+      ],
+      "additionalProperties": false
+    },
     "event.params": {
       "$schema": "https://json-schema.org/draft/2020-12/schema",
       "type": "object",