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