cdp-toolkit 1.8.0 → 1.9.1

package/CHANGELOG.md

@@ -5,6 +5,241 @@ 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
+a tool: the surface grows inside `evaluate_script`, the `target` selector
+grammar, and error DX. Tool count stays 45. Two seats landed sequentially —
+W2 (`label:` + key-echo) first, W1 (worker targets + idle-wake) on top of it —
+and every protocol assertion below was probed against a live Chrome 151 before
+being built on, because five 1.8.0 premises were folklore that measured false.
+
+### Added
+
+- **`label:<name>` in the target-selector grammar, universal across every
+  page-taking tool.** Resolves an exact label match against BOTH the origin
+  ledger (tabs this toolkit created) and live lease records (a tab taken over
+  and claimed with a label, which has no origin record) — so a tab you named
+  is findable by that name regardless of which path put you in it. A miss
+  enumerates the labels that DO exist, deduped across both sources; an
+  ambiguity (the same label on two live targets) names both ids rather than
+  silently picking the first. **The grammar turned out to have three
+  independent copies** — `pickPage` (`src/shared-tools.ts`), `pickTarget`
+  (`src/client.ts`, the one `evaluate_script`/`click`/`hover`/… actually call),
+  and `pickContext` (`src/bidi/driver.ts`, Firefox) — a fact the live smoke
+  caught immediately when `label:` worked in `claim_page` but not in
+  `evaluate_script`. The lookup core is now one function, `resolveLiveLabel`
+  in `src/origins.ts`, wired into all three call sites, each keeping its own
+  error class. A new structural test, `test/manifest-grammar-drift.test.ts`,
+  asserts every manifest description that names `title:` also names `label:`,
+  so a fourth resolver copy (or a stale description) can't slip past review
+  silently again.
+
+- **Key-echo validation on `evaluate_script`.** When `expression` is missing
+  or empty and the call instead carries `function`, `code`, `js`, `script`,
+  `fn`, or `body`, the error names the wrong key by value and says the right
+  one is `expression` — and, when the value looks like a function literal,
+  that function literals go in `expression` with `args`. One line, saving the
+  round trip the field complaint measured.
+
+- **`evaluate_script` can now evaluate inside an MV3 extension's background
+  SERVICE WORKER, not just a page — no raw-CDP escape hatch needed.** Pass
+  `target: "worker:<extension-id>"` (or any substring of the worker's url,
+  e.g. `worker:background.js`) and read `chrome.storage.local`,
+  `chrome.runtime`, and the worker's own globals directly. Chrome-only
+  (capability `worker.targets`) and accepted by `evaluate_script` alone —
+  `worker:` is deliberately absent from `pickPage`'s page-only grammar
+  (closing/selecting/releasing a worker is meaningless) and refused there by
+  name, and a new drift-test arm asserts no OTHER tool's manifest description
+  ever names `worker:<`, so a later sweep can't advertise a Chrome-only,
+  one-tool selector as universal grammar. Firefox refuses the arm with a
+  capability-gap error naming `worker.targets`, per ADR-001 — WebDriver BiDi
+  has no extension-service-worker target concept to map onto.
+  **`wake` (default `true`)** asks Chrome to start the worker first when the
+  selector matches nothing or a known-but-stopped worker, then re-resolves;
+  `wake:false` fails fast with an error that teaches the MV3 eviction fact
+  instead of a bare "not found". Worker targets bypass the lease gate
+  entirely (`assertLeaseOk` is skipped for a worker-typed resolution in
+  `client.ts`): reap's "close the stale tab" is meaningless for a target
+  Chrome starts and stops on its own, and strict mode auto-acquiring a lease
+  per evaluate would mint a file keyed on an id that vanishes at the next
+  idle — garbage the page-only reap set can never collect. The page-only id
+  set reap and leases already keep (`ReapInput.livePageIds`) was left
+  unmerged on purpose.
+
+### Measured, not assumed — the protocol facts this release ships on
+
+Every one of these was a hypothesis in the spec and a measurement against a
+live Chrome 151.0.7922.109 before any line of feature code was written:
+
+- **`evaluate_script` against a worker never needs a flattened browser
+  session.** `/json/list` exposes a running service worker with its own
+  `webSocketDebuggerUrl`, and a direct WebSocket connect + `Runtime.evaluate`
+  with `awaitPromise` works there exactly as it does against a page — proven
+  by `self.constructor.name === "ServiceWorkerGlobalScope"` in the same
+  round trip. The feature rides the existing per-target connect path with no
+  new connection model.
+- **The "awaited value is lost over a flattened session" folklore is false on
+  Chrome 151, measured anyway even though it turned out not to matter.**
+  `Target.attachToTarget{flatten:true}` against the same worker returns the
+  real awaited value too. **No warning was shipped for a loss that cannot be
+  triggered.**
+- **A stopped MV3 worker is invisible to every target listing — `/json/list`
+  and `Target.getTargets` under any filter — so "no such worker" almost
+  always means "idle-evicted," not "wrong id."** The only place a stopped
+  worker is visible at all is the registration inventory
+  `ServiceWorker.enable` pushes as events, which is why the miss/wake error
+  text says so explicitly.
+- **`ServiceWorker.enable`/`startWorker` do not exist on the browser
+  endpoint** (`-32601 wasn't found`) — **they work on a flattened session over
+  any page**, including a plain `about:blank` tab with no relationship to the
+  extension. That's the wake mechanism: attach to whichever page target
+  happens to be open, enable the domain there, start the matched scope.
+- **`startWorker` reports empty success for a scope that does not exist at
+  all** — its return value is worthless as proof a worker woke. A wake is
+  therefore verified only by re-reading the target list until the worker
+  reappears (bounded, 30 × 300ms), never by the command's own result.
+- **`--load-extension` is inert on Chrome 151**, even with the documented
+  `--disable-features=DisableLoadExtensionCommandLineSwitch` unblock flag —
+  confirmed by checking the ServiceWorker registration inventory, which would
+  show a stopped-but-installed extension even if nothing were running, and
+  showed nothing at all. `Extensions.loadUnpacked` over CDP is the install
+  path that actually works, and is what the new extension smoke and any
+  future extension testing with this toolkit should use. `--headless=new` is
+  fine for driving an extension; no headed instance is required.
+
+### Notes
+
+- Tool count is unchanged at **45** — this release grew `evaluate_script` and
+  the target-selector grammar, not the tool list.
+- `docs/social-preview.html` and `docs/demo.tape` carry no version string and
+  needed no re-render for this release.
+- New tests: `test/label-selector.test.ts`, `test/worker-selector.test.ts`,
+  two new arms in `test/manifest-grammar-drift.test.ts` (inclusion for
+  `label:`, exclusion for `worker:`), and a new live smoke,
+  `test/extension-smoke.ts`, against a fixture MV3 extension in
+  `test/fixtures/mv3-extension/` — 20/20 assertions, including a genuine idle
+  eviction (worker absence from `/json/list` asserted before waking) and a
+  strict-mode check that a worker evaluate mints zero lease files while a
+  page evaluate in the same run still mints one.
+
 ## [1.8.0] - 2026-08-09
 
 Two tracks land together, merged onto one integration branch. Track S closes the
@@ -752,6 +987,8 @@ 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
 [1.6.0]: https://github.com/sblattj/cdp-toolkit/releases/tag/v1.6.0

package/CONTRACT.md

@@ -18,6 +18,10 @@ 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`; 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:` (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.
 
 ## Core client API (from `src/client.ts`)
@@ -113,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

@@ -128,7 +128,7 @@ bun run mcp:smoke   # spawn the server + a real initialize/tools-list/tools-call
 
 Each point below leads with the symptom you've probably hit, then the cause, then the fix.
 
-- **Your agent stalls on a call when a busy background tab is open** → that's the **all-target fan-out**: every operation broadcasts to all attached targets. every cdp-toolkit call resolves *one* target (`active | index:N | url:<substr> | title:<substr> | <targetId>`) and attaches a single WebSocket to just that page, so a busy tab you did not name is never touched.
+- **Your agent stalls on a call when a busy background tab is open** → that's the **all-target fan-out**: every operation broadcasts to all attached targets. every cdp-toolkit call resolves *one* target (`active | index:N | url:<substr> | title:<substr> | label:<name> | <targetId>`) and attaches a single WebSocket to just that page, so a busy tab you did not name is never touched.
 - **A tool hangs forever and never returns** → the MCP's eager `Network.enable` on a busy or hung renderer is a known wedge. cdp-toolkit enables domains **lazily**, only where a tool needs them (the recorder enables `Network`/`Runtime`/`Log`; most tools touch only `Page`/`Runtime`/`DOM`).
 - **No way to bound a slow call** → `CdpConnection.send()` enforces `CDP_TIMEOUT_MS` (15s default) on *every* command and **rejects rather than hangs**, so a stuck renderer can never block a caller indefinitely.
 - **Element handles drift across calls** → a `uid` **is** a CDP `backendDOMNodeId`, resolved on demand via `DOM.resolveNode`. There is no server-side handle table to drift or expire.
@@ -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. |
+| `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`. |
@@ -293,6 +293,39 @@ The 29 parity tools are 1:1 with `chrome-devtools-mcp`; the 16 superset tools (`
 | `wait_for_download` *(superset)* | `Browser.setDownloadBehavior` + `Browser.downloadWillBegin`/`downloadProgress` on a standing browser-endpoint connection | Waits for a download to finish and returns it as a real file on disk: `{path,suggestedFilename,bytes,url,target}`. **Ordering rule, not optional:** call `wait_for_download{arm:true}` *before* the click that starts the download, then click, then call `wait_for_download` again to collect it — arming this late is not a preference, it's because Chrome reverts the download-behavior override the instant the arming client disconnects, and denies an unarmed download outright. **Browser-global side effect:** while armed, *every* download in the browser is redirected into the toolkit's downloads directory. **MCP-server only:** the arm lives on a connection this server process holds open; the one-shot CLI's connection dies with the process, so nothing is captured there. Chrome-only (`browser.downloads`). |
 | `grant_permissions` *(superset)* | `Browser.grantPermissions` / `Browser.resetPermissions` on the same standing connection | Grants permissions (`geolocation`, `notifications`, `clipboardReadWrite`, ...) for an origin up front, so a page doesn't show a prompt no agent can click. Keyed by **origin**, not tab — every tab on that origin is affected, including ones opened later. `reset:true` clears this server's previous grants first (or instead); note CDP's reset is not origin-scoped, so it clears every origin at once. Same MCP-server-only reasoning as `wait_for_download`: Chrome discards the grant the moment the granting connection closes. Chrome-only (`browser.permissions`). |
 
+## 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. 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": []}}
+```
+
+A few facts worth knowing before you reach for it, all measured against a real browser rather than assumed:
+
+- **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-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.
+
 ## Parallel tabs: many agents, one browser
 
 Two agents pointed at the same Chrome both resolve `target: active` to whatever tab the human last focused. Nothing errors. Each one gets plausible, well-formed output from the wrong page: a snapshot of someone else's form, a fill that lands in someone else's field. A crash gets caught; a silent wrong-tab success does not.
@@ -320,11 +353,11 @@ That auto-acquired lease is a weaker tier than an explicit one, and the differen
 - **Auto** (acquired by the gate, or by `new_page` without `claim:true`): owned by a *process*. Any later call from the same pid passes with no `lease` argument at all; only another process is refused.
 - **Explicit** (`claim_page`, or `new_page{claim:true}`): still demands its token on every call, even from the process that claimed it. This is how one subagent fences a tab off from sibling subagents that share its pid, since a Claude Code session's subagents all run inside one MCP server process.
 
-An unleased tab under strict mode is still refused to a different process exactly as under the default: the tab's whole selector surface (`active`, no target, `index:N`, `url:`, `title:`, a bare targetId) all resolve through the same gate, so there is no selector form that quietly bypasses acquisition. Turning `CDP_REQUIRE_LEASE` off never locks a process out of leases it already holds: the pid-only check on an auto lease is not itself gated on the flag, only the *acquiring* is.
+An unleased tab under strict mode is still refused to a different process exactly as under the default: the tab's whole selector surface (`active`, no target, `index:N`, `url:`, `title:`, `label:`, a bare targetId) all resolve through the same gate, so there is no selector form that quietly bypasses acquisition. Turning `CDP_REQUIRE_LEASE` off never locks a process out of leases it already holds: the pid-only check on an auto lease is not itself gated on the flag, only the *acquiring* is.
 
 **Strict mode is MCP-only, unconditionally, not by convention.** The CLI never reads `CDP_REQUIRE_LEASE` as true no matter how it is set, because a CLI invocation is one process per call: a lease it auto-acquired would be reclaimable by the dead-pid rule the instant that process exited, which is a worse position than no lease at all, and reap (below) would then read that instantly-dead-pid record as an abandoned agent tab and could close it the next time anything lists pages.
 
-**What can newly fail.** Any call that resolves to a leased tab without presenting that tab's token is refused, naming the tab, its url, and the label of whoever holds it. That is every selector form, not one of them: `active` or no target at all, `index:N`, `url:<substring>`, `title:<substring>`, and a bare targetId all reach the same check. The case worth singling out is `active` (or no target) against a leased tab index 0, because there you did not name the tab and before 1.2 the call silently succeeded against whatever tab happened to be first. That refusal is the point of the feature, and it is called out here rather than left to be discovered.
+**What can newly fail.** Any call that resolves to a leased tab without presenting that tab's token is refused, naming the tab, its url, and the label of whoever holds it. That is every selector form, not one of them: `active` or no target at all, `index:N`, `url:<substring>`, `title:<substring>`, `label:<name>`, and a bare targetId all reach the same check. The case worth singling out is `active` (or no target) against a leased tab index 0, because there you did not name the tab and before 1.2 the call silently succeeded against whatever tab happened to be first. That refusal is the point of the feature, and it is called out here rather than left to be discovered.
 
 **Reclamation.** A lease is reclaimable when its owning process is gone, or when `lastUsedAt` is older than `ttlMs` (default 15 minutes, `CDP_LEASE_TTL_MS`). Those two are the whole list. A lease whose tab is no longer open is *reported* by `list_leases` as `target-gone`, which is useful to see, but that report is not what frees it: such a record is freed by the same two rules as any other, whichever lands first. Every checked call refreshes `lastUsedAt`, so an agent that is working never expires and no heartbeat is needed. Reclaiming mints a fresh nonce, which invalidates the previous owner's token: a stalled agent that comes back cannot keep driving a tab someone else now owns. This applies equally to an auto lease and an explicit one; the tier only changes who may use the lease without a token, never how or when it goes stale.