cdp-toolkit 1.10.0 → 2.0.0

package/src/bidi/marionette.ts

@@ -0,0 +1,276 @@
+/**
+ * Minimal Firefox Marionette client — orphan BiDi-session recovery, issue #4.
+ *
+ * WHAT THIS IS FOR, AND NOTHING ELSE. Firefox serves exactly ONE
+ * WebDriver-BiDi session per browser instance, and Marionette and BiDi SHARE
+ * that one global session slot. When a cdp-toolkit process dies mid-drive it can
+ * leave Firefox believing a BiDi session is still active; the next `session.new`
+ * then fails with "Maximum number of active sessions" even though no live
+ * process holds it. `session-lease.ts` detects that a dead process left the slot
+ * occupied (its `staleHolder`); THIS module is the mechanism that then frees the
+ * slot inside Firefox itself, WITHOUT killing the browser — so a user's real,
+ * logged-in Firefox keeps running and only the orphaned session is cleared.
+ *
+ * WHY MARIONETTE AND NOT BIDI. The BiDi endpoint is what's wedged: it refuses a
+ * new session while the orphan is "active", and it exposes no cross-session
+ * teardown. Marionette is Firefox's OTHER, older remote-control channel (a raw
+ * TCP port, `--marionette`, default 2828). Because the two dialects share the
+ * one session slot, a single Marionette `WebDriver:DeleteSession` tears down
+ * whatever occupies that slot — the orphaned BiDi session included — as a blind
+ * cross-dialect teardown. No `WebDriver:NewSession` is needed first: DeleteSession
+ * against an empty slot is a harmless no-op ("invalid session id").
+ *
+ * THE WIRE PROTOCOL ("packet" dialect, marionetteProtocol 3), proven against
+ * Firefox 153.0.3:
+ *   - Framing, both directions: `<utf8-byte-length>:<json>` — the ASCII decimal
+ *     byte count of the JSON body, a literal ':', then exactly that many bytes of
+ *     UTF-8 JSON. Frames coalesce and split across TCP reads; the decoder handles
+ *     both (see FrameDecoder).
+ *   - On connect, Firefox immediately PUSHES a handshake frame (a bare object,
+ *     e.g. `50:{"applicationType":"gecko","marionetteProtocol":3}`) that a client
+ *     must consume before anything else.
+ *   - Command frame:  `[0, msgId, "Command:Name", params]`.
+ *   - Response frame: `[1, msgId, error_or_null, result_or_null]`.
+ *
+ * ZERO RUNTIME DEPENDENCIES: only `node:net`.
+ */
+import { Socket } from "node:net";
+
+/** Firefox's default Marionette control port. */
+const DEFAULT_MARIONETTE_PORT = 2828;
+/** Whole-exchange budget: connect + handshake + command + reply. */
+const DEFAULT_TIMEOUT_MS = 4000;
+/** Marionette listens on loopback only; never dial anything else. */
+const HOST = "127.0.0.1";
+/** ASCII ':' — the length/body delimiter in the packet framing. */
+const COLON = 0x3a;
+
+/**
+ * The one command we ever send. Marionette + BiDi share the single session slot,
+ * so this blindly tears down whatever occupies it (the orphaned BiDi session)
+ * with no NewSession first. Precomputed once: `34:[0,1,"WebDriver:DeleteSession",{}]`.
+ */
+const DELETE_SESSION_FRAME = encodeFrame([0, 1, "WebDriver:DeleteSession", {}]);
+
+/**
+ * The Marionette control port to target. Reads `CDP_FIREFOX_MARIONETTE_PORT`
+ * per call (like session-lease.ts's env getters, so a test can redirect it); a
+ * value that is not a finite number > 0 falls back to Firefox's 2828 default.
+ */
+export function defaultMarionettePort(): number {
+  const raw = Number(process.env.CDP_FIREFOX_MARIONETTE_PORT);
+  return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_MARIONETTE_PORT;
+}
+
+/**
+ * Encode one value as a Marionette wire frame: `<utf8-byte-length>:<utf8-json>`.
+ * The length prefix is the BYTE count of the JSON body (not its character
+ * count), so multi-byte UTF-8 payloads frame correctly. Pure; exported for tests.
+ */
+export function encodeFrame(json: unknown): Buffer {
+  const body = Buffer.from(JSON.stringify(json), "utf8");
+  const prefix = Buffer.from(`${body.length}:`, "ascii");
+  return Buffer.concat([prefix, body]);
+}
+
+/**
+ * Raised when the byte stream is not valid Marionette framing — a non-digit in
+ * the length prefix, or a frame body that is complete but not parseable JSON.
+ * FrameDecoder.next() throws this; forceClearOrphanSession catches it and
+ * degrades to `false` (a wedged/unparseable channel cannot confirm a free slot).
+ */
+export class MarionetteProtocolError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "MarionetteProtocolError";
+  }
+}
+
+/**
+ * Incremental decoder for the `<byte-length>:<json>` framing. Feed raw TCP
+ * chunks with push(); pull one complete, parsed frame per next() call.
+ *
+ * Handles the two things naive framing gets wrong on a real socket: a single
+ * frame SPLIT across several reads (next() returns undefined until the whole
+ * body has arrived) and several frames COALESCED into one read (repeated next()
+ * calls drain them one at a time). Exported for unit testing against known
+ * byte vectors.
+ */
+export class FrameDecoder {
+  private buf: Buffer = Buffer.alloc(0);
+
+  /** Append a chunk of bytes. Cheap: no scan happens here. */
+  push(chunk: Buffer): void {
+    this.buf = this.buf.length === 0 ? chunk : Buffer.concat([this.buf, chunk]);
+  }
+
+  /**
+   * Return the next complete frame as its parsed value, or undefined when more
+   * bytes are still needed to complete the frame currently at the front of the
+   * buffer. Throws MarionetteProtocolError on malformed framing/JSON.
+   */
+  next(): unknown | undefined {
+    const colon = this.buf.indexOf(COLON);
+    if (colon === -1) {
+      // No delimiter yet. Everything buffered so far must be ASCII digits, or
+      // this is not Marionette framing and never will be — fail fast instead of
+      // buffering garbage until the caller's timeout.
+      this.assertDigitsPrefix(this.buf.length);
+      return undefined;
+    }
+    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 undefined; // body not fully arrived yet
+
+    const payload = this.buf.toString("utf8", start, end);
+    this.buf = this.buf.subarray(end); // keep any trailing bytes for the next frame
+    try {
+      return JSON.parse(payload);
+    } catch {
+      throw new MarionetteProtocolError(
+        `frame body was not valid JSON (${len} bytes): ${payload.slice(0, 80)}`,
+      );
+    }
+  }
+
+  /** Every byte in buf[0, upTo) must be an ASCII digit, or the framing is bad. */
+  private assertDigitsPrefix(upTo: number): void {
+    for (let i = 0; i < upTo; i++) {
+      const b = this.buf[i]!;
+      if (b < 0x30 || b > 0x39) {
+        throw new MarionetteProtocolError(
+          `non-digit byte 0x${b.toString(16)} in frame length prefix`,
+        );
+      }
+    }
+  }
+}
+
+/**
+ * Interpret a `WebDriver:DeleteSession` reply frame `[1, msgId, error, result]`.
+ * The slot is FREE (return true) in exactly two shapes:
+ *   - error === null (result `{"value":null}`): an active session existed and
+ *     was cleared.
+ *   - error is an object with error === "invalid session id": the slot was
+ *     already empty — DeleteSession was a no-op.
+ * Any other shape (a different error, a non-response, a malformed frame) cannot
+ * confirm the slot is free, so it returns false.
+ */
+function isSlotFreedReply(frame: unknown): boolean {
+  if (!Array.isArray(frame)) return false;
+  const err: unknown = frame[2];
+  if (err === null) return true; // session existed and was cleared
+  if (typeof err === "object" && err !== null && (err as { error?: unknown }).error === "invalid session id") {
+    return true; // slot was already empty
+  }
+  return false; // any other error: cannot confirm
+}
+
+/**
+ * Force-clear an orphaned WebDriver-BiDi session so a subsequent BiDi
+ * `session.new` succeeds, WITHOUT killing Firefox.
+ *
+ * Connects to Marionette on `127.0.0.1:<marionettePort>`, drains the pushed
+ * handshake frame, sends exactly one `WebDriver:DeleteSession`, reads exactly one
+ * reply, and returns whether the session slot is now free.
+ *
+ * NEVER THROWS and NEVER LEAKS THE SOCKET. Every terminal path — success, a
+ * refused connection (Marionette not running because Firefox was not launched
+ * with --marionette; the NORMAL degrade case, not a loud error), a connect/read
+ * timeout, any socket error, a premature close, or an unexpected/unparseable
+ * reply — routes through a single settle() that destroys the socket exactly once
+ * and resolves the promise. Returns true only when the slot is confirmed free.
+ *
+ * @param marionettePort  TCP port Firefox's Marionette server listens on.
+ * @param opts.timeoutMs  Whole-exchange budget (connect+handshake+command+reply).
+ *                        Default 4000ms. On timeout the socket is destroyed and
+ *                        the result is false.
+ */
+export function forceClearOrphanSession(
+  marionettePort: number,
+  opts: { timeoutMs?: number } = {},
+): Promise<boolean> {
+  const timeoutMs =
+    opts.timeoutMs !== undefined && Number.isFinite(opts.timeoutMs) && opts.timeoutMs > 0
+      ? opts.timeoutMs
+      : DEFAULT_TIMEOUT_MS;
+
+  return new Promise<boolean>((resolve) => {
+    // Guard a nonsense port up front: net.Socket.connect throws synchronously on
+    // an out-of-range/NaN port, and that throw must not escape as a rejection.
+    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;
+
+    // One-shot terminal path. Idempotent (settled guard), removes listeners so a
+    // close/error triggered by our own destroy() can't re-enter, and ALWAYS
+    // destroys the socket — this is the single place the socket is torn down, so
+    // no code path can return without freeing it.
+    const settle = (value: boolean): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      sock.removeAllListeners();
+      sock.destroy();
+      resolve(value);
+    };
+
+    // The timeout covers the WHOLE exchange, including connect. unref() so a
+    // hosting process is never held open by this timer alone.
+    const timer = setTimeout(() => settle(false), timeoutMs);
+    if (typeof timer.unref === "function") timer.unref();
+
+    // ECONNREFUSED (no Marionette on the port) and every other socket error are
+    // the normal degrade to false — quiet, not logged.
+    sock.on("error", () => settle(false));
+    // Peer closed before we got a reply: can't confirm, degrade to false.
+    sock.on("close", () => settle(false));
+
+    sock.on("data", (chunk: Buffer) => {
+      if (settled) return;
+      try {
+        decoder.push(chunk);
+        for (;;) {
+          const frame = decoder.next();
+          if (frame === undefined) break; // need more bytes for the front frame
+          if (!handshakeSeen) {
+            // First frame is Firefox's handshake (a bare object). Consume and
+            // discard it, then keep draining in case a later frame coalesced.
+            handshakeSeen = true;
+            continue;
+          }
+          // First post-handshake frame is our DeleteSession reply. Done.
+          settle(isSlotFreedReply(frame));
+          return;
+        }
+        // Handshake in hand and command not yet on the wire → send it once.
+        if (handshakeSeen && !commandSent) {
+          commandSent = true;
+          sock.write(DELETE_SESSION_FRAME);
+        }
+      } catch {
+        // Malformed framing/JSON: the channel can't confirm a free slot.
+        settle(false);
+      }
+    });
+
+    // connect() can still throw synchronously (e.g. a mid-range but invalid
+    // arg); route that through settle so nothing escapes as a rejection.
+    try {
+      sock.connect(marionettePort, HOST);
+    } catch {
+      settle(false);
+    }
+  });
+}

package/src/bidi/session-lease.ts

@@ -0,0 +1,265 @@
+/**
+ * Firefox BiDi SESSION-slot lease: cross-process coordination for the ONE
+ * WebDriver-BiDi session a single Firefox instance will serve.
+ *
+ * WHY THIS EXISTS. Firefox admits exactly one active WebDriver-BiDi session per
+ * browser. When two cdp-toolkit MCP-server processes ATTACH to the same
+ * user-launched Firefox endpoint (e.g. ws://127.0.0.1:9223/session), they both
+ * want that one slot. Today the second process calls session.new and gets a
+ * hard "Maximum number of active sessions" with no way to tell a LIVE holder
+ * (another agent legitimately driving the browser) from a DEAD one (a crashed
+ * process that left the slot occupied). This module makes that distinction on
+ * disk, so a live holder is respected and a dead holder's orphan is reclaimed.
+ *
+ * WHY A FILE, AND WHY KEYED BY ENDPOINT. Same reasoning as the tab leases in
+ * ../leases.ts: two MCP servers are two processes, so in-process state would
+ * guard the wrong boundary. The tab lease is keyed by (backend, targetId)
+ * because it owns a tab; this lease is keyed by the BiDi ws ENDPOINT string
+ * because it owns the browser's single session slot, which is a property of the
+ * endpoint, not of any tab. One lock file per endpoint.
+ *
+ * WHY NO NONCE/TOKEN. A tab lease mints a nonce because a caller passes a token
+ * back and a reclamation must invalidate the superseded one. Nobody passes a
+ * session token back here: the slot is owned by whichever process currently
+ * holds the live BiDi connection and is released on dispose. Ownership is
+ * therefore identified by (pid, createdAt) of the record we wrote, which is
+ * enough to keep release from unlinking a record another process created after
+ * stealing the slot from us.
+ *
+ * WHY STALENESS IS PURE PID-LIVENESS, WITH NO TTL. A long-lived MCP server can
+ * legitimately hold the slot for hours, so a time-based expiry would reap a
+ * healthy holder. The only thing that makes a holder illegitimate is that its
+ * process is gone. So the sole staleness test is isPidAlive (reused from
+ * ../leases.ts): pid alive -> legitimate holder; pid dead -> orphan to steal.
+ *
+ * ATOMICITY. Claims are exclusive creates (writeFile flag "wx"), exactly like
+ * ../leases.ts claimLease, so "is the slot free, and if so take it" is atomic
+ * against a racing process for free, with no registry lock.
+ */
+import { mkdir, readFile, unlink, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { isPidAlive, leaseDir } from "../leases.ts";
+
+/**
+ * The on-disk record for a held session slot. Keyed by endpoint (one file per
+ * endpoint). No nonce: see the header. marionettePort is carried so a stealer
+ * can surface which Marionette port an orphaned session was bound to when it
+ * has to force-clear it.
+ */
+export interface SessionSlotRecord {
+  endpoint: string;
+  /** Owning MCP server process. The one field staleness turns on. */
+  pid: number;
+  /** Caller-supplied agent label, surfaced in busy/steal reporting. */
+  label: string;
+  createdAt: number;
+  /** Optional Marionette control port bound to this Firefox, when known. */
+  marionettePort?: number;
+}
+
+/**
+ * What a holder keeps so it can release ITS OWN record and never another
+ * process's. endpoint locates the file; (pid, createdAt) identify our record.
+ */
+export interface SessionSlotHandle {
+  endpoint: string;
+  pid: number;
+  createdAt: number;
+}
+
+export interface AcquireResult {
+  handle: SessionSlotHandle;
+  /**
+   * Set only when we STOLE a dead holder's slot. Its presence tells the caller
+   * that Firefox may still believe an orphaned BiDi session is active, so the
+   * caller must force-clear that session (e.g. via Marionette) before it calls
+   * session.new, or Firefox will still refuse with "Maximum number of active
+   * sessions". Absent on a clean first acquire.
+   */
+  staleHolder?: SessionSlotRecord;
+}
+
+export interface AcquireOptions {
+  label: string;
+  marionettePort?: number;
+  /** How long to keep polling a LIVE holder before giving up. Default sessionWaitMs(). */
+  waitMs?: number;
+  /** Injectable clock for the record's createdAt, so tests are deterministic. */
+  now?: number;
+  /** Poll interval while waiting on a live holder. Default DEFAULT_POLL_MS. */
+  pollMs?: number;
+}
+
+/** Env-overridable wait ceiling, in ms. */
+const DEFAULT_SESSION_WAIT_MS = 10_000;
+/** Poll cadence while a live holder is blocking us. */
+const DEFAULT_POLL_MS = 250;
+
+/** Same substitution rule as ../leases.ts safeId, applied to the endpoint URL. */
+function safeEndpoint(endpoint: string): string {
+  return endpoint.replace(/[^A-Za-z0-9._-]/g, "_");
+}
+
+/** One lock file per endpoint, a sibling of the tab lease files in ARTIFACT_DIR. */
+export function sessionSlotFile(endpoint: string): string {
+  return join(leaseDir(), `ff-session-${safeEndpoint(endpoint)}.json`);
+}
+
+/** Read per call (like leaseDir/leaseTtlMs), so a test can redirect it. A value
+ *  that is not a finite number > 0 falls back to the default. */
+export function sessionWaitMs(): number {
+  const raw = Number(process.env.CDP_FIREFOX_SESSION_WAIT_MS);
+  return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_SESSION_WAIT_MS;
+}
+
+/**
+ * Thrown when the slot is held by a LIVE process and did not free up within the
+ * wait window (or the attempt cap was hit). Names the live holder so the caller
+ * can decide to wait and retry or point this server at a different browser.
+ */
+export class SessionSlotBusyError extends Error {
+  readonly endpoint: string;
+  readonly holderPid?: number;
+  readonly holderLabel?: string;
+  constructor(endpoint: string, holder?: SessionSlotRecord) {
+    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;
+    }
+  }
+}
+
+/**
+ * Read the slot record, or undefined if the slot is genuinely free.
+ *
+ * Mirrors ../leases.ts readLease's fail-closed contract: ENOENT is "free" and
+ * returns undefined; any OTHER errno (EACCES, EIO, EISDIR, EMFILE...) is
+ * rethrown rather than reported as absent, because reporting "free" for a file
+ * that merely could not be read would admit a second process to a slot that is
+ * very much held. A record that reads but does not PARSE is treated as absent,
+ * deliberately: a corrupt record can never become readable, and failing closed
+ * on it would brick the endpoint with no in-product recovery, whereas an errno
+ * is transient.
+ */
+export async function readSessionSlot(endpoint: string): Promise<SessionSlotRecord | undefined> {
+  let raw: string;
+  try {
+    raw = await readFile(sessionSlotFile(endpoint), "utf8");
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return undefined; // genuinely free
+    throw err; // unreadable is not absent: fail closed
+  }
+  try {
+    const rec = JSON.parse(raw) as SessionSlotRecord;
+    if (typeof rec?.pid === "number" && typeof rec?.endpoint === "string" && typeof rec?.label === "string") {
+      return rec;
+    }
+  } catch {
+    /* unparseable: fall through to undefined, see the doc comment above */
+  }
+  return undefined;
+}
+
+/**
+ * Take the endpoint's session slot, coordinating with any other process.
+ *
+ * Returns { handle } on a clean acquire. Returns { handle, staleHolder } when
+ * the previous holder's process was dead and we stole its orphaned slot (the
+ * caller must then force-clear Firefox's orphaned session before session.new).
+ * Throws SessionSlotBusyError when a LIVE holder does not free the slot inside
+ * the wait window.
+ */
+export async function acquireSessionSlot(endpoint: string, opts: AcquireOptions): Promise<AcquireResult> {
+  const waitMs = opts.waitMs ?? sessionWaitMs();
+  const pollMs = opts.pollMs !== undefined && opts.pollMs > 0 ? opts.pollMs : DEFAULT_POLL_MS;
+  // opts.now stamps OUR record deterministically for tests; the wait deadline
+  // uses real time (with real sleeps) so a small waitMs actually times out.
+  const createdAt = opts.now ?? Date.now();
+  const file = sessionSlotFile(endpoint);
+
+  const record: SessionSlotRecord = {
+    endpoint,
+    pid: process.pid,
+    label: opts.label,
+    createdAt,
+  };
+  if (opts.marionettePort !== undefined) record.marionettePort = opts.marionettePort;
+  const handle: SessionSlotHandle = { endpoint, pid: process.pid, createdAt };
+  const payload = JSON.stringify(record);
+
+  await mkdir(leaseDir(), { recursive: true });
+
+  const deadline = Date.now() + waitMs;
+  // Bounds the immediate-retry paths (released-mid-race, steal-raced) so a
+  // pathological create/release partner can never spin us forever. The live
+  // holder is bounded by `deadline` instead; this cap is generous relative to
+  // it so it only bites on pathology, never on ordinary waiting.
+  const maxAttempts = Math.max(100, Math.ceil(waitMs / pollMs) + 100);
+
+  let attempts = 0;
+  let lastLiveHolder: SessionSlotRecord | undefined;
+
+  while (true) {
+    if (attempts >= maxAttempts) throw new SessionSlotBusyError(endpoint, lastLiveHolder);
+    attempts++;
+
+    // 1. Try to take the slot outright.
+    try {
+      await writeFile(file, payload, { flag: "wx" });
+      return { handle };
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== "EEXIST") throw err;
+    }
+
+    // 2. Occupied. Read the holder to classify it.
+    const holder = await readSessionSlot(endpoint);
+    if (!holder) continue; // released between our create and our read: retry immediately
+
+    if (!isPidAlive(holder.pid)) {
+      // 3. DEAD holder: orphan. Steal it — unlink, then re-create OUR record.
+      await unlink(file).catch(() => undefined);
+      try {
+        await writeFile(file, payload, { flag: "wx" });
+        return { handle, staleHolder: holder };
+      } catch (err) {
+        if ((err as NodeJS.ErrnoException).code !== "EEXIST") throw err;
+        continue; // steal raced another process: retry immediately
+      }
+    }
+
+    // 4. LIVE holder: legitimate contention. Poll until the deadline, then fail.
+    lastLiveHolder = holder;
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) throw new SessionSlotBusyError(endpoint, holder);
+    await sleep(Math.min(pollMs, remaining));
+  }
+}
+
+/**
+ * Release the slot, but ONLY if the record on disk is still the one we wrote.
+ *
+ * A record is ours iff its pid is this process AND its createdAt matches the
+ * handle. That guard is what stops us from unlinking a record another process
+ * created after stealing the slot from us (dead-pid steal), which would hand
+ * two processes the slot at once. Idempotent: a missing record is released:false.
+ */
+export async function releaseSessionSlot(handle: SessionSlotHandle): Promise<{ released: boolean }> {
+  const current = await readSessionSlot(handle.endpoint);
+  if (!current) return { released: false };
+  if (current.pid !== process.pid || current.createdAt !== handle.createdAt) return { released: false };
+  await unlink(sessionSlotFile(handle.endpoint)).catch(() => undefined); // swallow release races
+  return { released: true };
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/cli.ts

@@ -28,6 +28,7 @@ import { toolAvailability } from "./capabilities.ts";
 import { FIREFOX_TOOLS } from "./firefox-tools.ts";
 import { leaseFromArgs, withLeaseScope } from "./leases.ts";
 import { MANIFEST } from "./manifest.ts";
+import { runInstaller } from "./install/wizard.ts";
 
 const USAGE = `cdp-toolkit: raw single-target CDP, 29-tool chrome-devtools-mcp parity, plus a Firefox backend over WebDriver BiDi.
 
@@ -210,6 +211,15 @@ function printToolHelp(name: ToolName): void {
 
 async function main(): Promise<number> {
   const rawArgv = process.argv.slice(2);
+
+  // `install` is a CLI-ONLY subcommand (the `cdp install` wizard), not an MCP tool: it is not in
+  // TOOLS/MANIFEST and never appears in --list or tools/list. Dispatch it FIRST — before --browser
+  // resolution, --help, and tool dispatch — so `cdp install --help` reaches the installer's own
+  // help rather than the global USAGE, and so nothing below can reinterpret its flags.
+  if (rawArgv[0] === "install") {
+    return await runInstaller(rawArgv.slice(1));
+  }
+
   const { kind: browser, endpoint } = resolveBackend(rawArgv);
   const parsed = parseArgv(stripConnectFlag(stripBrowserFlag(rawArgv)));