smooth-operator-mcp 3.1.0 → 3.2.0

package/docs/STEALTH-GUIDE.md

@@ -54,6 +54,8 @@ handler source, form values, password content, and arbitrary data attributes.
 ## Connected-AI 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

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
@@ -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

@@ -43,15 +43,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 +131,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 +165,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
@@ -448,8 +451,10 @@ acquire a profile lease; the next browser operation retries acquisition.
 `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,
 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 same whole-batch
+deadline as `browser_batch` (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
@@ -467,6 +472,16 @@ 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`, plus the operation fields.
+`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`.
+
 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 +513,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 +536,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,8 +546,9 @@ 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.
 
@@ -539,8 +564,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 +593,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smooth-operator-mcp",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "type": "module",
   "packageManager": "npm@12.0.2",
   "description": "A lightweight, production-grade MCP server for secure browser automation.",