smooth-operator-mcp 3.0.6 → 3.1.0

package/docs/STEALTH-GUIDE.md

@@ -0,0 +1,84 @@
+# 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.
+`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/mcp-server.md

@@ -337,6 +337,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,6 +435,15 @@ 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,
@@ -450,6 +467,18 @@ 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.
 
+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 +493,16 @@ 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 total batch budget includes the individual step budgets. 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.
 
 If browser teardown times out or fails, later browser work returns the
 retryable `BROWSER_RECOVERY_REQUIRED` error. Call `browser_close_session` to
@@ -527,9 +566,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,
+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 +585,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.1.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"