browsemux 0.0.0-stage → 0.1.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/CHANGELOG.md +49 -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 +417 -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,49 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## 0.1.1 - 2026-11-21
|
|
4
|
+
|
|
5
|
+
- Rewrote the README for first-time users, with a plain-language explanation
|
|
6
|
+
of what Browsemux does, why it is useful, how to run it, and what it does not
|
|
7
|
+
replace.
|
|
8
|
+
- Removed the pre-release GitHub installation wording in favor of the public
|
|
9
|
+
npm package.
|
|
10
|
+
|
|
11
|
+
## 0.1.0 - 2026-11-21
|
|
12
|
+
|
|
13
|
+
- Added a portable `browsemux` harness skill and `browsemux skill install`
|
|
14
|
+
support for Codex, shared agent roots, Claude Code, Cursor, OpenCode, and
|
|
15
|
+
Hermes.
|
|
16
|
+
- Added a dependency-free direct-harness versus Browsemux benchmark with local
|
|
17
|
+
fixtures, deterministic success checks, token and cost accounting,
|
|
18
|
+
browser-command counts, and bounded model retries.
|
|
19
|
+
- Optimized BSK click, fill, select, press, and navigate execution through
|
|
20
|
+
`bsk step`, with partial-failure reconciliation and no action replay.
|
|
21
|
+
- Added immediate deterministic success after atomic action-and-observation.
|
|
22
|
+
- Made `doctor` honor custom backend commands, report readiness and missing
|
|
23
|
+
setup, validate custom provider key variables, and exit nonzero when
|
|
24
|
+
Browsemux cannot run.
|
|
25
|
+
- Returned exit code `2` for `completed-unverified` instead of treating an
|
|
26
|
+
unverified model claim as success.
|
|
27
|
+
- Allowed the same semantic action on different observations, fixing legitimate
|
|
28
|
+
workflows such as clicking `Next` across paginated pages.
|
|
29
|
+
- Marked browser process exits and timeouts after write actions as
|
|
30
|
+
`effect-unknown`, preventing unsafe replay.
|
|
31
|
+
- Removed provider API keys from browser subprocess environments.
|
|
32
|
+
- Tracked BSK tab changes returned by `step` and `sync` before reading the tab
|
|
33
|
+
URL, and kept partially opened browser sessions closeable.
|
|
34
|
+
- Rejected identical actions that produce no page change, excluded known
|
|
35
|
+
unproductive refs during recovery, and rejected premature model `DONE`
|
|
36
|
+
proposals when deterministic success criteria are configured.
|
|
37
|
+
- Preserved nonzero BSK JSON so an executed action is never mistaken for an
|
|
38
|
+
unexecuted one.
|
|
39
|
+
- Added a bounded observation, decision, validation, execution, and handoff loop.
|
|
40
|
+
- Added `agent-browser` and BSK browser backends.
|
|
41
|
+
- Added TypeSafe System One, OpenRouter Decisions, and OpenAI-compatible providers.
|
|
42
|
+
- Added stale-ref, role, operation, repeated-action, and navigation validation.
|
|
43
|
+
- Added deterministic URL and visible-text success checks.
|
|
44
|
+
- Added compact JSON and JSONL output with timing and usage.
|
|
45
|
+
- Added reproducible backend, package-footprint, and direct-versus-mediated
|
|
46
|
+
benchmark evidence.
|
|
47
|
+
- Added privacy, security-reporting, contribution, and code-of-conduct policies.
|
|
48
|
+
- Added package repository metadata, npm publish guards, and multi-version CI.
|
|
49
|
+
- 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,418 @@
|
|
|
1
|
-
|
|
1
|
+
<div align="center">
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
# 🧭 Browsemux
|
|
4
|
+
|
|
5
|
+
### Give your AI agent a safer, cheaper way to use a browser.
|
|
6
|
+
|
|
7
|
+
Browsemux sits between your AI agent and the browser tool it already uses. It
|
|
8
|
+
handles the repetitive page reading, click decisions, validation, and success
|
|
9
|
+
checks, then gives your agent one small result.
|
|
10
|
+
|
|
11
|
+
[](https://github.com/xenstar/browsemux/actions/workflows/test.yml)
|
|
12
|
+
[](https://www.npmjs.com/package/browsemux)
|
|
13
|
+
[](LICENSE)
|
|
14
|
+
[](https://nodejs.org/)
|
|
15
|
+
[](#project-status)
|
|
16
|
+
|
|
17
|
+
[How it works](#-how-it-works) · [Quick start](#-quick-start) ·
|
|
18
|
+
[Benchmarks](#-benchmarks) · [Documentation](#-documentation)
|
|
19
|
+
|
|
20
|
+
</div>
|
|
21
|
+
|
|
22
|
+
## ⚡ The Short Version
|
|
23
|
+
|
|
24
|
+
An AI agent can say, **"Find the documentation link and open it."** The hard
|
|
25
|
+
part is doing that reliably without making a large model inspect the whole page
|
|
26
|
+
after every click.
|
|
27
|
+
|
|
28
|
+
Browsemux turns that into a small, repeatable loop:
|
|
29
|
+
|
|
30
|
+
```text
|
|
31
|
+
Your AI agent
|
|
32
|
+
-> gives Browsemux a goal
|
|
33
|
+
-> Browsemux takes a small snapshot of the page
|
|
34
|
+
-> a decision model suggests one action
|
|
35
|
+
-> Browsemux checks the action
|
|
36
|
+
-> agent-browser or BSK performs it
|
|
37
|
+
-> Browsemux checks the result and returns a short report
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
**The main AI still manages the task. Browsemux only handles the browser work.**
|
|
41
|
+
|
|
42
|
+
## ❓ Why Do I Need It?
|
|
43
|
+
|
|
44
|
+
Browser agents often do this:
|
|
45
|
+
|
|
46
|
+
1. Send the page to a large AI model.
|
|
47
|
+
2. Ask it what to click.
|
|
48
|
+
3. Click.
|
|
49
|
+
4. Send the new page back.
|
|
50
|
+
5. Repeat.
|
|
51
|
+
|
|
52
|
+
That works, but it can use many tokens, become slow, repeat the same action, or
|
|
53
|
+
trust the model when it says "done" without proof.
|
|
54
|
+
|
|
55
|
+
Browsemux improves the workflow in five practical ways:
|
|
56
|
+
|
|
57
|
+
- **Less context:** the decision model sees a compact page snapshot, not the
|
|
58
|
+
entire conversation and page history.
|
|
59
|
+
- **Fewer wasted steps:** repeated actions and stale page references are
|
|
60
|
+
rejected before they reach the browser.
|
|
61
|
+
- **Clear completion:** a task is successful only when a URL or text check
|
|
62
|
+
passes, not because a model claims it finished.
|
|
63
|
+
- **Safer execution:** the model returns structured data; it never gets a
|
|
64
|
+
browser handle, shell access, or permission to run code directly.
|
|
65
|
+
- **Easy switching:** you can change the decision model or browser tool without
|
|
66
|
+
rewriting your agent workflow.
|
|
67
|
+
|
|
68
|
+
In simple terms, Browsemux is a supervisor. The main AI decides **what outcome
|
|
69
|
+
it wants**. A smaller decision model suggests **the next click**. Browsemux
|
|
70
|
+
checks whether that click makes sense before the browser performs it.
|
|
71
|
+
|
|
72
|
+
> Efficiency is a measured claim, not a promise. Model and network latency can
|
|
73
|
+
> dominate a very short task. See the [benchmark results](#-benchmarks).
|
|
74
|
+
|
|
75
|
+
## 👥 Who Is It For?
|
|
76
|
+
|
|
77
|
+
Browsemux is useful if you want to:
|
|
78
|
+
|
|
79
|
+
- give Codex, Claude Code, Cursor, OpenCode, Hermes, or another shell-capable
|
|
80
|
+
agent a safer browser workflow;
|
|
81
|
+
- use BSK or `agent-browser` without sending every browser step to your main
|
|
82
|
+
model;
|
|
83
|
+
- try different decision models, including JEV and OpenRouter models;
|
|
84
|
+
- get one consistent output format for successes, failures, and handoffs;
|
|
85
|
+
- keep browser actions inside a clear step limit.
|
|
86
|
+
|
|
87
|
+
It is **not** a replacement for Chrome, Edge, Playwright, or the browser tool
|
|
88
|
+
you already use. It is the decision and safety layer between your agent and
|
|
89
|
+
that tool.
|
|
90
|
+
|
|
91
|
+
## 🧩 Four Words You Will See
|
|
92
|
+
|
|
93
|
+
| Word | Plain meaning |
|
|
94
|
+
| --- | --- |
|
|
95
|
+
| **Agent / harness** | The AI program you are already using, such as Codex or Claude Code. |
|
|
96
|
+
| **Browser backend** | The tool that actually moves the browser, such as `agent-browser` or BSK. |
|
|
97
|
+
| **Decision provider** | The model that chooses the next browser action. |
|
|
98
|
+
| **Proposal** | A small data object such as "click `@e4`"; it is not permission to act. |
|
|
99
|
+
|
|
100
|
+
## 🚀 Quick Start
|
|
101
|
+
|
|
102
|
+
### Requirements
|
|
103
|
+
|
|
104
|
+
- Node.js 20 or newer
|
|
105
|
+
- `agent-browser` or BSK
|
|
106
|
+
- A TypeSafe/JEV, OpenRouter, or OpenAI-compatible API key
|
|
107
|
+
|
|
108
|
+
### 1. Install Browsemux
|
|
109
|
+
|
|
110
|
+
```bash
|
|
111
|
+
npm install -g browsemux
|
|
112
|
+
browsemux --version
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
### 2. Add the Browsemux skill to your agents
|
|
116
|
+
|
|
117
|
+
```bash
|
|
118
|
+
browsemux skill install --harness all
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
This teaches compatible agents to use Browsemux for bounded browser tasks. Start
|
|
122
|
+
a new agent session afterward so the skill is discovered.
|
|
123
|
+
|
|
124
|
+
### 3. Install one browser backend
|
|
125
|
+
|
|
126
|
+
For most first-time users, `agent-browser` is the easiest option:
|
|
127
|
+
|
|
128
|
+
```bash
|
|
129
|
+
npm install -g agent-browser
|
|
130
|
+
agent-browser install
|
|
131
|
+
agent-browser doctor
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
For BSK on Windows:
|
|
135
|
+
|
|
136
|
+
```powershell
|
|
137
|
+
irm https://raw.githubusercontent.com/Tencent/BrowserSkill/main/install.ps1 | iex
|
|
138
|
+
bsk --version
|
|
139
|
+
bsk doctor
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
For BSK on macOS or Linux:
|
|
143
|
+
|
|
144
|
+
```bash
|
|
145
|
+
curl -fsSL https://raw.githubusercontent.com/Tencent/BrowserSkill/main/install.sh | sh
|
|
146
|
+
export PATH="${BSK_INSTALL_DIR:-$HOME/.local/bin}:$PATH"
|
|
147
|
+
bsk --version
|
|
148
|
+
bsk doctor
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
BSK also needs its browser extension and a connected Chrome or Edge window. See
|
|
152
|
+
Tencent's
|
|
153
|
+
[agent install guide](https://github.com/Tencent/BrowserSkill/blob/main/AGENT_INSTALL.md).
|
|
154
|
+
|
|
155
|
+
### 4. Add a decision-provider key
|
|
156
|
+
|
|
157
|
+
PowerShell:
|
|
158
|
+
|
|
159
|
+
```powershell
|
|
160
|
+
$env:TYPESAFE_API_KEY = "<YOUR_TYPESAFE_API_KEY>"
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
macOS or Linux:
|
|
164
|
+
|
|
165
|
+
```bash
|
|
166
|
+
export TYPESAFE_API_KEY="<YOUR_TYPESAFE_API_KEY>"
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
Prefer another model? See [Providers](docs/providers.md).
|
|
170
|
+
|
|
171
|
+
### 5. Check everything
|
|
172
|
+
|
|
173
|
+
```bash
|
|
174
|
+
browsemux doctor
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
The result should include `"ready": true`.
|
|
178
|
+
|
|
179
|
+
### 6. Run a browser task
|
|
180
|
+
|
|
181
|
+
macOS or Linux:
|
|
182
|
+
|
|
183
|
+
```bash
|
|
184
|
+
browsemux run \
|
|
185
|
+
--backend agent-browser \
|
|
186
|
+
--provider typesafe \
|
|
187
|
+
--url https://example.com \
|
|
188
|
+
--goal "Open the Learn more documentation link" \
|
|
189
|
+
--success-url-contains iana.org \
|
|
190
|
+
--max-steps 4
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
Windows PowerShell:
|
|
194
|
+
|
|
195
|
+
```powershell
|
|
196
|
+
browsemux run --backend agent-browser --provider typesafe --url https://example.com --goal "Open the Learn more documentation link" --success-url-contains iana.org --max-steps 4
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
You should receive one JSON result. A real success includes
|
|
200
|
+
`"status": "success"` plus evidence from the final page.
|
|
201
|
+
|
|
202
|
+
## 🧠 How It Works
|
|
203
|
+
|
|
204
|
+
Here is the complete flow:
|
|
205
|
+
|
|
206
|
+
1. Your agent gives Browsemux a goal and success rule.
|
|
207
|
+
2. Browsemux takes a compact snapshot of the current page.
|
|
208
|
+
3. The decision model receives the goal and snapshot.
|
|
209
|
+
4. The model returns a small proposal, such as:
|
|
210
|
+
|
|
211
|
+
```json
|
|
212
|
+
{
|
|
213
|
+
"operation": "CLICK",
|
|
214
|
+
"target": "@e4",
|
|
215
|
+
"confidence": 0.93
|
|
216
|
+
}
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
5. Browsemux checks the proposal against local rules.
|
|
220
|
+
6. Only a valid action reaches `agent-browser` or BSK.
|
|
221
|
+
7. Browsemux observes the result and repeats until success, a blocker, or the
|
|
222
|
+
step limit.
|
|
223
|
+
|
|
224
|
+
### Why doesn't the model control the browser directly?
|
|
225
|
+
|
|
226
|
+
Because a model can be wrong, and page content can contain misleading
|
|
227
|
+
instructions. Letting it control the browser directly would turn a mistaken
|
|
228
|
+
prediction into a real click.
|
|
229
|
+
|
|
230
|
+
Browsemux treats the model output as untrusted data. It checks that the target
|
|
231
|
+
exists in the latest snapshot, has the correct role, uses a supported
|
|
232
|
+
operation, does not repeat without progress, and passes the configured success
|
|
233
|
+
criteria.
|
|
234
|
+
|
|
235
|
+
This is also why the decision model does not need a browser handle or the
|
|
236
|
+
ability to execute JavaScript.
|
|
237
|
+
|
|
238
|
+
## 🌐 Supported Tools
|
|
239
|
+
|
|
240
|
+
### Browser backends
|
|
241
|
+
|
|
242
|
+
| Backend | Best for | Notes |
|
|
243
|
+
| --- | --- | --- |
|
|
244
|
+
| `agent-browser` | Isolated browser tasks and a simple first setup | Recommended first choice |
|
|
245
|
+
| BSK / Tencent Agent Window | Using a connected Chrome or Edge window | Requires the BSK extension |
|
|
246
|
+
|
|
247
|
+
### Decision providers
|
|
248
|
+
|
|
249
|
+
| Provider | Use it when |
|
|
250
|
+
| --- | --- |
|
|
251
|
+
| TypeSafe / JEV | You want a compact JEV-based decision model |
|
|
252
|
+
| OpenRouter Decisions | You want to choose a supported OpenRouter decision model |
|
|
253
|
+
| OpenAI-compatible | You have another compatible endpoint that returns JSON |
|
|
254
|
+
|
|
255
|
+
You can change the provider or backend without changing the task goal. See
|
|
256
|
+
[Providers](docs/providers.md) and [Backends](docs/backends.md).
|
|
257
|
+
|
|
258
|
+
## 📊 Benchmarks
|
|
259
|
+
|
|
260
|
+
The repo includes a repeatable A/B test that compares **direct agent control**
|
|
261
|
+
with **the same browser behind Browsemux**.
|
|
262
|
+
|
|
263
|
+
Latest controlled run on 2026-11-21. Each backend and workflow was recorded
|
|
264
|
+
three times:
|
|
265
|
+
|
|
266
|
+
| Browser | Path | Verified | Median time | Input tokens | Cost per verified task |
|
|
267
|
+
| --- | --- | ---: | ---: | ---: | ---: |
|
|
268
|
+
| `agent-browser` | Direct agent | 12/12 | 12,500 ms | 910.5 | $0.000331 |
|
|
269
|
+
| `agent-browser` | Through Browsemux | 11/12 | 11,558 ms | 832.5 | $0.000294 |
|
|
270
|
+
| BSK | Direct agent | 11/12 | 15,532 ms | 993.5 | $0.000404 |
|
|
271
|
+
| BSK | Through Browsemux | 11/12 | 13,200 ms | 902.5 | $0.000401 |
|
|
272
|
+
|
|
273
|
+
What this run showed:
|
|
274
|
+
|
|
275
|
+
- **agent-browser:** Browsemux was 7.5% faster, used 8.6% fewer input tokens, and
|
|
276
|
+
cost 10.9% less per verified task. One Browsemux run failed during browser
|
|
277
|
+
startup before a model call, so verified success was 11/12 instead of 12/12.
|
|
278
|
+
- **BSK:** Browsemux was 15.0% faster, used 9.2% fewer input tokens, and had
|
|
279
|
+
approximately the same cost per verified task. Both paths verified 11/12.
|
|
280
|
+
- **Overall:** the efficiency signal is positive, but the reliability result is
|
|
281
|
+
mixed. These fixture results are evidence, not a universal guarantee.
|
|
282
|
+
|
|
283
|
+
- [Read the method and all results](docs/benchmarks.md)
|
|
284
|
+
- [Reproduce the benchmark](bench/README.md)
|
|
285
|
+
|
|
286
|
+
## ✅ What a Result Looks Like
|
|
287
|
+
|
|
288
|
+
Browsemux returns one JSON result by default. Add `--jsonl` to stream events:
|
|
289
|
+
|
|
290
|
+
```text
|
|
291
|
+
start
|
|
292
|
+
observation
|
|
293
|
+
decision
|
|
294
|
+
validation
|
|
295
|
+
action
|
|
296
|
+
result
|
|
297
|
+
```
|
|
298
|
+
|
|
299
|
+
The result contains the status, browser and provider, action history, step
|
|
300
|
+
count, timings, token usage, cost when available, and a compact handoff for the
|
|
301
|
+
parent agent.
|
|
302
|
+
|
|
303
|
+
| Status | What it means |
|
|
304
|
+
| --- | --- |
|
|
305
|
+
| `success` | The configured URL or text check passed |
|
|
306
|
+
| `completed-unverified` | The model claimed completion, but evidence is missing |
|
|
307
|
+
| `blocked` | A human decision or external blocker is required |
|
|
308
|
+
| `effect-unknown` | A write may have happened; do not blindly retry |
|
|
309
|
+
| `limit` | The step or recovery budget ended |
|
|
310
|
+
| `error` | Setup, provider, browser, or proposal failure |
|
|
311
|
+
|
|
312
|
+
Exit codes are `0` for success, `2` for completed-unverified, `3` for blocked,
|
|
313
|
+
`4` for effect-unknown, `5` for limit, and `1` for error.
|
|
314
|
+
|
|
315
|
+
## 🔐 Safety and Limits
|
|
316
|
+
|
|
317
|
+
- The decision model never receives a browser handle.
|
|
318
|
+
- The model cannot execute JavaScript or shell commands.
|
|
319
|
+
- Actions must reference the latest page snapshot.
|
|
320
|
+
- Only HTTP and HTTPS navigation is accepted.
|
|
321
|
+
- Repeated actions are bounded.
|
|
322
|
+
- Provider API keys are removed from browser subprocess environments.
|
|
323
|
+
- Secret input values are redacted from provider metadata.
|
|
324
|
+
|
|
325
|
+
Human approval is still required for payments, uploads, MFA, CAPTCHA, account
|
|
326
|
+
deletion, and other destructive actions. Browsemux is also not designed to
|
|
327
|
+
bypass anti-bot systems.
|
|
328
|
+
|
|
329
|
+
See [SECURITY.md](SECURITY.md) for the full trust model.
|
|
330
|
+
|
|
331
|
+
## 📚 Documentation
|
|
332
|
+
|
|
333
|
+
| Guide | What it covers |
|
|
334
|
+
| --- | --- |
|
|
335
|
+
| [Installation](docs/installation.md) | Complete setup, updates, and troubleshooting |
|
|
336
|
+
| [Harness skills](docs/harness-skills.md) | Codex, Claude Code, Cursor, OpenCode, and Hermes |
|
|
337
|
+
| [Backends](docs/backends.md) | `agent-browser` and BSK behavior |
|
|
338
|
+
| [Providers](docs/providers.md) | TypeSafe, OpenRouter, and compatible endpoints |
|
|
339
|
+
| [Architecture](docs/architecture.md) | Control flow and trust boundaries |
|
|
340
|
+
| [Validation](docs/validation.md) | Tested environments and live smoke evidence |
|
|
341
|
+
| [Benchmarks](docs/benchmarks.md) | Method, measurements, and limitations |
|
|
342
|
+
|
|
343
|
+
## 🛠️ Development
|
|
344
|
+
|
|
345
|
+
```bash
|
|
346
|
+
npm test
|
|
347
|
+
npm run check
|
|
348
|
+
npm run bench:smoke
|
|
349
|
+
```
|
|
350
|
+
|
|
351
|
+
The project has no runtime dependencies. Browser adapters fail closed,
|
|
352
|
+
providers return structured proposals, and public performance claims must stay
|
|
353
|
+
within the benchmark evidence.
|
|
354
|
+
|
|
355
|
+
## 🤝 Contributing
|
|
356
|
+
|
|
357
|
+
Contributions are welcome through
|
|
358
|
+
[issues](https://github.com/xenstar/browsemux/issues) and focused pull requests.
|
|
359
|
+
For behavior changes, include tests and update the relevant public claim.
|
|
360
|
+
|
|
361
|
+
[](https://github.com/xenstar/browsemux/graphs/contributors)
|
|
362
|
+
|
|
363
|
+
## 🔗 Policies
|
|
364
|
+
|
|
365
|
+
- [MIT License](LICENSE)
|
|
366
|
+
- [Contributing](CONTRIBUTING.md)
|
|
367
|
+
- [Code of Conduct](CODE_OF_CONDUCT.md)
|
|
368
|
+
- [Security](SECURITY.md)
|
|
369
|
+
- [Privacy](PRIVACY.md)
|
|
370
|
+
- [Changelog](CHANGELOG.md)
|
|
371
|
+
|
|
372
|
+
<details>
|
|
373
|
+
<summary><strong>Use Browsemux from JavaScript</strong></summary>
|
|
374
|
+
|
|
375
|
+
The CLI covers normal use. Advanced users can embed the same bounded loop:
|
|
376
|
+
|
|
377
|
+
```js
|
|
378
|
+
import {
|
|
379
|
+
AgentBrowserBackend,
|
|
380
|
+
OpenAICompatibleProvider,
|
|
381
|
+
normalizeInputs,
|
|
382
|
+
runLoop,
|
|
383
|
+
} from 'browsemux';
|
|
384
|
+
|
|
385
|
+
const browser = new AgentBrowserBackend();
|
|
386
|
+
const provider = new OpenAICompatibleProvider({
|
|
387
|
+
endpoint: 'https://openrouter.ai/api/v1/chat/completions',
|
|
388
|
+
apiKey: process.env.OPENROUTER_API_KEY,
|
|
389
|
+
model: '<OPENROUTER_DECISION_MODEL_SLUG>',
|
|
390
|
+
});
|
|
391
|
+
|
|
392
|
+
const observation = await browser.open('https://example.com');
|
|
393
|
+
const result = await runLoop({
|
|
394
|
+
goal: 'Open the Learn more link',
|
|
395
|
+
browser,
|
|
396
|
+
provider,
|
|
397
|
+
inputs: normalizeInputs(),
|
|
398
|
+
initialObservation: observation,
|
|
399
|
+
successCriteria: { urlContains: 'iana.org' },
|
|
400
|
+
maxSteps: 4,
|
|
401
|
+
});
|
|
402
|
+
```
|
|
403
|
+
|
|
404
|
+
</details>
|
|
405
|
+
|
|
406
|
+
<a id="project-status"></a>
|
|
407
|
+
## 🚦 Project Status
|
|
408
|
+
|
|
409
|
+
Browsemux is an early public release. The supported release includes:
|
|
410
|
+
|
|
411
|
+
- `agent-browser`
|
|
412
|
+
- BSK / Tencent Agent Window
|
|
413
|
+
- TypeSafe/JEV
|
|
414
|
+
- OpenRouter Decisions
|
|
415
|
+
- OpenAI-compatible JSON output
|
|
416
|
+
|
|
417
|
+
Playwright, Browser Use, Stagehand, Skyvern, and other backends are not part of
|
|
418
|
+
the current release.
|
package/SECURITY.md
ADDED
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
# Security
|
|
2
|
+
|
|
3
|
+
## Trust boundary
|
|
4
|
+
|
|
5
|
+
Decision models are untrusted proposal generators. They do not receive direct
|
|
6
|
+
browser handles and they cannot execute code. Browsemux validates every
|
|
7
|
+
proposal against the latest observation before dispatching a backend command.
|
|
8
|
+
|
|
9
|
+
## Default protections
|
|
10
|
+
|
|
11
|
+
- Target references must exist in the latest snapshot.
|
|
12
|
+
- Unsupported operations are rejected.
|
|
13
|
+
- Arbitrary JavaScript is not exposed to providers.
|
|
14
|
+
- Sensitive input values are not sent to decision providers.
|
|
15
|
+
- Navigation URLs must use HTTP or HTTPS.
|
|
16
|
+
- Repeated semantic actions are bounded.
|
|
17
|
+
- Browser sessions close by default.
|
|
18
|
+
|
|
19
|
+
## Sensitive actions
|
|
20
|
+
|
|
21
|
+
Do not delegate payments, destructive account actions, file uploads, MFA, or
|
|
22
|
+
CAPTCHA handling without explicit human approval and a backend-specific policy.
|
|
23
|
+
Browsemux does not solve CAPTCHAs and does not bypass authentication.
|
|
24
|
+
|
|
25
|
+
## Reporting
|
|
26
|
+
|
|
27
|
+
Do not open a public issue for a vulnerability involving credentials or browser
|
|
28
|
+
escape. Use GitHub private vulnerability reporting:
|
|
29
|
+
|
|
30
|
+
```text
|
|
31
|
+
https://github.com/xenstar/browsemux/security/advisories/new
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
Include the affected version, backend, provider, reproduction steps, and the
|
|
35
|
+
smallest safe diagnostic output. Never include API keys, cookies, session
|
|
36
|
+
tokens, private URLs, or page content.
|