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 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
- **Route browser decisions. Keep deterministic control.**
5
+ ### Give your AI agent a safer, cheaper way to use a browser.
6
6
 
7
- A bounded decision bridge between agent harnesses and browser backends.
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
  [![Tests](https://img.shields.io/github/actions/workflow/status/xenstar/browsemux/test.yml?branch=main&label=tests&style=flat-square&labelColor=black)](https://github.com/xenstar/browsemux/actions/workflows/test.yml)
12
+ [![npm](https://img.shields.io/npm/v/browsemux?style=flat-square&labelColor=black)](https://www.npmjs.com/package/browsemux)
10
13
  [![License](https://img.shields.io/github/license/xenstar/browsemux?style=flat-square&labelColor=black)](LICENSE)
11
14
  [![Node.js](https://img.shields.io/badge/node-%E2%89%A520-339933?style=flat-square&logo=node.js&logoColor=white&labelColor=black)](https://nodejs.org/)
12
- [![Status](https://img.shields.io/badge/status-pre--release-f59e0b?style=flat-square&labelColor=black)](#project-status)
13
- [![Stars](https://img.shields.io/github/stars/xenstar/browsemux?style=flat-square&labelColor=black)](https://github.com/xenstar/browsemux/stargazers)
14
- [![Forks](https://img.shields.io/github/forks/xenstar/browsemux?style=flat-square&labelColor=black)](https://github.com/xenstar/browsemux/network/members)
15
- [![Issues](https://img.shields.io/github/issues/xenstar/browsemux?style=flat-square&labelColor=black)](https://github.com/xenstar/browsemux/issues)
15
+ [![Status](https://img.shields.io/badge/status-early%20release-2563eb?style=flat-square&labelColor=black)](#project-status)
16
16
 
17
- [Features](#features) ยท [Install](#quick-install) ยท [Quick start](#quick-start) ยท
18
- [Benchmarks](#benchmarks) ยท [Documentation](#documentation) ยท
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
- ## ๐Ÿ“– 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.
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
- 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
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
- **Core contract:** the model proposes typed intent; code validates and executes
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
- <a id="project-status"></a>
65
- ## ๐Ÿšฆ Project Status
42
+ ## โ“ Why Do I Need It?
66
43
 
67
- Browsemux is a **pre-release** project. The current supported installation path
68
- is directly from GitHub.
44
+ Browser agents often do this:
69
45
 
70
- Supported browser backends:
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
- - `agent-browser`
73
- - BSK / Tencent Agent Window
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
- Supported decision providers:
55
+ Browsemux improves the workflow in five practical ways:
76
56
 
77
- - TypeSafe System One / JEV
78
- - OpenRouter Decisions
79
- - OpenAI-compatible chat completions with JSON output
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
- Browser Use, Playwright, Stagehand, Skyvern, and other frameworks remain
82
- outside the initial scope.
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
- <a id="quick-install"></a>
85
- ## ๐Ÿš€ Quick Install
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
- ### 1. Install Browsemux
75
+ ## ๐Ÿ‘ฅ Who Is It For?
88
76
 
89
- Recommended global install from GitHub:
77
+ Browsemux is useful if you want to:
90
78
 
91
- ```bash
92
- npm install -g github:xenstar/browsemux
93
- browsemux --version
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
- Install from a local clone:
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
- git clone https://github.com/xenstar/browsemux.git
100
- cd browsemux
101
- npm install
102
- npm link
111
+ npm install -g browsemux
103
112
  browsemux --version
104
113
  ```
105
114
 
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.
115
+ ### 2. Add the Browsemux skill to your agents
109
116
 
110
- Requirements:
117
+ ```bash
118
+ browsemux skill install --harness all
119
+ ```
111
120
 
112
- - Node.js 20 or newer
113
- - One supported browser backend
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
- ### 2. Install a browser backend
124
+ ### 3. Install one browser backend
117
125
 
118
- Recommended for first-time users:
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 requires its browser extension and a connected Chromium browser. See
144
- Tencent's official
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
- ### 3. Set a provider key
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
- Verify the local setup:
169
+ Prefer another model? See [Providers](docs/providers.md).
162
170
 
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:
171
+ ### 5. Check everything
173
172
 
174
173
  ```bash
175
- browsemux skill install --harness all
174
+ browsemux doctor
176
175
  ```
177
176
 
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
177
+ The result should include `"ready": true`.
196
178
 
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
- ```
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
- ### agent-browser + OpenRouter Decisions
228
-
229
- ```bash
230
- export OPENROUTER_API_KEY="<YOUR_OPENROUTER_API_KEY>"
193
+ Windows PowerShell:
231
194
 
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
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
- ### 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
- ```
199
+ You should receive one JSON result. A real success includes
200
+ `"status": "success"` plus evidence from the final page.
253
201
 
254
- BSK sessions close by default. Use `--keep-open` only when a human handoff is
255
- explicitly required.
202
+ ## ๐Ÿง  How It Works
256
203
 
257
- <a id="benchmarks"></a>
258
- ## ๐Ÿ“Š Benchmarks
204
+ Here is the complete flow:
259
205
 
260
- Latest three-repeat controlled rerun on 2026-11-21:
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
- | 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 |
211
+ ```json
212
+ {
213
+ "operation": "CLICK",
214
+ "target": "@e4",
215
+ "confidence": 0.93
216
+ }
217
+ ```
268
218
 
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% |
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
- 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.
224
+ ### Why doesn't the model control the browser directly?
279
225
 
280
- - [Benchmark methodology and results](docs/benchmarks.md)
281
- - [Reproduce the direct-versus-mediated benchmark](bench/README.md)
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
- Decision latency dominates these short tasks. Treat the results as controlled
284
- engineering evidence, not universal browser-agent rankings.
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
- <a id="configuration"></a>
287
- ## ๐Ÿงฐ Configuration
235
+ This is also why the decision model does not need a browser handle or the
236
+ ability to execute JavaScript.
288
237
 
289
- ### Supplied inputs
238
+ ## ๐ŸŒ Supported Tools
290
239
 
291
- Decision models select supplied values; they do not invent credentials or form
292
- content.
240
+ ### Browser backends
293
241
 
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
- ```
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
- 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
- ```
247
+ ### Decision providers
321
248
 
322
- Secret values are redacted from provider metadata.
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
- ### Actions
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
- ```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
- ```
258
+ ## ๐Ÿ“Š Benchmarks
339
259
 
340
- `CLICK`, `TYPE`, and `SELECT` require a target present in the latest snapshot.
341
- Invalid roles and stale refs are rejected before backend dispatch.
260
+ The repo includes a repeatable A/B test that compares **direct agent control**
261
+ with **the same browser behind Browsemux**.
342
262
 
343
- ### Completion
263
+ Latest controlled run on 2026-11-21. Each backend and workflow was recorded
264
+ three times:
344
265
 
345
- `DONE` from a model is not treated as proof. Without deterministic checks, the
346
- result is `completed-unverified`.
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
- Use one or both deterministic checks:
273
+ What this run showed:
349
274
 
350
- ```bash
351
- --success-url-contains <URL_FRAGMENT>
352
- --success-text-contains "<VISIBLE_TEXT>"
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
- Only matching checks produce `status: "success"`.
283
+ - [Read the method and all results](docs/benchmarks.md)
284
+ - [Reproduce the benchmark](bench/README.md)
356
285
 
357
- <a id="output"></a>
358
- ## ๐Ÿ“ฆ Output
286
+ ## โœ… What a Result Looks Like
359
287
 
360
- Default output is one JSON result. `--jsonl` streams:
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
- - 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.
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
- - Human approval is still required for payments, destructive account actions,
406
- uploads, MFA, and CAPTCHA.
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 boundary.
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 | Purpose |
333
+ | Guide | What it covers |
414
334
  | --- | --- |
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 |
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 OpenAI-compatible configuration |
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
- <a id="contributing"></a>
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 [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.
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
  [![Contributors](https://contrib.rocks/image?repo=xenstar/browsemux)](https://github.com/xenstar/browsemux/graphs/contributors)
432
362
 
433
- <a id="policies"></a>
434
- ## ๐Ÿค Project Policies
363
+ ## ๐Ÿ”— Policies
435
364
 
436
- - [License](LICENSE): MIT
365
+ - [MIT License](LICENSE)
437
366
  - [Contributing](CONTRIBUTING.md)
438
- - [Code of conduct](CODE_OF_CONDUCT.md)
439
- - [Security policy](SECURITY.md)
440
- - [Privacy and data handling](PRIVACY.md)
367
+ - [Code of Conduct](CODE_OF_CONDUCT.md)
368
+ - [Security](SECURITY.md)
369
+ - [Privacy](PRIVACY.md)
441
370
  - [Changelog](CHANGELOG.md)
442
371
 
443
- <a id="library"></a>
444
- ## ๐Ÿงฑ Library
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
- <a id="development"></a>
474
- ## ๐Ÿ› ๏ธ Development
404
+ </details>
475
405
 
476
- ```bash
477
- npm test
478
- npm run check
479
- npm run bench:smoke
480
- ```
406
+ <a id="project-status"></a>
407
+ ## ๐Ÿšฆ Project Status
481
408
 
482
- The initial release is intentionally small. Backend adapters must fail closed,
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
- ## ๐Ÿท๏ธ Name
411
+ - `agent-browser`
412
+ - BSK / Tencent Agent Window
413
+ - TypeSafe/JEV
414
+ - OpenRouter Decisions
415
+ - OpenAI-compatible JSON output
486
416
 
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.
417
+ Playwright, Browser Use, Stagehand, Skyvern, and other backends are not part of
418
+ the current release.
@@ -285,8 +285,8 @@ classification modes.
285
285
 
286
286
  | Metric | Value |
287
287
  | --- | ---: |
288
- | Packed package | approximately 46.5 KB |
289
- | Unpacked package | approximately 167.2 KB |
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
 
@@ -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 GitHub
22
+ ### Recommended: global install from npm
23
23
 
24
- For this pre-release, install the current public repository directly:
24
+ Install the published package:
25
25
 
26
26
  ```bash
27
- npm install -g github:xenstar/browsemux
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 github:xenstar/browsemux
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.0",
4
- "description": "A bounded decision bridge between agent harnesses and browser backends.",
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": {