cdp-toolkit 3.1.0 → 3.3.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 +32 -0
- package/README.md +69 -16
- package/dist/bidi/mux-daemon.js +560 -137
- package/dist/cli.js +1236 -493
- package/dist/index.js +708 -79
- package/dist/mcp.js +1229 -486
- package/package.json +3 -1
- package/src/bidi/driver.ts +346 -54
- package/src/bidi/protocol.ts +27 -9
- package/src/bidi/snapshot.ts +123 -113
- package/src/bidi-browser-tools.ts +366 -0
- package/src/bidi-tools.ts +29 -2
- package/src/cdp/driver.ts +36 -33
- package/src/cdp/endpoint.ts +200 -0
- package/src/cdp/session.ts +246 -0
- package/src/client.ts +118 -10
- package/src/driver.ts +22 -5
- package/src/firefox-tools.ts +6 -3
- package/src/manifest.ts +2 -2
- package/src/policy.ts +2 -2
- package/src/shared-tools.ts +96 -24
- package/src/toolDocs.ts +7 -7
- package/src/tools/dispatch-mouse.ts +6 -1
- package/src/tools/downloads.ts +5 -6
- package/src/tools/evaluate.ts +3 -3
- package/src/tools/navigation.ts +3 -3
- package/src/tools/network_mock.ts +2 -2
- package/src/tools/performance.ts +5 -5
- package/src/tools/permissions.ts +5 -5
- package/src/tools/recorder.ts +3 -3
- package/src/tools/screencast.ts +46 -6
- package/src/tools/snapshot.ts +2 -2
- package/src/version.ts +1 -1
package/src/firefox-tools.ts
CHANGED
|
@@ -1,20 +1,23 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* The complete Firefox tool registry: the 23 tools shared with Chrome (src/shared-tools.ts), the
|
|
3
3
|
* 7 Firefox-only console/network/mock tools (src/bidi-tools.ts), the 3 lease tools
|
|
4
|
-
* (src/leases-tools.ts),
|
|
5
|
-
*
|
|
6
|
-
*
|
|
4
|
+
* (src/leases-tools.ts), the 2 browser-scoped tools wait_for_download / grant_permissions
|
|
5
|
+
* (src/bidi-browser-tools.ts, Firefox 160+), and extract_page (src/tools/extract.ts), which is
|
|
6
|
+
* backend-neutral by construction (its page work runs entirely through Driver.evaluate). This is
|
|
7
|
+
* what src/neutral.ts used to be; it now composes five files instead of reimplementing everything in one.
|
|
7
8
|
*/
|
|
8
9
|
import type { BrowserDriver } from "./driver.ts";
|
|
9
10
|
import type { ToolName } from "./index.ts";
|
|
10
11
|
import { SHARED_TOOLS } from "./shared-tools.ts";
|
|
11
12
|
import { BIDI_ONLY_TOOLS } from "./bidi-tools.ts";
|
|
12
13
|
import { LEASE_TOOLS } from "./leases-tools.ts";
|
|
14
|
+
import { BIDI_BROWSER_TOOLS } from "./bidi-browser-tools.ts";
|
|
13
15
|
import { extractPage } from "./tools/extract.ts";
|
|
14
16
|
|
|
15
17
|
export const FIREFOX_TOOLS: Partial<Record<ToolName, (driver: BrowserDriver, args: never) => Promise<unknown>>> = {
|
|
16
18
|
...SHARED_TOOLS,
|
|
17
19
|
...BIDI_ONLY_TOOLS,
|
|
18
20
|
...LEASE_TOOLS,
|
|
21
|
+
...BIDI_BROWSER_TOOLS,
|
|
19
22
|
extract_page: extractPage,
|
|
20
23
|
};
|
package/src/manifest.ts
CHANGED
|
@@ -622,7 +622,7 @@ export const MANIFEST: ToolSpec[] = [
|
|
|
622
622
|
},
|
|
623
623
|
{
|
|
624
624
|
"name": "dispatch_mouse",
|
|
625
|
-
"description": "Dispatch one raw mouse event at viewport coordinates;
|
|
625
|
+
"description": "Dispatch one raw mouse event at viewport coordinates; Firefox needs 160 or newer.",
|
|
626
626
|
"inputSchema": {
|
|
627
627
|
"type": "object",
|
|
628
628
|
"properties": {
|
|
@@ -779,7 +779,7 @@ export const MANIFEST: ToolSpec[] = [
|
|
|
779
779
|
},
|
|
780
780
|
{
|
|
781
781
|
"name": "grant_permissions",
|
|
782
|
-
"description": "Grant or reset browser permissions; permissions are origin-scoped
|
|
782
|
+
"description": "Grant or reset browser permissions; permissions are origin-scoped (Chrome, Firefox 160+).",
|
|
783
783
|
"inputSchema": {
|
|
784
784
|
"type": "object",
|
|
785
785
|
"properties": {
|
package/src/policy.ts
CHANGED
|
@@ -95,8 +95,8 @@ export const MUTATING_TOOLS: ReadonlySet<string> = new Set([
|
|
|
95
95
|
"dispatch_mouse",
|
|
96
96
|
"focus_emulation", // Emulation.setFocusEmulationEnabled
|
|
97
97
|
"click_focus_gated",
|
|
98
|
-
"wait_for_download", // borderline: Browser.setDownloadBehavior changes browser state
|
|
99
|
-
"grant_permissions", // Browser.grantPermissions
|
|
98
|
+
"wait_for_download", // borderline: Browser.setDownloadBehavior / BiDi browser.setDownloadBehavior changes browser state
|
|
99
|
+
"grant_permissions", // Browser.grantPermissions / BiDi permissions.setPermission
|
|
100
100
|
// leases: claim installs an activity beacon in the page and writes a lease; release can close a tab
|
|
101
101
|
"claim_page",
|
|
102
102
|
"release_page",
|
package/src/shared-tools.ts
CHANGED
|
@@ -50,6 +50,7 @@ import { newTrackedPage, originIndex, resolveLiveLabel, type PageOrigin } from "
|
|
|
50
50
|
import { isWorkerSelector, WORKER_SELECTOR_PAGE_ONLY_MESSAGE, WORKER_SELECTOR_UNSUPPORTED_MESSAGE } from "./workers.ts";
|
|
51
51
|
import { FRAME_SELECTOR_PAGE_ONLY_MESSAGE, FRAME_SELECTOR_UNSUPPORTED_MESSAGE, isFrameSelector } from "./frames.ts";
|
|
52
52
|
import { reapAllowed, reapStaleAgentTabs, type ReapedTab } from "./reap.ts";
|
|
53
|
+
import { ACCNAME_HELPERS_SOURCE, MAX_NAME_LENGTH } from "./bidi/snapshot.ts";
|
|
53
54
|
import { allEndpoints, currentEndpoint, isDefaultEndpoint, withEndpointScope } from "./endpoints.ts";
|
|
54
55
|
|
|
55
56
|
const ARTIFACT_DIR = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
|
|
@@ -908,13 +909,66 @@ export async function takeSnapshot(
|
|
|
908
909
|
|
|
909
910
|
/* ------------------------------ interaction (8) ------------------------------ */
|
|
910
911
|
|
|
912
|
+
/**
|
|
913
|
+
* In-page source that names the element `this` is, as a snapshot-style `role "name"` string
|
|
914
|
+
* (`button "Save"`, `textbox "Email"`). It reuses the snapshot walker's role/accname heuristics;
|
|
915
|
+
* an element with no role falls back to its tag, and one with no accessible name falls back to
|
|
916
|
+
* its own text, so a click on a bare `<div>` still says what it hit. Exported for the tests.
|
|
917
|
+
*/
|
|
918
|
+
export function describeElementSource(): string {
|
|
919
|
+
return `function() {
|
|
920
|
+
var MAX_NAME_LENGTH = ${MAX_NAME_LENGTH};
|
|
921
|
+
${ACCNAME_HELPERS_SOURCE}
|
|
922
|
+
var el = this;
|
|
923
|
+
if (!el || el.nodeType !== 1) return null;
|
|
924
|
+
var role = implicitRole(el);
|
|
925
|
+
var name = accessibleName(el, !!CONTENT_NAMED_ROLES[role]);
|
|
926
|
+
if (!name) name = truncate(el.innerText || el.textContent || "");
|
|
927
|
+
return (role || el.tagName.toLowerCase()) + (name ? " " + JSON.stringify(name) : "");
|
|
928
|
+
}`;
|
|
929
|
+
}
|
|
930
|
+
|
|
931
|
+
/** How long describing may delay the action it precedes before it is given up on. */
|
|
932
|
+
const DESCRIBE_TIMEOUT_MS = 2_000;
|
|
933
|
+
|
|
934
|
+
/**
|
|
935
|
+
* Best-effort `role "name"` for the element an action is about to touch, read BEFORE the action
|
|
936
|
+
* (a click can navigate or unmount its node; fill should report the label, not the new value).
|
|
937
|
+
* Never throws and never blocks past DESCRIBE_TIMEOUT_MS: a stale or unresolvable locator is left
|
|
938
|
+
* for the action itself to fail on with its usual error, and the result just omits `element`.
|
|
939
|
+
*/
|
|
940
|
+
export async function describeElement(page: PageDriver, loc: ElementLocator): Promise<string | undefined> {
|
|
941
|
+
let timer: ReturnType<typeof setTimeout> | undefined;
|
|
942
|
+
try {
|
|
943
|
+
const timeout = new Promise<undefined>((r) => { timer = setTimeout(() => r(undefined), DESCRIBE_TIMEOUT_MS); });
|
|
944
|
+
const desc = await Promise.race([page.callOnElement(loc, describeElementSource()), timeout]);
|
|
945
|
+
return typeof desc === "string" && desc.length > 0 ? desc : undefined;
|
|
946
|
+
} catch {
|
|
947
|
+
return undefined;
|
|
948
|
+
} finally {
|
|
949
|
+
clearTimeout(timer);
|
|
950
|
+
}
|
|
951
|
+
}
|
|
952
|
+
|
|
953
|
+
/** A drag destination that names an element, as opposed to a viewport point or an offset. */
|
|
954
|
+
function isElementLocator(d: DragDestination): d is ElementLocator {
|
|
955
|
+
return !("x" in d) && !("dx" in d);
|
|
956
|
+
}
|
|
957
|
+
|
|
958
|
+
/** `{ element }` when there is a description, `{}` otherwise, for spreading into a result. */
|
|
959
|
+
function elementField(element: string | undefined): { element?: string } {
|
|
960
|
+
return element === undefined ? {} : { element };
|
|
961
|
+
}
|
|
962
|
+
|
|
911
963
|
export async function click(
|
|
912
964
|
driver: BrowserDriver,
|
|
913
965
|
args: { target?: TargetSelector; uid?: DriverUid; selector?: string; button?: "left" | "right" | "middle"; clickCount?: number; modifiers?: string[] },
|
|
914
|
-
): Promise<{ clicked: true; x: number; y: number }> {
|
|
966
|
+
): Promise<{ clicked: true; element?: string; x: number; y: number }> {
|
|
967
|
+
const loc = locatorOf(args);
|
|
915
968
|
return withPage(driver, args.target, async (page) => {
|
|
916
|
-
const
|
|
917
|
-
|
|
969
|
+
const element = await describeElement(page, loc);
|
|
970
|
+
const { x, y } = await page.click(loc, { button: args.button ?? "left", clickCount: args.clickCount ?? 1, modifiers: args.modifiers });
|
|
971
|
+
return { clicked: true, ...elementField(element), x, y };
|
|
918
972
|
});
|
|
919
973
|
}
|
|
920
974
|
|
|
@@ -959,10 +1013,12 @@ export async function scroll(
|
|
|
959
1013
|
});
|
|
960
1014
|
}
|
|
961
1015
|
|
|
962
|
-
export async function hover(driver: BrowserDriver, args: { target?: TargetSelector; uid?: DriverUid; selector?: string }): Promise<{ hovered: true; x: number; y: number }> {
|
|
1016
|
+
export async function hover(driver: BrowserDriver, args: { target?: TargetSelector; uid?: DriverUid; selector?: string }): Promise<{ hovered: true; element?: string; x: number; y: number }> {
|
|
1017
|
+
const loc = locatorOf(args);
|
|
963
1018
|
return withPage(driver, args.target, async (page) => {
|
|
964
|
-
const
|
|
965
|
-
|
|
1019
|
+
const element = await describeElement(page, loc);
|
|
1020
|
+
const { x, y } = await page.hover(loc);
|
|
1021
|
+
return { hovered: true, ...elementField(element), x, y };
|
|
966
1022
|
});
|
|
967
1023
|
}
|
|
968
1024
|
|
|
@@ -1057,47 +1113,60 @@ export async function drag(
|
|
|
1057
1113
|
mode?: "mouse" | "html5";
|
|
1058
1114
|
steps?: number;
|
|
1059
1115
|
},
|
|
1060
|
-
): Promise<{ dragged: true; mode: "mouse" | "html5"; steps: number; from: { x: number; y: number }; to: { x: number; y: number } }> {
|
|
1116
|
+
): Promise<{ dragged: true; element?: string; target_element?: string; mode: "mouse" | "html5"; steps: number; from: { x: number; y: number }; to: { x: number; y: number } }> {
|
|
1061
1117
|
if (!args.from) throw new SharedToolError("drag requires { from }");
|
|
1062
1118
|
const destination = resolveDragDestination(args);
|
|
1063
1119
|
const steps = resolveDragSteps(args.steps);
|
|
1064
1120
|
// Capability check BEFORE withPage: an unsupported mode must not claim a lease or open a socket.
|
|
1065
1121
|
const mode = resolveDragMode(args.mode, driver.capabilities);
|
|
1066
1122
|
return withPage(driver, args.target, async (page) => {
|
|
1067
|
-
const
|
|
1068
|
-
|
|
1123
|
+
const fromLoc = locatorOf(args.from);
|
|
1124
|
+
const element = await describeElement(page, fromLoc);
|
|
1125
|
+
const targetElement = isElementLocator(destination) ? await describeElement(page, destination) : undefined;
|
|
1126
|
+
const { from, to } = await page.drag(fromLoc, destination, { mode, steps });
|
|
1127
|
+
return {
|
|
1128
|
+
dragged: true, ...elementField(element), ...(targetElement === undefined ? {} : { target_element: targetElement }),
|
|
1129
|
+
mode, steps, from, to,
|
|
1130
|
+
};
|
|
1069
1131
|
});
|
|
1070
1132
|
}
|
|
1071
1133
|
|
|
1072
|
-
export async function fill(driver: BrowserDriver, args: { target?: TargetSelector; uid?: DriverUid; selector?: string; value: string }): Promise<{ filled: true; value: string }> {
|
|
1134
|
+
export async function fill(driver: BrowserDriver, args: { target?: TargetSelector; uid?: DriverUid; selector?: string; value: string }): Promise<{ filled: true; element?: string; value: string }> {
|
|
1073
1135
|
if (typeof args.value !== "string") throw new SharedToolError("fill requires a string { value }");
|
|
1136
|
+
const loc = locatorOf(args);
|
|
1074
1137
|
return withPage(driver, args.target, async (page) => {
|
|
1075
|
-
await page
|
|
1076
|
-
|
|
1138
|
+
const element = await describeElement(page, loc);
|
|
1139
|
+
await page.setValue(loc, args.value);
|
|
1140
|
+
return { filled: true, ...elementField(element), value: args.value };
|
|
1077
1141
|
});
|
|
1078
1142
|
}
|
|
1079
1143
|
|
|
1080
1144
|
export async function fillForm(
|
|
1081
1145
|
driver: BrowserDriver,
|
|
1082
1146
|
args: { target?: TargetSelector; fields: Array<{ uid?: DriverUid; selector?: string; value: string }> },
|
|
1083
|
-
): Promise<{ filled: number; fields: number }> {
|
|
1147
|
+
): Promise<{ filled: number; fields: number; elements: Array<string | null> }> {
|
|
1084
1148
|
if (!Array.isArray(args.fields) || args.fields.length === 0) throw new SharedToolError("fill_form requires a non-empty { fields } array");
|
|
1085
1149
|
return withPage(driver, args.target, async (page) => {
|
|
1086
1150
|
let filled = 0;
|
|
1151
|
+
const elements: Array<string | null> = [];
|
|
1087
1152
|
for (const f of args.fields) {
|
|
1088
1153
|
if (typeof f.value !== "string") throw new SharedToolError("each fill_form field requires a string value");
|
|
1089
|
-
|
|
1154
|
+
const loc = locatorOf(f);
|
|
1155
|
+
elements.push((await describeElement(page, loc)) ?? null);
|
|
1156
|
+
await page.setValue(loc, f.value);
|
|
1090
1157
|
filled++;
|
|
1091
1158
|
}
|
|
1092
|
-
return { filled, fields: args.fields.length };
|
|
1159
|
+
return { filled, fields: args.fields.length, elements };
|
|
1093
1160
|
});
|
|
1094
1161
|
}
|
|
1095
1162
|
|
|
1096
|
-
export async function typeText(driver: BrowserDriver, args: { target?: TargetSelector; uid?: DriverUid; selector?: string; text: string }): Promise<{ typed: true; text: string }> {
|
|
1163
|
+
export async function typeText(driver: BrowserDriver, args: { target?: TargetSelector; uid?: DriverUid; selector?: string; text: string }): Promise<{ typed: true; element?: string; text: string }> {
|
|
1097
1164
|
if (typeof args.text !== "string") throw new SharedToolError("type_text requires a string { text }");
|
|
1165
|
+
const loc = locatorOf(args);
|
|
1098
1166
|
return withPage(driver, args.target, async (page) => {
|
|
1099
|
-
await page
|
|
1100
|
-
|
|
1167
|
+
const element = await describeElement(page, loc);
|
|
1168
|
+
await page.typeText(loc, args.text);
|
|
1169
|
+
return { typed: true, ...elementField(element), text: args.text };
|
|
1101
1170
|
});
|
|
1102
1171
|
}
|
|
1103
1172
|
|
|
@@ -1110,14 +1179,16 @@ export async function pressKey(driver: BrowserDriver, args: { target?: TargetSel
|
|
|
1110
1179
|
});
|
|
1111
1180
|
}
|
|
1112
1181
|
|
|
1113
|
-
export async function uploadFile(driver: BrowserDriver, args: { target?: TargetSelector; uid?: DriverUid; selector?: string; files: string | string[] }): Promise<{ uploaded: string[] }> {
|
|
1182
|
+
export async function uploadFile(driver: BrowserDriver, args: { target?: TargetSelector; uid?: DriverUid; selector?: string; files: string | string[] }): Promise<{ uploaded: string[]; element?: string }> {
|
|
1114
1183
|
const files = Array.isArray(args.files) ? args.files : [args.files];
|
|
1115
1184
|
if (!files.length || files.some((f) => typeof f !== "string" || !f.length)) {
|
|
1116
1185
|
throw new SharedToolError("upload_file requires { files } as a non-empty path or array of paths");
|
|
1117
1186
|
}
|
|
1118
1187
|
return withPage(driver, args.target, async (page) => {
|
|
1119
|
-
|
|
1120
|
-
|
|
1188
|
+
const loc = locatorOf(args);
|
|
1189
|
+
const element = await describeElement(page, loc);
|
|
1190
|
+
await page.setFiles(loc, files);
|
|
1191
|
+
return { uploaded: files, ...elementField(element) };
|
|
1121
1192
|
});
|
|
1122
1193
|
}
|
|
1123
1194
|
|
|
@@ -1136,8 +1207,9 @@ const MAX_SCREENSHOT_SCALE = 8;
|
|
|
1136
1207
|
/**
|
|
1137
1208
|
* take_screenshot's `scale`, plus the second backend gate in this file (resolveDragMode is the
|
|
1138
1209
|
* first, and this follows its shape exactly). scale needs Capability "screenshot.scale", which
|
|
1139
|
-
*
|
|
1140
|
-
*
|
|
1210
|
+
* Chrome declares (Page.captureScreenshot takes a per-call clip.scale) and Firefox >= 160 declares
|
|
1211
|
+
* too (a one-capture devicePixelRatio override; captureScreenshot itself has no scale parameter, and
|
|
1212
|
+
* an older Firefox's driver refuses with "unsupported" from requireFirefox). Per ADR-001
|
|
1141
1213
|
* this is a PARAM-level gap, not a whole-tool one — take_screenshot stays in tools/list on Firefox
|
|
1142
1214
|
* because every other argument works there, and asking for a scale on Firefox is a clear
|
|
1143
1215
|
* validation error, never a silent 1x capture that would return an image the caller never asked
|
|
@@ -1150,7 +1222,7 @@ export function resolveScreenshotScale(scale: number | undefined, capabilities:
|
|
|
1150
1222
|
}
|
|
1151
1223
|
if (scale !== 1 && !capabilities.has("screenshot.scale")) {
|
|
1152
1224
|
throw new SharedToolError(
|
|
1153
|
-
"take_screenshot: 'scale' is not supported by this backend (
|
|
1225
|
+
"take_screenshot: 'scale' is not supported by this backend (no per-capture scale primitive). " +
|
|
1154
1226
|
`Call emulate with deviceScaleFactor:${scale} first and capture at scale 1, or use --browser chrome for a per-capture scale.`,
|
|
1155
1227
|
);
|
|
1156
1228
|
}
|
package/src/toolDocs.ts
CHANGED
|
@@ -118,7 +118,7 @@ export const TOOL_DOCS: Record<string, ToolDoc> = {
|
|
|
118
118
|
}
|
|
119
119
|
},
|
|
120
120
|
"click": {
|
|
121
|
-
"description": "Click an element via a synthetic mouse press/release at its scrolled-into-view center. Give exactly one of uid or selector. modifiers (Alt/Control/Meta/Shift) throws on the Firefox backend — use --browser chrome for a modifier-click. clickCount:3 triple-clicks (selects a line/paragraph in most editors).",
|
|
121
|
+
"description": "Click an element via a synthetic mouse press/release at its scrolled-into-view center. Give exactly one of uid or selector. modifiers (Alt/Control/Meta/Shift) throws on the Firefox backend — use --browser chrome for a modifier-click. clickCount:3 triple-clicks (selects a line/paragraph in most editors). Returns {clicked,element,x,y}; element names what was hit, snapshot-style (button \"Save\"), read before the click and omitted if it cannot be read.",
|
|
122
122
|
"params": {
|
|
123
123
|
"lease": "Lease token from claim_page. Omit for a tab this process holds; required for a tab held by another process or one claimed explicitly. Auto-acquired under CDP_REQUIRE_LEASE (then pass target, not lease). See server instructions.",
|
|
124
124
|
"target": "Page selector: 'active' (default), 'index:N', 'url:<substr>', 'title:<substr>', 'label:<name>', or a 32-hex '<targetId>'. Prefix any of these with 'endpoint:<name>/' for a named CDP endpoint (Chrome only). Grammar: see server instructions.",
|
|
@@ -164,7 +164,7 @@ export const TOOL_DOCS: Record<string, ToolDoc> = {
|
|
|
164
164
|
}
|
|
165
165
|
},
|
|
166
166
|
"dispatch_mouse": {
|
|
167
|
-
"description": "Dispatches one raw mouse event (move/down/up) at absolute viewport coordinates — the toolkit's lowest-level input primitive. Compose move/down/move/up calls yourself for anything click/drag's fixed sequences can't reach: canvas drag-painting, marquee/rubber-band selection, custom hit-testing widgets. Chrome
|
|
167
|
+
"description": "Dispatches one raw mouse event (move/down/up) at absolute viewport coordinates — the toolkit's lowest-level input primitive. Compose move/down/move/up calls yourself for anything click/drag's fixed sequences can't reach: canvas drag-painting, marquee/rubber-band selection, custom hit-testing widgets. Works on Chrome and on Firefox 160 or newer (WebDriver BiDi: a press held by 'down' in one call is released by 'up' in a later call); an older Firefox gets an unsupported error naming the version.",
|
|
168
168
|
"params": {
|
|
169
169
|
"lease": "Lease token from claim_page. Omit for a tab this process holds; required for a tab held by another process or one claimed explicitly. Auto-acquired under CDP_REQUIRE_LEASE (then pass target, not lease). See server instructions.",
|
|
170
170
|
"target": "Page selector: 'active' (default), 'index:N', 'url:<substr>', 'title:<substr>', 'label:<name>', or a 32-hex '<targetId>'. Prefix any of these with 'endpoint:<name>/' for a named CDP endpoint (Chrome only). Grammar: see server instructions.",
|
|
@@ -172,7 +172,7 @@ export const TOOL_DOCS: Record<string, ToolDoc> = {
|
|
|
172
172
|
"x": "Viewport x-coordinate. Required every call — CDP has no 'current pointer position' to default from.",
|
|
173
173
|
"y": "Viewport y-coordinate. Required every call.",
|
|
174
174
|
"button": "Mouse button: 'left' (default), 'right', or 'middle'.",
|
|
175
|
-
"clickCount": "Click-run length for a 'down' or 'up' event (2 = second half of a double-click, 3 = triple-click). Ignored for 'move'; defaults to 1.",
|
|
175
|
+
"clickCount": "Click-run length for a 'down' or 'up' event (2 = second half of a double-click, 3 = triple-click). Ignored for 'move'; defaults to 1. Ignored on Firefox (click counts follow native timing).",
|
|
176
176
|
"modifiers": "Modifier keys held for this one event, e.g. ['Shift']."
|
|
177
177
|
}
|
|
178
178
|
},
|
|
@@ -197,7 +197,7 @@ export const TOOL_DOCS: Record<string, ToolDoc> = {
|
|
|
197
197
|
}
|
|
198
198
|
},
|
|
199
199
|
"wait_for_download": {
|
|
200
|
-
"description": "Wait for a file download to finish and return it as a real file on disk: {path,suggestedFilename,bytes,url,target}, written under the artifact dir's downloads/. ORDERING RULE, not optional: capture must be ARMED BEFORE the click that starts the download — call wait_for_download{arm:true} first (returns {armed:true,downloadPath,pending}), then click, then call again to collect the file. The download-behavior override is per-connection state Chrome REVERTS the moment the arming client disconnects, and an unarmed headless Chrome denies the download outright, so one triggered before arming is lost. SIDE EFFECT, browser-global: arming redirects EVERY download in this browser (all tabs, all origins) into the toolkit's downloads dir until this server exits — they no longer land in the user's normal Downloads folder. The arm lives on a connection this server holds open (an MCP-server capability): under the one-shot CLI the connection dies with the process and nothing is captured.
|
|
200
|
+
"description": "Wait for a file download to finish and return it as a real file on disk: {path,suggestedFilename,bytes,url,target}, written under the artifact dir's downloads/. ORDERING RULE, not optional: capture must be ARMED BEFORE the click that starts the download — call wait_for_download{arm:true} first (returns {armed:true,downloadPath,pending}), then click, then call again to collect the file. The download-behavior override is per-connection state Chrome REVERTS the moment the arming client disconnects, and an unarmed headless Chrome denies the download outright, so one triggered before arming is lost. SIDE EFFECT, browser-global: arming redirects EVERY download in this browser (all tabs, all origins) into the toolkit's downloads dir until this server exits — they no longer land in the user's normal Downloads folder. The arm lives on a connection this server holds open (an MCP-server capability): under the one-shot CLI the connection dies with the process and nothing is captured. Capability 'browser.downloads': Chrome, and Firefox 160+ (an older Firefox is refused as unsupported). FIREFOX DIFFERS: every call arms, and a collecting call (no arm:true) RESTORES Firefox's normal download behavior when it returns or times out, so arm again before every later download.",
|
|
201
201
|
"params": {
|
|
202
202
|
"lease": "Lease token from claim_page. Omit for a tab this process holds; required for a tab held by another process or one claimed explicitly. Auto-acquired under CDP_REQUIRE_LEASE (then pass target, not lease). See server instructions.",
|
|
203
203
|
"target": "Names the tab for the lease check and the echoed target — a download is browser-scoped, so this does not pick which download is returned. Grammar: server instructions.",
|
|
@@ -206,7 +206,7 @@ export const TOOL_DOCS: Record<string, ToolDoc> = {
|
|
|
206
206
|
}
|
|
207
207
|
},
|
|
208
208
|
"grant_permissions": {
|
|
209
|
-
"description": "Grant browser permissions for an origin up front, so a page asking for geolocation / notifications / clipboard gets an answer instead of a prompt no agent can click. 'permissions' takes CDP PermissionType values ('geolocation','notifications','clipboardReadWrite','camera',...); an unknown name is refused by Chrome, quoting the bad value. Returns {granted,origin,target}, or {reset:true,target} for a reset-only call. Grants are keyed by ORIGIN, not by tab: every tab on that origin is affected, including ones opened later. reset:true clears this server's previous grants first (or instead, when no permissions are given) — CDP's reset is not origin-scoped, so it clears them for every origin at once. The grant lives on a connection this server holds open and Chrome DISCARDS IT when that connection closes: an MCP-server capability, so under the one-shot CLI the grant dies with the process.
|
|
209
|
+
"description": "Grant browser permissions for an origin up front, so a page asking for geolocation / notifications / clipboard gets an answer instead of a prompt no agent can click. 'permissions' takes CDP PermissionType values ('geolocation','notifications','clipboardReadWrite','camera',...); an unknown name is refused by Chrome, quoting the bad value. Returns {granted,origin,target}, or {reset:true,target} for a reset-only call. Grants are keyed by ORIGIN, not by tab: every tab on that origin is affected, including ones opened later. reset:true clears this server's previous grants first (or instead, when no permissions are given) — CDP's reset is not origin-scoped, so it clears them for every origin at once. The grant lives on a connection this server holds open and Chrome DISCARDS IT when that connection closes: an MCP-server capability, so under the one-shot CLI the grant dies with the process. Capability 'browser.permissions': Chrome, and Firefox 160+ (an older Firefox is refused as unsupported). FIREFOX DIFFERS: only geolocation, notifications, audioCapture, videoCapture, durableStorage, midi, midiSysex, wakeLockScreen map to a Firefox permission (any other name, e.g. clipboardReadWrite, is refused as unsupported); Firefox stores grants in the profile, so this server undoes them on reset:true and at shutdown (back to the state the page reported before the grant, or 'prompt' for another origin).",
|
|
210
210
|
"params": {
|
|
211
211
|
"lease": "Lease token from claim_page. Omit for a tab this process holds; required for a tab held by another process or one claimed explicitly. Auto-acquired under CDP_REQUIRE_LEASE (then pass target, not lease). See server instructions.",
|
|
212
212
|
"target": "Also the origin source when 'origin' is omitted. Grammar: server instructions.",
|
|
@@ -216,7 +216,7 @@ export const TOOL_DOCS: Record<string, ToolDoc> = {
|
|
|
216
216
|
}
|
|
217
217
|
},
|
|
218
218
|
"fill": {
|
|
219
|
-
"description": "Fills an element by focusing it, clearing existing content, then inserting value via Input.insertText (atomic paste-like commit, not per-character keystrokes — won't fire per-keypress handlers). Give exactly one of uid or selector.",
|
|
219
|
+
"description": "Fills an element by focusing it, clearing existing content, then inserting value via Input.insertText (atomic paste-like commit, not per-character keystrokes — won't fire per-keypress handlers). Give exactly one of uid or selector. Returns {filled,element,value}; element names the field (textbox \"Email\").",
|
|
220
220
|
"params": {
|
|
221
221
|
"lease": "Lease token from claim_page. Omit for a tab this process holds; required for a tab held by another process or one claimed explicitly. Auto-acquired under CDP_REQUIRE_LEASE (then pass target, not lease). See server instructions.",
|
|
222
222
|
"target": "Page selector: 'active' (default), 'index:N', 'url:<substr>', 'title:<substr>', 'label:<name>', or a 32-hex '<targetId>'. Prefix any of these with 'endpoint:<name>/' for a named CDP endpoint (Chrome only). Grammar: see server instructions.",
|
|
@@ -270,7 +270,7 @@ export const TOOL_DOCS: Record<string, ToolDoc> = {
|
|
|
270
270
|
"format": "Image format, default png. quality applies only to jpeg.",
|
|
271
271
|
"quality": "JPEG quality 0-100, default 80; ignored for png.",
|
|
272
272
|
"fullPage": "Capture the full scrollable height (via Page.getLayoutMetrics), not just the viewport.",
|
|
273
|
-
"scale": "Output-pixel multiplier for this capture only (0<scale<=8, default 1): output px = ceil(css px x scale x devicePixelRatio); the page is never told anything changed.
|
|
273
|
+
"scale": "Output-pixel multiplier for this capture only (0<scale<=8, default 1): output px = ceil(css px x scale x devicePixelRatio); the page is never told anything changed. Needs capability screenshot.scale: Chrome, and Firefox 160 or newer (an older Firefox: emulate{deviceScaleFactor} then scale:1). A projection over 16384 device px/side is refused up front, naming the largest scale that fits.",
|
|
274
274
|
"renderWidth": "Emulates this viewport width (CSS px, 1-16384) for one capture, then restores it. Required with renderHeight. Unlike scale, this changes what the page believes (media queries re-flow) — e.g. capture a responsive page at 1920x1080 from a differently-sized tab. Restore only works for an override this toolkit itself set; check result.renderRestored (false = still emulated, fix via emulate). Works on both backends (capability screenshot.renderSize).",
|
|
275
275
|
"renderHeight": "Emulates this viewport height (CSS px, 1-16384) for one capture. Required with renderWidth — a viewport is two numbers. A narrow renderWidth often reflows pages TALLER, which is the usual way a render-size capture trips the 16384px encode limit.",
|
|
276
276
|
"tile": "Whether to allow vertical-band stitching: omitted=AUTO (band only if a single shot wouldn't fit), false=never band (refuse instead), true=always band (Chrome-only capability). Banded output is PNG-only, can't returnBase64, and only bands on HEIGHT (oversized WIDTH is refused, not split). Bands are a faithful crop, but lazy/virtualized content the real viewport never scrolled to renders blank.",
|
|
@@ -1,7 +1,12 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* dispatch-mouse.ts: `dispatch_mouse` over raw CDP, the toolkit's raw mouse-event primitive.
|
|
3
3
|
*
|
|
4
|
-
*
|
|
4
|
+
* UPDATE: Firefox 160+ now serves dispatch_mouse too (bidi-tools.ts's dispatchMouse over
|
|
5
|
+
* PageDriver.dispatchMouse; same schema and validator from this file). The text below is why THIS
|
|
6
|
+
* module, the Chrome path, stays a raw-CDP tool; its "Chrome-only" and "absent under firefox"
|
|
7
|
+
* statements describe the state before Firefox 160 was measured.
|
|
8
|
+
*
|
|
9
|
+
* WHY THIS IS A STANDALONE CHROME MODULE (capability "input.raw", declared in ../driver.ts /
|
|
5
10
|
* ../cdp/driver.ts), NOT a PageDriver method
|
|
6
11
|
* ============================================================================
|
|
7
12
|
* Every other interaction (click/hover/drag/scroll) is a Driver-neutral, multi-event SEQUENCE:
|
package/src/tools/downloads.ts
CHANGED
|
@@ -2,16 +2,15 @@
|
|
|
2
2
|
* downloads.ts: `wait_for_download` — block until a file download finishes, then hand back a real
|
|
3
3
|
* path on disk with the page's own filename (1.8.0 Track P3).
|
|
4
4
|
*
|
|
5
|
-
* WHY THIS IS
|
|
6
|
-
*
|
|
5
|
+
* WHY THIS IS RAW CDP (capability "browser.downloads"), NOT a PageDriver method
|
|
6
|
+
* ============================================================================
|
|
7
7
|
* A download is browser-scoped, not page-scoped: Browser.setDownloadBehavior, Browser.downloadWillBegin
|
|
8
8
|
* and Browser.downloadProgress all live on the CDP browser endpoint, and the download a caller
|
|
9
9
|
* cares about may be started by a click in one tab and finish while another is focused. There is no
|
|
10
10
|
* page handle to hang it off, so it stays out of the Driver interface entirely, exactly like
|
|
11
|
-
* dispatch-mouse.ts and screencast.ts.
|
|
12
|
-
*
|
|
13
|
-
*
|
|
14
|
-
* from tools/list under --browser firefox rather than present and throwing.
|
|
11
|
+
* dispatch-mouse.ts and screencast.ts. This is the CHROME implementation. Firefox 160 added
|
|
12
|
+
* BiDi's browser.setDownloadBehavior, so the Firefox backend has its own implementation in
|
|
13
|
+
* src/bidi-browser-tools.ts, reusing this file's validator, safeFilename and nextFreeName.
|
|
15
14
|
*
|
|
16
15
|
* THE ORDERING RULE, and why it is a rule rather than a wart
|
|
17
16
|
* ---------------------------------------------------------
|
package/src/tools/evaluate.ts
CHANGED
|
@@ -15,7 +15,7 @@
|
|
|
15
15
|
* `CdpError` carrying the exception/description text.
|
|
16
16
|
*/
|
|
17
17
|
import { CdpError, withPage } from "../client.ts";
|
|
18
|
-
import type {
|
|
18
|
+
import type { PageConnection } from "../client.ts";
|
|
19
19
|
import type { TargetSelector } from "../types.ts";
|
|
20
20
|
|
|
21
21
|
/** A CDP RemoteObject as returned by Runtime.evaluate / Runtime.callFunctionOn. */
|
|
@@ -78,7 +78,7 @@ function unwrap(obj: RemoteObject): unknown {
|
|
|
78
78
|
return obj.description ?? null;
|
|
79
79
|
}
|
|
80
80
|
|
|
81
|
-
async function evaluateExpression(conn:
|
|
81
|
+
async function evaluateExpression(conn: PageConnection, expression: string, awaitPromise: boolean): Promise<unknown> {
|
|
82
82
|
const res = await conn.send<EvalResponse>("Runtime.evaluate", {
|
|
83
83
|
expression,
|
|
84
84
|
returnByValue: true,
|
|
@@ -94,7 +94,7 @@ async function evaluateExpression(conn: CdpConnection, expression: string, await
|
|
|
94
94
|
}
|
|
95
95
|
|
|
96
96
|
async function evaluateFunction(
|
|
97
|
-
conn:
|
|
97
|
+
conn: PageConnection,
|
|
98
98
|
expression: string,
|
|
99
99
|
awaitPromise: boolean,
|
|
100
100
|
args: unknown[],
|
package/src/tools/navigation.ts
CHANGED
|
@@ -12,7 +12,7 @@
|
|
|
12
12
|
* on a fixed interval until the text appears or the timeout elapses.
|
|
13
13
|
*/
|
|
14
14
|
import { CdpError, withPage } from "../client.ts";
|
|
15
|
-
import type {
|
|
15
|
+
import type { PageConnection } from "../client.ts";
|
|
16
16
|
import type { Target, TargetSelector } from "../types.ts";
|
|
17
17
|
|
|
18
18
|
export interface NavigatePageArgs {
|
|
@@ -65,7 +65,7 @@ export async function navigatePage(args: NavigatePageArgs): Promise<NavigatePage
|
|
|
65
65
|
|
|
66
66
|
return withPage(
|
|
67
67
|
args.target,
|
|
68
|
-
async (conn:
|
|
68
|
+
async (conn: PageConnection): Promise<NavigatePageResult> => {
|
|
69
69
|
await conn.send("Page.enable");
|
|
70
70
|
|
|
71
71
|
// Subscribe to the load milestone BEFORE acting so a fast page that loads
|
|
@@ -156,7 +156,7 @@ export async function waitForText(args: WaitForArgs): Promise<WaitForResult> {
|
|
|
156
156
|
|
|
157
157
|
return withPage(
|
|
158
158
|
args.target,
|
|
159
|
-
async (conn:
|
|
159
|
+
async (conn: PageConnection, _target: Target): Promise<WaitForResult> => {
|
|
160
160
|
await conn.send("Runtime.enable");
|
|
161
161
|
const expr = `(() => { const b = document.body; return !!b && typeof b.innerText === 'string' && b.innerText.includes(${JSON.stringify(args.text)}); })()`;
|
|
162
162
|
|
|
@@ -11,7 +11,7 @@
|
|
|
11
11
|
* CDP connection per target; integration-tested in test/mock-smoke.ts.
|
|
12
12
|
*/
|
|
13
13
|
import { CdpError, openPage, resolveTarget } from "../client.ts";
|
|
14
|
-
import type {
|
|
14
|
+
import type { PageConnection } from "../client.ts";
|
|
15
15
|
import type { Target, TargetSelector } from "../types.ts";
|
|
16
16
|
|
|
17
17
|
/* ============================================================================
|
|
@@ -143,7 +143,7 @@ interface MockRule {
|
|
|
143
143
|
}
|
|
144
144
|
|
|
145
145
|
interface MockSession {
|
|
146
|
-
conn:
|
|
146
|
+
conn: PageConnection;
|
|
147
147
|
target: Target;
|
|
148
148
|
rules: MockRule[];
|
|
149
149
|
intercepted: Array<{ url: string; method: string; action: MockAction }>;
|
package/src/tools/performance.ts
CHANGED
|
@@ -35,7 +35,7 @@
|
|
|
35
35
|
* path and the recommended entry point.
|
|
36
36
|
*/
|
|
37
37
|
import type { Target, TargetSelector } from "../types.ts";
|
|
38
|
-
import type {
|
|
38
|
+
import type { PageConnection } from "../client.ts";
|
|
39
39
|
import { CdpError, openPage } from "../client.ts";
|
|
40
40
|
import { mkdir, readFile, writeFile, stat, unlink } from "node:fs/promises";
|
|
41
41
|
import { join } from "node:path";
|
|
@@ -75,7 +75,7 @@ interface TraceEvent {
|
|
|
75
75
|
|
|
76
76
|
/** A traced-page registry entry held in-process between start and stop. */
|
|
77
77
|
interface LiveTrace {
|
|
78
|
-
conn:
|
|
78
|
+
conn: PageConnection;
|
|
79
79
|
target: Target;
|
|
80
80
|
events: TraceEvent[];
|
|
81
81
|
startedAt: number;
|
|
@@ -108,7 +108,7 @@ function stateFilePath(): string {
|
|
|
108
108
|
}
|
|
109
109
|
|
|
110
110
|
/** Subscribe to Tracing.dataCollected and buffer every event into `sink`. */
|
|
111
|
-
function bufferTraceData(conn:
|
|
111
|
+
function bufferTraceData(conn: PageConnection, sink: TraceEvent[]): () => void {
|
|
112
112
|
return conn.on("Tracing.dataCollected", (params: Record<string, unknown>) => {
|
|
113
113
|
const value = (params as { value?: TraceEvent[] }).value;
|
|
114
114
|
if (Array.isArray(value)) sink.push(...value);
|
|
@@ -116,7 +116,7 @@ function bufferTraceData(conn: CdpConnection, sink: TraceEvent[]): () => void {
|
|
|
116
116
|
}
|
|
117
117
|
|
|
118
118
|
/** Begin a trace on an already-open page connection. */
|
|
119
|
-
async function beginTrace(conn:
|
|
119
|
+
async function beginTrace(conn: PageConnection, categories: string[]): Promise<void> {
|
|
120
120
|
await conn.send("Tracing.start", {
|
|
121
121
|
traceConfig: { includedCategories: categories },
|
|
122
122
|
transferMode: "ReportEvents",
|
|
@@ -127,7 +127,7 @@ async function beginTrace(conn: CdpConnection, categories: string[]): Promise<vo
|
|
|
127
127
|
* End a trace, drain all buffered Tracing.dataCollected, and resolve once
|
|
128
128
|
* Tracing.tracingComplete fires (or the timeout elapses). Returns the events.
|
|
129
129
|
*/
|
|
130
|
-
async function endTrace(conn:
|
|
130
|
+
async function endTrace(conn: PageConnection, sink: TraceEvent[], timeoutMs = 30_000): Promise<TraceEvent[]> {
|
|
131
131
|
const complete = conn.waitFor("Tracing.tracingComplete", undefined, timeoutMs);
|
|
132
132
|
await conn.send("Tracing.end");
|
|
133
133
|
await complete;
|
package/src/tools/permissions.ts
CHANGED
|
@@ -3,14 +3,14 @@
|
|
|
3
3
|
* that asks for geolocation / notifications / clipboard gets a decision instead of a modal an
|
|
4
4
|
* agent cannot click (1.8.0 Track P3).
|
|
5
5
|
*
|
|
6
|
-
* WHY THIS IS
|
|
7
|
-
*
|
|
6
|
+
* WHY THIS IS RAW CDP (capability "browser.permissions"), NOT a PageDriver method
|
|
7
|
+
* ==============================================================================
|
|
8
8
|
* Browser.grantPermissions and Browser.resetPermissions are browser-endpoint commands keyed by
|
|
9
9
|
* ORIGIN, not by tab: a grant made "for" one tab applies to every tab on that origin, including
|
|
10
10
|
* ones opened later. There is no page-scoped concept to put on the Driver interface, so this stays
|
|
11
|
-
* a raw-CDP module like dispatch-mouse.ts.
|
|
12
|
-
*
|
|
13
|
-
*
|
|
11
|
+
* a raw-CDP module like dispatch-mouse.ts. This is the CHROME implementation; the Firefox 160+ one
|
|
12
|
+
* (BiDi permissions.setPermission, with a Chrome-name -> W3C-descriptor map and its asymmetries
|
|
13
|
+
* documented) is src/bidi-browser-tools.ts, reusing this file's validator and originOf.
|
|
14
14
|
*
|
|
15
15
|
* THE STANDING-CONNECTION REQUIREMENT (measured, not assumed)
|
|
16
16
|
* ----------------------------------------------------------
|
package/src/tools/recorder.ts
CHANGED
|
@@ -66,7 +66,7 @@
|
|
|
66
66
|
*/
|
|
67
67
|
import { mkdir, appendFile, writeFile, copyFile } from "node:fs/promises";
|
|
68
68
|
import { CdpError, listTargets, openPage, resolveTarget } from "../client.ts";
|
|
69
|
-
import type {
|
|
69
|
+
import type { PageConnection } from "../client.ts";
|
|
70
70
|
import { resolveWorkerSelector } from "../cdp/workers.ts";
|
|
71
71
|
import type { Target, TargetSelector } from "../types.ts";
|
|
72
72
|
import {
|
|
@@ -189,7 +189,7 @@ export interface RecorderHandle {
|
|
|
189
189
|
/** The resolved target this recorder is attached to. */
|
|
190
190
|
target: Target;
|
|
191
191
|
/** The live connection (exposed so a one-shot caller can drive Page.reload on it). */
|
|
192
|
-
conn:
|
|
192
|
+
conn: PageConnection;
|
|
193
193
|
/** Count of buffer-write failures observed (0 on a healthy capture). */
|
|
194
194
|
droppedWrites(): number;
|
|
195
195
|
}
|
|
@@ -286,7 +286,7 @@ export interface CaptureWindow {
|
|
|
286
286
|
/** The unique per-capture buffer file (read this for isolated results). */
|
|
287
287
|
file: string;
|
|
288
288
|
/** Live connection (open until stop), for Network.getResponseBody etc. */
|
|
289
|
-
conn:
|
|
289
|
+
conn: PageConnection;
|
|
290
290
|
/** Resolved target identity. */
|
|
291
291
|
resolved: { id: string; url: string; title: string };
|
|
292
292
|
/** How the window was driven: "reload" for a page, "listen" for a worker. */
|