@liyuera/dsh-chrome-browser 0.3.0 → 0.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +216 -10
- package/extension/manifest.json +4 -3
- package/extension/service-worker.js +721 -68
- package/lib/activity.d.ts +65 -0
- package/lib/activity.d.ts.map +1 -0
- package/lib/activity.js +111 -0
- package/lib/activity.js.map +1 -0
- package/lib/backend.d.ts +193 -11
- package/lib/backend.d.ts.map +1 -1
- package/lib/backend.js +344 -39
- package/lib/backend.js.map +1 -1
- package/lib/cdp.d.ts +7 -1
- package/lib/cdp.d.ts.map +1 -1
- package/lib/cdp.js +17 -1
- package/lib/cdp.js.map +1 -1
- package/lib/chrome.d.ts +8 -0
- package/lib/chrome.d.ts.map +1 -1
- package/lib/chrome.js +20 -0
- package/lib/chrome.js.map +1 -1
- package/lib/client/BrowserActivity.d.ts +22 -0
- package/lib/client/BrowserActivity.d.ts.map +1 -0
- package/lib/client/BrowserActivity.js +100 -0
- package/lib/client/BrowserActivity.js.map +1 -0
- package/lib/client/activity.d.ts +27 -0
- package/lib/client/activity.d.ts.map +1 -0
- package/lib/client/activity.js +57 -0
- package/lib/client/activity.js.map +1 -0
- package/lib/client/index.d.ts +4 -6
- package/lib/client/index.d.ts.map +1 -1
- package/lib/client/index.js +13 -19
- package/lib/client/index.js.map +1 -1
- package/lib/client/tab-catalog.d.ts +11 -1
- package/lib/client/tab-catalog.d.ts.map +1 -1
- package/lib/client/tab-catalog.js.map +1 -1
- package/lib/client/tab-source.d.ts +8 -2
- package/lib/client/tab-source.d.ts.map +1 -1
- package/lib/client/tab-source.js.map +1 -1
- package/lib/client.js +177 -13
- package/lib/client.js.map +1 -1
- package/lib/console-events.d.ts +32 -0
- package/lib/console-events.d.ts.map +1 -0
- package/lib/console-events.js +106 -0
- package/lib/console-events.js.map +1 -0
- package/lib/console-log.d.ts +107 -0
- package/lib/console-log.d.ts.map +1 -0
- package/lib/console-log.js +158 -0
- package/lib/console-log.js.map +1 -0
- package/lib/expressions.d.ts +71 -2
- package/lib/expressions.d.ts.map +1 -1
- package/lib/expressions.js +277 -14
- package/lib/expressions.js.map +1 -1
- package/lib/help.d.ts +89 -0
- package/lib/help.d.ts.map +1 -0
- package/lib/help.js +94 -0
- package/lib/help.js.map +1 -0
- package/lib/index.d.ts +4 -2
- package/lib/index.d.ts.map +1 -1
- package/lib/index.js +30 -9
- package/lib/index.js.map +1 -1
- package/lib/presentation.d.ts +130 -0
- package/lib/presentation.d.ts.map +1 -0
- package/lib/presentation.js +361 -0
- package/lib/presentation.js.map +1 -0
- package/lib/routes.d.ts +3 -8
- package/lib/routes.d.ts.map +1 -1
- package/lib/routes.js +20 -109
- package/lib/routes.js.map +1 -1
- package/lib/skill.d.ts +50 -0
- package/lib/skill.d.ts.map +1 -0
- package/lib/skill.js +163 -0
- package/lib/skill.js.map +1 -0
- package/lib/text.d.ts +21 -0
- package/lib/text.d.ts.map +1 -1
- package/lib/text.js +18 -0
- package/lib/text.js.map +1 -1
- package/lib/tools.d.ts +22 -4
- package/lib/tools.d.ts.map +1 -1
- package/lib/tools.js +467 -75
- package/lib/tools.js.map +1 -1
- package/lib/ws.d.ts +9 -2
- package/lib/ws.d.ts.map +1 -1
- package/lib/ws.js +49 -19
- package/lib/ws.js.map +1 -1
- package/package.json +4 -3
- package/lib/bindings.d.ts +0 -23
- package/lib/bindings.d.ts.map +0 -1
- package/lib/bindings.js +0 -49
- package/lib/bindings.js.map +0 -1
- package/lib/client/TabPicker.d.ts +0 -54
- package/lib/client/TabPicker.d.ts.map +0 -1
- package/lib/client/TabPicker.js +0 -329
- package/lib/client/TabPicker.js.map +0 -1
package/lib/tools.js
CHANGED
|
@@ -7,95 +7,217 @@
|
|
|
7
7
|
import { copyFileSync, mkdirSync, statSync, writeFileSync } from 'node:fs';
|
|
8
8
|
import { dirname, join } from 'node:path';
|
|
9
9
|
import { defineTool } from '@deepseek-ai/dsh-tools';
|
|
10
|
-
import {
|
|
10
|
+
import { clickCall, clickResult, closeCall, closeResult, consoleCall, consoleResult, evalCall, evalResult, helpCall, helpResult, hoverCall, hoverResult, navigateCall, navigateResult, openCall, openResult, pressCall, pressResult, readCall, readResult, screenshotCall, screenshotResult, selectCall, selectResult, tabsCall, tabsResult, typeCall, typeResult, waitCall, waitResult, } from "./presentation.js";
|
|
11
|
+
import { clipJson, clipText, normalizePageText, windowText } from "./text.js";
|
|
11
12
|
/** chrome_eval result serialization budget, characters. */
|
|
12
13
|
const EVAL_RESULT_LIMIT = 200_000;
|
|
14
|
+
/** `chrome_wait` bound when the caller names none. */
|
|
15
|
+
const DEFAULT_WAIT_MS = 10_000;
|
|
16
|
+
/** `chrome_wait` bound ceiling; a longer wait belongs in repeated calls, not one. */
|
|
17
|
+
const MAX_WAIT_MS = 300_000;
|
|
13
18
|
/** Generic JSON result rendering for every tool card. */
|
|
14
19
|
const render = (_args, value) => [
|
|
15
20
|
{ type: 'text', text: JSON.stringify(value, null, 2) },
|
|
16
21
|
];
|
|
17
|
-
/**
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
+
/**
|
|
23
|
+
* The executing agent itself, for routing a human question to its own UI. A
|
|
24
|
+
* delegated child cannot ask (the question service rejects it), so the value is
|
|
25
|
+
* forwarded as-is rather than guessed at.
|
|
26
|
+
*/
|
|
27
|
+
function agentOf(exec) {
|
|
28
|
+
return exec.agent;
|
|
22
29
|
}
|
|
23
30
|
/** Filesystem-safe tab id for screenshot names. */
|
|
24
31
|
function safeTabId(tabId) {
|
|
25
32
|
return tabId.replace(/[^0-9a-z_-]/gi, '_');
|
|
26
33
|
}
|
|
27
34
|
/**
|
|
28
|
-
*
|
|
29
|
-
*
|
|
35
|
+
* Why a dispatched click may not have taken effect. `element.click()` bypasses
|
|
36
|
+
* hit testing, so it fires on elements a real pointer could never reach; naming
|
|
37
|
+
* those cases is what stops a caller from reading "clicked" as "the page
|
|
38
|
+
* reacted".
|
|
39
|
+
* @param outcome - one click's counters.
|
|
40
|
+
* @returns one line per condition worth reporting; empty when every click
|
|
41
|
+
* landed on a visible, unobstructed, enabled element.
|
|
42
|
+
*/
|
|
43
|
+
export function clickWarnings(outcome) {
|
|
44
|
+
const warnings = [];
|
|
45
|
+
if (outcome.invisible > 0) {
|
|
46
|
+
warnings.push(`${outcome.invisible} clicked element(s) have no visible box (display:none, visibility:hidden or zero size);`
|
|
47
|
+
+ ' the page may have ignored the click');
|
|
48
|
+
}
|
|
49
|
+
if (outcome.offscreen > 0) {
|
|
50
|
+
warnings.push(`${outcome.offscreen} clicked element(s) lie outside the viewport;`
|
|
51
|
+
+ ' a real click would have scrolled them into view first');
|
|
52
|
+
}
|
|
53
|
+
if (outcome.covered > 0) {
|
|
54
|
+
warnings.push(`${outcome.covered} clicked element(s) are covered by another element at their centre;`
|
|
55
|
+
+ ' a real click would have landed on the covering element');
|
|
56
|
+
}
|
|
57
|
+
if (outcome.ariaDisabled > 0) {
|
|
58
|
+
warnings.push(`${outcome.ariaDisabled} clicked element(s) carry aria-disabled="true", which dispatches but asks consumers to ignore it`);
|
|
59
|
+
}
|
|
60
|
+
return warnings;
|
|
61
|
+
}
|
|
62
|
+
/**
|
|
63
|
+
* A tab's identity after its page loaded. `openTab` reports what the tab was at
|
|
64
|
+
* creation — usually an empty title — so a caller that waited for the load
|
|
65
|
+
* re-reads it. A listing failure falls back to the creation view rather than
|
|
66
|
+
* failing a call whose tab did open.
|
|
67
|
+
* @param backend - the live browser backend.
|
|
68
|
+
* @param opened - the tab as `openTab` returned it.
|
|
69
|
+
* @returns the listed tab, or `opened` when the tab is gone or unlistable.
|
|
70
|
+
*/
|
|
71
|
+
async function loadedTab(backend, opened) {
|
|
72
|
+
try {
|
|
73
|
+
const listed = await backend.listTabs();
|
|
74
|
+
return listed.find(candidate => candidate.id === opened.id) ?? opened;
|
|
75
|
+
}
|
|
76
|
+
catch {
|
|
77
|
+
// The follow-up lookup is a nicety; the tab itself already opened.
|
|
78
|
+
return opened;
|
|
79
|
+
}
|
|
80
|
+
}
|
|
81
|
+
/** URL schemes the plugin can drive a page on: it injects scripts into what it opens. */
|
|
82
|
+
const OPERABLE_URL_SCHEMES = new Set(['http:', 'https:', 'file:']);
|
|
83
|
+
/**
|
|
84
|
+
* Reject a URL the plugin cannot operate on, before a tab exists for it.
|
|
85
|
+
*
|
|
86
|
+
* `chrome_open` used to create the tab first and fail afterwards: a `data:` URL
|
|
87
|
+
* produced a tab that no tool could read, evaluate, click or even navigate away
|
|
88
|
+
* from, because the extension's host permissions do not cover that scheme. The
|
|
89
|
+
* caller gets the reason instead of a dead tab.
|
|
90
|
+
* @param tool - the tool name, for the error message.
|
|
91
|
+
* @param url - the requested URL.
|
|
30
92
|
*/
|
|
31
|
-
|
|
93
|
+
function assertOperableUrl(tool, url) {
|
|
94
|
+
if (url === '' || url === 'about:blank')
|
|
95
|
+
return;
|
|
96
|
+
let parsed;
|
|
97
|
+
try {
|
|
98
|
+
parsed = new URL(url);
|
|
99
|
+
}
|
|
100
|
+
catch {
|
|
101
|
+
throw new Error(`${tool}: "${url}" is not a valid URL`);
|
|
102
|
+
}
|
|
103
|
+
if (OPERABLE_URL_SCHEMES.has(parsed.protocol))
|
|
104
|
+
return;
|
|
105
|
+
throw new Error(`${tool}: cannot drive a ${parsed.protocol} URL — the plugin injects scripts into the page, which needs `
|
|
106
|
+
+ 'an http, https or file page. Use a real URL, or about:blank.');
|
|
107
|
+
}
|
|
108
|
+
/** Extensions that name an image format, as opposed to any other file name. */
|
|
109
|
+
const IMAGE_EXTENSIONS = new Set(['png', 'jpg', 'jpeg', 'webp', 'gif', 'bmp', 'tif', 'tiff']);
|
|
110
|
+
/**
|
|
111
|
+
* Keep the caller's path but never let its extension contradict the bytes.
|
|
112
|
+
*
|
|
113
|
+
* The two backends produce different formats — PNG over CDP, JPEG over the
|
|
114
|
+
* extension bridge — so a caller who asks for `shot.png` on the bridge would
|
|
115
|
+
* otherwise get a JPEG that readers trusting the name refuse to open. A path
|
|
116
|
+
* with no extension, or one this does not recognise, is left exactly as asked.
|
|
117
|
+
* @param path - the caller's requested output path.
|
|
118
|
+
* @param ext - the extension matching the bytes actually written.
|
|
119
|
+
* @returns the path to write, with the extension corrected when it disagrees.
|
|
120
|
+
*/
|
|
121
|
+
function imagePath(path, ext) {
|
|
122
|
+
const match = /\.([A-Za-z0-9]+)$/u.exec(path);
|
|
123
|
+
if (match === null)
|
|
124
|
+
return path;
|
|
125
|
+
const found = match[1].toLowerCase();
|
|
126
|
+
if (!IMAGE_EXTENSIONS.has(found) || found === ext)
|
|
127
|
+
return path;
|
|
128
|
+
return `${path.slice(0, match.index)}.${ext}`;
|
|
129
|
+
}
|
|
130
|
+
/**
|
|
131
|
+
* Resolve the tab a tool operates on: an explicit id wins, and anything else —
|
|
132
|
+
* an omitted id or the literal `active` — means the tab the user is looking at.
|
|
133
|
+
*
|
|
134
|
+
* There is no session binding to fall back to: the `@` menu inserts a reference
|
|
135
|
+
* chip and binds nothing, and the chip's `tabId` arrives in the injected context.
|
|
136
|
+
*/
|
|
137
|
+
async function resolveTabId(backend, exec, tabId) {
|
|
32
138
|
if (tabId !== undefined && tabId !== '' && tabId !== 'active')
|
|
33
139
|
return tabId;
|
|
34
|
-
|
|
35
|
-
if (tabId !== 'active' && sessionId !== undefined) {
|
|
36
|
-
const bound = bindings.get(sessionId);
|
|
37
|
-
if (bound !== undefined) {
|
|
38
|
-
const tabs = await backend.listTabs();
|
|
39
|
-
if (tabs.some(tab => tab.id === bound))
|
|
40
|
-
return bound;
|
|
41
|
-
}
|
|
42
|
-
}
|
|
140
|
+
void exec;
|
|
43
141
|
return backend.activeTabId();
|
|
44
142
|
}
|
|
45
|
-
/**
|
|
46
|
-
|
|
143
|
+
/**
|
|
144
|
+
* Build every chrome-browser tool definition bound to one backend.
|
|
145
|
+
* @param backend - the live browser backend.
|
|
146
|
+
* @param config - the resolved plugin configuration.
|
|
147
|
+
* @param consoleLog - the bounded console buffer `chrome_console` reads.
|
|
148
|
+
* @param help - the human-help channel `chrome_request_help` speaks to.
|
|
149
|
+
* @returns the tool definitions in registration order.
|
|
150
|
+
*/
|
|
151
|
+
export function chromeToolDefinitions(backend, config, consoleLog, help) {
|
|
47
152
|
return [
|
|
48
153
|
defineTool({
|
|
49
154
|
name: 'chrome_tabs',
|
|
50
155
|
description: 'List the tabs currently open in the Chrome instance the browser plugin controls: id, title, url, active and '
|
|
51
|
-
+ 'favicon
|
|
52
|
-
+ '
|
|
53
|
-
+ 'tabId to use the first session-selected tab, or "active" for the active tab.',
|
|
156
|
+
+ 'favicon. Get a tab id first, then pass it to every other chrome_* tool; omitting tabId (or passing '
|
|
157
|
+
+ '"active") means the tab the user is looking at, which is rarely the one a request names.',
|
|
54
158
|
parameters: {},
|
|
55
159
|
output: { schema: { type: 'json' }, render },
|
|
160
|
+
isConcurrencySafe: () => true,
|
|
161
|
+
presentCall: () => tabsCall(),
|
|
162
|
+
presentResult: (_args, outcome) => tabsResult(outcome),
|
|
56
163
|
execute: async (_args, _exec) => {
|
|
57
164
|
const tabs = await backend.listTabs();
|
|
58
|
-
|
|
59
|
-
const sessionId = sessionIdOf(_exec);
|
|
60
|
-
if (sessionId !== undefined) {
|
|
61
|
-
const boundIds = bindings.all(sessionId);
|
|
62
|
-
if (boundIds.length > 0) {
|
|
63
|
-
const picked = boundIds
|
|
64
|
-
.map(id => tabs.find(candidate => candidate.id === id))
|
|
65
|
-
.filter((tab) => tab !== undefined);
|
|
66
|
-
if (picked.length > 0) {
|
|
67
|
-
session = {
|
|
68
|
-
tabIds: picked.map(tab => tab.id),
|
|
69
|
-
tabs: picked.map(tab => ({ id: tab.id, title: tab.title, url: tab.url })),
|
|
70
|
-
};
|
|
71
|
-
}
|
|
72
|
-
}
|
|
73
|
-
}
|
|
74
|
-
return { tabs, session };
|
|
165
|
+
return { tabs };
|
|
75
166
|
},
|
|
76
167
|
}),
|
|
77
168
|
defineTool({
|
|
78
169
|
name: 'chrome_read',
|
|
79
|
-
description: 'Read one tab
|
|
80
|
-
+ '
|
|
170
|
+
description: 'Read one tab. mode="text" (the default) returns the page title, url and visible text: the text is a window '
|
|
171
|
+
+ 'of readTextLimit code points (default 30000) starting at `offset`, textChars reports the whole document, '
|
|
172
|
+
+ 'and a truncated window carries `nextOffset` to continue from. mode="interactive" instead lists the '
|
|
173
|
+
+ 'elements a reader can act on — each with a ready-to-use `selector`, its role and name, and whether it is '
|
|
174
|
+
+ '`inView`, `disabled` or `covered` by something else. Prefer mode="interactive" before clicking or typing: '
|
|
175
|
+
+ 'it is far smaller than the page text and answers "what can I act on, and will it work".',
|
|
81
176
|
parameters: {
|
|
82
|
-
tabId: { type: 'string', description: "Tab id from chrome_tabs
|
|
83
|
-
|
|
177
|
+
tabId: { type: 'string', description: "Tab id from chrome_tabs, or 'active' for the tab the user is looking at; omitting it means 'active' too." },
|
|
178
|
+
mode: {
|
|
179
|
+
type: 'string',
|
|
180
|
+
enum: ['text', 'interactive'],
|
|
181
|
+
description: '"text" (default) reads the page text; "interactive" lists actionable elements with their state.',
|
|
182
|
+
},
|
|
183
|
+
offset: { type: 'integer', description: 'Text mode: code points to skip before the window; pass the `nextOffset` a truncated read returned to continue.' },
|
|
184
|
+
includeHtml: { type: 'boolean', description: 'Text mode: also return the page HTML, clipped to the same budget.' },
|
|
84
185
|
},
|
|
85
186
|
output: { schema: { type: 'json' }, render },
|
|
187
|
+
isConcurrencySafe: () => true,
|
|
188
|
+
presentCall: args => readCall(args),
|
|
189
|
+
presentResult: (_args, outcome) => readResult(outcome),
|
|
86
190
|
execute: async (args, _exec) => {
|
|
87
|
-
const tabId = await resolveTabId(backend,
|
|
191
|
+
const tabId = await resolveTabId(backend, _exec, args.tabId);
|
|
192
|
+
if (args.mode === 'interactive') {
|
|
193
|
+
const inventory = await backend.inventory(tabId);
|
|
194
|
+
return {
|
|
195
|
+
tabId,
|
|
196
|
+
mode: 'interactive',
|
|
197
|
+
title: inventory.title,
|
|
198
|
+
url: inventory.url,
|
|
199
|
+
matched: inventory.matched,
|
|
200
|
+
shown: inventory.items.length,
|
|
201
|
+
items: inventory.items,
|
|
202
|
+
};
|
|
203
|
+
}
|
|
88
204
|
const value = await backend.read(tabId, args.includeHtml === true);
|
|
89
205
|
const rawText = normalizePageText(value.text);
|
|
90
|
-
const
|
|
206
|
+
const window = windowText(rawText, args.offset ?? 0, config.readTextLimit);
|
|
91
207
|
const html = args.includeHtml === true ? clipText(value.html, config.readTextLimit) : undefined;
|
|
92
208
|
return {
|
|
93
209
|
tabId,
|
|
210
|
+
mode: 'text',
|
|
94
211
|
title: value.title,
|
|
95
212
|
url: value.url,
|
|
96
|
-
text:
|
|
97
|
-
|
|
98
|
-
|
|
213
|
+
text: window.nextOffset === undefined
|
|
214
|
+
? window.text
|
|
215
|
+
: `${window.text}\n…[window ${window.offset}-${window.nextOffset} of ${window.total} code points;`
|
|
216
|
+
+ ` pass offset=${window.nextOffset} for the rest]`,
|
|
217
|
+
textChars: window.total,
|
|
218
|
+
offset: window.offset,
|
|
219
|
+
textTruncated: window.nextOffset !== undefined,
|
|
220
|
+
...(window.nextOffset === undefined ? {} : { nextOffset: window.nextOffset }),
|
|
99
221
|
...(html === undefined ? {} : { html }),
|
|
100
222
|
};
|
|
101
223
|
},
|
|
@@ -104,44 +226,91 @@ export function chromeToolDefinitions(backend, config, bindings) {
|
|
|
104
226
|
name: 'chrome_navigate',
|
|
105
227
|
description: 'Navigate one tab to a URL. By default waits until the page reaches readyState "complete" (up to waitLoadMs).',
|
|
106
228
|
parameters: {
|
|
107
|
-
url: {
|
|
108
|
-
|
|
229
|
+
url: {
|
|
230
|
+
type: 'string',
|
|
231
|
+
required: true,
|
|
232
|
+
description: 'Target URL, e.g. https://example.com. http(s) and file only; a file: URL also needs the '
|
|
233
|
+
+ 'extension to be granted file access in chrome://extensions.',
|
|
234
|
+
},
|
|
235
|
+
tabId: { type: 'string', description: "Tab id from chrome_tabs, or 'active' for the tab the user is looking at; omitting it means 'active' too." },
|
|
109
236
|
waitLoad: { type: 'boolean', description: 'Wait for load completion (default true).' },
|
|
110
237
|
},
|
|
111
238
|
output: { schema: { type: 'json' }, render },
|
|
239
|
+
presentCall: args => navigateCall(args),
|
|
240
|
+
presentResult: (_args, outcome) => navigateResult(outcome),
|
|
112
241
|
execute: async (args, _exec) => {
|
|
113
|
-
|
|
242
|
+
assertOperableUrl('chrome_navigate', args.url);
|
|
243
|
+
const tabId = await resolveTabId(backend, _exec, args.tabId);
|
|
114
244
|
await backend.navigate(tabId, args.url, args.waitLoad !== false, config.waitLoadMs);
|
|
115
245
|
return { tabId, url: args.url };
|
|
116
246
|
},
|
|
117
247
|
}),
|
|
118
248
|
defineTool({
|
|
119
249
|
name: 'chrome_open',
|
|
120
|
-
description: 'Open a new foreground tab.
|
|
250
|
+
description: 'Open a new foreground tab. By default waits until the tab reports readyState "complete" (up to waitLoadMs) '
|
|
251
|
+
+ 'before returning, so the returned title is the loaded page\'s and a following chrome_read sees the '
|
|
252
|
+
+ 'document; pass waitLoad=false to return as soon as the tab exists.',
|
|
121
253
|
parameters: {
|
|
122
|
-
url: {
|
|
254
|
+
url: {
|
|
255
|
+
type: 'string',
|
|
256
|
+
description: 'URL to open; defaults to about:blank. http(s) and file only — a file: URL also needs '
|
|
257
|
+
+ 'the extension to be granted file access in chrome://extensions, or the page will be unreadable.',
|
|
258
|
+
},
|
|
259
|
+
waitLoad: { type: 'boolean', description: 'Wait for load completion (default true).' },
|
|
260
|
+
},
|
|
261
|
+
output: { schema: { type: 'json' }, render },
|
|
262
|
+
presentCall: args => openCall(args),
|
|
263
|
+
presentResult: (_args, outcome) => openResult(outcome),
|
|
264
|
+
execute: async (args, _exec) => {
|
|
265
|
+
assertOperableUrl('chrome_open', args.url ?? 'about:blank');
|
|
266
|
+
const opened = await backend.openTab(args.url ?? 'about:blank');
|
|
267
|
+
if (args.waitLoad === false) {
|
|
268
|
+
return { tabId: opened.id, title: opened.title, url: opened.url };
|
|
269
|
+
}
|
|
270
|
+
await backend.waitForLoad(opened.id, config.waitLoadMs);
|
|
271
|
+
const loaded = await loadedTab(backend, opened);
|
|
272
|
+
return { tabId: loaded.id, title: loaded.title, url: loaded.url };
|
|
273
|
+
},
|
|
274
|
+
}),
|
|
275
|
+
defineTool({
|
|
276
|
+
name: 'chrome_close',
|
|
277
|
+
description: 'Close one tab by id. Closing the last tab of a window closes that window. `tabId` is required and '
|
|
278
|
+
+ 'must be a real id from chrome_tabs: this never falls back to the active tab, because the tab the '
|
|
279
|
+
+ 'user is looking at is rarely the one worth closing. Close what you opened.',
|
|
280
|
+
parameters: {
|
|
281
|
+
tabId: { type: 'string', required: true, description: 'Exact tab id from chrome_tabs.' },
|
|
123
282
|
},
|
|
124
283
|
output: { schema: { type: 'json' }, render },
|
|
284
|
+
presentCall: args => closeCall(args),
|
|
285
|
+
presentResult: (_args, outcome) => closeResult(outcome),
|
|
125
286
|
execute: async (args, _exec) => {
|
|
126
|
-
const
|
|
127
|
-
|
|
287
|
+
const tabId = args.tabId;
|
|
288
|
+
if (tabId === undefined || tabId === '' || tabId === 'active') {
|
|
289
|
+
throw new Error('chrome_close: tabId must be an exact tab id from chrome_tabs; it never defaults to the active tab');
|
|
290
|
+
}
|
|
291
|
+
await backend.closeTab(tabId);
|
|
292
|
+
return { tabId, closed: true };
|
|
128
293
|
},
|
|
129
294
|
}),
|
|
130
295
|
defineTool({
|
|
131
296
|
name: 'chrome_screenshot',
|
|
132
|
-
description: 'Capture one tab
|
|
133
|
-
+ '
|
|
297
|
+
description: 'Capture one tab to an image file on the host and return its path (plus bytes and the `mime`). The format '
|
|
298
|
+
+ 'depends on the connection — PNG over CDP, JPEG over the extension bridge — so a `.png` a caller asks for '
|
|
299
|
+
+ 'becomes `.jpg` rather than a JPEG named `.png`. Use the read_image tool on the returned path to view the '
|
|
300
|
+
+ 'page visually.',
|
|
134
301
|
parameters: {
|
|
135
|
-
tabId: { type: 'string', description: "Tab id from chrome_tabs
|
|
302
|
+
tabId: { type: 'string', description: "Tab id from chrome_tabs, or 'active' for the tab the user is looking at; omitting it means 'active' too." },
|
|
136
303
|
path: { type: 'string', description: 'Optional output file path; defaults to <screenshotDir>/<timestamp>-<tabId>.png.' },
|
|
137
304
|
},
|
|
138
305
|
output: { schema: { type: 'json' }, render },
|
|
306
|
+
presentCall: args => screenshotCall(args),
|
|
307
|
+
presentResult: (_args, outcome) => screenshotResult(outcome),
|
|
139
308
|
execute: async (args, _exec) => {
|
|
140
|
-
const tabId = await resolveTabId(backend,
|
|
309
|
+
const tabId = await resolveTabId(backend, _exec, args.tabId);
|
|
141
310
|
const shot = await backend.screenshot(tabId);
|
|
142
311
|
const ext = shot.mime === 'image/jpeg' ? 'jpg' : 'png';
|
|
143
312
|
const path = typeof args.path === 'string' && args.path !== ''
|
|
144
|
-
? args.path
|
|
313
|
+
? imagePath(args.path, ext)
|
|
145
314
|
: join(config.screenshotDir, `${Date.now()}-${safeTabId(tabId)}.${ext}`);
|
|
146
315
|
mkdirSync(dirname(path), { recursive: true });
|
|
147
316
|
let bytes = 0;
|
|
@@ -157,26 +326,68 @@ export function chromeToolDefinitions(backend, config, bindings) {
|
|
|
157
326
|
writeFileSync(path, buffer);
|
|
158
327
|
bytes = buffer.length;
|
|
159
328
|
}
|
|
160
|
-
return {
|
|
329
|
+
return {
|
|
330
|
+
path,
|
|
331
|
+
bytes,
|
|
332
|
+
mime: shot.mime ?? (ext === 'jpg' ? 'image/jpeg' : 'image/png'),
|
|
333
|
+
tabId,
|
|
334
|
+
};
|
|
161
335
|
},
|
|
162
336
|
}),
|
|
163
337
|
defineTool({
|
|
164
338
|
name: 'chrome_click',
|
|
165
|
-
description: 'Click elements matching a CSS selector in one tab
|
|
166
|
-
+ '
|
|
167
|
-
+ '
|
|
339
|
+
description: 'Click elements matching a CSS selector in one tab, through the page\'s own element.click(). Click the first '
|
|
340
|
+
+ 'match by default, or every match with all=true. `clicked` counts elements that received a dispatched click '
|
|
341
|
+
+ 'event, and `matched` counts what the selector found — a dispatched click is NOT evidence the page reacted, '
|
|
342
|
+
+ 'so read `warnings` when the page looks unchanged: they name elements that are hidden, outside the viewport, '
|
|
343
|
+
+ 'covered by another element, or marked aria-disabled. Throws when nothing matches, or when every match is '
|
|
344
|
+
+ 'natively disabled. Prefer this for buttons/links; use chrome_eval for interactions that need more.',
|
|
168
345
|
parameters: {
|
|
169
346
|
selector: { type: 'string', required: true, description: 'CSS selector, e.g. "#submit" or "a.download".' },
|
|
170
|
-
tabId: { type: 'string', description: "Tab id from chrome_tabs
|
|
347
|
+
tabId: { type: 'string', description: "Tab id from chrome_tabs, or 'active' for the tab the user is looking at; omitting it means 'active' too." },
|
|
171
348
|
all: { type: 'boolean', description: 'Click every matching element (default false: first match only).' },
|
|
172
349
|
},
|
|
173
350
|
output: { schema: { type: 'json' }, render },
|
|
351
|
+
presentCall: args => clickCall(args),
|
|
352
|
+
presentResult: (_args, outcome) => clickResult(outcome),
|
|
174
353
|
execute: async (args, _exec) => {
|
|
175
|
-
const tabId = await resolveTabId(backend,
|
|
176
|
-
const
|
|
177
|
-
if (
|
|
354
|
+
const tabId = await resolveTabId(backend, _exec, args.tabId);
|
|
355
|
+
const outcome = await backend.click(tabId, args.selector, args.all === true);
|
|
356
|
+
if (outcome.matched === 0)
|
|
178
357
|
throw new Error(`chrome_click: no element matched selector "${args.selector}"`);
|
|
179
|
-
|
|
358
|
+
if (outcome.clicked === 0) {
|
|
359
|
+
throw new Error(`chrome_click: selector "${args.selector}" matched ${outcome.matched} element(s), but none was clicked`
|
|
360
|
+
+ ` (${outcome.disabled} natively disabled); the page did not change`);
|
|
361
|
+
}
|
|
362
|
+
const warnings = clickWarnings(outcome);
|
|
363
|
+
return {
|
|
364
|
+
tabId,
|
|
365
|
+
selector: args.selector,
|
|
366
|
+
clicked: outcome.clicked,
|
|
367
|
+
matched: outcome.matched,
|
|
368
|
+
...(warnings.length === 0 ? {} : { warnings }),
|
|
369
|
+
};
|
|
370
|
+
},
|
|
371
|
+
}),
|
|
372
|
+
defineTool({
|
|
373
|
+
name: 'chrome_hover',
|
|
374
|
+
description: 'Hover the first element matching a CSS selector in one tab, to reveal UI that only appears on hover '
|
|
375
|
+
+ '(menus, tooltips, action rows). The events are synthetic, so they reach the listeners the page attached '
|
|
376
|
+
+ 'but do not set the browser\'s own hover state: a control revealed purely by a CSS :hover rule may stay '
|
|
377
|
+
+ 'hidden. Follow it with chrome_read mode="interactive" to see what appeared.',
|
|
378
|
+
parameters: {
|
|
379
|
+
selector: { type: 'string', required: true, description: 'CSS selector to hover, e.g. "#menu" or "[aria-label=More]".' },
|
|
380
|
+
tabId: { type: 'string', description: "Tab id from chrome_tabs, or 'active' for the tab the user is looking at; omitting it means 'active' too." },
|
|
381
|
+
},
|
|
382
|
+
output: { schema: { type: 'json' }, render },
|
|
383
|
+
presentCall: args => hoverCall(args),
|
|
384
|
+
presentResult: (_args, outcome) => hoverResult(outcome),
|
|
385
|
+
execute: async (args, _exec) => {
|
|
386
|
+
const tabId = await resolveTabId(backend, _exec, args.tabId);
|
|
387
|
+
const outcome = await backend.hover(tabId, args.selector);
|
|
388
|
+
if (outcome.matched === 0)
|
|
389
|
+
throw new Error(`chrome_hover: no element matched selector "${args.selector}"`);
|
|
390
|
+
return { tabId, selector: args.selector, hovered: outcome.hovered };
|
|
180
391
|
},
|
|
181
392
|
}),
|
|
182
393
|
defineTool({
|
|
@@ -187,17 +398,78 @@ export function chromeToolDefinitions(backend, config, bindings) {
|
|
|
187
398
|
parameters: {
|
|
188
399
|
selector: { type: 'string', required: true, description: 'CSS selector of the input/textarea/editable element.' },
|
|
189
400
|
text: { type: 'string', required: true, description: 'Text to insert.' },
|
|
190
|
-
tabId: { type: 'string', description: "Tab id from chrome_tabs
|
|
401
|
+
tabId: { type: 'string', description: "Tab id from chrome_tabs, or 'active' for the tab the user is looking at; omitting it means 'active' too." },
|
|
191
402
|
clear: { type: 'boolean', description: 'Select existing content first so the text replaces it (default true).' },
|
|
192
403
|
},
|
|
193
404
|
output: { schema: { type: 'json' }, render },
|
|
405
|
+
presentCall: args => typeCall(args),
|
|
406
|
+
presentResult: (_args, outcome) => typeResult(outcome),
|
|
194
407
|
execute: async (args, _exec) => {
|
|
195
|
-
const tabId = await resolveTabId(backend,
|
|
408
|
+
const tabId = await resolveTabId(backend, _exec, args.tabId);
|
|
196
409
|
const cleared = args.clear !== false;
|
|
197
410
|
await backend.type(tabId, args.selector, args.text, cleared);
|
|
198
411
|
return { tabId, selector: args.selector, text: args.text, cleared };
|
|
199
412
|
},
|
|
200
413
|
}),
|
|
414
|
+
defineTool({
|
|
415
|
+
name: 'chrome_press',
|
|
416
|
+
description: 'Press one key in a tab, optionally focusing a CSS selector first: Enter to submit, Escape to close a dialog, '
|
|
417
|
+
+ 'Tab or an arrow key to move through a menu. The events are synthetic, so the browser performs no default '
|
|
418
|
+
+ 'action — for Enter the owning form is submitted explicitly and `submitted: true` says that happened. A key '
|
|
419
|
+
+ 'that only moves focus or closes an overlay reports `submitted: false` and changes nothing else.',
|
|
420
|
+
parameters: {
|
|
421
|
+
key: { type: 'string', required: true, description: 'KeyboardEvent.key value, e.g. "Enter", "Escape", "Tab", "ArrowDown".' },
|
|
422
|
+
selector: { type: 'string', description: 'Focus this element first; omit to press on whatever currently has focus.' },
|
|
423
|
+
tabId: { type: 'string', description: "Tab id from chrome_tabs, or 'active' for the tab the user is looking at; omitting it means 'active' too." },
|
|
424
|
+
},
|
|
425
|
+
output: { schema: { type: 'json' }, render },
|
|
426
|
+
presentCall: args => pressCall(args),
|
|
427
|
+
presentResult: (_args, outcome) => pressResult(outcome),
|
|
428
|
+
execute: async (args, _exec) => {
|
|
429
|
+
const tabId = await resolveTabId(backend, _exec, args.tabId);
|
|
430
|
+
const outcome = await backend.press(tabId, args.key, args.selector);
|
|
431
|
+
if (!outcome.found) {
|
|
432
|
+
throw new Error(`chrome_press: no element matched selector "${args.selector ?? ''}" to focus`);
|
|
433
|
+
}
|
|
434
|
+
return {
|
|
435
|
+
tabId,
|
|
436
|
+
key: args.key,
|
|
437
|
+
selector: args.selector ?? null,
|
|
438
|
+
pressed: outcome.pressed,
|
|
439
|
+
submitted: outcome.submitted,
|
|
440
|
+
};
|
|
441
|
+
},
|
|
442
|
+
}),
|
|
443
|
+
defineTool({
|
|
444
|
+
name: 'chrome_select',
|
|
445
|
+
description: 'Choose an option in a <select> by its option VALUE, not its visible label. Sets the value through the '
|
|
446
|
+
+ 'prototype setter and fires input/change so controlled components update. Throws when the value is not one '
|
|
447
|
+
+ 'of the options, listing the values that are — read them from the error rather than guessing again.',
|
|
448
|
+
parameters: {
|
|
449
|
+
selector: { type: 'string', required: true, description: 'CSS selector for the <select> element.' },
|
|
450
|
+
value: { type: 'string', required: true, description: 'Option value to select (the value attribute, not the label).' },
|
|
451
|
+
tabId: { type: 'string', description: "Tab id from chrome_tabs, or 'active' for the tab the user is looking at; omitting it means 'active' too." },
|
|
452
|
+
},
|
|
453
|
+
output: { schema: { type: 'json' }, render },
|
|
454
|
+
presentCall: args => selectCall(args),
|
|
455
|
+
presentResult: (_args, outcome) => selectResult(outcome),
|
|
456
|
+
execute: async (args, _exec) => {
|
|
457
|
+
const tabId = await resolveTabId(backend, _exec, args.tabId);
|
|
458
|
+
const outcome = await backend.select(tabId, args.selector, args.value);
|
|
459
|
+
if (outcome.matched === 0) {
|
|
460
|
+
throw new Error(`chrome_select: no element matched selector "${args.selector}"`);
|
|
461
|
+
}
|
|
462
|
+
if (outcome.reason !== undefined) {
|
|
463
|
+
throw new Error(`chrome_select: "${args.selector}" is ${outcome.reason}; use chrome_type for text inputs`
|
|
464
|
+
+ ' or chrome_click for custom dropdowns');
|
|
465
|
+
}
|
|
466
|
+
if (!outcome.changed) {
|
|
467
|
+
const available = outcome.options.length === 0 ? '(the control has no options)' : outcome.options.join(', ');
|
|
468
|
+
throw new Error(`chrome_select: "${args.selector}" has no option with value "${args.value}"; available values: ${available}`);
|
|
469
|
+
}
|
|
470
|
+
return { tabId, selector: args.selector, value: outcome.value };
|
|
471
|
+
},
|
|
472
|
+
}),
|
|
201
473
|
defineTool({
|
|
202
474
|
name: 'chrome_eval',
|
|
203
475
|
description: 'Evaluate a JavaScript expression in one tab\'s page context and return its value as JSON text '
|
|
@@ -205,13 +477,133 @@ export function chromeToolDefinitions(backend, config, bindings) {
|
|
|
205
477
|
+ 'serialized by value. Example: document.querySelectorAll("a").length.',
|
|
206
478
|
parameters: {
|
|
207
479
|
expression: { type: 'string', required: true, description: 'JavaScript expression to evaluate in the page.' },
|
|
208
|
-
tabId: { type: 'string', description: "Tab id from chrome_tabs
|
|
480
|
+
tabId: { type: 'string', description: "Tab id from chrome_tabs, or 'active' for the tab the user is looking at; omitting it means 'active' too." },
|
|
209
481
|
},
|
|
210
482
|
output: { schema: { type: 'json' }, render },
|
|
483
|
+
presentCall: args => evalCall(args),
|
|
484
|
+
presentResult: (_args, outcome) => evalResult(outcome),
|
|
211
485
|
execute: async (args, _exec) => {
|
|
212
|
-
const tabId = await resolveTabId(backend,
|
|
486
|
+
const tabId = await resolveTabId(backend, _exec, args.tabId);
|
|
213
487
|
const value = await backend.evaluate(tabId, args.expression);
|
|
214
|
-
return {
|
|
488
|
+
return {
|
|
489
|
+
tabId,
|
|
490
|
+
value: clipJson(value, EVAL_RESULT_LIMIT),
|
|
491
|
+
// Absent on the normal route; present when the page's CSP forced the
|
|
492
|
+
// expression through the debugger protocol instead.
|
|
493
|
+
...(backend.lastEvalWorld === 'debugger' ? { world: 'debugger' } : {}),
|
|
494
|
+
};
|
|
495
|
+
},
|
|
496
|
+
}),
|
|
497
|
+
defineTool({
|
|
498
|
+
name: 'chrome_wait',
|
|
499
|
+
description: 'Wait for an element condition in one tab before acting on it — the way to handle a page that renders '
|
|
500
|
+
+ 'asynchronously, instead of reading too early. `state` defaults to "visible"; "hidden" also covers an '
|
|
501
|
+
+ 'element that is absent. The result says `satisfied`: **false means the timeout passed, not that the wait '
|
|
502
|
+
+ 'succeeded** — check it before assuming the page is ready.',
|
|
503
|
+
parameters: {
|
|
504
|
+
selector: { type: 'string', required: true, description: 'CSS selector to wait for.' },
|
|
505
|
+
state: {
|
|
506
|
+
type: 'string',
|
|
507
|
+
enum: ['visible', 'hidden', 'attached', 'detached'],
|
|
508
|
+
description: '"visible" (default): present with a layout box and not hidden. "hidden": absent or not shown. "attached"/"detached": presence only.',
|
|
509
|
+
},
|
|
510
|
+
timeoutMs: { type: 'integer', description: 'How long to wait (default 10000ms; max 300000).' },
|
|
511
|
+
tabId: { type: 'string', description: "Tab id from chrome_tabs, or 'active' for the tab the user is looking at; omitting it means 'active' too." },
|
|
512
|
+
},
|
|
513
|
+
output: { schema: { type: 'json' }, render },
|
|
514
|
+
presentCall: args => waitCall(args),
|
|
515
|
+
presentResult: (_args, outcome) => waitResult(outcome),
|
|
516
|
+
execute: async (args, _exec) => {
|
|
517
|
+
const tabId = await resolveTabId(backend, _exec, args.tabId);
|
|
518
|
+
const state = args.state === 'hidden' || args.state === 'attached' || args.state === 'detached'
|
|
519
|
+
? args.state
|
|
520
|
+
: 'visible';
|
|
521
|
+
const timeoutMs = Math.min(Math.max(args.timeoutMs ?? DEFAULT_WAIT_MS, 0), MAX_WAIT_MS);
|
|
522
|
+
const started = Date.now();
|
|
523
|
+
const satisfied = await backend.waitFor(tabId, args.selector, state, timeoutMs);
|
|
524
|
+
return {
|
|
525
|
+
tabId,
|
|
526
|
+
selector: args.selector,
|
|
527
|
+
state,
|
|
528
|
+
satisfied,
|
|
529
|
+
elapsedMs: Date.now() - started,
|
|
530
|
+
};
|
|
531
|
+
},
|
|
532
|
+
}),
|
|
533
|
+
defineTool({
|
|
534
|
+
name: 'chrome_request_help',
|
|
535
|
+
description: 'Ask the user to do a step only they can do — sign in, solve a CAPTCHA, approve a prompt, finish 2FA — and '
|
|
536
|
+
+ 'wait until they answer. Use it instead of guessing at a login wall or retrying a page you cannot get '
|
|
537
|
+
+ 'past. `completed: false` means they declined or dismissed it: stop that line of work rather than trying '
|
|
538
|
+
+ 'again. After `completed: true`, re-read the page to see the new state before continuing.',
|
|
539
|
+
parameters: {
|
|
540
|
+
reason: {
|
|
541
|
+
type: 'string',
|
|
542
|
+
required: true,
|
|
543
|
+
description: 'What the user must do, in their own language, naming the page or site so they know where to look.',
|
|
544
|
+
},
|
|
545
|
+
},
|
|
546
|
+
output: { schema: { type: 'json' }, render },
|
|
547
|
+
presentCall: args => helpCall(args),
|
|
548
|
+
presentResult: (_args, outcome) => helpResult(outcome),
|
|
549
|
+
execute: async (args, _exec) => {
|
|
550
|
+
const outcome = await help.request(args.reason, agentOf(_exec));
|
|
551
|
+
return {
|
|
552
|
+
completed: outcome.completed,
|
|
553
|
+
...(outcome.note === undefined ? {} : { note: outcome.note }),
|
|
554
|
+
};
|
|
555
|
+
},
|
|
556
|
+
}),
|
|
557
|
+
defineTool({
|
|
558
|
+
name: 'chrome_console',
|
|
559
|
+
description: 'Read the JavaScript console of one tab. Capture must be running BEFORE the page does the thing you want to '
|
|
560
|
+
+ 'observe, because nothing is recorded retroactively: action=start attaches the debugger and buffers (Chrome '
|
|
561
|
+
+ 'shows a "debugging this browser" bar on that tab until action=stop), action=read returns entries after '
|
|
562
|
+
+ '`since` together with a `cursor` to pass as the next `since`, and action=stop ends capture and drops the '
|
|
563
|
+
+ 'buffer. Browser-raised messages (failed requests, CSP refusals, deprecations) are included — a wrapper '
|
|
564
|
+
+ 'around console() would miss them. The buffer is bounded per tab and never written to the session log; '
|
|
565
|
+
+ '`dropped` counts entries evicted before you read them.',
|
|
566
|
+
parameters: {
|
|
567
|
+
action: {
|
|
568
|
+
type: 'string',
|
|
569
|
+
required: true,
|
|
570
|
+
enum: ['start', 'stop', 'read'],
|
|
571
|
+
description: 'start capture, read entries, or stop and drop the buffer.',
|
|
572
|
+
},
|
|
573
|
+
tabId: { type: 'string', description: "Tab id from chrome_tabs, or 'active' for the tab the user is looking at; omitting it means 'active' too." },
|
|
574
|
+
since: { type: 'integer', description: 'Read: return entries whose sequence number is greater than this cursor (default 0 = everything retained).' },
|
|
575
|
+
limit: { type: 'integer', description: 'Read: keep only the most recent N matching entries.' },
|
|
576
|
+
},
|
|
577
|
+
output: { schema: { type: 'json' }, render },
|
|
578
|
+
presentCall: args => consoleCall(args),
|
|
579
|
+
presentResult: (_args, outcome) => consoleResult(outcome),
|
|
580
|
+
execute: async (args, _exec) => {
|
|
581
|
+
const tabId = await resolveTabId(backend, _exec, args.tabId);
|
|
582
|
+
if (args.action === 'start') {
|
|
583
|
+
await backend.startConsole(tabId);
|
|
584
|
+
consoleLog.track(tabId);
|
|
585
|
+
return { tabId, capturing: true, capturingTabs: consoleLog.tracked() };
|
|
586
|
+
}
|
|
587
|
+
if (args.action === 'stop') {
|
|
588
|
+
await backend.stopConsole(tabId);
|
|
589
|
+
consoleLog.release(tabId);
|
|
590
|
+
return { tabId, capturing: false };
|
|
591
|
+
}
|
|
592
|
+
const page = consoleLog.read(tabId, {
|
|
593
|
+
...(args.since === undefined ? {} : { since: args.since }),
|
|
594
|
+
...(args.limit === undefined ? {} : { limit: args.limit }),
|
|
595
|
+
});
|
|
596
|
+
if (page === undefined) {
|
|
597
|
+
throw new Error(`chrome_console: tab ${tabId} is not being captured; call action=start BEFORE the page does the thing`
|
|
598
|
+
+ ' you want to observe, then action=read');
|
|
599
|
+
}
|
|
600
|
+
return {
|
|
601
|
+
tabId,
|
|
602
|
+
entries: page.entries,
|
|
603
|
+
retained: page.retained,
|
|
604
|
+
dropped: page.dropped,
|
|
605
|
+
cursor: page.cursor,
|
|
606
|
+
};
|
|
215
607
|
},
|
|
216
608
|
}),
|
|
217
609
|
];
|