smooth-operator-mcp 3.0.5 → 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/harnesses.md

@@ -56,6 +56,13 @@ npm install -g .
 smooth-operator install --help
 ```
 
+After installation, restart the harness and confirm the 64-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
+by default; set `SMOOTH_OPERATOR_BROWSER_IDLE_TIMEOUT_MS` only when an
+inactive browser should be closed automatically while retaining its profile.
+
 The supported targets are `claude-code`, `opencode`, `copilot`, `codex`,
 `gemini`, `vscode`, `cursor`, `windsurf`, and `claude-desktop`. Aliases such as
 `claude`, `github-copilot`, `codex-cli`, `gemini-cli`, and `vs-code` are also

package/docs/mcp-server.md

@@ -196,6 +196,14 @@ navigation policy guard is installed; targets whose attachment ownership
 cannot be determined are blocked or closed. These controls reduce races but do
 not make a host browser or network firewall trustworthy by themselves.
 
+Managed startup preflights a regular executable when it needs to launch, and
+launch startup performs the same check before invoking Chromium. Both wait for
+browser launch readiness before returning a connection. The loopback
+`/json/version` probe reads at most 64 KiB, including streamed-byte enforcement
+before JSON parsing. Target auto-attach readiness is acknowledged before a
+browser connection is returned; unsupported connections retain the safe
+unavailable behavior.
+
 Managed and launch modes create owner-only data, files, downloads, and browser
 profile directories below `SMOOTH_OPERATOR_DATA_DIR` (unless an explicit profile
 path is supplied), reject unsafe symlink components, and hold a profile lease
@@ -307,6 +315,7 @@ variables include:
 | `SMOOTH_OPERATOR_BROWSER_TIMEOUT_MS` | `15000` | Per-action deadline |
 | `SMOOTH_OPERATOR_BROWSER_CONNECT_TIMEOUT_MS` | `30000` | Browser connection deadline |
 | `SMOOTH_OPERATOR_BROWSER_CDP_TIMEOUT_MS` | `30000` | DevTools command deadline |
+| `SMOOTH_OPERATOR_BROWSER_IDLE_TIMEOUT_MS` | `0` | Idle browser cleanup in milliseconds; `0` disables it, maximum 24 hours |
 | `SMOOTH_OPERATOR_MAX_SCREENSHOT_BYTES` | `8000000` | Screenshot byte cap |
 | `SMOOTH_OPERATOR_MAX_HTML_CHARS` | `200000` | HTML output cap |
 | `SMOOTH_OPERATOR_ALLOWED_DOMAINS` | unset | Comma-separated allowlist |
@@ -328,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
@@ -359,9 +376,16 @@ are always applied, with explicit opt-ins where documented:
   the same policy checks; `about:blank` is allowed, data/blob URLs are limited
   to non-frame subresources, and file, browser-internal, extension, and
   unknown schemes are rejected.
+- Resource blocking is page-scoped and limited to image, stylesheet, font,
+  media, and script subresources. Document and navigation requests cannot be
+  selected; matching requests are aborted once without a navigation error, and
+  non-blocked requests still receive the full URL policy check.
 - Upload and PDF destinations must stay within configured directory roots after
   realpath and symlink checks; an existing regular file cannot be configured as
-  a root. Download paths and generated files are bounded.
+  a root. Upload staging accepts at most 20 files, caps each file at 50 MiB and
+  the aggregate at 100 MiB, requires `multiple` on the target input for more
+  than one file, and removes staged files on success and every failure path.
+  Download paths and generated files are bounded.
 - Page JavaScript is available in the native profile by default and can be
   disabled with `SMOOTH_OPERATOR_ALLOW_EVAL=false`; when enabled, page code can
   observe and mutate page state with the browser's privileges.
@@ -381,7 +405,7 @@ for confirming destructive calls.
 
 ### Tools
 
-The registry includes these groups of tools. Every input is schema-validated;
+The registry exposes 64 public tools in these groups. Every input is schema-validated;
 individual descriptions and limits are returned by `tools/list`.
 
 **Observation and extraction:** `browser_snapshot`, `browser_tabs`,
@@ -390,7 +414,8 @@ individual descriptions and limits are returned by `tools/list`.
 `browser_accessibility_snapshot`, `browser_extract`, `browser_extract_content`,
 `browser_find_text`, `browser_search_page`, `browser_find_elements`,
 `browser_dropdown_options`, `browser_computed_style`, `browser_page_next`,
-`browser_get_html`, `browser_challenge`, `browser_doctor`, and `server_health`.
+`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`,
@@ -402,19 +427,30 @@ individual descriptions and limits are returned by `tools/list`.
 
 **Available local capabilities:** `browser_screenshot`, `browser_pdf`,
 `browser_upload`, `browser_downloads`, `browser_network_log`,
-`browser_console_log`, `browser_dialog`, `browser_cookies`, `browser_storage`,
+`browser_search_network_log`, `browser_resource_blocking`, `browser_console_log`,
+`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_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`.
 
+`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. `browser_wait_for_human` pauses for an operator to complete a
+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
@@ -431,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
@@ -445,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
@@ -461,6 +519,38 @@ 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.
 
+### 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
+bodies, and response bodies are not returned; search terms and URLs are treated
+as untrusted data and secret query values are redacted.
+
+`browser_resource_blocking` is page-scoped with strict `get`, `set`, and
+`clear` operations. Its only selectable types are `image`, `stylesheet`,
+`font`, `media`, and `script`; `set` requires a non-empty de-duplicated list.
+Only matching subresources are aborted once. Document and navigation requests
+cannot be selected, data/blob subresources remain covered by the normal rules,
+and non-blocked requests still run the full URL policy.
+
+`browser_inspect_element` returns a bounded safe view of a selected element:
+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,
+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
+removed on success, validation failure, target failure, cancellation, or upload
+rejection.
+
+`browser_cookies` scopes reads, writes, and deletes to a validated page URL.
+Writes accept only the `Strict`, `Lax`, or `None` SameSite values, and cookie
+values are omitted from read results.
+
 ### Resources
 
 The server publishes read-only resources:
@@ -476,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
 
@@ -494,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.5",
+  "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"
@@ -25,12 +26,15 @@
     "dev": "tsx watch src/server/main.ts",
     "build": "node scripts/build.mjs",
     "postbuild": "node scripts/set-executable.mjs dist/smooth-operator.mjs",
-    "lint": "eslint .",
+    "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",
@@ -41,11 +45,11 @@
     "prepare": "npm run build"
   },
   "dependencies": {
-    "@modelcontextprotocol/node": "^2.0.0",
-    "@modelcontextprotocol/server": "^2.0.0",
-    "ghost-cursor": "^1.4.2",
-    "puppeteer-core": "^25.9.0",
-    "zod": "^4.4.3"
+    "@modelcontextprotocol/node": "2.0.0",
+    "@modelcontextprotocol/server": "2.0.0",
+    "ghost-cursor": "1.4.2",
+    "puppeteer-core": "25.10.0",
+    "zod": "4.5.4"
   },
   "devDependencies": {
     "@modelcontextprotocol/client": "^2.0.0",
@@ -60,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"