Run the route eviction hook before caller response hooks

A response hook registered by the caller runs in registration order, so one
that reads a failing 401/403 body or raises would skip the eviction hook
appended after it and leave the stale route cached. Prepend the hook in both
the sync and async installers; registration stays once per route cache.

Author: tnsardesai

src/kernel/lib/browser_routing/routing.py

@@ -209,7 +209,8 @@ def install_stale_direct_vm_auth_eviction(client: httpx.Client, *, cache: Browse
     whose body read fails — the read error surfaces from `send()` instead and the
     dead route would stay cached, wedging every later call for that session. A
     response event hook runs after the status is known and before any body is
-    read, which keeps eviction independent of the body.
+    read, which keeps eviction independent of the body. It is prepended so that a
+    caller-supplied hook cannot pre-empt it by reading a failing body or raising.
     """
     hooks = client.event_hooks.setdefault("response", [])
     if _has_eviction_hook(hooks, cache):
@@ -220,7 +221,7 @@ def evict(response: httpx.Response) -> None:
             maybe_evict_browser_route_from_response(response, cache=cache)
 
     setattr(evict, _EVICTION_HOOK_CACHE_ATTR, cache)
-    hooks.append(evict)
+    hooks.insert(0, evict)
 
 
 def install_async_stale_direct_vm_auth_eviction(client: httpx.AsyncClient, *, cache: BrowserRouteCache) -> None:
@@ -234,7 +235,7 @@ async def evict(response: httpx.Response) -> None:
             maybe_evict_browser_route_from_response(response, cache=cache)
 
     setattr(evict, _EVICTION_HOOK_CACHE_ATTR, cache)
-    hooks.append(evict)
+    hooks.insert(0, evict)
 
 
 def _has_eviction_hook(hooks: list[Any], cache: BrowserRouteCache) -> bool:

tests/test_browser_routing.py

@@ -1353,3 +1353,113 @@ def test_copied_client_registers_one_route_eviction_hook() -> None:
         assert copied.browser_route_cache is client.browser_route_cache
         hooks = client._client.event_hooks["response"]  # pyright: ignore[reportPrivateUsage]
         assert len(hooks) == 1
+
+
+def test_route_eviction_hook_runs_before_caller_response_hooks(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.delenv("KERNEL_BROWSER_ROUTING_SUBRESOURCES", raising=False)
+    requests: list[httpx.Request] = []
+    caller_hook_statuses: list[int] = []
+
+    def handle_request(request: httpx.Request) -> httpx.Response:
+        requests.append(request)
+        if "browser-session.test" in str(request.url):
+            return httpx.Response(401, stream=_FailingSyncStream(), headers={"content-type": "text/plain"})
+        return httpx.Response(200, content=b"png", headers={"content-type": "image/png"})
+
+    def caller_hook(response: httpx.Response) -> None:
+        caller_hook_statuses.append(response.status_code)
+        if response.status_code in {401, 403}:
+            # Reading a failing body raises out of the hook chain, which would
+            # skip any eviction hook registered after this one.
+            response.read()
+
+    http_client = httpx.Client(
+        transport=httpx.MockTransport(handle_request),
+        event_hooks={"response": [caller_hook]},
+    )
+    with Kernel(
+        base_url=base_url,
+        api_key=api_key,
+        max_retries=0,
+        http_client=http_client,
+        _strict_response_validation=True,
+    ) as client:
+        _cache_browser(client)
+        assert http_client.event_hooks["response"][-1] is caller_hook
+        with pytest.raises(APIConnectionError):
+            client.browsers.computer.capture_screenshot("sess-1")
+        assert caller_hook_statuses == [401]
+        assert client.browser_route_cache.get("sess-1") is None
+
+        client.browsers.computer.capture_screenshot("sess-1")
+
+    assert str(requests[0].url).startswith("http://browser-session.test/browser/kernel/computer/screenshot")
+    assert requests[1].url == httpx.URL(f"{base_url}/browsers/sess-1/computer/screenshot")
+    assert requests[1].url.params.get("jwt") is None
+    assert requests[1].headers.get("Authorization") == f"Bearer {api_key}"
+
+
+@pytest.mark.asyncio
+async def test_async_route_eviction_hook_runs_before_caller_response_hooks(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.delenv("KERNEL_BROWSER_ROUTING_SUBRESOURCES", raising=False)
+    requests: list[httpx.Request] = []
+    caller_hook_statuses: list[int] = []
+
+    async def handle_request(request: httpx.Request) -> httpx.Response:
+        requests.append(request)
+        if "browser-session.test" in str(request.url):
+            return httpx.Response(403, stream=_FailingAsyncStream(), headers={"content-type": "text/plain"})
+        return httpx.Response(200, content=b"png", headers={"content-type": "image/png"})
+
+    async def caller_hook(response: httpx.Response) -> None:
+        caller_hook_statuses.append(response.status_code)
+        if response.status_code in {401, 403}:
+            await response.aread()
+
+    http_client = httpx.AsyncClient(
+        transport=httpx.MockTransport(handle_request),
+        event_hooks={"response": [caller_hook]},
+    )
+    async with AsyncKernel(
+        base_url=base_url,
+        api_key=api_key,
+        max_retries=0,
+        http_client=http_client,
+        _strict_response_validation=True,
+    ) as client:
+        route = browser_route_from_browser(_fake_browser())
+        assert route is not None
+        client.browser_route_cache.set(route)
+        assert http_client.event_hooks["response"][-1] is caller_hook
+        with pytest.raises(APIConnectionError):
+            await client.browsers.computer.capture_screenshot("sess-1")
+        assert caller_hook_statuses == [403]
+        assert client.browser_route_cache.get("sess-1") is None
+
+        await client.browsers.computer.capture_screenshot("sess-1")
+
+    assert str(requests[0].url).startswith("http://browser-session.test/browser/kernel/computer/screenshot")
+    assert requests[1].url == httpx.URL(f"{base_url}/browsers/sess-1/computer/screenshot")
+    assert requests[1].url.params.get("jwt") is None
+    assert requests[1].headers.get("Authorization") == f"Bearer {api_key}"
+
+
+def test_route_eviction_hook_is_registered_once_before_caller_hooks() -> None:
+    def caller_hook(_response: httpx.Response) -> None:  # pragma: no cover - never invoked
+        return None
+
+    http_client = httpx.Client(event_hooks={"response": [caller_hook]})
+    with Kernel(
+        base_url=base_url,
+        api_key=api_key,
+        http_client=http_client,
+        _strict_response_validation=True,
+    ) as client:
+        client.copy(api_key="sk-456")
+        hooks = http_client.event_hooks["response"]
+        assert len(hooks) == 2
+        assert hooks[1] is caller_hook