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 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.
@@ -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
- # 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
+ ### 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
+ [![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)
13
+ [![License](https://img.shields.io/github/license/xenstar/browsemux?style=flat-square&labelColor=black)](LICENSE)
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/)
15
+ [![Status](https://img.shields.io/badge/status-early%20release-2563eb?style=flat-square&labelColor=black)](#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
+ [![Contributors](https://contrib.rocks/image?repo=xenstar/browsemux)](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.