Skip to content

Automate browser based workflows with AI

Add paused to the public RunStatus enum (SKY-12549) (#7576)

Aaron Pereza77cdac72f96
diff --git a/docs/api-reference/openapi.json b/docs/api-reference/openapi.json
index 00dc9b009..ab9d57f10 100644
--- a/docs/api-reference/openapi.json
+++ b/docs/api-reference/openapi.json
@@ -19735,6 +19735,7 @@
"created",
"queued",
"running",
+ "paused",
"timed_out",
"failed",
"terminated",
diff --git a/fern/openapi/skyvern_openapi.json b/fern/openapi/skyvern_openapi.json
index d8d540495..515c267f6 100644
--- a/fern/openapi/skyvern_openapi.json
+++ b/fern/openapi/skyvern_openapi.json
@@ -19625,6 +19625,7 @@
"created",
"queued",
"running",
+ "paused",
"timed_out",
"failed",
"terminated",
diff --git a/skyvern/client/types/run_status.py b/skyvern/client/types/run_status.py
index 13b9f8b9f..a306a4052 100644
--- a/skyvern/client/types/run_status.py
+++ b/skyvern/client/types/run_status.py
@@ -3,6 +3,6 @@
import typing
RunStatus = typing.Union[
- typing.Literal["created", "queued", "running", "timed_out", "failed", "terminated", "completed", "canceled"],
+ typing.Literal["created", "queued", "running", "paused", "timed_out", "failed", "terminated", "completed", "canceled"],
typing.Any,
]
diff --git a/skyvern/constants.py b/skyvern/constants.py
index f554eb568..b6df92a0a 100644
--- a/skyvern/constants.py
+++ b/skyvern/constants.py
@@ -44,6 +44,10 @@ MAX_UPLOAD_FILE_COUNT = 50
AZURE_BLOB_STORAGE_MAX_UPLOAD_FILE_COUNT = 50
CUSTOMER_STORAGE_UPLOAD_MAX_BYTES = 1 * 1024 * 1024 * 1024 # 1 GB per file (FileUploadBlock)
DEFAULT_MAX_SCREENSHOT_SCROLLS = 3
+# Sanity ceiling for a user-supplied scroll count. Bounds the value well below the
+# INTEGER column limit (a larger value overflowed workflow_runs on insert) while
+# staying far above any real screenshot need.
+MAX_SCREENSHOT_SCROLLS = 1000
# Default navigation_goal for LoginBlocks. Instructs the LLM how to find the login
# page, fill credentials, and handle multi-step flows / 2FA.
diff --git a/skyvern/forge/sdk/schemas/task_v2.py b/skyvern/forge/sdk/schemas/task_v2.py
index 8e8904ded..fc1f844ef 100644
--- a/skyvern/forge/sdk/schemas/task_v2.py
+++ b/skyvern/forge/sdk/schemas/task_v2.py
@@ -7,6 +7,7 @@ from pydantic import BaseModel, ConfigDict, Field, field_serializer, field_valid
from skyvern.forge.sdk.api.llm.custom_llm_registry import is_custom_llm_model_name
from skyvern.forge.sdk.settings_manager import SettingsManager
+from skyvern.forge.sdk.workflow.models.run_limits import MaxScreenshotScrolls
from skyvern.schemas.runs import GeoTarget, ProxyLocation, ProxyLocationInput
from skyvern.utils.secret_headers import mask_header_values
from skyvern.utils.url_validators import validate_url
@@ -220,7 +221,7 @@ class TaskV2Request(BaseModel):
error_code_mapping: dict[str, str] | None = None
workflow_system_prompt: str | None = None
model: dict[str, Any] | None = None
- max_screenshot_scrolls: int | None = None
+ max_screenshot_scrolls: MaxScreenshotScrolls = Field(default=None)
extra_http_headers: dict[str, str] | None = None
cdp_connect_headers: dict[str, str] | None = None
browser_address: str | None = None
diff --git a/skyvern/forge/sdk/schemas/tasks.py b/skyvern/forge/sdk/schemas/tasks.py
index cacaa8f91..22f226d70 100644
--- a/skyvern/forge/sdk/schemas/tasks.py
+++ b/skyvern/forge/sdk/schemas/tasks.py
@@ -18,6 +18,7 @@ from skyvern.forge.sdk.api.llm.custom_llm_registry import is_custom_llm_model_na
from skyvern.forge.sdk.db.enums import TaskType
from skyvern.forge.sdk.schemas.files import FileInfo
from skyvern.forge.sdk.settings_manager import SettingsManager
+from skyvern.forge.sdk.workflow.models.run_limits import MaxScreenshotScrolls
from skyvern.schemas.docs.doc_strings import PROXY_LOCATION_DOC_STRING
from skyvern.schemas.runs import ProxyLocationInput
from skyvern.utils.prompt_truncation import EXTRACTION_GOAL_MAX_TOKENS
@@ -120,7 +121,7 @@ class TaskBase(BaseModel):
description="Whether to include the action history when verifying the task is complete",
examples=[True, False],
)
- max_screenshot_scrolls: int | None = Field(
+ max_screenshot_scrolls: MaxScreenshotScrolls = Field(
default=None,
description="The maximum number of scrolls for the post action screenshot. When it's None or 0, it takes the current viewpoint screenshot.",
examples=[10],
diff --git a/skyvern/forge/sdk/workflow/models/run_limits.py b/skyvern/forge/sdk/workflow/models/run_limits.py
index e0b359937..640434110 100644
--- a/skyvern/forge/sdk/workflow/models/run_limits.py
+++ b/skyvern/forge/sdk/workflow/models/run_limits.py
@@ -1,7 +1,31 @@
+from typing import Annotated
+
+from pydantic import AfterValidator
+
+from skyvern.constants import MAX_SCREENSHOT_SCROLLS
+
WORKFLOW_RUN_DEFAULT_MAX_ELAPSED_TIME_MINUTES = 4 * 60
WORKFLOW_RUN_MAX_ELAPSED_TIME_MINUTES = 8 * 60
+def clamp_max_screenshot_scrolls(value: int | None) -> int | None:
+ """Clamp a scroll count into ``[0, MAX_SCREENSHOT_SCROLLS]``.
+
+ An *after*-validator so it runs once Pydantic has coerced the input to ``int``
+ — clamping a stringified number (e.g. ``"2147483648"``) as well as a raw int.
+ It normalizes both incoming requests (a value above the INTEGER column limit
+ would overflow ``max_screenshot_scrolling_times`` on insert) and rows hydrated
+ from the DB — a pre-cap historical value must not fail validation on
+ read/response reconstruction.
+ """
+ if value is None:
+ return None
+ return max(0, min(value, MAX_SCREENSHOT_SCROLLS))
+
+
+MaxScreenshotScrolls = Annotated[int | None, AfterValidator(clamp_max_screenshot_scrolls)]
+
+
def reject_bool_max_elapsed_time_minutes(max_elapsed_time_minutes: object) -> object:
if isinstance(max_elapsed_time_minutes, bool):
raise ValueError("max_elapsed_time_minutes must be an integer, not a boolean")
diff --git a/skyvern/forge/sdk/workflow/models/workflow.py b/skyvern/forge/sdk/workflow/models/workflow.py
index eda399209..20d5be24b 100644
--- a/skyvern/forge/sdk/workflow/models/workflow.py
+++ b/skyvern/forge/sdk/workflow/models/workflow.py
@@ -17,6 +17,7 @@ from skyvern.forge.sdk.workflow.models.block import BlockTypeVar, ForLoopBlock,
from skyvern.forge.sdk.workflow.models.parameter import PARAMETER_TYPE, OutputParameter
from skyvern.forge.sdk.workflow.models.run_limits import (
WORKFLOW_RUN_MAX_ELAPSED_TIME_MINUTES,
+ MaxScreenshotScrolls,
reject_bool_max_elapsed_time_minutes,
)
from skyvern.forge.sdk.workflow.models.validators import normalize_run_metadata, normalize_run_with
@@ -35,7 +36,7 @@ class WorkflowRequestBody(BaseModel):
totp_identifier: str | None = None
browser_session_id: str | None = None
browser_profile_id: str | None = None
- max_screenshot_scrolls: int | None = None
+ max_screenshot_scrolls: MaxScreenshotScrolls = Field(default=None)
max_elapsed_time_minutes: int | None = Field(default=None, ge=1, le=WORKFLOW_RUN_MAX_ELAPSED_TIME_MINUTES)
extra_http_headers: dict[str, str] | None = None
cdp_connect_headers: dict[str, str] | None = None
diff --git a/skyvern/schemas/run_blocks.py b/skyvern/schemas/run_blocks.py
index b7359850e..b27f510db 100644
--- a/skyvern/schemas/run_blocks.py
+++ b/skyvern/schemas/run_blocks.py
@@ -1,5 +1,6 @@
from pydantic import BaseModel, Field
+from skyvern.forge.sdk.workflow.models.run_limits import MaxScreenshotScrolls
from skyvern.schemas.credential_type import CredentialType
from skyvern.schemas.proxy_location import ProxyLocation
@@ -38,7 +39,7 @@ class BaseRunBlockRequest(BaseModel):
"to a remote browser via browser_address. Never forwarded to target websites."
),
)
- max_screenshot_scrolling_times: int | None = Field(
+ max_screenshot_scrolling_times: MaxScreenshotScrolls = Field(
default=None, description="Maximum number of times to scroll for screenshots"
)
diff --git a/skyvern/schemas/run_enums.py b/skyvern/schemas/run_enums.py
index 8fde66a18..af3156197 100644
--- a/skyvern/schemas/run_enums.py
+++ b/skyvern/schemas/run_enums.py
@@ -32,6 +32,7 @@ class RunStatus(StrEnum):
created = "created"
queued = "queued"
running = "running"
+ paused = "paused"
timed_out = "timed_out"
failed = "failed"
terminated = "terminated"
diff --git a/skyvern/schemas/runs.py b/skyvern/schemas/runs.py
index 04b16bed8..9303cbca4 100644
--- a/skyvern/schemas/runs.py
+++ b/skyvern/schemas/runs.py
@@ -18,6 +18,7 @@ from skyvern.forge.sdk.schemas.files import FileInfo
from skyvern.forge.sdk.workflow.models.run_limits import (
WORKFLOW_RUN_DEFAULT_MAX_ELAPSED_TIME_MINUTES,
WORKFLOW_RUN_MAX_ELAPSED_TIME_MINUTES,
+ MaxScreenshotScrolls,
reject_bool_max_elapsed_time_minutes,
)
from skyvern.forge.sdk.workflow.models.validators import normalize_run_metadata, normalize_run_with
@@ -169,7 +170,7 @@ class TaskRunRequest(BaseModel):
include_action_history_in_verification: bool | None = Field(
default=False, description="Whether to include action history when verifying that the task is complete"
)
- max_screenshot_scrolls: int | None = Field(
+ max_screenshot_scrolls: MaxScreenshotScrolls = Field(
default=None,
description="The maximum number of scrolls for the post action screenshot. When it's None or 0, it takes the current viewpoint screenshot.",
)
@@ -267,7 +268,7 @@ class WorkflowRunRequest(BaseModel):
default=None,
description="ID of a browser profile to reuse for this workflow run",
)
- max_screenshot_scrolls: int | None = Field(
+ max_screenshot_scrolls: MaxScreenshotScrolls = Field(
default=None,
description="The maximum number of scrolls for the post action screenshot. When it's None or 0, it takes the current viewpoint screenshot.",
)
@@ -405,7 +406,17 @@ class BaseRunResponse(BaseModel):
)
status: RunStatus = Field(
description="Current status of the run",
- examples=["created", "queued", "running", "timed_out", "failed", "terminated", "completed", "canceled"],
+ examples=[
+ "created",
+ "queued",
+ "running",
+ "paused",
+ "timed_out",
+ "failed",
+ "terminated",
+ "completed",
+ "canceled",
+ ],
)
output: dict | list | str | None = Field(
default=None,
diff --git a/skyvern/schemas/workflows.py b/skyvern/schemas/workflows.py
index f5ddf6fa4..d8b2f2202 100644
--- a/skyvern/schemas/workflows.py
+++ b/skyvern/schemas/workflows.py
@@ -14,6 +14,7 @@ from skyvern.forge.sdk.workflow.browser_profile_key import validate_browser_prof
from skyvern.forge.sdk.workflow.models.parameter import OutputParameter, ParameterType, WorkflowParameterType
from skyvern.forge.sdk.workflow.models.run_limits import (
WORKFLOW_RUN_MAX_ELAPSED_TIME_MINUTES,
+ MaxScreenshotScrolls,
reject_bool_max_elapsed_time_minutes,
)
from skyvern.forge.sdk.workflow.models.validators import normalize_run_with
@@ -1435,7 +1436,7 @@ class WorkflowCreateYAMLRequest(BaseModel):
model: dict[str, Any] | None = None
workflow_definition: WorkflowDefinitionYAML
is_saved_task: bool = False
- max_screenshot_scrolls: int | None = None
+ max_screenshot_scrolls: MaxScreenshotScrolls = Field(default=None)
max_elapsed_time_minutes: int | None = Field(default=None, ge=1, le=WORKFLOW_RUN_MAX_ELAPSED_TIME_MINUTES)
extra_http_headers: dict[str, str] | None = None
cdp_connect_headers: dict[str, str] | None = None
diff --git a/tests/unit/test_run_request_screenshot_scroll_bounds.py b/tests/unit/test_run_request_screenshot_scroll_bounds.py
new file mode 100644
index 000000000..1809b4f60
--- /dev/null
+++ b/tests/unit/test_run_request_screenshot_scroll_bounds.py
@@ -0,0 +1,93 @@
+"""max_screenshot_scrolls is clamped (not rejected) into [0, MAX_SCREENSHOT_SCROLLS].
+
+An unbounded value larger than the INTEGER column limit overflowed
+max_screenshot_scrolling_times on insert (psycopg NumericValueOutOfRange). A
+before-validator clamps the value, which fixes the write overflow while staying
+safe on the read path: the same field is populated when hydrating persisted rows
+(Task from convert_to_task, the workflow-run response's run_request), so a
+pre-cap historical value must clamp rather than raise.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+import pytest
+from pydantic import BaseModel
+
+from skyvern.constants import MAX_SCREENSHOT_SCROLLS
+from skyvern.forge.sdk.schemas.task_v2 import TaskV2Request
+from skyvern.forge.sdk.schemas.tasks import Task, TaskRequest
+from skyvern.forge.sdk.workflow.models.workflow import WorkflowRequestBody
+from skyvern.schemas.run_blocks import BaseRunBlockRequest
+from skyvern.schemas.runs import TaskRunRequest, WorkflowRunRequest
+from skyvern.schemas.workflows import WorkflowCreateYAMLRequest
+
+_PG_INT_OVERFLOW = 2**31
+
+# (model, field, required-kwargs) for every request/persistence model carrying the field.
+_CASES = [
+ (TaskRunRequest, "max_screenshot_scrolls", {"prompt": "x"}),
+ (WorkflowRunRequest, "max_screenshot_scrolls", {"workflow_id": "wpid_1"}),
+ (
+ WorkflowCreateYAMLRequest,
+ "max_screenshot_scrolls",
+ {"title": "t", "workflow_definition": {"parameters": [], "blocks": []}},
+ ),
+ (BaseRunBlockRequest, "max_screenshot_scrolling_times", {}),
+ (WorkflowRequestBody, "max_screenshot_scrolls", {}),
+ (TaskRequest, "max_screenshot_scrolls", {"url": "https://example.com"}),
+ (TaskV2Request, "max_screenshot_scrolls", {"user_prompt": "x"}),
+]
+
+
[email protected](("model", "field", "required"), _CASES)
+def test_overflowing_scroll_count_is_clamped_not_rejected(model: type[BaseModel], field: str, required: dict) -> None:
+ instance = model(**required, **{field: _PG_INT_OVERFLOW})
+ assert getattr(instance, field) == MAX_SCREENSHOT_SCROLLS
+
+
[email protected](("model", "field", "required"), _CASES)
+def test_stringified_overflow_is_clamped_after_coercion(model: type[BaseModel], field: str, required: dict) -> None:
+ # A quoted number is coerced to int by pydantic; the clamp must run after
+ # coercion, or a stringified overflow slips past and re-overflows on insert.
+ instance = model(**required, **{field: str(_PG_INT_OVERFLOW)})
+ assert getattr(instance, field) == MAX_SCREENSHOT_SCROLLS
+
+
[email protected](("model", "field", "required"), _CASES)
+def test_negative_scroll_count_is_clamped_to_zero(model: type[BaseModel], field: str, required: dict) -> None:
+ assert getattr(model(**required, **{field: -1}), field) == 0
+
+
[email protected](("model", "field", "required"), _CASES)
+def test_in_range_and_none_scroll_counts_preserved(model: type[BaseModel], field: str, required: dict) -> None:
+ assert getattr(model(**required, **{field: 5}), field) == 5
+ assert getattr(model(**required, **{field: MAX_SCREENSHOT_SCROLLS}), field) == MAX_SCREENSHOT_SCROLLS
+ assert getattr(model(**required), field) is None
+
+
+def test_hydrating_historical_over_cap_task_row_does_not_raise() -> None:
+ """A persisted Task row with a pre-cap scroll count must clamp on read, not 500.
+
+ Task inherits TaskBase and is built from the DB by convert_to_task; rejecting
+ here would break task detail/list for historical rows.
+ """
+ now = datetime.now(timezone.utc)
+ task = Task(
+ task_id="tsk_1",
+ organization_id="o_1",
+ status="completed",
+ created_at=now,
+ modified_at=now,
+ url="https://example.com",
+ max_screenshot_scrolls=50_000,
+ )
+ assert task.max_screenshot_scrolls == MAX_SCREENSHOT_SCROLLS
+
+
+def test_reconstructing_workflow_run_request_over_cap_does_not_raise() -> None:
+ """The workflow-run response builder reconstructs WorkflowRunRequest from the
+ stored run; a historical over-cap value must clamp rather than raise."""
+ reconstructed = WorkflowRunRequest(workflow_id="wpid_1", max_screenshot_scrolls=50_000)
+ assert reconstructed.max_screenshot_scrolls == MAX_SCREENSHOT_SCROLLS
diff --git a/tests/unit/test_run_response_types.py b/tests/unit/test_run_response_types.py
index 69c1a13bf..44de05b60 100644
--- a/tests/unit/test_run_response_types.py
+++ b/tests/unit/test_run_response_types.py
@@ -2,9 +2,23 @@ from datetime import UTC, datetime
from pydantic import TypeAdapter
+from skyvern.forge.sdk.workflow.models.workflow import WorkflowRunStatus
from skyvern.schemas.runs import RunResponse, RunStatus, RunType, TaskRunResponse, WorkflowRunResponse
+def test_every_workflow_run_status_maps_to_run_status() -> None:
+ # A workflow run's status is projected onto the public RunStatus via
+ # RunStatus(workflow_run.status); a WorkflowRunStatus value with no RunStatus
+ # member raises ValueError on that projection (paused did, in production).
+ for status in WorkflowRunStatus:
+ assert RunStatus(status.value).value == status.value
+
+
+def test_paused_run_status_is_non_final() -> None:
+ assert RunStatus("paused") is RunStatus.paused
+ assert RunStatus.paused.is_final() is False
+
+
def test_task_run_response_preserves_run_type_enum() -> None:
response = TaskRunResponse.model_validate(
{