@liyuera/dsh-chrome-browser 0.2.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.
Files changed (96) hide show
  1. package/README.md +270 -20
  2. package/extension/manifest.json +4 -3
  3. package/extension/service-worker.js +721 -68
  4. package/lib/activity.d.ts +65 -0
  5. package/lib/activity.d.ts.map +1 -0
  6. package/lib/activity.js +111 -0
  7. package/lib/activity.js.map +1 -0
  8. package/lib/backend.d.ts +193 -11
  9. package/lib/backend.d.ts.map +1 -1
  10. package/lib/backend.js +344 -39
  11. package/lib/backend.js.map +1 -1
  12. package/lib/cdp.d.ts +7 -1
  13. package/lib/cdp.d.ts.map +1 -1
  14. package/lib/cdp.js +17 -1
  15. package/lib/cdp.js.map +1 -1
  16. package/lib/chrome.d.ts +8 -0
  17. package/lib/chrome.d.ts.map +1 -1
  18. package/lib/chrome.js +20 -0
  19. package/lib/chrome.js.map +1 -1
  20. package/lib/client/BrowserActivity.d.ts +22 -0
  21. package/lib/client/BrowserActivity.d.ts.map +1 -0
  22. package/lib/client/BrowserActivity.js +100 -0
  23. package/lib/client/BrowserActivity.js.map +1 -0
  24. package/lib/client/activity.d.ts +27 -0
  25. package/lib/client/activity.d.ts.map +1 -0
  26. package/lib/client/activity.js +57 -0
  27. package/lib/client/activity.js.map +1 -0
  28. package/lib/client/index.d.ts +4 -6
  29. package/lib/client/index.d.ts.map +1 -1
  30. package/lib/client/index.js +13 -19
  31. package/lib/client/index.js.map +1 -1
  32. package/lib/client/tab-catalog.d.ts +11 -1
  33. package/lib/client/tab-catalog.d.ts.map +1 -1
  34. package/lib/client/tab-catalog.js.map +1 -1
  35. package/lib/client/tab-source.d.ts +8 -2
  36. package/lib/client/tab-source.d.ts.map +1 -1
  37. package/lib/client/tab-source.js.map +1 -1
  38. package/lib/client.js +177 -13
  39. package/lib/client.js.map +1 -1
  40. package/lib/console-events.d.ts +32 -0
  41. package/lib/console-events.d.ts.map +1 -0
  42. package/lib/console-events.js +106 -0
  43. package/lib/console-events.js.map +1 -0
  44. package/lib/console-log.d.ts +107 -0
  45. package/lib/console-log.d.ts.map +1 -0
  46. package/lib/console-log.js +158 -0
  47. package/lib/console-log.js.map +1 -0
  48. package/lib/expressions.d.ts +71 -2
  49. package/lib/expressions.d.ts.map +1 -1
  50. package/lib/expressions.js +277 -14
  51. package/lib/expressions.js.map +1 -1
  52. package/lib/extension-package.d.ts +33 -0
  53. package/lib/extension-package.d.ts.map +1 -0
  54. package/lib/extension-package.js +133 -0
  55. package/lib/extension-package.js.map +1 -0
  56. package/lib/help.d.ts +89 -0
  57. package/lib/help.d.ts.map +1 -0
  58. package/lib/help.js +94 -0
  59. package/lib/help.js.map +1 -0
  60. package/lib/index.d.ts +4 -2
  61. package/lib/index.d.ts.map +1 -1
  62. package/lib/index.js +30 -9
  63. package/lib/index.js.map +1 -1
  64. package/lib/presentation.d.ts +130 -0
  65. package/lib/presentation.d.ts.map +1 -0
  66. package/lib/presentation.js +361 -0
  67. package/lib/presentation.js.map +1 -0
  68. package/lib/routes.d.ts +3 -8
  69. package/lib/routes.d.ts.map +1 -1
  70. package/lib/routes.js +38 -99
  71. package/lib/routes.js.map +1 -1
  72. package/lib/skill.d.ts +50 -0
  73. package/lib/skill.d.ts.map +1 -0
  74. package/lib/skill.js +163 -0
  75. package/lib/skill.js.map +1 -0
  76. package/lib/text.d.ts +21 -0
  77. package/lib/text.d.ts.map +1 -1
  78. package/lib/text.js +18 -0
  79. package/lib/text.js.map +1 -1
  80. package/lib/tools.d.ts +22 -4
  81. package/lib/tools.d.ts.map +1 -1
  82. package/lib/tools.js +467 -75
  83. package/lib/tools.js.map +1 -1
  84. package/lib/ws.d.ts +9 -2
  85. package/lib/ws.d.ts.map +1 -1
  86. package/lib/ws.js +49 -19
  87. package/lib/ws.js.map +1 -1
  88. package/package.json +4 -3
  89. package/lib/bindings.d.ts +0 -23
  90. package/lib/bindings.d.ts.map +0 -1
  91. package/lib/bindings.js +0 -49
  92. package/lib/bindings.js.map +0 -1
  93. package/lib/client/TabPicker.d.ts +0 -54
  94. package/lib/client/TabPicker.d.ts.map +0 -1
  95. package/lib/client/TabPicker.js +0 -329
  96. 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 { clipJson, clipText, normalizePageText } from "./text.js";
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
- /** The executing agent's session id (minimal face; exec is a ToolRunContext). */
18
- function sessionIdOf(exec) {
19
- const agent = exec.agent;
20
- const id = agent?.session?.id;
21
- return typeof id === 'string' && id !== '' ? id : undefined;
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
- * Resolve the tab a tool operates on: explicit id wins, then the
29
- * session-bound tab, then the active tab.
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
- async function resolveTabId(backend, bindings, exec, tabId) {
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
- const sessionId = sessionIdOf(exec);
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
- /** Build every chrome-browser tool definition bound to one backend. */
46
- export function chromeToolDefinitions(backend, config, bindings) {
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, plus every tab this session selected (`session.tabs`, first = the default). Get a tab id first, '
52
- + 'then pass it to chrome_read/chrome_navigate/chrome_screenshot/chrome_click/chrome_type/chrome_eval; omit '
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
- let session = null;
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: page title, url and the visible text. The text is clipped to the configured readTextLimit '
80
- + '(default 30000 code points); textChars reports the full count.',
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; omit to use the session-selected tab, or 'active' for the active tab." },
83
- includeHtml: { type: 'boolean', description: 'Also return the page HTML, clipped to the same budget.' },
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, bindings, _exec, args.tabId);
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 clipped = clipText(rawText, config.readTextLimit);
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: clipped,
97
- textChars: Array.from(rawText).length,
98
- textTruncated: clipped !== rawText,
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: { type: 'string', required: true, description: 'Target URL, e.g. https://example.com.' },
108
- tabId: { type: 'string', description: "Tab id from chrome_tabs; omit to use the session-selected tab, or 'active' for the active tab." },
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
- const tabId = await resolveTabId(backend, bindings, _exec, args.tabId);
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. Returns its tab id for later tools.',
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: { type: 'string', description: 'URL to open; defaults to about:blank.' },
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 tab = await backend.openTab(args.url ?? 'about:blank');
127
- return { tabId: tab.id, title: tab.title, url: tab.url };
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 as a PNG file on the host and return its path (plus bytes). Use the read_image tool on the '
133
- + 'returned path to view the page visually.',
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; omit to use the session-selected tab, or 'active' for the active tab." },
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, bindings, _exec, args.tabId);
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 { path, bytes, tabId };
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. Click the first match by default, or every match with '
166
- + 'all=true. Throws when no element matches. Prefer this for buttons/links; use chrome_eval for interactions '
167
- + 'that need more.',
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; omit to use the session-selected tab, or 'active' for the active tab." },
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, bindings, _exec, args.tabId);
176
- const count = await backend.click(tabId, args.selector, args.all === true);
177
- if (count === 0)
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
- return { tabId, selector: args.selector, clicked: count };
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; omit to use the session-selected tab, or 'active' for the active tab." },
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, bindings, _exec, args.tabId);
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; omit to use the session-selected tab, or 'active' for the active tab." },
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, bindings, _exec, args.tabId);
486
+ const tabId = await resolveTabId(backend, _exec, args.tabId);
213
487
  const value = await backend.evaluate(tabId, args.expression);
214
- return { tabId, value: clipJson(value, EVAL_RESULT_LIMIT) };
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
  ];