agentenv-framework-protocol 0.1.480__tar.gz → 0.1.481__tar.gz

{agentenv_framework_protocol-0.1.480 → agentenv_framework_protocol-0.1.481}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentenv-framework-protocol
-Version: 0.1.480
+Version: 0.1.481
 Summary: Open data-plane protocol and server SDK for agent environments.
 Project-URL: Homepage, https://www.agentenvframework.com
 Project-URL: Documentation, https://www.agentenvframework.com/docs
@@ -945,14 +945,14 @@ under the session user's home (`.config/chromium` by default), whose contents fr
 are the profile's template. The base class adds:
 
 - **Its settings**, `BrowserSettings`, which a subclass's `Settings` extends: `start_urls`, opened in
-  tabs at launch, the first active (`["about:blank"]` by default; none may start with `-`), headless
-  the first from its command line and the rest over its pipe, since headless Chromium takes one; `window`,
+  tabs at launch, the first active (`["about:blank"]` by default; none may start with `-`); `window`,
   1280 × 800, alone only; `locale`; `time_zone`, set as `TZ` in its launch's `env`; `geolocation` and
   `notifications`, `deny` (the default), which answers a page's prompt for it, or `ask`; and `dialogs`, who
   answers a page's JavaScript dialogs: `agent` (the default), or agentenv, accepting (`accept`, a `prompt()`
   with its default text) or dismissing (`dismiss`) each. Either way agentenv leaves a page that asks before
   it's left (`beforeunload`), so none of its answers blocks a navigation.
-- **The flags agentenv owns**, after the subclass's command and before the start tabs: its profile, its
+- **The flags agentenv owns**, after the subclass's command and before `about:blank`, the one tab its command line
+  opens: its profile, its
   HTTP cache under `~/.cache` (`--disk-cache-dir`), `--remote-debugging-pipe`, `--no-first-run`,
   `--no-default-browser-check`, `--lang` and, when `/dev/shm` holds under 1 GiB (Docker gives 64 MiB),
   `--disable-dev-shm-usage`, so it keeps its shared memory in files. With
@@ -1011,6 +1011,8 @@ are the profile's template. The base class adds:
   - `files/choose {paths}`, files in `~/Uploads` for the file chooser open on it, which headless, and so
     alone, it intercepts;
   - `page/state`, the active tab's id, URL and title and the dialog or file chooser open on it.
+  - `sites/set {sites}`, the env's own sites, each `{name, domains}`, a `*.` domain matching one label more, which
+    the deploy hands it before it launches the browser and its server keeps for every launch after.
   - `cookies/get {urls?}`, `cookies/set {cookies}` and `cookies/delete {name?, domain?, path?}`, on its default
     context, each cookie as Playwright's `storageState` has it, CDP's `Network.Cookie` fields (`name`, `value`,
     `domain`, `path`, `expires`, `httpOnly`, `secure`, `sameSite`), so a storage state exported from Playwright loads
@@ -1033,9 +1035,26 @@ are the profile's template. The base class adds:
     under the `write_namespace` grant when there is one, else inline, as `data/get` returns files. Inline, the whole
     file is read into memory and sent base64 in one answer, so a large one belongs under a grant.
 
+  **Start tabs.** At each launch its start tabs open over its pipe, in a computer and alone alike: the first in the
+  blank tab its command line opened, the rest in tabs it opens blank after it, each held to the window's size
+  (headless) before it goes to its URL, so its page sees that size from its first script; then the first is brought
+  to the front. They load at once, and each settles once it has loaded (its load event fired, its document's final
+  status read), once it failed (a network error, or on one of the env's sites, as `sites/set` named them, a 4xx or
+  5xx status, which settles it at once), or once it has been waited on: every one settles within the browser's
+  ready timeout of its launch, the launch's setup counted against it, a tab on one of the env's sites waited on what's
+  left of it and any other on 30 s at most, so `data/reset`, a load and a deploy, which wait that timeout and a margin,
+  always get its outcome. Its `start_tabs_loaded` ready check passes once all have settled, so `cdp` and a deploy wait
+  for them. `record`'s `start_tabs` keeps each launch's (`StartTabsLaunch`: `at` and its
+  `tabs`, each a `StartTab`: `tab`, `url`, `final_url`, `status`, `error`, `load_ms`, `site` — the env's site's
+  name, null for a live one — and `outcome`, `loaded`, `failed` or `timed_out`), and `data/get`'s state keeps its
+  latest launch's. A deploy of a computer reads them once it's ready, keeps them in its record and fails, naming
+  each, if one on the env's sites didn't load; `data/reset` and a load that opens the start tabs again fail
+  the same way, while a server's restart only records it.
+
   The browser's data plane is a file tree, every file by its path under the session user's home:
   - `data/get` returns its state as `browser-state.json` (`BrowserState`: `cookies` and `local_storage`
-    as above, `tabs`, `closed_tabs`, `downloads` and `clock`, `real` with its `now`); its profile's files,
+    as above, `tabs`, `closed_tabs`, `downloads`, `clock`, `real` with its `now`, and `start_tabs`); its
+    profile's files,
     each database with its journal or log, copied in one pass with the browser paused once its state is
     read, so the files are of one moment, without caches (`Cache`, `Code Cache`,
     `GPUCache`, the shader and Dawn caches, `CacheStorage`, `ScriptCache`, `Crashpad`) or locks

{agentenv_framework_protocol-0.1.480 → agentenv_framework_protocol-0.1.481}/README.md

@@ -880,14 +880,14 @@ under the session user's home (`.config/chromium` by default), whose contents fr
 are the profile's template. The base class adds:
 
 - **Its settings**, `BrowserSettings`, which a subclass's `Settings` extends: `start_urls`, opened in
-  tabs at launch, the first active (`["about:blank"]` by default; none may start with `-`), headless
-  the first from its command line and the rest over its pipe, since headless Chromium takes one; `window`,
+  tabs at launch, the first active (`["about:blank"]` by default; none may start with `-`); `window`,
   1280 × 800, alone only; `locale`; `time_zone`, set as `TZ` in its launch's `env`; `geolocation` and
   `notifications`, `deny` (the default), which answers a page's prompt for it, or `ask`; and `dialogs`, who
   answers a page's JavaScript dialogs: `agent` (the default), or agentenv, accepting (`accept`, a `prompt()`
   with its default text) or dismissing (`dismiss`) each. Either way agentenv leaves a page that asks before
   it's left (`beforeunload`), so none of its answers blocks a navigation.
-- **The flags agentenv owns**, after the subclass's command and before the start tabs: its profile, its
+- **The flags agentenv owns**, after the subclass's command and before `about:blank`, the one tab its command line
+  opens: its profile, its
   HTTP cache under `~/.cache` (`--disk-cache-dir`), `--remote-debugging-pipe`, `--no-first-run`,
   `--no-default-browser-check`, `--lang` and, when `/dev/shm` holds under 1 GiB (Docker gives 64 MiB),
   `--disable-dev-shm-usage`, so it keeps its shared memory in files. With
@@ -946,6 +946,8 @@ are the profile's template. The base class adds:
   - `files/choose {paths}`, files in `~/Uploads` for the file chooser open on it, which headless, and so
     alone, it intercepts;
   - `page/state`, the active tab's id, URL and title and the dialog or file chooser open on it.
+  - `sites/set {sites}`, the env's own sites, each `{name, domains}`, a `*.` domain matching one label more, which
+    the deploy hands it before it launches the browser and its server keeps for every launch after.
   - `cookies/get {urls?}`, `cookies/set {cookies}` and `cookies/delete {name?, domain?, path?}`, on its default
     context, each cookie as Playwright's `storageState` has it, CDP's `Network.Cookie` fields (`name`, `value`,
     `domain`, `path`, `expires`, `httpOnly`, `secure`, `sameSite`), so a storage state exported from Playwright loads
@@ -968,9 +970,26 @@ are the profile's template. The base class adds:
     under the `write_namespace` grant when there is one, else inline, as `data/get` returns files. Inline, the whole
     file is read into memory and sent base64 in one answer, so a large one belongs under a grant.
 
+  **Start tabs.** At each launch its start tabs open over its pipe, in a computer and alone alike: the first in the
+  blank tab its command line opened, the rest in tabs it opens blank after it, each held to the window's size
+  (headless) before it goes to its URL, so its page sees that size from its first script; then the first is brought
+  to the front. They load at once, and each settles once it has loaded (its load event fired, its document's final
+  status read), once it failed (a network error, or on one of the env's sites, as `sites/set` named them, a 4xx or
+  5xx status, which settles it at once), or once it has been waited on: every one settles within the browser's
+  ready timeout of its launch, the launch's setup counted against it, a tab on one of the env's sites waited on what's
+  left of it and any other on 30 s at most, so `data/reset`, a load and a deploy, which wait that timeout and a margin,
+  always get its outcome. Its `start_tabs_loaded` ready check passes once all have settled, so `cdp` and a deploy wait
+  for them. `record`'s `start_tabs` keeps each launch's (`StartTabsLaunch`: `at` and its
+  `tabs`, each a `StartTab`: `tab`, `url`, `final_url`, `status`, `error`, `load_ms`, `site` — the env's site's
+  name, null for a live one — and `outcome`, `loaded`, `failed` or `timed_out`), and `data/get`'s state keeps its
+  latest launch's. A deploy of a computer reads them once it's ready, keeps them in its record and fails, naming
+  each, if one on the env's sites didn't load; `data/reset` and a load that opens the start tabs again fail
+  the same way, while a server's restart only records it.
+
   The browser's data plane is a file tree, every file by its path under the session user's home:
   - `data/get` returns its state as `browser-state.json` (`BrowserState`: `cookies` and `local_storage`
-    as above, `tabs`, `closed_tabs`, `downloads` and `clock`, `real` with its `now`); its profile's files,
+    as above, `tabs`, `closed_tabs`, `downloads`, `clock`, `real` with its `now`, and `start_tabs`); its
+    profile's files,
     each database with its journal or log, copied in one pass with the browser paused once its state is
     read, so the files are of one moment, without caches (`Cache`, `Code Cache`,
     `GPUCache`, the shader and Dawn caches, `CacheStorage`, `ScriptCache`, `Crashpad`) or locks

{agentenv_framework_protocol-0.1.480 → agentenv_framework_protocol-0.1.481}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agentenv-framework-protocol"
-version = "0.1.480"
+version = "0.1.481"
 description = "Open data-plane protocol and server SDK for agent environments."
 readme = "README.md"
 license = "Apache-2.0"

{agentenv_framework_protocol-0.1.480 → agentenv_framework_protocol-0.1.481}/src/agentenv_protocol/computer/app.py

@@ -446,7 +446,7 @@ class ComputerAppEnvironment(AgentEnvEnvironment):
         self._computer_app_data = AppDataPlane(
             self._computer_app, {op: getattr(self, name) for op, name in cls._data_hooks.items()}, self.paths,
             cls.data_timeout_s, live=cls.data_live, keeps_paths=cls.data_keeps_paths,
-            resets_failed_add=self._resets_failed_add)
+            resets_failed_add=self._resets_failed_add, relaunched=self._relaunched)
 
     def _launch_for(self, launch: Launch) -> Launch:
         """The launch its server uses, from the one declared for its OS, whose ``ready`` timeout it keeps: as
@@ -473,6 +473,9 @@ class ComputerAppEnvironment(AgentEnvEnvironment):
         """Whether a load that fails is followed by a reset, so the app isn't left half loaded: always."""
         return True
 
+    async def _relaunched(self, op: str) -> None:
+        """What a data call that stopped the app, ``op``, awaits once it has launched it again: nothing."""
+
     @classmethod
     def settings_on(cls, os_type: Optional[str]) -> type[BaseModel]:
         """Its ``Settings`` on ``os_type``, with the fields its OS adds."""

{agentenv_framework_protocol-0.1.480 → agentenv_framework_protocol-0.1.481}/src/agentenv_protocol/computer/app_data.py

@@ -11,7 +11,7 @@ import inspect
 import logging
 import shutil
 import tempfile
-from collections.abc import Callable
+from collections.abc import Awaitable, Callable
 from pathlib import Path, PurePosixPath
 from typing import TYPE_CHECKING, Any, Optional
 
@@ -41,7 +41,8 @@ class AppDataPlane:
 
     def __init__(self, runtime: AppRuntime, hooks: dict[str, Callable], paths: list[str], timeout_s: float, *,
                  live: frozenset[str] = frozenset(), keeps_paths: bool = False,
-                 resets_failed_add: Callable[[], bool] = lambda: True) -> None:
+                 resets_failed_add: Callable[[], bool] = lambda: True,
+                 relaunched: Optional[Callable[[str], Awaitable[None]]] = None) -> None:
         self.runtime = runtime
         self.hooks = hooks
         self.paths = paths
@@ -49,6 +50,8 @@ class AppDataPlane:
         #: The operations served on the running app; whether a hook's reset needs the paths as installed; and whether
         #: a load that fails is followed by a reset now.
         self.live, self.keeps_paths, self.resets_failed_add = live, keeps_paths, resets_failed_add
+        #: What a call that stopped the app awaits once it has launched it again, whose error fails the call.
+        self.relaunched = relaunched
         self.turn = asyncio.Lock()
         self.changing: set[asyncio.Task] = set()
 
@@ -99,6 +102,8 @@ class AppDataPlane:
             finally:
                 if running:
                     await self.runtime.launch_app(_CAUSES[op])
+            if running and self.relaunched is not None:
+                await self.relaunched(op)
         except Exception as e:
             if not answer.done():
                 answer.set_exception(e)

agentenv_framework_protocol-0.1.481/src/agentenv_protocol/website_browser/__init__.py

@@ -0,0 +1,25 @@
+"""WebsiteBrowserEnvironment: a website browser as a computer app, run inside a computer or alone. A subclass says how
+its build installs and starts; this class adds what agentenv owns, the same in both: its flags after the subclass's
+command, the unattended-use policies, a CDP connection over the browser's debugging pipe, the settings every browser
+takes, a fresh cache and the deploy's prompt answers at every launch, another window for a launch while it runs, its
+skill and ``browser/v1`` on its card. It runs alone, headless, on a computer with no display, a browser computer's,
+whose screen is its page; which site proxy it goes through comes from a variable agentenv sets, never from its
+settings."""
+from .control import (ACTIVE_CHECK_TIMEOUT_S, AGENT, AGENTENV, CAPTURE_TIMEOUT_S, DOWNLOADS, EXIT, FAILED,
+                      HASH_CHUNK_BYTES, LIVE_START_TAB_TIMEOUT_S, LOADED, PAGE_INPUT, PAGES, PIN_TIMEOUT_S, STOP,
+                      TIMED_OUT, UNKNOWN, UNNAVIGATED_CAPTURE_TIMEOUT_S, UPLOADS, BrowserControl)
+from .devtools import MAX_MESSAGE_BYTES, PIPE_IN, PIPE_OUT, DevToolsError, DevToolsPipe
+from .environment import (ALONE_BYPASS, BLOCK, BROWSER, COMPUTER_BYPASS, OWNED_FLAGS, POLICIES, READY_POLL_S,
+                          SHM_MIN_BYTES, SITE_PROXY_ENV, SITES, SKILL, BrowserSettings, WebsiteBrowserEnvironment,
+                          Window, start_tab_why)
+from .shapes import (BrowserRecord, ClosedTab, Cookie, CookieToSet, Dialog, Download, LaunchEntry, OpenTab,
+                     OriginStorage, PartitionKey, SiteNames, StartTab, StartTabsLaunch, StorageItem, origin_of)
+
+__all__ = ["ACTIVE_CHECK_TIMEOUT_S", "AGENT", "AGENTENV", "ALONE_BYPASS", "BLOCK", "BROWSER", "CAPTURE_TIMEOUT_S",
+           "COMPUTER_BYPASS", "DOWNLOADS", "EXIT", "FAILED", "HASH_CHUNK_BYTES", "LIVE_START_TAB_TIMEOUT_S", "LOADED",
+           "MAX_MESSAGE_BYTES", "OWNED_FLAGS", "PAGE_INPUT", "PAGES", "PIN_TIMEOUT_S", "PIPE_IN", "PIPE_OUT",
+           "POLICIES", "READY_POLL_S", "SHM_MIN_BYTES", "SITE_PROXY_ENV", "SITES", "SKILL", "STOP", "TIMED_OUT",
+           "UNKNOWN", "UNNAVIGATED_CAPTURE_TIMEOUT_S", "UPLOADS", "BrowserControl", "BrowserSettings", "DevToolsError",
+           "DevToolsPipe", "WebsiteBrowserEnvironment", "Window", "BrowserRecord", "ClosedTab", "Cookie", "CookieToSet",
+           "Dialog", "Download", "LaunchEntry", "OpenTab", "OriginStorage", "PartitionKey", "SiteNames", "StartTab",
+           "StartTabsLaunch", "StorageItem", "origin_of", "start_tab_why"]

{agentenv_framework_protocol-0.1.480 → agentenv_framework_protocol-0.1.481}/src/agentenv_protocol/website_browser/control.py

@@ -8,6 +8,7 @@ import hashlib
 import logging
 import time
 from collections.abc import AsyncIterator
+from dataclasses import dataclass, field
 from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any, Awaitable, Callable, Optional
@@ -15,7 +16,7 @@ from urllib.parse import urlsplit
 
 from ..computer.errors import DeviceUnavailable, InvalidArgument
 from .devtools import DevToolsError, DevToolsPipe
-from .shapes import (ClosedTab, Cookie, CookieToSet, Dialog, Download, OpenTab, OriginStorage, StorageItem,
+from .shapes import (ClosedTab, Cookie, CookieToSet, Dialog, Download, OpenTab, OriginStorage, StartTab, StorageItem,
                      origin_of)
 
 logger = logging.getLogger(__name__)
@@ -29,6 +30,10 @@ ACTIVE_CHECK_TIMEOUT_S = 2.0
 #: of agentenv's own may take to reach an origin, and how often it's asked meanwhile.
 PIN_TIMEOUT_S = 10.0
 ARRIVAL_POLL_S = 0.05
+#: How long a start tab on a site the env doesn't serve may take to load before it's left loading.
+LIVE_START_TAB_TIMEOUT_S = 30.0
+#: How a start tab settled.
+LOADED, FAILED, TIMED_OUT = "loaded", "failed", "timed_out"
 #: How much of a download each read hashes.
 HASH_CHUNK_BYTES = 1 << 20
 #: Who answered a dialog when agentenv didn't.
@@ -80,6 +85,8 @@ class BrowserControl:
         self._dialog_opened: dict[str, asyncio.Event] = {}
         self._pinned: dict[str, asyncio.Event] = {}
         self._tasks: set[asyncio.Future] = set()
+        #: Each start tab loading, by its session.
+        self._loading: dict[str, _StartLoad] = {}
         #: Every http and https origin a page or frame it follows loaded since this server started, and the sessions
         #: of agentenv's own pages whose requests it answers itself.
         self.origins: set[str] = set()
@@ -108,6 +115,9 @@ class BrowserControl:
         self._shots.clear()
         self._dialog_opened.clear()
         self._pinned.clear()
+        for load in self._loading.values():
+            load.error = load.error or "the browser ended"
+            load.settled.set()
 
     async def close_tab(self, target: str) -> None:
         """Close the tab ``target``, which the record says agentenv closed."""
@@ -138,18 +148,84 @@ class BrowserControl:
             await self._bring_to_front(active)
         return target
 
-    async def reopen_start_tabs(self, urls: list[str]) -> None:
-        """The start tabs at their ``urls`` again, in place, the first active: each tab open, in opened order, goes to
-        its URL, and any the browser lacks opens. A page already loaded doesn't read cookies set after it, so a tab
-        a load signed in shows it only once it loads again."""
-        tabs = list(self.tabs)
-        for index, url in enumerate(urls):
-            if index < len(tabs):
-                await self._navigate_tab(tabs[index], url)
-            else:
-                tabs.append(await self.open_tab(url))
-        if tabs:
-            await self._bring_to_front(tabs[0])
+    async def load_start_tabs(self, urls: list[str], site_of: Callable[[str], Optional[str]], own_timeout_s: float,
+                              live_timeout_s: float = LIVE_START_TAB_TIMEOUT_S) -> list[dict]:
+        """Each of ``urls`` in a start tab, in order, the first then active: in the tabs open now, in opened order, and
+        in tabs it opens blank after them; each held to the window's size, headless, before it goes to its URL, and
+        all loading at once. A tab settles once it has loaded, once it has failed, which on one of the env's own sites,
+        as ``site_of`` names them, an error status is too, or once it has been waited on ``own_timeout_s`` on such a
+        site, else ``live_timeout_s``. Each tab's outcome, in order, kept though the browser has gone and the first
+        can't come to the front. A page already loaded doesn't read cookies set after it, so a tab a load signed in
+        shows it only once it loads again."""
+        if not urls:
+            return []
+        targets = list(self.tabs)[:len(urls)] or [await self._first_tab()]
+        while len(targets) < len(urls):
+            targets.append((await self.devtools.call("Target.createTarget",
+                                                     {"url": "about:blank", "background": True}))["targetId"])
+        for target in targets:
+            await asyncio.wait_for(self._pinned.setdefault(target, asyncio.Event()).wait(), PIN_TIMEOUT_S)
+        loading = []
+        for target, url in zip(targets, urls):
+            site = site_of(url)
+            loading.append(await self._start_load(target, url, site))
+        outcomes = await asyncio.gather(*(self._settled(target, load, own_timeout_s if load.site is not None
+                                                        else live_timeout_s) for target, load in zip(targets, loading)))
+        with contextlib.suppress(ConnectionError, DevToolsError):
+            await self._bring_to_front(targets[0])
+        return outcomes
+
+    async def _first_tab(self) -> str:
+        """The tab a browser just launched opened, once it has one."""
+        deadline = asyncio.get_running_loop().time() + PIN_TIMEOUT_S
+        while not self.tabs:
+            if asyncio.get_running_loop().time() > deadline:
+                raise DeviceUnavailable(f"the browser opened no tab within {PIN_TIMEOUT_S:g} s")
+            await asyncio.sleep(ARRIVAL_POLL_S)
+        return next(iter(self.tabs))
+
+    async def _start_load(self, target: str, url: str, site: Optional[str]) -> _StartLoad:
+        """The tab ``target`` sent to ``url``, its navigation followed by what the browser says of it. The browser
+        answers a navigation once it commits, which a page that never answers never does, so its answer is awaited
+        apart, for as long as the tab is."""
+        session = next((s for s, t in self._sessions.items() if t == target), None)
+        if session is None:
+            raise DeviceUnavailable(f"the browser's tab {target} has no session to load a start tab in")
+        load = self._loading[session] = _StartLoad(session, url, site, asyncio.get_running_loop().time())
+        try:
+            await self.devtools.call("Network.enable", session_id=session)
+        except (ConnectionError, DevToolsError, asyncio.TimeoutError) as e:
+            load.error = f"{type(e).__name__}: {e}"
+            load.check()
+            return load
+        load.navigating = asyncio.ensure_future(self.devtools.request("Page.navigate", {"url": url},
+                                                                      session_id=session))
+        load.navigating.add_done_callback(load.answered)
+        return load
+
+    async def _settled(self, target: str, load: _StartLoad, timeout_s: float) -> dict:
+        """``load``'s outcome once it settles, or once it has been waited on ``timeout_s``."""
+        try:
+            await asyncio.wait_for(load.settled.wait(), timeout_s)
+        except asyncio.TimeoutError:
+            pass
+        finally:
+            if load.navigating is not None:
+                load.navigating.cancel()
+            self._loading.pop(load.session, None)
+            with contextlib.suppress(ConnectionError, DevToolsError, asyncio.TimeoutError):
+                await self.devtools.call("Network.disable", session_id=load.session)
+        document = load.current() or load.loader or ""
+        status, final_url = load.responses.get(document, (None, None))
+        error = load.error or load.failures.get(load.loader or "") or load.failures.get(document)
+        outcome = FAILED if error or (load.settled.is_set() and status is not None and status >= 400) else \
+            LOADED if load.settled.is_set() else TIMED_OUT
+        if final_url is None and outcome == LOADED:
+            await self._refresh(target)
+            final_url = self.tabs.get(target, {}).get("url")
+        return StartTab(tab=target, url=load.url, final_url=final_url, status=status, error=error,
+                        load_ms=round((asyncio.get_running_loop().time() - load.started) * 1000), site=load.site,
+                        outcome=outcome).model_dump()
 
     async def replace_tabs(self, tabs: list) -> None:
         """``tabs``, each with its ``url`` and whether it's ``active``, opened in order in place of the tabs open now,
@@ -161,14 +237,6 @@ class BrowserControl:
         if opened:
             await self._bring_to_front(next((target for target, tab in zip(opened, tabs) if tab.active), opened[0]))
 
-    async def _navigate_tab(self, target: str, url: str) -> None:
-        session = next((s for s, t in self._sessions.items() if t == target), None)
-        if session is None:
-            raise DeviceUnavailable(f"the browser's tab {target} has no session to navigate it")
-        answer = await self.devtools.call("Page.navigate", {"url": url}, session_id=session)
-        if error := answer.get("errorText"):
-            raise InvalidArgument(f"the browser couldn't open {url}: {error}")
-
     def forget(self) -> None:
         """A record that starts now, as a reset leaves the browser: no tabs closed, downloads or dialogs before it, and
         no origin seen."""
@@ -521,6 +589,26 @@ class BrowserControl:
     def _on_Page_frameNavigated(self, params: dict, session: Optional[str]) -> None:
         if session in self._sessions:
             self._saw(params.get("frame", {}).get("url", ""))
+        frame = params.get("frame", {})
+        if (load := self._loading.get(session)) is not None and not frame.get("parentId") and frame.get("loaderId"):
+            load.commits.append(frame["loaderId"])
+            load.check()
+
+    def _on_Network_requestWillBeSent(self, params: dict, session: Optional[str]) -> None:
+        if (load := self._loading.get(session)) is not None and params.get("type") == "Document":
+            load.requests[params["requestId"]] = params.get("loaderId", "")
+
+    def _on_Network_responseReceived(self, params: dict, session: Optional[str]) -> None:
+        if (load := self._loading.get(session)) is not None and params.get("type") == "Document" and \
+                params.get("requestId") in load.requests:
+            response = params.get("response", {})
+            load.responses[load.requests[params["requestId"]]] = (response.get("status"), response.get("url"))
+            load.check()
+
+    def _on_Network_loadingFailed(self, params: dict, session: Optional[str]) -> None:
+        if (load := self._loading.get(session)) is not None and (loader := load.requests.get(params.get("requestId"))):
+            load.failures[loader] = params.get("errorText") or "the load failed"
+            load.check()
 
     def _on_Fetch_requestPaused(self, params: dict, session: Optional[str]) -> None:
         if session in self._serving:
@@ -575,6 +663,9 @@ class BrowserControl:
         self._choosers.pop(session, None)
         if (target := self._sessions.get(session)) is not None:
             self._spawn(self._refresh(target))
+        if (load := self._loading.get(session)) is not None and load.commits:
+            load.loaded.add(load.commits[-1])
+            load.check()
 
     def _on_Page_fileChooserOpened(self, params: dict, session: Optional[str]) -> None:
         if session in self._sessions:
@@ -636,6 +727,58 @@ class BrowserControl:
             logger.warning(f"the browser's control connection: {type(error).__name__}: {error}")
 
 
+@dataclass
+class _StartLoad:
+    """What the browser has said of a start tab's navigation, by loader, since it was sent to ``url``: its main frame's
+    commits in order, the loads that fired after a commit, and its documents' requests, final responses and failures.
+    Its document is the last its main frame committed from its own navigation on, which a page that sends itself
+    elsewhere before it loads replaces. It's ``settled`` once its navigation or its document has failed, its document
+    has loaded or, on one of the env's ``site``, answered an error."""
+    session: str
+    url: str
+    site: Optional[str]
+    started: float
+    loader: Optional[str] = None
+    error: Optional[str] = None
+    commits: list[str] = field(default_factory=list)
+    loaded: set[str] = field(default_factory=set)
+    requests: dict[str, str] = field(default_factory=dict)
+    responses: dict[str, tuple[Optional[int], Optional[str]]] = field(default_factory=dict)
+    failures: dict[str, str] = field(default_factory=dict)
+    settled: asyncio.Event = field(default_factory=asyncio.Event)
+    navigating: Optional[asyncio.Future] = None
+
+    def answered(self, navigating: asyncio.Future) -> None:
+        """The browser's answer to its navigation: its loader, or why it couldn't navigate."""
+        if navigating.cancelled():
+            return
+        if (error := navigating.exception()) is not None:
+            self.error = f"{type(error).__name__}: {error}"
+        else:
+            answer = navigating.result()
+            if "error" in answer:
+                self.error = str(answer["error"].get("message", answer["error"]))
+            else:
+                self.error = answer.get("result", {}).get("errorText") or None
+                self.loader = answer.get("result", {}).get("loaderId")
+        self.check()
+
+    def current(self) -> Optional[str]:
+        """The loader of its document: the last its main frame committed, once its own navigation has; else None."""
+        return self.commits[-1] if self.loader is not None and self.loader in self.commits else None
+
+    def check(self) -> None:
+        if self.error or (self.loader is not None and self.loader in self.failures):
+            self.settled.set()
+            return
+        if (document := self.current()) is None:
+            return
+        status = self.responses.get(document, (None, None))[0]
+        if document in self.failures or document in self.loaded or (
+                self.site is not None and status is not None and status >= 400):
+            self.settled.set()
+
+
 def _size_and_sha256(path: Path) -> tuple[int, str]:
     digest = hashlib.sha256()
     with path.open("rb") as file: