cdp-toolkit 1.0.0 → 1.1.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "cdp-toolkit",
-  "version": "1.0.0",
-  "description": "A lightweight chrome-devtools-mcp alternative: a single-target Chrome DevTools Protocol MCP server + CLI that drives one tab over a direct WebSocket with a bounded timeout on every call, so a stuck page can't wedge your agent or force a /mcp restart. 33 tools including built-in network mocking. No Puppeteer, no all-target fan-out.",
+  "version": "1.1.0",
+  "description": "A lightweight chrome-devtools-mcp alternative: a single-target MCP server + CLI that drives one tab over a 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. 33 tools including built-in network mocking. No Puppeteer, no all-target fan-out.",
   "type": "module",
   "license": "MIT",
   "author": {
@@ -11,7 +11,7 @@
   "homepage": "https://github.com/sblattj/cdp-toolkit#readme",
   "repository": {
     "type": "git",
-    "url": "https://github.com/sblattj/cdp-toolkit.git"
+    "url": "git+https://github.com/sblattj/cdp-toolkit.git"
   },
   "bugs": {
     "url": "https://github.com/sblattj/cdp-toolkit/issues"
@@ -32,6 +32,11 @@
     "web-automation",
     "headless-chrome",
     "chrome-automation",
+    "firefox",
+    "firefox-automation",
+    "headless-firefox",
+    "webdriver-bidi",
+    "bidi",
     "network-mocking",
     "api-mocking",
     "claude-code",
@@ -50,8 +55,8 @@
     "./package.json": "./package.json"
   },
   "bin": {
-    "cdp-toolkit": "./dist/mcp.js",
-    "cdp": "./dist/cli.js"
+    "cdp-toolkit": "dist/mcp.js",
+    "cdp": "dist/cli.js"
   },
   "files": [
     "dist/",
@@ -70,7 +75,8 @@
     "test": "bun test",
     "smoke": "bun run ./test/smoke.ts",
     "mock:smoke": "bun run ./test/mock-smoke.ts",
-    "mcp:smoke": "bun run ./test/mcp-smoke.ts"
+    "mcp:smoke": "bun run ./test/mcp-smoke.ts",
+    "firefox:smoke": "bun run ./test/firefox-smoke.ts"
   },
   "devDependencies": {
     "@types/node": "22.10.10",

package/src/backend.ts

@@ -0,0 +1,86 @@
+/**
+ * Backend selection + Firefox process/driver lifetime, shared by cli.ts and mcp.ts.
+ *
+ * Selection precedence: explicit `--browser chrome|firefox` flag, else the
+ * `CDP_BROWSER` env var, else "chrome". Defaulting to chrome is REQUIRED: this
+ * ships to npm and today's users must see zero behavior change unless they
+ * opt in.
+ *
+ * Firefox cannot be attached to (see bidi/launch.ts's header) and its driver
+ * is `lifetime: "session"` (ADR-001), so ownership differs by entry point:
+ *   - CLI: one process per invocation. startFirefoxSession() launches, the
+ *     caller runs exactly one tool call, then disposeFirefoxSession() tears
+ *     the session AND the spawned process down before the process exits.
+ *   - MCP: long-lived. getOrCreateFirefoxSession() launches at most once and
+ *     memoizes the session at module scope; disposeFirefoxSession() runs on
+ *     shutdown (SIGINT/SIGTERM/stdin close), never per tool call.
+ * Both paths funnel through the same FirefoxSession so neither can leak a
+ * Firefox process: dispose() always closes the BiDi session THEN kills the
+ * spawned binary, in that order, and is idempotent.
+ */
+import type { BrowserDriver, DriverKind } from "./driver.ts";
+import { createFirefoxDriver } from "./bidi/driver.ts";
+import { launchFirefox } from "./bidi/launch.ts";
+
+/** Resolve the selected backend from argv (already flag-scanned) + env, defaulting to chrome. */
+export function resolveBrowserKind(argv: readonly string[]): DriverKind {
+  const flagIdx = argv.indexOf("--browser");
+  const flagVal = flagIdx !== -1 ? argv[flagIdx + 1] : undefined;
+  const raw = flagVal ?? process.env.CDP_BROWSER ?? "chrome";
+  if (raw !== "chrome" && raw !== "firefox") {
+    throw new Error(`unknown --browser '${raw}': expected 'chrome' or 'firefox' (or set CDP_BROWSER)`);
+  }
+  return raw;
+}
+
+/** Strip a `--browser <value>` pair out of argv so it never reaches tool-arg parsing. */
+export function stripBrowserFlag(argv: readonly string[]): string[] {
+  const out: string[] = [];
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === "--browser") { i++; continue; }
+    out.push(argv[i]!);
+  }
+  return out;
+}
+
+export interface FirefoxSession {
+  driver: BrowserDriver;
+  dispose(): Promise<void>;
+}
+
+/** Launch a fresh Firefox process and construct its Driver. Caller owns dispose(). */
+export async function startFirefoxSession(opts?: { headless?: boolean }): Promise<FirefoxSession> {
+  const launched = await launchFirefox({ headless: opts?.headless });
+  const driver = createFirefoxDriver(launched.port);
+  let disposed = false;
+  return {
+    driver,
+    async dispose(): Promise<void> {
+      if (disposed) return;
+      disposed = true;
+      // Close the BiDi session before killing the process: dispose() is a clean
+      // protocol-level teardown, close() is the fallback that guarantees no
+      // process survives even if the session was already dead.
+      await driver.dispose().catch(() => undefined);
+      await launched.close();
+    },
+  };
+}
+
+/* -------------------------- MCP-only: one memoized session -------------------------- */
+
+let sessionPromise: Promise<FirefoxSession> | undefined;
+
+/** Lazily launch Firefox at most once per server process; every caller shares it. */
+export function getOrCreateFirefoxSession(): Promise<FirefoxSession> {
+  if (!sessionPromise) sessionPromise = startFirefoxSession();
+  return sessionPromise;
+}
+
+/** Idempotent shutdown hook: no-op if Firefox was never launched this process. */
+export async function disposeFirefoxSession(): Promise<void> {
+  if (!sessionPromise) return;
+  const p = sessionPromise;
+  sessionPromise = undefined;
+  await p.then((s) => s.dispose()).catch(() => undefined);
+}

package/src/bidi/client.ts

@@ -0,0 +1,319 @@
+/**
+ * WebDriver BiDi transport for the Firefox backend, the counterpart to
+ * src/client.ts's raw CDP transport. Zero runtime dependencies, uses
+ * Node's global WebSocket (Node >= 22; verified on Node 25.9). See
+ * CONTRACT.md and driver.ts's ADR-001 for the session lifetime this
+ * transport exists to support.
+ */
+import type { BidiCommands, BidiErrorCode, BidiEventName, BidiEvents, BidiMethod } from "./protocol.ts";
+
+/** Default per-command timeout (ms). Override with BIDI_TIMEOUT_MS. */
+export const DEFAULT_TIMEOUT_MS = Number(process.env.BIDI_TIMEOUT_MS ?? 15_000);
+
+export class BidiError extends Error {
+  constructor(
+    message: string,
+    readonly code?: BidiErrorCode,
+    readonly data?: unknown,
+  ) {
+    super(message);
+    this.name = "BidiError";
+  }
+}
+
+type BidiEventHandler = (params: never) => void;
+
+interface RawSuccess { type: "success"; id: number; result: unknown }
+interface RawErrorMsg { type: "error"; id: number | null; error: BidiErrorCode; message: string }
+interface RawEvent { type: "event"; method: string; params: unknown }
+type RawMessage = RawSuccess | RawErrorMsg | RawEvent;
+
+interface PendingCall {
+  method: string;
+  start: number;
+  timer: ReturnType<typeof setTimeout>;
+  resolve: (raw: RawSuccess | RawErrorMsg) => void;
+  reject: (e: Error) => void;
+}
+
+/**
+ * A single WebDriver BiDi WebSocket connection.
+ *
+ * THE STRUCTURAL DIFFERENCE FROM CDP: a BiDi session is bound to exactly one
+ * socket. Dropping this connection and re-dialing does not resume the
+ * session, a fresh socket sending any command with the old sessionId gets
+ * "invalid session id" (verified against Firefox 153.0.3). So this class,
+ * once its session is established, IS the session: there is no reconnect
+ * path, only retain()/release() bookkeeping around one long-lived socket
+ * that closes exclusively via dispose(). ADR-001 (driver.ts) calls this the
+ * "session" LifetimeModel and depends on exactly this property: tool calls
+ * retain()/release() a shared connection instead of opening and closing
+ * their own.
+ *
+ * Event subscription bookkeeping lives entirely inside on()/waitFor(): BiDi
+ * has no per-domain "enable" the way CDP has Network.enable, only explicit
+ * session.subscribe / session.unsubscribe by event name. CALLERS NEVER
+ * SUBSCRIBE BY HAND. Each event name is refcounted here: the first listener
+ * added triggers session.subscribe, the last one removed triggers
+ * session.unsubscribe.
+ */
+export class BidiConnection {
+  private ws?: WebSocket;
+  private nextId = 0;
+  private sessId?: string;
+  private caps?: unknown;
+  private closed = false;
+  private refCount = 0;
+
+  private readonly pending = new Map<number, PendingCall>();
+  private readonly listeners = new Map<string, Set<BidiEventHandler>>();
+
+  constructor(
+    readonly wsUrl: string,
+    private readonly opts: { timeoutMs?: number } = {},
+  ) {}
+
+  /** The session id from session.new. Undefined until newSession() resolves. */
+  get sessionId(): string | undefined {
+    return this.sessId;
+  }
+
+  /** The capabilities object returned by session.new. */
+  get capabilities(): unknown {
+    return this.caps;
+  }
+
+  /** Current holder count, see retain()/release(). */
+  get holders(): number {
+    return this.refCount;
+  }
+
+  connect(): Promise<this> {
+    return new Promise((resolve, reject) => {
+      const ws = new WebSocket(this.wsUrl);
+      this.ws = ws;
+      const openTimer = setTimeout(
+        () => reject(new BidiError(`connect timeout: ${this.wsUrl}`)),
+        this.opts.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+      );
+      ws.onopen = () => {
+        clearTimeout(openTimer);
+        resolve(this);
+      };
+      ws.onerror = (e: Event) => {
+        clearTimeout(openTimer);
+        const msg = (e as ErrorEvent)?.message ?? "websocket error";
+        if (this.pending.size === 0) reject(new BidiError(msg));
+        this.rejectAll(new BidiError(msg));
+      };
+      ws.onclose = () => {
+        this.closed = true;
+        this.rejectAll(new BidiError("connection closed"));
+      };
+      ws.onmessage = (ev: MessageEvent) => this.onMessage(String(ev.data));
+    });
+  }
+
+  /**
+   * Create the BiDi session on this socket (session.new). Call once,
+   * immediately after connect(); everything else on this connection assumes
+   * a session already exists. Stores the returned sessionId/capabilities.
+   */
+  async newSession(
+    capabilities: BidiCommands["session.new"]["params"]["capabilities"] = {},
+  ): Promise<string> {
+    const result = await this.send("session.new", { capabilities });
+    this.sessId = result.sessionId;
+    this.caps = result.capabilities;
+    return result.sessionId;
+  }
+
+  private onMessage(raw: string): void {
+    let msg: RawMessage;
+    try {
+      msg = JSON.parse(raw);
+    } catch {
+      return;
+    }
+    if (msg.type === "success" || msg.type === "error") {
+      const id = msg.id;
+      if (typeof id !== "number" || !this.pending.has(id)) return;
+      const p = this.pending.get(id)!;
+      clearTimeout(p.timer);
+      this.pending.delete(id);
+      p.resolve(msg);
+      return;
+    }
+    if (msg.type === "event") {
+      const set = this.listeners.get(msg.method);
+      if (set) for (const h of set) h(msg.params as never);
+    }
+  }
+
+  /** Every in-flight promise rejects, never hangs, when the socket dies. */
+  private rejectAll(err: Error): void {
+    for (const [, p] of this.pending) {
+      clearTimeout(p.timer);
+      p.reject(err);
+    }
+    this.pending.clear();
+  }
+
+  /**
+   * Send a BiDi command and await its result. Generic over `method` alone:
+   * params and result both come from BidiCommands[M], so a caller gets full
+   * inference from just the method-name string literal. Rejects on a BiDi
+   * error response (typed BidiError carrying the wire code) or on timeout.
+   */
+  send<M extends BidiMethod>(
+    method: M,
+    params: BidiCommands[M]["params"],
+    opts: { timeoutMs?: number } = {},
+  ): Promise<BidiCommands[M]["result"]> {
+    if (this.closed || !this.ws) return Promise.reject(new BidiError("connection not open"));
+    const id = ++this.nextId;
+    const timeoutMs = opts.timeoutMs ?? this.opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const payload = { id, method, params };
+    return new Promise((resolve, reject) => {
+      const start = Date.now();
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        const elapsed = Date.now() - start;
+        reject(new BidiError(`'${method}' timed out after ${elapsed}ms`));
+      }, timeoutMs);
+      this.pending.set(id, {
+        method,
+        start,
+        timer,
+        resolve: (raw) => {
+          if (raw.type === "error") reject(new BidiError(`${method}: ${raw.message}`, raw.error));
+          else resolve(raw.result as BidiCommands[M]["result"]);
+        },
+        reject,
+      });
+      this.ws!.send(JSON.stringify(payload));
+    });
+  }
+
+  /**
+   * Subscribe to a BiDi event. Handles session.subscribe / session.unsubscribe
+   * bookkeeping internally: refcounted per event name, subscribes on the
+   * first listener, unsubscribes when the last one is removed. Returns an
+   * unsubscribe function; callers never call session.subscribe themselves.
+   */
+  on<E extends BidiEventName>(event: E, handler: (params: BidiEvents[E]) => void): () => void {
+    let set = this.listeners.get(event);
+    if (!set) {
+      set = new Set();
+      this.listeners.set(event, set);
+    }
+    const first = set.size === 0;
+    set.add(handler as BidiEventHandler);
+    if (first) {
+      this.send("session.subscribe", { events: [event] }).catch(() => {
+        /* best effort: a failed subscribe surfaces as missing events, not a thrown error here */
+      });
+    }
+
+    let removed = false;
+    return () => {
+      if (removed) return;
+      removed = true;
+      const s = this.listeners.get(event);
+      s?.delete(handler as BidiEventHandler);
+      if (s && s.size === 0) {
+        this.send("session.unsubscribe", { events: [event] }).catch(() => {
+          /* best effort on teardown */
+        });
+      }
+    };
+  }
+
+  /**
+   * Resolve when an event matching `event` (and optional predicate) fires,
+   * or reject on timeout. Subscribes via on(), so the refcounting above
+   * applies here too, an unmatched waitFor still unsubscribes cleanly.
+   */
+  waitFor<E extends BidiEventName>(
+    event: E,
+    predicate?: (params: BidiEvents[E]) => boolean,
+    timeoutMs = this.opts.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+  ): Promise<BidiEvents[E]> {
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        off();
+        reject(new BidiError(`waitFor('${event}') timed out after ${timeoutMs}ms`));
+      }, timeoutMs);
+      const off = this.on(event, (params) => {
+        if (!predicate || predicate(params)) {
+          clearTimeout(timer);
+          off();
+          resolve(params);
+        }
+      });
+    });
+  }
+
+  /**
+   * Add a holder. Under the "session" LifetimeModel (driver.ts) the socket
+   * outlives individual tool calls, so acquiring a page handle retains this
+   * connection instead of opening a new one.
+   */
+  retain(): void {
+    this.refCount++;
+  }
+
+  /** Remove a holder. Does NOT close the socket, only dispose() does that. */
+  release(): void {
+    if (this.refCount > 0) this.refCount--;
+  }
+
+  /**
+   * Close the socket. Idempotent. Every in-flight send()/waitFor() and any
+   * future call rejects with a clear "disposed" BidiError rather than
+   * hanging, which is the whole point of this transport.
+   */
+  dispose(): void {
+    if (this.closed) return;
+    this.closed = true;
+    this.rejectAll(new BidiError("connection disposed"));
+    try {
+      this.ws?.close();
+    } catch {
+      /* ignore */
+    }
+  }
+}
+
+/**
+ * Open a BiDi connection to a Firefox debug port and create its session in
+ * one step, per the established endpoint shape ws://127.0.0.1:<port>/session.
+ * This module does not launch Firefox; pass a port from launch.ts's
+ * launchFirefox() or any other running Firefox with the debug port open.
+ * The returned connection is retained once (holders === 1): the caller owns
+ * that first retain and must release() or dispose() it.
+ */
+export async function connectBidiSession(
+  port: number,
+  opts: {
+    timeoutMs?: number;
+    capabilities?: BidiCommands["session.new"]["params"]["capabilities"];
+  } = {},
+): Promise<BidiConnection> {
+  const conn = new BidiConnection(`ws://127.0.0.1:${port}/session`, { timeoutMs: opts.timeoutMs });
+  await conn.connect();
+  await conn.newSession(opts.capabilities ?? {});
+  conn.retain();
+  return conn;
+}
+
+/*
+ * BiDi modules/commands used: session (session.new, session.subscribe,
+ * session.unsubscribe). All other modules (browsingContext, script, input,
+ * network, storage, log, emulation) are exercised generically through the
+ * typed send()/on()/waitFor() surface above but this file itself calls none
+ * of their commands directly, that is left to the driver and tool layers
+ * built on top. Parity gap vs client.ts: there is no browserWsUrl/listTargets
+ * equivalent here, BiDi's endpoint discovery is the single fixed
+ * ws://127.0.0.1:<port>/session path, so no HTTP discovery step exists.
+ */