Merge pull request #72 from vstorm-co/fixes/0.3.11

fix: browser tool

Author: DEENUU1

CHANGELOG.md

@@ -5,6 +5,19 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.11] - 2026-04-13
+
+### Fixed
+
+- **Browser opens on every message (`BrowserCapability`)** — `async_playwright()` was entered eagerly
+  at the start of `wrap_run`, spawning the Playwright Node.js driver process (which in turn opened a
+  browser window) on every agent run — even when no browser tool was ever called. The Playwright context
+  manager is now entered lazily inside the first-tool-call launcher, so runs that never use the browser
+  incur zero Playwright overhead and no browser process is started.
+- **Browser window always visible (`browser_headless` default)** — the CLI config defaulted
+  `browser_headless = false`, meaning any browser launch produced a visible Chrome window. Changed to
+  `browser_headless = true`.
+
 ## [0.3.10] - 2026-04-12
 
 ### Changed

apps/cli/config.py

@@ -109,8 +109,8 @@ class CliConfig:
     logfire: bool = False
     include_browser: bool = True
     """Enable browser automation via Playwright (requires ``pydantic-deep[browser]``)."""
-    browser_headless: bool = False
-    """Run browser without a visible window. Default ``False`` — browser window is shown."""
+    browser_headless: bool = True
+    """Run browser without a visible window. Default ``True`` — browser window is hidden."""
 
 
 def load_config(path: Path | None = None) -> CliConfig:

pydantic_deep/capabilities/browser.py

@@ -112,9 +112,10 @@ async def _auto_install_chromium() -> bool:
 class BrowserCapability(AbstractCapability[Any]):
     """Provides a real async Playwright browser to the agent.
 
-    Manages the full browser lifecycle: Chromium is launched before the agent
-    run starts (via ``wrap_run``) and closed in a ``finally`` block, guaranteeing
-    cleanup on both success and failure paths.
+    Manages the full browser lifecycle: Playwright and Chromium are started
+    lazily on the first browser-tool call and closed in a ``finally`` block,
+    guaranteeing cleanup on both success and failure paths.  Runs that never
+    invoke a browser tool incur zero Playwright overhead.
 
     Requires the ``browser`` optional extra::
 
@@ -228,10 +229,38 @@ async def prepare_tools(
                 result.append(td)
         return result
 
-    def _make_launcher(self, pw: Any) -> Any:
-        """Return an async callable that lazily launches Chromium on first tool call."""
+    async def wrap_run(
+        self,
+        ctx: RunContext[Any],
+        *,
+        handler: WrapRunHandler,
+    ) -> AgentRunResult[Any]:
+        """Install a lazy browser launcher and clean up after the run.
+
+        Both Playwright and Chromium are started only when the first browser
+        tool is actually called.  Runs that never use the browser incur zero
+        Playwright overhead — no subprocess is spawned, no browser window
+        appears.
+
+        A ``finally`` block guarantees cleanup of the browser and the
+        Playwright driver whether the run succeeds, raises, or is cancelled.
+
+        If Chromium is not installed and ``auto_install`` is ``True`` (the
+        default), ``playwright install chromium`` is run automatically on the
+        first tool call, and the launch is retried once.
+        """
+        _require_browser()
+        assert async_playwright is not None  # guaranteed by _require_browser()
+        _start_playwright = async_playwright  # local non-None reference for the closure
+
+        _pw_ctx: Any = None  # Playwright context manager — entered lazily
 
         async def _launch() -> None:
+            nonlocal _pw_ctx
+            _pw_ctx = _start_playwright()
+            pw = await _pw_ctx.__aenter__()
+            self._state.playwright_instance = pw
+
             browser = None
             try:
                 browser = await pw.chromium.launch(headless=self.headless)
@@ -278,44 +307,19 @@ def _on_popup(popup: Any) -> None:
             self._state.browser = browser
             self._state.page = page
 
-        return _launch
-
-    async def wrap_run(
-        self,
-        ctx: RunContext[Any],
-        *,
-        handler: WrapRunHandler,
-    ) -> AgentRunResult[Any]:
-        """Set up Playwright context and install a lazy browser launcher.
-
-        Chromium is **not** launched here.  Instead a launcher callable is
-        stored on ``_state._lazy_launcher`` and is invoked by
-        ``BrowserToolset._ensure_page()`` only when a browser tool is first
-        called.  Runs that never use the browser incur zero Playwright
-        overhead.
-
-        A ``finally`` block cleans up all state and closes the browser (if it
-        was ever launched) whether the run succeeds, raises, or is cancelled.
-
-        If Chromium is not installed and ``auto_install`` is ``True`` (the
-        default), ``playwright install chromium`` is run automatically on the
-        first tool call, and the launch is retried once.
-        """
-        _require_browser()
-        assert async_playwright is not None  # guaranteed by _require_browser()
-        async with async_playwright() as pw:
-            self._state.playwright_instance = pw
-            self._state._lazy_launcher = self._make_launcher(pw)
-            try:
-                return await handler()
-            finally:
-                self._state._lazy_launcher = None
-                self._state.playwright_instance = None
-                self._state.launch_error = None
-                if self._state.browser is not None:
-                    browser = self._state.browser
-                    self._state.page = None
-                    self._state.browser = None
-                    await browser.close()
-                else:
-                    self._state.page = None
+        self._state._lazy_launcher = _launch
+        try:
+            return await handler()
+        finally:
+            self._state._lazy_launcher = None
+            self._state.playwright_instance = None
+            self._state.launch_error = None
+            if self._state.browser is not None:
+                browser = self._state.browser
+                self._state.page = None
+                self._state.browser = None
+                await browser.close()
+            else:
+                self._state.page = None
+            if _pw_ctx is not None:
+                await _pw_ctx.__aexit__(None, None, None)

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pydantic-deep"
-version = "0.3.10"
+version = "0.3.11"
 description = "Batteries-included agent harness for Python — tool-calling, sandboxed execution, multi-agent teams, and unlimited context on Pydantic AI"
 readme = "README.md"
 keywords = [

tests/test_browser.py

@@ -669,6 +669,7 @@ async def handler() -> Any:
             await cap.wrap_run(_ctx(), handler=handler)
 
         assert launcher_installed is not None  # launcher was installed
+        pw.__aenter__.assert_not_called()  # Playwright driver NOT started
         pw.chromium.launch.assert_not_called()  # Chromium NOT started
         browser.close.assert_not_called()  # nothing to close
 

tests/test_cli_config.py

@@ -293,10 +293,10 @@ def test_include_browser_defaults_true(self) -> None:
         config = CliConfig()
         assert config.include_browser is True
 
-    def test_browser_headless_defaults_false(self) -> None:
-        """Browser should show a visible window by default."""
+    def test_browser_headless_defaults_true(self) -> None:
+        """Browser should run headless (no visible window) by default."""
         config = CliConfig()
-        assert config.browser_headless is False
+        assert config.browser_headless is True
 
     def test_loads_include_browser_from_file(self, tmp_path: Path) -> None:
         config_file = tmp_path / "config.toml"