browserwright 0.6.2__py3-none-any.whl

browserwright/_executor/protocol.py

@@ -0,0 +1,152 @@
+"""Length-framed JSON request/response for the executor data plane (Fork 2).
+
+A deliberately simple wire format of OUR design — it does NOT pretend to be CDP
+(unlike the mode_b tunnel). Each message is a 4-byte big-endian unsigned length
+prefix followed by that many bytes of UTF-8 JSON. The thin heredoc client sends
+exactly one :class:`ExecuteRequest`; the executor replies with exactly one
+:class:`ExecuteResponse`.
+
+PR3 completes the response: ``console`` / ``return_value`` / ``warnings`` /
+``screenshots`` / ``truncated`` / ``error`` (with a traceback for generic
+exceptions, mirroring the in-process path), and the ``timeout_ms`` field is now
+ENFORCED executor-side (a wedged call returns a timeout error without blocking
+the serial queue forever).
+"""
+from __future__ import annotations
+
+import json
+import socket
+import struct
+from dataclasses import dataclass, field
+from typing import Any
+
+# Default per-call timeout (ms). Playwriter defaults to 10000ms, but real page
+# ops (cold navigation + network settle) can legitimately take longer, so we
+# pick a more generous default. It is deliberately bounded WELL UNDER any
+# realistic idle-reap threshold (`Config.idle_close_after`, default None = never)
+# so a slow-but-legitimate call never trips idle reclamation mid-flight.
+DEFAULT_TIMEOUT_MS = 90000
+
+# Cap on the rendered text block (console + return value), mirroring
+# playwriter's ~10000-char truncation. Whole-line aware truncation lives in
+# `snapshot._truncate_lines`; here we cap the console blob so a runaway print
+# loop can't ship megabytes back to the agent.
+MAX_TEXT_CHARS = 10000
+
+_LEN = struct.Struct(">I")
+_MAX_FRAME = 256 * 1024 * 1024  # generous: screenshots land here in PR3
+
+
+@dataclass
+class ExecuteRequest:
+    """A code blob the thin client ships to the executor."""
+
+    code: str
+    timeout_ms: int = DEFAULT_TIMEOUT_MS
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"code": self.code, "timeout_ms": self.timeout_ms}
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> "ExecuteRequest":
+        code = d.get("code")
+        if not isinstance(code, str):
+            raise ValueError("ExecuteRequest.code must be a string")
+        timeout = d.get("timeout_ms", DEFAULT_TIMEOUT_MS)
+        if not isinstance(timeout, int) or timeout <= 0:
+            timeout = DEFAULT_TIMEOUT_MS
+        return cls(code=code, timeout_ms=timeout)
+
+
+@dataclass
+class ExecuteResponse:
+    """The executor's reply to one :class:`ExecuteRequest` (PR3 full shape).
+
+    Mirrors playwriter's single response object:
+
+      - ``console``: captured stdout/stderr of the run.
+      - ``return_value``: ``repr`` of the trailing bare expression (if the last
+        statement was an expression), else None — playwriter's ``[return
+        value]`` block.
+      - ``warnings``: human-facing notices (e.g. a popup that became a tab) the
+        client renders as ``[WARNING] …`` lines. The field + plumbing exist
+        even though few producers exist yet.
+      - ``screenshots``: list of ``{"path": str, ...}`` blocks for any image the
+        heredoc captured — path-based (the executor and client share a
+        filesystem), so the (possibly large) bytes never ride the wire.
+      - ``truncated``: True when the text block was capped at ``MAX_TEXT_CHARS``.
+      - ``error``: ``errors.serialize(exc)`` (or None on success), WITH a
+        ``traceback`` key for generic exceptions so a shipped heredoc surfaces
+        the same traceback the in-process path writes.
+      - ``exit_code``: mirrors the heredoc's desired process exit code so the
+        thin client can propagate it.
+    """
+
+    console: str = ""
+    return_value: str | None = None
+    error: dict[str, Any] | None = None
+    exit_code: int = 0
+    warnings: list[str] = field(default_factory=list)
+    screenshots: list[dict[str, Any]] = field(default_factory=list)
+    truncated: bool = False
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "console": self.console,
+            "return_value": self.return_value,
+            "error": self.error,
+            "exit_code": self.exit_code,
+            "warnings": self.warnings,
+            "screenshots": self.screenshots,
+            "truncated": self.truncated,
+        }
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> "ExecuteResponse":
+        return cls(
+            console=str(d.get("console") or ""),
+            return_value=d.get("return_value"),
+            error=d.get("error"),
+            exit_code=int(d.get("exit_code") or 0),
+            warnings=list(d.get("warnings") or []),
+            screenshots=list(d.get("screenshots") or []),
+            truncated=bool(d.get("truncated") or False),
+        )
+
+
+# ---- length-framed transport ----------------------------------------------
+
+
+def send_message(sock: socket.socket, payload: dict[str, Any]) -> None:
+    """Send one length-framed JSON message over a blocking socket."""
+    body = json.dumps(payload).encode("utf-8")
+    sock.sendall(_LEN.pack(len(body)) + body)
+
+
+def _recv_exact(sock: socket.socket, n: int) -> bytes:
+    """Read exactly ``n`` bytes or raise ``ConnectionError`` on early EOF."""
+    chunks: list[bytes] = []
+    remaining = n
+    while remaining > 0:
+        chunk = sock.recv(remaining)
+        if not chunk:
+            raise ConnectionError("executor socket closed mid-message")
+        chunks.append(chunk)
+        remaining -= len(chunk)
+    return b"".join(chunks)
+
+
+def recv_message(sock: socket.socket) -> dict[str, Any]:
+    """Read one length-framed JSON message. Raises ``ConnectionError`` on a
+    clean peer close before any bytes, ``ValueError`` on a corrupt frame."""
+    header = b""
+    while len(header) < _LEN.size:
+        chunk = sock.recv(_LEN.size - len(header))
+        if not chunk:
+            raise ConnectionError("executor socket closed before a message")
+        header += chunk
+    (length,) = _LEN.unpack(header)
+    if length <= 0 or length > _MAX_FRAME:
+        raise ValueError(f"executor frame length out of range: {length}")
+    body = _recv_exact(sock, length)
+    return json.loads(body.decode("utf-8"))

browserwright/api.py

@@ -0,0 +1,66 @@
+"""Canonical primitive surface for ``from browserwright import *``.
+
+The inline / repl / task entry points all assemble their exec globals from
+this module. Keeping the list in one place means an agent who imports
+``browserwright`` directly from a saved task gets the same names the REPL
+gave them.
+
+Phase C PR3 (terminal state): the legacy CDP browser-driving primitives
+(``open``/``goto_url``/``click_at_xy``/``js``/``cdp``/``capture_screenshot``/
+``snapshot``/… — the whole page/tab interaction surface) are GONE from the
+agent surface. The agent now drives the browser with **real Playwright** via
+the injected ``page`` / ``context`` (bound to the session's current tab,
+reused across heredocs) and observes with ``snapshot()`` (a first-party AI
+aria snapshot whose ``[ref=eN]`` refs feed ``page.locator("aria-ref=eN")``).
+Those three names are injected per-heredoc by ``repl/_namespace.build_globals``,
+NOT exported here.
+
+What remains in EXPORTS is the set of NON-browser-driving helpers that do not
+overlap Playwright: ``http_get`` (no-browser escape hatch), the memory verbs,
+and the site-skill / task layer. The implementation modules under
+``primitives/`` still define the old functions (``current_page``, ``list_tabs``,
+the daemon-driving glue, …); they are kept as INTERNAL functions the Phase C
+binding glue (``repl/playwright_handle.py``) and the memory/site helpers rely
+on — they are simply no longer part of the agent-callable surface.
+"""
+from .errors import (
+    AuthWall,
+    BrowserwrightError,
+    Captcha,
+    CDPError,
+    DaemonUnavailable,
+    ElementNotFound,
+    NeedsUserConfirm,
+    NetworkError,
+    PageLoadFailed,
+)
+from .multitask import run_tasks_concurrent
+from .primitives import (
+    bootstrap_site,
+    http_get,
+    list_site_skills,
+    load_site_skill,
+    memory_read,
+    remember,
+    remember_global,
+    remember_preference,
+    run_task,
+)
+
+EXPORTS = [
+    # http (escape hatch — no browser; does not overlap Playwright)
+    "http_get",
+    # memory + site
+    "bootstrap_site", "remember", "remember_global", "remember_preference",
+    "memory_read",
+    # task / fan-out (site-skills run on the Playwright surface — see
+    # task_runner.run_task, which injects page/context into the task module)
+    "list_site_skills", "load_site_skill", "run_task",
+    "run_tasks_concurrent",
+    # errors
+    "BrowserwrightError", "PageLoadFailed", "ElementNotFound", "AuthWall",
+    "Captcha", "NetworkError", "DaemonUnavailable", "CDPError",
+    "NeedsUserConfirm",
+]
+
+__all__ = EXPORTS

browserwright/cdp.py

@@ -0,0 +1,285 @@
+"""Synchronous CDP client over a single browser-level WebSocket.
+
+Design:
+  - One root ws connection per Skill process.
+  - sessionId multiplex: ``send(method, session=...)`` for per-target ops,
+    no session for ``Target.*`` etc.
+  - Auto-attach to a tab on demand via ``attach(targetId)``; the resulting
+    session id is cached so subsequent calls reuse it.
+  - Events for the attached session are stashed in a per-session ring buffer
+    and exposed via ``drain_events()``.
+
+We intentionally do not depend on cdp-use here. The whole client is < 200
+lines of plain websockets — easier to reason about, easier to unit test,
+and we never need typed wrappers (spec §3 "raw CDP strings over typed
+wrappers").
+"""
+from __future__ import annotations
+
+import json
+import threading
+import time
+from collections import deque
+from typing import Any, Optional
+
+from websockets.exceptions import ConnectionClosed
+from websockets.sync.client import connect as ws_connect
+
+from .errors import CDPError
+
+
+_EVENT_RING_LIMIT = 1024
+
+
+class _UnixSocketAdapter:
+    """Wrap an ``AF_UNIX`` socket so ``setsockopt(IPPROTO_TCP, ...)`` becomes
+    a no-op. websockets unconditionally calls
+    ``sock.setsockopt(socket.IPPROTO_TCP, TCP_NODELAY, True)`` after
+    receiving a user-provided socket — which AF_UNIX doesn't support and
+    raises ``OSError: [Errno 102]``. Everything else delegates straight
+    through.
+    """
+
+    __slots__ = ("_s",)
+
+    def __init__(self, s):
+        self._s = s
+
+    def setsockopt(self, level, optname, value):
+        import socket as _sock
+        if level == _sock.IPPROTO_TCP:
+            return None  # silently ignore — unix sockets have no TCP layer
+        return self._s.setsockopt(level, optname, value)
+
+    def __getattr__(self, name):
+        return getattr(self._s, name)
+
+
+def _open_unix_websocket(ws_unix_url: str, *, connect_timeout: float):
+    """Open a ws connection over a unix socket. ``ws_unix_url`` has the form
+    ``ws+unix:///path/to/sock?client=skill-repl``. websockets supports this
+    via ``sock=`` + ``server_hostname=`` overrides, but we wrap the AF_UNIX
+    socket in ``_UnixSocketAdapter`` to absorb the unconditional
+    ``TCP_NODELAY`` set the library performs.
+    """
+    import socket as _sock
+    from urllib.parse import urlparse, urlunparse
+
+    parsed = urlparse(ws_unix_url)
+    path = parsed.path
+    query = parsed.query
+    raw = _sock.socket(_sock.AF_UNIX, _sock.SOCK_STREAM)
+    raw.settimeout(connect_timeout)
+    raw.connect(path)
+    sock = _UnixSocketAdapter(raw)
+    # Build a synthetic ws:// URL for the upgrade handshake; websockets parses
+    # this for the HTTP path + Host header.
+    upgrade_url = urlunparse(("ws", "browserwright", "/", "", query, ""))
+    return ws_connect(
+        upgrade_url,
+        sock=sock,
+        server_hostname="browserwright",
+        open_timeout=connect_timeout,
+        max_size=64 * 1024 * 1024,
+        proxy=None,
+        compression=None,  # daemon disables permessage-deflate (§6.3)
+    )
+
+
+def _rpc_error_fix(method: str, err: object) -> str:
+    """Recovery hint for a JSON-RPC error returned over the wire. A ``-32601``
+    ("method not found") almost always means the running daemon is older than
+    the installed code, so we surface the restart guidance (naming the method)
+    instead of leaking a bare envelope. Empty string for any other error."""
+    if isinstance(err, dict) and err.get("code") == -32601:
+        from .mode_b_client import ModeBClient  # lazy: avoid import cycle
+        return ModeBClient.explain_rpc_error(method, err)
+    return ""
+
+
+class CDPSession:
+    """Reader-singleton CDP transport.
+
+    All sends are synchronous: send → block on response with matching id →
+    return result. Events arrive on the same socket; the reader thread
+    routes them by sessionId into per-session deques.
+    """
+
+    def __init__(self, ws_url: str, connect_timeout: float = 8.0):
+        self.ws_url = ws_url
+        # ``proxy=None`` is critical: CDP endpoints are loopback (or a
+        # daemon-provided URL the user controls). websockets.sync defaults to
+        # ``proxy=True`` which means "respect $ALL_PROXY/$HTTP_PROXY" — agents
+        # commonly run inside shells that point those at a SOCKS proxy for
+        # their normal browsing, and routing CDP through one would fail in
+        # confusing ways. browserwright-daemon-implementer flagged this.
+        if ws_url.startswith("ws+unix://"):
+            # Mode B: connect to the daemon's unix socket, then upgrade as
+            # if it were a ws:// localhost endpoint. We hand websockets a
+            # pre-connected socket via ``sock=`` and a stand-in HTTP URL.
+            self._ws = _open_unix_websocket(ws_url, connect_timeout=connect_timeout)
+        else:
+            # ``compression=None`` matches the Mode B daemon contract (which
+            # disables permessage-deflate) and is also fine for direct CDP:
+            # Chrome's browser-level ws doesn't benefit from deflate on
+            # localhost. ``proxy=None`` keeps $ALL_PROXY out of loopback.
+            self._ws = ws_connect(
+                ws_url,
+                open_timeout=connect_timeout,
+                max_size=64 * 1024 * 1024,
+                proxy=None,
+                compression=None,
+            )
+        self._lock = threading.Lock()
+        self._next_id = 1
+        self._inflight: dict[int, dict] = {}
+        self._inflight_cv = threading.Condition(self._lock)
+        self._events: dict[Optional[str], deque] = {None: deque(maxlen=_EVENT_RING_LIMIT)}
+        self._closed = False
+        self._closed_reason: Optional[str] = None
+        self._reader = threading.Thread(target=self._read_loop, name="cdp-reader", daemon=True)
+        self._reader.start()
+        # Track which target each session is bound to. Attaching to the same
+        # target twice in the same process is a programmer error (§D.2.10).
+        self._sessions: dict[str, str] = {}  # targetId -> sessionId
+
+    # ---- public --------------------------------------------------------
+
+    def send(self, method: str, *, session: Optional[str] = None, **params) -> dict:
+        if self._closed:
+            raise CDPError(method=method, params=params,
+                           cdp_message=f"ws closed: {self._closed_reason}")
+        with self._lock:
+            mid = self._next_id
+            self._next_id += 1
+            msg = {"id": mid, "method": method, "params": params}
+            if session:
+                msg["sessionId"] = session
+            self._inflight[mid] = {}
+        payload = json.dumps(msg)
+        try:
+            self._ws.send(payload)
+        except ConnectionClosed as e:
+            self._closed, self._closed_reason = True, str(e)
+            raise CDPError(method=method, params=params, cdp_message=str(e)) from e
+        # Wait for the reply.
+        deadline = time.monotonic() + 30.0
+        with self._inflight_cv:
+            while not self._inflight[mid] and not self._closed:
+                remaining = deadline - time.monotonic()
+                if remaining <= 0:
+                    self._inflight.pop(mid, None)
+                    raise CDPError(method=method, params=params,
+                                   cdp_message="timeout waiting for CDP reply")
+                self._inflight_cv.wait(timeout=remaining)
+            entry = self._inflight.pop(mid, None)
+        if self._closed and not entry:
+            raise CDPError(method=method, params=params,
+                           cdp_message=f"ws closed: {self._closed_reason}")
+        if "error" in entry:
+            err = entry["error"]
+            raise CDPError(method=method, params=params,
+                           cdp_message=err.get("message", str(err)),
+                           fix=_rpc_error_fix(method, err))
+        return entry.get("result", {})
+
+    def attach(self, target_id: str) -> str:
+        """Attach (or reuse attachment) to ``target_id`` and return sessionId."""
+        if target_id in self._sessions:
+            return self._sessions[target_id]
+        res = self.send("Target.attachToTarget", targetId=target_id, flatten=True)
+        sid = res["sessionId"]
+        self._sessions[target_id] = sid
+        self._events.setdefault(sid, deque(maxlen=_EVENT_RING_LIMIT))
+        # Enable the usual domains so wait_for_load / drain_events have data.
+        for domain in ("Page", "Runtime", "DOM", "Network"):
+            try:
+                self.send(f"{domain}.enable", session=sid)
+            except CDPError:
+                pass  # Some domains are noop in some Chrome builds.
+        return sid
+
+    def attach_readonly(self, target_id: str) -> str:
+        """Daemon v0.3 H7 shared-read attach.
+
+        Requests a session via ``flags.allowSecondaryReadOnly=True`` — daemon
+        returns a sessionId that receives this target's events but rejects
+        any command other than ``Target.detachFromTarget`` (`-32602`). Useful
+        for tail-following another agent's session for monitoring / drift
+        detection.
+
+        Note: this opens a *second* session on the same target if some other
+        client / process already owns it. If we own it ourselves, prefer
+        ``attach()``.
+        """
+        res = self.send(
+            "Target.attachToTarget",
+            targetId=target_id,
+            flatten=True,
+            flags={"allowSecondaryReadOnly": True},
+        )
+        sid = res["sessionId"]
+        self._events.setdefault(sid, deque(maxlen=_EVENT_RING_LIMIT))
+        # We deliberately *don't* register sid in ``self._sessions`` — that
+        # map tracks owning attachments, and a readonly attachment isn't one.
+        return sid
+
+    def detach(self, target_id: str) -> None:
+        sid = self._sessions.pop(target_id, None)
+        if sid:
+            try:
+                self.send("Target.detachFromTarget", sessionId=sid)
+            except CDPError:
+                pass
+            self._events.pop(sid, None)
+
+    def drain_events(self, session: Optional[str] = None) -> list[dict]:
+        buf = self._events.get(session)
+        if not buf:
+            return []
+        with self._lock:
+            out = list(buf)
+            buf.clear()
+        return out
+
+    def close(self) -> None:
+        if self._closed:
+            return
+        self._closed = True
+        try:
+            self._ws.close()
+        except Exception:
+            pass
+        with self._inflight_cv:
+            self._inflight_cv.notify_all()
+
+    # ---- reader thread -------------------------------------------------
+
+    def _read_loop(self) -> None:
+        try:
+            for raw in self._ws:
+                try:
+                    msg = json.loads(raw)
+                except (TypeError, ValueError):
+                    continue
+                mid = msg.get("id")
+                if mid is not None:
+                    with self._inflight_cv:
+                        if mid in self._inflight:
+                            self._inflight[mid] = msg
+                            self._inflight_cv.notify_all()
+                    continue
+                # Event.
+                sid = msg.get("sessionId")
+                buf = self._events.get(sid)
+                if buf is None:
+                    buf = self._events.setdefault(sid, deque(maxlen=_EVENT_RING_LIMIT))
+                buf.append({"method": msg.get("method"), "params": msg.get("params", {}), "sessionId": sid})
+        except ConnectionClosed as e:
+            self._closed_reason = str(e)
+        except Exception as e:  # noqa: BLE001
+            self._closed_reason = f"reader crash: {e!r}"
+        finally:
+            self._closed = True
+            with self._inflight_cv:
+                self._inflight_cv.notify_all()