cdp-toolkit 1.9.0 → 1.9.4

package/src/tools/recorder.ts

@@ -38,11 +38,47 @@
  * reload-driven via `captureWindow`. `startRecorder` resolves only AFTER the CDP
  * domains are enabled, so a caller can trigger navigation/reload immediately and
  * be sure events are caught.
+ *
+ * SERVICE WORKERS (1.9.1)
+ * -----------------------
+ * A `worker:<substring>` (or bare worker-id) target records the same two domains
+ * over the worker's OWN connection, which is the whole point of the feature: the
+ * outbound fetch an MV3 background worker makes is a Network event on that
+ * session and nothing else can see it reliably. Measured on Chrome 151.0.7922.109
+ * before any of this was written:
+ *
+ *   - `Network.enable` succeeds on a direct worker connection and
+ *     requestWillBeSent / responseReceived / loadingFinished all arrive for a
+ *     fetch the worker performs; `Network.getResponseBody` serves its body.
+ *   - `Runtime.consoleAPICalled` delivers the worker's console.log on the same
+ *     session. (`Log.enable` also succeeds but emits nothing there.)
+ *   - `Page.enable` and `Page.reload` DO NOT EXIST on a worker session: both
+ *     answer `-32601 ... wasn't found`. So a worker capture window cannot be
+ *     reload-driven, and this module skips both instead of catching a failure —
+ *     the window simply LISTENS for durationMs while the worker runs.
+ *   - A held session SUPPRESSES MV3 idle-eviction (measured: alive and still
+ *     emitting Network events after 60s held; evicted ~30s after the detach). A
+ *     recording therefore keeps the worker alive for exactly as long as it runs,
+ *     which is a documented side effect of these tools, not an accident.
+ *   - An evicted worker that is woken has ALREADY run its top-level code by the
+ *     time the recorder attaches, so a request the worker makes at startup can be
+ *     missed. Trigger the work you want to observe during the window.
  */
 import { mkdir, appendFile, writeFile, copyFile } from "node:fs/promises";
-import { openPage, resolveTarget } from "../client.ts";
+import { CdpError, listTargets, openPage, resolveTarget } from "../client.ts";
 import type { CdpConnection } from "../client.ts";
+import { resolveWorkerSelector } from "../cdp/workers.ts";
 import type { Target, TargetSelector } from "../types.ts";
+import {
+  isWorkerSelector,
+  isWorkerTargetType,
+  resolveWorkerTargets,
+  workerAmbiguityMessage,
+  workerBufferReadMissMessage,
+  workerNeedle,
+  workerWakeMisuseMessage,
+  WORKER_EMPTY_NEEDLE_MESSAGE,
+} from "../workers.ts";
 
 /** Artifact / buffer directory (shared with the rest of the toolkit). */
 export const ARTIFACT_DIR = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
@@ -62,6 +98,52 @@ function delay(ms: number): Promise<void> {
   return new Promise((r) => setTimeout(r, ms));
 }
 
+/* ------------------------- worker targets (1.9.1) ------------------------- */
+
+/**
+ * Resolve the target for a console/network call, which is the ONE place the
+ * three reader tools differ from every other tool: a capture may start a
+ * stopped worker, a read never may.
+ *
+ * `capture: true`  — a recording is about to be made, so a `worker:` selector
+ *   goes through the waking resolver (Chrome-only, `cdp/workers.ts`), default
+ *   wake:true, exactly like evaluate_script.
+ * `capture: false` — an existing buffer is about to be read, so the same
+ *   selector resolves against the RUNNING workers only, and a miss gets the
+ *   read-path message rather than a promise that waking would help (it would
+ *   not: the buffer is keyed by a target id the restart re-mints).
+ *
+ * Non-worker selectors are untouched: they go through client.ts's resolveTarget,
+ * lease gate and all.
+ */
+export async function resolveRecorderTarget(
+  target: TargetSelector,
+  opts: { capture: boolean; wake?: boolean },
+): Promise<Target> {
+  if (!isWorkerSelector(target)) return resolveTarget(target);
+  if (opts.capture) return resolveWorkerSelector(target, { wake: opts.wake ?? true });
+
+  const needle = workerNeedle(target);
+  if (needle === "") throw new CdpError(WORKER_EMPTY_NEEDLE_MESSAGE);
+  const { matches, liveWorkers } = resolveWorkerTargets(await listTargets(), needle);
+  if (matches.length > 1) throw new CdpError(workerAmbiguityMessage(needle, matches));
+  if (matches.length === 1) return matches[0]!;
+  throw new CdpError(workerBufferReadMissMessage(needle, liveWorkers));
+}
+
+/**
+ * Validate `wake` for the three reader tools. It is REFUSED where it would do
+ * nothing rather than accepted and ignored — the evaluate_script precedent: an
+ * accepted argument reads as "this call will wake something", and a caller who
+ * is wrong about that never finds out.
+ */
+export function assertWakeApplies(target: TargetSelector, wake: boolean | undefined, capture: boolean): void {
+  if (wake === undefined) return;
+  if (typeof wake !== "boolean") throw new CdpError("'wake' must be a boolean");
+  if (!isWorkerSelector(target)) throw new CdpError(workerWakeMisuseMessage("not-a-worker-selector"));
+  if (!capture) throw new CdpError(workerWakeMisuseMessage("read-only-call"));
+}
+
 /** Network CDP events we persist. */
 const NETWORK_EVENTS = [
   "Network.requestWillBeSent",
@@ -186,11 +268,16 @@ export async function startRecorder(target: TargetSelector, opts: RecorderOption
 }
 
 /**
- * One-shot reload capture used by the console/network tools. Records BOTH
- * domains into a unique per-capture file, reloads the page, waits `durationMs`,
- * and (on stop) publishes the capture as the target's shared "latest" buffer.
- * The returned handle keeps the connection open until `stop()`, so a caller can
- * `flush()` then fetch response bodies before closing.
+ * One-shot capture used by the console/network tools. Records BOTH domains into
+ * a unique per-capture file, waits `durationMs`, and (on stop) publishes the
+ * capture as the target's shared "latest" buffer. The returned handle keeps the
+ * connection open until `stop()`, so a caller can `flush()` then fetch response
+ * bodies before closing.
+ *
+ * A PAGE window reloads to generate the traffic. A WORKER window does not (and
+ * cannot: `Page.*` is absent on a worker session) — it listens while the worker
+ * runs, and the session it holds keeps that worker from being idle-evicted for
+ * the length of the window.
  */
 export interface CaptureWindow {
   /** The unique per-capture buffer file (read this for isolated results). */
@@ -199,6 +286,8 @@ export interface CaptureWindow {
   conn: CdpConnection;
   /** Resolved target identity. */
   resolved: { id: string; url: string; title: string };
+  /** How the window was driven: "reload" for a page, "listen" for a worker. */
+  mode: "reload" | "listen";
   /** Buffer-write failure count. */
   droppedWrites(): number;
   /** Await in-flight appends without closing (bodies stay fetchable). */
@@ -210,9 +299,15 @@ export interface CaptureWindow {
 export async function captureWindow(
   target: TargetSelector,
   durationMs: number,
-  opts: { timeoutMs?: number } = {},
+  opts: { timeoutMs?: number; wake?: boolean } = {},
 ): Promise<CaptureWindow> {
-  const resolved = await resolveTarget(target);
+  const resolved = await resolveRecorderTarget(target, { capture: true, wake: opts.wake });
+  // A WORKER window is "listen", not "reload": Page.enable/Page.reload answer
+  // -32601 on a worker session (measured), and there is nothing to reload
+  // anyway — the caller triggers the worker's work during the window. Keyed off
+  // the RESOLVED TYPE rather than the selector shape, so a bare worker target id
+  // takes the same branch as `worker:<substring>`.
+  const isWorker = isWorkerTargetType(resolved.type);
   const captureId = `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
   const file = captureFile(resolved.id, captureId);
   // Record both domains so neither tool clobbers the other's history.
@@ -223,13 +318,16 @@ export async function captureWindow(
     file,
     timeoutMs: opts.timeoutMs,
   });
-  await rec.conn.send("Page.enable");
-  await rec.conn.send("Page.reload", { ignoreCache: false });
+  if (!isWorker) {
+    await rec.conn.send("Page.enable");
+    await rec.conn.send("Page.reload", { ignoreCache: false });
+  }
   await delay(durationMs);
   return {
     file: rec.file,
     conn: rec.conn,
     resolved: { id: rec.target.id, url: rec.target.url, title: rec.target.title },
+    mode: isWorker ? "listen" : "reload",
     droppedWrites: rec.droppedWrites,
     flush: () => rec.flush(),
     async stop(): Promise<void> {
@@ -257,6 +355,8 @@ export async function captureWindow(
  *   Runtime.exceptionThrown (event)
  *   Log.enable
  *   Log.entryAdded (event)
+ *   Page.enable / Page.reload   (PAGE capture windows only: absent on a worker)
+ *   ServiceWorker.enable / .startWorker  (via cdp/workers.ts, worker wake only)
  *
  * Parity gaps vs chrome-devtools-mcp:
  *   - Buffering is to a per-target JSONL file on disk, not an in-memory ring; the

package/src/types.ts

@@ -55,12 +55,14 @@ export interface CdpEvent<P = Record<string, unknown>> {
  *     URL contains the substring (an MV3 extension's background worker is
  *     `chrome-extension://<id>/<script>`, so both the extension id and the
  *     script name match). NOT UNIVERSAL, unlike every arm above it: resolved
- *     only by Chrome's pickTarget (this file's resolveTarget), accepted only by
- *     evaluate_script, refused with a capability error on Firefox and by the
- *     page-only resolvers. It reads the UNFILTERED target listing, because a
- *     worker is not a page target — and a worker that is idle-evicted is in no
- *     listing at all, which is what evaluate_script's `wake` exists for. See
- *     src/workers.ts and src/cdp/workers.ts.
+ *     only by Chrome's pickTarget (client.ts's resolveTarget), accepted by the
+ *     four tools in WORKER_CAPABLE_TOOLS (evaluate_script, which evaluates in a
+ *     worker, plus list_network_requests / get_network_request /
+ *     list_console_messages, which record one), refused with a capability error
+ *     on Firefox and by the page-only resolvers. It reads the UNFILTERED target
+ *     listing, because a worker is not a page target — and a worker that is
+ *     idle-evicted is in no listing at all, which is what `wake` exists for.
+ *     See src/workers.ts and src/cdp/workers.ts.
  */
 export type TargetSelector = string | undefined;
 

package/src/workers.ts

@@ -36,6 +36,25 @@
 /** Selector prefix owned by this arm. */
 export const WORKER_SELECTOR_PREFIX = "worker:";
 
+/**
+ * THE ALLOWLIST. Every tool that accepts a `worker:<substring>` target, and the
+ * single source of truth for it: the refusal messages below are built from this
+ * list, and test/manifest-grammar-drift.test.ts asserts that no OTHER tool's
+ * manifest description advertises the arm. Adding a fifth tool is therefore one
+ * deliberate edit here, not a description that quietly grew the grammar.
+ *
+ * 1.9.0 shipped one entry (evaluate_script). 1.9.1 adds the three console/network
+ * readers, because the request an MV3 background worker makes to a real backend
+ * is exactly what a caller needs to see and `Runtime.evaluate`-based
+ * interception cannot reliably show them (see the tools' descriptions).
+ */
+export const WORKER_CAPABLE_TOOLS = [
+  "evaluate_script",
+  "list_network_requests",
+  "get_network_request",
+  "list_console_messages",
+] as const;
+
 /**
  * CDP target types this arm resolves. `service_worker` is the MV3 case that
  * motivated the feature; `shared_worker` is included because it presents the
@@ -94,21 +113,64 @@ export const WORKER_EMPTY_NEEDLE_MESSAGE =
 
 /**
  * The Firefox refusal. A PARAM-level gap, exactly like drag's mode:'html5'
- * (see resolveDragMode): evaluate_script stays in tools/list on Firefox because
- * every page selector still works there, and only this one arm is refused.
- * Naming the reason matters — WebDriver BiDi has no extension-worker target
- * concept to map onto, so this is a protocol gap, not an unimplemented to-do.
+ * (see resolveDragMode): the worker-capable tools stay in tools/list on Firefox
+ * because every page selector still works there, and only this one arm is
+ * refused. Naming the reason matters — WebDriver BiDi has no extension-worker
+ * target concept to map onto, so this is a protocol gap, not an unimplemented
+ * to-do.
  */
 export const WORKER_SELECTOR_UNSUPPORTED_MESSAGE =
   "target 'worker:<substring>' selects a service/shared worker, which this backend cannot address " +
   "(WebDriver BiDi has no extension service-worker target; Capability 'worker.targets' is Chrome-only). " +
-  "Use --browser chrome to evaluate in an extension's background worker.";
+  "Use --browser chrome to evaluate in, or record console/network from, an extension's background worker.";
 
 /** Refusal from the page-only resolvers (close_page / select_page / release_page). */
 export const WORKER_SELECTOR_PAGE_ONLY_MESSAGE =
   "target 'worker:<substring>' selects a service/shared worker, and this tool is page-only " +
-  "(closing, selecting or releasing a worker is meaningless). evaluate_script is the one tool that " +
-  "accepts a worker: target.";
+  "(closing, selecting or releasing a worker is meaningless). The tools that accept a worker: target are " +
+  `${WORKER_CAPABLE_TOOLS.join(", ")}.`;
+
+/**
+ * WHY `wake` IS REFUSED RATHER THAN IGNORED ON THE READ PATH, and why a bare id
+ * can never be woken. Measured for 1.9.1 on Chrome 151.0.7922.109: a worker that
+ * idle-evicts and is then restarted comes back under a DIFFERENT target id
+ * (probed: C43F0A18... -> 1F7D3C59... for the same extension). The recorder keys
+ * its buffer file by target id, so waking a worker on a read gives you a live
+ * worker whose buffer is empty — "0 requests" for a capture that really did
+ * record some, which is a lie shaped like an answer. A wake therefore only makes
+ * sense when a capture is being STARTED, and only from a `worker:<substring>`
+ * selector, since the id of an evicted worker no longer exists to name.
+ */
+export function workerWakeMisuseMessage(kind: "not-a-worker-selector" | "read-only-call"): string {
+  if (kind === "not-a-worker-selector") {
+    return (
+      "'wake' only applies to a target of the form 'worker:<substring>'. A page is never asleep, and a bare " +
+      "worker target id cannot be woken either: Chrome destroys the target when an MV3 worker is evicted and " +
+      "mints a NEW id when it restarts, so only the url-substring form can name a worker that is not running."
+    );
+  }
+  return (
+    "'wake' only applies when a capture is being started (reload:true, or includeBody with url). Reading an " +
+    "existing buffer cannot use a woken worker: a restarted MV3 worker gets a NEW target id, and the buffer is " +
+    "keyed by id, so the wake would hand back an empty capture. Re-run with reload:true to record a fresh one."
+  );
+}
+
+/**
+ * The read-path miss. Deliberately NOT workerMissMessage's wake:false text,
+ * which promises that "wake:true (the default)" would fix it — true for
+ * evaluate_script and for a capture, false here (see workerWakeMisuseMessage).
+ */
+export function workerBufferReadMissMessage(needle: string, liveWorkers: readonly WorkerTargetLike[]): string {
+  const running = liveWorkers.length ? ` (running workers: ${urlList(liveWorkers)})` : " (no workers are running)";
+  return (
+    `no running worker whose url contains '${needle}'${running}. ` +
+    "An MV3 extension service worker is idle-evicted after seconds of inactivity and then appears in NO target " +
+    "listing, so this is usually a sleeping worker rather than a wrong substring. This call only READS a buffer " +
+    "recorded earlier, and that buffer is keyed by the worker's target id, which Chrome re-mints on restart — so " +
+    "re-run with reload:true, which starts the worker and records a fresh capture window."
+  );
+}
 
 function urlList(workers: readonly WorkerTargetLike[]): string {
   return workers.map((w) => w.url).join(", ");