cdp-toolkit 1.1.0 → 1.2.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.2.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. 36 tools including built-in network mocking. No Puppeteer, no all-target fan-out.",
   "type": "module",
   "license": "MIT",
   "author": {

package/src/bidi/driver.ts

@@ -30,6 +30,7 @@ import {
   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";
@@ -256,10 +257,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))];
@@ -771,7 +795,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/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 {

package/src/driver.ts

@@ -1,5 +1,5 @@
 /**
- * ADR-001: one browser-neutral Driver interface behind the 33 tools.
+ * ADR-001: one browser-neutral Driver interface behind the 36 tools.
  *
  * Context. Every tool in src/tools/ is a stateless one-shot on withPage():
  * open a socket, act, always close. That is only correct because a CDP `Uid`

package/src/firefox-tools.ts

@@ -1,14 +1,17 @@
 /**
- * The complete Firefox tool registry: the 20 tools shared with Chrome (src/shared-tools.ts) plus
- * the 7 Firefox-only console/network/mock tools (src/bidi-tools.ts). This is what src/neutral.ts
- * used to be; it now composes two files instead of reimplementing everything in one.
+ * The complete Firefox tool registry: the 20 tools shared with Chrome (src/shared-tools.ts), the
+ * 7 Firefox-only console/network/mock tools (src/bidi-tools.ts), and the 3 lease tools
+ * (src/leases-tools.ts), which are backend-neutral by construction. This is what src/neutral.ts
+ * used to be; it now composes three files instead of reimplementing everything in one.
  */
 import type { BrowserDriver } from "./driver.ts";
 import type { ToolName } from "./index.ts";
 import { SHARED_TOOLS } from "./shared-tools.ts";
 import { BIDI_ONLY_TOOLS } from "./bidi-tools.ts";
+import { LEASE_TOOLS } from "./leases-tools.ts";
 
 export const FIREFOX_TOOLS: Partial<Record<ToolName, (driver: BrowserDriver, args: never) => Promise<unknown>>> = {
   ...SHARED_TOOLS,
   ...BIDI_ONLY_TOOLS,
+  ...LEASE_TOOLS,
 };

package/src/index.ts

@@ -19,6 +19,7 @@
 // the byte-identical-Chrome-behavior contract this bind honors, and for the 7 tools that stay
 // two implementations (console/network/mock, immediately below, unchanged from before).
 import { createCdpDriver } from "./cdp/driver.ts";
+import { LEASE_TOOLS } from "./leases-tools.ts";
 import { SHARED_TOOLS } from "./shared-tools.ts";
 // --- console + network (read the recorder buffer) ---
 import { listConsoleMessages, getConsoleMessage } from "./tools/console.ts";
@@ -56,7 +57,7 @@ function onCdp<A>(fn: (driver: ReturnType<typeof createCdpDriver>, args: A) => P
  * (`performance_trace`, a robust single-call trace : the start/stop pair cannot
  * span two stateless CLI processes), plus a 3-tool network-mocking group
  * (mock_request/list_mocks/clear_mocks : a persistent per-target fake backend).
- * 33 entries total. Listed explicitly so the mapping is auditable at a glance and
+ * 36 entries total. Listed explicitly so the mapping is auditable at a glance and
  * the CLI can `--list` it.
  *
  * 20 of the 29 MCP-parity tools (pages/navigation/evaluate/snapshot/interaction/
@@ -110,6 +111,10 @@ export const TOOLS = {
   mock_request: mockRequest,
   list_mocks: listMocks,
   clear_mocks: clearMocks,
+  // tab leases (3) : opt-in ownership so many agents can share one browser
+  claim_page: onCdp(LEASE_TOOLS.claim_page),
+  release_page: onCdp(LEASE_TOOLS.release_page),
+  list_leases: onCdp(LEASE_TOOLS.list_leases),
 } satisfies Record<string, (args: never) => Promise<unknown>>;
 
 /** Canonical MCP tool name accepted by the registry. */

package/src/leases-tools.ts

@@ -0,0 +1,101 @@
+/**
+ * The three lease tools, shaped like src/shared-tools.ts entries
+ * ((driver, args) => Promise<result>) so ONE implementation serves Chrome and
+ * Firefox, exactly as the other 20 unified tools do.
+ */
+import type { BrowserDriver } from "./driver.ts";
+import {
+  claimLease,
+  leaseTtlMs,
+  listLeases,
+  releaseLease,
+  type LeaseBackend,
+  type LeaseSummary,
+  type LeaseToken,
+} from "./leases.ts";
+
+class LeaseToolError extends Error {}
+
+/** The driver's uid scheme is the one stable per-backend discriminator on the
+ *  BrowserDriver surface ("cdp" for Chrome, "bidi" for Firefox). */
+function backendOf(driver: BrowserDriver): LeaseBackend {
+  return driver.scheme === "bidi" ? "firefox" : "chrome";
+}
+
+export interface ClaimPageResult {
+  lease: LeaseToken;
+  targetId: string;
+  url: string;
+  label: string;
+  ttlMs: number;
+  expiresAt: number;
+}
+
+/**
+ * Claim a tab. With no targetId, opens a fresh tab first (optionally at `url`)
+ * and claims that, so "give me my own tab" is one call. With a targetId, claims
+ * an already-open tab.
+ */
+export async function claimPage(
+  driver: BrowserDriver,
+  args: { targetId?: string; url?: string; label?: string; ttlMs?: number } = {},
+): Promise<ClaimPageResult> {
+  const backend = backendOf(driver);
+  const label = typeof args.label === "string" && args.label.length ? args.label : `pid-${process.pid}`;
+  const pages = await driver.listPages();
+  let targetId = args.targetId;
+  let url = args.url ?? "about:blank";
+  if (targetId === undefined || targetId === "") {
+    const page = await driver.newPage(args.url);
+    targetId = page.id;
+    url = page.url;
+  } else {
+    const existing = pages.find((p) => p.id === targetId);
+    if (!existing) throw new LeaseToolError(`claim_page: no page target with id '${targetId}'`);
+    url = existing.url;
+  }
+  const liveIds = [...pages.map((p) => p.id), targetId];
+  const { record, token } = await claimLease(backend, targetId, {
+    label,
+    ttlMs: typeof args.ttlMs === "number" && args.ttlMs > 0 ? args.ttlMs : leaseTtlMs(),
+    liveIds,
+  });
+  return {
+    lease: token,
+    targetId,
+    url,
+    label: record.label,
+    ttlMs: record.ttlMs,
+    expiresAt: record.lastUsedAt + record.ttlMs,
+  };
+}
+
+/** Release a held lease. Idempotent: an already-released or reclaimed lease
+ *  reports released:false rather than throwing. */
+export async function releasePage(
+  _driver: BrowserDriver,
+  args: { lease?: LeaseToken },
+): Promise<{ released: boolean }> {
+  if (typeof args.lease !== "string" || !args.lease.length) {
+    throw new LeaseToolError("release_page requires the 'lease' token returned by claim_page");
+  }
+  return releaseLease(args.lease);
+}
+
+/** Enumerate active leases for diagnosis. Requires no token by design. */
+export async function listLeasesTool(
+  driver: BrowserDriver,
+  _args: Record<string, never> = {} as Record<string, never>,
+): Promise<{ leases: LeaseSummary[]; count: number }> {
+  const liveIds = (await driver.listPages()).map((p) => p.id);
+  // liveBackend scopes the target-gone test to the browser these ids came from,
+  // so leases held on the OTHER backend are not mislabeled as reclaimable.
+  const leases = await listLeases({ liveIds, liveBackend: backendOf(driver) });
+  return { leases, count: leases.length };
+}
+
+export const LEASE_TOOLS = {
+  claim_page: claimPage,
+  release_page: releasePage,
+  list_leases: listLeasesTool,
+} satisfies Record<string, (driver: BrowserDriver, args: never) => Promise<unknown>>;