browserwright 0.7.4__tar.gz → 0.8.1__tar.gz

{browserwright-0.7.4 → browserwright-0.8.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: browserwright
-Version: 0.7.4
+Version: 0.8.1
 Summary: Browserwright — let AI/code agents drive a real or isolated browser and author userscripts. Single package: the agent-facing REPL/site-skills/memory layer plus the bundled browser-resolving daemon (CDP proxy + extension/cloud backends).
 Requires-Python: >=3.11
 Requires-Dist: websockets==15.0.1

browserwright-0.8.1/pyproject.toml

@@ -0,0 +1,112 @@
+[build-system]
+requires = ["setuptools>=69"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "browserwright"
+# Placeholder, never bumped per release — the git tag is the single source of
+# truth. `.github/workflows/release.yml` rewrites this line (and
+# `chrome-extension/manifest.json`) from `GITHUB_REF_NAME` at build time, so a
+# release commit must NOT edit it. The sentinel is `0.0.0` on purpose: it is
+# valid semver, is below every published version, and can never be mistaken for
+# a real release — which a stale-but-plausible number (this used to sit at
+# "0.6.2" while tags had reached v0.8.0) very much could. Keep it in lockstep
+# with the manifest, keep the line on its own with no trailing comment: the
+# stamping regex is `^(version\s*=\s*)["'][^"']+["']\s*$` and CI aborts unless
+# it matches exactly once. `tests/skill/test_release_versioning.py` enforces all
+# of that before a tag is ever pushed. See RELEASING.md.
+version = "0.8.1"
+description = "Browserwright — let AI/code agents drive a real or isolated browser and author userscripts. Single package: the agent-facing REPL/site-skills/memory layer plus the bundled browser-resolving daemon (CDP proxy + extension/cloud backends)."
+requires-python = ">=3.11"
+dependencies = [
+    "websockets==15.0.1",
+    "pillow==12.2.0",
+    "httpx>=0.27",
+    # Phase C: the skill heredoc injects a real Playwright `page`/`context`
+    # bound to the daemon facade, so playwright is a runtime dependency now (it
+    # was previously dev-only). `playwright install chromium` is still needed
+    # for tests that launch a browser; the daemon-facade path drives the
+    # daemon-resolved Chrome and does not need Playwright's bundled browser.
+    "playwright>=1.60.0",
+    "pyyaml>=6.0.3",
+]
+
+[project.optional-dependencies]
+ux = ["rich>=13"]
+
+[dependency-groups]
+dev = [
+    "coverage>=7",
+    "pytest>=8",
+    "pytest-asyncio>=0.23",
+]
+
+[project.scripts]
+browserwright = "browserwright.cli:main"
+browserwright-daemon = "browserwright.daemon.cli:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+browserwright = [
+    "site_skills_starter/**/*.md",
+    "site_skills_starter/**/*.py",
+    "skill_runtime.md",
+]
+
+[tool.setuptools.exclude-package-data]
+browserwright = ["**/__pycache__/*", "**/*.pyc", "**/*.pyo"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+markers = [
+    "real_chrome: end-to-end test that launches a real Chrome + extension (skipped unless explicitly selected)",
+]
+
+# Lint config. `select` is explicit on purpose: ruff's *default* rule set grew
+# substantially by 0.16.x (ASYNC/S/BLE/B/UP/RUF/... are now on by default), which
+# silently took this repo from clean to 646 findings without a line of code
+# changing. Pinning the ruff version (mise `[tools]`) *and* the rule set here is
+# what makes `mise run lint` mean the same thing on every machine and across ruff
+# upgrades. Widening the set is a deliberate, separate decision — do it in one
+# focused pass, not as a side effect of an unrelated ruff release.
+[tool.ruff]
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E4", "E7", "E9", "F"]
+
+[tool.ruff.lint.per-file-ignores]
+# api.py exists purely to re-export the agent-facing surface; the names it
+# imports are listed in `EXPORTS` as *strings*, which ruff can't see as usage.
+# Without this, `--fix` strips the whole re-export block and every
+# `api.<name>` lookup dies at runtime (verified: it breaks 22 test modules).
+"src/browserwright/api.py" = ["F401"]
+# Site-skill task snippets are executed with a Playwright `page` injected into
+# globals by the executor — `page` is undefined at import time by design.
+"src/browserwright/site_skills_starter/**" = ["F821"]
+# pytest fixtures are shadowed by same-named test parameters (the standard
+# fixture-injection pattern), and the e2e helpers extend sys.path before
+# importing, so imports legitimately follow statements.
+"tests/daemon/e2e/**" = ["E402", "F811"]
+# Agent hook scripts bootstrap sys.path before importing their own modules.
+".claude/hooks/**" = ["E402"]
+".cursor/hooks/**" = ["E402"]
+
+[tool.coverage.run]
+source = ["src/browserwright"]
+omit = [
+    "src/browserwright/__main__.py",
+    "src/browserwright/site_skills_starter/*",
+]
+
+[tool.coverage.report]
+skip_covered = true
+sort = "Cover"

browserwright-0.7.4/src/browserwright/api.py → browserwright-0.8.1/src/browserwright/__init__.py

@@ -1,26 +1,38 @@
-"""Canonical primitive surface for ``from browserwright import *``.
+"""browserwright — Layer 2 of the browser stack.
 
-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.
+Public surface: ``browserwright.cli:main`` is the CLI entry point.
+
+For programmatic use inside REPL/task scripts, import names from the top-level
+``browserwright`` namespace::
+
+    from browserwright import http_get, remember, run_task
+
+``EXPORTS`` below is the canonical primitive surface. The inline / repl / task
+entry points all assemble their exec globals from it
+(``repl/_namespace.build_globals``), and ``skill_doc`` renders the generated
+skill documentation from it — so the list an agent reads always matches the
+list the binary actually binds. Keeping it in one place means an agent who
+imports ``browserwright`` directly from a saved task gets the same names the
+REPL gave them.
 
 The legacy CDP browser-driving primitives (``open``/``goto_url``/
 ``click_at_xy``/``js``/``cdp``/``capture_screenshot``/``snapshot``/… — the
 whole page/tab interaction surface) are DELETED. The agent 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. The internal tab
-lifecycle the Playwright binding glue relies on lives in
-``browserwright.session_runtime``.
+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; they are bound per call
+to the session's current tab. The internal tab lifecycle the Playwright binding
+glue relies on lives in ``browserwright.session_runtime``.
 
 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.
 """
-from .errors import (
+from .version import __version__  # noqa: F401
+
+from .errors import (  # noqa: F401
     AuthWall,
     BrowserwrightError,
     Captcha,
@@ -31,16 +43,18 @@ from .errors import (
     NetworkError,
     PageLoadFailed,
 )
-from .primitives import (
-    bootstrap_site,
-    http_get,
+from .primitives.discovery_api import (  # noqa: F401
     list_site_skills,
     load_site_skill,
+    run_task,
+)
+from .primitives.http import http_get  # noqa: F401
+from .primitives.site import (  # noqa: F401
+    bootstrap_site,
     memory_read,
     remember,
     remember_global,
     remember_preference,
-    run_task,
 )
 
 EXPORTS = [

{browserwright-0.7.4 → browserwright-0.8.1}/src/browserwright/_executor/__init__.py

@@ -29,19 +29,9 @@ Status: PR1 (process skeleton + data plane), PR2 (daemon-side supervision —
 idle reap / endSession kill / crash reap / orphan sweep), and PR3 (``reset()`` +
 full output protocol: warnings / screenshots / truncation / traceback-bearing
 errors + per-call timeout enforcement) are all in place.
+
+This package deliberately re-exports nothing: import ``.protocol`` (wire
+types) or ``.client`` (thin client) directly, which is what every call site
+already does.
 """
 from __future__ import annotations
-
-from .protocol import (
-    ExecuteRequest,
-    ExecuteResponse,
-    recv_message,
-    send_message,
-)
-
-__all__ = [
-    "ExecuteRequest",
-    "ExecuteResponse",
-    "recv_message",
-    "send_message",
-]

browserwright-0.8.1/src/browserwright/_executor/client.py

@@ -0,0 +1,301 @@
+"""Thin-client side of the executor data plane.
+
+Used by ``repl/inline.py`` when inline code touches ``page`` / ``context`` /
+``snapshot`` / ``state`` / ``reset``: the whole code body is shipped to the
+session's resident executor and the response is replayed locally.
+
+Control plane (spawn + discover) goes through the daemon's
+``BrowserwrightDaemon.ensureExecutor`` verb over the EXISTING mode_b socket
+(tiny payload). The daemon spawns the executor if absent, waits for it to bind +
+write its ``_ipc`` discovery file, and returns the socket path. The data plane
+(this module) then connects DIRECTLY to that socket — keeping arbitrary code +
+large output off the daemon's event loop (Fork 2).
+"""
+from __future__ import annotations
+
+import signal
+import socket
+import threading
+import time
+from collections.abc import Iterator
+from contextlib import contextmanager
+from dataclasses import dataclass
+
+from .. import session_registry as reg
+from ..errors import BrowserwrightError
+from .protocol import (
+    DEFAULT_TIMEOUT_MS,
+    ExecuteRequest,
+    ExecuteResponse,
+    TaskEnvelope,
+    recv_message,
+    send_message,
+)
+
+# Allow the executor's deadline response a small framing/delivery margin.  The
+# browser cold-start is part of the request deadline, not hidden extra time.
+_RESPONSE_DELIVERY_SLACK_S = 2.0
+
+
+class ExecutorUnavailable(BrowserwrightError):
+    """The session's executor could not be ensured/reached.
+
+    Surfaced when ``ensureExecutor`` fails or the executor socket can't be
+    connected — actionable: the daemon must be running (it spawns the
+    executor)."""
+
+    default_fix = ("ensure the daemon is running (`browserwright-daemon status "
+                   "--json` should show `alive`); if the executor is stale, "
+                   "call `reset()` as a standalone/final inline statement, "
+                   "then retry in a new command; or run `browserwright "
+                   "session reset <id>` before retrying.")
+
+
+@dataclass(frozen=True)
+class ExecutorLease:
+    sock_path: str
+    executor_id: str
+
+
+def _ensure_executor_lease(sess) -> ExecutorLease:
+    """Ask the daemon to ensure the session's executor and return its socket
+    path. Uses the session's mode_b CDP client (``sess.cdp``) to send the
+    control-plane verb."""
+    sid = _session_id(sess)
+    try:
+        # The browserwright session is already bound on the websocket query
+        # (`?session=<id>`). Do not pass it as CDP's top-level `sessionId`;
+        # that field means "attached target session" inside the proxy mux.
+        res = sess.cdp.send("BrowserwrightDaemon.ensureExecutor", bsSession=sid)
+    except Exception as e:
+        raise ExecutorUnavailable(
+            f"ensureExecutor failed for session {sid!r}: {e}"
+        ) from e
+    sock_path = res.get("exec_sock") if isinstance(res, dict) else None
+    executor_id = res.get("executor_id") if isinstance(res, dict) else None
+    if not isinstance(sock_path, str) or not sock_path:
+        raise ExecutorUnavailable(
+            f"ensureExecutor returned no socket for session {sid!r}: {res!r}"
+        )
+    if not isinstance(executor_id, str) or not executor_id:
+        raise ExecutorUnavailable(
+            "ensureExecutor returned no executor instance identity; restart "
+            "the daemon so timeout cleanup cannot target a newer process"
+        )
+    return ExecutorLease(sock_path=sock_path, executor_id=executor_id)
+
+
+def ensure_executor(sess) -> str:
+    """Compatibility wrapper returning only the executor socket path."""
+    return _ensure_executor_lease(sess).sock_path
+
+
+def run_on_executor(
+    sess,
+    code: str,
+    *,
+    timeout_ms: int = DEFAULT_TIMEOUT_MS,
+    env: dict[str, str] | None = None,
+) -> ExecuteResponse:
+    """Ship ``code`` to the session's executor and return its response.
+
+    Ensures the executor (control plane), connects its socket (data plane),
+    sends one :class:`ExecuteRequest`, reads one :class:`ExecuteResponse`.
+
+    The executor enforces ``timeout_ms`` across cold-start and user code.  A
+    terminal deadline/reset response is not returned to the caller until the
+    daemon confirms that exact executor instance has exited."""
+    return _run_request_on_executor(
+        sess,
+        ExecuteRequest(
+            code=code,
+            timeout_ms=timeout_ms,
+            env=dict(env or {}),
+        ),
+    )
+
+
+def run_task_on_executor(
+    sess,
+    site: str,
+    name: str,
+    *,
+    args: dict | None = None,
+    isolated: bool = False,
+    timeout_ms: int = DEFAULT_TIMEOUT_MS,
+    env: dict[str, str] | None = None,
+) -> ExecuteResponse:
+    """Run one validated site-skill task on the resident executor surface."""
+    return _run_request_on_executor(
+        sess,
+        ExecuteRequest(
+            code="",
+            timeout_ms=timeout_ms,
+            env=dict(env or {}),
+            task=TaskEnvelope(
+                site=site,
+                name=name,
+                args=dict(args or {}),
+                isolated=isolated,
+            ),
+        ),
+    )
+
+
+def _run_request_on_executor(
+    sess,
+    request: ExecuteRequest,
+) -> ExecuteResponse:
+    """Send one request through the shared lease/reap data-plane lifecycle."""
+    # Validate/copy before touching the daemon or opening a socket.  The
+    # executor validates again at the trust boundary.
+    request = ExecuteRequest.from_dict(request.to_dict())
+    sid = _session_id(sess)
+    # Session idle is "time since the last user/agent instruction", not
+    # executor process liveness. Touch before contacting the executor so a
+    # wedged or long-running executor cannot prevent the durable idle clock
+    # from reflecting that a new instruction arrived.
+    reg.touch(sid)
+    lease = _ensure_executor_lease(sess)
+    # The executor owns the exact outer deadline, including first-call
+    # cold-start.  Give only a small framing/delivery margin so its terminal
+    # response wins the race against the local socket timeout.
+    recv_timeout = (
+        max(request.timeout_ms, 1) / 1000.0 + _RESPONSE_DELIVERY_SLACK_S
+    )
+    conn = _connect(lease.sock_path, timeout=recv_timeout)
+    sent = False
+    interrupted: BaseException | None = None
+    transport_error: ConnectionError | OSError | ValueError | None = None
+    msg: dict | None = None
+    try:
+        with _sigterm_as_system_exit():
+            request.executor_id = lease.executor_id
+            send_message(conn, request.to_dict())
+            sent = True
+            msg = recv_message(conn)
+    except (KeyboardInterrupt, SystemExit) as e:
+        interrupted = e
+    except (ConnectionError, OSError, ValueError) as e:
+        transport_error = e
+    finally:
+        try:
+            conn.close()
+        except OSError:
+            pass
+
+    # Close the data plane before asking the daemon to wait for process death.
+    if interrupted is not None:
+        if sent:
+            _best_effort_recycle(sess, lease.executor_id)
+        raise interrupted
+    if transport_error is not None:
+        recycle_error: Exception | None = None
+        if sent:
+            try:
+                _confirm_recycled(sess, lease.executor_id)
+            except Exception as cleanup_error:  # noqa: BLE001
+                recycle_error = cleanup_error
+        suffix = (
+            f"; executor reap could not be confirmed: {recycle_error}"
+            if recycle_error is not None
+            else ""
+        )
+        raise ExecutorUnavailable(
+            f"executor data-plane error on {lease.sock_path!r}: "
+            f"{transport_error}{suffix}"
+        ) from transport_error
+    if msg is None:
+        raise ExecutorUnavailable(
+            f"executor returned no response on {lease.sock_path!r}"
+        )
+    try:
+        response = ExecuteResponse.from_dict(msg)
+    except (TypeError, ValueError) as e:
+        try:
+            _confirm_recycled(sess, lease.executor_id)
+        except Exception as cleanup_error:  # noqa: BLE001
+            raise ExecutorUnavailable(
+                "executor returned a malformed response and its reap could "
+                f"not be confirmed: {cleanup_error}"
+            ) from e
+        raise ExecutorUnavailable(
+            f"executor returned a malformed response: {e}"
+        ) from e
+    if response.terminal_reason is not None:
+        _confirm_recycled(sess, lease.executor_id)
+    return response
+
+
+def _confirm_recycled(sess, executor_id: str) -> dict:
+    """Ask the daemon to reap one exact executor and wait for process death."""
+    sid = _session_id(sess)
+    result = sess.cdp.send(
+        "BrowserwrightDaemon.killExecutor",
+        bsSession=sid,
+        executorId=executor_id,
+        wait=True,
+    )
+    if not isinstance(result, dict) or result.get("reaped") is not True:
+        raise ExecutorUnavailable(
+            f"daemon did not confirm executor {executor_id!r} was reaped: {result!r}"
+        )
+    return result
+
+
+def _best_effort_recycle(sess, executor_id: str) -> None:
+    try:
+        _confirm_recycled(sess, executor_id)
+    except BaseException:  # noqa: BLE001 - cannot mask the original interrupt
+        return
+
+
+@contextmanager
+def _sigterm_as_system_exit() -> Iterator[None]:
+    """Make SIGTERM unwind the blocking recv so exact-instance reap is tried."""
+    if (
+        not hasattr(signal, "SIGTERM")
+        or threading.current_thread() is not threading.main_thread()
+    ):
+        yield
+        return
+    previous = signal.getsignal(signal.SIGTERM)
+
+    def _handle(signum, _frame):
+        raise SystemExit(128 + int(signum))
+
+    try:
+        signal.signal(signal.SIGTERM, _handle)
+        yield
+    finally:
+        signal.signal(signal.SIGTERM, previous)
+
+
+def _connect(sock_path: str, *, timeout: float = 30.0,
+             retry_until: float = 5.0) -> socket.socket:
+    """Connect the executor's unix socket, briefly retrying a not-yet-bound
+    socket (the daemon returns the path the moment it spawns; the bind may race
+    by a few ms)."""
+    deadline = time.monotonic() + retry_until
+    last: OSError | None = None
+    while True:
+        s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+        s.settimeout(timeout)
+        try:
+            s.connect(sock_path)
+            return s
+        except OSError as e:
+            last = e
+            s.close()
+            if time.monotonic() >= deadline:
+                raise ExecutorUnavailable(
+                    f"could not connect executor socket {sock_path!r}: {e}"
+                ) from last
+            time.sleep(0.05)
+
+
+def _session_id(sess) -> str:
+    rec = getattr(sess, "session_record", None)
+    if isinstance(rec, dict) and rec.get("id"):
+        return str(rec["id"])
+    raise ExecutorUnavailable("no session id bound; cannot reach an executor")