cdp-toolkit 1.8.0 → 1.9.1

package/src/shared-tools.ts

@@ -44,7 +44,8 @@ import {
   type LeaseBackend, type LeaseStaleReason, type LeaseToken,
 } from "./leases.ts";
 import { installBeacon, probeRendererActivity, rendererProbeSupported } from "./activity.ts";
-import { newTrackedPage, originIndex, type PageOrigin } from "./origins.ts";
+import { newTrackedPage, originIndex, resolveLiveLabel, type PageOrigin } from "./origins.ts";
+import { isWorkerSelector, WORKER_SELECTOR_PAGE_ONLY_MESSAGE, WORKER_SELECTOR_UNSUPPORTED_MESSAGE } from "./workers.ts";
 import { reapStaleAgentTabs, type ReapedTab } from "./reap.ts";
 
 const ARTIFACT_DIR = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
@@ -132,6 +133,21 @@ export async function pickPage(driver: BrowserDriver, pages: PageInfo[], selecto
     if (!p) throw new SharedToolError(`no page title containing '${needle}'`);
     return p;
   }
+  if (selector.startsWith("label:")) return pickByLabel(driver, pages, selector.slice(6));
+  if (isWorkerSelector(selector)) {
+    // THE PAGE-ONLY CONTRACT, STATED OUT LOUD. Every caller of pickPage
+    // (resolvePage -> close_page / select_page / release_page, claim_page's
+    // takeover) acts on a TAB, and the 1.9.0 "worker:" arm is deliberately NOT
+    // implemented here: it resolves against the page-only listing these callers
+    // pass, which by construction never contains a worker, so the arm could
+    // only ever miss. Refusing with the reason beats falling through to the
+    // bare-id lookup, whose "no target with id 'worker:foo'" reads as a typo.
+    // The arm lives in client.ts's pickTarget (Chrome's all-targets resolver),
+    // and only evaluate_script routes to it.
+    throw new SharedToolError(
+      backendOf(driver) === "firefox" ? WORKER_SELECTOR_UNSUPPORTED_MESSAGE : WORKER_SELECTOR_PAGE_ONLY_MESSAGE,
+    );
+  }
   const exactPage = pages.find((x) => x.id === selector);
   if (exactPage) return exactPage;
   const all = await driver.listPages({ all: true });
@@ -140,6 +156,35 @@ export async function pickPage(driver: BrowserDriver, pages: PageInfo[], selecto
   throw new SharedToolError(`no target with id '${selector}'`);
 }
 
+/**
+ * "label:<name>" resolution for pickPage. The lookup itself (both stores,
+ * live-scoped) is shared with client.ts's pickTarget and bidi/driver.ts's
+ * pickContext via origins.ts's resolveLiveLabel, so the three copies of the
+ * selector grammar cannot drift on what counts as a hit, a miss or an
+ * ambiguity. Only the error wording is local, matching this file's
+ * SharedToolError idiom.
+ *
+ * Nothing is reaped here: this is a read, not a maintenance pass, and pickPage
+ * stays gate-free and side-effect-free over its inputs.
+ */
+async function pickByLabel(driver: BrowserDriver, pages: PageInfo[], label: string): Promise<PageInfo> {
+  const { matchIds, knownLabels } = await resolveLiveLabel(backendOf(driver), label, pages.map((x) => x.id));
+  if (matchIds.length > 1) {
+    throw new SharedToolError(
+      `label 'label:${label}' matches more than one live target: ${matchIds.join(", ")}. Resolve by target id instead.`,
+    );
+  }
+  if (matchIds.length === 1) {
+    const p = pages.find((x) => x.id === matchIds[0]);
+    if (p) return p;
+  }
+  throw new SharedToolError(
+    knownLabels.length
+      ? `no live target with label '${label}' (labels currently in use: ${knownLabels.join(", ")})`
+      : `no live target with label '${label}' (no labels are currently assigned to any open target)`,
+  );
+}
+
 /* -------------------------------- element locators -------------------------------- */
 
 function locatorOf(args: { uid?: DriverUid; selector?: string }): ElementLocator {
@@ -476,14 +521,70 @@ function sinkRequested(savePath?: string): savePath is string {
   return savePath !== undefined && savePath !== "";
 }
 
+/** Keys a caller reaches for out of habit from other automation APIs, none of
+ *  which this tool reads: the code always goes in 'expression'. Checked in
+ *  this order so the error names one wrong key, deterministically, when a
+ *  caller happens to pass more than one. */
+const EXPRESSION_ALIAS_KEYS = ["function", "code", "js", "script", "fn", "body"] as const;
+
+/**
+ * Turn a `worker:<substring>` target into a concrete target id, waking an
+ * idle-evicted MV3 service worker on the way when `wake` is not false.
+ *
+ * WHY THIS RETURNS AN ID RATHER THAN DRIVING THE WORKER ITSELF. Once resolved,
+ * a worker is just a target with its own webSocketDebuggerUrl, and a DIRECT
+ * connection to it evaluates exactly like a page does — `Runtime.evaluate` with
+ * `awaitPromise` returns real awaited values there (measured on Chrome 151;
+ * `chrome.storage.local.get(null)` comes back as an object, not undefined). So
+ * the worker rides the ordinary page() acquisition path from here, and every
+ * behavior around it — the args/function form, exception reporting, and above
+ * all savePath's no-value-in-the-response secret hygiene — is the SAME CODE,
+ * not a parallel copy that could quietly diverge on the leak-shaped edge.
+ *
+ * Exported for the unit tests, which need to reach the capability refusal
+ * without a browser.
+ */
+export async function resolveWorkerSelectorFor(
+  driver: BrowserDriver,
+  selector: string,
+  wake: boolean,
+): Promise<PageInfo> {
+  if (!driver.capabilities.has("worker.targets") || typeof driver.resolveWorkerTarget !== "function") {
+    throw new SharedToolError(`evaluateScript: ${WORKER_SELECTOR_UNSUPPORTED_MESSAGE}`);
+  }
+  return driver.resolveWorkerTarget(selector, { wake });
+}
+
 export async function evaluateScript(
   driver: BrowserDriver,
-  args: { target?: TargetSelector; expression: string; awaitPromise?: boolean; args?: unknown[]; savePath?: string },
+  args: { target?: TargetSelector; expression: string; awaitPromise?: boolean; args?: unknown[]; savePath?: string; wake?: boolean },
 ): Promise<unknown> {
   if (typeof args.expression !== "string" || args.expression.length === 0) {
+    const wrongKey = EXPRESSION_ALIAS_KEYS.find((k) => (args as Record<string, unknown>)[k] !== undefined);
+    if (wrongKey !== undefined) {
+      throw new SharedToolError(
+        `evaluateScript: you passed '${wrongKey}'; the key is 'expression' — function literals go in 'expression', invoked with 'args'.`,
+      );
+    }
     throw new SharedToolError("evaluateScript: 'expression' must be a non-empty string");
   }
-  return withPage(driver, args.target, async (page) => {
+  if (args.wake !== undefined && typeof args.wake !== "boolean") {
+    throw new SharedToolError("evaluateScript: 'wake' must be a boolean");
+  }
+  // `wake` is REFUSED on a page selector rather than ignored. Accepting it there
+  // would read as "this call will wake something", and the caller would never
+  // learn that the argument did nothing at all.
+  if (args.wake !== undefined && !isWorkerSelector(args.target)) {
+    throw new SharedToolError(
+      "evaluateScript: 'wake' only applies to a target of the form 'worker:<substring>'; a page target is never asleep.",
+    );
+  }
+  // Resolved to a bare target id BEFORE acquisition, so the page() call below is
+  // the same one every other selector makes.
+  const target = isWorkerSelector(args.target)
+    ? (await resolveWorkerSelectorFor(driver, args.target, args.wake ?? true)).id
+    : args.target;
+  return withPage(driver, target, async (page) => {
     const value = await page.evaluate(args.expression, { args: args.args, awaitPromise: args.awaitPromise ?? true });
     // No savePath: byte-identical to the pre-sink behavior, the value itself.
     // A thrown page-side exception never reaches here, so it still surfaces as

package/src/tools/console.ts

@@ -12,11 +12,18 @@
  *     unique per-capture file), Page.reload, capture for `durationMs` (default
  *     2500ms), stop, then read+return the console entries from that capture. The
  *     both-domains capture means a network reload never wipes console history.
+ *
+ * SERVICE WORKERS (1.9.1): list_console_messages accepts `worker:<substring>`
+ * and a bare worker target id, Chrome only (Capability "worker.targets"). A
+ * worker's console.log arrives as Runtime.consoleAPICalled on its own session
+ * (measured; `Log.entryAdded` never fires there). There is no reload to drive a
+ * worker capture, so reload:true means "listen for durationMs" — see
+ * recorder.ts's header.
  */
 import { readFile } from "node:fs/promises";
-import { CdpError, resolveTarget } from "../client.ts";
+import { CdpError } from "../client.ts";
 import type { TargetSelector } from "../types.ts";
-import { recFile, captureWindow } from "./recorder.ts";
+import { assertWakeApplies, recFile, captureWindow, resolveRecorderTarget } from "./recorder.ts";
 import type { RecLine } from "./recorder.ts";
 
 const DEFAULT_CAPTURE_MS = 2500;
@@ -44,6 +51,8 @@ export interface ListConsoleMessagesArgs {
   reload?: boolean;
   /** Capture window for reload mode (ms). Default 2500. */
   durationMs?: number;
+  /** Worker targets only, and only with reload:true — start an idle-evicted MV3 worker first (default true). */
+  wake?: boolean;
 }
 
 export interface GetConsoleMessageArgs {
@@ -144,8 +153,9 @@ export async function listConsoleMessages(args: ListConsoleMessagesArgs = {}): P
   messages: ConsoleEntry[];
   droppedWrites?: number;
 }> {
+  assertWakeApplies(args.target, args.wake, args.reload === true);
   if (args.reload) {
-    const cap = await captureWindow(args.target, args.durationMs ?? DEFAULT_CAPTURE_MS);
+    const cap = await captureWindow(args.target, args.durationMs ?? DEFAULT_CAPTURE_MS, { wake: args.wake });
     await cap.stop();
     const messages = await readConsoleEntries(cap.file);
     return {
@@ -156,7 +166,7 @@ export async function listConsoleMessages(args: ListConsoleMessagesArgs = {}): P
     };
   }
 
-  const target = await resolveTarget(args.target);
+  const target = await resolveRecorderTarget(args.target, { capture: false });
   const messages = await readConsoleEntries(recFile(target.id));
   return {
     target: { id: target.id, url: target.url, title: target.title },
@@ -170,7 +180,14 @@ export async function listConsoleMessages(args: ListConsoleMessagesArgs = {}): P
  * existing buffer for the target. Throws if the index is out of range.
  */
 export async function getConsoleMessage(args: GetConsoleMessageArgs = {}): Promise<ConsoleEntry> {
-  const target = await resolveTarget(args.target);
+  // Reads the SAME buffer list_console_messages just returned, so it resolves
+  // through the same read-path resolver: a worker target already reached this
+  // code through the 1.9.0 bare-id/`worker:` arm, and routing it here is what
+  // makes the miss message match the buffer it is actually reading. It is
+  // deliberately NOT advertised as worker-capable in the manifest (see
+  // WORKER_CAPABLE_TOOLS): index-into-a-buffer is not the worker story, and the
+  // drift test keeps the advertised list to the four tools that are.
+  const target = await resolveRecorderTarget(args.target, { capture: false });
   const messages = await readConsoleEntries(recFile(target.id));
   const index = args.index ?? 0;
   const entry = messages[index];
@@ -184,8 +201,8 @@ export async function getConsoleMessage(args: GetConsoleMessageArgs = {}): Promi
 
 /*
  * CDP methods / domains used (via recorder.ts + this module):
- *   Page.enable           (reload mode)
- *   Page.reload           (reload mode)
+ *   Page.enable           (reload mode, PAGE targets only)
+ *   Page.reload           (reload mode, PAGE targets only)
  *   Runtime.enable / Runtime.consoleAPICalled / Runtime.exceptionThrown (recorder)
  *   Log.enable / Log.entryAdded                                          (recorder)
  *

package/src/tools/network.ts

@@ -16,11 +16,19 @@
  * and calls Network.getResponseBody before closing. Because a reload re-mints
  * requestIds, body fetch is matched by `url` (stable), not by a carried-over
  * requestId; see getNetworkRequest for the exact contract.
+ *
+ * SERVICE WORKERS (1.9.1): both tools accept `worker:<substring>` and a bare
+ * worker target id, Chrome only (Capability "worker.targets"). The capture is
+ * the same recorder, over the worker's own connection; what differs is that
+ * there is no reload to drive it (see recorder.ts's header for the measurements)
+ * — the window listens while the worker works, so the traffic has to be
+ * triggered during it. `wake` starts an idle-evicted worker first, and is
+ * accepted only where it can actually do something.
  */
 import { readFile } from "node:fs/promises";
-import { CdpError, resolveTarget } from "../client.ts";
+import { CdpError } from "../client.ts";
 import type { TargetSelector } from "../types.ts";
-import { recFile, captureWindow } from "./recorder.ts";
+import { assertWakeApplies, recFile, captureWindow, resolveRecorderTarget } from "./recorder.ts";
 import type { RecLine } from "./recorder.ts";
 
 const DEFAULT_CAPTURE_MS = 2500;
@@ -55,6 +63,8 @@ export interface ListNetworkRequestsArgs {
   durationMs?: number;
   /** Only return requests whose URL contains this substring. */
   filterUrl?: string;
+  /** Worker targets only, and only with reload:true — start an idle-evicted MV3 worker first (default true). */
+  wake?: boolean;
 }
 
 export interface GetNetworkRequestArgs {
@@ -66,6 +76,8 @@ export interface GetNetworkRequestArgs {
   /** Fetch the response body too (drives a fresh reload capture; use with `url`). */
   includeBody?: boolean;
   durationMs?: number;
+  /** Worker targets only, and only with includeBody+url — start an idle-evicted MV3 worker first (default true). */
+  wake?: boolean;
 }
 
 /** Coerce a CDP headers object to a string-keyed/string-valued record. */
@@ -166,14 +178,15 @@ export async function listNetworkRequests(args: ListNetworkRequestsArgs = {}): P
   let resolved: { id: string; url: string; title: string };
   let droppedWrites: number | undefined;
 
+  assertWakeApplies(args.target, args.wake, args.reload === true);
   if (args.reload) {
-    const cap = await captureWindow(args.target, args.durationMs ?? DEFAULT_CAPTURE_MS);
+    const cap = await captureWindow(args.target, args.durationMs ?? DEFAULT_CAPTURE_MS, { wake: args.wake });
     await cap.stop();
     file = cap.file;
     resolved = cap.resolved;
     droppedWrites = cap.droppedWrites();
   } else {
-    const target = await resolveTarget(args.target);
+    const target = await resolveRecorderTarget(args.target, { capture: false });
     file = recFile(target.id);
     resolved = { id: target.id, url: target.url, title: target.title };
   }
@@ -214,9 +227,10 @@ export async function getNetworkRequest(args: GetNetworkRequestArgs = {}): Promi
   const describeSelector = (): string =>
     args.requestId ? `requestId ${args.requestId}` : `url ~ '${args.url}'`;
 
+  assertWakeApplies(args.target, args.wake, Boolean(args.includeBody && args.url));
   // Body fetch by URL: a fresh reload capture (url is stable across reload).
   if (args.includeBody && args.url) {
-    const cap = await captureWindow(args.target, args.durationMs ?? DEFAULT_CAPTURE_MS);
+    const cap = await captureWindow(args.target, args.durationMs ?? DEFAULT_CAPTURE_MS, { wake: args.wake });
     try {
       await cap.flush(); // ensure the buffer is complete; conn stays open for the body fetch
       const match = (await readNetworkRequests(cap.file)).find((r) => r.url.includes(args.url!));
@@ -239,7 +253,7 @@ export async function getNetworkRequest(args: GetNetworkRequestArgs = {}): Promi
   }
 
   // Metadata path: read the target's existing buffer (also the requestId+includeBody case).
-  const target = await resolveTarget(args.target);
+  const target = await resolveRecorderTarget(args.target, { capture: false });
   const match = pick(await readNetworkRequests(recFile(target.id)));
   if (!match) {
     throw new CdpError(
@@ -264,7 +278,7 @@ export async function getNetworkRequest(args: GetNetworkRequestArgs = {}): Promi
  *   Network.requestWillBeSent / .responseReceived / .loadingFinished /
  *     .loadingFailed (events)                                       (recorder)
  *   Network.getResponseBody                                         (includeBody mode)
- *   Page.enable / Page.reload                                       (reload mode)
+ *   Page.enable / Page.reload                          (reload mode, PAGE targets only)
  *
  * Parity gaps vs chrome-devtools-mcp:
  *   - Response bodies require a fresh reload capture (CDP serves bodies only from

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

@@ -41,6 +41,28 @@ export interface CdpEvent<P = Record<string, unknown>> {
  *   - "index:N"              -> Nth page-type target (0-based)
  *   - "url:<substring>"      -> first page whose url contains substring
  *   - "title:<substring>"    -> first page whose title contains substring
+ *   - "label:<name>"         -> the page-type target whose label EXACTLY
+ *     matches `name`, checked against both the origin ledger (agent-created
+ *     tabs, see src/origins.ts) and live lease records (covers a taken-over
+ *     tab claimed with a label, which has no origin record — see
+ *     src/leases-tools.ts's claimPage). The resolved id must be present in
+ *     the listing this call is resolving against; a label whose tab is gone
+ *     falls through to the normal no-match error. A miss enumerates the
+ *     labels that DO exist; two live targets sharing a label is an ambiguity
+ *     error naming both ids, never a silent first-match. See pickPage in
+ *     src/shared-tools.ts.
+ *   - "worker:<substring>"    -> a service_worker/shared_worker target whose
+ *     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 (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;