Skip to content

Automate browser based workflows with AI

Tag browser-session minutes with who actually ran the browser (#8252)

Shuchang Zheng2a3a01478498
diff --git a/skyvern/forge/agent.py b/skyvern/forge/agent.py
index ca3d107a6..273b59ca4 100644
--- a/skyvern/forge/agent.py
+++ b/skyvern/forge/agent.py
@@ -281,6 +281,40 @@ async def resolve_inherited_workflow_task_page(browser_state: BrowserState, work
raise InvalidWorkflowTaskURLState(workflow_run_id)
+def fail_step_if_browser_already_gone(task: Task, step: Step, browser_state: BrowserState) -> None:
+ """Probe liveness and fail the step if the browser is already known to be gone.
+
+ The probe is a local flag read that latches the disconnect diagnostic, so a state nothing upstream
+ probed (caller-supplied, or a cached Skyvern-hosted one the manager never reconnects) is still
+ caught here. ``check_and_fix_state`` clears the diagnostic whenever it rebuilds, so a latched one
+ means every page access this step makes is guaranteed to raise; reconnecting instead (what
+ ``block.py`` does at a block boundary) would hand a mid-flow task a blank browser with none of its
+ cookies or page state.
+ """
+ browser_state.is_connected()
+ diagnostic = get_browser_state_diagnostic(browser_state)
+ if diagnostic is None:
+ return
+ detected_at = datetime.now(UTC)
+ LOG.warning(
+ "Browser is already gone; failing the step instead of starting it against a dead browser",
+ task_id=task.task_id,
+ workflow_run_id=task.workflow_run_id,
+ step_order=step.order,
+ step_retry=step.retry_index,
+ disconnect_reason=diagnostic.reason,
+ disconnect_observed_at=diagnostic.disconnect_observed_at.isoformat(),
+ disconnect_observation_source=diagnostic.observation_source,
+ )
+ raise MissingBrowserStatePage(
+ task_id=task.task_id,
+ workflow_run_id=task.workflow_run_id,
+ diagnostic=diagnostic,
+ detected_at=detected_at,
+ failure_reason="browser_disconnected_before_step",
+ )
+
+
def should_auto_download_pdf(pdf_src: str) -> bool:
context = skyvern_context.current()
if not context:
@@ -4619,6 +4653,8 @@ class ForgeAgent:
task=task,
browser_session_id=browser_session_id,
)
+ # Every way a step can acquire a browser converges here, including a caller-supplied one.
+ fail_step_if_browser_already_gone(task=task, step=step, browser_state=browser_state)
# Initialize video artifact for the task here, afterwards it'll only get updated.
# The recording file is still open here, so skip the ffmpeg remux — matches the
# per-step sync path; the finalized upload happens in cleanup_and_persist_task.
diff --git a/tests/unit/test_screenshot_target_closed_callers.py b/tests/unit/test_screenshot_target_closed_callers.py
index 4f650abe2..76259b771 100644
--- a/tests/unit/test_screenshot_target_closed_callers.py
+++ b/tests/unit/test_screenshot_target_closed_callers.py
@@ -45,6 +45,7 @@ from skyvern.forge.sdk.core.skyvern_context import SkyvernContext
from skyvern.forge.sdk.models import StepStatus
from skyvern.schemas.runs import RunEngine
from skyvern.webeye.actions.actions import ActionType, ClickAction, CompleteAction
+from skyvern.webeye.real_browser_manager import RealBrowserManager
from tests.unit.helpers import make_browser_state, make_organization, make_step, make_task
from tests.unit.test_agent_step_characterization import make_agent_step_rig
@@ -522,6 +523,95 @@ class TestCompleteActionVerificationTargetClosed:
assert any("Failed to verify the complete action" in str(call.args[0]) for call in log.exception.call_args_list)
+class _CachedBrowserState:
+ """Mirrors ``RealBrowserState`` at the two points the step boundary depends on: the liveness read
+ is what latches the disconnect diagnostic, and the diagnostic is what every consumer reads to
+ decide the browser is provably gone."""
+
+ def __init__(self, *, connected: bool, browser_artifacts: Any = None) -> None:
+ self._connected = connected
+ self._diagnostic: BrowserStateDiagnostic | None = None
+ self.browser_context = None
+ self.browser_artifacts = browser_artifacts
+
+ def is_connected(self) -> bool:
+ if not self._connected and self._diagnostic is None:
+ self._diagnostic = BrowserStateDiagnostic(
+ reason="browser_context_closed",
+ disconnect_observed_at=datetime.now(UTC),
+ event="browser_context_disconnected",
+ observation_source="liveness_probe",
+ )
+ return self._connected
+
+ def get_browser_state_diagnostic(self) -> BrowserStateDiagnostic | None:
+ return self._diagnostic
+
+
+class TestStepBoundaryBrowserLoss:
+ """A step that starts against a browser already known to be gone spends its whole scrape ladder
+ re-discovering that. ``check_and_fix_state`` clears the diagnostic whenever it rebuilds, and
+ nothing in the scrape path rebuilds, so a diagnostic still latched at acquisition means every
+ page access this step makes is guaranteed to raise. Reconnecting instead — what ``block.py`` does
+ at a block boundary — would hand a mid-flow task a blank browser with none of its state.
+ """
+
+ def _rig(self, monkeypatch: pytest.MonkeyPatch, browser_state: _CachedBrowserState) -> tuple[ForgeAgent, dict]:
+ now = datetime.now(UTC)
+ organization = make_organization(now)
+ task = make_task(now, organization, task_id="tsk_boundary")
+ step = make_step(now, task, step_id="step-boundary", status=StepStatus.running, order=4, output=None)
+
+ manager = RealBrowserManager()
+ manager.pages[task.task_id] = browser_state # type: ignore[assignment]
+ monkeypatch.setattr(agent_mod.app, "BROWSER_MANAGER", manager)
+ skyvern_context.set(SkyvernContext(task_id=task.task_id, organization_id=task.organization_id))
+
+ return ForgeAgent(), {"task": task, "step": step}
+
+ @pytest.mark.asyncio
+ async def test_cached_dead_browser_fails_the_step_before_it_starts(self, monkeypatch: pytest.MonkeyPatch) -> None:
+ """A task with no persistent session is handed its cached, dead browser state untouched: the
+ manager only probes (and reconnects) persistent-session states, because only a session can
+ be re-acquired as the SAME browser. The gate's own probe is what makes the death visible."""
+ browser_state = _CachedBrowserState(connected=False, browser_artifacts=MagicMock())
+ agent, kwargs = self._rig(monkeypatch, browser_state)
+ video_artifacts = AsyncMock(side_effect=AssertionError("the step must not start on a dead browser"))
+ monkeypatch.setattr(agent_mod.app.BROWSER_MANAGER, "get_video_artifacts", video_artifacts)
+ create = AsyncMock(side_effect=AssertionError("a mid-flow task must not be given a fresh blank browser"))
+ monkeypatch.setattr(agent_mod.app.BROWSER_MANAGER, "_create_browser_state", create)
+
+ with pytest.raises(MissingBrowserStatePage) as exc_info:
+ await agent.initialize_execution_state(**kwargs)
+
+ assert exc_info.value.diagnostic is browser_state.get_browser_state_diagnostic()
+ video_artifacts.assert_not_called()
+ create.assert_not_called()
+
+ @pytest.mark.asyncio
+ async def test_pre_resolved_browser_state_does_not_bypass_the_gate(self, monkeypatch: pytest.MonkeyPatch) -> None:
+ """A caller-supplied state skips the manager entirely, so nothing upstream has probed it and
+ no diagnostic is latched yet. The gate must probe liveness itself, not just read."""
+ browser_state = _CachedBrowserState(connected=False, browser_artifacts=MagicMock())
+ assert browser_state.get_browser_state_diagnostic() is None
+ agent, kwargs = self._rig(monkeypatch, _CachedBrowserState(connected=True))
+
+ with pytest.raises(MissingBrowserStatePage) as exc_info:
+ await agent.initialize_execution_state(**kwargs, pre_resolved_browser_state=browser_state) # type: ignore[arg-type]
+
+ assert exc_info.value.diagnostic is browser_state.get_browser_state_diagnostic()
+
+ @pytest.mark.asyncio
+ async def test_a_live_browser_still_starts_the_step(self, monkeypatch: pytest.MonkeyPatch) -> None:
+ """Control: no observed disconnect means the browser is not provably gone, and the step runs."""
+ browser_state = _CachedBrowserState(connected=True)
+ agent, kwargs = self._rig(monkeypatch, browser_state)
+
+ _, acquired, _ = await agent.initialize_execution_state(**kwargs)
+
+ assert acquired is browser_state
+
+
class TestTaskV2IterationTargetClosed:
"""Structural guard: ``run_task_v2_helper`` needs a full workflow-run rig to drive, so this pins
the clause ordering instead — the closed-target handler must precede the generic ``LOG.exception``.