gatewaysdk 0.3.2__py3-none-any.whl

gatewaysdk/world_browser.py

@@ -0,0 +1,748 @@
+"""A browser on a world's UI: the computer-use half of a live session.
+
+A world session answers on SURFACES. ``tools`` is always there (the world's
+own operations over the rendezvous). An api-type world may also answer on
+``api`` (the service itself), ``ui`` (its dashboard, over the same state) and
+``browser`` — a headless Chromium the platform runs NEXT TO that UI, which an
+agent drives through Playwright. This module is the Python client for the
+last two:
+
+    with open_session("payments-like", "refund-dispute", surfaces=["ui", "browser"]) as s:
+        s.ready()
+        with s.browser() as b:
+            b.goto()                      # the UI's entry page
+            b.click("text=Refund")
+            png = b.screenshot()
+        cu = s.computer_use_tools()       # the same actions as model tools
+        my_agent(cu.impls, cu.schemas, s.instruction)
+        s.grade()                         # sees what the clicks did
+
+Playwright is an OPTIONAL dependency (``pip install playwright`` and
+``playwright install chromium`` for local mode); a hosted browser needs only
+the ``playwright`` package. Nothing here imports it until a browser is opened,
+so sessions that never touch a UI never pay for it.
+
+MODES. ``hosted`` connects to the session's own browser (``surfaces.browser``
+— a Playwright server the pod exposes over an authenticated websocket).
+``local`` launches Chromium on this machine and points it at ``surfaces.ui``;
+it is what a laptop uses against a hosted twin, and what tests use. ``auto``
+picks hosted when the session has one. Asking for a mode the session cannot
+serve raises :class:`WorldSurfaceUnavailable` — never a silent fallback to a
+different browser than the one the episode will be judged on.
+
+OBSERVABILITY. Every action a :class:`WorldBrowser` takes (goto, click, type,
+press, scroll, back) is reported to the platform as one event — what was done,
+whether it worked, where the page ended up, and a JPEG of the screen after —
+through a :class:`BrowserActionRecorder`. Reporting runs on a background
+thread and never fails the action; the platform renders it as the session's
+browser timeline. Typed text into secret-looking fields is redacted before it
+leaves the process.
+"""
+
+from __future__ import annotations
+
+import base64
+import importlib
+import logging
+import queue
+import re
+import threading
+import time
+import urllib.parse
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any, Callable, Dict, List, Optional, Protocol
+
+from .world_tools import (
+    WorldSessionError,
+    WorldToolkit,
+    WorldToolSpec,
+    schema_from_signature,
+)
+
+DEFAULT_VIEWPORT = {"width": 1280, "height": 800}
+UI_TOKEN_QUERY = "token"
+SETTLE_TIMEOUT_MS = 5_000
+SETTLE_QUIET_MS = 150
+SETTLE_POLL_MS = 25
+SURFACE_KINDS = ("tools", "api", "ui", "browser")
+
+EVENT_BATCH_SIZE = 10
+EVENT_FLUSH_INTERVAL_SEC = 1.0
+EVENT_MAX_RETRIES = 3
+EVENT_SCREENSHOT_QUALITY = 60
+EVENT_MAX_STRING = 500
+
+_SECRET_KEY = re.compile(
+    r"pass(word|wd)?|secret|token|api[-_]?key|authorization|cookie"
+    r"|(^|[-_ #.\[\"'=])(otp|pin|cvv|ssn)([-_ \]\"']|$)",
+    re.IGNORECASE,
+)
+_SECRET_VALUE = re.compile(r"^((sk|pk|ghp|xox[abp])[-_][-_A-Za-z0-9]{8,}|AKIA[0-9A-Z]{12,}|Bearer [-_.A-Za-z0-9]{8,})")
+
+log = logging.getLogger(__name__)
+
+
+class WorldSurfaceUnavailable(WorldSessionError):
+    """The session was not opened with (or the world does not have) this surface."""
+
+    def __init__(self, surface: str, reason: str) -> None:
+        super().__init__(f"World surface '{surface}' is unavailable: {reason}")
+        self.surface = surface
+
+
+@dataclass(frozen=True)
+class ApiSurface:
+    url: str
+    #: Per-session credential of a World Host api surface, presented as
+    #: ``Authorization: Bearer``. ``None`` for a pod or a customer-hosted twin,
+    #: which answer with the world's own declared auth.
+    token: Optional[str] = None
+
+    @property
+    def headers(self) -> Dict[str, str]:
+        """Headers every request to :attr:`url` needs."""
+        return {"Authorization": f"Bearer {self.token}"} if self.token else {}
+
+
+@dataclass(frozen=True)
+class UiSurface:
+    url: str
+    entry: str = "/"
+    #: Same-origin prefix the UI proxies to the world API (``/__world-api``),
+    #: or ``None`` when the UI only talks to the API server-side.
+    api_path: Optional[str] = None
+    #: Per-session credential of a World Host UI. A browser navigation cannot
+    #: carry a header, so the first page load presents it once as ``?token=``
+    #: and the host answers with an HttpOnly cookie. ``None`` for pod UIs.
+    token: Optional[str] = None
+
+    @property
+    def entry_url(self) -> str:
+        return self.url_for(self.entry or "/")
+
+    def url_for(self, path: str) -> str:
+        """The URL of ``path`` on this surface, carrying the session token when
+        there is one. ``path`` may already have a query string."""
+        rel = path if path.startswith("/") else "/" + path
+        full = self.url.rstrip("/") + rel
+        if not self.token:
+            return full
+        before_hash, hash_sep, fragment = full.partition("#")
+        joiner = "&" if "?" in before_hash else "?"
+        query = urllib.parse.urlencode({UI_TOKEN_QUERY: self.token})
+        return before_hash + joiner + query + hash_sep + fragment
+
+    @property
+    def api_url(self) -> Optional[str]:
+        """The API as reachable through the UI's origin, if it proxies one."""
+        if not self.api_path:
+            return None
+        return self.url.rstrip("/") + self.api_path
+
+
+def without_ui_token(url: str) -> str:
+    """``url`` without its ``token`` query parameter: what may be logged."""
+    parts = urllib.parse.urlsplit(url)
+    if not parts.query:
+        return url
+    kept = [(k, v) for k, v in urllib.parse.parse_qsl(parts.query, keep_blank_values=True) if k != UI_TOKEN_QUERY]
+    return urllib.parse.urlunsplit(parts._replace(query=urllib.parse.urlencode(kept)))
+
+
+@dataclass(frozen=True)
+class BrowserSurface:
+    """``protocol`` is ``cdp`` for the platform's Chromium relay (any number of
+    agents share one browser, each in its own context) or ``playwright`` for a
+    ``playwright run-server`` endpoint."""
+
+    ws_url: str
+    protocol: str = "cdp"
+    viewport: Dict[str, int] = field(default_factory=lambda: dict(DEFAULT_VIEWPORT))
+
+
+@dataclass(frozen=True)
+class SessionSurfaces:
+    """Parsed ``surfaces`` from the session descriptor."""
+
+    api: Optional[ApiSurface] = None
+    ui: Optional[UiSurface] = None
+    browser: Optional[BrowserSurface] = None
+
+    @classmethod
+    def from_descriptor(cls, raw: Optional[Dict[str, Any]]) -> "SessionSurfaces":
+        raw = raw or {}
+        api = raw.get("api")
+        ui = raw.get("ui")
+        browser = raw.get("browser")
+        return cls(
+            api=(ApiSurface(url=api["url"], token=api.get("token") or None) if api else None),
+            ui=(
+                UiSurface(
+                    url=ui["url"],
+                    entry=ui.get("entry") or "/",
+                    api_path=ui.get("apiPath") or None,
+                    token=ui.get("token") or None,
+                )
+                if ui
+                else None
+            ),
+            browser=(
+                BrowserSurface(
+                    ws_url=browser["wsUrl"],
+                    protocol=browser.get("protocol") or "cdp",
+                    viewport=dict(browser.get("viewport") or DEFAULT_VIEWPORT),
+                )
+                if browser
+                else None
+            ),
+        )
+
+    @property
+    def kinds(self) -> List[str]:
+        kinds = ["tools"]
+        if self.api is not None:
+            kinds.append("api")
+        if self.ui is not None:
+            kinds.append("ui")
+        if self.browser is not None:
+            kinds.append("browser")
+        return kinds
+
+
+class _Keyboard(Protocol):
+    def press(self, key: str, **kwargs: Any) -> Any: ...
+
+
+class _Mouse(Protocol):
+    def wheel(self, delta_x: float, delta_y: float) -> Any: ...
+
+
+class _Page(Protocol):
+    """The slice of a Playwright ``Page`` this module uses."""
+
+    url: str
+    keyboard: _Keyboard
+    mouse: _Mouse
+
+    def goto(self, url: str, **kwargs: Any) -> Any: ...
+    def click(self, selector: str, **kwargs: Any) -> Any: ...
+    def fill(self, selector: str, value: str, **kwargs: Any) -> Any: ...
+    def screenshot(self, **kwargs: Any) -> bytes: ...
+    def inner_text(self, selector: str, **kwargs: Any) -> str: ...
+    def content(self) -> str: ...
+    def go_back(self, **kwargs: Any) -> Any: ...
+    def wait_for_load_state(self, state: str = "load", **kwargs: Any) -> Any: ...
+    def wait_for_timeout(self, timeout: float) -> Any: ...
+    def title(self) -> str: ...
+    def on(self, event: str, handler: Callable[..., Any]) -> Any: ...
+
+
+# ── action events ────────────────────────────────────────────────────────────────
+
+
+def redact_action_args(action: str, args: Dict[str, Any]) -> Dict[str, Any]:
+    """What of an action's arguments may leave the process. Selectors, paths
+    and keys are what a reviewer needs; anything keyed like a credential, or
+    typed into a field whose selector names one, or shaped like a known key,
+    is replaced. Strings are capped, nested values dropped."""
+    out: Dict[str, Any] = {}
+    secret_field = action == "browser_type" and bool(_SECRET_KEY.search(str(args.get("selector", ""))))
+    for key, value in args.items():
+        if value is None or isinstance(value, (bool, int, float)):
+            out[key] = value
+        elif isinstance(value, str):
+            if _SECRET_KEY.search(key) or _SECRET_VALUE.match(value) or (secret_field and key == "text"):
+                out[key] = "[redacted]"
+            else:
+                out[key] = value if len(value) <= EVENT_MAX_STRING else value[:EVENT_MAX_STRING] + "…"
+        else:
+            out[key] = "[omitted]"
+    return out
+
+
+class BrowserActionRecorder:
+    """Ships browser action events to the platform, off the action's hot path.
+
+    ``post`` receives a batch of wire-shaped events (the body of
+    ``POST /world-sessions/{id}/browser-events``). Events are numbered here,
+    so ordering survives batching and retries — the platform dedups on
+    ``(agentId, seq)``. A batch that keeps failing is dropped with a warning:
+    telemetry must never stall or fail the agent.
+
+    Numbering is durable across recorders: :meth:`next_seq` hands out a
+    position within this recorder, and the first send adds the base
+    ``resume_from`` reports — the platform's next free seq for this agent —
+    so an agent id reopened in a later process appends to its timeline
+    instead of colliding with (and being deduplicated against) what it
+    already recorded. The base is fixed once resolved, which keeps retries
+    idempotent.
+    """
+
+    def __init__(
+        self,
+        post: Callable[[List[Dict[str, Any]]], None],
+        agent_id: str,
+        *,
+        resume_from: Optional[Callable[[], int]] = None,
+        batch_size: int = EVENT_BATCH_SIZE,
+        flush_interval: float = EVENT_FLUSH_INTERVAL_SEC,
+        max_retries: int = EVENT_MAX_RETRIES,
+    ) -> None:
+        self.agent_id = agent_id
+        self._post = post
+        self._resume_from = resume_from
+        self._base: Optional[int] = None
+        self._batch_size = batch_size
+        self._flush_interval = flush_interval
+        self._max_retries = max_retries
+        self._queue: "queue.Queue[Optional[Dict[str, Any]]]" = queue.Queue()
+        self._seq = 0
+        self._pending = 0
+        self._cond = threading.Condition()
+        self.sent = 0
+        self.dropped = 0
+        self._thread = threading.Thread(target=self._run, name="gateway-browser-events", daemon=True)
+        self._thread.start()
+
+    def next_seq(self) -> int:
+        """This recorder's next position; the wire seq is ``resume_from() + this``."""
+        with self._cond:
+            seq = self._seq
+            self._seq += 1
+            return seq
+
+    def _resolve_base(self) -> int:
+        if self._base is None:
+            base = self._resume_from() if self._resume_from is not None else 0
+            if not isinstance(base, int) or isinstance(base, bool) or base < 0:
+                raise ValueError(f"browser event base seq must be a non-negative integer, got {base!r}")
+            self._base = base
+        return self._base
+
+    def record(self, event: Dict[str, Any]) -> None:
+        with self._cond:
+            self._pending += 1
+        self._queue.put(event)
+
+    def flush(self, timeout: float = 15.0) -> bool:
+        """Block until everything recorded so far has been posted (or dropped)."""
+        with self._cond:
+            return self._cond.wait_for(lambda: self._pending == 0, timeout)
+
+    def close(self, timeout: float = 15.0) -> None:
+        self.flush(timeout)
+        self._queue.put(None)
+        self._thread.join(timeout)
+
+    def _run(self) -> None:
+        while True:
+            item = self._queue.get()
+            if item is None:
+                return
+            batch: List[Dict[str, Any]] = [item]
+            deadline = time.monotonic() + self._flush_interval
+            stop = False
+            while len(batch) < self._batch_size:
+                remaining = deadline - time.monotonic()
+                if remaining <= 0:
+                    break
+                try:
+                    item = self._queue.get(timeout=remaining)
+                except queue.Empty:
+                    break
+                if item is None:
+                    stop = True
+                    break
+                batch.append(item)
+            self._send(batch)
+            if stop:
+                return
+
+    def _send(self, batch: List[Dict[str, Any]]) -> None:
+        try:
+            for attempt in range(self._max_retries):
+                try:
+                    base = self._resolve_base()
+                    self._post(batch if base == 0 else [{**e, "seq": base + e["seq"]} for e in batch])
+                    self.sent += len(batch)
+                    return
+                except Exception as exc:  # noqa: BLE001 — telemetry must not raise
+                    if attempt + 1 == self._max_retries:
+                        self.dropped += len(batch)
+                        log.warning("dropping %d browser events after %d attempts: %s", len(batch), attempt + 1, exc)
+                        return
+                    time.sleep(0.5 * (2**attempt))
+        finally:
+            with self._cond:
+                self._pending -= len(batch)
+                self._cond.notify_all()
+
+
+def _playwright_module() -> Any:
+    try:
+        return importlib.import_module("playwright.sync_api")
+    except ImportError as error:  # pragma: no cover - depends on the install
+        raise WorldSessionError(
+            "Driving a world UI needs Playwright: pip install playwright "
+            "(and `playwright install chromium` for local mode)."
+        ) from error
+
+
+class WorldBrowser:
+    """One Playwright page on the session's UI.
+
+    Thin on purpose: the point is to hand the agent the SAME browser the
+    platform records, not to re-invent Playwright. ``page`` is the real
+    Playwright page for anything this wrapper does not cover.
+    """
+
+    def __init__(
+        self,
+        page: _Page,
+        ui: Optional[UiSurface],
+        *,
+        mode: str,
+        close: Callable[[], None],
+        viewport: Optional[Dict[str, int]] = None,
+        recorder: Optional[BrowserActionRecorder] = None,
+    ) -> None:
+        self.page = page
+        self.ui = ui
+        self.mode = mode
+        self.viewport = dict(viewport or DEFAULT_VIEWPORT)
+        self.recorder = recorder
+        self._close = close
+        self._inflight = 0
+        self._last_network = time.monotonic()
+        page.on("request", self._on_request)
+        page.on("requestfinished", self._on_request_done)
+        page.on("requestfailed", self._on_request_done)
+
+    @property
+    def agent_id(self) -> Optional[str]:
+        return self.recorder.agent_id if self.recorder else None
+
+    def _act(self, action: str, args: Dict[str, Any], fn: Callable[[], Any]) -> Any:
+        """Run one action and report it: the event carries what was asked,
+        whether it worked, and the screen after — for failures too, so a
+        reviewer sees what the agent saw when the selector did not match."""
+        if self.recorder is None:
+            return fn()
+        started = time.monotonic()
+        ok, error = True, None
+        try:
+            return fn()
+        except Exception as exc:
+            ok, error = False, f"{type(exc).__name__}: {exc}"[:4000]
+            raise
+        finally:
+            event: Dict[str, Any] = {
+                "agentId": self.recorder.agent_id,
+                "seq": self.recorder.next_seq(),
+                "ts": datetime.now(timezone.utc).isoformat(),
+                "action": action,
+                "args": redact_action_args(action, args),
+                "ok": ok,
+                "error": error,
+                "durationMs": int((time.monotonic() - started) * 1000),
+                "mode": self.mode,
+                "viewport": dict(self.viewport),
+            }
+            event.update(self._observe_for_event())
+            self.recorder.record(event)
+
+    def _observe_for_event(self) -> Dict[str, Any]:
+        out: Dict[str, Any] = {"url": None, "title": None, "screenshot": None}
+        try:
+            out["url"] = self.url
+            out["title"] = self.page.title()
+            jpeg = self.page.screenshot(type="jpeg", quality=EVENT_SCREENSHOT_QUALITY)
+            out["screenshot"] = base64.b64encode(jpeg).decode("ascii")
+        except Exception as exc:  # noqa: BLE001 — a closed page still gets its event
+            log.debug("browser event observation failed: %s", exc)
+        return out
+
+    # ── navigation ─────────────────────────────────────────────────────────
+    def goto(self, path_or_url: Optional[str] = None) -> str:
+        """Open a UI path (``/customers``), a full URL, or — with no argument —
+        the UI's declared entry page."""
+        if path_or_url is None:
+            if self.ui is None:
+                raise WorldSurfaceUnavailable("ui", "this session has no UI to navigate to")
+            target = self.ui.entry_url
+        elif path_or_url.startswith(("http://", "https://")):
+            target = path_or_url
+        else:
+            if self.ui is None:
+                raise WorldSurfaceUnavailable("ui", "relative paths need a UI surface")
+            target = self.ui.url_for(path_or_url)
+
+        def run() -> str:
+            self.page.goto(target, wait_until="load")
+            self._settle()
+            return self.url
+
+        return self._act(
+            "browser_goto",
+            {"path": path_or_url, "url": without_ui_token(target)},
+            run,
+        )
+
+    def back(self) -> str:
+        def run() -> str:
+            self.page.go_back(wait_until="load")
+            self._settle()
+            return self.url
+
+        return self._act("browser_back", {}, run)
+
+    def _on_request(self, _request: Any) -> None:
+        self._inflight += 1
+        self._last_network = time.monotonic()
+
+    def _on_request_done(self, _request: Any) -> None:
+        self._inflight = max(0, self._inflight - 1)
+        self._last_network = time.monotonic()
+
+    def _settle(self) -> None:
+        """Wait for the page to finish reacting to an action.
+
+        ``load`` alone is not enough for client-rendered UIs (React et al.): a
+        click returns before the fetch that re-renders the page, so an agent
+        would read stale text. Playwright's ``networkidle`` is per navigation
+        and resolves at once after the first one, so this tracks requests
+        itself: done when nothing is in flight and the network has been quiet
+        for ``SETTLE_QUIET_MS``, bounded so long-polling UIs cannot hang us.
+        """
+        self.page.wait_for_load_state("load")
+        deadline = time.monotonic() + SETTLE_TIMEOUT_MS / 1000
+        while time.monotonic() < deadline:
+            quiet = (time.monotonic() - self._last_network) * 1000 >= SETTLE_QUIET_MS
+            if self._inflight == 0 and quiet:
+                return
+            self.page.wait_for_timeout(SETTLE_POLL_MS)
+
+    # ── acting ─────────────────────────────────────────────────────────────
+    def click(self, selector: str) -> None:
+        def run() -> None:
+            self.page.click(selector)
+            self._settle()
+
+        self._act("browser_click", {"selector": selector}, run)
+
+    def type(self, selector: str, text: str) -> None:
+        self._act("browser_type", {"selector": selector, "text": text}, lambda: self.page.fill(selector, text))
+
+    def press(self, key: str) -> None:
+        def run() -> None:
+            self.page.keyboard.press(key)
+            self._settle()
+
+        self._act("browser_press", {"key": key}, run)
+
+    def scroll(self, dy: int) -> None:
+        self._act("browser_scroll", {"dy": dy}, lambda: self.page.mouse.wheel(0, dy))
+
+    # ── observing ──────────────────────────────────────────────────────────
+    def screenshot(self, full_page: bool = False) -> bytes:
+        return self.page.screenshot(type="png", full_page=full_page)
+
+    def screenshot_b64(self, full_page: bool = False) -> str:
+        return base64.b64encode(self.screenshot(full_page)).decode("ascii")
+
+    def text(self, selector: str = "body") -> str:
+        return self.page.inner_text(selector)
+
+    def html(self) -> str:
+        return self.page.content()
+
+    @property
+    def url(self) -> str:
+        """Where the page is, less the session token a World Host landing
+        carries: the host trades it for a cookie and redirects, but a page that
+        never got that far (host down, wrong origin) would still show it."""
+        return without_ui_token(self.page.url)
+
+    def title(self) -> str:
+        return self.page.title()
+
+    # ── lifecycle ──────────────────────────────────────────────────────────
+    def close(self) -> None:
+        try:
+            self._close()
+        finally:
+            if self.recorder is not None:
+                self.recorder.close()
+
+    def __enter__(self) -> "WorldBrowser":
+        return self
+
+    def __exit__(self, exc_type: Any, exc: Any, tb: Any) -> None:
+        self.close()
+
+
+def open_browser(
+    surfaces: SessionSurfaces,
+    *,
+    mode: str = "auto",
+    headless: bool = True,
+    recorder: Optional[BrowserActionRecorder] = None,
+) -> WorldBrowser:
+    """Open a browser on the session's UI in ``hosted``, ``local`` or ``auto`` mode."""
+    if mode not in ("auto", "hosted", "local"):
+        raise ValueError("mode must be 'auto', 'hosted' or 'local'")
+    if surfaces.ui is None and surfaces.browser is None:
+        raise WorldSurfaceUnavailable("ui", "open the session with surfaces=['ui'] on a world that declares [ui]")
+    resolved = mode
+    if mode == "auto":
+        resolved = "hosted" if surfaces.browser is not None else "local"
+    if resolved == "hosted" and surfaces.browser is None:
+        raise WorldSurfaceUnavailable("browser", "open the session with surfaces=['browser'] to get a hosted browser")
+
+    sync_api = _playwright_module()
+    pw = sync_api.sync_playwright().start()
+    viewport = surfaces.browser.viewport if surfaces.browser else dict(DEFAULT_VIEWPORT)
+    try:
+        if resolved == "hosted":
+            assert surfaces.browser is not None
+            if surfaces.browser.protocol == "playwright":
+                browser = pw.chromium.connect(surfaces.browser.ws_url)
+            else:
+                browser = pw.chromium.connect_over_cdp(surfaces.browser.ws_url)
+        else:
+            browser = pw.chromium.launch(headless=headless)
+        context = browser.new_context(viewport=viewport)
+        page = context.new_page()
+    except Exception:
+        pw.stop()
+        raise
+
+    def close() -> None:
+        try:
+            context.close()
+            browser.close()
+        finally:
+            pw.stop()
+
+    return WorldBrowser(page, surfaces.ui, mode=resolved, close=close, viewport=viewport, recorder=recorder)
+
+
+# ── computer-use tools ───────────────────────────────────────────────────────
+
+COMPUTER_USE_SPECS: List[WorldToolSpec] = [
+    WorldToolSpec(
+        "browser_goto",
+        "browser_goto(path=None)",
+        "Open a page of the world's UI. `path` is a UI path like /customers, a full URL, or omitted for the entry page. Returns the URL and page text.",
+    ),
+    WorldToolSpec(
+        "browser_click",
+        "browser_click(selector)",
+        "Click an element by Playwright selector (CSS, `text=Refund`, `role=button[name=Save]`). Returns the page text after the click.",
+    ),
+    WorldToolSpec(
+        "browser_type",
+        "browser_type(selector, text)",
+        "Replace the value of an input/textarea found by selector with `text`.",
+    ),
+    WorldToolSpec(
+        "browser_press",
+        "browser_press(key)",
+        "Press a key (Enter, Tab, Escape, ArrowDown, ...). Returns the page text after.",
+    ),
+    WorldToolSpec(
+        "browser_scroll",
+        "browser_scroll(dy=600)",
+        "Scroll the page vertically by `dy` pixels (negative scrolls up).",
+    ),
+    WorldToolSpec(
+        "browser_screenshot",
+        "browser_screenshot(full_page=False)",
+        "Take a PNG screenshot; returns {'image_base64': ..., 'url': ...}.",
+    ),
+    WorldToolSpec(
+        "browser_read",
+        "browser_read(selector='body')",
+        "Return the visible text of an element (default: whole page) plus the URL and title.",
+    ),
+    WorldToolSpec(
+        "browser_back",
+        "browser_back()",
+        "Go back one page in history.",
+    ),
+]
+
+
+def computer_use_toolkit(browser: WorldBrowser, max_text: int = 20000) -> WorldToolkit:
+    """The browser as model tools, in the same :class:`WorldToolkit` shape
+    the world's own tools come in — so an agent loop that already dispatches
+    ``toolkit().impls`` merges ``computer_use_toolkit(b).impls`` and gains a
+    screen without a second dispatch path."""
+
+    def observe(selector: str = "body") -> Dict[str, Any]:
+        text = browser.text(selector)
+        return {
+            "url": browser.url,
+            "title": browser.title(),
+            "text": text[:max_text],
+            "truncated": len(text) > max_text,
+        }
+
+    def goto(path: Optional[str] = None) -> Dict[str, Any]:
+        browser.goto(path)
+        return observe()
+
+    def click(selector: str) -> Dict[str, Any]:
+        browser.click(selector)
+        return observe()
+
+    def type_(selector: str, text: str) -> Dict[str, Any]:
+        browser.type(selector, str(text))
+        return {"ok": True, "url": browser.url}
+
+    def press(key: str) -> Dict[str, Any]:
+        browser.press(key)
+        return observe()
+
+    def scroll(dy: int = 600) -> Dict[str, Any]:
+        browser.scroll(int(dy))
+        return {"ok": True, "url": browser.url}
+
+    def screenshot(full_page: bool = False) -> Dict[str, Any]:
+        return {"image_base64": browser.screenshot_b64(bool(full_page)), "url": browser.url}
+
+    def read(selector: str = "body") -> Dict[str, Any]:
+        return observe(selector)
+
+    def back() -> Dict[str, Any]:
+        browser.back()
+        return observe()
+
+    raw_impls: Dict[str, Callable[..., Any]] = {
+        "browser_goto": goto,
+        "browser_click": click,
+        "browser_type": type_,
+        "browser_press": press,
+        "browser_scroll": scroll,
+        "browser_screenshot": screenshot,
+        "browser_read": read,
+        "browser_back": back,
+    }
+
+    def bind(fn: Callable[..., Any]) -> Callable[..., Any]:
+        # Callable either way, like the world's own tools: impl({"selector": s})
+        # or impl(selector=s).
+        def impl(args: Optional[Dict[str, Any]] = None, **kwargs: Any) -> Any:
+            payload = dict(args or {})
+            payload.update(kwargs)
+            return fn(**payload)
+
+        impl.__name__ = fn.__name__
+        return impl
+
+    return WorldToolkit(
+        schemas=[schema_from_signature(spec) for spec in COMPUTER_USE_SPECS],
+        impls={name: bind(fn) for name, fn in raw_impls.items()},
+        specs=list(COMPUTER_USE_SPECS),
+    )