smooth-operator-mcp 3.0.6 → 3.2.0

package/README.md

@@ -27,11 +27,24 @@ Or straight from GitHub:
 npm install -g github:Gitshop77/Smooth-Operator && smooth-operator install opencode
 ~~~
 
-The wizard asks exactly 3 focused questions: browser profile ownership, browser display, and the Chromium executable. Run `smooth-operator install` with no harness to pick one interactively (TTY only; piped/CI runs print usage and exit). `--yes` applies the recommended defaults, so give it a target: `smooth-operator install opencode --yes`. Personal Chrome mode launches a dedicated debugging profile on `9222` and derives `browserUrl` automatically. Managed mode owns one private persistent profile; connected mode launches and attaches to a dedicated debugging profile and does not claim ownership of an operator's daily browser.
+The wizard asks exactly three focused questions: browser profile ownership,
+browser display, and the Chromium executable. Run `smooth-operator install`
+without a harness to choose one interactively (TTY only; piped and CI runs
+print usage and exit). `--yes` applies the recommended defaults, so give it a
+target: `smooth-operator install opencode --yes`. Personal Chrome mode launches
+a dedicated debugging profile on port `9222` and derives `browserUrl`
+automatically. Managed mode owns one private persistent profile; connected mode
+launches and attaches to a dedicated debugging profile and does not claim
+ownership of an operator's daily browser.
 
-Requires Node 22.23.2+ and an installed Chromium-based browser. Profile at `~/.smooth-operator/browser` — sign in once.
+SmoothOperator requires Node.js 22.23.2 or newer and an installed
+Chromium-based browser. The default managed profile is
+`~/.smooth-operator/browser`; sign in once and reuse that private profile.
 
-Verify: `smooth-operator --help` and `server_health` / `browser_doctor` appear after restart.
+Verify: `smooth-operator --help` and `server_health` / `browser_doctor` appear after restart. `server_health` reports `ok` when the runtime is ready, `degraded` when browser recovery is required or its managed profile lease is not held, and `shutting_down` during teardown; an idle lazy browser is healthy.
+
+For a local release check, run `npm run verify`; it covers lint, type safety,
+tests, dead-code analysis, and the package smoke test.
 
 ## What it does
 
@@ -53,11 +66,19 @@ Ask: *“Scrape pricing into a table”*, *“Fill this form with ~/resume.pdf
 
 ## How to use
 
-Talk to your harness normally. It can call `browser_navigate` → `browser_snapshot` → `browser_click` and the rest of the MCP surface as needed. For a challenge, `browser_solve_challenge` returns fresh bounded visual/state evidence and an attempt budget; the connected AI keeps using ordinary browser actions and calls it again until the final classification is clear or the budget is exhausted. Human handoff remains available only as an explicit final option.
+Talk to your harness normally. The preferred loop is `browser_navigate`/`browser_snapshot` → one mutation → verify. Element actions accept exactly one current `target`, `ref` (`e5`/`ref:e5`), CSS `selector`, or zero-based `index`; refresh these after navigation or DOM changes. Set `includeSnapshot: true` on a mutation to combine the mutation and its trailing verification snapshot. `browser_batch` is useful for short independent sequences; its `timeoutMs` is a whole-batch deadline (120 seconds by default, 600 seconds maximum).
+
+Prefer canonical tools such as `browser_tabs`, `browser_snapshot`, `browser_input`, `browser_back`, `browser_close`, and `browser_extract`. Browser-use compatibility aliases remain available and are labeled as aliases in `tools/list`. Deterministic stale-reference, frame, dialog, element, and browser-recovery errors include a compact recovery tool suggestion.
+
+For a challenge, `browser_solve_challenge` returns fresh bounded visual and
+state evidence with an attempt budget. The connected AI uses ordinary browser
+actions and calls it again until a fresh classification reports the challenge
+absent or the automation budget is exhausted. Human handoff remains available
+only as an explicit final option.
 
 Browser identity remains native, page JavaScript is available by default, and
 behavioral timing is off for fast deterministic input. Set the explicit
-environment flags to change those choices. See `docs/STEALTH-GUIDE.md` for
+environment flags to change those choices. See the [browser compatibility guide](docs/STEALTH-GUIDE.md) for
 details and responsible use.
 
 For the fastest supported operation, keep behavioral timing off with
@@ -80,29 +101,6 @@ evaluation remains an explicit page capability.
 - Reliable — private profiles, stale-reference recovery, reconnect handling, and structured errors
 - Flexible — stdio by default, Streamable HTTP when you need it, plus connect and disabled modes
 
-## Benchmarks
-
-Compared with [Browser Use MCP](https://github.com/browser-use/browser-use) · [![Browser Use GitHub stars](https://img.shields.io/github/stars/browser-use/browser-use?style=social)](https://github.com/browser-use/browser-use) 
-
-Tested: 26 August 2026
-
-| Benchmark | Metric | SmoothOperator | Browser Use MCP |
-| --- | --- | ---: | ---: |
-| Live Web (8 sites, 32 episodes) | URL success | **32/32** | 23/32 |
-| Live Web | Page-text quality | **26/32** | 21/32 |
-| Live Web | Combined success | **26/32** | 18/32 |
-| Live Web | Task latency mean / p95 | **1,358 / 2,957 ms** | 4,604 / 30,780 ms |
-| Live Web | Navigation p95 | **2,130 ms** | 4,320 ms |
-| Live Web | Click p95 | 920 ms | **142 ms** |
-| Live Web | MCP call p95 | **943 ms** | 2,095 ms |
-| Live Web | Trace errors | **0** | 10 |
-| MiniWoB++ 0.14.3 (125 tasks) | Reward = 1 | **124/125** | 89/125 |
-| MiniWoB++ | Attempts | **125** | 125 |
-| MiniWoB++ | MCP errors | **0** | 29 |
-| MiniWoB++ | Transport errors | **0** | **0** |
-| MiniWoB++ | Timeouts | **0** | **0** |
-| Browser Use benchmark | Muse Spark 1.2 · score | **64% · 100 tasks** | 12% · 60 tasks |
-
-*Task counts and scoring rules differ; comparison is directional.*
-
-[View the Browser Use benchmark](https://github.com/browser-use/benchmark)
+For HTTP deployments, the configured MCP path also has a bounded readiness
+endpoint at `<path>/healthz` (normally `/mcp/healthz`), subject to the same
+HTTP authentication policy as the MCP endpoint.