@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/README.md CHANGED
@@ -26,6 +26,8 @@ Chrome 浏览器控制插件(host + 浏览器半边):通过 Chrome 扩展桥(默
26
26
  | `@` 标签页分组 | 在输入框敲 `@` 时列出实时标签页(行内是「标题 + URL」),选中插入一个引用芯片;发送后消息里只有这个引用,标签页的 URL 与 tabId 由宿主注入一条上下文消息给模型 |
27
27
  | **活动状态条** | 会话标题栏末尾**常驻**的淡色胶囊:空闲显示「Chrome 就绪」,调用中显示当前动作与标签页,失败短暂变红 |
28
28
  | `/chrome-browser` skill | 注册一个 agent skill:讲清什么时候用、调用顺序、失败怎么办、有哪些边界。模型通过 `skill` 工具读它,你也可以直接敲 `/chrome-browser`。宿主没有 skill 服务时静默跳过,工具照常可用 |
29
+ | **沙箱后端**(`backend: 'sandbox'`) | 每个 agent 一个**独立**的 owned CDP 实例,并且是工具的**默认**后端:按 `agent.id` 键控复用、并行隔离(各自的标签页/窗口/profile 互不可见)、空闲回收、`headless` 默认 true;**此模式仍安装扩展桥**,所以用户真实 Chrome 始终可达(`@` 标签页分组也可用)。详见[配置](#配置) |
30
+ | **按调用选择后端**(`backend` 参数) | 每个**操作浏览器**的工具(除 `chrome_request_help`)有可选的 `backend`:`'sandbox'`(**默认**)= 这个 agent 自己的隔离浏览器;`'user'` = **用户真实 Chrome**(扩展桥),用于已登录页面、用户正在看的标签页。`backend: 'extension'` / `'cdp'` 配置下没有沙箱,两种取值都走真实浏览器(参数无效果) |
29
31
 
30
32
  ### 活动状态条:让用户看见 Agent 在干什么
31
33
 
@@ -402,26 +404,33 @@ $DSH_HOME/profiles/<profile>/node_modules/@liyuera/dsh-chrome-browser/extension/
402
404
  - id: chrome-browser
403
405
  name: '@liyuera/dsh-chrome-browser'
404
406
  config:
405
- backend: extension # extension(默认,真实 Chrome 通过扩展桥);cdp = DevTools 协议
407
+ backend: extension # extension(默认,真实 Chrome 通过扩展桥);cdp = DevTools 协议;sandbox = 每 agent 一个隔离沙箱
406
408
  bridgePort: 21987 # 插件自有的扩展桥固定端口(避开 dsh 旧版的 19387);0 = 系统分配(测试/诊断)
407
- port: 9222 # DevTools 端口(cdp 后端)
408
- mode: owned # 仅 cdp:owned = 插件专用 Chrome;user = profile 副本接管
409
+ port: 9222 # DevTools 端口(cdp 后端;sandbox 从此端口起逐个 +1 分配,释放后回用)
410
+ mode: owned # 仅 cdp:owned = 插件专用 Chrome;user = profile 副本接管;sandbox 下被 registry 强制为 owned
409
411
  autoRelaunch: false # user 模式:默认 false,绝不自动重启你的浏览器
410
412
  attachOnly: false # true = 只连已有调试端口,不启动/不关闭
411
413
  chromePath: null # 显式 Chrome 路径;缺省自动检测(macOS/Windows/Linux)
412
- profileDir: null # owned 默认 $DSH_HOME/chrome-browser/profile-<port>;user 默认真实 profile
414
+ profileDir: null # owned 默认 $DSH_HOME/chrome-browser/profile-<port>;user 默认真实 profile;sandbox 下被 registry 按 port 重算
413
415
  readTextLimit: 30000 # chrome_read 文本字符预算
414
416
  waitLoadMs: 8000 # chrome_navigate 加载等待
415
417
  timeoutMs: 15000 # 单命令/就绪超时
416
418
  screenshotDir: null # 默认 <tmp>/dsh-chrome-shots
417
419
  consoleIdleMs: 300000 # chrome_console 无读取自动释放调试器的时限(毫秒;0 = 不自动释放)
420
+ sandboxMaxConcurrent: 4 # 沙箱同时存活上限(backend:'sandbox');满且无空闲可回收时抛错
421
+ sandboxIdleMs: 600000 # 沙箱空闲回收时限(毫秒;默认 10 分钟;0 = 永不回收)
422
+ sandboxHeadless: true # 沙箱 Chrome 是否无头(默认 true = 不弹窗; 设 false 才弹可见窗口)
418
423
  ```
419
424
 
420
425
  `bridgePort` 是扩展要拨的固定回环端口(默认 **21987**,插件自有端口,理由见[浏览器连接模式](#浏览器连接模式)):dsh web server 的实际监听端口与它不同时,插件在这个端口上另起一个只服务扩展的 HTTP/WS 服务;相同时不另起 listener,由 dsh web server 应答。`bridgePort: 0` 交给系统分配,扩展不知道实际端口,只用于测试/诊断。`backend: 'cdp'` 不启动固定桥,扩展面路由只在 dsh web server 上。
421
426
 
427
+ `backend: 'sandbox'` 给每个 agent 一个**独立**的 owned CDP 实例:按 `agent.id` 键控创建与复用,不同 agent 的标签页、窗口与 profile 彼此隔离(调试端口从 `port` 起**首次分配时逐个 +1 递增,释放后的端口会回用**),互不可见——适合并行子代理各自开浏览器互不干扰。它是**工具的默认后端**:不传 `backend` 时调用走这个沙箱。实例空闲超过 `sandboxIdleMs`(默认 **10 分钟**)自动回收并释放端口,`0` 表示永不回收;`sandboxMaxConcurrent`(默认 **4**)是同时存活的沙箱上限,满且没有空闲实例可回收时,新 agent 会抛错(提示等待其它会话空闲回收,或调大该值);`sandboxHeadless`(默认 **true**)控制沙箱 Chrome 是否无头运行(默认不弹窗,设 `false` 才出现可见窗口)。session/子代理结束时(`agent/disposed`)对应沙箱自动释放。
428
+
429
+ **per-call 选择**:16 个操作浏览器的工具(除 `chrome_request_help`)都接受一个可选的 `backend` 参数——`'sandbox'`(**默认**,该 agent 自己的沙箱)或 `'user'`(**用户真实 Chrome**,走扩展桥,有登录态和你正开着的标签页)。需要读已登录的内网/后台,或操作用户 `@` 引用的真实标签页时,在那一次调用里传 `backend: 'user'` 即可;**同一次会话里可以在沙箱和真实浏览器之间逐调用切换**。`backend: 'extension'` / `'cdp'` 配置下没有沙箱可走,两种取值都落到真实浏览器(`cdp` 后端没有扩展桥;`extension` 与 `sandbox` 都会安装扩展桥,`sandbox` 下 `@` 标签页分组仍然可用)。
430
+
422
431
  ## Model Experience
423
432
 
424
- 模型可见的输入/输出只有 17 个工具 JSON 结果,加上被引用标签页的上下文:每次 `chrome_read` 最多携带约 `readTextLimit` 字符的页面文本;`chrome_screenshot` 只返回文件路径与元数据,页面视觉内容需通过 `read_image` 再读取;`chrome_eval` 结果上限 200k 字符;`chrome_webmcp_list` 把页面声明的工具名、说明、JSON Schema 与安全注解带进模型上下文,`chrome_webmcp_call` 的结果同样按 200k 字符截断;对象结果以 JSON 字符串返回,模型要自己 parse,`pending` / `navigated` 是状态标记而不是执行结果,页面报错按工具错误返回。从 `@` 菜单选中标签页时,客户端在草稿里插入一个引用芯片,它序列化成 `@"标题"`——用户消息里只有这个引用(宿主按文本形状投影成引用芯片),宿主随后在用户消息后注入一条本插件的上下文消息(`## Referenced Chrome tabs`),逐个列出被引用标签页的 `tabId` 与 URL,模型照着 id 调 `chrome_*` 即可。同名标签页会列出全部候选并提示向用户确认;引用没有匹配到任何在开的标签页(已关闭,或那其实是带空格的文件路径)时不注入任何东西。插件不做会话级标签页绑定,一次选择只影响它所在的那条消息。本插件不发任何 provider 请求,无 LLM/KV-cache 影响。
433
+ 模型可见的输入/输出只有 17 个工具 JSON 结果,加上被引用标签页的上下文:每次 `chrome_read` 最多携带约 `readTextLimit` 字符的页面文本;`chrome_screenshot` 只返回文件路径与元数据,页面视觉内容需通过 `read_image` 再读取;`chrome_eval` 结果上限 200k 字符;`chrome_webmcp_list` 把页面声明的工具名、说明、JSON Schema 与安全注解带进模型上下文,`chrome_webmcp_call` 的结果同样按 200k 字符截断;对象结果以 JSON 字符串返回,模型要自己 parse,`pending` / `navigated` 是状态标记而不是执行结果,页面报错按工具错误返回。从 `@` 菜单选中标签页时,客户端在草稿里插入一个引用芯片,它序列化成 `@"标题"`——用户消息里只有这个引用(宿主按文本形状投影成引用芯片),宿主随后在用户消息后注入一条本插件的上下文消息(`## Referenced Chrome tabs`),逐个列出被引用标签页的 `tabId` 与 URL,模型照着 id 调 `chrome_*` 即可(`@` 引用的是用户真实浏览器,调用时带 `backend: 'user'`)。同名标签页会列出全部候选并提示向用户确认;引用没有匹配到任何在开的标签页(已关闭,或那其实是带空格的文件路径)时不注入任何东西。插件不做会话级标签页绑定,一次选择只影响它所在的那条消息。本插件不发任何 provider 请求,无 LLM/KV-cache 影响。
425
434
 
426
435
  工具卡片与并发分类是**宿主 + 客户端**的呈现信息,不进入模型请求:模型拿到的是 17 个工具 JSON 结果与 tool schema。skill 正文只在被调用时加载,目录里常驻的只有一行 description。
427
436
 
@@ -478,6 +487,9 @@ workflow 在 `chrome-browser/` 里跑 `npm publish --access public`,tag 与 `pac
478
487
  - **插件只调用页面自己的工具,不注册工具**:`chrome_webmcp_*` 暴露的是页面实现的动作;页面不实现 WebMCP 就没有可调用的工具,插件不改写工具定义。
479
488
  - **owned 模式重启 dsh 后需首次调用恢复窗口**:专用 Chrome 的窗口在 dsh 重启后不会自动弹出,第一次使用工具/选择器时拉起(profile 持久化,标签页都在)。
480
489
  - **user 模式只支持手动带调试端口启动的 Chrome**:插件不自动接管、不重启;`autoRelaunch` 打开时仍建议先把 dsh 界面移到别的浏览器再使用。
490
+ - **`backend: 'sandbox'` 下工具默认走沙箱,真实浏览器要显式选**:沙箱模式给每个 agent 一个隔离浏览器,默认调用**不**碰用户真实 Chrome;需要登录态、用户正开着的标签页时,在那次调用里传 `backend: 'user'` 走扩展桥。扩展桥在 `sandbox` 模式也会安装,`@` 标签页分组与 `/chrome-browser/tabs` 照常可用;只有 `backend: 'cdp'` 没有扩展桥。`backend: 'extension'` 配置下没有沙箱,`backend` 参数的两种取值都落到真实浏览器。
491
+ - **沙箱 profile 按端口持久,顺序复用同一端口会继承登录态**:`defaultProfileDir(port)` 是 `$DSH_HOME/chrome-browser/profile-<port>`,跨租约复用——沙箱是**长期身份**而不是一次性容器。并发时各沙箱彼此隔离;但某个 agent 结束后端口被回收、下一个 agent 拿到同一端口时,会继承前一个沙箱的 cookies/localStorage/登录态。需要干净身份时,删除对应 profile 目录(或改 `port`/基础端口)再让新沙箱启动。
492
+ - **`lib/` 构建产物未随本分支重新生成**:本分支新增的 `backend-registry.js`/`caller.js`/`ports.js` 等不在提交的 `lib/` 里(tsc/tsdown 在独立仓库未恢复)。发布前必须 `npm run build` 并提交 `lib/`,否则发布的包不含沙箱功能。
481
493
  - **点击/输入是 DOM 事件 + CDP Input**:不模拟真实指针/MIME 手势,对依赖真实 pointer 事件或 iframe/shadow DOM 深层结构的页面不完全可靠;这些场景可用 `chrome_eval` 绕过。`chrome_click` 已把「派发了但真实用户点不到」的情形报进 `warnings`,但**警告是启发式**:命中测试在 shadow DOM 内按元素自己的 root 进行,闭合 shadow root 与 iframe 内部无法判定。
482
494
  - **等加载有上限,超时不报错**:`chrome_open` / `chrome_navigate` 默认等 `readyState=complete`,但最多等 `waitLoadMs`(默认 8000)。长轮询页面、挂住的资源不会等到底——到点就返回当前状态,由模型读一次再决定。要等**某个元素**出现就用 `chrome_wait`(同样超时不报错,靠 `satisfied` 判断)。
483
495
  - **`chrome_hover` 是合成事件**:送达页面监听器,但不设置浏览器自身的 hover 状态,纯 CSS `:hover` 显示的元素可能仍不出现。
package/lib/activity.d.ts CHANGED
@@ -75,4 +75,3 @@ export declare class ActivityTracker {
75
75
  * @returns an equivalent definition that reports the call.
76
76
  */
77
77
  export declare function withActivity(definition: ToolDefinition, activity: ActivityTracker): ToolDefinition;
78
- //# sourceMappingURL=activity.d.ts.map
package/lib/activity.js CHANGED
@@ -7,6 +7,7 @@
7
7
  * Nothing is persisted, and nothing crosses into the model's request.
8
8
  * @module @liyuera/dsh-chrome-browser/activity
9
9
  */
10
+ import { sessionIdOf } from "./caller.js";
10
11
  /**
11
12
  * How long a settled call stays on screen before the chip returns to idle.
12
13
  * Short enough not to linger, long enough that a call finishing between two
@@ -110,12 +111,6 @@ function tabIdOf(args) {
110
111
  const value = args?.tabId;
111
112
  return typeof value === 'string' && value !== '' ? value : undefined;
112
113
  }
113
- /** The executing session id, as the tracker reads it from the execution. */
114
- function sessionIdOf(exec) {
115
- const session = exec?.agent?.session;
116
- const id = session?.id;
117
- return typeof id === 'string' && id !== '' ? id : undefined;
118
- }
119
114
  /** A thrown value as one line of text for the chip. */
120
115
  function messageOf(error) {
121
116
  const text = error instanceof Error ? error.message : String(error);
@@ -1 +1 @@
1
- {"version":3,"file":"activity.js","sourceRoot":"","sources":["../src/activity.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"activity.js","sourceRoot":"","sources":["../src/activity.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,56 @@
1
+ /**
2
+ * Per-agent browser backends: the extension backend stays a shared singleton
3
+ * (the user's real browser), while sandbox backends are created per agent id,
4
+ * pooled with a cap, idle-reclaimed, and released when the agent disposes.
5
+ * @module @liyuera/dsh-chrome-browser/backend-registry
6
+ */
7
+ import type { BrowserBackend } from './backend.ts';
8
+ import type { ResolvedChromeConfig } from './chrome.ts';
9
+ /** One pooled per-agent sandbox plus its reclamation bookkeeping. */
10
+ export interface SandboxLease {
11
+ readonly agentId: string;
12
+ readonly backend: BrowserBackend;
13
+ readonly port: number;
14
+ lastUsedAt: number;
15
+ idleTimer?: NodeJS.Timeout;
16
+ }
17
+ /** Creates one sandbox backend for a fully-built per-port config. */
18
+ export type SandboxFactory = (config: ResolvedChromeConfig) => BrowserBackend;
19
+ /**
20
+ * Owns the lifecycle of every browser backend the plugin drives. `shared` is
21
+ * built once (extension or single cdp); sandboxes are pooled per agent id.
22
+ */
23
+ export declare class BackendRegistry {
24
+ private readonly config;
25
+ private readonly shared;
26
+ private readonly factory;
27
+ private readonly leases;
28
+ private readonly ports;
29
+ constructor(config: ResolvedChromeConfig, shared: BrowserBackend, factory: SandboxFactory);
30
+ /**
31
+ * The backend one tool call should drive.
32
+ *
33
+ * An explicit `'user'` preference always means the shared backend (the user's
34
+ * real Chrome via the extension bridge). Otherwise — in sandbox mode, with an
35
+ * agent — the call drives that agent's own sandbox; outside sandbox mode
36
+ * there is no sandbox to drive, so the preference is effectively ignored and
37
+ * the shared backend answers.
38
+ * @param exec - execution context carrying the calling agent's id.
39
+ * @param backend - optional per-call preference; omitted means `'sandbox'`.
40
+ */
41
+ resolve(exec: unknown, backend?: 'sandbox' | 'user'): BrowserBackend;
42
+ /** Release one agent's sandbox and return its port. Idempotent. */
43
+ release(agentId: string): void;
44
+ /** Release every sandbox and the shared backend. */
45
+ dispose(): void;
46
+ private ensureSandbox;
47
+ /**
48
+ * Per-instance config: owned mode + independent profile keyed by port.
49
+ *
50
+ * `attachOnly`/`autoRelaunch` are pinned off: a sandbox must spawn its own
51
+ * Chrome, never attach to (or relaunch) whatever already answers on its port.
52
+ */
53
+ private sandboxConfig;
54
+ private armIdle;
55
+ private evictIdle;
56
+ }
@@ -0,0 +1,120 @@
1
+ /**
2
+ * Per-agent browser backends: the extension backend stays a shared singleton
3
+ * (the user's real browser), while sandbox backends are created per agent id,
4
+ * pooled with a cap, idle-reclaimed, and released when the agent disposes.
5
+ * @module @liyuera/dsh-chrome-browser/backend-registry
6
+ */
7
+ import { defaultProfileDir } from "./chrome.js";
8
+ import { agentIdOf } from "./caller.js";
9
+ import { PortAllocator } from "./ports.js";
10
+ /**
11
+ * Owns the lifecycle of every browser backend the plugin drives. `shared` is
12
+ * built once (extension or single cdp); sandboxes are pooled per agent id.
13
+ */
14
+ export class BackendRegistry {
15
+ config;
16
+ shared;
17
+ factory;
18
+ leases = new Map();
19
+ ports;
20
+ constructor(config, shared, factory) {
21
+ this.config = config;
22
+ this.shared = shared;
23
+ this.factory = factory;
24
+ this.ports = new PortAllocator(config.port);
25
+ }
26
+ /**
27
+ * The backend one tool call should drive.
28
+ *
29
+ * An explicit `'user'` preference always means the shared backend (the user's
30
+ * real Chrome via the extension bridge). Otherwise — in sandbox mode, with an
31
+ * agent — the call drives that agent's own sandbox; outside sandbox mode
32
+ * there is no sandbox to drive, so the preference is effectively ignored and
33
+ * the shared backend answers.
34
+ * @param exec - execution context carrying the calling agent's id.
35
+ * @param backend - optional per-call preference; omitted means `'sandbox'`.
36
+ */
37
+ resolve(exec, backend) {
38
+ if (backend === 'user')
39
+ return this.shared;
40
+ if (this.config.backend !== 'sandbox')
41
+ return this.shared;
42
+ const agentId = agentIdOf(exec);
43
+ if (agentId === undefined)
44
+ return this.shared;
45
+ return this.ensureSandbox(agentId).backend;
46
+ }
47
+ /** Release one agent's sandbox and return its port. Idempotent. */
48
+ release(agentId) {
49
+ const lease = this.leases.get(agentId);
50
+ if (lease === undefined)
51
+ return;
52
+ this.leases.delete(agentId);
53
+ clearTimeout(lease.idleTimer);
54
+ this.ports.release(lease.port);
55
+ lease.backend.dispose();
56
+ }
57
+ /** Release every sandbox and the shared backend. */
58
+ dispose() {
59
+ for (const agentId of [...this.leases.keys()])
60
+ this.release(agentId);
61
+ this.shared.dispose();
62
+ }
63
+ ensureSandbox(agentId) {
64
+ const existing = this.leases.get(agentId);
65
+ if (existing !== undefined) {
66
+ existing.lastUsedAt = Date.now();
67
+ this.armIdle(existing);
68
+ return existing;
69
+ }
70
+ this.evictIdle();
71
+ if (this.leases.size >= this.config.sandboxMaxConcurrent) {
72
+ throw new Error(`chrome-browser 沙箱池已达上限(${this.config.sandboxMaxConcurrent});`
73
+ + '没有可回收的空闲会话。等待其它会话空闲回收,或调大 sandboxMaxConcurrent。');
74
+ }
75
+ const port = this.ports.allocate();
76
+ const backend = this.factory(this.sandboxConfig(port));
77
+ const lease = { agentId, backend, port, lastUsedAt: Date.now() };
78
+ this.leases.set(agentId, lease);
79
+ this.armIdle(lease);
80
+ return lease;
81
+ }
82
+ /**
83
+ * Per-instance config: owned mode + independent profile keyed by port.
84
+ *
85
+ * `attachOnly`/`autoRelaunch` are pinned off: a sandbox must spawn its own
86
+ * Chrome, never attach to (or relaunch) whatever already answers on its port.
87
+ */
88
+ sandboxConfig(port) {
89
+ return {
90
+ ...this.config,
91
+ backend: 'cdp',
92
+ mode: 'owned',
93
+ attachOnly: false,
94
+ autoRelaunch: false,
95
+ port,
96
+ profileDir: defaultProfileDir(port),
97
+ };
98
+ }
99
+ armIdle(lease) {
100
+ if (!(this.config.sandboxIdleMs > 0))
101
+ return;
102
+ clearTimeout(lease.idleTimer);
103
+ const timer = setTimeout(() => {
104
+ if (this.leases.get(lease.agentId) === lease)
105
+ this.release(lease.agentId);
106
+ }, this.config.sandboxIdleMs);
107
+ timer.unref?.();
108
+ lease.idleTimer = timer;
109
+ }
110
+ evictIdle() {
111
+ if (!(this.config.sandboxIdleMs > 0))
112
+ return;
113
+ const now = Date.now();
114
+ for (const [agentId, lease] of this.leases) {
115
+ if (now - lease.lastUsedAt >= this.config.sandboxIdleMs)
116
+ this.release(agentId);
117
+ }
118
+ }
119
+ }
120
+ //# sourceMappingURL=backend-registry.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"backend-registry.js","sourceRoot":"","sources":["../src/backend-registry.ts"],"names":[],"mappings":"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"}
package/lib/backend.d.ts CHANGED
@@ -498,4 +498,3 @@ export declare function buildBackend(config: ResolvedChromeConfig, onConsole?: C
498
498
  export declare function extensionUpgradeHandler(backend: BrowserBackend): (req: {
499
499
  headers: Record<string, string | string[] | undefined>;
500
500
  }, socket: Duplex, head: Buffer) => void;
501
- //# sourceMappingURL=backend.d.ts.map
package/lib/bridge.d.ts CHANGED
@@ -23,4 +23,3 @@ import type { BridgeReport } from './routes.ts';
23
23
  * @returns the state the extension status route reports, mutated when the bind settles.
24
24
  */
25
25
  export declare function installExtensionBridge(ctx: Context, backend: BrowserBackend, screenshotDir: string, bridgePort: number): BridgeReport;
26
- //# sourceMappingURL=bridge.d.ts.map
@@ -0,0 +1,9 @@
1
+ /**
2
+ * Reading the calling agent from a tool execution context. Shared by the
3
+ * activity tracker and the backend registry.
4
+ * @module @liyuera/dsh-chrome-browser/caller
5
+ */
6
+ /** The agent id of an execution, or undefined when there is none. */
7
+ export declare function agentIdOf(exec: unknown): string | undefined;
8
+ /** The session id of an execution, or undefined when there is none. */
9
+ export declare function sessionIdOf(exec: unknown): string | undefined;
package/lib/caller.js ADDED
@@ -0,0 +1,17 @@
1
+ /**
2
+ * Reading the calling agent from a tool execution context. Shared by the
3
+ * activity tracker and the backend registry.
4
+ * @module @liyuera/dsh-chrome-browser/caller
5
+ */
6
+ /** The agent id of an execution, or undefined when there is none. */
7
+ export function agentIdOf(exec) {
8
+ const id = exec?.agent?.id;
9
+ return typeof id === 'string' && id !== '' ? id : undefined;
10
+ }
11
+ /** The session id of an execution, or undefined when there is none. */
12
+ export function sessionIdOf(exec) {
13
+ const session = exec?.agent?.session;
14
+ const id = session?.id;
15
+ return typeof id === 'string' && id !== '' ? id : undefined;
16
+ }
17
+ //# sourceMappingURL=caller.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"caller.js","sourceRoot":"","sources":["../src/caller.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,qEAAqE;AACrE,MAAM,UAAU,SAAS,CAAC,IAAa;IACrC,MAAM,EAAE,GAAI,IAAwD,EAAE,KAAK,EAAE,EAAE,CAAA;IAC/E,OAAO,OAAO,EAAE,KAAK,QAAQ,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAA;AAC7D,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,WAAW,CAAC,IAAa;IACvC,MAAM,OAAO,GAAI,IAAsE,EAAE,KAAK,EAAE,OAAO,CAAA;IACvG,MAAM,EAAE,GAAG,OAAO,EAAE,EAAE,CAAA;IACtB,OAAO,OAAO,EAAE,KAAK,QAAQ,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAA;AAC7D,CAAC"}
package/lib/cdp.d.ts CHANGED
@@ -54,4 +54,3 @@ export declare function cdpEndpoint(socket: CdpSocket, options: CdpEndpointOptio
54
54
  * @returns the socket; `ready` rejects on error, close, or timeout.
55
55
  */
56
56
  export declare function websocketSocket(wsUrl: string, timeoutMs: number): CdpSocket;
57
- //# sourceMappingURL=cdp.d.ts.map
package/lib/chrome.d.ts CHANGED
@@ -30,8 +30,8 @@ export declare const DEFAULT_BRIDGE_PORT = 21987;
30
30
  export declare const DEFAULT_CONSOLE_IDLE_MS: number;
31
31
  /** Fully-resolved plugin configuration (schema defaults already applied). */
32
32
  export interface ResolvedChromeConfig {
33
- /** Backend: `extension` (real Chrome via the extension bridge, default) or `cdp`. */
34
- backend: 'extension' | 'cdp';
33
+ /** Backend: `extension` (real Chrome via the extension bridge, default), `cdp`, or `sandbox`. */
34
+ backend: 'extension' | 'cdp' | 'sandbox';
35
35
  /** DevTools HTTP port. */
36
36
  port: number;
37
37
  /** Explicit Chrome executable path; detection is skipped when set. `undefined` = auto-detect. */
@@ -63,6 +63,12 @@ export interface ResolvedChromeConfig {
63
63
  * one (tests and diagnostics only — the shipped extension cannot find it).
64
64
  */
65
65
  bridgePort: number;
66
+ /** Max concurrent sandbox instances (backend:'sandbox' only). */
67
+ sandboxMaxConcurrent: number;
68
+ /** Idle reclamation bound in ms for a sandbox; 0 = never. */
69
+ sandboxIdleMs: number;
70
+ /** Run sandbox Chrome headless (default true). */
71
+ sandboxHeadless: boolean;
66
72
  }
67
73
  /** One page target as the model sees it (internal ws url kept private). */
68
74
  export interface ChromeTab {
@@ -134,6 +140,12 @@ export declare function copyUserProfileTo(source: string, dest: string, copy: (f
134
140
  export declare function defaultScreenshotDir(): string;
135
141
  /** Apply config defaults for fields whose schema left them optional. */
136
142
  export declare function resolveChromeConfig(config: Partial<ResolvedChromeConfig>, _platform?: NodeJS.Platform): ResolvedChromeConfig;
143
+ /**
144
+ * Shared argv: debug port, profile, origin allowlist, the headless flag when
145
+ * `sandboxHeadless`, per-spawn extras, the constructor-injected extra args,
146
+ * and the optional startup URL.
147
+ */
148
+ export declare function buildChromeArgs(config: ResolvedChromeConfig, profileDir: string, extra: readonly string[], startupUrl?: string, extraArgs?: readonly string[]): string[];
137
149
  /** Injectable seams for tests. */
138
150
  export interface ChromeOptions {
139
151
  /** fetch implementation (defaults to the Node global). */
@@ -195,6 +207,13 @@ export declare class Chrome {
195
207
  private readonly spawnProcess;
196
208
  private proc;
197
209
  private stderrTail;
210
+ /**
211
+ * In-flight `ensure()` body. The tool layer runs concurrency-safe ops in
212
+ * parallel, so a cold owned instance would otherwise spawn Chrome twice
213
+ * (the loser exits, clearing `proc`, and the next `ensure()` then refuses
214
+ * its own port as foreign). One promise per flight makes that impossible.
215
+ */
216
+ private ensurePromise;
198
217
  constructor(config: ResolvedChromeConfig, options?: ChromeOptions);
199
218
  /** DevTools HTTP base url. */
200
219
  get baseUrl(): string;
@@ -205,8 +224,13 @@ export declare class Chrome {
205
224
  * `attachOnly`, reuse an existing endpoint, relaunch the user's Chrome
206
225
  * with a debug port in `user` mode, or spawn a dedicated instance in
207
226
  * `owned` mode.
227
+ *
228
+ * Single-flight: concurrent callers (the host batches concurrency-safe
229
+ * tool calls) share one in-flight attempt instead of racing to spawn.
208
230
  */
209
231
  ensure(): Promise<void>;
232
+ /** The one `ensure()` implementation; concurrent callers share it via `ensure()`. */
233
+ private doEnsure;
210
234
  /**
211
235
  * Copy the user's real profile to the custom location Chrome will run from:
212
236
  * its standard-location profile cannot carry a debug port in Chrome 136+.
@@ -262,13 +286,18 @@ export declare class Chrome {
262
286
  */
263
287
  reclaimOwnedLeftover(): void;
264
288
  private removeOwnerPidFile;
265
- /** Shared argv: debug port, profile, origin allowlist, extras, optional startup URL. */
266
- private chromeArgs;
267
289
  private spawnOwnedChrome;
268
290
  private spawnUserChrome;
269
291
  private spawnChrome;
270
292
  private waitForEndpoint;
293
+ /**
294
+ * Wait (bounded) for a DevTools endpoint to stop answering. A disposed owned
295
+ * Chrome lets go of its port a moment after its process is signaled, so a
296
+ * port that was just released to the allocator may still answer briefly.
297
+ * Never throws: the caller re-checks and decides.
298
+ * @param maxMs - upper bound for the wait, milliseconds.
299
+ */
300
+ private waitForEndpointToClose;
271
301
  private httpJson;
272
302
  }
273
303
  export {};
274
- //# sourceMappingURL=chrome.d.ts.map
package/lib/chrome.js CHANGED
@@ -266,8 +266,31 @@ export function resolveChromeConfig(config, _platform = process.platform) {
266
266
  screenshotDir: config.screenshotDir ?? defaultScreenshotDir(),
267
267
  consoleIdleMs: config.consoleIdleMs ?? DEFAULT_CONSOLE_IDLE_MS,
268
268
  bridgePort: config.bridgePort ?? DEFAULT_BRIDGE_PORT,
269
+ sandboxMaxConcurrent: config.sandboxMaxConcurrent ?? 4,
270
+ sandboxIdleMs: config.sandboxIdleMs ?? 10 * 60_000,
271
+ sandboxHeadless: config.sandboxHeadless ?? true,
269
272
  };
270
273
  }
274
+ /**
275
+ * Shared argv: debug port, profile, origin allowlist, the headless flag when
276
+ * `sandboxHeadless`, per-spawn extras, the constructor-injected extra args,
277
+ * and the optional startup URL.
278
+ */
279
+ export function buildChromeArgs(config, profileDir, extra, startupUrl, extraArgs = []) {
280
+ const args = [
281
+ `--remote-debugging-port=${config.port}`,
282
+ `--user-data-dir=${profileDir}`,
283
+ '--remote-allow-origins=*',
284
+ '--no-first-run',
285
+ '--no-default-browser-check',
286
+ ...(config.sandboxHeadless ? ['--headless=new'] : []),
287
+ ...extra,
288
+ ...extraArgs,
289
+ ];
290
+ if (startupUrl !== undefined)
291
+ args.push(startupUrl);
292
+ return args;
293
+ }
271
294
  /**
272
295
  * Claim one leftover plugin-owned Chrome from a previous run: the pid file
273
296
  * under the owned profile marks the process; it is killed only when its
@@ -309,6 +332,13 @@ export class Chrome {
309
332
  spawnProcess;
310
333
  proc;
311
334
  stderrTail = [];
335
+ /**
336
+ * In-flight `ensure()` body. The tool layer runs concurrency-safe ops in
337
+ * parallel, so a cold owned instance would otherwise spawn Chrome twice
338
+ * (the loser exits, clearing `proc`, and the next `ensure()` then refuses
339
+ * its own port as foreign). One promise per flight makes that impossible.
340
+ */
341
+ ensurePromise;
312
342
  constructor(config, options = {}) {
313
343
  this.config = config;
314
344
  this.httpFetch = options.httpFetch ?? fetch;
@@ -338,19 +368,45 @@ export class Chrome {
338
368
  * `attachOnly`, reuse an existing endpoint, relaunch the user's Chrome
339
369
  * with a debug port in `user` mode, or spawn a dedicated instance in
340
370
  * `owned` mode.
371
+ *
372
+ * Single-flight: concurrent callers (the host batches concurrency-safe
373
+ * tool calls) share one in-flight attempt instead of racing to spawn.
341
374
  */
342
375
  async ensure() {
376
+ const pending = (this.ensurePromise ??= this.doEnsure().finally(() => {
377
+ this.ensurePromise = undefined;
378
+ }));
379
+ return pending;
380
+ }
381
+ /** The one `ensure()` implementation; concurrent callers share it via `ensure()`. */
382
+ async doEnsure() {
383
+ if (this.config.mode === 'owned' && !this.config.attachOnly) {
384
+ // A browser this instance already spawned owns its port; nothing to
385
+ // arbitrate. This also keeps `ensure()` idempotent on every later call.
386
+ if (this.proc !== undefined && this.proc.exitCode === null) {
387
+ await this.waitForEndpoint();
388
+ return;
389
+ }
390
+ // Never adopt whatever answers on an owned port: a leftover instance
391
+ // from a previous run is reclaimed first, then a foreign endpoint is
392
+ // refused rather than silently driven.
393
+ this.reclaimOwnedLeftover();
394
+ if (await this.hasEndpoint())
395
+ await this.waitForEndpointToClose(2000);
396
+ if (await this.hasEndpoint()) {
397
+ throw new Error(`chrome-browser: 端口 ${this.config.port} 被一个不属于本插件的 Chrome 占用(reclaim 后仍应答);`
398
+ + '拒绝附着,以免接管你的浏览器。请释放该端口或改 sandbox 基础端口。');
399
+ }
400
+ this.spawnOwnedChrome();
401
+ await this.waitForEndpoint();
402
+ return;
403
+ }
343
404
  if (await this.hasEndpoint())
344
405
  return;
345
406
  if (this.config.attachOnly) {
346
407
  throw new Error(`no Chrome DevTools endpoint at ${this.baseUrl}; start Chrome with --remote-debugging-port=${this.config.port} `
347
408
  + '(e.g. "--remote-debugging-port=9222 --user-data-dir=<dir>"), or set attachOnly false');
348
409
  }
349
- if (this.config.mode === 'owned') {
350
- this.spawnOwnedChrome();
351
- await this.waitForEndpoint();
352
- return;
353
- }
354
410
  if (!this.config.autoRelaunch) {
355
411
  throw new Error(`no Chrome DevTools endpoint at ${this.baseUrl}; 插件未接管 Chrome。为避免自动关闭你正在使用的浏览器窗口 `
356
412
  + `(dsh 界面很可能就在里面,会造成循环),插件不会擅自重启 Chrome。请手动启动: Chrome --remote-debugging-port=`
@@ -625,25 +681,14 @@ export class Chrome {
625
681
  // best effort
626
682
  }
627
683
  }
628
- /** Shared argv: debug port, profile, origin allowlist, extras, optional startup URL. */
629
- chromeArgs(profileDir, extra, startupUrl) {
630
- const args = [
631
- `--remote-debugging-port=${this.config.port}`,
632
- `--user-data-dir=${profileDir}`,
633
- '--remote-allow-origins=*',
634
- '--no-first-run',
635
- '--no-default-browser-check',
636
- ...extra,
637
- ...this.extraArgs,
638
- ];
639
- if (startupUrl !== undefined)
640
- args.push(startupUrl);
641
- return args;
642
- }
643
684
  spawnOwnedChrome() {
644
685
  this.spawnChrome(this.config.profileDir, [], 'about:blank');
645
686
  try {
646
- writeFileSync(join(this.config.profileDir, '.dsh-owner.pid'), String(process.pid), 'utf8');
687
+ // Record the Chrome pid, not ours: `reclaimOwnedLeftover` uses the pid
688
+ // file to find the process whose command line carries our profile
689
+ // marker. Writing the dsh host pid made the leftover Chrome unfindable
690
+ // after a host crash.
691
+ writeFileSync(join(this.config.profileDir, '.dsh-owner.pid'), String(this.proc?.pid ?? process.pid), 'utf8');
647
692
  }
648
693
  catch {
649
694
  // marker file is best-effort
@@ -658,7 +703,7 @@ export class Chrome {
658
703
  const chromePath = resolveChromePath(this.config.chromePath);
659
704
  mkdirSync(profileDir, { recursive: true });
660
705
  this.stderrTail = [];
661
- const proc = this.spawnProcess(chromePath, this.chromeArgs(profileDir, extra, startupUrl));
706
+ const proc = this.spawnProcess(chromePath, buildChromeArgs(this.config, profileDir, extra, startupUrl, this.extraArgs));
662
707
  this.proc = proc;
663
708
  proc.stderr?.on('data', (chunk) => {
664
709
  this.stderrTail.push(chunk.toString('utf8').trimEnd());
@@ -688,6 +733,21 @@ export class Chrome {
688
733
  }
689
734
  throw new Error(`Chrome DevTools endpoint at ${this.baseUrl} did not become ready within ${this.config.timeoutMs}ms`);
690
735
  }
736
+ /**
737
+ * Wait (bounded) for a DevTools endpoint to stop answering. A disposed owned
738
+ * Chrome lets go of its port a moment after its process is signaled, so a
739
+ * port that was just released to the allocator may still answer briefly.
740
+ * Never throws: the caller re-checks and decides.
741
+ * @param maxMs - upper bound for the wait, milliseconds.
742
+ */
743
+ async waitForEndpointToClose(maxMs) {
744
+ const deadline = Date.now() + maxMs;
745
+ while (Date.now() < deadline) {
746
+ if (!(await this.hasEndpoint()))
747
+ return;
748
+ await sleep(100);
749
+ }
750
+ }
691
751
  async httpJson(path, init) {
692
752
  const controller = new AbortController();
693
753
  const timer = setTimeout(() => controller.abort(), this.config.timeoutMs);