cdp-toolkit 3.0.3 → 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/CHANGELOG.md +13 -0
- package/CONTRACT.md +2 -2
- package/README.md +84 -1
- package/dist/bidi/mux-daemon.js +316 -10
- package/dist/cli.js +567 -85
- package/dist/index.js +404 -38
- package/dist/mcp.js +631 -130
- package/package.json +1 -1
- package/src/cdp/driver.ts +20 -9
- package/src/cli.ts +17 -4
- package/src/client.ts +22 -6
- package/src/endpoints.ts +428 -0
- package/src/leases-tools.ts +6 -3
- package/src/leases.ts +28 -4
- package/src/manifest.ts +54 -42
- package/src/mcp.ts +52 -8
- package/src/origins.ts +5 -2
- package/src/policy.ts +163 -0
- package/src/reap.ts +14 -0
- package/src/shared-tools.ts +72 -4
- package/src/toolDocs.ts +39 -36
- package/src/tools/browser-session.ts +26 -12
- package/src/tools/dispatch-mouse.ts +2 -1
- package/src/tools/focus-emulation.ts +5 -3
- package/src/tools/lighthouse.ts +4 -2
- package/src/version.ts +1 -1
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "cdp-toolkit",
|
|
3
|
-
"version": "3.0
|
|
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,
|
|
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);
|
|
@@ -1769,7 +1778,7 @@ class CdpBrowserDriver implements BrowserDriver {
|
|
|
1769
1778
|
// Opportunistic, not load-bearing: the beacon socket dies with the tab
|
|
1770
1779
|
// anyway, and readBeaconOver's dead-connection branch would drop it on the
|
|
1771
1780
|
// next read. Dropping it here just avoids holding a corpse until then.
|
|
1772
|
-
if (res.success !== false) beaconSessions.drop(id);
|
|
1781
|
+
if (res.success !== false) beaconSessions.drop(beaconKey(id));
|
|
1773
1782
|
return { success: res.success ?? true };
|
|
1774
1783
|
});
|
|
1775
1784
|
}
|
|
@@ -1821,7 +1830,8 @@ class CdpBrowserDriver implements BrowserDriver {
|
|
|
1821
1830
|
* into a document that already has it adds no second set of listeners.
|
|
1822
1831
|
*/
|
|
1823
1832
|
async installActivityBeacon(targetId: string): Promise<boolean> {
|
|
1824
|
-
const
|
|
1833
|
+
const key = beaconKey(targetId);
|
|
1834
|
+
const held = beaconSessions.get(key);
|
|
1825
1835
|
if (held) {
|
|
1826
1836
|
const rearmed = await held
|
|
1827
1837
|
.send("Runtime.evaluate", { expression: BEACON_SOURCE, returnByValue: true })
|
|
@@ -1830,7 +1840,7 @@ class CdpBrowserDriver implements BrowserDriver {
|
|
|
1830
1840
|
if (rearmed) return true;
|
|
1831
1841
|
// The socket is gone (tab closed, browser restarted): fall through and
|
|
1832
1842
|
// build a fresh one rather than reporting a beacon that is not there.
|
|
1833
|
-
beaconSessions.drop(
|
|
1843
|
+
beaconSessions.drop(key);
|
|
1834
1844
|
}
|
|
1835
1845
|
const wsUrl = await targetWsUrl(targetId).catch(() => undefined);
|
|
1836
1846
|
if (!wsUrl) return false;
|
|
@@ -1844,7 +1854,7 @@ class CdpBrowserDriver implements BrowserDriver {
|
|
|
1844
1854
|
conn.close();
|
|
1845
1855
|
return false;
|
|
1846
1856
|
}
|
|
1847
|
-
beaconSessions.set(
|
|
1857
|
+
beaconSessions.set(key, conn);
|
|
1848
1858
|
return true;
|
|
1849
1859
|
}
|
|
1850
1860
|
|
|
@@ -1859,11 +1869,12 @@ class CdpBrowserDriver implements BrowserDriver {
|
|
|
1859
1869
|
* CLI, which holds nothing.
|
|
1860
1870
|
*/
|
|
1861
1871
|
async readActivityBeacon(targetId: string): Promise<number | null> {
|
|
1862
|
-
const
|
|
1872
|
+
const key = beaconKey(targetId);
|
|
1873
|
+
const held = beaconSessions.get(key);
|
|
1863
1874
|
if (held) {
|
|
1864
1875
|
const value = await readBeaconOver(held);
|
|
1865
1876
|
if (value !== undefined) return value;
|
|
1866
|
-
beaconSessions.drop(
|
|
1877
|
+
beaconSessions.drop(key);
|
|
1867
1878
|
}
|
|
1868
1879
|
const wsUrl = await targetWsUrl(targetId).catch(() => undefined);
|
|
1869
1880
|
if (!wsUrl) return null;
|
|
@@ -1891,7 +1902,7 @@ class CdpBrowserDriver implements BrowserDriver {
|
|
|
1891
1902
|
* would let one wedged tab cost the listing two timeouts instead of one.
|
|
1892
1903
|
*/
|
|
1893
1904
|
async probeRenderer(targetId: string, timeoutMs: number = RENDERER_PROBE_TIMEOUT_MS): Promise<{ responsive: boolean; beaconTs: number | null }> {
|
|
1894
|
-
const held = beaconSessions.get(targetId);
|
|
1905
|
+
const held = beaconSessions.get(beaconKey(targetId));
|
|
1895
1906
|
if (held) return probeOver(held, timeoutMs);
|
|
1896
1907
|
const wsUrl = await targetWsUrl(targetId).catch(() => undefined);
|
|
1897
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>)(
|
|
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
|
-
/**
|
|
28
|
-
|
|
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
|
-
|
|
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(
|
|
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(
|
|
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
|
}
|
package/src/endpoints.ts
ADDED
|
@@ -0,0 +1,428 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Named CDP endpoints (issue #15): one process, several DevTools ports.
|
|
3
|
+
*
|
|
4
|
+
* A LEAF MODULE ON PURPOSE. client.ts, leases.ts and origins.ts all import it,
|
|
5
|
+
* so it imports nothing from this package, only node builtins.
|
|
6
|
+
*
|
|
7
|
+
* CONFIG SOURCES, all optional:
|
|
8
|
+
* CDP_BASE the single-endpoint shorthand. It is the endpoint named
|
|
9
|
+
* `default`, stored VERBATIM (no normalization, no
|
|
10
|
+
* validation), so `${base}${path}` is byte-for-byte what
|
|
11
|
+
* it was before this module existed.
|
|
12
|
+
* CDP_ENDPOINTS "browser=http://127.0.0.1:9222,teams=http://127.0.0.1:9333?mode=read"
|
|
13
|
+
* CDP_ENDPOINTS_FILE path to JSON:
|
|
14
|
+
* {"default":"browser","endpoints":{"browser":{"base":"http://127.0.0.1:9222"},
|
|
15
|
+
* "teams":{"base":"http://127.0.0.1:9333","readOnly":true}}}
|
|
16
|
+
* `"mode":"read"` is accepted as an alias of `"readOnly":true`.
|
|
17
|
+
*
|
|
18
|
+
* PRECEDENCE AND MERGING. The env string and the file are merged, never
|
|
19
|
+
* shadowed: a name both define must define it identically (same base, same
|
|
20
|
+
* mode), otherwise it is a config error, so precedence can never silently pick
|
|
21
|
+
* the wrong port. Order (which matters only for listing) is env string, then
|
|
22
|
+
* file. The DEFAULT endpoint is the file's `"default"` key if present, else the
|
|
23
|
+
* endpoint named `default`. When no source defines `default`, it is synthesized
|
|
24
|
+
* from CDP_BASE, else http://127.0.0.1:9222, exactly as before; it is NOT
|
|
25
|
+
* synthesized when the file names a different default and CDP_BASE is unset.
|
|
26
|
+
* When CDP_BASE is set and the config also defines `default`, both must agree on
|
|
27
|
+
* the base.
|
|
28
|
+
*
|
|
29
|
+
* NAMES are [A-Za-z0-9_]+ (no '-'): the name lands in lease and origin
|
|
30
|
+
* filenames as `lease-chrome@<name>-<targetId>.json`, and a '-' in it would make
|
|
31
|
+
* the name/id boundary unparseable.
|
|
32
|
+
*
|
|
33
|
+
* Malformed config throws EndpointConfigError naming the problem. Nothing here
|
|
34
|
+
* caches a failure: a bad file that gets fixed is picked up on the next call,
|
|
35
|
+
* and endpoint reachability is never consulted at all (connect-per-call already
|
|
36
|
+
* retries a port that was down at startup).
|
|
37
|
+
*/
|
|
38
|
+
import { AsyncLocalStorage } from "node:async_hooks";
|
|
39
|
+
import { readFileSync } from "node:fs";
|
|
40
|
+
|
|
41
|
+
export interface Endpoint {
|
|
42
|
+
name: string;
|
|
43
|
+
base: string;
|
|
44
|
+
readOnly: boolean;
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
export class EndpointConfigError extends Error {
|
|
48
|
+
constructor(message: string) {
|
|
49
|
+
super(message);
|
|
50
|
+
this.name = "EndpointConfigError";
|
|
51
|
+
}
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
/** The implicit base when nothing is configured; unchanged from client.ts's old const. */
|
|
55
|
+
export const DEFAULT_CDP_BASE = "http://127.0.0.1:9222";
|
|
56
|
+
|
|
57
|
+
/** The selector prefix, e.g. `endpoint:teams/title:Chat`. */
|
|
58
|
+
export const ENDPOINT_PREFIX = "endpoint:";
|
|
59
|
+
|
|
60
|
+
const NAME_RE = /^[A-Za-z0-9_]+$/;
|
|
61
|
+
|
|
62
|
+
export interface EndpointConfig {
|
|
63
|
+
default: Endpoint;
|
|
64
|
+
byName: Map<string, Endpoint>;
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
function checkName(name: string, where: string): void {
|
|
68
|
+
if (!NAME_RE.test(name)) {
|
|
69
|
+
throw new EndpointConfigError(
|
|
70
|
+
`${where}: endpoint name '${name}' is invalid; names are letters, digits and '_' only (no '-', '/', ':' or spaces)`,
|
|
71
|
+
);
|
|
72
|
+
}
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
/** Compare bases on a trailing-slash-insensitive form. Never used to BUILD a URL. */
|
|
76
|
+
function sameBase(a: string, b: string): boolean {
|
|
77
|
+
return a.replace(/\/+$/, "") === b.replace(/\/+$/, "");
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
/** Parse one configured base URL (from CDP_ENDPOINTS or the file), pulling out `?mode=`. */
|
|
81
|
+
function parseBase(raw: string, where: string): { base: string; mode?: "read" | "write" } {
|
|
82
|
+
let url: URL;
|
|
83
|
+
try {
|
|
84
|
+
url = new URL(raw);
|
|
85
|
+
} catch {
|
|
86
|
+
throw new EndpointConfigError(`${where}: '${raw}' is not a valid URL (expected e.g. http://127.0.0.1:9222)`);
|
|
87
|
+
}
|
|
88
|
+
if (url.protocol !== "http:" && url.protocol !== "https:") {
|
|
89
|
+
throw new EndpointConfigError(`${where}: '${raw}' must be an http:// or https:// DevTools origin, not ${url.protocol}`);
|
|
90
|
+
}
|
|
91
|
+
if (url.hash) throw new EndpointConfigError(`${where}: '${raw}' must not carry a #fragment`);
|
|
92
|
+
let mode: "read" | "write" | undefined;
|
|
93
|
+
for (const [key, value] of url.searchParams) {
|
|
94
|
+
if (key !== "mode") {
|
|
95
|
+
throw new EndpointConfigError(`${where}: unknown query parameter '${key}' in '${raw}' (only ?mode=read or ?mode=write is understood)`);
|
|
96
|
+
}
|
|
97
|
+
if (value !== "read" && value !== "write") {
|
|
98
|
+
throw new EndpointConfigError(`${where}: unknown mode '${value}' in '${raw}' (use mode=read or mode=write)`);
|
|
99
|
+
}
|
|
100
|
+
mode = value;
|
|
101
|
+
}
|
|
102
|
+
const path = url.pathname.replace(/\/+$/, "");
|
|
103
|
+
return { base: `${url.protocol}//${url.host}${path}`, mode };
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
function parseEnvString(spec: string): Endpoint[] {
|
|
107
|
+
const out: Endpoint[] = [];
|
|
108
|
+
const seen = new Set<string>();
|
|
109
|
+
for (const part of spec.split(",")) {
|
|
110
|
+
const entry = part.trim();
|
|
111
|
+
if (!entry) continue;
|
|
112
|
+
const eq = entry.indexOf("=");
|
|
113
|
+
if (eq <= 0) {
|
|
114
|
+
throw new EndpointConfigError(`CDP_ENDPOINTS: entry '${entry}' is not name=url (e.g. teams=http://127.0.0.1:9333)`);
|
|
115
|
+
}
|
|
116
|
+
const name = entry.slice(0, eq).trim();
|
|
117
|
+
checkName(name, "CDP_ENDPOINTS");
|
|
118
|
+
if (seen.has(name)) throw new EndpointConfigError(`CDP_ENDPOINTS: duplicate endpoint name '${name}'`);
|
|
119
|
+
seen.add(name);
|
|
120
|
+
const { base, mode } = parseBase(entry.slice(eq + 1).trim(), `CDP_ENDPOINTS endpoint '${name}'`);
|
|
121
|
+
out.push({ name, base, readOnly: mode === "read" });
|
|
122
|
+
}
|
|
123
|
+
return out;
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
function parseFile(path: string): { endpoints: Endpoint[]; defaultName?: string } {
|
|
127
|
+
let text: string;
|
|
128
|
+
try {
|
|
129
|
+
text = readFileSync(path, "utf8");
|
|
130
|
+
} catch (err) {
|
|
131
|
+
const code = (err as NodeJS.ErrnoException).code ?? String(err);
|
|
132
|
+
throw new EndpointConfigError(`CDP_ENDPOINTS_FILE: cannot read '${path}' (${code})`);
|
|
133
|
+
}
|
|
134
|
+
let json: unknown;
|
|
135
|
+
try {
|
|
136
|
+
json = JSON.parse(text);
|
|
137
|
+
} catch (err) {
|
|
138
|
+
throw new EndpointConfigError(`CDP_ENDPOINTS_FILE: '${path}' is not valid JSON (${err instanceof Error ? err.message : String(err)})`);
|
|
139
|
+
}
|
|
140
|
+
const where = `CDP_ENDPOINTS_FILE '${path}'`;
|
|
141
|
+
if (!json || typeof json !== "object" || Array.isArray(json)) {
|
|
142
|
+
throw new EndpointConfigError(`${where}: top level must be an object {"default"?, "endpoints": {...}}`);
|
|
143
|
+
}
|
|
144
|
+
const top = json as Record<string, unknown>;
|
|
145
|
+
for (const key of Object.keys(top)) {
|
|
146
|
+
if (key !== "default" && key !== "endpoints") throw new EndpointConfigError(`${where}: unknown top-level key '${key}'`);
|
|
147
|
+
}
|
|
148
|
+
if (top.default !== undefined && typeof top.default !== "string") {
|
|
149
|
+
throw new EndpointConfigError(`${where}: "default" must be an endpoint name string`);
|
|
150
|
+
}
|
|
151
|
+
const raw = top.endpoints ?? {};
|
|
152
|
+
if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
|
|
153
|
+
throw new EndpointConfigError(`${where}: "endpoints" must be an object keyed by endpoint name`);
|
|
154
|
+
}
|
|
155
|
+
const endpoints: Endpoint[] = [];
|
|
156
|
+
for (const [name, value] of Object.entries(raw as Record<string, unknown>)) {
|
|
157
|
+
checkName(name, where);
|
|
158
|
+
const at = `${where} endpoint '${name}'`;
|
|
159
|
+
if (!value || typeof value !== "object" || Array.isArray(value)) {
|
|
160
|
+
throw new EndpointConfigError(`${at}: must be an object like {"base":"http://127.0.0.1:9333"}`);
|
|
161
|
+
}
|
|
162
|
+
const v = value as Record<string, unknown>;
|
|
163
|
+
for (const key of Object.keys(v)) {
|
|
164
|
+
if (key !== "base" && key !== "readOnly" && key !== "mode") {
|
|
165
|
+
throw new EndpointConfigError(`${at}: unknown key '${key}' (known: base, readOnly, mode)`);
|
|
166
|
+
}
|
|
167
|
+
}
|
|
168
|
+
if (typeof v.base !== "string") throw new EndpointConfigError(`${at}: "base" is required and must be a URL string`);
|
|
169
|
+
if (v.readOnly !== undefined && typeof v.readOnly !== "boolean") throw new EndpointConfigError(`${at}: "readOnly" must be a boolean`);
|
|
170
|
+
if (v.mode !== undefined && v.mode !== "read" && v.mode !== "write") {
|
|
171
|
+
throw new EndpointConfigError(`${at}: unknown mode '${String(v.mode)}' (use "read" or "write")`);
|
|
172
|
+
}
|
|
173
|
+
const parsed = parseBase(v.base, at);
|
|
174
|
+
const votes = [parsed.mode, v.mode as string | undefined, v.readOnly === undefined ? undefined : v.readOnly ? "read" : "write"].filter(
|
|
175
|
+
(x): x is string => x !== undefined,
|
|
176
|
+
);
|
|
177
|
+
if (new Set(votes).size > 1) throw new EndpointConfigError(`${at}: readOnly / mode settings contradict each other`);
|
|
178
|
+
endpoints.push({ name, base: parsed.base, readOnly: votes[0] === "read" });
|
|
179
|
+
}
|
|
180
|
+
return { endpoints, defaultName: top.default as string | undefined };
|
|
181
|
+
}
|
|
182
|
+
|
|
183
|
+
/**
|
|
184
|
+
* Parse the endpoint config out of `env`. Pure apart from reading
|
|
185
|
+
* CDP_ENDPOINTS_FILE; no caching (see the memoized accessors below).
|
|
186
|
+
*/
|
|
187
|
+
export function loadEndpoints(env: NodeJS.ProcessEnv = process.env): EndpointConfig {
|
|
188
|
+
const fromEnv = env.CDP_ENDPOINTS !== undefined ? parseEnvString(env.CDP_ENDPOINTS) : [];
|
|
189
|
+
const file = env.CDP_ENDPOINTS_FILE ? parseFile(env.CDP_ENDPOINTS_FILE) : { endpoints: [] as Endpoint[], defaultName: undefined };
|
|
190
|
+
|
|
191
|
+
const merged = new Map<string, Endpoint>();
|
|
192
|
+
for (const ep of fromEnv) merged.set(ep.name, ep);
|
|
193
|
+
for (const ep of file.endpoints) {
|
|
194
|
+
const prior = merged.get(ep.name);
|
|
195
|
+
if (prior && (prior.base !== ep.base || prior.readOnly !== ep.readOnly)) {
|
|
196
|
+
throw new EndpointConfigError(
|
|
197
|
+
`endpoint '${ep.name}' is defined differently in CDP_ENDPOINTS (${prior.base}${prior.readOnly ? " read-only" : ""}) and CDP_ENDPOINTS_FILE (${ep.base}${ep.readOnly ? " read-only" : ""})`,
|
|
198
|
+
);
|
|
199
|
+
}
|
|
200
|
+
if (!prior) merged.set(ep.name, ep);
|
|
201
|
+
}
|
|
202
|
+
|
|
203
|
+
// CDP_BASE is the endpoint named `default`. Read with `!== undefined`, not
|
|
204
|
+
// truthiness, matching the old `process.env.CDP_BASE ?? ...` exactly.
|
|
205
|
+
const cdpBase = env.CDP_BASE;
|
|
206
|
+
if (cdpBase !== undefined) {
|
|
207
|
+
const configured = merged.get("default");
|
|
208
|
+
if (configured && !sameBase(configured.base, cdpBase)) {
|
|
209
|
+
throw new EndpointConfigError(
|
|
210
|
+
`CDP_BASE (${cdpBase}) and the configured endpoint 'default' (${configured.base}) disagree; drop one or make them match`,
|
|
211
|
+
);
|
|
212
|
+
}
|
|
213
|
+
// Verbatim string, never the normalized one, so a CDP_BASE-only setup builds byte-identical URLs.
|
|
214
|
+
merged.set("default", { name: "default", base: cdpBase, readOnly: configured?.readOnly ?? false });
|
|
215
|
+
}
|
|
216
|
+
|
|
217
|
+
const defaultName = file.defaultName ?? "default";
|
|
218
|
+
if (!merged.has(defaultName)) {
|
|
219
|
+
if (file.defaultName !== undefined) {
|
|
220
|
+
throw new EndpointConfigError(
|
|
221
|
+
`CDP_ENDPOINTS_FILE names default endpoint '${file.defaultName}', which is not defined (known: ${[...merged.keys()].join(", ") || "none"})`,
|
|
222
|
+
);
|
|
223
|
+
}
|
|
224
|
+
merged.set("default", { name: "default", base: DEFAULT_CDP_BASE, readOnly: false });
|
|
225
|
+
}
|
|
226
|
+
|
|
227
|
+
// The default endpoint first, then config order: listing order and the lease
|
|
228
|
+
// namespace tie-break (see leaseNamespace) both read this order.
|
|
229
|
+
const def = merged.get(defaultName)!;
|
|
230
|
+
const byName = new Map<string, Endpoint>([[def.name, def]]);
|
|
231
|
+
for (const [name, ep] of merged) if (name !== def.name) byName.set(name, ep);
|
|
232
|
+
return { default: def, byName };
|
|
233
|
+
}
|
|
234
|
+
|
|
235
|
+
/* ------------------------------ memoized accessors ------------------------------ */
|
|
236
|
+
|
|
237
|
+
let cache: { sig: string; config: EndpointConfig } | undefined;
|
|
238
|
+
|
|
239
|
+
function signature(env: NodeJS.ProcessEnv): string {
|
|
240
|
+
return JSON.stringify([env.CDP_BASE ?? null, env.CDP_ENDPOINTS ?? null, env.CDP_ENDPOINTS_FILE ?? null]);
|
|
241
|
+
}
|
|
242
|
+
|
|
243
|
+
/** The process config, re-parsed whenever the three env vars change. Errors are never cached. */
|
|
244
|
+
export function endpointConfig(): EndpointConfig {
|
|
245
|
+
const sig = signature(process.env);
|
|
246
|
+
if (cache?.sig === sig) return cache.config;
|
|
247
|
+
const config = loadEndpoints(process.env);
|
|
248
|
+
cache = { sig, config };
|
|
249
|
+
return config;
|
|
250
|
+
}
|
|
251
|
+
|
|
252
|
+
/** Test hook: forget the memoized config (e.g. after rewriting the file in place). */
|
|
253
|
+
export function resetEndpointCache(): void {
|
|
254
|
+
cache = undefined;
|
|
255
|
+
}
|
|
256
|
+
|
|
257
|
+
export function defaultEndpoint(): Endpoint {
|
|
258
|
+
return endpointConfig().default;
|
|
259
|
+
}
|
|
260
|
+
|
|
261
|
+
/** Every configured endpoint, default first. */
|
|
262
|
+
export function allEndpoints(): Endpoint[] {
|
|
263
|
+
return [...endpointConfig().byName.values()];
|
|
264
|
+
}
|
|
265
|
+
|
|
266
|
+
export function getEndpoint(name: string): Endpoint {
|
|
267
|
+
const { byName } = endpointConfig();
|
|
268
|
+
const ep = byName.get(name);
|
|
269
|
+
if (!ep) {
|
|
270
|
+
throw new EndpointConfigError(
|
|
271
|
+
`unknown endpoint '${name}' (known: ${[...byName.keys()].join(", ")}). Configure it with CDP_ENDPOINTS or CDP_ENDPOINTS_FILE.`,
|
|
272
|
+
);
|
|
273
|
+
}
|
|
274
|
+
return ep;
|
|
275
|
+
}
|
|
276
|
+
|
|
277
|
+
/**
|
|
278
|
+
* The lease/origin namespace of an endpoint: undefined means the legacy
|
|
279
|
+
* un-suffixed filenames (`lease-chrome-<id>.json`), shared with older
|
|
280
|
+
* processes. That is the default endpoint, and ANY endpoint whose base equals
|
|
281
|
+
* the default's: two names for one browser must share one lease space, or
|
|
282
|
+
* `endpoint:browser/` would walk straight past a lease held through the
|
|
283
|
+
* default. Two non-default names for one base share the namespace of the first
|
|
284
|
+
* declared.
|
|
285
|
+
*/
|
|
286
|
+
export function leaseNamespace(ep: Endpoint): string | undefined {
|
|
287
|
+
const { default: def, byName } = endpointConfig();
|
|
288
|
+
if (sameBase(ep.base, def.base)) return undefined;
|
|
289
|
+
for (const other of byName.values()) if (sameBase(other.base, ep.base)) return other.name;
|
|
290
|
+
return ep.name;
|
|
291
|
+
}
|
|
292
|
+
|
|
293
|
+
/* ---------------------------------- selectors ---------------------------------- */
|
|
294
|
+
|
|
295
|
+
/** True when `target` starts with the `endpoint:` prefix. `url:endpoint:x` is NOT a prefix. */
|
|
296
|
+
export function hasEndpointPrefix(target: unknown): target is string {
|
|
297
|
+
return typeof target === "string" && target.startsWith(ENDPOINT_PREFIX);
|
|
298
|
+
}
|
|
299
|
+
|
|
300
|
+
/**
|
|
301
|
+
* Split `endpoint:<name>/<rest>` into the endpoint and the remaining selector.
|
|
302
|
+
* No prefix: the default endpoint and the selector unchanged. `endpoint:teams`
|
|
303
|
+
* or `endpoint:teams/` alone: rest undefined (the endpoint's active page).
|
|
304
|
+
*/
|
|
305
|
+
export function splitEndpointSelector(target: string | undefined): { endpoint: Endpoint; rest: string | undefined } {
|
|
306
|
+
if (!hasEndpointPrefix(target)) return { endpoint: defaultEndpoint(), rest: target };
|
|
307
|
+
const body = target.slice(ENDPOINT_PREFIX.length);
|
|
308
|
+
const slash = body.indexOf("/");
|
|
309
|
+
const name = slash < 0 ? body : body.slice(0, slash);
|
|
310
|
+
if (!name) throw new EndpointConfigError(`selector '${target}' has an empty endpoint name; use endpoint:<name>/<selector>`);
|
|
311
|
+
const rest = slash < 0 ? undefined : body.slice(slash + 1);
|
|
312
|
+
return { endpoint: getEndpoint(name), rest: rest === "" ? undefined : rest };
|
|
313
|
+
}
|
|
314
|
+
|
|
315
|
+
/** Args keys that carry a target selector: `target` everywhere, `targetId` on claim_page. */
|
|
316
|
+
export const SELECTOR_KEYS = ["target", "targetId"] as const;
|
|
317
|
+
|
|
318
|
+
/** The refusal for any endpoint feature under the Firefox backend (mcp.ts and cli.ts). */
|
|
319
|
+
export const ENDPOINTS_FIREFOX_MESSAGE =
|
|
320
|
+
"named CDP endpoints (an 'endpoint:<name>/' selector prefix, the endpoint arg, list_pages allEndpoints) need the Chrome backend; the Firefox BiDi backend has one session and no endpoints";
|
|
321
|
+
|
|
322
|
+
/** True when args ask for any endpoint feature at all (used to refuse them on Firefox, without loading config). */
|
|
323
|
+
export function usesEndpointArgs(args: unknown): boolean {
|
|
324
|
+
if (!args || typeof args !== "object") return false;
|
|
325
|
+
const a = args as Record<string, unknown>;
|
|
326
|
+
return SELECTOR_KEYS.some((k) => hasEndpointPrefix(a[k])) || a.endpoint !== undefined || a.allEndpoints === true;
|
|
327
|
+
}
|
|
328
|
+
|
|
329
|
+
/**
|
|
330
|
+
* Resolve the endpoint and strip the prefix: the one place dispatch rewrites
|
|
331
|
+
* args. With no prefix and no `endpoint` key the ORIGINAL object comes back
|
|
332
|
+
* untouched. A prefix that names nothing after the slash deletes the key (so
|
|
333
|
+
* the tool sees its own default, 'active'), and the `endpoint` key itself is
|
|
334
|
+
* removed so no tool's own arg checks ever see it.
|
|
335
|
+
*/
|
|
336
|
+
export function stripEndpointArgs(args: unknown): { endpoint: Endpoint; args: unknown } {
|
|
337
|
+
if (!args || typeof args !== "object" || Array.isArray(args)) return { endpoint: defaultEndpoint(), args };
|
|
338
|
+
const a = args as Record<string, unknown>;
|
|
339
|
+
const picks: Array<{ from: string; endpoint: Endpoint }> = [];
|
|
340
|
+
let out: Record<string, unknown> | undefined;
|
|
341
|
+
for (const key of SELECTOR_KEYS) {
|
|
342
|
+
const v = a[key];
|
|
343
|
+
if (!hasEndpointPrefix(v)) continue;
|
|
344
|
+
const { endpoint, rest } = splitEndpointSelector(v);
|
|
345
|
+
picks.push({ from: `${key} '${v}'`, endpoint });
|
|
346
|
+
out ??= { ...a };
|
|
347
|
+
if (rest === undefined) delete out[key];
|
|
348
|
+
else out[key] = rest;
|
|
349
|
+
}
|
|
350
|
+
if (a.endpoint !== undefined) {
|
|
351
|
+
if (typeof a.endpoint !== "string" || a.endpoint === "") {
|
|
352
|
+
throw new EndpointConfigError("`endpoint` must be a non-empty endpoint name string");
|
|
353
|
+
}
|
|
354
|
+
picks.push({ from: `endpoint '${a.endpoint}'`, endpoint: getEndpoint(a.endpoint) });
|
|
355
|
+
out ??= { ...a };
|
|
356
|
+
delete out.endpoint;
|
|
357
|
+
}
|
|
358
|
+
// A Chrome lease token names its endpoint too (`chrome@<ns>:<targetId>:<nonce>`), so
|
|
359
|
+
// `release_page {lease}` with no prefix acts on the endpoint the lease was taken on,
|
|
360
|
+
// not the default. The token stays in args: the lease scope still reads it.
|
|
361
|
+
const token = leaseTokenNamespace(a.lease);
|
|
362
|
+
if (!picks.length) {
|
|
363
|
+
if (token?.ns === undefined) return { endpoint: defaultEndpoint(), args };
|
|
364
|
+
return { endpoint: endpointForNamespace(token.ns), args };
|
|
365
|
+
}
|
|
366
|
+
const first = picks[0]!;
|
|
367
|
+
for (const p of picks.slice(1)) {
|
|
368
|
+
if (p.endpoint.name !== first.endpoint.name) {
|
|
369
|
+
throw new EndpointConfigError(`conflicting endpoints: ${first.from} vs ${p.from}; name one endpoint per call`);
|
|
370
|
+
}
|
|
371
|
+
}
|
|
372
|
+
// Compared by lease namespace, not name: two names for one base share one lease space.
|
|
373
|
+
if (token && leaseNamespace(first.endpoint) !== token.ns) {
|
|
374
|
+
throw new EndpointConfigError(
|
|
375
|
+
`conflicting endpoints: ${first.from} vs the lease token, which belongs to ${token.ns === undefined ? "the default endpoint" : `endpoint '${token.ns}'`}; name one endpoint per call`,
|
|
376
|
+
);
|
|
377
|
+
}
|
|
378
|
+
return { endpoint: first.endpoint, args: out ?? a };
|
|
379
|
+
}
|
|
380
|
+
|
|
381
|
+
/**
|
|
382
|
+
* The lease namespace a Chrome lease token was minted under (leases.ts mintToken:
|
|
383
|
+
* `<backend>:<targetId>:<nonce>`, backend `chrome` or `chrome@<ns>`). `{ns: undefined}`
|
|
384
|
+
* is the default namespace (plain `chrome`). null for anything else: no token, a
|
|
385
|
+
* Firefox token, or a malformed one, which the lease layer rejects on its own terms.
|
|
386
|
+
* Parsed here rather than via leases.ts's tokenParts because this module is a leaf.
|
|
387
|
+
*/
|
|
388
|
+
function leaseTokenNamespace(lease: unknown): { ns: string | undefined } | null {
|
|
389
|
+
if (typeof lease !== "string") return null;
|
|
390
|
+
const colon = lease.indexOf(":");
|
|
391
|
+
if (colon <= 0) return null;
|
|
392
|
+
const head = lease.slice(0, colon);
|
|
393
|
+
if (head === "chrome") return { ns: undefined };
|
|
394
|
+
if (!head.startsWith("chrome@")) return null;
|
|
395
|
+
const ns = head.slice("chrome@".length);
|
|
396
|
+
return NAME_RE.test(ns) ? { ns } : null;
|
|
397
|
+
}
|
|
398
|
+
|
|
399
|
+
/** The first configured endpoint whose lease namespace is `ns` (see leaseNamespace). */
|
|
400
|
+
function endpointForNamespace(ns: string): Endpoint {
|
|
401
|
+
for (const ep of endpointConfig().byName.values()) if (leaseNamespace(ep) === ns) return ep;
|
|
402
|
+
throw new EndpointConfigError(
|
|
403
|
+
`the lease token belongs to endpoint '${ns}', which is not configured (known: ${[...endpointConfig().byName.keys()].join(", ")})`,
|
|
404
|
+
);
|
|
405
|
+
}
|
|
406
|
+
|
|
407
|
+
/** The endpoint a call's args select (selector prefix, `endpoint` key, or a `chrome@<ns>` lease token), else the default. */
|
|
408
|
+
export function endpointForArgs(args: unknown): Endpoint {
|
|
409
|
+
return stripEndpointArgs(args).endpoint;
|
|
410
|
+
}
|
|
411
|
+
|
|
412
|
+
/* ------------------------------------ scope ------------------------------------ */
|
|
413
|
+
|
|
414
|
+
const endpointScope = new AsyncLocalStorage<Endpoint>();
|
|
415
|
+
|
|
416
|
+
/** The endpoint of the enclosing withEndpointScope, else the default endpoint. */
|
|
417
|
+
export function currentEndpoint(): Endpoint {
|
|
418
|
+
return endpointScope.getStore() ?? defaultEndpoint();
|
|
419
|
+
}
|
|
420
|
+
|
|
421
|
+
/** True when the current scope is a non-default endpoint (used to tag output rows). */
|
|
422
|
+
export function isDefaultEndpoint(ep: Endpoint): boolean {
|
|
423
|
+
return ep.name === defaultEndpoint().name;
|
|
424
|
+
}
|
|
425
|
+
|
|
426
|
+
export function withEndpointScope<T>(ep: Endpoint, fn: () => Promise<T>): Promise<T> {
|
|
427
|
+
return endpointScope.run(ep, fn);
|
|
428
|
+
}
|