cdp-toolkit 3.2.0 → 3.4.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 +31 -0
- package/CONTRACT.md +1 -1
- package/README.md +35 -19
- package/dist/bidi/mux-daemon.js +263 -24
- package/dist/cli.js +633 -80
- package/dist/index.js +144 -38
- package/dist/mcp.js +641 -85
- package/package.json +1 -1
- package/src/bidi/driver.ts +367 -60
- package/src/bidi/protocol.ts +27 -9
- package/src/bidi-browser-tools.ts +366 -0
- package/src/bidi-tools.ts +29 -2
- package/src/cdp/driver.ts +119 -18
- package/src/driver.ts +42 -10
- package/src/firefox-tools.ts +6 -3
- package/src/frontApp.ts +62 -0
- package/src/leases-tools.ts +3 -2
- package/src/manifest.ts +17 -5
- package/src/origins.ts +3 -2
- package/src/policy.ts +4 -3
- package/src/shared-tools.ts +47 -24
- package/src/toolDocs.ts +18 -15
- package/src/tools/dispatch-mouse.ts +6 -1
- package/src/tools/downloads.ts +5 -6
- package/src/tools/permissions.ts +5 -5
- package/src/version.ts +1 -1
package/src/shared-tools.ts
CHANGED
|
@@ -36,7 +36,7 @@
|
|
|
36
36
|
import { mkdir, writeFile } from "node:fs/promises";
|
|
37
37
|
import { dirname, join } from "node:path";
|
|
38
38
|
import type {
|
|
39
|
-
BandedCapture, BrowserCookie, BrowserDriver, Capability, DragDestination, DriverUid, ElementLocator, NavigateResult, PageDriver, PageInfo, SnapshotNode,
|
|
39
|
+
BandedCapture, BrowserCookie, BrowserDriver, Capability, DragDestination, DriverUid, ElementLocator, NavigateResult, PageDriver, PageInfo, SnapshotNode, TextInputPath,
|
|
40
40
|
} from "./driver.ts";
|
|
41
41
|
import { isTiledCapture } from "./driver.ts";
|
|
42
42
|
import { stitchPngBandsToFile } from "./png.ts";
|
|
@@ -54,7 +54,6 @@ import { ACCNAME_HELPERS_SOURCE, MAX_NAME_LENGTH } from "./bidi/snapshot.ts";
|
|
|
54
54
|
import { allEndpoints, currentEndpoint, isDefaultEndpoint, withEndpointScope } from "./endpoints.ts";
|
|
55
55
|
|
|
56
56
|
const ARTIFACT_DIR = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
|
|
57
|
-
const STATE_DIR = process.env.CDP_STATE_DIR ?? "/tmp/cdp-toolkit";
|
|
58
57
|
|
|
59
58
|
class SharedToolError extends Error {}
|
|
60
59
|
|
|
@@ -402,12 +401,12 @@ async function listPagesOne(
|
|
|
402
401
|
|
|
403
402
|
export async function newPage(
|
|
404
403
|
driver: BrowserDriver,
|
|
405
|
-
args: { url?: string; claim?: boolean; label?: string; ttlMs?: number } = {},
|
|
404
|
+
args: { url?: string; claim?: boolean; label?: string; ttlMs?: number; focus?: boolean } = {},
|
|
406
405
|
): Promise<{ targetId: string; url: string; lease?: LeaseToken; label?: string; expiresAt?: number }> {
|
|
407
406
|
const label = typeof args.label === "string" && args.label.length ? args.label : defaultLabel();
|
|
408
407
|
// Creates the tab AND writes its creation record. The record outlives any
|
|
409
408
|
// lease taken below, which is the point: a released tab is still an agent's.
|
|
410
|
-
const p = await newTrackedPage(driver, backendOf(driver), { url: args.url, label });
|
|
409
|
+
const p = await newTrackedPage(driver, backendOf(driver), { url: args.url, label, focus: args.focus === true });
|
|
411
410
|
// Under strict mode a tab nobody holds is a tab nobody may drive, so creating
|
|
412
411
|
// one without claiming it would hand back a target the very next call has to
|
|
413
412
|
// auto-acquire anyway. Doing it here means the tab is never briefly unowned
|
|
@@ -454,16 +453,24 @@ export async function closePage(
|
|
|
454
453
|
}
|
|
455
454
|
|
|
456
455
|
async function writeSelectedFile(id: string): Promise<void> {
|
|
457
|
-
|
|
458
|
-
|
|
456
|
+
// Read per call, not at import, so a test can point CDP_STATE_DIR at a temp dir.
|
|
457
|
+
const stateDir = process.env.CDP_STATE_DIR ?? "/tmp/cdp-toolkit";
|
|
458
|
+
await mkdir(stateDir, { recursive: true });
|
|
459
|
+
await writeFile(join(stateDir, "selected"), id, "utf8");
|
|
459
460
|
}
|
|
460
461
|
|
|
461
|
-
|
|
462
|
+
/**
|
|
463
|
+
* Persist the selection; raise the tab only on an explicit focus:true. Raising
|
|
464
|
+
* (Target.activateTarget / browsingContext.activate) switches the user's visible
|
|
465
|
+
* tab and takes window focus, so it is never a side effect of selecting.
|
|
466
|
+
* resolvePage already ran the lease gate, so skipping activatePage loses no check.
|
|
467
|
+
*/
|
|
468
|
+
export async function selectPage(driver: BrowserDriver, args: { target?: TargetSelector; focus?: boolean }): Promise<{ selected: string; focused: boolean }> {
|
|
462
469
|
if (args.target === undefined || args.target === "") throw new SharedToolError("select_page requires an explicit target");
|
|
463
470
|
const p = await resolvePage(driver, args.target);
|
|
464
|
-
const
|
|
465
|
-
await writeSelectedFile(
|
|
466
|
-
return { selected:
|
|
471
|
+
const id = args.focus === true ? (await driver.activatePage(p.id)).id : p.id;
|
|
472
|
+
await writeSelectedFile(id);
|
|
473
|
+
return { selected: id, focused: args.focus === true };
|
|
467
474
|
}
|
|
468
475
|
|
|
469
476
|
/* ------------------------------ navigation (2) ------------------------------ */
|
|
@@ -1131,50 +1138,65 @@ export async function drag(
|
|
|
1131
1138
|
});
|
|
1132
1139
|
}
|
|
1133
1140
|
|
|
1134
|
-
|
|
1141
|
+
/** `inputPath` rides a result only when the commit did NOT go the trusted way (a background tab's
|
|
1142
|
+
* in-page fallback, or a skipped non-text element), so the common foreground shape is unchanged. */
|
|
1143
|
+
function inputPathField(path: void | TextInputPath): { inputPath?: TextInputPath } {
|
|
1144
|
+
return path && path !== "trusted" ? { inputPath: path } : {};
|
|
1145
|
+
}
|
|
1146
|
+
|
|
1147
|
+
export async function fill(driver: BrowserDriver, args: { target?: TargetSelector; uid?: DriverUid; selector?: string; value: string }): Promise<{ filled: true; element?: string; value: string; inputPath?: TextInputPath }> {
|
|
1135
1148
|
if (typeof args.value !== "string") throw new SharedToolError("fill requires a string { value }");
|
|
1136
1149
|
const loc = locatorOf(args);
|
|
1137
1150
|
return withPage(driver, args.target, async (page) => {
|
|
1138
1151
|
const element = await describeElement(page, loc);
|
|
1139
|
-
await page.setValue(loc, args.value);
|
|
1140
|
-
return { filled: true, ...elementField(element), value: args.value };
|
|
1152
|
+
const path = await page.setValue(loc, args.value);
|
|
1153
|
+
return { filled: true, ...elementField(element), value: args.value, ...inputPathField(path) };
|
|
1141
1154
|
});
|
|
1142
1155
|
}
|
|
1143
1156
|
|
|
1144
1157
|
export async function fillForm(
|
|
1145
1158
|
driver: BrowserDriver,
|
|
1146
1159
|
args: { target?: TargetSelector; fields: Array<{ uid?: DriverUid; selector?: string; value: string }> },
|
|
1147
|
-
): Promise<{ filled: number; fields: number; elements: Array<string | null
|
|
1160
|
+
): Promise<{ filled: number; fields: number; elements: Array<string | null>; inputPaths?: TextInputPath[] }> {
|
|
1148
1161
|
if (!Array.isArray(args.fields) || args.fields.length === 0) throw new SharedToolError("fill_form requires a non-empty { fields } array");
|
|
1149
1162
|
return withPage(driver, args.target, async (page) => {
|
|
1150
1163
|
let filled = 0;
|
|
1151
1164
|
const elements: Array<string | null> = [];
|
|
1165
|
+
const paths: TextInputPath[] = [];
|
|
1152
1166
|
for (const f of args.fields) {
|
|
1153
1167
|
if (typeof f.value !== "string") throw new SharedToolError("each fill_form field requires a string value");
|
|
1154
1168
|
const loc = locatorOf(f);
|
|
1155
1169
|
elements.push((await describeElement(page, loc)) ?? null);
|
|
1156
|
-
await page.setValue(loc, f.value);
|
|
1170
|
+
paths.push((await page.setValue(loc, f.value)) || "trusted");
|
|
1157
1171
|
filled++;
|
|
1158
1172
|
}
|
|
1159
|
-
|
|
1173
|
+
// Per field, in order, and only when some field went a non-trusted way.
|
|
1174
|
+
return { filled, fields: args.fields.length, elements, ...(paths.some((p) => p !== "trusted") ? { inputPaths: paths } : {}) };
|
|
1160
1175
|
});
|
|
1161
1176
|
}
|
|
1162
1177
|
|
|
1163
|
-
export async function typeText(driver: BrowserDriver, args: { target?: TargetSelector; uid?: DriverUid; selector?: string; text: string }): Promise<{ typed: true; element?: string; text: string }> {
|
|
1178
|
+
export async function typeText(driver: BrowserDriver, args: { target?: TargetSelector; uid?: DriverUid; selector?: string; text: string }): Promise<{ typed: true; element?: string; text: string; inputPath?: TextInputPath }> {
|
|
1164
1179
|
if (typeof args.text !== "string") throw new SharedToolError("type_text requires a string { text }");
|
|
1165
1180
|
const loc = locatorOf(args);
|
|
1166
1181
|
return withPage(driver, args.target, async (page) => {
|
|
1167
1182
|
const element = await describeElement(page, loc);
|
|
1168
|
-
await page.typeText(loc, args.text);
|
|
1169
|
-
return { typed: true, ...elementField(element), text: args.text };
|
|
1183
|
+
const path = await page.typeText(loc, args.text);
|
|
1184
|
+
return { typed: true, ...elementField(element), text: args.text, ...inputPathField(path) };
|
|
1170
1185
|
});
|
|
1171
1186
|
}
|
|
1172
1187
|
|
|
1173
|
-
export async function pressKey(driver: BrowserDriver, args: { target?: TargetSelector; key: string; modifiers?: string[] }): Promise<{ pressed: string; modifiers: string[] }> {
|
|
1188
|
+
export async function pressKey(driver: BrowserDriver, args: { target?: TargetSelector; key: string; modifiers?: string[] }): Promise<{ pressed: string; modifiers: string[]; delivered?: false; note?: string }> {
|
|
1174
1189
|
if (typeof args.key !== "string" || !args.key.length) throw new SharedToolError("press_key requires a non-empty { key }");
|
|
1175
1190
|
const modifiers = args.modifiers ?? [];
|
|
1176
1191
|
return withPage(driver, args.target, async (page) => {
|
|
1177
|
-
await page.pressKey({ key: args.key, modifiers });
|
|
1192
|
+
const res = await page.pressKey({ key: args.key, modifiers });
|
|
1193
|
+
// Only a definite miss is reported; delivered/unknown keeps the old shape.
|
|
1194
|
+
if (res && res.delivered === false) {
|
|
1195
|
+
return {
|
|
1196
|
+
pressed: args.key, modifiers, delivered: false,
|
|
1197
|
+
note: "the page saw no keydown: a background tab gets no trusted keyboard input. A click on the tab's page (click tool) usually gives it focus so keys land; or open the tab with new_page focus:true. A key handled inside a cross-origin iframe also reads as not delivered.",
|
|
1198
|
+
};
|
|
1199
|
+
}
|
|
1178
1200
|
return { pressed: args.key, modifiers };
|
|
1179
1201
|
});
|
|
1180
1202
|
}
|
|
@@ -1207,8 +1229,9 @@ const MAX_SCREENSHOT_SCALE = 8;
|
|
|
1207
1229
|
/**
|
|
1208
1230
|
* take_screenshot's `scale`, plus the second backend gate in this file (resolveDragMode is the
|
|
1209
1231
|
* first, and this follows its shape exactly). scale needs Capability "screenshot.scale", which
|
|
1210
|
-
*
|
|
1211
|
-
*
|
|
1232
|
+
* Chrome declares (Page.captureScreenshot takes a per-call clip.scale) and Firefox >= 160 declares
|
|
1233
|
+
* too (a one-capture devicePixelRatio override; captureScreenshot itself has no scale parameter, and
|
|
1234
|
+
* an older Firefox's driver refuses with "unsupported" from requireFirefox). Per ADR-001
|
|
1212
1235
|
* this is a PARAM-level gap, not a whole-tool one — take_screenshot stays in tools/list on Firefox
|
|
1213
1236
|
* because every other argument works there, and asking for a scale on Firefox is a clear
|
|
1214
1237
|
* validation error, never a silent 1x capture that would return an image the caller never asked
|
|
@@ -1221,7 +1244,7 @@ export function resolveScreenshotScale(scale: number | undefined, capabilities:
|
|
|
1221
1244
|
}
|
|
1222
1245
|
if (scale !== 1 && !capabilities.has("screenshot.scale")) {
|
|
1223
1246
|
throw new SharedToolError(
|
|
1224
|
-
"take_screenshot: 'scale' is not supported by this backend (
|
|
1247
|
+
"take_screenshot: 'scale' is not supported by this backend (no per-capture scale primitive). " +
|
|
1225
1248
|
`Call emulate with deviceScaleFactor:${scale} first and capture at scale 1, or use --browser chrome for a per-capture scale.`,
|
|
1226
1249
|
);
|
|
1227
1250
|
}
|
package/src/toolDocs.ts
CHANGED
|
@@ -13,14 +13,15 @@ export const TOOL_DOCS: Record<string, ToolDoc> = {
|
|
|
13
13
|
}
|
|
14
14
|
},
|
|
15
15
|
"new_page": {
|
|
16
|
-
"description": "Open a new browser tab via Target.createTarget and return {targetId,url}. Defaults to about:blank; navigation is not awaited here (use navigate_page to load and wait).",
|
|
16
|
+
"description": "Open a new browser tab via Target.createTarget and return {targetId,url}. The tab opens in the BACKGROUND (createTarget background:true; browsingContext.create background:true on Firefox), so the user's visible tab and keyboard focus stay put (on macOS the user's frontmost app is put back if the browser app came forward; CDP_RESTORE_FRONT_APP=0 turns that off); pass focus:true to open it in the foreground. Defaults to about:blank; navigation is not awaited here (use navigate_page to load and wait).",
|
|
17
17
|
"params": {
|
|
18
18
|
"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.",
|
|
19
19
|
"url": "URL to open in the new tab; defaults to about:blank.",
|
|
20
20
|
"endpoint": "Name of a CDP endpoint configured with CDP_ENDPOINTS / CDP_ENDPOINTS_FILE to open the tab on (Chrome only); default endpoint when omitted. Address the new tab later as 'endpoint:<name>/<targetId>'.",
|
|
21
21
|
"claim": "Claim the new tab atomically and return a lease token alongside {targetId,url}. Under CDP_REQUIRE_LEASE the tab is claimed and a lease returned even without claim:true; claim:true makes it an EXPLICIT lease that demands its token on every later call, even from this process. Default false.",
|
|
22
22
|
"label": "Agent label recorded on the lease when the tab is claimed; surfaced in conflict errors and list_leases. Defaults to pid-<pid>.",
|
|
23
|
-
"ttlMs": "How long a claimed lease survives without use before it is reclaimable. Defaults to CDP_LEASE_TTL_MS, else 900000 (15min); every checked call refreshes it. Ignored when not claiming."
|
|
23
|
+
"ttlMs": "How long a claimed lease survives without use before it is reclaimable. Defaults to CDP_LEASE_TTL_MS, else 900000 (15min); every checked call refreshes it. Ignored when not claiming.",
|
|
24
|
+
"focus": "Open the tab in the foreground, switching the user's visible tab and taking focus. Default false: the tab opens in the background."
|
|
24
25
|
}
|
|
25
26
|
},
|
|
26
27
|
"close_page": {
|
|
@@ -31,10 +32,11 @@ export const TOOL_DOCS: Record<string, ToolDoc> = {
|
|
|
31
32
|
}
|
|
32
33
|
},
|
|
33
34
|
"select_page": {
|
|
34
|
-
"description": "
|
|
35
|
+
"description": "Persist a page target's bare targetId to the selected-state file (CDP_STATE_DIR/selected) and return {selected,focused}. By default it does NOT raise the tab: the user's visible tab and window focus stay put. focus:true also activates it (Target.activateTarget; browsingContext.activate on Firefox), which was the old default. Requires an explicit, resolvable target.",
|
|
35
36
|
"params": {
|
|
36
37
|
"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.",
|
|
37
|
-
"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."
|
|
38
|
+
"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.",
|
|
39
|
+
"focus": "Also raise the tab and take window focus (Target.activateTarget / browsingContext.activate). Default false: selection only."
|
|
38
40
|
}
|
|
39
41
|
},
|
|
40
42
|
"navigate_page": {
|
|
@@ -164,7 +166,7 @@ export const TOOL_DOCS: Record<string, ToolDoc> = {
|
|
|
164
166
|
}
|
|
165
167
|
},
|
|
166
168
|
"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
|
|
169
|
+
"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
170
|
"params": {
|
|
169
171
|
"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
172
|
"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 +174,7 @@ export const TOOL_DOCS: Record<string, ToolDoc> = {
|
|
|
172
174
|
"x": "Viewport x-coordinate. Required every call — CDP has no 'current pointer position' to default from.",
|
|
173
175
|
"y": "Viewport y-coordinate. Required every call.",
|
|
174
176
|
"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.",
|
|
177
|
+
"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
178
|
"modifiers": "Modifier keys held for this one event, e.g. ['Shift']."
|
|
177
179
|
}
|
|
178
180
|
},
|
|
@@ -197,7 +199,7 @@ export const TOOL_DOCS: Record<string, ToolDoc> = {
|
|
|
197
199
|
}
|
|
198
200
|
},
|
|
199
201
|
"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.
|
|
202
|
+
"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
203
|
"params": {
|
|
202
204
|
"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
205
|
"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 +208,7 @@ export const TOOL_DOCS: Record<string, ToolDoc> = {
|
|
|
206
208
|
}
|
|
207
209
|
},
|
|
208
210
|
"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.
|
|
211
|
+
"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
212
|
"params": {
|
|
211
213
|
"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
214
|
"target": "Also the origin source when 'origin' is omitted. Grammar: server instructions.",
|
|
@@ -216,7 +218,7 @@ export const TOOL_DOCS: Record<string, ToolDoc> = {
|
|
|
216
218
|
}
|
|
217
219
|
},
|
|
218
220
|
"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
|
|
221
|
+
"description": "Fills an element by focusing it, clearing existing content, then inserting value via Input.insertText (atomic paste-like commit, not per-character keystrokes, so it won't fire per-keypress handlers). Give exactly one of uid or selector. Returns {filled,element,value}; element names the field (textbox \"Email\"). On a background tab (Chrome), which gets no trusted keyboard input, the commit is verified and falls back in-page (execCommand insertText, else the native value setter plus input/change events); the result then carries inputPath. The tab is never raised.",
|
|
220
222
|
"params": {
|
|
221
223
|
"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
224
|
"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.",
|
|
@@ -226,7 +228,7 @@ export const TOOL_DOCS: Record<string, ToolDoc> = {
|
|
|
226
228
|
}
|
|
227
229
|
},
|
|
228
230
|
"fill_form": {
|
|
229
|
-
"description": "Fills multiple form fields in one call; each is focused, cleared, then set via Input.insertText (overwrites existing content, same as fill). Each entry in the non-empty 'fields' array takes exactly one of uid or selector plus a string value.",
|
|
231
|
+
"description": "Fills multiple form fields in one call; each is focused, cleared, then set via Input.insertText (overwrites existing content, same as fill). Each entry in the non-empty 'fields' array takes exactly one of uid or selector plus a string value. Background tab (Chrome): each field falls back in-page like fill, and inputPaths lists the path per field when any fell back.",
|
|
230
232
|
"params": {
|
|
231
233
|
"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.",
|
|
232
234
|
"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.",
|
|
@@ -234,7 +236,7 @@ export const TOOL_DOCS: Record<string, ToolDoc> = {
|
|
|
234
236
|
}
|
|
235
237
|
},
|
|
236
238
|
"type_text": {
|
|
237
|
-
"description": "Focuses an element and appends text via Input.insertText without clearing first
|
|
239
|
+
"description": "Focuses an element and appends text via Input.insertText without clearing first: the closest primitive to typing, but still atomic (not per-character keystrokes). Give exactly one of uid or selector. Background tab (Chrome): falls back in-page like fill and reports inputPath.",
|
|
238
240
|
"params": {
|
|
239
241
|
"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.",
|
|
240
242
|
"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.",
|
|
@@ -244,7 +246,7 @@ export const TOOL_DOCS: Record<string, ToolDoc> = {
|
|
|
244
246
|
}
|
|
245
247
|
},
|
|
246
248
|
"press_key": {
|
|
247
|
-
"description": "Dispatches a keyDown/keyUp pair for one key with optional modifiers. 'key' is a named key (Enter, Tab, Escape, ArrowDown, Backspace, etc.) or a single printable character
|
|
249
|
+
"description": "Dispatches a keyDown/keyUp pair for one key with optional modifiers. 'key' is a named key (Enter, Tab, Escape, ArrowDown, Backspace, etc.) or a single printable character; the named-key table is curated, with no F-keys, numpad, or IME support. A background tab gets no trusted keys: the result then says delivered:false (nothing is faked). A click on the page first usually gives it focus so keys land.",
|
|
248
250
|
"params": {
|
|
249
251
|
"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.",
|
|
250
252
|
"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 +272,7 @@ export const TOOL_DOCS: Record<string, ToolDoc> = {
|
|
|
270
272
|
"format": "Image format, default png. quality applies only to jpeg.",
|
|
271
273
|
"quality": "JPEG quality 0-100, default 80; ignored for png.",
|
|
272
274
|
"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.
|
|
275
|
+
"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
276
|
"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
277
|
"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
278
|
"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.",
|
|
@@ -403,7 +405,7 @@ export const TOOL_DOCS: Record<string, ToolDoc> = {
|
|
|
403
405
|
"maxWidth": "Caps the streamed frame width in px; also pins frame size if the viewport may change mid-recording.",
|
|
404
406
|
"maxHeight": "Caps the streamed frame height in px.",
|
|
405
407
|
"everyNthFrame": "Capture only every Nth repaint (1=every frame), to shrink spool size on a busy page; per-frame durations keep playback at wallclock speed either way.",
|
|
406
|
-
"bringToFront": "Activate the tab (Page.bringToFront) before recording, default false. A backgrounded/occluded tab may never repaint, yielding a 0-frame recording."
|
|
408
|
+
"bringToFront": "Activate the tab (Page.bringToFront) before recording, default false. A backgrounded/occluded tab may never repaint, yielding a 0-frame recording. new_page opens tabs in the background, so a fresh tab needs this (or new_page focus:true) for a real frame rate."
|
|
407
409
|
}
|
|
408
410
|
},
|
|
409
411
|
"stop_screen_recording": {
|
|
@@ -473,7 +475,8 @@ export const TOOL_DOCS: Record<string, ToolDoc> = {
|
|
|
473
475
|
"targetId": "Exact target id (not a selector) of an already-open page to claim instead of opening one. Back-compat only; prefer target, which also accepts an exact id. Mutually exclusive with target.",
|
|
474
476
|
"url": "When opening a fresh tab, navigate it here. Ignored when target or targetId is given.",
|
|
475
477
|
"label": "Agent label recorded on the lease; surfaced in conflict errors and list_leases. Defaults to pid-<pid>.",
|
|
476
|
-
"ttlMs": "How long the lease survives without use before it is reclaimable. Defaults to CDP_LEASE_TTL_MS, else 900000 (15min); every checked call refreshes it."
|
|
478
|
+
"ttlMs": "How long the lease survives without use before it is reclaimable. Defaults to CDP_LEASE_TTL_MS, else 900000 (15min); every checked call refreshes it.",
|
|
479
|
+
"focus": "Fresh-tab mode only: open the tab in the foreground and take focus. Default false: the tab opens in the background. Ignored on takeover (target/targetId), which never raises the tab."
|
|
477
480
|
}
|
|
478
481
|
},
|
|
479
482
|
"release_page": {
|
|
@@ -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/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/version.ts
CHANGED