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/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
- const ORIGIN_FILE_RE = /^origin-(chrome|firefox)-(.+)\.json$/;
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
  *
@@ -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
- return driver.scheme === "bidi" ? "firefox" : "chrome";
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
- const reaped = requireLease() ? await reapStaleAgentTabs(driver, backend) : [];
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 { x, y } = await page.click(locatorOf(args), { button: args.button ?? "left", clickCount: args.clickCount ?? 1, modifiers: args.modifiers });
849
- return { clicked: true, x, y };
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 { x, y } = await page.hover(locatorOf(args));
897
- return { hovered: true, x, y };
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 { from, to } = await page.drag(locatorOf(args.from), destination, { mode, steps });
1000
- return { dragged: true, mode, steps, from, to };
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.setValue(locatorOf(args), args.value);
1008
- return { filled: true, value: args.value };
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
- await page.setValue(locatorOf(f), f.value);
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.typeText(locatorOf(args), args.text);
1032
- return { typed: true, text: args.text };
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
- await page.setFiles(locatorOf(args), files);
1052
- return { uploaded: files };
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