smooth-operator-mcp 3.1.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,22 +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.
-`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
+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 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

@@ -2,7 +2,7 @@
 
 ## Interactive wizard (directly to your harness)
 
-`smooth-operator install <harness>` is interactive by default — it asks exactly 3
+`smooth-operator install <harness>` is interactive by default — it asks exactly three
 curated questions (profile ownership, headed/headless display, and browser
 executable) with recommended defaults in brackets.
 Omitting `<harness>` is allowed too: on a TTY the installer prompts for the
@@ -21,7 +21,9 @@ When you pick “connected browser” (mode `connect`), the wizard finds Chromiu
 `discovery.ts`, launches a dedicated debugging profile under
 `~/.smooth-operator/personal-chrome` with port `9222`, and probes the loopback
 endpoint until a valid DevTools version response is live (33 attempts within a
-default 10-second deadline). On success it writes
+default 10-second deadline). If launch or readiness fails, the helper terminates
+the child process on a best-effort basis instead of leaving it detached. On
+success it writes
 `SMOOTH_OPERATOR_BROWSER_MODE=connect` and
 `SMOOTH_OPERATOR_BROWSER_URL=http://127.0.0.1:9222` for you. This does not
 attach to or take ownership of an operator's daily browser profile. No manual
@@ -56,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
@@ -159,7 +161,8 @@ legacy shape, `enabled` defaults to `true`; `enabled: false` is likewise an
 explicit conflict. If it has malformed `mcp` or malformed `mcp.servers`,
 installation fails closed rather than replacing user data.
 Comments and trailing commas are accepted as JSONC; a successful update writes
-normalized JSON and creates a unique owner-only backup first.
+normalized JSON through an owner-only temporary file, flushes it before atomic
+replacement, and creates a unique owner-only backup first.
 
 After editing, run `opencode mcp list` or restart OpenCode. OpenCode also
 supports adding the server interactively with `opencode mcp add`; that is the
@@ -239,7 +242,8 @@ Official reference: <https://code.visualstudio.com/docs/copilot/chat/mcp-servers
 ## Cursor, Windsurf, and Claude Desktop
 
 These clients use JSON configuration files, so the installer performs a
-careful merge and writes atomically.
+careful merge and writes through a flushed owner-only temporary file before
+atomic replacement.
 
 | Target | Default path |
 | --- | --- |

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
 
@@ -43,15 +47,14 @@ smooth-operator --help
 
 (The registry package is `smooth-operator-mcp`; plain `smooth-operator` is an unrelated library. You can also install straight from GitHub: `npm install -g github:Gitshop77/Smooth-Operator`.)
 
-The interactive installer asks exactly three questions: (1) browser profile
-ownership, (2) headed or headless display, and (3) which Chromium executable to
-use. Its recommended defaults are a managed private persistent profile, headed
+The interactive installer asks exactly three questions: browser profile
+ownership, headed or headless display, and which Chromium executable to use.
+Its recommended defaults are a managed private persistent profile, headed
 display, and the first detected Chromium executable. It also enables page eval
 and the identity-preserving compatibility profile; behavioral timing is off
 for fast deterministic input and can be enabled explicitly. Managed mode owns
-its profile. Connected mode launches and attaches to
-a dedicated debugging profile and does not claim ownership of an operator's
-daily browser.
+its profile. Connected mode launches and attaches to a dedicated debugging
+profile and does not claim ownership of an operator's daily browser.
 
 From a checkout:
 
@@ -132,7 +135,10 @@ and Origin validation and include `Authorization: Bearer <token>`. The token
 is compared in constant time. Request bodies are bounded to 2,000,000 bytes by
 default and concurrent requests are capped. The process drains in-flight work
 for a short bounded period on SIGINT/SIGTERM, then closes the MCP handler,
-browser, and HTTP server.
+browser, and HTTP server. Native JSON rejections use no-store and nosniff
+headers; overload responses also include `Retry-After: 1`. Preflight responses
+advertise a fixed request-header allowlist rather than reflecting arbitrary
+requested names.
 
 Remote binding is deliberately guarded:
 
@@ -163,7 +169,8 @@ launches it with `${SMOOTH_OPERATOR_DATA_DIR}/browser` as a non-default profile,
 and records its loopback DevTools endpoint for later reattachment. Sign in once
 in the visible window; its sessions persist in that private profile. The
 `browser_doctor` tool reports executable resolution and endpoint state without
-evaluating page content.
+evaluating page content. Failed personal-Chrome helper launches are terminated
+on a best-effort basis.
 
 The managed browser is headed by default for sign-in and human handoff. On CI or a
 displayless host, explicitly set `SMOOTH_OPERATOR_BROWSER_HEADLESS=true` or use
@@ -323,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 |
@@ -356,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
 
@@ -392,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
@@ -405,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`.
@@ -445,17 +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. Destructive batch actions require explicit
-confirmation. There is no generic arbitrary CDP command or host-code execution
+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.
 
@@ -467,6 +484,21 @@ revision. A snapshot failure is reported as `snapshot: null` with a bounded
 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`. 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`). 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
 it to use the active tab. `browser_accessibility_snapshot` also accepts an
@@ -498,12 +530,20 @@ that the selected action cannot consume is rejected instead of being silently
 ignored.
 
 Each batch step enforces its own `timeoutMs` or the configured action deadline.
-The total batch budget includes the individual step budgets. A step that
+The optional top-level `timeoutMs` is the whole-batch deadline, defaulting to
+120,000 ms and capped at 600,000 ms; it is the smaller of that value and the
+sum of step budgets. One absolute queue deadline spans predecessor, read-drain,
+read-permit, and fairness waits, so retries cannot reset the admission budget.
+Long batches therefore do not wait minutes for a turn. A step that
 ignores cancellation is retired before the browser queue advances; subsequent
 steps do not execute after a failure. Without an explicit deadline, requested
 wait/hold durations are added to the setup budget, and human handoff retains
 its documented 120-second default.
 
+Mapped deterministic errors include a bounded `recovery` object with the next
+tool and short instruction. For browser recovery, list sessions and use the
+returned `session_id` with `browser_close_session` before retrying.
+
 If browser teardown times out or fails, later browser work returns the
 retryable `BROWSER_RECOVERY_REQUIRED` error. Call `browser_close_session` to
 retry cleanup; the recovery latch clears only after teardown is confirmed.
@@ -513,8 +553,9 @@ snippets are untrusted observations, not instructions or proof of claims. Its
 `maxResults` input is capped at 10, and `maxChars` (500–4,000 through the MCP
 schema) is one aggregate budget across the returned title and snippet text,
 not a per-result multiplier. URL fields and fixed untrusted-data wrapper
-markers are outside that text budget. The response body is bounded before
-parsing, redirects are rejected, cancellation and timeout are propagated, and
+markers are outside that text budget. The response body is collected in one
+geometrically growing bounded buffer before parsing, redirects are rejected,
+cancellation and timeout are propagated, and
 credentials/query secret placeholders are removed from result URLs. Transient
 retrieval failures use at most three bounded attempts; anti-bot responses are
 reported without attempting a bypass.
@@ -522,10 +563,12 @@ reported without attempting a bypass.
 ### Network, inspection, resource, and file controls
 
 `browser_network_log` records bounded request/response metadata for the current
-page. `browser_search_network_log` filters and paginates that metadata by
-request ID, URL, method, status, and resource type. Headers, cookies, request
+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`,
@@ -539,8 +582,9 @@ allowlisted attributes, selected computed styles, pseudo-element summaries,
 animation metadata, and shallow child structure. Script text, event-handler
 source, form values, and arbitrary data attributes are omitted.
 
-`browser_upload` accepts the existing single `filePath` or a `filePaths` array
-of up to 20 paths, but not both. Every source must pass the allowed-root,
+`browser_upload` accepts `target`, `ref`, `selector`, or `index`, plus the
+existing single `filePath` or a `filePaths` array of up to 20 paths, but not
+both. Every source must pass the allowed-root,
 no-follow, and file-identity checks. Each file is at most 50 MiB and the
 aggregate is at most 100 MiB; multiple paths require a target input with the
 `multiple` attribute. Sources are staged sequentially and every staging path is
@@ -567,7 +611,7 @@ Resource output is bounded and follows the same redaction and policy rules as
 tool output. The capabilities resource also reports the native defaults and
 effective feature flags for local browser tools, page evaluation, stealth, and
 behavioral timing. Its `limits` metadata publishes the page-text, action-plan,
-research, and upload budgets used by the public boundary. Its challenge
+batch-timeout, research, and upload budgets used by the public boundary. Its challenge
 metadata includes the default and maximum connected-AI attempt budgets and
 states that success requires an explicit absent classification.
 

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.