cdp-toolkit 1.10.0 → 1.11.0

package/dist/mcp.js

@@ -7081,6 +7081,252 @@ async function connectBidiSessionUrl(wsUrl, opts = {}) {
   return conn;
 }
 
+// src/bidi/session-lease.ts
+import { mkdir as mkdir12, readFile as readFile8, unlink as unlink5, writeFile as writeFile9 } from "node:fs/promises";
+import { join as join10 } from "node:path";
+var DEFAULT_SESSION_WAIT_MS = 1e4;
+var DEFAULT_POLL_MS = 250;
+function safeEndpoint(endpoint) {
+  return endpoint.replace(/[^A-Za-z0-9._-]/g, "_");
+}
+function sessionSlotFile(endpoint) {
+  return join10(leaseDir(), `ff-session-${safeEndpoint(endpoint)}.json`);
+}
+function sessionWaitMs() {
+  const raw = Number(process.env.CDP_FIREFOX_SESSION_WAIT_MS);
+  return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_SESSION_WAIT_MS;
+}
+
+class SessionSlotBusyError extends Error {
+  endpoint;
+  holderPid;
+  holderLabel;
+  constructor(endpoint, holder) {
+    const who = holder ? `'${holder.label}' (pid ${holder.pid})` : "another live process";
+    super(`Firefox BiDi session slot for endpoint '${endpoint}' is held by ${who}. ` + `Firefox serves exactly ONE WebDriver-BiDi session per browser instance, and this slot is held ` + `by a LIVE process, so it cannot be taken. Wait for that process to release it and retry, or point ` + `this server at a different endpoint/browser.`);
+    this.name = "SessionSlotBusyError";
+    this.endpoint = endpoint;
+    if (holder) {
+      this.holderPid = holder.pid;
+      this.holderLabel = holder.label;
+    }
+  }
+}
+async function readSessionSlot(endpoint) {
+  let raw;
+  try {
+    raw = await readFile8(sessionSlotFile(endpoint), "utf8");
+  } catch (err) {
+    if (err.code === "ENOENT")
+      return;
+    throw err;
+  }
+  try {
+    const rec = JSON.parse(raw);
+    if (typeof rec?.pid === "number" && typeof rec?.endpoint === "string" && typeof rec?.label === "string") {
+      return rec;
+    }
+  } catch {}
+  return;
+}
+async function acquireSessionSlot(endpoint, opts) {
+  const waitMs = opts.waitMs ?? sessionWaitMs();
+  const pollMs = opts.pollMs !== undefined && opts.pollMs > 0 ? opts.pollMs : DEFAULT_POLL_MS;
+  const createdAt = opts.now ?? Date.now();
+  const file = sessionSlotFile(endpoint);
+  const record2 = {
+    endpoint,
+    pid: process.pid,
+    label: opts.label,
+    createdAt
+  };
+  if (opts.marionettePort !== undefined)
+    record2.marionettePort = opts.marionettePort;
+  const handle = { endpoint, pid: process.pid, createdAt };
+  const payload = JSON.stringify(record2);
+  await mkdir12(leaseDir(), { recursive: true });
+  const deadline = Date.now() + waitMs;
+  const maxAttempts = Math.max(100, Math.ceil(waitMs / pollMs) + 100);
+  let attempts = 0;
+  let lastLiveHolder;
+  while (true) {
+    if (attempts >= maxAttempts)
+      throw new SessionSlotBusyError(endpoint, lastLiveHolder);
+    attempts++;
+    try {
+      await writeFile9(file, payload, { flag: "wx" });
+      return { handle };
+    } catch (err) {
+      if (err.code !== "EEXIST")
+        throw err;
+    }
+    const holder = await readSessionSlot(endpoint);
+    if (!holder)
+      continue;
+    if (!isPidAlive(holder.pid)) {
+      await unlink5(file).catch(() => {
+        return;
+      });
+      try {
+        await writeFile9(file, payload, { flag: "wx" });
+        return { handle, staleHolder: holder };
+      } catch (err) {
+        if (err.code !== "EEXIST")
+          throw err;
+        continue;
+      }
+    }
+    lastLiveHolder = holder;
+    const remaining = deadline - Date.now();
+    if (remaining <= 0)
+      throw new SessionSlotBusyError(endpoint, holder);
+    await sleep2(Math.min(pollMs, remaining));
+  }
+}
+async function releaseSessionSlot(handle) {
+  const current = await readSessionSlot(handle.endpoint);
+  if (!current)
+    return { released: false };
+  if (current.pid !== process.pid || current.createdAt !== handle.createdAt)
+    return { released: false };
+  await unlink5(sessionSlotFile(handle.endpoint)).catch(() => {
+    return;
+  });
+  return { released: true };
+}
+function sleep2(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// src/bidi/marionette.ts
+import { Socket } from "node:net";
+var DEFAULT_MARIONETTE_PORT = 2828;
+var DEFAULT_TIMEOUT_MS3 = 4000;
+var HOST = "127.0.0.1";
+var COLON = 58;
+var DELETE_SESSION_FRAME = encodeFrame([0, 1, "WebDriver:DeleteSession", {}]);
+function defaultMarionettePort() {
+  const raw = Number(process.env.CDP_FIREFOX_MARIONETTE_PORT);
+  return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_MARIONETTE_PORT;
+}
+function encodeFrame(json) {
+  const body = Buffer.from(JSON.stringify(json), "utf8");
+  const prefix = Buffer.from(`${body.length}:`, "ascii");
+  return Buffer.concat([prefix, body]);
+}
+
+class MarionetteProtocolError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "MarionetteProtocolError";
+  }
+}
+
+class FrameDecoder {
+  buf = Buffer.alloc(0);
+  push(chunk) {
+    this.buf = this.buf.length === 0 ? chunk : Buffer.concat([this.buf, chunk]);
+  }
+  next() {
+    const colon = this.buf.indexOf(COLON);
+    if (colon === -1) {
+      this.assertDigitsPrefix(this.buf.length);
+      return;
+    }
+    if (colon === 0)
+      throw new MarionetteProtocolError("empty frame length prefix");
+    this.assertDigitsPrefix(colon);
+    const len = Number.parseInt(this.buf.toString("ascii", 0, colon), 10);
+    const start = colon + 1;
+    const end = start + len;
+    if (this.buf.length < end)
+      return;
+    const payload = this.buf.toString("utf8", start, end);
+    this.buf = this.buf.subarray(end);
+    try {
+      return JSON.parse(payload);
+    } catch {
+      throw new MarionetteProtocolError(`frame body was not valid JSON (${len} bytes): ${payload.slice(0, 80)}`);
+    }
+  }
+  assertDigitsPrefix(upTo) {
+    for (let i = 0;i < upTo; i++) {
+      const b = this.buf[i];
+      if (b < 48 || b > 57) {
+        throw new MarionetteProtocolError(`non-digit byte 0x${b.toString(16)} in frame length prefix`);
+      }
+    }
+  }
+}
+function isSlotFreedReply(frame) {
+  if (!Array.isArray(frame))
+    return false;
+  const err = frame[2];
+  if (err === null)
+    return true;
+  if (typeof err === "object" && err !== null && err.error === "invalid session id") {
+    return true;
+  }
+  return false;
+}
+function forceClearOrphanSession(marionettePort, opts = {}) {
+  const timeoutMs = opts.timeoutMs !== undefined && Number.isFinite(opts.timeoutMs) && opts.timeoutMs > 0 ? opts.timeoutMs : DEFAULT_TIMEOUT_MS3;
+  return new Promise((resolve) => {
+    if (!Number.isFinite(marionettePort) || marionettePort <= 0 || marionettePort > 65535) {
+      resolve(false);
+      return;
+    }
+    const sock = new Socket;
+    const decoder = new FrameDecoder;
+    let settled = false;
+    let handshakeSeen = false;
+    let commandSent = false;
+    const settle = (value) => {
+      if (settled)
+        return;
+      settled = true;
+      clearTimeout(timer);
+      sock.removeAllListeners();
+      sock.destroy();
+      resolve(value);
+    };
+    const timer = setTimeout(() => settle(false), timeoutMs);
+    if (typeof timer.unref === "function")
+      timer.unref();
+    sock.on("error", () => settle(false));
+    sock.on("close", () => settle(false));
+    sock.on("data", (chunk) => {
+      if (settled)
+        return;
+      try {
+        decoder.push(chunk);
+        for (;; ) {
+          const frame = decoder.next();
+          if (frame === undefined)
+            break;
+          if (!handshakeSeen) {
+            handshakeSeen = true;
+            continue;
+          }
+          settle(isSlotFreedReply(frame));
+          return;
+        }
+        if (handshakeSeen && !commandSent) {
+          commandSent = true;
+          sock.write(DELETE_SESSION_FRAME);
+        }
+      } catch {
+        settle(false);
+      }
+    });
+    try {
+      sock.connect(marionettePort, HOST);
+    } catch {
+      settle(false);
+    }
+  });
+}
+
 // src/bidi/snapshot.ts
 var STAMP_ATTR = "data-cdp-uid";
 async function takeStampedSnapshot(evaluate) {
@@ -7657,6 +7903,22 @@ var BIDI_CAPABILITIES = new Set([
   "locate.xpath"
 ]);
 var connections = new Map;
+var slotHandles = new Map;
+var connecting = new Map;
+async function releaseSlotOnDialFailure(endpoint, owned) {
+  if (owned)
+    return;
+  const h = slotHandles.get(endpoint);
+  if (h) {
+    await releaseSessionSlot(h).catch(() => {
+      return;
+    });
+    slotHandles.delete(endpoint);
+  }
+}
+function orphanNotClearedError(endpoint) {
+  return driverError2("disconnected", `Firefox holds an orphaned WebDriver BiDi session on ${endpoint} that could not be auto-cleared. ` + `Marionette recovery needs Firefox launched with --marionette (default port 2828, or set ` + `CDP_FIREFOX_MARIONETTE_PORT); otherwise restart Firefox to free the slot. (A client killed without ` + `session.end can leave a session Firefox does not reap.)`);
+}
 async function getConnection(endpoint, timeoutMs) {
   const existing = connections.get(endpoint);
   if (existing && existing.isOpen) {
@@ -7665,17 +7927,68 @@ async function getConnection(endpoint, timeoutMs) {
   }
   if (existing)
     connections.delete(endpoint);
-  const conn = await connectBidiSessionUrl(endpoint, {
-    ...timeoutMs !== undefined ? { timeoutMs } : {},
-    capabilities: { alwaysMatch: { unhandledPromptBehavior: { default: "ignore" } } }
-  }).catch((e) => {
-    if (e instanceof BidiError && /maximum number of active sessions/i.test(e.message)) {
-      throw driverError2("disconnected", `Firefox already has an active WebDriver BiDi session on ${endpoint}; it allows only one. ` + `Close the other client, or restart Firefox, then retry. (A previously killed client can leave a ` + `session that Firefox does not reap.)`);
+  const inflight = connecting.get(endpoint);
+  if (inflight) {
+    const conn = await inflight;
+    conn.retain();
+    return conn;
+  }
+  const create = (async () => {
+    const mport = defaultMarionettePort();
+    const owned = slotHandles.has(endpoint);
+    if (!owned) {
+      let acq;
+      try {
+        acq = await acquireSessionSlot(endpoint, { label: defaultLabel(), marionettePort: mport });
+      } catch (e) {
+        if (e instanceof SessionSlotBusyError) {
+          const who = e.holderLabel ? `'${e.holderLabel}' (pid ${e.holderPid})` : "another live process";
+          throw driverError2("disconnected", `Firefox's single WebDriver BiDi session on ${endpoint} is held by a LIVE process ${who}. ` + `Firefox serves exactly ONE BiDi session per browser instance, so this server cannot take it ` + `while that process is running. Wait for it to release the session and retry, or point this ` + `server at a different endpoint/browser.`);
+        }
+        throw e;
+      }
+      slotHandles.set(endpoint, acq.handle);
+      if (acq.staleHolder) {
+        await forceClearOrphanSession(acq.staleHolder.marionettePort ?? mport);
+      }
     }
-    throw e;
-  });
-  connections.set(endpoint, conn);
-  return conn;
+    const dialOpts = {
+      ...timeoutMs !== undefined ? { timeoutMs } : {},
+      capabilities: { alwaysMatch: { unhandledPromptBehavior: { default: "ignore" } } }
+    };
+    let conn;
+    try {
+      conn = await connectBidiSessionUrl(endpoint, dialOpts);
+    } catch (e) {
+      if (e instanceof BidiError && /maximum number of active sessions/i.test(e.message)) {
+        const cleared = await forceClearOrphanSession(mport);
+        if (!cleared) {
+          await releaseSlotOnDialFailure(endpoint, owned);
+          throw orphanNotClearedError(endpoint);
+        }
+        try {
+          conn = await connectBidiSessionUrl(endpoint, dialOpts);
+        } catch (e2) {
+          await releaseSlotOnDialFailure(endpoint, owned);
+          if (e2 instanceof BidiError && /maximum number of active sessions/i.test(e2.message)) {
+            throw orphanNotClearedError(endpoint);
+          }
+          throw e2;
+        }
+      } else {
+        await releaseSlotOnDialFailure(endpoint, owned);
+        throw e;
+      }
+    }
+    connections.set(endpoint, conn);
+    return conn;
+  })();
+  connecting.set(endpoint, create);
+  try {
+    return await create;
+  } finally {
+    connecting.delete(endpoint);
+  }
 }
 var bidiBeaconScripts = new Map;
 async function safeTitle(conn, contextId) {
@@ -8441,14 +8754,27 @@ class BidiBrowserDriver {
       if (key.startsWith(`${this.endpoint}:`))
         bidiBeaconScripts.delete(key);
     }
+    connecting.delete(this.endpoint);
     const conn = connections.get(this.endpoint);
-    if (!conn)
+    if (!conn) {
+      await this.releaseSessionSlotIfHeld();
       return;
+    }
     connections.delete(this.endpoint);
     await conn.send("session.end", {}).catch(() => {
       return;
     });
     conn.dispose();
+    await this.releaseSessionSlotIfHeld();
+  }
+  async releaseSessionSlotIfHeld() {
+    const h = slotHandles.get(this.endpoint);
+    if (!h)
+      return;
+    await releaseSessionSlot(h).catch(() => {
+      return;
+    });
+    slotHandles.delete(this.endpoint);
   }
 }
 function createFirefoxDriver(port, opts) {
@@ -8463,7 +8789,7 @@ import { spawn as spawn3 } from "node:child_process";
 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";
+import { join as join11 } from "node:path";
 function resolveBinary() {
   const candidates = [
     process.env.FIREFOX_BIN,
@@ -8541,7 +8867,7 @@ async function launchFirefox(opts = {}) {
   const binary = resolveBinary();
   const port = await pickPort(opts.port);
   const isThrowaway = opts.profilePath === undefined;
-  const profilePath = opts.profilePath ?? mkdtempSync(join10(tmpdir(), "cdp-toolkit-ff-profile-"));
+  const profilePath = opts.profilePath ?? mkdtempSync(join11(tmpdir(), "cdp-toolkit-ff-profile-"));
   const args = ["--profile", profilePath, "--remote-debugging-port", String(port), "--no-remote"];
   if (opts.headless)
     args.push("--headless");
@@ -8892,7 +9218,7 @@ var FIREFOX_TOOLS = {
 };
 
 // src/mcp.ts
-var VERSION = "1.10.0";
+var VERSION = "1.11.0";
 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.10.0",
+  "version": "1.11.0",
   "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",
@@ -79,6 +79,7 @@
     "mcp:smoke": "bun run ./test/mcp-smoke.ts",
     "firefox:smoke": "bun run ./test/firefox-smoke.ts",
     "firefox:attach:smoke": "bun run ./test/firefox-attach-smoke.ts",
+    "firefox:coord:smoke": "bun run ./test/firefox-session-coord-smoke.ts",
     "lease:smoke": "bun run ./test/lease-smoke.ts",
     "staleness:smoke": "bun run ./test/staleness-smoke.ts",
     "input:smoke": "bun run ./test/input-smoke.ts",