cdp-toolkit 1.9.0 → 1.9.1

package/CHANGELOG.md

@@ -5,6 +5,123 @@ All notable changes to cdp-toolkit are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.9.1] - 2026-08-10
+
+`list_network_requests`, `get_network_request`, and `list_console_messages` now
+observe MV3 background service workers, not just pages: the outbound fetch a
+worker makes to a real backend is a first-class capture target, not something
+you have to fake with an `evaluate_script` monkeypatch. Tool count stays 45 —
+the three tools grow a `worker:` arm, no new tool. One seat (N1) landed it,
+every protocol claim below probed against a live Chrome 151 before being built
+on.
+
+### Added
+
+- **The three console/network reader tools accept `target: "worker:<substring>"`
+  or a bare worker target id**, alongside the page selectors they already took.
+  Chrome only (capability `worker.targets`) — Firefox refuses the arm from its
+  real capability set before launching a browser that could never have served
+  the call. The allowlist that grants the arm, `WORKER_CAPABLE_TOOLS` in
+  `src/workers.ts`, now names four tools (`evaluate_script` plus these three);
+  it is the single source of truth for both the refusal messages and
+  `test/manifest-grammar-drift.test.ts`'s exclusion property, so a fifth tool
+  cannot silently advertise `worker:` without a deliberate edit here.
+
+- **A worker capture LISTENS instead of reloading.** Measured on Chrome
+  151.0.7922.109: `Network.enable` and `Runtime.consoleAPICalled` work
+  identically on a direct worker session to how they work on a page — all four
+  events the recorder persists (`requestWillBeSent`, `responseReceived`,
+  `loadingFinished`, `loadingFailed`) arrive, and `Network.getResponseBody`
+  serves the body — but `Page.enable`/`Page.reload` **do not exist** on a
+  worker session (`-32601 'Page.enable' wasn't found`). A page capture is
+  reload-driven; a worker capture cannot be, so it opens the worker's own CDP
+  session and listens for `durationMs` instead. `captureWindow()`'s branch is
+  keyed off the resolved target's type, not the selector's shape, so a bare
+  worker id takes the listen path too.
+
+- **Recording a worker keeps it alive for the length of the capture — a
+  deliberate side effect, not a bug.** A held CDP session suppresses MV3 idle
+  eviction; measured in both directions with the same polling loop so
+  "stayed alive" isn't an artifact of how the poll works: with the recorder's
+  session held, the worker is still present in `/json/list` and still emits a
+  fresh `Network.requestWillBeSent` for a triggered fetch at t+60s; once the
+  session detaches, the same worker idle-evicts within ~30s. Documented in the
+  three tools' manifest descriptions and asserted in both directions by the
+  live smoke, not left implicit.
+
+- **`wake` (default `true` on a capture) is REFUSED on a read-only call and on
+  a bare target id, rather than accepted and ignored.** Measured: a worker
+  that idle-evicts and restarts comes back under a brand-new target id (probed
+  restart: `C43F0A18...` → `1F7D3C59...` for the same extension). The recorder
+  keys its buffer file by target id, so waking a worker on a *read* would hand
+  back a live worker with an empty buffer — "0 requests" for a capture that
+  really did record some, a zero shaped like an answer. A wake therefore only
+  makes sense when a capture is being started, and only from a
+  `worker:<substring>` selector, since an evicted worker's old id no longer
+  exists to name. The refusal messages (`workerWakeMisuseMessage`,
+  `workerBufferReadMissMessage` in `src/workers.ts`) teach the id-re-mint fact
+  rather than just rejecting the argument.
+
+- **Known limitation, stated rather than silently absent: a worker woken BY a
+  capture has already run its top-level code by the time the recorder
+  attaches**, so a fetch the worker makes at startup can be missed. Trigger
+  the request you want to observe (a message, an alarm) after the capture
+  starts rather than relying on the worker's own boot-time fetch. Fixing this
+  needs `Target.setAutoAttach{waitForDebuggerOnStart}` on a held browser
+  session, a different feature; the limitation is documented in
+  `recorder.ts`'s header and in the three manifest descriptions instead.
+
+- **`get_console_message` reads the same worker-keyed buffer (so its miss
+  message matches what it reads) but is deliberately NOT in
+  `WORKER_CAPABLE_TOOLS`** — it already resolved worker targets through the
+  1.9.0 arm, routing it through the read-path resolver only sharpens its miss
+  message; advertising it as worker-capable was out of scope, and the drift
+  test pins the advertised list at four.
+
+### Measured, not assumed — the protocol facts this release ships on
+
+- **`Page.enable`/`Page.reload` are `-32601` on a worker session** — the
+  single measurement that shapes the implementation: a worker window cannot
+  be reload-driven, so it listens.
+- **A held session suppresses MV3 idle eviction; detach restores it** —
+  confirmed in both directions with the same polling loop, including a
+  post-hold evaluate and a fresh `Network.requestWillBeSent` at t+60s, so
+  "alive" means genuinely live, not a stale listing entry.
+- **A worker's target id is re-minted on every restart, never stable** — this
+  is why `wake` is refused on reads and on bare ids rather than silently doing
+  the wrong thing.
+- **Two things a caller might reach for instead don't work, for ordinary
+  JavaScript reasons, not a service-worker-specific one.** A value bound at
+  module top level is not visible from `evaluate_script`'s global scope
+  (plain lexical scoping, identical in a page); assigning `self.fetch`
+  afterward cannot rebind a `fetch` reference the module already captured
+  (closure semantics, also identical in a page). `Network`-domain recording
+  on the worker's own session observes what the code ACTUALLY SENT and needs
+  neither. (An earlier field report attributing this to service-worker eval
+  semantics was a misdiagnosis of an outdated loaded extension build, not a
+  real capability gap — see the stale-build tip below.)
+
+### Notes
+
+- Tool count is unchanged at **45** — this release grew the `target` grammar
+  on three existing tools, not the tool list.
+- `docs/social-preview.html` and `docs/demo.tape` carry no version string and
+  needed no re-render for this release.
+- Before deep-debugging an extension that "the toolkit can't see": verify the
+  loaded build is current with
+  `evaluate_script {target:"worker:<id>", expression:"chrome.runtime.getManifest().version"}`.
+  An outdated unpacked build left over from a prior load mimics every symptom
+  in this release's "measured facts" section above.
+- New tests: 20 in `test/worker-capture.test.ts`, 3 more in
+  `test/manifest-grammar-drift.test.ts` (allowlist rescoped from an
+  evaluate_script-only exclusion to the four-tool `WORKER_CAPABLE_TOOLS`
+  allowlist), and new live scenarios in `test/extension-smoke.ts` covering the
+  worker fetch/console capture, the eviction pair in both directions, and the
+  capture-path wake (proven by the fixture's own start counter, `starts: 2 ->
+  3`, never by `ServiceWorker.startWorker`'s result, which reports empty
+  success even for a scope that doesn't exist) — 31/31 assertions, up from the
+  1.9.0 baseline of 20.
+
 ## [1.9.0] - 2026-08-09
 
 Four complaints from a field agent driving an MV3 extension, closed without adding
@@ -870,6 +987,7 @@ First public release.
 - Zero runtime dependencies in the CDP/CLI layer (Node's global `WebSocket` + `fetch`). The MCP server adds only `@modelcontextprotocol/sdk`; `lighthouse_audit` is the sole non-CDP tool and shells out to `npx lighthouse`.
 - Runtime: Bun ≥ 1.1 (recommended) or Node ≥ 22 (for the global `WebSocket`). Requires Chrome/Chromium started with `--remote-debugging-port=9222`.
 
+[1.9.1]: https://github.com/sblattj/cdp-toolkit/releases/tag/v1.9.1
 [1.9.0]: https://github.com/sblattj/cdp-toolkit/releases/tag/v1.9.0
 [1.8.0]: https://github.com/sblattj/cdp-toolkit/releases/tag/v1.8.0
 [1.7.0]: https://github.com/sblattj/cdp-toolkit/releases/tag/v1.7.0

package/CONTRACT.md

@@ -18,9 +18,9 @@ writing a module.
 
    **`claim_page{target}` is a deliberate, reviewed exception to this rule, not a violation of it.** Its target resolution goes through `pickPage` (`src/shared-tools.ts`), which is exported *specifically* for this one caller and does **not** call `assertLeaseOk`. Routing a claim through `resolvePage` instead would, under strict mode, auto-acquire a lease on the way in and then collide with the explicit claim right behind it, one call claiming the same tab against itself twice. The protection is not dropped, only relocated one layer down: `claimLease`'s own conflict check still refuses a tab any live process holds, auto-acquired or explicit, so a stranger's tab is still refused, only later and by a different function. `pickPage` must never gain a second caller without re-deriving this argument for that caller too; if it does not need gate-free resolution, it needs `resolvePage`, not `pickPage`.
 
-   **A worker-typed hit inside `resolveTarget` is the other deliberate exception, added in 1.9.0.** A `worker:<substring>` selector (Chrome only, capability `worker.targets`, `evaluate_script`'s alone) resolves to a service/shared worker target, and `resolveTarget` returns it before reaching `assertLeaseOk` — see the comment at the top of that branch in `src/client.ts`. A lease answers "who is driving this tab"; a worker is not a tab, has no reap-meaningful close, and strict-mode auto-acquire on it would mint a lease file keyed on an id that vanishes the moment Chrome idles the worker out, garbage the page-only reap set (`ReapInput.livePageIds`) can never collect. This also cannot be used to bypass a lease on an actual tab: there is no tab a worker resolution could stand in for.
+   **A worker-typed hit inside `resolveTarget` is the other deliberate exception, added in 1.9.0.** A `worker:<substring>` selector (Chrome only, capability `worker.targets`; one tool in 1.9.0, `evaluate_script` — four as of 1.9.1, see `WORKER_CAPABLE_TOOLS` in `src/workers.ts`) resolves to a service/shared worker target, and `resolveTarget` returns it before reaching `assertLeaseOk` — see the comment at the top of that branch in `src/client.ts`. A lease answers "who is driving this tab"; a worker is not a tab, has no reap-meaningful close, and strict-mode auto-acquire on it would mint a lease file keyed on an id that vanishes the moment Chrome idles the worker out, garbage the page-only reap set (`ReapInput.livePageIds`) can never collect. This also cannot be used to bypass a lease on an actual tab: there is no tab a worker resolution could stand in for. **The three console/network reader tools take a parallel path, not this one** — `resolveRecorderTarget`/`resolveWorkerSelector` in `src/tools/recorder.ts`/`src/cdp/workers.ts` — but the same reasoning holds: neither touches `assertLeaseOk`, tested by asserting zero lease files on a worker read with a page control in the same strict-mode window.
 
-   **The `TargetSelector` grammar itself also has three independent copies, a separate fact from the lease choke points above** — `pickTarget` (`src/client.ts`, what `resolveTarget` calls, and what most tools reach through), `pickPage` (`src/shared-tools.ts`), and `pickContext` (`src/bidi/driver.ts`, Firefox). A prefix arm added to one does not exist for callers routed through another; `label:` (1.9.0) was first wired into only `pickPage` and passed every unit test while `evaluate_script` still rejected it, because `evaluate_script` calls `pickTarget`, not `pickPage`, and only the live smoke caught the gap. The shared lookup core for an arm that needs identical semantics everywhere (as `label:` does) belongs in its own module — see `resolveLiveLabel` in `src/origins.ts` — wired into all three call sites, each keeping its own error class (`CdpError` / `SharedToolError` / `DriverError`). `test/manifest-grammar-drift.test.ts` structurally asserts a completeness property (every `title:` mention also mentions `label:`) and, separately, an exclusion property for `worker:` (no tool other than `evaluate_script` may name it) — grep `startsWith("title:")` across `src/` before adding a new arm, and extend or scope that test for it.
+   **The `TargetSelector` grammar itself also has three independent copies, a separate fact from the lease choke points above** — `pickTarget` (`src/client.ts`, what `resolveTarget` calls, and what most tools reach through), `pickPage` (`src/shared-tools.ts`), and `pickContext` (`src/bidi/driver.ts`, Firefox). A prefix arm added to one does not exist for callers routed through another; `label:` (1.9.0) was first wired into only `pickPage` and passed every unit test while `evaluate_script` still rejected it, because `evaluate_script` calls `pickTarget`, not `pickPage`, and only the live smoke caught the gap. The shared lookup core for an arm that needs identical semantics everywhere (as `label:` does) belongs in its own module — see `resolveLiveLabel` in `src/origins.ts` — wired into all three call sites, each keeping its own error class (`CdpError` / `SharedToolError` / `DriverError`). `test/manifest-grammar-drift.test.ts` structurally asserts a completeness property (every `title:` mention also mentions `label:`) and, separately, an exclusion property for `worker:` (only a tool in the `WORKER_CAPABLE_TOOLS` allowlist — four as of 1.9.1 — may name it) — grep `startsWith("title:")` across `src/` before adding a new arm, and extend or scope that test for it.
 
 7. **Never dispatch `Input.*` outside `sendInput`.** As of 1.8.0 there is exactly one function that writes a synthesized input command to a Chrome connection: `sendInput(conn, backend, targetId, method, params)` in `src/activity.ts`. `CdpPageDriver.dispatchInput` (the per-driver choke point every interaction method already had to go through) delegates to it, and any tool built outside the Driver abstraction (`dispatch_mouse`, in `src/tools/dispatch-mouse.ts`, is the precedent) must call it directly rather than opening its own `conn.send("Input....", ...)`. This is what keeps the activity beacon's human/agent discrimination (`src/activity.ts`'s dispatch log) correct: a new input path that bypasses `sendInput` will typecheck, pass its own unit tests, and pass `bun test` in full, while silently making the toolkit's own input read as a human using the tab — exactly the 1.8.0 merge bug `test/input-dispatch-wiring.test.ts` now exists to catch (it walks every `.ts` under `src/`, strips comment-only lines, and fails on any line that both sends and names `Input.`). On the Firefox side, `BidiPageDriver.performActions` is the twin choke point and already calls `recordDispatch`; a new BiDi input path goes through it the same way `CdpPageDriver.dispatchInput` is used on Chrome. Mode-toggle commands that dispatch no page input themselves (`Input.setInterceptDrags`'s arm/disarm around HTML5 drag) are still sent through `sendInput` but are on a denylist that skips recording them — classify a new such command explicitly; the default for anything unclassified is to be logged, since over-warning a human is recoverable and silently misattributing their input to "agent" is not.
 
@@ -117,7 +117,7 @@ A `Uid` **is** a CDP `backendDOMNodeId` (a number). This makes refs stateless:
 | `src/tools/screenshot.ts` | `take_screenshot`→`takeScreenshot` | `Page.captureScreenshot`. Support `{ format:'png'|'jpeg', quality, fullPage, uid?/selector? (element clip via getBoxModel), savePath? }`. Write to ARTIFACT_DIR, return `{ path, bytes, format }` and optionally base64 when `{ returnBase64:true }`. |
 | `src/tools/emulation.ts` | `emulate`→`emulate`, `resize_page`→`resizePage` | `Emulation.setDeviceMetricsOverride` (width,height,deviceScaleFactor,mobile), `Emulation.setUserAgentOverride`, `Emulation.setCPUThrottlingRate`, `Emulation.setEmulatedMedia`, `Network`-based throttling via `Network.emulateNetworkConditions`. `resize_page` = device metrics width/height. |
 | `src/tools/dialogs.ts` | `handle_dialog`→`handleDialog` | `Page.enable`, subscribe `Page.javascriptDialogOpening`, respond with `Page.handleJavaScriptDialog({ accept, promptText })`. Support a "wait for next dialog then handle" mode and an "auto-handle for N ms" mode. |
-| `src/tools/recorder.ts` + `src/tools/console.ts` + `src/tools/network.ts` | console: `list_console_messages`→`listConsoleMessages`, `get_console_message`→`getConsoleMessage`; network: `list_network_requests`→`listNetworkRequests`, `get_network_request`→`getNetworkRequest` | **Owned by one agent.** `recorder.ts` exports `startRecorder(target, {network,console}): Promise<{stop()}>` that opens a persistent `openPage` conn, enables `Network`+`Runtime`(+`Log`), and appends events to `rec-<targetId>.jsonl`. console/network `list_*` read that file (and support a one-shot `{ reload:true, durationMs }` mode that records fresh by reloading the page and capturing for a window, then returns). `get_*` filter by id/url. Document the recorder model at the top of `recorder.ts`. |
+| `src/tools/recorder.ts` + `src/tools/console.ts` + `src/tools/network.ts` | console: `list_console_messages`→`listConsoleMessages`, `get_console_message`→`getConsoleMessage`; network: `list_network_requests`→`listNetworkRequests`, `get_network_request`→`getNetworkRequest` | **Owned by one agent.** `recorder.ts` exports `startRecorder(target, {network,console}): Promise<{stop()}>` that opens a persistent `openPage` conn, enables `Network`+`Runtime`(+`Log`), and appends events to `rec-<targetId>.jsonl`. console/network `list_*` read that file (and support a one-shot `{ reload:true, durationMs }` mode that records fresh by reloading the page and capturing for a window, then returns). `get_*` filter by id/url. Document the recorder model at the top of `recorder.ts`. **As of 1.9.1, the same three tools also accept a `worker:<substring>` target** (Chrome only, capability `worker.targets`; MV3 service/shared workers), resolved via `resolveRecorderTarget`/`resolveWorkerSelector` in `src/workers.ts` rather than `resolveTarget`. Because `Page.enable`/`Page.reload` do not exist on a worker session (measured: `-32601`), `captureWindow()` skips the reload for a worker-typed resolution and LISTENS on the held connection for `durationMs` instead — keyed off the resolved target's type, not the selector's shape, so a bare worker id takes the same branch as a `worker:` selector. Holding that session is a deliberate side effect, the same pattern as the beacon sessions below: it SUPPRESSES the worker's MV3 idle eviction for as long as the capture runs (measured: alive and still emitting events at 60s held, evicted ~30s after detach). `wake` (default `true` on a capture) restarts an evicted worker first, but is refused on a read-only call and on a bare target id, because a restart mints a NEW target id and the buffer is keyed by the old one — see `workerWakeMisuseMessage` in `src/workers.ts`. |
 | `src/tools/performance.ts` | `performance_start_trace`→`performanceStartTrace`, `performance_stop_trace`→`performanceStopTrace`, `performance_analyze_insight`→`performanceAnalyzeInsight` | `Tracing.start`(categories incl. `devtools.timeline`,`blink.user_timing`,`loading`,`-*`), collect `Tracing.dataCollected`, `Tracing.end`→`Tracing.tracingComplete`, write trace JSON to ARTIFACT_DIR. start/stop need a persistent conn, so use a state file to hold the in-flight trace path/connection target. `performance_analyze_insight` parses a trace file for LCP, FCP/navigation timing, long tasks (>50ms), layout shifts (CLS), total blocking time; return structured metrics. **Mark in a top comment that this is a CDP-native approximation of the MCP's insight analyzer.** |
 | `src/tools/screencast.ts` | `start_screen_recording`→`startScreenRecording`, `stop_screen_recording`→`stopScreenRecording` | **Toolkit addition (not MCP parity): a tab captured to an H.265 MP4.** Persistent `openPage` conn parked in a module-level `Map` keyed by targetId (recorder.ts's statefulness, performance.ts's registry), `Page.startScreencast` → `Page.screencastFrame` → **ack from the handler, before the disk write** (an unacked frame stalls the stream) → spool file + ledger row `{file,timestamp,width,height}`. Frames arrive on repaint only, so playback timing MUST come from per-frame ffconcat `duration`s off the ledger, never a fixed rate. Encoder ladder probed once from `ffmpeg -encoders`: `hevc_videotoolbox`→`h264_videotoolbox`→`libx265`→`libx264`, `-tag:v hvc1` on HEVC, always `+faststart`/`yuv420p`/even dims. ffmpeg is probed at START (fail before capturing, not after). Pure parts (`frameDurationsMs`/`buildConcatManifest`/`selectEncoder`/`buildFfmpegArgs`/`imageSize`) are unit-tested; live capture via `test/screencast-smoke.ts`. |
 | `src/tools/heap.ts` | `take_heapsnapshot`→`takeHeapsnapshot` | `HeapProfiler.enable` → `HeapProfiler.takeHeapSnapshot`, assemble `HeapProfiler.addHeapSnapshotChunk` events into a `.heapsnapshot` file under ARTIFACT_DIR; return `{ path, bytes }`. |

package/README.md

@@ -253,7 +253,7 @@ The 29 parity tools are 1:1 with `chrome-devtools-mcp`; the 16 superset tools (`
 | `select_page` | `Target.activateTarget` + selected-state file | Writes a flat-file selected target; `resolveTarget` does not read it, so `active` still means `index:0` unless a tool opts in. |
 | `navigate_page` | `Page.navigate` / `Page.reload` + load events, or `history:'back'\|'forward'` (Chrome: `Page.getNavigationHistory` + `Page.navigateToHistoryEntry`; Firefox: `browsingContext.traverseHistory`) | Returns `{url,frameId,waitedFor}` (no auto-snapshot; a history move also returns `traversed:'back'\|'forward'`). `waitUntil` supports `load`/`domcontentloaded`. `reload:true` (+ `ignoreCache:true` for a hard reload). `url`/`reload`/`history` are mutually exclusive; going back from the first entry (or forward from the last) is an error naming the direction, never a silent no-op. Works on both backends. |
 | `wait_for` | `Runtime.evaluate` (poll `innerText`) | Text-substring waiting only; throws on timeout rather than returning `{found:false}`. |
-| `evaluate_script` | `Runtime.evaluate` / `callFunctionOn` | No live `page`/element handle; `args` are plain JSON. Main-world context only. Toolkit addition: optional `savePath` writes the value to a JSON file and keeps it out of the response entirely. If `expression` is missing/empty and the call instead carries `function`/`code`/`js`/`script`/`fn`/`body`, the error names the wrong key and points at `expression`. The one tool that also accepts `target: "worker:<substring>"` (Chrome only, capability `worker.targets`) to evaluate inside an MV3 extension's background service worker — see "Driving MV3 extensions" below. |
+| `evaluate_script` | `Runtime.evaluate` / `callFunctionOn` | No live `page`/element handle; `args` are plain JSON. Main-world context only. Toolkit addition: optional `savePath` writes the value to a JSON file and keeps it out of the response entirely. If `expression` is missing/empty and the call instead carries `function`/`code`/`js`/`script`/`fn`/`body`, the error names the wrong key and points at `expression`. One of four tools that also accept `target: "worker:<substring>"` (Chrome only, capability `worker.targets`) to reach an MV3 extension's background service worker — see "Driving MV3 extensions" below. |
 | `list_cookies` *(superset)* | `Network.getCookies` | Reads the target page's cookie store, httpOnly cookies included, which `document.cookie` and therefore `evaluate_script` cannot see. Page-scoped on purpose, not the browser-wide jar (`Storage.getCookies`), so it answers for the tab you named. Optional `domain`/`name` filters; optional `savePath` writes the array to a JSON file and returns `{path,bytes,count,target}` with no cookie value in the response. |
 | `set_cookie` *(superset)* | `Network.setCookie` | Writes one cookie, httpOnly and secure ones included, which `document.cookie` cannot create. Either `url` or `domain` is required and the call is refused with an error when neither is given. Chrome's `success:false` refusal is raised as an error rather than reported as a write. Answers `{set:true,target}` and never echoes the value back. `path` is passed through as given, never defaulted. |
 | `delete_cookies` *(superset)* | `Network.deleteCookies` | Removes the named cookie, httpOnly ones included. Requires `name` plus `url` or `domain`, so a name-only call cannot sweep the store; optional `path` narrows further. Answers `{deleted:true,target}` with no count, because neither protocol reports one; read `list_cookies` before and after for a real count. |
@@ -274,10 +274,10 @@ The 29 parity tools are 1:1 with `chrome-devtools-mcp`; the 16 superset tools (`
 | `emulate` | `Emulation.*` / `Network.emulateNetworkConditions` | Stateless: UA/CPU/media/network overrides reset when the per-call connection closes. No named device presets. |
 | `resize_page` | `Emulation.setDeviceMetricsOverride` | Verifies via `window.innerWidth/innerHeight`. Override persists on the target. |
 | `handle_dialog` | `Page.javascriptDialogOpening` / `handleJavaScriptDialog` | Caller arms first and triggers out-of-band (or `handleDialogForExpression` to trigger-and-handle atomically). Supports wait-for-next and auto-handle-for-N-ms. |
-| `list_console_messages` | `Runtime`/`Log` events (+ `Page.reload`) | `reload:true` records console+network into a unique per-capture file; default read returns the latest. Args flattened best-effort. |
-| `get_console_message` | reads the shared "latest" buffer | Index into the latest capture; throws if out of range. |
-| `list_network_requests` | `Network.*` events (+ `Page.reload`) | Correlated rows from the per-capture buffer; redirect chains collapse to the first row. No timing breakdown / POST data. |
-| `get_network_request` | above + `Network.getResponseBody` | Bodies only via a fresh reload capture (CDP serves bodies from the live session); `includeBody` matches by **url**. |
+| `list_console_messages` | `Runtime`/`Log` events (+ `Page.reload`, or LISTEN for `durationMs` on a worker target) | `reload:true` records console+network into a unique per-capture file; default read returns the latest. Args flattened best-effort. Accepts `target: "worker:<substring>"` (Chrome only) to capture an MV3 service worker's `console.log` — see "Driving MV3 extensions" below. |
+| `get_console_message` | reads the shared "latest" buffer | Index into the latest capture; throws if out of range. Resolves a worker-keyed buffer too, but is deliberately not advertised as worker-capable (see CHANGELOG 1.9.1). |
+| `list_network_requests` | `Network.*` events (+ `Page.reload`, or LISTEN for `durationMs` on a worker target) | Correlated rows from the per-capture buffer; redirect chains collapse to the first row. No timing breakdown / POST data. Accepts `target: "worker:<substring>"` (Chrome only) to capture the requests an MV3 service worker itself makes — see "Driving MV3 extensions" below. |
+| `get_network_request` | above + `Network.getResponseBody` | Bodies only via a fresh capture (CDP serves bodies from the live session); `includeBody` matches by **url**. Worker-capable, same as `list_network_requests`. |
 | `performance_start_trace` | `Tracing.start` / `dataCollected` | Works ONLY within one process; a live trace buffer is bound to its connection. Use `performance_trace` for robustness. |
 | `performance_stop_trace` | `Tracing.end` / `tracingComplete` | Must run in the SAME process as `performance_start_trace`; throws a clear error otherwise. |
 | `performance_analyze_insight` | parses a trace JSON file | A **CDP-native approximation** of the MCP insight analyzer (FCP/LCP/CLS/TBT/long-tasks); close but not byte-identical. Requires an explicit `tracePath`. |
@@ -295,7 +295,7 @@ The 29 parity tools are 1:1 with `chrome-devtools-mcp`; the 16 superset tools (`
 
 ## Driving MV3 extensions
 
-An MV3 extension's logic lives in a background **service worker**, not a page, so `chrome.storage.local`, `chrome.runtime`, and everything else the extension owns is unreachable through a page-typed selector. `evaluate_script` is the one tool that also accepts `target: "worker:<substring>"` (Chrome only, capability `worker.targets`) — any substring of the worker's url, so `worker:<extension-id>` and `worker:background.js` both work:
+An MV3 extension's logic lives in a background **service worker**, not a page, so `chrome.storage.local`, `chrome.runtime`, and everything else the extension owns is unreachable through a page-typed selector. Four tools accept `target: "worker:<substring>"` (Chrome only, capability `worker.targets`) — `evaluate_script`, and, as of 1.9.1, `list_network_requests`, `get_network_request`, and `list_console_messages` — any substring of the worker's url, so `worker:<extension-id>` and `worker:background.js` both work:
 
 ```json
 {"tool": "evaluate_script", "arguments": {"target": "worker:ekgaohljhieodkfggjkfgmmamfpngdhn", "expression": "chrome.storage.local.get()", "args": []}}
@@ -306,9 +306,23 @@ A few facts worth knowing before you reach for it, all measured against a real b
 - **An idle MV3 worker is evicted within seconds of its last activity, and once evicted it is invisible to every target listing** — not "stopped and still visible," genuinely absent from `/json/list` and `Target.getTargets` under any filter. So a `worker:` miss almost always means "asleep," not "wrong id," and the error says so.
 - **`wake` defaults to `true`:** a selector that matches nothing, or a known-but-stopped worker, is started for you first, then re-resolved. Pass `wake:false` to fail fast instead — the error then teaches the eviction fact rather than reading like a typo.
 - **A wake is verified by re-reading the target list, never by the start command's own result** — Chrome's start command reports success even for a scope that doesn't exist, so nothing here trusts it.
-- **Worker targets bypass the lease gate entirely.** `claim_page`/strict mode never mint a lease for a worker evaluate; a worker id is Chrome's to create and destroy, not this toolkit's to fence.
+- **Worker targets bypass the lease gate entirely.** `claim_page`/strict mode never mint a lease for a worker-targeted call, on any of the four tools; a worker id is Chrome's to create and destroy, not this toolkit's to fence.
 - **If you're loading your own unpacked extension for testing, `--load-extension` does nothing on recent Chrome**, even with the documented unblock flag. Use `Extensions.loadUnpacked` over CDP instead (what this toolkit's own extension smoke does).
 - **The extension id is a hash of the unpacked extension's absolute path**, so it's deterministic across loads from the same directory but differs from the id a packed/store install would get — don't hardcode an id copied from a different machine's path.
+- **Before deep-debugging something that looks like "the toolkit can't see it," check you're driving the build you think you are:** `evaluate_script {target:"worker:<id>", expression:"chrome.runtime.getManifest().version"}`. Chrome keeps serving a stale unpacked build's worker until you explicitly reload the extension, and an outdated loaded build mimics every symptom below.
+
+### Watching what a worker sends and logs (1.9.1)
+
+`list_network_requests`, `get_network_request`, and `list_console_messages` record a worker the same way they record a page — over the worker's own CDP session, the same `Network`/`Runtime` domains, the same `get_*` follow-up for bodies — with one difference: a worker capture can't be driven by reload. Measured against Chrome 151.0.7922.109: `Page.enable`/`Page.reload` don't exist on a worker session (`-32601 'Page.enable' wasn't found`), so a worker capture LISTENS for `durationMs` instead of reloading; `Network.requestWillBeSent`/`responseReceived`/`loadingFinished` and `Runtime.consoleAPICalled` all arrive on that same session, and `Network.getResponseBody` serves the body, exactly like a page capture.
+
+```json
+{"tool": "list_network_requests", "arguments": {"target": "worker:ekgaohljhieodkfggjkfgmmamfpngdhn", "reload": true, "durationMs": 5000}}
+```
+
+- **Recording a worker keeps it alive for the length of the capture — a documented side effect, not a bug.** A held CDP session suppresses MV3 idle eviction (measured: alive and still emitting events at 60s held; evicted ~30s after the recorder detaches). Watch a worker and Chrome won't put it to sleep out from under you until you stop.
+- **`wake` (default `true` on a capture) is refused on a read-only call and on a bare target id**, rather than accepted and quietly doing nothing useful. A worker that idle-evicts and restarts comes back under a brand-new target id (measured: re-minted on every restart), and the buffer is keyed by id, so waking on a *read* would hand back a live worker with an empty buffer — "0 requests" for a capture that really did record some, a zero shaped like an answer. Re-run with `reload:true` to record a fresh capture instead.
+- **A worker woken by the capture has already run its top-level code by the time the recorder attaches**, so a fetch it makes at startup can be missed. Trigger the request you want to observe (a message, an alarm) after the capture starts rather than relying on the worker's own boot-time fetch.
+- **A `self.fetch` monkeypatch via `evaluate_script` won't reliably intercept a worker's requests, and reading a module-scoped value from `evaluate_script` won't reliably work either — both for ordinary JavaScript reasons, not a service-worker-specific one.** A value bound at module top level is not visible from `evaluate_script`'s global scope (plain lexical scoping, identical in a page); assigning `self.fetch` cannot rebind a `fetch` reference the module already captured (closure semantics, also identical in a page). `list_network_requests`/`get_network_request` observe the `Network` domain on the worker's own session directly and need neither.
 
 `worker:` is deliberately absent everywhere else — `close_page`/`select_page`/`release_page` and `claim_page`'s `target` stay page-only, refusing the arm by name rather than silently missing, and Firefox refuses it with a capability error (`worker.targets`), since WebDriver BiDi has no extension-service-worker target to map onto.
 

package/dist/cli.js

@@ -406,6 +406,12 @@ async function resolveLiveLabel(backend, label, liveIds) {
 
 // src/workers.ts
 var WORKER_SELECTOR_PREFIX = "worker:";
+var WORKER_CAPABLE_TOOLS = [
+  "evaluate_script",
+  "list_network_requests",
+  "get_network_request",
+  "list_console_messages"
+];
 var WORKER_TARGET_TYPES = new Set(["service_worker", "shared_worker"]);
 function isWorkerSelector(selector) {
   return typeof selector === "string" && selector.startsWith(WORKER_SELECTOR_PREFIX);
@@ -424,8 +430,18 @@ function resolveWorkerTargets(targets, needle) {
   };
 }
 var WORKER_EMPTY_NEEDLE_MESSAGE = "'worker:' needs a substring of the worker's url, e.g. worker:<extension-id> or worker:background.js";
-var 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.";
-var 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.";
+var 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, or record console/network from, an extension's background worker.";
+var 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). The tools that accept a worker: target are " + `${WORKER_CAPABLE_TOOLS.join(", ")}.`;
+function workerWakeMisuseMessage(kind) {
+  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.";
+}
+function workerBufferReadMissMessage(needle, liveWorkers) {
+  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) {
   return workers.map((w) => w.url).join(", ");
 }
@@ -2840,6 +2856,31 @@ function captureFile(targetId, captureId) {
 function delay2(ms) {
   return new Promise((r) => setTimeout(r, ms));
 }
+async function resolveRecorderTarget(target, opts) {
+  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));
+}
+function assertWakeApplies(target, wake, capture) {
+  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"));
+}
 var NETWORK_EVENTS = [
   "Network.requestWillBeSent",
   "Network.responseReceived",
@@ -2905,7 +2946,8 @@ async function startRecorder(target, opts = {}) {
   };
 }
 async function captureWindow(target, durationMs, opts = {}) {
-  const resolved = await resolveTarget(target);
+  const resolved = await resolveRecorderTarget(target, { capture: true, wake: opts.wake });
+  const isWorker = isWorkerTargetType(resolved.type);
   const captureId = `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
   const file = captureFile(resolved.id, captureId);
   const rec = await startRecorder(resolved.id, {
@@ -2915,13 +2957,16 @@ async function captureWindow(target, durationMs, opts = {}) {
     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 delay2(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() {
@@ -3021,8 +3066,9 @@ async function readConsoleEntries(file) {
   return out;
 }
 async function listConsoleMessages(args = {}) {
+  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 messages2 = await readConsoleEntries(cap.file);
     return {
@@ -3032,7 +3078,7 @@ async function listConsoleMessages(args = {}) {
       droppedWrites: cap.droppedWrites()
     };
   }
-  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 },
@@ -3041,7 +3087,7 @@ async function listConsoleMessages(args = {}) {
   };
 }
 async function getConsoleMessage(args = {}) {
-  const target = await resolveTarget(args.target);
+  const target = await resolveRecorderTarget(args.target, { capture: false });
   const messages = await readConsoleEntries(recFile(target.id));
   const index = args.index ?? 0;
   const entry = messages[index];
@@ -3139,14 +3185,15 @@ async function listNetworkRequests(args = {}) {
   let file;
   let resolved;
   let droppedWrites;
+  assertWakeApplies(args.target, args.wake, args.reload === true);
   if (args.reload) {
-    const cap = await captureWindow(args.target, args.durationMs ?? DEFAULT_CAPTURE_MS2);
+    const cap = await captureWindow(args.target, args.durationMs ?? DEFAULT_CAPTURE_MS2, { 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 };
   }
@@ -3167,8 +3214,9 @@ async function getNetworkRequest(args = {}) {
     return requests.find((r) => r.url.includes(args.url));
   };
   const describeSelector = () => args.requestId ? `requestId ${args.requestId}` : `url ~ '${args.url}'`;
+  assertWakeApplies(args.target, args.wake, Boolean(args.includeBody && args.url));
   if (args.includeBody && args.url) {
-    const cap = await captureWindow(args.target, args.durationMs ?? DEFAULT_CAPTURE_MS2);
+    const cap = await captureWindow(args.target, args.durationMs ?? DEFAULT_CAPTURE_MS2, { wake: args.wake });
     try {
       await cap.flush();
       const match2 = (await readNetworkRequests(cap.file)).find((r) => r.url.includes(args.url));
@@ -3185,7 +3233,7 @@ async function getNetworkRequest(args = {}) {
       await cap.stop();
     }
   }
-  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(`no network request matched ${describeSelector()}; run list_network_requests with reload:true first` + (args.includeBody ? `, then fetch the body with the url selector (reload re-mints requestIds)` : ``));
@@ -5993,6 +6041,11 @@ async function withPage3(driver, target, fn) {
 }
 var consoleBuffers = new Map;
 var networkBuffers = new Map;
+function refuseWorkerSelector(driver, target) {
+  if (isWorkerSelector(target) && !driver.capabilities.has("worker.targets")) {
+    throw new BidiToolError(WORKER_SELECTOR_UNSUPPORTED_MESSAGE);
+  }
+}
 function bufferFor(map, id) {
   let b = map.get(id);
   if (!b) {
@@ -6021,6 +6074,7 @@ async function captureFresh(page, durationMs) {
   }
 }
 async function listConsoleMessages2(driver, args = {}) {
+  refuseWorkerSelector(driver, args.target);
   return withPage3(driver, args.target, async (page) => {
     if (args.reload)
       await captureFresh(page, args.durationMs ?? 2500);
@@ -6029,6 +6083,7 @@ async function listConsoleMessages2(driver, args = {}) {
   });
 }
 async function getConsoleMessage2(driver, args = {}) {
+  refuseWorkerSelector(driver, args.target);
   return withPage3(driver, args.target, async (page) => {
     const buf = bufferFor(consoleBuffers, page.info.id);
     const idx = args.index ?? 0;
@@ -6039,6 +6094,7 @@ async function getConsoleMessage2(driver, args = {}) {
   });
 }
 async function listNetworkRequests2(driver, args = {}) {
+  refuseWorkerSelector(driver, args.target);
   return withPage3(driver, args.target, async (page) => {
     if (args.reload)
       await captureFresh(page, args.durationMs ?? 2500);
@@ -6049,6 +6105,7 @@ async function listNetworkRequests2(driver, args = {}) {
   });
 }
 async function getNetworkRequest2(driver, args = {}) {
+  refuseWorkerSelector(driver, args.target);
   if (!args.requestId && !args.url)
     throw new BidiToolError("get_network_request requires requestId or url");
   return withPage3(driver, args.target, async (page) => {
@@ -6161,8 +6218,10 @@ zero behavior change for existing users). Firefox is LAUNCHED per invocation (it
 to), used for exactly one tool call, then disposed before the process exits.
 
 Target selector grammar: active | index:N | url:<substr> | title:<substr> | label:<name> | <targetId>
-  plus worker:<substr> for evaluate_script ONLY (Chrome only): an MV3 extension's background service
-  worker, e.g. worker:<extension-id>. An idle-evicted worker is started first unless wake:false.
+  plus worker:<substr> (Chrome only) for evaluate_script, list_network_requests, get_network_request
+  and list_console_messages ONLY: an MV3 extension's background service worker, e.g.
+  worker:<extension-id>. An idle-evicted worker is started first unless wake:false. Recording a
+  worker keeps it alive for the length of the capture.
 Leases: pass --lease <token> to act on a tab another agent claimed with claim_page (MCP only).
 Run list_leases to see who holds what; release_page --lease <token> gives a lease back.
 Run with --list to print every tool name available under the selected backend.

package/dist/index.js

@@ -404,6 +404,12 @@ async function resolveLiveLabel(backend, label, liveIds) {
 
 // src/workers.ts
 var WORKER_SELECTOR_PREFIX = "worker:";
+var WORKER_CAPABLE_TOOLS = [
+  "evaluate_script",
+  "list_network_requests",
+  "get_network_request",
+  "list_console_messages"
+];
 var WORKER_TARGET_TYPES = new Set(["service_worker", "shared_worker"]);
 function isWorkerSelector(selector) {
   return typeof selector === "string" && selector.startsWith(WORKER_SELECTOR_PREFIX);
@@ -422,8 +428,18 @@ function resolveWorkerTargets(targets, needle) {
   };
 }
 var WORKER_EMPTY_NEEDLE_MESSAGE = "'worker:' needs a substring of the worker's url, e.g. worker:<extension-id> or worker:background.js";
-var 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.";
-var 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.";
+var 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, or record console/network from, an extension's background worker.";
+var 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). The tools that accept a worker: target are " + `${WORKER_CAPABLE_TOOLS.join(", ")}.`;
+function workerWakeMisuseMessage(kind) {
+  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.";
+}
+function workerBufferReadMissMessage(needle, liveWorkers) {
+  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) {
   return workers.map((w) => w.url).join(", ");
 }
@@ -2838,6 +2854,31 @@ function captureFile(targetId, captureId) {
 function delay2(ms) {
   return new Promise((r) => setTimeout(r, ms));
 }
+async function resolveRecorderTarget(target, opts) {
+  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));
+}
+function assertWakeApplies(target, wake, capture) {
+  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"));
+}
 var NETWORK_EVENTS = [
   "Network.requestWillBeSent",
   "Network.responseReceived",
@@ -2903,7 +2944,8 @@ async function startRecorder(target, opts = {}) {
   };
 }
 async function captureWindow(target, durationMs, opts = {}) {
-  const resolved = await resolveTarget(target);
+  const resolved = await resolveRecorderTarget(target, { capture: true, wake: opts.wake });
+  const isWorker = isWorkerTargetType(resolved.type);
   const captureId = `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
   const file = captureFile(resolved.id, captureId);
   const rec = await startRecorder(resolved.id, {
@@ -2913,13 +2955,16 @@ async function captureWindow(target, durationMs, opts = {}) {
     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 delay2(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() {
@@ -3019,8 +3064,9 @@ async function readConsoleEntries(file) {
   return out;
 }
 async function listConsoleMessages(args = {}) {
+  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 messages2 = await readConsoleEntries(cap.file);
     return {
@@ -3030,7 +3076,7 @@ async function listConsoleMessages(args = {}) {
       droppedWrites: cap.droppedWrites()
     };
   }
-  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 },
@@ -3039,7 +3085,7 @@ async function listConsoleMessages(args = {}) {
   };
 }
 async function getConsoleMessage(args = {}) {
-  const target = await resolveTarget(args.target);
+  const target = await resolveRecorderTarget(args.target, { capture: false });
   const messages = await readConsoleEntries(recFile(target.id));
   const index = args.index ?? 0;
   const entry = messages[index];
@@ -3137,14 +3183,15 @@ async function listNetworkRequests(args = {}) {
   let file;
   let resolved;
   let droppedWrites;
+  assertWakeApplies(args.target, args.wake, args.reload === true);
   if (args.reload) {
-    const cap = await captureWindow(args.target, args.durationMs ?? DEFAULT_CAPTURE_MS2);
+    const cap = await captureWindow(args.target, args.durationMs ?? DEFAULT_CAPTURE_MS2, { 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 };
   }
@@ -3165,8 +3212,9 @@ async function getNetworkRequest(args = {}) {
     return requests.find((r) => r.url.includes(args.url));
   };
   const describeSelector = () => args.requestId ? `requestId ${args.requestId}` : `url ~ '${args.url}'`;
+  assertWakeApplies(args.target, args.wake, Boolean(args.includeBody && args.url));
   if (args.includeBody && args.url) {
-    const cap = await captureWindow(args.target, args.durationMs ?? DEFAULT_CAPTURE_MS2);
+    const cap = await captureWindow(args.target, args.durationMs ?? DEFAULT_CAPTURE_MS2, { wake: args.wake });
     try {
       await cap.flush();
       const match2 = (await readNetworkRequests(cap.file)).find((r) => r.url.includes(args.url));
@@ -3183,7 +3231,7 @@ async function getNetworkRequest(args = {}) {
       await cap.stop();
     }
   }
-  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(`no network request matched ${describeSelector()}; run list_network_requests with reload:true first` + (args.includeBody ? `, then fetch the body with the url selector (reload re-mints requestIds)` : ``));