Automate browser based workflows with AI
Python aiapiautomationbrowserbrowser-automationcomputergptllmplaywrightpowerautomatepuppeteerpythonrpaseleniumvisionworkflow
Recover from dead blank working page by closing it and falling back to the remaining page (SKY-15371) (#8589)
LawyZhengd23ceb40f5b9
diff --git a/skyvern/core/script_generations/generate_script.py b/skyvern/core/script_generations/generate_script.pyindex cd08837dc..b739898a4 100644--- a/skyvern/core/script_generations/generate_script.py+++ b/skyvern/core/script_generations/generate_script.py@@ -1570,6 +1570,10 @@ def _build_block_fn()else:for act in actions:+ # Internal-recovery closes are runtime-synthesized and have no ACTION_MAP entry; skip+ # only the marked ones so user-authored close_page semantics are left untouched.+ if act.get("is_internal_recovery"):+ continueif act["action_type"] in [ActionType.COMPLETE,ActionType.TERMINATE,diff --git a/skyvern/forge/agent.py b/skyvern/forge/agent.pyindex aa6150f3d..af8751b30 100644--- a/skyvern/forge/agent.py+++ b/skyvern/forge/agent.py@@ -70,6 +70,7 @@ from skyvern.exceptions import (NoTOTPVerificationCodeFound,PDFEmbedBase64DecodeError,ScrapingFailed,+ ScrapingFailedBlankPage,ScreenshotTargetClosed,SkyvernException,SkyvernPageAnalysisTimeout,@@ -223,6 +224,7 @@ from skyvern.webeye.actions.actions import (Action,ActionStatus,ClickAction,+ ClosePageAction,CompleteAction,CompleteVerifyResult,DecisiveAction,@@ -267,11 +269,16 @@ from skyvern.webeye.cdp_download_interceptor import ()from skyvern.webeye.dom_inspection import read_current_urlfrom skyvern.webeye.scraper.scraped_page import ElementTreeFormat, ScrapedPage+from skyvern.webeye.scraper.scraper import page_is_dead_blank, page_is_http_survivorfrom skyvern.webeye.utils.page import OTP_INPUT_PRIVACY_JS, SkyvernFrame, build_open_tabs_contextLOG = structlog.get_logger()BLANK_WORKFLOW_TASK_URLS = {"about:blank", ":"}RECOVERABLE_BLANK_WORKFLOW_TASK_URLS = {":"}+# Consecutive dead-blank recovery attempts allowed per task before falling through to terminal+# failure. Incremented at injection (so a guard-declined close still consumes the cap) and reset on+# any successful step-body scrape.+EMPTY_PAGE_RECOVERY_MAX_ATTEMPTS = 3EXTRACT_ACTION_TEMPLATE = "extract-action"DECISIVE_CRITERION_VALIDATE_TEMPLATE = "decisive-criterion-validate"@@ -3831,6 +3838,10 @@ class ForgeAgent:reuse_speculative_llm_response = json_response is not Nonespeculative_llm_metadata = speculative_plan.llm_metadataprompt_name = speculative_plan.prompt_name+ # A consumed speculative plan is backed by a successful survivor scrape, so it counts+ # as a successful step-body scrape for the consecutive-attempt cap.+ if context is not None:+ context.empty_page_recovery_attempts.pop(task.task_id, None)await self._persist_scrape_artifacts(task=task,step=step,@@ -3844,18 +3855,43 @@ class ForgeAgent:)prefetched_summary_task.add_done_callback(_discard_background_task_result)- step_prompt = await self.build_and_record_step_prompt(- task,- step,- browser_state,- engine,- )- scraped_page = step_prompt.scraped_page- extract_action_prompt = step_prompt.extract_action_prompt- use_caching = step_prompt.use_caching- prompt_name = step_prompt.prompt_name- without_page_information = step_prompt.without_page_information- json_response = None+ try:+ step_prompt = await self.build_and_record_step_prompt(+ task,+ step,+ browser_state,+ engine,+ )+ except ScrapingFailedBlankPage:+ # The working page is a dead blank after the scrape ladder. If a survivor exists,+ # recover by injecting a single ClosePageAction (no LLM); otherwise re-raise so+ # the existing terminal handler fails the task exactly as on main.+ recovery_actions = await self._empty_page_recovery_plan(task, step, browser_state)+ if recovery_actions is None:+ raise+ injected_actions = recovery_actions+ scraped_page = ScrapedPage(+ elements=[],+ element_tree=[],+ element_tree_trimmed=[],+ _browser_state=browser_state,+ _clean_up_func=None,+ _scrape_exclude=None,+ )+ extract_action_prompt = ""+ use_caching = False+ prompt_name = ""+ without_page_information = False+ json_response = None+ else:+ scraped_page = step_prompt.scraped_page+ extract_action_prompt = step_prompt.extract_action_prompt+ use_caching = step_prompt.use_caching+ prompt_name = step_prompt.prompt_name+ without_page_information = step_prompt.without_page_information+ json_response = None+ if context is not None:+ context.empty_page_recovery_attempts.pop(task.task_id, None)detailed_agent_step_output.scraped_page = scraped_pagedetailed_agent_step_output.extract_action_prompt = extract_action_prompt@@ -6093,6 +6129,59 @@ class ForgeAgent:allow_transient_ui_suppression=True,)+ async def _empty_page_recovery_plan(+ self, task: Task, step: Step, browser_state: BrowserState+ ) -> list[Action] | None:+ """Fail-closed eligibility for dead-blank recovery.++ Returns a single internal-recovery ClosePageAction when the current working page is a dead+ blank, holds no download-popup claim, a usable http/https survivor exists, and the per-task+ attempt cap is not reached. Any uncertainty (or exception) returns None so the caller+ re-raises the original blank exception and reproduces main's terminal behavior exactly.+ """+ try:+ context = skyvern_context.current()+ page = await browser_state.get_working_page()+ if context is None or page is None or not page_is_dead_blank(page):+ return None+ if context.has_download_popup_claim(task.task_id, page):+ return None+ pages = await browser_state.list_valid_pages(max_pages=0)+ if not any(p is not page and page_is_http_survivor(p) for p in pages):+ return None+ attempts = context.empty_page_recovery_attempts.get(task.task_id, 0)+ if attempts >= EMPTY_PAGE_RECOVERY_MAX_ATTEMPTS:+ return None+ context.empty_page_recovery_attempts[task.task_id] = attempts + 1+ context.empty_page_recovery_step_id = step.step_id+ # A pending reload must not substitute for the close inside the action loop.+ context.refresh_working_page = False+ LOG.info(+ "Empty-page recovery: closing dead blank working page to fall back to a survivor",+ task_id=task.task_id,+ step_id=step.step_id,+ attempt=attempts + 1,+ )+ return [+ ClosePageAction(+ is_internal_recovery=True,+ reasoning="Recovering from a dead blank working page by closing it.",+ organization_id=task.organization_id,+ task_id=task.task_id,+ step_id=step.step_id,+ step_order=step.order,+ action_order=0,+ )+ ]+ except Exception:+ LOG.warning(+ "Empty-page recovery plan failed; falling through to terminal handling",+ exc_info=True,+ task_id=task.task_id,+ step_id=step.step_id,+ )+ return None+@traced(name="skyvern.agent.scrape_and_prompt", role="wrapper")async def build_and_record_step_prompt(self,@@ -6190,6 +6279,7 @@ class ForgeAgent:consecutive_timeouts=context.browser_health.consecutive_timeouts,stuck_operations=stuck_operations,)+ blank_page_error: ScrapingFailedBlankPage | None = Nonefor idx, scrape_type in enumerate(SCRAPE_TYPE_ORDER):try:scraped_page = await self._scrape_with_type(@@ -6201,6 +6291,11 @@ class ForgeAgent:)breakexcept (FailedToTakeScreenshot, ScrapingFailed, FailedToReloadPage) as e:+ # A later rung reloading the uncommitted blank page can fail with+ # FailedToReloadPage; remember the blank evidence so exhaustion surfaces it+ # instead, keeping the recovery-eligible signature intact.+ if isinstance(e, ScrapingFailedBlankPage):+ blank_page_error = eif idx < len(SCRAPE_TYPE_ORDER) - 1:LOG.warning("Scrape attempt failed, will retry with next strategy",@@ -6230,7 +6325,7 @@ class ForgeAgent:step_order=step.order,step_retry=step.retry_index,)- raise e+ raise blank_page_error or eif scraped_page is None:raise EmptyScrapePage()@@ -8983,6 +9078,12 @@ class ForgeAgent:engine: RunEngine = RunEngine.skyvern_v1,complete_verification: bool = True,) -> tuple[bool | None, Step | None, Step | None]:+ # A step whose only action was an internal-recovery close must not complete the block or trip+ # the max-steps failure by itself; the block's real action still runs on the next step. Read+ # once here so the parallel-verification path (which carries its own unconditional max-step+ # failure) is bypassed for recovery steps, not just the sequential path below.+ recovery_context = skyvern_context.current()+ recovery_only = recovery_context is not None and recovery_context.empty_page_recovery_step_id == step.step_id# Check if parallel verification should be used# Only use it when we have the required data AND when verification would normally happentask_completes_on_download = task_block and task_block.complete_on_download and task.workflow_run_id@@ -8992,6 +9093,7 @@ class ForgeAgent:and not step.is_terminated()and not isinstance(task_block, ActionBlock)and not task_completes_on_download+ and not recovery_onlyand (task.navigation_goal or task.complete_criterion))@@ -9095,7 +9197,7 @@ class ForgeAgent:)# HACK: action block only have one step to execute without complete action, so we consider the task is completed as long as the step is completed- if isinstance(task_block, ActionBlock) and step.is_success():+ if isinstance(task_block, ActionBlock) and step.is_success() and not recovery_only:LOG.info("Step completed for the action block, marking task as completed",step_order=step.order,@@ -9120,7 +9222,7 @@ class ForgeAgent:)return False, last_step, None- if step.order + 1 >= max_steps_per_run:+ if step.order + 1 >= max_steps_per_run and not recovery_only:LOG.info("Step completed but max steps reached, marking task as failed",step_order=step.order,diff --git a/skyvern/forge/sdk/core/skyvern_context.py b/skyvern/forge/sdk/core/skyvern_context.pyindex d98741802..df095fdde 100644--- a/skyvern/forge/sdk/core/skyvern_context.py+++ b/skyvern/forge/sdk/core/skyvern_context.py@@ -348,6 +348,10 @@ class SkyvernContext:# this like workflow_block_engine_lock or one task's refs stomp another's mid-flight.opaque_url_refs: dict[str, str] = field(default_factory=dict)refresh_working_page: bool = False+ # Empty-page recovery: the step whose plan was replaced by an internal-recovery+ # ClosePageAction, and a per-task consecutive-attempt counter that caps recovery at 3.+ empty_page_recovery_step_id: str | None = None+ empty_page_recovery_attempts: dict[str, int] = field(default_factory=dict)frame_index_map: dict[Frame, int] = field(default_factory=dict)dropped_css_svg_element_map: dict[str, bool] = field(default_factory=dict)max_screenshot_scrolls: int | None = None@@ -739,6 +743,13 @@ class SkyvernContext:del self.download_popup_claims[task_id]return True+ def has_download_popup_claim(self, task_id: str, page: Page) -> bool:+ """Identity read: is this exact Page still held as a task-scoped download-popup claim."""+ claims = self.download_popup_claims.get(task_id)+ if not claims:+ return False+ return any(existing is page for existing in claims)+def take_download_popup_claims(self, task_id: str) -> list[Page]:return self.download_popup_claims.pop(task_id, [])diff --git a/skyvern/webeye/actions/actions.py b/skyvern/webeye/actions/actions.pyindex 40d89b74a..4f7ea048c 100644--- a/skyvern/webeye/actions/actions.py+++ b/skyvern/webeye/actions/actions.py@@ -315,6 +315,10 @@ class ClosePageAction(Action):action_type: ActionType = ActionType.CLOSE_PAGE# When set, close the open tab at this index in the open-tabs list instead of the current tab.tab_index: int | None = None+ # Set only when the agent synthesized this close to recover from a dead blank working page.+ # Persists into action_json via model_dump; gates the recovery recheck, the completed-step+ # guards, and the cached-script marker filter.+ is_internal_recovery: bool = Falseclass NewTabAction(Action):diff --git a/skyvern/webeye/actions/handler.py b/skyvern/webeye/actions/handler.pyindex bf8cc674b..0615de6e0 100644--- a/skyvern/webeye/actions/handler.py+++ b/skyvern/webeye/actions/handler.py@@ -168,6 +168,7 @@ from skyvern.webeye.actions.actions import (ActionStatus,CheckboxAction,ClickAction,+ ClosePageAction,CompleteVerifyResult,DownloadFileAction,InputOrSelectContext,@@ -225,6 +226,8 @@ from skyvern.webeye.scraper.scraped_page import (from skyvern.webeye.scraper.scraper import (IncrementalScrapePage,hash_element,+ page_is_dead_blank,+ page_is_http_survivor,structural_identity,trim_element_tree,)@@ -4604,8 +4607,15 @@ class ActionHandler:# download credit. Identity-based, before any action-specific branch so it covers the false-click,# explicit-download, and non-download paths alike; recovery rebinds and switch-tab adoption are the# next action entry's transfer, not this one.+ # An internal-recovery close must NOT retire the dead page's claim here: the recovery guard+ # below reads it to fail closed on a claimed download popup, so retiring it would blind that+ # check and let recovery close a page that is still capturing a download._reuse_owning_context = skyvern_context.current()- if _reuse_owning_context is not None and _reuse_owning_context.discard_download_popup_claim(task.task_id, page):+ if (+ not (isinstance(action, ClosePageAction) and action.is_internal_recovery)+ and _reuse_owning_context is not None+ and _reuse_owning_context.discard_download_popup_claim(task.task_id, page)+ ):with contained_effect("retire reused download popup claim"):LOG.info("Retired download popup claim for reused page",@@ -10767,6 +10777,24 @@ async def handle_close_page_action(step: Step,) -> list[ActionResult]:target_page = page+ if action.is_internal_recovery:+ # Sub-second, LLM-free recheck against the page as it is now: only close it if it is still a+ # dead blank, another usable page survives, and it holds no download-popup claim. Any drift+ # declines with a non-terminal failure so the next cycle re-detects.+ browser_state = app.BROWSER_MANAGER.get_for_task(task.task_id, workflow_run_id=task.workflow_run_id)+ ctx = skyvern_context.current()+ pages = await browser_state.list_valid_pages(max_pages=0) if browser_state is not None else []+ if (+ not page_is_dead_blank(page)+ or not any(p is not page and page_is_http_survivor(p) for p in pages)+ or (ctx is not None and ctx.has_download_popup_claim(task.task_id, page))+ ):+ return [+ ActionFailure(+ Exception("recovery close declined: page state changed"),+ stop_execution_on_failure=False,+ )+ ]if action.tab_index is not None:browser_state = app.BROWSER_MANAGER.get_for_task(task.task_id, workflow_run_id=task.workflow_run_id)if browser_state is None:diff --git a/skyvern/webeye/scraper/scraper.py b/skyvern/webeye/scraper/scraper.pyindex 27528aeb0..616b79e51 100644--- a/skyvern/webeye/scraper/scraper.py+++ b/skyvern/webeye/scraper/scraper.py@@ -3,6 +3,7 @@ import copyimport jsonfrom collections import defaultdictfrom typing import TYPE_CHECKING, Any+from urllib.parse import urlparseimport structlogfrom opentelemetry import trace as otel_trace@@ -35,7 +36,7 @@ from skyvern.forge.sdk.trace import apply_context_attrs, traced, traced_spanfrom skyvern.utils.image_resizer import Resolutionfrom skyvern.utils.token_counter import approx_count_tokensfrom skyvern.utils.url_validators import strip_query_params-from skyvern.webeye.browser_state import BrowserState+from skyvern.webeye.browser_state import BLANK_PAGE_URLS, BrowserStatefrom skyvern.webeye.scraper.scraped_page import (CleanupElementTreeFunc,ElementTreeBuilder,@@ -516,6 +517,23 @@ def _record_scrape_span_attrs(span.set_attribute("screenshots_consumed", ctx.scrape_screenshots_consumed)+def page_has_meaningful_child_frame(page: Page) -> bool:+ # Blank/empty frame urls (ad iframes, tracking pixels, detached frames) don't make a blank page+ # scrapeable; a real child frame (e.g. an Edge PDF interstitial rendered on about:blank) does.+ return any(f.url and f.url not in ("about:blank", "") for f in page.main_frame.child_frames)+++def page_is_dead_blank(page: Page) -> bool:+ return page.url in BLANK_PAGE_URLS and not page_has_meaningful_child_frame(page)+++def page_is_http_survivor(page: Page) -> bool:+ # A usable fallback target: an open http/https page. Blank (":"/"about:blank") and+ # chrome-error:// pages are not survivors, so recovery stays fail-closed when only dead pages+ # remain (planning and execution-time rechecks share this one definition).+ return not page.is_closed() and urlparse(page.url).scheme in ("http", "https")++@traced(name="skyvern.agent.scrape")async def scrape_web_unsafe(browser_state: BrowserState,@@ -555,17 +573,13 @@ async def scrape_web_unsafe(# This also solves the issue where we can't scroll due to a popup.(e.g. geico first popup on the homepage after# clicking start my quote)url = page.url- if url == "about:blank" and not support_empty_page:- # Allow scraping if the page has child frames with meaningful content- # (e.g., Edge PDF interstitial pages render content via iframes on about:blank).- # Filter out empty/blank frames (ad iframes, tracking pixels, detached frames).- meaningful_frames = [f for f in page.main_frame.child_frames if f.url and f.url not in ("about:blank", "")]- if not meaningful_frames:+ if url in BLANK_PAGE_URLS and not support_empty_page:+ # A blank working page (about:blank or the ":" download-popup shape) is only scrapeable when+ # a meaningful child frame renders real content (e.g. an Edge PDF interstitial); otherwise it+ # is a dead blank and must fail classification so the caller can recover or fail closed.+ if not page_has_meaningful_child_frame(page):raise ScrapingFailedBlankPage()- LOG.info(- "about:blank page has meaningful child frames, proceeding with scraping",- frame_count=len(meaningful_frames),- )+ LOG.info("blank page has meaningful child frames, proceeding with scraping")skyvern_frame = await SkyvernFrame.create_instance(page, engine_selection=browser_state.engine_selection)await _wait_for_scrape_ready(skyvern_frame)diff --git a/tests/unit/test_agent_step_characterization.py b/tests/unit/test_agent_step_characterization.pyindex 733da0e6b..f94d23b82 100644--- a/tests/unit/test_agent_step_characterization.py+++ b/tests/unit/test_agent_step_characterization.py@@ -456,6 +456,134 @@ async def test_parallel_verification_marks_speculative_original_status(monkeypat# get_failure_reason_for_task is the only source of that reason for a terminated task; either# empty path below used to return None, which handle_completed_step then handed straight to# update_task, tripping the invariant and crashing the step as an "unexpected exception".+def _prime_blank_recovery(rig: AgentStepRig, *, survivors: list[str] | None = None, dead_url: str = ":") -> MagicMock:+ """Make the step-body scrape raise a dead-blank error and shape the browser so recovery can+ inspect a dead working page plus any survivors. Returns the dead working page mock."""+ from skyvern.exceptions import ScrapingFailedBlankPage++ dead_page = MagicMock()+ dead_page.url = dead_url+ dead_page.main_frame.child_frames = []+ dead_page.is_closed.return_value = False+ rig.browser_state.get_working_page = AsyncMock(return_value=dead_page)++ pages = [dead_page]+ for url in survivors or []:+ survivor = MagicMock()+ survivor.url = url+ survivor.is_closed.return_value = False+ pages.append(survivor)+ rig.browser_state.list_valid_pages = AsyncMock(return_value=pages)++ rig.agent.build_and_record_step_prompt = AsyncMock(side_effect=ScrapingFailedBlankPage())+ return dead_page+++async def test_dead_blank_working_page_recovers_by_injecting_internal_close(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ # A ":" working page with one http survivor: the step's plan is exactly one internal-recovery+ # ClosePageAction, synthesized with no action-plan LLM call, and the step completes.+ rig = make_agent_step_rig(monkeypatch)+ _prime_blank_recovery(rig, survivors=["https://survivor.test/app"])++ step, output = await rig.run()++ assert step.status == StepStatus.completed+ assert rig.llm_handler.await_count == 0+ assert output.actions is not None+ assert len(output.actions) == 1+ close = output.actions[0]+ assert close.action_type == ActionType.CLOSE_PAGE+ assert close.is_internal_recovery is True+ assert rig.action_handler.await_args.kwargs["action"] is close+ assert rig.context.empty_page_recovery_step_id == step.step_id+ assert rig.context.empty_page_recovery_attempts[rig.task.task_id] == 1+++async def test_dead_blank_without_http_survivor_reraises_to_terminal(monkeypatch: pytest.MonkeyPatch) -> None:+ from skyvern.exceptions import ScrapingFailedBlankPage++ # No usable survivor -> ineligible -> the original blank exception propagates to the terminal+ # handler, and nothing (no LLM, no action) is executed.+ rig = make_agent_step_rig(monkeypatch)+ _prime_blank_recovery(rig, survivors=[])++ with pytest.raises(ScrapingFailedBlankPage):+ await rig.run()+ assert rig.llm_handler.await_count == 0+ assert rig.action_handler.await_count == 0+ assert rig.task.task_id not in rig.context.empty_page_recovery_attempts+++async def test_dead_blank_recovery_cap_reraises_after_three_attempts(monkeypatch: pytest.MonkeyPatch) -> None:+ from skyvern.exceptions import ScrapingFailedBlankPage++ rig = make_agent_step_rig(monkeypatch)+ _prime_blank_recovery(rig, survivors=["https://survivor.test/app"])+ rig.context.empty_page_recovery_attempts[rig.task.task_id] = 3++ with pytest.raises(ScrapingFailedBlankPage):+ await rig.run()+ # The cap was already consumed; a 4th detection declines rather than injecting again.+ assert rig.action_handler.await_count == 0+ assert rig.context.empty_page_recovery_attempts[rig.task.task_id] == 3+++async def test_speculative_plan_consumption_resets_recovery_attempt_counter(monkeypatch: pytest.MonkeyPatch) -> None:+ from skyvern.forge.agent import SpeculativePlan++ # A step that consumes a successfully-scraped speculative plan (parallel-verification path) is a+ # successful scrape too, so it must reset the per-task recovery counter — otherwise the+ # "consecutive" cap silently becomes cumulative across non-adjacent blank incidents.+ rig = make_agent_step_rig(monkeypatch)+ rig.agent._persist_scrape_artifacts = AsyncMock()+ rig.context.empty_page_recovery_attempts[rig.task.task_id] = 2+ rig.context.speculative_plans[rig.step.step_id] = SpeculativePlan(+ scraped_page=rig.scraped_page,+ extract_action_prompt="prompt",+ use_caching=False,+ llm_json_response={"actions": [{"action_type": "CLICK", "element_id": "node-1"}]},+ )++ step, _output = await rig.run()++ assert step.status == StepStatus.completed+ assert rig.task.task_id not in rig.context.empty_page_recovery_attempts+++async def test_non_blank_scrape_failure_is_not_recovered(monkeypatch: pytest.MonkeyPatch) -> None:+ from skyvern.exceptions import ScrapingFailed++ # A generic scrape failure (not a dead blank) must propagate untouched: recovery only ever adds a+ # path for the blank signature, never intercepts other terminal scrape errors.+ rig = make_agent_step_rig(monkeypatch)+ rig.agent.build_and_record_step_prompt = AsyncMock(side_effect=ScrapingFailed())++ with pytest.raises(ScrapingFailed):+ await rig.run()+ assert rig.action_handler.await_count == 0+ assert rig.task.task_id not in rig.context.empty_page_recovery_attempts+++async def test_successful_scrape_resets_recovery_attempt_counter(monkeypatch: pytest.MonkeyPatch) -> None:+ # A normal (non-blank) step-body scrape clears a prior task's recovery counter so the next dead+ # blank starts from a fresh budget.+ rig = make_agent_step_rig(monkeypatch)+ rig.context.empty_page_recovery_attempts[rig.task.task_id] = 2++ step, _output = await rig.run()++ assert step.status == StepStatus.completed+ assert rig.task.task_id not in rig.context.empty_page_recovery_attempts++@pytest.mark.asyncioasync def test_get_failure_reason_for_task_falls_back_when_terminate_reasoning_is_empty(monkeypatch: pytest.MonkeyPatch,diff --git a/tests/unit/test_empty_page_recovery.py b/tests/unit/test_empty_page_recovery.pynew file mode 100644index 000000000..fcf3396dd--- /dev/null+++ b/tests/unit/test_empty_page_recovery.py@@ -0,0 +1,314 @@+"""Empty-page recovery: close a dead blank working page and fall back to a survivor.++Covers the scraper blank predicate, the scrape-ladder blank-evidence preservation, the+handle_completed_step ActionBlock/max-step guards for a recovery-only step, the download-popup+claim read, and the cached-script generation marker filter.+"""++from __future__ import annotations++from datetime import UTC, datetime+from unittest.mock import AsyncMock, MagicMock++import pytest++from skyvern.exceptions import FailedToReloadPage, ScrapingFailedBlankPage+from skyvern.forge.agent import ForgeAgent+from skyvern.forge.sdk.core import skyvern_context+from skyvern.forge.sdk.core.skyvern_context import SkyvernContext+from skyvern.forge.sdk.models import StepStatus+from skyvern.forge.sdk.workflow.models.block import ActionBlock+from skyvern.schemas.steps import AgentStepOutput+from skyvern.webeye.actions.actions import ClosePageAction+from skyvern.webeye.actions.responses import ActionSuccess+from skyvern.webeye.scraper.scraper import (+ page_has_meaningful_child_frame,+ page_is_dead_blank,+ page_is_http_survivor,+ scrape_web_unsafe,+)+from tests.unit.helpers import make_organization, make_step, make_task+++def _frame(url: str) -> MagicMock:+ frame = MagicMock()+ frame.url = url+ return frame+++def _page(url: str, child_frame_urls: list[str] | None = None) -> MagicMock:+ page = MagicMock()+ page.url = url+ page.main_frame.child_frames = [_frame(u) for u in (child_frame_urls or [])]+ return page+++# ---- Case 1: scraper blank predicate + raise -------------------------------------------------+++ ("url", "child_frame_urls", "expected"),+ [+ (":", [], True),+ ("about:blank", [], True),+ (":", ["about:blank", ""], True), # blank/empty frames are not meaningful+ (":", ["https://real.test/app"], False), # meaningful frame -> not a dead blank+ ("about:blank", ["https://real.test/app"], False),+ ("https://real.test/app", [], False),+ ],+)+def test_page_is_dead_blank(url: str, child_frame_urls: list[str], expected: bool) -> None:+ assert page_is_dead_blank(_page(url, child_frame_urls)) is expected+++def test_page_has_meaningful_child_frame_filters_blank_and_empty() -> None:+ assert page_has_meaningful_child_frame(_page(":", ["about:blank", ""])) is False+ assert page_has_meaningful_child_frame(_page(":", ["https://real.test"])) is True+++ ("url", "is_closed", "expected"),+ [+ ("https://real.test/app", False, True),+ ("http://real.test", False, True),+ (":", False, False), # dead blank is not a survivor+ ("about:blank", False, False),+ ("chrome-error://chromewebdata/", False, False), # error tab is not a survivor+ ("https://real.test/app", True, False), # closed http page is not a survivor+ ],+)+def test_page_is_http_survivor(url: str, is_closed: bool, expected: bool) -> None:+ page = MagicMock()+ page.url = url+ page.is_closed.return_value = is_closed+ assert page_is_http_survivor(page) is expected+++async def test_scrape_raises_blank_for_colon_page_without_meaningful_frames() -> None:+ # The production incident signature: the working page's url is ":" with no meaningful child+ # frame. On main this url slips past the about:blank-only guard; it must now be classified blank.+ browser_state = MagicMock()+ browser_state.must_get_working_page = AsyncMock(return_value=_page(":", []))++ with pytest.raises(ScrapingFailedBlankPage):+ await scrape_web_unsafe(browser_state, "https://real.test", AsyncMock())+++async def test_scrape_does_not_raise_blank_when_support_empty_page() -> None:+ # Negative: an empty-page-tolerant scrape never classifies the dead blank, so recovery never+ # arms for those callers (the support_empty_page escape is preserved).+ browser_state = MagicMock()+ browser_state.must_get_working_page = AsyncMock(return_value=_page(":", []))++ with pytest.raises(Exception) as exc_info:+ await scrape_web_unsafe(browser_state, "https://real.test", AsyncMock(), support_empty_page=True)+ assert not isinstance(exc_info.value, ScrapingFailedBlankPage)+++async def test_scrape_does_not_classify_colon_page_with_meaningful_frame_as_blank() -> None:+ # A ":" page carrying a meaningful child frame is not a dead blank; it must not raise the blank+ # classification (it proceeds into normal scraping, which then fails on the bare mock elsewhere).+ browser_state = MagicMock()+ browser_state.must_get_working_page = AsyncMock(return_value=_page(":", ["https://real.test/app"]))++ with pytest.raises(Exception) as exc_info:+ await scrape_web_unsafe(browser_state, "https://real.test", AsyncMock())+ assert not isinstance(exc_info.value, ScrapingFailedBlankPage)+++# ---- Case 2: scrape ladder preserves the earlier blank evidence -----------------------------+++async def test_ladder_reraises_blank_even_when_final_rung_fails_to_reload(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ agent = ForgeAgent()+ now = datetime.now(UTC)+ organization = make_organization(now)+ task = make_task(now, organization, navigation_goal="do it", workflow_run_id="wr-ladder")+ step = make_step(now, task, step_id="step-ladder", status=StepStatus.running, order=0, output=None)++ # NORMAL and STOPLOADING see the blank page; the final RELOAD rung fails to reload the+ # uncommitted ":" page. The ladder must surface the blank evidence, not the reload failure.+ side_effects = [+ ScrapingFailedBlankPage(),+ ScrapingFailedBlankPage(),+ FailedToReloadPage(url="https://real.test", error_message="cannot reload :"),+ ]+ agent._scrape_with_type = AsyncMock(side_effect=side_effects)+ agent._persist_scrape_artifacts = AsyncMock()++ context = SkyvernContext(task_id=task.task_id, organization_id=task.organization_id)+ skyvern_context.set(context)+ try:+ with pytest.raises(ScrapingFailedBlankPage):+ await agent.build_and_record_step_prompt(task, step, MagicMock(), engine=None) # type: ignore[arg-type]+ finally:+ skyvern_context.reset()+++# ---- Case 4: outer contract -- a recovery-only step does not complete an ActionBlock ---------+++def _recovery_step(now: datetime, task, *, order: int):+ output = AgentStepOutput(actions_and_results=[(ClosePageAction(is_internal_recovery=True), [ActionSuccess()])])+ return make_step(now, task, step_id="step-recovery", status=StepStatus.completed, order=order, output=output)+++async def _run_handle_completed_step(monkeypatch: pytest.MonkeyPatch, *, mark_recovery: bool):+ agent = ForgeAgent()+ now = datetime.now(UTC)+ organization = make_organization(now)+ # max_steps_per_run=1 is the ActionBlock default; step.order+1 would trip the max-steps failure.+ task = make_task(now, organization, navigation_goal="do it", workflow_run_id="wr-block", max_steps_per_run=1)+ step = _recovery_step(now, task, order=0)++ agent._check_workflow_run_step_budget = AsyncMock(return_value=None)+ agent.update_step = AsyncMock(side_effect=lambda s, *a, **k: s)+ agent.update_task = AsyncMock(side_effect=lambda t, *a, **k: t)+ next_step_sentinel = MagicMock(name="next_step")+ monkeypatch.setattr(+ "skyvern.forge.agent.app.DATABASE.tasks.create_step",+ AsyncMock(return_value=next_step_sentinel),+ )++ context = SkyvernContext(task_id=task.task_id, organization_id=task.organization_id)+ if mark_recovery:+ context.empty_page_recovery_step_id = step.step_id+ skyvern_context.set(context)+ try:+ return next_step_sentinel, await agent.handle_completed_step(+ organization=organization,+ task=task,+ step=step,+ page=MagicMock(),+ task_block=ActionBlock.model_construct(label="b", max_steps_per_run=1),+ browser_state=MagicMock(),+ scraped_page=None,+ )+ finally:+ skyvern_context.reset()+++async def _run_navigation_completed_step(monkeypatch: pytest.MonkeyPatch, *, mark_recovery: bool):+ # A non-ActionBlock navigation task with goal verification enabled: without a recovery guard this+ # routes through the parallel-verification path, which applies its own unconditional max-step+ # failure and would fail a recovery step on the last allowed step (violating invariant I3).+ agent = ForgeAgent()+ now = datetime.now(UTC)+ organization = make_organization(now)+ task = make_task(now, organization, navigation_goal="do it", workflow_run_id="wr-nav", max_steps_per_run=1)+ step = _recovery_step(now, task, order=0)++ agent._check_workflow_run_step_budget = AsyncMock(return_value=None)+ agent.update_step = AsyncMock(side_effect=lambda s, *a, **k: s)+ agent.update_task = AsyncMock(side_effect=lambda t, *a, **k: t)+ agent.summary_failure_reason_for_max_steps = AsyncMock()+ next_step_sentinel = MagicMock(name="next_step")+ monkeypatch.setattr(+ "skyvern.forge.agent.app.DATABASE.tasks.create_step",+ AsyncMock(return_value=next_step_sentinel),+ )+ # DISABLE_USER_GOAL_CHECK=False => verification would dispatch unless the step is recovery-only.+ monkeypatch.setattr(+ "skyvern.forge.agent.app.EXPERIMENTATION_PROVIDER.is_feature_enabled_cached",+ AsyncMock(return_value=False),+ )+ parallel_sentinel = MagicMock(name="parallel_result")+ parallel = AsyncMock(return_value=parallel_sentinel)+ agent._handle_completed_step_with_parallel_verification = parallel++ context = SkyvernContext(task_id=task.task_id, organization_id=task.organization_id)+ if mark_recovery:+ context.empty_page_recovery_step_id = step.step_id+ skyvern_context.set(context)+ try:+ result = await agent.handle_completed_step(+ organization=organization,+ task=task,+ step=step,+ page=MagicMock(),+ task_block=None,+ browser_state=MagicMock(),+ scraped_page=MagicMock(),+ )+ return next_step_sentinel, parallel, result+ finally:+ skyvern_context.reset()+++async def test_recovery_only_navigation_step_skips_parallel_verification(monkeypatch: pytest.MonkeyPatch) -> None:+ next_step_sentinel, parallel, (task_result, last_step, created_next) = await _run_navigation_completed_step(+ monkeypatch, mark_recovery=True+ )+ # Recovery-only steps must not be routed through parallel verification (which would apply its own+ # unconditional max-step failure); they take the guarded path and create the next step.+ parallel.assert_not_awaited()+ assert task_result is None+ assert created_next is next_step_sentinel+++async def test_non_recovery_navigation_step_still_uses_parallel_verification(monkeypatch: pytest.MonkeyPatch) -> None:+ # Control: an ordinary navigation step with verification enabled still dispatches parallel+ # verification. Proves the recovery marker is what diverts, not the setup.+ _next, parallel, result = await _run_navigation_completed_step(monkeypatch, mark_recovery=False)+ parallel.assert_awaited_once()+ assert result is parallel.return_value+++async def test_recovery_step_does_not_complete_or_maxstep_fail_action_block(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ next_step_sentinel, (task_result, last_step, created_next) = await _run_handle_completed_step(+ monkeypatch, mark_recovery=True+ )+ # The block is neither completed (True) nor max-step-failed (False, last_step); a next step runs+ # so the block's real action still gets its chance.+ assert task_result is None+ assert last_step is None+ assert created_next is next_step_sentinel+++async def test_non_recovery_success_still_completes_action_block(monkeypatch: pytest.MonkeyPatch) -> None:+ # Control: without the recovery marker, the same successful step completes the ActionBlock via the+ # pre-existing single-step hack. Proves the guard is what discriminates, not the setup.+ _next, (task_result, _last_step, created_next) = await _run_handle_completed_step(monkeypatch, mark_recovery=False)+ assert task_result is True+ assert created_next is None+++# ---- download-popup claim read ---------------------------------------------------------------+++def test_has_download_popup_claim_is_identity_based() -> None:+ context = SkyvernContext(task_id="tsk", organization_id="o")+ claimed = MagicMock()+ other = MagicMock()+ context.record_download_popup_claim("tsk", claimed)++ assert context.has_download_popup_claim("tsk", claimed) is True+ assert context.has_download_popup_claim("tsk", other) is False+ assert context.has_download_popup_claim("other-task", claimed) is False+++# ---- Case 8: cached-script generation skips the recovery marker ------------------------------+++def test_generate_script_skips_internal_recovery_close_action() -> None:+ from skyvern.core.script_generations.generate_script import _build_block_fn++ recovery_action = {"action_type": "close_page", "is_internal_recovery": True}+ block = {"block_type": "navigation", "label": "b", "actions": [recovery_action]}++ # The recovery close has no ACTION_MAP entry; without the marker filter _action_to_stmt raises+ # KeyError and aborts whole-script generation. The filter must drop it so generation succeeds.+ fn = _build_block_fn(block, actions=[recovery_action])+ assert fn is not Nonediff --git a/tests/unit/test_tab_action_handlers.py b/tests/unit/test_tab_action_handlers.pyindex 45b77e44f..7711ad466 100644--- a/tests/unit/test_tab_action_handlers.py+++ b/tests/unit/test_tab_action_handlers.py@@ -1,5 +1,6 @@"""Tests for the NEW_TAB / SWITCH_TAB / CLOSE_PAGE action handlers."""+from datetime import UTC, datetimefrom unittest.mock import AsyncMock, MagicMock, patchimport pytest@@ -7,13 +8,16 @@ import pytestfrom skyvern.exceptions import FailedToNavigateToUrlfrom skyvern.forge.sdk.core import skyvern_contextfrom skyvern.forge.sdk.core.skyvern_context import SkyvernContext+from skyvern.forge.sdk.models import StepStatusfrom skyvern.webeye.actions import actionsfrom skyvern.webeye.actions.handler import (+ ActionHandler,handle_close_page_action,handle_new_tab_action,handle_switch_tab_action,)from skyvern.webeye.actions.responses import ActionFailure, ActionSuccess+from tests.unit.helpers import make_organization, make_step, make_taskdef _task() -> MagicMock:@@ -23,6 +27,22 @@ def _task() -> MagicMock:return task+def _dead_blank_page(url: str = ":") -> MagicMock:+ page = MagicMock()+ page.url = url+ page.main_frame.child_frames = []+ page.is_closed.return_value = False+ page.close = AsyncMock()+ return page+++def _survivor_page() -> MagicMock:+ page = MagicMock()+ page.url = "https://survivor.test/app"+ page.is_closed.return_value = False+ return page++def _mock_app(browser_state: MagicMock) -> MagicMock:mock_app = MagicMock()# get_for_task is synchronous and returns the browser state for the task.@@ -189,3 +209,155 @@ async def test_close_page_out_of_range_fails_without_stopping_step() -> None:assert isinstance(result[0], ActionFailure)assert result[0].stop_execution_on_failure is Falsecurrent_page.close.assert_not_awaited()+++# ---- Empty-page recovery guard on the internal-recovery close -------------------------------+++async def test_recovery_close_closes_page_still_dead_blank_with_survivor() -> None:+ dead = _dead_blank_page(":")+ browser_state = MagicMock()+ browser_state.list_valid_pages = AsyncMock(return_value=[dead, _survivor_page()])+ action = actions.ClosePageAction(is_internal_recovery=True)++ with patch("skyvern.webeye.actions.handler.app", _mock_app(browser_state)):+ with patch.object(skyvern_context, "current", return_value=SkyvernContext(run_id="wr")):+ result = await handle_close_page_action(action, dead, MagicMock(), _task(), MagicMock())++ assert isinstance(result[0], ActionSuccess)+ assert result[0].skip_remaining_actions is True+ dead.close.assert_awaited_once()+++async def test_recovery_close_declines_when_page_no_longer_blank() -> None:+ # The working page committed a real navigation during the sub-second window: decline, don't close.+ live = _dead_blank_page("https://real.test/now")+ browser_state = MagicMock()+ browser_state.list_valid_pages = AsyncMock(return_value=[live, _survivor_page()])+ action = actions.ClosePageAction(is_internal_recovery=True)++ with patch("skyvern.webeye.actions.handler.app", _mock_app(browser_state)):+ with patch.object(skyvern_context, "current", return_value=SkyvernContext(run_id="wr")):+ result = await handle_close_page_action(action, live, MagicMock(), _task(), MagicMock())++ assert isinstance(result[0], ActionFailure)+ assert result[0].stop_execution_on_failure is False+ live.close.assert_not_awaited()+++async def test_recovery_close_declines_when_no_other_valid_page() -> None:+ dead = _dead_blank_page(":")+ browser_state = MagicMock()+ browser_state.list_valid_pages = AsyncMock(return_value=[dead])+ action = actions.ClosePageAction(is_internal_recovery=True)++ with patch("skyvern.webeye.actions.handler.app", _mock_app(browser_state)):+ with patch.object(skyvern_context, "current", return_value=SkyvernContext(run_id="wr")):+ result = await handle_close_page_action(action, dead, MagicMock(), _task(), MagicMock())++ assert isinstance(result[0], ActionFailure)+ dead.close.assert_not_awaited()+++async def test_recovery_close_declines_when_only_other_page_is_not_http_survivor() -> None:+ # The healthy HTTP(S) page used at planning time closed/navigated to an error during the window,+ # leaving only another dead page (a chrome-error tab). Execution-time revalidation must fail+ # closed on the missing healthy survivor rather than close the current page and strand the run.+ dead = _dead_blank_page(":")+ other_dead = _dead_blank_page("chrome-error://chromewebdata/")+ browser_state = MagicMock()+ browser_state.list_valid_pages = AsyncMock(return_value=[dead, other_dead])+ action = actions.ClosePageAction(is_internal_recovery=True)++ with patch("skyvern.webeye.actions.handler.app", _mock_app(browser_state)):+ with patch.object(skyvern_context, "current", return_value=SkyvernContext(run_id="wr")):+ result = await handle_close_page_action(action, dead, MagicMock(), _task(), MagicMock())++ assert isinstance(result[0], ActionFailure)+ assert result[0].stop_execution_on_failure is False+ dead.close.assert_not_awaited()+++async def test_recovery_close_declines_when_dead_page_holds_download_claim() -> None:+ dead = _dead_blank_page(":")+ browser_state = MagicMock()+ browser_state.list_valid_pages = AsyncMock(return_value=[dead, _survivor_page()])+ task = _task()+ context = SkyvernContext(run_id="wr", task_id=task.task_id)+ context.record_download_popup_claim(task.task_id, dead)+ action = actions.ClosePageAction(is_internal_recovery=True)++ with patch("skyvern.webeye.actions.handler.app", _mock_app(browser_state)):+ with patch.object(skyvern_context, "current", return_value=context):+ result = await handle_close_page_action(action, dead, MagicMock(), task, MagicMock())++ assert isinstance(result[0], ActionFailure)+ dead.close.assert_not_awaited()+++async def test_user_close_is_not_gated_by_blank_recovery_guard() -> None:+ # A user-emitted close (marker false) skips the recovery recheck entirely and closes as before,+ # even on a page that happens to be blank.+ dead = _dead_blank_page(":")++ result = await handle_close_page_action(actions.ClosePageAction(), dead, MagicMock(), _task(), MagicMock())++ assert isinstance(result[0], ActionSuccess)+ dead.close.assert_awaited_once()+++def _handle_action_deps(browser_state: MagicMock) -> MagicMock:+ app_mock = _mock_app(browser_state)+ app_mock.AGENT_FUNCTION.wait_for_challenge_solver = AsyncMock()+ app_mock.DATABASE.workflow_params.create_action = AsyncMock(return_value=MagicMock(action_id="a1"))+ return app_mock+++async def test_handle_action_preserves_download_claim_for_recovery_close() -> None:+ # The action wrapper must NOT retire the dead page's popup claim for an internal-recovery close,+ # so the handler guard can still read it. _handle_action is stubbed to isolate the wrapper.+ now = datetime.now(UTC)+ task = make_task(now, make_organization(now), task_id="tsk_recovery", workflow_run_id="wr")+ step = make_step(now, task, step_id="step-x", status=StepStatus.running, order=0, output=None)+ dead = _dead_blank_page(":")+ context = SkyvernContext(task_id=task.task_id)+ context.record_download_popup_claim(task.task_id, dead)+ action = actions.ClosePageAction(is_internal_recovery=True)++ with (+ patch.object(ActionHandler, "_handle_action", AsyncMock(return_value=[ActionSuccess()])),+ patch("skyvern.webeye.actions.handler.app", _handle_action_deps(MagicMock())),+ patch("skyvern.webeye.actions.handler.skyvern_context.current", return_value=context),+ ):+ await ActionHandler.handle_action(MagicMock(), task, step, dead, action)++ assert context.has_download_popup_claim(task.task_id, dead) is True+++async def test_handle_action_retires_download_claim_for_user_close() -> None:+ # Control: a user-emitted close is still treated as accepting the page as navigation state, so+ # the wrapper retires its stale claim. Proves the bypass is marker-gated, not blanket close_page.+ now = datetime.now(UTC)+ task = make_task(now, make_organization(now), task_id="tsk_user", workflow_run_id="wr")+ step = make_step(now, task, step_id="step-x", status=StepStatus.running, order=0, output=None)+ dead = _dead_blank_page(":")+ context = SkyvernContext(task_id=task.task_id)+ context.record_download_popup_claim(task.task_id, dead)+ action = actions.ClosePageAction()++ with (+ patch.object(ActionHandler, "_handle_action", AsyncMock(return_value=[ActionSuccess()])),+ patch("skyvern.webeye.actions.handler.app", _handle_action_deps(MagicMock())),+ patch("skyvern.webeye.actions.handler.skyvern_context.current", return_value=context),+ ):+ await ActionHandler.handle_action(MagicMock(), task, step, dead, action)++ assert context.has_download_popup_claim(task.task_id, dead) is False