patchright-cli 0.11.0__tar.gz → 0.11.1__tar.gz

{patchright_cli-0.11.0 → patchright_cli-0.11.1}/.claude-plugin/marketplace.json

@@ -5,7 +5,7 @@
   },
   "metadata": {
     "description": "Anti-detect browser automation CLI & Skills for AI agents, powered by Patchright",
-    "version": "0.11.0"
+    "version": "0.11.1"
   },
   "plugins": [
     {

{patchright_cli-0.11.0 → patchright_cli-0.11.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: patchright-cli
-Version: 0.11.0
+Version: 0.11.1
 Summary: Anti-detect browser automation CLI using Patchright (undetected Playwright fork)
 Project-URL: Homepage, https://github.com/AhaiMk01/patchright-cli
 Project-URL: Repository, https://github.com/AhaiMk01/patchright-cli

{patchright_cli-0.11.0 → patchright_cli-0.11.1}/docs/daemon-protocol.md

@@ -72,9 +72,29 @@ Every reply carries an explicit boolean `success` and a string `output`, on
 both success and failure. `success: false` indicates authentication, command,
 or daemon errors. `output` contains the result or a human-readable error.
 Additional fields, such as `snapshot_path`, are command-specific. Clients must
-ignore unknown fields. No structured error codes are currently provided.
+ignore unknown fields.
 
-Clients can detect these states in failed replies by matching these output
+### Error codes
+
+A failed reply in one of these states carries a string `code`. Branch on it
+rather than on `output`, whose wording can change in any release:
+
+| `code` | State |
+| --- | --- |
+| `session_not_open` | The requested session is absent. |
+| `tab_not_open` | The requested named tab is absent from the session, including one whose page closed or crashed outside the daemon. `open --tab <name>` opens it again. |
+| `target_closed` | The page, context or browser closed under the command. Also the default tab's page closed or crashed outside the daemon (a person, the page, the Host, or a renderer crash): the default tab does not move to another page on its own, so pick one with `tab-select <index>` or open one with `tab-new`. An `open` or `attach` that fails while starting a new session never carries it. A command whose own action closes its page (a popup's "Done" button) succeeds and says the page closed. |
+| `no_page` | The session is open but has no pages left, whether they were closed with `tab-close`, closed outside the daemon, or crashed. The session stays open; `tab-new` opens a page. |
+
+A page closed or crashed outside the daemon leaves the session as soon as Chrome reports it: `tab-list` stops listing it. A crashed page cannot be reloaded, since Patchright fails every later call on it, so the session closes it (in a Host Context, only a page the session opened). While the default tab has no page, `tab-close <index>` still works; `tab-close` without an index is refused rather than closing a neighbour.
+
+Other failures carry no `code`; more codes can be added later, so treat an
+unknown one like a missing one. Successful replies, including the no-ops below,
+never carry `code`. Daemons before 0.11.1 send no codes under the same
+`protocol`, so a client that may meet one keeps the output fragments below as
+its fallback.
+
+Clients can also detect these states in failed replies by matching these output
 fragments. Surrounding context and recovery advice can vary. The fragments in
 this table are part of the protocol:
 
@@ -130,17 +150,18 @@ An empty list is `[]`, and its `output` states the zero explicitly, for example
 `0 cookies in this session`. Commands not listed here send no `data`. More
 fields or commands can gain `data` later, so read only the keys you need.
 
-Best effort, not covered by the compatibility rules below: a command on a page,
-context or browser that has closed usually fails with Playwright's own message
-containing `has been closed`. That text comes from Playwright and can change
-with its version without a protocol increment.
+A command on a page, context or browser that has closed fails with
+`code: "target_closed"`. Its `output` is Playwright's own message, usually
+containing `has been closed`; that text can change with Playwright's version
+without a protocol increment, so match the code instead.
 
 ## Compatibility
 
 `protocol` is independent of the package version. Any incompatible change to
 framing, request limits, request fields (`command`, `args`, `options`, `cwd`,
-`token`), reply fields (`success`, `output`), authentication, or the
-state-detection fragments in the table above requires a protocol increment.
+`token`), reply fields (`success`, `output`), authentication, the error
+codes, or the state-detection fragments in the tables above requires a
+protocol increment. Adding an error code does not.
 Raising a request limit is not incompatible. Optional additive fields and new
 commands do not require an increment. Clients can reject unsupported protocol
 versions before sending requests.

{patchright_cli-0.11.0 → patchright_cli-0.11.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "patchright-cli"
-version = "0.11.0"
+version = "0.11.1"
 description = "Anti-detect browser automation CLI using Patchright (undetected Playwright fork)"
 license = "Apache-2.0"
 requires-python = ">=3.12"

{patchright_cli-0.11.0 → patchright_cli-0.11.1}/src/patchright_cli/__init__.py

@@ -1,3 +1,3 @@
 """patchright-cli — Undetected browser automation CLI using Patchright."""
 
-__version__ = "0.11.0"
+__version__ = "0.11.1"

{patchright_cli-0.11.0 → patchright_cli-0.11.1}/src/patchright_cli/daemon.py

@@ -30,7 +30,7 @@ from urllib.parse import unquote, urlparse
 
 from patchright_cli import daemon_pid, snapshot_text, values
 from patchright_cli.debugger import SessionDebugger
-from patchright_cli.snapshot import EMPTY_SNAPSHOT, ai_snapshot, probe_ref, save_snapshot
+from patchright_cli.snapshot import EMPTY_SNAPSHOT, ai_snapshot, is_target_closed, probe_ref, save_snapshot
 from patchright_cli.snapshot_text import SnapshotIndex, has_ref, normalize_ref, render_hits
 
 logger = logging.getLogger("patchright-cli.daemon")
@@ -106,6 +106,10 @@ class Tab:
         self.history: list[str] = []
         self.history_index: int = -1
         self.codegen: list[str] | None = None
+        # Its page closed or crashed outside the daemon. The tab stays until the
+        # next command reports it as not open, so a command still running on it
+        # never falls back to the default tab's page.
+        self.gone = False
 
 
 class Session:
@@ -147,6 +151,16 @@ class Session:
         # True when `open --webmcp` launched Chrome with the WebMCP feature on.
         self.webmcp = False
         self.current_tab: int = 0
+        # The default tab's page closed or crashed outside the daemon. Its index
+        # would otherwise slide onto a neighbour, and the next command would run
+        # on someone else's tab. Cleared only by select_page.
+        self._current_gone = False
+        # Named tabs being opened right now. Their pages arrive through the
+        # context's page event like any other; they must not become the
+        # default tab's page.
+        self._opening_named = 0
+        # A renderer crash leaves page.is_closed() False, so crashes are remembered here.
+        self._crashed: weakref.WeakSet = weakref.WeakSet()
         self.tabs: dict[str, Tab] = {DEFAULT_TAB: Tab(DEFAULT_TAB)}
         # Whether anyone actually works in the implicit default tab. A session
         # opened only through `--tab` never touches it, and an untouched default
@@ -207,10 +221,35 @@ class Session:
     async def setup_listeners(self):
         """Attach network and dialog listeners to all existing pages."""
         for page in self.pages:
+            self._watch_page(page)
             await self._attach_page_listeners(page)
         self.context.on("page", lambda page: asyncio.ensure_future(self._on_new_page(page)))
 
+    def _watch_page(self, page) -> None:
+        # Chrome reports pages a person, the page or the Host closed. A crashed
+        # page is gone too: Patchright fails every later call on it, reload
+        # included, so it is closed when the session may close it.
+        page.on("close", lambda *_: self._forget_page(page, outside=True))
+        page.on("crash", lambda *_: self._on_crash(page))
+
+    def _is_dead(self, page) -> bool:
+        return page.is_closed() or page in self._crashed
+
+    def _on_crash(self, page) -> None:
+        self._crashed.add(page)
+        self._forget_page(page, outside=True)
+        if self.may_close_page(page):
+            asyncio.ensure_future(self._close_quietly(page))
+
+    async def _close_quietly(self, page) -> None:
+        with contextlib.suppress(Exception):
+            await self._unattended(page.close())
+
     async def _on_new_page(self, page):
+        # Before any await: a popup can close (or crash) while this runs.
+        self._watch_page(page)
+        if self._is_dead(page):
+            return
         if self.uses_host_context and page not in self.own_pages:
             try:
                 opener = await page.opener()
@@ -218,9 +257,19 @@ class Session:
                 opener = None
             if opener is not None and opener in self.own_pages:
                 self.own_pages.add(page)
+        if self._is_dead(page):
+            if page in self._crashed and self.may_close_page(page):
+                # Ownership is only known now, after the crash handler ran.
+                asyncio.ensure_future(self._close_quietly(page))
+            return
         if page not in self.pages:
-            self.pages.append(page)
-            self.current_tab = len(self.pages) - 1
+            # A named tab's page belongs to that tab. While the default tab's
+            # page is gone, a new page came from some other tab. Taking either
+            # would put the default caller on someone else's tab.
+            if self._current_gone or self._opening_named:
+                self.pages.append(page)
+            else:
+                self.select_page(page)
         # Emulate before the listener setup awaits, so a popup's own scripts
         # see the session's media features as early as possible.
         await self.apply_emulation(page)
@@ -392,7 +441,7 @@ class Session:
         pinned = self.active_tab.page
         if pinned is not None:
             return pinned
-        if not self.pages:
+        if self._current_gone or not self.pages:
             return None
         idx = max(0, min(self.current_tab, len(self.pages) - 1))
         return self.pages[idx]
@@ -448,14 +497,14 @@ class Session:
         whoever activated last owned every post-await write, so a command that
         suspended came back storing its refs and history on someone else's tab.
 
-        The binding carries the session name so a tab name cannot be honoured
-        against a different session that happens to use the same name.
+        The binding carries the Session itself, so a tab cannot be honoured
+        against another session, a reopened one of the same name included. It holds
+        the Tab itself, not its name: when the tab is dropped or its name reused
+        mid-command, the command keeps working on the tab it started on.
         """
         bound = _ACTIVE_TAB.get()
-        if bound is not None and bound[0] == self.name:
-            tab = self.tabs.get(bound[1])
-            if tab is not None:
-                return tab
+        if bound is not None and bound[0] is self:
+            return bound[1]
         return self._ensure_default_tab()
 
     def _ensure_default_tab(self) -> Tab:
@@ -469,23 +518,26 @@ class Session:
     def activate_tab(self, name: str) -> Tab:
         """Route this task's state access to `name`. Raises KeyError if unknown."""
         tab = self.tabs[name]
-        _ACTIVE_TAB.set((self.name, name))
+        _ACTIVE_TAB.set((self, tab))
         return tab
 
     async def open_tab(self, name: str) -> Tab:
         """Return the named tab, giving it a fresh page on first use."""
         existing = self.tabs.get(name)
-        if existing is not None:
+        if existing is not None and not existing.gone:
             return existing
-        # _on_new_page advances current_tab for every page the context opens.
-        # A named tab owns its page outright, so letting it move that pointer
-        # would silently reassign whichever page the default caller was on.
-        previous = self.current_tab
-        page = await self.new_page()
-        if page not in self.pages:
-            self.pages.append(page)
-        self.current_tab = min(previous, max(0, len(self.pages) - 1))
+        # Leaves the default tab's page alone: whatever it does meanwhile (a
+        # close outside, a tab-select) stands.
+        self._opening_named += 1
+        try:
+            page = await self.new_page()
+        finally:
+            self._opening_named -= 1
         tab = Tab(name, page)
+        if self._is_dead(page):
+            tab.gone = True
+        elif page not in self.pages:
+            self.pages.append(page)
         self.tabs[name] = tab
         return tab
 
@@ -503,16 +555,7 @@ class Session:
         tab = self.tabs.pop(name)
         page = tab.page
         if page is not None:
-            self._console_sessions.pop(id(page), None)
-            if page in self.pages:
-                removed_index = self.pages.index(page)
-                self.pages.remove(page)
-                # Follow the page current_tab pointed at. Clamping alone silently
-                # reassigns the default caller to its neighbour when an earlier
-                # page is the one that went.
-                if removed_index < self.current_tab:
-                    self.current_tab -= 1
-            self.current_tab = max(0, min(self.current_tab, len(self.pages) - 1))
+            self._forget_page(page)
             try:
                 await self._unattended(page.close())
             except Exception:
@@ -523,13 +566,51 @@ class Session:
             self.default_in_use = False
             self._ensure_default_tab()
 
-        named = [key for key in self.tabs if key != DEFAULT_TAB]
+        named = [key for key, t in self.tabs.items() if key != DEFAULT_TAB and not t.gone]
         return bool(named) or self.default_in_use
 
+    def select_page(self, page) -> None:
+        """Make `page` the default tab's page, tracking it first if it is new."""
+        if self._is_dead(page):
+            return
+        if page not in self.pages:
+            self.pages.append(page)
+        self.current_tab = self.pages.index(page)
+        self._current_gone = False
+
+    def _forget_page(self, page, *, outside: bool = False) -> None:
+        """Stop tracking `page`. Every removal goes through here; idempotent.
+
+        `outside` means Chrome reported it closed or crashed, not that a command
+        closed it: then the default tab does not move on to another page, and a
+        named tab on it is marked gone.
+        """
+        self._console_sessions.pop(id(page), None)
+        if outside:
+            for tab in self.tabs.values():
+                if tab.page is page:
+                    tab.gone = True
+        if page not in self.pages:
+            return
+        removed_index = self.pages.index(page)
+        self.pages.remove(page)
+        if outside and removed_index == self.current_tab:
+            self._current_gone = True
+        # Follow the page current_tab pointed at. Clamping alone silently
+        # reassigns the default caller to its neighbour when an earlier page
+        # is the one that went.
+        elif removed_index < self.current_tab:
+            self.current_tab -= 1
+        self.current_tab = max(0, min(self.current_tab, len(self.pages) - 1))
+
     async def new_page(self):
         """Open a Page in this Session's context and record it as ours."""
         page = await self.context.new_page()
         self.own_pages.add(page)
+        if page in self._crashed:
+            # It crashed before it was ours, so the crash handler could not close it.
+            await self._close_quietly(page)
+            return page
         # The context's "page" handler applies this too, but runs as a task;
         # applying here means the caller never navigates an unemulated page.
         await self.apply_emulation(page)
@@ -1112,10 +1193,16 @@ class DaemonState:
         return time.monotonic() - self.last_activity > self.idle_timeout
 
     async def get_or_create_session(self, name: str = "default", **kwargs) -> Session:
-        if kwargs.get("cdp_endpoint") and kwargs.get("context_mode") == "host":
-            async with self._host_attach_lock:
-                return await self._get_or_create_session(name, **kwargs)
-        return await self._get_or_create_session(name, **kwargs)
+        try:
+            if kwargs.get("cdp_endpoint") and kwargs.get("context_mode") == "host":
+                async with self._host_attach_lock:
+                    return await self._get_or_create_session(name, **kwargs)
+            return await self._get_or_create_session(name, **kwargs)
+        except Exception as exc:
+            # A session that never got registered was never open, so there is no target to recover.
+            if is_target_closed(exc) and name not in self.sessions:
+                raise RuntimeError(f"Chrome closed while opening session '{name}': {exc}") from exc
+            raise
 
     async def _get_or_create_session(
         self,
@@ -1515,6 +1602,8 @@ async def _page_info(session: Session, cwd: str | None = None) -> dict:
     """Return standard page info + snapshot after a state-changing command."""
     page = session.page
     if page is None:
+        if session.pages:
+            return {"success": True, "output": "### Page\n- The page closed after the command."}
         return {"success": True, "output": "No page open."}
 
     url = page.url
@@ -1523,7 +1612,14 @@ async def _page_info(session: Session, cwd: str | None = None) -> dict:
     except Exception:
         title = ""
 
-    snap_path = save_snapshot(_printed(await _ai_snapshot(session, page)), cwd)
+    try:
+        snap = await _ai_snapshot(session, page)
+    except Exception as exc:
+        if not is_target_closed(exc):
+            raise
+        # The command's own action closed the page (a popup's "Done" button). It ran, so this is no failure.
+        return {"success": True, "output": f"### Page\n- Page URL: {url}\n- The page closed after the command."}
+    snap_path = save_snapshot(_printed(snap), cwd)
 
     output_lines = [
         "### Page",
@@ -1791,9 +1887,20 @@ def _error_message(cmd: str, args: list, options: dict, exc: Exception) -> tuple
     return message, []
 
 
+# Stable `code` values on failed replies (docs/daemon-protocol.md). Clients branch
+# on these instead of on `output`, whose wording can change in any release.
+SESSION_NOT_OPEN = "session_not_open"
+TAB_NOT_OPEN = "tab_not_open"
+TARGET_CLOSED = "target_closed"
+NO_PAGE = "no_page"
+
+
 def _error_reply(cmd: str, args: list, options: dict, exc: Exception, *extra: str) -> dict:
     message, helps = _error_message(cmd, args, options, exc)
-    return {"success": False, "output": "\n".join([f"Error: {message}", *extra, *helps])}
+    reply = {"success": False, "output": "\n".join([f"Error: {message}", *extra, *helps])}
+    if is_target_closed(exc):
+        reply["code"] = TARGET_CLOSED
+    return reply
 
 
 @register("click")
@@ -1969,6 +2076,8 @@ async def cmd_snapshot(session: Session, page, args: list, options: dict, cwd: s
         try:
             matches = await scoped.count()
         except Exception as exc:
+            if is_target_closed(exc):
+                raise
             return {"success": False, "output": f"Invalid selector {selector!r}: {exc}"}
         if not matches:
             return {"success": False, "output": f"No element matches {selector!r} on this page."}
@@ -2068,6 +2177,8 @@ async def _find_by_role(session: Session, page, role: str, options: dict, limit:
     try:
         total = await locator.count()
     except Exception as exc:
+        if is_target_closed(exc):
+            raise
         return {"success": False, "output": f"find {query} failed: {exc}"}
     if not total:
         return {
@@ -2499,6 +2610,8 @@ async def cmd_html(session: Session, page, args: list, options: dict, cwd: str |
         try:
             matches = await scoped.count()
         except Exception as exc:
+            if is_target_closed(exc):
+                raise
             return {"success": False, "output": f"Invalid selector {selector!r}: {exc}"}
         if matches != 1:
             if not matches:
@@ -2634,6 +2747,7 @@ async def cmd_tab_new(session: Session, page, args: list, options: dict, cwd: st
     url = args[0] if args else "about:blank"
     await session.check_navigation(url, _web_only(options))
     new_page = await session.new_page()
+    session.select_page(new_page)
     if url and url != "about:blank":
         await session.goto(new_page, url, _web_only(options))
     return await _page_info(session, cwd)
@@ -2641,6 +2755,11 @@ async def cmd_tab_new(session: Session, page, args: list, options: dict, cwd: st
 
 @register("tab-close")
 async def cmd_tab_close(session: Session, page, args: list, options: dict, cwd: str | None, state: DaemonState) -> dict:
+    if not session.pages:
+        return _no_page_reply()
+    if not args and session.page is None:
+        # current_tab already points at a neighbour; closing it would close someone else's tab.
+        return _gone_reply()
     idx = int(args[0]) if args else session.current_tab
     if not (0 <= idx < len(session.pages)):
         return {"success": False, "output": f"Invalid tab index: {idx}"}
@@ -2658,11 +2777,7 @@ async def cmd_tab_close(session: Session, page, args: list, options: dict, cwd:
         await session.close_tab(owner)
         return {"success": True, "output": f"Tab {idx} closed (was tab '{owner}')."}
 
-    session.pages.pop(idx)
-    session._console_sessions.pop(id(page), None)
-    if idx < session.current_tab:
-        session.current_tab -= 1
-    session.current_tab = max(0, min(session.current_tab, len(session.pages) - 1))
+    session._forget_page(page)
     await page.close()
     return {"success": True, "output": f"Tab {idx} closed."}
 
@@ -2683,7 +2798,7 @@ async def cmd_tab_select(
         }
     idx = int(args[0])
     if 0 <= idx < len(session.pages):
-        session.current_tab = idx
+        session.select_page(session.pages[idx])
         await session.pages[idx].bring_to_front()
         return await _page_info(session, cwd)
     return {"success": False, "output": f"Invalid tab index: {idx}"}
@@ -4089,6 +4204,8 @@ _WEBMCP_UNTRUSTED = "Tool names, descriptions, schemas and results are page-prov
 
 def _webmcp_error(exc: Exception) -> dict:
     """A WebMCP failure as a reply: Playwright's first line, without its `WebMCP.tools: ` prefix."""
+    if is_target_closed(exc):
+        raise exc
     message = str(exc).strip().splitlines()[0] if str(exc).strip() else type(exc).__name__
     message = re.sub(r"^WebMCP\.\w+: ", "", message)
     if "WebMCP is not enabled" in message:
@@ -4274,6 +4391,30 @@ async def cmd_debugger_status(
 
 # Commands that end a Session run its teardown unattended (see SessionDebugger),
 # so they must not be held at a pause themselves.
+def _no_page_reply() -> dict:
+    """The session is open but has no pages left."""
+    return {
+        "success": False,
+        "output": "No page open. Run 'tab-new' to create one, or 'close' and 'open' again.",
+        "code": NO_PAGE,
+    }
+
+
+def _gone_reply() -> dict:
+    """The default tab's page closed or crashed outside the daemon, and no page took its place."""
+    return {
+        "success": False,
+        "output": (
+            "This tab's page closed or crashed outside the daemon.\n"
+            "help: run `tab-list`, then `tab-select <index>`, or `tab-new [url]`"
+        ),
+        "code": TARGET_CLOSED,
+    }
+
+
+# Commands that run without a current page: the tab ones get a page back, and
+# console reads the session-wide buffer, which outlives the page that closed.
+_PAGELESS = frozenset({"tab-new", "tab-select", "tab-list", "tab-close", "console"})
 _NOT_HELD = {"close", "close-all", "kill-all", "detach", "delete-data", "list", "profile-list"}
 
 
@@ -4368,6 +4509,8 @@ async def _dispatch_command(state: DaemonState, msg: dict) -> dict:
                 session.default_in_use = True
                 session._ensure_default_tab()
             session.activate_tab(tab_name)
+            if session.page is None and session.pages:
+                return _gone_reply()
             if session.page:
                 session.push_history(session.page.url)
             return await _page_info(session, cwd)
@@ -4482,6 +4625,7 @@ async def _dispatch_command(state: DaemonState, msg: dict) -> dict:
             return {
                 "success": False,
                 "output": f"Session '{session_name}' is not open. Run 'open' first.",
+                "code": SESSION_NOT_OPEN,
             }
 
         page = session.page
@@ -4534,6 +4678,8 @@ async def _dispatch_command(state: DaemonState, msg: dict) -> dict:
         # Route to the caller's tab last, so it cannot shadow an unknown command
         # or the page-less commands above, and re-read the page afterwards --
         # activation is what decides which page `session.page` resolves to.
+        if tab_name in session.tabs and session.tabs[tab_name].gone is True:
+            del session.tabs[tab_name]
         if tab_name not in session.tabs:
             return {
                 "success": False,
@@ -4541,19 +4687,19 @@ async def _dispatch_command(state: DaemonState, msg: dict) -> dict:
                     f"Tab '{tab_name}' is not open in session '{session_name}'. "
                     f"Run `patchright-cli --tab {tab_name} open <url>` first."
                 ),
+                "code": TAB_NOT_OPEN,
             }
         session.activate_tab(tab_name)
         page = session.page
 
-        if page is None:
-            return {
-                "success": False,
-                "output": "No page open. Run 'tab-new' to create one, or 'close' and 'open' again.",
-            }
-
-        await _apply_timeouts(page, options)
+        if page is None and session.pages and cmd not in _PAGELESS:
+            return _gone_reply()
+        if page is None and cmd not in _PAGELESS:
+            return _no_page_reply()
 
-        await _draw_action_callout(session, page, cmd, args)
+        if page is not None:
+            await _apply_timeouts(page, options)
+            await _draw_action_callout(session, page, cmd, args)
         result = await handler(session, page, args, options, cwd, state)
         if result.get("success") and session._codegen is not None and cmd in _CODEGEN_RECORDABLE:
             args_quoted = [f'"{a}"' if " " in a else a for a in args]

{patchright_cli-0.11.0 → patchright_cli-0.11.1}/src/patchright_cli/mcp_server.py

@@ -24,6 +24,8 @@ from fastmcp.tools import ToolResult
 from mcp.types import ImageContent
 from pydantic import Field
 
+from patchright_cli import values
+
 CLI = (sys.executable, "-m", "patchright_cli")
 DAEMON_PORT = int(os.environ.get("PATCHRIGHT_CLI_MCP_DAEMON_PORT", "9321"))
 # File paths given to tools must sit beneath MCP_ROOT, so an MCP client (possibly
@@ -220,6 +222,7 @@ TOOL_SPECS = {
         "description": "CLI command: snapshot Capture an accessibility snapshot and refresh element references.",
         "params": [
             ("ref", "string", False, "", "Optional element reference for a subtree."),
+            ("selector", "string", False, "", "Optional CSS selector of the one element to print; not with ref."),
             ("filename", "string", False, "", "Optional output file."),
             ("depth", "number", False, 0, "Maximum snapshot depth; zero means unlimited."),
             ("interactive", "boolean", False, False, "Return interactive elements only."),
@@ -286,7 +289,8 @@ TOOL_SPECS = {
         ],
     },
     "patchright_drop": {
-        "description": "CLI command: drop Drop a file or data payload onto an element.",
+        "description": "CLI command: drop Drop a file or data payload onto an element. Fails when the target does not "
+        "accept drops (its dragover handler must call preventDefault()).",
         "params": [
             ("ref", "string", True, None, "Target element reference."),
             ("path", "string", False, "", "File path."),
@@ -794,9 +798,16 @@ TOOL_SPECS = {
         ],
     },
     "patchright_console": {
-        "description": "CLI command: console Return captured browser console messages.",
+        "description": "CLI command: console Return captured browser console messages. The first call starts "
+        "session-wide CDP capture, which pages can detect; messages from before it are unavailable.",
         "params": [
-            ("level", "string", False, "", "Optional level: debug, info, log, warning or error."),
+            (
+                "level",
+                "string",
+                False,
+                None,
+                "Level to filter by, e.g. error, warning, info or log; empty for every level.",
+            ),
             ("clear", "boolean", False, False, "Clear messages after reading."),
             ("session", "string", False, "default", "Named Patchright browser session."),
         ],
@@ -840,7 +851,8 @@ TOOL_SPECS = {
         ],
     },
     "patchright_highlight": {
-        "description": "CLI command: highlight Show, style or hide a page highlight overlay.",
+        "description": "CLI command: highlight Show, style or hide a page highlight overlay. The page can detect the "
+        "overlay while it is shown; hiding the last highlight removes it.",
         "params": [
             ("ref", "string", False, "", "Element reference; optional with hide=true, which then clears all."),
             ("style", "string", False, "", "Optional CSS style."),
@@ -1260,9 +1272,13 @@ def _build_args(name: str, p: dict[str, Any]) -> list[str]:
 
     if name == "patchright_snapshot":
         _validate_cli_path(p["filename"])
+        if p["ref"] and p["selector"]:
+            raise ValueError("Give either ref or selector, not both")
         args = ["snapshot"]
         if p["ref"]:
             args.append(_V(p["ref"]))
+        if p["selector"]:
+            args.append(f"--selector={p['selector']}")
         if p["filename"]:
             args.append(f"--filename={p['filename']}")
         if p["depth"] != 0:
@@ -1616,6 +1632,9 @@ def _parameter_type(tool_name: str, param_name: str, type_name: str) -> Any:
     if tool_name == "patchright_network_state_set" and param_name == "state":
         return Literal["online", "offline"]
 
+    if tool_name == "patchright_console" and param_name == "level":
+        return Literal[("", *values.CONSOLE_LEVELS)] | None
+
     if tool_name in _EMULATION_VALUES and param_name == "value":
         return Literal[_EMULATION_VALUES[tool_name]]
 

{patchright_cli-0.11.0 → patchright_cli-0.11.1}/src/patchright_cli/snapshot.py

@@ -17,6 +17,16 @@ from patchright_cli.snapshot_text import REF_TAG
 EMPTY_SNAPSHOT = "# Empty page - no accessible elements found\n"
 
 
+def is_target_closed(exc: Exception) -> bool:
+    """The page, context or browser closed under the command.
+
+    Patchright raises every driver-reported close as TargetClosedError, matched
+    by name because Patchright is imported lazily. Never by message: a page's
+    own error can say "has been closed".
+    """
+    return type(exc).__name__ == "TargetClosedError"
+
+
 async def ai_snapshot(page, boxes: bool = False) -> str:
     """The full page's AI snapshot, iframes included. Refreshes the page's ref map.
 
@@ -24,7 +34,9 @@ async def ai_snapshot(page, boxes: bool = False) -> str:
     """
     try:
         return await page.aria_snapshot(mode="ai", boxes=True if boxes else None)
-    except Exception:
+    except Exception as exc:
+        if is_target_closed(exc):
+            raise
         return ""
 
 

{patchright_cli-0.11.0 → patchright_cli-0.11.1}/tests/test_attach.py

@@ -15,6 +15,7 @@ def _fake_page(url="https://example.com", opener=None):
     page.close = AsyncMock()
     page.goto = AsyncMock()
     page.opener = AsyncMock(return_value=opener)
+    page.is_closed = MagicMock(return_value=False)
     return page