webbrain-one · esokullu · Jul 21, 2026 · Jul 20, 2026 · Jul 20, 2026 · Jul 20, 2026
diff --git a/README.md b/README.md
@@ -49,6 +49,7 @@
 - **Smart Context** — Token-aware auto-compaction (summarizes older turns once the conversation nears the model's context window, with a visible "Context automatically compacted" notice), tool result limits, and emergency overflow recovery
 - **Browser History Control** — Act mode can use native `go_back` / `go_forward` history tools instead of CSP-sensitive page JavaScript
 - **API Shortcut Hints** — Repeated clicks that fire the same XHR/fetch request can surface a matching `fetch_url` suggestion while preserving the UI-first and `/allow-api` mutation policy
+- **WebMCP Fast Path (experimental, opt-in)** — When enabled under Settings → General → Advanced, supporting Chrome pages let Mid/Full and Ask runs discover page-declared structured tools through CDP; Act/Dev can invoke them by opaque ID instead of guessing DOM controls. Catalogs, annotations, and results stay inside the untrusted-page boundary, and every invocation uses the normal permission gate. It is off by default, so normal runs do not receive WebMCP tools or prompt guidance.
 - **On-demand Skills and Skill Tools** — Settings → Skills can import trusted skill text or URLs. Mid/Full runs receive a small eligible ID/name/summary/semantic-intent catalog and load full instructions plus compatible `webbrain-tools` only when relevant; Compact disables skills. FreeSkillz.xyz and the browser-only email verification-code helper are enabled by default, and either can be removed.
 - **Copy Support** — Copy buttons on code blocks and full messages
 - **Page Inspection Banner** — Visual indicator when the agent is interacting with the page
@@ -219,6 +220,8 @@ Legend: **Yes** = available · **-** = not available · **C** = Chrome only · *
 | `get_accessibility_tree` | Yes | Yes | Yes | Yes | - |
 | `read_page` | Yes | Yes | Yes | Yes | - |
 | `read_pdf` | Yes | No | Yes | Yes | - |
+| `list_webmcp_tools` | C | No | C | C | - |
+| `execute_webmcp_tool` | No | No | C | C | - |
 | `read_page_source` | No | No | No | No | Yes |
 | `get_window_info` | Yes | Yes | Yes | Yes | - |
 | `get_interactive_elements` | Yes | No | Yes | Yes | - |
@@ -274,6 +277,15 @@ Legend: **Yes** = available · **-** = not available · **C** = Chrome only · *
 | `inspect_event_listeners` | No | No | No | No | C |
 | `highlight_element` | No | No | No | No | C |
 
+The WebMCP rows above apply only when **Experimental WebMCP** is enabled under
+Settings → General → Advanced. The setting is off by default; while off, the
+tools and their prompt guidance are omitted from model requests. WebMCP
+annotations such as `readOnly` are page-authored hints, not a security
+boundary. Every invocation requires Act or Dev, fresh per-call confirmation,
+and the normal capability × registration-frame-origin permission. WebMCP
+currently requires a supporting Chrome build/page configuration; Firefox does
+not expose these tools.
+
 Loaded skills can append additional tool schemas for the current run. For example,
 the bundled FreeSkillz.xyz skill can expose `read_youtube_transcript` for YouTube
 transcripts plus `resolve_public_media` / `download_public_media` for public

diff --git a/docs/architecture.md b/docs/architecture.md
@@ -202,6 +202,7 @@ while (steps < maxSteps) {
 | `navigate`, `new_tab`, `go_back`, `go_forward` | `chrome.tabs` / `browser.tabs` API | Background script |
 | `fetch_url`, `research_url`, `list_downloads`, etc. | `network-tools.js` | Service worker |
 | Enabled skill tools | `skills.js` registry + `executeHttpSkillTool()` | Service worker |
+| `list_webmcp_tools`, `execute_webmcp_tool` | experimental CDP `WebMCP` domain | Chrome service worker + page-registered callback |
 | `done` | agent.js — captures verification screenshot + page state probe | Service worker + CDP |
 | `clarify` | agent.js — pauses for user input | Service worker |
 | `solve_captcha` | captcha-solver.js | Service worker + CapSolver API |
@@ -502,6 +503,26 @@ Wraps `chrome.debugger` API for:
 - **Trusted events** — `Input.dispatchMouseEvent`, `Input.dispatchKeyEvent` (event.isTrusted === true)
 - **Screenshots** — `Page.captureScreenshot` with clip/scale control
 - **DOM queries** — `Runtime.evaluate` for shadow DOM piercing, `DOM.getDocument` for closed roots
+- **WebMCP** — `WebMCP.enable` maintains a bounded live catalog and
+  `WebMCP.invokeTool` executes a page-registered structured capability. WebBrain
+  exposes opaque `wmcp_*` IDs rather than page-controlled names as call handles.
+
+WebMCP is an experimental Chrome-only fast path that is off by default. The
+user must enable **Experimental WebMCP** under Settings → General → Advanced;
+until then, neither WebMCP tool schemas nor WebMCP prompt guidance enter model
+requests. When enabled, `list_webmcp_tools` is
+available in Ask, Act, and Dev; `execute_webmcp_tool` is restricted to Act/Dev
+and every invocation requires fresh confirmation plus permission against the
+registration frame's actual origin. Page-authored annotations such as
+`readOnly` are advisory and never bypass that boundary. Page-provided names,
+descriptions, schemas, frame
+URLs, outputs, and errors are always wrapped as untrusted content. The frame ID
+and effective HTTP(S) security origin are revalidated immediately before
+dispatch, so navigation, opaque sandbox origins, or stale permission metadata
+fail closed. Tool discovery is bounded to 200 registrations and returned in
+pages of at most 25 entries; invocations time out and issue
+`WebMCP.cancelInvocation` when stopped. Turning the setting off removes the
+tools from subsequent model steps and closes every active WebMCP CDP session.
 
 Without CDP (Firefox), all events are synthetic (`el.click()`, `new KeyboardEvent()`).
 

diff --git a/docs/privacy-and-data-flow.md b/docs/privacy-and-data-flow.md
@@ -181,6 +181,22 @@ bodies and response bodies are not captured. The buffer is deleted when the tab
 closes, and no observer data leaves the browser unless a loop warning surfaces
 the URL + method to the active LLM conversation.
 
+### Experimental WebMCP
+
+WebMCP is off by default. A user must enable **Experimental WebMCP** under
+Settings → General → Advanced before WebBrain sends its tool schemas or prompt
+guidance to the configured LLM. On supporting Chrome pages, WebBrain can then
+enable the experimental CDP `WebMCP` domain. Chrome reports the structured tools registered by the current page,
+including their page-supplied name, description, input schema, annotations, and
+registration frame. WebBrain keeps a bounded in-memory per-tab catalog, assigns
+opaque `wmcp_*` IDs, and removes it when the conversation/tab CDP session is
+cleaned up. The catalog is not uploaded separately, but catalog fields and tool
+results enter the ordinary conversation context when the model calls
+`list_webmcp_tools` or `execute_webmcp_tool`, so they are sent to the configured
+LLM provider like other page content. They are always wrapped as untrusted page
+data. Turning the setting off closes active WebMCP sessions. Firefox does not
+support this path.
+
 ---
 
 ## Telemetry / Analytics

diff --git a/docs/prompt-injection-defense.md b/docs/prompt-injection-defense.md
@@ -61,6 +61,9 @@ Treat **all** of the following as attacker-controllable:
   `done` result includes `pageTitle` / `pageState` (dialog titles, live-region
   text). Non-obvious, easy to miss — `done` was mis-classified once for exactly
   this reason.
+- **WebMCP catalogs and results** — page-registered tool names, descriptions,
+  schemas, frame URLs, annotations, outputs, and errors remain attacker-
+  controlled even though Chrome transports them through CDP.
 
 Model-authored text (a tool's own status string, the agent's `summary`) and the
 **user's** messages are trusted. `clarify` answers are also trusted when the

diff --git a/docs/security-model.md b/docs/security-model.md
@@ -110,6 +110,7 @@ The primary threat: a malicious page crafts content that, when read by the agent
 | **Tiered tool exposure** | Provider tiers (`compact | mid | full`) limit the normal browser-agent surface for smaller models. Compact gets the smallest action surface; Mid adds common task tools; Full adds advanced UI/DOM fallbacks. Compact Dev is blocked. |
 | **Plan before Act** | When enabled, action-mode runs first produce a structured plan and wait for side-panel approval before any browser tool executes. Scheduled runs can auto-approve the plan only through scheduler policy. |
 | **Skill import boundary** | Skills can expose read-only HTTP tools and download-job tools through a `webbrain-tools` manifest. Importing or keeping the skill enabled is the trust decision for the declared HTTPS endpoint; declared skill tools use `credentials: "omit"` and should mark third-party results `resultPolicy: "untrusted"`. Download-job skill tools still require an action mode and the normal Downloads permission gate before saving files. |
+| **WebMCP boundary** | Experimental WebMCP is off by default, so its tools and prompt guidance do not enter ordinary model requests unless the user opts in under Settings → General → Advanced. When enabled, Chrome page-registered names, descriptions, schemas, frame URLs, annotations, outputs, and errors are page-controlled and always use the untrusted-content wrapper. Calls use opaque IDs. Ask may list tools but cannot invoke them. Because a callback can run arbitrary page logic, every invocation requires Act/Dev, fresh per-call confirmation, and a permission grant for the actual registration-frame origin; a page-authored `readOnly` hint never bypasses those gates. Missing/opaque frame identity fails closed, and the frame plus effective HTTP(S) security origin are revalidated immediately before dispatch to prevent navigation races from borrowing an old grant. |
 | **`/allow-api`** | A per-conversation `/allow-api` flag that *waives* the permission prompt for write-method network egress (`fetch_url`/`research_url` with POST/PUT/PATCH/DELETE). It does NOT waive GET egress or any other capability. Clears on conversation reset. |
 | **`done()` blocking** | Before accepting completion, the agent probes for open dialogs/forms. If the summary claims "created"/"saved" but a modal is still open, the agent is forced to continue. |
 | **Duplicate-submit guard** | Clicks on submit-like text (create/save/submit/add/post/publish/send/confirm/sign up/log in/pay/checkout/order, etc.) are blocked within a 45-second window per tab+URL (Chrome). |
@@ -173,6 +174,7 @@ Firefox has no CDP (`debugger` permission), so:
 - No trusted events (synthetic `el.click()` only)
 - No full-page screenshots
 - No shadow DOM piercing for closed roots
+- No WebMCP discovery or invocation (the integration uses Chrome's experimental CDP `WebMCP` domain)
 - `execute_js` is a Dev add-on in both builds: Firefox uses its MV2 content-script evaluator, while Chrome uses CDP `Runtime.evaluate`; neither build exposes it in Ask or normal Act
 - Chrome's reversible CSS/element patches are Dev-only and host-permission gated. Console and network diagnostics are Dev-only reads. Event-listener inspection briefly adds and restores an internal target attribute, while element highlighting inserts a temporary overlay; both use the temporary page-modification permission. All page-derived diagnostic results are wrapped as untrusted content. Network headers/bodies are excluded by default and sensitive header names are always redacted before buffering
 - No offscreen document (CORS must be handled by LLM servers)