cdp-toolkit 3.0.3 → 3.2.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 +28 -0
- package/CONTRACT.md +2 -2
- package/README.md +122 -1
- package/dist/bidi/mux-daemon.js +675 -130
- package/dist/cli.js +1432 -635
- package/dist/index.js +1110 -116
- package/dist/mcp.js +1474 -658
- package/package.json +3 -1
- package/src/bidi/snapshot.ts +123 -113
- package/src/cdp/driver.ts +55 -41
- package/src/cdp/endpoint.ts +200 -0
- package/src/cdp/session.ts +246 -0
- package/src/cli.ts +17 -4
- package/src/client.ts +140 -16
- 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 +164 -25
- package/src/toolDocs.ts +41 -38
- package/src/tools/browser-session.ts +26 -12
- package/src/tools/dispatch-mouse.ts +2 -1
- package/src/tools/evaluate.ts +3 -3
- package/src/tools/focus-emulation.ts +5 -3
- package/src/tools/lighthouse.ts +4 -2
- 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/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/origins.ts
CHANGED
|
@@ -32,7 +32,7 @@
|
|
|
32
32
|
import { mkdir, readFile, readdir, unlink, writeFile } from "node:fs/promises";
|
|
33
33
|
import { join } from "node:path";
|
|
34
34
|
import type { BrowserDriver, PageInfo } from "./driver.ts";
|
|
35
|
-
import { defaultLabel, leaseDir, listLeases, type LeaseBackend } from "./leases.ts";
|
|
35
|
+
import { BACKEND_KEY_SOURCE, defaultLabel, leaseDir, listLeases, type LeaseBackend } from "./leases.ts";
|
|
36
36
|
|
|
37
37
|
/** What list_pages can say about where a tab came from. There is deliberately
|
|
38
38
|
* no "human": see the file header. */
|
|
@@ -60,7 +60,10 @@ export function originFile(backend: LeaseBackend, targetId: string): string {
|
|
|
60
60
|
return join(leaseDir(), `origin-${backend}-${safeId(targetId)}.json`);
|
|
61
61
|
}
|
|
62
62
|
|
|
63
|
-
|
|
63
|
+
// Same backend-key grammar as leases.ts: `origin-chrome@teams-<id>.json` for a named
|
|
64
|
+
// endpoint. listOrigins' liveBackend scoping then keeps one endpoint's target list from
|
|
65
|
+
// reaping another endpoint's records.
|
|
66
|
+
const ORIGIN_FILE_RE = new RegExp(`^origin-(${BACKEND_KEY_SOURCE})-(.+)\\.json$`);
|
|
64
67
|
|
|
65
68
|
/**
|
|
66
69
|
* Record that this toolkit just created `targetId`.
|
package/src/policy.ts
ADDED
|
@@ -0,0 +1,163 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Read-only endpoint policy (#15): which tools may run against an endpoint marked read-only.
|
|
3
|
+
*
|
|
4
|
+
* The rule: a READ tool sends no CDP command that changes page or browser state. Every tool in
|
|
5
|
+
* the registry (`TOOLS`, src/index.ts) is in exactly one of READ_TOOLS / MUTATING_TOOLS, and the
|
|
6
|
+
* dispatch-only meta tools of src/mcp.ts (search_tools, call_tool, describe_tool) are META: the
|
|
7
|
+
* inner tool of a call_tool is checked when it re-enters dispatch. test/policy.test.ts fails when
|
|
8
|
+
* a tool is added to the registry without being classified here.
|
|
9
|
+
*
|
|
10
|
+
* Default-deny: a name in none of the sets is treated as MUTATING.
|
|
11
|
+
*
|
|
12
|
+
* DECISION (user): evaluate_script is READ. The agent is responsible for what it runs.
|
|
13
|
+
*
|
|
14
|
+
* Classification is by tool name. A few READ tools have arguments that escalate them to a state
|
|
15
|
+
* change (see `escalatesToMutation`); the optional `args` parameter of `assertAllowed` covers those.
|
|
16
|
+
*/
|
|
17
|
+
|
|
18
|
+
/** Tools that change no page or browser state (see the borderline notes inline). */
|
|
19
|
+
export const READ_TOOLS: ReadonlySet<string> = new Set([
|
|
20
|
+
// borderline: GET /json/list, plus a local lease/ledger read. `probe` only does a Runtime.evaluate
|
|
21
|
+
// (renderer ping + beacon read). CAVEAT for the dispatcher: under strict-lease mode listPages first
|
|
22
|
+
// reaps stale agent tabs (Target.closeTarget, src/shared-tools.ts listPages); skip the reap on a
|
|
23
|
+
// read-only endpoint.
|
|
24
|
+
"list_pages",
|
|
25
|
+
// borderline: polls Runtime.evaluate for text; changes nothing.
|
|
26
|
+
"wait_for",
|
|
27
|
+
// borderline: arbitrary JS. READ by the user's decision, not by the nature of the tool.
|
|
28
|
+
"evaluate_script",
|
|
29
|
+
// Network.getCookies only. (set_cookie / delete_cookies are MUTATING.)
|
|
30
|
+
"list_cookies",
|
|
31
|
+
// borderline: Accessibility.enable + getFullAXTree; enabling a domain is not a page change.
|
|
32
|
+
"take_snapshot",
|
|
33
|
+
// borderline: Page.getLayoutMetrics + Page.captureScreenshot. With `uid`/`selector` it calls
|
|
34
|
+
// DOM.scrollIntoViewIfNeeded (a scroll); with renderWidth/renderHeight it applies and restores an
|
|
35
|
+
// Emulation.setDeviceMetricsOverride. The latter is escalated in `escalatesToMutation`.
|
|
36
|
+
"take_screenshot",
|
|
37
|
+
// borderline: default reads a buffer a prior recorder wrote. `reload:true` runs Page.reload
|
|
38
|
+
// (escalated in `escalatesToMutation`).
|
|
39
|
+
"list_console_messages",
|
|
40
|
+
"get_console_message",
|
|
41
|
+
"list_network_requests",
|
|
42
|
+
// borderline: metadata read, but `includeBody` with `url` drives a reload capture (escalated).
|
|
43
|
+
"get_network_request",
|
|
44
|
+
// borderline: reads a local trace JSON file; sends no CDP command at all.
|
|
45
|
+
"performance_analyze_insight",
|
|
46
|
+
// borderline: HeapProfiler.enable + takeHeapSnapshot. Forces a GC and can stall the page for a
|
|
47
|
+
// moment, but changes no state.
|
|
48
|
+
"take_heapsnapshot",
|
|
49
|
+
// borderline: lists local fake-backend sessions; its only CDP command is a Runtime.evaluate("1") liveness ping.
|
|
50
|
+
"list_mocks",
|
|
51
|
+
// borderline: a Runtime.evaluate that cleans the page HTML, then POSTs it to an LLM endpoint.
|
|
52
|
+
// Nothing is written to the page. Data leaves the machine; that is not a page-state change.
|
|
53
|
+
"extract_page",
|
|
54
|
+
// borderline: reads the local lease store and /json/list. Same strict-mode reap caveat as list_pages.
|
|
55
|
+
"list_leases",
|
|
56
|
+
]);
|
|
57
|
+
|
|
58
|
+
/** Tools that send a CDP command that changes page or browser state, or change lease state. */
|
|
59
|
+
export const MUTATING_TOOLS: ReadonlySet<string> = new Set([
|
|
60
|
+
// pages
|
|
61
|
+
"new_page", // Target.createTarget
|
|
62
|
+
"close_page", // Target.closeTarget
|
|
63
|
+
// borderline: Target.activateTarget raises the tab and steals window focus. A state change.
|
|
64
|
+
"select_page",
|
|
65
|
+
"navigate_page", // Page.navigate / reload / history
|
|
66
|
+
"set_cookie",
|
|
67
|
+
"delete_cookies",
|
|
68
|
+
// interaction
|
|
69
|
+
"click",
|
|
70
|
+
"hover", // borderline: Input.dispatchMouseEvent mouseMoved fires hover handlers and can open menus
|
|
71
|
+
"drag",
|
|
72
|
+
"scroll", // borderline: wheel event moves the scroll offset and can trigger lazy loading
|
|
73
|
+
"fill",
|
|
74
|
+
"fill_form",
|
|
75
|
+
"type_text",
|
|
76
|
+
"press_key",
|
|
77
|
+
"upload_file",
|
|
78
|
+
// emulation
|
|
79
|
+
"emulate",
|
|
80
|
+
"resize_page",
|
|
81
|
+
"handle_dialog",
|
|
82
|
+
// performance
|
|
83
|
+
// borderline: Tracing.start begins a browser-wide trace session, and the one-shot variant also reloads.
|
|
84
|
+
"performance_start_trace",
|
|
85
|
+
"performance_stop_trace",
|
|
86
|
+
"performance_trace",
|
|
87
|
+
// recorder: Page.startScreencast / bringToFront, plus ffmpeg and files
|
|
88
|
+
"start_screen_recording",
|
|
89
|
+
"stop_screen_recording",
|
|
90
|
+
// borderline: attaches Lighthouse, which navigates, reloads and throttles the page
|
|
91
|
+
"lighthouse_audit",
|
|
92
|
+
// Fetch.enable: intercepts and rewrites the page's traffic
|
|
93
|
+
"mock_request",
|
|
94
|
+
"clear_mocks",
|
|
95
|
+
"dispatch_mouse",
|
|
96
|
+
"focus_emulation", // Emulation.setFocusEmulationEnabled
|
|
97
|
+
"click_focus_gated",
|
|
98
|
+
"wait_for_download", // borderline: Browser.setDownloadBehavior changes browser state
|
|
99
|
+
"grant_permissions", // Browser.grantPermissions
|
|
100
|
+
// leases: claim installs an activity beacon in the page and writes a lease; release can close a tab
|
|
101
|
+
"claim_page",
|
|
102
|
+
"release_page",
|
|
103
|
+
]);
|
|
104
|
+
|
|
105
|
+
/** Dispatch-only tools of src/mcp.ts (not in TOOLS). The inner tool is checked on re-entry. */
|
|
106
|
+
export const META_TOOLS: ReadonlySet<string> = new Set(["search_tools", "call_tool", "describe_tool"]);
|
|
107
|
+
|
|
108
|
+
export class PolicyError extends Error {
|
|
109
|
+
readonly code = "read_only_endpoint";
|
|
110
|
+
readonly tool: string;
|
|
111
|
+
readonly endpoint: string;
|
|
112
|
+
constructor(tool: string, endpoint: string) {
|
|
113
|
+
super(`'${tool}' is not allowed on endpoint '${endpoint}': the endpoint is read-only (tools that change state are refused before any CDP message is sent)`);
|
|
114
|
+
this.name = "PolicyError";
|
|
115
|
+
this.tool = tool;
|
|
116
|
+
this.endpoint = endpoint;
|
|
117
|
+
}
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
/** True when the tool is a known READ tool. Unknown names are false (default-deny). */
|
|
121
|
+
export function isReadTool(name: string): boolean {
|
|
122
|
+
return READ_TOOLS.has(name);
|
|
123
|
+
}
|
|
124
|
+
|
|
125
|
+
/**
|
|
126
|
+
* Argument combinations that turn a READ tool into a state change. Returns true when the call
|
|
127
|
+
* must be refused on a read-only endpoint even though the tool name is READ.
|
|
128
|
+
*/
|
|
129
|
+
export function escalatesToMutation(tool: string, args: unknown): boolean {
|
|
130
|
+
if (typeof args !== "object" || args === null) return false;
|
|
131
|
+
const a = args as Record<string, unknown>;
|
|
132
|
+
switch (tool) {
|
|
133
|
+
case "list_console_messages":
|
|
134
|
+
case "list_network_requests":
|
|
135
|
+
return a.reload === true;
|
|
136
|
+
case "get_network_request":
|
|
137
|
+
return a.includeBody === true && typeof a.url === "string" && a.url !== "";
|
|
138
|
+
case "take_screenshot":
|
|
139
|
+
return a.renderWidth !== undefined || a.renderHeight !== undefined;
|
|
140
|
+
default:
|
|
141
|
+
return false;
|
|
142
|
+
}
|
|
143
|
+
}
|
|
144
|
+
|
|
145
|
+
/**
|
|
146
|
+
* Throw PolicyError when the endpoint is read-only and `tool` may change state. Unknown names are
|
|
147
|
+
* treated as MUTATING. Pass the call's `args` to also refuse the escalating combinations above.
|
|
148
|
+
*/
|
|
149
|
+
export function assertAllowed(
|
|
150
|
+
tool: string,
|
|
151
|
+
endpoint: { name: string; readOnly: boolean },
|
|
152
|
+
args?: unknown,
|
|
153
|
+
): void {
|
|
154
|
+
if (!endpoint.readOnly) return;
|
|
155
|
+
if (META_TOOLS.has(tool)) return;
|
|
156
|
+
if (!READ_TOOLS.has(tool)) throw new PolicyError(tool, endpoint.name);
|
|
157
|
+
if (escalatesToMutation(tool, args)) throw new PolicyError(tool, endpoint.name);
|
|
158
|
+
}
|
|
159
|
+
|
|
160
|
+
/** MCP tools/list annotation: `readOnlyHint` is true for READ tools only. */
|
|
161
|
+
export function toolAnnotations(name: string): { readOnlyHint: boolean } {
|
|
162
|
+
return { readOnlyHint: READ_TOOLS.has(name) };
|
|
163
|
+
}
|
package/src/reap.ts
CHANGED
|
@@ -30,6 +30,7 @@
|
|
|
30
30
|
* `expired` as grounds to close anything. See staleAgentTabs' condition 4.
|
|
31
31
|
*/
|
|
32
32
|
import type { BrowserDriver } from "./driver.ts";
|
|
33
|
+
import { currentEndpoint } from "./endpoints.ts";
|
|
33
34
|
import { listLeases, releaseLeaseFor, type LeaseBackend, type LeaseSummary } from "./leases.ts";
|
|
34
35
|
import { originIndex, type OriginSummary } from "./origins.ts";
|
|
35
36
|
|
|
@@ -125,6 +126,19 @@ export function reapGraceMs(): number {
|
|
|
125
126
|
return Number.isFinite(raw) && raw >= 0 ? raw : DEFAULT_REAP_GRACE_MS;
|
|
126
127
|
}
|
|
127
128
|
|
|
129
|
+
/**
|
|
130
|
+
* Whether the strict-mode reap may run in the current dispatch scope (#15).
|
|
131
|
+
* NEVER on a read-only endpoint: the reap closes tabs (Target.closeTarget), and
|
|
132
|
+
* a read-only endpoint promises that list_pages / list_leases change nothing
|
|
133
|
+
* there. Read off currentEndpoint(), not the dispatch endpoint, because
|
|
134
|
+
* list_pages{allEndpoints} re-scopes per endpoint. The bidi (Firefox) driver
|
|
135
|
+
* has no named endpoints and never loads their config, so it is always allowed.
|
|
136
|
+
*/
|
|
137
|
+
export function reapAllowed(driver: BrowserDriver): boolean {
|
|
138
|
+
if (driver.scheme === "bidi") return true;
|
|
139
|
+
return !currentEndpoint().readOnly;
|
|
140
|
+
}
|
|
141
|
+
|
|
128
142
|
/**
|
|
129
143
|
* Select, close, and drop the leases. Returns ONLY the tabs actually closed.
|
|
130
144
|
*
|
package/src/shared-tools.ts
CHANGED
|
@@ -42,14 +42,16 @@ import { isTiledCapture } from "./driver.ts";
|
|
|
42
42
|
import { stitchPngBandsToFile } from "./png.ts";
|
|
43
43
|
import type { TargetSelector } from "./types.ts";
|
|
44
44
|
import {
|
|
45
|
-
assertLeaseOk, claimLease, defaultLabel, leaseTtlMs, listLeases, releaseLeaseFor, requireLease,
|
|
45
|
+
assertLeaseOk, chromeLeaseBackend, claimLease, defaultLabel, leaseTtlMs, listLeases, releaseLeaseFor, requireLease,
|
|
46
46
|
type LeaseBackend, type LeaseStaleReason, type LeaseToken,
|
|
47
47
|
} from "./leases.ts";
|
|
48
48
|
import { installBeacon, probeRendererActivity, rendererProbeSupported } from "./activity.ts";
|
|
49
49
|
import { newTrackedPage, originIndex, resolveLiveLabel, type PageOrigin } from "./origins.ts";
|
|
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
|
-
import { reapStaleAgentTabs, type ReapedTab } from "./reap.ts";
|
|
52
|
+
import { reapAllowed, reapStaleAgentTabs, type ReapedTab } from "./reap.ts";
|
|
53
|
+
import { ACCNAME_HELPERS_SOURCE, MAX_NAME_LENGTH } from "./bidi/snapshot.ts";
|
|
54
|
+
import { allEndpoints, currentEndpoint, isDefaultEndpoint, withEndpointScope } from "./endpoints.ts";
|
|
53
55
|
|
|
54
56
|
const ARTIFACT_DIR = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
|
|
55
57
|
const STATE_DIR = process.env.CDP_STATE_DIR ?? "/tmp/cdp-toolkit";
|
|
@@ -64,7 +66,8 @@ function target3(p: PageInfo): { id: string; url: string; title: string } {
|
|
|
64
66
|
/** Same discriminator leases-tools.ts uses: the driver's own uid scheme tag
|
|
65
67
|
* ("cdp" for Chrome, "bidi" for Firefox). */
|
|
66
68
|
function backendOf(driver: BrowserDriver): LeaseBackend {
|
|
67
|
-
|
|
69
|
+
// Chrome's key carries the dispatch scope's named endpoint (chrome@<name>); see LeaseBackend.
|
|
70
|
+
return driver.scheme === "bidi" ? "firefox" : chromeLeaseBackend();
|
|
68
71
|
}
|
|
69
72
|
|
|
70
73
|
/* -------------------------------- page acquisition -------------------------------- */
|
|
@@ -217,6 +220,12 @@ function locatorOf(args: { uid?: DriverUid; selector?: string }): ElementLocator
|
|
|
217
220
|
* them today.
|
|
218
221
|
*/
|
|
219
222
|
export interface ListedPage extends PageInfo {
|
|
223
|
+
/** The named CDP endpoint this page lives on (src/endpoints.ts). Present on
|
|
224
|
+
* every row from a NON-default endpoint, and on every row of an
|
|
225
|
+
* allEndpoints listing, so a caller can build an `endpoint:<name>/<id>`
|
|
226
|
+
* selector. Absent on a default-endpoint listing, which keeps that output
|
|
227
|
+
* byte-identical to before named endpoints existed. */
|
|
228
|
+
endpoint?: string;
|
|
220
229
|
/** "agent" when the creation ledger has a record for this target. Otherwise
|
|
221
230
|
* "unknown", NEVER "human": the absence of a record is not proof that a
|
|
222
231
|
* person opened the tab. See src/origins.ts. */
|
|
@@ -277,7 +286,66 @@ async function reapSet(driver: BrowserDriver, pages: PageInfo[], all?: boolean):
|
|
|
277
286
|
}
|
|
278
287
|
}
|
|
279
288
|
|
|
289
|
+
/** One endpoint's status in a list_pages{allEndpoints:true} result. */
|
|
290
|
+
export type EndpointListing =
|
|
291
|
+
| { endpoint: string; base: string; readOnly: boolean; count: number }
|
|
292
|
+
| { endpoint: string; base: string; readOnly: boolean; down: true; error: string };
|
|
293
|
+
|
|
294
|
+
/**
|
|
295
|
+
* list_pages. With allEndpoints (Chrome only) every configured endpoint is
|
|
296
|
+
* listed in its own endpoint scope, concurrently: page rows are tagged with
|
|
297
|
+
* `endpoint`, `endpoints` reports each endpoint's count, and an endpoint that
|
|
298
|
+
* cannot be reached is reported `{endpoint, down: true, error}` there instead
|
|
299
|
+
* of failing the call. Each endpoint's reap runs in its own scope, so it
|
|
300
|
+
* compares that endpoint's leases only against that endpoint's live targets,
|
|
301
|
+
* and a down endpoint reaps nothing at all.
|
|
302
|
+
*/
|
|
280
303
|
export async function listPages(
|
|
304
|
+
driver: BrowserDriver,
|
|
305
|
+
args: { all?: boolean; probe?: boolean; allEndpoints?: boolean } = {},
|
|
306
|
+
): Promise<{ pages: ListedPage[]; count: number; reaped?: Array<ReapedTab & { endpoint?: string }>; endpoints?: EndpointListing[] }> {
|
|
307
|
+
const one = { all: args.all, probe: args.probe };
|
|
308
|
+
if (args.allEndpoints === true) {
|
|
309
|
+
if (driver.scheme === "bidi") throw new SharedToolError("list_pages: allEndpoints needs the Chrome backend; named endpoints are CDP-only");
|
|
310
|
+
const results = await Promise.all(
|
|
311
|
+
allEndpoints().map((ep) =>
|
|
312
|
+
withEndpointScope(ep, () => listPagesOne(driver, one)).then(
|
|
313
|
+
(r) => ({ ep, r }),
|
|
314
|
+
(e: unknown) => ({ ep, error: e instanceof Error ? e.message : String(e) }),
|
|
315
|
+
),
|
|
316
|
+
),
|
|
317
|
+
);
|
|
318
|
+
const pages: ListedPage[] = [];
|
|
319
|
+
const reaped: Array<ReapedTab & { endpoint: string }> = [];
|
|
320
|
+
const endpoints: EndpointListing[] = [];
|
|
321
|
+
for (const res of results) {
|
|
322
|
+
const { ep } = res;
|
|
323
|
+
if ("error" in res) {
|
|
324
|
+
endpoints.push({ endpoint: ep.name, base: ep.base, readOnly: ep.readOnly, down: true, error: res.error });
|
|
325
|
+
continue;
|
|
326
|
+
}
|
|
327
|
+
for (const p of res.r.pages) pages.push({ ...p, endpoint: ep.name });
|
|
328
|
+
for (const t of res.r.reaped ?? []) reaped.push({ ...t, endpoint: ep.name });
|
|
329
|
+
endpoints.push({ endpoint: ep.name, base: ep.base, readOnly: ep.readOnly, count: res.r.count });
|
|
330
|
+
}
|
|
331
|
+
return { pages, count: pages.length, ...(reaped.length ? { reaped } : {}), endpoints };
|
|
332
|
+
}
|
|
333
|
+
const res = await listPagesOne(driver, one);
|
|
334
|
+
if (driver.scheme !== "bidi") {
|
|
335
|
+
const ep = currentEndpoint();
|
|
336
|
+
if (!isDefaultEndpoint(ep)) {
|
|
337
|
+
return {
|
|
338
|
+
...res,
|
|
339
|
+
pages: res.pages.map((p) => ({ ...p, endpoint: ep.name })),
|
|
340
|
+
...(res.reaped ? { reaped: res.reaped.map((t) => ({ ...t, endpoint: ep.name })) } : {}),
|
|
341
|
+
};
|
|
342
|
+
}
|
|
343
|
+
}
|
|
344
|
+
return res;
|
|
345
|
+
}
|
|
346
|
+
|
|
347
|
+
/** One endpoint's listing: the pre-#15 list_pages body, unchanged. */
|
|
348
|
+
async function listPagesOne(
|
|
281
349
|
driver: BrowserDriver,
|
|
282
350
|
args: { all?: boolean; probe?: boolean } = {},
|
|
283
351
|
): Promise<{ pages: ListedPage[]; count: number; reaped?: ReapedTab[] }> {
|
|
@@ -286,7 +354,8 @@ export async function listPages(
|
|
|
286
354
|
// this same call is in the middle of deleting. Under strict mode only: see
|
|
287
355
|
// requireLease.
|
|
288
356
|
const backend = backendOf(driver);
|
|
289
|
-
|
|
357
|
+
// Never on a read-only endpoint (#15): reapAllowed.
|
|
358
|
+
const reaped = requireLease() && reapAllowed(driver) ? await reapStaleAgentTabs(driver, backend) : [];
|
|
290
359
|
const reapedIds = new Set(reaped.map((r) => r.targetId));
|
|
291
360
|
const pages = (await driver.listPages({ all: args.all })).filter((p) => !reapedIds.has(p.id));
|
|
292
361
|
// Never let provenance break the listing: originIndex does not throw, and a
|
|
@@ -840,13 +909,66 @@ export async function takeSnapshot(
|
|
|
840
909
|
|
|
841
910
|
/* ------------------------------ interaction (8) ------------------------------ */
|
|
842
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
|
+
|
|
843
963
|
export async function click(
|
|
844
964
|
driver: BrowserDriver,
|
|
845
965
|
args: { target?: TargetSelector; uid?: DriverUid; selector?: string; button?: "left" | "right" | "middle"; clickCount?: number; modifiers?: string[] },
|
|
846
|
-
): Promise<{ clicked: true; x: number; y: number }> {
|
|
966
|
+
): Promise<{ clicked: true; element?: string; x: number; y: number }> {
|
|
967
|
+
const loc = locatorOf(args);
|
|
847
968
|
return withPage(driver, args.target, async (page) => {
|
|
848
|
-
const
|
|
849
|
-
|
|
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 };
|
|
850
972
|
});
|
|
851
973
|
}
|
|
852
974
|
|
|
@@ -891,10 +1013,12 @@ export async function scroll(
|
|
|
891
1013
|
});
|
|
892
1014
|
}
|
|
893
1015
|
|
|
894
|
-
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);
|
|
895
1018
|
return withPage(driver, args.target, async (page) => {
|
|
896
|
-
const
|
|
897
|
-
|
|
1019
|
+
const element = await describeElement(page, loc);
|
|
1020
|
+
const { x, y } = await page.hover(loc);
|
|
1021
|
+
return { hovered: true, ...elementField(element), x, y };
|
|
898
1022
|
});
|
|
899
1023
|
}
|
|
900
1024
|
|
|
@@ -989,47 +1113,60 @@ export async function drag(
|
|
|
989
1113
|
mode?: "mouse" | "html5";
|
|
990
1114
|
steps?: number;
|
|
991
1115
|
},
|
|
992
|
-
): 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 } }> {
|
|
993
1117
|
if (!args.from) throw new SharedToolError("drag requires { from }");
|
|
994
1118
|
const destination = resolveDragDestination(args);
|
|
995
1119
|
const steps = resolveDragSteps(args.steps);
|
|
996
1120
|
// Capability check BEFORE withPage: an unsupported mode must not claim a lease or open a socket.
|
|
997
1121
|
const mode = resolveDragMode(args.mode, driver.capabilities);
|
|
998
1122
|
return withPage(driver, args.target, async (page) => {
|
|
999
|
-
const
|
|
1000
|
-
|
|
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
|
+
};
|
|
1001
1131
|
});
|
|
1002
1132
|
}
|
|
1003
1133
|
|
|
1004
|
-
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 }> {
|
|
1005
1135
|
if (typeof args.value !== "string") throw new SharedToolError("fill requires a string { value }");
|
|
1136
|
+
const loc = locatorOf(args);
|
|
1006
1137
|
return withPage(driver, args.target, async (page) => {
|
|
1007
|
-
await page
|
|
1008
|
-
|
|
1138
|
+
const element = await describeElement(page, loc);
|
|
1139
|
+
await page.setValue(loc, args.value);
|
|
1140
|
+
return { filled: true, ...elementField(element), value: args.value };
|
|
1009
1141
|
});
|
|
1010
1142
|
}
|
|
1011
1143
|
|
|
1012
1144
|
export async function fillForm(
|
|
1013
1145
|
driver: BrowserDriver,
|
|
1014
1146
|
args: { target?: TargetSelector; fields: Array<{ uid?: DriverUid; selector?: string; value: string }> },
|
|
1015
|
-
): Promise<{ filled: number; fields: number }> {
|
|
1147
|
+
): Promise<{ filled: number; fields: number; elements: Array<string | null> }> {
|
|
1016
1148
|
if (!Array.isArray(args.fields) || args.fields.length === 0) throw new SharedToolError("fill_form requires a non-empty { fields } array");
|
|
1017
1149
|
return withPage(driver, args.target, async (page) => {
|
|
1018
1150
|
let filled = 0;
|
|
1151
|
+
const elements: Array<string | null> = [];
|
|
1019
1152
|
for (const f of args.fields) {
|
|
1020
1153
|
if (typeof f.value !== "string") throw new SharedToolError("each fill_form field requires a string value");
|
|
1021
|
-
|
|
1154
|
+
const loc = locatorOf(f);
|
|
1155
|
+
elements.push((await describeElement(page, loc)) ?? null);
|
|
1156
|
+
await page.setValue(loc, f.value);
|
|
1022
1157
|
filled++;
|
|
1023
1158
|
}
|
|
1024
|
-
return { filled, fields: args.fields.length };
|
|
1159
|
+
return { filled, fields: args.fields.length, elements };
|
|
1025
1160
|
});
|
|
1026
1161
|
}
|
|
1027
1162
|
|
|
1028
|
-
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 }> {
|
|
1029
1164
|
if (typeof args.text !== "string") throw new SharedToolError("type_text requires a string { text }");
|
|
1165
|
+
const loc = locatorOf(args);
|
|
1030
1166
|
return withPage(driver, args.target, async (page) => {
|
|
1031
|
-
await page
|
|
1032
|
-
|
|
1167
|
+
const element = await describeElement(page, loc);
|
|
1168
|
+
await page.typeText(loc, args.text);
|
|
1169
|
+
return { typed: true, ...elementField(element), text: args.text };
|
|
1033
1170
|
});
|
|
1034
1171
|
}
|
|
1035
1172
|
|
|
@@ -1042,14 +1179,16 @@ export async function pressKey(driver: BrowserDriver, args: { target?: TargetSel
|
|
|
1042
1179
|
});
|
|
1043
1180
|
}
|
|
1044
1181
|
|
|
1045
|
-
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 }> {
|
|
1046
1183
|
const files = Array.isArray(args.files) ? args.files : [args.files];
|
|
1047
1184
|
if (!files.length || files.some((f) => typeof f !== "string" || !f.length)) {
|
|
1048
1185
|
throw new SharedToolError("upload_file requires { files } as a non-empty path or array of paths");
|
|
1049
1186
|
}
|
|
1050
1187
|
return withPage(driver, args.target, async (page) => {
|
|
1051
|
-
|
|
1052
|
-
|
|
1188
|
+
const loc = locatorOf(args);
|
|
1189
|
+
const element = await describeElement(page, loc);
|
|
1190
|
+
await page.setFiles(loc, files);
|
|
1191
|
+
return { uploaded: files, ...elementField(element) };
|
|
1053
1192
|
});
|
|
1054
1193
|
}
|
|
1055
1194
|
|