cdp-toolkit 3.0.2 → 3.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "cdp-toolkit",
3
- "version": "3.0.2",
3
+ "version": "3.1.0",
4
4
  "description": "A lightweight chrome-devtools-mcp alternative: an MCP server + CLI that drives the tabs you name, one target per call over one 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. 48 tools (only 5 core tools listed by default, plus search_tools/call_tool to reach the rest) including built-in network mocking, a cookie group, tab leases with human-activity detection, real HTML5 drag-and-drop, raw mouse/scroll dispatch, downloads, permission grants, and tab-to-video screen recording so several agents can drive one browser without stealing each other's tabs or a human's. No Puppeteer, no all-target fan-out.",
5
5
  "type": "module",
6
6
  "license": "MIT",
package/src/cdp/driver.ts CHANGED
@@ -7,7 +7,8 @@
7
7
  */
8
8
  import { CdpConnection, CdpError, listTargets, openBrowser, openPage, resolveTarget } from "../client.ts";
9
9
  import type { Target, TargetSelector } from "../types.ts";
10
- import { LeaseConflictError } from "../leases.ts";
10
+ import { chromeLeaseBackend, LeaseConflictError } from "../leases.ts";
11
+ import { currentEndpoint } from "../endpoints.ts";
11
12
  import { BEACON_READ_EXPRESSION, BEACON_SOURCE, BeaconSessions, RENDERER_PROBE_EXPRESSION, RENDERER_PROBE_TIMEOUT_MS, sendInput } from "../activity.ts";
12
13
  import { resolveUid } from "../tools/snapshot.ts";
13
14
  import { resolveWorkerSelector } from "./workers.ts";
@@ -703,7 +704,7 @@ class CdpPageDriver implements PageDriver {
703
704
  * one.
704
705
  */
705
706
  private async dispatchInput<T = Record<string, unknown>>(method: string, params: Record<string, unknown> = {}): Promise<T> {
706
- return sendInput<T>(this.conn, "chrome", this.info.id, method, params);
707
+ return sendInput<T>(this.conn, chromeLeaseBackend(), this.info.id, method, params);
707
708
  }
708
709
  /** Same as ensureDomain but tolerates the enable call itself failing (matches a legacy
709
710
  * `.catch(() => undefined)` site); a failed enable is NOT re-attempted on the next call. */
@@ -1597,6 +1598,14 @@ class CdpPageDriver implements PageDriver {
1597
1598
  */
1598
1599
  const beaconSessions = new BeaconSessions<CdpConnection>((conn) => conn.close());
1599
1600
 
1601
+ /** Beacon sessions are keyed by endpoint plus target id: a target id only means
1602
+ * something inside one browser, and named endpoints are separate browsers. The
1603
+ * default endpoint keeps the bare id. */
1604
+ function beaconKey(targetId: string): string {
1605
+ const backend = chromeLeaseBackend(currentEndpoint());
1606
+ return backend === "chrome" ? targetId : `${backend}\u0000${targetId}`;
1607
+ }
1608
+
1600
1609
  /** The page endpoint for a target id, or undefined if the browser no longer has it. */
1601
1610
  async function targetWsUrl(targetId: string): Promise<string | undefined> {
1602
1611
  const hit = (await listTargets()).find((t) => t.id === targetId);
@@ -1691,6 +1700,56 @@ function noSuchTarget(e: unknown): never {
1691
1700
  if (typeof (e as { code?: unknown } | null | undefined)?.code === "string") throw e;
1692
1701
  throw driverError("no-such-target", e instanceof CdpError ? e.message : String(e));
1693
1702
  }
1703
+ /** Upper bound on waiting for a new tab to settle; see createSettledTarget. */
1704
+ export const NEW_TARGET_SETTLE_MS = 2000;
1705
+
1706
+ /**
1707
+ * Create a tab and return only once the browser has finished adopting it.
1708
+ *
1709
+ * Vivaldi wedges a tab that anything attaches to in the first few milliseconds
1710
+ * after Target.createTarget: the tab keeps an empty URL, its renderer never
1711
+ * answers again (Page.enable, Runtime.evaluate and runIfWaitingForDebugger all
1712
+ * time out), and only a manual reload recovers it. new_page{claim:true} hit this
1713
+ * every time, because the activity beacon attaches straight after creation.
1714
+ * Measured on Vivaldi 8.2 (Chromium 152): an attach at ~0ms wedged 5/5 tabs
1715
+ * (https and about:blank alike, page socket or flattened session alike); an
1716
+ * attach after the tab's first Target.targetInfoChanged loaded 5/5.
1717
+ *
1718
+ * So: discover targets, create, and wait for that first targetInfoChanged for
1719
+ * this id, capped at NEW_TARGET_SETTLE_MS. The listener is registered BEFORE
1720
+ * createTarget because the event can beat the command's response. A browser
1721
+ * that never sends the event costs at most the cap, never a failure.
1722
+ */
1723
+ export async function createSettledTarget(
1724
+ conn: Pick<CdpConnection, "send" | "on">,
1725
+ url: string,
1726
+ settleMs = NEW_TARGET_SETTLE_MS,
1727
+ ): Promise<string> {
1728
+ const changed = new Set<string>();
1729
+ let id = "";
1730
+ let wake: (() => void) | undefined;
1731
+ const off = conn.on("Target.targetInfoChanged", (params) => {
1732
+ const t = (params as { targetInfo?: { targetId?: string } }).targetInfo?.targetId;
1733
+ if (!t) return;
1734
+ changed.add(t);
1735
+ if (t === id) wake?.();
1736
+ });
1737
+ try {
1738
+ await conn.send("Target.setDiscoverTargets", { discover: true }).catch(() => undefined);
1739
+ const { targetId } = await conn.send<{ targetId: string }>("Target.createTarget", { url });
1740
+ if (!targetId) throw driverError("page-error", "Target.createTarget returned no targetId");
1741
+ id = targetId;
1742
+ if (!changed.has(targetId)) {
1743
+ await new Promise<void>((resolve) => {
1744
+ const timer = setTimeout(resolve, settleMs);
1745
+ wake = () => { clearTimeout(timer); resolve(); };
1746
+ });
1747
+ }
1748
+ return targetId;
1749
+ } finally {
1750
+ off();
1751
+ }
1752
+ }
1694
1753
  class CdpBrowserDriver implements BrowserDriver {
1695
1754
  readonly scheme = "cdp";
1696
1755
  readonly lifetime: LifetimeModel = "per-call";
@@ -1706,8 +1765,7 @@ class CdpBrowserDriver implements BrowserDriver {
1706
1765
  }
1707
1766
  async newPage(url?: string): Promise<PageInfo> {
1708
1767
  return withBrowserConn(async (conn) => {
1709
- const { targetId } = await conn.send<{ targetId: string }>("Target.createTarget", { url: url ?? "about:blank" });
1710
- if (!targetId) throw driverError("page-error", "Target.createTarget returned no targetId");
1768
+ const targetId = await createSettledTarget(conn, url ?? "about:blank");
1711
1769
  return { id: targetId, url: url ?? "about:blank", title: "" };
1712
1770
  });
1713
1771
  }
@@ -1720,7 +1778,7 @@ class CdpBrowserDriver implements BrowserDriver {
1720
1778
  // Opportunistic, not load-bearing: the beacon socket dies with the tab
1721
1779
  // anyway, and readBeaconOver's dead-connection branch would drop it on the
1722
1780
  // next read. Dropping it here just avoids holding a corpse until then.
1723
- if (res.success !== false) beaconSessions.drop(id);
1781
+ if (res.success !== false) beaconSessions.drop(beaconKey(id));
1724
1782
  return { success: res.success ?? true };
1725
1783
  });
1726
1784
  }
@@ -1772,7 +1830,8 @@ class CdpBrowserDriver implements BrowserDriver {
1772
1830
  * into a document that already has it adds no second set of listeners.
1773
1831
  */
1774
1832
  async installActivityBeacon(targetId: string): Promise<boolean> {
1775
- const held = beaconSessions.get(targetId);
1833
+ const key = beaconKey(targetId);
1834
+ const held = beaconSessions.get(key);
1776
1835
  if (held) {
1777
1836
  const rearmed = await held
1778
1837
  .send("Runtime.evaluate", { expression: BEACON_SOURCE, returnByValue: true })
@@ -1781,7 +1840,7 @@ class CdpBrowserDriver implements BrowserDriver {
1781
1840
  if (rearmed) return true;
1782
1841
  // The socket is gone (tab closed, browser restarted): fall through and
1783
1842
  // build a fresh one rather than reporting a beacon that is not there.
1784
- beaconSessions.drop(targetId);
1843
+ beaconSessions.drop(key);
1785
1844
  }
1786
1845
  const wsUrl = await targetWsUrl(targetId).catch(() => undefined);
1787
1846
  if (!wsUrl) return false;
@@ -1795,7 +1854,7 @@ class CdpBrowserDriver implements BrowserDriver {
1795
1854
  conn.close();
1796
1855
  return false;
1797
1856
  }
1798
- beaconSessions.set(targetId, conn);
1857
+ beaconSessions.set(key, conn);
1799
1858
  return true;
1800
1859
  }
1801
1860
 
@@ -1810,11 +1869,12 @@ class CdpBrowserDriver implements BrowserDriver {
1810
1869
  * CLI, which holds nothing.
1811
1870
  */
1812
1871
  async readActivityBeacon(targetId: string): Promise<number | null> {
1813
- const held = beaconSessions.get(targetId);
1872
+ const key = beaconKey(targetId);
1873
+ const held = beaconSessions.get(key);
1814
1874
  if (held) {
1815
1875
  const value = await readBeaconOver(held);
1816
1876
  if (value !== undefined) return value;
1817
- beaconSessions.drop(targetId);
1877
+ beaconSessions.drop(key);
1818
1878
  }
1819
1879
  const wsUrl = await targetWsUrl(targetId).catch(() => undefined);
1820
1880
  if (!wsUrl) return null;
@@ -1842,7 +1902,7 @@ class CdpBrowserDriver implements BrowserDriver {
1842
1902
  * would let one wedged tab cost the listing two timeouts instead of one.
1843
1903
  */
1844
1904
  async probeRenderer(targetId: string, timeoutMs: number = RENDERER_PROBE_TIMEOUT_MS): Promise<{ responsive: boolean; beaconTs: number | null }> {
1845
- const held = beaconSessions.get(targetId);
1905
+ const held = beaconSessions.get(beaconKey(targetId));
1846
1906
  if (held) return probeOver(held, timeoutMs);
1847
1907
  const wsUrl = await targetWsUrl(targetId).catch(() => undefined);
1848
1908
  if (!wsUrl) return { responsive: false, beaconTs: null };
package/src/cli.ts CHANGED
@@ -19,7 +19,7 @@
19
19
  * wins; --json is applied first, then the individual flags).
20
20
  *
21
21
  * Output:
22
- * - success -> JSON.stringify(result, null, 2) to stdout, exit 0.
22
+ * - success -> JSON.stringify(result ?? null, null, 2) to stdout, exit 0.
23
23
  * - throw -> JSON.stringify({ error: message }) to stderr, exit 1.
24
24
  * - no tool -> usage message to stderr, exit 1.
25
25
  * - --list -> all tool names (one per line) to stdout, exit 0.
@@ -29,7 +29,9 @@ import { resolveBackend, stripBrowserFlag, stripConnectFlag, startFirefoxSession
29
29
  import { toolAvailability } from "./capabilities.ts";
30
30
  import { FIREFOX_TOOLS } from "./firefox-tools.ts";
31
31
  import { leaseFromArgs, withLeaseScope } from "./leases.ts";
32
+ import { ENDPOINTS_FIREFOX_MESSAGE, stripEndpointArgs, usesEndpointArgs, withEndpointScope } from "./endpoints.ts";
32
33
  import { MANIFEST } from "./manifest.ts";
34
+ import { assertAllowed } from "./policy.ts";
33
35
  import { runInstaller } from "./install/wizard.ts";
34
36
  import { realpathSync } from "node:fs";
35
37
  import { fileURLToPath } from "node:url";
@@ -344,16 +346,27 @@ async function main(): Promise<number> {
344
346
  return withLeaseScope(leaseFromArgs(parsed.args), async () => {
345
347
  if (browser === "chrome") {
346
348
  const fn = TOOLS[tool];
349
+ // Same endpoint scope as mcp.ts's runTool: the endpoint:<name>/ prefix (or
350
+ // --endpoint) is resolved and stripped once, here. A bad name or a malformed
351
+ // CDP_ENDPOINTS throws to main's catch, which prints {"error": ...} and exits 1.
352
+ const { endpoint, args: toolArgs } = stripEndpointArgs(parsed.args);
353
+ // Read-only endpoint policy, before the tool runs (same check as mcp.ts's runTool).
354
+ // A PolicyError throws to main's catch: {"error": "'click' is not allowed on endpoint ..."}, exit 1.
355
+ assertAllowed(tool, endpoint, toolArgs);
347
356
  // The registry's value type is the union of all tool signatures; each tool
348
357
  // validates its own args at runtime, so we hand the parsed object through.
349
- const result = await (fn as (args: unknown) => Promise<unknown>)(parsed.args);
350
- process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
358
+ const result = await withEndpointScope(endpoint, () => (fn as (args: unknown) => Promise<unknown>)(toolArgs));
359
+ process.stdout.write(`${JSON.stringify(result ?? null, null, 2)}\n`);
351
360
  return 0;
352
361
  }
353
362
 
354
363
  // Firefox: one process per invocation. Launch (or, with --connect/CDP_FIREFOX_ENDPOINT,
355
364
  // attach), run exactly one tool call, always dispose, even if the tool call itself throws —
356
365
  // in launch mode that reaps the spawned process; in attach mode it only ends the BiDi session.
366
+ if (usesEndpointArgs(parsed.args)) {
367
+ process.stderr.write(`${JSON.stringify({ error: ENDPOINTS_FIREFOX_MESSAGE })}\n`);
368
+ return 1;
369
+ }
357
370
  const neutralFn = FIREFOX_TOOLS[tool];
358
371
  if (!neutralFn) {
359
372
  process.stderr.write(`${JSON.stringify({ error: `tool '${tool}' has no Firefox implementation wired` })}\n`);
@@ -362,7 +375,7 @@ async function main(): Promise<number> {
362
375
  const session = await startFirefoxSession({ endpoint });
363
376
  try {
364
377
  const result = await neutralFn(session.driver, parsed.args as never);
365
- process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
378
+ process.stdout.write(`${JSON.stringify(result ?? null, null, 2)}\n`);
366
379
  return 0;
367
380
  } finally {
368
381
  await session.dispose();
package/src/client.ts CHANGED
@@ -4,8 +4,9 @@
4
4
  * the primitives exported here. See CONTRACT.md.
5
5
  */
6
6
  import type { CdpResponse, Target, TargetSelector } from "./types.ts";
7
- import { assertLeaseOk } from "./leases.ts";
7
+ import { assertLeaseOk, chromeLeaseBackend } from "./leases.ts";
8
8
  import { resolveLiveLabel } from "./origins.ts";
9
+ import { currentEndpoint, defaultEndpoint, DEFAULT_CDP_BASE } from "./endpoints.ts";
9
10
  import {
10
11
  isWorkerSelector,
11
12
  isWorkerTargetType,
@@ -24,8 +25,21 @@ import {
24
25
  FRAME_EMPTY_NEEDLE_MESSAGE,
25
26
  } from "./frames.ts";
26
27
 
27
- /** Base HTTP origin of the DevTools endpoint. Override with CDP_BASE. */
28
- export const BASE = process.env.CDP_BASE ?? "http://127.0.0.1:9222";
28
+ /**
29
+ * Base HTTP origin of the DEFAULT DevTools endpoint, fixed at import (CDP_BASE, else
30
+ * http://127.0.0.1:9222, or the default named by CDP_ENDPOINTS / CDP_ENDPOINTS_FILE).
31
+ * Kept for library callers; nothing in this package reads it to build a URL any more:
32
+ * every request resolves its base per call through currentEndpoint() (src/endpoints.ts).
33
+ * A malformed endpoint config must not crash the import, so this falls back to the old
34
+ * expression and the config error surfaces on first use (or at MCP/CLI startup).
35
+ */
36
+ export const BASE: string = (() => {
37
+ try {
38
+ return defaultEndpoint().base;
39
+ } catch {
40
+ return process.env.CDP_BASE ?? DEFAULT_CDP_BASE;
41
+ }
42
+ })();
29
43
 
30
44
  /** Default per-command timeout (ms). Override with CDP_TIMEOUT_MS. */
31
45
  export const DEFAULT_TIMEOUT_MS = Number(process.env.CDP_TIMEOUT_MS ?? 15_000);
@@ -194,7 +208,9 @@ export class CdpConnection {
194
208
  /* ----------------------------- endpoint discovery ----------------------------- */
195
209
 
196
210
  async function httpJson<T>(path: string): Promise<T> {
197
- const res = await fetch(`${BASE}${path}`);
211
+ // Resolved PER CALL, never cached: the endpoint comes from the dispatch scope, and an
212
+ // endpoint that was down a moment ago is simply tried again.
213
+ const res = await fetch(`${currentEndpoint().base}${path}`);
198
214
  if (!res.ok) throw new CdpError(`${path} -> HTTP ${res.status}`);
199
215
  return (await res.json()) as T;
200
216
  }
@@ -237,7 +253,7 @@ export async function resolveTarget(selector: TargetSelector, opts: { lease?: st
237
253
  // target we just resolved. Passing it would only suggest a check is happening
238
254
  // that is not. target-gone earns its keep on claim, and on a list_leases
239
255
  // reap, where a record's id may genuinely be absent from the browser.
240
- await assertLeaseOk("chrome", hit.id, { lease: opts.lease, url: hit.url, title: hit.title });
256
+ await assertLeaseOk(chromeLeaseBackend(), hit.id, { lease: opts.lease, url: hit.url, title: hit.title });
241
257
  return hit;
242
258
  }
243
259
 
@@ -266,7 +282,7 @@ async function pickTarget(targets: Target[], selector: TargetSelector): Promise<
266
282
  }
267
283
  if (selector.startsWith("label:")) {
268
284
  const label = selector.slice(6);
269
- const { matchIds, knownLabels } = await resolveLiveLabel("chrome", label, pages.map((t) => t.id));
285
+ const { matchIds, knownLabels } = await resolveLiveLabel(chromeLeaseBackend(), label, pages.map((t) => t.id));
270
286
  if (matchIds.length > 1) {
271
287
  throw new CdpError(`label 'label:${label}' matches more than one live target: ${matchIds.join(", ")}. Resolve by target id instead.`);
272
288
  }