cdp-toolkit 3.3.0 → 3.5.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 +24 -0
- package/CONTRACT.md +1 -1
- package/README.md +20 -4
- package/dist/bidi/mux-daemon.js +231 -10
- package/dist/cli.js +409 -52
- package/dist/index.js +380 -43
- package/dist/mcp.js +433 -67
- package/package.json +1 -1
- package/src/bidi/driver.ts +21 -6
- package/src/cdp/driver.ts +190 -21
- package/src/cdp/hiddenTabs.ts +285 -0
- package/src/client.ts +12 -3
- package/src/driver.ts +26 -5
- package/src/frontApp.ts +62 -0
- package/src/leases-tools.ts +9 -2
- package/src/leases.ts +6 -0
- package/src/manifest.ts +15 -3
- package/src/mcp.ts +4 -0
- package/src/origins.ts +3 -2
- package/src/policy.ts +2 -1
- package/src/shared-tools.ts +79 -26
- package/src/toolDocs.ts +15 -12
- package/src/types.ts +3 -0
- package/src/version.ts +1 -1
package/src/shared-tools.ts
CHANGED
|
@@ -36,17 +36,17 @@
|
|
|
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";
|
|
43
43
|
import type { TargetSelector } from "./types.ts";
|
|
44
44
|
import {
|
|
45
|
-
assertLeaseOk, chromeLeaseBackend, claimLease, defaultLabel, leaseTtlMs, listLeases, releaseLeaseFor, requireLease,
|
|
45
|
+
assertLeaseOk, chromeLeaseBackend, claimLease, defaultLabel, leaseTtlMs, listLeases, readLease, 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
|
-
import { newTrackedPage, originIndex, resolveLiveLabel, type PageOrigin } from "./origins.ts";
|
|
49
|
+
import { newTrackedPage, originIndex, readOrigin, recordOrigin, 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
52
|
import { reapAllowed, reapStaleAgentTabs, type ReapedTab } from "./reap.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,19 +401,21 @@ 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 } = {},
|
|
406
|
-
): Promise<{ targetId: string; url: string; lease?: LeaseToken; label?: string; expiresAt?: number }> {
|
|
404
|
+
args: { url?: string; claim?: boolean; label?: string; ttlMs?: number; focus?: boolean } = {},
|
|
405
|
+
): Promise<{ targetId: string; url: string; hidden?: true; 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 });
|
|
410
|
+
// Present only for a hidden tab (CDP_HIDDEN_TABS), so the default output is byte-identical.
|
|
411
|
+
const hidden = p.hidden === true ? { hidden: true as const } : {};
|
|
411
412
|
// Under strict mode a tab nobody holds is a tab nobody may drive, so creating
|
|
412
413
|
// one without claiming it would hand back a target the very next call has to
|
|
413
414
|
// auto-acquire anyway. Doing it here means the tab is never briefly unowned
|
|
414
415
|
// AND the caller is handed a token it can release with, which matters because
|
|
415
416
|
// an auto-acquired lease never returns one.
|
|
416
417
|
const explicit = args.claim === true;
|
|
417
|
-
if (!explicit && !requireLease()) return { targetId: p.id, url: p.url };
|
|
418
|
+
if (!explicit && !requireLease()) return { targetId: p.id, url: p.url, ...hidden };
|
|
418
419
|
// Atomic in the sense that matters: the tab is claimed before this call
|
|
419
420
|
// returns, so no other agent can see it unclaimed and take it first.
|
|
420
421
|
const { record, token } = await claimLease(backendOf(driver), p.id, {
|
|
@@ -431,7 +432,7 @@ export async function newPage(
|
|
|
431
432
|
// it and a person has picked it up, which is the case the beacon exists for.
|
|
432
433
|
// Nothing here is read back: a tab created a moment ago has no human history.
|
|
433
434
|
await installBeacon(driver, p.id);
|
|
434
|
-
return { targetId: p.id, url: p.url, lease: token, label: record.label, expiresAt: record.lastUsedAt + record.ttlMs };
|
|
435
|
+
return { targetId: p.id, url: p.url, ...hidden, lease: token, label: record.label, expiresAt: record.lastUsedAt + record.ttlMs };
|
|
435
436
|
}
|
|
436
437
|
|
|
437
438
|
export async function closePage(
|
|
@@ -454,16 +455,53 @@ export async function closePage(
|
|
|
454
455
|
}
|
|
455
456
|
|
|
456
457
|
async function writeSelectedFile(id: string): Promise<void> {
|
|
457
|
-
|
|
458
|
-
|
|
458
|
+
// Read per call, not at import, so a test can point CDP_STATE_DIR at a temp dir.
|
|
459
|
+
const stateDir = process.env.CDP_STATE_DIR ?? "/tmp/cdp-toolkit";
|
|
460
|
+
await mkdir(stateDir, { recursive: true });
|
|
461
|
+
await writeFile(join(stateDir, "selected"), id, "utf8");
|
|
459
462
|
}
|
|
460
463
|
|
|
461
|
-
|
|
464
|
+
/**
|
|
465
|
+
* Persist the selection; raise the tab only on an explicit focus:true. Raising
|
|
466
|
+
* (Target.activateTarget / browsingContext.activate) switches the user's visible
|
|
467
|
+
* tab and takes window focus, so it is never a side effect of selecting.
|
|
468
|
+
* resolvePage already ran the lease gate, so skipping activatePage loses no check.
|
|
469
|
+
*
|
|
470
|
+
* focus:true on a HIDDEN tab (CDP_HIDDEN_TABS) cannot raise it in place: the driver reopens its
|
|
471
|
+
* URL in a new visible tab and closes the hidden one (see the CDP driver's activatePage). The new
|
|
472
|
+
* id is what gets selected and returned, with `revealedFrom` naming the closed hidden tab. The
|
|
473
|
+
* tab's provenance label moves with it, and a lease on the hidden tab is moved to the new tab and
|
|
474
|
+
* its NEW token returned as `lease`, since the old token names a tab that no longer exists.
|
|
475
|
+
*/
|
|
476
|
+
export async function selectPage(
|
|
477
|
+
driver: BrowserDriver,
|
|
478
|
+
args: { target?: TargetSelector; focus?: boolean },
|
|
479
|
+
): Promise<{ selected: string; focused: boolean; revealedFrom?: string; lease?: LeaseToken }> {
|
|
462
480
|
if (args.target === undefined || args.target === "") throw new SharedToolError("select_page requires an explicit target");
|
|
463
481
|
const p = await resolvePage(driver, args.target);
|
|
464
|
-
|
|
465
|
-
|
|
466
|
-
|
|
482
|
+
if (args.focus !== true) {
|
|
483
|
+
await writeSelectedFile(p.id);
|
|
484
|
+
return { selected: p.id, focused: false };
|
|
485
|
+
}
|
|
486
|
+
const shown = await driver.activatePage(p.id);
|
|
487
|
+
if (shown.revealedFrom === undefined || shown.id === p.id) {
|
|
488
|
+
await writeSelectedFile(shown.id);
|
|
489
|
+
return { selected: shown.id, focused: true };
|
|
490
|
+
}
|
|
491
|
+
const moved = await moveRevealedTab(backendOf(driver), shown.revealedFrom, shown.id);
|
|
492
|
+
await writeSelectedFile(shown.id);
|
|
493
|
+
return { selected: shown.id, focused: true, revealedFrom: shown.revealedFrom, ...(moved.lease ? { lease: moved.lease } : {}) };
|
|
494
|
+
}
|
|
495
|
+
|
|
496
|
+
/** Carry a revealed hidden tab's origin label and lease over to the visible tab that replaced it. */
|
|
497
|
+
async function moveRevealedTab(backend: LeaseBackend, fromId: string, toId: string): Promise<{ lease?: LeaseToken }> {
|
|
498
|
+
const origin = await readOrigin(backend, fromId).catch(() => undefined);
|
|
499
|
+
if (origin) await recordOrigin(backend, toId, { label: origin.label, now: origin.createdAt });
|
|
500
|
+
const lease = await readLease(backend, fromId).catch(() => undefined);
|
|
501
|
+
if (!lease) return {};
|
|
502
|
+
await releaseLeaseFor(backend, fromId);
|
|
503
|
+
const { token } = await claimLease(backend, toId, { label: lease.label, ttlMs: lease.ttlMs, auto: lease.auto === true });
|
|
504
|
+
return { lease: token };
|
|
467
505
|
}
|
|
468
506
|
|
|
469
507
|
/* ------------------------------ navigation (2) ------------------------------ */
|
|
@@ -1131,50 +1169,65 @@ export async function drag(
|
|
|
1131
1169
|
});
|
|
1132
1170
|
}
|
|
1133
1171
|
|
|
1134
|
-
|
|
1172
|
+
/** `inputPath` rides a result only when the commit did NOT go the trusted way (a background tab's
|
|
1173
|
+
* in-page fallback, or a skipped non-text element), so the common foreground shape is unchanged. */
|
|
1174
|
+
function inputPathField(path: void | TextInputPath): { inputPath?: TextInputPath } {
|
|
1175
|
+
return path && path !== "trusted" ? { inputPath: path } : {};
|
|
1176
|
+
}
|
|
1177
|
+
|
|
1178
|
+
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
1179
|
if (typeof args.value !== "string") throw new SharedToolError("fill requires a string { value }");
|
|
1136
1180
|
const loc = locatorOf(args);
|
|
1137
1181
|
return withPage(driver, args.target, async (page) => {
|
|
1138
1182
|
const element = await describeElement(page, loc);
|
|
1139
|
-
await page.setValue(loc, args.value);
|
|
1140
|
-
return { filled: true, ...elementField(element), value: args.value };
|
|
1183
|
+
const path = await page.setValue(loc, args.value);
|
|
1184
|
+
return { filled: true, ...elementField(element), value: args.value, ...inputPathField(path) };
|
|
1141
1185
|
});
|
|
1142
1186
|
}
|
|
1143
1187
|
|
|
1144
1188
|
export async function fillForm(
|
|
1145
1189
|
driver: BrowserDriver,
|
|
1146
1190
|
args: { target?: TargetSelector; fields: Array<{ uid?: DriverUid; selector?: string; value: string }> },
|
|
1147
|
-
): Promise<{ filled: number; fields: number; elements: Array<string | null
|
|
1191
|
+
): Promise<{ filled: number; fields: number; elements: Array<string | null>; inputPaths?: TextInputPath[] }> {
|
|
1148
1192
|
if (!Array.isArray(args.fields) || args.fields.length === 0) throw new SharedToolError("fill_form requires a non-empty { fields } array");
|
|
1149
1193
|
return withPage(driver, args.target, async (page) => {
|
|
1150
1194
|
let filled = 0;
|
|
1151
1195
|
const elements: Array<string | null> = [];
|
|
1196
|
+
const paths: TextInputPath[] = [];
|
|
1152
1197
|
for (const f of args.fields) {
|
|
1153
1198
|
if (typeof f.value !== "string") throw new SharedToolError("each fill_form field requires a string value");
|
|
1154
1199
|
const loc = locatorOf(f);
|
|
1155
1200
|
elements.push((await describeElement(page, loc)) ?? null);
|
|
1156
|
-
await page.setValue(loc, f.value);
|
|
1201
|
+
paths.push((await page.setValue(loc, f.value)) || "trusted");
|
|
1157
1202
|
filled++;
|
|
1158
1203
|
}
|
|
1159
|
-
|
|
1204
|
+
// Per field, in order, and only when some field went a non-trusted way.
|
|
1205
|
+
return { filled, fields: args.fields.length, elements, ...(paths.some((p) => p !== "trusted") ? { inputPaths: paths } : {}) };
|
|
1160
1206
|
});
|
|
1161
1207
|
}
|
|
1162
1208
|
|
|
1163
|
-
export async function typeText(driver: BrowserDriver, args: { target?: TargetSelector; uid?: DriverUid; selector?: string; text: string }): Promise<{ typed: true; element?: string; text: string }> {
|
|
1209
|
+
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
1210
|
if (typeof args.text !== "string") throw new SharedToolError("type_text requires a string { text }");
|
|
1165
1211
|
const loc = locatorOf(args);
|
|
1166
1212
|
return withPage(driver, args.target, async (page) => {
|
|
1167
1213
|
const element = await describeElement(page, loc);
|
|
1168
|
-
await page.typeText(loc, args.text);
|
|
1169
|
-
return { typed: true, ...elementField(element), text: args.text };
|
|
1214
|
+
const path = await page.typeText(loc, args.text);
|
|
1215
|
+
return { typed: true, ...elementField(element), text: args.text, ...inputPathField(path) };
|
|
1170
1216
|
});
|
|
1171
1217
|
}
|
|
1172
1218
|
|
|
1173
|
-
export async function pressKey(driver: BrowserDriver, args: { target?: TargetSelector; key: string; modifiers?: string[] }): Promise<{ pressed: string; modifiers: string[] }> {
|
|
1219
|
+
export async function pressKey(driver: BrowserDriver, args: { target?: TargetSelector; key: string; modifiers?: string[] }): Promise<{ pressed: string; modifiers: string[]; delivered?: false; note?: string }> {
|
|
1174
1220
|
if (typeof args.key !== "string" || !args.key.length) throw new SharedToolError("press_key requires a non-empty { key }");
|
|
1175
1221
|
const modifiers = args.modifiers ?? [];
|
|
1176
1222
|
return withPage(driver, args.target, async (page) => {
|
|
1177
|
-
await page.pressKey({ key: args.key, modifiers });
|
|
1223
|
+
const res = await page.pressKey({ key: args.key, modifiers });
|
|
1224
|
+
// Only a definite miss is reported; delivered/unknown keeps the old shape.
|
|
1225
|
+
if (res && res.delivered === false) {
|
|
1226
|
+
return {
|
|
1227
|
+
pressed: args.key, modifiers, delivered: false,
|
|
1228
|
+
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.",
|
|
1229
|
+
};
|
|
1230
|
+
}
|
|
1178
1231
|
return { pressed: args.key, modifiers };
|
|
1179
1232
|
});
|
|
1180
1233
|
}
|
package/src/toolDocs.ts
CHANGED
|
@@ -3,7 +3,7 @@ export type ToolDoc = { readonly description: string; readonly params: Record<st
|
|
|
3
3
|
|
|
4
4
|
export const TOOL_DOCS: Record<string, ToolDoc> = {
|
|
5
5
|
"list_pages": {
|
|
6
|
-
"description": "Enumerate browser page targets (GET /json/list); page-type tabs only unless all=true, which also lists workers and out-of-process (OOPIF) iframes. Each entry carries its targetId plus an origin field: 'agent' means this toolkit created it (also carries the creating label/createdAt, and stays 'agent' after the lease is released or the creator dies, making stray agent tabs findable), 'unknown' means no creation record - it never says 'human', the honest word for any tab it did not create; a record that exists but won't read adds originUnreadable. An entry under an active, readable lease also carries a 'lease' object {label,pid,idleMs,expiresAt,stale}, with idleMs and expiresAt computed fresh every call (never off disk), independent of probe. Under CDP_REQUIRE_LEASE this call also reaps abandoned agent tabs into an additive reaped array - but a lease reads reclaimable the moment its TTL elapses, while the tab is CLOSED only after a further grace (CDP_REAP_GRACE_MS, default 2700000ms/45min, so 60min total after last use); a dead-pid lease is reaped at once, a tab with no lease never. With probe, each page-type entry also gets 'responsive' (and humanActiveMs where human input is seen); both are absent, never false/null, without probe.",
|
|
6
|
+
"description": "Enumerate browser page targets (GET /json/list); page-type tabs only unless all=true, which also lists workers and out-of-process (OOPIF) iframes. Each entry carries its targetId plus an origin field: 'agent' means this toolkit created it (also carries the creating label/createdAt, and stays 'agent' after the lease is released or the creator dies, making stray agent tabs findable), 'unknown' means no creation record - it never says 'human', the honest word for any tab it did not create; a record that exists but won't read adds originUnreadable. An entry under an active, readable lease also carries a 'lease' object {label,pid,idleMs,expiresAt,stale}, with idleMs and expiresAt computed fresh every call (never off disk), independent of probe. Under CDP_REQUIRE_LEASE this call also reaps abandoned agent tabs into an additive reaped array - but a lease reads reclaimable the moment its TTL elapses, while the tab is CLOSED only after a further grace (CDP_REAP_GRACE_MS, default 2700000ms/45min, so 60min total after last use); a dead-pid lease is reaped at once, a tab with no lease never. With probe, each page-type entry also gets 'responsive' (and humanActiveMs where human input is seen); both are absent, never false/null, without probe. Under CDP_HIDDEN_TABS=1 (MCP server, Chrome), a tab this server opened hidden carries hidden:true: it is live and drivable but in no browser window, so the user cannot see it (select_page focus:true reveals it); hidden tabs are listed after the visible ones.",
|
|
7
7
|
"params": {
|
|
8
8
|
"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.",
|
|
9
9
|
"all": "Include non-page targets (service/shared workers, background pages, out-of-process (OOPIF) iframes); default false lists page-type tabs only. A returned non-page targetId is accepted as a bare id by any tool's `target` param.",
|
|
@@ -13,28 +13,30 @@ 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. Under CDP_HIDDEN_TABS=1 (MCP server, Chrome; ignored by the CLI) a non-focus new_page opens a HIDDEN tab instead (createTarget hidden:true): the browser app never comes forward, the result carries hidden:true, the tab is fully drivable (1280x800 emulated viewport, screenshots, clicks, typing, same cookies/logins) but the user cannot see it, it dies if this server or the browser restarts (later calls on its id fail no-such-target), and at most CDP_HIDDEN_TABS_MAX (default 20) may be open at once (new_page then refuses and names them; close_page frees one). Use select_page focus:true to show one to the user. 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 (a hidden tab under CDP_HIDDEN_TABS=1)."
|
|
24
25
|
}
|
|
25
26
|
},
|
|
26
27
|
"close_page": {
|
|
27
|
-
"description": "Close a page target via Target.closeTarget. Requires an explicit, resolvable target; errors rather than guessing when the selector matches nothing.",
|
|
28
|
+
"description": "Close a page target via Target.closeTarget. Requires an explicit, resolvable target; errors rather than guessing when the selector matches nothing. A hidden tab (CDP_HIDDEN_TABS) is closed over the connection that keeps it alive, and closing it never brings the browser forward.",
|
|
28
29
|
"params": {
|
|
29
30
|
"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.",
|
|
30
31
|
"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."
|
|
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. focus:true on a hidden tab (list_pages hidden:true, CDP_HIDDEN_TABS) cannot raise it in place: its current URL is opened in a new VISIBLE foreground tab, the hidden tab is closed, and the result's selected is the NEW targetId with revealedFrom naming the old one (its label moves along; a lease moves too and its new token comes back as lease). In-page state the URL does not carry (form input, scroll position) is lost. 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); a hidden tab is reopened visibly under a new targetId instead. Default false: selection only."
|
|
38
40
|
}
|
|
39
41
|
},
|
|
40
42
|
"navigate_page": {
|
|
@@ -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.",
|
|
@@ -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": {
|
package/src/types.ts
CHANGED
|
@@ -17,6 +17,9 @@ export interface Target {
|
|
|
17
17
|
/** present on some Chromium builds */
|
|
18
18
|
parentId?: string;
|
|
19
19
|
faviconUrl?: string;
|
|
20
|
+
/** A hidden tab this process owns (CDP_HIDDEN_TABS, see cdp/hiddenTabs.ts). The browser lists
|
|
21
|
+
* it as type "other"; listTargets relabels it "page" and sets this. Absent on every other target. */
|
|
22
|
+
hidden?: boolean;
|
|
20
23
|
}
|
|
21
24
|
|
|
22
25
|
/** Raw CDP response envelope. */
|
package/src/version.ts
CHANGED