Skip to content

Self-improving AI Employees for everyone

10.0 KB
Raw Blame
"""WebMCP: the tools a web page offers to agents.

A page registers tools with ``document.modelContext.registerTool(...)``
(on by default in Chrome 150+, secure contexts only). Chrome reports them
over its experimental CDP ``WebMCP`` domain, per page session:

- ``WebMCP.enable`` replays ``toolsAdded`` for tools already registered;
- ``toolsAdded`` / ``toolsRemoved`` carry ``{name, description, inputSchema,
  annotations{readOnly, untrustedContent, consequential}, frameId}``;
- ``invokeTool{frameId, toolName, input}`` answers ``{invocationId}`` and the
  result arrives later as ``toolResponded{invocationId, status, output,
  errorText}``.

Chrome sends no ``toolsRemoved`` when a page navigates away, so a frame's
tools are dropped here on ``Page.frameNavigated``. Chrome does not validate
the input against ``inputSchema`` either. The output is the page's words, so
it is returned marked untrusted and capped.
"""

from __future__ import annotations

import asyncio
import json
from typing import Any, Dict, List, Optional

from core.logging import get_logger
from services.plugin.base import NodeUserError

from ._cdp import CDPError, CDPSession

logger = get_logger(__name__)

OUTPUT_LIMIT_BYTES = 32 * 1024
INVOKE_TIMEOUT = 60.0


class WebMcpOutcomeUnknown(NodeUserError):
    """The invocation may have taken effect even though its reply was lost."""


def _cap(value: Any) -> tuple[Any, bool]:
    text = value if isinstance(value, str) else json.dumps(value, default=str, ensure_ascii=False)
    if len(text.encode("utf-8")) <= OUTPUT_LIMIT_BYTES:
        return value, False
    clipped = text.encode("utf-8")[:OUTPUT_LIMIT_BYTES].decode("utf-8", errors="ignore")
    return clipped + " ... [truncated]", True


class WebMcpTracker:
    """Tools per page target, kept current from CDP events."""

    def __init__(self) -> None:
        #: target_id -> frame_id -> tool name -> tool
        self._tools: Dict[str, Dict[str, Dict[str, Dict[str, Any]]]] = {}
        self._main_frames: Dict[str, str] = {}
        self._sessions: Dict[str, CDPSession] = {}
        self._pending: Dict[str, asyncio.Future] = {}
        self._early: Dict[str, Dict[str, Any]] = {}
        self._sensitive = False

    # -- wiring ---------------------------------------------------------------

    async def attach(self, target_id: str, session: CDPSession) -> None:
        """Start tracking a page (called on every auto-attached page session)."""
        self._sessions[target_id] = session
        session.on("WebMCP.toolsAdded", lambda p: self._added(target_id, p))
        session.on("WebMCP.toolsRemoved", lambda p: self._removed(target_id, p))
        session.on("WebMCP.toolResponded", self._responded)
        session.on("Page.frameNavigated", lambda p: self._navigated(target_id, p))
        if self._sensitive:
            return
        try:
            await session.send("WebMCP.enable", timeout=10)
        except CDPError as exc:
            if not exc.method_not_found:
                logger.debug("[browser] WebMCP.enable failed on %s: %s", target_id, exc)

    async def sensitive_barrier(self, enabled: bool) -> None:
        """Disable page-provided metadata before credential values are fetched."""
        self._sensitive = enabled
        self._tools.clear()
        self._early.clear()
        for session in list(self._sessions.values()):
            try:
                await session.send("WebMCP.disable" if enabled else "WebMCP.enable", timeout=5)
            except CDPError as exc:
                if not exc.method_not_found:
                    raise RuntimeError("WebMCP suspension could not be confirmed") from None

    def detach(self, target_id: str) -> None:
        self._sessions.pop(target_id, None)
        self._tools.pop(target_id, None)
        self._main_frames.pop(target_id, None)

    def _added(self, target_id: str, params: Dict[str, Any]) -> None:
        if self._sensitive:
            return
        frames = self._tools.setdefault(target_id, {})
        for tool in params.get("tools") or []:
            name, frame = tool.get("name"), tool.get("frameId")
            if name and frame:
                frames.setdefault(frame, {})[name] = tool

    def _removed(self, target_id: str, params: Dict[str, Any]) -> None:
        frames = self._tools.get(target_id, {})
        for tool in params.get("tools") or []:
            frames.get(tool.get("frameId"), {}).pop(tool.get("name"), None)

    def _navigated(self, target_id: str, params: Dict[str, Any]) -> None:
        frame = params.get("frame") or {}
        frame_id = frame.get("id")
        if not frame_id:
            return
        if not frame.get("parentId"):
            # The page navigated: every frame's registrations are gone.
            self._main_frames[target_id] = frame_id
            self._tools[target_id] = {}
        else:
            self._tools.get(target_id, {}).pop(frame_id, None)

    def _responded(self, params: Dict[str, Any]) -> None:
        if self._sensitive:
            return
        invocation = params.get("invocationId") or ""
        future = self._pending.get(invocation)
        if future is not None:
            if not future.done():
                future.set_result(params)
            return
        # The reply to invokeTool arrives first, but the event can be read
        # before invoke() gets to register for it; keep it briefly.
        self._early[invocation] = params
        while len(self._early) > 64:
            self._early.pop(next(iter(self._early)))

    # -- queries -------------------------------------------------------------

    def tools(self, target_id: Optional[str]) -> List[Dict[str, Any]]:
        """The page's tools, shaped for the agent (no stack traces or node ids)."""
        if self._sensitive or not target_id:
            return []
        out = []
        main = self._main_frames.get(target_id)
        for frame_id, tools in self._tools.get(target_id, {}).items():
            for tool in tools.values():
                annotations = tool.get("annotations") or {}
                out.append(
                    {
                        "name": tool.get("name"),
                        "description": tool.get("description") or "",
                        "input_schema": tool.get("inputSchema") or {"type": "object"},
                        "read_only": bool(annotations.get("readOnly")),
                        "consequential": bool(annotations.get("consequential")),
                        "untrusted_output": bool(annotations.get("untrustedContent")),
                        "frame_id": frame_id,
                        "main_frame": frame_id == main,
                    }
                )
        return sorted(out, key=lambda t: (not t["main_frame"], t["name"]))

    def count(self, target_id: Optional[str]) -> int:
        return len(self.tools(target_id))

    async def invoke(
        self,
        target_id: Optional[str],
        name: str,
        tool_input: Dict[str, Any],
        *,
        frame_id: Optional[str] = None,
        mode: str = "read_only",
        timeout: float = INVOKE_TIMEOUT,
    ) -> Dict[str, Any]:
        if self._sensitive:
            raise NodeUserError("Browser observations are paused during protected login.")
        if mode == "disabled":
            raise NodeUserError("WebMCP tools are turned off for this Browser node.")
        session = self._sessions.get(target_id or "")
        if session is None:
            raise NodeUserError("No page is open; navigate first.")
        matches = [t for t in self.tools(target_id) if t["name"] == name and (frame_id is None or t["frame_id"] == frame_id)]
        if not matches:
            raise NodeUserError(f"This page has no WebMCP tool named {name!r}. Call webmcp_list to see what it offers.")
        if len(matches) > 1:
            raise NodeUserError(f"Several frames offer {name!r}; pass frame_id (see webmcp_list).")
        tool = matches[0]
        if mode == "read_only" and not tool["read_only"]:
            raise NodeUserError(
                f"{name!r} can change things on the site, and this Browser node only allows read-only WebMCP tools. "
                "Do the step through the page instead, or ask the owner (request_user)."
            )
        if not isinstance(tool_input, dict):
            raise NodeUserError("WebMCP tool input must be a JSON object.")

        started = asyncio.get_running_loop().time()
        try:
            result = await session.send(
                "WebMCP.invokeTool", {"frameId": tool["frame_id"], "toolName": name, "input": tool_input}, timeout=min(15, timeout)
            )
        except (TimeoutError, ConnectionError) as exc:
            raise WebMcpOutcomeUnknown("The page tool may have started, but its reply was lost. Inspect the page before another action.") from exc
        invocation = result.get("invocationId") or ""
        future = asyncio.get_running_loop().create_future()
        early = self._early.pop(invocation, None)
        if early is not None:
            future.set_result(early)
        self._pending[invocation] = future
        try:
            response = await asyncio.wait_for(future, timeout=max(0.0, timeout - (asyncio.get_running_loop().time() - started)))
        except asyncio.TimeoutError:
            try:
                await session.send("WebMCP.cancelInvocation", {"invocationId": invocation}, timeout=5)
            except Exception:  # noqa: BLE001
                pass
            raise WebMcpOutcomeUnknown(f"The page's {name!r} tool did not answer within {int(timeout)} s. Its action may already have happened.") from None
        finally:
            self._pending.pop(invocation, None)

        status = response.get("status")
        if status == "Completed":
            output, truncated = _cap(response.get("output"))
            return {"status": "completed", "output": output, "truncated": truncated, "untrusted": True, "tool": name}
        detail = response.get("errorText") or ((response.get("exception") or {}).get("description")) or status
        return {"status": (status or "error").lower(), "error": str(detail)[:1000], "untrusted": True, "tool": name}


__all__ = ["OUTPUT_LIMIT_BYTES", "WebMcpTracker"]