@liyuera/dsh-chrome-browser 0.5.0 → 0.6.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.
- package/README.md +31 -16
- package/extension/manifest.json +1 -1
- package/extension/service-worker.js +103 -4
- package/lib/activity.d.ts +35 -22
- package/lib/activity.d.ts.map +1 -1
- package/lib/activity.js +68 -28
- package/lib/activity.js.map +1 -1
- package/lib/backend.d.ts +45 -3
- package/lib/backend.d.ts.map +1 -1
- package/lib/backend.js +90 -8
- package/lib/backend.js.map +1 -1
- package/lib/client/BrowserActivity.d.ts +14 -11
- package/lib/client/BrowserActivity.d.ts.map +1 -1
- package/lib/client/BrowserActivity.js +86 -45
- package/lib/client/BrowserActivity.js.map +1 -1
- package/lib/client/activity.d.ts +16 -9
- package/lib/client/activity.d.ts.map +1 -1
- package/lib/client/activity.js +41 -20
- package/lib/client/activity.js.map +1 -1
- package/lib/client/index.d.ts +2 -2
- package/lib/client/index.d.ts.map +1 -1
- package/lib/client/index.js +9 -8
- package/lib/client/index.js.map +1 -1
- package/lib/client.js +195 -73
- package/lib/client.js.map +1 -1
- package/lib/expressions.d.ts +20 -0
- package/lib/expressions.d.ts.map +1 -1
- package/lib/expressions.js +44 -0
- package/lib/expressions.js.map +1 -1
- package/lib/routes.d.ts.map +1 -1
- package/lib/routes.js +10 -2
- package/lib/routes.js.map +1 -1
- package/lib/skill.js +3 -3
- package/lib/tools.d.ts.map +1 -1
- package/lib/tools.js +14 -1
- package/lib/tools.js.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -11,7 +11,7 @@ Chrome 浏览器控制插件(host + 浏览器半边):通过 Chrome 扩展桥(默
|
|
|
11
11
|
| `chrome_navigate` | 标签页导航到 URL(默认等待 `readyState=complete`) |
|
|
12
12
|
| `chrome_open` | 新开前台标签页;**默认等加载完成**(`readyState=complete`,上限 `waitLoadMs`)后返回,返回的标题已是加载后的标题。**URL 只接受 http/https/file**,其它 scheme 在开标签页**之前**就报错 |
|
|
13
13
|
| `chrome_close` | 按 id 关闭一个标签页;**`tabId` 必填,不接受 `active`**——关掉用户正在看的那一页几乎总是错的 |
|
|
14
|
-
| `chrome_screenshot` |
|
|
14
|
+
| `chrome_screenshot` | 截图落盘,返回路径/字节数/mime;模型用 `read_image` 查看。**`fullPage: true` 一次拍完整页**,`selector` 只拍某个元素(等同 DevTools 的「截取节点屏幕截图」) |
|
|
15
15
|
| `chrome_click` | CSS 选择器 `element.click()`(可选 `all` 批量)。返回**实际派发点击**的元素数(不是匹配到的数量),并报告「存在但不可点」的原因 |
|
|
16
16
|
| `chrome_hover` | 悬停到元素上,展开只在 hover 时出现的菜单/工具条 |
|
|
17
17
|
| `chrome_type` | 聚焦输入框并输入文本(默认先全选替换) |
|
|
@@ -22,9 +22,37 @@ Chrome 浏览器控制插件(host + 浏览器半边):通过 Chrome 扩展桥(默
|
|
|
22
22
|
| `chrome_console` | 采集/读取某个标签页的控制台(`action: start / read / stop`);**必须在页面出问题之前 start**,含浏览器自身抛的错误(资源加载失败、CSP 拦截) |
|
|
23
23
|
| `chrome_request_help` | 停下来请用户做只有人能做的事(登录、验证码、二次验证),等用户答复;`completed: false` 表示用户跳过了,不要重试 |
|
|
24
24
|
| `@` 标签页分组 | 在输入框敲 `@` 时列出实时标签页(行内是「标题 + URL」),选中插入一个引用芯片;发送后消息里只有这个引用,标签页的 URL 与 tabId 由宿主注入一条上下文消息给模型 |
|
|
25
|
-
|
|
|
25
|
+
| **活动状态条** | 会话标题栏末尾**常驻**的淡色胶囊:空闲显示「Chrome 就绪」,调用中显示当前动作与标签页,失败短暂变红 |
|
|
26
26
|
| `/chrome-browser` skill | 注册一个 agent skill:讲清什么时候用、调用顺序、失败怎么办、有哪些边界。模型通过 `skill` 工具读它,你也可以直接敲 `/chrome-browser`。宿主没有 skill 服务时静默跳过,工具照常可用 |
|
|
27
27
|
|
|
28
|
+
### 活动状态条:让用户看见 Agent 在干什么
|
|
29
|
+
|
|
30
|
+
插件在你的浏览器里操作时,**DSH 界面里原本没有任何指示**——用户只能盯着自己的页面看它自己变化。
|
|
31
|
+
|
|
32
|
+
现在**会话标题栏末尾**有一枚**常驻**的淡色胶囊:
|
|
33
|
+
|
|
34
|
+
```
|
|
35
|
+
● Chrome 就绪 空闲
|
|
36
|
+
● 点击 · 标签页 7 调用中
|
|
37
|
+
● 完成 / 失败 刚结束
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
| 状态 | 何时 | 显示 |
|
|
41
|
+
| --- | --- | --- |
|
|
42
|
+
| `Chrome 就绪` | 扩展已连接,空闲 | 淡绿点(最弱的存在感) |
|
|
43
|
+
| `点击 · 标签页 7` | 调用进行中 | 绿色脉冲点 + 当前动作 |
|
|
44
|
+
| `完成` | 调用成功结束后 2.5 秒 | 绿点 |
|
|
45
|
+
| `失败` | 调用失败后 7 秒,悬停显示原因 | 红点 |
|
|
46
|
+
| `Chrome 未连接` | 扩展没连上 | 灰点 |
|
|
47
|
+
| `扩展待更新` | 扩展在跑旧文件 | 黄点 |
|
|
48
|
+
|
|
49
|
+
- **它不再只出现在调用期间**。之前那版放在输入框上方、空闲时完全不渲染——而 `chrome_*` 调用多数是毫秒级,一条闪 50ms 的提示不是信息,是抖动,用户根本来不及看。
|
|
50
|
+
- 失败停留得比成功久(7 秒 vs 2.5 秒),因为它要求被读;连接类状态**优先于**调用结果——在一个断开的桥上显示「完成」是误导。
|
|
51
|
+
- 所有尺寸是**内联样式**:曾经把尺寸写在注入的样式表里,而那份样式没生效,内置的 512px 图标就按原始尺寸渲染,把标题栏撑满了(实测)。
|
|
52
|
+
- 数据来自插件自己的 `GET /chrome-browser/activity?sessionId=…`,应答里同时带上「桥是否连着」和「扩展是否在跑旧文件」——这两个状态没有任何工具调用会报告,因为断开的桥什么也不应答。
|
|
53
|
+
- 客户端每秒探一次(走 400ms 缓存),因此**每个打开的会话视图**都有一条本地回环 GET。宿主不可达时显示「Chrome 未连接」,不闪错误。
|
|
54
|
+
- `chrome_request_help` 在跑时显示「等待你操作」——这正是需要用户抬头的时刻。
|
|
55
|
+
|
|
28
56
|
### chrome_read:两个阅读模式
|
|
29
57
|
|
|
30
58
|
**`mode: 'text'`(默认)** —— 返回页面可见文本的**一个窗口**,不是一个死胡同:
|
|
@@ -186,20 +214,6 @@ chrome_request_help { reason: '请在打开的 example.com 页面里登录,然
|
|
|
186
214
|
- 走 DSH 的 `ctx.userQuestions` 服务。**宿主没有这个服务时**(精简组合、或被委派的子 agent 调用),工具会明确报错说明无法联系用户,而不是假装成功或挂住。
|
|
187
215
|
- 委派的子 agent 提问会被告知「子 agent 没有人工应答者」,这是宿主的策略,插件不绕过。
|
|
188
216
|
|
|
189
|
-
### 活动状态条:让用户看见 Agent 在干什么
|
|
190
|
-
|
|
191
|
-
插件在你的浏览器里操作时,**DSH 界面里原本没有任何指示**——用户只能盯着自己的页面看它自己变化。
|
|
192
|
-
|
|
193
|
-
现在输入框上方会出现一条状态条,**只在真的有工具在跑时**出现:
|
|
194
|
-
|
|
195
|
-
```
|
|
196
|
-
● 🟢 点击 标签页 7
|
|
197
|
-
```
|
|
198
|
-
|
|
199
|
-
- **空闲时完全不渲染**——常驻徽章是噪音,而每次调用的细节已经在对话里的工具卡片上。
|
|
200
|
-
- 数据来自插件自己的 `GET /chrome-browser/activity?sessionId=…`:`ctx.tools.register` 的每个定义都被包了一层,执行期间登记、结束即释放。
|
|
201
|
-
- 客户端每秒探一次(走 900ms 缓存),因此**每个打开的会话视图**都有一条本地回环 GET。宿主不可达时状态条保持隐藏,不闪错误。
|
|
202
|
-
- `chrome_request_help` 在跑时显示「等待你操作」——这正是需要用户抬头的时刻。
|
|
203
217
|
- 状态**不落盘、不进模型请求**:它只影响界面。
|
|
204
218
|
|
|
205
219
|
## 浏览器连接模式
|
|
@@ -356,6 +370,7 @@ DSH_CHROME_SMOKE=1 npx vitest run tests/smoke.spec.ts # headless Chrome 全链
|
|
|
356
370
|
- **`about:blank` 只能开、不能导航过去**:扩展注不进空白页,所以空白标签页读不了、点不了、跑不了 JS。`chrome_open` 允许开一个(当**临时中转页**用,随后 `chrome_navigate` 走),并且**不会等它加载**(没东西可等);但 `chrome_navigate` 拒绝导航到 `about:blank`——那会丢弃页面上原有的内容,只剩一个谁也读不了的标签页。
|
|
357
371
|
- **`chrome_close` 不猜目标**:`tabId` 是必填的精确 id。省略或写 `active` 都会报错——关掉「用户当前正在看的标签页」几乎总是错的。关闭窗口的最后一个标签页会连带关闭该窗口。
|
|
358
372
|
- **扩展自动更新依赖 `chrome.runtime.reload()` 能读到磁盘上的新文件**:这是该 API 的预期行为,但已加载的解压扩展由 Chrome 缓存,所以插件**只尝试一次**并在失败时明确报告,而不是无限重载。状态见 `/chrome-browser/ext/status`。
|
|
373
|
+
- **`chrome_screenshot` 默认只拍视口**:整页要显式传 `fullPage: true`(一次调用完成,不要靠滚动拼接——拼接会重复固定元素、接缝错位,而且很难对齐)。`selector` 拍单个元素,元素在首屏之下也照样能拍对。
|
|
359
374
|
- **`chrome_screenshot` 会在该标签页显示调试提示条**:它走 `chrome.debugger` 的 `Page.captureScreenshot`(与 CDP 后端同一条路),因此在标签页处于后台时照样可用,也**不会返回陈旧帧**。代价是 Chrome 在该标签页顶部显示「正在调试」提示条,且已打开 DevTools 时无法附着(会明确报错)。如果该标签页已被 `chrome_console` 采集,则复用同一会话,不产生第二次附着。
|
|
360
375
|
- ~~截图要求窗口可见~~:旧实现走 `chrome.tabs.captureVisibleTab`,窗口被遮挡时报 `image readback failed`,窗口停止重绘时**返回上一帧**(实测两张相隔数秒的截图逐字节相同,而返回的路径与字节数不会告诉你它是陈旧的)。已改为调试通道。
|
|
361
376
|
- **活动状态条是轮询的**:客户端每秒发一次本地回环 GET。将来若接入会话事件流可以去掉轮询,目前用的是插件已有的路由机制。
|
package/extension/manifest.json
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
"manifest_version": 3,
|
|
3
3
|
"name": "dsh Chrome Control",
|
|
4
4
|
"description": "Lets the local dsh agent drive this Chrome: list tabs, read pages, click and type, run JS, capture screenshots, read console output. Talks to dsh on this machine only.",
|
|
5
|
-
"version": "0.
|
|
5
|
+
"version": "0.4.1",
|
|
6
6
|
"permissions": [
|
|
7
7
|
"tabs",
|
|
8
8
|
"scripting",
|
|
@@ -112,7 +112,7 @@ const SUPPORTED_OPS = [
|
|
|
112
112
|
* user stayed on a stale extension with nothing to show for it. Only a value
|
|
113
113
|
* carried by the loaded code can tell the host which code is loaded.
|
|
114
114
|
*/
|
|
115
|
-
const BUILD_HASH = '
|
|
115
|
+
const BUILD_HASH = 'd20a9c8f1b8b1023b11ed2a3f36001f2e9f452c3c98ed02e976313164927f27e'
|
|
116
116
|
|
|
117
117
|
/** Introduce this worker: what it runs, what it can answer, and which code it is. */
|
|
118
118
|
async function hello() {
|
|
@@ -458,7 +458,10 @@ async function run(command) {
|
|
|
458
458
|
// failed" while the user is looking at something else — and when the
|
|
459
459
|
// window merely stops repainting it returns the PREVIOUS frame with no
|
|
460
460
|
// sign that it did. Page.captureScreenshot has neither problem.
|
|
461
|
-
const base64 = await captureViaDebugger(Number(command.args.tabId)
|
|
461
|
+
const base64 = await captureViaDebugger(Number(command.args.tabId), {
|
|
462
|
+
fullPage: command.args.fullPage === true,
|
|
463
|
+
selector: typeof command.args.selector === 'string' ? command.args.selector : undefined,
|
|
464
|
+
})
|
|
462
465
|
// Image bytes travel back as a plain HTTP POST, never as a WS JSON frame:
|
|
463
466
|
// an oversized frame closed the bridge right after a successful capture.
|
|
464
467
|
const blob = await (await fetch('data:image/jpeg;base64,' + base64)).blob()
|
|
@@ -481,6 +484,52 @@ async function run(command) {
|
|
|
481
484
|
}
|
|
482
485
|
}
|
|
483
486
|
|
|
487
|
+
/**
|
|
488
|
+
* Longest edge a capture may produce, in device pixels.
|
|
489
|
+
*
|
|
490
|
+
* A tab can be far taller than this (a package page runs past 12000 CSS px),
|
|
491
|
+
* and a texture beyond the GPU's limit makes the capture fail outright rather
|
|
492
|
+
* than downscale it. Width is left to follow the scale, so the aspect ratio is
|
|
493
|
+
* the page's.
|
|
494
|
+
*/
|
|
495
|
+
const MAX_CAPTURE_PX = 16_000
|
|
496
|
+
|
|
497
|
+
/**
|
|
498
|
+
* Clip rectangle covering the whole page, scaled down when it would not fit.
|
|
499
|
+
* @param tabId - the tab to measure.
|
|
500
|
+
* @returns the clip rectangle, with the scale that keeps it capturable.
|
|
501
|
+
*/
|
|
502
|
+
async function pageClip(tabId) {
|
|
503
|
+
const size = await pageExec(tabId, pageAgent, [{ op: 'size' }])
|
|
504
|
+
if (size === null || typeof size !== 'object' || !(size.width > 0) || !(size.height > 0)) {
|
|
505
|
+
throw new Error('截图失败:读不到页面尺寸')
|
|
506
|
+
}
|
|
507
|
+
const device = size.height * (size.dpr || 1)
|
|
508
|
+
return {
|
|
509
|
+
x: 0,
|
|
510
|
+
y: 0,
|
|
511
|
+
width: size.width,
|
|
512
|
+
height: size.height,
|
|
513
|
+
scale: device > MAX_CAPTURE_PX ? MAX_CAPTURE_PX / device : 1,
|
|
514
|
+
}
|
|
515
|
+
}
|
|
516
|
+
|
|
517
|
+
/**
|
|
518
|
+
* One element's clip rectangle, or a failure naming the selector.
|
|
519
|
+
* @param tabId - the tab to measure in.
|
|
520
|
+
* @param selector - CSS selector of the element to capture.
|
|
521
|
+
* @returns the clip rectangle in page coordinates.
|
|
522
|
+
*/
|
|
523
|
+
async function rectOf(tabId, selector) {
|
|
524
|
+
const box = await pageExec(tabId, pageAgent, [{ op: 'rect', selector }])
|
|
525
|
+
if (box === null || typeof box !== 'object' || box.matched !== 1) {
|
|
526
|
+
throw new Error(`截图失败:没有匹配 ${selector} 的元素`)
|
|
527
|
+
}
|
|
528
|
+
const { x, y, width, height } = box
|
|
529
|
+
if (!(width > 0) || !(height > 0)) throw new Error(`截图失败:${selector} 没有可见尺寸(宽 ${width} 高 ${height})`)
|
|
530
|
+
return { x, y, width, height, scale: 1 }
|
|
531
|
+
}
|
|
532
|
+
|
|
484
533
|
/** JPEG quality the screenshot is encoded at before upload. */
|
|
485
534
|
const SCREENSHOT_QUALITY = 75
|
|
486
535
|
|
|
@@ -492,9 +541,15 @@ const SCREENSHOT_QUALITY = 75
|
|
|
492
541
|
* answer with a stale frame. It costs the debugger infobar on that tab, which is
|
|
493
542
|
* why a tab `chrome_console` already attached needs no second attach.
|
|
494
543
|
*/
|
|
495
|
-
async function captureViaDebugger(tabId) {
|
|
544
|
+
async function captureViaDebugger(tabId, options) {
|
|
496
545
|
const id = Number(tabId)
|
|
497
546
|
if (!Number.isInteger(id)) throw new Error(`无效的标签页 id:${String(tabId)}`)
|
|
547
|
+
const selector = options !== undefined && typeof options.selector === 'string' && options.selector !== ''
|
|
548
|
+
? options.selector
|
|
549
|
+
: undefined
|
|
550
|
+
// `captureBeyondViewport` is what turns a viewport grab into a whole-page
|
|
551
|
+
// one; a clip needs it too, for any element below the fold.
|
|
552
|
+
const beyond = options !== undefined && (options.fullPage === true || selector !== undefined)
|
|
498
553
|
const targets = await chrome.debugger.getTargets()
|
|
499
554
|
const existing = targets.find(target => target.tabId === id && target.attached === true)
|
|
500
555
|
if (existing !== undefined && existing.extensionId !== chrome.runtime.id) {
|
|
@@ -503,10 +558,14 @@ async function captureViaDebugger(tabId) {
|
|
|
503
558
|
const ours = existing !== undefined
|
|
504
559
|
if (!ours) await chrome.debugger.attach({ tabId: id }, '1.3')
|
|
505
560
|
try {
|
|
561
|
+
const clip = selector !== undefined
|
|
562
|
+
? await rectOf(id, selector)
|
|
563
|
+
: options !== undefined && options.fullPage === true ? await pageClip(id) : undefined
|
|
506
564
|
const response = await chrome.debugger.sendCommand({ tabId: id }, 'Page.captureScreenshot', {
|
|
507
565
|
format: 'jpeg',
|
|
508
566
|
quality: SCREENSHOT_QUALITY,
|
|
509
|
-
captureBeyondViewport:
|
|
567
|
+
captureBeyondViewport: beyond,
|
|
568
|
+
...(clip === undefined ? {} : { clip }),
|
|
510
569
|
})
|
|
511
570
|
if (response === undefined || typeof response.data !== 'string' || response.data === '') {
|
|
512
571
|
throw new Error('截图失败:调试通道没有返回图像数据')
|
|
@@ -681,6 +740,44 @@ function pageAgent(request) {
|
|
|
681
740
|
return { found: true, pressed: true, submitted }
|
|
682
741
|
}
|
|
683
742
|
|
|
743
|
+
/**
|
|
744
|
+
* One element's box in PAGE coordinates, for a clipped screenshot.
|
|
745
|
+
*
|
|
746
|
+
* `getBoundingClientRect` is viewport-relative; `Page.captureScreenshot`'s
|
|
747
|
+
* clip is page-relative, so the scroll offset is added back. Page coordinates
|
|
748
|
+
* are also why the caller asks for `captureBeyondViewport`: the element may
|
|
749
|
+
* sit below the fold.
|
|
750
|
+
*/
|
|
751
|
+
function elementRect(selector) {
|
|
752
|
+
const el = document.querySelector(selector)
|
|
753
|
+
if (el === null) return { matched: 0 }
|
|
754
|
+
const rect = el.getBoundingClientRect()
|
|
755
|
+
return {
|
|
756
|
+
matched: 1,
|
|
757
|
+
x: rect.left + window.scrollX,
|
|
758
|
+
y: rect.top + window.scrollY,
|
|
759
|
+
width: rect.width,
|
|
760
|
+
height: rect.height,
|
|
761
|
+
}
|
|
762
|
+
}
|
|
763
|
+
|
|
764
|
+
/**
|
|
765
|
+
* The whole page's box and pixel ratio, for a full-page screenshot.
|
|
766
|
+
*
|
|
767
|
+
* `captureBeyondViewport` on its own does NOT widen the capture; it only
|
|
768
|
+
* permits a clip that reaches past the fold. The ratio is here because the
|
|
769
|
+
* caller's size cap is in device pixels.
|
|
770
|
+
*/
|
|
771
|
+
function pageSize() {
|
|
772
|
+
const el = document.documentElement
|
|
773
|
+
const body = document.body
|
|
774
|
+
return {
|
|
775
|
+
width: Math.max(el.scrollWidth, el.clientWidth, body === null ? 0 : body.scrollWidth),
|
|
776
|
+
height: Math.max(el.scrollHeight, el.clientHeight, body === null ? 0 : body.scrollHeight),
|
|
777
|
+
dpr: window.devicePixelRatio || 1,
|
|
778
|
+
}
|
|
779
|
+
}
|
|
780
|
+
|
|
684
781
|
// A throw must not escape: `chrome.scripting.executeScript` answers it with
|
|
685
782
|
// `result: undefined` and no `error`, so a malformed selector would reach the
|
|
686
783
|
// model as "no element matched" — the page never saw the query at all.
|
|
@@ -688,6 +785,8 @@ function pageAgent(request) {
|
|
|
688
785
|
switch (request.op) {
|
|
689
786
|
case 'click': return clickSelector(request.selector, request.all === true)
|
|
690
787
|
case 'inventory': return interactiveInventory()
|
|
788
|
+
case 'rect': return elementRect(request.selector)
|
|
789
|
+
case 'size': return pageSize()
|
|
691
790
|
case 'press': return pressKey(request.key, request.selector)
|
|
692
791
|
default: return { __dshPageError: '未知的页面操作:' + request.op }
|
|
693
792
|
}
|
package/lib/activity.d.ts
CHANGED
|
@@ -1,38 +1,51 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* What the plugin is doing right now, for the
|
|
2
|
+
* What the plugin is doing right now, for the persistent header indicator.
|
|
3
3
|
*
|
|
4
4
|
* The host half is the only place that knows a call is in flight, so it records
|
|
5
5
|
* every tool execution here and serves the snapshot over its own route; the
|
|
6
|
-
* browser half polls that route and renders
|
|
7
|
-
*
|
|
6
|
+
* browser half polls that route and renders one chip in the Session header.
|
|
7
|
+
* Nothing is persisted, and nothing crosses into the model's request.
|
|
8
8
|
* @module @liyuera/dsh-chrome-browser/activity
|
|
9
9
|
*/
|
|
10
10
|
import type { ToolDefinition } from '@deepseek-ai/dsh-tools';
|
|
11
|
-
/**
|
|
11
|
+
/**
|
|
12
|
+
* How long a settled call stays on screen before the chip returns to idle.
|
|
13
|
+
* Short enough not to linger, long enough that a call finishing between two
|
|
14
|
+
* polls is still seen: the browser half polls at POLL_MS, so a hold shorter
|
|
15
|
+
* than one poll interval can be missed entirely.
|
|
16
|
+
*/
|
|
17
|
+
export declare const DONE_HOLD_MS = 2500;
|
|
18
|
+
/** How long a failure stays on screen. Longer: it asks to be read. */
|
|
19
|
+
export declare const ERROR_HOLD_MS = 7000;
|
|
20
|
+
/** Which of the four things the chip can be saying. */
|
|
21
|
+
export type ActivityPhase = 'running' | 'done' | 'error' | 'ready';
|
|
22
|
+
/** What the browser half renders from. */
|
|
12
23
|
export interface ActivitySnapshot {
|
|
13
|
-
/**
|
|
14
|
-
readonly
|
|
15
|
-
/**
|
|
24
|
+
/** Current phase for the session being asked about. */
|
|
25
|
+
readonly phase: ActivityPhase;
|
|
26
|
+
/** Tool the phase belongs to, when it belongs to a call. */
|
|
16
27
|
readonly tool?: string;
|
|
17
|
-
/** Tab
|
|
28
|
+
/** Tab that call named, when it named one. */
|
|
18
29
|
readonly tabId?: string;
|
|
19
|
-
/**
|
|
20
|
-
readonly
|
|
21
|
-
/**
|
|
22
|
-
readonly
|
|
23
|
-
/** Epoch milliseconds the most recent call finished. */
|
|
24
|
-
readonly lastAt?: number;
|
|
30
|
+
/** Failure text, shortened, when the phase is `error`. */
|
|
31
|
+
readonly detail?: string;
|
|
32
|
+
/** Epoch milliseconds this phase began, or the last call's start. */
|
|
33
|
+
readonly since: number;
|
|
25
34
|
}
|
|
26
35
|
/** Route-facing view of one snapshot. */
|
|
27
36
|
export type ActivityAnswer = Record<string, string | number | boolean>;
|
|
28
37
|
/**
|
|
29
|
-
* In-flight and
|
|
30
|
-
* has one.
|
|
31
|
-
*
|
|
38
|
+
* In-flight and recently finished browser calls, keyed by session when the
|
|
39
|
+
* caller has one.
|
|
40
|
+
*
|
|
41
|
+
* The tracker holds facts, not timers: `snapshot` decides whether a settled
|
|
42
|
+
* call is still worth showing from the clock alone. That keeps a host tick out
|
|
43
|
+
* of the loop and means a browser that polls late sees the same answer a
|
|
44
|
+
* host-side timer would have produced.
|
|
32
45
|
*/
|
|
33
46
|
export declare class ActivityTracker {
|
|
34
47
|
private readonly running;
|
|
35
|
-
private readonly
|
|
48
|
+
private readonly settled;
|
|
36
49
|
/** Session key for a caller with no session identity. */
|
|
37
50
|
private static readonly ANONYMOUS;
|
|
38
51
|
/**
|
|
@@ -40,20 +53,20 @@ export declare class ActivityTracker {
|
|
|
40
53
|
* @param tool - the tool name.
|
|
41
54
|
* @param tabId - the tab the call named, when it named one.
|
|
42
55
|
* @param sessionId - the calling session, when the execution carried one.
|
|
43
|
-
* @returns the disposer that records the call
|
|
56
|
+
* @returns the disposer that records how the call ended; idempotent.
|
|
44
57
|
*/
|
|
45
|
-
begin(tool: string, tabId: string | undefined, sessionId: string | undefined): () => void;
|
|
58
|
+
begin(tool: string, tabId: string | undefined, sessionId: string | undefined): (ok: boolean, detail?: string) => void;
|
|
46
59
|
/**
|
|
47
60
|
* The current state for one session.
|
|
48
61
|
* @param sessionId - the session to report on; omit for the most recent call in any session.
|
|
49
|
-
* @returns the snapshot the
|
|
62
|
+
* @returns the snapshot the chip renders from.
|
|
50
63
|
*/
|
|
51
64
|
snapshot(sessionId?: string): ActivitySnapshot;
|
|
52
65
|
/** Drop every record; the plugin calls this on unload. */
|
|
53
66
|
clear(): void;
|
|
54
67
|
}
|
|
55
68
|
/**
|
|
56
|
-
* Wrap one tool definition so its execution is visible to the
|
|
69
|
+
* Wrap one tool definition so its execution is visible to the header chip.
|
|
57
70
|
*
|
|
58
71
|
* Every other member is carried over untouched: this adds observation, it does
|
|
59
72
|
* not change what the tool declares or returns.
|
package/lib/activity.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"activity.d.ts","sourceRoot":"","sources":["../src/activity.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA;AAE5D,
|
|
1
|
+
{"version":3,"file":"activity.d.ts","sourceRoot":"","sources":["../src/activity.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA;AAE5D;;;;;GAKG;AACH,eAAO,MAAM,YAAY,OAAQ,CAAA;AAEjC,sEAAsE;AACtE,eAAO,MAAM,aAAa,OAAQ,CAAA;AAKlC,uDAAuD;AACvD,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAA;AAElE,0CAA0C;AAC1C,MAAM,WAAW,gBAAgB;IAC/B,uDAAuD;IACvD,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAA;IAC7B,4DAA4D;IAC5D,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,8CAA8C;IAC9C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,0DAA0D;IAC1D,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,qEAAqE;IACrE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CACvB;AAmBD,yCAAyC;AACzC,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAA;AAEtE;;;;;;;;GAQG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgB;IACxC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA6B;IAErD,yDAAyD;IACzD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAK;IAEtC;;;;;;OAMG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,CAAC,EAAE,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,MAAM,KAAK,IAAI;IAyBrH;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,gBAAgB;IA8B9C,0DAA0D;IAC1D,KAAK,IAAI,IAAI;CAId;AAqBD;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,cAAc,EAAE,QAAQ,EAAE,eAAe,GAAG,cAAc,CAgBlG"}
|
package/lib/activity.js
CHANGED
|
@@ -1,20 +1,35 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* What the plugin is doing right now, for the
|
|
2
|
+
* What the plugin is doing right now, for the persistent header indicator.
|
|
3
3
|
*
|
|
4
4
|
* The host half is the only place that knows a call is in flight, so it records
|
|
5
5
|
* every tool execution here and serves the snapshot over its own route; the
|
|
6
|
-
* browser half polls that route and renders
|
|
7
|
-
*
|
|
6
|
+
* browser half polls that route and renders one chip in the Session header.
|
|
7
|
+
* Nothing is persisted, and nothing crosses into the model's request.
|
|
8
8
|
* @module @liyuera/dsh-chrome-browser/activity
|
|
9
9
|
*/
|
|
10
10
|
/**
|
|
11
|
-
*
|
|
12
|
-
*
|
|
13
|
-
*
|
|
11
|
+
* How long a settled call stays on screen before the chip returns to idle.
|
|
12
|
+
* Short enough not to linger, long enough that a call finishing between two
|
|
13
|
+
* polls is still seen: the browser half polls at POLL_MS, so a hold shorter
|
|
14
|
+
* than one poll interval can be missed entirely.
|
|
15
|
+
*/
|
|
16
|
+
export const DONE_HOLD_MS = 2_500;
|
|
17
|
+
/** How long a failure stays on screen. Longer: it asks to be read. */
|
|
18
|
+
export const ERROR_HOLD_MS = 7_000;
|
|
19
|
+
/** Longest failure text carried to the chip; the card holds the full one. */
|
|
20
|
+
const DETAIL_LIMIT = 120;
|
|
21
|
+
/**
|
|
22
|
+
* In-flight and recently finished browser calls, keyed by session when the
|
|
23
|
+
* caller has one.
|
|
24
|
+
*
|
|
25
|
+
* The tracker holds facts, not timers: `snapshot` decides whether a settled
|
|
26
|
+
* call is still worth showing from the clock alone. That keeps a host tick out
|
|
27
|
+
* of the loop and means a browser that polls late sees the same answer a
|
|
28
|
+
* host-side timer would have produced.
|
|
14
29
|
*/
|
|
15
30
|
export class ActivityTracker {
|
|
16
31
|
running = [];
|
|
17
|
-
|
|
32
|
+
settled = new Map();
|
|
18
33
|
/** Session key for a caller with no session identity. */
|
|
19
34
|
static ANONYMOUS = '';
|
|
20
35
|
/**
|
|
@@ -22,7 +37,7 @@ export class ActivityTracker {
|
|
|
22
37
|
* @param tool - the tool name.
|
|
23
38
|
* @param tabId - the tab the call named, when it named one.
|
|
24
39
|
* @param sessionId - the calling session, when the execution carried one.
|
|
25
|
-
* @returns the disposer that records the call
|
|
40
|
+
* @returns the disposer that records how the call ended; idempotent.
|
|
26
41
|
*/
|
|
27
42
|
begin(tool, tabId, sessionId) {
|
|
28
43
|
const entry = {
|
|
@@ -33,20 +48,27 @@ export class ActivityTracker {
|
|
|
33
48
|
};
|
|
34
49
|
this.running.push(entry);
|
|
35
50
|
let ended = false;
|
|
36
|
-
return () => {
|
|
51
|
+
return (ok, detail) => {
|
|
37
52
|
if (ended)
|
|
38
53
|
return;
|
|
39
54
|
ended = true;
|
|
40
55
|
const at = this.running.indexOf(entry);
|
|
41
56
|
if (at >= 0)
|
|
42
57
|
this.running.splice(at, 1);
|
|
43
|
-
|
|
58
|
+
const shortened = detail === undefined ? undefined : detail.slice(0, DETAIL_LIMIT);
|
|
59
|
+
this.settled.set(sessionId ?? ActivityTracker.ANONYMOUS, {
|
|
60
|
+
tool,
|
|
61
|
+
ok,
|
|
62
|
+
at: Date.now(),
|
|
63
|
+
...(entry.tabId === undefined ? {} : { tabId: entry.tabId }),
|
|
64
|
+
...(ok || shortened === undefined ? {} : { detail: shortened }),
|
|
65
|
+
});
|
|
44
66
|
};
|
|
45
67
|
}
|
|
46
68
|
/**
|
|
47
69
|
* The current state for one session.
|
|
48
70
|
* @param sessionId - the session to report on; omit for the most recent call in any session.
|
|
49
|
-
* @returns the snapshot the
|
|
71
|
+
* @returns the snapshot the chip renders from.
|
|
50
72
|
*/
|
|
51
73
|
snapshot(sessionId) {
|
|
52
74
|
const key = sessionId ?? ActivityTracker.ANONYMOUS;
|
|
@@ -54,23 +76,33 @@ export class ActivityTracker {
|
|
|
54
76
|
// one browser, so an unidentified call is still this caller's call.
|
|
55
77
|
const running = [...this.running].reverse()
|
|
56
78
|
.find(entry => entry.sessionId === undefined || sessionId === undefined || entry.sessionId === key);
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
: {
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
79
|
+
if (running !== undefined) {
|
|
80
|
+
return {
|
|
81
|
+
phase: 'running',
|
|
82
|
+
tool: running.tool,
|
|
83
|
+
since: running.startedAt,
|
|
84
|
+
...(running.tabId === undefined ? {} : { tabId: running.tabId }),
|
|
85
|
+
};
|
|
86
|
+
}
|
|
87
|
+
const settled = this.settled.get(key);
|
|
88
|
+
if (settled !== undefined) {
|
|
89
|
+
const hold = settled.ok ? DONE_HOLD_MS : ERROR_HOLD_MS;
|
|
90
|
+
if (Date.now() - settled.at < hold) {
|
|
91
|
+
return {
|
|
92
|
+
phase: settled.ok ? 'done' : 'error',
|
|
93
|
+
tool: settled.tool,
|
|
94
|
+
since: settled.at,
|
|
95
|
+
...(settled.tabId === undefined ? {} : { tabId: settled.tabId }),
|
|
96
|
+
...(settled.detail === undefined ? {} : { detail: settled.detail }),
|
|
97
|
+
};
|
|
98
|
+
}
|
|
99
|
+
}
|
|
100
|
+
return { phase: 'ready', since: settled?.at ?? 0 };
|
|
69
101
|
}
|
|
70
102
|
/** Drop every record; the plugin calls this on unload. */
|
|
71
103
|
clear() {
|
|
72
104
|
this.running.length = 0;
|
|
73
|
-
this.
|
|
105
|
+
this.settled.clear();
|
|
74
106
|
}
|
|
75
107
|
}
|
|
76
108
|
/** The tab a call named, as the tracker reads it from frozen arguments. */
|
|
@@ -84,8 +116,13 @@ function sessionIdOf(exec) {
|
|
|
84
116
|
const id = session?.id;
|
|
85
117
|
return typeof id === 'string' && id !== '' ? id : undefined;
|
|
86
118
|
}
|
|
119
|
+
/** A thrown value as one line of text for the chip. */
|
|
120
|
+
function messageOf(error) {
|
|
121
|
+
const text = error instanceof Error ? error.message : String(error);
|
|
122
|
+
return text.replace(/\s+/gu, ' ').trim();
|
|
123
|
+
}
|
|
87
124
|
/**
|
|
88
|
-
* Wrap one tool definition so its execution is visible to the
|
|
125
|
+
* Wrap one tool definition so its execution is visible to the header chip.
|
|
89
126
|
*
|
|
90
127
|
* Every other member is carried over untouched: this adds observation, it does
|
|
91
128
|
* not change what the tool declares or returns.
|
|
@@ -100,10 +137,13 @@ export function withActivity(definition, activity) {
|
|
|
100
137
|
async execute(args, exec) {
|
|
101
138
|
const end = activity.begin(definition.name, tabIdOf(args), sessionIdOf(exec));
|
|
102
139
|
try {
|
|
103
|
-
|
|
140
|
+
const value = await run(args, exec);
|
|
141
|
+
end(true);
|
|
142
|
+
return value;
|
|
104
143
|
}
|
|
105
|
-
|
|
106
|
-
end();
|
|
144
|
+
catch (error) {
|
|
145
|
+
end(false, messageOf(error));
|
|
146
|
+
throw error;
|
|
107
147
|
}
|
|
108
148
|
},
|
|
109
149
|
};
|
package/lib/activity.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"activity.js","sourceRoot":"","sources":["../src/activity.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;
|
|
1
|
+
{"version":3,"file":"activity.js","sourceRoot":"","sources":["../src/activity.ts"],"names":[],"mappings":"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"}
|
package/lib/backend.d.ts
CHANGED
|
@@ -13,6 +13,18 @@ import type { CapturedMessage } from './console-events.ts';
|
|
|
13
13
|
import type { WaitState } from './expressions.ts';
|
|
14
14
|
import { Chrome } from './chrome.ts';
|
|
15
15
|
import type { ResolvedChromeConfig } from './chrome.ts';
|
|
16
|
+
/**
|
|
17
|
+
* What a screenshot should cover.
|
|
18
|
+
*
|
|
19
|
+
* Absent fields mean "the visible viewport", which is what a caller who just
|
|
20
|
+
* wants the page as the user sees it needs.
|
|
21
|
+
*/
|
|
22
|
+
export interface ScreenshotOptions {
|
|
23
|
+
/** Capture the whole scrollable page rather than the viewport. */
|
|
24
|
+
fullPage?: boolean;
|
|
25
|
+
/** Capture one element instead, matched by CSS selector. */
|
|
26
|
+
selector?: string;
|
|
27
|
+
}
|
|
16
28
|
/** One tab as tools and the picker see it. */
|
|
17
29
|
export interface BackendTab {
|
|
18
30
|
id: string;
|
|
@@ -150,7 +162,7 @@ export interface BrowserBackend {
|
|
|
150
162
|
*/
|
|
151
163
|
waitFor(tabId: string, selector: string, state: WaitState, timeoutMs: number): Promise<boolean>;
|
|
152
164
|
type(tabId: string, selector: string, text: string, clear: boolean): Promise<void>;
|
|
153
|
-
screenshot(tabId: string): Promise<{
|
|
165
|
+
screenshot(tabId: string, options?: ScreenshotOptions): Promise<{
|
|
154
166
|
data: string;
|
|
155
167
|
path?: string;
|
|
156
168
|
mime?: string;
|
|
@@ -223,6 +235,17 @@ export declare class ExtensionBackend implements BrowserBackend {
|
|
|
223
235
|
* host process both settle.
|
|
224
236
|
*/
|
|
225
237
|
private reloadAskedFor;
|
|
238
|
+
/**
|
|
239
|
+
* Set when a build the host already asked about came back unchanged.
|
|
240
|
+
*
|
|
241
|
+
* The reload usually works. When it does not, the extension is re-reading a
|
|
242
|
+
* DIFFERENT copy of its files than the one this plugin ships — which happens
|
|
243
|
+
* when the install method changes while the host is running, because the host
|
|
244
|
+
* keeps resolving its old module path while Chrome keeps serving the copy it
|
|
245
|
+
* loaded. No number of reloads can close that, so it is reported rather than
|
|
246
|
+
* retried.
|
|
247
|
+
*/
|
|
248
|
+
private reloadIneffective;
|
|
226
249
|
private seq;
|
|
227
250
|
private readonly unacked;
|
|
228
251
|
/**
|
|
@@ -257,7 +280,7 @@ export declare class ExtensionBackend implements BrowserBackend {
|
|
|
257
280
|
select(tabId: string, selector: string, value: string): Promise<SelectOutcome>;
|
|
258
281
|
waitFor(tabId: string, selector: string, state: WaitState, timeoutMs: number): Promise<boolean>;
|
|
259
282
|
type(tabId: string, selector: string, text: string, clear: boolean): Promise<void>;
|
|
260
|
-
screenshot(tabId: string): Promise<{
|
|
283
|
+
screenshot(tabId: string, options?: ScreenshotOptions): Promise<{
|
|
261
284
|
data: string;
|
|
262
285
|
path?: string;
|
|
263
286
|
mime?: string;
|
|
@@ -277,6 +300,9 @@ export declare class ExtensionBackend implements BrowserBackend {
|
|
|
277
300
|
expectedBuild: string;
|
|
278
301
|
stale: boolean;
|
|
279
302
|
autoReloadAsked: boolean;
|
|
303
|
+
reloadAskedFor: string;
|
|
304
|
+
reloadIneffective: boolean;
|
|
305
|
+
ops: string;
|
|
280
306
|
};
|
|
281
307
|
/**
|
|
282
308
|
* Record the extension's self-report, and ask it to reload when it is running
|
|
@@ -334,11 +360,27 @@ export declare class CdpBackend implements BrowserBackend {
|
|
|
334
360
|
select(tabId: string, selector: string, value: string): Promise<SelectOutcome>;
|
|
335
361
|
waitFor(tabId: string, selector: string, state: WaitState, timeoutMs: number): Promise<boolean>;
|
|
336
362
|
type(tabId: string, selector: string, text: string, clear: boolean): Promise<void>;
|
|
337
|
-
screenshot(tabId: string): Promise<{
|
|
363
|
+
screenshot(tabId: string, options?: ScreenshotOptions): Promise<{
|
|
338
364
|
data: string;
|
|
339
365
|
path?: string;
|
|
340
366
|
mime?: string;
|
|
341
367
|
}>;
|
|
368
|
+
/**
|
|
369
|
+
* Clip rectangle covering the whole page, scaled down when it would not fit.
|
|
370
|
+
*
|
|
371
|
+
* Without a clip, `captureBeyondViewport` returns exactly one viewport — the
|
|
372
|
+
* flag permits reaching past the fold, it does not ask for it.
|
|
373
|
+
* @param endpoint - the tab's CDP endpoint.
|
|
374
|
+
* @returns the clip rectangle, with the scale that keeps it capturable.
|
|
375
|
+
*/
|
|
376
|
+
private pageClipOf;
|
|
377
|
+
/**
|
|
378
|
+
* One element's clip rectangle, or a failure naming the selector.
|
|
379
|
+
* @param endpoint - the tab's CDP endpoint.
|
|
380
|
+
* @param selector - CSS selector of the element to capture.
|
|
381
|
+
* @returns the clip rectangle in page coordinates.
|
|
382
|
+
*/
|
|
383
|
+
private clipOf;
|
|
342
384
|
startConsole(tabId: string): Promise<void>;
|
|
343
385
|
stopConsole(tabId: string): Promise<void>;
|
|
344
386
|
dispose(): void;
|