Skip to content

Automate browser based workflows with AI

Add a pure, fail-closed policy core for browser actions (#7753)

Aaron Perez1dfc4c9925a8
diff --git a/skyvern/config.py b/skyvern/config.py
index 18361589d..bfad34221 100644
--- a/skyvern/config.py
+++ b/skyvern/config.py
@@ -2,7 +2,7 @@ import logging
import os
import platform
from pathlib import Path
-from typing import Any
+from typing import Any, Literal
from pydantic import AliasChoices, Field
from pydantic_settings import BaseSettings, SettingsConfigDict
@@ -109,6 +109,9 @@ class Settings(BaseSettings):
DOWNLOAD_PATH: str = f"{REPO_ROOT_DIR}/downloads"
BROWSER_ACTION_TIMEOUT_MS: int = 5000
BROWSER_ACTION_MAX_EXECUTION_SECONDS: int = 1200
+ # "enforce" is deliberately absent: the policy core can only observe until every sink consumes
+ # an exact approval, so an enforcing value must be unrepresentable rather than merely unused.
+ BROWSER_ACTION_POLICY_MODE: Literal["disabled", "observe"] = "disabled"
POPUP_VIDEO_PATH_TIMEOUT_SECONDS: float = 3.0
CACHED_ACTION_DELAY_SECONDS: float = 1.0
# Page readiness settings for cached action execution
diff --git a/skyvern/exceptions.py b/skyvern/exceptions.py
index ed49c35b6..218200f11 100644
--- a/skyvern/exceptions.py
+++ b/skyvern/exceptions.py
@@ -1,4 +1,5 @@
import re
+from collections.abc import Sequence
from http import HTTPStatus
from importlib.util import find_spec
from typing import NoReturn
@@ -177,6 +178,21 @@ class DisabledBlockExecutionError(SkyvernHTTPException):
super().__init__(message, status_code=HTTPStatus.BAD_REQUEST)
+class BrowserActionPolicyNotEnforceable(SkyvernHTTPException):
+ """A workflow version was enrolled in a browser action policy the runtime cannot uphold.
+
+ `reasons` are stable codes describing the configuration only — never workflow content, origins
+ or identifiers — because they are rendered to callers and stamped on failed runs.
+ """
+
+ def __init__(self, reasons: Sequence[str]):
+ self.reasons = tuple(reasons)
+ super().__init__(
+ f"Workflow cannot run under a browser action policy: {', '.join(self.reasons)}",
+ status_code=HTTPStatus.BAD_REQUEST,
+ )
+
+
class RateLimitExceeded(SkyvernHTTPException):
def __init__(self, organization_id: str, max_requests: int, window_seconds: int):
message = (
diff --git a/skyvern/forge/agent.py b/skyvern/forge/agent.py
index acea10149..1cd992407 100644
--- a/skyvern/forge/agent.py
+++ b/skyvern/forge/agent.py
@@ -97,6 +97,12 @@ from skyvern.forge.sdk.api.llm.yutori_navigator_response import parse_navigator_
from skyvern.forge.sdk.api.real_gcp import get_gcs_client
from skyvern.forge.sdk.artifact.manager import BulkArtifactCreationRequest
from skyvern.forge.sdk.artifact.models import ArtifactType
+from skyvern.forge.sdk.browser_action_preflight import (
+ observed_page,
+ preflight_action,
+ preflight_batch,
+ stamp_parsed_actions,
+)
from skyvern.forge.sdk.cache import extraction_cache, extraction_shadow
from skyvern.forge.sdk.copilot.block_goal_wrapping import unwrap_goal_fields
from skyvern.forge.sdk.core import skyvern_context
@@ -1778,6 +1784,10 @@ class ForgeAgent:
actions=actions,
)
+ # The complete batch is evaluated here — after WAIT filtering, and before any of it is
+ # persisted, reported through a callback, slept on or executed.
+ preflight_batch(actions, site="step_action_batch")
+
# initialize list of tuples and set actions as the first element of each tuple so that in the case
# of an exception, we can still see all the actions
detailed_agent_step_output.actions_and_results = [(action, []) for action in actions]
@@ -1829,6 +1839,10 @@ class ForgeAgent:
step_order=step.order,
action_order=action_idx,
)
+ # The reload it follows happened after the last scrape, so it carries no
+ # observation of the page it is about to act on. Unstamped by construction: only
+ # _generate_step_actions stamps, and this action never went through it.
+ preflight_action(action, observed_page(), site="internal_refresh")
detailed_agent_step_output.actions_and_results[action_idx] = (action, [action_result])
action.action_id = (await app.DATABASE.workflow_params.create_action(action=action)).action_id
artifact_tracker.task = asyncio.create_task(
@@ -2201,6 +2215,10 @@ class ForgeAgent:
pdf_auto_download_src: str | None = None
pdf_auto_download_used_bytes = False
actions: list[Action]
+ # Provenance is opt-in per branch, so a branch added later is unstamped until someone
+ # decides it was derived from the scrape. A blanket stamp at the end of this method had the
+ # opposite default and silently gave runtime-synthesized actions provenance they never had.
+ derived_from_scrape = False
# If prepare_step_execution injected actions (e.g. proactive captcha solving),
# skip LLM entirely and use the injected actions directly.
if injected_actions is not None:
@@ -2212,6 +2230,7 @@ class ForgeAgent:
)
actions = injected_actions
elif engine == RunEngine.openai_cua:
+ derived_from_scrape = True
actions, new_cua_response = await self._generate_cua_actions(
task=task,
step=step,
@@ -2222,6 +2241,7 @@ class ForgeAgent:
detailed_agent_step_output.cua_response = new_cua_response
elif engine == RunEngine.anthropic_cua:
assert llm_caller is not None
+ derived_from_scrape = True
actions = await self._generate_anthropic_actions(
task=task,
step=step,
@@ -2234,6 +2254,7 @@ class ForgeAgent:
properties={"organization_id": task.organization_id},
):
assert llm_caller is not None
+ derived_from_scrape = True
actions = await self._generate_ui_tars_actions(
task=task,
step=step,
@@ -2242,6 +2263,7 @@ class ForgeAgent:
)
elif engine == RunEngine.yutori_navigator:
assert llm_caller is not None
+ derived_from_scrape = True
actions = await self._generate_yutori_navigator_actions(
task=task,
step=step,
@@ -2251,6 +2273,7 @@ class ForgeAgent:
else:
if is_extraction_task:
+ derived_from_scrape = True
actions = [
await self.create_extract_action(
task,
@@ -2343,6 +2366,8 @@ class ForgeAgent:
)
download_url = pdf_src
+ # The PDF src came out of the scraped element tree.
+ derived_from_scrape = True
actions = [
DownloadFileAction(
reasoning="Downloading the file from the PDF viewer.",
@@ -2368,6 +2393,7 @@ class ForgeAgent:
detailed_agent_step_output.llm_response = otp_json_response
actions = otp_actions
else:
+ derived_from_scrape = True
actions = parse_actions(
task, step.step_id, step.order, scraped_page, _require_actions_payload(json_response)
)
@@ -2424,6 +2450,11 @@ class ForgeAgent:
screenshots=scraped_page.screenshots,
)
speculative_llm_metadata = None
+ if derived_from_scrape:
+ # Only actions the scrape produced may carry its provenance. Everything else here —
+ # actions injected before the scrape ran, a magic-link navigation aimed at a page nobody
+ # scraped, a TOTP timeout terminate — stays unstamped and is judged on that.
+ stamp_parsed_actions(actions)
return actions, pdf_auto_download_src, pdf_auto_download_used_bytes
async def _generate_cua_actions(
@@ -6412,6 +6443,10 @@ class ForgeAgent:
actions = parse_actions(
task, step.step_id, step.order, scraped_page, _require_actions_payload(json_response)
)
+ # Parsed from the current scrape, so stamped here rather than by the caller: this return
+ # shares its shape with the magic-link one below, which is runtime-derived and must stay
+ # unstamped. Distinguishing them at the caller would mean guessing which branch ran.
+ stamp_parsed_actions(actions)
return json_response, actions
if should_verify_by_magic_link:
diff --git a/skyvern/forge/sdk/browser_action_policy.py b/skyvern/forge/sdk/browser_action_policy.py
new file mode 100644
index 000000000..077ffef56
--- /dev/null
+++ b/skyvern/forge/sdk/browser_action_policy.py
@@ -0,0 +1,580 @@
+"""Pure decision core for the browser action firewall (SKY-12872).
+
+Deterministic, side-effect free policy evaluation: callers hand in already-extracted facts and get
+back an immutable decision. The module performs no I/O, no async work, no ambient-state lookup and
+no classification of its own — a probabilistic verdict is evidence, never authority.
+"""
+
+from __future__ import annotations
+
+import ipaddress
+import re
+from collections.abc import Iterable
+from dataclasses import dataclass
+from enum import StrEnum
+from urllib.parse import urlsplit
+
+from skyvern.webeye.actions.action_types import ActionType
+from skyvern.webeye.actions.actions import (
+ Action,
+ CheckboxAction,
+ ClickAction,
+ ClosePageAction,
+ CompleteAction,
+ DownloadFileAction,
+ DragAction,
+ ExecuteJsAction,
+ ExtractAction,
+ GoBackAction,
+ GoForwardAction,
+ GotoUrlAction,
+ HoverAction,
+ InputTextAction,
+ KeypressAction,
+ LeftMouseAction,
+ MoveAction,
+ NewTabAction,
+ NullAction,
+ ReloadPageAction,
+ ScrollAction,
+ SelectOptionAction,
+ SolveCaptchaAction,
+ SwitchTabAction,
+ TerminateAction,
+ UploadFileAction,
+ VerificationCodeAction,
+ WaitAction,
+)
+
+
+class ObservationVerdict(StrEnum):
+ """Detector evidence about the observed page.
+
+ Member values are pinned to the cloud detector's DetectionOutcome, which the OSS boundary
+ forbids importing here. Cloud passes its member straight in: StrEnum compares equal to its
+ value, so the two vocabularies stay interchangeable without a dependency.
+ """
+
+ NO_MATCH = "no_match"
+ SUSPICIOUS = "suspicious"
+ UNKNOWN = "unknown"
+
+
+class AuthorityState(StrEnum):
+ """Availability of the run's ADR-0011 task-URL-derived origin authority.
+
+ Separate from enrollment on purpose. Enrollment answers "is this run protected, and what did an
+ operator authorize at most"; this answers "what may this run reach right now". Only ESTABLISHED
+ grants anything, and the origins it grants are still intersected with the enrolled ceiling.
+ """
+
+ ESTABLISHED = "established"
+ #: Never established, or lost before a browser context was bound. ADR-0011 blocks until it is.
+ MISSING = "missing"
+ #: Rotated or conflicted after a browser context was bound. ADR-0011 makes this permanent,
+ #: because existing connections cannot be proven closed.
+ INVALIDATED = "invalidated"
+ #: No runtime authority source is wired into this build at all — see UNWIRED_AUTHORITY.
+ UNWIRED = "unwired"
+
+
+class ActionClass(StrEnum):
+ BENIGN = "benign"
+ READ = "read"
+ TERMINAL = "terminal"
+ MUTATING = "mutating"
+ NAVIGATION = "navigation"
+ EGRESS = "egress"
+ UNRESOLVABLE = "unresolvable"
+ UNSUPPORTED = "unsupported"
+
+
+class ProtectedReferenceKind(StrEnum):
+ SECRET = "secret"
+ VERIFICATION_CODE = "verification_code"
+ FILE = "file"
+
+
+class PolicyOutcome(StrEnum):
+ NOT_ENROLLED = "not_enrolled"
+ ALLOWED = "allowed"
+ DENIED = "denied"
+ UNSUPPORTED = "unsupported"
+
+
+class PolicyReason(StrEnum):
+ UNSUPPORTED_ACTION = "unsupported_action"
+ UNKNOWN_ACTION = "unknown_action"
+ ACTION_MODEL_MISMATCH = "action_model_mismatch"
+ UNRESOLVABLE_TARGET = "unresolvable_target"
+ MISSING_PAGE_EVIDENCE = "missing_page_evidence"
+ STALE_PAGE_EVIDENCE = "stale_page_evidence"
+ MISSING_PROTECTED_REFERENCE = "missing_protected_reference"
+ INCOMPLETE_PROTECTED_REFERENCE = "incomplete_protected_reference"
+ UNOWNED_PROTECTED_REFERENCE = "unowned_protected_reference"
+ UNTRUSTED_OBSERVATION = "untrusted_observation"
+ UNVERIFIED_OBSERVATION = "unverified_observation"
+ UNWIRED_RUNTIME_AUTHORITY = "unwired_runtime_authority"
+ MISSING_RUNTIME_AUTHORITY = "missing_runtime_authority"
+ INVALIDATED_RUNTIME_AUTHORITY = "invalidated_runtime_authority"
+ MISSING_PAGE_ORIGIN = "missing_page_origin"
+ PAGE_ORIGIN_NOT_AUTHORIZED = "page_origin_not_authorized"
+ MISSING_TARGET_ORIGIN = "missing_target_origin"
+ TARGET_ORIGIN_NOT_AUTHORIZED = "target_origin_not_authorized"
+
+
+# Documented precedence, most structural first: what the action *is*, then whether the evidence
+# supporting it is usable, then whether the origins it touches were granted. Decisions report every
+# applicable reason in this order so a caller can log the full picture and act on reasons[0].
+REASON_PRECEDENCE: tuple[PolicyReason, ...] = (
+ PolicyReason.UNSUPPORTED_ACTION,
+ PolicyReason.UNKNOWN_ACTION,
+ PolicyReason.ACTION_MODEL_MISMATCH,
+ PolicyReason.UNRESOLVABLE_TARGET,
+ PolicyReason.MISSING_PAGE_EVIDENCE,
+ PolicyReason.STALE_PAGE_EVIDENCE,
+ PolicyReason.MISSING_PROTECTED_REFERENCE,
+ PolicyReason.INCOMPLETE_PROTECTED_REFERENCE,
+ PolicyReason.UNOWNED_PROTECTED_REFERENCE,
+ PolicyReason.UNTRUSTED_OBSERVATION,
+ PolicyReason.UNVERIFIED_OBSERVATION,
+ PolicyReason.UNWIRED_RUNTIME_AUTHORITY,
+ PolicyReason.MISSING_RUNTIME_AUTHORITY,
+ PolicyReason.INVALIDATED_RUNTIME_AUTHORITY,
+ PolicyReason.MISSING_PAGE_ORIGIN,
+ PolicyReason.PAGE_ORIGIN_NOT_AUTHORIZED,
+ PolicyReason.MISSING_TARGET_ORIGIN,
+ PolicyReason.TARGET_ORIGIN_NOT_AUTHORIZED,
+)
+
+_DEFAULT_PORTS = {"http": 80, "https": 443}
+_IPV4_LAST_LABEL = re.compile(r"0[xX][0-9a-fA-F]*|[0-9]+")
+_WEBSOCKET_SCHEMES = {"ws": "http", "wss": "https"}
+
+# Origin and verdict are independent axes and must not share one exemption set.
+# Recovery means letting a stranded agent navigate back from an unauthorized origin, so the recovery
+# set is exempt from the origin check. It does not mean letting it READ a hostile page: EXTRACT
+# pulls untrusted content into the agent's context, which is the exposure this control exists for,
+# so it stays subject to the detector verdict.
+_ORIGIN_UNGATED_CLASSES = frozenset({ActionClass.BENIGN, ActionClass.READ, ActionClass.TERMINAL})
+_VERDICT_UNGATED_CLASSES = frozenset({ActionClass.BENIGN, ActionClass.TERMINAL})
+
+_ACTION_CLASSES: dict[ActionType, ActionClass] = {
+ ActionType.NULL_ACTION: ActionClass.BENIGN,
+ ActionType.WAIT: ActionClass.BENIGN,
+ ActionType.HOVER: ActionClass.BENIGN,
+ ActionType.EXTRACT: ActionClass.READ,
+ ActionType.SCROLL: ActionClass.BENIGN,
+ ActionType.MOVE: ActionClass.BENIGN,
+ ActionType.GO_BACK: ActionClass.BENIGN,
+ ActionType.CLOSE_PAGE: ActionClass.BENIGN,
+ ActionType.SWITCH_TAB: ActionClass.BENIGN,
+ ActionType.TERMINATE: ActionClass.TERMINAL,
+ ActionType.COMPLETE: ActionClass.TERMINAL,
+ ActionType.CLICK: ActionClass.MUTATING,
+ ActionType.INPUT_TEXT: ActionClass.MUTATING,
+ ActionType.UPLOAD_FILE: ActionClass.MUTATING,
+ ActionType.SELECT_OPTION: ActionClass.MUTATING,
+ ActionType.CHECKBOX: ActionClass.MUTATING,
+ ActionType.KEYPRESS: ActionClass.MUTATING,
+ ActionType.SOLVE_CAPTCHA: ActionClass.MUTATING,
+ ActionType.VERIFICATION_CODE: ActionClass.MUTATING,
+ # GO_FORWARD is gated while GO_BACK is not: forward can advance to a page the agent never
+ # authorized in this epoch, whereas back only revisits history it already passed policy on.
+ ActionType.GOTO_URL: ActionClass.NAVIGATION,
+ ActionType.NEW_TAB: ActionClass.NAVIGATION,
+ ActionType.RELOAD_PAGE: ActionClass.NAVIGATION,
+ ActionType.GO_FORWARD: ActionClass.NAVIGATION,
+ ActionType.DOWNLOAD_FILE: ActionClass.EGRESS,
+ ActionType.DRAG: ActionClass.UNRESOLVABLE,
+ ActionType.LEFT_MOUSE: ActionClass.UNRESOLVABLE,
+ ActionType.EXECUTE_JS: ActionClass.UNSUPPORTED,
+}
+
+# Exact model expected for each discriminator. `action_type` is a defaulted field rather than a
+# Literal discriminator, so a mismatched pair such as ClickAction(action_type=GOTO_URL) constructs
+# cleanly; this table is what makes that detectable.
+_ACTION_MODELS: dict[ActionType, type[Action]] = {
+ ActionType.NULL_ACTION: NullAction,
+ ActionType.WAIT: WaitAction,
+ ActionType.HOVER: HoverAction,
+ ActionType.EXTRACT: ExtractAction,
+ ActionType.SCROLL: ScrollAction,
+ ActionType.MOVE: MoveAction,
+ ActionType.GO_BACK: GoBackAction,
+ ActionType.CLOSE_PAGE: ClosePageAction,
+ ActionType.SWITCH_TAB: SwitchTabAction,
+ ActionType.TERMINATE: TerminateAction,
+ ActionType.COMPLETE: CompleteAction,
+ ActionType.CLICK: ClickAction,
+ ActionType.INPUT_TEXT: InputTextAction,
+ ActionType.UPLOAD_FILE: UploadFileAction,
+ ActionType.SELECT_OPTION: SelectOptionAction,
+ ActionType.CHECKBOX: CheckboxAction,
+ ActionType.KEYPRESS: KeypressAction,
+ ActionType.SOLVE_CAPTCHA: SolveCaptchaAction,
+ ActionType.VERIFICATION_CODE: VerificationCodeAction,
+ ActionType.GOTO_URL: GotoUrlAction,
+ ActionType.NEW_TAB: NewTabAction,
+ ActionType.RELOAD_PAGE: ReloadPageAction,
+ ActionType.GO_FORWARD: GoForwardAction,
+ ActionType.DOWNLOAD_FILE: DownloadFileAction,
+ ActionType.DRAG: DragAction,
+ ActionType.LEFT_MOUSE: LeftMouseAction,
+ ActionType.EXECUTE_JS: ExecuteJsAction,
+}
+
+
+@dataclass(frozen=True, slots=True)
+class BrowserOrigin:
+ scheme: str
+ host: str
+ port: int
+
+ @property
+ def canonical(self) -> str:
+ host = f"[{self.host}]" if ":" in self.host else self.host
+ port = "" if self.port == _DEFAULT_PORTS[self.scheme] else f":{self.port}"
+ return f"{self.scheme}://{host}{port}"
+
+
+@dataclass(frozen=True, slots=True)
+class ProtectedReference:
+ """Opaque handle to a secret, code or file. The protected value never enters this module."""
+
+ kind: ProtectedReferenceKind
+ reference_id: str
+ owner_id: str
+
+ @property
+ def complete(self) -> bool:
+ return isinstance(self.kind, ProtectedReferenceKind) and bool(self.reference_id) and bool(self.owner_id)
+
+
+@dataclass(frozen=True, slots=True)
+class ActionTarget:
+ urls: tuple[str, ...] = ()
+ resolvable: bool = True
+
+
+@dataclass(frozen=True, slots=True)
+class ActionProjection:
+ action_type: ActionType | None
+ action_class: ActionClass | None
+ target: ActionTarget
+ required_references: frozenset[ProtectedReferenceKind] = frozenset()
+ defects: tuple[PolicyReason, ...] = ()
+
+
+@dataclass(frozen=True, slots=True)
+class PageObservation:
+ page_url: str
+ observation_epoch: int
+ verdict: ObservationVerdict
+
+
+@dataclass(frozen=True, slots=True)
+class BrowserActionPolicy:
+ owner_id: str
+ allowed_origins: frozenset[BrowserOrigin]
+ version: int = 1
+
+
+@dataclass(frozen=True, slots=True)
+class RuntimeOriginAuthority:
+ """What the run may reach right now, per ADR-0011's task-URL-derived exact-origin authority.
+
+ `origins` is only consulted when `state` is ESTABLISHED, and even then it is intersected with the
+ enrolled ceiling: an authority naming an origin the operator never enrolled grants nothing.
+ """
+
+ state: AuthorityState
+ origins: frozenset[BrowserOrigin] = frozenset()
+
+
+#: The authority every caller passes today, because nothing derives one yet.
+#:
+#: SKY-12883, SKY-12884 and SKY-12886 are the tickets that fill this seam. Until they land, two
+#: ADR-0011 behaviours have no implementation anywhere in this repository:
+#: * blocking until authority is established, and unblocking once it is;
+#: * permanently invalidating a task or workflow context when authority is lost or rotated after a
+#: browser context has been bound.
+#: A static enrolled origin set never goes missing and never rotates, so neither behaviour can be
+#: inferred from enrollment — do not read "the run is enrolled" as "the run has authority".
+#: This state is deliberately distinct from MISSING so that source, decisions and observe-mode logs
+#: all distinguish "the authority source says no" from "there is no authority source".
+UNWIRED_AUTHORITY = RuntimeOriginAuthority(state=AuthorityState.UNWIRED)
+
+_AUTHORITY_REASONS: dict[AuthorityState, PolicyReason] = {
+ AuthorityState.UNWIRED: PolicyReason.UNWIRED_RUNTIME_AUTHORITY,
+ AuthorityState.MISSING: PolicyReason.MISSING_RUNTIME_AUTHORITY,
+ AuthorityState.INVALIDATED: PolicyReason.INVALIDATED_RUNTIME_AUTHORITY,
+}
+
+
+@dataclass(frozen=True, slots=True)
+class BrowserActionRequest:
+ policy: BrowserActionPolicy | None
+ projection: ActionProjection
+ # No default: the absent-authority states must be named at every construction site rather than
+ # reachable by leaving an argument off.
+ authority: RuntimeOriginAuthority
+ request_epoch: int
+ evidence: PageObservation | None = None
+ protected_references: tuple[ProtectedReference, ...] = ()
+
+ def __post_init__(self) -> None:
+ # Omitting the field already raises. This rejects the other way in — passing None
+ # explicitly — so absence is unreachable by assignment as well, and a gated decision can
+ # never reach an authority it cannot read.
+ if not isinstance(self.authority, RuntimeOriginAuthority):
+ raise TypeError("A browser action request requires a runtime origin authority")
+
+
+@dataclass(frozen=True, slots=True)
+class PolicyDecision:
+ outcome: PolicyOutcome
+ reasons: tuple[PolicyReason, ...] = ()
+
+
+def coerce_verdict(value: object) -> ObservationVerdict:
+ """Normalize a detector verdict by value, failing closed to UNKNOWN."""
+ if not isinstance(value, str):
+ return ObservationVerdict.UNKNOWN
+ try:
+ return ObservationVerdict(value)
+ except ValueError:
+ return ObservationVerdict.UNKNOWN
+
+
+def canonicalize_origin(url: object) -> BrowserOrigin | None:
+ """Extract a canonical origin from an untrusted runtime URL, or None if it is not usable."""
+ if not isinstance(url, str) or not url or url != url.strip() or "\\" in url:
+ return None
+ if any(ord(character) < 32 or ord(character) == 127 for character in url):
+ return None
+ try:
+ parsed = urlsplit(url)
+ raw_scheme = parsed.scheme.lower()
+ scheme = _WEBSOCKET_SCHEMES.get(raw_scheme, raw_scheme)
+ if scheme not in _DEFAULT_PORTS or parsed.username is not None or parsed.password is not None:
+ return None
+ host = parsed.hostname
+ parsed_port = parsed.port
+ port = parsed_port if parsed_port is not None else _DEFAULT_PORTS[scheme]
+ except (UnicodeError, ValueError):
+ return None
+ if host is None or not parsed.netloc or "%" in host:
+ return None
+ host = host.rstrip(".").lower()
+ if not host:
+ return None
+ if not host.isascii():
+ # str.encode("idna") is IDNA2003 + nameprep, which folds ß to "ss" and ς to σ; browsers use
+ # UTS-46 nontransitional and do not. Trusting it would authorize a host the browser never
+ # visits, so a non-ASCII host is refused and operators declare the A-label the browser uses.
+ return None
+ try:
+ host = ipaddress.ip_address(host).compressed.lower()
+ except ValueError:
+ # WHATWG parses a host whose last label is numeric as an IPv4 literal, in decimal, octal or
+ # hex. Anything ip_address refuses here is a malformed or legacy address literal (leading
+ # zeros per CVE-2021-29921, bare integers, 0x7f000001). Passing it through as a domain name
+ # would mint an origin that never matches the host a resolver actually reaches.
+ if _IPV4_LAST_LABEL.fullmatch(host.rpartition(".")[2]):
+ return None
+ try:
+ # IDNA rewrites non-ASCII label separators (U+3002 and friends) as ASCII dots, so the
+ # root label can only be stripped once encoding has settled the separators.
+ host = host.encode("idna").decode("ascii").lower().rstrip(".")
+ except UnicodeError:
+ return None
+ if not host:
+ return None
+ return BrowserOrigin(scheme=scheme, host=host, port=port)
+
+
+def declare_origin(url: str) -> BrowserOrigin:
+ """Validate an operator-declared origin, raising rather than silently narrowing it."""
+ origin = canonicalize_origin(url)
+ if origin is None:
+ raise ValueError(f"Not a declarable browser origin: {url!r}")
+ return origin
+
+
+def declare_policy(*, owner_id: str, origin_urls: Iterable[str], version: int = 1) -> BrowserActionPolicy:
+ if not owner_id:
+ raise ValueError("A browser action policy requires an owner")
+ origins = frozenset(declare_origin(url) for url in origin_urls)
+ if not origins:
+ raise ValueError("A browser action policy requires at least one declared origin")
+ return BrowserActionPolicy(owner_id=owner_id, allowed_origins=origins, version=version)
+
+
+def classify_action_type(action_type: ActionType | str) -> ActionClass | None:
+ try:
+ normalized = ActionType(action_type)
+ except ValueError:
+ return None
+ return _ACTION_CLASSES.get(normalized)
+
+
+def _required_references(action: Action, action_type: ActionType) -> frozenset[ProtectedReferenceKind]:
+ if action_type is ActionType.VERIFICATION_CODE:
+ return frozenset({ProtectedReferenceKind.VERIFICATION_CODE})
+ if action_type is ActionType.UPLOAD_FILE:
+ return frozenset({ProtectedReferenceKind.FILE})
+ if isinstance(action, InputTextAction) and (action.totp_code_required or action.totp_identifier or action.totp_url):
+ return frozenset({ProtectedReferenceKind.SECRET})
+ if isinstance(action, ClickAction) and action.file_url:
+ return frozenset({ProtectedReferenceKind.FILE})
+ return frozenset()
+
+
+def _target(action: Action, action_type: ActionType) -> ActionTarget:
+ if _ACTION_CLASSES.get(action_type) is ActionClass.UNRESOLVABLE:
+ return ActionTarget(resolvable=False)
+ if isinstance(action, (GotoUrlAction, NewTabAction)):
+ return ActionTarget(urls=(action.url,))
+ if isinstance(action, DownloadFileAction) and action.download_url:
+ return ActionTarget(urls=(action.download_url,))
+ # A download carrying bytes rather than a URL has no destination to check here; confining where
+ # it lands is the sink's job, so an EGRESS action is not always target-checked.
+ if isinstance(action, (ClickAction, UploadFileAction)) and action.file_url:
+ return ActionTarget(urls=(action.file_url,))
+ return ActionTarget()
+
+
+def project_action(action: Action) -> ActionProjection:
+ """Project a concrete action model into policy facts, failing closed on any mismatch.
+
+ Never memoize this per action id: handlers rewrite `action_type` in place (COMPLETE becomes
+ TERMINATE), so a projection is only valid for the object as it stands right now.
+ """
+ try:
+ action_type = ActionType(action.action_type)
+ except ValueError:
+ return ActionProjection(
+ action_type=None,
+ action_class=None,
+ target=ActionTarget(resolvable=False),
+ defects=(PolicyReason.UNKNOWN_ACTION,),
+ )
+
+ expected_model = _ACTION_MODELS.get(action_type)
+ action_class = _ACTION_CLASSES.get(action_type)
+ if expected_model is None or action_class is None:
+ # A newly added ActionType that nobody mapped. Crashing inside a security control would make
+ # observe mode behavioural, so it degrades to an unknown action instead.
+ return ActionProjection(
+ action_type=action_type,
+ action_class=None,
+ target=ActionTarget(resolvable=False),
+ defects=(PolicyReason.UNKNOWN_ACTION,),
+ )
+
+ if type(action) is not expected_model:
+ # The field layout cannot be trusted once the model and its discriminator disagree, so no
+ # target or reference facts are extracted from it.
+ return ActionProjection(
+ action_type=action_type,
+ action_class=None,
+ target=ActionTarget(resolvable=False),
+ defects=(PolicyReason.ACTION_MODEL_MISMATCH,),
+ )
+
+ return ActionProjection(
+ action_type=action_type,
+ action_class=action_class,
+ target=_target(action, action_type),
+ required_references=_required_references(action, action_type),
+ )
+
+
+def _reference_reasons(
+ required: frozenset[ProtectedReferenceKind],
+ supplied: tuple[ProtectedReference, ...],
+ owner_id: str,
+) -> set[PolicyReason]:
+ reasons: set[PolicyReason] = set()
+ usable: set[ProtectedReferenceKind] = set()
+ for reference in supplied:
+ if not reference.complete:
+ reasons.add(PolicyReason.INCOMPLETE_PROTECTED_REFERENCE)
+ elif reference.owner_id != owner_id:
+ reasons.add(PolicyReason.UNOWNED_PROTECTED_REFERENCE)
+ else:
+ usable.add(reference.kind)
+ if required - usable:
+ reasons.add(PolicyReason.MISSING_PROTECTED_REFERENCE)
+ return reasons
+
+
+def decide_browser_action(request: BrowserActionRequest) -> PolicyDecision:
+ """Evaluate one proposed browser action. `policy=None` is the only path to `not_enrolled`.
+
+ The enrolled policy is a ceiling, not the complete authority: an origin-gated action is allowed
+ only when a live `RuntimeOriginAuthority` grants it *and* the ceiling admits it.
+ """
+ policy = request.policy
+ if policy is None:
+ return PolicyDecision(outcome=PolicyOutcome.NOT_ENROLLED)
+
+ projection = request.projection
+ action_class = projection.action_class
+ reasons: set[PolicyReason] = set(projection.defects)
+
+ if action_class is None and not reasons & {PolicyReason.UNKNOWN_ACTION, PolicyReason.ACTION_MODEL_MISMATCH}:
+ # ActionProjection is public API with `defects` defaulting to (), so a caller can hand us an
+ # unclassified projection. Unclassifiable means deny, never fall through to the exempt set.
+ reasons.add(PolicyReason.UNKNOWN_ACTION)
+ if action_class is ActionClass.UNSUPPORTED:
+ reasons.add(PolicyReason.UNSUPPORTED_ACTION)
+ if action_class is ActionClass.UNRESOLVABLE or not projection.target.resolvable:
+ reasons.add(PolicyReason.UNRESOLVABLE_TARGET)
+
+ evidence = request.evidence
+ if evidence is None:
+ reasons.add(PolicyReason.MISSING_PAGE_EVIDENCE)
+ page_origin = None
+ verdict = ObservationVerdict.UNKNOWN
+ else:
+ if evidence.observation_epoch != request.request_epoch:
+ reasons.add(PolicyReason.STALE_PAGE_EVIDENCE)
+ page_origin = canonicalize_origin(evidence.page_url)
+ if page_origin is None:
+ reasons.add(PolicyReason.MISSING_PAGE_ORIGIN)
+ verdict = coerce_verdict(evidence.verdict)
+
+ reasons |= _reference_reasons(projection.required_references, request.protected_references, policy.owner_id)
+
+ if action_class not in _VERDICT_UNGATED_CLASSES:
+ if verdict is ObservationVerdict.SUSPICIOUS:
+ reasons.add(PolicyReason.UNTRUSTED_OBSERVATION)
+ elif verdict is ObservationVerdict.UNKNOWN:
+ reasons.add(PolicyReason.UNVERIFIED_OBSERVATION)
+ if action_class not in _ORIGIN_UNGATED_CLASSES:
+ authority = request.authority
+ authority_reason = _AUTHORITY_REASONS.get(authority.state)
+ if authority.state is not AuthorityState.ESTABLISHED:
+ # Being inside the enrolled ceiling is never sufficient to allow. Without a live
+ # authority the answer to "what may this action reach" is unknown, and unknown denies.
+ reasons.add(authority_reason if authority_reason is not None else PolicyReason.MISSING_RUNTIME_AUTHORITY)
+ else:
+ reachable = policy.allowed_origins & authority.origins
+ if page_origin is not None and page_origin not in reachable:
+ reasons.add(PolicyReason.PAGE_ORIGIN_NOT_AUTHORIZED)
+ for url in projection.target.urls:
+ target_origin = canonicalize_origin(url)
+ if target_origin is None:
+ reasons.add(PolicyReason.MISSING_TARGET_ORIGIN)
+ elif target_origin not in reachable:
+ reasons.add(PolicyReason.TARGET_ORIGIN_NOT_AUTHORIZED)
+
+ if PolicyReason.UNSUPPORTED_ACTION in reasons:
+ outcome = PolicyOutcome.UNSUPPORTED
+ elif reasons:
+ outcome = PolicyOutcome.DENIED
+ else:
+ outcome = PolicyOutcome.ALLOWED
+ return PolicyDecision(outcome=outcome, reasons=tuple(sorted(reasons, key=REASON_PRECEDENCE.index)))
diff --git a/skyvern/forge/sdk/browser_action_preflight.py b/skyvern/forge/sdk/browser_action_preflight.py
new file mode 100644
index 000000000..f5effd98c
--- /dev/null
+++ b/skyvern/forge/sdk/browser_action_preflight.py
@@ -0,0 +1,345 @@
+"""Observe-only wiring of the browser action policy onto the agent's action path (SKY-12874).
+
+Turns the pure decision core in :mod:`skyvern.forge.sdk.browser_action_policy` into something that
+runs against a live browser: it advances a run-local observation epoch on every accepted scrape,
+stamps parsed actions with the epoch they were planned under, and evaluates each proposed action
+against live page facts before it reaches its effective path.
+
+Nothing here is allowed to change execution. ``decide_browser_action`` returns a decision and never
+raises; every function in this module swallows its own failures for the same reason. Enforcement
+belongs at the sinks (SKY-12881+), and that separation is what keeps observe mode non-behavioural.
+Observation is also a pure observer of the browser: it reads the page and never re-pins the working
+page, closes a tab, registers a listener or runs script. Where a page cannot be observed without
+mutating something, the answer is no observation, not a mutation to produce one.
+
+An epoch is PROVENANCE, not freshness — see :func:`_live_observation` for what that does and does
+not establish. Nothing in this module proves that page content still matches what was scraped.
+
+The policy is read from the already-bound :class:`~skyvern.forge.sdk.core.skyvern_context.
+SkyvernContext` slot and never re-read from the database: it binds once per run before the browser
+exists, so a mid-run control-plane replacement cannot alter a live run's authority.
+"""
+
+from __future__ import annotations
+
+import weakref
+from collections.abc import Iterable
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+import structlog
+
+from skyvern.config import settings
+from skyvern.forge.sdk.api.crypto import calculate_sha256
+from skyvern.forge.sdk.browser_action_policy import (
+ BrowserActionRequest,
+ ObservationVerdict,
+ PageObservation,
+ PolicyDecision,
+ PolicyOutcome,
+ canonicalize_origin,
+ decide_browser_action,
+ project_action,
+)
+from skyvern.forge.sdk.core import skyvern_context
+
+if TYPE_CHECKING:
+ from playwright.async_api import Page
+
+ from skyvern.webeye.actions.actions import Action
+
+LOG = structlog.get_logger()
+
+# *** NO LOG CALL IN THIS MODULE MAY CARRY EXCEPTION TEXT. ***
+# An exception's text is arbitrary and routinely carries the data it choked on — a page URL, a
+# signed download link — and exc_info formats it into both the log stream and the persisted run
+# artifact. This is an observe-only security control; leaking is the one thing it must not do.
+# That means no exc_info, no exception object, no str(exc) under any name, and not LOG.exception,
+# which supplies a traceback implicitly. Faults report their type and their source location via
+# _error_location instead. Enforced by a test that permits an exact SET OF ARGUMENT EXPRESSIONS and
+# rejects everything else, because three earlier versions of that check matched forbidden NAMES and
+# each was evaded by a name the next edit was free to choose differently.
+
+# An action that never went through `stamp_batch` carries no observation identity. -1 can never
+# equal a real epoch, so such an action is reported stale rather than silently matching one.
+UNSTAMPED_EPOCH = -1
+
+# Not a PolicyOutcome: the policy never produced one. Emitted on the decision event so an operator
+# counting outcomes sees a control that failed rather than a control that found nothing.
+INTERNAL_ERROR_OUTCOME = "internal_error"
+
+# Every emitter of this event must be non-sensitive BY CONSTRUCTION, not by a redactor downstream.
+# There is more than one — the decision path and the internal-fault path — and a guarantee that
+# holds on one of two sinks is not a guarantee.
+DECISION_EVENT = "Browser action policy decision"
+
+
+@dataclass(frozen=True, slots=True)
+class ObservationEpoch:
+ """One accepted scrape, bound to the facts it observed.
+
+ ``page`` is a weak reference rather than ``id(page)`` because CPython reuses ids after
+ collection, and a reused id would let one tab's observation vouch for another tab's action.
+ """
+
+ epoch: int
+ page: weakref.ReferenceType[Page] | None
+ main_frame_url: str
+ element_digest: str
+
+
+def policy_observation_enabled() -> bool:
+ """Whether policy observation runs. Deliberately independent of any prompt-scanning switch:
+ the scanner supplies a verdict, it does not decide whether the policy gets to look."""
+ return settings.BROWSER_ACTION_POLICY_MODE != "disabled"
+
+
+def _page_reference(page: Page) -> weakref.ReferenceType[Page] | None:
+ try:
+ return weakref.ref(page)
+ except TypeError:
+ # An unreferenceable page can never be matched later, so the observation vouches for
+ # nothing. That is the fail-closed direction.
+ return None
+
+
+def _error_location(error: BaseException) -> str | None:
+ """Where a fault came from, read straight off the traceback objects.
+
+ Deliberately NOT ``traceback.extract_tb``: that resolves each frame's source line through
+ linecache, which may call a module loader's ``get_source`` while catching only ImportError and
+ OSError — so any other loader exception propagates. This helper is called from inside handlers
+ whose entire job is to swallow, so a helper that can raise would let the control end the caller
+ while handling its own internal fault. That is the one thing observe mode may never do.
+
+ ``tb_lineno`` and the code object are already in memory: no source lookup, no I/O, and the walk
+ to the innermost frame is a pointer chase. The whole body is wrapped anyway, because "cannot
+ raise" is worth having structurally rather than by argument.
+
+ The values are code identifiers for every frame in this call graph, which is statically defined.
+ That is not a universal guarantee — a dynamically compiled frame can carry arbitrary text in
+ ``co_filename`` — so this is safe for the frames we actually reach, not by construction for all
+ conceivable ones.
+ """
+ try:
+ frame_traceback = error.__traceback__
+ if frame_traceback is None:
+ return None
+ while frame_traceback.tb_next is not None:
+ frame_traceback = frame_traceback.tb_next
+ code = frame_traceback.tb_frame.f_code
+ return f"{code.co_filename.rpartition('/')[2]}:{frame_traceback.tb_lineno}:{code.co_name}"
+ except Exception:
+ return None
+
+
+def advance_observation_epoch(page: Page, *, main_frame_url: str, element_hashes: Iterable[str]) -> None:
+ """Record an accepted scrape as the run's newest observation.
+
+ Called once per successful scrape, from the scrape itself rather than from its retry wrapper —
+ the wrapper recurses, so one accepted scrape would otherwise advance the epoch twice.
+ """
+ if not policy_observation_enabled():
+ return
+ try:
+ context = skyvern_context.current()
+ if context is None:
+ return
+ previous = context.browser_observation_epoch
+ context.browser_observation_epoch = ObservationEpoch(
+ epoch=1 if previous is None else previous.epoch + 1,
+ page=_page_reference(page),
+ main_frame_url=main_frame_url,
+ element_digest=calculate_sha256("\n".join(sorted(element_hashes))),
+ )
+ except Exception as error:
+ # Nested guard: this handler's contract is to swallow, so nothing inside it may raise
+ # either — not the formatting, not the logger. Structural, not by argument.
+ try:
+ LOG.warning(
+ "Failed to advance the browser action observation epoch",
+ error_type=type(error).__name__,
+ error_location=_error_location(error),
+ )
+ except Exception:
+ pass
+
+
+def stamp_parsed_actions(actions: Iterable[Action]) -> None:
+ """Bind actions parsed out of a scrape to the observation they were parsed from.
+
+ Only actions derived from the scrape may be stamped. An action the runtime injected before the
+ scrape ran — a proactive captcha solve, an internal reload — predates the observation, so
+ stamping it here would hand it provenance it never earned. Such an action stays unstamped and
+ is judged on that.
+ """
+ if not policy_observation_enabled():
+ return
+ try:
+ context = skyvern_context.current()
+ epoch = None if context is None else context.browser_observation_epoch
+ if epoch is None:
+ return
+ for action in actions:
+ action.observation_epoch = epoch.epoch
+ action.observation_digest = epoch.element_digest
+ except Exception as error:
+ try:
+ LOG.warning(
+ "Failed to stamp actions with an observation epoch",
+ error_type=type(error).__name__,
+ error_location=_error_location(error),
+ )
+ except Exception:
+ pass
+
+
+def observed_page() -> Page | None:
+ """The page the newest accepted scrape ran on, read from this module's own record.
+
+ Deliberately not resolved through the browser state. ``must_get_working_page`` re-pins the
+ working page and can close over-limit tabs, so asking it for a page would make observe mode
+ diverge from disabled mode. When no page is resolvable the answer is no observation, never a
+ mutation to make one possible.
+ """
+ context = skyvern_context.current()
+ epoch = None if context is None else context.browser_observation_epoch
+ if epoch is None or epoch.page is None:
+ return None
+ return epoch.page()
+
+
+def _live_observation(action: Action, page: Page) -> PageObservation | None:
+ """Provenance for this action, or None when it has none. NOT a freshness proof.
+
+ What is checked here is verifiable from a synchronous, read-only look at the page: the action
+ was parsed from the newest accepted scrape, that scrape ran on this same page object, that page
+ is still open, and the main-frame URL has not changed since.
+
+ *** WHAT IS NOT CHECKED, BECAUSE IT CANNOT BE. *** A page can replace its own content with
+ ``document.write`` or by assigning ``innerHTML`` while the page object, the URL and this epoch
+ all stay fixed. Chromium emits no navigation event for either, so no read-only signal exists to
+ detect it, and re-observing would mean a rescrape. An earlier revision used a ``framenavigated``
+ listener here; it was removed because a real browser never fires it for these cases, so it
+ advertised coverage it did not have.
+
+ Content trust therefore lives entirely on the verdict axis, which is where ADR-0011 puts it:
+ the detector scans what the observation captured, and its verdict is what a content-dependent
+ action is gated on. This function establishes only that the action came from the observation
+ that describes this page — never that the page still matches what was observed.
+ """
+ context = skyvern_context.current()
+ epoch = None if context is None else context.browser_observation_epoch
+ if epoch is None:
+ return None
+ # A reference that could not be taken, or whose page has been collected, vouches for nothing.
+ observed = None if epoch.page is None else epoch.page()
+ if observed is None or observed is not page:
+ return None
+ if page.is_closed():
+ # Playwright keeps serving the LAST KNOWN url and main_frame.url from cache after close, so
+ # every other check here still passes on a page that no longer exists. is_closed is
+ # synchronous and read-only, which is the only reason it may be consulted from here.
+ return None
+ if action.observation_digest != epoch.element_digest:
+ # Provenance is content-bound, not positional: an epoch number alone can be matched by a
+ # value that never came from this observation, and the digest cannot.
+ return None
+ if page.main_frame.url != epoch.main_frame_url:
+ # The page navigated since the scrape, so the observed elements no longer describe it. The
+ # live URL alone is not an observation.
+ return None
+ return PageObservation(
+ page_url=page.url,
+ observation_epoch=epoch.epoch,
+ # No detector supplies a verdict yet — SKY-12526's scanner is unmerged — and an unverified
+ # observation denies rather than passes. See the module docstring of the policy core.
+ verdict=ObservationVerdict.UNKNOWN,
+ )
+
+
+def preflight_action(action: Action, page: Page | None, *, site: str) -> PolicyDecision | None:
+ """Evaluate one proposed action against live page facts. Returns None when observation is off.
+
+ Never memoized per action id: handlers rewrite ``action_type`` in place and derive new actions
+ from old ones, so every effective path re-projects the object as it stands right now.
+
+ ``page`` may be None when nothing observable could be resolved without mutating browser state;
+ that yields a decision with no evidence, which denies.
+ """
+ if not policy_observation_enabled():
+ return None
+ try:
+ context = skyvern_context.current()
+ if context is None:
+ return None
+ observation = None if page is None else _live_observation(action, page)
+ decision = decide_browser_action(
+ BrowserActionRequest(
+ policy=context.browser_action_policy,
+ projection=project_action(action),
+ authority=context.browser_action_authority,
+ request_epoch=action.observation_epoch if action.observation_epoch is not None else UNSTAMPED_EPOCH,
+ evidence=observation,
+ )
+ )
+ _emit(decision, action=action, observation=observation, site=site)
+ return decision
+ except Exception as error:
+ # Swallowing is required — observe mode may never change execution — but silence is not.
+ # Without its own outcome an internal fault reads as "no policy concern" on a dashboard
+ # counting decisions, which is the same mistake UNWIRED exists to avoid.
+ try:
+ LOG.warning(
+ DECISION_EVENT,
+ site=site,
+ outcome=INTERNAL_ERROR_OUTCOME,
+ reasons=[],
+ error_type=type(error).__name__,
+ error_location=_error_location(error),
+ )
+ except Exception:
+ pass
+ return None
+
+
+def preflight_batch(actions: Iterable[Action], *, site: str) -> None:
+ """Evaluate a complete batch before any of it is persisted, awaited or executed.
+
+ Stamping is not done here. It belongs at the point actions are parsed out of a scrape, so that
+ an action which reached this batch by another route cannot pick up provenance on the way past.
+ """
+ if not policy_observation_enabled():
+ return
+ page = observed_page()
+ for action in actions:
+ preflight_action(action, page, site=site)
+
+
+def preflight_derived_action(derived: Action, page: Page, *, parent: Action, site: str) -> PolicyDecision | None:
+ """Evaluate an action a handler built from another one, before it takes its effective path.
+
+ The derived action inherits the parent's observation identity because it carries out the same
+ planned intent; what it does not inherit is the parent's projection, which is the point.
+ """
+ derived.observation_epoch = parent.observation_epoch
+ derived.observation_digest = parent.observation_digest
+ return preflight_action(derived, page, site=site)
+
+
+def _emit(decision: PolicyDecision, *, action: Action, observation: PageObservation | None, site: str) -> None:
+ """Log a decision. Carries stable codes and canonical origins only — never page text, full URLs
+ (query strings carry customer data), element content or protected values."""
+ if decision.outcome is PolicyOutcome.NOT_ENROLLED:
+ return
+ origin = None if observation is None else canonicalize_origin(observation.page_url)
+ LOG.info(
+ DECISION_EVENT,
+ site=site,
+ outcome=decision.outcome.value,
+ reasons=[reason.value for reason in decision.reasons],
+ action_type=action.action_type,
+ action_epoch=action.observation_epoch,
+ observation_epoch=None if observation is None else observation.observation_epoch,
+ page_origin=None if origin is None else origin.canonical,
+ )
diff --git a/skyvern/forge/sdk/core/skyvern_context.py b/skyvern/forge/sdk/core/skyvern_context.py
index 0c0937ed6..78ccdfbd9 100644
--- a/skyvern/forge/sdk/core/skyvern_context.py
+++ b/skyvern/forge/sdk/core/skyvern_context.py
@@ -1,6 +1,7 @@
from __future__ import annotations
import asyncio
+import builtins
from contextlib import contextmanager
from contextvars import ContextVar, Token
from dataclasses import dataclass, field
@@ -15,6 +16,8 @@ from skyvern.config import settings
if TYPE_CHECKING:
from playwright.async_api import FileChooser, Frame, Page
+ from skyvern.forge.sdk.browser_action_policy import BrowserActionPolicy, RuntimeOriginAuthority
+ from skyvern.forge.sdk.browser_action_preflight import ObservationEpoch
from skyvern.forge.sdk.db.enums import WorkflowRunTriggerType
# Deferred import: skyvern_context.py sits below the service layer and
@@ -31,6 +34,14 @@ MAX_RECENT_DIALOG_MESSAGES = 5
MAX_DIALOG_MESSAGE_CHARS = 500
+def _unwired_authority() -> RuntimeOriginAuthority:
+ # Same deferred-import reason as the TYPE_CHECKING block above: the policy core pulls the action
+ # models, which this module must not import at module load.
+ from skyvern.forge.sdk.browser_action_policy import UNWIRED_AUTHORITY
+
+ return UNWIRED_AUTHORITY
+
+
class DialogEntry(TypedDict):
type: str
message: str
@@ -96,7 +107,9 @@ class SkyvernContext:
active_credential_parameter_key: str | None = None
log: list[dict] = field(default_factory=list)
hashed_href_map: dict[str, str] = field(default_factory=dict)
- downloaded_pdf_sources: set[str] = field(default_factory=set)
+ # builtins.set, not set: the module-level `set` context setter below shadows the
+ # builtin for anything that resolves the name after import.
+ downloaded_pdf_sources: set[str] = field(default_factory=builtins.set)
refresh_working_page: bool = False
frame_index_map: dict[Frame, int] = field(default_factory=dict)
dropped_css_svg_element_map: dict[str, bool] = field(default_factory=dict)
@@ -156,7 +169,7 @@ class SkyvernContext:
script_run_parameters: dict[str, Any] = field(default_factory=dict)
script_mode: bool = False
is_static_script: bool = False
- sensitive_values: set[str] = field(default_factory=set)
+ sensitive_values: set[str] = field(default_factory=builtins.set)
ai_mode_override: str | None = None
script_llm_call_count: int = 0
last_classify_result: str | None = None
@@ -199,7 +212,7 @@ class SkyvernContext:
# Track task_ids where proactive captcha injection has already been attempted,
# preventing repeated injection loops when the captcha solver succeeds but the page doesn't change
- proactive_captcha_task_ids: set[str] = field(default_factory=set)
+ proactive_captcha_task_ids: set[str] = field(default_factory=builtins.set)
# Circuit breaker: consecutive captcha solve timeouts for this workflow run.
# When this reaches the threshold, further captcha solve attempts are short-circuited.
@@ -220,6 +233,34 @@ class SkyvernContext:
# can be completed when a subsequent click triggers the actual file chooser.
pending_file_chooser: PendingFileChooserListener | None = None
+ # Browser action firewall (SKY-12873). Bound from the resolved workflow version before the run's
+ # browser exists; None means unenrolled, which is the only state standalone SDK actions can be
+ # in. Never copied from a parent context — a child workflow binds its own version's policy.
+ #
+ # Deliberately a plain attribute and not a property: the value must already be resolved before
+ # the browser existed, and an accessor would invite lazy loading that reads it mid-run, letting
+ # a control-plane replacement change a live run's authority.
+ #
+ # This is a CEILING, not the complete authority. It answers "is this run protected, and what did
+ # an operator authorize at most" — not "what may this action reach right now". A consumer must
+ # not treat within-the-enrolled-set as sufficient to allow.
+ browser_action_policy: BrowserActionPolicy | None = None
+
+ # What the run may reach *right now* (SKY-12874). The ceiling above says what an operator
+ # authorized at most; this says what ADR-0011's task-URL-derived authority grants at this
+ # moment, and an origin-gated action needs both.
+ #
+ # It is UNWIRED_AUTHORITY on every run today, because nothing derives an authority yet:
+ # SKY-12883, SKY-12884 and SKY-12886 are the tickets that fill this slot. Until they land, no
+ # code in this repository implements ADR-0011's "block until authority is established" or its
+ # "permanently invalidate on loss or rotation after a browser context is bound". Enrollment
+ # cannot stand in for either — a static origin set never goes missing and never rotates.
+ browser_action_authority: RuntimeOriginAuthority = field(default_factory=_unwired_authority)
+
+ # Newest accepted scrape (SKY-12874). Advanced by the scrape itself; actions are stamped with
+ # the epoch they were planned under so an observation cannot vouch for a plan built before it.
+ browser_observation_epoch: ObservationEpoch | None = None
+
def set_enrich_tree_mode(self, mode: Any) -> None:
self.enrich_tree_mode = parse_enrich_tree_mode(mode)
diff --git a/skyvern/forge/sdk/db/repositories/workflow_parameters.py b/skyvern/forge/sdk/db/repositories/workflow_parameters.py
index 5774779cb..ab5d5111a 100644
--- a/skyvern/forge/sdk/db/repositories/workflow_parameters.py
+++ b/skyvern/forge/sdk/db/repositories/workflow_parameters.py
@@ -1037,4 +1037,7 @@ class WorkflowParametersRepository(BaseRepository):
)
actions = (await session.scalars(query)).all()
- return [Action.model_validate(action) for action in actions]
+ # hydrate_action, not Action.model_validate: the base model has no action_json merge, so
+ # validating the row directly drops every subclass field a cached action was recorded
+ # with. Matches every other retrieval site.
+ return [hydrate_action(action) for action in actions]
diff --git a/skyvern/forge/sdk/db/repositories/workflows.py b/skyvern/forge/sdk/db/repositories/workflows.py
index ff3e811a1..a8af273cb 100644
--- a/skyvern/forge/sdk/db/repositories/workflows.py
+++ b/skyvern/forge/sdk/db/repositories/workflows.py
@@ -8,6 +8,7 @@ import structlog
from sqlalchemy import exists, func, or_, select, update
from skyvern.constants import DEFAULT_SCRIPT_RUN_ID
+from skyvern.forge.sdk.browser_action_policy import BrowserActionPolicy, declare_policy
from skyvern.forge.sdk.db._error_handling import db_operation
from skyvern.forge.sdk.db._sentinels import _UNSET
from skyvern.forge.sdk.db._soft_delete import exclude_deleted
@@ -32,6 +33,13 @@ from skyvern.forge.sdk.db.models import (
from skyvern.forge.sdk.db.repositories.workflow_parameters import WorkflowParametersRepository
from skyvern.forge.sdk.db.tag_filters import workflow_tag_wpid_subqueries
from skyvern.forge.sdk.db.utils import convert_to_workflow, nullable_column_equals, serialize_proxy_location
+from skyvern.forge.sdk.workflow.browser_action_policy_enrollment import (
+ carried_policy,
+ read_policy,
+ serialize_policy,
+ stored_policy_version,
+ with_policy,
+)
from skyvern.forge.sdk.workflow.models.block import Block, ForLoopBlock, WhileLoopBlock
from skyvern.forge.sdk.workflow.models.parameter import OutputParameter
from skyvern.forge.sdk.workflow.models.workflow import Workflow, WorkflowDefinition
@@ -86,6 +94,26 @@ def _align_block_output_parameters(workflow_definition: WorkflowDefinition) -> N
class WorkflowsRepository(BaseRepository):
"""Database operations for workflow management."""
+ async def _policy_of_latest_version(
+ self, session: Any, workflow_permanent_id: str, organization_id: str | None
+ ) -> object | None:
+ """Deliberately does NOT exclude soft-deleted rows, unlike the read used at bind time.
+
+ `create_workflow_from_request` numbers the new version off this same row set
+ (`filter_deleted=False`), so "previous version" has to mean the same thing here. Skipping
+ deleted rows would let deleting the enrolled version silently unenroll the next save — a
+ clear, which no ordinary save is allowed to perform.
+ """
+ query = (
+ select(WorkflowModel.workflow_definition)
+ .filter_by(workflow_permanent_id=workflow_permanent_id)
+ .order_by(WorkflowModel.version.desc())
+ .limit(1)
+ )
+ if organization_id:
+ query = query.filter_by(organization_id=organization_id)
+ return carried_policy(await session.scalar(query))
+
@db_operation("create_workflow")
async def create_workflow(
self,
@@ -124,11 +152,18 @@ class WorkflowsRepository(BaseRepository):
edited_by: str | None = None,
) -> Workflow:
async with self.Session() as session:
+ # Policy is never taken from the caller's definition: a new version inherits exactly what
+ # the previous one stored, so no save path can add, widen or clear an enrollment.
+ carried = (
+ await self._policy_of_latest_version(session, workflow_permanent_id, organization_id)
+ if workflow_permanent_id
+ else None
+ )
workflow = WorkflowModel(
organization_id=organization_id,
title=title,
description=description,
- workflow_definition=workflow_definition,
+ workflow_definition=with_policy(workflow_definition, carried),
proxy_location=serialize_proxy_location(proxy_location),
webhook_callback_url=webhook_callback_url,
totp_verification_url=totp_verification_url,
@@ -183,6 +218,58 @@ class WorkflowsRepository(BaseRepository):
await session.refresh(workflow)
return convert_to_workflow(workflow, self.debug_enabled)
+ @db_operation("get_browser_action_policy")
+ async def get_browser_action_policy(
+ self, workflow_id: str, organization_id: str | None = None
+ ) -> BrowserActionPolicy | None:
+ """The workflow version's enrolled policy, or None. Raises ValueError on corrupt stored data
+ so an unreadable enrollment fails the run instead of silently unenrolling it."""
+ query = exclude_deleted(
+ select(WorkflowModel.workflow_definition).filter_by(workflow_id=workflow_id), WorkflowModel
+ )
+ if organization_id:
+ query = query.filter_by(organization_id=organization_id)
+ async with self.Session() as session:
+ return read_policy(await session.scalar(query))
+
+ @db_operation("set_browser_action_policy")
+ async def set_browser_action_policy(
+ self,
+ workflow_id: str,
+ organization_id: str,
+ allowed_origin_urls: list[str] | None,
+ ) -> BrowserActionPolicy | None:
+ """Replace (or, with `allowed_origin_urls=None`, clear) the version's policy.
+
+ The policy version is minted here, inside the read-modify-write, so concurrent replacements
+ cannot mint the same one. It advances for the life of an enrollment and restarts after a
+ clear — a clear is an operator de-enrolling the version, not an edit to a live policy.
+
+ Runs already past binding keep the policy they resolved; only subsequent runs see this.
+ """
+ async with self.Session() as session:
+ query = exclude_deleted(
+ select(WorkflowModel).filter_by(workflow_id=workflow_id, organization_id=organization_id),
+ WorkflowModel,
+ ).with_for_update()
+ workflow = (await session.scalars(query)).first()
+ if not workflow:
+ raise NotFoundError("Workflow not found")
+
+ definition: dict[str, Any] = workflow.workflow_definition or {}
+ policy: BrowserActionPolicy | None = None
+ if allowed_origin_urls is not None:
+ policy = declare_policy(
+ owner_id=organization_id,
+ origin_urls=allowed_origin_urls,
+ version=stored_policy_version(definition) + 1,
+ )
+ workflow.workflow_definition = with_policy(
+ definition, serialize_policy(policy) if policy is not None else None
+ )
+ await session.commit()
+ return policy
+
@db_operation("soft_delete_workflow_by_id")
async def soft_delete_workflow_by_id(self, workflow_id: str, organization_id: str) -> None:
async with self.Session() as session:
@@ -721,7 +808,9 @@ class WorkflowsRepository(BaseRepository):
if description is not None:
workflow.description = description
if workflow_definition is not None:
- workflow.workflow_definition = workflow_definition
+ workflow.workflow_definition = with_policy(
+ workflow_definition, carried_policy(workflow.workflow_definition)
+ )
if version is not None:
workflow.version = version
if run_with is not None:
@@ -1076,7 +1165,9 @@ class WorkflowsRepository(BaseRepository):
# not depend on caller-side object identity between the
# top-level parameters list and each block's field.
_align_block_output_parameters(workflow_definition)
- workflow.workflow_definition = workflow_definition.model_dump(mode="json")
+ workflow.workflow_definition = with_policy(
+ workflow_definition.model_dump(mode="json"), carried_policy(workflow.workflow_definition)
+ )
if version is not None:
workflow.version = version
if run_with is not None:
diff --git a/skyvern/forge/sdk/forge_log.py b/skyvern/forge/sdk/forge_log.py
index 38cc00a41..23658b094 100644
--- a/skyvern/forge/sdk/forge_log.py
+++ b/skyvern/forge/sdk/forge_log.py
@@ -213,6 +213,17 @@ def redact_bearer_tokens(logger: logging.Logger, method_name: str, event_dict: E
return event_dict
+def _compact_action(action: Any) -> Any:
+ """The few fields a log line needs to correlate. Anything else belongs in the database."""
+ if isinstance(action, (str, int, float, bool, dict, list, type(None))):
+ return action
+ return {
+ "id": getattr(action, "action_id", None),
+ "type": str(getattr(action, "action_type", type(action).__name__)),
+ "element_id": getattr(action, "element_id", None),
+ }
+
+
def compact_action_objects(logger: logging.Logger, method_name: str, event_dict: EventDict) -> EventDict:
"""Compact verbose Action / ActionResult kwargs to a few key fields.
@@ -220,15 +231,24 @@ def compact_action_objects(logger: logging.Logger, method_name: str, event_dict:
Action dataclass dumps 25+ attributes including LLM-generated reasoning /
intention / response strings. Full action data is persisted to the DB and
queryable there; logs only need enough to correlate.
+
+ ``actions=`` is handled the same way for the same reason: a batch of ten renders ten full
+ reprs. It happens to keep a signed ``file_url`` out of that one shape, but this is a LOG VOLUME
+ control and NOT a redaction control — it inspects two fixed keys and nothing else, so no part of
+ it should be relied on to keep credentials out of logs. Credential redaction across the logging
+ stack is a separate concern with its own ticket.
"""
action = event_dict.get("action")
if action is not None and not isinstance(action, (str, int, float, bool, dict, list, type(None))):
try:
- event_dict["action"] = {
- "id": getattr(action, "action_id", None),
- "type": str(getattr(action, "action_type", type(action).__name__)),
- "element_id": getattr(action, "element_id", None),
- }
+ event_dict["action"] = _compact_action(action)
+ except Exception:
+ pass
+
+ actions = event_dict.get("actions")
+ if isinstance(actions, (list, tuple)) and actions:
+ try:
+ event_dict["actions"] = [_compact_action(item) for item in actions]
except Exception:
pass
diff --git a/skyvern/forge/sdk/workflow/browser_action_policy_enrollment.py b/skyvern/forge/sdk/workflow/browser_action_policy_enrollment.py
new file mode 100644
index 000000000..36c956dd9
--- /dev/null
+++ b/skyvern/forge/sdk/workflow/browser_action_policy_enrollment.py
@@ -0,0 +1,145 @@
+"""Enrollment of workflow versions in the browser action firewall (SKY-12873).
+
+Persistence, eligibility and run binding for :mod:`skyvern.forge.sdk.browser_action_policy`. The
+policy is stored as a reserved key inside the existing ``workflow_definition`` JSON rather than as a
+field on :class:`WorkflowDefinition`: pydantic drops unknown keys, so no request model can carry a
+policy in and no response can echo one out. That same drop would silently erase an enrollment on any
+read-modify-write through the model, so every write goes through :func:`with_policy`.
+
+An enrolled policy is a CEILING, not a complete authority: it records that an operator protected this
+workflow version and the widest origin set they authorized. It does not say what a given action may
+reach at this moment, and a consumer must not read "inside the enrolled set" as sufficient to allow.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Any
+
+from skyvern.exceptions import BrowserActionPolicyNotEnforceable
+from skyvern.forge.sdk.browser_action_policy import BrowserActionPolicy, declare_policy
+from skyvern.forge.sdk.core import skyvern_context
+from skyvern.forge.sdk.workflow.models.block import BlockType, get_all_blocks
+from skyvern.forge.sdk.workflow.models.workflow import Workflow
+
+POLICY_KEY = "browser_action_policy"
+
+_STORED_FIELDS = frozenset({"owner_id", "allowed_origins", "version"})
+
+
+class EnrollmentRejection(StrEnum):
+ """Why a workflow version cannot run under a policy. Values are stable and carry no content."""
+
+ CODE_BLOCK_PRESENT = "code_block_present"
+ CODE_EXECUTION_SELECTED = "code_execution_selected"
+ ADAPTIVE_CACHING_ENABLED = "adaptive_caching_enabled"
+ SCRIPT_GENERATION_ENABLED = "script_generation_enabled"
+
+
+def serialize_policy(policy: BrowserActionPolicy) -> dict[str, Any]:
+ """`allowed_origins` is a frozenset and frozensets have no order — sorting the canonical forms is
+ what makes two equal policies serialize to identical JSON."""
+ return {
+ "owner_id": policy.owner_id,
+ "allowed_origins": sorted(origin.canonical for origin in policy.allowed_origins),
+ "version": policy.version,
+ }
+
+
+def deserialize_policy(raw: object) -> BrowserActionPolicy:
+ """Rebuild a stored policy, raising ValueError on anything the declaration rules reject."""
+ if not isinstance(raw, dict):
+ raise ValueError(f"Stored browser action policy is not an object: {type(raw).__name__}")
+ if set(raw) != _STORED_FIELDS:
+ raise ValueError(f"Stored browser action policy has unexpected fields: {sorted(raw)}")
+ owner_id = raw["owner_id"]
+ origins = raw["allowed_origins"]
+ version = raw["version"]
+ if not isinstance(owner_id, str):
+ raise ValueError("Stored browser action policy has a non-string owner")
+ if isinstance(version, bool) or not isinstance(version, int):
+ raise ValueError("Stored browser action policy has a non-integer version")
+ if not isinstance(origins, list) or not all(isinstance(origin, str) for origin in origins):
+ raise ValueError("Stored browser action policy origins are not a list of strings")
+ return declare_policy(owner_id=owner_id, origin_urls=origins, version=version)
+
+
+def read_policy(workflow_definition: object) -> BrowserActionPolicy | None:
+ """The version's policy, or None when it is unenrolled. Raises when it is enrolled but unusable —
+ an enrolled version whose policy cannot be read must never degrade to an unenrolled run."""
+ if not isinstance(workflow_definition, dict) or POLICY_KEY not in workflow_definition:
+ return None
+ return deserialize_policy(workflow_definition[POLICY_KEY])
+
+
+def carried_policy(workflow_definition: object) -> object | None:
+ """The stored policy value, verbatim. Never validates: a save carries policy forward untouched,
+ and a save that could repair a corrupt policy could also alter a sound one."""
+ if not isinstance(workflow_definition, dict):
+ return None
+ return workflow_definition.get(POLICY_KEY)
+
+
+def with_policy(workflow_definition: dict[str, Any], stored_policy: object) -> dict[str, Any]:
+ """A copy of the definition carrying exactly `stored_policy`, dropping any key the caller sent."""
+ definition = {key: value for key, value in workflow_definition.items() if key != POLICY_KEY}
+ if stored_policy is not None:
+ definition[POLICY_KEY] = stored_policy
+ return definition
+
+
+def stored_policy_version(workflow_definition: object) -> int:
+ """Best-effort read of the persisted policy version; 0 when absent or unreadable.
+
+ Never raises: replacing an unreadable policy is the repair path, and it must still advance the
+ counter rather than reissue a version some run may already have bound.
+ """
+ raw = carried_policy(workflow_definition)
+ if not isinstance(raw, dict):
+ return 0
+ version = raw.get("version")
+ if isinstance(version, bool) or not isinstance(version, int) or version < 0:
+ return 0
+ return version
+
+
+def rejection_reasons(workflow: Workflow, *, run_with: str | None) -> tuple[EnrollmentRejection, ...]:
+ """Configurations an action-level firewall cannot cover, because the browser work happens inside
+ generated or operator-supplied code that never reaches an action sink."""
+ reasons: list[EnrollmentRejection] = []
+ if any(block.block_type == BlockType.CODE for block in get_all_blocks(workflow.workflow_definition.blocks)):
+ reasons.append(EnrollmentRejection.CODE_BLOCK_PRESENT)
+ # Either level selecting code is disqualifying: a single agent-mode run does not make a
+ # code-mode version enforceable, and a run-level override can pick code on an agent version.
+ if workflow.run_with == "code" or run_with == "code":
+ reasons.append(EnrollmentRejection.CODE_EXECUTION_SELECTED)
+ if workflow.adaptive_caching:
+ reasons.append(EnrollmentRejection.ADAPTIVE_CACHING_ENABLED)
+ if workflow.generate_script_on_terminal:
+ reasons.append(EnrollmentRejection.SCRIPT_GENERATION_ENABLED)
+ return tuple(reasons)
+
+
+def bind_policy_to_context(
+ policy: BrowserActionPolicy | None,
+ workflow: Workflow,
+ *,
+ run_with: str | None,
+) -> None:
+ """Bind the resolved workflow version's policy to the current run.
+
+ An unenrolled version clears the slot rather than leaving it alone, so a grant cannot survive
+ into a run, child workflow or reused context that did not earn it.
+ """
+ if policy is None:
+ context = skyvern_context.current()
+ if context is not None:
+ context.browser_action_policy = None
+ return
+
+ reasons = rejection_reasons(workflow, run_with=run_with)
+ if reasons:
+ raise BrowserActionPolicyNotEnforceable(reasons)
+ # ensure_context rather than a silent skip: with no context there is nothing to consume the
+ # policy, and an enrolled run must not proceed as though it had been bound.
+ skyvern_context.ensure_context().browser_action_policy = policy
diff --git a/skyvern/forge/sdk/workflow/service.py b/skyvern/forge/sdk/workflow/service.py
index ad99a1595..f239f5197 100644
--- a/skyvern/forge/sdk/workflow/service.py
+++ b/skyvern/forge/sdk/workflow/service.py
@@ -38,6 +38,7 @@ from skyvern.constants import GET_DOWNLOADED_FILES_TIMEOUT, SAVE_DOWNLOADED_FILE
from skyvern.exceptions import (
BlockedHost,
BlockNotFound,
+ BrowserActionPolicyNotEnforceable,
BrowserProfileNotFound,
BrowserSessionNotFound,
BrowserSessionNotRenewable,
@@ -59,6 +60,7 @@ from skyvern.forge.prompts import prompt_engine
from skyvern.forge.sdk.api.files import is_temp_working_dir
from skyvern.forge.sdk.artifact.models import Artifact, ArtifactType
from skyvern.forge.sdk.artifact.storage.base import _file_infos_from_download_artifacts
+from skyvern.forge.sdk.browser_action_policy import BrowserActionPolicy
from skyvern.forge.sdk.cache import extraction_cache
from skyvern.forge.sdk.cache.factory import CacheFactory
from skyvern.forge.sdk.core import skyvern_context
@@ -81,6 +83,7 @@ from skyvern.forge.sdk.schemas.tasks import Task, TaskStatus
from skyvern.forge.sdk.schemas.workflow_runs import WorkflowRunBlock, WorkflowRunTimeline, WorkflowRunTimelineType
from skyvern.forge.sdk.submission import shadow as submission_shadow
from skyvern.forge.sdk.trace import traced
+from skyvern.forge.sdk.workflow.browser_action_policy_enrollment import bind_policy_to_context, rejection_reasons
from skyvern.forge.sdk.workflow.browser_profile_key import (
build_browser_profile_key_digest,
build_workflow_browser_session_storage_key,
@@ -1718,6 +1721,19 @@ class WorkflowService:
log_context={"workflow_run_id": workflow_run.workflow_run_id},
)
+ # Bind the resolved version's browser action policy onto the run's own context.
+ # execute_workflow re-binds because a Temporal worker boots a fresh context; this
+ # binding covers the paths that drive the run in-process from here.
+ try:
+ await self.bind_browser_action_policy(workflow, run_with=workflow_request.run_with)
+ except BrowserActionPolicyNotEnforceable as e:
+ # The row already exists, so fail it rather than leave a run stuck in `created`.
+ await self.mark_workflow_run_as_failed(
+ workflow_run_id=workflow_run.workflow_run_id,
+ failure_reason=get_user_facing_exception_message(e),
+ )
+ raise
+
# Create all the workflow run parameters, AWSSecretParameter won't have workflow run parameters created.
all_workflow_parameters = await self.get_workflow_parameters(workflow_id=workflow.workflow_id)
try:
@@ -2963,6 +2979,33 @@ class WorkflowService:
)
return workflow_run
+ # Bind before anything can open a browser or a code worker. Re-bound here rather than
+ # inherited from setup: a Temporal worker boots a fresh context, and a run must always
+ # execute under the policy of the exact version stamped on it.
+ try:
+ await self.bind_browser_action_policy(workflow, run_with=workflow_run.run_with)
+ except BrowserActionPolicyNotEnforceable as e:
+ LOG.warning(
+ "Workflow version cannot run under its browser action policy",
+ workflow_run_id=workflow_run_id,
+ organization_id=organization_id,
+ workflow_permanent_id=workflow.workflow_permanent_id,
+ policy_rejection_reasons=list(e.reasons),
+ )
+ workflow_run = await self.mark_workflow_run_as_failed(
+ workflow_run_id=workflow_run_id,
+ failure_reason=get_user_facing_exception_message(e),
+ )
+ await self.clean_up_workflow(
+ workflow=workflow,
+ workflow_run=workflow_run,
+ api_key=api_key,
+ browser_session_id=browser_session_id,
+ close_browser_on_completion=close_browser_on_completion,
+ need_call_webhook=need_call_webhook,
+ )
+ return workflow_run
+
# Set workflow run status to running, create workflow run parameters
workflow_run = await self.mark_workflow_run_as_running(workflow_run_id=workflow_run_id)
# Short-circuit when the conditional transition was refused (cron beat us
@@ -10155,6 +10198,64 @@ class WorkflowService:
workflow_permanent_id=workflow.workflow_permanent_id,
)
+ async def bind_browser_action_policy(
+ self,
+ workflow: Workflow,
+ *,
+ run_with: str | None,
+ ) -> BrowserActionPolicy | None:
+ """Bind the exact resolved workflow version's policy to the current run.
+
+ Every path that executes a workflow version calls this before the run's browser can exist.
+ Raises BrowserActionPolicyNotEnforceable when the version is enrolled but configured in a
+ way the action-level firewall cannot cover.
+ """
+ policy = await app.DATABASE.workflows.get_browser_action_policy(
+ workflow_id=workflow.workflow_id,
+ organization_id=workflow.organization_id,
+ )
+ bind_policy_to_context(policy, workflow, run_with=run_with)
+ return policy
+
+ async def replace_browser_action_policy(
+ self,
+ *,
+ workflow_permanent_id: str,
+ organization_id: str,
+ allowed_origin_urls: list[str] | None,
+ ) -> BrowserActionPolicy | None:
+ """Control-plane enrollment: replace (or, with None, clear) the latest version's policy.
+
+ The only writer of policy. Enrolling a version the firewall cannot cover is refused here so
+ an operator learns at enrollment time rather than when the next run fails.
+ """
+ workflow = await self.get_workflow_by_permanent_id(
+ workflow_permanent_id=workflow_permanent_id,
+ organization_id=organization_id,
+ )
+ if workflow is None:
+ raise WorkflowNotFound(workflow_permanent_id=workflow_permanent_id)
+ if allowed_origin_urls is not None:
+ reasons = rejection_reasons(workflow, run_with=None)
+ if reasons:
+ raise BrowserActionPolicyNotEnforceable(reasons)
+
+ policy = await app.DATABASE.workflows.set_browser_action_policy(
+ workflow_id=workflow.workflow_id,
+ organization_id=organization_id,
+ allowed_origin_urls=allowed_origin_urls,
+ )
+ LOG.info(
+ "Browser action policy replaced",
+ workflow_permanent_id=workflow_permanent_id,
+ workflow_id=workflow.workflow_id,
+ workflow_version=workflow.version,
+ organization_id=organization_id,
+ policy_version=policy.version if policy else None,
+ allowed_origin_count=len(policy.allowed_origins) if policy else 0,
+ )
+ return policy
+
async def should_run_script(
self,
workflow: Workflow,
@@ -10168,6 +10269,12 @@ class WorkflowService:
an upgraded run has no matching script for a non-eligible workflow
and so degrades cleanly to agent per block.
"""
+ context = skyvern_context.current()
+ if context and context.browser_action_policy is not None:
+ # An enrolled run must not reach script execution: generated code drives the browser
+ # without passing an action sink, so the flag-gated upgrade below would silently
+ # produce a run the firewall cannot see.
+ return False
if workflow_run.run_with is not None:
intended_code = workflow_run.run_with == "code"
else:
diff --git a/skyvern/webeye/actions/actions.py b/skyvern/webeye/actions/actions.py
index 41383a9a8..5c9c2d6f8 100644
--- a/skyvern/webeye/actions/actions.py
+++ b/skyvern/webeye/actions/actions.py
@@ -166,6 +166,16 @@ class Action(BaseModel):
# batched action would clobber an in-action combobox selection.
stop_batch_after_dropdown_select: bool = Field(default=False, exclude=True)
+ # Transient (never serialized): the observation epoch this action was planned under (SKY-12874).
+ # It must not reach the database — an epoch is run-local, so a value read back from a stored row
+ # could collide with a live run's counter and make a stale action look freshly observed.
+ observation_epoch: int | None = Field(default=None, exclude=True)
+
+ # Transient (never serialized): digest of the element hashes the observation covered. The epoch
+ # above is positional and a stray integer can match it by luck; this cannot, so provenance is
+ # bound to what was actually seen rather than to a counter's value.
+ observation_digest: str | None = Field(default=None, exclude=True)
+
created_at: datetime | None = None
modified_at: datetime | None = None
created_by: str | None = None
diff --git a/skyvern/webeye/actions/handler.py b/skyvern/webeye/actions/handler.py
index 4f95948c0..6329646b4 100644
--- a/skyvern/webeye/actions/handler.py
+++ b/skyvern/webeye/actions/handler.py
@@ -87,6 +87,7 @@ from skyvern.forge.sdk.api.files import (
from skyvern.forge.sdk.api.llm.api_handler_factory import LLMAPIHandlerFactory, LLMCallerManager
from skyvern.forge.sdk.api.llm.exceptions import LLMProviderError
from skyvern.forge.sdk.api.llm.schema_validator import validate_and_fill_extraction_result
+from skyvern.forge.sdk.browser_action_preflight import preflight_action, preflight_derived_action
from skyvern.forge.sdk.cache import extraction_cache, extraction_shadow
from skyvern.forge.sdk.copilot.block_goal_wrapping import unwrap_goal_fields
from skyvern.forge.sdk.core import skyvern_context
@@ -2352,6 +2353,9 @@ class ActionHandler:
_action_span.set_attribute("step_order", step.order)
if getattr(action, "element_id", None):
_action_span.set_attribute("element_id", action.element_id)
+ # Re-evaluated here, against the page as it is now, before anything downstream looks up a
+ # browser, chooses the download-capturing path or persists a row.
+ preflight_action(action, page, site="handle_action")
browser_state = app.BROWSER_MANAGER.get_for_task(task.task_id, workflow_run_id=task.workflow_run_id)
# TODO: maybe support all action types in the future(?)
trigger_download_action = (
@@ -3288,6 +3292,7 @@ async def handle_click_action(
element_id=action.element_id,
file_url=action.file_url,
)
+ preflight_derived_action(upload_file_action, page, parent=action, site="click_to_upload")
return await handle_upload_file_action(upload_file_action, page, scraped_page, task, step)
else:
incremental_scraped: IncrementalScrapePage | None = None
@@ -4634,6 +4639,8 @@ async def handle_upload_file_action(
LOG.info("Taking UploadFileAction. Found non file input tag", action=action)
# treat it as a click action
action.is_upload_file_tag = False
+ # The action itself changed shape; re-project it before it takes the click path.
+ preflight_action(action, page, site="upload_to_click")
return await chain_click(
task,
scraped_page,
@@ -4753,6 +4760,7 @@ async def handle_select_option_action(
return [ActionFailure(InteractWithDisabledElement(skyvern_element.get_id()))]
click_action = ClickAction(element_id=action.element_id)
action.set_has_mini_agent()
+ preflight_derived_action(click_action, page, parent=action, site="select_option_to_click")
return await chain_click(task, scraped_page, page, click_action, skyvern_element)
if not await skyvern_element.is_selectable():
@@ -4895,6 +4903,7 @@ async def handle_select_option_action(
)
check_action = CheckboxAction(element_id=action.element_id, is_checked=True)
action.set_has_mini_agent()
+ preflight_derived_action(check_action, page, parent=action, site="select_option_to_checkbox")
return await handle_checkbox_action(check_action, page, scraped_page, task, step)
if await skyvern_element.is_radio():
@@ -4904,6 +4913,7 @@ async def handle_select_option_action(
)
click_action = ClickAction(element_id=action.element_id)
action.set_has_mini_agent()
+ preflight_derived_action(click_action, page, parent=action, site="select_option_to_click")
return await chain_click(task, scraped_page, page, click_action, skyvern_element)
# FIXME: maybe there's a case where <input type="button"> could trigger dropdown menu?
@@ -4914,6 +4924,7 @@ async def handle_select_option_action(
)
click_action = ClickAction(element_id=action.element_id)
action.set_has_mini_agent()
+ preflight_derived_action(click_action, page, parent=action, site="select_option_to_click")
return await chain_click(task, scraped_page, page, click_action, skyvern_element)
LOG.info(
@@ -5276,6 +5287,9 @@ async def handle_complete_action(
step_order=action.step_order,
action_order=action.action_order,
)
+ # Before the terminate runs, not after the rewrite below: once `action_type` is reassigned
+ # in place the original projection is gone, and it is the TerminateAction that executes.
+ preflight_derived_action(terminate_action, page, parent=action, site="complete_to_terminate")
results = await handle_terminate_action(terminate_action, page, scraped_page, task, step)
action.action_type = ActionType.TERMINATE
action.reasoning = terminate_action.reasoning
diff --git a/skyvern/webeye/scraper/scraper.py b/skyvern/webeye/scraper/scraper.py
index 0cde4b934..2d8897d2c 100644
--- a/skyvern/webeye/scraper/scraper.py
+++ b/skyvern/webeye/scraper/scraper.py
@@ -21,6 +21,7 @@ from skyvern.exceptions import (
)
from skyvern.experimentation.wait_utils import empty_page_retry_wait
from skyvern.forge.sdk.api.crypto import calculate_sha256
+from skyvern.forge.sdk.browser_action_preflight import advance_observation_epoch
from skyvern.forge.sdk.core import skyvern_context
from skyvern.forge.sdk.settings_manager import SettingsManager
from skyvern.forge.sdk.trace import apply_context_attrs, traced
@@ -569,6 +570,8 @@ async def scrape_web_unsafe(
empty_page_retry=empty_page_retry,
)
+ advance_observation_epoch(page, main_frame_url=page.main_frame.url, element_hashes=id_to_element_hash.values())
+
return ScrapedPage(
elements=elements,
id_to_css_dict=id_to_css_dict,
diff --git a/tests/unit/forge/sdk/db/test_workflow_browser_action_policy.py b/tests/unit/forge/sdk/db/test_workflow_browser_action_policy.py
new file mode 100644
index 000000000..397367833
--- /dev/null
+++ b/tests/unit/forge/sdk/db/test_workflow_browser_action_policy.py
@@ -0,0 +1,388 @@
+"""Policy persistence rules on the workflows repository (SKY-12873).
+
+Only the control-plane setter may write policy; every ordinary definition write carries the stored
+value forward unchanged.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pytest
+import pytest_asyncio
+from sqlalchemy import select, update
+
+from scripts.backfill_encrypt_file_block_secrets import encrypt_file_block_secrets
+from skyvern.forge.sdk.browser_action_policy import declare_policy
+from skyvern.forge.sdk.db.agent_db import AgentDB
+from skyvern.forge.sdk.db.exceptions import NotFoundError
+from skyvern.forge.sdk.db.models import WorkflowModel
+from skyvern.forge.sdk.workflow.browser_action_policy_enrollment import POLICY_KEY, serialize_policy
+from skyvern.forge.sdk.workflow.models.workflow import WorkflowDefinition
+
+EMPTY_DEFINITION: dict[str, Any] = {"parameters": [], "blocks": []}
+
+
+@pytest_asyncio.fixture
+async def org_id(agent_db: AgentDB) -> str:
+ org = await agent_db.organizations.create_organization(
+ organization_name="Policy Org",
+ domain="policy.test",
+ )
+ return org.organization_id
+
+
+async def _stored_definition(agent_db: AgentDB, workflow_id: str) -> dict[str, Any]:
+ """Read the raw JSON column directly — the policy is deliberately invisible to the Workflow
+ model, and the repository exposes no unscoped reader for it."""
+ async with agent_db.workflows.Session() as session:
+ stored = await session.scalar(
+ select(WorkflowModel.workflow_definition).where(WorkflowModel.workflow_id == workflow_id)
+ )
+ assert isinstance(stored, dict)
+ return stored
+
+
+async def _enroll(agent_db: AgentDB, workflow_id: str, org_id: str, *origins: str) -> Any:
+ return await agent_db.workflows.set_browser_action_policy(
+ workflow_id=workflow_id,
+ organization_id=org_id,
+ allowed_origin_urls=list(origins) or ["https://example.com"],
+ )
+
+
+async def test_a_new_workflow_starts_unenrolled(agent_db: AgentDB, org_id: str) -> None:
+ workflow = await agent_db.workflows.create_workflow(
+ title="fresh", workflow_definition=EMPTY_DEFINITION, organization_id=org_id
+ )
+ assert POLICY_KEY not in await _stored_definition(agent_db, workflow.workflow_id)
+ assert (
+ await agent_db.workflows.get_browser_action_policy(workflow_id=workflow.workflow_id, organization_id=org_id)
+ is None
+ )
+
+
+async def test_control_plane_enrollment_round_trips(agent_db: AgentDB, org_id: str) -> None:
+ workflow = await agent_db.workflows.create_workflow(
+ title="enrolled", workflow_definition=EMPTY_DEFINITION, organization_id=org_id
+ )
+ written = await _enroll(agent_db, workflow.workflow_id, org_id, "https://example.com", "https://app.example.com")
+
+ read_back = await agent_db.workflows.get_browser_action_policy(
+ workflow_id=workflow.workflow_id, organization_id=org_id
+ )
+ assert read_back == written
+ assert read_back is not None
+ assert read_back.owner_id == org_id
+ assert {origin.canonical for origin in read_back.allowed_origins} == {
+ "https://example.com",
+ "https://app.example.com",
+ }
+
+
+async def test_each_replacement_advances_the_pinned_policy_version(agent_db: AgentDB, org_id: str) -> None:
+ workflow = await agent_db.workflows.create_workflow(
+ title="versions", workflow_definition=EMPTY_DEFINITION, organization_id=org_id
+ )
+ first = await _enroll(agent_db, workflow.workflow_id, org_id, "https://example.com")
+ second = await _enroll(agent_db, workflow.workflow_id, org_id, "https://other.example.com")
+ assert first is not None and second is not None
+ assert (first.version, second.version) == (1, 2)
+
+
+async def test_clearing_removes_the_policy_and_restarts_the_version(agent_db: AgentDB, org_id: str) -> None:
+ workflow = await agent_db.workflows.create_workflow(
+ title="cleared", workflow_definition=EMPTY_DEFINITION, organization_id=org_id
+ )
+ await _enroll(agent_db, workflow.workflow_id, org_id, "https://example.com")
+
+ cleared = await agent_db.workflows.set_browser_action_policy(
+ workflow_id=workflow.workflow_id, organization_id=org_id, allowed_origin_urls=None
+ )
+ assert cleared is None
+ assert POLICY_KEY not in await _stored_definition(agent_db, workflow.workflow_id)
+
+ # A clear de-enrolls the version outright, so the next enrollment is a new regime from v1.
+ reenrolled = await _enroll(agent_db, workflow.workflow_id, org_id, "https://example.com")
+ assert reenrolled is not None and reenrolled.version == 1
+
+
+async def test_enrollment_is_scoped_to_the_owning_organization(agent_db: AgentDB, org_id: str) -> None:
+ other = await agent_db.organizations.create_organization(organization_name="Other", domain="other.test")
+ workflow = await agent_db.workflows.create_workflow(
+ title="scoped", workflow_definition=EMPTY_DEFINITION, organization_id=org_id
+ )
+ with pytest.raises(NotFoundError):
+ await agent_db.workflows.set_browser_action_policy(
+ workflow_id=workflow.workflow_id,
+ organization_id=other.organization_id,
+ allowed_origin_urls=["https://example.com"],
+ )
+ assert POLICY_KEY not in await _stored_definition(agent_db, workflow.workflow_id)
+
+
+async def test_an_undeclarable_origin_is_refused_at_enrollment(agent_db: AgentDB, org_id: str) -> None:
+ workflow = await agent_db.workflows.create_workflow(
+ title="bad-origin", workflow_definition=EMPTY_DEFINITION, organization_id=org_id
+ )
+ with pytest.raises(ValueError):
+ await _enroll(agent_db, workflow.workflow_id, org_id, "file:///etc/passwd")
+ assert POLICY_KEY not in await _stored_definition(agent_db, workflow.workflow_id)
+
+
+async def test_reading_a_corrupt_stored_policy_raises(agent_db: AgentDB, org_id: str) -> None:
+ # Written past the repository — no supported write path can produce this, but a hand-edited or
+ # partially-migrated row must fail the run rather than resolve to "unenrolled".
+ workflow = await agent_db.workflows.create_workflow(
+ title="corrupt", workflow_definition=EMPTY_DEFINITION, organization_id=org_id
+ )
+ async with agent_db.workflows.Session() as session:
+ await session.execute(
+ update(WorkflowModel)
+ .where(WorkflowModel.workflow_id == workflow.workflow_id)
+ .values(workflow_definition={**EMPTY_DEFINITION, POLICY_KEY: {"owner_id": org_id}})
+ )
+ await session.commit()
+
+ with pytest.raises(ValueError):
+ await agent_db.workflows.get_browser_action_policy(workflow_id=workflow.workflow_id, organization_id=org_id)
+
+
+async def test_an_ordinary_create_cannot_add_policy(agent_db: AgentDB, org_id: str) -> None:
+ # A caller that smuggles the key into the definition dict must not get an enrolled workflow.
+ workflow = await agent_db.workflows.create_workflow(
+ title="smuggled",
+ workflow_definition={
+ **EMPTY_DEFINITION,
+ POLICY_KEY: serialize_policy(declare_policy(owner_id=org_id, origin_urls=["https://evil.example.com"])),
+ },
+ organization_id=org_id,
+ )
+ assert POLICY_KEY not in await _stored_definition(agent_db, workflow.workflow_id)
+
+
+async def test_a_new_version_carries_the_policy_forward(agent_db: AgentDB, org_id: str) -> None:
+ first = await agent_db.workflows.create_workflow(
+ title="v1", workflow_definition=EMPTY_DEFINITION, organization_id=org_id
+ )
+ policy = await _enroll(agent_db, first.workflow_id, org_id, "https://example.com")
+
+ second = await agent_db.workflows.create_workflow(
+ title="v2",
+ workflow_definition=EMPTY_DEFINITION,
+ organization_id=org_id,
+ workflow_permanent_id=first.workflow_permanent_id,
+ version=first.version + 1,
+ )
+ assert (
+ await agent_db.workflows.get_browser_action_policy(workflow_id=second.workflow_id, organization_id=org_id)
+ == policy
+ )
+
+
+async def test_a_new_version_cannot_widen_the_carried_policy(agent_db: AgentDB, org_id: str) -> None:
+ first = await agent_db.workflows.create_workflow(
+ title="v1", workflow_definition=EMPTY_DEFINITION, organization_id=org_id
+ )
+ await _enroll(agent_db, first.workflow_id, org_id, "https://example.com")
+
+ widened = serialize_policy(
+ declare_policy(owner_id=org_id, origin_urls=["https://example.com", "https://evil.example.com"], version=99)
+ )
+ second = await agent_db.workflows.create_workflow(
+ title="v2",
+ workflow_definition={**EMPTY_DEFINITION, POLICY_KEY: widened},
+ organization_id=org_id,
+ workflow_permanent_id=first.workflow_permanent_id,
+ version=first.version + 1,
+ )
+ carried = await agent_db.workflows.get_browser_action_policy(workflow_id=second.workflow_id, organization_id=org_id)
+ assert carried is not None
+ assert {origin.canonical for origin in carried.allowed_origins} == {"https://example.com"}
+ assert carried.version == 1
+
+
+async def test_a_new_version_of_an_unenrolled_workflow_stays_unenrolled(agent_db: AgentDB, org_id: str) -> None:
+ first = await agent_db.workflows.create_workflow(
+ title="v1", workflow_definition=EMPTY_DEFINITION, organization_id=org_id
+ )
+ second = await agent_db.workflows.create_workflow(
+ title="v2",
+ workflow_definition=EMPTY_DEFINITION,
+ organization_id=org_id,
+ workflow_permanent_id=first.workflow_permanent_id,
+ version=first.version + 1,
+ )
+ assert POLICY_KEY not in await _stored_definition(agent_db, second.workflow_id)
+
+
+async def test_updating_the_definition_preserves_the_policy(agent_db: AgentDB, org_id: str) -> None:
+ workflow = await agent_db.workflows.create_workflow(
+ title="edited", workflow_definition=EMPTY_DEFINITION, organization_id=org_id
+ )
+ policy = await _enroll(agent_db, workflow.workflow_id, org_id, "https://example.com")
+
+ await agent_db.workflows.update_workflow(
+ workflow_id=workflow.workflow_id,
+ organization_id=org_id,
+ workflow_definition={"parameters": [], "blocks": [], "workflow_system_prompt": "edited"},
+ )
+ stored = await _stored_definition(agent_db, workflow.workflow_id)
+ assert stored["workflow_system_prompt"] == "edited"
+ assert (
+ await agent_db.workflows.get_browser_action_policy(workflow_id=workflow.workflow_id, organization_id=org_id)
+ == policy
+ )
+
+
+async def test_updating_the_definition_cannot_clear_the_policy(agent_db: AgentDB, org_id: str) -> None:
+ workflow = await agent_db.workflows.create_workflow(
+ title="cleared-by-edit", workflow_definition=EMPTY_DEFINITION, organization_id=org_id
+ )
+ policy = await _enroll(agent_db, workflow.workflow_id, org_id, "https://example.com")
+
+ await agent_db.workflows.update_workflow(
+ workflow_id=workflow.workflow_id, organization_id=org_id, workflow_definition=EMPTY_DEFINITION
+ )
+ assert (
+ await agent_db.workflows.get_browser_action_policy(workflow_id=workflow.workflow_id, organization_id=org_id)
+ == policy
+ )
+
+
+async def test_updating_the_definition_cannot_add_policy(agent_db: AgentDB, org_id: str) -> None:
+ workflow = await agent_db.workflows.create_workflow(
+ title="added-by-edit", workflow_definition=EMPTY_DEFINITION, organization_id=org_id
+ )
+ smuggled = serialize_policy(declare_policy(owner_id=org_id, origin_urls=["https://evil.example.com"]))
+ await agent_db.workflows.update_workflow(
+ workflow_id=workflow.workflow_id,
+ organization_id=org_id,
+ workflow_definition={**EMPTY_DEFINITION, POLICY_KEY: smuggled},
+ )
+ assert POLICY_KEY not in await _stored_definition(agent_db, workflow.workflow_id)
+
+
+async def test_the_reconciling_definition_write_preserves_the_policy(agent_db: AgentDB, org_id: str) -> None:
+ workflow = await agent_db.workflows.create_workflow(
+ title="reconciled", workflow_definition=EMPTY_DEFINITION, organization_id=org_id
+ )
+ policy = await _enroll(agent_db, workflow.workflow_id, org_id, "https://example.com")
+
+ await agent_db.workflows.update_workflow_and_reconcile_definition_params(
+ workflow_id=workflow.workflow_id,
+ organization_id=org_id,
+ workflow_definition=WorkflowDefinition(parameters=[], blocks=[], workflow_system_prompt="reconciled"),
+ )
+ stored = await _stored_definition(agent_db, workflow.workflow_id)
+ assert stored["workflow_system_prompt"] == "reconciled"
+ assert (
+ await agent_db.workflows.get_browser_action_policy(workflow_id=workflow.workflow_id, organization_id=org_id)
+ == policy
+ )
+
+
+async def test_the_policy_is_invisible_to_the_workflow_model(agent_db: AgentDB, org_id: str) -> None:
+ # Keeping the key out of WorkflowDefinition is what keeps it off the generated public client.
+ workflow = await agent_db.workflows.create_workflow(
+ title="hidden", workflow_definition=EMPTY_DEFINITION, organization_id=org_id
+ )
+ await _enroll(agent_db, workflow.workflow_id, org_id, "https://example.com")
+
+ reloaded = await agent_db.workflows.get_workflow(workflow_id=workflow.workflow_id, organization_id=org_id)
+ assert reloaded is not None
+ assert POLICY_KEY not in reloaded.workflow_definition.model_dump(mode="json")
+ assert POLICY_KEY not in reloaded.model_dump(mode="json")
+
+
+async def test_a_definition_round_trip_through_the_pydantic_model_cannot_erase_the_policy(
+ agent_db: AgentDB, org_id: str
+) -> None:
+ """The reserved key is invisible to WorkflowDefinition, which is what keeps it off the public
+ client — and would silently erase it on any read-modify-write if the repository did not restore
+ it. This is the erasure half of "cannot add, clear or widen"."""
+ workflow = await agent_db.workflows.create_workflow(
+ title="round-trip", workflow_definition=EMPTY_DEFINITION, organization_id=org_id
+ )
+ policy = await _enroll(agent_db, workflow.workflow_id, org_id, "https://example.com")
+
+ reloaded = await agent_db.workflows.get_workflow(workflow_id=workflow.workflow_id, organization_id=org_id)
+ assert reloaded is not None
+ # The model genuinely drops the key — this is the erasure the repository has to undo.
+ round_tripped = WorkflowDefinition.model_validate(reloaded.workflow_definition.model_dump(mode="json"))
+ assert POLICY_KEY not in round_tripped.model_dump(mode="json")
+
+ await agent_db.workflows.update_workflow_and_reconcile_definition_params(
+ workflow_id=workflow.workflow_id, organization_id=org_id, workflow_definition=round_tripped
+ )
+ assert (
+ await agent_db.workflows.get_browser_action_policy(workflow_id=workflow.workflow_id, organization_id=org_id)
+ == policy
+ )
+
+
+async def test_the_secret_backfill_transform_preserves_the_policy(agent_db: AgentDB, org_id: str) -> None:
+ """The one definition writer outside this repository. It mutates a deepcopy of the raw dict
+ rather than rebuilding it, so the reserved key survives; this pins that."""
+ stored = serialize_policy(declare_policy(owner_id=org_id, origin_urls=["https://example.com"]))
+ definition = {
+ "parameters": [],
+ "blocks": [{"block_type": "file_upload", "label": "upload", "path": "/tmp/x"}],
+ POLICY_KEY: stored,
+ }
+ transformed, _ = await encrypt_file_block_secrets(definition, org_id)
+ assert transformed[POLICY_KEY] == stored
+
+
+async def test_a_new_version_inherits_from_the_most_recent_version_even_if_it_was_deleted(
+ agent_db: AgentDB, org_id: str
+) -> None:
+ """Carry-forward reads the highest version including soft-deleted rows, on purpose.
+
+ `create_workflow_from_request` numbers the new version off the same row set
+ (`filter_deleted=False`), so skipping deleted rows here would let deleting the enrolled version
+ silently unenroll the next save — a clear, which no ordinary save is allowed to perform.
+ """
+ first = await agent_db.workflows.create_workflow(
+ title="v1", workflow_definition=EMPTY_DEFINITION, organization_id=org_id
+ )
+ second = await agent_db.workflows.create_workflow(
+ title="v2",
+ workflow_definition=EMPTY_DEFINITION,
+ organization_id=org_id,
+ workflow_permanent_id=first.workflow_permanent_id,
+ version=first.version + 1,
+ )
+ policy = await _enroll(agent_db, second.workflow_id, org_id, "https://example.com")
+ await agent_db.workflows.soft_delete_workflow_by_id(workflow_id=second.workflow_id, organization_id=org_id)
+
+ third = await agent_db.workflows.create_workflow(
+ title="v3",
+ workflow_definition=EMPTY_DEFINITION,
+ organization_id=org_id,
+ workflow_permanent_id=first.workflow_permanent_id,
+ version=second.version + 1,
+ )
+ assert (
+ await agent_db.workflows.get_browser_action_policy(workflow_id=third.workflow_id, organization_id=org_id)
+ == policy
+ )
diff --git a/tests/unit/test_browser_action_policy.py b/tests/unit/test_browser_action_policy.py
new file mode 100644
index 000000000..88b2971f6
--- /dev/null
+++ b/tests/unit/test_browser_action_policy.py
@@ -0,0 +1,900 @@
+import ast
+import dataclasses
+from enum import StrEnum
+from pathlib import Path
+
+import pytest
+from pydantic import ValidationError
+
+from skyvern.config import Settings
+from skyvern.forge.sdk.browser_action_policy import (
+ REASON_PRECEDENCE,
+ UNWIRED_AUTHORITY,
+ ActionClass,
+ ActionProjection,
+ ActionTarget,
+ AuthorityState,
+ BrowserActionPolicy,
+ BrowserActionRequest,
+ BrowserOrigin,
+ ObservationVerdict,
+ PageObservation,
+ PolicyDecision,
+ PolicyOutcome,
+ PolicyReason,
+ ProtectedReference,
+ ProtectedReferenceKind,
+ RuntimeOriginAuthority,
+ canonicalize_origin,
+ classify_action_type,
+ coerce_verdict,
+ decide_browser_action,
+ declare_origin,
+ declare_policy,
+)
+from skyvern.webeye.actions.action_types import ActionType
+from skyvern.webeye.actions.actions import (
+ Action,
+ CheckboxAction,
+ ClickAction,
+ ClosePageAction,
+ CompleteAction,
+ DownloadFileAction,
+ DragAction,
+ ExecuteJsAction,
+ ExtractAction,
+ GoBackAction,
+ GoForwardAction,
+ GotoUrlAction,
+ HoverAction,
+ InputTextAction,
+ KeypressAction,
+ LeftMouseAction,
+ MoveAction,
+ NewTabAction,
+ NullAction,
+ ReloadPageAction,
+ ScrollAction,
+ SelectOption,
+ SelectOptionAction,
+ SolveCaptchaAction,
+ SwitchTabAction,
+ TerminateAction,
+ UploadFileAction,
+ VerificationCodeAction,
+ WaitAction,
+)
+
+OWNER = "wr_12872"
+HOME = "https://example.com/start"
+HOME_ORIGIN = declare_origin(HOME)
+POLICY = declare_policy(owner_id=OWNER, origin_urls=[HOME])
+EPOCH = 7
+# The runtime authority the existing gates are exercised against: established, and wide enough that
+# it never narrows the ceiling. Tests about authority itself pass their own.
+FULL_AUTHORITY = RuntimeOriginAuthority(state=AuthorityState.ESTABLISHED, origins=POLICY.allowed_origins)
+
+# Every concrete action model at its minimum valid construction, keyed by discriminator.
+CONCRETE_ACTIONS: dict[ActionType, Action] = {
+ ActionType.CLICK: ClickAction(element_id="1"),
+ ActionType.INPUT_TEXT: InputTextAction(element_id="1", text="hello"),
+ ActionType.UPLOAD_FILE: UploadFileAction(element_id="1", file_url="https://example.com/f.pdf"),
+ ActionType.DOWNLOAD_FILE: DownloadFileAction(file_name="f.pdf"),
+ ActionType.SELECT_OPTION: SelectOptionAction(element_id="1", option=SelectOption(label="a")),
+ ActionType.CHECKBOX: CheckboxAction(element_id="1", is_checked=True),
+ ActionType.WAIT: WaitAction(),
+ ActionType.HOVER: HoverAction(element_id="1"),
+ ActionType.NULL_ACTION: NullAction(),
+ ActionType.SOLVE_CAPTCHA: SolveCaptchaAction(),
+ ActionType.TERMINATE: TerminateAction(),
+ ActionType.COMPLETE: CompleteAction(),
+ ActionType.RELOAD_PAGE: ReloadPageAction(),
+ ActionType.CLOSE_PAGE: ClosePageAction(),
+ ActionType.NEW_TAB: NewTabAction(url=HOME),
+ ActionType.SWITCH_TAB: SwitchTabAction(tab_index=0),
+ ActionType.EXTRACT: ExtractAction(),
+ ActionType.VERIFICATION_CODE: VerificationCodeAction(verification_code="123456"),
+ ActionType.GOTO_URL: GotoUrlAction(url=HOME),
+ ActionType.GO_BACK: GoBackAction(),
+ ActionType.GO_FORWARD: GoForwardAction(),
+ ActionType.SCROLL: ScrollAction(),
+ ActionType.KEYPRESS: KeypressAction(keys=["Enter"]),
+ ActionType.MOVE: MoveAction(),
+ ActionType.DRAG: DragAction(),
+ ActionType.LEFT_MOUSE: LeftMouseAction(direction="down"),
+ ActionType.EXECUTE_JS: ExecuteJsAction(js_code="1"),
+}
+
+
+def build_request(
+ action: Action,
+ *,
+ policy: BrowserActionPolicy | None = POLICY,
+ page_url: str = HOME,
+ evidence_epoch: int | None = EPOCH,
+ request_epoch: int = EPOCH,
+ verdict: ObservationVerdict = ObservationVerdict.NO_MATCH,
+ protected_references: tuple[ProtectedReference, ...] = (),
+ evidence: PageObservation | None = None,
+ omit_evidence: bool = False,
+ authority: RuntimeOriginAuthority = FULL_AUTHORITY,
+) -> BrowserActionRequest:
+ if not omit_evidence and evidence is None:
+ evidence = PageObservation(
+ page_url=page_url,
+ observation_epoch=EPOCH if evidence_epoch is None else evidence_epoch,
+ verdict=verdict,
+ )
+ return BrowserActionRequest(
+ policy=policy,
+ projection=project_for(action),
+ authority=authority,
+ evidence=None if omit_evidence else evidence,
+ request_epoch=request_epoch,
+ protected_references=protected_references,
+ )
+
+
+def project_for(action: Action) -> ActionProjection:
+ from skyvern.forge.sdk.browser_action_policy import project_action
+
+ return project_action(action)
+
+
+def secret_ref(owner_id: str = OWNER) -> ProtectedReference:
+ return ProtectedReference(
+ kind=ProtectedReferenceKind.SECRET,
+ reference_id="ref_1",
+ owner_id=owner_id,
+ )
+
+
+def file_ref(owner_id: str = OWNER) -> ProtectedReference:
+ return ProtectedReference(
+ kind=ProtectedReferenceKind.FILE,
+ reference_id="ref_2",
+ owner_id=owner_id,
+ )
+
+
+def code_ref(owner_id: str = OWNER) -> ProtectedReference:
+ return ProtectedReference(
+ kind=ProtectedReferenceKind.VERIFICATION_CODE,
+ reference_id="ref_3",
+ owner_id=owner_id,
+ )
+
+
+def refs_for(action: Action) -> tuple[ProtectedReference, ...]:
+ projection = project_for(action)
+ supplied = {
+ ProtectedReferenceKind.SECRET: secret_ref(),
+ ProtectedReferenceKind.FILE: file_ref(),
+ ProtectedReferenceKind.VERIFICATION_CODE: code_ref(),
+ }
+ return tuple(supplied[kind] for kind in sorted(projection.required_references))
+
+
+class TestObservationVerdictContract:
+ def test_member_values_are_pinned_literal_strings(self) -> None:
+ # Pins THIS enum's wire values, which is the half of the contract this package controls.
+ # It cannot observe cloud/prompt_security.DetectionOutcome — the OSS boundary forbids
+ # importing it — so the two-sided cross-check belongs in tests/cloud/ once that lands.
+ assert ObservationVerdict.NO_MATCH.value == "no_match"
+ assert ObservationVerdict.SUSPICIOUS.value == "suspicious"
+ assert ObservationVerdict.UNKNOWN.value == "unknown"
+ assert [member.value for member in ObservationVerdict] == ["no_match", "suspicious", "unknown"]
+
+ def test_accepts_a_foreign_str_enum_by_value(self) -> None:
+ class ForeignDetectionOutcome(StrEnum):
+ NO_MATCH = "no_match"
+ SUSPICIOUS = "suspicious"
+ UNKNOWN = "unknown"
+
+ for foreign in ForeignDetectionOutcome:
+ assert coerce_verdict(foreign) is ObservationVerdict(foreign.value)
+
+ @pytest.mark.parametrize("value", [None, "", "clean", "NO_MATCH", 0, object(), ["no_match"]])
+ def test_unrecognized_verdict_fails_closed_to_unknown(self, value: object) -> None:
+ assert coerce_verdict(value) is ObservationVerdict.UNKNOWN
+
+
+class TestOriginCanonicalization:
+ @pytest.mark.parametrize(
+ ("url", "canonical"),
+ [
+ ("https://example.com", "https://example.com"),
+ ("https://example.com:443/path?q=1#f", "https://example.com"),
+ ("http://example.com:80/", "http://example.com"),
+ ("https://example.com:8443/", "https://example.com:8443"),
+ ("HTTPS://ExAmPlE.CoM/", "https://example.com"),
+ ("https://example.com./", "https://example.com"),
+ ("https://[2001:0db8:0000:0000:0000:0000:0000:0001]/", "https://[2001:db8::1]"),
+ ("https://192.168.1.1/", "https://192.168.1.1"),
+ ("https://xn--bcher-kva.example/", "https://xn--bcher-kva.example"),
+ ("ws://example.com/socket", "http://example.com"),
+ ("wss://example.com/socket", "https://example.com"),
+ ],
+ )
+ def test_canonicalizes_deterministically(self, url: str, canonical: str) -> None:
+ origin = canonicalize_origin(url)
+ assert origin is not None
+ assert origin.canonical == canonical
+ assert canonicalize_origin(url) == origin
+
+ @pytest.mark.parametrize(
+ "url",
+ [
+ None,
+ "",
+ " ",
+ " https://example.com",
+ "https://example.com ",
+ "https://user:[email protected]/",
+ "https://[email protected]/",
+ "https:\\\\example.com/",
+ "https://exa\tmple.com/",
+ "https://exa\nmple.com/",
+ "https://example.com\x7f/",
+ "file:///etc/passwd",
+ "javascript:alert(1)",
+ "data:text/html,x",
+ "about:blank",
+ "chrome://newtab/",
+ "ftp://example.com/",
+ "https:///path",
+ "https://%2e%2e/",
+ "not a url",
+ 123,
+ # Ambiguous dotted-decimal forms: ip_address rejects leading zeros (CVE-2021-29921),
+ # so silently IDNA-encoding them would mint an origin that never matches its own host.
+ "https://192.168.001.001/",
+ "https://0177.0.0.1/",
+ "https://1/",
+ ],
+ )
+ def test_runtime_extraction_fails_closed(self, url: object) -> None:
+ assert canonicalize_origin(url) is None
+
+ @pytest.mark.parametrize(
+ "url",
+ [
+ # stdlib .encode("idna") is IDNA2003 + nameprep; browsers use UTS-46 nontransitional.
+ # Nameprep folds ß to "ss" and ς to σ, so trusting it would authorize a host the browser
+ # never visits. Operators declare the A-label instead, which is what the browser uses.
+ "https://faß.de",
+ "https://σος.example",
+ "https://exa‌mple.com",
+ "https://bücher.example",
+ "https://example。com。",
+ "https://example。com",
+ # WHATWG parses a trailing numeric label as an IPv4 literal, so these reach a host that
+ # ipaddress refuses to canonicalize for us.
+ "https://0x7f000001",
+ "https://example.0x1",
+ "https://2130706433",
+ ],
+ )
+ def test_browser_divergent_hosts_are_rejected(self, url: str) -> None:
+ assert canonicalize_origin(url) is None
+
+ def test_sharp_s_twin_cannot_borrow_an_allowlisted_origin(self) -> None:
+ # A browser sends faß.de to xn--fa-hia.de, a separately registrable domain. GotoUrlAction.url
+ # is model-proposed text, so this is attacker-reachable under indirect prompt injection.
+ policy = declare_policy(owner_id=OWNER, origin_urls=["https://fass.de"])
+ request = BrowserActionRequest(
+ policy=policy,
+ projection=project_for(GotoUrlAction(url="https://faß.de")),
+ authority=RuntimeOriginAuthority(state=AuthorityState.ESTABLISHED, origins=policy.allowed_origins),
+ request_epoch=EPOCH,
+ evidence=PageObservation(
+ page_url="https://fass.de", observation_epoch=EPOCH, verdict=ObservationVerdict.NO_MATCH
+ ),
+ )
+ decision = decide_browser_action(request)
+ assert decision.outcome is PolicyOutcome.DENIED
+ assert PolicyReason.MISSING_TARGET_ORIGIN in decision.reasons
+
+ def test_equivalent_host_spellings_share_one_canonical_form(self) -> None:
+ # A declared origin that canonicalizes to a host no page can ever present would be a policy
+ # that silently matches nothing, so equivalent spellings must collapse to one value.
+ for spelling in (
+ "https://example.com",
+ "https://example.com.",
+ "https://EXAMPLE.COM.",
+ "https://example.com..",
+ ):
+ assert canonicalize_origin(spelling) == HOME_ORIGIN, spelling
+ # A confusable is a DIFFERENT host and must NOT collapse onto the declared one.
+ assert canonicalize_origin("https://exаmple.com") is None
+
+ def test_declaration_is_strict(self) -> None:
+ assert declare_origin("https://example.com:443/x") == BrowserOrigin(
+ scheme="https", host="example.com", port=443
+ )
+ with pytest.raises(ValueError):
+ declare_origin("file:///etc/passwd")
+ with pytest.raises(ValueError):
+ declare_policy(owner_id=OWNER, origin_urls=["https://example.com", "javascript:alert(1)"])
+
+ def test_declared_policy_is_immutable_and_hashable(self) -> None:
+ policy = declare_policy(owner_id=OWNER, origin_urls=[HOME, HOME])
+ assert policy.allowed_origins == frozenset({HOME_ORIGIN})
+ with pytest.raises(dataclasses.FrozenInstanceError):
+ policy.owner_id = "other" # type: ignore[misc]
+ with pytest.raises(dataclasses.FrozenInstanceError):
+ HOME_ORIGIN.host = "evil.example" # type: ignore[misc]
+
+
+class TestClassificationCoverage:
+ def test_every_action_type_is_classified(self) -> None:
+ unclassified = [member for member in ActionType if classify_action_type(member) is None]
+ assert unclassified == []
+
+ def test_every_action_type_has_a_concrete_model_under_test(self) -> None:
+ assert set(CONCRETE_ACTIONS) == set(ActionType)
+
+ def test_every_concrete_model_projects_without_defects(self) -> None:
+ for action_type, action in CONCRETE_ACTIONS.items():
+ projection = project_for(action)
+ assert projection.defects == (), f"{action_type} projected with defects {projection.defects}"
+ assert projection.action_type is action_type
+ assert projection.action_class is classify_action_type(action_type)
+
+ def test_execute_js_is_unsupported(self) -> None:
+ assert classify_action_type(ActionType.EXECUTE_JS) is ActionClass.UNSUPPORTED
+
+ def test_coordinate_only_actions_are_unresolvable(self) -> None:
+ for action_type in (ActionType.DRAG, ActionType.LEFT_MOUSE):
+ assert classify_action_type(action_type) is ActionClass.UNRESOLVABLE
+ assert project_for(CONCRETE_ACTIONS[action_type]).target.resolvable is False
+
+ def test_unknown_action_type_fails_closed(self) -> None:
+ assert classify_action_type("teleport") is None
+ rogue = NullAction()
+ rogue.action_type = "teleport" # type: ignore[assignment]
+ projection = project_for(rogue)
+ assert PolicyReason.UNKNOWN_ACTION in projection.defects
+ assert projection.action_class is None
+
+ def test_model_discriminator_mismatch_fails_closed(self) -> None:
+ # A0 finding F1: action_type is a defaulted field, not a Literal discriminator, so this
+ # mismatched object constructs cleanly.
+ mismatched = ClickAction(element_id="1", action_type=ActionType.GOTO_URL)
+ assert mismatched.action_type is ActionType.GOTO_URL
+ projection = project_for(mismatched)
+ assert PolicyReason.ACTION_MODEL_MISMATCH in projection.defects
+
+ decision = decide_browser_action(build_request(mismatched))
+ assert decision.outcome is PolicyOutcome.DENIED
+ assert PolicyReason.ACTION_MODEL_MISMATCH in decision.reasons
+
+ def test_complete_to_terminate_rewrite_is_re_projected_not_memoized(self) -> None:
+ # A0 finding F4: handler.py rewrites action.action_type = TERMINATE on a CompleteAction.
+ action = CompleteAction()
+ assert project_for(action).defects == ()
+ action.action_type = ActionType.TERMINATE
+ assert PolicyReason.ACTION_MODEL_MISMATCH in project_for(action).defects
+ assert decide_browser_action(build_request(action)).outcome is PolicyOutcome.DENIED
+
+ replacement = TerminateAction()
+ assert project_for(replacement).defects == ()
+ assert decide_browser_action(build_request(replacement)).outcome is PolicyOutcome.ALLOWED
+
+ def test_element_identity_is_not_a_policy_fact(self) -> None:
+ # `_retarget_disabled_element_for_click` swaps the element a click lands on without touching
+ # `action.element_id`, and SKY-12874 deliberately does not re-project there because the
+ # projection cannot change. That reasoning holds only while element identity stays out of
+ # the projection. The day it goes in, this fails and names the site that needs a call.
+ from skyvern.forge.sdk.browser_action_policy import project_action
+
+ assert project_action(ClickAction(element_id="1")) == project_action(ClickAction(element_id="2"))
+
+ def test_navigation_targets_are_extracted(self) -> None:
+ assert project_for(GotoUrlAction(url=HOME)).target.urls == (HOME,)
+ assert project_for(NewTabAction(url=HOME)).target.urls == (HOME,)
+ assert project_for(DownloadFileAction(file_name="f", download_url=HOME)).target.urls == (HOME,)
+ assert project_for(ClickAction(element_id="1")).target.urls == ()
+ assert project_for(UploadFileAction(element_id="1", file_url=HOME)).target.urls == (HOME,)
+ assert project_for(ClickAction(element_id="1", file_url=HOME)).target.urls == (HOME,)
+
+ def test_fetchable_file_urls_are_origin_checked(self) -> None:
+ decision = decide_browser_action(
+ build_request(
+ UploadFileAction(element_id="1", file_url="https://evil.example/x.pdf"),
+ protected_references=(file_ref(),),
+ )
+ )
+ assert decision.outcome is PolicyOutcome.DENIED
+ assert PolicyReason.TARGET_ORIGIN_NOT_AUTHORIZED in decision.reasons
+
+ def test_protected_reference_requirements_are_declared(self) -> None:
+ assert project_for(
+ InputTextAction(element_id="1", text="x", totp_code_required=True)
+ ).required_references == frozenset({ProtectedReferenceKind.SECRET})
+ assert project_for(VerificationCodeAction(verification_code="1")).required_references == frozenset(
+ {ProtectedReferenceKind.VERIFICATION_CODE}
+ )
+ assert project_for(
+ UploadFileAction(element_id="1", file_url="https://example.com/f.pdf")
+ ).required_references == frozenset({ProtectedReferenceKind.FILE})
+ assert project_for(InputTextAction(element_id="1", text="x")).required_references == frozenset()
+
+
+class TestUnclassifiableProjections:
+ def test_a_hand_built_unclassified_projection_is_denied(self) -> None:
+ # ActionProjection is public API and `defects` defaults to (), so downstream tickets can
+ # construct one directly. Unclassifiable must deny, not fall through to the recovery set.
+ projection = ActionProjection(
+ action_type=ActionType.GOTO_URL,
+ action_class=None,
+ target=ActionTarget(urls=("https://totally-evil.example/",)),
+ )
+ decision = decide_browser_action(
+ BrowserActionRequest(
+ policy=POLICY,
+ projection=projection,
+ authority=FULL_AUTHORITY,
+ request_epoch=EPOCH,
+ evidence=PageObservation(
+ page_url="https://also-evil.example/",
+ observation_epoch=EPOCH,
+ verdict=ObservationVerdict.SUSPICIOUS,
+ ),
+ )
+ )
+ assert decision.outcome is PolicyOutcome.DENIED
+ assert PolicyReason.UNKNOWN_ACTION in decision.reasons
+ assert PolicyReason.TARGET_ORIGIN_NOT_AUTHORIZED in decision.reasons
+ assert PolicyReason.PAGE_ORIGIN_NOT_AUTHORIZED in decision.reasons
+ assert PolicyReason.UNTRUSTED_OBSERVATION in decision.reasons
+
+ def test_an_action_type_missing_from_the_tables_fails_closed_without_crashing(self) -> None:
+ rogue = NullAction()
+ rogue.action_type = "teleport" # type: ignore[assignment]
+ assert project_for(rogue).defects == (PolicyReason.UNKNOWN_ACTION,)
+
+ def test_an_unmapped_action_type_degrades_instead_of_crashing(self, monkeypatch: pytest.MonkeyPatch) -> None:
+ # Simulates a future ActionType member that nobody added to the tables. A crash inside the
+ # policy core would make observe mode behavioural, which is the one thing it must never be.
+ import skyvern.forge.sdk.browser_action_policy as module
+
+ monkeypatch.delitem(module._ACTION_MODELS, ActionType.CLICK)
+ monkeypatch.delitem(module._ACTION_CLASSES, ActionType.CLICK)
+ projection = project_for(ClickAction(element_id="1"))
+ assert projection.defects == (PolicyReason.UNKNOWN_ACTION,)
+ assert decide_browser_action(build_request(ClickAction(element_id="1"))).outcome is PolicyOutcome.DENIED
+
+ def test_protected_reference_kind_is_type_checked(self) -> None:
+ # `kind in ProtectedReferenceKind` raises TypeError for a plain string on 3.11.
+ assert ProtectedReference(kind="secret", reference_id="r", owner_id=OWNER).complete is False # type: ignore[arg-type]
+ assert ProtectedReference(kind=ProtectedReferenceKind.SECRET, reference_id="r", owner_id=OWNER).complete
+
+
+class TestEnrollmentBoundary:
+ def test_policy_none_is_the_exclusive_not_enrolled_result(self) -> None:
+ decision = decide_browser_action(build_request(ClickAction(element_id="1"), policy=None))
+ assert decision.outcome is PolicyOutcome.NOT_ENROLLED
+ assert decision.reasons == ()
+
+ def test_not_enrolled_survives_every_other_defect(self) -> None:
+ decision = decide_browser_action(
+ build_request(
+ ExecuteJsAction(js_code="1"),
+ policy=None,
+ page_url="javascript:alert(1)",
+ evidence_epoch=EPOCH - 3,
+ verdict=ObservationVerdict.SUSPICIOUS,
+ )
+ )
+ assert decision.outcome is PolicyOutcome.NOT_ENROLLED
+ assert decision.reasons == ()
+
+ def test_no_enrolled_request_can_yield_not_enrolled(self) -> None:
+ outcomes = set()
+ for action in CONCRETE_ACTIONS.values():
+ for verdict in ObservationVerdict:
+ for page_url in (HOME, "https://evil.example/"):
+ for epoch in (EPOCH, EPOCH - 1):
+ decision = decide_browser_action(
+ build_request(
+ action,
+ page_url=page_url,
+ evidence_epoch=epoch,
+ verdict=verdict,
+ protected_references=refs_for(action),
+ )
+ )
+ outcomes.add(decision.outcome)
+ assert PolicyOutcome.NOT_ENROLLED not in outcomes
+
+
+class TestEvidenceRequirements:
+ def test_missing_evidence_denies(self) -> None:
+ decision = decide_browser_action(build_request(ClickAction(element_id="1"), omit_evidence=True))
+ assert decision.outcome is PolicyOutcome.DENIED
+ assert PolicyReason.MISSING_PAGE_EVIDENCE in decision.reasons
+
+ def test_stale_epoch_denies(self) -> None:
+ decision = decide_browser_action(build_request(ClickAction(element_id="1"), evidence_epoch=EPOCH - 1))
+ assert decision.outcome is PolicyOutcome.DENIED
+ assert PolicyReason.STALE_PAGE_EVIDENCE in decision.reasons
+
+ def test_future_epoch_denies(self) -> None:
+ decision = decide_browser_action(build_request(ClickAction(element_id="1"), evidence_epoch=EPOCH + 1))
+ assert PolicyReason.STALE_PAGE_EVIDENCE in decision.reasons
+
+ def test_unparseable_page_url_denies(self) -> None:
+ decision = decide_browser_action(build_request(ClickAction(element_id="1"), page_url="about:blank"))
+ assert decision.outcome is PolicyOutcome.DENIED
+ assert PolicyReason.MISSING_PAGE_ORIGIN in decision.reasons
+
+ def test_benign_actions_still_require_fresh_evidence(self) -> None:
+ decision = decide_browser_action(build_request(WaitAction(), evidence_epoch=EPOCH - 1))
+ assert decision.outcome is PolicyOutcome.DENIED
+ assert PolicyReason.STALE_PAGE_EVIDENCE in decision.reasons
+
+
+class TestProtectedReferences:
+ def test_missing_required_reference_denies(self) -> None:
+ action = VerificationCodeAction(verification_code="123456")
+ decision = decide_browser_action(build_request(action, protected_references=()))
+ assert decision.outcome is PolicyOutcome.DENIED
+ assert PolicyReason.MISSING_PROTECTED_REFERENCE in decision.reasons
+
+ @pytest.mark.parametrize("blank_field", ["reference_id", "owner_id"])
+ def test_incomplete_reference_facts_deny(self, blank_field: str) -> None:
+ fields = {"kind": ProtectedReferenceKind.VERIFICATION_CODE, "reference_id": "ref", "owner_id": OWNER}
+ fields[blank_field] = ""
+ reference = ProtectedReference(**fields) # type: ignore[arg-type]
+ assert reference.complete is False
+ decision = decide_browser_action(
+ build_request(VerificationCodeAction(verification_code="1"), protected_references=(reference,))
+ )
+ assert decision.outcome is PolicyOutcome.DENIED
+ assert PolicyReason.INCOMPLETE_PROTECTED_REFERENCE in decision.reasons
+
+ def test_reference_owned_by_another_run_denies(self) -> None:
+ decision = decide_browser_action(
+ build_request(
+ VerificationCodeAction(verification_code="1"),
+ protected_references=(code_ref(owner_id="wr_other"),),
+ )
+ )
+ assert decision.outcome is PolicyOutcome.DENIED
+ assert PolicyReason.UNOWNED_PROTECTED_REFERENCE in decision.reasons
+
+ def test_complete_owned_reference_allows(self) -> None:
+ decision = decide_browser_action(
+ build_request(VerificationCodeAction(verification_code="1"), protected_references=(code_ref(),))
+ )
+ assert decision.outcome is PolicyOutcome.ALLOWED
+ assert decision.reasons == ()
+
+
+class TestOriginAuthorization:
+ def test_unauthorized_page_origin_denies(self) -> None:
+ decision = decide_browser_action(build_request(ClickAction(element_id="1"), page_url="https://evil.example/"))
+ assert decision.outcome is PolicyOutcome.DENIED
+ assert PolicyReason.PAGE_ORIGIN_NOT_AUTHORIZED in decision.reasons
+
+ def test_unauthorized_target_origin_denies(self) -> None:
+ decision = decide_browser_action(build_request(GotoUrlAction(url="https://evil.example/")))
+ assert decision.outcome is PolicyOutcome.DENIED
+ assert PolicyReason.TARGET_ORIGIN_NOT_AUTHORIZED in decision.reasons
+
+ def test_unparseable_target_denies(self) -> None:
+ decision = decide_browser_action(build_request(GotoUrlAction(url="javascript:alert(1)")))
+ assert decision.outcome is PolicyOutcome.DENIED
+ assert PolicyReason.MISSING_TARGET_ORIGIN in decision.reasons
+
+ def test_authorized_navigation_allows(self) -> None:
+ assert decide_browser_action(build_request(GotoUrlAction(url=HOME))).outcome is PolicyOutcome.ALLOWED
+
+ def test_benign_action_survives_an_unauthorized_origin(self) -> None:
+ # The recovery set must let the agent get back to authorized ground.
+ for action in (WaitAction(), ScrollAction(), GoBackAction(), TerminateAction()):
+ decision = decide_browser_action(build_request(action, page_url="https://evil.example/"))
+ assert decision.outcome is PolicyOutcome.ALLOWED, action.action_type
+
+ def test_mutating_action_is_gated_on_an_unauthorized_origin(self) -> None:
+ decision = decide_browser_action(build_request(ClickAction(element_id="1"), page_url="https://evil.example/"))
+ assert decision.outcome is PolicyOutcome.DENIED
+
+
+class TestRuntimeAuthority:
+ """The enrolled policy is a ceiling, not the complete authority (ADR-0011).
+
+ Every test here pins verdict=NO_MATCH and puts the page origin *inside* POLICY.allowed_origins,
+ so the only thing that can deny is the authority gate. Without those two pins a request denies
+ anyway on UNVERIFIED_OBSERVATION and the assertions would hold against any implementation.
+ """
+
+ def test_unwired_authority_denies_an_action_inside_the_ceiling(self) -> None:
+ decision = decide_browser_action(build_request(ClickAction(element_id="1"), authority=UNWIRED_AUTHORITY))
+ assert decision.outcome is PolicyOutcome.DENIED
+ assert decision.reasons == (PolicyReason.UNWIRED_RUNTIME_AUTHORITY,)
+
+ def test_established_authority_over_the_same_origin_allows(self) -> None:
+ # The twin of the test above. If this one fails, the deny above proves nothing: it would be
+ # denying for some reason other than the authority gate.
+ decision = decide_browser_action(build_request(ClickAction(element_id="1"), authority=FULL_AUTHORITY))
+ assert decision.outcome is PolicyOutcome.ALLOWED
+ assert decision.reasons == ()
+
+ def test_missing_authority_denies(self) -> None:
+ authority = RuntimeOriginAuthority(state=AuthorityState.MISSING, origins=POLICY.allowed_origins)
+ decision = decide_browser_action(build_request(ClickAction(element_id="1"), authority=authority))
+ assert decision.outcome is PolicyOutcome.DENIED
+ assert decision.reasons == (PolicyReason.MISSING_RUNTIME_AUTHORITY,)
+
+ def test_invalidated_authority_denies_even_carrying_the_right_origins(self) -> None:
+ # ADR-0011: rotation or conflict after a browser context is bound is permanent, and the
+ # origins it used to carry do not buy it back.
+ authority = RuntimeOriginAuthority(state=AuthorityState.INVALIDATED, origins=POLICY.allowed_origins)
+ decision = decide_browser_action(build_request(ClickAction(element_id="1"), authority=authority))
+ assert decision.outcome is PolicyOutcome.DENIED
+ assert decision.reasons == (PolicyReason.INVALIDATED_RUNTIME_AUTHORITY,)
+
+ def test_established_authority_narrower_than_the_ceiling_denies_outside_itself(self) -> None:
+ other = "https://other.example/"
+ wide = declare_policy(owner_id=OWNER, origin_urls=[HOME, other])
+ narrow = RuntimeOriginAuthority(state=AuthorityState.ESTABLISHED, origins=frozenset({declare_origin(other)}))
+ decision = decide_browser_action(
+ build_request(ClickAction(element_id="1"), policy=wide, page_url=HOME, authority=narrow)
+ )
+ assert decision.outcome is PolicyOutcome.DENIED
+ assert decision.reasons == (PolicyReason.PAGE_ORIGIN_NOT_AUTHORIZED,)
+
+ def test_authority_cannot_widen_the_ceiling(self) -> None:
+ outside = "https://outside.example/"
+ authority = RuntimeOriginAuthority(
+ state=AuthorityState.ESTABLISHED,
+ origins=frozenset({HOME_ORIGIN, declare_origin(outside)}),
+ )
+ decision = decide_browser_action(
+ build_request(ClickAction(element_id="1"), page_url=outside, authority=authority)
+ )
+ assert decision.outcome is PolicyOutcome.DENIED
+ assert decision.reasons == (PolicyReason.PAGE_ORIGIN_NOT_AUTHORIZED,)
+
+ def test_navigation_target_is_checked_against_the_intersection(self) -> None:
+ wide = declare_policy(owner_id=OWNER, origin_urls=[HOME, "https://other.example/"])
+ narrow = RuntimeOriginAuthority(state=AuthorityState.ESTABLISHED, origins=frozenset({HOME_ORIGIN}))
+ decision = decide_browser_action(
+ build_request(GotoUrlAction(url="https://other.example/next"), policy=wide, authority=narrow)
+ )
+ assert decision.outcome is PolicyOutcome.DENIED
+ assert decision.reasons == (PolicyReason.TARGET_ORIGIN_NOT_AUTHORIZED,)
+
+ def test_recovery_actions_survive_an_unwired_authority(self) -> None:
+ # ADR-0011 keeps read-only and recovery actions available so a run can stop safely. If the
+ # authority gate ever swallows these, a protected run has no way out.
+ for action in (WaitAction(), ScrollAction(), GoBackAction(), ExtractAction(), TerminateAction()):
+ decision = decide_browser_action(build_request(action, authority=UNWIRED_AUTHORITY))
+ assert decision.outcome is PolicyOutcome.ALLOWED, action.action_type
+
+ def test_an_unenrolled_run_is_still_not_enrolled(self) -> None:
+ decision = decide_browser_action(
+ build_request(ClickAction(element_id="1"), policy=None, authority=UNWIRED_AUTHORITY)
+ )
+ assert decision.outcome is PolicyOutcome.NOT_ENROLLED
+
+ def test_authority_is_required_with_no_default(self) -> None:
+ # A default would let a caller reach the absent state by omission. It has to be named.
+ with pytest.raises(TypeError):
+ BrowserActionRequest( # type: ignore[call-arg]
+ policy=POLICY,
+ projection=project_for(ClickAction(element_id="1")),
+ request_epoch=EPOCH,
+ )
+
+ def test_unwired_is_a_state_of_its_own(self) -> None:
+ # Collapsing unwired into missing is what would hide the empty seam, in source and in logs.
+ assert UNWIRED_AUTHORITY.state is AuthorityState.UNWIRED
+ assert UNWIRED_AUTHORITY.state is not AuthorityState.MISSING
+ assert UNWIRED_AUTHORITY.origins == frozenset()
+
+
+class TestObservationGating:
+ def test_suspicious_observation_denies_a_mutating_action(self) -> None:
+ decision = decide_browser_action(
+ build_request(ClickAction(element_id="1"), verdict=ObservationVerdict.SUSPICIOUS)
+ )
+ assert decision.outcome is PolicyOutcome.DENIED
+ assert PolicyReason.UNTRUSTED_OBSERVATION in decision.reasons
+
+ def test_unknown_observation_denies_a_mutating_action(self) -> None:
+ decision = decide_browser_action(build_request(ClickAction(element_id="1"), verdict=ObservationVerdict.UNKNOWN))
+ assert decision.outcome is PolicyOutcome.DENIED
+ assert PolicyReason.UNVERIFIED_OBSERVATION in decision.reasons
+
+ def test_extract_respects_a_suspicious_verdict(self) -> None:
+ # EXTRACT is the channel that pulls untrusted page content into the agent context, which is
+ # the very attack SKY-12526 is about. Recovery does not mean reading a hostile page.
+ assert classify_action_type(ActionType.EXTRACT) is ActionClass.READ
+ decision = decide_browser_action(build_request(ExtractAction(), verdict=ObservationVerdict.SUSPICIOUS))
+ assert decision.outcome is PolicyOutcome.DENIED
+ assert PolicyReason.UNTRUSTED_OBSERVATION in decision.reasons
+
+ def test_extract_still_works_on_an_unauthorized_origin(self) -> None:
+ # Origin and verdict are separate axes: EXTRACT stays available for recovery.
+ decision = decide_browser_action(build_request(ExtractAction(), page_url="https://evil.example/"))
+ assert decision.outcome is PolicyOutcome.ALLOWED
+
+ def test_suspicious_observation_does_not_block_recovery(self) -> None:
+ decision = decide_browser_action(build_request(GoBackAction(), verdict=ObservationVerdict.SUSPICIOUS))
+ assert decision.outcome is PolicyOutcome.ALLOWED
+
+ def test_raw_string_verdict_is_coerced_fail_closed(self) -> None:
+ evidence = PageObservation(page_url=HOME, observation_epoch=EPOCH, verdict=ObservationVerdict.NO_MATCH)
+ object.__setattr__(evidence, "verdict", "totally-clean")
+ decision = decide_browser_action(build_request(ClickAction(element_id="1"), evidence=evidence))
+ assert PolicyReason.UNVERIFIED_OBSERVATION in decision.reasons
+
+
+class TestUnsupportedActions:
+ def test_execute_js_is_unsupported_not_merely_denied(self) -> None:
+ decision = decide_browser_action(build_request(ExecuteJsAction(js_code="1")))
+ assert decision.outcome is PolicyOutcome.UNSUPPORTED
+ assert PolicyReason.UNSUPPORTED_ACTION in decision.reasons
+
+ def test_execute_js_stays_unsupported_on_an_authorized_clean_page(self) -> None:
+ decision = decide_browser_action(
+ build_request(ExecuteJsAction(js_code="1"), verdict=ObservationVerdict.NO_MATCH)
+ )
+ assert decision.outcome is PolicyOutcome.UNSUPPORTED
+
+ def test_unresolvable_actions_deny(self) -> None:
+ for action in (DragAction(), LeftMouseAction(direction="down")):
+ decision = decide_browser_action(build_request(action))
+ assert decision.outcome is PolicyOutcome.DENIED, action.action_type
+ assert PolicyReason.UNRESOLVABLE_TARGET in decision.reasons
+
+
+class TestReasonPrecedence:
+ def test_precedence_covers_every_reason_exactly_once(self) -> None:
+ assert list(REASON_PRECEDENCE) == sorted(REASON_PRECEDENCE, key=REASON_PRECEDENCE.index)
+ assert set(REASON_PRECEDENCE) == set(PolicyReason)
+ assert len(REASON_PRECEDENCE) == len(set(REASON_PRECEDENCE)) == len(PolicyReason)
+
+ def test_all_applicable_reasons_are_returned_in_precedence_order(self) -> None:
+ decision = decide_browser_action(
+ build_request(
+ GotoUrlAction(url="https://evil.example/"),
+ page_url="https://also-evil.example/",
+ evidence_epoch=EPOCH - 2,
+ verdict=ObservationVerdict.SUSPICIOUS,
+ )
+ )
+ assert decision.outcome is PolicyOutcome.DENIED
+ expected = {
+ PolicyReason.STALE_PAGE_EVIDENCE,
+ PolicyReason.UNTRUSTED_OBSERVATION,
+ PolicyReason.PAGE_ORIGIN_NOT_AUTHORIZED,
+ PolicyReason.TARGET_ORIGIN_NOT_AUTHORIZED,
+ }
+ assert set(decision.reasons) == expected
+ assert list(decision.reasons) == sorted(decision.reasons, key=REASON_PRECEDENCE.index)
+
+ def test_repeated_reasons_collapse_to_one(self) -> None:
+ # Two unauthorized targets raise the same reason twice; the decision must report it once.
+ projection = ActionProjection(
+ action_type=ActionType.GOTO_URL,
+ action_class=ActionClass.NAVIGATION,
+ target=ActionTarget(urls=("https://evil.example/a", "https://evil.example/b")),
+ )
+ decision = decide_browser_action(
+ BrowserActionRequest(
+ policy=POLICY,
+ projection=projection,
+ authority=FULL_AUTHORITY,
+ request_epoch=EPOCH,
+ evidence=PageObservation(page_url=HOME, observation_epoch=EPOCH, verdict=ObservationVerdict.NO_MATCH),
+ )
+ )
+ assert decision.reasons == (PolicyReason.TARGET_ORIGIN_NOT_AUTHORIZED,)
+
+ def test_reason_codes_are_stable_strings(self) -> None:
+ assert {member.value for member in PolicyReason} == {
+ "unsupported_action",
+ "unknown_action",
+ "action_model_mismatch",
+ "unresolvable_target",
+ "missing_page_evidence",
+ "stale_page_evidence",
+ "missing_protected_reference",
+ "incomplete_protected_reference",
+ "unowned_protected_reference",
+ "untrusted_observation",
+ "unverified_observation",
+ "unwired_runtime_authority",
+ "missing_runtime_authority",
+ "invalidated_runtime_authority",
+ "missing_page_origin",
+ "page_origin_not_authorized",
+ "missing_target_origin",
+ "target_origin_not_authorized",
+ }
+
+
+class TestHappyPath:
+ def test_clean_authorized_mutating_action_allows(self) -> None:
+ decision = decide_browser_action(build_request(ClickAction(element_id="1")))
+ assert decision == PolicyDecision(outcome=PolicyOutcome.ALLOWED, reasons=())
+
+ def test_decisions_are_immutable(self) -> None:
+ decision = decide_browser_action(build_request(ClickAction(element_id="1")))
+ with pytest.raises(dataclasses.FrozenInstanceError):
+ decision.outcome = PolicyOutcome.DENIED # type: ignore[misc]
+
+ def test_deciding_twice_yields_an_equal_decision(self) -> None:
+ request = build_request(ClickAction(element_id="1"))
+ assert decide_browser_action(request) == decide_browser_action(request)
+
+
+class TestPurity:
+ MODULE = Path(__file__).resolve().parents[2] / "skyvern" / "forge" / "sdk" / "browser_action_policy.py"
+
+ def parsed(self) -> ast.Module:
+ return ast.parse(self.MODULE.read_text())
+
+ def test_module_declares_no_async_work(self) -> None:
+ offenders = [node.name for node in ast.walk(self.parsed()) if isinstance(node, ast.AsyncFunctionDef)]
+ assert offenders == []
+ assert not [node for node in ast.walk(self.parsed()) if isinstance(node, (ast.Await, ast.AsyncWith))]
+
+ def test_module_imports_nothing_impure(self) -> None:
+ forbidden = {
+ "asyncio",
+ "cloud",
+ "httpx",
+ "requests",
+ "aiohttp",
+ "socket",
+ "subprocess",
+ "os",
+ "pathlib",
+ "skyvern.config",
+ "skyvern.forge.sdk.core.skyvern_context",
+ }
+ imported: set[str] = set()
+ for node in ast.walk(self.parsed()):
+ if isinstance(node, ast.Import):
+ imported.update(alias.name for alias in node.names)
+ elif isinstance(node, ast.ImportFrom) and node.module:
+ imported.add(node.module)
+ assert imported & forbidden == set()
+ assert not any(name.split(".")[0] == "cloud" for name in imported)
+
+ def test_module_does_no_global_context_lookup(self) -> None:
+ source = self.MODULE.read_text()
+ for needle in ("skyvern_context", "contextvars", "ContextVar", "app.AGENT_FUNCTION", "open("):
+ assert needle not in source, needle
+
+ def test_every_public_dataclass_is_frozen(self) -> None:
+ for obj in (
+ BrowserOrigin,
+ ProtectedReference,
+ ActionTarget,
+ ActionProjection,
+ PageObservation,
+ BrowserActionPolicy,
+ BrowserActionRequest,
+ PolicyDecision,
+ ):
+ assert dataclasses.is_dataclass(obj)
+ assert obj.__dataclass_params__.frozen is True, obj.__name__
+
+
+class TestConfiguration:
+ def test_mode_defaults_to_disabled(self) -> None:
+ assert Settings().BROWSER_ACTION_POLICY_MODE == "disabled"
+
+ def test_observe_is_accepted(self) -> None:
+ assert Settings(BROWSER_ACTION_POLICY_MODE="observe").BROWSER_ACTION_POLICY_MODE == "observe"
+
+ @pytest.mark.parametrize("mode", ["enforce", "block", "ENFORCE", "on", ""])
+ def test_enforce_is_rejected_by_configuration(self, mode: str) -> None:
+ with pytest.raises(ValidationError):
+ Settings(BROWSER_ACTION_POLICY_MODE=mode)
diff --git a/tests/unit/test_browser_action_policy_enrollment.py b/tests/unit/test_browser_action_policy_enrollment.py
new file mode 100644
index 000000000..1a8c706ba
--- /dev/null
+++ b/tests/unit/test_browser_action_policy_enrollment.py
@@ -0,0 +1,457 @@
+"""Enrollment persistence and run binding for the browser action policy (SKY-12873)."""
+
+from __future__ import annotations
+
+import inspect
+import re
+from datetime import datetime, timezone
+from pathlib import Path
+from types import SimpleNamespace
+from typing import Any, cast
+from unittest.mock import AsyncMock
+
+import pytest
+
+from skyvern.exceptions import BrowserActionPolicyNotEnforceable
+from skyvern.forge import app
+from skyvern.forge.sdk.browser_action_policy import BrowserActionPolicy, declare_origin, declare_policy
+from skyvern.forge.sdk.core import skyvern_context
+from skyvern.forge.sdk.core.skyvern_context import SkyvernContext
+from skyvern.forge.sdk.workflow.browser_action_policy_enrollment import (
+ POLICY_KEY,
+ EnrollmentRejection,
+ bind_policy_to_context,
+ carried_policy,
+ deserialize_policy,
+ read_policy,
+ rejection_reasons,
+ serialize_policy,
+ stored_policy_version,
+ with_policy,
+)
+from skyvern.forge.sdk.workflow.models.workflow import Workflow
+from skyvern.forge.sdk.workflow.service import WorkflowService
+from skyvern.schemas.workflows import WorkflowCreateYAMLRequest
+
+
+def _output_parameter(key: str) -> dict[str, Any]:
+ return {
+ "parameter_type": "output",
+ "key": key,
+ "output_parameter_id": f"op_{key}",
+ "workflow_id": "wf_test",
+ "created_at": datetime.now(timezone.utc),
+ "modified_at": datetime.now(timezone.utc),
+ }
+
+
+def _navigation_block(label: str = "open_site") -> dict[str, Any]:
+ return {
+ "block_type": "navigation",
+ "label": label,
+ "url": "https://example.com/login",
+ "navigation_goal": "Open the site",
+ "output_parameter": _output_parameter(f"{label}_output"),
+ }
+
+
+def _code_block(label: str = "run_code") -> dict[str, Any]:
+ return {
+ "block_type": "code",
+ "label": label,
+ "code": "result = 1",
+ "output_parameter": _output_parameter(f"{label}_output"),
+ }
+
+
+def _for_loop_block(inner: list[dict[str, Any]], label: str = "loop") -> dict[str, Any]:
+ return {
+ "block_type": "for_loop",
+ "label": label,
+ "loop_over_parameter_key": "items",
+ "loop_blocks": inner,
+ "output_parameter": _output_parameter(f"{label}_output"),
+ }
+
+
+def _workflow(blocks: list[dict[str, Any]] | None = None, **overrides: Any) -> Workflow:
+ fields: dict[str, Any] = {
+ "workflow_id": "wf_test",
+ "organization_id": "o_test",
+ "workflow_permanent_id": "wpid_test",
+ "title": "test",
+ "version": 1,
+ "is_saved_task": False,
+ "workflow_definition": {"parameters": [], "blocks": blocks if blocks is not None else [_navigation_block()]},
+ "created_at": datetime.now(timezone.utc),
+ "modified_at": datetime.now(timezone.utc),
+ }
+ fields.update(overrides)
+ return Workflow(**fields)
+
+
+def _policy(*origin_urls: str, owner_id: str = "o_test", version: int = 1) -> BrowserActionPolicy:
+ return declare_policy(owner_id=owner_id, origin_urls=list(origin_urls) or ["https://example.com"], version=version)
+
+
+class TestSerialization:
+ def test_round_trip_preserves_the_policy(self) -> None:
+ policy = _policy("https://example.com", "https://a.example.com:8443", version=7)
+ assert deserialize_policy(serialize_policy(policy)) == policy
+
+ def test_origin_order_is_deterministic_regardless_of_frozenset_iteration(self) -> None:
+ urls = ["https://z.example.com", "https://a.example.com", "https://m.example.com:8443"]
+ first = serialize_policy(declare_policy(owner_id="o_test", origin_urls=urls))
+ second = serialize_policy(declare_policy(owner_id="o_test", origin_urls=list(reversed(urls))))
+ assert first == second
+ assert first["allowed_origins"] == sorted(first["allowed_origins"])
+
+ @pytest.mark.parametrize("spelling", ["HTTPS://Example.COM:443/path", "https://example.com."])
+ def test_serialized_origins_are_canonical(self, spelling: str) -> None:
+ stored = serialize_policy(declare_policy(owner_id="o_test", origin_urls=[spelling]))
+ assert stored["allowed_origins"] == [declare_origin(spelling).canonical]
+ assert stored["allowed_origins"] == [declare_origin("https://example.com").canonical]
+
+ @pytest.mark.parametrize(
+ "corrupt",
+ [
+ None,
+ "https://example.com",
+ [],
+ {"owner_id": "o_test", "allowed_origins": ["https://example.com"]},
+ {"owner_id": "o_test", "allowed_origins": ["https://example.com"], "version": 1, "extra": 1},
+ {"owner_id": "", "allowed_origins": ["https://example.com"], "version": 1},
+ {"owner_id": "o_test", "allowed_origins": [], "version": 1},
+ {"owner_id": "o_test", "allowed_origins": ["not a url"], "version": 1},
+ {"owner_id": "o_test", "allowed_origins": ["file:///etc/passwd"], "version": 1},
+ {"owner_id": "o_test", "allowed_origins": "https://example.com", "version": 1},
+ {"owner_id": "o_test", "allowed_origins": [1], "version": 1},
+ {"owner_id": 5, "allowed_origins": ["https://example.com"], "version": 1},
+ {"owner_id": "o_test", "allowed_origins": ["https://example.com"], "version": "1"},
+ {"owner_id": "o_test", "allowed_origins": ["https://example.com"], "version": True},
+ # Hosts the core refuses because their spelling cannot be reconciled with what a browser
+ # would resolve: non-ASCII (stdlib IDNA2003 diverges from browser UTS-46), non-ASCII
+ # label separators, and last labels that read as address literals.
+ {"owner_id": "o_test", "allowed_origins": ["https://exämple.com"], "version": 1},
+ {"owner_id": "o_test", "allowed_origins": ["https://example。com。"], "version": 1},
+ {"owner_id": "o_test", "allowed_origins": ["https://example.0x1"], "version": 1},
+ {"owner_id": "o_test", "allowed_origins": ["https://example.12"], "version": 1},
+ ],
+ )
+ def test_corrupt_policy_data_is_rejected(self, corrupt: object) -> None:
+ with pytest.raises(ValueError):
+ deserialize_policy(corrupt)
+
+ def test_a_host_the_core_refuses_cannot_be_smuggled_in_through_storage(self) -> None:
+ # Rehydration goes through declare_policy, so a stored origin the declaration rules would
+ # never have minted stays unusable rather than becoming an allowlist entry on reload.
+ with pytest.raises(ValueError):
+ declare_policy(owner_id="o_test", origin_urls=["https://exämple.com"])
+ with pytest.raises(ValueError):
+ read_policy({POLICY_KEY: {"owner_id": "o_test", "allowed_origins": ["https://exämple.com"], "version": 1}})
+
+ def test_an_internationalized_origin_is_declared_and_stored_as_its_a_label(self) -> None:
+ # The core refuses the unicode spelling rather than encoding it, so an operator declares the
+ # punycode form — which is what the browser puts on the wire anyway.
+ stored = serialize_policy(declare_policy(owner_id="o_test", origin_urls=["https://xn--exmple-cua.com"]))
+ assert stored["allowed_origins"] == [declare_origin("https://xn--exmple-cua.com").canonical]
+ assert deserialize_policy(stored).allowed_origins == frozenset({declare_origin("https://xn--exmple-cua.com")})
+
+ def test_read_policy_returns_none_for_an_unenrolled_definition(self) -> None:
+ assert read_policy({"parameters": [], "blocks": []}) is None
+ assert read_policy(None) is None
+
+ def test_read_policy_raises_rather_than_silently_unenrolling_a_corrupt_row(self) -> None:
+ with pytest.raises(ValueError):
+ read_policy({"parameters": [], "blocks": [], POLICY_KEY: {"owner_id": "o_test"}})
+
+ def test_a_yaml_save_cannot_express_a_policy_at_all(self) -> None:
+ # The first line of defence: the request model has no such field, so a submitted policy is
+ # dropped before any write path sees it — and no response model can echo one back out.
+ stored = serialize_policy(_policy("https://evil.example.com"))
+ request = WorkflowCreateYAMLRequest.model_validate(
+ {
+ "title": "smuggled",
+ "workflow_definition": {"parameters": [], "blocks": [], POLICY_KEY: stored},
+ POLICY_KEY: stored,
+ }
+ )
+ assert POLICY_KEY not in request.model_dump(mode="json")
+ assert POLICY_KEY not in request.workflow_definition.model_dump(mode="json")
+
+ def test_with_policy_sets_and_clears_without_touching_the_definition(self) -> None:
+ definition = {"parameters": [], "blocks": [_navigation_block()]}
+ stored = serialize_policy(_policy())
+
+ enrolled = with_policy(definition, stored)
+ assert enrolled[POLICY_KEY] == stored
+ assert enrolled["blocks"] == definition["blocks"]
+ assert POLICY_KEY not in definition
+
+ assert POLICY_KEY not in with_policy(enrolled, None)
+
+ def test_carried_policy_copies_the_stored_value_verbatim(self) -> None:
+ stored = {"owner_id": "o_test", "allowed_origins": ["https://example.com"], "version": 3}
+ assert carried_policy({"blocks": [], POLICY_KEY: stored}) == stored
+ assert carried_policy({"blocks": []}) is None
+ assert carried_policy(None) is None
+
+ def test_carried_policy_copies_corrupt_data_unchanged(self) -> None:
+ # A save must not be able to alter policy, including "repairing" it into something valid.
+ corrupt = {"owner_id": "o_test"}
+ assert carried_policy({POLICY_KEY: corrupt}) == corrupt
+
+ @pytest.mark.parametrize(
+ "definition,expected",
+ [
+ ({}, 0),
+ (None, 0),
+ ({POLICY_KEY: {"version": 4}}, 4),
+ ({POLICY_KEY: {"version": 0}}, 0),
+ ({POLICY_KEY: {"version": True}}, 0),
+ ({POLICY_KEY: {"version": "4"}}, 0),
+ ({POLICY_KEY: "garbage"}, 0),
+ ],
+ )
+ def test_stored_policy_version_never_raises(self, definition: object, expected: int) -> None:
+ assert stored_policy_version(definition) == expected
+
+
+class TestEligibility:
+ def test_an_ordinary_agent_workflow_is_eligible(self) -> None:
+ assert rejection_reasons(_workflow(), run_with=None) == ()
+
+ def test_a_code_block_is_rejected(self) -> None:
+ assert rejection_reasons(_workflow([_code_block()]), run_with=None) == (EnrollmentRejection.CODE_BLOCK_PRESENT,)
+
+ def test_a_code_block_nested_in_a_loop_is_rejected(self) -> None:
+ blocks = [_for_loop_block([_navigation_block("inner_nav"), _code_block("inner_code")])]
+ assert EnrollmentRejection.CODE_BLOCK_PRESENT in rejection_reasons(_workflow(blocks), run_with=None)
+
+ def test_workflow_level_code_execution_is_rejected(self) -> None:
+ assert rejection_reasons(_workflow(run_with="code"), run_with=None) == (
+ EnrollmentRejection.CODE_EXECUTION_SELECTED,
+ )
+
+ def test_run_level_code_execution_overrides_an_agent_workflow(self) -> None:
+ assert rejection_reasons(_workflow(run_with="agent"), run_with="code") == (
+ EnrollmentRejection.CODE_EXECUTION_SELECTED,
+ )
+
+ def test_run_level_agent_does_not_rescue_a_code_workflow(self) -> None:
+ # The version still selects code execution; a single agent run does not make it enforceable.
+ assert rejection_reasons(_workflow(run_with="code"), run_with="agent") == (
+ EnrollmentRejection.CODE_EXECUTION_SELECTED,
+ )
+
+ def test_cached_and_generated_script_selection_is_rejected(self) -> None:
+ assert rejection_reasons(_workflow(adaptive_caching=True), run_with=None) == (
+ EnrollmentRejection.ADAPTIVE_CACHING_ENABLED,
+ )
+ assert rejection_reasons(_workflow(generate_script_on_terminal=True), run_with=None) == (
+ EnrollmentRejection.SCRIPT_GENERATION_ENABLED,
+ )
+
+ def test_every_reason_is_reported_in_a_stable_order(self) -> None:
+ workflow = _workflow([_code_block()], run_with="code", adaptive_caching=True, generate_script_on_terminal=True)
+ assert rejection_reasons(workflow, run_with=None) == (
+ EnrollmentRejection.CODE_BLOCK_PRESENT,
+ EnrollmentRejection.CODE_EXECUTION_SELECTED,
+ EnrollmentRejection.ADAPTIVE_CACHING_ENABLED,
+ EnrollmentRejection.SCRIPT_GENERATION_ENABLED,
+ )
+
+ def test_reasons_carry_no_workflow_content(self) -> None:
+ workflow = _workflow([_code_block("secret_label")], run_with="code")
+ rendered = " ".join(rejection_reasons(workflow, run_with=None))
+ assert "secret_label" not in rendered
+ assert "example.com" not in rendered
+
+
+class TestBinding:
+ @pytest.fixture(autouse=True)
+ def _fresh_context(self) -> Any:
+ skyvern_context.set(SkyvernContext(organization_id="o_test"))
+ yield
+ skyvern_context.reset()
+
+ def test_an_unenrolled_version_leaves_the_context_unenrolled(self) -> None:
+ bind_policy_to_context(None, _workflow(), run_with=None)
+ assert skyvern_context.ensure_context().browser_action_policy is None
+
+ def test_an_enrolled_version_binds_the_exact_policy(self) -> None:
+ policy = _policy("https://example.com")
+ bind_policy_to_context(policy, _workflow(), run_with=None)
+ assert skyvern_context.ensure_context().browser_action_policy is policy
+
+ def test_an_unenrolled_version_clears_a_policy_left_on_a_reused_context(self) -> None:
+ # A grant must not survive into a run whose own version is unenrolled.
+ skyvern_context.ensure_context().browser_action_policy = _policy("https://example.com")
+ bind_policy_to_context(None, _workflow(), run_with=None)
+ assert skyvern_context.ensure_context().browser_action_policy is None
+
+ def test_an_ineligible_enrolled_version_is_rejected_and_binds_nothing(self) -> None:
+ with pytest.raises(BrowserActionPolicyNotEnforceable) as excinfo:
+ bind_policy_to_context(_policy(), _workflow([_code_block()]), run_with=None)
+ assert excinfo.value.reasons == (EnrollmentRejection.CODE_BLOCK_PRESENT,)
+ assert skyvern_context.ensure_context().browser_action_policy is None
+
+ def test_rejection_message_carries_only_stable_reason_codes(self) -> None:
+ with pytest.raises(BrowserActionPolicyNotEnforceable) as excinfo:
+ bind_policy_to_context(_policy("https://example.com"), _workflow(run_with="code"), run_with=None)
+ message = str(excinfo.value.message)
+ assert EnrollmentRejection.CODE_EXECUTION_SELECTED in message
+ assert "example.com" not in message
+ assert "wpid_test" not in message
+
+ def test_an_ineligible_unenrolled_version_is_left_alone(self) -> None:
+ # Code blocks and script execution are only refused for versions an operator enrolled.
+ bind_policy_to_context(None, _workflow([_code_block()], run_with="code"), run_with="code")
+ assert skyvern_context.ensure_context().browser_action_policy is None
+
+ def test_binding_an_enrolled_policy_without_a_context_fails_closed(self) -> None:
+ # Nothing could consume the policy, so the run must not proceed as if it had been bound.
+ skyvern_context.reset()
+ with pytest.raises(RuntimeError):
+ bind_policy_to_context(_policy(), _workflow(), run_with=None)
+
+ def test_binding_an_unenrolled_version_without_a_context_is_a_no_op(self) -> None:
+ skyvern_context.reset()
+ bind_policy_to_context(None, _workflow(), run_with=None)
+ assert skyvern_context.current() is None
+
+
+class TestExecutionPathBinding:
+ @pytest.fixture(autouse=True)
+ def _fresh_context(self) -> Any:
+ skyvern_context.set(SkyvernContext(organization_id="o_test"))
+ yield
+ skyvern_context.reset()
+
+ @pytest.mark.asyncio
+ async def test_the_service_binds_the_resolved_workflow_versions_policy(self) -> None:
+ policy = _policy("https://example.com")
+ app.DATABASE.workflows.get_browser_action_policy = AsyncMock(return_value=policy)
+ workflow = _workflow()
+
+ await WorkflowService().bind_browser_action_policy(workflow, run_with=None)
+
+ app.DATABASE.workflows.get_browser_action_policy.assert_awaited_once_with(
+ workflow_id=workflow.workflow_id, organization_id=workflow.organization_id
+ )
+ assert skyvern_context.ensure_context().browser_action_policy is policy
+
+ @pytest.mark.asyncio
+ async def test_the_service_rejects_an_ineligible_enrolled_version(self) -> None:
+ app.DATABASE.workflows.get_browser_action_policy = AsyncMock(return_value=_policy("https://example.com"))
+ with pytest.raises(BrowserActionPolicyNotEnforceable):
+ await WorkflowService().bind_browser_action_policy(_workflow([_code_block()]), run_with=None)
+
+ @pytest.mark.asyncio
+ async def test_a_child_workflow_binds_its_own_policy_over_the_parents(self) -> None:
+ parent_policy = _policy("https://parent.example.com")
+ child_policy = _policy("https://child.example.com")
+ service = WorkflowService()
+
+ app.DATABASE.workflows.get_browser_action_policy = AsyncMock(return_value=parent_policy)
+ await service.bind_browser_action_policy(_workflow(), run_with=None)
+
+ # A child workflow run replaces the context; binding must not inherit the parent's grant.
+ skyvern_context.replace(SkyvernContext(organization_id="o_test"))
+ app.DATABASE.workflows.get_browser_action_policy = AsyncMock(return_value=child_policy)
+ await service.bind_browser_action_policy(_workflow(workflow_id="wf_child"), run_with=None)
+
+ assert skyvern_context.ensure_context().browser_action_policy is child_policy
+
+ @pytest.mark.asyncio
+ async def test_an_unenrolled_child_does_not_inherit_the_parents_grant(self) -> None:
+ service = WorkflowService()
+ app.DATABASE.workflows.get_browser_action_policy = AsyncMock(return_value=_policy("https://parent.example.com"))
+ await service.bind_browser_action_policy(_workflow(), run_with=None)
+
+ app.DATABASE.workflows.get_browser_action_policy = AsyncMock(return_value=None)
+ await service.bind_browser_action_policy(_workflow(workflow_id="wf_child"), run_with=None)
+
+ assert skyvern_context.ensure_context().browser_action_policy is None
+
+ @pytest.mark.parametrize("path", ["setup_workflow_run", "execute_workflow"])
+ def test_execution_paths_bind_before_any_browser_is_created(self, path: str) -> None:
+ source = inspect.getsource(getattr(WorkflowService, path))
+ bind_at = source.find("bind_browser_action_policy")
+ assert bind_at != -1, f"{path} must bind the workflow-version policy"
+ for browser_call in ("BROWSER_MANAGER", "auto_create_browser_session"):
+ first_use = source.find(browser_call)
+ assert first_use == -1 or bind_at < first_use, f"{path} creates a browser before binding policy"
+
+ @pytest.mark.parametrize("path", ["setup_workflow_run", "execute_workflow"])
+ def test_a_rejected_binding_fails_the_run_rather_than_stranding_it(self, path: str) -> None:
+ # The workflow_run row exists by the time either site binds, so neither may let the
+ # rejection escape without moving the run out of its non-final state.
+ source = inspect.getsource(getattr(WorkflowService, path))
+ assert "BrowserActionPolicyNotEnforceable" in source
+ assert "mark_workflow_run_as_failed" in source
+
+ @pytest.mark.asyncio
+ async def test_an_enrolled_run_never_selects_cached_script_execution(self) -> None:
+ # An action-level firewall cannot see inside generated script execution, so the rollout that
+ # upgrades ordinary runs to code mode must not reach an enrolled run.
+ skyvern_context.ensure_context().browser_action_policy = _policy("https://example.com")
+ app.AGENT_FUNCTION.should_upgrade_to_code_mode = AsyncMock(return_value=True)
+ app.AGENT_FUNCTION.should_keep_code_mode_for_workflow_run = AsyncMock(return_value=True)
+
+ workflow_run = SimpleNamespace(run_with=None, retried_from_workflow_run_id=None)
+ decision = await WorkflowService().should_run_script(_workflow(), cast(Any, workflow_run))
+
+ assert decision is False
+ app.AGENT_FUNCTION.should_upgrade_to_code_mode.assert_not_awaited()
+
+ @pytest.mark.asyncio
+ async def test_an_unenrolled_run_still_reaches_the_code_mode_rollout(self) -> None:
+ app.AGENT_FUNCTION.should_upgrade_to_code_mode = AsyncMock(return_value=True)
+ app.AGENT_FUNCTION.should_keep_code_mode_for_workflow_run = AsyncMock(return_value=True)
+
+ workflow_run = SimpleNamespace(run_with=None, retried_from_workflow_run_id=None)
+ assert await WorkflowService().should_run_script(_workflow(), cast(Any, workflow_run)) is True
+
+
+class TestNoUnguardedDefinitionWriter:
+ """`with_policy` is only a guarantee if it is the ONLY thing that writes the definition column.
+
+ Proving that by construction is what lets an erasure slip in later: any writer that reads the
+ definition into `WorkflowDefinition` and writes the model back drops the reserved key and
+ silently unenrolls the workflow. These pin the writer set instead of arguing about it.
+ """
+
+ ROOTS = ("skyvern", "cloud", "scripts", "alembic")
+ # Writes a mutated deepcopy of the raw dict and never rebuilds it, so unknown top-level keys
+ # survive. Pinned behaviourally by test_the_secret_backfill_transform_preserves_the_policy.
+ ALLOWLIST = {"scripts/backfill_encrypt_file_block_secrets.py"}
+
+ def _write_sites(self) -> list[tuple[str, int, str]]:
+ repo_root = Path(__file__).resolve().parents[2]
+ pattern = re.compile(r"\.workflow_definition\s*=[^=]")
+ sites: list[tuple[str, int, str]] = []
+ for root in self.ROOTS:
+ for path in (repo_root / root).rglob("*.py"):
+ relative = path.relative_to(repo_root).as_posix()
+ for number, line in enumerate(path.read_text().splitlines(), start=1):
+ if pattern.search(line):
+ sites.append((relative, number, line.strip()))
+ return sites
+
+ def test_the_search_actually_finds_the_known_writers(self) -> None:
+ # Without this the guard below passes vacuously if the pattern ever stops matching.
+ files = {relative for relative, _, _ in self._write_sites()}
+ assert "skyvern/forge/sdk/db/repositories/workflows.py" in files
+ assert self.ALLOWLIST <= files
+
+ def test_every_definition_write_goes_through_with_policy(self) -> None:
+ unguarded = [
+ (relative, number, line)
+ for relative, number, line in self._write_sites()
+ if relative not in self.ALLOWLIST and "with_policy" not in line
+ ]
+ assert unguarded == [], (
+ "These write the workflow_definition column without carrying the stored browser action "
+ "policy forward, which silently unenrolls the workflow: " + repr(unguarded)
+ )
diff --git a/tests/unit/test_browser_action_preflight.py b/tests/unit/test_browser_action_preflight.py
new file mode 100644
index 000000000..d1c39adf8
--- /dev/null
+++ b/tests/unit/test_browser_action_preflight.py
@@ -0,0 +1,1214 @@
+"""Observation epochs and batch/action preflight wiring (SKY-12874).
+
+Every test here is written to fail when the thing it guards is *removed*, not merely to pass while
+it is present. Where that means asserting an ordering, the spy raises so the test can prove nothing
+downstream ran; where it means asserting a deny, the request is arranged so the deny can only come
+from the gate under test.
+"""
+
+from __future__ import annotations
+
+import ast
+import gc
+import inspect
+from pathlib import Path
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+from skyvern.config import settings
+from skyvern.forge.agent import ForgeAgent
+from skyvern.forge.sdk import browser_action_preflight as preflight
+from skyvern.forge.sdk.browser_action_policy import (
+ ActionProjection,
+ ActionTarget,
+ AuthorityState,
+ BrowserActionRequest,
+ PolicyOutcome,
+ PolicyReason,
+ RuntimeOriginAuthority,
+ declare_origin,
+ declare_policy,
+)
+from skyvern.forge.sdk.browser_action_preflight import (
+ advance_observation_epoch,
+ observed_page,
+ preflight_action,
+ preflight_batch,
+ preflight_derived_action,
+ stamp_parsed_actions,
+)
+from skyvern.forge.sdk.core import skyvern_context
+from skyvern.forge.sdk.core.skyvern_context import SkyvernContext
+from skyvern.webeye.actions import actions as action_models
+from skyvern.webeye.actions.action_types import ActionType
+from skyvern.webeye.actions.handler import ActionHandler
+
+HOME = "https://example.com/start"
+OWNER = "wr_12874"
+POLICY = declare_policy(owner_id=OWNER, origin_urls=[HOME])
+ESTABLISHED = RuntimeOriginAuthority(state=AuthorityState.ESTABLISHED, origins=POLICY.allowed_origins)
+
+# Every action model that takes no required argument, so the surviving set can be measured rather
+# than asserted from memory.
+CONCRETE_ACTIONS_FOR_SURVIVAL = (
+ action_models.WaitAction,
+ action_models.ScrollAction,
+ action_models.MoveAction,
+ action_models.NullAction,
+ action_models.GoBackAction,
+ action_models.GoForwardAction,
+ action_models.ClosePageAction,
+ action_models.ReloadPageAction,
+ action_models.TerminateAction,
+ action_models.CompleteAction,
+ action_models.ExtractAction,
+ action_models.SolveCaptchaAction,
+ lambda: action_models.HoverAction(element_id="1"),
+ lambda: action_models.ClickAction(element_id="1"),
+ lambda: action_models.SwitchTabAction(tab_index=0),
+ lambda: action_models.GotoUrlAction(url=HOME),
+)
+
+
+class FakePage:
+ """Just enough Page for the preflight: a URL, a main frame and an event registry.
+
+ The registry is real rather than a MagicMock so listener leaks are observable — a mock would
+ happily record a thousand registrations and assert nothing.
+ """
+
+ def __init__(self, url: str = HOME) -> None:
+ self.url = url
+ self.main_frame = MagicMock()
+ self.main_frame.url = url
+ self.listeners: dict[str, list] = {}
+ self.closed = False
+
+ def is_closed(self) -> bool:
+ return self.closed
+
+ def close(self) -> None:
+ """Playwright keeps serving the cached url and main_frame.url after close; it does not
+ raise. A fake that raised here would be more hostile than reality in the one way that
+ hides a closed page reading as observable."""
+ self.closed = True
+
+ def on(self, event: str, handler) -> None:
+ self.listeners.setdefault(event, []).append(handler)
+
+ def remove_listener(self, event: str, handler) -> None:
+ self.listeners.get(event, []).remove(handler)
+
+ def navigate_to(self, url: str) -> None:
+ """A cross-document navigation, which IS observable: the main-frame URL changes."""
+ self.url = url
+ self.main_frame.url = url
+
+
+class ExplodingPage(FakePage):
+ """A page whose `url` raises. Not what closing looks like — see FakePage.close — but a stand-in
+ for any unexpected fault inside the preflight, which must never escape."""
+
+ def __getattribute__(self, name: str):
+ if name == "url":
+ raise RuntimeError("boom")
+ return object.__getattribute__(self, name)
+
+
[email protected](autouse=True)
+def observing(monkeypatch: pytest.MonkeyPatch):
+ monkeypatch.setattr(settings, "BROWSER_ACTION_POLICY_MODE", "observe")
+ context = SkyvernContext(request_id="req_12874", browser_action_policy=POLICY)
+ skyvern_context.set(context)
+ try:
+ yield context
+ finally:
+ skyvern_context.reset()
+
+
+def scrape(page: FakePage, context: SkyvernContext, *, hashes: tuple[str, ...] = ("h1", "h2")) -> None:
+ advance_observation_epoch(page, main_frame_url=page.main_frame.url, element_hashes=hashes)
+
+
+class TestObservationEpochs:
+ def test_each_accepted_scrape_advances_the_epoch(self, observing: SkyvernContext) -> None:
+ page = FakePage()
+ assert observing.browser_observation_epoch is None
+ scrape(page, observing)
+ assert observing.browser_observation_epoch is not None
+ assert observing.browser_observation_epoch.epoch == 1
+ scrape(page, observing)
+ assert observing.browser_observation_epoch.epoch == 2
+
+ def test_the_epoch_is_bound_to_the_scraped_element_hashes(self, observing: SkyvernContext) -> None:
+ page = FakePage()
+ scrape(page, observing, hashes=("h1", "h2"))
+ first = observing.browser_observation_epoch
+ scrape(page, observing, hashes=("h1", "h3"))
+ second = observing.browser_observation_epoch
+ assert first is not None and second is not None
+ assert first.element_digest != second.element_digest
+
+ def test_hash_order_does_not_change_the_binding(self, observing: SkyvernContext) -> None:
+ page = FakePage()
+ scrape(page, observing, hashes=("h1", "h2"))
+ first = observing.browser_observation_epoch
+ scrape(page, observing, hashes=("h2", "h1"))
+ second = observing.browser_observation_epoch
+ assert first is not None and second is not None
+ assert first.element_digest == second.element_digest
+
+ def test_the_epoch_is_bound_to_the_page_it_observed(self, observing: SkyvernContext) -> None:
+ observed, other = FakePage(), FakePage()
+ scrape(observed, observing)
+ action = action_models.ClickAction(element_id="1")
+ stamp_parsed_actions([action])
+ decision = preflight_action(action, other, site="test")
+ assert decision is not None
+ # Another tab's observation vouches for nothing on this one.
+ assert PolicyReason.MISSING_PAGE_EVIDENCE in decision.reasons
+
+ def test_navigation_since_the_scrape_invalidates_the_observation(self, observing: SkyvernContext) -> None:
+ page = FakePage()
+ scrape(page, observing)
+ action = action_models.ClickAction(element_id="1")
+ stamp_parsed_actions([action])
+ page.main_frame.url = "https://example.com/somewhere-else"
+ decision = preflight_action(action, page, site="test")
+ assert decision is not None
+ assert PolicyReason.MISSING_PAGE_EVIDENCE in decision.reasons
+
+ def test_an_action_planned_under_an_older_scrape_is_stale(self, observing: SkyvernContext) -> None:
+ page = FakePage()
+ scrape(page, observing)
+ action = action_models.ClickAction(element_id="1")
+ stamp_parsed_actions([action])
+ scrape(page, observing)
+ decision = preflight_action(action, page, site="test")
+ assert decision is not None
+ assert PolicyReason.STALE_PAGE_EVIDENCE in decision.reasons
+
+ def test_an_unstamped_action_carries_no_observation(self, observing: SkyvernContext) -> None:
+ page = FakePage()
+ scrape(page, observing)
+ decision = preflight_action(action_models.ClickAction(element_id="1"), page, site="test")
+ assert decision is not None
+ assert PolicyReason.MISSING_PAGE_EVIDENCE in decision.reasons
+
+ def test_a_closed_page_is_not_observable(self, observing: SkyvernContext) -> None:
+ # Playwright serves url and main_frame.url from cache after close, so every other check
+ # here still passes on a page that no longer exists.
+ page = FakePage()
+ scrape(page, observing)
+ action = action_models.ClickAction(element_id="1")
+ stamp_parsed_actions([action])
+ assert PolicyReason.MISSING_PAGE_EVIDENCE not in preflight_action(action, page, site="test").reasons
+
+ page.close()
+
+ decision = preflight_action(action, page, site="test")
+ assert decision is not None
+ assert PolicyReason.MISSING_PAGE_EVIDENCE in decision.reasons
+
+ def test_a_closed_page_still_reports_its_cached_url(self) -> None:
+ # Pins the fake to the real object's behaviour. If this ever starts raising, the fake has
+ # drifted more hostile than Playwright and will hide the bug above all over again.
+ page = FakePage()
+ page.close()
+ assert page.url == HOME
+ assert page.main_frame.url == HOME
+ assert page.is_closed() is True
+
+ def test_nothing_is_observed_while_the_mode_is_disabled(
+ self, observing: SkyvernContext, monkeypatch: pytest.MonkeyPatch
+ ) -> None:
+ monkeypatch.setattr(settings, "BROWSER_ACTION_POLICY_MODE", "disabled")
+ page = FakePage()
+ scrape(page, observing)
+ assert observing.browser_observation_epoch is None
+ assert preflight_action(action_models.ClickAction(element_id="1"), page, site="test") is None
+
+
+class TestTheScrapeAdvancesTheEpoch:
+ """AC1. Every test above calls ``advance_observation_epoch`` directly, so on their own they
+ prove the epoch machinery works and nothing about whether a scrape ever reaches it."""
+
+ def test_an_accepted_scrape_is_what_advances_it(self) -> None:
+ source = ast.parse(Path("skyvern/webeye/scraper/scraper.py").read_text())
+ advancing = {
+ node.name
+ for node in ast.walk(source)
+ if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef))
+ and any(
+ isinstance(call, ast.Call)
+ and isinstance(call.func, ast.Name)
+ and call.func.id == "advance_observation_epoch"
+ for call in ast.walk(node)
+ )
+ }
+ # Named, not merely non-empty: the retry wrapper `scrape_website` recurses, so advancing
+ # there would count one accepted scrape twice.
+ assert advancing == {"scrape_web_unsafe"}
+
+ def test_it_advances_once_per_accepted_scrape(self, observing: SkyvernContext) -> None:
+ # The wrapper returns the inner result rather than re-deriving one, so a retried scrape must
+ # still land on a single epoch.
+ page = FakePage()
+ scrape(page, observing)
+ assert observing.browser_observation_epoch is not None
+ assert observing.browser_observation_epoch.epoch == 1
+
+
+class TestStampingHappensAtTheParsePoint:
+ """F2. prepare_step_execution can build an action BEFORE the step scrape runs. Stamping the
+ whole batch later handed such an action provenance for an observation it predates."""
+
+ @staticmethod
+ async def _generate(injected: list | None, parsed, *, extraction: bool = True, otp=None) -> list:
+ async def fake_extract(*_a, **_k):
+ return parsed
+
+ async def no_otp(*_a, **_k):
+ return {}, []
+
+ agent = MagicMock()
+ agent.create_extract_action = fake_extract
+ agent.handle_potential_OTP_actions = otp or no_otp
+ scraped = MagicMock()
+ scraped.check_pdf_viewer_embed.return_value = None
+ scraped.check_pdf_iframe = AsyncMock(return_value=None)
+ task = MagicMock()
+ task.navigation_payload = {}
+ task.navigation_goal = "goal"
+ task.llm_key = None
+ task.totp_verification_url = None
+ task.totp_identifier = None
+ task.organization_id = "o"
+ task.workflow_run_id = "wr"
+ task.task_id = "tsk"
+ llm = AsyncMock(return_value={"actions": []})
+ with (
+ patch.object(ForgeAgent, "create_extract_action", fake_extract),
+ patch("skyvern.forge.agent.LLMAPIHandlerFactory.get_override_llm_api_handler", return_value=llm),
+ ):
+ actions, _, _ = await ForgeAgent._generate_step_actions(
+ agent,
+ task=task,
+ step=MagicMock(),
+ browser_state=MagicMock(),
+ engine=MagicMock(),
+ scraped_page=scraped,
+ detailed_agent_step_output=MagicMock(),
+ injected_actions=injected,
+ is_extraction_task=extraction,
+ prefetched_summary_task=None,
+ cua_response=None,
+ llm_caller=None,
+ extract_action_prompt="",
+ prompt_name="",
+ use_caching=False,
+ without_page_information=False,
+ json_response=None,
+ reuse_speculative_llm_response=False,
+ speculative_llm_metadata=None,
+ context=None,
+ )
+ return actions
+
+ @pytest.mark.asyncio
+ async def test_an_action_injected_before_the_scrape_is_never_stamped(self, observing: SkyvernContext) -> None:
+ scrape(FakePage(), observing)
+ injected = action_models.SolveCaptchaAction()
+ actions = await self._generate([injected], None)
+ assert actions == [injected]
+ assert injected.observation_epoch is None
+ assert injected.observation_digest is None
+
+ @pytest.mark.asyncio
+ async def test_a_runtime_derived_otp_action_is_never_stamped(self, observing: SkyvernContext) -> None:
+ # The magic-link path: polling supplies a link, browser_state.new_page() opens a page nobody
+ # has scraped, and the code synthesizes a GotoUrlAction — all with injected_actions None, so
+ # a blanket end-of-method stamp reached it. Provenance for a page that was never observed.
+ scrape(FakePage(), observing)
+ otp_action = action_models.GotoUrlAction(url="https://mail.example/magic-link")
+
+ async def fake_otp(*_a, **_k):
+ return {}, [otp_action]
+
+ actions = await self._generate(None, None, extraction=False, otp=fake_otp)
+ assert actions == [otp_action]
+ assert otp_action.observation_epoch is None
+ assert otp_action.observation_digest is None
+
+ @pytest.mark.asyncio
+ async def test_a_scraped_verification_code_action_is_stamped(self, observing: SkyvernContext) -> None:
+ # The mirror image of the OTP test above, and it shares that return path. When the model
+ # asks for a verification code, handle_potential_verification_code re-prompts from the
+ # CURRENT scraped page and parse_actions builds from it — genuinely scrape-derived. Leaving
+ # it unstamped is fail-closed but wrong: observe telemetry lies, and under enforcement a
+ # valid TOTP step would be blocked.
+ scrape(FakePage(), observing)
+ epoch = observing.browser_observation_epoch
+ assert epoch is not None
+ parsed = action_models.InputTextAction(element_id="1", text="123456")
+
+ agent = MagicMock()
+ agent.handle_potential_verification_code = AsyncMock(return_value={"actions": []})
+ task = MagicMock()
+ task.organization_id = "o"
+ task.totp_identifier = "id"
+ task.totp_verification_url = None
+
+ with patch("skyvern.forge.agent.parse_actions", return_value=[parsed]):
+ _, actions = await ForgeAgent.handle_potential_OTP_actions(
+ agent,
+ task,
+ MagicMock(),
+ MagicMock(),
+ MagicMock(),
+ {"place_to_enter_verification_code": True, "should_enter_verification_code": True},
+ )
+
+ assert actions == [parsed]
+ assert parsed.observation_epoch == epoch.epoch
+ assert parsed.observation_digest == epoch.element_digest
+
+ @pytest.mark.asyncio
+ async def test_a_magic_link_action_from_the_same_return_path_stays_unstamped(
+ self, observing: SkyvernContext
+ ) -> None:
+ # The twin that makes the test above mean something: same method, same tuple shape, opposite
+ # outcome. A fix that stamped the shared return would pass the test above and fail this one.
+ scrape(FakePage(), observing)
+ magic_link = action_models.GotoUrlAction(url="https://mail.example/magic-link")
+
+ agent = MagicMock()
+ agent.handle_potential_magic_link = AsyncMock(return_value=[magic_link])
+ task = MagicMock()
+ task.organization_id = "o"
+ task.totp_identifier = "id"
+ task.totp_verification_url = None
+
+ _, actions = await ForgeAgent.handle_potential_OTP_actions(
+ agent, task, MagicMock(), MagicMock(), MagicMock(), {"should_verify_by_magic_link": True}
+ )
+
+ assert actions == [magic_link]
+ assert magic_link.observation_epoch is None
+ assert magic_link.observation_digest is None
+
+ @pytest.mark.asyncio
+ async def test_an_action_parsed_from_the_scrape_is_stamped(self, observing: SkyvernContext) -> None:
+ # The twin. Without it every test above passes against an implementation that never stamps.
+ scrape(FakePage(), observing)
+ epoch = observing.browser_observation_epoch
+ assert epoch is not None
+ parsed = action_models.ExtractAction()
+ actions = await self._generate(None, parsed)
+ assert actions == [parsed]
+ assert parsed.observation_epoch == epoch.epoch
+ assert parsed.observation_digest == epoch.element_digest
+
+ @pytest.mark.asyncio
+ async def test_the_llm_parse_branch_is_stamped(self, observing: SkyvernContext) -> None:
+ # The other twin, on the branch the OTP test shares: same code path, opposite outcome.
+ scrape(FakePage(), observing)
+ epoch = observing.browser_observation_epoch
+ assert epoch is not None
+ parsed = action_models.ClickAction(element_id="1")
+ with patch("skyvern.forge.agent.parse_actions", return_value=[parsed]):
+ actions = await self._generate(None, None, extraction=False)
+ assert actions == [parsed]
+ assert parsed.observation_epoch == epoch.epoch
+ assert parsed.observation_digest == epoch.element_digest
+
+
+class TestObserveModeIsAPureObserver:
+ """F1. must_get_working_page is not a getter — it re-pins the working page and, via
+ list_valid_pages, closes over-limit tabs. Observe mode reaching it made observe diverge from
+ disabled. These test the invariant, not that one call."""
+
+ STATE_CHANGING = {
+ "must_get_working_page",
+ "get_working_page",
+ "set_working_page",
+ "set_active_page",
+ "list_valid_pages",
+ "reload_page",
+ "navigate_to_url",
+ "close",
+ "goto",
+ "bring_to_front",
+ "evaluate",
+ }
+
+ def test_the_preflight_module_calls_nothing_state_changing(self) -> None:
+ tree = ast.parse(Path("skyvern/forge/sdk/browser_action_preflight.py").read_text())
+ called = {
+ node.func.attr
+ for node in ast.walk(tree)
+ if isinstance(node, ast.Call) and isinstance(node.func, ast.Attribute)
+ }
+ assert called, "found no calls at all — the scan is broken, not the module"
+ assert not called & self.STATE_CHANGING
+
+ def test_no_preflight_call_site_hands_over_browser_state(self) -> None:
+ # The reviewer found F1 by behaviour rather than by diff, so this sweeps every site rather
+ # than the one that was wrong.
+ offenders = []
+ for path in ("skyvern/forge/agent.py", "skyvern/webeye/actions/handler.py"):
+ tree = ast.parse(Path(path).read_text())
+ for node in ast.walk(tree):
+ if not isinstance(node, ast.Call) or not isinstance(node.func, ast.Name):
+ continue
+ if not node.func.id.startswith("preflight_"):
+ continue
+ rendered = " ".join(ast.unparse(arg) for arg in node.args)
+ if "browser_state" in rendered or "working_page" in rendered:
+ offenders.append((path, ast.unparse(node)))
+ assert offenders == []
+
+ def test_the_preflight_only_reads_the_page(self, observing: SkyvernContext) -> None:
+ reads: list[str] = []
+
+ internals = {"listeners", "on", "remove_listener", "navigate_to", "closed", "close"}
+
+ class RecordingPage(FakePage):
+ def __getattribute__(self, name: str):
+ if not name.startswith("_") and name not in internals:
+ reads.append(name)
+ return object.__getattribute__(self, name)
+
+ page = RecordingPage()
+ scrape(page, observing)
+ action = action_models.ClickAction(element_id="1")
+ stamp_parsed_actions([action])
+ reads.clear()
+ preflight_action(action, page, site="test")
+ # url, main_frame and is_closed are read-only queries — observation. Anything else is the
+ # page being steered. This list is the whole permission set, so an addition shows up here
+ # and has to be justified rather than slipping in.
+ assert set(reads) <= {"url", "main_frame", "is_closed"}
+
+
+class TestContentFreshnessIsNotClaimed:
+ """A page can replace its own content with document.write or innerHTML while the page object,
+ the URL and the epoch all stay fixed, and Chromium emits NO navigation event for either. An
+ earlier revision watched framenavigated here; a real browser never fires it for these cases, so
+ it advertised coverage it did not have — and the unit test that "proved" it worked was firing
+ the event itself, which tested the handler rather than the signal's existence.
+
+ Nothing below simulates any signal. The page is mutated exactly as a real page mutates itself:
+ invisibly. These tests pin what actually happens as a result.
+ """
+
+ @staticmethod
+ def replace_document(page: FakePage) -> None:
+ """What document.write or innerHTML= looks like from outside: nothing observable changes."""
+
+ def test_a_same_document_replacement_is_not_detectable(self, observing: SkyvernContext) -> None:
+ # A documentation lock rather than a guard: it fails if someone adds detection, forcing the
+ # claims in _live_observation and the PR to be updated with it.
+ page = FakePage()
+ scrape(page, observing)
+ action = action_models.ClickAction(element_id="1")
+ stamp_parsed_actions([action])
+ before = preflight_action(action, page, site="test")
+
+ self.replace_document(page)
+
+ after = preflight_action(action, page, site="test")
+ assert before is not None and after is not None
+ # Stated, not hidden: provenance cannot see this, and a test claiming otherwise would be
+ # simulating a signal the browser does not emit.
+ assert after.reasons == before.reasons
+
+ def test_a_content_dependent_action_denies_anyway(self, observing: SkyvernContext) -> None:
+ """The guarantee that survives: content trust rides the verdict axis, not the epoch, so an
+ action whose safety depends on what the page says is denied whether or not the page was
+ swapped underneath it.
+
+ This is also a tripwire — see test_no_verdict_source_exists_yet for the half that binds it
+ to production. On its own this assertion would go stale silently: the helper advances its
+ own epoch and supplies no scanner result, so if production later took a verdict and passed
+ NO_MATCH, the fake would keep supplying UNKNOWN and this would stay green forever.
+ """
+ page = FakePage()
+ scrape(page, observing)
+ for action in (
+ action_models.ClickAction(element_id="1"),
+ action_models.InputTextAction(element_id="1", text="x"),
+ action_models.ExtractAction(),
+ action_models.GotoUrlAction(url=HOME),
+ ):
+ stamp_parsed_actions([action])
+ self.replace_document(page)
+ decision = preflight_action(action, page, site="test")
+ assert decision is not None, action.action_type
+ assert decision.outcome is PolicyOutcome.DENIED, action.action_type
+ assert PolicyReason.UNVERIFIED_OBSERVATION in decision.reasons, action.action_type
+
+ def test_only_the_recovery_set_survives_a_replaced_document(self, observing: SkyvernContext) -> None:
+ # ADR-0011 keeps read-only and recovery actions available so a run can stop safely, and a
+ # DOM swap does not make "wait" or "terminate" unsafe. This pins the exact surviving set so
+ # nobody widens it by accident.
+ page = FakePage()
+ scrape(page, observing)
+ allowed = []
+ for model in CONCRETE_ACTIONS_FOR_SURVIVAL:
+ action = model()
+ stamp_parsed_actions([action])
+ self.replace_document(page)
+ decision = preflight_action(action, page, site="test")
+ if decision is not None and decision.outcome is PolicyOutcome.ALLOWED:
+ allowed.append(action.action_type)
+ assert set(allowed) == {
+ ActionType.WAIT,
+ ActionType.SCROLL,
+ ActionType.MOVE,
+ ActionType.HOVER,
+ ActionType.NULL_ACTION,
+ ActionType.GO_BACK,
+ ActionType.CLOSE_PAGE,
+ ActionType.SWITCH_TAB,
+ ActionType.TERMINATE,
+ ActionType.COMPLETE,
+ }
+
+ def test_the_two_direct_verdict_seams_are_still_empty(self) -> None:
+ """Watches the two DIRECT seams a scanner would touch, and claims nothing beyond them.
+
+ The test above proves today's UNKNOWN behaviour through a fake epoch, which will keep
+ supplying UNKNOWN no matter what production does. These assertions instead read production:
+ the observation source takes no verdict, and the verdict in _live_observation is a literal.
+
+ *** WHAT THIS DOES NOT COVER. *** A scanner that arrives by any other route — wrapping or
+ replacing the observation after _live_observation returns, or setting the verdict further
+ downstream — leaves both assertions true and this test green. Pinning an arbitrary future
+ change is not achievable, and three attempts at widening this only implied coverage it did
+ not have. So: when SKY-12526's scanner lands, the undetectable same-document replacement gap
+ described on this class must be RE-DECIDED deliberately. It must not be assumed handled
+ because this test still passes.
+ """
+ assert "verdict" not in inspect.signature(advance_observation_epoch).parameters
+
+ source = ast.parse(Path("skyvern/forge/sdk/browser_action_preflight.py").read_text())
+ observation = next(
+ node for node in ast.walk(source) if isinstance(node, ast.FunctionDef) and node.name == "_live_observation"
+ )
+ verdicts = [
+ ast.unparse(keyword.value)
+ for node in ast.walk(observation)
+ if isinstance(node, ast.Call)
+ for keyword in node.keywords
+ if keyword.arg == "verdict"
+ ]
+ assert verdicts == ["ObservationVerdict.UNKNOWN"]
+
+ def test_the_epoch_does_not_keep_the_page_alive(self, observing: SkyvernContext) -> None:
+ # The weakref is the liveness signal; anything capturing the page strongly would defeat it.
+ page = FakePage()
+ scrape(page, observing)
+ epoch = observing.browser_observation_epoch
+ assert epoch is not None and epoch.page is not None
+ del page
+ gc.collect()
+ assert epoch.page() is None
+ assert observed_page() is None
+
+ def test_nothing_registers_a_listener_on_the_page(self, observing: SkyvernContext) -> None:
+ # A listener is per-page state that outlives the run context that created it, so it leaks
+ # across contexts on a persistent page. The module registers none.
+ page = FakePage()
+ for _ in range(5):
+ scrape(page, observing)
+ preflight_action(action_models.ClickAction(element_id="1"), page, site="test")
+ assert page.listeners == {}
+
+
+class TestContentBoundProvenance:
+ """F3. The epoch counter is positional; a stray integer can match it by luck. The digest cannot."""
+
+ def test_an_epoch_that_matches_by_value_alone_is_not_provenance(self, observing: SkyvernContext) -> None:
+ page = FakePage()
+ scrape(page, observing)
+ epoch = observing.browser_observation_epoch
+ assert epoch is not None
+
+ # Exactly the rehydrated-integer collision: the number is right, the observation is not.
+ action = action_models.ClickAction(element_id="1")
+ action.observation_epoch = epoch.epoch
+
+ decision = preflight_action(action, page, site="test")
+ assert decision is not None
+ assert PolicyReason.MISSING_PAGE_EVIDENCE in decision.reasons
+
+ def test_a_correctly_stamped_action_is_accepted(self, observing: SkyvernContext) -> None:
+ # The twin: without it the test above could be passing for an unrelated reason.
+ page = FakePage()
+ scrape(page, observing)
+ action = action_models.ClickAction(element_id="1")
+ stamp_parsed_actions([action])
+ decision = preflight_action(action, page, site="test")
+ assert decision is not None
+ assert PolicyReason.MISSING_PAGE_EVIDENCE not in decision.reasons
+ assert PolicyReason.STALE_PAGE_EVIDENCE not in decision.reasons
+
+
+class TestInternalFailuresAreVisible:
+ """Swallowing is required — observe mode may never change execution — but silence is not, and
+ neither is a decision line that is safe on only one of its two emitters."""
+
+ def test_a_swallowed_failure_still_emits_a_decision_event(self, observing: SkyvernContext) -> None:
+ page = FakePage()
+ scrape(page, observing)
+ emitted: list[dict] = []
+ with patch.object(preflight.LOG, "warning", lambda _event, **kwargs: emitted.append(kwargs)):
+ with patch("skyvern.forge.sdk.browser_action_preflight.decide_browser_action", side_effect=RuntimeError):
+ assert preflight_action(action_models.ClickAction(element_id="1"), page, site="test") is None
+ assert len(emitted) == 1
+ assert emitted[0]["outcome"] == preflight.INTERNAL_ERROR_OUTCOME
+ assert emitted[0]["error_type"] == "RuntimeError"
+ # Still enough to find the fault: source identifiers, which are code and not data.
+ assert emitted[0]["error_location"].endswith(":preflight_action") or ".py:" in emitted[0]["error_location"]
+
+ def test_an_exception_message_never_reaches_a_decision_line(self, observing: SkyvernContext) -> None:
+ """An exception's text is arbitrary and routinely carries the data it choked on.
+
+ This is the internal-fault sink, which is a SECOND emitter of the decision event. AC8 was
+ verified on the normal emitter alone, and a guarantee that holds on one of two sinks is not
+ a guarantee.
+ """
+ page = FakePage()
+ scrape(page, observing)
+ secret = "https://example.test/p?signature=SECRETVALUE9"
+ emitted: list[dict] = []
+ with patch.object(preflight.LOG, "warning", lambda event, **kwargs: emitted.append({"event": event, **kwargs})):
+ with patch(
+ "skyvern.forge.sdk.browser_action_preflight.decide_browser_action",
+ side_effect=RuntimeError(f"failed {secret}"),
+ ):
+ preflight_action(action_models.ClickAction(element_id="1"), page, site="test")
+ assert len(emitted) == 1
+ assert "SECRETVALUE9" not in repr(emitted[0])
+ # exc_info would format the exception text downstream of anything this module controls.
+ assert "exc_info" not in emitted[0]
+
+ # Every argument expression any LOG call in this module is permitted to pass. This is the whole
+ # permitted set: anything not listed fails, including expressions that look harmless. Adding a
+ # field to a log line therefore requires a human to add it here and say why.
+ #
+ # An ALLOWLIST because three previous versions of this check were name-matchers and each one was
+ # evaded by a name a future edit was free to choose differently: a key allowlist in the
+ # redactor, then event-name scoping that missed two sibling sinks, then variable-name matching
+ # that missed `exc`, one hop of indirection, and LOG.exception's implicit exc_info. Following
+ # the value rather than hunting for forbidden names is the same fix, applied to the test.
+ PERMITTED_LOG_ARGUMENTS = {
+ "DECISION_EVENT",
+ "INTERNAL_ERROR_OUTCOME",
+ "'Failed to advance the browser action observation epoch'",
+ "'Failed to stamp actions with an observation epoch'",
+ "site",
+ "[]",
+ "[reason.value for reason in decision.reasons]",
+ "decision.outcome.value",
+ "action.action_type",
+ "action.observation_epoch",
+ "None if observation is None else observation.observation_epoch",
+ "None if origin is None else origin.canonical",
+ "type(error).__name__",
+ "_error_location(error)",
+ }
+ # info and warning take exc_info only when asked. LOG.exception supplies it IMPLICITLY, which is
+ # why it is barred outright rather than checked for a kwarg — swapping warning for exception in
+ # a handler is a one-word edit that reads as harmless.
+ PERMITTED_LOG_METHODS = {"info", "warning"}
+ LOG_CALL_COUNT = 4
+
+ @staticmethod
+ def _log_calls() -> list:
+ source = ast.parse(Path("skyvern/forge/sdk/browser_action_preflight.py").read_text())
+ return [
+ node
+ for node in ast.walk(source)
+ if isinstance(node, ast.Call)
+ and isinstance(node.func, ast.Attribute)
+ and isinstance(node.func.value, ast.Name)
+ and node.func.value.id == "LOG"
+ ]
+
+ def test_every_log_argument_in_the_module_is_on_the_allowlist(self) -> None:
+ """A regression guard over the direct call shape. NOT a proof that leaking is impossible.
+
+ CAUGHT: a denylist of {exc_info, error=} missed `error_type=str(error)`; before that the
+ check was scoped to one event name and missed two sibling sinks entirely.
+
+ *** WHAT IT DOES CATCH, verified by mutation rather than claimed. *** Every one of these was
+ run against it and failed the suite: `exc_info=True` restored at any of the three fault
+ sinks; an exception passed positionally; passed as `error=error`; stringified as
+ `str(error)`; stringified as `repr(error)` one hop away; `str(exc)` under a different
+ variable name; `LOG.exception` in place of `LOG.warning`; `getattr(LOG, "warning")`; a fifth
+ LOG call appearing anywhere in the module; and the event string inlined at an emitter to
+ escape a name-scoped scan. It also failed on its own first version, where a substring check
+ for `LOG.exception` matched the comment explaining why `LOG.exception` is barred.
+
+ *** WHAT THIS DOES NOT CATCH. *** It records each argument's VALUE expression, not the
+ keyword it was passed under, and it only sees `LOG.<method>(...)` written literally in this
+ module. All four of these defeat it and were confirmed to defeat it:
+
+ * a permitted value passed under a dangerous keyword — `exc_info=DECISION_EVENT`, which
+ structlog reads as a truthy request for the active traceback;
+ * a logger alias — `AUDIT = LOG` then `AUDIT.exception(...)`;
+ * a second logger from `structlog.get_logger()` inside a module helper;
+ * logging delegated to a helper in another module.
+
+ This is the fourth iteration of this check. The first three were beaten by a key name, an
+ event name and a variable name, each fix correct and each defeated one order up — so the
+ claim stops growing here rather than inviting a fifth version for a third-order trick. A
+ guard that states its limits beats one that advertises coverage it lacks.
+
+ THE LOAD-BEARING ASSURANCE IS ELSEWHERE: the four committed emitters are verified safe by
+ behavioural probes against the real JSON pipeline, not by this scan. Full static enforcement
+ is a follow-up ticket.
+ """
+ calls = self._log_calls()
+ assert len(calls) == self.LOG_CALL_COUNT, "LOG call count changed — the scan or the module did"
+ used = set()
+ for call in calls:
+ for argument in list(call.args) + [keyword.value for keyword in call.keywords]:
+ used.add(ast.unparse(argument))
+ assert used <= self.PERMITTED_LOG_ARGUMENTS, used - self.PERMITTED_LOG_ARGUMENTS
+
+ def test_no_log_method_that_carries_a_traceback_implicitly(self) -> None:
+ """CAUGHT: LOG.exception passes exc_info without naming it, so a kwarg check never sees it."""
+ source = ast.parse(Path("skyvern/forge/sdk/browser_action_preflight.py").read_text())
+ # Structural, not a substring scan: a comment mentioning LOG.exception is not a call, and a
+ # text match on it fails on this module's own documentation. That is the same fragility this
+ # test exists to guard against, one level up.
+ attributes = {
+ node.attr
+ for node in ast.walk(source)
+ if isinstance(node, ast.Attribute) and isinstance(node.value, ast.Name) and node.value.id == "LOG"
+ }
+ assert attributes <= self.PERMITTED_LOG_METHODS, attributes - self.PERMITTED_LOG_METHODS
+ # An alias or a dynamic lookup would move the call out of the AST shape scanned above.
+ lookups = [
+ node
+ for node in ast.walk(source)
+ if isinstance(node, ast.Call)
+ and isinstance(node.func, ast.Name)
+ and node.func.id == "getattr"
+ and any(isinstance(arg, ast.Name) and arg.id == "LOG" for arg in node.args)
+ ]
+ assert lookups == []
+
+ def test_the_module_has_no_other_way_to_emit(self) -> None:
+ """Pins today's emission surface: the scans above see `LOG.<method>(...)` and nothing else.
+
+ Narrow by construction — it checks imports, assignments and `print`, so it catches a stdlib
+ logger or a `warnings` call appearing, and does NOT catch an alias of the existing LOG or a
+ `structlog.get_logger()` helper. See the allowlist test above for the full boundary.
+ """
+ source = ast.parse(Path("skyvern/forge/sdk/browser_action_preflight.py").read_text())
+ imported = {
+ alias.name.split(".")[0]
+ for node in ast.walk(source)
+ if isinstance(node, (ast.Import, ast.ImportFrom))
+ for alias in node.names
+ }
+ assert not imported & {"logging", "warnings", "sys", "traceback", "linecache"}
+ assignments = {
+ target.id
+ for node in ast.walk(source)
+ if isinstance(node, ast.Assign)
+ for target in node.targets
+ if isinstance(target, ast.Name)
+ }
+ assert "LOG" in assignments
+ text = Path("skyvern/forge/sdk/browser_action_preflight.py").read_text()
+ assert "print(" not in text
+
+ def test_the_decision_event_has_more_than_one_emitter_and_all_are_covered(self) -> None:
+ """CAUGHT: AC8 was verified on the decision sink while a second, unsafe emitter of the same
+ event sat beside it.
+
+ The weakest of the three and deliberately kept. Its non-vacuity role is now covered by the
+ module-wide allowlist above, which does not depend on the event name; what survives is an
+ executable record that this event has more than one emitter, so the next person verifying
+ "the decision line is safe" checks all of them rather than the one they are looking at.
+ """
+ emitters = [
+ call for call in self._log_calls() if any(ast.unparse(arg) == "DECISION_EVENT" for arg in call.args)
+ ]
+ assert len(emitters) >= 2, "expected the decision and internal-fault sinks — the scan is broken"
+
+ def test_the_event_string_cannot_be_inlined_to_escape_the_scan(self) -> None:
+ """CAUGHT: inlining the literal at an emitter escapes any name-scoped scan.
+
+ Independently useful beyond leak-safety: one source for the event name means every emitter
+ is findable by grepping a single constant, which is what would have surfaced the second sink
+ immediately instead of several review rounds later.
+ """
+ source = Path("skyvern/forge/sdk/browser_action_preflight.py").read_text()
+ assert source.count('"Browser action policy decision"') == 1
+
+ def test_the_error_path_cannot_itself_raise(self, observing: SkyvernContext) -> None:
+ """The error path needed its own error path tested.
+
+ The battery proved exception TEXT cannot reach a log; nothing proved the code that formats
+ the fault cannot raise out of the handler that must swallow it. `_error_location` used
+ traceback.extract_tb, which resolves source lines through linecache and can invoke a module
+ loader whose failure it does not catch — so the helper added to make the error path safe
+ could end the caller while handling an internal fault.
+ """
+ page = FakePage()
+ scrape(page, observing)
+ action = action_models.ClickAction(element_id="1")
+ stamp_parsed_actions([action])
+ with patch.object(preflight, "_error_location", side_effect=RuntimeError("helper exploded")):
+ with patch.object(preflight, "decide_browser_action", side_effect=RuntimeError("inner")):
+ assert preflight_action(action, page, site="test") is None
+
+ def test_the_location_helper_never_raises_whatever_it_is_handed(self) -> None:
+ class Hostile(Exception):
+ @property
+ def __traceback__(self): # type: ignore[override]
+ raise RuntimeError("boom")
+
+ assert preflight._error_location(Hostile()) is None
+ assert preflight._error_location(ValueError("no traceback")) is None
+
+ def test_an_authority_of_none_is_rejected_at_construction(self) -> None:
+ # Omission already raised. This is the other way in.
+ with pytest.raises(TypeError):
+ BrowserActionRequest(
+ policy=POLICY,
+ projection=ActionProjection(action_type=None, action_class=None, target=ActionTarget()),
+ authority=None, # type: ignore[arg-type]
+ request_epoch=1,
+ )
+
+
+class TestTransientObservationIdentity:
+ def test_a_planned_batch_carries_the_current_epoch(self, observing: SkyvernContext) -> None:
+ page = FakePage()
+ scrape(page, observing)
+ batch = [action_models.ClickAction(element_id="1"), action_models.WaitAction()]
+ stamp_parsed_actions(batch)
+ assert [action.observation_epoch for action in batch] == [1, 1]
+
+ def test_the_observation_epoch_never_reaches_the_persisted_payload(self) -> None:
+ # create_action writes action.model_dump() straight into action_json. An epoch is run-local,
+ # so a value read back from a stored row could collide with a live run's counter and make a
+ # stale action look freshly observed. This is the guard on `exclude=True`.
+ action = action_models.ClickAction(element_id="1")
+ action.observation_epoch = 3
+ assert "observation_epoch" not in action.model_dump()
+ assert "observation_epoch" not in action.model_dump(mode="json")
+ assert action.observation_epoch == 3
+
+ def test_a_derived_action_inherits_its_parent_identity(self, observing: SkyvernContext) -> None:
+ page = FakePage()
+ scrape(page, observing)
+ parent = action_models.ClickAction(element_id="1", file_url=HOME)
+ stamp_parsed_actions([parent])
+ derived = action_models.UploadFileAction(element_id="1", file_url=HOME)
+ preflight_derived_action(derived, page, parent=parent, site="test")
+ assert derived.observation_epoch == parent.observation_epoch
+
+ def test_a_derived_action_is_judged_on_its_own_projection(self, observing: SkyvernContext) -> None:
+ # The whole point of re-projecting: parent and child do not require the same things.
+ page = FakePage()
+ scrape(page, observing)
+ parent = action_models.ClickAction(element_id="1")
+ stamp_parsed_actions([parent])
+ derived = action_models.UploadFileAction(element_id="1", file_url=HOME)
+ decision = preflight_derived_action(derived, page, parent=parent, site="test")
+ assert decision is not None
+ assert PolicyReason.MISSING_PROTECTED_REFERENCE in decision.reasons
+
+
+class TestPolicyObservationIsIndependentOfPromptScanning:
+ def test_observation_runs_with_no_scanner_wired(self, observing: SkyvernContext) -> None:
+ # AC7. No detector exists in this tree, and the policy still gets to look. The verdict it
+ # gets is UNKNOWN, which denies — fail-closed, not silently skipped.
+ page = FakePage()
+ scrape(page, observing)
+ action = action_models.ClickAction(element_id="1")
+ stamp_parsed_actions([action])
+ decision = preflight_action(action, page, site="test")
+ assert decision is not None
+ assert PolicyReason.UNVERIFIED_OBSERVATION in decision.reasons
+
+ def test_an_unenrolled_run_reaches_not_enrolled_and_nothing_else(self, observing: SkyvernContext) -> None:
+ observing.browser_action_policy = None
+ page = FakePage()
+ scrape(page, observing)
+ action = action_models.ClickAction(element_id="1")
+ stamp_parsed_actions([action])
+ decision = preflight_action(action, page, site="test")
+ assert decision is not None
+ assert decision.outcome is PolicyOutcome.NOT_ENROLLED
+
+
+class TestEmptyRuntimeAuthoritySeam:
+ """SKY-12883/12884/12886 fill the authority seam. Until they do it denies, loudly."""
+
+ def test_an_enrolled_run_has_no_runtime_authority_today(self, observing: SkyvernContext) -> None:
+ assert observing.browser_action_authority.state is AuthorityState.UNWIRED
+
+ def test_being_inside_the_enrolled_ceiling_does_not_allow(self, observing: SkyvernContext) -> None:
+ # Page origin IS enrolled and the observation IS current; the only thing left to deny on is
+ # the absent authority. Without those two pins this would pass against any implementation.
+ page = FakePage()
+ scrape(page, observing)
+ action = action_models.GotoUrlAction(url=HOME)
+ stamp_parsed_actions([action])
+ decision = preflight_action(action, page, site="test")
+ assert decision is not None
+ assert decision.outcome is PolicyOutcome.DENIED
+ assert PolicyReason.UNWIRED_RUNTIME_AUTHORITY in decision.reasons
+
+ def test_the_same_action_allows_once_an_authority_exists(self, observing: SkyvernContext) -> None:
+ # The twin. If this fails, the deny above proves nothing about the authority gate.
+ observing.browser_action_authority = ESTABLISHED
+ page = FakePage()
+ scrape(page, observing)
+ action = action_models.GoBackAction()
+ stamp_parsed_actions([action])
+ decision = preflight_action(action, page, site="test")
+ assert decision is not None
+ assert decision.outcome is PolicyOutcome.ALLOWED
+
+
+class TestBatchPreflight:
+ """AC3: the complete batch, after WAIT filtering, before persistence/callback/sleep/execution."""
+
+ @staticmethod
+ async def _run(actions: list, spy) -> list:
+ seen: list = []
+
+ def capture(batch, *, site: str) -> None:
+ seen.extend(spy(list(batch), site))
+ raise _Reached(site)
+
+ browser_state = MagicMock()
+ browser_state.must_get_working_page = AsyncMock(return_value=FakePage())
+ tracker = MagicMock()
+ tracker.drain = AsyncMock()
+ output = MagicMock()
+ with patch("skyvern.forge.agent.preflight_batch", capture):
+ with pytest.raises(_Reached):
+ await ForgeAgent._execute_step_actions(
+ MagicMock(),
+ task=MagicMock(),
+ step=MagicMock(),
+ browser_state=browser_state,
+ engine=MagicMock(),
+ scraped_page=MagicMock(),
+ complete_verification=False,
+ actions=actions,
+ detailed_agent_step_output=output,
+ pdf_auto_download_src=None,
+ pdf_auto_download_used_bytes=False,
+ file_download_false_click_eligible=False,
+ _step_span=MagicMock(),
+ artifact_tracker=tracker,
+ )
+ # F1: the preflight must not have reached into browser state to find a page.
+ browser_state.must_get_working_page.assert_not_awaited()
+ return seen
+
+ @pytest.mark.asyncio
+ async def test_the_batch_is_evaluated_after_wait_filtering(self) -> None:
+ batch = [action_models.WaitAction(), action_models.ClickAction(element_id="1")]
+ seen = await self._run(batch, lambda actions, site: [(a.action_type, site) for a in actions])
+ # If the call were placed before the WAIT filter, the skipped WAIT would show up here.
+ assert seen == [(ActionType.CLICK, "step_action_batch")]
+
+ @pytest.mark.asyncio
+ async def test_the_batch_is_evaluated_before_anything_executes_or_persists(self) -> None:
+ mock_app = MagicMock()
+ with patch("skyvern.webeye.actions.handler.ActionHandler.handle_action") as handle:
+ with patch("skyvern.forge.agent.app", mock_app):
+ await self._run([action_models.ClickAction(element_id="1")], lambda actions, site: [site])
+ handle.assert_not_called()
+ mock_app.DATABASE.workflow_params.create_action.assert_not_called()
+
+ @pytest.mark.asyncio
+ async def test_a_wait_only_batch_is_still_evaluated(self) -> None:
+ seen = await self._run([action_models.WaitAction()], lambda actions, site: [a.action_type for a in actions])
+ assert seen == [ActionType.WAIT]
+
+ @pytest.mark.asyncio
+ async def test_the_batch_preflight_does_not_stamp(self, observing: SkyvernContext) -> None:
+ # F2: stamping belongs at the parse point. An action that reached this batch by another
+ # route must not pick up provenance on the way past.
+ page = FakePage()
+ scrape(page, observing)
+ action = action_models.ClickAction(element_id="1")
+ preflight_batch([action], site="test")
+ assert action.observation_epoch is None
+ assert action.observation_digest is None
+
+
+class TestPerActionPreflight:
+ """AC4: re-evaluated in the concrete handler, before browser-manager lookup or persistence."""
+
+ @pytest.mark.asyncio
+ async def test_handle_action_preflights_before_the_browser_manager_lookup(self) -> None:
+ seen: list[str] = []
+
+ def capture(action, page, *, site: str) -> None:
+ seen.append(site)
+ raise _Reached(site)
+
+ mock_app = MagicMock()
+ with patch("skyvern.webeye.actions.handler.preflight_action", capture):
+ with patch("skyvern.webeye.actions.handler.app", mock_app):
+ with pytest.raises(_Reached):
+ await ActionHandler.handle_action(
+ scraped_page=MagicMock(),
+ task=MagicMock(),
+ step=MagicMock(),
+ page=FakePage(),
+ action=action_models.ClickAction(element_id="1"),
+ )
+ assert seen == ["handle_action"]
+ mock_app.BROWSER_MANAGER.get_for_task.assert_not_called()
+ mock_app.DATABASE.workflow_params.create_action.assert_not_called()
+
+
+class TestReprojectionOfDerivedActions:
+ """AC5. The COMPLETE->TERMINATE conversion is driven for real because its ordering is the subtle
+ part; the remaining conversions are pinned structurally below."""
+
+ @pytest.mark.asyncio
+ async def test_complete_to_terminate_is_reprojected_before_the_terminate_runs(self) -> None:
+ order: list[str] = []
+
+ async def fake_complete_verify(*_args, **_kwargs):
+ result = MagicMock()
+ result.is_terminate = True
+ result.thoughts = "stop"
+ result.status = None
+ return result
+
+ async def fake_terminate(*_args, **_kwargs):
+ order.append("terminate")
+ return []
+
+ def capture(derived, page, *, parent, site: str) -> None:
+ order.append(f"preflight:{site}:{derived.action_type}")
+
+ action = action_models.CompleteAction(verified=False)
+ with patch("skyvern.webeye.actions.handler.app.agent.complete_verify", side_effect=fake_complete_verify):
+ with patch("skyvern.webeye.actions.handler.handle_terminate_action", side_effect=fake_terminate):
+ with patch("skyvern.webeye.actions.handler.preflight_derived_action", capture):
+ from skyvern.webeye.actions.handler import handle_complete_action
+
+ await handle_complete_action(action, FakePage(), MagicMock(), MagicMock(), MagicMock())
+
+ assert order == [f"preflight:complete_to_terminate:{ActionType.TERMINATE}", "terminate"]
+ # And the in-place rewrite still happens, so nothing about execution changed.
+ assert action.action_type == ActionType.TERMINATE
+
+ def test_every_conversion_site_is_wired_to_the_right_preflight(self) -> None:
+ wired = _preflight_calls(Path("skyvern/webeye/actions/handler.py")) | _preflight_calls(
+ Path("skyvern/forge/agent.py")
+ )
+ assert wired == {
+ # Judged as a batch; stamped earlier, at the point it was parsed out of the scrape.
+ "step_action_batch": "preflight_batch",
+ # Synthesized by the runtime after a reload. Judged, never stamped — stamping happens
+ # only at the parse point, which this action never reaches.
+ "internal_refresh": "preflight_action",
+ "handle_action": "preflight_action",
+ "click_to_upload": "preflight_derived_action",
+ "upload_to_click": "preflight_action",
+ "select_option_to_click": "preflight_derived_action",
+ "select_option_to_checkbox": "preflight_derived_action",
+ "complete_to_terminate": "preflight_derived_action",
+ }
+
+
+class TestObserveModeIsNotBehavioural:
+ def test_a_preflight_failure_is_swallowed(self, observing: SkyvernContext) -> None:
+ page = FakePage()
+ scrape(page, observing)
+ with patch("skyvern.forge.sdk.browser_action_preflight.decide_browser_action", side_effect=RuntimeError):
+ assert preflight_action(action_models.ClickAction(element_id="1"), page, site="test") is None
+
+ def test_an_unexpected_page_fault_does_not_escape(self, observing: SkyvernContext) -> None:
+ broken = ExplodingPage()
+ scrape(broken, observing)
+ action = action_models.ClickAction(element_id="1")
+ stamp_parsed_actions([action])
+ assert preflight_action(action, broken, site="test") is None
+
+ def test_a_runtime_synthesized_action_is_never_stamped(self, observing: SkyvernContext) -> None:
+ # F2: only _generate_step_actions stamps, and an injected or synthesized action never
+ # passes through it. Stamping one would hand it a page nobody scraped since.
+ page = FakePage()
+ scrape(page, observing)
+ action = action_models.ReloadPageAction()
+ preflight_action(action, observed_page(), site="test")
+ assert action.observation_epoch is None
+ assert action.observation_digest is None
+
+ def test_no_observable_page_yields_a_decision_not_a_mutation(self, observing: SkyvernContext) -> None:
+ # F1: when nothing can be observed the answer is a denial with a recorded reason, never a
+ # reach into browser state to produce a page.
+ assert observed_page() is None
+ decision = preflight_action(action_models.ClickAction(element_id="1"), None, site="test")
+ assert decision is not None
+ assert PolicyReason.MISSING_PAGE_EVIDENCE in decision.reasons
+
+ def test_advancing_the_epoch_outside_a_run_is_a_no_op(self, monkeypatch: pytest.MonkeyPatch) -> None:
+ monkeypatch.setattr(settings, "BROWSER_ACTION_POLICY_MODE", "observe")
+ skyvern_context.reset()
+ assert skyvern_context.current() is None
+ advance_observation_epoch(FakePage(), main_frame_url=HOME, element_hashes=())
+ stamp_parsed_actions([action_models.ClickAction(element_id="1")])
+
+ def test_decisions_carry_no_page_content(self, observing: SkyvernContext) -> None:
+ # AC8: non-sensitive. A full URL can carry customer data in its query string; the canonical
+ # origin is what ADR-0011's monitoring plan actually asks for.
+ page = FakePage(url="https://example.com/apply?ssn=123-45-6789&name=Someone")
+ scrape(page, observing)
+ action = action_models.ClickAction(element_id="1")
+ stamp_parsed_actions([action])
+ emitted: list[dict] = []
+ with patch.object(preflight.LOG, "info", lambda _event, **kwargs: emitted.append(kwargs)):
+ preflight_action(action, page, site="test")
+ assert len(emitted) == 1
+ rendered = repr(emitted[0])
+ assert "ssn" not in rendered
+ assert "123-45-6789" not in rendered
+ assert emitted[0]["page_origin"] == declare_origin(HOME).canonical
+
+
+class _Reached(Exception):
+ """Raised by a spy so a test can prove nothing downstream of it ran."""
+
+
+def _preflight_calls(path: Path) -> dict[str, str]:
+ """Every preflight call in a module as `site` -> the function it calls, read from its AST.
+
+ Carrying the function name and not just the site is what makes this catch a swap as well as a
+ deletion: `preflight_planned_batch` stamps and `preflight_unplanned_action` does not, so using
+ the wrong one at a site is a fail-open that leaves the site name untouched. Fails loudly rather
+ than silently matching nothing: callers assert against an exact expected mapping.
+ """
+ tree = ast.parse(path.read_text())
+ calls: dict[str, str] = {}
+ for node in ast.walk(tree):
+ if not isinstance(node, ast.Call) or not isinstance(node.func, ast.Name):
+ continue
+ if not node.func.id.startswith("preflight_"):
+ continue
+ for keyword in node.keywords:
+ if keyword.arg == "site" and isinstance(keyword.value, ast.Constant):
+ calls[keyword.value.value] = node.func.id
+ return calls
diff --git a/tests/unit/test_credential_rotation.py b/tests/unit/test_credential_rotation.py
index b4b66ad8b..81bda9537 100644
--- a/tests/unit/test_credential_rotation.py
+++ b/tests/unit/test_credential_rotation.py
@@ -207,6 +207,7 @@ async def test_run_credential_override_persists_for_rotation_parameter() -> None
repo = _SelectionRepo()
with patch("skyvern.forge.sdk.workflow.service.app") as mock_app:
+ mock_app.DATABASE.workflows.get_browser_action_policy = AsyncMock(return_value=None)
mock_app.DATABASE.workflow_run_credential_selections = repo
overrides = await service._apply_run_credential_parameter_overrides(
workflow=workflow,
@@ -251,6 +252,7 @@ async def test_run_credential_override_rejects_conflicting_existing_selection()
patch("skyvern.forge.sdk.workflow.service.app") as mock_app,
pytest.raises(SkyvernHTTPException, match="conflicts with an existing credential selection"),
):
+ mock_app.DATABASE.workflows.get_browser_action_policy = AsyncMock(return_value=None)
mock_app.DATABASE.workflow_run_credential_selections = repo
await service._apply_run_credential_parameter_overrides(
workflow=workflow,
@@ -521,6 +523,7 @@ async def test_workflow_save_validation_rejects_unknown_credential_id() -> None:
parameter = _credential_parameter(credential_ids=["cred_missing"])
with patch("skyvern.forge.sdk.workflow.service.app") as mock_app:
+ mock_app.DATABASE.workflows.get_browser_action_policy = AsyncMock(return_value=None)
mock_app.DATABASE.credentials.get_credentials_by_ids = AsyncMock(return_value=[])
with pytest.raises(InvalidCredentialId):
await service._validate_and_normalize_credential_rotation_parameters([parameter], org)
@@ -544,6 +547,7 @@ async def test_workflow_save_validation_normalizes_credential_id_to_first_rotati
existing = [SimpleNamespace(credential_id="cred_a"), SimpleNamespace(credential_id="cred_b")]
with patch("skyvern.forge.sdk.workflow.service.app") as mock_app:
+ mock_app.DATABASE.workflows.get_browser_action_policy = AsyncMock(return_value=None)
mock_app.DATABASE.credentials.get_credentials_by_ids = AsyncMock(return_value=existing)
await service._validate_and_normalize_credential_rotation_parameters([parameter], org)
@@ -565,6 +569,7 @@ async def test_workflow_save_validation_dedupes_credential_ids_preserving_order(
]
with patch("skyvern.forge.sdk.workflow.service.app") as mock_app:
+ mock_app.DATABASE.workflows.get_browser_action_policy = AsyncMock(return_value=None)
mock_get_credentials = AsyncMock(return_value=existing)
mock_app.DATABASE.credentials.get_credentials_by_ids = mock_get_credentials
await service._validate_and_normalize_credential_rotation_parameters([parameter], org)
@@ -635,6 +640,7 @@ async def test_resolve_login_block_credential_ids_returns_selected_rotating_id()
block = SimpleNamespace(parameters=[parameter])
with patch("skyvern.forge.sdk.workflow.service.app") as mock_app:
+ mock_app.DATABASE.workflows.get_browser_action_policy = AsyncMock(return_value=None)
mock_app.WORKFLOW_CONTEXT_MANAGER.workflow_run_contexts = {"wr_test": context}
credential_ids = await service._resolve_login_block_credential_ids(
block=block,
@@ -730,6 +736,7 @@ async def _attempt_setup_rotation_profile_run(
patch("skyvern.forge.sdk.workflow.service.app") as mock_app,
patch("skyvern.forge.sdk.workflow.service.select_credential_for_run", select_mock),
):
+ mock_app.DATABASE.workflows.get_browser_action_policy = AsyncMock(return_value=None)
mock_app.EXPERIMENTATION_PROVIDER.is_feature_enabled_cached = AsyncMock(return_value=False)
mock_app.AGENT_FUNCTION.should_use_flex_llm_routing = AsyncMock(return_value=False)
mock_app.AGENT_FUNCTION.is_browser_memory_engine_enabled = AsyncMock(return_value=False)
diff --git a/tests/unit/test_forge_log_compaction.py b/tests/unit/test_forge_log_compaction.py
index abfd5a8de..d28980a1d 100644
--- a/tests/unit/test_forge_log_compaction.py
+++ b/tests/unit/test_forge_log_compaction.py
@@ -1,4 +1,6 @@
-from skyvern.forge.sdk.forge_log import compact_action_objects
+from skyvern.forge.sdk.forge_log import (
+ compact_action_objects,
+)
class _FakeAction:
@@ -53,3 +55,35 @@ def test_compact_action_passthrough_when_keys_absent() -> None:
event = {"event": "msg", "step_order": 0}
result = compact_action_objects(None, "info", event) # type: ignore[arg-type]
assert result == event
+
+
+def test_compact_plural_actions_list() -> None:
+ event = {"event": "Executing actions", "actions": [_FakeAction("act_1"), _FakeAction("act_2")]}
+ result = compact_action_objects(None, "info", event) # type: ignore[arg-type]
+ assert result["actions"] == [
+ {"id": "act_1", "type": "click", "element_id": "AAA"},
+ {"id": "act_2", "type": "click", "element_id": "AAA"},
+ ]
+
+
+def test_compact_plural_actions_leaves_an_empty_list_alone() -> None:
+ event = {"event": "msg", "actions": []}
+ assert compact_action_objects(None, "info", event)["actions"] == [] # type: ignore[arg-type]
+
+
+def test_plural_actions_compaction_is_not_a_redaction_control() -> None:
+ """It keeps a signed file_url out of THIS shape as a side effect, and that is all it does.
+
+ Nothing here inspects a value or a nested container: `cached_action=`, `next_action=` and a bare
+ `download_url=` string all pass through untouched, exactly as on main. Credential redaction
+ across the logging stack is a separate concern with its own ticket, and treating this as one
+ would be the mistake the docstring warns about.
+ """
+ from skyvern.webeye.actions.actions import ClickAction
+
+ signed = "https://example.com/a.pdf?X-Amz-Signature=SIGSECRET0123456789"
+ event = {"event": "line", "actions": [ClickAction(element_id="1", file_url=signed)], "cached_action": signed}
+ result = compact_action_objects(None, "info", event) # type: ignore[arg-type]
+
+ assert result["actions"] == [{"id": None, "type": "click", "element_id": "1"}]
+ assert result["cached_action"] == signed
diff --git a/tests/unit/test_hydrate_action_resilience.py b/tests/unit/test_hydrate_action_resilience.py
index aae2e4f98..91d671ae3 100644
--- a/tests/unit/test_hydrate_action_resilience.py
+++ b/tests/unit/test_hydrate_action_resilience.py
@@ -4,14 +4,49 @@ Regression for SKY-9512: a single bad action row should not crash the timeline
endpoint via ValidationError propagation.
"""
+import inspect
from datetime import datetime
from types import SimpleNamespace
from typing import Any
+from unittest.mock import patch
import pytest
-from skyvern.forge.sdk.db.utils import hydrate_action
-from skyvern.webeye.actions.actions import Action, ActionStatus, ActionType, MoveAction
+from skyvern.forge.sdk.db.repositories.workflow_parameters import WorkflowParametersRepository
+from skyvern.forge.sdk.db.utils import ACTION_TYPE_TO_CLASS, hydrate_action
+from skyvern.webeye.actions.actions import (
+ Action,
+ ActionStatus,
+ ActionType,
+ ClickAction,
+ MoveAction,
+ UploadFileAction,
+)
+
+
+def _task() -> SimpleNamespace:
+ return SimpleNamespace(task_id="tsk_test", url="https://example.com", navigation_goal="goal")
+
+
+def _session_yielding(rows: list) -> Any:
+ """A Session factory whose scalars() returns `rows`, so the repository method runs for real."""
+
+ class _Result:
+ @staticmethod
+ def all() -> list:
+ return rows
+
+ class _Session:
+ async def __aenter__(self) -> "_Session":
+ return self
+
+ async def __aexit__(self, *_: Any) -> None:
+ return None
+
+ async def scalars(self, _query: Any) -> _Result:
+ return _Result()
+
+ return staticmethod(lambda *_args: _Session())
def _action_row(**overrides: Any) -> SimpleNamespace:
@@ -76,3 +111,71 @@ def test_hydrate_action_unknown_action_type_falls_back_to_base_action() -> None:
assert isinstance(result, Action)
assert result.action_id == "act_test"
+
+
+def test_every_action_type_hydrates_as_its_concrete_model() -> None:
+ """SKY-12874: the mapping is exhaustive, checked against the enum at runtime.
+
+ Asserted against ``set(ActionType)`` rather than a count, because a hardcoded number inherits
+ whichever human miscounted it and keeps inheriting it. A type that falls through to base
+ ``Action`` projects as ``action_model_mismatch`` and denies, so an unmapped type is fail-closed —
+ but it is fail-closed by breaking every action of that type, which is worth catching here.
+ """
+ assert set(ACTION_TYPE_TO_CLASS) == set(ActionType)
+ assert len(set(ACTION_TYPE_TO_CLASS.values())) == len(ActionType)
+
+
+async def test_subclass_fields_survive_the_production_retrieval_path() -> None:
+ """SKY-12874 / AC6. Drives the repository method itself, not a hand-rolled stand-in.
+
+ ``retrieve_action_plan`` used ``Action.model_validate(row)``, which has no action_json merge, so
+ every cached action came back as a base ``Action`` with its subclass fields gone. A test that
+ calls ``hydrate_action`` directly proves the helper works and says nothing about retrieval.
+ """
+ row = _action_row(
+ action_type=ActionType.UPLOAD_FILE,
+ element_id="7",
+ action_json={"element_id": "7", "file_url": "https://example.com/a.pdf", "is_upload_file_tag": True},
+ )
+ repo = WorkflowParametersRepository.__new__(WorkflowParametersRepository)
+ with patch.object(WorkflowParametersRepository, "Session", _session_yielding([row]), create=True):
+ retrieved = await inspect.unwrap(WorkflowParametersRepository.retrieve_action_plan)(repo, task=_task())
+
+ assert len(retrieved) == 1
+ action = retrieved[0]
+ assert isinstance(action, UploadFileAction)
+ assert action.file_url == "https://example.com/a.pdf"
+ assert action.is_upload_file_tag is True
+
+ # caching.retrieve_action_plan then copies, retargets by element hash and personalizes.
+ retargeted = action.model_copy()
+ retargeted.element_id = "9"
+ retargeted.file_url = "https://example.com/b.pdf"
+ assert isinstance(retargeted, UploadFileAction)
+ assert retargeted.action_type == ActionType.UPLOAD_FILE
+ assert retargeted.file_url == "https://example.com/b.pdf"
+ assert retargeted.is_upload_file_tag is True
+
+
+async def test_a_cached_download_click_is_retrieved_as_a_download_click() -> None:
+ """The behavioural consequence of the fix above, pinned deliberately.
+
+ ``ActionHandler.handle_action`` selects its download-capturing path with
+ ``isinstance(action, ClickAction) and action.download``. A base ``Action`` failed that isinstance
+ check, so a cached click recorded as a download silently skipped download capture on replay.
+ This affects unenrolled runs, which is the population the security ACs give no cover for.
+ """
+ row = _action_row(
+ action_type=ActionType.CLICK,
+ element_id="3",
+ action_json={"element_id": "3", "download": True},
+ )
+ repo = WorkflowParametersRepository.__new__(WorkflowParametersRepository)
+ with patch.object(WorkflowParametersRepository, "Session", _session_yielding([row]), create=True):
+ retrieved = await inspect.unwrap(WorkflowParametersRepository.retrieve_action_plan)(repo, task=_task())
+
+ action = retrieved[0]
+ assert isinstance(action, ClickAction)
+ assert action.download is True
diff --git a/tests/unit/test_workflow_browser_profile_id.py b/tests/unit/test_workflow_browser_profile_id.py
index 54f2f4efc..bf10a3f9b 100644
--- a/tests/unit/test_workflow_browser_profile_id.py
+++ b/tests/unit/test_workflow_browser_profile_id.py
@@ -243,6 +243,7 @@ async def test_refresh_workflow_schedule_runtime_limits_reupserts_backend_schedu
)
with patch("skyvern.forge.sdk.workflow.service.app") as mock_app:
+ mock_app.DATABASE.workflows.get_browser_action_policy = AsyncMock(return_value=None)
mock_app.DATABASE.schedules.get_workflow_schedules = AsyncMock(
return_value=[schedule_with_backend, schedule_without_backend]
)
@@ -370,6 +371,7 @@ async def test_setup_workflow_run_falls_back_to_workflow_browser_profile_id() ->
assert request.browser_profile_id is None
with patch("skyvern.forge.sdk.workflow.service.app") as mock_app:
+ mock_app.DATABASE.workflows.get_browser_action_policy = AsyncMock(return_value=None)
mock_app.EXPERIMENTATION_PROVIDER.is_feature_enabled_cached = AsyncMock(return_value=False)
mock_app.AGENT_FUNCTION.should_use_flex_llm_routing = AsyncMock(return_value=False)
@@ -392,6 +394,7 @@ async def test_setup_workflow_run_run_level_value_takes_precedence() -> None:
request = WorkflowRequestBody(data={}, browser_profile_id="bp_run_specific")
with patch("skyvern.forge.sdk.workflow.service.app") as mock_app:
+ mock_app.DATABASE.workflows.get_browser_action_policy = AsyncMock(return_value=None)
mock_app.EXPERIMENTATION_PROVIDER.is_feature_enabled_cached = AsyncMock(return_value=False)
mock_app.AGENT_FUNCTION.should_use_flex_llm_routing = AsyncMock(return_value=False)
@@ -414,6 +417,7 @@ async def test_setup_workflow_run_no_default_no_request_stays_none() -> None:
request = WorkflowRequestBody(data={})
with patch("skyvern.forge.sdk.workflow.service.app") as mock_app:
+ mock_app.DATABASE.workflows.get_browser_action_policy = AsyncMock(return_value=None)
mock_app.EXPERIMENTATION_PROVIDER.is_feature_enabled_cached = AsyncMock(return_value=False)
mock_app.AGENT_FUNCTION.should_use_flex_llm_routing = AsyncMock(return_value=False)
@@ -437,6 +441,7 @@ async def test_setup_workflow_run_session_present_skips_workflow_default() -> No
assert request.browser_profile_id is None
with patch("skyvern.forge.sdk.workflow.service.app") as mock_app:
+ mock_app.DATABASE.workflows.get_browser_action_policy = AsyncMock(return_value=None)
mock_app.EXPERIMENTATION_PROVIDER.is_feature_enabled_cached = AsyncMock(return_value=False)
mock_app.AGENT_FUNCTION.should_use_flex_llm_routing = AsyncMock(return_value=False)
@@ -459,6 +464,7 @@ async def test_setup_workflow_run_prefers_request_max_elapsed_time_over_workflow
request = WorkflowRequestBody(data={}, max_elapsed_time_minutes=10)
with patch("skyvern.forge.sdk.workflow.service.app") as mock_app:
+ mock_app.DATABASE.workflows.get_browser_action_policy = AsyncMock(return_value=None)
mock_app.EXPERIMENTATION_PROVIDER.is_feature_enabled_cached = AsyncMock(return_value=False)
mock_app.AGENT_FUNCTION.should_use_flex_llm_routing = AsyncMock(return_value=False)
diff --git a/tests/unit/test_workflow_elapsed_timeout.py b/tests/unit/test_workflow_elapsed_timeout.py
index 8ba1b82fa..88595baf7 100644
--- a/tests/unit/test_workflow_elapsed_timeout.py
+++ b/tests/unit/test_workflow_elapsed_timeout.py
@@ -225,6 +225,7 @@ async def test_execute_workflow_returns_after_elapsed_timeout_without_finally(mo
monkeypatch.setattr(svc, "get_workflow_run", AsyncMock(return_value=created_run))
monkeypatch.setattr(svc, "get_workflow", AsyncMock(return_value=workflow))
+ monkeypatch.setattr(svc, "bind_browser_action_policy", AsyncMock(return_value=None))
monkeypatch.setattr(svc, "mark_workflow_run_as_running", AsyncMock(return_value=running_run))
monkeypatch.setattr(svc, "get_workflow_run_parameter_tuples", AsyncMock(return_value=[]))
monkeypatch.setattr(svc, "get_workflow_output_parameters", AsyncMock(return_value=[]))
@@ -308,6 +309,7 @@ async def test_execute_workflow_times_out_slow_pre_block_script_lookup(monkeypat
monkeypatch.setattr(svc, "get_workflow_run", AsyncMock(return_value=created_run))
monkeypatch.setattr(svc, "get_workflow", AsyncMock(return_value=workflow))
+ monkeypatch.setattr(svc, "bind_browser_action_policy", AsyncMock(return_value=None))
monkeypatch.setattr(svc, "mark_workflow_run_as_running", AsyncMock(return_value=running_run))
monkeypatch.setattr(svc, "get_workflow_run_parameter_tuples", AsyncMock(return_value=[]))
monkeypatch.setattr(svc, "get_workflow_output_parameters", AsyncMock(return_value=[]))
@@ -396,6 +398,7 @@ async def test_execute_workflow_preserves_completed_status_after_post_run_timeou
monkeypatch.setattr(svc, "get_workflow_run", AsyncMock(return_value=created_run))
monkeypatch.setattr(svc, "get_workflow", AsyncMock(return_value=workflow))
+ monkeypatch.setattr(svc, "bind_browser_action_policy", AsyncMock(return_value=None))
monkeypatch.setattr(svc, "mark_workflow_run_as_running", AsyncMock(return_value=running_run))
monkeypatch.setattr(svc, "get_workflow_run_parameter_tuples", AsyncMock(return_value=[]))
monkeypatch.setattr(svc, "get_workflow_output_parameters", AsyncMock(return_value=[]))
@@ -487,6 +490,7 @@ async def test_execute_workflow_preserves_timed_out_status_after_non_terminal_po
monkeypatch.setattr(svc, "get_workflow_run", AsyncMock(return_value=created_run))
monkeypatch.setattr(svc, "get_workflow", AsyncMock(return_value=workflow))
+ monkeypatch.setattr(svc, "bind_browser_action_policy", AsyncMock(return_value=None))
monkeypatch.setattr(svc, "mark_workflow_run_as_running", AsyncMock(return_value=running_run))
monkeypatch.setattr(svc, "get_workflow_run_parameter_tuples", AsyncMock(return_value=[]))
monkeypatch.setattr(svc, "get_workflow_output_parameters", AsyncMock(return_value=[]))
@@ -582,6 +586,7 @@ async def test_execute_workflow_marks_timed_out_when_post_run_budget_is_exhauste
monkeypatch.setattr(svc, "get_workflow_run", AsyncMock(return_value=created_run))
monkeypatch.setattr(svc, "get_workflow", AsyncMock(return_value=workflow))
+ monkeypatch.setattr(svc, "bind_browser_action_policy", AsyncMock(return_value=None))
monkeypatch.setattr(svc, "mark_workflow_run_as_running", AsyncMock(return_value=running_run))
monkeypatch.setattr(svc, "get_workflow_run_parameter_tuples", AsyncMock(return_value=[]))
monkeypatch.setattr(svc, "get_workflow_output_parameters", AsyncMock(return_value=[]))
@@ -759,6 +764,7 @@ async def test_execute_workflow_refreshes_terminal_status_after_immediate_post_r
monkeypatch.setattr(svc, "get_workflow_run", AsyncMock(return_value=created_run))
monkeypatch.setattr(svc, "get_workflow", AsyncMock(return_value=workflow))
+ monkeypatch.setattr(svc, "bind_browser_action_policy", AsyncMock(return_value=None))
monkeypatch.setattr(svc, "mark_workflow_run_as_running", AsyncMock(return_value=running_run))
monkeypatch.setattr(svc, "get_workflow_run_parameter_tuples", AsyncMock(return_value=[]))
monkeypatch.setattr(svc, "get_workflow_output_parameters", AsyncMock(return_value=[]))
@@ -850,6 +856,7 @@ async def test_execute_workflow_returns_finalized_status_after_post_run_timeout(
monkeypatch.setattr(svc, "get_workflow_run", AsyncMock(return_value=created_run))
monkeypatch.setattr(svc, "get_workflow", AsyncMock(return_value=workflow))
+ monkeypatch.setattr(svc, "bind_browser_action_policy", AsyncMock(return_value=None))
monkeypatch.setattr(svc, "mark_workflow_run_as_running", AsyncMock(return_value=running_run))
monkeypatch.setattr(svc, "get_workflow_run_parameter_tuples", AsyncMock(return_value=[]))
monkeypatch.setattr(svc, "get_workflow_output_parameters", AsyncMock(return_value=[]))
@@ -939,6 +946,7 @@ async def test_execute_workflow_runs_finally_for_existing_timed_out_status(
monkeypatch.setattr(svc, "get_workflow_run", AsyncMock(return_value=created_run))
monkeypatch.setattr(svc, "get_workflow", AsyncMock(return_value=workflow))
+ monkeypatch.setattr(svc, "bind_browser_action_policy", AsyncMock(return_value=None))
monkeypatch.setattr(svc, "mark_workflow_run_as_running", AsyncMock(return_value=running_run))
monkeypatch.setattr(svc, "get_workflow_run_parameter_tuples", AsyncMock(return_value=[]))
monkeypatch.setattr(svc, "get_workflow_output_parameters", AsyncMock(return_value=[]))
@@ -1020,6 +1028,7 @@ async def test_execute_workflow_finalizes_failed_when_body_interrupted_before_te
monkeypatch.setattr(svc, "get_workflow_run", AsyncMock(return_value=created_run))
monkeypatch.setattr(svc, "get_workflow", AsyncMock(return_value=workflow))
+ monkeypatch.setattr(svc, "bind_browser_action_policy", AsyncMock(return_value=None))
monkeypatch.setattr(svc, "mark_workflow_run_as_running", AsyncMock(return_value=running_run))
monkeypatch.setattr(svc, "get_workflow_run_parameter_tuples", AsyncMock(return_value=[]))
monkeypatch.setattr(svc, "get_workflow_output_parameters", AsyncMock(return_value=[]))
@@ -1177,6 +1186,7 @@ async def test_execute_workflow_skips_interrupted_finalize_for_cancellation(
monkeypatch.setattr(svc, "get_workflow_run", AsyncMock(return_value=created_run))
monkeypatch.setattr(svc, "get_workflow", AsyncMock(return_value=workflow))
+ monkeypatch.setattr(svc, "bind_browser_action_policy", AsyncMock(return_value=None))
monkeypatch.setattr(svc, "mark_workflow_run_as_running", AsyncMock(return_value=running_run))
monkeypatch.setattr(svc, "get_workflow_run_parameter_tuples", AsyncMock(return_value=[]))
monkeypatch.setattr(svc, "get_workflow_output_parameters", AsyncMock(return_value=[]))
diff --git a/tests/unit/test_workflow_run_parameter_batching.py b/tests/unit/test_workflow_run_parameter_batching.py
index db0504a23..3f4e2eb54 100644
--- a/tests/unit/test_workflow_run_parameter_batching.py
+++ b/tests/unit/test_workflow_run_parameter_batching.py
@@ -107,6 +107,7 @@ async def test_apply_initial_run_metadata_tags_uses_system_source_for_fallback_c
explicit_context = TagWriteContext(caller_id="user_test", source=TagSource.MANUAL, caller_type=CallerType.USER)
with patch("skyvern.forge.sdk.workflow.service.app") as mock_app:
+ mock_app.DATABASE.workflows.get_browser_action_policy = AsyncMock(return_value=None)
mock_app.DATABASE.tags.apply_run_tag_changes = AsyncMock()
await WorkflowService._apply_initial_run_metadata_tags(
@@ -138,6 +139,7 @@ async def test_setup_workflow_run_writes_run_metadata_as_run_tags() -> None:
tag_context = TagWriteContext(caller_id="user_test", source=TagSource.MANUAL, caller_type=CallerType.USER)
with patch("skyvern.forge.sdk.workflow.service.app") as mock_app:
+ mock_app.DATABASE.workflows.get_browser_action_policy = AsyncMock(return_value=None)
mock_app.EXPERIMENTATION_PROVIDER.is_feature_enabled_cached = AsyncMock(return_value=False)
mock_app.AGENT_FUNCTION.should_use_flex_llm_routing = AsyncMock(return_value=False)
mock_app.DATABASE.tags.apply_run_tag_changes = AsyncMock()
@@ -165,6 +167,7 @@ async def test_setup_workflow_run_continues_when_initial_run_tag_write_fails() -
request = WorkflowRequestBody(data={}, run_metadata={"env": "prod"})
with patch("skyvern.forge.sdk.workflow.service.app") as mock_app:
+ mock_app.DATABASE.workflows.get_browser_action_policy = AsyncMock(return_value=None)
mock_app.EXPERIMENTATION_PROVIDER.is_feature_enabled_cached = AsyncMock(return_value=False)
mock_app.AGENT_FUNCTION.should_use_flex_llm_routing = AsyncMock(return_value=False)
mock_app.DATABASE.tags.apply_run_tag_changes = AsyncMock(side_effect=RuntimeError("tag write failed"))
@@ -195,6 +198,7 @@ async def test_setup_workflow_run_writes_create_time_system_tags() -> None:
return_value="known_platform",
),
):
+ mock_app.DATABASE.workflows.get_browser_action_policy = AsyncMock(return_value=None)
mock_app.EXPERIMENTATION_PROVIDER.is_feature_enabled_cached = AsyncMock(return_value=False)
mock_app.AGENT_FUNCTION.should_use_flex_llm_routing = AsyncMock(return_value=False)
mock_app.DATABASE.tags.apply_system_run_tag_changes = AsyncMock()
@@ -230,6 +234,7 @@ async def test_setup_workflow_run_writes_trigger_tag_when_target_domain_is_unava
return_value=None,
),
):
+ mock_app.DATABASE.workflows.get_browser_action_policy = AsyncMock(return_value=None)
mock_app.EXPERIMENTATION_PROVIDER.is_feature_enabled_cached = AsyncMock(return_value=False)
mock_app.AGENT_FUNCTION.should_use_flex_llm_routing = AsyncMock(return_value=False)
mock_app.DATABASE.tags.apply_system_run_tag_changes = AsyncMock()
@@ -260,6 +265,7 @@ async def test_setup_workflow_run_continues_when_creation_tag_write_fails() -> N
return_value="known_platform",
),
):
+ mock_app.DATABASE.workflows.get_browser_action_policy = AsyncMock(return_value=None)
mock_app.EXPERIMENTATION_PROVIDER.is_feature_enabled_cached = AsyncMock(return_value=False)
mock_app.AGENT_FUNCTION.should_use_flex_llm_routing = AsyncMock(return_value=False)
mock_app.DATABASE.tags.apply_system_run_tag_changes = AsyncMock(side_effect=RuntimeError("tag write failed"))
@@ -290,6 +296,7 @@ async def test_setup_workflow_run_writes_provenance_tags_when_platform_detection
side_effect=RuntimeError("detector unavailable"),
),
):
+ mock_app.DATABASE.workflows.get_browser_action_policy = AsyncMock(return_value=None)
mock_app.EXPERIMENTATION_PROVIDER.is_feature_enabled_cached = AsyncMock(return_value=False)
mock_app.AGENT_FUNCTION.should_use_flex_llm_routing = AsyncMock(return_value=False)
mock_app.DATABASE.tags.apply_system_run_tag_changes = AsyncMock()
@@ -319,6 +326,7 @@ async def test_setup_workflow_run_raises_on_missing_required_parameters() -> Non
request = WorkflowRequestBody(data={}) # no data for api_key
with patch("skyvern.forge.sdk.workflow.service.app") as mock_app:
+ mock_app.DATABASE.workflows.get_browser_action_policy = AsyncMock(return_value=None)
mock_app.EXPERIMENTATION_PROVIDER.is_feature_enabled_cached = AsyncMock(return_value=False)
mock_app.AGENT_FUNCTION.should_use_flex_llm_routing = AsyncMock(return_value=False)
@@ -364,6 +372,7 @@ async def test_setup_workflow_run_persistence_error_identifies_specific_failing_
request = WorkflowRequestBody(data={"alpha_count": 5, "middle_label": "test", "zebra_url": "https://z.com"})
with patch("skyvern.forge.sdk.workflow.service.app") as mock_app:
+ mock_app.DATABASE.workflows.get_browser_action_policy = AsyncMock(return_value=None)
mock_app.EXPERIMENTATION_PROVIDER.is_feature_enabled_cached = AsyncMock(return_value=False)
mock_app.AGENT_FUNCTION.should_use_flex_llm_routing = AsyncMock(return_value=False)
@@ -396,6 +405,7 @@ async def test_setup_workflow_run_raises_on_non_string_credential_id() -> None:
request = WorkflowRequestBody(data={"credential": 12345}) # not a string
with patch("skyvern.forge.sdk.workflow.service.app") as mock_app:
+ mock_app.DATABASE.workflows.get_browser_action_policy = AsyncMock(return_value=None)
mock_app.EXPERIMENTATION_PROVIDER.is_feature_enabled_cached = AsyncMock(return_value=False)
mock_app.AGENT_FUNCTION.should_use_flex_llm_routing = AsyncMock(return_value=False)
@@ -429,6 +439,7 @@ async def test_setup_workflow_run_validates_credentials_before_preparing_managed
request = WorkflowRequestBody(data={"credential": "cred_missing"})
with patch("skyvern.forge.sdk.workflow.service.app") as mock_app:
+ mock_app.DATABASE.workflows.get_browser_action_policy = AsyncMock(return_value=None)
mock_app.EXPERIMENTATION_PROVIDER.is_feature_enabled_cached = AsyncMock(return_value=False)
mock_app.AGENT_FUNCTION.should_use_flex_llm_routing = AsyncMock(return_value=False)
@@ -462,6 +473,7 @@ async def test_setup_workflow_run_batches_credential_validation() -> None:
request = WorkflowRequestBody(data={})
with patch("skyvern.forge.sdk.workflow.service.app") as mock_app:
+ mock_app.DATABASE.workflows.get_browser_action_policy = AsyncMock(return_value=None)
mock_app.EXPERIMENTATION_PROVIDER.is_feature_enabled_cached = AsyncMock(return_value=False)
mock_app.AGENT_FUNCTION.should_use_flex_llm_routing = AsyncMock(return_value=False)
@@ -493,6 +505,7 @@ async def test_setup_workflow_run_skips_credential_lookup_when_no_credentials()
request = WorkflowRequestBody(data={})
with patch("skyvern.forge.sdk.workflow.service.app") as mock_app:
+ mock_app.DATABASE.workflows.get_browser_action_policy = AsyncMock(return_value=None)
mock_app.EXPERIMENTATION_PROVIDER.is_feature_enabled_cached = AsyncMock(return_value=False)
mock_app.AGENT_FUNCTION.should_use_flex_llm_routing = AsyncMock(return_value=False)
@@ -521,6 +534,7 @@ async def test_setup_workflow_run_raises_invalid_credential_when_missing() -> No
request = WorkflowRequestBody(data={})
with patch("skyvern.forge.sdk.workflow.service.app") as mock_app:
+ mock_app.DATABASE.workflows.get_browser_action_policy = AsyncMock(return_value=None)
mock_app.EXPERIMENTATION_PROVIDER.is_feature_enabled_cached = AsyncMock(return_value=False)
mock_app.AGENT_FUNCTION.should_use_flex_llm_routing = AsyncMock(return_value=False)
@@ -553,6 +567,7 @@ async def test_setup_workflow_run_surfaces_all_missing_credentials() -> None:
request = WorkflowRequestBody(data={})
with patch("skyvern.forge.sdk.workflow.service.app") as mock_app:
+ mock_app.DATABASE.workflows.get_browser_action_policy = AsyncMock(return_value=None)
mock_app.EXPERIMENTATION_PROVIDER.is_feature_enabled_cached = AsyncMock(return_value=False)
mock_app.AGENT_FUNCTION.should_use_flex_llm_routing = AsyncMock(return_value=False)
@@ -591,6 +606,7 @@ async def test_setup_workflow_run_dedupes_repeated_credential_ids() -> None:
request = WorkflowRequestBody(data={})
with patch("skyvern.forge.sdk.workflow.service.app") as mock_app:
+ mock_app.DATABASE.workflows.get_browser_action_policy = AsyncMock(return_value=None)
mock_app.EXPERIMENTATION_PROVIDER.is_feature_enabled_cached = AsyncMock(return_value=False)
mock_app.AGENT_FUNCTION.should_use_flex_llm_routing = AsyncMock(return_value=False)
@@ -615,6 +631,7 @@ async def test_setup_workflow_run_defaults_missing_trigger_type_to_api() -> None
service, organization, _ = _make_service_with_mocks(workflow_parameters=[])
with patch("skyvern.forge.sdk.workflow.service.app") as mock_app:
+ mock_app.DATABASE.workflows.get_browser_action_policy = AsyncMock(return_value=None)
mock_app.EXPERIMENTATION_PROVIDER.is_feature_enabled_cached = AsyncMock(return_value=False)
mock_app.AGENT_FUNCTION.should_use_flex_llm_routing = AsyncMock(return_value=False)
@@ -652,6 +669,7 @@ async def test_setup_workflow_run_inherits_missing_trigger_type_from_parent_cont
)
with patch("skyvern.forge.sdk.workflow.service.app") as mock_app:
+ mock_app.DATABASE.workflows.get_browser_action_policy = AsyncMock(return_value=None)
mock_app.EXPERIMENTATION_PROVIDER.is_feature_enabled_cached = AsyncMock(return_value=False)
mock_app.AGENT_FUNCTION.should_use_flex_llm_routing = AsyncMock(return_value=False)
@@ -687,6 +705,7 @@ async def test_setup_workflow_run_explicit_trigger_type_overrides_parent_context
)
with patch("skyvern.forge.sdk.workflow.service.app") as mock_app:
+ mock_app.DATABASE.workflows.get_browser_action_policy = AsyncMock(return_value=None)
mock_app.EXPERIMENTATION_PROVIDER.is_feature_enabled_cached = AsyncMock(return_value=False)
mock_app.AGENT_FUNCTION.should_use_flex_llm_routing = AsyncMock(return_value=False)
@@ -724,6 +743,7 @@ async def test_setup_workflow_run_preserves_parent_loop_state_when_replacing_con
skyvern_context.set(parent_context)
with patch("skyvern.forge.sdk.workflow.service.app") as mock_app:
+ mock_app.DATABASE.workflows.get_browser_action_policy = AsyncMock(return_value=None)
mock_app.EXPERIMENTATION_PROVIDER.is_feature_enabled_cached = AsyncMock(return_value=False)
mock_app.AGENT_FUNCTION.should_use_flex_llm_routing = AsyncMock(return_value=False)
@@ -768,6 +788,7 @@ async def test_setup_workflow_run_opens_one_outer_session() -> None:
request = WorkflowRequestBody(data={"k": "v"})
with patch("skyvern.forge.sdk.workflow.service.app") as mock_app:
+ mock_app.DATABASE.workflows.get_browser_action_policy = AsyncMock(return_value=None)
mock_app.EXPERIMENTATION_PROVIDER.is_feature_enabled_cached = AsyncMock(return_value=False)
mock_app.AGENT_FUNCTION.should_use_flex_llm_routing = AsyncMock(return_value=False)
@@ -823,6 +844,7 @@ async def test_setup_workflow_run_rolls_back_outer_session_on_batch_failure() ->
request = WorkflowRequestBody(data={"a": "1", "b": "2"})
with patch("skyvern.forge.sdk.workflow.service.app") as mock_app:
+ mock_app.DATABASE.workflows.get_browser_action_policy = AsyncMock(return_value=None)
mock_app.EXPERIMENTATION_PROVIDER.is_feature_enabled_cached = AsyncMock(return_value=False)
mock_app.AGENT_FUNCTION.should_use_flex_llm_routing = AsyncMock(return_value=False)
@@ -854,6 +876,7 @@ async def test_setup_workflow_run_skips_browser_inheritance_for_fallback_retry()
request = WorkflowRequestBody(data={}, browser_profile_id=None, browser_session_id=None, cdp_connect_headers=None)
with patch("skyvern.forge.sdk.workflow.service.app") as mock_app:
+ mock_app.DATABASE.workflows.get_browser_action_policy = AsyncMock(return_value=None)
mock_app.EXPERIMENTATION_PROVIDER.is_feature_enabled_cached = AsyncMock(return_value=False)
mock_app.AGENT_FUNCTION.should_use_flex_llm_routing = AsyncMock(return_value=False)
@@ -881,6 +904,7 @@ async def test_setup_workflow_run_inherits_browser_profile_for_normal_run() -> N
request = WorkflowRequestBody(data={}, browser_profile_id=None, browser_session_id=None, cdp_connect_headers=None)
with patch("skyvern.forge.sdk.workflow.service.app") as mock_app:
+ mock_app.DATABASE.workflows.get_browser_action_policy = AsyncMock(return_value=None)
mock_app.EXPERIMENTATION_PROVIDER.is_feature_enabled_cached = AsyncMock(return_value=False)
mock_app.AGENT_FUNCTION.should_use_flex_llm_routing = AsyncMock(return_value=False)
diff --git a/tests/unit/test_workflow_service_managed_browser_profile.py b/tests/unit/test_workflow_service_managed_browser_profile.py
index 11a740de2..9dd3cc3fd 100644
--- a/tests/unit/test_workflow_service_managed_browser_profile.py
+++ b/tests/unit/test_workflow_service_managed_browser_profile.py
@@ -125,6 +125,7 @@ def _patch_execute_workflow_deps(
monkeypatch.setattr(svc, "get_workflow_run", AsyncMock(return_value=created_run))
monkeypatch.setattr(svc, "get_workflow", AsyncMock(return_value=workflow))
+ monkeypatch.setattr(svc, "bind_browser_action_policy", AsyncMock(return_value=None))
monkeypatch.setattr(svc, "mark_workflow_run_as_running", AsyncMock(return_value=running_run))
monkeypatch.setattr(svc, "get_workflow_run_parameter_tuples", AsyncMock(return_value=[]))
monkeypatch.setattr(svc, "get_workflow_output_parameters", AsyncMock(return_value=[]))