cdp-toolkit 1.0.0 → 1.2.0

package/src/index.ts

@@ -2,7 +2,7 @@
  * cdp-toolkit public surface.
  *
  * Two exports:
- *   1. `TOOLS` — the registry mapping every chrome-devtools-mcp tool name
+ *   1. `TOOLS` : the registry mapping every chrome-devtools-mcp tool name
  *      (snake_case string, all 29) to its raw-CDP implementation function. The
  *      CLI and any embedder dispatch through this single table.
  *   2. The client primitives, re-exported so consumers can build their own
@@ -12,21 +12,15 @@
  * value (or throws). See CONTRACT.md for the design rules each module follows.
  */
 
-// --- pages (browser endpoint: Target.*) ---
-import { listPages, newPage, closePage, selectPage } from "./tools/pages.ts";
-// --- navigation ---
-import { navigatePage, waitForText } from "./tools/navigation.ts";
-// --- evaluate ---
-import { evaluateScript } from "./tools/evaluate.ts";
-// --- snapshot (a11y tree + shared resolveUid helper) ---
-import { takeSnapshot } from "./tools/snapshot.ts";
-// --- input / interaction ---
-import { click, hover, drag, fill, fillForm, typeText, pressKey, uploadFile } from "./tools/input.ts";
-// --- screenshot + emulation ---
-import { takeScreenshot } from "./tools/screenshot.ts";
-import { emulate, resizePage } from "./tools/emulation.ts";
-// --- dialogs ---
-import { handleDialog } from "./tools/dialogs.ts";
+// --- the 20 tools unified with Firefox onto one Driver-based implementation ---
+// (list_pages/new_page/close_page/select_page, navigate_page/wait_for, evaluate_script,
+// take_snapshot, click/hover/drag/fill/fill_form/type_text/press_key/upload_file,
+// take_screenshot/emulate/resize_page, handle_dialog). See shared-tools.ts's file header for
+// 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";
 import { listNetworkRequests, getNetworkRequest } from "./tools/network.ts";
@@ -41,49 +35,64 @@ import {
 import { takeHeapsnapshot } from "./tools/heap.ts";
 // --- lighthouse (the sole non-CDP tool) ---
 import { lighthouseAudit } from "./tools/lighthouse.ts";
-// --- network mocking (Fetch domain) — toolkit addition beyond the 29 parity tools ---
+// --- network mocking (Fetch domain) : toolkit addition beyond the 29 parity tools ---
 import { mockRequest, listMocks, clearMocks } from "./tools/network_mock.ts";
 
 /** A toolkit tool: a single typed-args function returning JSON-serializable data. */
 export type ToolFn = (args: never) => Promise<unknown>;
 
+// One stateless CDP driver, reused across calls (lifetime "per-call": every page() acquisition
+// still opens its own throwaway connection, same as the pre-migration withPage per-call model).
+// Constructing it does not dial a browser (capabilities.ts already relies on this).
+const cdpDriver = createCdpDriver();
+
+/** Bind a shared-tools.ts function to the module-level CDP driver, args-typed for the registry. */
+function onCdp<A>(fn: (driver: ReturnType<typeof createCdpDriver>, args: A) => Promise<unknown>): (args: A) => Promise<unknown> {
+  return (args: A) => fn(cdpDriver, args);
+}
+
 /**
  * The complete chrome-devtools-mcp parity surface: all 29 MCP tools keyed by
  * their canonical MCP (snake_case) name, plus one convenience superset tool
- * (`performance_trace`, a robust single-call trace — the start/stop pair cannot
+ * (`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
+ * (mock_request/list_mocks/clear_mocks : a persistent per-target fake backend).
+ * 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/
+ * screenshot+emulation/dialogs) now route through shared-tools.ts's single Driver-based
+ * implementation via the CDP driver, instead of a Chrome-only copy in src/tools/*.ts.
+ * See shared-tools.ts's file header for the shape/behavior contract this preserves.
  */
 export const TOOLS = {
   // pages (4)
-  list_pages: listPages,
-  new_page: newPage,
-  close_page: closePage,
-  select_page: selectPage,
+  list_pages: onCdp(SHARED_TOOLS.list_pages),
+  new_page: onCdp(SHARED_TOOLS.new_page),
+  close_page: onCdp(SHARED_TOOLS.close_page),
+  select_page: onCdp(SHARED_TOOLS.select_page),
   // navigation (2)
-  navigate_page: navigatePage,
-  wait_for: waitForText,
+  navigate_page: onCdp(SHARED_TOOLS.navigate_page),
+  wait_for: onCdp(SHARED_TOOLS.wait_for),
   // evaluate (1)
-  evaluate_script: evaluateScript,
+  evaluate_script: onCdp(SHARED_TOOLS.evaluate_script),
   // snapshot (1)
-  take_snapshot: takeSnapshot,
+  take_snapshot: onCdp(SHARED_TOOLS.take_snapshot),
   // interaction (8)
-  click: click,
-  hover: hover,
-  drag: drag,
-  fill: fill,
-  fill_form: fillForm,
-  type_text: typeText,
-  press_key: pressKey,
-  upload_file: uploadFile,
+  click: onCdp(SHARED_TOOLS.click),
+  hover: onCdp(SHARED_TOOLS.hover),
+  drag: onCdp(SHARED_TOOLS.drag),
+  fill: onCdp(SHARED_TOOLS.fill),
+  fill_form: onCdp(SHARED_TOOLS.fill_form),
+  type_text: onCdp(SHARED_TOOLS.type_text),
+  press_key: onCdp(SHARED_TOOLS.press_key),
+  upload_file: onCdp(SHARED_TOOLS.upload_file),
   // screenshot + emulation (3)
-  take_screenshot: takeScreenshot,
-  emulate: emulate,
-  resize_page: resizePage,
+  take_screenshot: onCdp(SHARED_TOOLS.take_screenshot),
+  emulate: onCdp(SHARED_TOOLS.emulate),
+  resize_page: onCdp(SHARED_TOOLS.resize_page),
   // dialogs (1)
-  handle_dialog: handleDialog,
+  handle_dialog: onCdp(SHARED_TOOLS.handle_dialog),
   // console + network (4)
   list_console_messages: listConsoleMessages,
   get_console_message: getConsoleMessage,
@@ -96,12 +105,16 @@ export const TOOLS = {
   performance_trace: performanceTrace,
   // heap (1)
   take_heapsnapshot: takeHeapsnapshot,
-  // lighthouse (1) — the only non-CDP tool
+  // lighthouse (1) : the only non-CDP tool
   lighthouse_audit: lighthouseAudit,
-  // network mocking (3) — persistent per-target fake backend (toolkit addition, Fetch domain)
+  // network mocking (3) : persistent per-target fake backend (toolkit addition, Fetch domain)
   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>>;