browsemux 0.0.0-stage → 0.1.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.
- package/CHANGELOG.md +41 -0
- package/CODE_OF_CONDUCT.md +32 -0
- package/CONTRIBUTING.md +30 -0
- package/LICENSE +21 -0
- package/NOTICE.md +11 -0
- package/PRIVACY.md +39 -0
- package/README.md +488 -2
- package/SECURITY.md +36 -0
- package/bin/browsemux.mjs +53 -0
- package/docs/architecture.md +154 -0
- package/docs/backends.md +60 -0
- package/docs/benchmarks.md +308 -0
- package/docs/harness-skills.md +123 -0
- package/docs/installation.md +334 -0
- package/docs/providers.md +87 -0
- package/docs/validation.md +99 -0
- package/package.json +60 -4
- package/skills/browsemux/SKILL.md +138 -0
- package/skills/browsemux/references/routing.md +115 -0
- package/src/backends/agent-browser.mjs +283 -0
- package/src/backends/bsk.mjs +566 -0
- package/src/backends/index.mjs +27 -0
- package/src/cli.mjs +481 -0
- package/src/contracts.mjs +178 -0
- package/src/decisions/decisions-api.mjs +118 -0
- package/src/decisions/http.mjs +68 -0
- package/src/decisions/index.mjs +42 -0
- package/src/decisions/openai-compatible.mjs +189 -0
- package/src/decisions/questions.mjs +285 -0
- package/src/errors.mjs +16 -0
- package/src/index.mjs +25 -0
- package/src/inputs.mjs +96 -0
- package/src/loop.mjs +494 -0
- package/src/skills.mjs +228 -0
- package/src/status.mjs +17 -0
- package/src/util/json.mjs +47 -0
- package/src/util/process.mjs +82 -0
- package/src/util/time.mjs +11 -0
- package/src/util/url.mjs +17 -0
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## 0.1.0 - 2026-11-21
|
|
4
|
+
|
|
5
|
+
- Added a portable `browsemux` harness skill and `browsemux skill install`
|
|
6
|
+
support for Codex, shared agent roots, Claude Code, Cursor, OpenCode, and
|
|
7
|
+
Hermes.
|
|
8
|
+
- Added a dependency-free direct-harness versus Browsemux benchmark with local
|
|
9
|
+
fixtures, deterministic success checks, token and cost accounting,
|
|
10
|
+
browser-command counts, and bounded model retries.
|
|
11
|
+
- Optimized BSK click, fill, select, press, and navigate execution through
|
|
12
|
+
`bsk step`, with partial-failure reconciliation and no action replay.
|
|
13
|
+
- Added immediate deterministic success after atomic action-and-observation.
|
|
14
|
+
- Made `doctor` honor custom backend commands, report readiness and missing
|
|
15
|
+
setup, validate custom provider key variables, and exit nonzero when
|
|
16
|
+
Browsemux cannot run.
|
|
17
|
+
- Returned exit code `2` for `completed-unverified` instead of treating an
|
|
18
|
+
unverified model claim as success.
|
|
19
|
+
- Allowed the same semantic action on different observations, fixing legitimate
|
|
20
|
+
workflows such as clicking `Next` across paginated pages.
|
|
21
|
+
- Marked browser process exits and timeouts after write actions as
|
|
22
|
+
`effect-unknown`, preventing unsafe replay.
|
|
23
|
+
- Removed provider API keys from browser subprocess environments.
|
|
24
|
+
- Tracked BSK tab changes returned by `step` and `sync` before reading the tab
|
|
25
|
+
URL, and kept partially opened browser sessions closeable.
|
|
26
|
+
- Rejected identical actions that produce no page change, excluded known
|
|
27
|
+
unproductive refs during recovery, and rejected premature model `DONE`
|
|
28
|
+
proposals when deterministic success criteria are configured.
|
|
29
|
+
- Preserved nonzero BSK JSON so an executed action is never mistaken for an
|
|
30
|
+
unexecuted one.
|
|
31
|
+
- Added a bounded observation, decision, validation, execution, and handoff loop.
|
|
32
|
+
- Added `agent-browser` and BSK browser backends.
|
|
33
|
+
- Added TypeSafe System One, OpenRouter Decisions, and OpenAI-compatible providers.
|
|
34
|
+
- Added stale-ref, role, operation, repeated-action, and navigation validation.
|
|
35
|
+
- Added deterministic URL and visible-text success checks.
|
|
36
|
+
- Added compact JSON and JSONL output with timing and usage.
|
|
37
|
+
- Added reproducible backend, package-footprint, and direct-versus-mediated
|
|
38
|
+
benchmark evidence.
|
|
39
|
+
- Added privacy, security-reporting, contribution, and code-of-conduct policies.
|
|
40
|
+
- Added package repository metadata, npm publish guards, and multi-version CI.
|
|
41
|
+
- Added 65 focused tests and verified live `agent-browser` and BSK smoke paths.
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
# Code of Conduct
|
|
2
|
+
|
|
3
|
+
## Expected Behavior
|
|
4
|
+
|
|
5
|
+
- Discuss code, evidence, and tradeoffs without attacking people.
|
|
6
|
+
- Give reproducible examples and redact credentials, private URLs, and page
|
|
7
|
+
content.
|
|
8
|
+
- Respect browser owners, website terms, authentication boundaries, and local
|
|
9
|
+
law.
|
|
10
|
+
- Report security-sensitive material privately through [SECURITY.md](SECURITY.md).
|
|
11
|
+
|
|
12
|
+
## Unacceptable Behavior
|
|
13
|
+
|
|
14
|
+
- Harassment, threats, discrimination, or sustained disruption.
|
|
15
|
+
- Publishing another person's secrets or private data.
|
|
16
|
+
- Pressuring contributors to add CAPTCHA bypasses, credential theft, evasive
|
|
17
|
+
automation, or destructive browser actions.
|
|
18
|
+
- Misrepresenting an unverified proposal as a completed or verified browser
|
|
19
|
+
action.
|
|
20
|
+
|
|
21
|
+
## Scope and Enforcement
|
|
22
|
+
|
|
23
|
+
This policy applies to project repositories, issues, reviews, discussions, and
|
|
24
|
+
other project spaces. Maintainers may edit or remove content, close
|
|
25
|
+
conversations, reject contributions, or restrict participation when behavior
|
|
26
|
+
violates this policy.
|
|
27
|
+
|
|
28
|
+
Report conduct concerns privately to the maintainer through their GitHub
|
|
29
|
+
profile. Good-faith reports will be reviewed with discretion. Retaliation is
|
|
30
|
+
not permitted.
|
|
31
|
+
|
|
32
|
+
This policy is informed by the Contributor Covenant, version 2.1.
|
package/CONTRIBUTING.md
ADDED
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
# Contributing
|
|
2
|
+
|
|
3
|
+
Browsemux is intentionally narrow. The initial backend scope is:
|
|
4
|
+
|
|
5
|
+
- `agent-browser`
|
|
6
|
+
- BSK / Tencent Agent Window
|
|
7
|
+
|
|
8
|
+
The initial decision-provider scope is:
|
|
9
|
+
|
|
10
|
+
- OpenRouter Decisions or TypeSafe System One
|
|
11
|
+
- OpenAI-compatible chat completions with structured JSON
|
|
12
|
+
|
|
13
|
+
## Development
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
npm test
|
|
17
|
+
npm run check
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
No runtime dependencies are currently accepted without a concrete need.
|
|
21
|
+
Browser backends must fail closed when a target is stale or an action has an
|
|
22
|
+
unknown effect.
|
|
23
|
+
|
|
24
|
+
## Pull requests
|
|
25
|
+
|
|
26
|
+
- Keep provider and backend contracts separate.
|
|
27
|
+
- Add deterministic tests with fake browser and provider implementations.
|
|
28
|
+
- Do not add a full browser-agent loop behind the connector.
|
|
29
|
+
- Do not let a decision provider execute browser commands directly.
|
|
30
|
+
- Document any new action with its validation and failure behavior.
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Browsemux contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/NOTICE.md
ADDED
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
# Notice
|
|
2
|
+
|
|
3
|
+
Browsemux is an independent implementation. Its design was informed by:
|
|
4
|
+
|
|
5
|
+
- `forvela/jev-agent-browser`, MIT licensed
|
|
6
|
+
- `browser-use/jev-ultrafast`, MIT licensed
|
|
7
|
+
- The public `agent-browser` CLI by Vercel Labs
|
|
8
|
+
- Tencent BrowserSkill / BSK
|
|
9
|
+
|
|
10
|
+
No browser binary or browser-agent runtime is bundled with Browsemux. Users
|
|
11
|
+
install and operate the selected browser backend separately.
|
package/PRIVACY.md
ADDED
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
# Privacy and Data Handling
|
|
2
|
+
|
|
3
|
+
Browsemux does not include telemetry or analytics. It does not persist page
|
|
4
|
+
content, prompts, credentials, or API keys by default.
|
|
5
|
+
|
|
6
|
+
## Data Sent to Decision Providers
|
|
7
|
+
|
|
8
|
+
For each decision, Browsemux sends the configured provider:
|
|
9
|
+
|
|
10
|
+
- the parent-supplied goal
|
|
11
|
+
- the current URL and page title
|
|
12
|
+
- a bounded, indexed page snapshot
|
|
13
|
+
- labels, kinds, and target hints for supplied inputs
|
|
14
|
+
- recent action metadata and bounded recovery context
|
|
15
|
+
|
|
16
|
+
Secret input values are replaced with `[redacted]` before provider requests.
|
|
17
|
+
Non-secret values are sent only when the parent supplies them.
|
|
18
|
+
|
|
19
|
+
A page snapshot can still contain personal, confidential, or regulated data
|
|
20
|
+
that appears in visible page content. Use a local or contractually suitable
|
|
21
|
+
provider when the page cannot be disclosed to a third party.
|
|
22
|
+
|
|
23
|
+
## API Keys
|
|
24
|
+
|
|
25
|
+
API keys are read from environment variables and sent only as authorization
|
|
26
|
+
headers to the selected provider. They are not included in prompts, action
|
|
27
|
+
history, JSON results, or handoffs.
|
|
28
|
+
|
|
29
|
+
## Browser State
|
|
30
|
+
|
|
31
|
+
Session persistence, cookies, profiles, downloads, and browser logs are
|
|
32
|
+
controlled by the selected backend (`agent-browser` or BSK), not by a central
|
|
33
|
+
Browsemux service. Browsemux closes sessions by default.
|
|
34
|
+
|
|
35
|
+
## Diagnostics
|
|
36
|
+
|
|
37
|
+
Review JSONL output before publishing it. Redact credentials, cookies, session
|
|
38
|
+
IDs, private URLs, and page content. Security reports should use the process in
|
|
39
|
+
[SECURITY.md](SECURITY.md).
|
package/README.md
CHANGED
|
@@ -1,3 +1,489 @@
|
|
|
1
|
-
|
|
1
|
+
<div align="center">
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
# 🧭 Browsemux
|
|
4
|
+
|
|
5
|
+
**Route browser decisions. Keep deterministic control.**
|
|
6
|
+
|
|
7
|
+
A bounded decision bridge between agent harnesses and browser backends.
|
|
8
|
+
|
|
9
|
+
[](https://github.com/xenstar/browsemux/actions/workflows/test.yml)
|
|
10
|
+
[](LICENSE)
|
|
11
|
+
[](https://nodejs.org/)
|
|
12
|
+
[](#project-status)
|
|
13
|
+
[](https://github.com/xenstar/browsemux/stargazers)
|
|
14
|
+
[](https://github.com/xenstar/browsemux/network/members)
|
|
15
|
+
[](https://github.com/xenstar/browsemux/issues)
|
|
16
|
+
|
|
17
|
+
[Features](#features) · [Install](#quick-install) · [Quick start](#quick-start) ·
|
|
18
|
+
[Benchmarks](#benchmarks) · [Documentation](#documentation) ·
|
|
19
|
+
[Contributing](#contributing)
|
|
20
|
+
|
|
21
|
+
</div>
|
|
22
|
+
|
|
23
|
+
## 📖 Table of Contents
|
|
24
|
+
|
|
25
|
+
- [✨ Features](#features)
|
|
26
|
+
- [🚦 Project Status](#project-status)
|
|
27
|
+
- [🚀 Quick Install](#quick-install)
|
|
28
|
+
- [⚡ Quick Start](#quick-start)
|
|
29
|
+
- [📊 Benchmarks](#benchmarks)
|
|
30
|
+
- [🧰 Configuration](#configuration)
|
|
31
|
+
- [📦 Output](#output)
|
|
32
|
+
- [🔐 Safety](#safety)
|
|
33
|
+
- [📚 Documentation](#documentation)
|
|
34
|
+
- [🧱 Library](#library)
|
|
35
|
+
- [🛠️ Development](#development)
|
|
36
|
+
- [🤝 Contributing](#contributing)
|
|
37
|
+
- [🔗 Policies](#policies)
|
|
38
|
+
|
|
39
|
+
<a id="features"></a>
|
|
40
|
+
## ✨ Features
|
|
41
|
+
|
|
42
|
+
- [x] 🧭 **Bounded browser loop**: Observe, decide, validate, act, re-observe, and stop within a strict budget.
|
|
43
|
+
- [x] 🛡️ **Deterministic control**: Typed model intent is checked against targets, roles, inputs, URLs, repetition, and completion criteria.
|
|
44
|
+
- [x] 🔌 **Swappable browser backends**: Use `agent-browser` for isolated sessions or BSK for an existing Agent Window.
|
|
45
|
+
- [x] 🧠 **Swappable decision providers**: Use TypeSafe/JEV, OpenRouter Decisions, or compatible chat-completions providers.
|
|
46
|
+
- [x] 🧩 **Harness routing skill**: Install one portable skill for Codex, Claude Code, Cursor, OpenCode, and Hermes.
|
|
47
|
+
- [x] 📦 **Dependency-free package**: The runtime uses Node.js APIs without a browser framework or HTTP SDK.
|
|
48
|
+
- [x] 📊 **Reproducible benchmarks**: Compare direct control with Browsemux using fixed tasks, one model, deterministic checks, and raw records.
|
|
49
|
+
- [x] 🚦 **Explicit failure states**: Distinguish verified success, unverified completion, limits, blockers, and unknown action effects.
|
|
50
|
+
|
|
51
|
+
```text
|
|
52
|
+
Harness
|
|
53
|
+
-> Browsemux
|
|
54
|
+
-> typed decision provider
|
|
55
|
+
-> local proposal validation
|
|
56
|
+
-> agent-browser or BSK
|
|
57
|
+
-> settled observation
|
|
58
|
+
<- compact evidence, usage, timings, and handoff
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
**Core contract:** the model proposes typed intent; code validates and executes
|
|
62
|
+
it. The model never receives a browser handle or executes code.
|
|
63
|
+
|
|
64
|
+
<a id="project-status"></a>
|
|
65
|
+
## 🚦 Project Status
|
|
66
|
+
|
|
67
|
+
Browsemux is a **pre-release** project. The current supported installation path
|
|
68
|
+
is directly from GitHub.
|
|
69
|
+
|
|
70
|
+
Supported browser backends:
|
|
71
|
+
|
|
72
|
+
- `agent-browser`
|
|
73
|
+
- BSK / Tencent Agent Window
|
|
74
|
+
|
|
75
|
+
Supported decision providers:
|
|
76
|
+
|
|
77
|
+
- TypeSafe System One / JEV
|
|
78
|
+
- OpenRouter Decisions
|
|
79
|
+
- OpenAI-compatible chat completions with JSON output
|
|
80
|
+
|
|
81
|
+
Browser Use, Playwright, Stagehand, Skyvern, and other frameworks remain
|
|
82
|
+
outside the initial scope.
|
|
83
|
+
|
|
84
|
+
<a id="quick-install"></a>
|
|
85
|
+
## 🚀 Quick Install
|
|
86
|
+
|
|
87
|
+
### 1. Install Browsemux
|
|
88
|
+
|
|
89
|
+
Recommended global install from GitHub:
|
|
90
|
+
|
|
91
|
+
```bash
|
|
92
|
+
npm install -g github:xenstar/browsemux
|
|
93
|
+
browsemux --version
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
Install from a local clone:
|
|
97
|
+
|
|
98
|
+
```bash
|
|
99
|
+
git clone https://github.com/xenstar/browsemux.git
|
|
100
|
+
cd browsemux
|
|
101
|
+
npm install
|
|
102
|
+
npm link
|
|
103
|
+
browsemux --version
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
The npm package ships the Browsemux skill, but `npm install` does not modify
|
|
107
|
+
harness skill directories. Run the skill installation step once after each
|
|
108
|
+
install or update.
|
|
109
|
+
|
|
110
|
+
Requirements:
|
|
111
|
+
|
|
112
|
+
- Node.js 20 or newer
|
|
113
|
+
- One supported browser backend
|
|
114
|
+
- One decision-provider API key
|
|
115
|
+
|
|
116
|
+
### 2. Install a browser backend
|
|
117
|
+
|
|
118
|
+
Recommended for first-time users:
|
|
119
|
+
|
|
120
|
+
```bash
|
|
121
|
+
npm install -g agent-browser
|
|
122
|
+
agent-browser install
|
|
123
|
+
agent-browser doctor
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
For BSK on Windows:
|
|
127
|
+
|
|
128
|
+
```powershell
|
|
129
|
+
irm https://raw.githubusercontent.com/Tencent/BrowserSkill/main/install.ps1 | iex
|
|
130
|
+
bsk --version
|
|
131
|
+
bsk doctor
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
For BSK on macOS or Linux:
|
|
135
|
+
|
|
136
|
+
```bash
|
|
137
|
+
curl -fsSL https://raw.githubusercontent.com/Tencent/BrowserSkill/main/install.sh | sh
|
|
138
|
+
export PATH="${BSK_INSTALL_DIR:-$HOME/.local/bin}:$PATH"
|
|
139
|
+
bsk --version
|
|
140
|
+
bsk doctor
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
BSK also requires its browser extension and a connected Chromium browser. See
|
|
144
|
+
Tencent's official
|
|
145
|
+
[agent install guide](https://github.com/Tencent/BrowserSkill/blob/main/AGENT_INSTALL.md).
|
|
146
|
+
|
|
147
|
+
### 3. Set a provider key
|
|
148
|
+
|
|
149
|
+
PowerShell:
|
|
150
|
+
|
|
151
|
+
```powershell
|
|
152
|
+
$env:TYPESAFE_API_KEY = "<YOUR_TYPESAFE_API_KEY>"
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
macOS or Linux:
|
|
156
|
+
|
|
157
|
+
```bash
|
|
158
|
+
export TYPESAFE_API_KEY="<YOUR_TYPESAFE_API_KEY>"
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
Verify the local setup:
|
|
162
|
+
|
|
163
|
+
```bash
|
|
164
|
+
browsemux doctor
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
`doctor` checks CLI availability and whether the expected provider environment
|
|
168
|
+
variable is present. It does not validate API credit or the BSK extension state.
|
|
169
|
+
|
|
170
|
+
### 4. Install the harness routing skill
|
|
171
|
+
|
|
172
|
+
Install the Browsemux skill into the supported harness skill directories:
|
|
173
|
+
|
|
174
|
+
```bash
|
|
175
|
+
browsemux skill install --harness all
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
This is an explicit setup step, not an npm lifecycle side effect. It avoids
|
|
179
|
+
writing into another tool's home directory during package installation.
|
|
180
|
+
|
|
181
|
+
The skill tells harness agents to use Browsemux for bounded browser work instead
|
|
182
|
+
of driving `agent-browser` or BSK one command at a time. Direct browser commands
|
|
183
|
+
remain reserved for setup, visual inspection, exploratory debugging, and human
|
|
184
|
+
takeover.
|
|
185
|
+
|
|
186
|
+
Start a new harness session after installation so skill discovery refreshes.
|
|
187
|
+
See [Harness skills](docs/harness-skills.md) for per-harness paths, project
|
|
188
|
+
installation, updates, and limitations.
|
|
189
|
+
|
|
190
|
+
> Replace every `<ANGLE_BRACKET_VALUE>` before running an example. See
|
|
191
|
+
> [Installation](docs/installation.md) for provider, BSK, update, and
|
|
192
|
+
> troubleshooting instructions.
|
|
193
|
+
|
|
194
|
+
<a id="quick-start"></a>
|
|
195
|
+
## ⚡ Quick Start
|
|
196
|
+
|
|
197
|
+
### agent-browser + JEV
|
|
198
|
+
|
|
199
|
+
PowerShell:
|
|
200
|
+
|
|
201
|
+
```powershell
|
|
202
|
+
$env:TYPESAFE_API_KEY = "<YOUR_TYPESAFE_API_KEY>"
|
|
203
|
+
|
|
204
|
+
browsemux run `
|
|
205
|
+
--backend agent-browser `
|
|
206
|
+
--provider typesafe `
|
|
207
|
+
--url https://example.com `
|
|
208
|
+
--goal "Open the Learn more documentation link" `
|
|
209
|
+
--success-url-contains iana.org `
|
|
210
|
+
--max-steps 4
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
macOS or Linux:
|
|
214
|
+
|
|
215
|
+
```bash
|
|
216
|
+
export TYPESAFE_API_KEY="<YOUR_TYPESAFE_API_KEY>"
|
|
217
|
+
|
|
218
|
+
browsemux run \
|
|
219
|
+
--backend agent-browser \
|
|
220
|
+
--provider typesafe \
|
|
221
|
+
--url https://example.com \
|
|
222
|
+
--goal "Open the Learn more documentation link" \
|
|
223
|
+
--success-url-contains iana.org \
|
|
224
|
+
--max-steps 4
|
|
225
|
+
```
|
|
226
|
+
|
|
227
|
+
### agent-browser + OpenRouter Decisions
|
|
228
|
+
|
|
229
|
+
```bash
|
|
230
|
+
export OPENROUTER_API_KEY="<YOUR_OPENROUTER_API_KEY>"
|
|
231
|
+
|
|
232
|
+
browsemux run \
|
|
233
|
+
--provider openrouter \
|
|
234
|
+
--model "<OPENROUTER_DECISION_MODEL_SLUG>" \
|
|
235
|
+
--url https://example.com \
|
|
236
|
+
--goal "Open the Learn more documentation link" \
|
|
237
|
+
--success-url-contains iana.org
|
|
238
|
+
```
|
|
239
|
+
|
|
240
|
+
### BSK + OpenRouter Decisions
|
|
241
|
+
|
|
242
|
+
```bash
|
|
243
|
+
export OPENROUTER_API_KEY="<YOUR_OPENROUTER_API_KEY>"
|
|
244
|
+
|
|
245
|
+
browsemux run \
|
|
246
|
+
--backend bsk \
|
|
247
|
+
--provider openrouter \
|
|
248
|
+
--model "<OPENROUTER_DECISION_MODEL_SLUG>" \
|
|
249
|
+
--attach \
|
|
250
|
+
--bsk-scope "<YOUR_AGENT_WINDOW_SCOPE>" \
|
|
251
|
+
--goal "Find the latest invoice"
|
|
252
|
+
```
|
|
253
|
+
|
|
254
|
+
BSK sessions close by default. Use `--keep-open` only when a human handoff is
|
|
255
|
+
explicitly required.
|
|
256
|
+
|
|
257
|
+
<a id="benchmarks"></a>
|
|
258
|
+
## 📊 Benchmarks
|
|
259
|
+
|
|
260
|
+
Latest three-repeat controlled rerun on 2026-11-21:
|
|
261
|
+
|
|
262
|
+
| Backend | Arm | Verified | Median wall | Median input tokens | Cost / verified task |
|
|
263
|
+
| --- | --- | ---: | ---: | ---: | ---: |
|
|
264
|
+
| `agent-browser` | direct | 12/12 | 12,500 ms | 910.5 | $0.000331 |
|
|
265
|
+
| `agent-browser` | Browsemux | 11/12 | 11,558 ms | 832.5 | $0.000294 |
|
|
266
|
+
| BSK | direct | 11/12 | 15,532 ms | 993.5 | $0.000404 |
|
|
267
|
+
| BSK | Browsemux | 11/12 | 13,200 ms | 902.5 | $0.000401 |
|
|
268
|
+
|
|
269
|
+
| Backend | Success delta | Wall change | Input-token change | Cost / verified change |
|
|
270
|
+
| --- | ---: | ---: | ---: | ---: |
|
|
271
|
+
| `agent-browser` | -8.3 pp | -7.5% | -8.6% | -10.9% |
|
|
272
|
+
| BSK | 0.0 pp | -15.0% | -9.2% | -0.7% |
|
|
273
|
+
|
|
274
|
+
The efficiency gains are real in this fixture run, but the reliability result
|
|
275
|
+
is mixed. `agent-browser` recorded one failure: a Browsemux startup failure
|
|
276
|
+
before any model call. BSK recorded two failures: one direct and one Browsemux.
|
|
277
|
+
The earlier two-repeat BSK regression did not reproduce, so Browsemux does not
|
|
278
|
+
currently claim a stable cost advantage on every BSK workflow.
|
|
279
|
+
|
|
280
|
+
- [Benchmark methodology and results](docs/benchmarks.md)
|
|
281
|
+
- [Reproduce the direct-versus-mediated benchmark](bench/README.md)
|
|
282
|
+
|
|
283
|
+
Decision latency dominates these short tasks. Treat the results as controlled
|
|
284
|
+
engineering evidence, not universal browser-agent rankings.
|
|
285
|
+
|
|
286
|
+
<a id="configuration"></a>
|
|
287
|
+
## 🧰 Configuration
|
|
288
|
+
|
|
289
|
+
### Supplied inputs
|
|
290
|
+
|
|
291
|
+
Decision models select supplied values; they do not invent credentials or form
|
|
292
|
+
content.
|
|
293
|
+
|
|
294
|
+
```bash
|
|
295
|
+
browsemux run \
|
|
296
|
+
--url https://example.com/search \
|
|
297
|
+
--goal "Search for Browsemux" \
|
|
298
|
+
--inputs-json '{"text":{"query":"Browsemux"},"keys":{"submit":"Enter"}}'
|
|
299
|
+
```
|
|
300
|
+
|
|
301
|
+
Input groups:
|
|
302
|
+
|
|
303
|
+
- `text`: `TYPE`
|
|
304
|
+
- `select`: `SELECT`
|
|
305
|
+
- `keys`: `PRESS`
|
|
306
|
+
- `urls`: `NAVIGATE`
|
|
307
|
+
|
|
308
|
+
Mark a value as secret when supplying metadata:
|
|
309
|
+
|
|
310
|
+
```json
|
|
311
|
+
{
|
|
312
|
+
"text": {
|
|
313
|
+
"password": {
|
|
314
|
+
"value": "<ACCOUNT_PASSWORD>",
|
|
315
|
+
"label": "Account password",
|
|
316
|
+
"secret": true
|
|
317
|
+
}
|
|
318
|
+
}
|
|
319
|
+
}
|
|
320
|
+
```
|
|
321
|
+
|
|
322
|
+
Secret values are redacted from provider metadata.
|
|
323
|
+
|
|
324
|
+
### Actions
|
|
325
|
+
|
|
326
|
+
```text
|
|
327
|
+
CLICK
|
|
328
|
+
TYPE
|
|
329
|
+
SELECT
|
|
330
|
+
PRESS
|
|
331
|
+
SCROLL_UP
|
|
332
|
+
SCROLL_DOWN
|
|
333
|
+
BACK
|
|
334
|
+
WAIT
|
|
335
|
+
NAVIGATE
|
|
336
|
+
DONE
|
|
337
|
+
BLOCKED
|
|
338
|
+
```
|
|
339
|
+
|
|
340
|
+
`CLICK`, `TYPE`, and `SELECT` require a target present in the latest snapshot.
|
|
341
|
+
Invalid roles and stale refs are rejected before backend dispatch.
|
|
342
|
+
|
|
343
|
+
### Completion
|
|
344
|
+
|
|
345
|
+
`DONE` from a model is not treated as proof. Without deterministic checks, the
|
|
346
|
+
result is `completed-unverified`.
|
|
347
|
+
|
|
348
|
+
Use one or both deterministic checks:
|
|
349
|
+
|
|
350
|
+
```bash
|
|
351
|
+
--success-url-contains <URL_FRAGMENT>
|
|
352
|
+
--success-text-contains "<VISIBLE_TEXT>"
|
|
353
|
+
```
|
|
354
|
+
|
|
355
|
+
Only matching checks produce `status: "success"`.
|
|
356
|
+
|
|
357
|
+
<a id="output"></a>
|
|
358
|
+
## 📦 Output
|
|
359
|
+
|
|
360
|
+
Default output is one JSON result. `--jsonl` streams:
|
|
361
|
+
|
|
362
|
+
```text
|
|
363
|
+
start
|
|
364
|
+
observation
|
|
365
|
+
decision
|
|
366
|
+
validation
|
|
367
|
+
action
|
|
368
|
+
result
|
|
369
|
+
```
|
|
370
|
+
|
|
371
|
+
The result contains:
|
|
372
|
+
|
|
373
|
+
- final status and reason
|
|
374
|
+
- backend and provider
|
|
375
|
+
- action count and step count
|
|
376
|
+
- observation, decision, and action timings
|
|
377
|
+
- provider usage when available
|
|
378
|
+
- bounded action history
|
|
379
|
+
- compact handoff for the parent harness
|
|
380
|
+
|
|
381
|
+
Exit codes:
|
|
382
|
+
|
|
383
|
+
| Code | Status | Meaning |
|
|
384
|
+
| ---: | --- | --- |
|
|
385
|
+
| `0` | `success` | Deterministic success criteria matched. |
|
|
386
|
+
| `2` | `completed-unverified` | The model claimed completion, but no success check proved it. |
|
|
387
|
+
| `3` | `blocked` | The browser or model reported a required human decision or blocker. |
|
|
388
|
+
| `4` | `effect-unknown` | A write action may have executed; do not replay it blindly. |
|
|
389
|
+
| `5` | `limit` | The step or recovery budget ended before completion. |
|
|
390
|
+
| `1` | `error` | Setup, provider, browser, or proposal failure. |
|
|
391
|
+
|
|
392
|
+
`completed-unverified` is intentionally nonzero so scripts do not treat an
|
|
393
|
+
unverified model claim as success.
|
|
394
|
+
|
|
395
|
+
<a id="safety"></a>
|
|
396
|
+
## 🔐 Safety
|
|
397
|
+
|
|
398
|
+
- Providers cannot execute browser commands or JavaScript.
|
|
399
|
+
- Targets must exist in the latest observation.
|
|
400
|
+
- Operation-to-role validation happens locally.
|
|
401
|
+
- Navigation accepts only HTTP and HTTPS.
|
|
402
|
+
- Repeated semantic actions are bounded.
|
|
403
|
+
- Sensitive supplied values are redacted from provider metadata.
|
|
404
|
+
- Provider API keys are removed from browser subprocess environments.
|
|
405
|
+
- Human approval is still required for payments, destructive account actions,
|
|
406
|
+
uploads, MFA, and CAPTCHA.
|
|
407
|
+
|
|
408
|
+
See [SECURITY.md](SECURITY.md) for the trust boundary.
|
|
409
|
+
|
|
410
|
+
<a id="documentation"></a>
|
|
411
|
+
## 📚 Documentation
|
|
412
|
+
|
|
413
|
+
| Guide | Purpose |
|
|
414
|
+
| --- | --- |
|
|
415
|
+
| [Installation](docs/installation.md) | End-to-end setup, verification, updates, and troubleshooting |
|
|
416
|
+
| [Harness skills](docs/harness-skills.md) | Routing guidance for Codex, Claude Code, Cursor, OpenCode, and Hermes |
|
|
417
|
+
| [Backends](docs/backends.md) | `agent-browser` and BSK behavior |
|
|
418
|
+
| [Providers](docs/providers.md) | TypeSafe, OpenRouter, and OpenAI-compatible configuration |
|
|
419
|
+
| [Architecture](docs/architecture.md) | Control flow and trust boundaries |
|
|
420
|
+
| [Validation](docs/validation.md) | Tested environments and live smoke evidence |
|
|
421
|
+
| [Benchmarks](docs/benchmarks.md) | Method, measurements, and limitations |
|
|
422
|
+
|
|
423
|
+
<a id="contributing"></a>
|
|
424
|
+
## 🤝 Contributing
|
|
425
|
+
|
|
426
|
+
Contributions are welcome through [issues](https://github.com/xenstar/browsemux/issues)
|
|
427
|
+
and focused pull requests. Keep backend adapters fail-closed, keep provider
|
|
428
|
+
outputs typed, add tests for behavior changes, and update public claims when the
|
|
429
|
+
benchmark evidence changes.
|
|
430
|
+
|
|
431
|
+
[](https://github.com/xenstar/browsemux/graphs/contributors)
|
|
432
|
+
|
|
433
|
+
<a id="policies"></a>
|
|
434
|
+
## 🤝 Project Policies
|
|
435
|
+
|
|
436
|
+
- [License](LICENSE): MIT
|
|
437
|
+
- [Contributing](CONTRIBUTING.md)
|
|
438
|
+
- [Code of conduct](CODE_OF_CONDUCT.md)
|
|
439
|
+
- [Security policy](SECURITY.md)
|
|
440
|
+
- [Privacy and data handling](PRIVACY.md)
|
|
441
|
+
- [Changelog](CHANGELOG.md)
|
|
442
|
+
|
|
443
|
+
<a id="library"></a>
|
|
444
|
+
## 🧱 Library
|
|
445
|
+
|
|
446
|
+
```js
|
|
447
|
+
import {
|
|
448
|
+
AgentBrowserBackend,
|
|
449
|
+
OpenAICompatibleProvider,
|
|
450
|
+
normalizeInputs,
|
|
451
|
+
runLoop,
|
|
452
|
+
} from 'browsemux';
|
|
453
|
+
|
|
454
|
+
const browser = new AgentBrowserBackend();
|
|
455
|
+
const provider = new OpenAICompatibleProvider({
|
|
456
|
+
endpoint: 'https://openrouter.ai/api/v1/chat/completions',
|
|
457
|
+
apiKey: process.env.OPENROUTER_API_KEY,
|
|
458
|
+
model: '<OPENROUTER_DECISION_MODEL_SLUG>',
|
|
459
|
+
});
|
|
460
|
+
|
|
461
|
+
const observation = await browser.open('https://example.com');
|
|
462
|
+
const result = await runLoop({
|
|
463
|
+
goal: 'Open the Learn more link',
|
|
464
|
+
browser,
|
|
465
|
+
provider,
|
|
466
|
+
inputs: normalizeInputs(),
|
|
467
|
+
initialObservation: observation,
|
|
468
|
+
successCriteria: { urlContains: 'iana.org' },
|
|
469
|
+
maxSteps: 4,
|
|
470
|
+
});
|
|
471
|
+
```
|
|
472
|
+
|
|
473
|
+
<a id="development"></a>
|
|
474
|
+
## 🛠️ Development
|
|
475
|
+
|
|
476
|
+
```bash
|
|
477
|
+
npm test
|
|
478
|
+
npm run check
|
|
479
|
+
npm run bench:smoke
|
|
480
|
+
```
|
|
481
|
+
|
|
482
|
+
The initial release is intentionally small. Backend adapters must fail closed,
|
|
483
|
+
and provider adapters must return typed proposals rather than browser commands.
|
|
484
|
+
|
|
485
|
+
## 🏷️ Name
|
|
486
|
+
|
|
487
|
+
**Browsemux** means multiplexing one harness workflow across swappable browser
|
|
488
|
+
backends and decision providers without giving either one direct authority over
|
|
489
|
+
the browser.
|