cdp-toolkit 1.11.0 → 2.0.0

package/CHANGELOG.md

@@ -5,6 +5,46 @@ 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).
 
+## [2.0.0] - 2026-08-29
+
+**Progressive disclosure: the default `tools/list` an agent loads shrinks ~88% (≈20,200 → ≈2,500 tokens) to 12 core tools plus two meta-tools, with the full 45-tool surface, and the full per-tool documentation, one `browser_tools` call away.** This is the first npm publication since 1.11.0, so it also **carries the [1.11.1] changes below** (the two Firefox BiDi navigation fixes) that landed on main but were never released. Tool names, parameters, and schema shapes are unchanged — a strip-descriptions deep-equal of the manifest gates the change, the same check 1.10.0 used.
+
+### Added
+
+- **Tool profiles + on-demand group activation.** The server now starts on the `core` profile (`list_pages`, `new_page`, `close_page`, `select_page`, `navigate_page`, `wait_for`, `take_snapshot`, `click`, `fill`, `type_text`, `evaluate_script`, `take_screenshot`) and holds the other 33 tools in 12 activatable groups (`src/toolGroups.ts`). `CDP_TOOL_PROFILE=full` advertises everything at startup — the exact prior behavior. Profiles are MCP-only; the CLI still exposes all 45 tools.
+- **`browser_tools` meta-tool** — `list_groups` (every group, its tools, active state), `activate`/`deactivate` (toggle one group), `set_profile` (core|full wholesale). Any change fires `notifications/tools/list_changed` so the client re-fetches `tools/list`; the server now declares `tools.listChanged: true`.
+- **`describe_tool` meta-tool** — full description and per-parameter docs for any tool by name, *including tools not currently listed* (`src/toolDocs.ts`, generated verbatim from the pre-2.0 manifest prose). Call it before using an unfamiliar tool; the live listing carries only terse summaries.
+- Environment knob: `CDP_TOOL_PROFILE` (`core` default, `full` = prior behavior).
+- The server `instructions` block now front-loads the disclosure model: core profile at startup, `browser_tools` to activate, `describe_tool` for full docs, hidden tools still callable by name.
+
+### Changed
+
+- **The manifest advertised over `tools/list` now carries terse one-line descriptions; the full prose moved to `describe_tool`.** Description text drops 61,002 → 14,077 chars; the full 45-tool payload would be ~8.5k tokens (−58% vs 1.x) and the default surface ~2.5k (−88%). Schema shapes are untouched. Hidden does not mean disabled: a hidden-but-available tool called by name still executes — only discovery is gated.
+- **MCP SDK 1.29 → 2.0.** The runtime dependency is now `@modelcontextprotocol/server@^2.0.0` (the SDK 2.0 package split), with `@modelcontextprotocol/client@^2.0.0` as a devDependency powering the in-process client tests; `scripts/build.ts` keeps the SDK external under the new package name.
+- **Tests re-pointed, guarantees preserved.** Every description assertion in `test/` now reads `TOOL_DOCS` instead of the manifest (worker-capture traps, HTML5 drag modes, lease semantics, the 500ms probe bound — all still asserted, relocated), and `test/origins.test.ts` now proves the "origin is never 'human'" vocabulary is reachable end-to-end through `describe_tool` over a real stdio MCP connection.
+- Repo hygiene: the private `.cbm-atlas`/`.cbmignore` indexing artifacts and one internal design plan doc are no longer tracked.
+
+### Fixed
+
+- Seven one-line manifest descriptions that a mechanical compression pass had corrupted with copy-paste text from unrelated tools (`fill.value`, `fill_form.fields[].value`, `emulate.mediaFeatures` item name/value, `mock_request.action`, `lighthouse_audit.categories`, `clear_mocks.all`, `list_mocks.target`) now carry their correct terse wording, derived from the preserved `TOOL_DOCS` prose.
+- The runtime version constant (`src/mcp.ts` `VERSION`) had drifted from `package.json` since 1.11.0; both now read from the same release.
+
+## [1.11.1] - 2026-08-25
+
+**Two Firefox BiDi navigation fixes: every plain `reload:true` no longer fails, and `file://` navigation gets automation-pref parity plus an actionable error when the OS still refuses.** Chrome behavior is unchanged. The tool surface is unchanged (45 tools).
+
+### Fixed
+
+- **Every plain `reload:true` on Firefox failed with `Argument "ignoreCache" is not supported yet`.** `browsingContext.reload` was sent `ignoreCache: false` unconditionally, and Firefox's BiDi server rejects the KEY regardless of value — so the default reload path, not just hard reloads, was broken on the Firefox backend. The key is now omitted from the params entirely on plain reloads, and an explicit `ignoreCache: true` fails fast with a clear backend-capability error (the same doctrine as `click`'s modifiers) instead of an opaque mid-flight protocol rejection. The `navigate_page` manifest and docs now state the Firefox limitation up front.
+- **#6 — `file://` navigation on the Firefox backend.** Two parts, with their evidentiary limits stated:
+  - Launched-Firefox profiles now carry Mozilla's automation prefs. Firefox's Remote Agent has its own recommended automation bundle, but it is gated on `remote.prefs.recommended`, which DEFAULTS TO FALSE (verified in mozilla-central's `remote/shared/RecommendedPreferences.sys.mjs`) — so a bare `--remote-debugging-port` launch ran with consumer prefs while every geckodriver/Marionette-class setup applies the bundle. `launch.ts` now seeds `user.js` into every throwaway profile with `remote.prefs.recommended: true` plus `security.fileuri.strict_origin_policy: false` and `dom.file.createInChild: true` (the latter is the pref Marionette's own `geckoinstance.py` sets). An explicit `profilePath` is deliberately NOT mutated — it belongs to its owner.
+  - `NS_ERROR_FILE_ACCESS_DENIED` now maps to an actionable error naming snap/AppArmor confinement (an Ubuntu snap Firefox cannot read host paths outside its mount namespace, and no preference fixes that) and the localhost-server workaround, instead of relaying the bare nsresult.
+  - Live-verified on macOS (Firefox 153, launch mode): top-level `file://` navigation, sibling `<script src>` loading, and same-directory `fetch()` all pass end-to-end (`test/firefox-smoke.ts`, 24/24). The Linux snap-confined case cannot be reproduced on macOS and is covered by the error mapping instead; a negative control confirmed sibling-script/fetch behavior does not discriminate the seeded prefs on Firefox 153/macOS, so those smoke checks are regression guards, not causal proof.
+
+### Changed
+
+- **`test/firefox-smoke.ts`** gains the file:// + reload section (check 7b2) with its evidentiary limits documented inline, and no longer claims to avoid `file://` categorically.
+
 ## [1.11.0] - 2026-08-18
 
 **Firefox multi-process session coordination + orphan auto-recovery, and a new `cdp install` one-command setup.** Attaching several cdp-toolkit processes to one user Firefox no longer hard-wedges on Firefox's single-BiDi-session limit, and a session orphaned by a killed client is now auto-cleared over the Marionette side channel instead of requiring a Firefox restart. Chrome behavior is unchanged. The tool surface is still 45 tools — the installer is a CLI subcommand, not a new tool.

package/README.md

@@ -1,6 +1,6 @@
 # cdp-toolkit
 
-**A lightweight, drop-in alternative to [`chrome-devtools-mcp`](https://github.com/ChromeDevTools/chrome-devtools-mcp) that won't wedge your agent.** It drives the Chrome tabs you point it at over the raw DevTools Protocol: any number of tabs, one explicitly named target per call over one direct socket, with a bounded timeout on every call, so a stuck page returns a clean error instead of hanging your agent and forcing a `/mcp` restart. Same idea, no all-target fan-out, plus tab leases so several agents can work one browser (and know when a human is using it too), plus a built-in network-mocking fake backend. **45 tools.** Chrome is the flagship default; a second backend drives Firefox over WebDriver BiDi behind the same tool surface (see below).
+**A lightweight, drop-in alternative to [`chrome-devtools-mcp`](https://github.com/ChromeDevTools/chrome-devtools-mcp) that won't wedge your agent.** It drives the Chrome tabs you point it at over the raw DevTools Protocol: any number of tabs, one explicitly named target per call over one direct socket, with a bounded timeout on every call, so a stuck page returns a clean error instead of hanging your agent and forcing a `/mcp` restart. Same idea, no all-target fan-out, plus tab leases so several agents can work one browser (and know when a human is using it too), plus a built-in network-mocking fake backend. **45 tools — 12 of them on the MCP server's default listing**, the rest revealed by one `browser_tools` call (see [Progressive disclosure](#progressive-disclosure)). Chrome is the flagship default; a second backend drives Firefox over WebDriver BiDi behind the same tool surface (see below).
 
 > For AI-agent developers and Claude Code / Cursor users who need **the tabs they name driven reliably**, not a Puppeteer-managed browser.
 
@@ -129,7 +129,7 @@ bun run mcp:smoke   # spawn the server + a real initialize/tools-list/tools-call
 
 - **One target per call, never a broadcast.** Each call opens one WebSocket to the one target it named, with a bounded timeout on every CDP command, lazy domain enabling, and stateless element refs. Drive as many tabs as you like across calls; there is still no broadcast step that can stall on a wedged tab.
 - **Network mocking: build the UI before the backend exists.** `mock_request` arms a persistent per-target fake backend: return canned responses, force errors, or inject latency/fault rates. Mocks survive reloads and navigations until `clear_mocks`.
-- **Full chrome-devtools-mcp parity + extras.** All 29 upstream tools, plus `performance_trace` (a robust single-call trace), Lighthouse audits, heap snapshots, a cookie group that reads, writes, and deletes httpOnly cookies, real HTML5 drag-and-drop, raw scroll/mouse dispatch, download capture, permission grants, and tab-to-video screen recording. 45 single-purpose tools, no discovery overhead, and they coexist with `chrome-devtools-mcp` in a separate namespace.
+- **Full chrome-devtools-mcp parity + extras.** All 29 upstream tools, plus `performance_trace` (a robust single-call trace), Lighthouse audits, heap snapshots, a cookie group that reads, writes, and deletes httpOnly cookies, real HTML5 drag-and-drop, raw scroll/mouse dispatch, download capture, permission grants, and tab-to-video screen recording. The MCP server lists a lean 12-tool core by default and activates the rest per group via `browser_tools`, so the discovery payload stays small; the CLI exposes all 45. They coexist with `chrome-devtools-mcp` in a separate namespace.
 - **A whole page is a file, not a wedged tab.** Chrome cannot encode a screenshot past 16384 device px on either side, and past that `Page.captureScreenshot` does not error — it never answers, and leaves the tab resized to the clip it was capturing. On a ratio-2 display that ceiling arrives at about 8192 CSS px: an ordinary long article. `take_screenshot` measures the projection before every capture and, past the cap, takes the page as vertical bands stitched losslessly into one PNG — a 140,982 CSS px page comes back as a 2780×281964 file in 18 bands, in 17 seconds, with the tab still healthy. Also per-capture `scale`, and `renderWidth`/`renderHeight` to shoot one capture at an emulated viewport and restore the tab afterwards.
 - **Many agents, one browser, no stolen tabs.** `claim_page` hands out an opaque lease token for one tab; every other tool checks it at target resolution, so an unqualified call against a leased tab is refused by name rather than silently retargeted to whatever tab a different agent is driving.
 - **Knows when a human is already using the tab you're driving.** An in-page activity beacon distinguishes a person's clicks/keys/scrolls from the toolkit's own dispatched input, so `claim_page` and `list_leases` can report `humanActiveMs` and warn on contention instead of silently fighting someone for the keyboard. See "Staleness: is a human already using this tab?" below.
@@ -224,13 +224,36 @@ await TOOLS.navigate_page({ target: "index:0", url: "https://example.com" });
 | `CDP_STATE_DIR` | `/tmp/cdp-toolkit` | `select_page` selected-target file, in-flight trace state. |
 | `CDP_LEASE_TTL_MS` | `900000` | How long a tab lease survives without use before another agent can reclaim it. Refreshed on every checked call. |
 | `CDP_REQUIRE_LEASE` | off | Strict mode, MCP server only (inert under the CLI regardless of value). Turns leasing from optional into mandatory: a call against an unheld tab acquires a lease instead of driving it lease-free, and `list_pages`/`list_leases` close tabs an abandoned agent left behind. See "Parallel tabs" below. |
+| `CDP_TOOL_PROFILE` | `core` | MCP server only. Startup tool profile: `core` lists the 12 everyday tools plus the `browser_tools`/`describe_tool` meta-tools; `full` lists everything at startup (exact 1.x behavior). Groups toggle at runtime via `browser_tools` either way. See "Progressive disclosure" below. |
 | `CDP_REAP_GRACE_MS` | `2700000` | Extra grace (on top of `CDP_LEASE_TTL_MS`) before an `expired` lease's tab is actually destroyed by reap; `dead-pid` tabs are reaped immediately regardless. See "Reap" below. |
 | `CDP_FIREFOX_MARIONETTE_PORT` | `2828` | Firefox backend only. The Marionette side-channel port used to force-clear Firefox's orphaned BiDi session during orphan-session recovery (a blind `WebDriver:DeleteSession`). Only effective when that Firefox was launched with `--marionette`. See "Firefox" below. |
 | `CDP_FIREFOX_SESSION_WAIT_MS` | `10000` | Firefox backend only. How long a second process waits for a live holder to release Firefox's one BiDi session before returning the distinguishable "held by a live process" error. See "Firefox" below. |
 
+## Progressive disclosure
+
+By default the MCP server starts on the `core` profile: 12 everyday tools (`list_pages`, `new_page`, `close_page`, `select_page`, `navigate_page`, `wait_for`, `take_snapshot`, `click`, `fill`, `type_text`, `evaluate_script`, `take_screenshot`) plus two always-listed meta-tools, `browser_tools` and `describe_tool`. The other 33 tools stay hidden inside 12 activatable groups (`input`, `cookies`, `network`, `console`, `mocking`, `emulation`, `performance`, `recording`, `leases`, `permissions`, `dialogs`, `downloads`) until one `browser_tools` call reveals them. `CDP_TOOL_PROFILE=full` in the server's env restores 1.x behavior: everything advertised at startup.
+
+The default listing costs under 2.5k tokens and the full profile about 8.5k, down from about 20.2k in 1.x (−88% and −58%). Tool names, parameters, and schema shapes are unchanged; only what a client sees at discovery time moves.
+
+`browser_tools` drives the disclosure; `describe_tool` serves the full docs:
+
+```json
+{"tool": "browser_tools", "arguments": {"action": "list_groups"}}
+{"tool": "browser_tools", "arguments": {"action": "activate", "group": "mocking"}}
+{"tool": "describe_tool", "arguments": {"name": "wait_for_download"}}
+```
+
+Every `activate`/`deactivate`/`set_profile` that changes the listing fires `notifications/tools/list_changed` (the server declares `listChanged: true`), so a compliant client re-fetches `tools/list` and sees the new surface. Clients that cache their tool list should honor that notification rather than keep serving the stale one.
+
+Three rules worth knowing:
+
+- **Hidden does not mean blocked.** Only discovery is gated. `tools/call` checks backend availability, not group membership, so an agent that names a hidden-but-available tool still executes it; only a tool the selected browser cannot run at all is refused by name.
+- **`describe_tool` works for any tool by name, hidden ones included** — the full description and per-parameter docs behind the terse one-liner `tools/list` now carries.
+- **Meta-tools are MCP-only.** Profiles are an MCP-server concept: `cdp browser_tools` fails with `unknown tool`, and the CLI keeps exposing all 45 tools no matter how `CDP_TOOL_PROFILE` is set.
+
 ## Firefox (WebDriver BiDi)
 
-cdp-toolkit ships a second backend, Firefox over [WebDriver BiDi](https://w3c.github.io/webdriver-bidi/), behind the same 45-tool surface. Chrome stays the default and its behavior is unchanged, opt in explicitly to reach Firefox:
+cdp-toolkit ships a second backend, Firefox over [WebDriver BiDi](https://w3c.github.io/webdriver-bidi/), behind the same tool surface. Chrome stays the default and its behavior is unchanged, opt in explicitly to reach Firefox:
 
 ```bash
 cdp --browser firefox take_snapshot                 # CLI: explicit flag
@@ -304,7 +327,7 @@ This coordinates and recovers **around** Firefox's one-session limit; it does no
 
 **Attaching is not relaunching.** The one thing that is genuinely impossible is handing a debug port to an *already-running* Firefox process after the fact: the `--remote-debugging-port` flag only takes effect on a process's original launch, so relaunching the `firefox` binary against a running instance hands off to it and exits silently, opening no port (verified against Firefox 153.0.3). That is a real, narrow limitation of the Firefox binary itself. It is not the same claim as "Firefox cannot be attached to" — a Firefox that was launched *with* the debug port open, whether by this toolkit or by your own hand, exposes a plain BiDi endpoint that any number of fresh clients can connect to later, which is exactly what `--connect`/`CDP_FIREFOX_ENDPOINT` does.
 
-**Tool availability is filtered per backend**, not per call: `tools/list` (MCP) and `--list`/`--capabilities` (CLI) only ever advertise a tool the selected browser can actually run. A tool is never listed and then thrown from at call time. Under Firefox, four tool groups are absent because Firefox 153's BiDi implementation has no equivalent domain:
+**Tool availability is filtered per backend**, not per call: `tools/list` (MCP) and `--list`/`--capabilities` (CLI) only ever advertise a tool the selected browser can actually run. A tool is never listed and then thrown from at call time. On the MCP server a second filter composes on top: a tool is listed only when the backend can run it *and* its group is active — backend availability first, profile second (see [Progressive disclosure](#progressive-disclosure)). Under Firefox, six capability areas are absent because Firefox 153's BiDi implementation has no equivalent domain:
 
 - `performance_start_trace`, `performance_stop_trace`, `performance_analyze_insight`, `performance_trace` (needs `trace.performance`)
 - `take_heapsnapshot` (needs `heap.snapshot`)
@@ -313,7 +336,7 @@ This coordinates and recovers **around** Firefox's one-session limit; it does no
 - `dispatch_mouse` (needs `input.raw`): the raw move/down/up primitive is a direct `Input.dispatchMouseEvent` wrapper with no BiDi analogue.
 - `wait_for_download`, `grant_permissions` (need `browser.downloads` / `browser.permissions`): both drive Chrome's `Browser.*` domain; WebDriver BiDi has no command to redirect a download or pre-grant a permission.
 
-Everything else, including `mock_request`/`list_mocks`/`clear_mocks` (Firefox's `network.addIntercept` covers the same fake-backend use case as Chrome's `Fetch` domain), the `claim_page`/`release_page`/`list_leases` lease group, and the new `scroll` tool (Chrome dispatches `Input.dispatchMouseEvent{type:'mouseWheel'}`, Firefox uses BiDi's `wheel` input source — both live-verified), is available under both backends: 34 of the 45 tools. One asymmetry to know before expecting Chrome-style concurrency: the lease group fences *tabs* on both backends, but Firefox permits only **one BiDi session per browser instance**, so multiple agents under Firefox share and serialize on that single session (coordinated by the cross-process session lease above), not the independent concurrent sessions Chrome's unlimited CDP connections allow — see "Parallel tabs" below.
+Everything else, including `mock_request`/`list_mocks`/`clear_mocks` (Firefox's `network.addIntercept` covers the same fake-backend use case as Chrome's `Fetch` domain), the `claim_page`/`release_page`/`list_leases` lease group, and the new `scroll` tool (Chrome dispatches `Input.dispatchMouseEvent{type:'mouseWheel'}`, Firefox uses BiDi's `wheel` input source — both live-verified), is available under both backends: 34 of the 45 tools. Under the MCP server's default profile only the core subset of those is listed until their groups are activated — the profile filter applies after this backend filter. One asymmetry to know before expecting Chrome-style concurrency: the lease group fences *tabs* on both backends, but Firefox permits only **one BiDi session per browser instance**, so multiple agents under Firefox share and serialize on that single session (coordinated by the cross-process session lease above), not the independent concurrent sessions Chrome's unlimited CDP connections allow — see "Parallel tabs" below.
 
 **Honest capability gaps, not oversold parity:**
 
@@ -328,6 +351,8 @@ Everything else, including `mock_request`/`list_mocks`/`clear_mocks` (Firefox's
 
 ## The tools (29 parity + 16 superset = 45)
 
+This table is the **full-profile view** — all 45 tools, which is what `cdp --list` and `CDP_TOOL_PROFILE=full` show. On the MCP server's default `core` profile only 12 of them are listed at startup; the rest sit in 12 activatable groups: `input` (7: hover, drag, scroll, dispatch_mouse, press_key, fill_form, upload_file), `cookies` (3: list/set/delete_cookies), `network` (2: list/get_network_request), `console` (2: list/get_console_message), `mocking` (3: mock_request, list_mocks, clear_mocks), `emulation` (2: emulate, resize_page), `performance` (6: the four trace tools, take_heapsnapshot, lighthouse_audit), `recording` (2: start/stop_screen_recording), `leases` (3: claim_page, release_page, list_leases), `permissions` (1: grant_permissions), `dialogs` (1: handle_dialog), `downloads` (1: wait_for_download). See [Progressive disclosure](#progressive-disclosure).
+
 The 29 parity tools are 1:1 with `chrome-devtools-mcp`; the 16 superset tools (`performance_trace`, the `list_cookies`/`set_cookie`/`delete_cookies` cookie group, the `mock_request`/`list_mocks`/`clear_mocks` group, the `claim_page`/`release_page`/`list_leases` lease group, the `start_screen_recording`/`stop_screen_recording` screen-recording pair, `scroll`, `dispatch_mouse`, `wait_for_download`, and `grant_permissions`) are toolkit additions. Each row notes the underlying CDP method(s) and the precise parity gaps.
 
 | MCP name | CDP method(s) | Parity notes / gaps |
@@ -372,7 +397,7 @@ The 29 parity tools are 1:1 with `chrome-devtools-mcp`; the 16 superset tools (`
 | `mock_request` *(superset)* | `Fetch.*` (+ `Page.reload`) | **A fake backend.** Registers a rule on a target's persistent session: fulfill with a canned response, fail, or continue (with optional `delayMs`/`failRate`). Persists across reloads until `clear_mocks`. Request-stage only. Cached requests aren't intercepted (use `reload:true`). |
 | `list_mocks` *(superset)* | `Runtime.evaluate` (liveness probe) | Lists active mock sessions with rules + hit counts; prunes sessions whose tab closed. |
 | `clear_mocks` *(superset)* | `Fetch.disable` | Tears down the resolved target's mock session (or all with `all:true`). |
-| `claim_page` *(superset)* | `Target.createTarget` + lease file | Opens a fresh tab and claims it (no `target`/`targetId`), or takes over a tab that is already open (`target`, any selector, or the exact-id `targetId`) and returns an opaque lease token plus `opened` (true only when this call created the tab). Never steals a tab another live process holds. Also returns `humanActiveMs` (ms since input this server did not dispatch; `null` means no data, never "no human") and, on a takeover of a tab a human used within the last 30s, a `contention` warning — the claim is never refused for it. MCP only; the CLI refuses it. |
+| `claim_page` *(superset)* | `Target.createTarget` + lease file | Opens a fresh tab and claims it (no `target`/`targetId`), or takes over a tab that is already open (`target`, any selector, or the exact-id `targetId`) and returns an opaque lease token plus `opened` (true only when this call created the tab). Never steals a tab another live process holds. Also returns `humanActiveMs` (ms since input this server did not dispatch; `null` means no data, never "no human") and, on a takeover of a tab a human used within the last 30s, a `contention` warning — the claim is never refused for it. MCP only; the CLI refuses it. The `browser_tools`/`describe_tool` meta-tools are likewise MCP-only. |
 | `release_page` *(superset)* | lease file | Gives a lease back via `lease` (the token) or `target` (a selector, for a lease the gate auto-acquired and so never handed out a token for). Idempotent. Closes the tab by default when this toolkit's creation ledger says it opened it; leaves a merely-claimed tab open. Override either way with `close`. |
 | `list_leases` *(superset)* | lease file | Who holds what, with pid liveness and reclaimability, plus computed `idleMs`/`expiresAt` and, where the tab's beacon answers, `humanActiveMs` (absent, not null, when there's no answer). Needs no token; never returns the nonce. A lease file that could not be read or parsed is reported as an `unreadable` row instead of being skipped (with `idleMs`/`expiresAt` omitted). Under `CDP_REQUIRE_LEASE` also reaps abandoned agent tabs, reporting closures in an additive `reaped` array. |
 | `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`). |
@@ -530,8 +555,10 @@ src/
   types.ts           # Target, TargetSelector, Uid, CDP envelopes
   index.ts           # TOOLS registry (45) + re-exported client primitives
   cli.ts             # the Bun CLI
-  mcp.ts             # stdio MCP server (exposes TOOLS via @modelcontextprotocol/sdk)
+  mcp.ts             # stdio MCP server (exposes TOOLS via @modelcontextprotocol/server)
   manifest.ts        # JSON Schemas advertised by the MCP server (one per tool)
+  toolGroups.ts      # tool-to-group map + core/full profiles (progressive disclosure)
+  toolDocs.ts        # full per-tool prose served on demand by describe_tool
   leases.ts          # lease records, staleness, reclamation, assertLeaseOk, CDP_REQUIRE_LEASE
   leases-tools.ts    # claim_page / release_page / list_leases
   origins.ts         # tab creation ledger: who OPENED a tab, outliving its lease