browserwright 0.17.4__tar.gz → 0.18.0__tar.gz

{browserwright-0.17.4/src/browserwright.egg-info → browserwright-0.18.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: browserwright
-Version: 0.17.4
+Version: 0.18.0
 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).
 License-Expression: AGPL-3.0-only
 Requires-Python: >=3.11

{browserwright-0.17.4 → browserwright-0.18.0}/pyproject.toml

@@ -15,7 +15,7 @@ name = "browserwright"
 # 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.17.4"
+version = "0.18.0"
 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"
 license = "AGPL-3.0-only"

{browserwright-0.17.4 → browserwright-0.18.0}/src/browserwright/_executor/client.py

@@ -56,11 +56,9 @@ class ExecutorUnavailable(BrowserwrightError):
     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.")
+    default_fix = ("run `browserwright recover --session <id>`; it diagnoses "
+                   "the daemon, tab, and executor in order and reports the "
+                   "one layer that still needs human attention")
 
 
 @dataclass(frozen=True)
@@ -105,8 +103,8 @@ def _ensure_executor_lease(sess) -> ExecutorLease:
         )
     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"
+            "ensureExecutor returned no executor instance identity; run "
+            "`browserwright recover --session <id>` before retrying"
         )
     return ExecutorLease(session_id=sid, executor_id=executor_id)
 

{browserwright-0.17.4 → browserwright-0.18.0}/src/browserwright/_executor/process.py

@@ -269,6 +269,11 @@ class _Worker:
         self._active_globals: dict[str, Any] | None = None
         # The currently-armed facade-death handler (Fork 4).
         self._facade_death_handler: Any = None
+        # PID of the daemon whose facade produced the live Browser.  The sync
+        # Playwright driver does not dispatch ``disconnected`` while this
+        # worker is idle, so this out-of-band identity check detects a daemon
+        # replacement before we touch the stale context on the next call.
+        self._facade_daemon_pid: int | None = None
         # Persistent per-session state, injected by reference each call (Fork 5).
         self._state: dict[str, Any] = {}
         # One live-page holder shared by every injected view (snapshot /
@@ -425,7 +430,41 @@ class _Worker:
         constraint). Bind the session FIRST so ``current_session()`` /
         ``resolve_current_target()`` resolve the right ledger record."""
         if self._connected:
-            return
+            try:
+                from ..daemon import _ipc
+
+                current_daemon_pid = _ipc.ping_status_sync().pid
+            except Exception:  # noqa: BLE001 - the connect path reports details
+                current_daemon_pid = None
+            if (self._facade_daemon_pid is not None
+                    and current_daemon_pid != self._facade_daemon_pid):
+                self._on_facade_dead(self._browser)
+            # A resident executor is usually parked in ``queue.get`` between
+            # calls.  Playwright's sync driver only dispatches the browser
+            # ``disconnected`` event while a sync API call pumps its fiber, so
+            # a daemon swap can leave this flag stale until the next command.
+            # Pump once before trusting it; the armed callback then clears the
+            # old objects and this same call reconnects below.  Without this,
+            # the first post-swap command tries to bind on the dead context,
+            # times out, and the client reaps the adopted executor (losing
+            # persistent Python state).
+            try:
+                from ..repl.playwright_handle import drain_page_events
+
+                if self._context is not None:
+                    drain_page_events(self._context)
+            except Exception:  # noqa: BLE001 - liveness pump is best-effort
+                pass
+            if self._connected:
+                is_connected = getattr(self._browser, "is_connected", None)
+                try:
+                    alive = bool(is_connected()) if callable(is_connected) else True
+                except Exception:  # noqa: BLE001 - a failed probe is disconnected
+                    alive = False
+                if not alive:
+                    self._on_facade_dead()
+            if self._connected:
+                return
         from ..session import Session, set_session
         from ..session_ctx import resolve_session
 
@@ -494,6 +533,12 @@ class _Worker:
             # the previous call's list and the notice would vanish.
             warn=lambda m: self._call_warnings.append(m),
         )
+        try:
+            from ..daemon import _ipc
+
+            self._facade_daemon_pid = _ipc.ping_status_sync().pid
+        except Exception:  # noqa: BLE001 - browser connection itself is live
+            self._facade_daemon_pid = None
         self._arm_facade_death()
         # Issue #21: the live page must follow the session's current target
         # (``session_runtime.bind_target`` / ``open_session_tab`` /
@@ -692,8 +737,14 @@ class _Worker:
 
         The handler reference is retained for testability and lifecycle
         introspection."""
+        # Capture the exact connection this callback belongs to.  A
+        # disconnected event from the old daemon can be delivered late while
+        # the worker is already connecting a replacement Browser; that stale
+        # callback must not clear the newly assigned objects.
+        armed_browser = self._browser
+
         def handler(*_):
-            return self._on_facade_dead()
+            return self._on_facade_dead(armed_browser)
 
         try:
             self._browser.on("disconnected", handler)
@@ -701,14 +752,46 @@ class _Worker:
         except Exception:  # noqa: BLE001 - never let arming break cold-start
             self._facade_death_handler = None
 
-    def _on_facade_dead(self) -> None:
+    def _on_facade_dead(self, browser: Any | None = None) -> None:
+        """ADR-0013 rule 1: survive the daemon, reconnect lazily.
+
+        This used to ``os._exit(0)`` ("Fork 4"), which made every daemon
+        restart destroy every session's ``state``. Now the executor only
+        forgets its Playwright objects; the next call finds ``_connected``
+        False and re-runs :meth:`_connect_and_bind` on the same live driver —
+        the exact path a failed cold-start already retries. The replacement
+        daemon adopts this process from its discovery record, so the agent's
+        variables survive the swap. If no daemon comes back, the reconnect
+        fails with an actionable error and the flag stays False for the next
+        attempt; the daemon's idle reaper eventually retires us.
+
+        Fires on Playwright's driver thread; only flags and references are
+        touched here, never the (thread-affine) Playwright objects."""
+        if browser is not None and self._browser is not browser:
+            return
         sys.stderr.write(
             f"executor {self._session_id}: facade transport dropped "
-            "(daemon restart?); self-exiting for cold restart\n")
-        # os._exit so we don't run atexit/finalizers that might re-enter the
-        # (now dead) Playwright driver and hang. The daemon reaps us + cleans
-        # the discovery file; the next heredoc cold-starts a fresh executor.
-        os._exit(0)
+            "(daemon restart?); will reconnect on the next call\n")
+        self._connected = False
+        self._facade_death_handler = None
+        self._facade_daemon_pid = None
+        self._browser = None
+        self._context = None
+        self._page = None
+        self._live_page_holder.page = None
+        # The session's control-plane socket to the old daemon is dead too;
+        # drop it so the rebind dials the replacement instead of a corpse.
+        try:
+            from ..session import current_session
+            sess = current_session()
+            close = getattr(sess, "close", None)
+            if callable(close):
+                close()
+            invalidate = getattr(getattr(sess, "daemon", None), "invalidate", None)
+            if callable(invalidate):
+                invalidate()
+        except Exception:  # noqa: BLE001 - best-effort; the rebind re-dials
+            pass
 
     def _execute(self, req: ExecuteRequest) -> ExecuteResponse:
         """Run one code blob in the persistent namespace, capturing stdout +
@@ -871,11 +954,9 @@ class _Worker:
                 "the session's tab binding is gone (extension "
                 "reloaded/updated, daemon restarted, or the tab was closed) "
                 f"and re-binding a fresh tab failed ({failure}). The "
-                "executor recycled itself; the NEXT command re-attaches the "
-                "session automatically. If the tab is gone for good, run "
-                f"`browserwright session reset -s {sid}` first, or "
-                f"`browserwright session attach-active -s {sid}` to adopt the "
-                "tab you are looking at, then retry."
+                "executor recycled itself. Run "
+                f"`browserwright recover --session {sid}`; it re-attaches or "
+                "opens the session tab and returns healthy before you retry."
             )
             return self._finish(
                 buf, error=error, exit_code=exit_code,

{browserwright-0.17.4 → browserwright-0.18.0}/src/browserwright/cdp.py

@@ -40,9 +40,8 @@ def _rpc_error_fix(method: str, err: object) -> str:
         # breaks the deadlock; the generic -32601 hint does not apply.
         return (
             "an executor orphaned by a daemon crash may still hold this "
-            "target: run `browserwright session reset <session-id>` (or "
-            "`browserwright session end --session=<session-id>`) to reap it, "
-            "then retry"
+            "target: run `browserwright recover --session <session-id>`; it "
+            "adopts or replaces that executor without changing other sessions"
         )
     return ""
 

{browserwright-0.17.4 → browserwright-0.18.0}/src/browserwright/cli.py

@@ -30,7 +30,8 @@ Usage:
   browserwright -s <session-id> [--env NAME ...] -f script.py
   browserwright -s <session-id> [--env NAME ...] --code-stdin < script.py
 
-  browserwright session new --backend=<extension|cdp|env> --name=SESSION_LABEL [--create | --attach=PORT]
+  browserwright session new --backend=<extension|cdp> --name=SESSION_LABEL [--reuse] [--create | --attach=PORT]
+  browserwright recover --session=<id>          (the one recovery verb: exit 0 healthy, 4 needs-human)
   browserwright session reset <id>
   browserwright session end --session=ID
   browserwright session attach-active [--session=ID | -s ID] [--json]
@@ -726,6 +727,101 @@ def _cmd_memory(args: list[str]) -> int:
     return 1
 
 
+def _cmd_recover(args: list[str], *, session_id: Optional[str] = None) -> int:
+    """`browserwright recover --session <id>` — ADR-0013 rule 2, the ONE
+    thing an agent does when a call failed.
+
+    Client side first: a dead daemon cannot answer an RPC, so the daemon
+    self-check (three criteria, two agreeing probes) runs here. "Gone" or
+    "stale version" is repaired through the default endpoint's on-demand
+    start (the sanctioned restart path); "something else answers on the
+    port" and "the probes disagree" are `needs-human` because recovery never
+    signals or replaces an unidentified process. Then the daemon runs
+    the per-session ladder and reports the state reached. Exit 0 = healthy,
+    4 = needs-human, 2 = usage."""
+    kw = _parse_kv_args(args)
+    sid = kw.get("session") or session_id
+    if not sid:
+        print("usage: browserwright recover --session=<id>", file=sys.stderr)
+        return 2
+    sid = str(sid)
+    from . import session_create
+    from .daemon.launchagent import daemon_self_check
+    from .daemon_url import daemon_endpoint
+
+    steps: list[str] = []
+    ep = daemon_endpoint()
+    verdict = daemon_self_check(None)
+    if not verdict["healthy"]:
+        crit = verdict["criterion"]
+        if crit in ("gone", "version") and not ep.explicit:
+            steps.append(f"daemon: {verdict['detail']}; starting the installed one")
+            from .daemon import _ipc
+            _ipc.log_lifecycle(
+                "automatic-recovery", criterion=crit,
+                probes=",".join(verdict.get("probes") or []),
+                reason=verdict["detail"], session=sid)
+            try:
+                session_create._ensure_daemon_running()
+            except Exception as e:  # noqa: BLE001
+                return _recover_report(sid, "needs-human", steps,
+                                       f"daemon could not be started: {e}")
+            from .mode_b_client import ModeBClient
+            if not ModeBClient().wait_until_alive(timeout=20.0):
+                return _recover_report(sid, "needs-human", steps,
+                                       "no daemon answered within 20s after the "
+                                       "start; `browserwright-daemon logs` has "
+                                       "its last words")
+            steps.append("daemon: up")
+        else:
+            return _recover_report(sid, "needs-human", steps, verdict["detail"])
+    else:
+        steps.append(f"daemon: {verdict['detail']}")
+
+    import json as _json
+    import subprocess
+    try:
+        proc = subprocess.run(
+            ["browserwright-daemon", "recover", "--session", sid],
+            capture_output=True, text=True, timeout=120.0,
+            env=session_create._daemon_child_env())
+    except (OSError, subprocess.SubprocessError) as e:
+        return _recover_report(sid, "needs-human", steps,
+                               f"could not ask the daemon to recover: {e}")
+    try:
+        result = _json.loads(proc.stdout.strip().splitlines()[-1])
+        if not isinstance(result, dict):
+            raise ValueError("recover result is not an object")
+    except (ValueError, IndexError):
+        detail = ((proc.stderr or proc.stdout).strip()[:400]
+                  if proc.returncode != 0 else
+                  f"unreadable recover result: {proc.stdout[:200]!r}")
+        return _recover_report(
+            sid, "needs-human", steps,
+            detail or f"daemon recover exited {proc.returncode}")
+    if proc.returncode not in (0, 4):
+        return _recover_report(sid, "needs-human", steps,
+                               (proc.stderr or f"daemon recover exited "
+                                f"{proc.returncode}").strip()[:400])
+    for st in result.get("steps") or []:
+        steps.append(f"{st.get('rung')}: {st.get('detail')}")
+    return _recover_report(sid, result.get("state") or "needs-human", steps,
+                           result.get("reason") or "")
+
+
+def _recover_report(sid: str, state: str, steps: list[str], reason: str) -> int:
+    for line in steps:
+        print(f"  - {line}", file=sys.stderr)
+    if state == "healthy":
+        print(f"session {sid}: healthy — retry your call")
+        return 0
+    print(f"session {sid}: {state}" + (f" — {reason}" if reason else ""))
+    if state == "needs-human":
+        print("  a retry will not change this; report it with the lines above "
+              "(`browserwright doctor` has the full picture)", file=sys.stderr)
+    return 4
+
+
 def _cmd_session(args: list[str], *, session_id: Optional[str] = None) -> int:
     """``browserwright session {new|attach-active|reset|end|list|prune} ...`` (P2)."""
     from . import session_create
@@ -756,7 +852,7 @@ def _cmd_session(args: list[str], *, session_id: Optional[str] = None) -> int:
                       file=sys.stderr)
                 return 1
             print("usage: browserwright session new --backend=<extension|cdp> "
-                  "--name=SESSION_LABEL [--create | --attach=<port|url>]",
+                  "--name=SESSION_LABEL [--reuse] [--create | --attach=<port|url>]",
                   file=sys.stderr)
             print("--name is a short task-specific session label. Extension sessions "
                   "use it as the Chrome tab group title; cdp sessions use it only to "
@@ -769,11 +865,16 @@ def _cmd_session(args: list[str], *, session_id: Optional[str] = None) -> int:
             sid = session_create.new(
                 backend=backend, create=bool(kw.get("create")),
                 attach=kw.get("attach"), name=kw.get("name"),
+                reuse=bool(kw.get("reuse")),
             )
         except ValueError as e:
             print(str(e), file=sys.stderr)
             return 1
-        print(f"OK: session {sid} created", file=sys.stderr)
+        if session_create.last_new_reused == sid:
+            print(f"OK: reusing session {sid} (--reuse matched an existing "
+                  f"{backend} session named {kw.get('name')!r})", file=sys.stderr)
+        else:
+            print(f"OK: session {sid} created", file=sys.stderr)
         print(sid)  # token-frugal: bare id
         return 0
 
@@ -1110,6 +1211,8 @@ def main(argv: Optional[list[str]] = None) -> None:
         sys.exit(_cmd_session(rest, session_id=global_session))
     if cmd == "whoami":
         sys.exit(_cmd_whoami(rest, session_id=global_session))
+    if cmd == "recover":
+        sys.exit(_cmd_recover(rest, session_id=global_session))
     if cmd == "userscript":
         sys.exit(_cmd_userscript(rest, session_id=global_session))