cdp-toolkit 1.9.5 → 1.9.7

package/CHANGELOG.md

@@ -5,6 +5,44 @@ 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

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.5";
+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.5",
+  "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

@@ -322,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

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.5";
+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);