cdp-toolkit 1.1.0 → 1.4.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "cdp-toolkit",
-  "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.",
+  "version": "1.4.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. 39 tools including built-in network mocking and a cookie group. No Puppeteer, no all-target fan-out.",
   "type": "module",
   "license": "MIT",
   "author": {
@@ -76,7 +76,8 @@
     "smoke": "bun run ./test/smoke.ts",
     "mock:smoke": "bun run ./test/mock-smoke.ts",
     "mcp:smoke": "bun run ./test/mcp-smoke.ts",
-    "firefox:smoke": "bun run ./test/firefox-smoke.ts"
+    "firefox:smoke": "bun run ./test/firefox-smoke.ts",
+    "lease:smoke": "bun run ./test/lease-smoke.ts"
   },
   "devDependencies": {
     "@types/node": "22.10.10",

package/src/bidi/driver.ts

@@ -25,11 +25,13 @@
 import type { TargetSelector } from "../types.ts";
 import {
   UID_STAMP_ATTR, isDriverError,
-  type BrowserDriver, type Capability, type HandledDialogInfo, type DriverError, type DriverErrorCode, type DriverEvent,
+  type BrowserCookie, type BrowserDriver, type Capability, type DeleteCookiesFilter, type HandledDialogInfo, type DriverError, type DriverErrorCode, type DriverEvent,
+  type SetCookieParams,
   type DriverUid, type ElementLocator, type EmulationOptions, type InterceptRule, type KeyPress, type LifetimeModel,
   type MouseButtonOptions, type NavigateOptions, type NavigateResult, type PageDriver, type PageInfo,
   type ScreenshotOptions, type SnapshotNode, type UidStability,
 } from "../driver.ts";
+import { assertLeaseOk } from "../leases.ts";
 import { BidiConnection, BidiError, connectBidiSession } from "./client.ts";
 import { takeStampedSnapshot } from "./snapshot.ts";
 import { selectRule, buildFulfillParams, effectiveAction } from "../tools/network_mock.ts";
@@ -37,8 +39,60 @@ import type {
   BrowsingContextId, BrowsingContextInfo, BrowsingContextLocator, BrowsingContextReadinessState,
   BrowsingContextCaptureScreenshotParameters, ScriptSharedReference, ScriptRemoteValue, ScriptLocalValue,
   ScriptNodeRemoteValue, ScriptExceptionDetails, InputSourceActions, InputPointerSourceAction, InputKeySourceAction,
+  NetworkCookie,
 } from "./protocol.ts";
 
+/* ---------------------------------- cookies ---------------------------------- */
+/**
+ * BiDi's cookie shape to the neutral one. Three differences to absorb:
+ *  - the value is a network.BytesValue, either a plain string or base64, so a
+ *    base64 one is decoded rather than handed back as opaque base64;
+ *  - `expiry` is optional and simply absent for a session cookie, which becomes
+ *    the neutral -1 that CDP reports directly;
+ *  - `session` has no BiDi field at all, so it is derived from that same
+ *    absence, which is exactly what a session cookie means.
+ * `sameSite` already uses the lowercase vocabulary the neutral shape adopted.
+ */
+export function normalizeBidiCookie(c: NetworkCookie): BrowserCookie {
+  const value = c.value.type === "base64" ? Buffer.from(c.value.value, "base64").toString("utf8") : c.value.value;
+  const hasExpiry = typeof c.expiry === "number";
+  return {
+    name: c.name, value, domain: c.domain, path: c.path,
+    expires: hasExpiry ? (c.expiry as number) : -1,
+    size: typeof c.size === "number" ? c.size : Buffer.byteLength(`${c.name}${value}`, "utf8"),
+    httpOnly: c.httpOnly === true, secure: c.secure === true,
+    sameSite: c.sameSite ?? "default", session: !hasExpiry,
+  };
+}
+
+/**
+ * The host of a url, for the BiDi cookie calls that require a `domain` and have
+ * no `url` parameter of their own.
+ *
+ * Exported so a test can pin the failure cases without a browser. Every branch
+ * that cannot produce a host THROWS: an absent url, an unparseable one, and a
+ * parseable one with an empty host (about:blank, data:, javascript:) all raise
+ * a message naming the tool and what it needs. The alternative, sending the
+ * call without a domain, is a request Firefox answers cleanly while writing or
+ * deleting nothing recognizable, which is the exact wrong-but-plausible ack
+ * this driver refuses to emit.
+ */
+export function hostFromUrl(url: string | undefined, toolName: string): string {
+  if (url === undefined || url === "") {
+    throw driverError("unsupported", `${toolName} on Firefox needs a 'domain': BiDi's storage cookie calls have no 'url' parameter, and no url was given to derive one from.`);
+  }
+  let host = "";
+  try {
+    host = new URL(url).hostname;
+  } catch {
+    throw driverError("unsupported", `${toolName} could not parse the url '${url}' to derive the 'domain' BiDi requires. Pass 'domain' explicitly.`);
+  }
+  if (host === "") {
+    throw driverError("unsupported", `${toolName} cannot derive a 'domain' from '${url}': that url has no host. Pass 'domain' explicitly.`);
+  }
+  return host;
+}
+
 /* ------------------------------ error + uid codec ------------------------------ */
 function driverError(code: DriverErrorCode, message: string, data?: unknown): DriverError {
   return Object.assign(new Error(message), { code, ...(data !== undefined ? { data } : {}) }) as DriverError;
@@ -256,10 +310,33 @@ async function pageInfoOf(conn: BidiConnection, ctx: BrowsingContextInfo): Promi
   return { id: ctx.context, url: ctx.url, title: await safeTitle(conn, ctx.context) };
 }
 /** Same TargetSelector grammar as client.ts's resolveTarget, but resolved entirely over BiDi
- *  (browsingContext.getTree): there is no HTTP discovery endpoint here, per client.ts's own footer. */
-async function resolveContext(conn: BidiConnection, selector: TargetSelector): Promise<BrowsingContextInfo> {
+ *  (browsingContext.getTree): there is no HTTP discovery endpoint here, per client.ts's own footer.
+ *
+ *  THE Firefox choke point for tab leases. Keyed "firefox", never a bare id: a CDP targetId and a
+ *  BiDi context id are not disjoint by construction, so one bare key space could produce a false
+ *  collision between an unrelated Chrome tab and a Firefox context. Note this backend needs the
+ *  lease far less than Chrome does (backend.ts: every MCP server process launches its OWN Firefox,
+ *  so two sessions cannot race over one instance the way they do over Chrome on port 9222). It is
+ *  here for consistency and for a future shared-instance setup, not to close an observed gap. */
+async function resolveContext(
+  conn: BidiConnection,
+  selector: TargetSelector,
+  opts: { lease?: string } = {},
+): Promise<BrowsingContextInfo> {
   const { contexts } = await conn.send("browsingContext.getTree", {}).catch((e) => { throw mapBidiError(e); });
   if (!contexts.length) throw driverError("no-such-target", "no browsing contexts available");
+  const hit = await pickContext(conn, contexts, selector);
+  // liveIds deliberately not passed: hit is by construction a member of contexts, so target-gone
+  // could never fire for the context just resolved (see leases.ts's assertLeaseOk callers).
+  await assertLeaseOk("firefox", hit.context, { lease: opts.lease, url: hit.url });
+  return hit;
+}
+
+async function pickContext(
+  conn: BidiConnection,
+  contexts: BrowsingContextInfo[],
+  selector: TargetSelector,
+): Promise<BrowsingContextInfo> {
   if (selector === undefined || selector === "active") return contexts[0]!;
   if (selector.startsWith("index:")) {
     const t = contexts[Number(selector.slice(6))];
@@ -619,6 +696,88 @@ class BidiPageDriver implements PageDriver {
     return this.handleOneDialog(accept, promptText, opts?.timeoutMs ?? 15_000);
   }
 
+  /**
+   * storage.getCookies, partitioned by THIS browsing context.
+   *
+   * The context partition is the BiDi counterpart of the CDP driver's choice of
+   * the page-scoped Network.getCookies over the browser-wide jar: it asks for
+   * the cookies of the tab that was resolved, not for every cookie the profile
+   * holds. httpOnly cookies are included, since this reads the cookie store
+   * over the protocol rather than evaluating document.cookie in the page.
+   */
+  async getCookies(): Promise<BrowserCookie[]> {
+    try {
+      const { cookies } = await this.conn.send("storage.getCookies", { partition: { type: "context", context: this.contextId } });
+      return (cookies ?? []).map(normalizeBidiCookie);
+    } catch (e) {
+      throw mapBidiError(e);
+    }
+  }
+
+  /**
+   * storage.setCookie, partitioned by THIS browsing context.
+   *
+   * One real difference from CDP to absorb, and it is absorbed EXPLICITLY
+   * rather than papered over: BiDi has no `url` parameter and requires
+   * `domain`, while CDP accepts either and derives the rest from the url. So a
+   * caller who supplied only a url gets its host used as the domain, and a url
+   * with no host (about:blank, a data: URL, a malformed string) throws instead
+   * of being dropped, because a set that silently did nothing is the failure
+   * this tool must never produce.
+   *
+   * Note the derivation is narrower than CDP's: CDP also takes `path` and
+   * `secure` from the url, and this does not, so those stay exactly as the
+   * caller gave them on both backends.
+   */
+  async setCookie(params: SetCookieParams): Promise<void> {
+    const domain = params.domain ?? hostFromUrl(params.url, "set_cookie");
+    try {
+      await this.conn.send("storage.setCookie", {
+        cookie: {
+          name: params.name,
+          value: { type: "string", value: params.value },
+          domain,
+          ...(params.path !== undefined ? { path: params.path } : {}),
+          ...(params.expires !== undefined ? { expiry: params.expires } : {}),
+          ...(params.httpOnly !== undefined ? { httpOnly: params.httpOnly } : {}),
+          ...(params.secure !== undefined ? { secure: params.secure } : {}),
+          ...(params.sameSite !== undefined ? { sameSite: params.sameSite } : {}),
+        },
+        partition: { type: "context", context: this.contextId },
+      });
+    } catch (e) {
+      throw mapBidiError(e);
+    }
+  }
+
+  /**
+   * storage.deleteCookies with a filter, partitioned by THIS browsing context.
+   *
+   * Same url-to-domain derivation as setCookie and for the same reason: the
+   * BiDi filter has `domain` and no `url`, and a filter that quietly dropped
+   * the only site constraint would delete by name across the partition, which
+   * is a bigger deletion than the caller asked for.
+   *
+   * BiDi reports a partitionKey and no count, exactly as CDP reports nothing,
+   * so this returns nothing on both backends rather than one of them inventing
+   * a number the other cannot produce.
+   */
+  async deleteCookies(filter: DeleteCookiesFilter): Promise<void> {
+    const domain = filter.domain ?? hostFromUrl(filter.url, "delete_cookies");
+    try {
+      await this.conn.send("storage.deleteCookies", {
+        filter: {
+          name: filter.name,
+          domain,
+          ...(filter.path !== undefined ? { path: filter.path } : {}),
+        },
+        partition: { type: "context", context: this.contextId },
+      });
+    } catch (e) {
+      throw mapBidiError(e);
+    }
+  }
+
   // Response bodies need network.addDataCollector armed BEFORE the request, per the established
   // fact this driver was handed: no way to read a body for a request that happened before
   // capture was armed. That is the mirror of the CDP driver's own honest omission of
@@ -771,7 +930,11 @@ class BidiBrowserDriver implements BrowserDriver {
 export function createFirefoxDriver(port: number, opts?: { timeoutMs?: number }): BrowserDriver {
   return new BidiBrowserDriver(port, opts?.timeoutMs);
 }
-export { BidiBrowserDriver, BidiPageDriver };
+// resolveContext is exported for ONE reason: it is the Firefox lease choke
+// point, and a choke point nothing can call directly is a choke point nothing
+// can test. Its gate was deletable with a green suite until test/leases.test.ts
+// could drive it against a stub connection. Not part of the public surface.
+export { BidiBrowserDriver, BidiPageDriver, resolveContext };
 
 /* ------------------------------------------------------------------------------
  * BiDi modules/commands used: session (new, subscribe/unsubscribe, via client.ts); browsingContext

package/src/capabilities.ts

@@ -1,5 +1,5 @@
 /**
- * Per-backend tool availability: filters the 33-tool registry down to what a
+ * Per-backend tool availability: filters the 36-tool registry down to what a
  * given DriverKind can actually run, per ADR-001's rule that tools/list
  * discovers gaps, not runtime "unsupported" throws. Pure and I/O-free: driver
  * construction reads a static readonly `capabilities` set, it does not dial a

package/src/cdp/driver.ts

@@ -7,10 +7,12 @@
  */
 import { type CdpConnection, CdpError, listTargets, openBrowser, openPage, resolveTarget } from "../client.ts";
 import type { Target, TargetSelector } from "../types.ts";
+import { LeaseConflictError } from "../leases.ts";
 import { resolveUid } from "../tools/snapshot.ts";
 import { buildFulfillParams, effectiveAction, selectRule } from "../tools/network_mock.ts";
 import {
-  LEGACY_NUMERIC_UID, type BrowserDriver, type Capability, type HandledDialogInfo, type DriverError, type DriverErrorCode, type DriverEvent,
+  LEGACY_NUMERIC_UID, type BrowserCookie, type BrowserDriver, type Capability, type DeleteCookiesFilter, type HandledDialogInfo, type DriverError, type DriverErrorCode, type DriverEvent,
+  type SetCookieParams,
   type DriverUid, type ElementLocator, type EmulationOptions, type InterceptRule, type KeyPress, type LifetimeModel, type MouseButtonOptions,
   type NavigateOptions, type NavigateResult, type PageDriver, type PageInfo, type ScreenshotOptions, type SnapshotNode, type UidStability,
 } from "../driver.ts";
@@ -29,6 +31,49 @@ function decodeUid(uid: DriverUid): number {
   if (!Number.isSafeInteger(n) || n <= 0) throw driverError("foreign-uid", `malformed cdp uid payload: ${uid}`);
   return n;
 }
+/* ---------------------------------- cookies ---------------------------------- */
+/** The subset of CDP's `Network.Cookie` this driver reads. */
+export interface CdpCookie {
+  name: string; value: string; domain: string; path: string; expires: number; size: number;
+  httpOnly: boolean; secure: boolean; session: boolean; sameSite?: string;
+}
+
+/**
+ * CDP's cookie shape to the neutral one. Two mappings carry the difference:
+ * `sameSite` is capitalized by CDP and absent when the cookie never set the
+ * attribute, so it lowercases and falls back to "default" (BiDi's word for the
+ * same state); `expires` is already CDP's Unix seconds with -1 for a session
+ * cookie, so it passes through, with `session` kept as the browser's own flag
+ * rather than re-derived from the timestamp.
+ */
+export function normalizeCdpCookie(c: CdpCookie): BrowserCookie {
+  const same = (c.sameSite ?? "").toLowerCase();
+  const sameSite: BrowserCookie["sameSite"] =
+    same === "strict" || same === "lax" || same === "none" ? same : "default";
+  return {
+    name: c.name, value: c.value, domain: c.domain, path: c.path,
+    expires: typeof c.expires === "number" ? c.expires : -1,
+    size: typeof c.size === "number" ? c.size : Buffer.byteLength(`${c.name}${c.value}`, "utf8"),
+    httpOnly: c.httpOnly === true, secure: c.secure === true, sameSite, session: c.session === true,
+  };
+}
+
+/**
+ * The neutral lowercase `sameSite` back to CDP's own vocabulary.
+ *
+ * The inverse of normalizeCdpCookie's mapping, and it has to be the inverse:
+ * CDP capitalizes the three real values and has NO word for "default", which
+ * is BiDi's name for a cookie that never set the attribute. So "default"
+ * returns undefined and the caller omits the field, which is exactly the state
+ * it describes.
+ */
+export function cdpSameSite(sameSite?: "strict" | "lax" | "none" | "default"): "Strict" | "Lax" | "None" | undefined {
+  if (sameSite === "strict") return "Strict";
+  if (sameSite === "lax") return "Lax";
+  if (sameSite === "none") return "None";
+  return undefined;
+}
+
 /* ---------------------- copied helpers, see attributions below ---------------------- */
 // Copied verbatim from src/tools/input.ts `centerOf`: scroll into view, read viewport-space center.
 async function centerOf(conn: CdpConnection, objectId: string): Promise<{ x: number; y: number }> {
@@ -535,6 +580,79 @@ class CdpPageDriver implements PageDriver {
       });
     });
   }
+  /**
+   * `Network.getCookies` over `Storage.getCookies`, deliberately.
+   *
+   * The two differ in SCOPE, not in detail: `Storage.getCookies` returns the
+   * whole browser jar (every cookie for every site the profile has), while
+   * `Network.getCookies`, called with no `urls`, returns the cookies of the
+   * page this connection is attached to and its subframes. This driver is
+   * always attached to one resolved target, so the page-scoped call is the one
+   * that answers the question the caller asked. It also keeps unrelated sites'
+   * session credentials out of a result that only named one tab.
+   *
+   * The Network domain is enabled with the same lazy ensureDomain the rest of
+   * the class uses. httpOnly cookies come back either way: this is a protocol
+   * read of the cookie store, not a `document.cookie` evaluation, which is the
+   * entire reason a tool is better here than a script.
+   */
+  async getCookies(): Promise<BrowserCookie[]> {
+    await this.ensureDomain("Network");
+    const { cookies } = await this.conn.send<{ cookies: CdpCookie[] }>("Network.getCookies");
+    return (cookies ?? []).map(normalizeCdpCookie);
+  }
+  /**
+   * `Network.setCookie`, which answers `{success: boolean}` rather than an
+   * error when it declines a cookie.
+   *
+   * That return is the whole reason this method is more than one line. Chrome
+   * refuses a cookie for plenty of ordinary reasons (a domain the url does not
+   * belong to, `secure` on an insecure origin, an oversized value) and reports
+   * the refusal as `success:false` with a perfectly successful protocol reply.
+   * Resolving on that would hand the caller a "cookie set" that is not set, so
+   * a false is turned into a thrown error naming the cookie.
+   *
+   * `path` is passed through as given, not defaulted: with a `url` CDP derives
+   * the path from it, and inventing "/" here would silently widen the scope of
+   * a cookie the caller asked to scope narrowly.
+   */
+  async setCookie(params: SetCookieParams): Promise<void> {
+    await this.ensureDomain("Network");
+    const sameSite = cdpSameSite(params.sameSite);
+    const { success } = await this.conn.send<{ success: boolean }>("Network.setCookie", {
+      name: params.name,
+      value: params.value,
+      ...(params.url !== undefined ? { url: params.url } : {}),
+      ...(params.domain !== undefined ? { domain: params.domain } : {}),
+      ...(params.path !== undefined ? { path: params.path } : {}),
+      ...(params.expires !== undefined ? { expires: params.expires } : {}),
+      ...(params.httpOnly !== undefined ? { httpOnly: params.httpOnly } : {}),
+      ...(params.secure !== undefined ? { secure: params.secure } : {}),
+      ...(sameSite !== undefined ? { sameSite } : {}),
+    });
+    if (success !== true) {
+      // "page-error" is this file's code for a browser-side refusal of an
+      // operation that reached the browser intact, which is precisely this.
+      throw driverError(
+        "page-error",
+        `Network.setCookie declined the cookie '${params.name}'. Chrome rejects a cookie whose domain does not match the url, a secure cookie on an insecure origin, and an oversized name or value.`,
+      );
+    }
+  }
+  /**
+   * `Network.deleteCookies`. Unlike setCookie it reports nothing at all, not
+   * even a count, so this resolves on the protocol acknowledgement and the tool
+   * above it returns a boolean ack instead of a fabricated number.
+   */
+  async deleteCookies(filter: DeleteCookiesFilter): Promise<void> {
+    await this.ensureDomain("Network");
+    await this.conn.send("Network.deleteCookies", {
+      name: filter.name,
+      ...(filter.url !== undefined ? { url: filter.url } : {}),
+      ...(filter.domain !== undefined ? { domain: filter.domain } : {}),
+      ...(filter.path !== undefined ? { path: filter.path } : {}),
+    });
+  }
   async startBodyCapture(): Promise<() => Promise<void>> {
     await this.ensureDomain("Network");
     return async () => {
@@ -587,7 +705,33 @@ async function withBrowserConn<T>(fn: (conn: CdpConnection) => Promise<T>): Prom
     conn.close();
   }
 }
+/**
+ * Relabel a target-resolution failure as `no-such-target`, but ONLY when the
+ * failure carries no type of its own.
+ *
+ * This used to relabel everything, and that was wrong in a way no unit test
+ * caught, because the message text survived and the MCP surface reads message
+ * text. resolveTarget is where the Chrome lease gate lives, so a
+ * LeaseConflictError raised by assertLeaseOk came through here and lost its
+ * class, its targetId and its holder, and came out coded `no-such-target`,
+ * which tells a caller the selector matched nothing and it should stop. A lease
+ * conflict is the one case where retrying, or going to fetch the token, is the
+ * right move. readLease's deliberate rethrow on an UNREADABLE lease file was
+ * mislabeled the same way, which is precisely the confusion that throw exists
+ * to prevent. BiDi never had a blanket catch, so the two backends disagreed.
+ *
+ * The pass-through is by TYPE, not by an enumerated list of errors, so a typed
+ * error added anywhere below this frame is protected without anyone having to
+ * remember to come back here:
+ *   - LeaseConflictError, named because it is the one the caller acts on;
+ *   - anything carrying a STRING `code`, which covers every DriverError and
+ *     every fs errno (an EACCES out of readLease reaches this frame).
+ * CdpError's `code` is a NUMBER (a CDP protocol error code), so a genuine
+ * "that target does not exist" from pickTarget still relabels, as it must.
+ */
 function noSuchTarget(e: unknown): never {
+  if (e instanceof LeaseConflictError) throw e;
+  if (typeof (e as { code?: unknown } | null | undefined)?.code === "string") throw e;
   throw driverError("no-such-target", e instanceof CdpError ? e.message : String(e));
 }
 class CdpBrowserDriver implements BrowserDriver {

package/src/cli.ts

@@ -26,6 +26,7 @@ import { TOOLS, TOOL_NAMES, type ToolName } from "./index.ts";
 import { resolveBrowserKind, stripBrowserFlag, startFirefoxSession } from "./backend.ts";
 import { toolAvailability } from "./capabilities.ts";
 import { FIREFOX_TOOLS } from "./firefox-tools.ts";
+import { leaseFromArgs, withLeaseScope } from "./leases.ts";
 
 const USAGE = `cdp-toolkit: raw single-target CDP, 29-tool chrome-devtools-mcp parity, plus a Firefox backend over WebDriver BiDi.
 
@@ -48,6 +49,8 @@ zero behavior change for existing users). Firefox is LAUNCHED per invocation (it
 to), used for exactly one tool call, then disposed before the process exits.
 
 Target selector grammar: active | index:N | url:<substr> | title:<substr> | <targetId>
+Leases: pass --lease <token> to act on a tab another agent claimed with claim_page (MCP only).
+Run list_leases to see who holds what; release_page --lease <token> gives a lease back.
 Run with --list to print every tool name available under the selected backend.
 Run with --capabilities to see, per tool, whether it is available and (if not) which capability
 the selected backend is missing.`;
@@ -168,30 +171,52 @@ async function main(): Promise<number> {
     return 1;
   }
 
-  if (browser === "chrome") {
-    const fn = TOOLS[parsed.tool];
-    // The registry's value type is the union of all tool signatures; each tool
-    // validates its own args at runtime, so we hand the parsed object through.
-    const result = await (fn as (args: unknown) => Promise<unknown>)(parsed.args);
-    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
-    return 0;
-  }
-
-  // Firefox: one process per invocation. Launch, run exactly one tool call, always dispose,
-  // even if the tool call itself throws, so the spawned Firefox process never leaks.
-  const neutralFn = FIREFOX_TOOLS[parsed.tool];
-  if (!neutralFn) {
-    process.stderr.write(`${JSON.stringify({ error: `tool '${parsed.tool}' has no Firefox implementation wired` })}\n`);
+  // Decision: the CLI cannot claim a lease. Per backend.ts, a CLI invocation is
+  // one process per call, so the claiming process is already dead by the next
+  // call and the dead-pid rule would make the lease reclaimable at once,
+  // regardless of ttlMs. A lease that is reclaimable on arrival is worse than
+  // no lease, because it reads as protection that is not there. Every OTHER
+  // CLI call still goes through assertLeaseOk and may present --lease.
+  if (parsed.tool === "claim_page") {
+    process.stderr.write(
+      `${JSON.stringify({
+        error:
+          "claim_page is not available from the CLI: a CLI invocation is one process per call, so the lease it claimed would be reclaimable immediately by the dead-pid rule. Claim from the cdp-toolkit MCP server, which is long lived, then pass the token to CLI calls with --lease <token>.",
+      })}\n`,
+    );
     return 1;
   }
-  const session = await startFirefoxSession();
-  try {
-    const result = await neutralFn(session.driver, parsed.args as never);
-    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
-    return 0;
-  } finally {
-    await session.dispose();
-  }
+
+  // ONE lease scope per invocation, wrapping BOTH backend branches, exactly as
+  // mcp.ts does. `--lease <token>` lands in parsed.args like any other flag, so
+  // no tool signature changes and a tool added later is covered for free.
+  const tool = parsed.tool;
+  return withLeaseScope(leaseFromArgs(parsed.args), async () => {
+    if (browser === "chrome") {
+      const fn = TOOLS[tool];
+      // The registry's value type is the union of all tool signatures; each tool
+      // validates its own args at runtime, so we hand the parsed object through.
+      const result = await (fn as (args: unknown) => Promise<unknown>)(parsed.args);
+      process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+      return 0;
+    }
+
+    // Firefox: one process per invocation. Launch, run exactly one tool call, always dispose,
+    // even if the tool call itself throws, so the spawned Firefox process never leaks.
+    const neutralFn = FIREFOX_TOOLS[tool];
+    if (!neutralFn) {
+      process.stderr.write(`${JSON.stringify({ error: `tool '${tool}' has no Firefox implementation wired` })}\n`);
+      return 1;
+    }
+    const session = await startFirefoxSession();
+    try {
+      const result = await neutralFn(session.driver, parsed.args as never);
+      process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+      return 0;
+    } finally {
+      await session.dispose();
+    }
+  });
 }
 
 main()

package/src/client.ts

@@ -1,9 +1,10 @@
 /**
- * Core raw-CDP client. Zero runtime dependencies — uses Node's global
+ * Core raw-CDP client. Zero runtime dependencies: uses Node's global
  * WebSocket (Node >= 22; verified on Node 25.9). Every tool module is built on
  * the primitives exported here. See CONTRACT.md.
  */
 import type { CdpResponse, Target, TargetSelector } from "./types.ts";
+import { assertLeaseOk } from "./leases.ts";
 
 /** Base HTTP origin of the DevTools endpoint. Override with CDP_BASE. */
 export const BASE = process.env.CDP_BASE ?? "http://127.0.0.1:9222";
@@ -185,15 +186,32 @@ export function listTargets(): Promise<Target[]> {
   return httpJson<Target[]>("/json/list");
 }
 
-/** Browser-level WebSocket URL (GET /json/version) — for Target.* / Browser.*. */
+/** Browser-level WebSocket URL (GET /json/version), for Target.* / Browser.*. */
 export async function browserWsUrl(): Promise<string> {
   const v = await httpJson<{ webSocketDebuggerUrl: string }>("/json/version");
   return v.webSocketDebuggerUrl;
 }
 
-/** Resolve a TargetSelector to a concrete page target. See types.ts for grammar. */
-export async function resolveTarget(selector: TargetSelector): Promise<Target> {
+/** Resolve a TargetSelector to a concrete page target. See types.ts for grammar.
+ *  opts.lease is for library callers; the MCP/CLI path supplies the token through
+ *  the ambient lease scope instead (see leases.ts). */
+export async function resolveTarget(selector: TargetSelector, opts: { lease?: string } = {}): Promise<Target> {
   const targets = await listTargets();
+  const hit = pickTarget(targets, selector);
+  // THE Chrome choke point. Every tool reaches a page through here, so a tool
+  // added after this shipped is protected with no action from its author.
+  //
+  // Deliberately NOT passing liveIds. It would be inert here: pickTarget
+  // returns an element of `targets`, so hit.id is always a member of that list
+  // and the "target-gone" staleness condition could never fire for the very
+  // target we just resolved. Passing it would only suggest a check is happening
+  // that is not. target-gone earns its keep on claim, and on a list_leases
+  // reap, where a record's id may genuinely be absent from the browser.
+  await assertLeaseOk("chrome", hit.id, { lease: opts.lease, url: hit.url, title: hit.title });
+  return hit;
+}
+
+function pickTarget(targets: Target[], selector: TargetSelector): Target {
   const pages = targets.filter((t) => t.type === "page");
   if (!selector || selector === "active") {
     if (!pages.length) throw new CdpError("no page targets open");
@@ -230,9 +248,9 @@ export async function openBrowser(opts: { timeoutMs?: number } = {}): Promise<Cd
 /** Open a connection to a page target. Returns the connection and the target. */
 export async function openPage(
   selector: TargetSelector,
-  opts: { timeoutMs?: number } = {},
+  opts: { timeoutMs?: number; lease?: string } = {},
 ): Promise<{ conn: CdpConnection; target: Target }> {
-  const target = await resolveTarget(selector);
+  const target = await resolveTarget(selector, { lease: opts.lease });
   const conn = await new CdpConnection(target.webSocketDebuggerUrl, opts).connect();
   return { conn, target };
 }
@@ -244,7 +262,7 @@ export async function openPage(
 export async function withPage<T>(
   selector: TargetSelector,
   fn: (conn: CdpConnection, target: Target) => Promise<T>,
-  opts: { timeoutMs?: number } = {},
+  opts: { timeoutMs?: number; lease?: string } = {},
 ): Promise<T> {
   const { conn, target } = await openPage(selector, opts);
   try {