browserwright 0.6.2__py3-none-any.whl

browserwright/repl/_namespace.py

@@ -0,0 +1,106 @@
+"""Assemble the exec globals shared by inline / repl-server / task entry points.
+
+Every entry point hot-imports ``browserwright`` so the agent always sees the
+same names (``http_get``, ``remember``, etc.). It also injects the per-heredoc
+Playwright surface (``page`` / ``context`` / ``snapshot``). We also pull
+``json``, ``re``, ``time``, and a handful of builtins that agents reach for
+constantly — saves a ``import`` line per heredoc.
+
+Finally we hot-load ``$BS_HOME/agent_helpers.py`` — the agent-editable
+primitive layer (see SKILL.md "Extending the primitive surface"). It loads
+*after* the core surface so helpers can call core primitives, and a conflict
+guard refuses any helper that would shadow a core name.
+"""
+from __future__ import annotations
+
+import importlib.util
+import json
+import re
+import sys
+import time
+from typing import Any
+
+import browserwright
+
+
+def _load_agent_helpers(g: dict[str, Any]) -> None:
+    """Inject agent-authored helpers from ``$BS_HOME/agent_helpers.py`` into
+    ``g``. No-op when the file is absent. Names already in ``g`` (the core
+    primitive surface + stdlib helpers) are protected: a shadowing definition
+    is refused with a stderr warning, never silently applied. Underscore-
+    prefixed names stay private. A broken file warns but never breaks the
+    namespace — the core surface must always come up.
+    """
+    # Imported lazily to avoid a module-import cycle (memory -> primitives).
+    from browserwright.memory.global_mem import home_dir
+
+    path = home_dir() / "agent_helpers.py"
+    if not path.exists():
+        return
+
+    protected = set(g)  # core EXPORTS + json/re/time/sys already placed
+    try:
+        spec = importlib.util.spec_from_file_location(
+            "browserwright_agent_helpers", path)
+        if spec is None or spec.loader is None:
+            return
+        module = importlib.util.module_from_spec(spec)
+        # Pre-seed the helper module's globals with the core surface so a
+        # helper can call ``http_get`` / ``remember`` / ``run_task`` etc. with
+        # no import — a function resolves free names against its own module
+        # dict, which is this one. (browser-harness requires explicit imports
+        # here.)
+        module.__dict__.update(
+            {k: v for k, v in g.items() if not k.startswith("__")})
+        spec.loader.exec_module(module)
+    except Exception as exc:  # syntax error, import error, anything
+        print(f"browserwright: failed to load agent_helpers.py ({path}): "
+              f"{type(exc).__name__}: {exc}", file=sys.stderr)
+        return
+
+    for name, value in vars(module).items():
+        if name.startswith("_"):
+            continue
+        if name in protected:
+            # Same object (e.g. the helper did `import json`) → harmless skip.
+            if g.get(name) is not value:
+                print(f"browserwright: agent helper {name!r} shadows a core "
+                      f"primitive — ignored, keeping core (rename it)",
+                      file=sys.stderr)
+            continue
+        g[name] = value
+
+
+def build_globals() -> dict[str, Any]:
+    g: dict[str, Any] = {}
+    # Every primitive + every error class.
+    for name in browserwright.EXPORTS:
+        g[name] = getattr(browserwright, name)
+    # Commonly-needed stdlib.
+    g["json"] = json
+    g["re"] = re
+    g["time"] = time
+    g["sys"] = sys
+    g["__name__"] = "__skill__"
+    g["__builtins__"] = __builtins__
+    # Phase C: a lazy Playwright `page` / `context` bound to the session's
+    # current tab. Both are transparent proxies that DON'T connect until first
+    # use, so a pure memory()/site-skill heredoc opens no browser connection.
+    # The owning handle is stashed under a private key so the heredoc runner
+    # can tear the connection down at heredoc end (see inline.py). It is NOT a
+    # core EXPORT — only entry points that drive a heredoc inject it here.
+    from .playwright_handle import PlaywrightHandle, _LazyHandleProxy
+    handle = PlaywrightHandle()
+    g["page"] = _LazyHandleProxy(handle, "page")
+    g["context"] = _LazyHandleProxy(handle, "context")
+    g["__bw_playwright_handle__"] = handle
+    # Phase C: `snapshot()` is the Playwright first-party AI aria snapshot
+    # bound to THIS heredoc's `page` (refs → `page.locator("aria-ref=eN")`).
+    # The legacy coordinate `snapshot` was removed from EXPORTS in PR3, so this
+    # is now the sole observation verb the agent gets — there is nothing left
+    # to override.
+    from .snapshot import make_snapshot
+    g["snapshot"] = make_snapshot(handle)
+    # Agent-editable layer last, so helpers can call core primitives.
+    _load_agent_helpers(g)
+    return g

browserwright/repl/_smart_goto.py

@@ -0,0 +1,236 @@
+"""Transparent smart waiting for Playwright ``Page.goto``.
+
+Browserwright agents already know Playwright, so navigation should keep the
+same surface while avoiding Playwright's SPA-hostile default ``wait_until=load``.
+This module patches Page instances in place: callers can keep using
+``page.goto(...)`` and still receive the normal Playwright ``Response | None``.
+"""
+from __future__ import annotations
+
+import time
+import types
+from datetime import timedelta
+from typing import Any
+
+from ..errors import PageLoadFailed
+
+
+_PATCHED = "_bw_smart_goto"
+_ORIG_GOTO = "_bw_orig_goto"
+_CONTEXT_PATCHED = "_bw_smart_new_page"
+_ORIG_NEW_PAGE = "_bw_orig_new_page"
+_STABLE_WINDOW_MS = 1500
+_DEFAULT_TIMEOUT_MS = 60_000
+_DOMCONTENTLOADED_TIMEOUT_MS = 10_000
+
+
+def patch_context_pages(context: Any) -> None:
+    """Patch existing pages and future ``context.new_page()`` results."""
+    for page in list(getattr(context, "pages", []) or []):
+        patch_page_goto(page)
+    if getattr(context, _CONTEXT_PATCHED, False):
+        return
+
+    orig_new_page = context.new_page
+
+    def new_page(*args: Any, **kwargs: Any) -> Any:
+        page = orig_new_page(*args, **kwargs)
+        patch_page_goto(page)
+        return page
+
+    try:
+        setattr(context, _ORIG_NEW_PAGE, orig_new_page)
+        setattr(context, "new_page", new_page)
+        setattr(context, _CONTEXT_PATCHED, True)
+    except Exception:  # noqa: BLE001 - best effort; returned pages still patch.
+        return
+
+
+def patch_page_goto(page: Any) -> Any:
+    """Replace one Playwright Page instance's ``goto`` with smart waiting."""
+    if getattr(page, _PATCHED, False):
+        return page
+
+    orig_goto = page.goto
+
+    def smart_goto(self: Any, url: str, *, timeout: int | float | timedelta | None = _DEFAULT_TIMEOUT_MS,
+                   wait_until: str | None = None, referer: str | None = None) -> Any:
+        timeout_ms = _normalize_timeout(timeout)
+        network = _NetworkMonitor(self)
+        deadline = _deadline_for(timeout_ms)
+        try:
+            response = orig_goto(url, timeout=timeout_ms,
+                                 wait_until="commit", referer=referer)
+        except Exception as exc:  # noqa: BLE001 - translate Playwright failures.
+            network.detach()
+            raise _page_load_failed(url, "commit", exc) from exc
+
+        _wait_for_domcontentloaded(self, _remaining_timeout_ms(deadline))
+        try:
+            _smart_wait_settled(self, deadline, network)
+        finally:
+            network.detach()
+        return response
+
+    try:
+        setattr(page, _ORIG_GOTO, orig_goto)
+        setattr(page, "goto", types.MethodType(smart_goto, page))
+        setattr(page, _PATCHED, True)
+    except Exception:  # noqa: BLE001
+        return page
+    return page
+
+
+def _normalize_timeout(timeout: int | float | timedelta | None) -> int:
+    if timeout is None:
+        return _DEFAULT_TIMEOUT_MS
+    if isinstance(timeout, timedelta):
+        return max(0, int(timeout.total_seconds() * 1000))
+    try:
+        timeout_ms = int(timeout)
+    except (TypeError, ValueError):
+        return _DEFAULT_TIMEOUT_MS
+    return timeout_ms if timeout_ms >= 0 else _DEFAULT_TIMEOUT_MS
+
+
+def _deadline_for(timeout_ms: int) -> float | None:
+    if timeout_ms == 0:
+        return None
+    return time.monotonic() + (timeout_ms / 1000.0)
+
+
+def _remaining_timeout_ms(deadline: float | None) -> int:
+    if deadline is None:
+        return _DOMCONTENTLOADED_TIMEOUT_MS
+    return max(1, int((deadline - time.monotonic()) * 1000))
+
+
+def _wait_for_domcontentloaded(page: Any, remaining_timeout_ms: int) -> None:
+    try:
+        page.wait_for_load_state(
+            "domcontentloaded",
+            timeout=_bounded_timeout(remaining_timeout_ms, _DOMCONTENTLOADED_TIMEOUT_MS),
+        )
+    except Exception:
+        pass
+
+
+def _smart_wait_settled(page: Any, deadline: float | None, network: "_NetworkMonitor") -> None:
+    try:
+        page.evaluate(_INSTALL_MONITOR_JS)
+    except Exception:
+        return
+
+    while deadline is None or time.monotonic() < deadline:
+        remaining_ms = None if deadline is None else max(1, int((deadline - time.monotonic()) * 1000))
+        poll_ms = 250 if remaining_ms is None else min(250, remaining_ms)
+        try:
+            settled = page.evaluate(_SETTLED_JS, _STABLE_WINDOW_MS)
+        except Exception:
+            return
+        if settled or network.is_idle(_STABLE_WINDOW_MS):
+            return
+        try:
+            page.wait_for_timeout(poll_ms)
+        except Exception:
+            return
+
+
+def _bounded_timeout(total_ms: int, cap_ms: int) -> int:
+    if total_ms == 0:
+        return cap_ms
+    return max(1, min(int(total_ms), cap_ms))
+
+
+def _page_load_failed(url: str, phase: str, exc: BaseException) -> PageLoadFailed:
+    msg = str(exc)
+    exc_type = type(exc).__name__
+    lower = msg.lower()
+    if "timeout" in lower or exc_type == "TimeoutError":
+        return PageLoadFailed(
+            url,
+            phase,
+            fix="site did not respond at commit; verify it with http_get(url) or retry",
+        )
+    if "net::" in msg or "ssl" in lower or "name_not_resolved" in lower:
+        return PageLoadFailed(
+            url,
+            "network",
+            fix="check the URL and network; use http_get(url) to verify the site is reachable",
+        )
+    return PageLoadFailed(
+        url,
+        "network",
+        fix="check the URL and network; use http_get(url) to verify the site is reachable",
+    )
+
+
+class _NetworkMonitor:
+    def __init__(self, page: Any) -> None:
+        self.page = page
+        self.inflight = 0
+        self.last_activity = time.monotonic()
+
+        def on_request(*_args: Any) -> None:
+            self.inflight += 1
+            self.last_activity = time.monotonic()
+
+        def on_done(*_args: Any) -> None:
+            self.inflight = max(0, self.inflight - 1)
+            self.last_activity = time.monotonic()
+
+        self._handlers = {
+            "request": on_request,
+            "requestfinished": on_done,
+            "requestfailed": on_done,
+        }
+        for event, handler in self._handlers.items():
+            try:
+                page.on(event, handler)
+            except Exception:
+                pass
+
+    def is_idle(self, stable_window_ms: int) -> bool:
+        quiet_s = stable_window_ms / 1000.0
+        return self.inflight == 0 and (time.monotonic() - self.last_activity) >= quiet_s
+
+    def detach(self) -> None:
+        for event, handler in self._handlers.items():
+            try:
+                self.page.off(event, handler)
+            except Exception:
+                pass
+
+
+_INSTALL_MONITOR_JS = """
+() => {
+  const w = window;
+  const now = Date.now();
+  if (!w.__bwSmartGoto) {
+    const state = { lastMutation: now };
+    try {
+      const observer = new MutationObserver(() => { state.lastMutation = Date.now(); });
+      observer.observe(document.documentElement || document, {
+        childList: true,
+        subtree: true,
+        attributes: true,
+        characterData: true,
+      });
+      state.observer = observer;
+    } catch (e) {}
+    w.__bwSmartGoto = state;
+  }
+  return true;
+}
+"""
+
+
+_SETTLED_JS = """
+(stableWindowMs) => {
+  const state = window.__bwSmartGoto || {};
+  const now = Date.now();
+  const lastMutation = state.lastMutation || now;
+  return document.readyState === "complete" &&
+    (now - lastMutation) >= stableWindowMs;
+}
+"""

browserwright/repl/inline.py

@@ -0,0 +1,180 @@
+"""``browserwright -s <id> -e <code>`` — single-shot code execution.
+
+Two paths, chosen by a cheap static pre-check on the code (Phase B, Fork 7):
+
+  - **In-process** (Phase C path, unchanged): code that touches NONE of
+    ``{page, context, snapshot, state, reset}`` — pure ``memory()`` /
+    site-skill / ``http_get`` — is exec'd here, in this short-lived process. It
+    never spawns or contacts an executor (stays lightweight).
+  - **Shipped to the executor** (Phase B path): code that references any of
+    those names is shipped WHOLE to the session's resident, per-session executor
+    subprocess, where ``page`` / ``context`` are LIVE objects that survive
+    across calls and ``state`` is a persistent dict. You cannot return a
+    live cross-process ``Page`` into a local ``exec``, so the entire body runs
+    there.
+
+The old cross-process Skill REPL daemon was removed (P3): it froze
+``BD_NAME``/backend into a shared SINGLETON and forwarded calls without their
+env — the documented cross-talk accident. Phase B's executor avoids that by
+keying strictly on ``session_id`` (playwriter's ``Map<sessionId, executor>``),
+never a shared singleton.
+"""
+from __future__ import annotations
+
+import io
+import json
+import sys
+import traceback
+from contextlib import redirect_stdout
+from typing import IO
+
+from ..errors import BrowserwrightError, serialize
+from . import _namespace
+
+# Names whose presence routes the heredoc to the persistent executor (Fork 7).
+# `state` / `reset` are executor-only (live across calls / acts on live
+# objects); `page` / `context` / `snapshot` are live cross-process objects.
+_EXECUTOR_NAMES = frozenset({"page", "context", "snapshot", "state", "reset"})
+
+
+def _touches_executor_surface(code_obj) -> bool:
+    """True iff the compiled code references any executor-only name.
+
+    Uses ``co_names`` (free/global name references) — cheap and deterministic.
+    KNOWN ESCAPE (acceptable): indirect access like ``g = globals(); g['page']``
+    evades ``co_names`` — but the fallback (in-process) is only WRONG in that it
+    can't actually serve a live ``page``; such code would raise a plain
+    ``NameError`` exactly as it does today, never silently misbehave. The common
+    case (writing ``page``/``state`` directly) routes correctly. We also scan
+    nested code objects (functions/comprehensions) so a name used only inside a
+    ``def`` still routes to the executor."""
+    seen = [code_obj]
+    while seen:
+        co = seen.pop()
+        if _EXECUTOR_NAMES.intersection(co.co_names):
+            return True
+        for const in co.co_consts:
+            if hasattr(const, "co_names"):  # nested code object
+                seen.append(const)
+    return False
+
+
+def run(stdin: IO[str]) -> int:
+    """Deprecated stdin entrypoint kept only to reject old heredoc usage."""
+    code = stdin.read()
+    del code
+    print("usage: browserwright -s <session-id> -e 'print(snapshot())'",
+          file=sys.stderr)
+    return 1
+
+
+def run_code(code: str, *, session_id: str) -> int:
+    """Execute inline code for an explicit session id."""
+    if not code.strip():
+        print("usage: browserwright -s <session-id> -e 'print(snapshot())'",
+              file=sys.stderr)
+        return 1
+
+    # P1: refuse loudly at the entrypoint when no session is in scope, then
+    # bind that explicit ledger record so primitives drive the session's
+    # daemon/backend — never an env-guessed default.
+    from ..errors import NoSession
+    from ..session import Session, set_session
+    from ..session_ctx import resolve_session
+    try:
+        rec = resolve_session(session_id)
+    except NoSession as e:
+        print(str(e), file=sys.stderr)
+        return e.exit_code
+    sess = Session(record=rec)
+    set_session(sess)
+
+    # Static pre-check: ship to the executor iff the code touches the live
+    # browser surface; otherwise run the lightweight in-process path.
+    try:
+        code_obj = compile(code, "<inline>", "exec")
+    except SyntaxError:
+        # Let the in-process path raise the SyntaxError with a full traceback
+        # (identical behaviour to before); never ship un-compilable code.
+        code_obj = None
+    if code_obj is not None and _touches_executor_surface(code_obj):
+        return _run_on_executor(sess, code)
+
+    # Run in-process. Capture stdout so we can replay it after the exec.
+    globals_ = _namespace.build_globals()
+    buf = io.StringIO()
+    try:
+        with redirect_stdout(buf):
+            exec(code_obj if code_obj is not None
+                 else compile(code, "<inline>", "exec"), globals_)
+    except BrowserwrightError as e:
+        sys.stdout.write(buf.getvalue())
+        sys.stderr.write(json.dumps(serialize(e)) + "\n")
+        return e.exit_code
+    except SystemExit as e:
+        sys.stdout.write(buf.getvalue())
+        return int(e.code) if isinstance(e.code, int) else 0
+    except Exception:  # noqa: BLE001
+        sys.stdout.write(buf.getvalue())
+        sys.stderr.write(traceback.format_exc())
+        return 3
+    finally:
+        # Phase C: tear down the lazy Playwright connection at heredoc end. A
+        # no-op when `page`/`context` were never accessed (nothing connected).
+        # close() disconnects the CDP transport only — it never closes the
+        # user's real tabs/browser. Fully suppressed so cleanup can't change
+        # the heredoc's exit code.
+        handle = globals_.get("__bw_playwright_handle__")
+        if handle is not None:
+            try:
+                handle.close()
+            except Exception:  # noqa: BLE001
+                pass
+    sys.stdout.write(buf.getvalue())
+    return 0
+
+
+def _run_on_executor(sess, code: str) -> int:
+    """Ship the whole code body to the session's persistent executor and replay
+    its response locally (Phase B path).
+
+    The executor holds live ``page`` / ``context`` + persistent ``state`` across
+    heredoc calls. We print its captured console to stdout, surface any error to
+    stderr in the same shape the in-process path uses (``serialize`` dict for a
+    BrowserwrightError, else the raw type/msg), and propagate its exit code. The
+    in-process ``finally`` teardown does NOT run on this path — no local
+    ``__bw_playwright_handle__`` was built; the executor owns teardown."""
+    from .._executor.client import run_on_executor
+
+    try:
+        # ExecutorUnavailable is a BrowserwrightError subclass — caught below.
+        resp = run_on_executor(sess, code)
+    except BrowserwrightError as e:
+        sys.stderr.write(json.dumps(serialize(e)) + "\n")
+        return e.exit_code
+    except Exception:  # noqa: BLE001 - never let transport blow up opaque
+        sys.stderr.write(traceback.format_exc())
+        return 3
+
+    if resp.console:
+        sys.stdout.write(resp.console)
+    for w in resp.warnings:
+        sys.stderr.write(f"[WARNING] {w}\n")
+    for shot in resp.screenshots:
+        path = shot.get("path") if isinstance(shot, dict) else None
+        if path:
+            sys.stderr.write(f"[screenshot] {path}\n")
+    if resp.return_value is not None:
+        sys.stdout.write(f"[return value] {resp.return_value}\n")
+    if resp.truncated:
+        sys.stderr.write("[output truncated]\n")
+    if resp.error is not None:
+        tb = resp.error.get("tb") or resp.error.get("traceback") \
+            if isinstance(resp.error, dict) else None
+        if tb:
+            # Mirror the in-process path: a generic exception writes its full
+            # traceback to stderr (the serialized envelope carries it).
+            sys.stderr.write(tb if tb.endswith("\n") else tb + "\n")
+        else:
+            sys.stderr.write(json.dumps(resp.error) + "\n")
+    return resp.exit_code