browserwright 0.6.9__tar.gz → 0.6.12__tar.gz

{browserwright-0.6.9 → browserwright-0.6.12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: browserwright
-Version: 0.6.9
+Version: 0.6.12
 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: cdp-use==1.4.5

{browserwright-0.6.9 → browserwright-0.6.12}/README.md

@@ -61,13 +61,12 @@ from your own systemd-user unit or process supervisor.
 
 The browser extension is intentionally not part of the PyPI packaging contract.
 The long-term user path is to publish/install it through the Chrome Web Store.
-Until then, local development and release installs can still use the repo's
-`chrome-extension/` directory or the copied local release extension described
+Until then, local development can use the repo's `chrome-extension/` directory,
+and global installs should use the GitHub Release extension artifact described
 below.
 
-The agent skill bundle remains a thin shell around the installed CLI. For
-local release installs, the release installer symlinks that shell into Claude
-Code, Codex, and Pi. For PyPI installs, the intended stable contract is:
+The agent skill bundle remains a thin shell around the installed CLI. For PyPI
+installs, the intended stable contract is:
 
 ```bash
 browserwright --print-skill
@@ -115,60 +114,39 @@ git push origin v0.6.3
 The GitHub Action only runs for `v*` tags. A tag like `v0.6.3` publishes package
 version `0.6.3`.
 
-### Local immutable release install
+Each `v*` GitHub Release also includes a
+`browserwright-extension-<version>.zip` asset. Use that zip as the official
+extension download path when installing outside PyPI or before the Chrome Web
+Store path is available.
 
-From the repo root. If you have [`mise`](https://mise.jdx.dev/), install an immutable local release:
+### Local development link
 
-```bash
-mise run install-release
-```
-
-This builds a wheel, installs it into:
-
-```bash
-~/.local/share/browserwright/releases/<version>/
-```
-
-and points global entry points at that release copy:
+For development only, `mise run dev-link` links the current checkout into
+global PATH and skill dirs. That is convenient for debugging but can break
+global agents if the checkout is broken.
 
 ```bash
-~/.local/bin/browserwright        -> releases/<version>/.venv/bin/browserwright
-~/.local/bin/browserwright-daemon -> releases/<version>/.venv/bin/browserwright-daemon
-~/.claude/skills/browserwright    -> releases/<version>/skill
-~/.codex/skills/browserwright     -> releases/<version>/skill
-~/.pi/agent/skills/browserwright  -> releases/<version>/skill
+mise run dev-link
 ```
 
-The global install does not point at the development checkout, so broken in-progress edits do not break agents already using browserwright.
-
-Useful release commands:
-
-```bash
-browserwright release status
-browserwright release list
-browserwright release activate <version>
-mise run version-check
-```
-
-The skill bundle is intentionally a thin shell. The authoritative agent instructions come from `browserwright --print-skill`, so installed agents read docs generated by the installed CLI in the active release.
-
-For development only, `mise run dev-link` links the current checkout into global PATH and skill dirs. That is convenient for debugging but can break global agents if the checkout is broken.
+The skill bundle is intentionally a thin shell. The authoritative agent
+instructions come from `browserwright --print-skill`, so installed agents read
+docs generated by the installed CLI.
 
 ## Update the local global install
 
-Use this flow when you want the global Code Agent install on this machine to pick up the current repo state:
+Use this flow when you want the global Code Agent install on this machine to
+pick up the latest published release:
 
 ```bash
-# 1. Build a non-editable release and atomically update global symlinks.
-mise run install-release
+# 1. Install/upgrade browserwright from PyPI.
+# 2. Download the matching GitHub Release extension artifact.
+# 3. Restart the daemon and verify versions.
+mise run upgrade-global
 
-# 2. Verify the active release, CLI, daemon, generated skill, and extension metadata.
-browserwright release status
+# 4. Optional explicit verification.
 browserwright version check
 browserwright-daemon version check
-
-# 3. Restart the daemon if release status says the running daemon is stale.
-browserwright-daemon restart
 ```
 
 If the daemon is running manually instead of as the macOS LaunchAgent, restart it manually:
@@ -178,23 +156,25 @@ browserwright-daemon stop
 browserwright-daemon serve
 ```
 
-The release installer also copies the unpacked Chrome extension into the stable local load path:
+`upgrade-global` unpacks the GitHub Release asset into the stable local load
+path:
 
 ```bash
 /Users/metajs/Library/Mobile Documents/com~apple~CloudDocs/etc/chrome-extension/browserwright
 ```
 
-If `install-release` reports `reload_chrome_extension: true`, open `chrome://extensions/` and reload the `browserwright` unpacked extension from that stable path. The path does not change across releases; the installer overwrites its contents.
+If the task reports that the extension changed, open `chrome://extensions/` and
+reload the `browserwright` unpacked extension from that stable path. The path
+does not change across releases; the task overwrites its contents.
 Reload any existing tab that already shows a duplicated `👀` attach marker so
 the extension can normalize the title marker after the upgrade.
 
-## Local release discipline
+## Release discipline
 
-For local immutable release installs, `pyproject.toml` is the semver source used
-by the local build. For PyPI releases, the git tag is the source of truth and
-the publish workflow writes that version into `pyproject.toml` before building.
-The Python runtime, daemon runtime, generated skill document, and extension
-checks all read or compare against the built package version.
+For PyPI releases, the git tag is the source of truth and the publish workflow
+writes that version into `pyproject.toml` before building. The release workflow
+also writes the same tag version into `chrome-extension/manifest.json` before
+uploading `browserwright-extension-<version>.zip` to the GitHub Release.
 
 After installing a release:
 
@@ -204,7 +184,9 @@ browserwright-daemon version check
 browserwright-daemon restart   # when installed as the macOS LaunchAgent
 ```
 
-If `browserwright release install-local` reports that `chrome_extension` changed, reload the unpacked extension in Chrome from the active release's `chrome-extension/` path. Chrome does not allow this repo to refresh the extension automatically.
+Chrome does not allow this repo to refresh an unpacked extension automatically.
+If `mise run upgrade-global` reports that the extension changed, reload it in
+Chrome.
 
 ## Smoke test
 

{browserwright-0.6.9 → browserwright-0.6.12}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "browserwright"
-version = "0.6.9"
+version = "0.6.12"
 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 = [

{browserwright-0.6.9 → browserwright-0.6.12}/src/browserwright/_executor/client.py

@@ -17,6 +17,7 @@ import socket
 import time
 
 from ..errors import BrowserwrightError
+from .. import session_registry as reg
 from .protocol import (
     DEFAULT_TIMEOUT_MS,
     ExecuteRequest,
@@ -81,6 +82,12 @@ def run_on_executor(sess, code: str, *,
     connect_over_cdp + bind (moved off the control plane), which can add up to
     ~35s. The executor itself bounds the worker per-call timeout; this slack
     only prevents the CLIENT recv from giving up before the executor replies."""
+    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)
     sock_path = ensure_executor(sess)
     recv_timeout = max(timeout_ms, 1) / 1000.0 + _COLD_START_RECV_SLACK_S
     conn = _connect(sock_path, timeout=recv_timeout)

{browserwright-0.6.9 → browserwright-0.6.12}/src/browserwright/daemon/config.py

@@ -131,6 +131,7 @@ class Config:
     cdp_url: str | None = None             # BD_CDP_URL / BU_CDP_URL — env backend uses this
     chrome_binary: str | None = None       # BD_CHROME_BINARY — launch-chrome
     idle_close_after: float | None = None  # seconds; None = never (default)
+    session_idle_prune: float | None = 24 * 3600  # ledger prune threshold
     # Playwright-facing CDP facade. `serve` binds an additional TCP ws+HTTP
     # endpoint that a real Playwright client can `connect_over_cdp` to.
     #
@@ -246,6 +247,9 @@ def load(
         cfg.backends.cloud.auth = dict(auth_subtables[cfg.backends.cloud.auth_kind])
     if "idle_close_after" in toml and isinstance(toml["idle_close_after"], (int, float)):
         cfg.idle_close_after = float(toml["idle_close_after"])
+    if "session_idle_prune" in toml and isinstance(toml["session_idle_prune"], (int, float)):
+        v = float(toml["session_idle_prune"])
+        cfg.session_idle_prune = v if v > 0 else None
     # Playwright facade port (phase A1). toml key `facade_port`.
     if "facade_port" in toml and isinstance(toml["facade_port"], int):
         cfg.facade_port = toml["facade_port"]
@@ -268,6 +272,15 @@ def load(
             from .errors import UserError
             raise UserError(
                 f"BD_IDLE_CLOSE_AFTER must be a number, got {e['BD_IDLE_CLOSE_AFTER']!r}")
+    if "BD_SESSION_IDLE_PRUNE" in e:
+        try:
+            v = float(e["BD_SESSION_IDLE_PRUNE"])
+            cfg.session_idle_prune = v if v > 0 else None
+        except ValueError:
+            from .errors import UserError
+            raise UserError(
+                f"BD_SESSION_IDLE_PRUNE must be a number, got "
+                f"{e['BD_SESSION_IDLE_PRUNE']!r}")
     if "BD_CDP_WS" in e:
         cfg.cdp_ws = e["BD_CDP_WS"]; cfg.cdp_ws_source = "BD_CDP_WS"
     elif "BU_CDP_WS" in e:

{browserwright-0.6.9 → browserwright-0.6.12}/src/browserwright/daemon/server/extension_upstream.py

@@ -500,6 +500,7 @@ class ExtensionUpstream:
         group_name: str | None = "Agent",
         session_id: str | None = None,
         background: bool = True,
+        skip_post_attach_commands: bool = False,
     ) -> dict:
         """Open a background tab in the session's tab group via the relay,
         fabricate a sessionId, and return
@@ -514,7 +515,12 @@ class ExtensionUpstream:
             gid = self._relay.session_group(session_id)
         self.reset_session_announce(session_id)
         gt = await self._relay.create_background_tab(
-            url, group_name=group_name, group_id=gid, background=background)
+            url,
+            group_name=group_name,
+            group_id=gid,
+            background=background,
+            skip_post_attach_commands=skip_post_attach_commands,
+        )
         group_id = getattr(gt, "group_id", -1)
         group_id = int(group_id) if isinstance(group_id, int) else -1
         if self._group_required(

{browserwright-0.6.9 → browserwright-0.6.12}/src/browserwright/daemon/server/facade_extension.py

@@ -511,7 +511,8 @@ class ExtensionFacadeBridge:
             gt = await self._ext.open_background_tab(
                 url, group_name=group_name,
                 session_id=self._session_id,
-                background=True)
+                background=True,
+                skip_post_attach_commands=True)
             tab_id = int(gt["tabId"])
             created_group = gt.get("groupId")
             if isinstance(created_group, int) and created_group >= 0:

{browserwright-0.6.9 → browserwright-0.6.12}/src/browserwright/daemon/server/listener.py

@@ -46,6 +46,8 @@ from .facade import PlaywrightFacade
 
 logger = logging.getLogger(__name__)
 
+_SESSION_PRUNE_INTERVAL_S = 3600.0
+
 
 # ---- per-upstream context factory ------------------------------------------
 
@@ -224,8 +226,10 @@ async def run_serve(cfg: Config) -> int:
     # (Fork 4 self-exit / segfault) so the registry never accumulates corpses.
     # Upstream idle-close + executor idle-reap are gated on cfg.idle_close_after
     # inside the loop.
+    await _auto_prune_sessions(daemon, reason="startup")
     idle_task: asyncio.Task | None = asyncio.create_task(
-        _idle_watchdog(daemon, cfg.idle_close_after))
+        _idle_watchdog(daemon, cfg.idle_close_after,
+                       session_idle_prune=cfg.session_idle_prune))
     try:
         await stop.wait()
         logger.info("browserwright-daemon shutdown requested")
@@ -979,7 +983,76 @@ class _UpstreamHolder:
 # ---- graceful shutdown -----------------------------------------------------
 
 
-async def _idle_watchdog(daemon: "Daemon", idle_after: float | None) -> None:
+async def _auto_prune_sessions(daemon: "Daemon", *, reason: str) -> list[dict]:
+    """Best-effort durable ledger prune.
+
+    The session idle clock is `ledger.last_seen`, updated when a new
+    user/agent instruction arrives. Executor liveness is deliberately ignored:
+    a stuck executor can stay alive forever and must not keep a session from
+    being cleaned after the instruction-idle threshold.
+    """
+    idle_seconds = daemon.cfg.session_idle_prune
+    if not idle_seconds:
+        return []
+    try:
+        from ... import session_registry
+        stale = session_registry.stale(idle_seconds=idle_seconds)
+    except Exception as e:  # noqa: BLE001 - cleanup must not kill the daemon
+        logger.warning("auto session-prune failed (%s): %r", reason, e)
+        return []
+    pruned: list[dict] = []
+    for rec in stale:
+        sid = str(rec.get("id") or "")
+        if not sid:
+            continue
+        try:
+            daemon.executors.kill(sid)
+        except Exception as e:  # noqa: BLE001
+            logger.warning("auto session-prune executor kill failed "
+                           "(session=%s): %r", sid, e)
+        if rec.get("backend") == "rdp" and rec.get("owner") == "create":
+            try:
+                await daemon.teardown_rdp_context(sid)
+            except Exception as e:  # noqa: BLE001
+                logger.warning("auto session-prune rdp teardown failed "
+                               "(session=%s): %r", sid, e)
+        elif rec.get("backend") == "extension":
+            try:
+                runtime = rec.get("runtime") or {}
+                group_id = runtime.get("group_id")
+                group_id = (
+                    group_id
+                    if isinstance(group_id, int) and group_id >= 0
+                    else None
+                )
+                holder = daemon.shared_context.holder
+                upstream = holder.upstream
+                if hasattr(upstream, "end_session"):
+                    await upstream.end_session(sid, group_id)  # type: ignore[attr-defined]
+            except Exception as e:  # noqa: BLE001
+                logger.warning("auto session-prune extension teardown failed "
+                               "(session=%s): %r", sid, e)
+        try:
+            removed = session_registry.remove(sid)
+        except Exception as e:  # noqa: BLE001
+            logger.warning("auto session-prune ledger remove failed "
+                           "(session=%s): %r", sid, e)
+            removed = None
+        if removed is not None:
+            pruned.append(removed)
+    if pruned:
+        logger.info("auto-pruned %d idle session(s) on %s: %s",
+                    len(pruned), reason,
+                    [str(rec.get("id")) for rec in pruned])
+    return pruned
+
+
+async def _idle_watchdog(
+    daemon: "Daemon",
+    idle_after: float | None,
+    *,
+    session_idle_prune: float | None = None,
+) -> None:
     """Spec §6.5/§6.6: when configured, close each upstream after `idle_after`
     seconds with no activity. The next client command lazy-opens it again.
 
@@ -995,13 +1068,21 @@ async def _idle_watchdog(daemon: "Daemon", idle_after: float | None) -> None:
         leak a subprocess.
 
     Runs unconditionally; idle-close + idle-reap are no-ops when `idle_after`
-    is None. We poll at half the idle threshold (or every 5s when idle is off,
-    just for crash-reap granularity).
+    is None. Durable ledger prune is controlled independently by
+    `session_idle_prune`. We poll at the smallest active supervision cadence,
+    or every 5s when only crash-reap is active.
     """
-    poll = 5.0 if not idle_after else max(1.0, idle_after / 2.0)
+    cadences = [5.0]
+    if idle_after:
+        cadences.append(max(1.0, idle_after / 2.0))
+    if session_idle_prune:
+        cadences.append(_SESSION_PRUNE_INTERVAL_S)
+    poll = min(cadences)
+    last_session_prune_at = time.time()
     try:
         while True:
             await asyncio.sleep(poll)
+            now = time.time()
             # --- executor supervision (Phase B PR2) ---
             try:
                 daemon.executors.reap_dead()
@@ -1010,12 +1091,16 @@ async def _idle_watchdog(daemon: "Daemon", idle_after: float | None) -> None:
             except Exception as e:  # noqa: BLE001 - never let reap break the loop
                 logger.warning("executor reap failed: %r", e)
             # --- upstream idle-close (gated) ---
+            if session_idle_prune and (
+                    now - last_session_prune_at >= _SESSION_PRUNE_INTERVAL_S):
+                await _auto_prune_sessions(daemon, reason="watchdog")
+                last_session_prune_at = now
             if not idle_after:
                 continue
             for ctx in daemon.all_contexts():
                 if ctx.state.upstream_phase != UpstreamPhase.CONNECTED:
                     continue
-                idle_for = time.time() - ctx.state.last_activity_at
+                idle_for = now - ctx.state.last_activity_at
                 if idle_for >= idle_after:
                     logger.info("idle-watchdog: closing %s upstream after %.1fs",
                                 ctx.backend, idle_for)

{browserwright-0.6.9 → browserwright-0.6.12}/src/browserwright/daemon/server/proxy.py

@@ -1171,10 +1171,12 @@ class Router:
         # extension backend; background=False opens the tab in the foreground.
         background = params.get("background")
         background = background if isinstance(background, bool) else True
+        skip_post_attach_commands = params.get("skipPostAttachCommands") is True
         try:
             result = await self._open_background_tab(
                 url, group_name=group_name, session_id=session,
-                background=background)
+                background=background,
+                skip_post_attach_commands=skip_post_attach_commands)
         except Exception as e:
             await self._send_to_client(client.client_id, _error_response(
                 req_id, -32603, f"openBackgroundTab failed: {e!r}"))

{browserwright-0.6.9 → browserwright-0.6.12}/src/browserwright/daemon/server/relay.py

@@ -435,6 +435,7 @@ class RelayServer:
         group_name: str | None = "Agent",
         group_id: int | None = None,
         background: bool = True,
+        skip_post_attach_commands: bool = False,
         timeout: float = 10.0,
     ) -> GhostTarget:
         """Spec Phase B Feature 1: open a tab in the background (active=false)
@@ -467,6 +468,8 @@ class RelayServer:
         # is requested so existing extensions default to background.
         if not background:
             body["background"] = False
+        if skip_post_attach_commands:
+            body["skipPostAttachCommands"] = True
         result = await self._request(ext, body, timeout=timeout) or {}
         tab_id = int(result.get("tabId", -1))
         if tab_id < 0:
@@ -866,7 +869,7 @@ class RelayServer:
             # lifecycle so they can synthesize Target.targetCreated /
             # attachedToTarget for a live `connect_over_cdp` client. The agent
             # path ignores these (its `_on_event` only handles `event`).
-            await self._fanout_listeners(msg)
+            self._schedule_fanout_listeners(msg)
             return
 
         if kind == "detached":
@@ -874,7 +877,7 @@ class RelayServer:
             if tab_id < 0:
                 return
             ext.tabs.pop(tab_id, None)
-            await self._fanout_listeners(msg)
+            self._schedule_fanout_listeners(msg)
             return
 
         if kind == "response":
@@ -933,6 +936,28 @@ class RelayServer:
             except Exception as e:  # noqa: BLE001
                 logger.warning("relay fan-out listener raised: %r", e)
 
+    def _schedule_fanout_listeners(self, msg: dict) -> None:
+        """Notify secondary observers without blocking the relay reader.
+
+        An extension ``attached`` frame is often followed immediately by the
+        response to the create/attach request. Facade listeners may issue their
+        own relay requests for scoped visibility checks, so awaiting them inline
+        can deadlock the single websocket reader before it consumes the pending
+        response. Schedule the fan-out instead and keep draining extension
+        frames.
+        """
+        if not self._event_listeners:
+            return
+        task = asyncio.create_task(self._fanout_listeners(dict(msg)))
+
+        def _done(t: asyncio.Task) -> None:
+            try:
+                t.result()
+            except Exception as e:  # noqa: BLE001
+                logger.warning("relay fan-out task raised: %r", e)
+
+        task.add_done_callback(_done)
+
 
 class _CommandError(Exception):
     """Wrapped extension-side CDP error. Surfaced to the caller in

{browserwright-0.6.9 → browserwright-0.6.12}/src/browserwright/primitives/page.py

@@ -224,7 +224,12 @@ def switch_tab(target) -> dict:
     return {"targetId": target_id}
 
 
-def open(url: str = "about:blank", *, background: bool = True) -> dict:
+def open(
+    url: str = "about:blank",
+    *,
+    background: bool = True,
+    skip_post_attach_commands: bool = False,
+) -> dict:
     """Open a new working tab in this session's browser, attach, bind as
     current. The unified tab-opening primitive (docs §Tier B) — replaces
     both ``new_tab`` and ``open_background``.
@@ -246,7 +251,10 @@ def open(url: str = "about:blank", *, background: bool = True) -> dict:
     try:
         payload = sess.cdp.send(
             "BrowserwrightDaemon.openBackgroundTab",
-            url=url, bsSession=sid, background=background,
+            url=url,
+            bsSession=sid,
+            background=background,
+            skipPostAttachCommands=skip_post_attach_commands,
         )
     except CDPError as e:
         raise CDPError(
@@ -400,7 +408,7 @@ def current_page() -> dict:
         return {"targetId": tabs[0]["targetId"], "url": tabs[0]["url"],
                 "title": tabs[0]["title"], "accuracy": "unknown"}
     # 4. Empty session — open a fresh working tab (NOT adopt).
-    return open("about:blank") | {"accuracy": "unknown"}
+    return open("about:blank", skip_post_attach_commands=True) | {"accuracy": "unknown"}
 
 
 def wait(seconds: float = 1.0) -> None:

{browserwright-0.6.9 → browserwright-0.6.12}/src/browserwright/session_create.py

@@ -125,10 +125,17 @@ def reset_executor(record: dict) -> str:
 def reap(*, idle_seconds: float) -> list[dict]:
     """Prune idle sessions; for create-owned ones, also tear down the browser
     the daemon launched. Returns the pruned records."""
-    pruned = reg.prune(idle_seconds=idle_seconds)
-    for rec in pruned:
+    stale = reg.stale(idle_seconds=idle_seconds)
+    pruned: list[dict] = []
+    for rec in stale:
+        _reap_executor(rec)
+        if rec.get("backend") == "extension":
+            _end_extension_workspace(rec)
         if rec.get("owner") == "create":
             _close_browser(rec)
+        removed = reg.remove(str(rec.get("id")))
+        if removed is not None:
+            pruned.append(removed)
     return pruned
 
 

{browserwright-0.6.9 → browserwright-0.6.12}/src/browserwright/session_registry.py

@@ -124,6 +124,20 @@ def list_all() -> list[dict]:
     return [sessions[k] for k in sorted(sessions, key=int)]
 
 
+def stale(*, idle_seconds: float) -> list[dict]:
+    """Sessions idle longer than ``idle_seconds`` without removing them."""
+    now = time.time()
+    p = _ledger_path()
+    if not p.exists():
+        return []
+    sessions = json.loads(p.read_text())["sessions"]
+    records = [
+        e for e in sessions.values()
+        if now - e.get("last_seen", 0.0) >= idle_seconds
+    ]
+    return sorted(records, key=lambda e: int(e.get("id", 0)))
+
+
 def prune(*, idle_seconds: float) -> list[dict]:
     """Remove sessions idle longer than ``idle_seconds``; return removed records."""
     now = time.time()

{browserwright-0.6.9 → browserwright-0.6.12}/src/browserwright.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: browserwright
-Version: 0.6.9
+Version: 0.6.12
 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: cdp-use==1.4.5