@xnng/browser-relay 1.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (79) hide show
  1. package/LICENSE +22 -0
  2. package/README.md +445 -0
  3. package/docs/README.zh-CN.md +421 -0
  4. package/docs/benchmarks/browser-gaps-codex-ax.json +418 -0
  5. package/docs/benchmarks/browser-gaps-relay-after.json +655 -0
  6. package/docs/benchmarks/browser-gaps-relay-baseline.json +679 -0
  7. package/docs/benchmarks/browser-readiness-cost.json +106 -0
  8. package/docs/benchmarks/browser-runtime-balanced-headed.json +412 -0
  9. package/docs/benchmarks/browser-runtime-balanced-rtt50.json +412 -0
  10. package/docs/benchmarks/browser-runtime-balanced.json +412 -0
  11. package/docs/benchmarks/browser-runtime-rtt50.json +194 -0
  12. package/docs/benchmarks/browser-runtime.json +254 -0
  13. package/docs/benchmarks/browser-use-parity.json +54 -0
  14. package/docs/benchmarks/codex-extension-audit.json +131 -0
  15. package/docs/benchmarks/codex-native-protocol.md +69 -0
  16. package/docs/benchmarks/codex-native-replay.js +116 -0
  17. package/docs/benchmarks/codex-native-status.json +81 -0
  18. package/docs/benchmarks/codex-native.json +1003 -0
  19. package/docs/benchmarks/extension-sessions.png +0 -0
  20. package/docs/benchmarks/extension-tasks.png +0 -0
  21. package/docs/benchmarks/iframe-routing-regression.json +37 -0
  22. package/docs/browser-use-comparison.md +331 -0
  23. package/docs/browser-use-gap-audit.md +141 -0
  24. package/docs/browser-use-parity.md +105 -0
  25. package/docs/demo/intranet.html +103 -0
  26. package/docs/releases/v1.5.0.md +59 -0
  27. package/docs/releases/v1.5.1.md +16 -0
  28. package/docs/releases/v1.5.2.md +42 -0
  29. package/docs/releases/v1.5.3.md +33 -0
  30. package/docs/releases/v1.5.4.md +42 -0
  31. package/docs/releases/v1.6.0.md +16 -0
  32. package/docs/remote-control-hub.md +523 -0
  33. package/extension/activity.js +328 -0
  34. package/extension/automation.js +1839 -0
  35. package/extension/background.js +1854 -0
  36. package/extension/i18n.js +149 -0
  37. package/extension/icons/icon128.png +0 -0
  38. package/extension/icons/icon16.png +0 -0
  39. package/extension/icons/icon32.png +0 -0
  40. package/extension/icons/icon48.png +0 -0
  41. package/extension/manifest.json +47 -0
  42. package/extension/observations.js +109 -0
  43. package/extension/options.html +289 -0
  44. package/extension/options.js +269 -0
  45. package/extension/popup.html +74 -0
  46. package/extension/popup.js +105 -0
  47. package/extension/protocol.js +45 -0
  48. package/extension/remote-auth.js +18 -0
  49. package/extension/sessions.js +134 -0
  50. package/extension/snapshot.js +161 -0
  51. package/extension/task-groups.js +108 -0
  52. package/extension/tasks.js +186 -0
  53. package/extension/wait.js +89 -0
  54. package/hub/README.md +42 -0
  55. package/hub/package-lock.json +1544 -0
  56. package/hub/package.json +13 -0
  57. package/hub/src/rpc.js +41 -0
  58. package/hub/src/worker.js +322 -0
  59. package/hub/wrangler.example.toml +19 -0
  60. package/package.json +83 -0
  61. package/server/cdp-bridge.js +200 -0
  62. package/server/cli.js +1798 -0
  63. package/server/hub-server.js +258 -0
  64. package/server/install.js +250 -0
  65. package/server/mcp-server.js +504 -0
  66. package/server/npx-runner.js +96 -0
  67. package/server/relay-server.js +1356 -0
  68. package/server/remote-protocol.js +76 -0
  69. package/server/runtime-worker.js +166 -0
  70. package/server/script-runtime.js +189 -0
  71. package/server/sdk.js +307 -0
  72. package/server/service-state.js +103 -0
  73. package/server/snapshot.js +161 -0
  74. package/server/uninstall.js +61 -0
  75. package/server/windows-service-entry.js +58 -0
  76. package/server/windows-service.js +360 -0
  77. package/skills/browser-relay/SKILL.md +192 -0
  78. package/skills/browser-relay/references/legacy-api.md +163 -0
  79. package/skills/browser-relay/references/runtime.md +240 -0
package/docs/demo/intranet.html ADDED
@@ -0,0 +1,103 @@
1
+ <!doctype html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta charset="utf-8">
5
+ <meta name="viewport" content="width=device-width, initial-scale=1">
6
+ <title>Northstar Internal · Approvals</title>
7
+ <style>
8
+ :root {
9
+ color-scheme: light;
10
+ font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
11
+ color: #14213d;
12
+ background: #f3f6fb;
13
+ }
14
+ * { box-sizing: border-box; }
15
+ body { margin: 0; min-height: 100vh; background: #f3f6fb; }
16
+ button { font: inherit; }
17
+ .shell { display: grid; grid-template-columns: 240px 1fr; min-height: 100vh; }
18
+ aside { padding: 28px 20px; color: #edf4ff; background: #10213d; }
19
+ .brand { display: flex; gap: 12px; align-items: center; margin-bottom: 36px; font-weight: 750; }
20
+ .brand-mark { display: grid; width: 36px; height: 36px; place-items: center; border-radius: 11px; background: #62e6a7; color: #10213d; }
21
+ nav { display: grid; gap: 8px; }
22
+ nav button { padding: 12px 14px; border: 0; border-radius: 10px; color: #bfd0e9; background: transparent; text-align: left; cursor: pointer; }
23
+ nav button.active, nav button:hover { color: white; background: #203b63; }
24
+ main { padding: 30px 36px 48px; }
25
+ header { display: flex; align-items: center; justify-content: space-between; margin-bottom: 28px; }
26
+ h1 { margin: 0 0 6px; font-size: 30px; letter-spacing: -0.03em; }
27
+ .muted { margin: 0; color: #66758e; }
28
+ .session { display: flex; gap: 10px; align-items: center; padding: 10px 14px; border: 1px solid #d8e2f0; border-radius: 999px; background: white; font-size: 13px; }
29
+ .dot { width: 9px; height: 9px; border-radius: 50%; background: #22b573; box-shadow: 0 0 0 4px #dcf8eb; }
30
+ .stats { display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 16px; margin-bottom: 24px; }
31
+ .card { padding: 20px; border: 1px solid #dfe7f2; border-radius: 16px; background: white; box-shadow: 0 8px 24px rgb(29 55 90 / 6%); }
32
+ .label { color: #718096; font-size: 13px; font-weight: 650; text-transform: uppercase; letter-spacing: 0.06em; }
33
+ .value { margin-top: 8px; font-size: 30px; font-weight: 780; }
34
+ .panel-head { display: flex; align-items: center; justify-content: space-between; margin-bottom: 16px; }
35
+ h2 { margin: 0; font-size: 20px; }
36
+ .primary { padding: 10px 15px; border: 0; border-radius: 10px; background: #2457e6; color: white; cursor: pointer; font-weight: 700; }
37
+ .primary:hover { background: #1745c7; }
38
+ table { width: 100%; border-collapse: collapse; }
39
+ th, td { padding: 14px 10px; border-bottom: 1px solid #e8edf5; text-align: left; }
40
+ th { color: #718096; font-size: 12px; text-transform: uppercase; letter-spacing: 0.05em; }
41
+ .pill { display: inline-flex; padding: 5px 9px; border-radius: 999px; background: #fff3d6; color: #8a5a00; font-size: 12px; font-weight: 700; }
42
+ .result { display: none; margin: 0 0 18px; padding: 13px 15px; border: 1px solid #a9e5c7; border-radius: 12px; background: #eafaf2; color: #17633e; font-weight: 650; }
43
+ .result.visible { display: block; }
44
+ @media (max-width: 760px) {
45
+ .shell { grid-template-columns: 1fr; }
46
+ aside { display: none; }
47
+ main { padding: 22px 18px; }
48
+ header { align-items: flex-start; gap: 14px; }
49
+ .stats { grid-template-columns: 1fr; }
50
+ }
51
+ </style>
52
+ </head>
53
+ <body>
54
+ <div class="shell">
55
+ <aside>
56
+ <div class="brand"><span class="brand-mark">N</span>Northstar Internal</div>
57
+ <nav aria-label="Internal navigation">
58
+ <button>Overview</button>
59
+ <button class="active" data-testid="pending-approvals">Pending approvals</button>
60
+ <button>Reports</button>
61
+ <button>Team directory</button>
62
+ </nav>
63
+ </aside>
64
+ <main>
65
+ <header>
66
+ <div>
67
+ <h1>Pending approvals</h1>
68
+ <p class="muted">Mock internal dashboard · no real company data</p>
69
+ </div>
70
+ <div class="session"><span class="dot"></span>SSO session active · office device</div>
71
+ </header>
72
+
73
+ <section class="stats" aria-label="Approval summary">
74
+ <article class="card"><div class="label">Pending today</div><div class="value" data-testid="pending-count">3</div></article>
75
+ <article class="card"><div class="label">Due this week</div><div class="value">7</div></article>
76
+ <article class="card"><div class="label">Average age</div><div class="value">1.4d</div></article>
77
+ </section>
78
+
79
+ <p class="result" role="status" data-testid="refresh-result">Refreshed: 3 approvals are waiting for review.</p>
80
+
81
+ <section class="card">
82
+ <div class="panel-head">
83
+ <h2>Needs review</h2>
84
+ <button class="primary" data-testid="refresh-approvals">Refresh approvals</button>
85
+ </div>
86
+ <table>
87
+ <thead><tr><th>Request</th><th>Owner</th><th>Submitted</th><th>Status</th></tr></thead>
88
+ <tbody>
89
+ <tr><td>Vendor access renewal</td><td>Maya Chen</td><td>09:12</td><td><span class="pill">Pending</span></td></tr>
90
+ <tr><td>Analytics workspace</td><td>Jon Bell</td><td>08:47</td><td><span class="pill">Pending</span></td></tr>
91
+ <tr><td>Quarterly export</td><td>Priya Shah</td><td>Yesterday</td><td><span class="pill">Pending</span></td></tr>
92
+ </tbody>
93
+ </table>
94
+ </section>
95
+ </main>
96
+ </div>
97
+ <script>
98
+ document.querySelector('[data-testid="refresh-approvals"]').addEventListener('click', () => {
99
+ document.querySelector('[data-testid="refresh-result"]').classList.add('visible');
100
+ });
101
+ </script>
102
+ </body>
103
+ </html>
package/docs/releases/v1.5.0.md ADDED
@@ -0,0 +1,59 @@
1
+ # Browser Relay 1.5.0
2
+
3
+ Browser Relay 1.5 adds complete page reading, persistent JavaScript workflows, and managed browser sessions to your existing, logged-in Chrome. Local and remote workflows use the same extension executor.
4
+
5
+ ## Highlights
6
+
7
+ - **Read complete content with usable context.** `read`, `tab.read()` and MCP `browser_read` preserve document order, article labels, full links and actionable refs. Read a selected subtree, include its same-origin and cross-origin frames, and follow `nextCursor` for long pages. Unread pages do not advance the diff baseline.
8
+ - **Keep scripts and browser handles between calls.** MCP `browser_exec` and CLI `repl` retain top-level `await`, variables and tab handles. Ordered action groups run in the extension and return the resulting state. Runtime output has its own recoverable pagination; one-shot CLI `exec` drains it before exiting.
9
+ - **Combine semantic and visual operations.** Use scoped role/name locators, fresh refs or CSS; combine text and screenshots with `observe({mode:'both'})`. Click, hover and drag support screenshot coordinate mapping. Readiness waits check controls before dispatch without replaying input.
10
+ - **Coordinate ownership of shared tabs.** Managed sessions claim tabs, renew leases, and support release, handoff and stop. The extension popup shows owners and lets the user stop a session while keeping its pages open.
11
+ - **Stop pending work reliably.** Request cancellation, timeouts and disconnects propagate through the SDK, CLI, MCP and hub. Errors retain task identity and available partial results. Cancellation stops subsequent Relay actions; it cannot undo dispatched input or a page's own requests.
12
+ - **Diagnose the actual running extension.** Protocol negotiation and `doctor` report the live executor version and instance, and explain when an older extension needs reloading.
13
+
14
+ ## Upgrade from 1.4.x
15
+
16
+ ```bash
17
+ npm install -g @linsoai/browser-relay@1.5.0
18
+ browser-relay install
19
+ browser-relay restart
20
+ browser-relay path
21
+ ```
22
+
23
+ Reload the existing unpacked Browser Relay extension in Chrome using the extension folder shown by `path`. Both the CLI/daemon and extension must be updated; restarting the daemon alone does not update the running Chrome extension.
24
+
25
+ Then verify the running pair:
26
+
27
+ ```bash
28
+ browser-relay capabilities
29
+ browser-relay doctor
30
+ browser-relay tabs
31
+ ```
32
+
33
+ Update the installed Browser Relay skill for the agents you use, for example:
34
+
35
+ ```bash
36
+ browser-relay skill install --agent codex
37
+ ```
38
+
39
+ ### Compatibility and deployment notes
40
+
41
+ - Existing CSS/HTTP commands remain available. A tab claimed by a managed session must be released or handed off before switching clients, including legacy commands and the local CDP bridge. MCP tools and persistent runtimes can have different session IDs; coordinate with `browser.sessionId`.
42
+ - Background pages may defer rendering. Scrolling requires a foreground tab or explicit `allowFocus`; semantic background clicks report when they use DOM activation.
43
+ - Session leases, element refs and continuation caches belong to the running extension/runtime and can expire on navigation, eviction or restart. Re-observe or establish a new session when an error requires it.
44
+ - Local scripts run with the agent's OS permissions. Process isolation supplies timeout/reset behavior, not an OS security sandbox.
45
+ - Self-hosted Node/Cloudflare hubs should be upgraded with this version for hub-side cancellation. Publishing the npm package or GitHub Release does not deploy an existing hub or update a Chrome Web Store installation.
46
+
47
+ ## Validation
48
+
49
+ The release was independently reviewed with Astra. The ten issues found during development were fixed and reverified, including iframe omissions, reordered content, long-output truncation, CSS subtree reading, cancellation races, CDP connection compatibility and prerelease publishing guards.
50
+
51
+ Local checks: 124 unit tests passed (8 environment-dependent skips), and 36 isolated-browser tests passed. Additional checks covered 180,000-character/emoji reading, recovery after large log output, and real Node hub timeouts where no subsequent click executed. Worker packaging and type generation passed locally.
52
+
53
+ These results are not a claim of performance parity with Codex native Browser Use. The final version has not completed the logged-in X comparison, and deployed Cloudflare client-disconnect behavior was not exercised in this validation.
54
+
55
+ ## 中文摘要
56
+
57
+ 1.5.0 补齐了完整正文与 iframe 阅读、持久脚本、文字和截图联动、标签页归属与交接，以及贯穿 CLI／SDK／MCP／hub 的取消处理。Astra 独立审查发现的十项问题均已修复并复验通过。
58
+
59
+ 升级时须更新 npm 包、执行 `browser-relay restart` 并重载正在运行的 Chrome 扩展，再执行 `capabilities` 与 `doctor`。已认领的标签页切换客户端前应 release 或 handoff。自托管 hub 需要同步升级；本次包发布不自动部署现有 hub。这里的验证结果不代表新版已经追平 Codex 原生的 X 浏览效率。
package/docs/releases/v1.5.1.md ADDED
@@ -0,0 +1,16 @@
1
+ # Browser Relay 1.5.1
2
+
3
+ `browser-relay skill` and `browser-relay skill command` now print an installation command for all agents using `--agent "*"`. The wildcard is quoted for safe copying into a shell. Doctor guidance and the English/Chinese documentation use the same default; explicit agent selection remains available.
4
+
5
+ These commands print installation instructions. Run the printed command to install the Skill.
6
+
7
+ Upgrade:
8
+
9
+ ```bash
10
+ npm install -g @linsoai/browser-relay@1.5.1
11
+ browser-relay skill
12
+ ```
13
+
14
+ ## 中文
15
+
16
+ 默认 Skill 安装提示改为所有 Agent（`--agent "*"`），并同步 doctor 提示和中英文文档；指定 Agent 的用法继续保留。
package/docs/releases/v1.5.2.md ADDED
@@ -0,0 +1,42 @@
1
+ # Browser Relay 1.5.2
2
+
3
+ The working tab now shows a softly diffused, multicolor edge glow and a blinking
4
+ status dot on its website icon. Cool and warm color pools move independently,
5
+ with no solid border or rounded frame. Page titles stay unchanged.
6
+
7
+ - Fix unwanted activity animation when opening ordinary tabs. Automatic debugger
8
+ attachment, logging subscriptions, session claims and heartbeats stay idle.
9
+ - Keep the indicator active throughout a running operation, including waits.
10
+ Overlapping operations share it; completion, cancellation and disconnect clean
11
+ it up, and active navigation carries it to the new document.
12
+ - Restore the website's latest icon after work. The decoration does not intercept
13
+ clicks, change page layout or appear in accessibility snapshots. Reduced-motion
14
+ settings show a static glow and status dot.
15
+
16
+ ## Upgrade
17
+
18
+ ```bash
19
+ npm install -g @linsoai/browser-relay@1.5.2
20
+ browser-relay restart
21
+ browser-relay path
22
+ ```
23
+
24
+ Reload the existing unpacked Browser Relay extension in `chrome://extensions`,
25
+ using the extension directory printed by `browser-relay path`. Restarting the
26
+ daemon alone does not update the running Chrome extension. Run
27
+ `browser-relay doctor` to confirm the live version.
28
+
29
+ The extension adds Chrome's `favicon` permission to read locally cached website
30
+ icons. No external favicon service is used. This release updates npm and the
31
+ GitHub extension download; it does not update a Chrome Web Store installation.
32
+
33
+ Validation: 130 unit tests passed (9 environment-dependent skips), 37 isolated
34
+ browser tests passed, and the production dependency audit found no vulnerabilities.
35
+
36
+ ## 中文
37
+
38
+ 工作标签页改为多彩流动柔光与网站图标上的闪烁状态点。冷暖光团独立游动，
39
+ 没有实体边框或圆角，保留网站原标题。修复普通新标签页误触发动画的问题；
40
+ 任务结束、取消或断连后恢复网站图标，支持减少动态效果设置。
41
+
42
+ 升级 npm 包后，还需在 Chrome 扩展管理页重载本地插件，光晕才会更新。
package/docs/releases/v1.5.3.md ADDED
@@ -0,0 +1,33 @@
1
+ # Browser Relay 1.5.3
2
+
3
+ Fix activity indicators disappearing before short reads, clicks and scrolls have
4
+ shown a full animation cycle. After an operation completes, the page glow and
5
+ favicon animation now remain active for four seconds instead of 600 ms.
6
+ Another operation renews that interval without restarting the animation.
7
+
8
+ Cancellation, disconnect and tab closure keep their immediate cleanup behavior.
9
+ Ordinary tabs, connection setup and session heartbeats still do not start the
10
+ effect. The glow's colors, movement and shape are unchanged.
11
+
12
+ The regression test uses completed short reads with gaps between calls. Live
13
+ Chrome verification on X covered eight reads and four scrolls taking 47–129 ms
14
+ each: the indicator stayed active between calls, the favicon animated, and the
15
+ effect cleared after the final operation's four-second interval.
16
+
17
+ ## Upgrade
18
+
19
+ ```bash
20
+ npm install -g @linsoai/browser-relay@1.5.3
21
+ browser-relay restart
22
+ browser-relay doctor
23
+ ```
24
+
25
+ If doctor still reports an older running Chrome executor, reload the existing
26
+ unpacked Browser Relay extension in Chrome. The extension ZIP is also attached
27
+ to this release.
28
+
29
+ ## 中文
30
+
31
+ 修复普通读取、点击和滚动时动画过早消失的问题。操作结束后保留 4 秒，
32
+ 期间的新操作会延续同一段动画；取消、断连和关闭标签页仍立即清理。
33
+ 已在真实 X 页面完成短操作验证，页面光晕和标签图标动画均正常。
package/docs/releases/v1.5.4.md ADDED
@@ -0,0 +1,42 @@
1
+ # Browser Relay 1.5.4
2
+
3
+ Fix background scrolling unexpectedly bringing Chrome tabs and windows to the
4
+ foreground. Hidden tabs now scroll through the DOM, including nested scrollable
5
+ panels, without activation. Older callers passing `allowFocus:true` to scroll
6
+ also stay in the background. Foreground scrolling keeps native wheel input.
7
+
8
+ The Skill, runtime instructions and MCP tool descriptions now tell agents to
9
+ preserve the user's foreground tab by default. Explicit focus remains available
10
+ when the user requests foreground operation or a visual demonstration.
11
+
12
+ Hidden sites may defer rendering new content. Scroll results distinguish viewport
13
+ movement from observed text changes; an unchanged feed is not a reason to steal
14
+ focus. Background iframe scrolling requires an explicit target with `frameId`.
15
+
16
+ Regression coverage checks real tab visibility and Chrome activation events.
17
+ Live verification in the user's Chrome confirmed that background reads, input,
18
+ semantic clicks and scrolling leave the test tab hidden throughout.
19
+
20
+ ## Upgrade
21
+
22
+ ```bash
23
+ npm install -g @linsoai/browser-relay@1.5.4
24
+ browser-relay restart
25
+ browser-relay skill
26
+ browser-relay doctor
27
+ ```
28
+
29
+ Reload the existing unpacked Browser Relay extension in Chrome to load the new
30
+ executor. Run the install command printed by `browser-relay skill` to refresh
31
+ installed Skills, and restart persistent MCP clients so agents receive the
32
+ updated foreground policy. The extension ZIP is attached to this release.
33
+
34
+ ## 中文
35
+
36
+ 修复后台滚动把标签页和浏览器窗口顶到前台的问题。后台页面和内嵌滚动区域
37
+ 改用 DOM 滚动，即使旧调用方传入 `allowFocus:true` 也不会因滚动切到前台。
38
+ 同步更新 Skill、运行时提示词和 MCP 工具说明，默认保留用户当前前台页面。
39
+
40
+ 已通过后台可见性与 Chrome 激活事件回归，并在日常 Chrome 实测读取、输入、
41
+ 语义点击和滚动全程保持后台。网站可能延迟后台内容渲染，此时应报告限制，
42
+ 不能自动抢焦点。显式前台操作能力保留。
package/docs/releases/v1.6.0.md ADDED
@@ -0,0 +1,16 @@
1
+ # Browser Relay 1.6.0
2
+
3
+ Named sessions now manage native Chrome tab groups. The first task-created tab creates a group, subsequent tabs and page-opened popups join it, and separate tasks remain isolated. A session spanning windows has one group per window.
4
+
5
+ - `session start --session <id> --label <title>` assigns a readable group title.
6
+ - `new-tab --session <id>` and `exec --session <id>` share the same task across CLI calls.
7
+ - `session complete --session <id>` closes tracked task-created pages and removes empty open groups. It rejects pending operations and reports partial cleanup failures for retry.
8
+ - `release` keeps a result page outside the task group; `handoff` transfers its group and ownership.
9
+ - Stop, expiry, disconnect and SDK disposal preserve pages. Explicit completion remains available after stop/expiry and extension worker restart. Existing user pages, manually moved pages and pages taken over by another task are protected.
10
+ - SDK adds `browser.start(label)` and `browser.complete()`; MCP session actions add `start` and `complete`. Session listings include group/window/tab identifiers.
11
+
12
+ Collapsed-group operations keep their groups collapsed and leave the foreground tab unchanged. Paint settling uses an abortable extension-side timer, and managed jobs resume frozen target pages before reading or dispatching input so successful clicks also run page handlers.
13
+
14
+ The extension adds the `tabGroups` permission and must be reloaded after updating the package. CLI-only updates do not activate browser-side grouping.
15
+
16
+ The npm package excludes local Hub dependencies and machine-specific deployment configuration; self-hosters can copy `hub/wrangler.example.toml` to `hub/wrangler.toml`.