smooth-operator-mcp 3.2.0 → 3.3.0

package/docs/STEALTH-GUIDE.md

@@ -10,28 +10,33 @@ deterministic input.
 
 The installer asks exactly three questions: browser profile ownership, browser
 display, and the Chromium executable. Managed mode owns one private persistent
-profile below `SMOOTH_OPERATOR_DATA_DIR`; connected mode launches and attaches
-to a dedicated debugging profile and does not claim ownership of an operator's
-daily browser. A profile is not a privacy boundary from the websites it visits,
-so use a dedicated profile and the narrowest policy that fits the task.
+profile below `SMOOTH_OPERATOR_DATA_DIR`. Wizard Personal Chrome launches a
+dedicated debugging profile and does not take over daily Chrome. A profile is
+not a privacy boundary from the websites it visits, so use a dedicated profile
+and the narrowest policy that fits the task.
 
 ## Optional controls
 
-`SMOOTH_OPERATOR_STEALTH_ENABLED=true` is retained as a compatibility setting.
-It applies only an explicitly configured viewport and never hides automation
-signals or fabricates a user agent, platform, browser version, language, client
-hints, WebGL, canvas, TLS, or operating-system identity. Set it to `false` to
-skip that viewport script entirely.
+`SMOOTH_OPERATOR_STEALTH_ENABLED=true` is retained as a compatibility label.
+It does not hide automation signals, inject a page script, or fabricate a user
+agent, platform, browser version, language, client hints, WebGL, canvas, TLS,
+or operating-system identity. An explicit viewport is applied through launch
+`--window-size` and `page.setViewport`, independent of this flag.
 
 `SMOOTH_OPERATOR_STEALTH_PROFILE=balanced` or `max` are accepted compatibility
-labels for the same supported patch set. `SMOOTH_OPERATOR_STEALTH_GPU=true`
+labels with no patch-set difference. `SMOOTH_OPERATOR_STEALTH_GPU=true`
 adds GPU launch flags but is not an identity or coherence guarantee.
 
-`SMOOTH_OPERATOR_BEHAVIOR_ENABLED` controls optional pointer, typing, and
-scrolling timing wrappers. It defaults off for the fastest raw interaction
+`SMOOTH_OPERATOR_BEHAVIOR_ENABLED` controls optional pointer and typing
+timing wrappers. It defaults off for the fastest raw interaction
 path. If enabled, timings are short, bounded, and cancellable; this is a
 workflow choice, not a guarantee of human identity or site access.
 
+Connect mode attaches to the configured `browserURL` / `wsEndpoint`. The
+installer Personal Chrome helper uses a dedicated debugging profile
+(`~/.smooth-operator/personal-chrome`) and does not take over daily Chrome.
+Advanced `chrome://inspect` attach is documented in `mcp-server.md`.
+
 ## Bounded browser controls
 
 `SMOOTH_OPERATOR_BROWSER_IDLE_TIMEOUT_MS` is disabled by default (`0`). When
@@ -51,24 +56,27 @@ are never captured by that journal.
 animations, safe attributes, and shallow structure. It omits scripts, event
 handler source, form values, password content, and arbitrary data attributes.
 
-## Connected-AI challenge loop
+## Connected-harness challenge loop
 
 `browser_challenge` is an evidence-only detector and is available by default.
 Title, text, HTML, frame-source, and visible-marker inputs have independent
 limits so one oversized evidence category cannot hide later challenge markers.
-`browser_solve_challenge` is an internal connected-AI loop: each call is one
-bounded verification cycle. It collects a fresh challenge classification and
-bounded visual/state evidence, including `attemptsRemaining`; the connected AI
-uses normal browser actions and calls it again until the final classification
-explicitly reports the challenge absent or `automation_exhausted`. The tool
-returns screenshot data as MCP image content when requested. `present`,
-`unknown`, or a failed probe is never success, and human handoff is only an
+`browser_solve_challenge` is one evidence cycle for the connected harness.
+Each call collects a fresh challenge classification and bounded visual/state
+evidence, including `attemptsRemaining`. The connected harness uses normal
+browser actions and calls it again until the final classification explicitly
+reports the challenge absent or `automation_exhausted`. The tool returns
+screenshot data as MCP image content when requested. `present`, `unknown`,
+or a failed probe is never success, and `browser_wait_for_human` is only an
 explicit option after exhaustion.
 
 `browser_wait_for_human` is an optional handoff for a person to complete a
 visible challenge or sign-in step. It does not claim success without a fresh
 final classification. The server does not rotate identities or open network,
-file, or authentication permissions for challenge handling.
+file, or authentication permissions for challenge handling. Launch args stay
+native-identity: they do not set `navigator.webdriver` to false, invent
+UA/platform/client-hint/WebGL/canvas strings, or advertise `HeadlessChrome` on
+the headed path.
 
 ## Boundaries and responsible use
 

package/docs/architecture.md

@@ -0,0 +1,64 @@
+# Architecture
+
+SmoothOperator is a standalone Node.js MCP browser server. The harness reasons.
+The server validates, enforces policy twice, drives one Chromium profile, and
+returns a bounded result envelope. There is no model SDK, planner loop,
+packaged browser add-on, or arbitrary CDP/host-code tool.
+
+```text
+MCP client
+  ├─ stdio, or Streamable HTTP (`/mcp`) + sibling `/healthz`
+  └─ MCP registry (one catalog → tools, resources, prompts)
+       └─ ServerRuntime
+            ├─ SecurityPolicy   (edge + service, same implementation)
+            ├─ BrowserService   (exclusive queue + Puppeteer/CDP)
+            ├─ ResearchService  (bounded DuckDuckGo HTML)
+            └─ Logger           (JSON stderr, redacted)
+```
+
+## Module ownership
+
+| Module | Owns |
+|---|---|
+| `src/server/main.ts` | CLI dispatch: `server`, `install`, `doctor` |
+| `src/server/cli.ts` | Help, version, doctor diagnostics |
+| `src/server/http.ts` | Streamable HTTP, Host/Origin/bearer, `healthz`, shutdown bounds |
+| `src/server/catalog.ts` | Locked 57-tool names, retired-name map, resources, prompts, instructions |
+| `src/server/mcp.ts` | Registration and dispatch from the catalog |
+| `src/server/envelope.ts` | One result envelope: bound, redact, explicit truncation |
+| `src/server/contracts.ts` | Zod schemas shared by tools and `browser_batch` |
+| `src/server/runtime.ts` | Lifecycle, exclusive profile lease, health |
+| `src/server/policy.ts` | URL/DNS/file/eval gates used at the MCP edge and again at the service |
+| `src/server/config.ts` | Env + JSON config, chmod-600 reads |
+| `src/server/browser/service.ts` | Browser facade: execute, snapshot, tabs, doctor, four modes |
+| `src/server/browser/queue.ts` | Exclusive/read lane, absolute queue deadline, abort recovery |
+| `src/server/browser/challenges.ts` | Pure evidence → classification |
+| `src/server/research.ts` | Bounded search, `redirect: "error"`, anti-bot reported not bypassed |
+| `src/server/installer.ts` / `installer-wizard.ts` | Harness install, three-question wizard, atomic config IO |
+| `src/server/errors.ts` / `logger.ts` / `security.ts` | AppError + recovery, JSON logs, untrusted wrappers |
+
+## One of each
+
+- **One catalog** feeds `tools/list` and handlers (`catalog.ts`).
+- **One envelope** serializes success and error (`envelope.ts`). Text fallback equals structured content.
+- **One policy implementation** (`SecurityPolicy`) is applied at the MCP edge (navigate/eval) and again inside `BrowserService` / research.
+- **One exclusive profile lease** (`runtime.ts` lock file) plus one in-process operation queue (`browser/queue.ts`). A timed-out operation recovers the old lifecycle before the next waiter is released.
+
+## Browser modes
+
+| Mode | Process | Profile |
+|---|---|---|
+| `managed` | Launch or reattach via `DevToolsActivePort` | `${DATA_DIR}/browser` |
+| `connect` | Attach to configured `browserURL` / `wsEndpoint` | Wizard Personal Chrome uses `personal-chrome`; `chrome://inspect` daily-profile attach is advanced opt-in (`mcp-server.md`) |
+| `launch` | Launch configured executable | Configured `userDataDir` |
+| `disabled` | None | Browser tools fail `BROWSER_DISABLED`; policy still runs |
+
+## Transports
+
+Stdio is the default. HTTP binds loopback unless `SMOOTH_OPERATOR_ALLOW_REMOTE_HTTP=true` with a 32-character token. `GET/HEAD <path>/healthz` uses the same Host, Origin, and bearer checks as `/mcp` and returns `{ status, ready, server, transport, checks }` without page data.
+
+## Verify
+
+`npm run verify` is lint, typecheck, coverage tests, knip, and package smoke
+(which builds). Coverage and `npm test` pass `--exclude tests/browser-live.test.ts`.
+Live Chrome is only `npm run test:browser:live` (explicit `vitest run tests/browser-live.test.ts`) and is not inside verify.

package/docs/config.md

@@ -0,0 +1,54 @@
+# Configuration
+
+Environment variables or `--config` JSON (`chmod 600`, no symlinks).
+Comma-separated lists reject more than 128 entries before normalization.
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `SMOOTH_OPERATOR_TRANSPORT` | `stdio` | `stdio` or `http` |
+| `SMOOTH_OPERATOR_CONFIG` | auto `~/.smooth-operator/config.json` | Explicit JSON path |
+| `SMOOTH_OPERATOR_DATA_DIR` | `~/.smooth-operator` | Data root |
+| `SMOOTH_OPERATOR_BROWSER_MODE` | `managed` | `managed` / `connect` / `launch` / `disabled` |
+| `SMOOTH_OPERATOR_BROWSER_URL` | `http://127.0.0.1:9222` | DevTools HTTP endpoint |
+| `SMOOTH_OPERATOR_BROWSER_WS_ENDPOINT` | unset | DevTools WebSocket endpoint |
+| `SMOOTH_OPERATOR_BROWSER_EXECUTABLE` | unset | Chromium binary (required for `launch`) |
+| `SMOOTH_OPERATOR_BROWSER_USER_DATA_DIR` | `${DATA_DIR}/browser` | Persistent profile |
+| `SMOOTH_OPERATOR_BROWSER_HEADLESS` | `false` | Headless Chrome |
+| `SMOOTH_OPERATOR_BROWSER_VIEWPORT_WIDTH` / `_HEIGHT` | unset | Set both for an explicit viewport |
+| `SMOOTH_OPERATOR_BROWSER_AUTO_LAUNCH` | `false` | Legacy connect-mode recovery launch |
+| `SMOOTH_OPERATOR_BROWSER_TIMEOUT_MS` | `15000` | Action timeout |
+| `SMOOTH_OPERATOR_BROWSER_CONNECT_TIMEOUT_MS` | `30000` | Connect timeout |
+| `SMOOTH_OPERATOR_BROWSER_CDP_TIMEOUT_MS` | `30000` | CDP timeout |
+| `SMOOTH_OPERATOR_BROWSER_IDLE_TIMEOUT_MS` | `0` | Idle cleanup; `0` disabled, max 24 hours |
+| `SMOOTH_OPERATOR_MAX_SCREENSHOT_BYTES` | `8000000` | Screenshot cap |
+| `SMOOTH_OPERATOR_MAX_HTML_CHARS` | `200000` | HTML cap |
+| `SMOOTH_OPERATOR_ALLOWED_DOMAINS` | unset | Hostname allowlist (`*.` suffix ok) |
+| `SMOOTH_OPERATOR_BLOCKED_DOMAINS` | unset | Hostname denylist |
+| `SMOOTH_OPERATOR_ALLOWED_FILE_ROOTS` | `files`,`downloads` | Upload/PDF roots |
+| `SMOOTH_OPERATOR_ALLOW_PRIVATE_NETWORK` | `false` | Non-loopback private targets |
+| `SMOOTH_OPERATOR_ALLOW_EVAL` | `true` | Page JavaScript |
+| `SMOOTH_OPERATOR_STEALTH_ENABLED` | `true` | Compatibility label; identity stays native |
+| `SMOOTH_OPERATOR_STEALTH_PROFILE` | `balanced` | `balanced` or `max`; no patch-set difference |
+| `SMOOTH_OPERATOR_STEALTH_GPU` | `false` | Opt-in GPU flags |
+| `SMOOTH_OPERATOR_BEHAVIOR_ENABLED` | `false` | Opt-in timing wrappers |
+| `SMOOTH_OPERATOR_HTTP_HOST` | `127.0.0.1` | HTTP bind host |
+| `SMOOTH_OPERATOR_HTTP_PORT` | `3344` | HTTP bind port |
+| `SMOOTH_OPERATOR_HTTP_PATH` | `/mcp` | MCP path; health is `<path>/healthz` |
+| `SMOOTH_OPERATOR_HTTP_TOKEN` | unset | Bearer token |
+| `SMOOTH_OPERATOR_ALLOW_REMOTE_HTTP` | `false` | Non-loopback HTTP |
+| `SMOOTH_OPERATOR_HTTP_MAX_BODY_BYTES` | `2000000` | Body cap |
+| `SMOOTH_OPERATOR_ALLOWED_HOSTS` / `_ORIGINS` | localhost, loopback | HTTP allowlists |
+| `SMOOTH_OPERATOR_LOG_LEVEL` | `info` | `debug` / `info` / `warn` / `error` |
+
+Removed (fail closed if set): `SMOOTH_OPERATOR_BROWSER_PROFILE`,
+`SMOOTH_OPERATOR_BROWSER_STEALTH`, `SMOOTH_OPERATOR_DEFAULT_MODE`,
+`SMOOTH_OPERATOR_BROWSER_USER_AGENT`.
+
+CLI: `smooth-operator [server] [--transport stdio|http] [--config path] [--host host] [--port port]`,
+`smooth-operator install [harness] --yes`, `smooth-operator doctor`.
+
+The wizard asks exactly three questions: browser profile ownership, browser
+display, and the Chromium executable. `--yes` uses managed, headed, eval on,
+native-identity compatibility, and deterministic input.
+
+See `.env.example` for a copy-paste template.

package/docs/harnesses.md

@@ -58,7 +58,7 @@ npm install -g .
 smooth-operator install --help
 ```
 
-After installation, restart the harness and confirm the 64-tool registry is
+After installation, restart the harness and confirm the 57-tool registry is
 visible. `server_health` reports the active capabilities; `browser_doctor`
 reports whether the configured or discovered executable is launch-ready and
 whether a managed DevTools endpoint is live. Optional idle cleanup is disabled

package/docs/mcp-server.md

@@ -25,11 +25,15 @@ MCP client
             └─ Logger and safe error boundary
 ```
 
-`src/server/main.ts` owns transport startup, authentication, signal handling,
-and graceful shutdown. `src/server/mcp.ts` registers the public protocol
-surface. `src/server/runtime.ts` owns dependency lifecycle. Browser operations
-are in `src/server/browser/service.ts`; policy and configuration are in
-`src/server/policy.ts` and `src/server/config.ts`.
+`src/server/main.ts` owns CLI dispatch (`server`, `install`, `doctor`).
+`src/server/http.ts` owns Streamable HTTP, `healthz`, and shutdown bounds.
+`src/server/catalog.ts` is the locked public surface; `src/server/mcp.ts`
+registers it. `src/server/envelope.ts` serializes one result envelope.
+`src/server/runtime.ts` owns dependency lifecycle and the profile lease.
+Browser operations are in `src/server/browser/service.ts` with the exclusive
+queue in `src/server/browser/queue.ts`. Policy and configuration are in
+`src/server/policy.ts` and `src/server/config.ts`. See
+[architecture.md](architecture.md) for the module table.
 
 ## Install and start
 
@@ -326,8 +330,8 @@ variables include:
 | `SMOOTH_OPERATOR_ALLOWED_FILE_ROOTS` | data `files`, `downloads` | Explicit roots replace defaults |
 | `SMOOTH_OPERATOR_ALLOW_PRIVATE_NETWORK` | `false` | Allows non-loopback private targets when true |
 | `SMOOTH_OPERATOR_ALLOW_EVAL` | `true` | Set `false` to disable page JavaScript |
-| `SMOOTH_OPERATOR_STEALTH_ENABLED` | `true` | Native-identity viewport compatibility script |
-| `SMOOTH_OPERATOR_STEALTH_PROFILE` | `balanced` | `balanced` or `max` compatibility label |
+| `SMOOTH_OPERATOR_STEALTH_ENABLED` | `true` | Compatibility label; identity stays native |
+| `SMOOTH_OPERATOR_STEALTH_PROFILE` | `balanced` | `balanced` or `max`; no patch-set difference |
 | `SMOOTH_OPERATOR_STEALTH_GPU` | `false` | Adds opt-in GPU launch flags |
 | `SMOOTH_OPERATOR_BEHAVIOR_ENABLED` | `false` | Opt-in timing wrappers |
 | `SMOOTH_OPERATOR_HTTP_HOST` | `127.0.0.1` | HTTP bind host |
@@ -359,8 +363,9 @@ loop is introduced.
 Raw MCP/tool-call speed is not the main bot-detection vector. Sites can score
 network and browser identity, IP reputation, session history, and interaction
 timing independently. A faster call does not bypass a challenge or make an
-automated session legitimate; use the internal AI workflow or human handoff
-only where the target permits automation.
+automated session legitimate. The connected harness loops
+`browser_solve_challenge` / `browser_wait_for_human` only where the target
+permits automation.
 
 ## Security enforcement layers
 
@@ -395,9 +400,10 @@ are always applied, with explicit opt-ins where documented:
 - Page text, HTML, titles, attributes, search snippets, cookies, and logs are
   treated as untrusted data, normalized, bounded, and redacted before output.
 - Challenge and anti-bot markers are reported from bounded evidence. The server
-  does not rotate identities or silently bypass challenges. The connected-AI
-  challenge loop collects fresh classification and visual/state evidence,
-  allows ordinary browser actions, and verifies with a subsequent call.
+  does not rotate identities or silently bypass challenges. The connected harness
+  loops `browser_solve_challenge` / `browser_wait_for_human`: each solve call
+  collects fresh classification and visual/state evidence, allows ordinary
+  browser actions, and verifies with a subsequent call.
 
 Run the server with a dedicated browser profile and the smallest domain and
 file-root allowlists that fit the task. Browser automation can still perform
@@ -408,32 +414,37 @@ for confirming destructive calls.
 
 ### Tools
 
-The registry exposes 64 public tools in these groups. Every input is schema-validated;
-individual descriptions and limits are returned by `tools/list`.
+The registry exposes 57 public tools in these groups. Every input is schema-validated;
+individual descriptions and limits are returned by `tools/list`. Each listed
+name does one job. Cookies: `get`/`set`/`delete`. Storage and resource-blocking:
+`get`/`set`/`clear`. Network and console logs:
+`enable`/`disable`/`read`/`clear`/`read_and_clear`. Dialogs:
+`get_text`/`accept`/`dismiss`/`send_keys`.
 
 **Observation and extraction:** `browser_snapshot`, `browser_tabs`,
-`browser_list_tabs`, `browser_list_sessions`, `browser_get_state`,
+`browser_list_sessions`,
 `browser_page_info`, `browser_interactive`, `browser_frames`,
-`browser_accessibility_snapshot`, `browser_extract`, `browser_extract_content`,
+`browser_accessibility_snapshot`, `browser_extract`,
 `browser_find_text`, `browser_search_page`, `browser_find_elements`,
 `browser_dropdown_options`, `browser_computed_style`, `browser_page_next`,
 `browser_get_html`, `browser_search_network_log`, `browser_inspect_element`,
 `browser_challenge`, `browser_doctor`, and `server_health`.
 
 **Navigation and interaction:** `browser_navigate`, `browser_back`,
-`browser_go_back`, `browser_forward`, `browser_reload`, `browser_switch_tab`,
+`browser_forward`, `browser_reload`, `browser_switch_tab`,
 `browser_close_tab`, `browser_click`, `browser_input`, `browser_select`,
 `browser_scroll`, `browser_scroll_to_bottom`, `browser_key`,
-`browser_wait`, `browser_wait_for_element`, `browser_wait_for_text`, `browser_wait_for_url`,
-`browser_wait_for_network_idle`, `browser_hover`, `browser_move`, `browser_press_and_hold`,
-`browser_type`, `browser_close`, and `browser_close_all`.
+`browser_wait`, `browser_wait_for_element`, `browser_wait_for_text`,
+`browser_wait_for_url`, `browser_wait_for_network_idle`,
+`browser_hover`, `browser_move`, `browser_press_and_hold`,
+and `browser_close`.
 
 **Available local capabilities:** `browser_screenshot`, `browser_pdf`,
 `browser_upload`, `browser_downloads`, `browser_network_log`,
-`browser_search_network_log`, `browser_resource_blocking`, `browser_console_log`,
+`browser_console_log`, `browser_resource_blocking`,
 `browser_dialog`, `browser_cookies`, `browser_storage`,
-`browser_batch`, `browser_exec`, `browser_wait_for_human`,
-`browser_solve_challenge`, and all other browser tools are available by default.
+`browser_batch`, `browser_solve_challenge`, `browser_wait_for_human`,
+and all other browser tools are available by default.
 `browser_close_session` remains a local lifecycle control and does not change
 browser permissions. Page evaluation is available by default and can be
 disabled explicitly with `SMOOTH_OPERATOR_ALLOW_EVAL=false`.
@@ -448,19 +459,20 @@ acquire a profile lease; the next browser operation retries acquisition.
 `ready` reports readiness based on the runtime's current ownership state.
 
 `browser_evaluate` is page JavaScript and is available by default (set
-`SMOOTH_OPERATOR_ALLOW_EVAL=false` when it is not wanted). `browser_exec`
-accepts only a JSON array of validated browser actions; it is not a shell,
+`SMOOTH_OPERATOR_ALLOW_EVAL=false` when it is not wanted). `browser_batch`
+accepts only a validated array of browser actions; it is not a shell,
 Python, or arbitrary code runner. Its explicit `evaluate` action still follows
-the page-evaluation policy, and its optional `timeoutMs` is the same whole-batch
-deadline as `browser_batch` (120,000 ms default, 600,000 ms maximum).
+the page-evaluation policy, and its optional `timeoutMs` is the whole-batch
+deadline (120,000 ms default, 600,000 ms maximum).
 Destructive batch actions require explicit confirmation. There is no generic
 arbitrary CDP command or host-code execution
 tool. `browser_wait_for_human` pauses for an operator to complete a
-visible sign-in or challenge. `browser_solve_challenge` is an internal
-connected-AI observe/act/verify loop: it returns bounded evidence and is
-successful only when a fresh final classification explicitly reports the
-challenge absent; present and exhausted cycles report the remaining attempt
-budget and `automation_exhausted` is the final non-success state.
+visible sign-in or challenge. The connected harness loops
+`browser_solve_challenge` (one evidence cycle per call) and, after
+exhaustion, `browser_wait_for_human`. Success requires a fresh final
+classification that reports the challenge absent; present and exhausted
+cycles report the remaining attempt budget and `automation_exhausted` is
+the final non-success state.
 `browser_close_session`
 closes the one native browser session by its explicit session identifier.
 
@@ -473,14 +485,19 @@ accepts the same option at the top level and captures only one snapshot after
 the final action.
 
 Element-targeting tools accept exactly one of `target`, `ref` (`e5` or
-`ref:e5`), CSS `selector`, or zero-based `index`, plus the operation fields.
+`ref:e5`), CSS `selector`, or zero-based `index`. They do not take
+`operation`. `browser_click`, `browser_move`, and `browser_press_and_hold`
+also accept `coordinateX`/`coordinateY`; hold also accepts start/end
+coordinates or a path. `browser_challenge` is detect-only; solve is
+`browser_solve_challenge`.
 `browser_select` additionally requires exactly one of `optionValue` or
 `optionValues`; `browser_upload` requires exactly one target form and exactly
 one of `filePath` or `filePaths`. Snapshot refs and indexes are invalidated by
 navigation and DOM-changing actions, so refresh the snapshot before reuse.
 Prefer canonical tools (`browser_tabs`, `browser_snapshot`, `browser_input`,
-`browser_back`, `browser_close`, `browser_extract`); browser-use compatibility
-aliases are retained and labeled in `tools/list`.
+`browser_back`, `browser_close`, `browser_extract`). Compatibility aliases
+and retired `browser_logs` are unlisted catalog maps; `tools/list` is exactly
+the 57 names.
 
 The current-page observation tools `browser_interactive`, `browser_frames`,
 `browser_page_info`, and `browser_challenge` accept an optional `pageId`; omit
@@ -550,7 +567,8 @@ page. `browser_search_network_log` scans once, retains only the requested result
 page, and filters metadata by request ID, URL, method, status, and resource
 type. Headers, cookies, request
 bodies, and response bodies are not returned; search terms and URLs are treated
-as untrusted data and secret query values are redacted.
+as untrusted data and secret query values are redacted. `browser_console_log` is
+the bounded console journal.
 
 `browser_resource_blocking` is page-scoped with strict `get`, `set`, and
 `clear` operations. Its only selectable types are `image`, `stylesheet`,

package/docs/security.md

@@ -0,0 +1,58 @@
+# Security
+
+Fail closed. Bound and redact untrusted page, search, and log data. Dual-enforce
+the same `SecurityPolicy` at the MCP edge and again at the browser/research
+service.
+
+## Network
+
+- HTTP(S) only. Credentials in URLs are rejected. Untrusted URL credentials are redacted in output.
+- Redirects are re-checked with the same policy and fail closed. Research fetch uses `redirect: "error"`.
+- Private, link-local, and multicast addresses are blocked unless `SMOOTH_OPERATOR_ALLOW_PRIVATE_NETWORK=true`. Loopback is allowed.
+- DNS is a best-effort preflight (deny-only cache). The browser resolver is not pinned.
+- Resource blocking is page-scoped to image, stylesheet, font, media, and script. Document/navigation cannot be selected.
+
+## Files
+
+- Allowed roots are canonicalized once. Filesystem-root roots and regular-file roots are rejected.
+- Unresolved symlink escapes fail closed. Blocked-path errors include only configured-root metadata.
+- Uploads: at most 20 files, 50 MiB each, 100 MiB aggregate; every staging path is cleaned on all outcomes. Multiple files require `multiple` on the input.
+- Config files and backups are bounded, owner-only (`chmod 600`), regular, and symlink-safe. Writes use a temp file, flush, then atomic rename.
+
+## Page data
+
+Returned HTML, text, accessibility, inspect, cookies, and storage omit:
+
+- scripts and event-handler attributes
+- form values (including accessibility descendants)
+- cookie values on read
+- secret placeholders, bearer-shaped strings, and secret query keys
+
+Truncation is explicit (`truncated`, `mcpOutputTruncated`, `*Truncated`, omission counts). Silent omission is a bug.
+
+Page evaluation is on by default and gated by `SecurityPolicy.assertEvalAllowed()` at the MCP edge and again in `BrowserService`. There is no generic CDP or host-code tool.
+
+## HTTP
+
+- Loopback bind unless remote HTTP is explicitly enabled.
+- Remote HTTP requires a token of at least 32 printable ASCII characters.
+- Host and Origin are parsed and allowlisted. Bearer comparison is constant-time.
+- `healthz` uses the same Host/Origin/bearer policy as `/mcp`.
+- Bodies are capped (default 2 MiB). Malformed or partial responses close the connection.
+
+## Browser process
+
+- One profile lease (`.smooth-operator-profile.lock`). Concurrent sessions fail with `BROWSER_PROFILE_IN_USE`.
+- Managed and launch require a regular executable, a bounded 64 KiB `/json/version` probe, and target auto-attach acknowledgement.
+- Connect mode attaches to the configured `browserURL` / `wsEndpoint`. The wizard Personal Chrome helper uses `~/.smooth-operator/personal-chrome` and does not take over daily Chrome. Advanced `chrome://inspect` attach to a daily profile is opt-in; see [mcp-server.md](mcp-server.md).
+- After an uncooperative timeout the old lifecycle is retired before the queue advances. A late close cannot release another request's lock.
+
+## Challenges and research
+
+Challenges are classified from independently bounded title, text, HTML, frame, and visible-marker evidence. The connected harness loops `browser_solve_challenge` / `browser_wait_for_human`. Success requires a fresh classification that is explicitly **absent**. There is no solver, token injection, or anti-bot bypass. Identity stays native: launch args do not fabricate UA, platform, WebGL, canvas, client hints, or `navigator.webdriver`.
+
+`web_search` is bounded DuckDuckGo HTML. Anti-bot responses are `SEARCH_BLOCKED`. The server does not complete challenges for the search provider.
+
+## Logs
+
+JSON lines on stderr. Secret keys and values are redacted. Logging failures never change protocol responses.

package/docs/tools.md

@@ -0,0 +1,90 @@
+# Tools, resources, and prompts
+
+The public surface is locked in `src/server/catalog.ts` and
+`tests/contract-snapshot.test.ts`. `tools/list` is 57 one-job tools.
+Compatibility aliases and retired `browser_logs` are unlisted catalog maps.
+
+Operations: cookies `get`/`set`/`delete`; storage and resource-blocking
+`get`/`set`/`clear`; network and console logs
+`enable`/`disable`/`read`/`clear`/`read_and_clear`; dialogs
+`get_text`/`accept`/`dismiss`/`send_keys`. Element tools take exactly one of
+`target`, `ref`, `selector`, or `index` and have no `operation`.
+`browser_click`, `browser_move`, and `browser_press_and_hold` also accept
+`coordinateX`/`coordinateY` (hold also start/end coordinates or a path).
+`browser_challenge` is detect-only; solve is `browser_solve_challenge`.
+
+Canonical tools: `browser_tabs`, `browser_snapshot`, `browser_input`,
+`browser_back`, `browser_close`, `browser_extract`, `browser_wait`,
+`browser_network_log`, `browser_challenge`, `browser_batch`.
+
+## Unlisted catalog maps
+
+Compatibility aliases (`browser_list_tabs`, `browser_get_state`,
+`browser_type`, `browser_extract_content`, `browser_go_back`,
+`browser_close_all`, `browser_exec`) plus retired `browser_logs` are not in
+`tools/list`.
+
+| Unlisted name | Canonical call |
+|---|---|
+| `browser_list_tabs` | `browser_tabs` |
+| `browser_get_state` | `browser_snapshot` |
+| `browser_type` | `browser_input` |
+| `browser_extract_content` | `browser_extract` |
+| `browser_go_back` | `browser_back` |
+| `browser_close_all` | `browser_close` |
+| `browser_exec` | `browser_batch` (`actions` is a validated array, never a shell) |
+| `browser_logs` | `browser_network_log` `{ operation: "read" }` |
+
+## Observation
+
+`browser_snapshot`, `browser_tabs`, `browser_list_sessions`,
+`browser_page_info`, `browser_interactive`, `browser_frames`,
+`browser_accessibility_snapshot`, `browser_extract`,
+`browser_find_text`, `browser_search_page`, `browser_find_elements`,
+`browser_inspect_element`, `browser_dropdown_options`, `browser_computed_style`,
+`browser_page_next`, `browser_get_html`, `browser_search_network_log`,
+`browser_challenge`, `browser_doctor`, `server_health`.
+
+Refs (`e5` / `ref:e5`), indexes, and coordinates are observation-bound. Refresh
+them after navigation or DOM changes. Snapshot refs are page/frame/revision-bound.
+
+## Navigation and interaction
+
+`browser_navigate`, `browser_back`, `browser_forward`,
+`browser_reload`, `browser_switch_tab`, `browser_close_tab`, `browser_click`,
+`browser_input`, `browser_select`, `browser_scroll`, `browser_scroll_to_bottom`,
+`browser_key`, `browser_wait`, `browser_wait_for_element`,
+`browser_wait_for_text`, `browser_wait_for_url`, `browser_wait_for_network_idle`,
+`browser_hover`, `browser_move`, `browser_press_and_hold`, `browser_close`.
+
+Also: `browser_upload`, `browser_screenshot`, `browser_pdf`, `browser_downloads`,
+`browser_evaluate`, `browser_batch`, `browser_dialog`,
+`browser_cookies`, `browser_storage`, `browser_network_log`,
+`browser_console_log`, `browser_resource_blocking`, `browser_solve_challenge`,
+`browser_wait_for_human`, `web_search`, `browser_close_session`.
+
+`includeSnapshot=true` on a mutation returns one trailing snapshot. Destructive
+batches require `confirmDestructive=true`. `browser_batch` accepts validated JSON
+actions only.
+
+## Envelope
+
+Success and error results set `content[0].text` to the JSON of `structuredContent`
+(non-objects wrapped as `{ value }`). Errors are
+`{ ok: false, error: { code, message, retryable, details?, recovery? } }`.
+Truncation flags are explicit. Screenshot bytes travel as MCP image content,
+not inside the JSON record.
+
+## Resources
+
+- `smooth-operator://server/capabilities`
+- `smooth-operator://browser/tabs`
+- `smooth-operator://browser/page/current`
+- `smooth-operator://browser/page/{pageId}`
+- `smooth-operator://browser/downloads`
+- `smooth-operator://browser/logs/network`
+- `smooth-operator://browser/logs/console`
+
+## Prompts
+
+`agent-chrome-setup`, `browser-workflow`, `extract-page`, `research-question`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smooth-operator-mcp",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "type": "module",
   "packageManager": "npm@12.0.2",
   "description": "A lightweight, production-grade MCP server for secure browser automation.",
@@ -14,6 +14,10 @@
     "docs/mcp-server.md",
     "docs/harnesses.md",
     "docs/STEALTH-GUIDE.md",
+    "docs/architecture.md",
+    "docs/security.md",
+    "docs/tools.md",
+    "docs/config.md",
     "README.md",
     "LICENSE",
     ".env.example"
@@ -28,13 +32,13 @@
     "postbuild": "node scripts/set-executable.mjs dist/smooth-operator.mjs",
     "lint": "eslint . --ignore-pattern scripts/benchmark-network-journal.ts",
     "typecheck": "tsc --noEmit",
-    "test": "vitest run",
+    "test": "vitest run --exclude tests/browser-live.test.ts",
     "test:unit": "vitest run --exclude tests/browser-live.test.ts",
     "benchmark:network": "tsx scripts/benchmark-network-journal.ts",
     "test:browser:live": "node scripts/test-browser-live.mjs",
-    "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage",
-    "verify": "npm run lint && npm run typecheck && npm test && npm run dead-code && npm run package:smoke",
+    "test:watch": "vitest --exclude tests/browser-live.test.ts",
+    "test:coverage": "vitest run --coverage --exclude tests/browser-live.test.ts",
+    "verify": "npm run lint && npm run typecheck && npm run test:coverage && npm run dead-code && npm run package:smoke",
     "dead-code": "knip --include files,exports,dependencies,unlisted --no-progress",
     "mcp:stdio": "npm run start -- --transport stdio",
     "mcp:http": "npm run start -- --transport http",
@@ -49,7 +53,7 @@
     "@modelcontextprotocol/server": "2.0.0",
     "ghost-cursor": "1.4.2",
     "puppeteer-core": "25.10.0",
-    "zod": "4.5.4"
+    "zod": "4.6.2"
   },
   "devDependencies": {
     "@modelcontextprotocol/client": "^2.0.0",