Skip to content

Automate browser based workflows with AI

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.py
index 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"):
+ continue
if act["action_type"] in [
ActionType.COMPLETE,
ActionType.TERMINATE,
diff --git a/skyvern/forge/agent.py b/skyvern/forge/agent.py
index 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_url
from skyvern.webeye.scraper.scraped_page import ElementTreeFormat, ScrapedPage
+from skyvern.webeye.scraper.scraper import page_is_dead_blank, page_is_http_survivor
from skyvern.webeye.utils.page import OTP_INPUT_PRIVACY_JS, SkyvernFrame, build_open_tabs_context
LOG = 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 = 3
EXTRACT_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 None
speculative_llm_metadata = speculative_plan.llm_metadata
prompt_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_page
detailed_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 = None
for idx, scrape_type in enumerate(SCRAPE_TYPE_ORDER):
try:
scraped_page = await self._scrape_with_type(
@@ -6201,6 +6291,11 @@ class ForgeAgent:
)
break
except (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 = e
if 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 e
if 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 happen
task_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_only
and (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.py
index 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.py
index 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 = False
class NewTabAction(Action):
diff --git a/skyvern/webeye/actions/handler.py b/skyvern/webeye/actions/handler.py
index 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.py
index 27528aeb0..616b79e51 100644
--- a/skyvern/webeye/scraper/scraper.py
+++ b/skyvern/webeye/scraper/scraper.py
@@ -3,6 +3,7 @@ import copy
import json
from collections import defaultdict
from typing import TYPE_CHECKING, Any
+from urllib.parse import urlparse
import structlog
from opentelemetry import trace as otel_trace
@@ -35,7 +36,7 @@ from skyvern.forge.sdk.trace import apply_context_attrs, traced, traced_span
from skyvern.utils.image_resizer import Resolution
from skyvern.utils.token_counter import approx_count_tokens
from skyvern.utils.url_validators import strip_query_params
-from skyvern.webeye.browser_state import BrowserState
+from skyvern.webeye.browser_state import BLANK_PAGE_URLS, BrowserState
from 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.py
index 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.asyncio
async 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.py
new file mode 100644
index 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 None
diff --git a/tests/unit/test_tab_action_handlers.py b/tests/unit/test_tab_action_handlers.py
index 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, datetime
from unittest.mock import AsyncMock, MagicMock, patch
import pytest
@@ -7,13 +8,16 @@ import pytest
from skyvern.exceptions import FailedToNavigateToUrl
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.webeye.actions import actions
from 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_task
def _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 False
current_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