cdp-toolkit 1.9.4 → 1.9.7

package/CHANGELOG.md

@@ -5,6 +5,89 @@ 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.7] - 2026-08-14
+
+### Fixed
+
+- **A dropped Firefox WebDriver BiDi connection is now re-dialed instead of erroring
+  permanently.** The backend memoizes one `BidiConnection` per endpoint, and `getConnection`
+  (`src/bidi/driver.ts`) returned the cached one unconditionally; once its socket dropped —
+  a Firefox restart, an idle/network drop, or a lost BiDi session slot — every later call
+  rejected forever with `connection not open`, for the entire life of the MCP server.
+  `getConnection` now evicts a dead cached connection (via a new `BidiConnection.isOpen`
+  getter) and re-creates the session on the next call, so Firefox tools recover on their own
+  instead of needing a server restart.
+- **Firefox launch mode no longer returns the hardcoded macOS Firefox path on Linux.**
+  `resolveBinary` (`src/bidi/launch.ts`) returned the first truthy candidate without checking
+  it existed, so on Linux it handed back `/Applications/Firefox.app/Contents/MacOS/firefox`
+  and never fell back to `firefox` on `PATH` — `ENOENT` at spawn, in launch mode only. An
+  absolute candidate (`FIREFOX_BIN`, the macOS path) is now only returned if it exists on this
+  box; the bare `firefox` name is left for `spawn` to resolve against `PATH`.
+- **Recorder artifact directory is now resolved per call, so `CDP_ARTIFACT_DIR` is honored at
+  runtime instead of being frozen at import time.** The buffer directory in `src/tools/recorder.ts`
+  was a module-level `const` bound the moment the module loaded, so a caller (or a test) that set
+  `CDP_ARTIFACT_DIR` afterward was ignored and `recFile`/`captureFile` still pointed at
+  `/tmp/cdp-toolkit`. On a clean CI runner that path does not exist, so the first buffer
+  `writeFile` threw `ENOENT` and the worker-capture suite failed there while passing on any box
+  where `/tmp/cdp-toolkit` happened to exist. It now reads the env var per call through a local
+  `artifactDir()` helper — the same "read per call, not at module load" pattern as `leaseDir()` in
+  `src/leases.ts` — so the directory is resolved at write time and a redirect takes effect.
+
+## [1.9.6] - 2026-08-13
+
+**Fix: `upload_file`'s `files` parameter is now declared array-only in the tool manifest** (was
+`"type": ["string","array"]`). Google's Gemini function-calling API rejects union-typed parameter
+schemas — the `any_of` branch's untyped `items` fails its `$type == Type.ARRAY` predicate — which
+hard-fails the entire `GenerateContentRequest` and kills any Gemini-backed agent session the
+moment this manifest is included in its toolset (observed as subagents returning empty results on
+every dispatch). Runtime behavior is unchanged: the handler still accepts and wraps a bare string
+for direct CDP/CLI callers; MCP/model callers now pass `[path]` per the declared schema.
+
+## [1.9.5] - 2026-08-11
+
+**Documentation and stale code-comment clarifications; NO behavior changes since 1.9.4.** Two
+updates. First, the Firefox `fullPage` screenshot gap that 1.9.2's docs hedged as "unmeasured" is
+now resolved: measured against a real Firefox 153.0.3 through the shipped CLI in attach mode, a
+20,000px-tall page captured with `take_screenshot --fullPage true` came back as a single
+1366×20000 PNG at scale 1 — verified complete top-to-bottom (a marker at y=0, a marker at y=20000,
+an unbroken ruler through the middle, no truncation). Firefox has no equivalent of Chrome's
+16384-device-px encode cap, so `browsingContext.captureScreenshot(origin:"document")` returns the
+whole long page in one BiDi call and never needs the band-tiling Chrome's cap requires — tiling
+exists solely to route around that cap, and Firefox doesn't have one, so `screenshot.tile` is a
+non-issue for Firefox correctness rather than a gap. `screenshot.scale` remains a genuine,
+unrelated Firefox gap: BiDi's `captureScreenshot` has no scale parameter at all, so Firefox
+captures stay 1x only. That same measured result also replaces three stale "unmeasured"/"probably
+implementable" comments in `src/bidi/driver.ts` describing `screenshot.tile` — comments only, no
+logic changed, since `screenshot.tile` was already correctly left undeclared and `tile:true`
+already correctly refused on Firefox; only the *reasoning* in the comments was stale. Second, this
+release also gives a changelog entry to doc-only additions that landed on top of 1.9.4 without one:
+Linux and remote-over-SSH attach guidance, and a `claude mcp add` one-liner, both in README.md's
+setup instructions.
+
+### Added
+
+- README.md: Linux and remote-over-SSH `--connect`/`CDP_FIREFOX_ENDPOINT`
+  attach guidance, and a `claude mcp add cdp-toolkit --scope user -- bun run
+  "$(pwd)/src/mcp.ts"` one-liner in the quick-start block.
+
+### Changed
+
+- README.md's "Honest capability gaps" list and CONTRACT.md's `screenshot.ts`
+  module row: the Firefox `tile:true`/`screenshot.tile` hedge ("unmeasured
+  gap... probably implementable") is replaced with the measured result above.
+  `scale`'s status is unchanged and still called out as a genuine gap.
+- `src/bidi/driver.ts`: three comment blocks (the `BIDI_CAPABILITIES` header
+  comment, the `capture()` method's `tile:true` refusal comment, and the
+  per-capability doc-comment list) rewritten from "unmeasured"/"probably
+  implementable" to the measured result above. No capability declarations, no
+  refusal logic, and no error-message text changed — comments only.
+
+### Notes
+
+- Tool count unchanged at **45**; no tool added, renamed, or removed.
+- Version bump only: `package.json` and `src/mcp.ts`'s `VERSION` constant move
+  1.9.4 → 1.9.5. No runtime behavior changed anywhere in this release.
+
 ## [1.9.4] - 2026-08-11
 
 Firefox gains a second mode: **attach**. Until now `--browser firefox` always spawned a

package/CONTRACT.md

@@ -171,7 +171,7 @@ A `Uid` **is** a CDP `backendDOMNodeId` (a number). This makes refs stateless:
 | `src/tools/evaluate.ts` | `evaluate_script`→`evaluateScript` | `Runtime.enable` + `Runtime.evaluate` (`returnByValue`, `awaitPromise`). Support optional `args` via `Runtime.callFunctionOn` on a uid/selector. Surface `exceptionDetails` as thrown error. |
 | `src/tools/snapshot.ts` | `take_snapshot`→`takeSnapshot` **+ export `resolveUid`** | a11y tree + ref scheme above. |
 | `src/tools/input.ts` | `click`→`click`, `hover`→`hover`, `drag`→`drag`, `fill`→`fill`, `fill_form`→`fillForm`, `type_text`→`typeText`, `press_key`→`pressKey`, `upload_file`→`uploadFile` | imports `resolveUid` from `./snapshot.ts`. `hover`=mouseMoved. `drag`=press→move→release. `fill`/`type_text`=focus + `Input.insertText` (fast) or `dispatchKeyEvent`. `press_key`=`Input.dispatchKeyEvent` (support modifiers + named keys). `upload_file`=`DOM.setFileInputFiles` on resolved node. `fill_form`=array of {uid|selector,value}. |
-| `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 }`. **As of 1.9.2 also `scale` (Chrome-only capability `screenshot.scale`, rides `clip.scale`), `renderWidth`/`renderHeight` (BOTH backends, `screenshot.renderSize`, an `Emulation.setDeviceMetricsOverride` held for one capture and undone in a `finally` against the viewport record above), and `tile` (three-valued, `true` costs `screenshot.tile`).** Two rules the size arithmetic imposes on anyone touching this path. **(a) Guard the projection, not the knob:** output px are `ceil(css × scale × devicePixelRatio)`, Chrome cannot encode past 16384 device px per side, and past that `Page.captureScreenshot` NEVER ANSWERS while `captureBeyondViewport` (hardcoded true) leaves the renderer resized to the clip — a wedged tab a `finally` cannot undo, because the client-side timeout fires while Chrome's command is still running. So `Page.getLayoutMetrics` is fetched and the projection checked on EVERY capture, including the plain no-clip one; a guard conditioned on the feature that motivated it (`scale !== 1`) has already let two wedges through. **(b) Bands are lazy and vertical:** past the cap the driver hands the tool layer a `BandedCapture` whose Nth `Page.captureScreenshot` runs only when the Nth band is pulled (accumulating them into an array would typecheck, pass on a small page, and hold 1.4 GB on a large one), stitched by `stitchPngBandsToFile` in `src/png.ts` — a zero-dependency streaming PNG stitcher (`node:zlib`), not an MCP tool and deliberately absent from the `TOOLS` registry. Vertical only: PNG scanlines are the one axis concatenable without decoding the image, so an over-WIDE projection is refused, never split. |
+| `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 }`. **As of 1.9.2 also `scale` (Chrome-only capability `screenshot.scale`, rides `clip.scale`), `renderWidth`/`renderHeight` (BOTH backends, `screenshot.renderSize`, an `Emulation.setDeviceMetricsOverride` held for one capture and undone in a `finally` against the viewport record above), and `tile` (three-valued, `true` costs `screenshot.tile`).** Firefox declares neither `screenshot.scale` (BiDi's `captureScreenshot` has no scale parameter, so Firefox captures are always 1x) nor `screenshot.tile` — but the tile gap is moot, not a limitation: Firefox has no Chrome-style 16384-device-px encode cap to band around, so `browsingContext.captureScreenshot(origin:"document")` returns an arbitrarily long `fullPage` capture in one shot. Measured against Firefox 153.0.3: a 20,000px-tall page came back as a single 1366×20000 PNG at scale 1, verified complete top-to-bottom (no truncation). Two rules the size arithmetic imposes on anyone touching this path. **(a) Guard the projection, not the knob:** output px are `ceil(css × scale × devicePixelRatio)`, Chrome cannot encode past 16384 device px per side, and past that `Page.captureScreenshot` NEVER ANSWERS while `captureBeyondViewport` (hardcoded true) leaves the renderer resized to the clip — a wedged tab a `finally` cannot undo, because the client-side timeout fires while Chrome's command is still running. So `Page.getLayoutMetrics` is fetched and the projection checked on EVERY capture, including the plain no-clip one; a guard conditioned on the feature that motivated it (`scale !== 1`) has already let two wedges through. **(b) Bands are lazy and vertical:** past the cap the driver hands the tool layer a `BandedCapture` whose Nth `Page.captureScreenshot` runs only when the Nth band is pulled (accumulating them into an array would typecheck, pass on a small page, and hold 1.4 GB on a large one), stitched by `stitchPngBandsToFile` in `src/png.ts` — a zero-dependency streaming PNG stitcher (`node:zlib`), not an MCP tool and deliberately absent from the `TOOLS` registry. Vertical only: PNG scanlines are the one axis concatenable without decoding the image, so an over-WIDE projection is refused, never split. |
 | `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`. **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`. |

package/README.md

@@ -265,6 +265,21 @@ cdp --connect ws://127.0.0.1:9223/session take_snapshot   # or the full ws:// UR
 
 `<endpoint>` accepts three spellings, all normalized to a ws URL: a bare port (`9223`), `host:port` (`127.0.0.1:9223`), or a full `ws://`/`wss://` URL. `--connect`/`CDP_FIREFOX_ENDPOINT` implies the Firefox backend on its own and errors against an explicit `--browser chrome`.
 
+**On Linux, and over SSH to a remote host.** Attach is a plain loopback WebSocket, so it is byte-identical on every OS; only the *launch* half is platform-specific. On Linux the binary is `firefox` on `PATH` (or `/usr/bin/firefox`), and the same `--remote-debugging-port 9223` opens the endpoint. One catch worth stating plainly: if your everyday Firefox is already running, relaunching it with the flag just focuses the open window and opens no port (see "Attaching is not relaunching" below). To attach to your real logged-in profile, quit Firefox first and reopen it with the flag; to run beside your daily browser instead, use the separate `--no-remote -profile` instance shown above.
+
+When Firefox runs on a different host than cdp-toolkit (a remote box, a container), its debug port binds to loopback *there*, so forward the port and attach to localhost:
+
+```bash
+ssh -L 9223:127.0.0.1:9223 you@the-box     # forward the remote debug port
+cdp --connect 9223 take_snapshot           # then attach as if it were local
+```
+
+For Claude Code, register the MCP server with the endpoint in one line (the env var implies the Firefox backend):
+
+```bash
+claude mcp add cdp-toolkit -e CDP_FIREFOX_ENDPOINT=9223 -- npx -y cdp-toolkit
+```
+
 **Firefox allows only one active WebDriver BiDi session at a time.** A second `session.new` against the same endpoint fails outright while a first session is open. Disposing cleanly (the normal exit path, both CLI and MCP shutdown) sends `session.end` first, which frees the slot for the next attach. A client that dies **without** disposing — a `SIGKILL`, a crash — leaves the slot occupied: Firefox does not reap an abandoned session on its own. A colliding attach against an occupied slot now fails fast with an actionable error naming the endpoint, rather than hanging forever (fixed in 1.9.4); recover by closing the other client or restarting Firefox.
 
 **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.
@@ -289,7 +304,7 @@ Everything else, including `mock_request`/`list_mocks`/`clear_mocks` (Firefox's
 - **`locate.text` is not available** (Firefox 153's `browsingContext.locateNodes` rejects the `innerText` locator type as unsupported), unlike Chrome, which has it via `DOM.performSearch`.
 - **No modifier-key clicks.** `click`'s `modifiers` (Alt/Control/Meta/Shift) is a Chrome-only *parameter* on an otherwise-universal tool: a non-empty `modifiers` array throws under `--browser firefox` rather than being silently dropped. A plain click still works on both backends.
 - **No real HTML5 drag-and-drop mode.** `drag`'s `mode:"html5"` requires capability `input.html5Drag` and is rejected with a clear error under Firefox; `mode:"mouse"` (the default) works on both.
-- **No per-capture screenshot `scale`, and no band tiling** — two *parameters* on an otherwise-universal tool, for two different reasons. `scale` (`screenshot.scale`) is a genuine protocol gap: `browsingContext.captureScreenshot` has no scale parameter at all, and the refusal points at `emulate {deviceScaleFactor}` + a scale-1 capture instead. `tile:true` (`screenshot.tile`) is an **unmeasured** gap, not a missing primitive: BiDi does take a box clip, so bands are probably implementable, but every property tiling rests on (does a box clip render past the viewport, is `clip.y` CSS px, do fixed elements repeat per band, are seams pixel-exact) was measured on Chrome and nowhere else, so it is not advertised. Auto-tiling never fires without `screenshot.tile`, so a Firefox capture behaves exactly as it did before. **`renderWidth`/`renderHeight` (`screenshot.renderSize`) are available on both backends** — that one is not a gap.
+- **No per-capture screenshot `scale`; band tiling is a Chrome-only workaround Firefox has no use for.** Two *parameters* on an otherwise-universal tool, for two different reasons. `scale` (`screenshot.scale`) is a genuine protocol gap: `browsingContext.captureScreenshot` has no scale parameter at all, and the refusal points at `emulate {deviceScaleFactor}` + a scale-1 capture instead — Firefox captures are always 1x. `tile:true` (`screenshot.tile`) is **not** a Firefox gap: measured against Firefox 153.0.3, `take_screenshot --fullPage true` on a 20,000px-tall page returned one 1366×20000 PNG at scale 1 from a single BiDi `captureScreenshot(origin:"document")` call — verified complete top-to-bottom (a marker at y=0, a marker at y=20000, an unbroken ruler through the middle, no truncation). Chrome's banding exists solely to route around its 16384-device-px encode cap; Firefox has no such cap, so there is nothing for tiling to work around, and auto-tiling correctly never fires there — a Firefox `fullPage` capture is already the whole page in one shot, however long. **`renderWidth`/`renderHeight` (`screenshot.renderSize`) are available on both backends** — that one is not a gap.
 
 ## The tools (29 parity + 16 superset = 45)
 

package/dist/cli.js

@@ -3702,12 +3702,14 @@ import { readFile as readFile4 } from "node:fs/promises";
 
 // src/tools/recorder.ts
 import { mkdir as mkdir6, appendFile, writeFile as writeFile5, copyFile } from "node:fs/promises";
-var ARTIFACT_DIR2 = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
+function artifactDir() {
+  return process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
+}
 function recFile(targetId) {
-  return `${ARTIFACT_DIR2}/rec-${targetId}.jsonl`;
+  return `${artifactDir()}/rec-${targetId}.jsonl`;
 }
 function captureFile(targetId, captureId) {
-  return `${ARTIFACT_DIR2}/rec-${targetId}-${captureId}.jsonl`;
+  return `${artifactDir()}/rec-${targetId}-${captureId}.jsonl`;
 }
 function delay2(ms) {
   return new Promise((r) => setTimeout(r, ms));
@@ -3747,7 +3749,7 @@ var CONSOLE_EVENTS = ["Runtime.consoleAPICalled", "Runtime.exceptionThrown", "Lo
 async function startRecorder(target, opts = {}) {
   const network = opts.network ?? true;
   const consoleCap = opts.console ?? true;
-  await mkdir6(ARTIFACT_DIR2, { recursive: true });
+  await mkdir6(artifactDir(), { recursive: true });
   const { conn, target: resolved } = await openPage(target, { timeoutMs: opts.timeoutMs });
   const file = opts.file ?? recFile(resolved.id);
   if (opts.truncate) {
@@ -4107,7 +4109,7 @@ async function getNetworkRequest(args = {}) {
 // src/tools/performance.ts
 import { mkdir as mkdir7, readFile as readFile6, writeFile as writeFile6, stat, unlink as unlink4 } from "node:fs/promises";
 import { join as join5 } from "node:path";
-var ARTIFACT_DIR3 = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
+var ARTIFACT_DIR2 = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
 var STATE_DIR2 = process.env.CDP_STATE_DIR ?? "/tmp/cdp-toolkit";
 var DEFAULT_CATEGORIES = [
   "devtools.timeline",
@@ -4146,8 +4148,8 @@ async function endTrace(conn, sink, timeoutMs = 30000) {
   return sink;
 }
 async function writeTrace(events, targetId) {
-  await mkdir7(ARTIFACT_DIR3, { recursive: true });
-  const path = join5(ARTIFACT_DIR3, `trace-${shortId(targetId)}-${stamp2()}.json`);
+  await mkdir7(ARTIFACT_DIR2, { recursive: true });
+  const path = join5(ARTIFACT_DIR2, `trace-${shortId(targetId)}-${stamp2()}.json`);
   const body = JSON.stringify({ traceEvents: events, metadata: { source: "cdp-toolkit" } });
   await writeFile6(path, body, "utf8");
   const { size } = await stat(path);
@@ -4340,7 +4342,7 @@ async function performanceAnalyzeInsight(args = {}) {
 import { spawn } from "node:child_process";
 import { mkdir as mkdir8, rm as rm2, stat as stat2, writeFile as writeFile7 } from "node:fs/promises";
 import { join as join6 } from "node:path";
-var ARTIFACT_DIR4 = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
+var ARTIFACT_DIR3 = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
 var FFMPEG_BIN = process.env.CDP_FFMPEG ?? "ffmpeg";
 function frameDurationsMs(ledger, stopWallclockMs) {
   return ledger.map((entry, i) => {
@@ -4560,7 +4562,7 @@ async function startScreenRecording(args = {}) {
     conn.close();
     throw err;
   }
-  const spoolDir = join6(ARTIFACT_DIR4, `screencast-${shortId2(target.id)}-${stamp3()}`);
+  const spoolDir = join6(ARTIFACT_DIR3, `screencast-${shortId2(target.id)}-${stamp3()}`);
   try {
     await mkdir8(spoolDir, { recursive: true });
   } catch (err) {
@@ -4666,8 +4668,8 @@ async function stopScreenRecording(args = {}) {
     await rm2(rec.spoolDir, { recursive: true, force: true }).catch(() => {});
     throw new CdpError(`screen recording captured 0 frames for target ${shortId2(rec.target.id)}. Chrome emits a screencast frame only on repaint: a fully backgrounded or occluded tab may never paint. Retry with bringToFront:true, or drive the page while recording.`);
   }
-  await mkdir8(ARTIFACT_DIR4, { recursive: true });
-  const outPath = args.savePath ?? join6(ARTIFACT_DIR4, `screen-recording-${shortId2(rec.target.id)}-${stamp3()}.mp4`);
+  await mkdir8(ARTIFACT_DIR3, { recursive: true });
+  const outPath = args.savePath ?? join6(ARTIFACT_DIR3, `screen-recording-${shortId2(rec.target.id)}-${stamp3()}.mp4`);
   const frames = coalesceToConcatGrid(ledger, stoppedAt);
   const manifestPath = join6(rec.spoolDir, "frames.ffconcat");
   await writeFile7(manifestPath, buildConcatManifest(frames), "utf8");
@@ -4703,7 +4705,7 @@ ffmpeg said: ${res.stderr.trim().slice(0, 800)}`);
 // src/tools/heap.ts
 import { mkdir as mkdir9, writeFile as writeFile8 } from "node:fs/promises";
 import { join as join7 } from "node:path";
-var ARTIFACT_DIR5 = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
+var ARTIFACT_DIR4 = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
 function stamp4(targetId) {
   const short = targetId.slice(0, 8);
   const iso = new Date().toISOString().replace(/[:.]/g, "-");
@@ -4727,8 +4729,8 @@ async function takeHeapsnapshot(args = {}) {
     if (snapshot.length === 0) {
       throw new Error("HeapProfiler.takeHeapSnapshot produced no chunks");
     }
-    await mkdir9(ARTIFACT_DIR5, { recursive: true });
-    const path = args.savePath ? args.savePath.startsWith("/") ? args.savePath : join7(ARTIFACT_DIR5, args.savePath) : join7(ARTIFACT_DIR5, `take_heapsnapshot-${stamp4(target.id)}.heapsnapshot`);
+    await mkdir9(ARTIFACT_DIR4, { recursive: true });
+    const path = args.savePath ? args.savePath.startsWith("/") ? args.savePath : join7(ARTIFACT_DIR4, args.savePath) : join7(ARTIFACT_DIR4, `take_heapsnapshot-${stamp4(target.id)}.heapsnapshot`);
     await writeFile8(path, snapshot, "utf8");
     const bytes = Buffer.byteLength(snapshot, "utf8");
     return {
@@ -4743,7 +4745,7 @@ async function takeHeapsnapshot(args = {}) {
 // src/tools/lighthouse.ts
 import { spawn as spawn2 } from "node:child_process";
 import { mkdir as mkdir10, readFile as readFile7, stat as stat3 } from "node:fs/promises";
-var ARTIFACT_DIR6 = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
+var ARTIFACT_DIR5 = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
 function cdpPort() {
   const base = process.env.CDP_BASE ?? "http://127.0.0.1:9222";
   const m = base.match(/:(\d+)/);
@@ -4803,8 +4805,8 @@ async function lighthouseAudit(args) {
   const url = args.url.trim();
   const timeoutMs = args.timeoutMs ?? 120000;
   const port = cdpPort();
-  await mkdir10(ARTIFACT_DIR6, { recursive: true });
-  const outPath = args.savePath ?? `${ARTIFACT_DIR6}/lighthouse-${shortHost(url)}-${stamp5()}.json`;
+  await mkdir10(ARTIFACT_DIR5, { recursive: true });
+  const outPath = args.savePath ?? `${ARTIFACT_DIR5}/lighthouse-${shortHost(url)}-${stamp5()}.json`;
   const formFactor = args.formFactor ?? "desktop";
   const lhArgs = [
     "--yes",
@@ -4925,8 +4927,8 @@ import { basename, extname, join as join9 } from "node:path";
 // src/tools/browser-session.ts
 import { mkdir as mkdir11 } from "node:fs/promises";
 import { join as join8 } from "node:path";
-var ARTIFACT_DIR7 = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
-var DOWNLOADS_DIR = join8(ARTIFACT_DIR7, "downloads");
+var ARTIFACT_DIR6 = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
+var DOWNLOADS_DIR = join8(ARTIFACT_DIR6, "downloads");
 var DOWNLOAD_BUFFER_LIMIT = 50;
 var session;
 function isDisconnect(e) {
@@ -5235,6 +5237,9 @@ class BidiConnection {
   get holders() {
     return this.refCount;
   }
+  get isOpen() {
+    return !this.closed && this.ws !== undefined;
+  }
   connect() {
     return new Promise((resolve, reject) => {
       const ws = new WebSocket(this.wsUrl);
@@ -5969,10 +5974,12 @@ var BIDI_CAPABILITIES = new Set([
 var connections = new Map;
 async function getConnection(endpoint, timeoutMs) {
   const existing = connections.get(endpoint);
-  if (existing) {
+  if (existing && existing.isOpen) {
     existing.retain();
     return existing;
   }
+  if (existing)
+    connections.delete(endpoint);
   const conn = await connectBidiSessionUrl(endpoint, {
     ...timeoutMs !== undefined ? { timeoutMs } : {},
     capabilities: { alwaysMatch: { unhandledPromptBehavior: { default: "ignore" } } }
@@ -6768,7 +6775,7 @@ function createFirefoxDriverForEndpoint(wsUrl, opts) {
 
 // src/bidi/launch.ts
 import { spawn as spawn3 } from "node:child_process";
-import { mkdtempSync, rmSync } from "node:fs";
+import { existsSync, mkdtempSync, rmSync } from "node:fs";
 import { createConnection, createServer } from "node:net";
 import { tmpdir } from "node:os";
 import { join as join10 } from "node:path";
@@ -6779,8 +6786,12 @@ function resolveBinary() {
     "firefox"
   ];
   for (const c of candidates) {
-    if (c)
-      return c;
+    if (!c)
+      continue;
+    const isAbsolute = c.startsWith("/");
+    if (isAbsolute && !existsSync(c))
+      continue;
+    return c;
   }
   throw new Error("Firefox binary not found. Tried FIREFOX_BIN env var, " + "/Applications/Firefox.app/Contents/MacOS/firefox, and 'firefox' on PATH.");
 }
@@ -8065,14 +8076,11 @@ var MANIFEST = [
           description: "CSS selector for the file input element (resolved via document.querySelector). Provide exactly one of uid or selector."
         },
         files: {
-          type: [
-            "string",
-            "array"
-          ],
+          type: "array",
           items: {
             type: "string"
           },
-          description: "Absolute path, or array of absolute paths, to the file(s) to attach to the <input type=file>. Accepts a single string or an array of strings."
+          description: 'Absolute path(s) to the file(s) to attach to the <input type=file>, as an array of absolute paths. A single path must be wrapped in an array (e.g. ["/tmp/a.pdf"]). Declared array-only because some model APIs (Google Gemini function calling) reject union-typed parameters.'
         }
       },
       required: [

package/dist/index.js

@@ -3700,12 +3700,14 @@ import { readFile as readFile4 } from "node:fs/promises";
 
 // src/tools/recorder.ts
 import { mkdir as mkdir6, appendFile, writeFile as writeFile5, copyFile } from "node:fs/promises";
-var ARTIFACT_DIR2 = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
+function artifactDir() {
+  return process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
+}
 function recFile(targetId) {
-  return `${ARTIFACT_DIR2}/rec-${targetId}.jsonl`;
+  return `${artifactDir()}/rec-${targetId}.jsonl`;
 }
 function captureFile(targetId, captureId) {
-  return `${ARTIFACT_DIR2}/rec-${targetId}-${captureId}.jsonl`;
+  return `${artifactDir()}/rec-${targetId}-${captureId}.jsonl`;
 }
 function delay2(ms) {
   return new Promise((r) => setTimeout(r, ms));
@@ -3745,7 +3747,7 @@ var CONSOLE_EVENTS = ["Runtime.consoleAPICalled", "Runtime.exceptionThrown", "Lo
 async function startRecorder(target, opts = {}) {
   const network = opts.network ?? true;
   const consoleCap = opts.console ?? true;
-  await mkdir6(ARTIFACT_DIR2, { recursive: true });
+  await mkdir6(artifactDir(), { recursive: true });
   const { conn, target: resolved } = await openPage(target, { timeoutMs: opts.timeoutMs });
   const file = opts.file ?? recFile(resolved.id);
   if (opts.truncate) {
@@ -4105,7 +4107,7 @@ async function getNetworkRequest(args = {}) {
 // src/tools/performance.ts
 import { mkdir as mkdir7, readFile as readFile6, writeFile as writeFile6, stat, unlink as unlink4 } from "node:fs/promises";
 import { join as join5 } from "node:path";
-var ARTIFACT_DIR3 = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
+var ARTIFACT_DIR2 = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
 var STATE_DIR2 = process.env.CDP_STATE_DIR ?? "/tmp/cdp-toolkit";
 var DEFAULT_CATEGORIES = [
   "devtools.timeline",
@@ -4144,8 +4146,8 @@ async function endTrace(conn, sink, timeoutMs = 30000) {
   return sink;
 }
 async function writeTrace(events, targetId) {
-  await mkdir7(ARTIFACT_DIR3, { recursive: true });
-  const path = join5(ARTIFACT_DIR3, `trace-${shortId(targetId)}-${stamp2()}.json`);
+  await mkdir7(ARTIFACT_DIR2, { recursive: true });
+  const path = join5(ARTIFACT_DIR2, `trace-${shortId(targetId)}-${stamp2()}.json`);
   const body = JSON.stringify({ traceEvents: events, metadata: { source: "cdp-toolkit" } });
   await writeFile6(path, body, "utf8");
   const { size } = await stat(path);
@@ -4338,7 +4340,7 @@ async function performanceAnalyzeInsight(args = {}) {
 import { spawn } from "node:child_process";
 import { mkdir as mkdir8, rm as rm2, stat as stat2, writeFile as writeFile7 } from "node:fs/promises";
 import { join as join6 } from "node:path";
-var ARTIFACT_DIR4 = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
+var ARTIFACT_DIR3 = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
 var FFMPEG_BIN = process.env.CDP_FFMPEG ?? "ffmpeg";
 function frameDurationsMs(ledger, stopWallclockMs) {
   return ledger.map((entry, i) => {
@@ -4558,7 +4560,7 @@ async function startScreenRecording(args = {}) {
     conn.close();
     throw err;
   }
-  const spoolDir = join6(ARTIFACT_DIR4, `screencast-${shortId2(target.id)}-${stamp3()}`);
+  const spoolDir = join6(ARTIFACT_DIR3, `screencast-${shortId2(target.id)}-${stamp3()}`);
   try {
     await mkdir8(spoolDir, { recursive: true });
   } catch (err) {
@@ -4664,8 +4666,8 @@ async function stopScreenRecording(args = {}) {
     await rm2(rec.spoolDir, { recursive: true, force: true }).catch(() => {});
     throw new CdpError(`screen recording captured 0 frames for target ${shortId2(rec.target.id)}. Chrome emits a screencast frame only on repaint: a fully backgrounded or occluded tab may never paint. Retry with bringToFront:true, or drive the page while recording.`);
   }
-  await mkdir8(ARTIFACT_DIR4, { recursive: true });
-  const outPath = args.savePath ?? join6(ARTIFACT_DIR4, `screen-recording-${shortId2(rec.target.id)}-${stamp3()}.mp4`);
+  await mkdir8(ARTIFACT_DIR3, { recursive: true });
+  const outPath = args.savePath ?? join6(ARTIFACT_DIR3, `screen-recording-${shortId2(rec.target.id)}-${stamp3()}.mp4`);
   const frames = coalesceToConcatGrid(ledger, stoppedAt);
   const manifestPath = join6(rec.spoolDir, "frames.ffconcat");
   await writeFile7(manifestPath, buildConcatManifest(frames), "utf8");
@@ -4701,7 +4703,7 @@ ffmpeg said: ${res.stderr.trim().slice(0, 800)}`);
 // src/tools/heap.ts
 import { mkdir as mkdir9, writeFile as writeFile8 } from "node:fs/promises";
 import { join as join7 } from "node:path";
-var ARTIFACT_DIR5 = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
+var ARTIFACT_DIR4 = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
 function stamp4(targetId) {
   const short = targetId.slice(0, 8);
   const iso = new Date().toISOString().replace(/[:.]/g, "-");
@@ -4725,8 +4727,8 @@ async function takeHeapsnapshot(args = {}) {
     if (snapshot.length === 0) {
       throw new Error("HeapProfiler.takeHeapSnapshot produced no chunks");
     }
-    await mkdir9(ARTIFACT_DIR5, { recursive: true });
-    const path = args.savePath ? args.savePath.startsWith("/") ? args.savePath : join7(ARTIFACT_DIR5, args.savePath) : join7(ARTIFACT_DIR5, `take_heapsnapshot-${stamp4(target.id)}.heapsnapshot`);
+    await mkdir9(ARTIFACT_DIR4, { recursive: true });
+    const path = args.savePath ? args.savePath.startsWith("/") ? args.savePath : join7(ARTIFACT_DIR4, args.savePath) : join7(ARTIFACT_DIR4, `take_heapsnapshot-${stamp4(target.id)}.heapsnapshot`);
     await writeFile8(path, snapshot, "utf8");
     const bytes = Buffer.byteLength(snapshot, "utf8");
     return {
@@ -4741,7 +4743,7 @@ async function takeHeapsnapshot(args = {}) {
 // src/tools/lighthouse.ts
 import { spawn as spawn2 } from "node:child_process";
 import { mkdir as mkdir10, readFile as readFile7, stat as stat3 } from "node:fs/promises";
-var ARTIFACT_DIR6 = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
+var ARTIFACT_DIR5 = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
 function cdpPort() {
   const base = process.env.CDP_BASE ?? "http://127.0.0.1:9222";
   const m = base.match(/:(\d+)/);
@@ -4801,8 +4803,8 @@ async function lighthouseAudit(args) {
   const url = args.url.trim();
   const timeoutMs = args.timeoutMs ?? 120000;
   const port = cdpPort();
-  await mkdir10(ARTIFACT_DIR6, { recursive: true });
-  const outPath = args.savePath ?? `${ARTIFACT_DIR6}/lighthouse-${shortHost(url)}-${stamp5()}.json`;
+  await mkdir10(ARTIFACT_DIR5, { recursive: true });
+  const outPath = args.savePath ?? `${ARTIFACT_DIR5}/lighthouse-${shortHost(url)}-${stamp5()}.json`;
   const formFactor = args.formFactor ?? "desktop";
   const lhArgs = [
     "--yes",
@@ -4923,8 +4925,8 @@ import { basename, extname, join as join9 } from "node:path";
 // src/tools/browser-session.ts
 import { mkdir as mkdir11 } from "node:fs/promises";
 import { join as join8 } from "node:path";
-var ARTIFACT_DIR7 = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
-var DOWNLOADS_DIR = join8(ARTIFACT_DIR7, "downloads");
+var ARTIFACT_DIR6 = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
+var DOWNLOADS_DIR = join8(ARTIFACT_DIR6, "downloads");
 var DOWNLOAD_BUFFER_LIMIT = 50;
 var session;
 function isDisconnect(e) {

package/dist/mcp.js

@@ -3702,12 +3702,14 @@ import { readFile as readFile4 } from "node:fs/promises";
 
 // src/tools/recorder.ts
 import { mkdir as mkdir6, appendFile, writeFile as writeFile5, copyFile } from "node:fs/promises";
-var ARTIFACT_DIR2 = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
+function artifactDir() {
+  return process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
+}
 function recFile(targetId) {
-  return `${ARTIFACT_DIR2}/rec-${targetId}.jsonl`;
+  return `${artifactDir()}/rec-${targetId}.jsonl`;
 }
 function captureFile(targetId, captureId) {
-  return `${ARTIFACT_DIR2}/rec-${targetId}-${captureId}.jsonl`;
+  return `${artifactDir()}/rec-${targetId}-${captureId}.jsonl`;
 }
 function delay2(ms) {
   return new Promise((r) => setTimeout(r, ms));
@@ -3747,7 +3749,7 @@ var CONSOLE_EVENTS = ["Runtime.consoleAPICalled", "Runtime.exceptionThrown", "Lo
 async function startRecorder(target, opts = {}) {
   const network = opts.network ?? true;
   const consoleCap = opts.console ?? true;
-  await mkdir6(ARTIFACT_DIR2, { recursive: true });
+  await mkdir6(artifactDir(), { recursive: true });
   const { conn, target: resolved } = await openPage(target, { timeoutMs: opts.timeoutMs });
   const file = opts.file ?? recFile(resolved.id);
   if (opts.truncate) {
@@ -4107,7 +4109,7 @@ async function getNetworkRequest(args = {}) {
 // src/tools/performance.ts
 import { mkdir as mkdir7, readFile as readFile6, writeFile as writeFile6, stat, unlink as unlink4 } from "node:fs/promises";
 import { join as join5 } from "node:path";
-var ARTIFACT_DIR3 = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
+var ARTIFACT_DIR2 = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
 var STATE_DIR2 = process.env.CDP_STATE_DIR ?? "/tmp/cdp-toolkit";
 var DEFAULT_CATEGORIES = [
   "devtools.timeline",
@@ -4146,8 +4148,8 @@ async function endTrace(conn, sink, timeoutMs = 30000) {
   return sink;
 }
 async function writeTrace(events, targetId) {
-  await mkdir7(ARTIFACT_DIR3, { recursive: true });
-  const path = join5(ARTIFACT_DIR3, `trace-${shortId(targetId)}-${stamp2()}.json`);
+  await mkdir7(ARTIFACT_DIR2, { recursive: true });
+  const path = join5(ARTIFACT_DIR2, `trace-${shortId(targetId)}-${stamp2()}.json`);
   const body = JSON.stringify({ traceEvents: events, metadata: { source: "cdp-toolkit" } });
   await writeFile6(path, body, "utf8");
   const { size } = await stat(path);
@@ -4340,7 +4342,7 @@ async function performanceAnalyzeInsight(args = {}) {
 import { spawn } from "node:child_process";
 import { mkdir as mkdir8, rm as rm2, stat as stat2, writeFile as writeFile7 } from "node:fs/promises";
 import { join as join6 } from "node:path";
-var ARTIFACT_DIR4 = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
+var ARTIFACT_DIR3 = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
 var FFMPEG_BIN = process.env.CDP_FFMPEG ?? "ffmpeg";
 function frameDurationsMs(ledger, stopWallclockMs) {
   return ledger.map((entry, i) => {
@@ -4560,7 +4562,7 @@ async function startScreenRecording(args = {}) {
     conn.close();
     throw err;
   }
-  const spoolDir = join6(ARTIFACT_DIR4, `screencast-${shortId2(target.id)}-${stamp3()}`);
+  const spoolDir = join6(ARTIFACT_DIR3, `screencast-${shortId2(target.id)}-${stamp3()}`);
   try {
     await mkdir8(spoolDir, { recursive: true });
   } catch (err) {
@@ -4666,8 +4668,8 @@ async function stopScreenRecording(args = {}) {
     await rm2(rec.spoolDir, { recursive: true, force: true }).catch(() => {});
     throw new CdpError(`screen recording captured 0 frames for target ${shortId2(rec.target.id)}. Chrome emits a screencast frame only on repaint: a fully backgrounded or occluded tab may never paint. Retry with bringToFront:true, or drive the page while recording.`);
   }
-  await mkdir8(ARTIFACT_DIR4, { recursive: true });
-  const outPath = args.savePath ?? join6(ARTIFACT_DIR4, `screen-recording-${shortId2(rec.target.id)}-${stamp3()}.mp4`);
+  await mkdir8(ARTIFACT_DIR3, { recursive: true });
+  const outPath = args.savePath ?? join6(ARTIFACT_DIR3, `screen-recording-${shortId2(rec.target.id)}-${stamp3()}.mp4`);
   const frames = coalesceToConcatGrid(ledger, stoppedAt);
   const manifestPath = join6(rec.spoolDir, "frames.ffconcat");
   await writeFile7(manifestPath, buildConcatManifest(frames), "utf8");
@@ -4703,7 +4705,7 @@ ffmpeg said: ${res.stderr.trim().slice(0, 800)}`);
 // src/tools/heap.ts
 import { mkdir as mkdir9, writeFile as writeFile8 } from "node:fs/promises";
 import { join as join7 } from "node:path";
-var ARTIFACT_DIR5 = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
+var ARTIFACT_DIR4 = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
 function stamp4(targetId) {
   const short = targetId.slice(0, 8);
   const iso = new Date().toISOString().replace(/[:.]/g, "-");
@@ -4727,8 +4729,8 @@ async function takeHeapsnapshot(args = {}) {
     if (snapshot.length === 0) {
       throw new Error("HeapProfiler.takeHeapSnapshot produced no chunks");
     }
-    await mkdir9(ARTIFACT_DIR5, { recursive: true });
-    const path = args.savePath ? args.savePath.startsWith("/") ? args.savePath : join7(ARTIFACT_DIR5, args.savePath) : join7(ARTIFACT_DIR5, `take_heapsnapshot-${stamp4(target.id)}.heapsnapshot`);
+    await mkdir9(ARTIFACT_DIR4, { recursive: true });
+    const path = args.savePath ? args.savePath.startsWith("/") ? args.savePath : join7(ARTIFACT_DIR4, args.savePath) : join7(ARTIFACT_DIR4, `take_heapsnapshot-${stamp4(target.id)}.heapsnapshot`);
     await writeFile8(path, snapshot, "utf8");
     const bytes = Buffer.byteLength(snapshot, "utf8");
     return {
@@ -4743,7 +4745,7 @@ async function takeHeapsnapshot(args = {}) {
 // src/tools/lighthouse.ts
 import { spawn as spawn2 } from "node:child_process";
 import { mkdir as mkdir10, readFile as readFile7, stat as stat3 } from "node:fs/promises";
-var ARTIFACT_DIR6 = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
+var ARTIFACT_DIR5 = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
 function cdpPort() {
   const base = process.env.CDP_BASE ?? "http://127.0.0.1:9222";
   const m = base.match(/:(\d+)/);
@@ -4803,8 +4805,8 @@ async function lighthouseAudit(args) {
   const url = args.url.trim();
   const timeoutMs = args.timeoutMs ?? 120000;
   const port = cdpPort();
-  await mkdir10(ARTIFACT_DIR6, { recursive: true });
-  const outPath = args.savePath ?? `${ARTIFACT_DIR6}/lighthouse-${shortHost(url)}-${stamp5()}.json`;
+  await mkdir10(ARTIFACT_DIR5, { recursive: true });
+  const outPath = args.savePath ?? `${ARTIFACT_DIR5}/lighthouse-${shortHost(url)}-${stamp5()}.json`;
   const formFactor = args.formFactor ?? "desktop";
   const lhArgs = [
     "--yes",
@@ -4925,8 +4927,8 @@ import { basename, extname, join as join9 } from "node:path";
 // src/tools/browser-session.ts
 import { mkdir as mkdir11 } from "node:fs/promises";
 import { join as join8 } from "node:path";
-var ARTIFACT_DIR7 = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
-var DOWNLOADS_DIR = join8(ARTIFACT_DIR7, "downloads");
+var ARTIFACT_DIR6 = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
+var DOWNLOADS_DIR = join8(ARTIFACT_DIR6, "downloads");
 var DOWNLOAD_BUFFER_LIMIT = 50;
 var session;
 function isDisconnect(e) {
@@ -6072,14 +6074,11 @@ var MANIFEST = [
           description: "CSS selector for the file input element (resolved via document.querySelector). Provide exactly one of uid or selector."
         },
         files: {
-          type: [
-            "string",
-            "array"
-          ],
+          type: "array",
           items: {
             type: "string"
           },
-          description: "Absolute path, or array of absolute paths, to the file(s) to attach to the <input type=file>. Accepts a single string or an array of strings."
+          description: 'Absolute path(s) to the file(s) to attach to the <input type=file>, as an array of absolute paths. A single path must be wrapped in an array (e.g. ["/tmp/a.pdf"]). Declared array-only because some model APIs (Google Gemini function calling) reject union-typed parameters.'
         }
       },
       required: [
@@ -6913,6 +6912,9 @@ class BidiConnection {
   get holders() {
     return this.refCount;
   }
+  get isOpen() {
+    return !this.closed && this.ws !== undefined;
+  }
   connect() {
     return new Promise((resolve, reject) => {
       const ws = new WebSocket(this.wsUrl);
@@ -7647,10 +7649,12 @@ var BIDI_CAPABILITIES = new Set([
 var connections = new Map;
 async function getConnection(endpoint, timeoutMs) {
   const existing = connections.get(endpoint);
-  if (existing) {
+  if (existing && existing.isOpen) {
     existing.retain();
     return existing;
   }
+  if (existing)
+    connections.delete(endpoint);
   const conn = await connectBidiSessionUrl(endpoint, {
     ...timeoutMs !== undefined ? { timeoutMs } : {},
     capabilities: { alwaysMatch: { unhandledPromptBehavior: { default: "ignore" } } }
@@ -8446,7 +8450,7 @@ function createFirefoxDriverForEndpoint(wsUrl, opts) {
 
 // src/bidi/launch.ts
 import { spawn as spawn3 } from "node:child_process";
-import { mkdtempSync, rmSync } from "node:fs";
+import { existsSync, mkdtempSync, rmSync } from "node:fs";
 import { createConnection, createServer } from "node:net";
 import { tmpdir } from "node:os";
 import { join as join10 } from "node:path";
@@ -8457,8 +8461,12 @@ function resolveBinary() {
     "firefox"
   ];
   for (const c of candidates) {
-    if (c)
-      return c;
+    if (!c)
+      continue;
+    const isAbsolute = c.startsWith("/");
+    if (isAbsolute && !existsSync(c))
+      continue;
+    return c;
   }
   throw new Error("Firefox binary not found. Tried FIREFOX_BIN env var, " + "/Applications/Firefox.app/Contents/MacOS/firefox, and 'firefox' on PATH.");
 }
@@ -8874,7 +8882,7 @@ var FIREFOX_TOOLS = {
 };
 
 // src/mcp.ts
-var VERSION = "1.9.4";
+var VERSION = "1.9.7";
 var { kind: BROWSER, endpoint: FIREFOX_ENDPOINT } = resolveBackend(process.argv.slice(2));
 var AVAILABILITY = toolAvailability(BROWSER);
 var AVAILABLE_NAMES = new Set(AVAILABILITY.available);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cdp-toolkit",
-  "version": "1.9.4",
+  "version": "1.9.7",
   "description": "A lightweight chrome-devtools-mcp alternative: an MCP server + CLI that drives the tabs you name, one target per call over one direct WebSocket, with a bounded timeout on every call, so a stuck page can't wedge your agent or force a /mcp restart. Chrome over CDP and Firefox over WebDriver BiDi, with tools a backend can't run absent from tools/list rather than throwing mid-task. 45 tools including built-in network mocking, a cookie group, tab leases with human-activity detection, real HTML5 drag-and-drop, raw mouse/scroll dispatch, downloads, permission grants, and tab-to-video screen recording so several agents can drive one browser without stealing each other's tabs or a human's. No Puppeteer, no all-target fan-out.",
   "type": "module",
   "license": "MIT",

package/src/bidi/client.ts

@@ -88,6 +88,17 @@ export class BidiConnection {
     return this.refCount;
   }
 
+  /**
+   * True while this connection still has a live socket. Goes false once the
+   * socket closes (ws.onclose) or dispose() runs — both set `closed` and
+   * reject all in-flight calls. getConnection uses this to skip and evict a
+   * dead cached connection so the next call re-dials a fresh session instead
+   * of reusing a socket that can only reject with "connection not open".
+   */
+  get isOpen(): boolean {
+    return !this.closed && this.ws !== undefined;
+  }
+
   connect(): Promise<this> {
     return new Promise((resolve, reject) => {
       const ws = new WebSocket(this.wsUrl);

package/src/bidi/driver.ts

@@ -301,11 +301,13 @@ const AWAIT_SCROLL_SETTLE_SOURCE = "function(){return window.__cdpScrollSettle;}
  * above already rides, applied for one capture and undone afterwards. Refusing it would be dishonest
  * in the opposite direction — claiming a missing primitive this driver demonstrably has. Contrast
  * screenshot.scale, absent because captureScreenshot genuinely has no scale parameter.
- * screenshot.tile is absent for a THIRD reason, neither "has it" nor "no such parameter": the
- * primitive plausibly exists (clip:{type:"box"}) but nothing about band tiling has been measured on
- * this backend, and the Chrome declaration rests entirely on measurement. An undeclared capability
- * that turns out to work is a follow-up; a declared one that silently mis-stitches is a wrong image
- * the caller cannot tell from a right one.
+ * screenshot.tile stays undeclared, but no longer for an unmeasured reason: live-fired against
+ * Firefox 153.0.3, a 20,000px-tall page captured with take_screenshot --fullPage true came back
+ * as a single 1366x20000 PNG at scale 1, verified complete top-to-bottom — no clip, no bands.
+ * Chrome's band tiling exists solely to route around its 16384-device-px encode cap; Firefox has
+ * no such cap, so screenshot.tile (the capability gating explicit tile:true forced banding) has
+ * no gap here to close. It stays undeclared because it would advertise a forced-tiling primitive
+ * this backend has never needed, not because band-tiling behavior is untested.
  */
 const BIDI_CAPABILITIES: ReadonlySet<Capability> = new Set<Capability>([
   "emulate.deviceMetrics", "screenshot.fullPage", "screenshot.element", "screenshot.renderSize", "network.intercept", "locate.xpath",
@@ -320,7 +322,13 @@ const BIDI_CAPABILITIES: ReadonlySet<Capability> = new Set<Capability>([
 const connections = new Map<string, BidiConnection>();
 async function getConnection(endpoint: string, timeoutMs?: number): Promise<BidiConnection> {
   const existing = connections.get(endpoint);
-  if (existing) { existing.retain(); return existing; }
+  if (existing && existing.isOpen) { existing.retain(); return existing; }
+  // A cached connection whose socket has died (ws.onclose fired) can only reject every
+  // send() with "connection not open" — reusing it would strand the endpoint permanently.
+  // Evict it so the code below re-dials and creates a fresh BiDi session. No cleanup is
+  // needed: a dead connection already had `closed` set and rejectAll() cleared its per-call
+  // timers, and BidiConnection holds no heartbeat/keepalive resource to leak (see client.ts).
+  if (existing) connections.delete(endpoint);
   // Firefox 153's default unhandledPromptBehavior is "dismiss": a page-blocking alert()/confirm()
   // gets auto-dismissed before handleDialog() ever runs, and Firefox's own userPromptOpened event
   // reports handler:"dismiss" on it (verified: a bare session.new left "no such alert" on the very
@@ -882,15 +890,14 @@ class BidiPageDriver implements PageDriver {
           `deviceScaleFactor:${opts.scale} first and capture at scale 1, or use --browser chrome.`,
       );
     }
-    // Same ADR-001 param-level shape, and the reason is HONESTY rather than a missing primitive.
-    // browsingContext.captureScreenshot does take clip:{type:"box",x,y,width,height}, so a banded
-    // capture is probably implementable here — but Firefox was not launched for this change, so
-    // every property band tiling depends on is unmeasured on this backend: whether a box clip
-    // renders content outside the viewport at all, whether clip.y is CSS px, whether fixed elements
-    // repeat per band, whether seams are pixel-exact. Each of those was measured on Chrome before
-    // the Chrome path was declared. Shipping an unverified twin would put a silently-wrong stitch in
-    // front of a caller, so this refuses and says why. `tile:false` and the default (auto, which
-    // never bands here) ask this backend for nothing and are untouched.
+    // Same ADR-001 param-level shape, but now a measured non-gap rather than an unmeasured one.
+    // Live-fired against Firefox 153.0.3: a 20,000px-tall page captured with take_screenshot
+    // --fullPage true came back as one 1366x20000 PNG at scale 1, verified complete top-to-bottom,
+    // via the single origin:"document" capture below — no clip, no bands. Chrome's band tiling
+    // exists only to route around its 16384-device-px encode cap; this backend has no such cap, so
+    // there is nothing for tile:true's forced banding to do here. The refusal below stays because
+    // there is no forced-tiling primitive to build, not because it is untested. `tile:false` and
+    // the default (auto, which never bands here) ask this backend for nothing and are untouched.
     if (opts?.tile === true) {
       throw driverError(
         "unsupported",
@@ -1408,13 +1415,14 @@ export { BidiBrowserDriver, BidiPageDriver, resolveContext };
  *     Firefox is next driven: whether a null viewport reverts to the real window (CDP's clear does
  *     NOT, for an override another session set), and whether setViewport reflows synchronously the
  *     way Emulation.setDeviceMetricsOverride was measured to on Chrome.
- *   - screenshot.tile: not declared, and unlike screenshot.scale this is an UNMEASURED gap rather
- *     than a missing parameter. captureScreenshot does take clip:{type:"box"}, so bands are probably
- *     implementable — but every property band tiling rests on (does a box clip render past the
- *     viewport, is clip.y CSS px, do fixed elements repeat per band, are seams pixel-exact) was
- *     measured on Chrome and on nothing else, and Firefox was not launched here. `tile:true` is a
- *     refusal in screenshot() naming --browser chrome; the default (auto) never bands on this
- *     backend, so it is unchanged.
+ *   - screenshot.tile: not declared, but no longer an unmeasured gap. Live-fired against Firefox
+ *     153.0.3: take_screenshot --fullPage true on a 20,000px-tall page returned one 1366x20000 PNG
+ *     at scale 1, verified complete top-to-bottom, via a single origin:"document" capture — no
+ *     clip, no bands, no cap hit. Chrome's band tiling exists solely to route around its
+ *     16384-device-px encode cap; Firefox has no such cap, so screenshot.tile (forced tiling via
+ *     tile:true) has nothing to do here. `tile:true` is still a refusal in screenshot() naming
+ *     --browser chrome; the default (auto) still never bands on this backend — both unchanged, now
+ *     for a documented reason instead of an untested one.
  *   - emulate.mediaFeatures / emulate.cpuThrottling / emulate.networkConditions: not declared.
  *     Firefox 153 does not implement setMediaFeaturesOverride; CPU throttling and network condition
  *     emulation have no verified-working BiDi path in this environment, so emulate() never claims

package/src/bidi/launch.ts

@@ -22,7 +22,7 @@
  * node:os and node:path.
  */
 import { spawn, type ChildProcess } from "node:child_process";
-import { mkdtempSync, rmSync } from "node:fs";
+import { existsSync, mkdtempSync, rmSync } from "node:fs";
 import { createConnection, createServer } from "node:net";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -58,7 +58,14 @@ function resolveBinary(): string {
     "firefox",
   ];
   for (const c of candidates) {
-    if (c) return c;
+    if (!c) continue;
+    // An ABSOLUTE candidate (FIREFOX_BIN, the macOS app path) is only usable if it exists on this
+    // box — otherwise the hardcoded macOS path would win on Linux and shadow the "firefox" PATH
+    // fallback, yielding ENOENT at spawn. A bare name like "firefox" is not a filesystem path, so
+    // let spawn resolve it against PATH.
+    const isAbsolute = c.startsWith("/");
+    if (isAbsolute && !existsSync(c)) continue;
+    return c;
   }
   throw new Error(
     "Firefox binary not found. Tried FIREFOX_BIN env var, " +

package/src/manifest.ts

@@ -891,14 +891,11 @@ export const MANIFEST: ToolSpec[] = [
           "description": "CSS selector for the file input element (resolved via document.querySelector). Provide exactly one of uid or selector."
         },
         "files": {
-          "type": [
-            "string",
-            "array"
-          ],
+          "type": "array",
           "items": {
             "type": "string"
           },
-          "description": "Absolute path, or array of absolute paths, to the file(s) to attach to the <input type=file>. Accepts a single string or an array of strings."
+          "description": "Absolute path(s) to the file(s) to attach to the <input type=file>, as an array of absolute paths. A single path must be wrapped in an array (e.g. [\"/tmp/a.pdf\"]). Declared array-only because some model APIs (Google Gemini function calling) reject union-typed parameters."
         }
       },
       "required": [

package/src/mcp.ts

@@ -26,7 +26,7 @@ import { toolAvailability } from "./capabilities.ts";
 import { FIREFOX_TOOLS } from "./firefox-tools.ts";
 import { leaseFromArgs, markLongLivedProcess, withLeaseScope } from "./leases.ts";
 
-const VERSION = "1.9.4";
+const VERSION = "1.9.7";
 
 // Backend + (Firefox only) attach endpoint are read once at startup (MCP has no per-call notion
 // of backend): --browser flag / CDP_BROWSER env, else "chrome" (zero behavior change for existing

package/src/tools/recorder.ts

@@ -80,17 +80,20 @@ import {
   WORKER_EMPTY_NEEDLE_MESSAGE,
 } from "../workers.ts";
 
-/** Artifact / buffer directory (shared with the rest of the toolkit). */
-export const ARTIFACT_DIR = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
+/** Artifact / buffer directory (shared with the rest of the toolkit). Read per
+ *  call, not at module load, so a test can redirect the directory (as leases.ts). */
+function artifactDir(): string {
+  return process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
+}
 
 /** Compute the shared "latest" JSONL buffer path for a given targetId. */
 export function recFile(targetId: string): string {
-  return `${ARTIFACT_DIR}/rec-${targetId}.jsonl`;
+  return `${artifactDir()}/rec-${targetId}.jsonl`;
 }
 
 /** Compute a unique per-capture JSONL buffer path (isolates concurrent captures). */
 export function captureFile(targetId: string, captureId: string): string {
-  return `${ARTIFACT_DIR}/rec-${targetId}-${captureId}.jsonl`;
+  return `${artifactDir()}/rec-${targetId}-${captureId}.jsonl`;
 }
 
 /** Sleep helper (module runtime only; not the workflow-script sandbox). */
@@ -200,7 +203,7 @@ export async function startRecorder(target: TargetSelector, opts: RecorderOption
   const network = opts.network ?? true;
   const consoleCap = opts.console ?? true;
 
-  await mkdir(ARTIFACT_DIR, { recursive: true });
+  await mkdir(artifactDir(), { recursive: true });
   const { conn, target: resolved } = await openPage(target, { timeoutMs: opts.timeoutMs });
   const file = opts.file ?? recFile(resolved.id);