ai-dev-browser 0.58.2__tar.gz → 0.58.4__tar.gz

{ai_dev_browser-0.58.2 → ai_dev_browser-0.58.4}/.github/workflows/ci.yml

@@ -167,13 +167,13 @@ jobs:
         env:
           AI_DEV_BROWSER_CHROME: ${{ steps.chrome.outputs.chrome-path }}
           AI_DEV_BROWSER_TEST_EXTENSION_CHROME: ${{ steps.chrome.outputs.chrome-path }}
-        run: xvfb-run -a -s "-screen 0 1280x1000x24" python -m pytest -v --full-trace -o faulthandler_timeout=180 tests/integration/test_remote_view.py tests/integration/test_remote_selection_live.py tests/integration/test_remote_vnc.py tests/integration/test_browser_control_live.py tests/integration/test_browser_session_live.py tests/integration/test_browser_files_live.py tests/integration/test_browser_worker_live.py tests/integration/test_existing_worker_live.py tests/integration/test_navigation_startup.py --basetemp remote-results
+        run: xvfb-run -a -s "-screen 0 1280x1000x24" python -m pytest -v --full-trace -o faulthandler_timeout=180 tests/integration/test_remote_view.py tests/integration/test_discovery_socket_pressure.py tests/integration/test_remote_selection_live.py tests/integration/test_remote_vnc.py tests/integration/test_browser_control_live.py tests/integration/test_browser_session_live.py tests/integration/test_browser_files_live.py tests/integration/test_browser_worker_live.py tests/integration/test_existing_worker_live.py tests/integration/test_navigation_startup.py --basetemp remote-results
       - name: Run page and extension workflows on Windows
         if: runner.os == 'Windows'
         env:
           AI_DEV_BROWSER_CHROME: ${{ steps.chrome.outputs.chrome-path }}
           AI_DEV_BROWSER_TEST_EXTENSION_CHROME: ${{ steps.chrome.outputs.chrome-path }}
-        run: python -m pytest -v --full-trace -o faulthandler_timeout=180 tests/integration/test_remote_view.py tests/integration/test_remote_selection_live.py tests/integration/test_browser_control_live.py tests/integration/test_browser_session_live.py tests/integration/test_browser_files_live.py tests/integration/test_browser_worker_live.py tests/integration/test_existing_worker_live.py tests/integration/test_navigation_startup.py --basetemp remote-results
+        run: python -m pytest -v --full-trace -o faulthandler_timeout=180 tests/integration/test_remote_view.py tests/integration/test_discovery_socket_pressure.py tests/integration/test_remote_selection_live.py tests/integration/test_browser_control_live.py tests/integration/test_browser_session_live.py tests/integration/test_browser_files_live.py tests/integration/test_browser_worker_live.py tests/integration/test_existing_worker_live.py tests/integration/test_navigation_startup.py --basetemp remote-results
       - name: Retain real viewer evidence
         if: always()
         uses: actions/upload-artifact@v4
@@ -193,7 +193,7 @@ jobs:
         run: docker build -f deploy/managed-chrome/Dockerfile --secret "id=extension_key,src=$RUNNER_TEMP/extension-fixture.pem" --build-arg "SOURCE_REVISION=$GITHUB_SHA" -t adb-managed-chrome:ci .
       - name: Run real signed extension, handoff and viewer workflows
         run: |
-          docker create --name "adb-managed-live-$GITHUB_RUN_ID" --memory=1536m --shm-size=256m --pids-limit=384 \
+          docker create --init --name "adb-managed-live-$GITHUB_RUN_ID" --memory=1536m --shm-size=256m --pids-limit=384 \
             --mount "type=bind,source=$PWD/tests,target=/opt/browser/tests,readonly" \
             adb-managed-chrome:ci /bin/sleep infinity
           docker start "adb-managed-live-$GITHUB_RUN_ID"
@@ -250,7 +250,7 @@ jobs:
       - name: Run the real extension on both WebSocket server implementations
         env:
           AI_DEV_BROWSER_TEST_EXTENSION_CHROME: ${{ steps.chrome.outputs.chrome-path }}
-        run: uv run --no-sync python -m pytest -v --full-trace -o faulthandler_timeout=180 tests/integration/test_cli_extension_workflows.py tests/integration/test_recording_workflows.py tests/integration/test_recording_demo.py tests/integration/test_browser_lifecycle.py tests/integration/test_remote_view.py tests/integration/test_extension_ownership.py tests/integration/test_cli_steering.py -k "real_extension or outbound_proxy" --basetemp extension-results
+        run: uv run --no-sync python -m pytest -v --full-trace -o faulthandler_timeout=180 tests/integration/test_cli_extension_workflows.py tests/integration/test_recording_workflows.py tests/integration/test_recording_demo.py tests/integration/test_browser_lifecycle.py tests/integration/test_remote_view.py tests/integration/test_extension_ownership.py tests/integration/test_cli_steering.py tests/integration/test_extension_windowless.py -k "real_extension or outbound_proxy" --basetemp extension-results
 
       - name: Install the unchanged released extension fixture
         run: uv pip install --target previous-extension-fixture --no-deps ai-dev-browser==0.57.7
@@ -261,6 +261,15 @@ jobs:
           AI_DEV_BROWSER_TEST_PREVIOUS_EXTENSION: ${{ github.workspace }}/previous-extension-fixture/ai_dev_browser/extension
         run: uv run --no-sync python -m pytest -v tests/integration/test_extension_window_previous.py --basetemp previous-extension-results
 
+      - name: Install the released extension without version reporting
+        run: uv pip install --target unknown-extension-fixture --no-deps ai-dev-browser==0.54.0
+
+      - name: Recover an unknown extension runtime through an ordinary reload
+        env:
+          AI_DEV_BROWSER_TEST_EXTENSION_CHROME: ${{ steps.chrome.outputs.chrome-path }}
+          AI_DEV_BROWSER_TEST_UNKNOWN_EXTENSION: ${{ github.workspace }}/unknown-extension-fixture/ai_dev_browser/extension
+        run: uv run --no-sync python -m pytest -v tests/integration/test_extension_runtime_upgrade.py --basetemp runtime-upgrade-results
+
       - name: Honor genuine Windows window visibility before input
         if: runner.os == 'Windows'
         env:
@@ -300,13 +309,24 @@ jobs:
             extension-results/**/extension-lifecycle.png
             extension-results/**/installed-extension.png
             extension-results/**/extension-startup-evidence.json
+            extension-results/**/windowless-startup-order.json
+            extension-results/**/windowless-extension-accepted.png
             extension-results/**/extension-chrome.log
+            extension-results/**/host-resources-*.json
+            extension-results/**/navigation-readiness.json
             extension-results/**/extension-cleanup-stacks.txt
             native-ownership-results/**
             native-window-results/**/native-window-evidence.json
             native-window-results/**/native-window-accepted.png
             native-window-results/**/extension-chrome.log
+            native-window-results/**/host-resources-*.json
+            native-window-results/**/extension-cleanup-evidence.json
+            native-window-results/**/extension-cleanup-stacks.txt
             previous-extension-results/**/previous-extension-evidence.json
+            runtime-upgrade-results/**/runtime-upgrade-evidence.json
+            runtime-upgrade-results/**/runtime-upgrade-accepted.png
+            runtime-upgrade-results/**/extension-*.json
+            runtime-upgrade-results/**/extension-chrome.log
 
   # ─────────────────────────────────────────────────────────────────────
   # CI-integration dogfood: prove the documented "consumer's CI" recipe

{ai_dev_browser-0.58.2 → ai_dev_browser-0.58.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ai-dev-browser
-Version: 0.58.2
+Version: 0.58.4
 Summary: A browser for AI to develop web automation — human-like automation that works seamlessly in a world designed for humans
 Author: sudoprivacy
 License: AGPL-3.0
@@ -94,6 +94,11 @@ python -m ai_dev_browser.tools.browser_disconnect --session-id <returned-id>
 python -m ai_dev_browser.tools.browser_reconnect --session-id <returned-id>
 ```
 
+Fresh CDP launches prepare a blank owned page before navigating once to the
+requested URL, and return that exact page. If page
+creation is uncertain, Chrome remains running; connect to the reported port and
+inspect its pages before continuing.
+
 For extension startup, first install and enable the bundled bridge in the chosen
 Chrome profile. Select `--chrome-path`, `--user-data-dir`, `--profile-directory`
 and `--headless` explicitly as needed. Startup adds neither a debugging port nor
@@ -453,11 +458,15 @@ and [GitHub Releases](https://github.com/sudoprivacy/ai-dev-browser/releases).
 Each GitHub release includes the same wheel and source distribution sent to PyPI,
 the bundled Chrome extension as an unpackable ZIP, and `SHA256SUMS`.
 For extension mode, extract the ZIP and load its directory in `chrome://extensions`.
-After upgrading, reload the extension and restart an already running bridge.
+After upgrading, ordinarily reload the extension in the intended Chrome profile,
+then reconnect with `browser_connect --transport extension`.
 `browser_connect` reports the actual loaded `extension_version`, the
 `bundled_extension_version`, and whether they match. Updating Python alone does
 not reload Chrome's extension. Reload can reset control; inspect the session and
 its owned page before resuming input.
+`extension_warning` is non-null when the loaded version is unknown or differs
+from the bundle. Follow its steps before input; `connected=true` confirms a
+connection. Version matching and actual page visibility are separate checks.
 
 For a hidden extension page, `window_set --state normal --focus` requests real
 window restoration and reports observed `visibility`, `focused`, and

{ai_dev_browser-0.58.2 → ai_dev_browser-0.58.4}/README.md

@@ -52,6 +52,11 @@ python -m ai_dev_browser.tools.browser_disconnect --session-id <returned-id>
 python -m ai_dev_browser.tools.browser_reconnect --session-id <returned-id>
 ```
 
+Fresh CDP launches prepare a blank owned page before navigating once to the
+requested URL, and return that exact page. If page
+creation is uncertain, Chrome remains running; connect to the reported port and
+inspect its pages before continuing.
+
 For extension startup, first install and enable the bundled bridge in the chosen
 Chrome profile. Select `--chrome-path`, `--user-data-dir`, `--profile-directory`
 and `--headless` explicitly as needed. Startup adds neither a debugging port nor
@@ -411,11 +416,15 @@ and [GitHub Releases](https://github.com/sudoprivacy/ai-dev-browser/releases).
 Each GitHub release includes the same wheel and source distribution sent to PyPI,
 the bundled Chrome extension as an unpackable ZIP, and `SHA256SUMS`.
 For extension mode, extract the ZIP and load its directory in `chrome://extensions`.
-After upgrading, reload the extension and restart an already running bridge.
+After upgrading, ordinarily reload the extension in the intended Chrome profile,
+then reconnect with `browser_connect --transport extension`.
 `browser_connect` reports the actual loaded `extension_version`, the
 `bundled_extension_version`, and whether they match. Updating Python alone does
 not reload Chrome's extension. Reload can reset control; inspect the session and
 its owned page before resuming input.
+`extension_warning` is non-null when the loaded version is unknown or differs
+from the bundle. Follow its steps before input; `connected=true` confirms a
+connection. Version matching and actual page visibility are separate checks.
 
 For a hidden extension page, `window_set --state normal --focus` requests real
 window restoration and reports observed `visibility`, `focused`, and

{ai_dev_browser-0.58.2 → ai_dev_browser-0.58.4}/ai_dev_browser/core/_recorder.py

@@ -17,6 +17,7 @@ import websockets
 from PIL import GifImagePlugin, Image, ImageChops, ImageOps
 
 from ._demo import Overlay, index_path
+from ._transport import _local_websocket_options
 from .errors import RecordingError
 from .recording import _read_json, _write_json
 
@@ -212,7 +213,11 @@ class _Capture:
 
 async def _record(folder: Path, config: dict, partial: Path) -> dict:
     async with websockets.connect(
-        config["url"], max_size=16 * 1024 * 1024, open_timeout=5, close_timeout=2
+        config["url"],
+        max_size=16 * 1024 * 1024,
+        open_timeout=5,
+        close_timeout=2,
+        **_local_websocket_options(config["url"]),
     ) as ws:
         capture = _Capture(ws)
         receiver = asyncio.create_task(capture.receive())
@@ -273,13 +278,23 @@ async def _record(folder: Path, config: dict, partial: Path) -> dict:
                         source, timestamp, metadata or capture.metadata
                     )
 
+            health_metrics = None
+
+            async def sample_health():
+                nonlocal health_metrics
+                while True:
+                    # A quiet page emits no frames. Check target liveness on
+                    # its own clock: a slow RPC must not stop cursor animation.
+                    health_metrics = await capture.command("Page.getLayoutMetrics")
+                    await asyncio.sleep(0.2)
+
+            tasks.append(asyncio.create_task(sample_health()))
             with partial.open("xb") as output:
                 gif = _Gif(output)
                 data, started = capture.latest
                 await asyncio.to_thread(gif.push, render(data, started), started)
                 last_frame = started
                 last_received = started
-                last_health = 0.0
                 last_state = 0.0
                 while True:
                     if (folder / "abort").exists():
@@ -289,30 +304,29 @@ async def _record(folder: Path, config: dict, partial: Path) -> dict:
                     for task in tasks:
                         if task.done():
                             task.result()
-                    now = time.monotonic()
                     requested_viewport = _read_json(folder / "viewport.json")
                     if requested_viewport != viewport:
                         await capture.command(
                             "Emulation.setDeviceMetricsOverride", requested_viewport
                         )
                         viewport = requested_viewport
-                    if now - started >= config["max_duration"]:
-                        raise RecordingError(
-                            "Recording reached max_duration before stop; no GIF published"
-                        )
-                    if now - last_health >= 0.2:
-                        # Quiet pages legitimately emit no frames. Probe the target
-                        # separately so a detached extension cannot look like idle.
-                        metrics = await capture.command("Page.getLayoutMetrics")
-                        actual = metrics["cssLayoutViewport"]
+                    if health_metrics is not None:
+                        actual = health_metrics["cssLayoutViewport"]
+                        health_metrics = None
                         if (actual["clientWidth"], actual["clientHeight"]) != (
                             viewport["width"],
                             viewport["height"],
                         ):
+                            # Keep viewport writes on this one task, including
+                            # explicit resize requests and navigation recovery.
                             await capture.command(
                                 "Emulation.setDeviceMetricsOverride", viewport
                             )
-                        last_health = now
+                    now = time.monotonic()
+                    if now - started >= config["max_duration"]:
+                        raise RecordingError(
+                            "Recording reached max_duration before stop; no GIF published"
+                        )
                     if now - last_state >= 0.5:
                         _write_json(
                             folder / "state.json",

{ai_dev_browser-0.58.2 → ai_dev_browser-0.58.4}/ai_dev_browser/core/_session.py

@@ -242,6 +242,7 @@ def describe(record: dict) -> dict:
                 "extension_version",
                 "bundled_extension_version",
                 "extension_version_matches_bundle",
+                "extension_warning",
             )
             if record.get("transport") == "extension"
         }

{ai_dev_browser-0.58.2 → ai_dev_browser-0.58.4}/ai_dev_browser/core/_transport.py

@@ -163,6 +163,17 @@ def _cdp_get_module(domain: str | types.ModuleType):
     return importlib.import_module(domain)
 
 
+def _local_websocket_options(url: str) -> dict:
+    """Keep loopback control direct on proxy-aware websockets versions."""
+    if _is_loopback_host(urlsplit(url).hostname or "") and (
+        "proxy" in inspect.signature(websockets.connect).parameters
+    ):
+        # websockets 15+ discovers environment proxies by default. Older
+        # supported versions have no proxy parameter and connect directly.
+        return {"proxy": None}
+    return {}
+
+
 class CDPConnection:
     """Async WebSocket connection to a CDP endpoint.
 
@@ -189,19 +200,11 @@ class CDPConnection:
         """Open WebSocket and start listener."""
         if self._websocket and not self._websocket.close_code:
             return  # already connected
-        options = {}
-        if _is_loopback_host(urlsplit(self.websocket_url).hostname or "") and (
-            "proxy" in inspect.signature(websockets.connect).parameters
-        ):
-            # websockets 15+ discovers environment proxies by default. Local
-            # Chrome/extension control is direct; older supported versions have
-            # no proxy parameter and already connect directly.
-            options["proxy"] = None
         self._websocket = await websockets.connect(
             self.websocket_url,
             ping_timeout=PING_TIMEOUT,
             max_size=MAX_SIZE,
-            **options,
+            **_local_websocket_options(self.websocket_url),
         )
         self._listener_task = asyncio.ensure_future(self._listener())
         await self._register_handlers()

{ai_dev_browser-0.58.2 → ai_dev_browser-0.58.4}/ai_dev_browser/core/browser.py

@@ -144,7 +144,9 @@ def _resolve_do_match(
     return env_match if env_match is not None else _proxy_in_args(extra_args)
 
 
-async def _read_navigator_language(port: int) -> str | None:
+async def _read_navigator_language(
+    port: int, target_id: str | None = None
+) -> str | None:
     """The locale actually in effect — `navigator.language` read back from the
     launched browser. Chrome maps --lang to its nearest supported UI locale, so
     this is what a site sees, which may differ from the requested locale.
@@ -156,7 +158,11 @@ async def _read_navigator_language(port: int) -> str | None:
     browser = None
     try:
         browser = await connect_browser(port=port)
-        tab = await get_active_tab(browser)
+        tab = (
+            next(t for t in browser.tabs if str(t._target.target_id) == target_id)
+            if target_id
+            else await get_active_tab(browser)
+        )
         val = await tab.evaluate("navigator.language")
         return val if isinstance(val, str) and val else None
     except Exception:
@@ -227,6 +233,9 @@ def browser_start(
     data directory returns conflict; use browser_connect instead. Startup
     changes neither installed extensions nor profile preferences. A failed
     handshake leaves the explicitly launched Chrome running and reports its PID.
+    Read extension_warning before input: an attached extension's unknown or
+    mismatched version needs an ordinary update/reload and a fresh connection.
+    Fresh CDP launches prepare their owned page before the initial URL navigation.
 
     Proxy consistency (automatic): if `extra_args` carries a `--proxy-server`
     and you don't pass an explicit `timezone`/`geo`, this auto-aligns the
@@ -267,8 +276,10 @@ def browser_start(
         reuse: "none" (always new) or "any" (reuse an idle same-profile
             Chrome, default). Only consulted for a named profile — an
             ephemeral session never reuses.
-        startup_timeout: Seconds to wait for Chrome's debug port and CDP browser
-            identity, or the configured extension handshake. `None` resolves to the
+        startup_timeout: Seconds to wait for Chrome's debug port, CDP browser
+            identity, owned page/network context and initial navigation, or
+            the extension handshake.
+            `None` resolves to the
             `AI_DEV_BROWSER_STARTUP_TIMEOUT` env var, else 30s — which
             covers cold-start on slow Windows machines (fresh profile init
             + Defender scan + I/O contention from the user's main Chrome).
@@ -506,23 +517,23 @@ def browser_start(
     from typing import Any
 
     launch_options: dict[str, Any] = {"chrome_path": chrome_path} if chrome_path else {}
+    launch_overrides = {"--no-startup-window": "", **(override_default_args or {})}
     if display is not None:
         launch_options["display"] = display
     for attempt in range(max_attempts):
         process = launch_chrome(
             port=port,
             headless=headless_resolved,
-            start_url=start_url,
+            start_url="",
             user_data_dir=str(cdp_data_dir),
             extra_args=extra_args,
-            override_default_args=override_default_args,
+            override_default_args=launch_overrides,
             silent_stderr=silent_stderr,
             stealth=stealth,
             **launch_options,
         )
 
-        # Browser identity can precede the first page on a loaded host.
-        # Wait for both read-only handshakes before reporting a usable session.
+        # Establish this process's browser identity before creating its owned page.
         bound = False
         ready_guid = None
         ready_target = None
@@ -532,10 +543,8 @@ def browser_start(
             if is_port_in_use(port=port):
                 ready_guid = _query_chrome_guid(port)
                 if ready_guid:
-                    ready_target = _query_initial_page(port)
-                    if ready_target:
-                        bound = True
-                        break
+                    bound = True
+                    break
             if process.poll() is not None:
                 stderr = process.stderr.read() if process.stderr else ""
                 if not stderr:
@@ -558,7 +567,7 @@ def browser_start(
             last_error = {
                 "error": (
                     f"Chrome started (PID {orphan_pid}) but port {port} not "
-                    f"ready with a CDP browser identity and initial page after {startup_timeout}s — process killed to "
+                    f"ready with a CDP browser identity after {startup_timeout}s — process killed to "
                     f"release profile lockfile. Retry with startup_timeout=<larger> "
                     f"if your environment is slow (Windows + main Chrome running, "
                     f"first-time profile init, AV scanning, etc.)."
@@ -584,6 +593,60 @@ def browser_start(
             continue
         return last_error
 
+    ready_target = None
+    start_options["headless"] = headless_resolved
+    spawned_args = getattr(process, "args", None)
+    if isinstance(spawned_args, (list, tuple)) and spawned_args:
+        # Preserve the executable launched when macOS reports a code-sign clone.
+        start_options["chrome_path"] = str(spawned_args[0])
+    try:
+        ready_target = _run_coro(
+            _create_startup_page(
+                port,
+                ready_guid,
+                "about:blank",
+                max(0.0, startup_timeout - (time.monotonic() - wait_started)),
+            )
+        )
+        _run_coro(
+            _prepare_startup_page(
+                port,
+                ready_target,
+                start_url,
+                max(0.0, startup_timeout - (time.monotonic() - wait_started)),
+            )
+        )
+    except Exception as error:
+        # A lost creation or navigation reply is ambiguous. Retain Chrome and
+        # the known target so reconnect can inspect the outcome.
+        registry.register_instance(
+            port=port,
+            guid=ready_guid,
+            workspace=os.getcwd(),
+            pid=process.pid,
+            user_data_dir=str(cdp_data_dir),
+        )
+        state = {
+            "transport": "cdp",
+            "port": port,
+            "pid": process.pid,
+            "browser_closed": False,
+            "user_data_dir": str(cdp_data_dir),
+            "headless": headless_resolved,
+        }
+        if ready_target:
+            state = _describe_cdp(
+                {**state, "automation_target_id": ready_target},
+                start_options=start_options,
+                guid=ready_guid,
+            )
+        return _session.failure(
+            "transient",
+            f"Chrome's initial page could not be confirmed: {str(error) or type(error).__name__}. "
+            "Reconnect and inspect its pages before continuing.",
+            **state,
+        )
+
     # Record this instance so workspace/profile discovery can find it WITHOUT
     # reading Chrome's command line over CDP (which needs --enable-automation,
     # off under stealth). Keyed later by the browser GUID from /json/version so
@@ -664,21 +727,96 @@ def browser_start(
             # the locale applied while navigator.language was unchanged). Surface
             # the requested value too when Chrome normalized it away.
             requested = identity["locale"]
-            effective = _run_coro(_read_navigator_language(port)) or requested
+            effective = (
+                _run_coro(_read_navigator_language(port, ready_target)) or requested
+            )
             result["locale"] = effective
             if effective != requested:
                 result["locale_requested"] = requested
         if egress_ip:
             result["egress_ip"] = egress_ip
-    start_options["headless"] = headless_resolved
-    spawned_args = getattr(process, "args", None)
-    if isinstance(spawned_args, (list, tuple)) and spawned_args:
-        # psutil can observe a temporary macOS code-sign clone. Restart the
-        # executable we actually launched; retain the observed path for PID checks.
-        start_options["chrome_path"] = str(spawned_args[0])
     return _describe_cdp(result, start_options=start_options, guid=ready_guid)
 
 
+async def _create_startup_page(port: int, guid: str, url: str, timeout: float) -> str:
+    """Create the one startup target on the verified browser, without replay."""
+    from ai_dev_browser.cdp import target
+    from ._transport import CDPConnection
+
+    connection = CDPConnection(f"ws://127.0.0.1:{port}/devtools/browser/{guid}")
+
+    async def create():
+        await connection.connect()
+        return str(await connection.send(target.create_target(url), timeout=timeout))
+
+    try:
+        return await asyncio.wait_for(create(), timeout=timeout)
+    finally:
+        await connection.disconnect()
+
+
+async def _prepare_startup_page(
+    port: int, target_id: str, url: str, timeout: float
+) -> None:
+    """Prepare the blank owned page, then issue the requested navigation once.
+
+    Chrome's temporary empty document can already report readyState=complete.
+    Its navigation entry has no name and no DOMContentLoaded timestamp.
+    """
+    from ai_dev_browser.cdp import network, page, runtime
+    from ._transport import CDPConnection, ProtocolException
+
+    connection = CDPConnection(f"ws://127.0.0.1:{port}/devtools/page/{target_id}")
+
+    async def wait_document(previous_loader=None):
+        while True:
+            try:
+                frame = (await connection.send(page.get_frame_tree())).frame
+                if previous_loader is not None and frame.loader_id == previous_loader:
+                    await asyncio.sleep(0.01)
+                    continue
+                result, exception = await connection.send(
+                    runtime.evaluate(
+                        "performance.getEntriesByType('navigation').some("
+                        "n => n.name && n.domContentLoadedEventEnd > 0)",
+                        return_by_value=True,
+                    )
+                )
+                if not exception and result.value is True:
+                    return
+            except ProtocolException as error:
+                # The initial navigation can replace the temporary JS context.
+                if "Execution context was destroyed" not in str(error):
+                    raise
+            await asyncio.sleep(0.01)
+
+    async def prepare():
+        await connection.connect()
+        await connection.send(page.enable())
+        # A parsed blank page can precede Chrome's profile NetworkContext.
+        # This origin-scoped CookieManager RPC waits for that context without
+        # making an HTTP request. Discard its result; no cookies are modified.
+        await asyncio.gather(
+            wait_document(),
+            connection.send(network.get_cookies(urls=[f"http://127.0.0.1:{port}/"])),
+        )
+        if url != "about:blank":
+            previous_loader = (
+                await connection.send(page.get_frame_tree())
+            ).frame.loader_id
+            _, loader, error, *_ = await connection.send(page.navigate(url))
+            if error:
+                raise ProtocolException(
+                    f"Navigation failed: {error}", method="Page.navigate"
+                )
+            await wait_document(previous_loader if loader else None)
+
+    try:
+        await asyncio.wait_for(prepare(), timeout=timeout)
+    finally:
+        await connection.disconnect()
+
+
 def _query_initial_page(port: int) -> str | None:
     """A listening browser endpoint does not prove its initial page exists."""
     import json
@@ -793,7 +931,7 @@ async def browser_connect(
     headless: bool | str | None = None,
     timeout: float = 4.0,
 ) -> dict:
-    """Use when: attaching to existing CDP or the user's real Chrome/profile via extension; returns connected, session_id and capabilities.
+    """Use when: attaching to existing CDP or real Chrome; returns session identity and extension_warning to check before input.
 
     {mode_guidance}
 
@@ -813,6 +951,9 @@ async def browser_connect(
     `bundled_extension_version`; an unknown version stays null. Updating Python
     does not reload Chrome's extension. Ordinary extension reload can reset
     control: inspect the session and original owned page before further input.
+    A non-null extension_warning means the runtime version is unknown or differs
+    from the bundle: follow its update/reload steps before input. connected=true
+    confirms the connection; actual visibility/readiness comes from window_set.
 
     Args:
         transport: "cdp" (default, existing debug Chrome) or "extension"
@@ -830,6 +971,8 @@ async def browser_connect(
         owner, profile_owner, actual headless (null if unknown), account for
         extension, port for CDP, tabs and tab_count. Includes version/git_commit
         and loaded/bundled extension versions with their observed match status.
+        extension_warning is null when versions match, otherwise actionable
+        compatibility guidance; version matching alone does not prove visibility.
 
     Failure:
         Read error_code and setup_instructions. Missing bridge/extension needs
@@ -1082,6 +1225,8 @@ async def browser_reconnect(session_id: str, timeout: float = 10.0) -> dict:
     closed page state, or repeat a click/submission. The returned identity and
     tabs confirm reconnection; inspect page/server state before continuing an
     action whose previous result was uncertain.
+    Read any extension_warning before input: a reconnected extension may still
+    need an ordinary update/reload and another explicit connection.
 
     Args:
         session_id: Identity from browser_start/browser_connect.

{ai_dev_browser-0.58.2 → ai_dev_browser-0.58.4}/ai_dev_browser/core/connection.py

@@ -680,6 +680,10 @@ async def connect_extension(session_id: str | None = None) -> BrowserClient:
     viewport override, and it follows popups/new tabs your automation opens (an
     OAuth account-chooser, a magic-link tab) while never touching your own tabs.
 
+    Before initial workflow input, call browser_connect(transport="extension")
+    and resolve any extension_warning about the actual loaded version. Bind its
+    returned session_id here; an ordinary extension reload can replace the session.
+
     Pair with `get_active_tab(browser, url_contains=...)` to pick the tab, same
     as CDP mode.
 

{ai_dev_browser-0.58.2 → ai_dev_browser-0.58.4}/ai_dev_browser/core/ext_bridge.py

@@ -39,6 +39,7 @@ from urllib.parse import parse_qs, urlsplit
 import websockets
 
 from .extension import EXTENSION_BRIDGE_PORT
+from ._transport import _local_websocket_options
 
 logger = logging.getLogger(__name__)
 
@@ -370,7 +371,8 @@ async def bridge_status(
     """Query the daemon's own state (`{extension_connected, account}`) — a status
     frame it answers without relaying to the extension. None if unreachable."""
     try:
-        async with websockets.connect(f"ws://127.0.0.1:{port}") as ws:
+        url = f"ws://127.0.0.1:{port}"
+        async with websockets.connect(url, **_local_websocket_options(url)) as ws:
             await ws.send(json.dumps({"id": 1, "method": "_bridge.status"}))
             resp = json.loads(await asyncio.wait_for(ws.recv(), timeout))
             return resp.get("result")
@@ -383,7 +385,8 @@ async def shutdown_bridge(
 ) -> bool:
     """Close this bridge's sockets through its own protocol, never its host PID."""
     try:
-        async with websockets.connect(f"ws://127.0.0.1:{port}") as ws:
+        url = f"ws://127.0.0.1:{port}"
+        async with websockets.connect(url, **_local_websocket_options(url)) as ws:
             await ws.send(
                 json.dumps(
                     {
@@ -440,7 +443,7 @@ def _launch_page(connection_or_path, request_or_headers):
     path = connection_or_path if legacy else request_or_headers.path
     if not re.fullmatch(r"/adb-launch/[a-f0-9]{32}", path):
         return None
-    body = "<!doctype html><meta charset=utf-8><title>Connecting AI Dev Browser</title><p>Waiting for the configured browser extension.</p>"
+    body = "<!doctype html><meta charset=utf-8><title>AI Dev Browser</title><p>This window is reserved for your browser task.</p>"
     if legacy:
         return (
             HTTPStatus.OK,

{ai_dev_browser-0.58.2 → ai_dev_browser-0.58.4}/ai_dev_browser/core/extension.py

@@ -32,12 +32,30 @@ def extension_version_info(loaded_version: str | None) -> dict:
     bundled = json.loads(
         (extension_dir() / "manifest.json").read_text(encoding="utf-8")
     )["version"]
+    matches = loaded_version == bundled if loaded_version else None
+    warning = None
+    if matches is not True:
+        observed = (
+            f"Loaded extension {loaded_version} differs from SDK bundle {bundled}"
+            if loaded_version
+            else f"Loaded extension version is unknown (SDK bundle {bundled})"
+        )
+        warning = (
+            f"{observed}; compatibility has not been verified. Before page input, "
+            "align the Python package and running extension with an ordinary "
+            "update/reload in chrome://extensions in the intended profile. "
+            f"This SDK's bundle is {extension_dir()}. "
+            "Python updates do not reload Chrome's extension. Then use "
+            "browser_connect --transport extension and inspect session/profile, "
+            "owned target and real visibility before resuming; reload may replace "
+            "the session. Keep Chrome and its existing tabs; do not replay "
+            "earlier submissions."
+        )
     return {
         "extension_version": loaded_version,
         "bundled_extension_version": bundled,
-        "extension_version_matches_bundle": loaded_version == bundled
-        if loaded_version
-        else None,
+        "extension_version_matches_bundle": matches,
+        "extension_warning": warning,
     }