smooth-operator-mcp 3.0.6 → 3.2.0

package/docs/STEALTH-GUIDE.md

@@ -0,0 +1,86 @@
+# Browser identity, compatibility, and challenge handling
+
+## Defaults
+
+SmoothOperator drives a real Chromium-based browser. The recommended native
+profile is headed, persistent, keeps Chromium's native identity and automation
+signals, and enables page evaluation. All local browser tools are available
+from the first request. Behavioral timing is off by default for fast,
+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.
+
+## 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_PROFILE=balanced` or `max` are accepted compatibility
+labels for the same supported patch set. `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
+path. If enabled, timings are short, bounded, and cancellable; this is a
+workflow choice, not a guarantee of human identity or site access.
+
+## Bounded browser controls
+
+`SMOOTH_OPERATOR_BROWSER_IDLE_TIMEOUT_MS` is disabled by default (`0`). When
+set to a positive value up to 24 hours, an idle browser is closed or detached
+only when no operation, dialog, challenge handoff, target preparation, or
+queued work is active. The private profile lease is retained and the next
+browser request reconnects or relaunches normally.
+
+`browser_resource_blocking` can block only page-scoped image, stylesheet, font,
+media, or script subresources. Document and navigation requests are never
+selectable, and non-blocked requests still pass the normal URL and private
+network policy. `browser_search_network_log` exposes bounded metadata-only
+request/response correlation; headers, cookies, payloads, and response bodies
+are never captured by that journal.
+
+`browser_inspect_element` returns bounded styles, pseudo-element summaries,
+animations, safe attributes, and shallow structure. It omits scripts, event
+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
+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
+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.
+
+## Boundaries and responsible use
+
+- Remote HTTP remains loopback-only unless explicitly enabled and authenticated.
+- Private and link-local network targets remain blocked by default.
+- Host/origin checks, bearer authentication, URL policy, and file-root/symlink
+  checks remain enforced for every request.
+- Uploads remain inside allowed roots, cap each file at 50 MiB and all files at
+  100 MiB, require a `multiple` input for multi-file requests, and clean their
+  staging paths on every outcome.
+- Page text, HTML, screenshots, titles, URLs, and classifications are bounded
+  untrusted evidence, never instructions.
+
+The server does not attempt to conceal automation or guarantee passage of a
+challenge. Use automation only where the target and applicable law permit it.

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
@@ -337,6 +340,14 @@ variables include:
 | `SMOOTH_OPERATOR_ALLOWED_ORIGINS` | `localhost,127.0.0.1,[::1]` | HTTP Origin allowlist |
 | `SMOOTH_OPERATOR_LOG_LEVEL` | `info` | `debug`, `info`, `warn`, or `error` |
 
+Streamable HTTP also exposes a JSON readiness endpoint, subject to the same
+authentication policy, at
+`<SMOOTH_OPERATOR_HTTP_PATH>/healthz` (for the default path:
+`/mcp/healthz`). It returns `200` while `ready` is true and `503` when the
+runtime is degraded or shutting down. It is a transport-level health check,
+not a replacement for the MCP `server_health` tool; it never returns page
+contents or browser credentials.
+
 ### Fast operation mode
 
 The default configuration is a native managed browser with page evaluation
@@ -427,12 +438,23 @@ individual descriptions and limits are returned by `tools/list`.
 browser permissions. Page evaluation is available by default and can be
 disabled explicitly with `SMOOTH_OPERATOR_ALLOW_EVAL=false`.
 
+`server_health` returns a bounded readiness projection in addition to the
+capabilities metadata. `status` is `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. The browser check reports `disabled`,
+`idle`, `connected`, `profile_unavailable`, or `recovery_required`; an idle
+browser is expected because browser startup is lazy. Health checks do not
+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,
 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
@@ -450,6 +472,28 @@ 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
+optional `frameId`, which is useful when the accessible content is inside a
+same-page frame.
+
+Passive text and accessibility observations omit form values and textarea
+defaults, including editable control descendants in the accessibility tree.
+Controls keep their labels, roles, and state so they remain actionable through
+fresh refs. Use the explicit page-evaluation capability when reading a value
+is part of the authorized task.
+
 `browser_extract` returns `offset`, `nextOffset`, `hasMore`, and `revision`.
 Use `browser_page_next` with the returned offset and revision; a stale revision
 returns the retryable `STALE_PAGE_SLICE` error instead of silently overlapping
@@ -464,6 +508,24 @@ network-log, and console-log operations are normalized before validation;
 conflicting alias and canonical fields fail with their action index and field
 names. A failed batch preserves bounded completed results and reports
 `failedIndex`, `failedAction`, and `completedActions`.
+Action-specific fields are also validated after alias normalization; a field
+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 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
@@ -474,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.
@@ -483,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.
 
@@ -500,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
@@ -527,9 +592,10 @@ The server publishes read-only resources:
 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 challenge metadata includes the default and maximum
-connected-AI attempt budgets and states that success requires an explicit
-absent classification.
+behavioral timing. Its `limits` metadata publishes the page-text, action-plan,
+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.
 
 ### Prompts
 
@@ -545,9 +611,10 @@ data directories, constructs the runtime, and registers the MCP surface. The
 browser is connected or launched only when a browser operation requires it.
 
 On SIGINT/SIGTERM, the server stops accepting HTTP requests, waits for active
-requests up to a bounded grace period, closes the MCP transport, closes pages,
-and terminates a browser process that it owns. A browser connected in `connect`
-mode remains under the operator's ownership.
+requests up to a bounded grace period, cancels in-flight research retrieval,
+closes the MCP transport, closes pages, and terminates a browser process that
+it owns. A browser connected in `connect` mode remains under the operator's
+ownership.
 
 To clean up a local installation:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smooth-operator-mcp",
-  "version": "3.0.6",
+  "version": "3.2.0",
   "type": "module",
   "packageManager": "npm@12.0.2",
   "description": "A lightweight, production-grade MCP server for secure browser automation.",
@@ -13,6 +13,7 @@
     "dist",
     "docs/mcp-server.md",
     "docs/harnesses.md",
+    "docs/STEALTH-GUIDE.md",
     "README.md",
     "LICENSE",
     ".env.example"
@@ -28,10 +29,12 @@
     "lint": "eslint . --ignore-pattern scripts/benchmark-network-journal.ts",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
+    "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",
     "dead-code": "knip --include files,exports,dependencies,unlisted --no-progress",
     "mcp:stdio": "npm run start -- --transport stdio",
     "mcp:http": "npm run start -- --transport http",
@@ -45,8 +48,8 @@
     "@modelcontextprotocol/node": "2.0.0",
     "@modelcontextprotocol/server": "2.0.0",
     "ghost-cursor": "1.4.2",
-    "puppeteer-core": "25.9.0",
-    "zod": "4.4.3"
+    "puppeteer-core": "25.10.0",
+    "zod": "4.5.4"
   },
   "devDependencies": {
     "@modelcontextprotocol/client": "^2.0.0",
@@ -61,6 +64,10 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.11"
   },
+  "allowScripts": {
+    "esbuild@0.28.2": true,
+    "fsevents@2.3.3": true
+  },
   "engines": {
     "node": ">=22.23.2",
     "npm": ">=12.0.2"