browsemux 0.1.0 โ 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 +8 -0
- package/README.md +233 -304
- package/docs/benchmarks.md +2 -2
- package/docs/installation.md +4 -4
- package/package.json +2 -2
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,13 @@
|
|
|
1
1
|
# Changelog
|
|
2
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
|
+
|
|
3
11
|
## 0.1.0 - 2026-11-21
|
|
4
12
|
|
|
5
13
|
- Added a portable `browsemux` harness skill and `browsemux skill install`
|
package/README.md
CHANGED
|
@@ -2,120 +2,128 @@
|
|
|
2
2
|
|
|
3
3
|
# ๐งญ Browsemux
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
### Give your AI agent a safer, cheaper way to use a browser.
|
|
6
6
|
|
|
7
|
-
|
|
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.
|
|
8
10
|
|
|
9
11
|
[](https://github.com/xenstar/browsemux/actions/workflows/test.yml)
|
|
12
|
+
[](https://www.npmjs.com/package/browsemux)
|
|
10
13
|
[](LICENSE)
|
|
11
14
|
[](https://nodejs.org/)
|
|
12
|
-
[](https://github.com/xenstar/browsemux/stargazers)
|
|
14
|
-
[](https://github.com/xenstar/browsemux/network/members)
|
|
15
|
-
[](https://github.com/xenstar/browsemux/issues)
|
|
15
|
+
[](#project-status)
|
|
16
16
|
|
|
17
|
-
[
|
|
18
|
-
[Benchmarks](
|
|
19
|
-
[Contributing](#contributing)
|
|
17
|
+
[How it works](#-how-it-works) ยท [Quick start](#-quick-start) ยท
|
|
18
|
+
[Benchmarks](#-benchmarks) ยท [Documentation](#-documentation)
|
|
20
19
|
|
|
21
20
|
</div>
|
|
22
21
|
|
|
23
|
-
##
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
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.
|
|
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:
|
|
50
29
|
|
|
51
30
|
```text
|
|
52
|
-
|
|
53
|
-
-> Browsemux
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
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
|
|
59
38
|
```
|
|
60
39
|
|
|
61
|
-
**
|
|
62
|
-
it. The model never receives a browser handle or executes code.
|
|
40
|
+
**The main AI still manages the task. Browsemux only handles the browser work.**
|
|
63
41
|
|
|
64
|
-
|
|
65
|
-
## ๐ฆ Project Status
|
|
42
|
+
## โ Why Do I Need It?
|
|
66
43
|
|
|
67
|
-
|
|
68
|
-
is directly from GitHub.
|
|
44
|
+
Browser agents often do this:
|
|
69
45
|
|
|
70
|
-
|
|
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.
|
|
71
51
|
|
|
72
|
-
|
|
73
|
-
|
|
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.
|
|
74
54
|
|
|
75
|
-
|
|
55
|
+
Browsemux improves the workflow in five practical ways:
|
|
76
56
|
|
|
77
|
-
-
|
|
78
|
-
|
|
79
|
-
-
|
|
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.
|
|
80
67
|
|
|
81
|
-
|
|
82
|
-
|
|
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.
|
|
83
71
|
|
|
84
|
-
|
|
85
|
-
|
|
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).
|
|
86
74
|
|
|
87
|
-
|
|
75
|
+
## ๐ฅ Who Is It For?
|
|
88
76
|
|
|
89
|
-
|
|
77
|
+
Browsemux is useful if you want to:
|
|
90
78
|
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
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.
|
|
95
90
|
|
|
96
|
-
|
|
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
|
|
97
109
|
|
|
98
110
|
```bash
|
|
99
|
-
|
|
100
|
-
cd browsemux
|
|
101
|
-
npm install
|
|
102
|
-
npm link
|
|
111
|
+
npm install -g browsemux
|
|
103
112
|
browsemux --version
|
|
104
113
|
```
|
|
105
114
|
|
|
106
|
-
|
|
107
|
-
harness skill directories. Run the skill installation step once after each
|
|
108
|
-
install or update.
|
|
115
|
+
### 2. Add the Browsemux skill to your agents
|
|
109
116
|
|
|
110
|
-
|
|
117
|
+
```bash
|
|
118
|
+
browsemux skill install --harness all
|
|
119
|
+
```
|
|
111
120
|
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
- One decision-provider API key
|
|
121
|
+
This teaches compatible agents to use Browsemux for bounded browser tasks. Start
|
|
122
|
+
a new agent session afterward so the skill is discovered.
|
|
115
123
|
|
|
116
|
-
###
|
|
124
|
+
### 3. Install one browser backend
|
|
117
125
|
|
|
118
|
-
|
|
126
|
+
For most first-time users, `agent-browser` is the easiest option:
|
|
119
127
|
|
|
120
128
|
```bash
|
|
121
129
|
npm install -g agent-browser
|
|
@@ -140,11 +148,11 @@ bsk --version
|
|
|
140
148
|
bsk doctor
|
|
141
149
|
```
|
|
142
150
|
|
|
143
|
-
BSK also
|
|
144
|
-
Tencent's
|
|
151
|
+
BSK also needs its browser extension and a connected Chrome or Edge window. See
|
|
152
|
+
Tencent's
|
|
145
153
|
[agent install guide](https://github.com/Tencent/BrowserSkill/blob/main/AGENT_INSTALL.md).
|
|
146
154
|
|
|
147
|
-
###
|
|
155
|
+
### 4. Add a decision-provider key
|
|
148
156
|
|
|
149
157
|
PowerShell:
|
|
150
158
|
|
|
@@ -158,63 +166,21 @@ macOS or Linux:
|
|
|
158
166
|
export TYPESAFE_API_KEY="<YOUR_TYPESAFE_API_KEY>"
|
|
159
167
|
```
|
|
160
168
|
|
|
161
|
-
|
|
169
|
+
Prefer another model? See [Providers](docs/providers.md).
|
|
162
170
|
|
|
163
|
-
|
|
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:
|
|
171
|
+
### 5. Check everything
|
|
173
172
|
|
|
174
173
|
```bash
|
|
175
|
-
browsemux
|
|
174
|
+
browsemux doctor
|
|
176
175
|
```
|
|
177
176
|
|
|
178
|
-
|
|
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
|
|
177
|
+
The result should include `"ready": true`.
|
|
196
178
|
|
|
197
|
-
###
|
|
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
|
-
```
|
|
179
|
+
### 6. Run a browser task
|
|
212
180
|
|
|
213
181
|
macOS or Linux:
|
|
214
182
|
|
|
215
183
|
```bash
|
|
216
|
-
export TYPESAFE_API_KEY="<YOUR_TYPESAFE_API_KEY>"
|
|
217
|
-
|
|
218
184
|
browsemux run \
|
|
219
185
|
--backend agent-browser \
|
|
220
186
|
--provider typesafe \
|
|
@@ -224,140 +190,102 @@ browsemux run \
|
|
|
224
190
|
--max-steps 4
|
|
225
191
|
```
|
|
226
192
|
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
```bash
|
|
230
|
-
export OPENROUTER_API_KEY="<YOUR_OPENROUTER_API_KEY>"
|
|
193
|
+
Windows PowerShell:
|
|
231
194
|
|
|
232
|
-
|
|
233
|
-
|
|
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
|
|
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
|
|
238
197
|
```
|
|
239
198
|
|
|
240
|
-
|
|
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
|
-
```
|
|
199
|
+
You should receive one JSON result. A real success includes
|
|
200
|
+
`"status": "success"` plus evidence from the final page.
|
|
253
201
|
|
|
254
|
-
|
|
255
|
-
explicitly required.
|
|
202
|
+
## ๐ง How It Works
|
|
256
203
|
|
|
257
|
-
|
|
258
|
-
## ๐ Benchmarks
|
|
204
|
+
Here is the complete flow:
|
|
259
205
|
|
|
260
|
-
|
|
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:
|
|
261
210
|
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
211
|
+
```json
|
|
212
|
+
{
|
|
213
|
+
"operation": "CLICK",
|
|
214
|
+
"target": "@e4",
|
|
215
|
+
"confidence": 0.93
|
|
216
|
+
}
|
|
217
|
+
```
|
|
268
218
|
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
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.
|
|
273
223
|
|
|
274
|
-
|
|
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.
|
|
224
|
+
### Why doesn't the model control the browser directly?
|
|
279
225
|
|
|
280
|
-
|
|
281
|
-
|
|
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.
|
|
282
229
|
|
|
283
|
-
|
|
284
|
-
|
|
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.
|
|
285
234
|
|
|
286
|
-
|
|
287
|
-
|
|
235
|
+
This is also why the decision model does not need a browser handle or the
|
|
236
|
+
ability to execute JavaScript.
|
|
288
237
|
|
|
289
|
-
|
|
238
|
+
## ๐ Supported Tools
|
|
290
239
|
|
|
291
|
-
|
|
292
|
-
content.
|
|
240
|
+
### Browser backends
|
|
293
241
|
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
--inputs-json '{"text":{"query":"Browsemux"},"keys":{"submit":"Enter"}}'
|
|
299
|
-
```
|
|
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 |
|
|
300
246
|
|
|
301
|
-
|
|
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
|
-
```
|
|
247
|
+
### Decision providers
|
|
321
248
|
|
|
322
|
-
|
|
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 |
|
|
323
254
|
|
|
324
|
-
|
|
255
|
+
You can change the provider or backend without changing the task goal. See
|
|
256
|
+
[Providers](docs/providers.md) and [Backends](docs/backends.md).
|
|
325
257
|
|
|
326
|
-
|
|
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
|
-
```
|
|
258
|
+
## ๐ Benchmarks
|
|
339
259
|
|
|
340
|
-
|
|
341
|
-
|
|
260
|
+
The repo includes a repeatable A/B test that compares **direct agent control**
|
|
261
|
+
with **the same browser behind Browsemux**.
|
|
342
262
|
|
|
343
|
-
|
|
263
|
+
Latest controlled run on 2026-11-21. Each backend and workflow was recorded
|
|
264
|
+
three times:
|
|
344
265
|
|
|
345
|
-
|
|
346
|
-
|
|
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 |
|
|
347
272
|
|
|
348
|
-
|
|
273
|
+
What this run showed:
|
|
349
274
|
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
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.
|
|
354
282
|
|
|
355
|
-
|
|
283
|
+
- [Read the method and all results](docs/benchmarks.md)
|
|
284
|
+
- [Reproduce the benchmark](bench/README.md)
|
|
356
285
|
|
|
357
|
-
|
|
358
|
-
## ๐ฆ Output
|
|
286
|
+
## โ
What a Result Looks Like
|
|
359
287
|
|
|
360
|
-
|
|
288
|
+
Browsemux returns one JSON result by default. Add `--jsonl` to stream events:
|
|
361
289
|
|
|
362
290
|
```text
|
|
363
291
|
start
|
|
@@ -368,80 +296,83 @@ action
|
|
|
368
296
|
result
|
|
369
297
|
```
|
|
370
298
|
|
|
371
|
-
The result contains
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
|
|
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.
|
|
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.
|
|
404
322
|
- Provider API keys are removed from browser subprocess environments.
|
|
405
|
-
-
|
|
406
|
-
|
|
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.
|
|
407
328
|
|
|
408
|
-
See [SECURITY.md](SECURITY.md) for the trust
|
|
329
|
+
See [SECURITY.md](SECURITY.md) for the full trust model.
|
|
409
330
|
|
|
410
|
-
<a id="documentation"></a>
|
|
411
331
|
## ๐ Documentation
|
|
412
332
|
|
|
413
|
-
| Guide |
|
|
333
|
+
| Guide | What it covers |
|
|
414
334
|
| --- | --- |
|
|
415
|
-
| [Installation](docs/installation.md) |
|
|
416
|
-
| [Harness skills](docs/harness-skills.md) |
|
|
335
|
+
| [Installation](docs/installation.md) | Complete setup, updates, and troubleshooting |
|
|
336
|
+
| [Harness skills](docs/harness-skills.md) | Codex, Claude Code, Cursor, OpenCode, and Hermes |
|
|
417
337
|
| [Backends](docs/backends.md) | `agent-browser` and BSK behavior |
|
|
418
|
-
| [Providers](docs/providers.md) | TypeSafe, OpenRouter, and
|
|
338
|
+
| [Providers](docs/providers.md) | TypeSafe, OpenRouter, and compatible endpoints |
|
|
419
339
|
| [Architecture](docs/architecture.md) | Control flow and trust boundaries |
|
|
420
340
|
| [Validation](docs/validation.md) | Tested environments and live smoke evidence |
|
|
421
341
|
| [Benchmarks](docs/benchmarks.md) | Method, measurements, and limitations |
|
|
422
342
|
|
|
423
|
-
|
|
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
|
+
|
|
424
355
|
## ๐ค Contributing
|
|
425
356
|
|
|
426
|
-
Contributions are welcome through
|
|
427
|
-
and focused pull requests.
|
|
428
|
-
|
|
429
|
-
benchmark evidence changes.
|
|
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.
|
|
430
360
|
|
|
431
361
|
[](https://github.com/xenstar/browsemux/graphs/contributors)
|
|
432
362
|
|
|
433
|
-
|
|
434
|
-
## ๐ค Project Policies
|
|
363
|
+
## ๐ Policies
|
|
435
364
|
|
|
436
|
-
- [License](LICENSE)
|
|
365
|
+
- [MIT License](LICENSE)
|
|
437
366
|
- [Contributing](CONTRIBUTING.md)
|
|
438
|
-
- [Code of
|
|
439
|
-
- [Security
|
|
440
|
-
- [Privacy
|
|
367
|
+
- [Code of Conduct](CODE_OF_CONDUCT.md)
|
|
368
|
+
- [Security](SECURITY.md)
|
|
369
|
+
- [Privacy](PRIVACY.md)
|
|
441
370
|
- [Changelog](CHANGELOG.md)
|
|
442
371
|
|
|
443
|
-
<
|
|
444
|
-
|
|
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:
|
|
445
376
|
|
|
446
377
|
```js
|
|
447
378
|
import {
|
|
@@ -470,20 +401,18 @@ const result = await runLoop({
|
|
|
470
401
|
});
|
|
471
402
|
```
|
|
472
403
|
|
|
473
|
-
|
|
474
|
-
## ๐ ๏ธ Development
|
|
404
|
+
</details>
|
|
475
405
|
|
|
476
|
-
|
|
477
|
-
|
|
478
|
-
npm run check
|
|
479
|
-
npm run bench:smoke
|
|
480
|
-
```
|
|
406
|
+
<a id="project-status"></a>
|
|
407
|
+
## ๐ฆ Project Status
|
|
481
408
|
|
|
482
|
-
|
|
483
|
-
and provider adapters must return typed proposals rather than browser commands.
|
|
409
|
+
Browsemux is an early public release. The supported release includes:
|
|
484
410
|
|
|
485
|
-
|
|
411
|
+
- `agent-browser`
|
|
412
|
+
- BSK / Tencent Agent Window
|
|
413
|
+
- TypeSafe/JEV
|
|
414
|
+
- OpenRouter Decisions
|
|
415
|
+
- OpenAI-compatible JSON output
|
|
486
416
|
|
|
487
|
-
|
|
488
|
-
|
|
489
|
-
the browser.
|
|
417
|
+
Playwright, Browser Use, Stagehand, Skyvern, and other backends are not part of
|
|
418
|
+
the current release.
|
package/docs/benchmarks.md
CHANGED
|
@@ -285,8 +285,8 @@ classification modes.
|
|
|
285
285
|
|
|
286
286
|
| Metric | Value |
|
|
287
287
|
| --- | ---: |
|
|
288
|
-
| Packed package | approximately 46.
|
|
289
|
-
| Unpacked package | approximately
|
|
288
|
+
| Packed package | approximately 46.1 KB |
|
|
289
|
+
| Unpacked package | approximately 164.8 KB |
|
|
290
290
|
| Packaged files | 39 |
|
|
291
291
|
| Runtime dependencies | 0 |
|
|
292
292
|
|
package/docs/installation.md
CHANGED
|
@@ -19,12 +19,12 @@ For the easiest first run, use `agent-browser` with TypeSafe System One / JEV.
|
|
|
19
19
|
|
|
20
20
|
## ๐ฅ Install Browsemux
|
|
21
21
|
|
|
22
|
-
### Recommended: global install from
|
|
22
|
+
### Recommended: global install from npm
|
|
23
23
|
|
|
24
|
-
|
|
24
|
+
Install the published package:
|
|
25
25
|
|
|
26
26
|
```bash
|
|
27
|
-
npm install -g
|
|
27
|
+
npm install -g browsemux
|
|
28
28
|
browsemux --version
|
|
29
29
|
```
|
|
30
30
|
|
|
@@ -315,7 +315,7 @@ restarting or reinstalling repeatedly.
|
|
|
315
315
|
Update Browsemux:
|
|
316
316
|
|
|
317
317
|
```bash
|
|
318
|
-
npm install -g
|
|
318
|
+
npm install -g browsemux
|
|
319
319
|
```
|
|
320
320
|
|
|
321
321
|
Update `agent-browser`:
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "browsemux",
|
|
3
|
-
"version": "0.1.
|
|
4
|
-
"description": "A
|
|
3
|
+
"version": "0.1.1",
|
|
4
|
+
"description": "A safer browser decision bridge for AI agents.",
|
|
5
5
|
"author": "xenstar",
|
|
6
6
|
"homepage": "https://github.com/xenstar/browsemux",
|
|
7
7
|
"repository": {
|