@liyuera/dsh-chrome-browser 0.6.9 → 0.7.1

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 (95) hide show
  1. package/README.md +17 -5
  2. package/lib/activity.d.ts +0 -1
  3. package/lib/activity.js +1 -6
  4. package/lib/activity.js.map +1 -1
  5. package/lib/backend-registry.d.ts +56 -0
  6. package/lib/backend-registry.js +120 -0
  7. package/lib/backend-registry.js.map +1 -0
  8. package/lib/backend.d.ts +0 -1
  9. package/lib/bridge.d.ts +0 -1
  10. package/lib/caller.d.ts +9 -0
  11. package/lib/caller.js +17 -0
  12. package/lib/caller.js.map +1 -0
  13. package/lib/cdp.d.ts +0 -1
  14. package/lib/chrome.d.ts +34 -5
  15. package/lib/chrome.js +82 -22
  16. package/lib/chrome.js.map +1 -1
  17. package/lib/client.js +489 -551
  18. package/lib/client.js.map +1 -1
  19. package/lib/console-events.d.ts +0 -1
  20. package/lib/console-log.d.ts +0 -1
  21. package/lib/expressions.d.ts +0 -1
  22. package/lib/extension-package.d.ts +0 -1
  23. package/lib/help.d.ts +0 -1
  24. package/lib/index.d.ts +8 -3
  25. package/lib/index.js +30 -18
  26. package/lib/index.js.map +1 -1
  27. package/lib/invariant.d.ts +0 -1
  28. package/lib/local-server.d.ts +0 -1
  29. package/lib/mentions.d.ts +0 -1
  30. package/lib/mentions.js +2 -1
  31. package/lib/mentions.js.map +1 -1
  32. package/lib/message-source.d.ts +0 -1
  33. package/lib/ports.d.ts +13 -0
  34. package/lib/ports.js +20 -0
  35. package/lib/ports.js.map +1 -0
  36. package/lib/presentation.d.ts +0 -1
  37. package/lib/routes.d.ts +0 -1
  38. package/lib/skill.d.ts +0 -1
  39. package/lib/skill.js +29 -12
  40. package/lib/skill.js.map +1 -1
  41. package/lib/text.d.ts +0 -1
  42. package/lib/tools.d.ts +8 -4
  43. package/lib/tools.js +87 -25
  44. package/lib/tools.js.map +1 -1
  45. package/lib/ws.d.ts +0 -1
  46. package/package.json +10 -3
  47. package/lib/activity.d.ts.map +0 -1
  48. package/lib/backend.d.ts.map +0 -1
  49. package/lib/bridge.d.ts.map +0 -1
  50. package/lib/cdp.d.ts.map +0 -1
  51. package/lib/chrome.d.ts.map +0 -1
  52. package/lib/client/BrowserActivity.d.ts +0 -25
  53. package/lib/client/BrowserActivity.d.ts.map +0 -1
  54. package/lib/client/BrowserActivity.js +0 -141
  55. package/lib/client/BrowserActivity.js.map +0 -1
  56. package/lib/client/activity.d.ts +0 -34
  57. package/lib/client/activity.d.ts.map +0 -1
  58. package/lib/client/activity.js +0 -78
  59. package/lib/client/activity.js.map +0 -1
  60. package/lib/client/chrome-icon.d.ts +0 -3
  61. package/lib/client/chrome-icon.d.ts.map +0 -1
  62. package/lib/client/chrome-icon.js +0 -3
  63. package/lib/client/chrome-icon.js.map +0 -1
  64. package/lib/client/index.d.ts +0 -18
  65. package/lib/client/index.d.ts.map +0 -1
  66. package/lib/client/index.js +0 -32
  67. package/lib/client/index.js.map +0 -1
  68. package/lib/client/tab-catalog.d.ts +0 -28
  69. package/lib/client/tab-catalog.d.ts.map +0 -1
  70. package/lib/client/tab-catalog.js +0 -50
  71. package/lib/client/tab-catalog.js.map +0 -1
  72. package/lib/client/tab-icon.d.ts +0 -18
  73. package/lib/client/tab-icon.d.ts.map +0 -1
  74. package/lib/client/tab-icon.js +0 -50
  75. package/lib/client/tab-icon.js.map +0 -1
  76. package/lib/client/tab-source.d.ts +0 -61
  77. package/lib/client/tab-source.d.ts.map +0 -1
  78. package/lib/client/tab-source.js +0 -129
  79. package/lib/client/tab-source.js.map +0 -1
  80. package/lib/console-events.d.ts.map +0 -1
  81. package/lib/console-log.d.ts.map +0 -1
  82. package/lib/expressions.d.ts.map +0 -1
  83. package/lib/extension-package.d.ts.map +0 -1
  84. package/lib/help.d.ts.map +0 -1
  85. package/lib/index.d.ts.map +0 -1
  86. package/lib/invariant.d.ts.map +0 -1
  87. package/lib/local-server.d.ts.map +0 -1
  88. package/lib/mentions.d.ts.map +0 -1
  89. package/lib/message-source.d.ts.map +0 -1
  90. package/lib/presentation.d.ts.map +0 -1
  91. package/lib/routes.d.ts.map +0 -1
  92. package/lib/skill.d.ts.map +0 -1
  93. package/lib/text.d.ts.map +0 -1
  94. package/lib/tools.d.ts.map +0 -1
  95. package/lib/ws.d.ts.map +0 -1
package/lib/skill.js CHANGED
@@ -10,14 +10,15 @@
10
10
  /** Skill name the catalog, the `skill` tool, and `/chrome-browser` address. */
11
11
  export const SKILL_NAME = 'chrome-browser';
12
12
  /** Routing line the catalog shows while the body stays unloaded. */
13
- export const SKILL_DESCRIPTION = '控制用户当前打开的 Chrome 标签页:列标签页、读页面、导航、点击、输入、截图、执行 JS。'
14
- + '适用于用户提到"这个页面/我开着的标签页",或需要读取已登录的内网/后台页面。';
13
+ export const SKILL_DESCRIPTION = '控制浏览器(默认是每个 agent 自己的沙箱;传 backend: "user" 改用用户真实 Chrome):列标签页、读页面、'
14
+ + '导航、点击、输入、截图、执行 JS。适用于用户提到"这个页面/我开着的标签页",或需要读取已登录的内网/后台页面。';
15
15
  /** Body loaded only when the skill is invoked. Annotated `string` so the emitted
16
16
  * declarations carry the type and not a 6 KB literal. */
17
- export const SKILL_CONTENT = `# Chrome 浏览器(用户真实标签页)
17
+ export const SKILL_CONTENT = `# Chrome 浏览器(沙箱优先,真实浏览器按需)
18
18
 
19
- \`chrome_*\` 工具直接操作用户正在使用的 Chrome——不新开窗口、不复制 profile。
20
- 用户打开什么,你就能看什么;登录态、内网、后台系统都能用。
19
+ \`chrome_*\` 工具驱动的浏览器由 \`backend\` 参数选择(见下「后端选择」):默认是这个 agent 自己的隔离浏览器;
20
+ 只有传 \`backend: 'user'\` 时才操作你用户正在使用的真实 Chrome——不新开窗口、不复制 profile。
21
+ 也只有这条通道能看到用户打开什么、登录态、内网与后台系统。
21
22
 
22
23
  ## 工具一览
23
24
 
@@ -41,12 +42,23 @@ export const SKILL_CONTENT = `# Chrome 浏览器(用户真实标签页)
41
42
  | \`chrome_console\` | 采集/读取控制台(start / read / stop),含浏览器自己抛的错误。**start 会占用调试器,用完必须 stop**;5 分钟无读取会自动释放调试器(日志保留,read 返回 \`detached: "idle"\`) |
42
43
  | \`chrome_request_help\` | 请用户做只有人能做的事(登录/验证码),等答复;\`completed: false\` 表示用户跳过,不要重试 |
43
44
 
45
+ ## 后端选择:沙箱优先,真实浏览器备选
46
+
47
+ 16 个**操作浏览器**的工具都有这个可选参数(\`chrome_request_help\` 不驱动浏览器,没有该参数):
48
+
49
+ - \`backend: 'sandbox'\`(**默认**):驱动这个 agent **自己的隔离浏览器**(owned Chrome),并行子代理互不干扰;没有你的登录态。
50
+ - \`backend: 'user'\`:驱动**用户真实 Chrome**(扩展桥),用于已登录的内网/后台页面、用户正在看的 \`@\` 标签页。
51
+
52
+ 默认用 sandbox;只有当你需要用户的登录态、或要操作引用/打开的真实标签页时,才传 \`backend: 'user'\`。
53
+ 如果插件以 \`backend: 'extension'\` 或 \`backend: 'cdp'\` 配置运行(没有沙箱),所有工具都走真实浏览器,\`backend\` 参数无效果。
54
+
44
55
  ## 什么时候用
45
56
 
46
57
  - 用户提到"这个页面""我现在开着的标签页""帮我填一下这个表单"。
47
58
  - 用户消息里带 \`@"页面标题"\` 引用——宿主随后注入一条 \`## Referenced Chrome tabs\`,
48
- 里面有该标签页的 \`tabId\` 与 URL,照着用即可。
49
- - 需要读取用户已登录、你抓不到的页面。
59
+ 里面有该标签页的 \`tabId\` 与 URL。**这个 id 属于用户真实浏览器,调用时必须带 \`backend: 'user'\`**;
60
+ \`chrome_tabs\` 返回的 id 只在当次选择的那个浏览器里有效,切后端后要重新列。
61
+ - 需要读取用户已登录、你抓不到的页面——这类页面只在用户真实浏览器里,调用时带 \`backend: 'user'\`。
50
62
 
51
63
  不需要浏览器时不要调用这些工具。
52
64
 
@@ -55,7 +67,7 @@ export const SKILL_CONTENT = `# Chrome 浏览器(用户真实标签页)
55
67
  0. **先看有没有 WebMCP**——页面若实现了 WebMCP(需要 Chrome 启用 WebMCP),先 \`chrome_webmcp_list\`;
56
68
  有工具时优先 \`chrome_webmcp_call\`,比点 DOM 稳。\`pending: true\` 表示工具已激活但还在等用户操作
57
69
  (常见于声明式表单),不要重复调用,先请用户确认。
58
- 1. **拿到 tabId**——引用已注入时直接用;否则先 \`chrome_tabs\`。
70
+ 1. **拿到 tabId**——引用已注入时直接用(并带 \`backend: 'user'\`);否则先 \`chrome_tabs\` 列当前后端的标签页。
59
71
  2. **先感知再操作**——要动手时用 \`chrome_read { mode: 'interactive' }\`:它直接给出每个可交互元素的
60
72
  \`selector\` 以及 \`disabled\` / \`covered\` / \`inView\`,比读正文小得多,而且读完就能点。
61
73
  只是要理解页面内容时才用默认的 \`mode: 'text'\`。
@@ -74,11 +86,16 @@ export const SKILL_CONTENT = `# Chrome 浏览器(用户真实标签页)
74
86
  ## tabId 从哪来
75
87
 
76
88
  - **显式 id**——来自 \`chrome_tabs\`,或用户引用某标签页时宿主注入的上下文。**优先用这个。**
77
- - 省略 \`tabId\`、或写 \`"active"\`——都是**用户当前正在看的那个标签页**。
89
+ - 省略 \`tabId\`、或写 \`"active"\`——指**你当前所选后端(默认沙箱)的活动标签页**;
90
+ 默认沙箱时它是沙箱自己的活动页,不是你用户正在看的那一页。要操作用户真实浏览器里的活动页,
91
+ 显式传 \`backend: 'user'\`。
78
92
 
79
93
  \`@\` 菜单插入的是引用芯片,**不绑定会话**;所以没有「本会话选中的标签页」这回事。
80
94
  用户明确要你操作某个页面时,不要省略 \`tabId\`:那时活动标签页很可能已经是别的了。
81
95
 
96
+ **id 只在产生它的浏览器里有效。** \`chrome_tabs\` 拿到的 id 属于当次选择的那个后端;
97
+ 切换 \`backend\` 后要重新列,不要拿沙箱的 id 去操作真实浏览器(反之亦然)。
98
+
82
99
  **模型侧看到的是 id,不是标题。** 标题只能用来在 \`chrome_tabs\` 的结果里认出目标。
83
100
 
84
101
  ## 失败怎么办
@@ -152,9 +169,9 @@ export const SKILL_CONTENT = `# Chrome 浏览器(用户真实标签页)
152
169
  - **按键、悬停、下拉的事件是合成的**:送达页面监听器,但不产生浏览器默认行为。
153
170
  Enter 提交靠显式 \`requestSubmit()\` 兜底(\`chrome_press\` 会报告 \`submitted\`);依赖真实按键序列
154
171
  (组合键、输入法)或真实指针的组件仍可能不响应,这些场景退回 \`chrome_eval\`。
155
- - **操作的是用户真实标签页**:用户可能同时在操作同一个页面;
156
- 写操作前确认目标,不要在用户正在输入的页面上抢焦点。截图优先走调试通道,不会切换标签页,
157
- 但会在该标签页显示「正在调试」提示条。
172
+ - **默认操作的是你自己的沙箱(隔离)**:只有传 \`backend: 'user'\` 才碰用户真实页面——那时用户可能
173
+ 同时在操作同一个页面,写操作前确认目标,不要在用户正在输入的页面上抢焦点。截图优先走调试通道,
174
+ 不会切换标签页,但会在该标签页显示「正在调试」提示条。
158
175
  - **截图自带降级**:调试通道失败(DevTools 占用、页面拒绝渲染、clip 测量失败等)时,
159
176
  \`chrome_screenshot\` 自动退回 \`chrome.tabs.captureVisibleTab\` 的可视区域截图,结果带
160
177
  \`fallback: "visible-tab"\` + \`warning\`(含失败原因),\`fullPage\`/\`selector\` 不生效时还带
package/lib/skill.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"skill.js","sourceRoot":"","sources":["../src/skill.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,+EAA+E;AAC/E,MAAM,CAAC,MAAM,UAAU,GAAG,gBAAgB,CAAA;AAE1C,oEAAoE;AACpE,MAAM,CAAC,MAAM,iBAAiB,GAC5B,kDAAkD;MAChD,yCAAyC,CAAA;AAE7C;yDACyD;AACzD,MAAM,CAAC,MAAM,aAAa,GAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6JpC,CAAA;AAuBD,yCAAyC;AACzC,MAAM,UAAU,WAAW;IACzB,OAAO;QACL,IAAI,EAAE,UAAU;QAChB,WAAW,EAAE,iBAAiB;QAC9B,OAAO,EAAE,aAAa;QACtB,MAAM,EAAE,SAAS;QACjB,yEAAyE;QACzE,6BAA6B;QAC7B,UAAU,EAAE,EAAE,cAAc,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE;KAC1D,CAAA;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CAAC,GAAY;IAC9C,GAAG,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,EAAE;QAChC,MAAM,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,QAAQ,CAA2B,CAAA;QAC7D,IAAI,MAAM,KAAK,SAAS;YAAE,OAAM;QAChC,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC,EAAE,uBAAuB,CAAC,CAAA;IAC9E,CAAC,CAAC,CAAA;AACJ,CAAC"}
1
+ {"version":3,"file":"skill.js","sourceRoot":"","sources":["../src/skill.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,+EAA+E;AAC/E,MAAM,CAAC,MAAM,UAAU,GAAG,gBAAgB,CAAA;AAE1C,oEAAoE;AACpE,MAAM,CAAC,MAAM,iBAAiB,GAC5B,oEAAoE;MAClE,2DAA2D,CAAA;AAE/D;yDACyD;AACzD,MAAM,CAAC,MAAM,aAAa,GAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8KpC,CAAA;AAuBD,yCAAyC;AACzC,MAAM,UAAU,WAAW;IACzB,OAAO;QACL,IAAI,EAAE,UAAU;QAChB,WAAW,EAAE,iBAAiB;QAC9B,OAAO,EAAE,aAAa;QACtB,MAAM,EAAE,SAAS;QACjB,yEAAyE;QACzE,6BAA6B;QAC7B,UAAU,EAAE,EAAE,cAAc,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE;KAC1D,CAAA;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CAAC,GAAY;IAC9C,GAAG,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,EAAE;QAChC,MAAM,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,QAAQ,CAA2B,CAAA;QAC7D,IAAI,MAAM,KAAK,SAAS;YAAE,OAAM;QAChC,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC,EAAE,uBAAuB,CAAC,CAAA;IAC9E,CAAC,CAAC,CAAA;AACJ,CAAC"}
package/lib/text.d.ts CHANGED
@@ -43,4 +43,3 @@ export declare function windowText(text: string, offset: number, limit: number):
43
43
  * @returns bounded JSON text.
44
44
  */
45
45
  export declare function clipJson(value: unknown, maxChars: number): string;
46
- //# sourceMappingURL=text.d.ts.map
package/lib/tools.d.ts CHANGED
@@ -20,12 +20,16 @@ import type { HelpChannel } from './help.ts';
20
20
  */
21
21
  export declare function clickWarnings(outcome: ClickOutcome): string[];
22
22
  /**
23
- * Build every chrome-browser tool definition bound to one backend.
24
- * @param backend - the live browser backend.
23
+ * Build every chrome-browser tool definition. Each tool resolves its backend
24
+ * from the executing agent on every call, so a sandbox backend stays scoped to
25
+ * one agent while the extension/cdp backends keep a shared singleton. An
26
+ * explicit per-call `backend: 'user'` opts out of the sandbox and drives the
27
+ * shared backend (the user's real browser) instead.
28
+ * @param resolve - maps an execution context and an optional backend preference
29
+ * to the browser backend the call drives.
25
30
  * @param config - the resolved plugin configuration.
26
31
  * @param consoleLog - the bounded console buffer `chrome_console` reads.
27
32
  * @param help - the human-help channel `chrome_request_help` speaks to.
28
33
  * @returns the tool definitions in registration order.
29
34
  */
30
- export declare function chromeToolDefinitions(backend: BrowserBackend, config: ResolvedChromeConfig, consoleLog: ConsoleLog, help: HelpChannel): ToolDefinition[];
31
- //# sourceMappingURL=tools.d.ts.map
35
+ export declare function chromeToolDefinitions(resolve: (exec: unknown, backend?: 'sandbox' | 'user') => BrowserBackend, config: ResolvedChromeConfig, consoleLog: ConsoleLog, help: HelpChannel): ToolDefinition[];
package/lib/tools.js CHANGED
@@ -19,6 +19,29 @@ const MAX_WAIT_MS = 300_000;
19
19
  const render = (_args, value) => [
20
20
  { type: 'text', text: JSON.stringify(value, null, 2) },
21
21
  ];
22
+ /**
23
+ * Per-call backend preference shared by every backend-using tool: the agent's
24
+ * own sandbox (default) or the user's real browser. The description states
25
+ * that the parameter is inert outside sandbox config, so a model never assumes
26
+ * isolation it does not have.
27
+ */
28
+ const BACKEND_PARAM = {
29
+ backend: {
30
+ type: 'string',
31
+ enum: ['sandbox', 'user'],
32
+ description: 'Which browser to drive: "sandbox" (default) is this agent\'s isolated owned browser; '
33
+ + '"user" is the real Chrome (the extension bridge), for logged-in pages or the user\'s own tabs. '
34
+ + 'In "extension" or "cdp" config mode this parameter has no effect — every call drives the real Chrome.',
35
+ },
36
+ };
37
+ /**
38
+ * Narrow one validated `backend` argument to the registry's preference union.
39
+ * Omission and anything the schema does not allow leave the choice to the
40
+ * registry, which defaults to the agent's sandbox.
41
+ * @param backend - the raw per-call argument.
42
+ * @returns `'user'`, `'sandbox'`, or `undefined` for "no explicit preference".
43
+ */
44
+ const backendPreference = (backend) => backend === 'user' ? 'user' : backend === 'sandbox' ? 'sandbox' : undefined;
22
45
  /**
23
46
  * The executing agent itself, for routing a human question to its own UI. A
24
47
  * delegated child cannot ask (the question service rejects it), so the value is
@@ -149,7 +172,9 @@ function imagePath(path, ext) {
149
172
  }
150
173
  /**
151
174
  * 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.
175
+ * an omitted id or the literal `active` — means the active tab of the backend
176
+ * this call drives (the sandbox's own page by default, the user's real tab
177
+ * with `backend: 'user'`).
153
178
  *
154
179
  * There is no session binding to fall back to: the `@` menu inserts a reference
155
180
  * chip and binds nothing, and the chip's `tabId` arrives in the injected context.
@@ -161,14 +186,19 @@ async function resolveTabId(backend, exec, tabId) {
161
186
  return backend.activeTabId();
162
187
  }
163
188
  /**
164
- * Build every chrome-browser tool definition bound to one backend.
165
- * @param backend - the live browser backend.
189
+ * Build every chrome-browser tool definition. Each tool resolves its backend
190
+ * from the executing agent on every call, so a sandbox backend stays scoped to
191
+ * one agent while the extension/cdp backends keep a shared singleton. An
192
+ * explicit per-call `backend: 'user'` opts out of the sandbox and drives the
193
+ * shared backend (the user's real browser) instead.
194
+ * @param resolve - maps an execution context and an optional backend preference
195
+ * to the browser backend the call drives.
166
196
  * @param config - the resolved plugin configuration.
167
197
  * @param consoleLog - the bounded console buffer `chrome_console` reads.
168
198
  * @param help - the human-help channel `chrome_request_help` speaks to.
169
199
  * @returns the tool definitions in registration order.
170
200
  */
171
- export function chromeToolDefinitions(backend, config, consoleLog, help) {
201
+ export function chromeToolDefinitions(resolve, config, consoleLog, help) {
172
202
  /**
173
203
  * Console captures that stop being read are released automatically.
174
204
  *
@@ -190,7 +220,7 @@ export function chromeToolDefinitions(backend, config, consoleLog, help) {
190
220
  idleTimers.delete(tabId);
191
221
  }
192
222
  };
193
- const armIdleTimer = (tabId) => {
223
+ const armIdleTimer = (backend, tabId) => {
194
224
  clearIdleTimer(tabId);
195
225
  if (!(config.consoleIdleMs > 0))
196
226
  return;
@@ -206,15 +236,17 @@ export function chromeToolDefinitions(backend, config, consoleLog, help) {
206
236
  return [
207
237
  defineTool({
208
238
  name: 'chrome_tabs',
209
- description: 'List the tabs currently open in the Chrome instance the browser plugin controls: id, title, url, active and '
210
- + 'favicon. Get a tab id first, then pass it to every other chrome_* tool; omitting tabId (or passing '
211
- + '"active") means the tab the user is looking at, which is rarely the one a request names.',
212
- parameters: {},
239
+ description: 'List the tabs in the browser this call drives: the agent\'s own sandbox by default, the user\'s real Chrome '
240
+ + 'with backend "user". Reports id, title, url, active and favicon. Get a tab id first, then pass it to every '
241
+ + 'other chrome_* tool; omitting tabId (or passing "active") means the active tab of that same backend, which '
242
+ + 'is rarely the one a request names.',
243
+ parameters: { ...BACKEND_PARAM },
213
244
  output: { schema: { type: 'json' }, render },
214
245
  isConcurrencySafe: () => true,
215
246
  presentCall: () => tabsCall(),
216
247
  presentResult: (_args, outcome) => tabsResult(outcome),
217
- execute: async (_args, _exec) => {
248
+ execute: async (args, _exec) => {
249
+ const backend = resolve(_exec, backendPreference(args.backend));
218
250
  const tabs = await backend.listTabs();
219
251
  return { tabs };
220
252
  },
@@ -228,7 +260,8 @@ export function chromeToolDefinitions(backend, config, consoleLog, help) {
228
260
  + '`inView`, `disabled` or `covered` by something else. Prefer mode="interactive" before clicking or typing: '
229
261
  + 'it is far smaller than the page text and answers "what can I act on, and will it work".',
230
262
  parameters: {
231
- tabId: { type: 'string', description: "Tab id from chrome_tabs, or 'active' for the tab the user is looking at; omitting it means 'active' too." },
263
+ ...BACKEND_PARAM,
264
+ tabId: { type: 'string', description: "Tab id from chrome_tabs, or 'active' for the chosen backend's active tab (the user's own tab only with backend: 'user'); omitting it means 'active' too." },
232
265
  mode: {
233
266
  type: 'string',
234
267
  enum: ['text', 'interactive'],
@@ -242,6 +275,7 @@ export function chromeToolDefinitions(backend, config, consoleLog, help) {
242
275
  presentCall: args => readCall(args),
243
276
  presentResult: (_args, outcome) => readResult(outcome),
244
277
  execute: async (args, _exec) => {
278
+ const backend = resolve(_exec, backendPreference(args.backend));
245
279
  const tabId = await resolveTabId(backend, _exec, args.tabId);
246
280
  if (args.mode === 'interactive') {
247
281
  const inventory = await backend.inventory(tabId);
@@ -280,19 +314,21 @@ export function chromeToolDefinitions(backend, config, consoleLog, help) {
280
314
  name: 'chrome_navigate',
281
315
  description: 'Navigate one tab to a URL. By default waits until the page reaches readyState "complete" (up to waitLoadMs).',
282
316
  parameters: {
317
+ ...BACKEND_PARAM,
283
318
  url: {
284
319
  type: 'string',
285
320
  required: true,
286
321
  description: 'Target URL, e.g. https://example.com. http(s) and file only; a file: URL also needs the '
287
322
  + 'extension to be granted file access in chrome://extensions.',
288
323
  },
289
- tabId: { type: 'string', description: "Tab id from chrome_tabs, or 'active' for the tab the user is looking at; omitting it means 'active' too." },
324
+ tabId: { type: 'string', description: "Tab id from chrome_tabs, or 'active' for the chosen backend's active tab (the user's own tab only with backend: 'user'); omitting it means 'active' too." },
290
325
  waitLoad: { type: 'boolean', description: 'Wait for load completion (default true).' },
291
326
  },
292
327
  output: { schema: { type: 'json' }, render },
293
328
  presentCall: args => navigateCall(args),
294
329
  presentResult: (_args, outcome) => navigateResult(outcome),
295
330
  execute: async (args, _exec) => {
331
+ const backend = resolve(_exec, backendPreference(args.backend));
296
332
  assertOperableUrl('chrome_navigate', args.url, false);
297
333
  const tabId = await resolveTabId(backend, _exec, args.tabId);
298
334
  await backend.navigate(tabId, args.url, args.waitLoad !== false, config.waitLoadMs);
@@ -305,6 +341,7 @@ export function chromeToolDefinitions(backend, config, consoleLog, help) {
305
341
  + 'before returning, so the returned title is the loaded page\'s and a following chrome_read sees the '
306
342
  + 'document; pass waitLoad=false to return as soon as the tab exists.',
307
343
  parameters: {
344
+ ...BACKEND_PARAM,
308
345
  url: {
309
346
  type: 'string',
310
347
  description: 'URL to open; defaults to about:blank. http(s) and file only — a file: URL also needs '
@@ -317,6 +354,7 @@ export function chromeToolDefinitions(backend, config, consoleLog, help) {
317
354
  presentCall: args => openCall(args),
318
355
  presentResult: (_args, outcome) => openResult(outcome),
319
356
  execute: async (args, _exec) => {
357
+ const backend = resolve(_exec, backendPreference(args.backend));
320
358
  const target = args.url ?? 'about:blank';
321
359
  assertOperableUrl('chrome_open', target, true);
322
360
  const opened = await backend.openTab(target);
@@ -338,12 +376,14 @@ export function chromeToolDefinitions(backend, config, consoleLog, help) {
338
376
  + 'must be a real id from chrome_tabs: this never falls back to the active tab, because the tab the '
339
377
  + 'user is looking at is rarely the one worth closing. Close what you opened.',
340
378
  parameters: {
379
+ ...BACKEND_PARAM,
341
380
  tabId: { type: 'string', required: true, description: 'Exact tab id from chrome_tabs.' },
342
381
  },
343
382
  output: { schema: { type: 'json' }, render },
344
383
  presentCall: args => closeCall(args),
345
384
  presentResult: (_args, outcome) => closeResult(outcome),
346
385
  execute: async (args, _exec) => {
386
+ const backend = resolve(_exec, backendPreference(args.backend));
347
387
  const tabId = args.tabId;
348
388
  if (tabId === undefined || tabId === '' || tabId === 'active') {
349
389
  throw new Error('chrome_close: tabId must be an exact tab id from chrome_tabs; it never defaults to the active tab');
@@ -362,7 +402,8 @@ export function chromeToolDefinitions(backend, config, consoleLog, help) {
362
402
  + 'result then carries `fallback: "visible-tab"`, a `warning`, and `viewportOnly` when `fullPage`/`selector` '
363
403
  + 'could not be honoured. If that fallback fails too, the call throws with both causes.',
364
404
  parameters: {
365
- tabId: { type: 'string', description: "Tab id from chrome_tabs, or 'active' for the tab the user is looking at; omitting it means 'active' too." },
405
+ ...BACKEND_PARAM,
406
+ tabId: { type: 'string', description: "Tab id from chrome_tabs, or 'active' for the chosen backend's active tab (the user's own tab only with backend: 'user'); omitting it means 'active' too." },
366
407
  path: { type: 'string', description: 'Optional output file path; defaults to <screenshotDir>/<timestamp>-<tabId>.png.' },
367
408
  fullPage: {
368
409
  type: 'boolean',
@@ -379,6 +420,7 @@ export function chromeToolDefinitions(backend, config, consoleLog, help) {
379
420
  presentCall: args => screenshotCall(args),
380
421
  presentResult: (_args, outcome) => screenshotResult(outcome),
381
422
  execute: async (args, _exec) => {
423
+ const backend = resolve(_exec, backendPreference(args.backend));
382
424
  const tabId = await resolveTabId(backend, _exec, args.tabId);
383
425
  const shot = await backend.screenshot(tabId, {
384
426
  fullPage: args.fullPage === true,
@@ -433,14 +475,16 @@ export function chromeToolDefinitions(backend, config, consoleLog, help) {
433
475
  + 'covered by another element, or marked aria-disabled. Throws when nothing matches, or when every match is '
434
476
  + 'natively disabled. Prefer this for buttons/links; use chrome_eval for interactions that need more.',
435
477
  parameters: {
478
+ ...BACKEND_PARAM,
436
479
  selector: { type: 'string', required: true, description: 'CSS selector, e.g. "#submit" or "a.download".' },
437
- tabId: { type: 'string', description: "Tab id from chrome_tabs, or 'active' for the tab the user is looking at; omitting it means 'active' too." },
480
+ tabId: { type: 'string', description: "Tab id from chrome_tabs, or 'active' for the chosen backend's active tab (the user's own tab only with backend: 'user'); omitting it means 'active' too." },
438
481
  all: { type: 'boolean', description: 'Click every matching element (default false: first match only).' },
439
482
  },
440
483
  output: { schema: { type: 'json' }, render },
441
484
  presentCall: args => clickCall(args),
442
485
  presentResult: (_args, outcome) => clickResult(outcome),
443
486
  execute: async (args, _exec) => {
487
+ const backend = resolve(_exec, backendPreference(args.backend));
444
488
  const tabId = await resolveTabId(backend, _exec, args.tabId);
445
489
  const outcome = await backend.click(tabId, args.selector, args.all === true);
446
490
  if (outcome.matched === 0)
@@ -466,13 +510,15 @@ export function chromeToolDefinitions(backend, config, consoleLog, help) {
466
510
  + 'but do not set the browser\'s own hover state: a control revealed purely by a CSS :hover rule may stay '
467
511
  + 'hidden. Follow it with chrome_read mode="interactive" to see what appeared.',
468
512
  parameters: {
513
+ ...BACKEND_PARAM,
469
514
  selector: { type: 'string', required: true, description: 'CSS selector to hover, e.g. "#menu" or "[aria-label=More]".' },
470
- tabId: { type: 'string', description: "Tab id from chrome_tabs, or 'active' for the tab the user is looking at; omitting it means 'active' too." },
515
+ tabId: { type: 'string', description: "Tab id from chrome_tabs, or 'active' for the chosen backend's active tab (the user's own tab only with backend: 'user'); omitting it means 'active' too." },
471
516
  },
472
517
  output: { schema: { type: 'json' }, render },
473
518
  presentCall: args => hoverCall(args),
474
519
  presentResult: (_args, outcome) => hoverResult(outcome),
475
520
  execute: async (args, _exec) => {
521
+ const backend = resolve(_exec, backendPreference(args.backend));
476
522
  const tabId = await resolveTabId(backend, _exec, args.tabId);
477
523
  const outcome = await backend.hover(tabId, args.selector);
478
524
  if (outcome.matched === 0)
@@ -486,15 +532,17 @@ export function chromeToolDefinitions(backend, config, consoleLog, help) {
486
532
  + 'content (clear=true, the default, so the text replaces it), then sets the value with a native-setter '
487
533
  + 'input/change dispatch so React-style controlled fields update.',
488
534
  parameters: {
535
+ ...BACKEND_PARAM,
489
536
  selector: { type: 'string', required: true, description: 'CSS selector of the input/textarea/editable element.' },
490
537
  text: { type: 'string', required: true, description: 'Text to insert.' },
491
- 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
+ tabId: { type: 'string', description: "Tab id from chrome_tabs, or 'active' for the chosen backend's active tab (the user's own tab only with backend: 'user'); omitting it means 'active' too." },
492
539
  clear: { type: 'boolean', description: 'Select existing content first so the text replaces it (default true).' },
493
540
  },
494
541
  output: { schema: { type: 'json' }, render },
495
542
  presentCall: args => typeCall(args),
496
543
  presentResult: (_args, outcome) => typeResult(outcome),
497
544
  execute: async (args, _exec) => {
545
+ const backend = resolve(_exec, backendPreference(args.backend));
498
546
  const tabId = await resolveTabId(backend, _exec, args.tabId);
499
547
  const cleared = args.clear !== false;
500
548
  await backend.type(tabId, args.selector, args.text, cleared);
@@ -508,14 +556,16 @@ export function chromeToolDefinitions(backend, config, consoleLog, help) {
508
556
  + 'action — for Enter the owning form is submitted explicitly and `submitted: true` says that happened. A key '
509
557
  + 'that only moves focus or closes an overlay reports `submitted: false` and changes nothing else.',
510
558
  parameters: {
559
+ ...BACKEND_PARAM,
511
560
  key: { type: 'string', required: true, description: 'KeyboardEvent.key value, e.g. "Enter", "Escape", "Tab", "ArrowDown".' },
512
561
  selector: { type: 'string', description: 'Focus this element first; omit to press on whatever currently has focus.' },
513
- tabId: { type: 'string', description: "Tab id from chrome_tabs, or 'active' for the tab the user is looking at; omitting it means 'active' too." },
562
+ tabId: { type: 'string', description: "Tab id from chrome_tabs, or 'active' for the chosen backend's active tab (the user's own tab only with backend: 'user'); omitting it means 'active' too." },
514
563
  },
515
564
  output: { schema: { type: 'json' }, render },
516
565
  presentCall: args => pressCall(args),
517
566
  presentResult: (_args, outcome) => pressResult(outcome),
518
567
  execute: async (args, _exec) => {
568
+ const backend = resolve(_exec, backendPreference(args.backend));
519
569
  const tabId = await resolveTabId(backend, _exec, args.tabId);
520
570
  const outcome = await backend.press(tabId, args.key, args.selector);
521
571
  if (!outcome.found) {
@@ -536,14 +586,16 @@ export function chromeToolDefinitions(backend, config, consoleLog, help) {
536
586
  + 'prototype setter and fires input/change so controlled components update. Throws when the value is not one '
537
587
  + 'of the options, listing the values that are — read them from the error rather than guessing again.',
538
588
  parameters: {
589
+ ...BACKEND_PARAM,
539
590
  selector: { type: 'string', required: true, description: 'CSS selector for the <select> element.' },
540
591
  value: { type: 'string', required: true, description: 'Option value to select (the value attribute, not the label).' },
541
- tabId: { type: 'string', description: "Tab id from chrome_tabs, or 'active' for the tab the user is looking at; omitting it means 'active' too." },
592
+ tabId: { type: 'string', description: "Tab id from chrome_tabs, or 'active' for the chosen backend's active tab (the user's own tab only with backend: 'user'); omitting it means 'active' too." },
542
593
  },
543
594
  output: { schema: { type: 'json' }, render },
544
595
  presentCall: args => selectCall(args),
545
596
  presentResult: (_args, outcome) => selectResult(outcome),
546
597
  execute: async (args, _exec) => {
598
+ const backend = resolve(_exec, backendPreference(args.backend));
547
599
  const tabId = await resolveTabId(backend, _exec, args.tabId);
548
600
  const outcome = await backend.select(tabId, args.selector, args.value);
549
601
  if (outcome.matched === 0) {
@@ -566,13 +618,15 @@ export function chromeToolDefinitions(backend, config, consoleLog, help) {
566
618
  + '(bounded to 200k characters). Expression runs in the page\'s main world; returned values are '
567
619
  + 'serialized by value. Example: document.querySelectorAll("a").length.',
568
620
  parameters: {
621
+ ...BACKEND_PARAM,
569
622
  expression: { type: 'string', required: true, description: 'JavaScript expression to evaluate in the page.' },
570
- tabId: { type: 'string', description: "Tab id from chrome_tabs, or 'active' for the tab the user is looking at; omitting it means 'active' too." },
623
+ tabId: { type: 'string', description: "Tab id from chrome_tabs, or 'active' for the chosen backend's active tab (the user's own tab only with backend: 'user'); omitting it means 'active' too." },
571
624
  },
572
625
  output: { schema: { type: 'json' }, render },
573
626
  presentCall: args => evalCall(args),
574
627
  presentResult: (_args, outcome) => evalResult(outcome),
575
628
  execute: async (args, _exec) => {
629
+ const backend = resolve(_exec, backendPreference(args.backend));
576
630
  const tabId = await resolveTabId(backend, _exec, args.tabId);
577
631
  const value = await backend.evaluate(tabId, args.expression);
578
632
  return {
@@ -593,13 +647,15 @@ export function chromeToolDefinitions(backend, config, consoleLog, help) {
593
647
  + '--enable-features=WebMCP or an origin trial) or listing failed — fall back to the DOM tools. '
594
648
  + '`available: true` with an empty `tools` array means the page has the API but registers no tools right now.',
595
649
  parameters: {
596
- tabId: { type: 'string', description: "Tab id from chrome_tabs, or 'active' for the tab the user is looking at; omitting it means 'active' too." },
650
+ ...BACKEND_PARAM,
651
+ tabId: { type: 'string', description: "Tab id from chrome_tabs, or 'active' for the chosen backend's active tab (the user's own tab only with backend: 'user'); omitting it means 'active' too." },
597
652
  },
598
653
  output: { schema: { type: 'json' }, render },
599
654
  isConcurrencySafe: () => true,
600
655
  presentCall: args => webmcpListCall(args),
601
656
  presentResult: (_args, outcome) => webmcpListResult(outcome),
602
657
  execute: async (args, _exec) => {
658
+ const backend = resolve(_exec, backendPreference(args.backend));
603
659
  const tabId = await resolveTabId(backend, _exec, args.tabId);
604
660
  const listing = await backend.webmcpTools(tabId);
605
661
  return {
@@ -620,14 +676,16 @@ export function chromeToolDefinitions(backend, config, consoleLog, help) {
620
676
  + 'Respect consequentialHint: confirm with the user '
621
677
  + '(chrome_request_help) before high-stakes tools.',
622
678
  parameters: {
679
+ ...BACKEND_PARAM,
623
680
  name: { type: 'string', required: true, description: '工具名,来自 chrome_webmcp_list 的 name。' },
624
681
  input: { type: 'object', additionalProperties: true, description: '该工具 inputSchema 对应的参数对象;不需要参数时省略。' },
625
- tabId: { type: 'string', description: "Tab id from chrome_tabs, or 'active' for the tab the user is looking at; omitting it means 'active' too." },
682
+ tabId: { type: 'string', description: "Tab id from chrome_tabs, or 'active' for the chosen backend's active tab (the user's own tab only with backend: 'user'); omitting it means 'active' too." },
626
683
  },
627
684
  output: { schema: { type: 'json' }, render },
628
685
  presentCall: args => webmcpCallCall(args),
629
686
  presentResult: (_args, outcome) => webmcpCallResult(outcome),
630
687
  execute: async (args, _exec) => {
688
+ const backend = resolve(_exec, backendPreference(args.backend));
631
689
  const tabId = await resolveTabId(backend, _exec, args.tabId);
632
690
  const input = typeof args.input === 'object' && args.input !== null && !Array.isArray(args.input) ? args.input : {};
633
691
  const outcome = await backend.webmcpCall(tabId, args.name, input);
@@ -658,6 +716,7 @@ export function chromeToolDefinitions(backend, config, consoleLog, help) {
658
716
  + 'element that is absent. The result says `satisfied`: **false means the timeout passed, not that the wait '
659
717
  + 'succeeded** — check it before assuming the page is ready.',
660
718
  parameters: {
719
+ ...BACKEND_PARAM,
661
720
  selector: { type: 'string', required: true, description: 'CSS selector to wait for.' },
662
721
  state: {
663
722
  type: 'string',
@@ -665,12 +724,13 @@ export function chromeToolDefinitions(backend, config, consoleLog, help) {
665
724
  description: '"visible" (default): present with a layout box and not hidden. "hidden": absent or not shown. "attached"/"detached": presence only.',
666
725
  },
667
726
  timeoutMs: { type: 'integer', description: 'How long to wait (default 10000ms; max 300000).' },
668
- tabId: { type: 'string', description: "Tab id from chrome_tabs, or 'active' for the tab the user is looking at; omitting it means 'active' too." },
727
+ tabId: { type: 'string', description: "Tab id from chrome_tabs, or 'active' for the chosen backend's active tab (the user's own tab only with backend: 'user'); omitting it means 'active' too." },
669
728
  },
670
729
  output: { schema: { type: 'json' }, render },
671
730
  presentCall: args => waitCall(args),
672
731
  presentResult: (_args, outcome) => waitResult(outcome),
673
732
  execute: async (args, _exec) => {
733
+ const backend = resolve(_exec, backendPreference(args.backend));
674
734
  const tabId = await resolveTabId(backend, _exec, args.tabId);
675
735
  const state = args.state === 'hidden' || args.state === 'attached' || args.state === 'detached'
676
736
  ? args.state
@@ -723,13 +783,14 @@ export function chromeToolDefinitions(backend, config, consoleLog, help) {
723
783
  + 'included — a wrapper around console() would miss them. The buffer is bounded per tab and never written to '
724
784
  + 'the session log; `dropped` counts entries evicted before you read them.',
725
785
  parameters: {
786
+ ...BACKEND_PARAM,
726
787
  action: {
727
788
  type: 'string',
728
789
  required: true,
729
790
  enum: ['start', 'stop', 'read'],
730
791
  description: 'start capture, read entries, or stop and drop the buffer.',
731
792
  },
732
- tabId: { type: 'string', description: "Tab id from chrome_tabs, or 'active' for the tab the user is looking at; omitting it means 'active' too." },
793
+ tabId: { type: 'string', description: "Tab id from chrome_tabs, or 'active' for the chosen backend's active tab (the user's own tab only with backend: 'user'); omitting it means 'active' too." },
733
794
  since: { type: 'integer', description: 'Read: return entries whose sequence number is greater than this cursor (default 0 = everything retained).' },
734
795
  limit: { type: 'integer', description: 'Read: keep only the most recent N matching entries.' },
735
796
  },
@@ -737,12 +798,13 @@ export function chromeToolDefinitions(backend, config, consoleLog, help) {
737
798
  presentCall: args => consoleCall(args),
738
799
  presentResult: (_args, outcome) => consoleResult(outcome),
739
800
  execute: async (args, _exec) => {
801
+ const backend = resolve(_exec, backendPreference(args.backend));
740
802
  const tabId = await resolveTabId(backend, _exec, args.tabId);
741
803
  if (args.action === 'start') {
742
804
  await backend.startConsole(tabId);
743
805
  consoleLog.track(tabId);
744
806
  idleReleased.delete(tabId);
745
- armIdleTimer(tabId);
807
+ armIdleTimer(backend, tabId);
746
808
  return { tabId, capturing: true, capturingTabs: consoleLog.tracked() };
747
809
  }
748
810
  if (args.action === 'stop') {
@@ -764,7 +826,7 @@ export function chromeToolDefinitions(backend, config, consoleLog, help) {
764
826
  // ones; the read says so instead of looking like a live capture.
765
827
  const idle = idleReleased.has(tabId);
766
828
  if (!idle)
767
- armIdleTimer(tabId);
829
+ armIdleTimer(backend, tabId);
768
830
  return {
769
831
  tabId,
770
832
  entries: page.entries,