Skip to content

Automate browser based workflows with AI

fix(SKY-9871): drop blank late download artifacts (#6017)

Aaron Perez37237f71fc46
diff --git a/skyvern/webeye/actions/handler.py b/skyvern/webeye/actions/handler.py
index fe69bb223..70a71375f 100644
--- a/skyvern/webeye/actions/handler.py
+++ b/skyvern/webeye/actions/handler.py
@@ -125,6 +125,7 @@ from skyvern.webeye.utils.page import SkyvernFrame
LOG = structlog.get_logger()
DOWNLOAD_EVENT_ACTIVE_DIR_GRACE_SECONDS = 60
+DOWNLOAD_DUPLICATE_STEM_SUFFIX_RE = re.compile(r"(?:\s+\(\d{1,3}\)|_\d{1,3})$")
def _download_target_path(download_dir: Path, suggested_filename: str | None) -> Path:
@@ -147,6 +148,112 @@ def _remove_download_listener(page: Page, callback: Callable[[Download], None])
LOG.warning("Page does not support removing download listeners")
+def _canonical_download_duplicate_stem(stem: str) -> str:
+ """Return a stem with common browser duplicate suffixes removed."""
+ return DOWNLOAD_DUPLICATE_STEM_SUFFIX_RE.sub("", stem)
+
+
+def _has_download_duplicate_suffix(stem: str) -> bool:
+ """Return whether a stem carries a browser duplicate suffix."""
+ return _canonical_download_duplicate_stem(stem) != stem
+
+
+def _is_empty_duplicate_download_placeholder(file_path: str, non_empty_file_paths: set[str]) -> bool:
+ """Return whether a 0-byte local file is a duplicate-name placeholder.
+
+ Empty exports can be valid artifacts, so only remove a 0-byte file when a
+ file carrying a browser duplicate suffix has the same extension and
+ canonical stem as a non-empty local file, such as ``report_1.pdf`` next to
+ ``report.pdf``.
+ """
+ file_dir = os.path.dirname(file_path)
+ file_stem, file_suffix = os.path.splitext(os.path.basename(file_path))
+ if not _has_download_duplicate_suffix(file_stem):
+ return False
+
+ file_canonical_stem = _canonical_download_duplicate_stem(file_stem)
+
+ for non_empty_file_path in non_empty_file_paths:
+ if os.path.dirname(non_empty_file_path) != file_dir:
+ continue
+
+ non_empty_stem, non_empty_suffix = os.path.splitext(os.path.basename(non_empty_file_path))
+ if non_empty_suffix != file_suffix:
+ continue
+
+ non_empty_canonical_stem = _canonical_download_duplicate_stem(non_empty_stem)
+ if file_stem != non_empty_stem and file_canonical_stem == non_empty_canonical_stem:
+ return True
+
+ return False
+
+
+def _deduplicate_new_downloaded_file_paths(
+ new_file_paths: set[str],
+ workflow_run_id: str | None,
+ observed_file_paths: set[str] | None = None,
+) -> list[str]:
+ """Filter junk local downloads and remove checksum duplicates.
+
+ Remote browser-session URIs are returned untouched because the action
+ process cannot hash or delete them locally. Local 0-byte files are removed
+ only when they look like duplicate-name placeholders for a non-empty file
+ observed in the run directory.
+ """
+ non_empty_file_paths: set[str] = set()
+ for fp in observed_file_paths or new_file_paths:
+ if not os.path.isfile(fp):
+ continue
+ try:
+ if os.path.getsize(fp) > 0:
+ non_empty_file_paths.add(fp)
+ except OSError:
+ continue
+
+ seen_checksums: dict[str, str] = {}
+ deduplicated_paths: list[str] = []
+ for fp in sorted(new_file_paths):
+ if not os.path.isfile(fp):
+ deduplicated_paths.append(fp)
+ continue
+
+ try:
+ file_size = os.path.getsize(fp)
+ if file_size == 0:
+ if _is_empty_duplicate_download_placeholder(fp, non_empty_file_paths):
+ LOG.warning(
+ "Removing 0-byte duplicate downloaded file placeholder",
+ file=os.path.basename(fp),
+ workflow_run_id=workflow_run_id,
+ )
+ os.remove(fp)
+ else:
+ deduplicated_paths.append(fp)
+ continue
+ checksum = calculate_sha256_for_file(fp)
+ except OSError:
+ LOG.warning(
+ "Downloaded file disappeared before deduplication",
+ file=os.path.basename(fp),
+ workflow_run_id=workflow_run_id,
+ exc_info=True,
+ )
+ continue
+
+ if checksum in seen_checksums:
+ LOG.info(
+ "Removing duplicate downloaded file from single action",
+ file=os.path.basename(fp),
+ duplicate_of=os.path.basename(seen_checksums[checksum]),
+ checksum=checksum,
+ )
+ os.remove(fp)
+ else:
+ seen_checksums[checksum] = fp
+ deduplicated_paths.append(fp)
+ return deduplicated_paths
+
+
async def _screenshot_without_cursor(page: Page, **kwargs: Any) -> bytes:
"""Take a screenshot with cursor overlay hidden so it doesn't interfere with LLM analysis."""
if SettingsManager.get_settings().BROWSER_CURSOR_VISUALIZATION:
@@ -681,30 +788,16 @@ class ActionHandler:
timeout=task.download_timeout or BROWSER_DOWNLOAD_TIMEOUT,
)
- # Calculate newly downloaded file names and deduplicate local files by checksum.
- # A single click can trigger multiple identical downloads (e.g., when an <a> click
- # event bubbles to a parent <tr onclick> that opens the same URL).
- # Only local files are deduplicated — remote URIs (s3://, azure://) from browser
- # sessions are passed through as-is since we cannot hash or remove them locally.
+ # Re-scan after waiting for .crdownload files to settle. The first
+ # snapshot stops at the earliest download signal, while late browser
+ # artifacts can still appear before task cleanup persists files.
+ list_files_after = await _list_observed_download_files()
new_file_paths = set(list_files_after) - set(list_files_before)
- seen_checksums: dict[str, str] = {}
- deduplicated_paths: list[str] = []
- for fp in sorted(new_file_paths):
- if not os.path.isfile(fp):
- deduplicated_paths.append(fp)
- continue
- checksum = calculate_sha256_for_file(fp)
- if checksum in seen_checksums:
- LOG.info(
- "Removing duplicate downloaded file from single action",
- file=os.path.basename(fp),
- duplicate_of=os.path.basename(seen_checksums[checksum]),
- checksum=checksum,
- )
- os.remove(fp)
- else:
- seen_checksums[checksum] = fp
- deduplicated_paths.append(fp)
+ deduplicated_paths = _deduplicate_new_downloaded_file_paths(
+ new_file_paths,
+ workflow_run_id=task.workflow_run_id,
+ observed_file_paths=set(list_files_after),
+ )
downloaded_file_names = [os.path.basename(fp) for fp in deduplicated_paths]
if downloaded_file_names:
results[-1].downloaded_files = downloaded_file_names
diff --git a/tests/unit/test_download_dedup.py b/tests/unit/test_download_dedup.py
index f2f4fb9c0..1376aedc4 100644
--- a/tests/unit/test_download_dedup.py
+++ b/tests/unit/test_download_dedup.py
@@ -9,8 +9,9 @@ checksum so only one copy is kept.
from __future__ import annotations
import os
+from pathlib import Path
-from skyvern.forge.sdk.api.files import calculate_sha256_for_file
+from skyvern.webeye.actions.handler import _deduplicate_new_downloaded_file_paths
def _write_file(directory: str, name: str, content: bytes) -> str:
@@ -20,24 +21,19 @@ def _write_file(directory: str, name: str, content: bytes) -> str:
return path
-def _deduplicate_new_files(new_file_paths: set[str]) -> list[str]:
- """Replicate the dedup logic from ActionHandler._handle_action_for_download."""
- seen_checksums: dict[str, str] = {}
- deduplicated: list[str] = []
- for fp in sorted(new_file_paths):
- if not os.path.isfile(fp):
- deduplicated.append(fp)
- continue
- checksum = calculate_sha256_for_file(fp)
- if checksum in seen_checksums:
- os.remove(fp)
- else:
- seen_checksums[checksum] = fp
- deduplicated.append(fp)
- return deduplicated
-
-
-def test_duplicate_files_are_deduplicated(tmp_path):
+def _deduplicate_new_files(
+ new_file_paths: set[str],
+ observed_file_paths: set[str] | None = None,
+) -> list[str]:
+ """Call the action handler helper with a stable test workflow id."""
+ return _deduplicate_new_downloaded_file_paths(
+ new_file_paths,
+ workflow_run_id="wr_test",
+ observed_file_paths=observed_file_paths,
+ )
+
+
+def test_duplicate_files_are_deduplicated(tmp_path: Path) -> None:
"""Two files with identical content should keep only one."""
dir_ = str(tmp_path)
a = _write_file(dir_, "report.xlsx", b"identical content")
@@ -49,7 +45,7 @@ def test_duplicate_files_are_deduplicated(tmp_path):
assert len(os.listdir(dir_)) == 1
-def test_duplicate_file_is_removed_from_disk(tmp_path):
+def test_duplicate_file_is_removed_from_disk(tmp_path: Path) -> None:
"""The duplicate file should be deleted from the local download directory."""
dir_ = str(tmp_path)
a = _write_file(dir_, "file_a.pdf", b"same bytes")
@@ -60,7 +56,7 @@ def test_duplicate_file_is_removed_from_disk(tmp_path):
assert len(os.listdir(dir_)) == 1
-def test_different_files_are_not_deduplicated(tmp_path):
+def test_different_files_are_not_deduplicated(tmp_path: Path) -> None:
"""Files with different content should both be kept."""
dir_ = str(tmp_path)
a = _write_file(dir_, "invoice_jan.xlsx", b"january data")
@@ -72,7 +68,7 @@ def test_different_files_are_not_deduplicated(tmp_path):
assert len(os.listdir(dir_)) == 2
-def test_three_duplicates_keeps_only_one(tmp_path):
+def test_three_duplicates_keeps_only_one(tmp_path: Path) -> None:
"""Three identical files should keep one and delete two."""
dir_ = str(tmp_path)
a = _write_file(dir_, "doc.pdf", b"triplicate")
@@ -85,7 +81,7 @@ def test_three_duplicates_keeps_only_one(tmp_path):
assert len(os.listdir(dir_)) == 1
-def test_mixed_unique_and_duplicate_files(tmp_path):
+def test_mixed_unique_and_duplicate_files(tmp_path: Path) -> None:
"""Mix of unique and duplicate files: only duplicates are removed."""
dir_ = str(tmp_path)
a = _write_file(dir_, "unique_a.xlsx", b"content A")
@@ -98,7 +94,7 @@ def test_mixed_unique_and_duplicate_files(tmp_path):
assert len(os.listdir(dir_)) == 2
-def test_original_filename_kept_over_suffixed_duplicate(tmp_path):
+def test_original_filename_kept_over_suffixed_duplicate(tmp_path: Path) -> None:
"""Sorted order keeps the original name over the _1 suffixed copy."""
dir_ = str(tmp_path)
a = _write_file(dir_, "Alignment-Feb-2026.xlsx", b"same content")
@@ -112,7 +108,7 @@ def test_original_filename_kept_over_suffixed_duplicate(tmp_path):
assert os.listdir(dir_) == ["Alignment-Feb-2026.xlsx"]
-def test_remote_uris_are_passed_through(tmp_path):
+def test_remote_uris_are_passed_through(tmp_path: Path) -> None:
"""S3/Azure URIs from browser sessions should not be hashed or removed."""
dir_ = str(tmp_path)
local = _write_file(dir_, "local.xlsx", b"local content")
@@ -124,3 +120,68 @@ def test_remote_uris_are_passed_through(tmp_path):
assert remote in result
assert local in result
assert len(os.listdir(dir_)) == 1 # only the local file on disk
+
+
+def test_zero_byte_duplicate_placeholder_is_removed_from_disk(tmp_path: Path) -> None:
+ """A blank duplicate-name placeholder should be deleted."""
+ dir_ = str(tmp_path)
+ valid = _write_file(dir_, "report.pdf", b"valid content")
+ empty = _write_file(dir_, "report_1.pdf", b"")
+
+ result = _deduplicate_new_files({empty, valid})
+
+ assert result == [valid]
+ assert os.listdir(dir_) == ["report.pdf"]
+
+
+def test_zero_byte_placeholder_matches_prior_observed_file(tmp_path: Path) -> None:
+ """A new blank duplicate is deleted when the real file predates the action."""
+ dir_ = str(tmp_path)
+ prior_valid = _write_file(dir_, "report.pdf", b"valid content")
+ new_empty = _write_file(dir_, "report_1.pdf", b"")
+
+ result = _deduplicate_new_files(
+ {new_empty},
+ observed_file_paths={prior_valid, new_empty},
+ )
+
+ assert result == []
+ assert os.listdir(dir_) == ["report.pdf"]
+
+
+def test_unsuffixed_zero_byte_file_is_preserved_with_prior_suffixed_file(tmp_path: Path) -> None:
+ """A new empty canonical filename is not deleted beside a prior suffixed file."""
+ dir_ = str(tmp_path)
+ prior_valid = _write_file(dir_, "report_1.pdf", b"valid content")
+ new_empty = _write_file(dir_, "report.pdf", b"")
+
+ result = _deduplicate_new_files(
+ {new_empty},
+ observed_file_paths={prior_valid, new_empty},
+ )
+
+ assert result == [new_empty]
+ assert sorted(os.listdir(dir_)) == ["report.pdf", "report_1.pdf"]
+
+
+def test_single_zero_byte_file_is_preserved_without_alternate(tmp_path: Path) -> None:
+ """A single empty download remains valid when no better artifact exists."""
+ dir_ = str(tmp_path)
+ empty = _write_file(dir_, "empty.csv", b"")
+
+ result = _deduplicate_new_files({empty})
+
+ assert result == [empty]
+ assert os.listdir(dir_) == ["empty.csv"]
+
+
+def test_named_zero_byte_file_is_preserved_with_non_empty_artifact(tmp_path: Path) -> None:
+ """An intentionally empty export should not be removed beside another file."""
+ dir_ = str(tmp_path)
+ empty_export = _write_file(dir_, "empty_rows.csv", b"")
+ manifest = _write_file(dir_, "manifest.csv", b"columns,row_count")
+
+ result = _deduplicate_new_files({empty_export, manifest})
+
+ assert set(result) == {empty_export, manifest}
+ assert sorted(os.listdir(dir_)) == ["empty_rows.csv", "manifest.csv"]
diff --git a/tests/unit/test_download_file_action_handler.py b/tests/unit/test_download_file_action_handler.py
index 8498e4a42..2afae2e6d 100644
--- a/tests/unit/test_download_file_action_handler.py
+++ b/tests/unit/test_download_file_action_handler.py
@@ -1,6 +1,7 @@
import os
import tempfile
import time
+from collections.abc import Callable
from datetime import UTC, datetime
from unittest.mock import AsyncMock, MagicMock, patch
@@ -462,7 +463,7 @@ async def test_handle_action_navigates_back_from_blank_page_after_download(
)
# _handle_action simulates the page navigating to about:blank during the print download
- async def mock_inner_handle_action(*args, **kwargs) -> list[ActionSuccess]:
+ async def mock_inner_handle_action(*args: object, **kwargs: object) -> list[ActionSuccess]:
page.url = "about:blank"
return [ActionSuccess()]
@@ -471,8 +472,8 @@ async def test_handle_action_navigates_back_from_blank_page_after_download(
with open(dummy_file, "w") as f:
f.write("dummy")
- # list_files_in_directory: empty before action, one file after action
- list_files_side_effect = [[], [dummy_file]]
+ # list_files_in_directory: empty before action, one file after action, re-scan after wait
+ list_files_side_effect = [[], [dummy_file], [dummy_file]]
mock_app = MagicMock()
mock_app.BROWSER_MANAGER.get_for_task.return_value = browser_state
@@ -542,7 +543,7 @@ async def test_handle_action_does_not_navigate_back_when_page_url_unchanged() ->
)
# _handle_action does NOT change the page URL (normal case)
- async def mock_inner_handle_action(*args, **kwargs) -> list[ActionSuccess]:
+ async def mock_inner_handle_action(*args: object, **kwargs: object) -> list[ActionSuccess]:
return [ActionSuccess()]
with tempfile.TemporaryDirectory() as temp_dir:
@@ -550,7 +551,7 @@ async def test_handle_action_does_not_navigate_back_when_page_url_unchanged() ->
with open(dummy_file, "w") as f:
f.write("dummy")
- list_files_side_effect = [[], [dummy_file]]
+ list_files_side_effect = [[], [dummy_file], [dummy_file]]
mock_app = MagicMock()
mock_app.BROWSER_MANAGER.get_for_task.return_value = browser_state
@@ -617,7 +618,7 @@ async def test_handle_action_download_no_signal_fails_fast(span_exporter: InMemo
step_id=step.step_id,
)
- async def mock_inner_handle_action(*args, **kwargs) -> list[ActionSuccess]:
+ async def mock_inner_handle_action(*args: object, **kwargs: object) -> list[ActionSuccess]:
return [ActionSuccess()]
with tempfile.TemporaryDirectory() as temp_dir:
@@ -680,7 +681,7 @@ async def test_handle_action_prefers_observed_file_over_download_event_copy(
page = MagicMock()
page.url = "https://example.com/download"
page.context.browser = None
- download_callbacks: dict[str, object] = {}
+ download_callbacks: dict[str, Callable[[object], None]] = {}
page.on.side_effect = lambda event, callback: download_callbacks.__setitem__(event, callback)
browser_state = MagicMock()
@@ -711,7 +712,7 @@ async def test_handle_action_prefers_observed_file_over_download_event_copy(
primary_dir = os.path.join(temp_root, "pbs-1")
os.makedirs(primary_dir)
- async def mock_inner_handle_action(*args, **kwargs) -> list[ActionSuccess]:
+ async def mock_inner_handle_action(*args: object, **kwargs: object) -> list[ActionSuccess]:
download_callbacks["download"](download)
with open(os.path.join(primary_dir, "report.pdf"), "w") as f:
f.write("dummy")
@@ -777,7 +778,7 @@ async def test_handle_action_copies_download_event_when_no_observed_file_appears
page = MagicMock()
page.url = "https://example.com/download"
page.context.browser = None
- download_callbacks: dict[str, object] = {}
+ download_callbacks: dict[str, Callable[[object], None]] = {}
page.on.side_effect = lambda event, callback: download_callbacks.__setitem__(event, callback)
browser_state = MagicMock()
@@ -809,7 +810,7 @@ async def test_handle_action_copies_download_event_when_no_observed_file_appears
download.save_as = AsyncMock(side_effect=save_download)
- async def mock_inner_handle_action(*args, **kwargs) -> list[ActionSuccess]:
+ async def mock_inner_handle_action(*args: object, **kwargs: object) -> list[ActionSuccess]:
download_callbacks["download"](download)
return [ActionSuccess()]
@@ -881,7 +882,7 @@ async def test_handle_action_ignores_empty_download_event_fallback_file(
page = MagicMock()
page.url = "https://example.com/download"
page.context.browser = None
- download_callbacks: dict[str, object] = {}
+ download_callbacks: dict[str, Callable[[object], None]] = {}
page.on.side_effect = lambda event, callback: download_callbacks.__setitem__(event, callback)
browser_state = MagicMock()
@@ -912,7 +913,7 @@ async def test_handle_action_ignores_empty_download_event_fallback_file(
download.save_as = AsyncMock(side_effect=save_empty_download)
- async def mock_inner_handle_action(*args, **kwargs) -> list[ActionSuccess]:
+ async def mock_inner_handle_action(*args: object, **kwargs: object) -> list[ActionSuccess]:
download_callbacks["download"](download)
return [ActionSuccess()]
@@ -983,7 +984,7 @@ async def test_handle_action_stops_after_download_event_fallback_failure(
page = MagicMock()
page.url = "https://example.com/download"
page.context.browser = None
- download_callbacks: dict[str, object] = {}
+ download_callbacks: dict[str, Callable[[object], None]] = {}
page.on.side_effect = lambda event, callback: download_callbacks.__setitem__(event, callback)
browser_state = MagicMock()
@@ -1010,7 +1011,7 @@ async def test_handle_action_stops_after_download_event_fallback_failure(
download.suggested_filename = "report.pdf"
download.save_as = AsyncMock(side_effect=RuntimeError("copy failed"))
- async def mock_inner_handle_action(*args, **kwargs) -> list[ActionSuccess]:
+ async def mock_inner_handle_action(*args: object, **kwargs: object) -> list[ActionSuccess]:
download_callbacks["download"](download)
return [ActionSuccess()]
@@ -1062,6 +1063,99 @@ async def test_handle_action_stops_after_download_event_fallback_failure(
assert span_attrs["download_event_fallback_failed"] is True
+async def test_handle_action_removes_late_zero_byte_duplicate_after_download_wait() -> None:
+ """A 0-byte duplicate that appears after the first download signal should be removed.
+
+ The polling loop exits as soon as one new file appears. Browser-native
+ downloads can still surface a second empty duplicate artifact while waiting
+ for ``.crdownload`` files to settle; that junk file must not be left for
+ task cleanup to upload.
+ """
+ now = datetime.now(UTC)
+ organization = make_organization(now)
+ task = make_task(
+ now,
+ organization,
+ workflow_run_id="wr-1",
+ browser_session_id=None,
+ )
+ step = make_step(now, task, step_id="step-1", status=StepStatus.created, order=0, output=None)
+
+ page = MagicMock()
+ page.url = "https://example.com/download"
+ page.context.browser = None
+
+ browser_state = MagicMock()
+ browser_state.list_valid_pages = AsyncMock(return_value=[page])
+
+ scraped_page = ScrapedPage(
+ elements=[],
+ element_tree=[],
+ element_tree_trimmed=[],
+ _browser_state=browser_state,
+ _clean_up_func=AsyncMock(return_value=[]),
+ _scrape_exclude=None,
+ )
+
+ action = ClickAction(
+ element_id="download-link",
+ download=True,
+ organization_id=task.organization_id,
+ task_id=task.task_id,
+ step_id=step.step_id,
+ )
+
+ with tempfile.TemporaryDirectory() as temp_root:
+ primary_dir = os.path.join(temp_root, "pbs-1")
+ os.makedirs(primary_dir)
+ good_file = os.path.join(primary_dir, "report.pdf")
+ empty_file = os.path.join(primary_dir, "report_1.pdf")
+
+ async def mock_inner_handle_action(*args: object, **kwargs: object) -> list[ActionSuccess]:
+ with open(good_file, "wb") as f:
+ f.write(b"valid report")
+ return [ActionSuccess()]
+
+ async def wait_then_create_empty_file(*args: object, **kwargs: object) -> None:
+ with open(empty_file, "wb"):
+ pass
+
+ mock_app = MagicMock()
+ mock_app.BROWSER_MANAGER.get_for_task.return_value = browser_state
+ mock_app.DATABASE.workflow_params.create_action = AsyncMock(return_value=action)
+ mock_app.STORAGE = MagicMock()
+
+ with (
+ patch.object(ActionHandler, "_handle_action", side_effect=mock_inner_handle_action),
+ patch("skyvern.webeye.actions.handler.get_download_dir", return_value=primary_dir),
+ patch(
+ "skyvern.webeye.actions.handler.skyvern_context.current",
+ return_value=MagicMock(run_id="pbs-1"),
+ ),
+ patch(
+ "skyvern.webeye.actions.handler.check_downloading_files_and_wait_for_download_to_complete",
+ new=AsyncMock(side_effect=wait_then_create_empty_file),
+ ),
+ patch("skyvern.webeye.actions.handler.app", mock_app),
+ ):
+ results = await ActionHandler.handle_action(
+ scraped_page=scraped_page,
+ task=task,
+ step=step,
+ page=page,
+ action=action,
+ )
+
+ remaining_files = sorted(os.listdir(primary_dir))
+
+ assert results[-1].download_triggered is True
+ assert results[-1].downloaded_files == ["report.pdf"]
+ assert action.downloaded_files == ["report.pdf"]
+ assert remaining_files == ["report.pdf"]
+ page.off.assert_called_once()
+
+
@pytest.mark.asyncio
async def test_handle_action_removes_download_listener_when_inner_action_raises() -> None:
now = datetime.now(UTC)
@@ -1076,7 +1170,7 @@ async def test_handle_action_removes_download_listener_when_inner_action_raises(
page = MagicMock()
page.url = "https://example.com/download"
- download_callbacks: dict[str, object] = {}
+ download_callbacks: dict[str, Callable[[object], None]] = {}
page.on.side_effect = lambda event, callback: download_callbacks.__setitem__(event, callback)
browser_state = MagicMock()