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 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.
@@ -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
- # Temporary Holding Version
1
+ <div align="center">
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ # 🧭 Browsemux
4
+
5
+ **Route browser decisions. Keep deterministic control.**
6
+
7
+ A bounded decision bridge between agent harnesses and browser backends.
8
+
9
+ [![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)
10
+ [![License](https://img.shields.io/github/license/xenstar/browsemux?style=flat-square&labelColor=black)](LICENSE)
11
+ [![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)
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
+ [![Contributors](https://contrib.rocks/image?repo=xenstar/browsemux)](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.