Skip to content

Automate browser based workflows with AI

Fix browser session download fail-silents (SKY-13385) (#7979)

Aaron Pereze945a96fcae2
diff --git a/docs/api-reference/openapi.json b/docs/api-reference/openapi.json
index 203789464..87f16003d 100644
--- a/docs/api-reference/openapi.json
+++ b/docs/api-reference/openapi.json
@@ -4170,6 +4170,39 @@
"403": {
"description": "Unauthorized - Invalid or missing authentication"
},
+ "503": {
+ "description": "Downloaded files could not be returned",
+ "content": {
+ "application/json": {
+ "schema": {
+ "type": "object",
+ "required": [
+ "detail"
+ ],
+ "properties": {
+ "detail": {
+ "type": "object",
+ "required": [
+ "code",
+ "retryable"
+ ],
+ "properties": {
+ "code": {
+ "type": "string",
+ "enum": [
+ "downloaded_files_unavailable"
+ ]
+ },
+ "retryable": {
+ "type": "boolean"
+ }
+ }
+ }
+ }
+ }
+ }
+ }
+ },
"422": {
"description": "Validation Error",
"content": {
diff --git a/skyvern/forge/sdk/routes/browser_sessions.py b/skyvern/forge/sdk/routes/browser_sessions.py
index 4b37a0f05..f7d0e2496 100644
--- a/skyvern/forge/sdk/routes/browser_sessions.py
+++ b/skyvern/forge/sdk/routes/browser_sessions.py
@@ -331,6 +331,27 @@ async def update_browser_session(
200: {"description": "Successfully retrieved browser session details"},
404: {"description": "Browser session not found"},
403: {"description": "Unauthorized - Invalid or missing authentication"},
+ 503: {
+ "description": "Downloaded files could not be returned",
+ "content": {
+ "application/json": {
+ "schema": {
+ "type": "object",
+ "required": ["detail"],
+ "properties": {
+ "detail": {
+ "type": "object",
+ "required": ["code", "retryable"],
+ "properties": {
+ "code": {"type": "string", "enum": ["downloaded_files_unavailable"]},
+ "retryable": {"type": "boolean"},
+ },
+ }
+ },
+ }
+ }
+ },
+ },
},
)
@base_router.get(
@@ -351,7 +372,11 @@ async def get_browser_session(
)
if not browser_session:
raise HTTPException(status_code=404, detail=f"Browser session {browser_session_id} not found")
- return await BrowserSessionResponse.from_browser_session(browser_session, app.STORAGE)
+ return await BrowserSessionResponse.from_browser_session(
+ browser_session,
+ app.STORAGE,
+ fail_download_lookup=True,
+ )
@base_router.get(
diff --git a/skyvern/webeye/schemas.py b/skyvern/webeye/schemas.py
index d07b49e72..ccf8c0154 100644
--- a/skyvern/webeye/schemas.py
+++ b/skyvern/webeye/schemas.py
@@ -4,6 +4,7 @@ import asyncio
from datetime import datetime
import structlog
+from fastapi import HTTPException, status
from pydantic import BaseModel, Field
from skyvern.config import settings
@@ -88,13 +89,20 @@ class BrowserSessionResponse(BaseModel):
@classmethod
async def from_browser_session(
- cls, browser_session: PersistentBrowserSession, storage: BaseStorage | None = None
+ cls,
+ browser_session: PersistentBrowserSession,
+ storage: BaseStorage | None = None,
+ *,
+ # False deliberately preserves the existing permissive timeout behavior for PATCH,
+ # active-list, and history responses; the single-session GET opts into strict lookup.
+ fail_download_lookup: bool = False,
) -> BrowserSessionResponse:
"""
Creates a BrowserSessionResponse from a PersistentBrowserSession object.
Args:
browser_session: The persistent browser session to convert
+ fail_download_lookup: Raise a structured 503 when downloads cannot be listed.
Returns:
BrowserSessionResponse: The converted response object
@@ -118,6 +126,11 @@ class BrowserSessionResponse(BaseModel):
LOG.warning(
"Timeout getting downloaded files", browser_session_id=browser_session.persistent_browser_session_id
)
+ if fail_download_lookup:
+ raise HTTPException(
+ status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+ detail={"code": "downloaded_files_unavailable", "retryable": True},
+ ) from None
try:
async with asyncio.timeout(GET_DOWNLOADED_FILES_TIMEOUT):
diff --git a/tests/unit/forge/sdk/routes/test_browser_sessions.py b/tests/unit/forge/sdk/routes/test_browser_sessions.py
index b280d69b2..1f2ba2748 100644
--- a/tests/unit/forge/sdk/routes/test_browser_sessions.py
+++ b/tests/unit/forge/sdk/routes/test_browser_sessions.py
@@ -25,3 +25,28 @@ async def test_close_browser_session_returns_404_without_org_owned_session() ->
assert exc_info.value.status_code == 404
app_mock.PERSISTENT_SESSIONS_MANAGER.get_session.assert_awaited_once_with("pbs_foreign", "org_requester")
app_mock.PERSISTENT_SESSIONS_MANAGER.close_session.assert_not_awaited()
+
+
+async def test_get_browser_session_enables_strict_download_lookup() -> None:
+ browser_session = MagicMock()
+ response = MagicMock()
+ app_mock = MagicMock()
+ app_mock.PERSISTENT_SESSIONS_MANAGER.get_session = AsyncMock(return_value=browser_session)
+ from_browser_session = AsyncMock(return_value=response)
+
+ with (
+ patch.object(browser_sessions_mod, "app", app_mock),
+ patch.object(browser_sessions_mod.BrowserSessionResponse, "from_browser_session", from_browser_session),
+ ):
+ result = await browser_sessions_mod.get_browser_session(
+ "pbs_1",
+ current_org=SimpleNamespace(organization_id="org_1"),
+ )
+
+ assert result is response
+ from_browser_session.assert_awaited_once_with(
+ browser_session,
+ app_mock.STORAGE,
+ fail_download_lookup=True,
+ )
diff --git a/tests/unit/test_browser_session_download_artifacts.py b/tests/unit/test_browser_session_download_artifacts.py
index 3e73bbb79..e7ef3f28b 100644
--- a/tests/unit/test_browser_session_download_artifacts.py
+++ b/tests/unit/test_browser_session_download_artifacts.py
@@ -17,14 +17,19 @@ The unit-level tests below cover:
from __future__ import annotations
+from datetime import datetime, timezone
from unittest.mock import AsyncMock, MagicMock, patch
from urllib.parse import urlparse
import pytest
+from fastapi import HTTPException
from skyvern.forge.sdk.artifact.manager import ArtifactManager
from skyvern.forge.sdk.artifact.models import Artifact, ArtifactType
from skyvern.forge.sdk.artifact.storage.s3 import S3Storage
+from skyvern.forge.sdk.routes.browser_sessions import base_router
+from skyvern.forge.sdk.schemas.persistent_browser_sessions import PersistentBrowserSession
+from skyvern.webeye.schemas import BrowserSessionResponse
_DUMMY_KEYRING_JSON = '{"current_kid": "k1", "keys": {"k1": {"secret": "0000000000000000000000000000000000000000000000000000000000000000"}}}'
@@ -591,3 +596,69 @@ async def test_delete_browser_session_file_swallows_db_failure_and_still_deletes
# Watcher-level tests for browser_controller live under tests/cloud/ — the
# browser_controller module imports cloud-only dependencies (redis client) and
# can't load in the OSS-synced unit suite.
+
+
+async def test_browser_session_response_returns_retryable_503_when_download_lookup_times_out():
+ now = datetime.now(timezone.utc)
+ browser_session = PersistentBrowserSession(
+ persistent_browser_session_id="pbs_1",
+ organization_id="o_1",
+ status="running",
+ created_at=now,
+ modified_at=now,
+ )
+ storage = MagicMock()
+ storage.get_shared_downloaded_files_in_browser_session = AsyncMock(side_effect=TimeoutError)
+
+ with pytest.raises(HTTPException) as exc_info:
+ await BrowserSessionResponse.from_browser_session(browser_session, storage, fail_download_lookup=True)
+
+ assert exc_info.value.status_code == 503
+ assert exc_info.value.detail == {"code": "downloaded_files_unavailable", "retryable": True}
+
+
+async def test_browser_session_response_preserves_empty_downloads_on_timeout_by_default():
+ now = datetime.now(timezone.utc)
+ browser_session = PersistentBrowserSession(
+ persistent_browser_session_id="pbs_1",
+ organization_id="o_1",
+ status="running",
+ created_at=now,
+ modified_at=now,
+ )
+ storage = MagicMock()
+ storage.get_shared_downloaded_files_in_browser_session = AsyncMock(side_effect=TimeoutError)
+ storage.get_shared_recordings_in_browser_session = AsyncMock(return_value=[])
+
+ with patch("skyvern.webeye.schemas.app") as app_mock:
+ app_mock.AGENT_FUNCTION.resolve_browser_session_connect_url = AsyncMock(return_value=None)
+ response = await BrowserSessionResponse.from_browser_session(browser_session, storage)
+
+ assert response.downloaded_files == []
+
+
+def test_get_browser_session_openapi_documents_download_unavailable_response():
+ route = next(
+ route
+ for route in base_router.routes
+ if getattr(route, "path", None) == "/browser_sessions/{browser_session_id}"
+ and "GET" in getattr(route, "methods", set())
+ )
+ response_schema = route.responses[503]["content"]["application/json"]["schema"]
+
+ assert response_schema == {
+ "type": "object",
+ "required": ["detail"],
+ "properties": {
+ "detail": {
+ "type": "object",
+ "required": ["code", "retryable"],
+ "properties": {
+ "code": {"type": "string", "enum": ["downloaded_files_unavailable"]},
+ "retryable": {"type": "boolean"},
+ },
+ }
+ },
+ }