Skip to content

Automate browser based workflows with AI

SKY-12058: Distinguish MCP trigger type (#7236)

Aaron Perez95e57cf43d51
diff --git a/fern/openapi/skyvern_openapi.json b/fern/openapi/skyvern_openapi.json
index 057480da2..de8880c90 100644
--- a/fern/openapi/skyvern_openapi.json
+++ b/fern/openapi/skyvern_openapi.json
@@ -18782,6 +18782,16 @@
"type": "boolean",
"title": "Script Run",
"default": false
+ },
+ "trigger_type": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/WorkflowRunTriggerType"
+ },
+ {
+ "type": "null"
+ }
+ ]
}
},
"type": "object",
@@ -25207,12 +25217,13 @@
"type": "string",
"enum": [
"manual",
+ "mcp",
"api",
"scheduled",
"webhook"
],
"title": "WorkflowRunTriggerType",
- "description": "How a workflow run was initiated.\n\n- manual: User clicked \"Run\" in the UI\n- api: Direct API call to the run endpoint\n- scheduled: Triggered by a cron schedule\n- webhook: Triggered by an external system via the webhook endpoint"
+ "description": "How a workflow run was initiated.\n\n- manual: User clicked \"Run\" in the UI\n- mcp: First-party MCP client request\n- api: Direct API call to the run endpoint\n- scheduled: Triggered by a cron schedule\n- webhook: Triggered by an external system via the webhook endpoint"
},
"WorkflowSchedule": {
"properties": {
diff --git a/skyvern-frontend/src/api/types.ts b/skyvern-frontend/src/api/types.ts
index bf6da1067..cbc97706e 100644
--- a/skyvern-frontend/src/api/types.ts
+++ b/skyvern-frontend/src/api/types.ts
@@ -31,6 +31,7 @@ export type ArtifactType = (typeof ArtifactType)[keyof typeof ArtifactType];
export const TriggerType = {
Manual: "manual",
+ Mcp: "mcp",
Api: "api",
Scheduled: "scheduled",
} as const;
@@ -695,6 +696,7 @@ export type TaskRunListItem = {
workflow_permanent_id: string | null;
workflow_deleted: boolean;
script_run: boolean;
+ trigger_type?: TriggerType | null;
searchable_text: string | null;
};
diff --git a/skyvern-frontend/src/components/TriggerTypeBadge.tsx b/skyvern-frontend/src/components/TriggerTypeBadge.tsx
index bdd8c4eda..33f7cbfbf 100644
--- a/skyvern-frontend/src/components/TriggerTypeBadge.tsx
+++ b/skyvern-frontend/src/components/TriggerTypeBadge.tsx
@@ -1,6 +1,7 @@
import { TriggerType } from "@/api/types";
import {
CalendarIcon,
+ CubeIcon,
CursorArrowIcon,
LightningBoltIcon,
} from "@radix-ui/react-icons";
@@ -18,6 +19,10 @@ const triggerConfig: Record<
icon: <CursorArrowIcon className="size-3.5 text-slate-400" />,
label: "Manual",
},
+ [TriggerType.Mcp]: {
+ icon: <CubeIcon className="size-3.5 text-emerald-400" />,
+ label: "MCP",
+ },
[TriggerType.Api]: {
icon: <LightningBoltIcon className="size-3.5 text-amber-400" />,
label: "API",
diff --git a/skyvern-frontend/src/components/TriggerTypeFilterDropdown.tsx b/skyvern-frontend/src/components/TriggerTypeFilterDropdown.tsx
index 0d9dc6915..7fa88c577 100644
--- a/skyvern-frontend/src/components/TriggerTypeFilterDropdown.tsx
+++ b/skyvern-frontend/src/components/TriggerTypeFilterDropdown.tsx
@@ -18,6 +18,10 @@ const triggerTypeDropdownItems: Array<TriggerTypeDropdownItem> = [
label: "Manual",
value: TriggerType.Manual,
},
+ {
+ label: "MCP",
+ value: TriggerType.Mcp,
+ },
{
label: "API",
value: TriggerType.Api,
diff --git a/skyvern-frontend/src/routes/history/RunHistory.test.tsx b/skyvern-frontend/src/routes/history/RunHistory.test.tsx
index 56f196a13..4b4a372ac 100644
--- a/skyvern-frontend/src/routes/history/RunHistory.test.tsx
+++ b/skyvern-frontend/src/routes/history/RunHistory.test.tsx
@@ -10,10 +10,10 @@ import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { afterEach, describe, expect, it, vi } from "vitest";
import { MemoryRouter } from "react-router-dom";
-import { TaskRunType } from "@/api/types";
+import { TaskRunType, TriggerType, type TaskRunListItem } from "@/api/types";
import { RunHistory } from "./RunHistory";
-const workflowRun = {
+const workflowRun: TaskRunListItem = {
task_run_id: "tr_1",
task_run_type: TaskRunType.WorkflowRun,
run_id: "wr_123",
@@ -25,6 +25,7 @@ const workflowRun = {
workflow_permanent_id: "wpid_1",
workflow_deleted: false,
script_run: false,
+ trigger_type: null,
searchable_text: "city Paris",
};
@@ -58,6 +59,12 @@ vi.mock("@/components/StatusFilterDropdown", () => ({
StatusFilterDropdown: () => <div data-testid="status-filter" />,
}));
+vi.mock("@/components/TriggerTypeBadge", () => ({
+ TriggerTypeBadge: ({ triggerType }: { triggerType: string }) => (
+ <span data-testid={`trigger-type-${triggerType}`}>{triggerType}</span>
+ ),
+}));
+
vi.mock("@/components/onboarding/OnboardingEmptyState", () => ({
OnboardingEmptyState: () => <div data-testid="onboarding-empty" />,
}));
@@ -116,6 +123,7 @@ function activateSearch() {
}
afterEach(() => {
+ runsData.splice(0, runsData.length, workflowRun);
cleanup();
vi.clearAllMocks();
});
@@ -143,4 +151,15 @@ describe("RunHistory inputs during filtering", () => {
expect(await screen.findByText("Run Inputs")).toBeTruthy();
expect(screen.getByText("Paris")).toBeTruthy();
});
+
+ it("renders the MCP trigger badge from persisted trigger_type", () => {
+ runsData.splice(0, runsData.length, {
+ ...workflowRun,
+ trigger_type: TriggerType.Mcp,
+ });
+
+ renderRunHistory();
+
+ expect(screen.getByTestId("trigger-type-mcp")).toBeTruthy();
+ });
});
diff --git a/skyvern-frontend/src/routes/history/RunHistory.tsx b/skyvern-frontend/src/routes/history/RunHistory.tsx
index 120794d22..029fe1c23 100644
--- a/skyvern-frontend/src/routes/history/RunHistory.tsx
+++ b/skyvern-frontend/src/routes/history/RunHistory.tsx
@@ -97,6 +97,9 @@ function parseStatusParam(raw: string | null): Array<Status> {
// Scheduled workflow runs carry a deterministic `wr_sched_<hash>` id prefix.
function inferTriggerType(run: TaskRunListItem): TriggerType | null {
+ if (run.trigger_type) {
+ return run.trigger_type;
+ }
if (
run.task_run_type === TaskRunType.WorkflowRun &&
run.run_id.startsWith("wr_sched_")
diff --git a/skyvern/cli/core/browser_ops.py b/skyvern/cli/core/browser_ops.py
index 2276bd521..a502769fe 100644
--- a/skyvern/cli/core/browser_ops.py
+++ b/skyvern/cli/core/browser_ops.py
@@ -1129,6 +1129,14 @@ class ExecuteStep:
params: dict[str, Any] = field(default_factory=dict)
+class ToolStepError(RuntimeError):
+ """Step failure that preserves the failing tool's structured error payload."""
+
+ def __init__(self, error: dict[str, Any]) -> None:
+ super().__init__(error.get("message", "Tool execution failed"))
+ self.error = error
+
+
@dataclass
class StepResult:
step: int
@@ -1136,7 +1144,7 @@ class StepResult:
ok: bool
wall_ms: int = 0
data: dict[str, Any] | None = None
- error: str | None = None
+ error: str | dict[str, Any] | None = None
@dataclass
@@ -1186,7 +1194,8 @@ async def do_execute(
except Exception as e:
wall_ms = int((time.monotonic() - t0) * 1000)
- results.append(StepResult(step=i, tool=step.tool, ok=False, wall_ms=wall_ms, error=str(e)))
+ error_payload: str | dict[str, Any] = e.error if isinstance(e, ToolStepError) else str(e)
+ results.append(StepResult(step=i, tool=step.tool, ok=False, wall_ms=wall_ms, error=error_payload))
if step.tool == "navigate":
nav_failed = True
if stop_on_error:
diff --git a/skyvern/cli/mcp_tools/_element_state.py b/skyvern/cli/mcp_tools/_element_state.py
new file mode 100644
index 000000000..b57a4ea0e
--- /dev/null
+++ b/skyvern/cli/mcp_tools/_element_state.py
@@ -0,0 +1,121 @@
+from __future__ import annotations
+
+import asyncio
+import os
+from typing import Any, Literal
+
+from ._common import ErrorCode, make_error
+
+DEFAULT_ACTION_TIMEOUT_MS = 30000
+DEFAULT_DIRECT_ACTION_TIMEOUT_MS = 5000
+DIRECT_ACTION_TIMEOUT_ENV = "SKYVERN_MCP_DIRECT_TIMEOUT_MS"
+MIN_ACTION_TIMEOUT_MS = 1000
+MAX_ACTION_TIMEOUT_MS = 60000
+ELEMENT_STATE_PROBE_TIMEOUT_MS = 1000
+
+ACTION_TIMEOUT_DESCRIPTION = (
+ "Max time to wait for the element in ms. "
+ "Defaults to 5000 for deterministic selector-only/direct calls and 30000 for AI/fallback paths."
+)
+
+ElementState = Literal["not_found", "hidden", "disabled", "occluded", "unknown"]
+
+_STATE_ERRORS: dict[ElementState, tuple[str, str, str]] = {
+ "not_found": (
+ ErrorCode.SELECTOR_NOT_FOUND,
+ "Selector did not match any element before the direct action timeout",
+ "Verify the selector matches an element on the page, or wait for the element to render before retrying.",
+ ),
+ "hidden": (
+ ErrorCode.ACTION_FAILED,
+ "Selector matched an element that is not visible",
+ "The element exists but is not visible; it may be display:none or inside a collapsed container.",
+ ),
+ "disabled": (
+ ErrorCode.ACTION_FAILED,
+ "Selector matched a disabled element",
+ "The element exists but is disabled; wait for it to become enabled or choose an enabled control.",
+ ),
+ "occluded": (
+ ErrorCode.ACTION_FAILED,
+ "Selector matched an element blocked by another element",
+ "Another element is intercepting the action; close overlays, scroll, or target the visible control.",
+ ),
+ "unknown": (
+ ErrorCode.ACTION_FAILED,
+ "Direct action failed before the element became actionable",
+ "Re-check the selector and page state, or use an intent-based action if the target is dynamic.",
+ ),
+}
+
+
+def is_direct_action(selector: str | None, ai_mode: str | None, *, deterministic: bool = False) -> bool:
+ return selector is not None and (ai_mode is None or deterministic)
+
+
+def _direct_action_timeout_default_ms() -> int:
+ raw_value = os.environ.get(DIRECT_ACTION_TIMEOUT_ENV)
+ if raw_value is None:
+ return DEFAULT_DIRECT_ACTION_TIMEOUT_MS
+ try:
+ timeout = int(raw_value)
+ except ValueError:
+ return DEFAULT_DIRECT_ACTION_TIMEOUT_MS
+ return max(MIN_ACTION_TIMEOUT_MS, min(MAX_ACTION_TIMEOUT_MS, timeout))
+
+
+def resolve_action_timeout_ms(timeout: int | None, *, direct_action: bool) -> int:
+ if timeout is not None:
+ return timeout
+ return _direct_action_timeout_default_ms() if direct_action else DEFAULT_ACTION_TIMEOUT_MS
+
+
+def is_pointer_interception_error(exc: Exception) -> bool:
+ message = str(exc).lower()
+ return "intercepts pointer events" in message or "intercepted by another element" in message
+
+
+async def classify_element_state(page: Any, selector: str, *, pointer_intercepted: bool = False) -> ElementState:
+ # Frame-aware actions resolve against SkyvernPage._locator_scope (working iframe if set);
+ # the probe must query the same root or an iframe failure misclassifies as not_found.
+ probe_root = getattr(page, "_locator_scope", None)
+ if probe_root is None:
+ probe_root = page.page
+
+ async def _probe() -> ElementState:
+ locator = probe_root.locator(selector)
+ if await locator.count() == 0:
+ return "not_found"
+ first = locator.first
+ if not await first.is_visible():
+ return "hidden"
+ if not await first.is_enabled():
+ return "disabled"
+ if pointer_intercepted:
+ return "occluded"
+ return "unknown"
+
+ try:
+ return await asyncio.wait_for(_probe(), timeout=ELEMENT_STATE_PROBE_TIMEOUT_MS / 1000)
+ except Exception:
+ return "unknown"
+
+
+def element_state_error(state: ElementState, exc: Exception, *, selector: str, timeout_ms: int) -> dict[str, Any]:
+ code, message, hint = _STATE_ERRORS[state]
+ return make_error(
+ code,
+ message,
+ hint,
+ details={
+ "element_state": state,
+ "selector": selector,
+ "actionability_timeout_ms": timeout_ms,
+ "exception_type": type(exc).__name__,
+ },
+ )
+
+
+async def make_direct_action_error(page: Any, selector: str, exc: Exception, *, timeout_ms: int) -> dict[str, Any]:
+ state = await classify_element_state(page, selector, pointer_intercepted=is_pointer_interception_error(exc))
+ return element_state_error(state, exc, selector=selector, timeout_ms=timeout_ms)
diff --git a/skyvern/cli/mcp_tools/browser.py b/skyvern/cli/mcp_tools/browser.py
index b479b4127..ab9e27b8e 100644
--- a/skyvern/cli/mcp_tools/browser.py
+++ b/skyvern/cli/mcp_tools/browser.py
@@ -15,6 +15,7 @@ from skyvern.cli.core.browser_ops import (
_ALLOWED_EXECUTE_TOOLS,
MAX_EXECUTE_STEPS,
ExecuteStep,
+ ToolStepError,
do_act,
do_execute,
do_extract,
@@ -52,6 +53,17 @@ from ._common import (
make_result,
save_artifact,
)
+from ._element_state import (
+ ACTION_TIMEOUT_DESCRIPTION,
+ MAX_ACTION_TIMEOUT_MS,
+ MIN_ACTION_TIMEOUT_MS,
+ classify_element_state,
+ element_state_error,
+ is_direct_action,
+ is_pointer_interception_error,
+ make_direct_action_error,
+ resolve_action_timeout_ms,
+)
from ._localhost import is_localhost_url
from ._session import BrowserNotAvailableError, get_current_session, get_page, no_browser_error
@@ -124,6 +136,46 @@ def _must_reject_localhost_url(ctx: Any, url: str | None) -> bool:
return bool(url and is_localhost_url(url) and getattr(ctx, "can_access_localhost", None) is False)
+async def _direct_failure_result(
+ action: str,
+ ctx: Any,
+ timer: Timer,
+ page: Any,
+ selector: str,
+ exc: Exception,
+ timeout_ms: int,
+) -> dict[str, Any]:
+ return make_result(
+ action,
+ ok=False,
+ browser_context=ctx,
+ timing_ms=timer.timing_ms,
+ error=await make_direct_action_error(page, selector, exc, timeout_ms=timeout_ms),
+ )
+
+
+async def _drag_failure_error(
+ page: Any,
+ source_selector: str,
+ target_selector: str | None,
+ exc: Exception,
+ timeout_ms: int,
+) -> dict[str, Any]:
+ # Probe both ends without the pointer-interception hint: interception during a drag usually
+ # happens at the drop point, so an actionable source must not absorb the occluded label.
+ failed_selector = source_selector
+ state = await classify_element_state(page, source_selector)
+ if state == "unknown" and target_selector is not None:
+ failed_selector = target_selector
+ state = await classify_element_state(page, target_selector)
+ if state == "unknown" and is_pointer_interception_error(exc):
+ state = "occluded"
+ error = element_state_error(state, exc, selector=failed_selector, timeout_ms=timeout_ms)
+ if failed_selector != source_selector:
+ error["details"]["source_selector"] = source_selector
+ return error
+
+
_SelectorMode = Annotated[
Literal["resilient", "direct"],
Field(
@@ -231,13 +283,9 @@ async def skyvern_click(
session_id: Annotated[str | None, Field(description="Browser session ID (pbs_...)")] = None,
cdp_url: Annotated[str | None, Field(description="CDP WebSocket URL")] = None,
timeout: Annotated[
- int,
- Field(
- description="Max time to wait for the element in ms. Increase for slow-loading pages. Default 30000 (30s)",
- ge=1000,
- le=60000,
- ),
- ] = 30000,
+ int | None,
+ Field(description=ACTION_TIMEOUT_DESCRIPTION, ge=MIN_ACTION_TIMEOUT_MS, le=MAX_ACTION_TIMEOUT_MS),
+ ] = None,
button: Annotated[str | None, Field(description="Mouse button: left, right, middle")] = None,
click_count: Annotated[int | None, Field(description="Number of clicks (2 for double-click)")] = None,
intent: Annotated[str | None, Field(description=AI_FALLBACK_DESCRIPTION)] = None,
@@ -272,19 +320,21 @@ async def skyvern_click(
return make_result("skyvern_click", ok=False, error=no_browser_error())
deterministic = selector is not None and selector_mode == "direct"
+ direct_action = is_direct_action(selector, ai_mode, deterministic=deterministic)
+ action_timeout = resolve_action_timeout_ms(timeout, direct_action=direct_action)
used_ai_path = False
native_option_selection = None
resolved: str | None = None
with Timer() as timer:
try:
- kwargs: dict[str, Any] = {"timeout": timeout}
+ kwargs: dict[str, Any] = {"timeout": action_timeout}
if button:
kwargs["button"] = button
if click_count is not None:
kwargs["click_count"] = click_count
if selector is not None and (deterministic or ai_mode is None or ai_mode == "fallback"):
- native_option_selection = await select_native_option_if_targeted(page, selector, timeout=timeout)
+ native_option_selection = await select_native_option_if_targeted(page, selector, timeout=action_timeout)
if native_option_selection is not None:
resolved = native_option_selection.select_selector
@@ -300,6 +350,8 @@ async def skyvern_click(
resolved = await page.click(selector=selector, **kwargs)
timer.mark("sdk")
except PlaywrightTimeoutError as e:
+ if direct_action and selector is not None:
+ return await _direct_failure_result("skyvern_click", ctx, timer, page, selector, e, action_timeout)
return make_result(
"skyvern_click",
ok=False,
@@ -313,6 +365,8 @@ async def skyvern_click(
)
except Exception as e:
code = ErrorCode.AI_FALLBACK_FAILED if used_ai_path else ErrorCode.ACTION_FAILED
+ if direct_action and selector is not None and is_pointer_interception_error(e):
+ return await _direct_failure_result("skyvern_click", ctx, timer, page, selector, e, action_timeout)
return make_result(
"skyvern_click",
ok=False,
@@ -387,13 +441,9 @@ async def skyvern_drag(
session_id: Annotated[str | None, Field(description="Browser session ID (pbs_...)")] = None,
cdp_url: Annotated[str | None, Field(description="CDP WebSocket URL")] = None,
timeout: Annotated[
- int,
- Field(
- description="Max time to wait for elements in ms. Default 30000 (30s)",
- ge=1000,
- le=60000,
- ),
- ] = 30000,
+ int | None,
+ Field(description=ACTION_TIMEOUT_DESCRIPTION, ge=MIN_ACTION_TIMEOUT_MS, le=MAX_ACTION_TIMEOUT_MS),
+ ] = None,
source_intent: Annotated[str | None, Field(description=AI_FALLBACK_DESCRIPTION)] = None,
target_intent: Annotated[str | None, Field(description=AI_FALLBACK_DESCRIPTION)] = None,
) -> dict[str, Any]:
@@ -425,6 +475,7 @@ async def skyvern_drag(
return make_result("skyvern_drag", ok=False, error=no_browser_error())
use_selectors = source_selector and target_selector and not source_intent and not target_intent
+ action_timeout = resolve_action_timeout_ms(timeout, direct_action=bool(use_selectors))
with Timer() as timer:
try:
@@ -432,7 +483,7 @@ async def skyvern_drag(
await page.page.drag_and_drop(
source_selector,
target_selector,
- timeout=timeout, # type: ignore[arg-type]
+ timeout=action_timeout, # type: ignore[arg-type]
)
else:
src = source_intent or source_selector
@@ -440,6 +491,15 @@ async def skyvern_drag(
await do_act(page, f"Drag {src} and drop it onto {tgt}")
timer.mark("sdk")
except PlaywrightTimeoutError as e:
+ if use_selectors:
+ assert source_selector is not None
+ return make_result(
+ "skyvern_drag",
+ ok=False,
+ browser_context=ctx,
+ timing_ms=timer.timing_ms,
+ error=await _drag_failure_error(page, source_selector, target_selector, e, action_timeout),
+ )
return make_result(
"skyvern_drag",
ok=False,
@@ -452,6 +512,15 @@ async def skyvern_drag(
),
)
except Exception as e:
+ if use_selectors and is_pointer_interception_error(e):
+ assert source_selector is not None
+ return make_result(
+ "skyvern_drag",
+ ok=False,
+ browser_context=ctx,
+ timing_ms=timer.timing_ms,
+ error=await _drag_failure_error(page, source_selector, target_selector, e, action_timeout),
+ )
return make_result(
"skyvern_drag",
ok=False,
@@ -488,13 +557,9 @@ async def skyvern_file_upload(
session_id: Annotated[str | None, Field(description="Browser session ID (pbs_...)")] = None,
cdp_url: Annotated[str | None, Field(description="CDP WebSocket URL")] = None,
timeout: Annotated[
- int,
- Field(
- description="Max time to wait for the element in ms. Default 30000 (30s)",
- ge=1000,
- le=60000,
- ),
- ] = 30000,
+ int | None,
+ Field(description=ACTION_TIMEOUT_DESCRIPTION, ge=MIN_ACTION_TIMEOUT_MS, le=MAX_ACTION_TIMEOUT_MS),
+ ] = None,
intent: Annotated[str | None, Field(description=AI_FALLBACK_DESCRIPTION)] = None,
) -> dict[str, Any]:
"""Upload files to a file input element. Accepts local paths or URLs (auto-downloaded).
@@ -522,6 +587,8 @@ async def skyvern_file_upload(
"Use intent='the file upload button' or selector='input[type=file]'",
),
)
+ direct_action = is_direct_action(selector, ai_mode)
+ action_timeout = resolve_action_timeout_ms(timeout, direct_action=direct_action)
has_urls = any(fp.startswith(("http://", "https://", "s3://", "gs://", "azure://")) for fp in file_paths)
has_local = any(not fp.startswith(("http://", "https://", "s3://", "gs://", "azure://")) for fp in file_paths)
@@ -575,11 +642,11 @@ async def skyvern_file_upload(
files=fp,
prompt=intent,
ai=ai_mode,
- timeout=timeout,
+ timeout=action_timeout,
)
else:
assert selector is not None
- await page.upload_file(selector=selector, files=fp, timeout=timeout)
+ await page.upload_file(selector=selector, files=fp, timeout=action_timeout)
elif ai_mode is not None and len(file_paths) == 1:
# Single local file + intent: use SDK for AI element resolution
await page.upload_file(
@@ -587,16 +654,20 @@ async def skyvern_file_upload(
files=file_paths[0],
prompt=intent,
ai=ai_mode,
- timeout=timeout,
+ timeout=action_timeout,
)
else:
# Local files + selector: set directly via Playwright
assert selector is not None
locator = page.page.locator(selector).first
- await locator.set_input_files(file_paths, timeout=timeout)
+ await locator.set_input_files(file_paths, timeout=action_timeout)
timer.mark("sdk")
except PlaywrightTimeoutError as e:
+ if direct_action and selector is not None:
+ return await _direct_failure_result(
+ "skyvern_file_upload", ctx, timer, page, selector, e, action_timeout
+ )
return make_result(
"skyvern_file_upload",
ok=False,
@@ -610,6 +681,10 @@ async def skyvern_file_upload(
)
except Exception as e:
code = ErrorCode.AI_FALLBACK_FAILED if ai_mode else ErrorCode.ACTION_FAILED
+ if direct_action and selector is not None and is_pointer_interception_error(e):
+ return await _direct_failure_result(
+ "skyvern_file_upload", ctx, timer, page, selector, e, action_timeout
+ )
return make_result(
"skyvern_file_upload",
ok=False,
@@ -633,13 +708,9 @@ async def skyvern_hover(
session_id: Annotated[str | None, Field(description="Browser session ID (pbs_...)")] = None,
cdp_url: Annotated[str | None, Field(description="CDP WebSocket URL")] = None,
timeout: Annotated[
- int,
- Field(
- description="Max time to wait for the element in ms. Default 30000 (30s)",
- ge=1000,
- le=60000,
- ),
- ] = 30000,
+ int | None,
+ Field(description=ACTION_TIMEOUT_DESCRIPTION, ge=MIN_ACTION_TIMEOUT_MS, le=MAX_ACTION_TIMEOUT_MS),
+ ] = None,
intent: Annotated[str | None, Field(description=AI_FALLBACK_DESCRIPTION)] = None,
) -> dict[str, Any]:
"""Hover over an element to reveal tooltips, menus, or hidden content. Uses AI intent, CSS/XPath selector, or both."""
@@ -654,6 +725,8 @@ async def skyvern_hover(
"Use intent='describe what to hover' for AI-powered hovering, or selector='#css-selector' for precise targeting",
),
)
+ direct_action = is_direct_action(selector, ai_mode)
+ action_timeout = resolve_action_timeout_ms(timeout, direct_action=direct_action)
try:
page, ctx = await get_page(session_id=session_id, cdp_url=cdp_url)
@@ -667,9 +740,11 @@ async def skyvern_hover(
else:
assert selector is not None
loc = page.locator(selector)
- await loc.hover(timeout=timeout)
+ await loc.hover(timeout=action_timeout)
timer.mark("sdk")
except PlaywrightTimeoutError as e:
+ if direct_action and selector is not None:
+ return await _direct_failure_result("skyvern_hover", ctx, timer, page, selector, e, action_timeout)
return make_result(
"skyvern_hover",
ok=False,
@@ -683,6 +758,8 @@ async def skyvern_hover(
)
except Exception as e:
code = ErrorCode.AI_FALLBACK_FAILED if ai_mode else ErrorCode.ACTION_FAILED
+ if direct_action and selector is not None and is_pointer_interception_error(e):
+ return await _direct_failure_result("skyvern_hover", ctx, timer, page, selector, e, action_timeout)
return make_result(
"skyvern_hover",
ok=False,
@@ -721,13 +798,9 @@ async def skyvern_type(
session_id: Annotated[str | None, Field(description="Browser session ID (pbs_...)")] = None,
cdp_url: Annotated[str | None, Field(description="CDP WebSocket URL")] = None,
timeout: Annotated[
- int,
- Field(
- description="Max time to wait for the element in ms. Increase for slow-loading pages. Default 30000 (30s)",
- ge=1000,
- le=60000,
- ),
- ] = 30000,
+ int | None,
+ Field(description=ACTION_TIMEOUT_DESCRIPTION, ge=MIN_ACTION_TIMEOUT_MS, le=MAX_ACTION_TIMEOUT_MS),
+ ] = None,
clear: Annotated[bool, Field(description="Clear existing content before typing")] = True,
delay: Annotated[int | None, Field(description="Delay between keystrokes in ms")] = None,
intent: Annotated[str | None, Field(description=AI_FALLBACK_DESCRIPTION)] = None,
@@ -791,6 +864,9 @@ async def skyvern_type(
)
deterministic = selector is not None and selector_mode == "direct"
+ direct_action = is_direct_action(selector, ai_mode, deterministic=deterministic)
+ action_timeout = resolve_action_timeout_ms(timeout, direct_action=direct_action)
+
with Timer() as timer:
try:
# selector_mode="direct" pins the selector with no AI fall-back. Resilient (default) and
@@ -799,14 +875,14 @@ async def skyvern_type(
if clear:
if deterministic:
assert selector is not None
- await page.fill(selector, text, mode="direct", timeout=timeout)
+ await page.fill(selector, text, mode="direct", timeout=action_timeout)
elif ai_mode is not None:
- await page.fill(selector=selector, value=text, prompt=intent, ai=ai_mode, timeout=timeout) # type: ignore[arg-type]
+ await page.fill(selector=selector, value=text, prompt=intent, ai=ai_mode, timeout=action_timeout) # type: ignore[arg-type]
else:
assert selector is not None
- await page.fill(selector, text, timeout=timeout)
+ await page.fill(selector, text, timeout=action_timeout)
else:
- kwargs: dict[str, Any] = {"timeout": timeout}
+ kwargs: dict[str, Any] = {"timeout": action_timeout}
if delay is not None:
kwargs["delay"] = delay
if deterministic:
@@ -819,6 +895,8 @@ async def skyvern_type(
await page.type(selector, text, **kwargs)
timer.mark("sdk")
except PlaywrightTimeoutError as e:
+ if direct_action and selector is not None:
+ return await _direct_failure_result("skyvern_type", ctx, timer, page, selector, e, action_timeout)
return make_result(
"skyvern_type",
ok=False,
@@ -832,6 +910,8 @@ async def skyvern_type(
)
except Exception as e:
code = ErrorCode.AI_FALLBACK_FAILED if (ai_mode and not deterministic) else ErrorCode.ACTION_FAILED
+ if direct_action and selector is not None and is_pointer_interception_error(e):
+ return await _direct_failure_result("skyvern_type", ctx, timer, page, selector, e, action_timeout)
return make_result(
"skyvern_type",
ok=False,
@@ -1040,8 +1120,9 @@ async def skyvern_select_option(
session_id: Annotated[str | None, Field(description="Browser session ID (pbs_...)")] = None,
cdp_url: Annotated[str | None, Field(description="CDP WebSocket URL")] = None,
timeout: Annotated[
- int, Field(description="Max time to wait for the dropdown in ms. Default 30000 (30s)", ge=1000, le=60000)
- ] = 30000,
+ int | None,
+ Field(description=ACTION_TIMEOUT_DESCRIPTION, ge=MIN_ACTION_TIMEOUT_MS, le=MAX_ACTION_TIMEOUT_MS),
+ ] = None,
by_label: Annotated[bool, Field(description="Select by visible label instead of value")] = False,
intent: Annotated[str | None, Field(description=AI_FALLBACK_DESCRIPTION)] = None,
) -> dict[str, Any]:
@@ -1069,24 +1150,55 @@ async def skyvern_select_option(
return make_result("skyvern_select_option", ok=False, error=no_browser_error())
deterministic = selector is not None and selector_mode == "direct"
+ direct_action = is_direct_action(selector, ai_mode, deterministic=deterministic)
+ action_timeout = resolve_action_timeout_ms(timeout, direct_action=direct_action)
+
with Timer() as timer:
try:
# selector_mode="direct" pins the selector with no AI fall-back. Only an intent-only call
# (no selector) uses AI to interpret the option text.
if ai_mode is not None and not deterministic:
- await page.select_option(selector=selector, value=value, prompt=intent, ai=ai_mode, timeout=timeout) # type: ignore[arg-type]
+ await page.select_option(
+ selector=selector, # type: ignore[arg-type]
+ value=value,
+ prompt=intent,
+ ai=ai_mode,
+ timeout=action_timeout,
+ )
else:
assert selector is not None
if by_label:
# Bypass SkyvernPage to avoid value="" coercion conflicting with label kwarg.
- await page.page.locator(selector).select_option(label=value, timeout=timeout)
+ await page.page.locator(selector).select_option(label=value, timeout=action_timeout)
elif deterministic:
- await page.select_option(selector, value=value, ai=None, timeout=timeout)
+ await page.select_option(selector, value=value, ai=None, timeout=action_timeout)
else:
- await page.select_option(selector, value=value, timeout=timeout)
+ await page.select_option(selector, value=value, timeout=action_timeout)
timer.mark("sdk")
+ except PlaywrightTimeoutError as e:
+ if direct_action and selector is not None:
+ return await _direct_failure_result(
+ "skyvern_select_option", ctx, timer, page, selector, e, action_timeout
+ )
+ code = ErrorCode.AI_FALLBACK_FAILED if (ai_mode and not deterministic) else ErrorCode.ACTION_FAILED
+ return make_result(
+ "skyvern_select_option",
+ ok=False,
+ browser_context=ctx,
+ timing_ms=timer.timing_ms,
+ error=make_error(
+ code,
+ _exception_message(e),
+ "Check selector and available options",
+ details=_exception_details(e),
+ ),
+ )
except Exception as e:
code = ErrorCode.AI_FALLBACK_FAILED if (ai_mode and not deterministic) else ErrorCode.ACTION_FAILED
+ if direct_action and selector is not None and is_pointer_interception_error(e):
+ return await _direct_failure_result(
+ "skyvern_select_option", ctx, timer, page, selector, e, action_timeout
+ )
return make_result(
"skyvern_select_option",
ok=False,
@@ -1126,6 +1238,10 @@ async def skyvern_press_key(
] = None,
session_id: Annotated[str | None, Field(description="Browser session ID (pbs_...)")] = None,
cdp_url: Annotated[str | None, Field(description="CDP WebSocket URL")] = None,
+ timeout: Annotated[
+ int | None,
+ Field(description=ACTION_TIMEOUT_DESCRIPTION, ge=MIN_ACTION_TIMEOUT_MS, le=MAX_ACTION_TIMEOUT_MS),
+ ] = None,
intent: Annotated[str | None, Field(description=AI_FALLBACK_DESCRIPTION)] = None,
) -> dict[str, Any]:
"""Press a keyboard key -- Enter, Tab, Escape, arrow keys, shortcuts, etc.
@@ -1138,20 +1254,28 @@ async def skyvern_press_key(
except BrowserNotAvailableError:
return make_result("skyvern_press_key", ok=False, error=no_browser_error())
+ ai_mode = _resolve_ai_mode(selector, intent)[0] if (intent or selector) else None
+ direct_action = is_direct_action(selector, ai_mode)
+ action_timeout = resolve_action_timeout_ms(timeout, direct_action=direct_action)
+
with Timer() as timer:
try:
if intent or selector:
- ai_mode, _ = _resolve_ai_mode(selector, intent)
if ai_mode is not None:
loc = page.locator(selector=selector, prompt=intent, ai=ai_mode) # type: ignore[arg-type]
+ await loc.press(key, timeout=action_timeout)
else:
assert selector is not None
- loc = page.locator(selector)
- await loc.press(key)
+ await page.locator(selector).press(key, timeout=action_timeout)
else:
await page.keyboard.press(key)
timer.mark("sdk")
except Exception as e:
+ if direct_action and selector is not None:
+ if isinstance(e, PlaywrightTimeoutError) or is_pointer_interception_error(e):
+ return await _direct_failure_result(
+ "skyvern_press_key", ctx, timer, page, selector, e, action_timeout
+ )
return make_result(
"skyvern_press_key",
ok=False,
@@ -2182,7 +2306,7 @@ _TOOL_ACCEPTED_PARAMS: dict[str, frozenset[str]] = {
"navigate": frozenset({"url", "timeout", "wait_until"}),
"click": frozenset({"intent", "selector", "timeout", "click_count", "button"}),
"type": frozenset({"text", "intent", "selector", "clear_first", "press_enter", "timeout"}),
- "press_key": frozenset({"key", "intent", "selector"}),
+ "press_key": frozenset({"key", "intent", "selector", "timeout"}),
"select_option": frozenset({"value", "intent", "selector", "timeout", "by_label"}),
"hover": frozenset({"intent", "selector", "timeout"}),
"scroll": frozenset({"direction", "amount", "intent", "selector"}),
@@ -2241,8 +2365,7 @@ async def _dispatch_step(
tool_result = await tool_fn(**filtered_params)
if not tool_result.get("ok", False):
- error = tool_result.get("error", {})
- raise RuntimeError(error.get("message", "Tool execution failed"))
+ raise ToolStepError(tool_result.get("error") or {})
return tool_result.get("data")
diff --git a/skyvern/client/types/task_run_list_item.py b/skyvern/client/types/task_run_list_item.py
index f816909de..fcb7bb79e 100644
--- a/skyvern/client/types/task_run_list_item.py
+++ b/skyvern/client/types/task_run_list_item.py
@@ -5,6 +5,7 @@ import typing
import pydantic
from ..core.pydantic_utilities import IS_PYDANTIC_V2, UniversalBaseModel
+from .workflow_run_trigger_type import WorkflowRunTriggerType
class TaskRunListItem(UniversalBaseModel):
@@ -23,6 +24,7 @@ class TaskRunListItem(UniversalBaseModel):
workflow_permanent_id: typing.Optional[str] = None
workflow_deleted: typing.Optional[bool] = None
script_run: typing.Optional[bool] = None
+ trigger_type: typing.Optional[WorkflowRunTriggerType] = None
if IS_PYDANTIC_V2:
model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow", frozen=True) # type: ignore # Pydantic v2
diff --git a/skyvern/client/types/workflow_run_trigger_type.py b/skyvern/client/types/workflow_run_trigger_type.py
index 2d04cf802..5fccfb518 100644
--- a/skyvern/client/types/workflow_run_trigger_type.py
+++ b/skyvern/client/types/workflow_run_trigger_type.py
@@ -2,4 +2,4 @@
import typing
-WorkflowRunTriggerType = typing.Union[typing.Literal["manual", "api", "scheduled", "webhook"], typing.Any]
+WorkflowRunTriggerType = typing.Union[typing.Literal["manual", "mcp", "api", "scheduled", "webhook"], typing.Any]
diff --git a/skyvern/forge/sdk/api/llm/api_handler_factory.py b/skyvern/forge/sdk/api/llm/api_handler_factory.py
index d06ff6051..311211df1 100644
--- a/skyvern/forge/sdk/api/llm/api_handler_factory.py
+++ b/skyvern/forge/sdk/api/llm/api_handler_factory.py
@@ -45,7 +45,7 @@ from skyvern.forge.sdk.artifact.manager import BulkArtifactCreationRequest
from skyvern.forge.sdk.artifact.models import ArtifactType
from skyvern.forge.sdk.core import skyvern_context
from skyvern.forge.sdk.core.skyvern_context import EnrichTreeMode, SkyvernContext
-from skyvern.forge.sdk.db.enums import WorkflowRunTriggerType
+from skyvern.forge.sdk.db.enums import is_manual_like_workflow_run_trigger_type
from skyvern.forge.sdk.experimentation.prompt_families import effective_prompt_schema_variant
from skyvern.forge.sdk.models import SpeculativeLLMMetadata, Step
from skyvern.forge.sdk.schemas.ai_suggestions import AISuggestion
@@ -883,9 +883,9 @@ class LLMAPIHandlerFactory:
@staticmethod
def _maybe_get_non_flex_handler(default: LLMAPIHandler) -> LLMAPIHandler | None:
"""Mirror of `_maybe_get_flex_handler` for the inverse direction: swap a flex
- default for its non-flex twin when `trigger_type == manual` (UI/MCP)."""
+ default for its non-flex twin when `trigger_type` is manual-like."""
ctx = skyvern_context.current()
- if ctx is None or ctx.trigger_type != WorkflowRunTriggerType.manual:
+ if ctx is None or not is_manual_like_workflow_run_trigger_type(ctx.trigger_type):
return None
effective_key = (
getattr(default, "llm_key", None)
diff --git a/skyvern/forge/sdk/db/enums.py b/skyvern/forge/sdk/db/enums.py
index 15a5b8925..40c9bc984 100644
--- a/skyvern/forge/sdk/db/enums.py
+++ b/skyvern/forge/sdk/db/enums.py
@@ -20,12 +20,26 @@ class WorkflowRunTriggerType(StrEnum):
"""How a workflow run was initiated.
- manual: User clicked "Run" in the UI
+ - mcp: First-party MCP client request
- api: Direct API call to the run endpoint
- scheduled: Triggered by a cron schedule
- webhook: Triggered by an external system via the webhook endpoint
"""
manual = "manual"
+ mcp = "mcp"
api = "api"
scheduled = "scheduled"
webhook = "webhook"
+
+
+MANUAL_LIKE_WORKFLOW_RUN_TRIGGER_TYPES = frozenset(
+ {
+ WorkflowRunTriggerType.manual,
+ WorkflowRunTriggerType.mcp,
+ }
+)
+
+
+def is_manual_like_workflow_run_trigger_type(trigger_type: WorkflowRunTriggerType | None) -> bool:
+ return trigger_type in MANUAL_LIKE_WORKFLOW_RUN_TRIGGER_TYPES
diff --git a/skyvern/forge/sdk/db/repositories/workflow_runs.py b/skyvern/forge/sdk/db/repositories/workflow_runs.py
index 74ef678f6..8f9fc09e5 100644
--- a/skyvern/forge/sdk/db/repositories/workflow_runs.py
+++ b/skyvern/forge/sdk/db/repositories/workflow_runs.py
@@ -602,6 +602,7 @@ class WorkflowRunsRepository(BaseRepository):
TaskRunModel.created_at.label("created_at"),
effective_wpid.label("workflow_permanent_id"),
TaskRunModel.script_run.label("script_run"),
+ WorkflowRunModel.trigger_type.label("trigger_type"),
TaskRunModel.searchable_text.label("searchable_text"),
workflow_deleted_expr,
)
@@ -672,6 +673,7 @@ class WorkflowRunsRepository(BaseRepository):
WorkflowRunModel.created_at.label("created_at"),
WorkflowRunModel.workflow_permanent_id.label("workflow_permanent_id"),
WorkflowRunModel.script_run.label("script_run"),
+ WorkflowRunModel.trigger_type.label("trigger_type"),
WorkflowModel.title.label("searchable_text"),
self._workflow_deleted_expr(
WorkflowRunModel.workflow_permanent_id,
diff --git a/skyvern/forge/sdk/routes/trigger_type.py b/skyvern/forge/sdk/routes/trigger_type.py
index e8373a89d..9eaf1c7e7 100644
--- a/skyvern/forge/sdk/routes/trigger_type.py
+++ b/skyvern/forge/sdk/routes/trigger_type.py
@@ -1,10 +1,10 @@
from skyvern.constants import SKYVERN_MCP_USER_AGENT, SKYVERN_UI_USER_AGENT
from skyvern.forge.sdk.db.enums import WorkflowRunTriggerType
-_MANUAL_USER_AGENTS = frozenset({SKYVERN_UI_USER_AGENT, SKYVERN_MCP_USER_AGENT})
-
def workflow_run_trigger_type_from_user_agent(x_user_agent: str | None) -> WorkflowRunTriggerType:
- if x_user_agent in _MANUAL_USER_AGENTS:
+ if x_user_agent == SKYVERN_UI_USER_AGENT:
return WorkflowRunTriggerType.manual
+ if x_user_agent == SKYVERN_MCP_USER_AGENT:
+ return WorkflowRunTriggerType.mcp
return WorkflowRunTriggerType.api
diff --git a/skyvern/schemas/runs.py b/skyvern/schemas/runs.py
index 34c865f86..3ee34a251 100644
--- a/skyvern/schemas/runs.py
+++ b/skyvern/schemas/runs.py
@@ -13,6 +13,7 @@ from pydantic import (
model_validator,
)
+from skyvern.forge.sdk.db.enums import WorkflowRunTriggerType
from skyvern.forge.sdk.schemas.files import FileInfo
from skyvern.forge.sdk.workflow.models.run_limits import (
WORKFLOW_RUN_DEFAULT_MAX_ELAPSED_TIME_MINUTES,
@@ -514,6 +515,7 @@ class TaskRunListItem(BaseModel):
workflow_permanent_id: str | None = None
workflow_deleted: bool = False
script_run: bool = False
+ trigger_type: WorkflowRunTriggerType | None = None
searchable_text: str | None = Field(default=None, exclude=True)
@field_validator("script_run", mode="before")
diff --git a/tests/unit/_mcp_browser_fakes.py b/tests/unit/_mcp_browser_fakes.py
index c57a0673a..1a5181972 100644
--- a/tests/unit/_mcp_browser_fakes.py
+++ b/tests/unit/_mcp_browser_fakes.py
@@ -49,6 +49,21 @@ def make_mock_page(
return page
+def make_probe_locator(
+ *,
+ count: int = 1,
+ visible: bool = True,
+ enabled: bool = True,
+ side_effect: Exception | None = None,
+) -> MagicMock:
+ locator = MagicMock()
+ locator.first = locator
+ locator.count = AsyncMock(side_effect=side_effect, return_value=count)
+ locator.is_visible = AsyncMock(side_effect=side_effect, return_value=visible)
+ locator.is_enabled = AsyncMock(side_effect=side_effect, return_value=enabled)
+ return locator
+
+
def make_skyvern_page(page: MagicMock) -> MagicMock:
wrapper = MagicMock()
wrapper.page = page
diff --git a/tests/unit/forge/sdk/test_trigger_type.py b/tests/unit/forge/sdk/test_trigger_type.py
index 82ae26835..71c9801f9 100644
--- a/tests/unit/forge/sdk/test_trigger_type.py
+++ b/tests/unit/forge/sdk/test_trigger_type.py
@@ -7,8 +7,8 @@ def test_workflow_run_trigger_type_from_user_agent_ui_returns_manual() -> None:
assert workflow_run_trigger_type_from_user_agent(SKYVERN_UI_USER_AGENT) == WorkflowRunTriggerType.manual
-def test_workflow_run_trigger_type_from_user_agent_mcp_returns_manual() -> None:
- assert workflow_run_trigger_type_from_user_agent(SKYVERN_MCP_USER_AGENT) == WorkflowRunTriggerType.manual
+def test_workflow_run_trigger_type_from_user_agent_mcp_returns_mcp() -> None:
+ assert workflow_run_trigger_type_from_user_agent(SKYVERN_MCP_USER_AGENT) == WorkflowRunTriggerType.mcp
def test_workflow_run_trigger_type_from_user_agent_none_returns_api() -> None:
diff --git a/tests/unit/test_credential_test_trigger_type.py b/tests/unit/test_credential_test_trigger_type.py
index 12d2ffc89..d09edc46a 100644
--- a/tests/unit/test_credential_test_trigger_type.py
+++ b/tests/unit/test_credential_test_trigger_type.py
@@ -16,7 +16,7 @@ from skyvern.schemas.runs import ProxyLocation
USER_AGENT_CASES = [
("skyvern-ui", WorkflowRunTriggerType.manual),
- ("skyvern-mcp", WorkflowRunTriggerType.manual),
+ ("skyvern-mcp", WorkflowRunTriggerType.mcp),
(None, WorkflowRunTriggerType.api),
("python-sdk/1.0", WorkflowRunTriggerType.api),
]
@@ -212,7 +212,7 @@ def _auth_override() -> SimpleNamespace:
"headers, expected",
[
({"x-user-agent": "skyvern-ui"}, WorkflowRunTriggerType.manual),
- ({"X-User-Agent": "skyvern-mcp"}, WorkflowRunTriggerType.manual),
+ ({"X-User-Agent": "skyvern-mcp"}, WorkflowRunTriggerType.mcp),
({}, WorkflowRunTriggerType.api),
({"x-user-agent": "python-sdk/1.0"}, WorkflowRunTriggerType.api),
],
diff --git a/tests/unit/test_mcp_browser_extensions.py b/tests/unit/test_mcp_browser_extensions.py
index a15fe2c0c..33b1f3d2a 100644
--- a/tests/unit/test_mcp_browser_extensions.py
+++ b/tests/unit/test_mcp_browser_extensions.py
@@ -10,6 +10,7 @@ import pytest
from skyvern.cli.core.result import BrowserContext
from skyvern.cli.mcp_tools import browser as mcp_browser
from skyvern.cli.mcp_tools.browser import _wrap_async_iife
+from tests.unit._mcp_browser_fakes import make_probe_locator
# -- Helpers --
@@ -112,7 +113,57 @@ class TestDrag:
result = await mcp_browser.skyvern_drag(source_selector="#src", target_selector="#tgt")
assert result["ok"] is True
assert result["data"]["mode"] == "selector"
- raw.drag_and_drop.assert_awaited_once_with("#src", "#tgt", timeout=30000)
+ raw.drag_and_drop.assert_awaited_once_with("#src", "#tgt", timeout=5000)
+
+ @pytest.mark.asyncio
+ async def test_selector_drag_timeout_attributes_hidden_target(self, monkeypatch: pytest.MonkeyPatch) -> None:
+ locators = {"#src": make_probe_locator(), "#tgt": make_probe_locator(visible=False)}
+ raw = MagicMock()
+ raw.drag_and_drop = AsyncMock(side_effect=mcp_browser.PlaywrightTimeoutError("Timeout 5000ms exceeded."))
+ raw.locator = MagicMock(side_effect=lambda selector: locators[selector])
+ page = _fake_page(raw)
+ _patch_get_page(monkeypatch, page=page)
+
+ result = await mcp_browser.skyvern_drag(source_selector="#src", target_selector="#tgt")
+
+ assert result["ok"] is False
+ assert result["error"]["details"]["element_state"] == "hidden"
+ assert result["error"]["details"]["selector"] == "#tgt"
+ assert result["error"]["details"]["source_selector"] == "#src"
+
+ @pytest.mark.asyncio
+ async def test_selector_drag_interception_attributes_occluded_target(self, monkeypatch: pytest.MonkeyPatch) -> None:
+ locators = {"#src": make_probe_locator(), "#tgt": make_probe_locator()}
+ raw = MagicMock()
+ raw.drag_and_drop = AsyncMock(
+ side_effect=mcp_browser.PlaywrightTimeoutError("<div class='overlay'></div> intercepts pointer events")
+ )
+ raw.locator = MagicMock(side_effect=lambda selector: locators[selector])
+ page = _fake_page(raw)
+ _patch_get_page(monkeypatch, page=page)
+
+ result = await mcp_browser.skyvern_drag(source_selector="#src", target_selector="#tgt")
+
+ assert result["ok"] is False
+ assert result["error"]["details"]["element_state"] == "occluded"
+ assert result["error"]["details"]["selector"] == "#tgt"
+ assert result["error"]["details"]["source_selector"] == "#src"
+
+ @pytest.mark.asyncio
+ async def test_selector_drag_timeout_attributes_missing_source(self, monkeypatch: pytest.MonkeyPatch) -> None:
+ locators = {"#src": make_probe_locator(count=0), "#tgt": make_probe_locator()}
+ raw = MagicMock()
+ raw.drag_and_drop = AsyncMock(side_effect=mcp_browser.PlaywrightTimeoutError("Timeout 5000ms exceeded."))
+ raw.locator = MagicMock(side_effect=lambda selector: locators[selector])
+ page = _fake_page(raw)
+ _patch_get_page(monkeypatch, page=page)
+
+ result = await mcp_browser.skyvern_drag(source_selector="#src", target_selector="#tgt")
+
+ assert result["ok"] is False
+ assert result["error"]["details"]["element_state"] == "not_found"
+ assert result["error"]["details"]["selector"] == "#src"
+ assert "source_selector" not in result["error"]["details"]
@pytest.mark.asyncio
async def test_intent_mode_calls_do_act(self, monkeypatch: pytest.MonkeyPatch) -> None:
@@ -174,7 +225,7 @@ class TestFileUpload:
assert result["data"]["files_count"] == 1
raw.locator.assert_called_once_with("input[type=file]")
# set_input_files receives a list with the single file
- mock_locator.set_input_files.assert_awaited_once_with(["/tmp/test.txt"], timeout=30000)
+ mock_locator.set_input_files.assert_awaited_once_with(["/tmp/test.txt"], timeout=5000)
@pytest.mark.asyncio
async def test_intent_only_local_file_uses_sdk(self, monkeypatch: pytest.MonkeyPatch) -> None:
@@ -206,7 +257,7 @@ class TestFileUpload:
page.upload_file.assert_awaited_once_with(
selector="input[type=file]",
files="https://example.com/file.pdf",
- timeout=30000,
+ timeout=5000,
)
@pytest.mark.asyncio
@@ -227,7 +278,7 @@ class TestFileUpload:
assert result["ok"] is True
assert result["data"]["files_count"] == 2
# Single call with both files, not two separate calls
- mock_locator.set_input_files.assert_awaited_once_with(["/tmp/a.txt", "/tmp/b.txt"], timeout=30000)
+ mock_locator.set_input_files.assert_awaited_once_with(["/tmp/a.txt", "/tmp/b.txt"], timeout=5000)
@pytest.mark.asyncio
async def test_multi_url_returns_error(self) -> None:
diff --git a/tests/unit/test_mcp_browser_tools.py b/tests/unit/test_mcp_browser_tools.py
index e664e9acb..28f74300e 100644
--- a/tests/unit/test_mcp_browser_tools.py
+++ b/tests/unit/test_mcp_browser_tools.py
@@ -12,6 +12,7 @@ from skyvern.cli.core.result import BrowserContext
from skyvern.cli.mcp_tools import browser as mcp_browser
from skyvern.cli.mcp_tools import mcp
from skyvern.client.errors import InternalServerError, UnprocessableEntityError
+from tests.unit._mcp_browser_fakes import make_probe_locator
@pytest.mark.asyncio
@@ -209,6 +210,25 @@ def _click_page(monkeypatch: pytest.MonkeyPatch) -> AsyncMock:
return click
+def _direct_click_page(
+ monkeypatch: pytest.MonkeyPatch,
+ *,
+ count: int = 1,
+ visible: bool = True,
+ enabled: bool = True,
+ probe_side_effect: Exception | None = None,
+ click_error: Exception | None = None,
+) -> tuple[AsyncMock, MagicMock]:
+ locator = make_probe_locator(count=count, visible=visible, enabled=enabled, side_effect=probe_side_effect)
+ raw_page = MagicMock()
+ raw_page.locator = MagicMock(return_value=locator)
+ click = AsyncMock(side_effect=click_error, return_value="#target")
+ page = SimpleNamespace(page=raw_page, click=click)
+ context = BrowserContext(mode="cloud_session", session_id="pbs_test")
+ monkeypatch.setattr(mcp_browser, "get_page", AsyncMock(return_value=(page, context)))
+ return click, locator
+
+
# Default (resilient) keeps the shared MCP surface unchanged for external callers: a selector
# tries first, then dismisses overlays and AI-falls-back. selector_mode="direct" (which the
# copilot binds via forced_args) opts into deterministic, no-AI behavior.
@@ -233,6 +253,236 @@ async def test_skyvern_click_selector_mode_direct_is_deterministic(monkeypatch:
assert "prompt" not in click.await_args.kwargs and "ai" not in click.await_args.kwargs
+async def test_skyvern_click_selector_only_uses_fast_direct_default_timeout(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ click = _click_page(monkeypatch)
+
+ result = await mcp_browser.skyvern_click(selector="#submit")
+
+ assert result["ok"] is True
+ assert click.await_args.kwargs["timeout"] == 5000
+
+
+async def test_skyvern_click_selector_mode_direct_uses_fast_default_timeout(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ click = _click_page(monkeypatch)
+
+ result = await mcp_browser.skyvern_click(selector="#submit", selector_mode="direct")
+
+ assert result["ok"] is True
+ assert click.await_args.kwargs["timeout"] == 5000
+
+
+async def test_skyvern_click_explicit_timeout_is_honored_on_direct_path(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ click = _click_page(monkeypatch)
+
+ result = await mcp_browser.skyvern_click(selector="#submit", timeout=1234)
+
+ assert result["ok"] is True
+ assert click.await_args.kwargs["timeout"] == 1234
+
+
+async def test_skyvern_click_selector_plus_intent_keeps_30s_default_timeout(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ click = _click_page(monkeypatch)
+
+ result = await mcp_browser.skyvern_click(selector="#submit", intent="the blue submit button")
+
+ assert result["ok"] is True
+ assert click.await_args.kwargs["timeout"] == 30000
+
+
+async def test_skyvern_click_intent_only_keeps_30s_default_timeout(monkeypatch: pytest.MonkeyPatch) -> None:
+ click = _click_page(monkeypatch)
+
+ result = await mcp_browser.skyvern_click(intent="the blue submit button")
+
+ assert result["ok"] is True
+ assert click.await_args.kwargs["timeout"] == 30000
+
+
+ ("env_value", "expected_timeout"),
+ [
+ ("2500", 2500),
+ ("42", 1000),
+ ("90000", 60000),
+ ("not-an-int", 5000),
+ ],
+)
+async def test_skyvern_click_direct_timeout_env_override_is_respected_and_clamped(
+ monkeypatch: pytest.MonkeyPatch,
+ env_value: str,
+ expected_timeout: int,
+) -> None:
+ monkeypatch.setenv("SKYVERN_MCP_DIRECT_TIMEOUT_MS", env_value)
+ click = _click_page(monkeypatch)
+
+ result = await mcp_browser.skyvern_click(selector="#submit")
+
+ assert result["ok"] is True
+ assert click.await_args.kwargs["timeout"] == expected_timeout
+
+
+ ("element_state", "count", "visible", "enabled", "message", "expected_code"),
+ [
+ ("not_found", 0, False, False, "Timeout 5000ms exceeded.", mcp_browser.ErrorCode.SELECTOR_NOT_FOUND),
+ ("hidden", 1, False, True, "Timeout 5000ms exceeded.", mcp_browser.ErrorCode.ACTION_FAILED),
+ ("disabled", 1, True, False, "Timeout 5000ms exceeded.", mcp_browser.ErrorCode.ACTION_FAILED),
+ (
+ "occluded",
+ 1,
+ True,
+ True,
+ "<div class='overlay'></div> intercepts pointer events",
+ mcp_browser.ErrorCode.ACTION_FAILED,
+ ),
+ ],
+)
+async def test_skyvern_click_direct_failure_reports_element_state(
+ monkeypatch: pytest.MonkeyPatch,
+ element_state: str,
+ count: int,
+ visible: bool,
+ enabled: bool,
+ message: str,
+ expected_code: str,
+) -> None:
+ click_error = mcp_browser.PlaywrightTimeoutError(message)
+ click, locator = _direct_click_page(
+ monkeypatch,
+ count=count,
+ visible=visible,
+ enabled=enabled,
+ click_error=click_error,
+ )
+
+ result = await mcp_browser.skyvern_click(selector="#target", selector_mode="direct")
+
+ assert result["ok"] is False
+ assert result["error"]["code"] == expected_code
+ assert result["error"]["details"]["element_state"] == element_state
+ assert result["error"]["hint"]
+ click.assert_awaited_once()
+ locator.count.assert_awaited_once()
+
+
+async def test_skyvern_click_direct_failure_probes_working_frame(monkeypatch: pytest.MonkeyPatch) -> None:
+ frame_locator = make_probe_locator(visible=False)
+ frame = MagicMock()
+ frame.locator = MagicMock(return_value=frame_locator)
+ main_locator = make_probe_locator(count=0)
+ raw_page = MagicMock()
+ raw_page.locator = MagicMock(return_value=main_locator)
+ click = AsyncMock(side_effect=mcp_browser.PlaywrightTimeoutError("Timeout 5000ms exceeded."))
+ page = SimpleNamespace(page=raw_page, click=click, _locator_scope=frame)
+ context = BrowserContext(mode="cloud_session", session_id="pbs_test")
+ monkeypatch.setattr(mcp_browser, "get_page", AsyncMock(return_value=(page, context)))
+
+ result = await mcp_browser.skyvern_click(selector="#in-iframe", selector_mode="direct")
+
+ assert result["ok"] is False
+ # Main frame has count=0: a main-frame probe would say not_found; hidden proves the frame was probed.
+ assert result["error"]["details"]["element_state"] == "hidden"
+ frame.locator.assert_called_once_with("#in-iframe")
+
+
+async def test_skyvern_click_direct_failure_reports_unknown_when_probe_fails(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ click, locator = _direct_click_page(
+ monkeypatch,
+ probe_side_effect=asyncio.TimeoutError(),
+ click_error=mcp_browser.PlaywrightTimeoutError("Timeout 5000ms exceeded."),
+ )
+
+ result = await mcp_browser.skyvern_click(selector="#target", selector_mode="direct")
+
+ assert result["ok"] is False
+ assert result["error"]["details"]["element_state"] == "unknown"
+ assert result["error"]["hint"]
+ click.assert_awaited_once()
+ locator.count.assert_awaited_once()
+
+
+async def test_skyvern_press_key_selector_only_uses_fast_default_timeout(monkeypatch: pytest.MonkeyPatch) -> None:
+ press = AsyncMock()
+ locator = MagicMock()
+ locator.press = press
+ page = SimpleNamespace(locator=MagicMock(return_value=locator))
+ context = BrowserContext(mode="cloud_session", session_id="pbs_test")
+ monkeypatch.setattr(mcp_browser, "get_page", AsyncMock(return_value=(page, context)))
+
+ result = await mcp_browser.skyvern_press_key(key="Enter", selector="#field")
+
+ assert result["ok"] is True
+ press.assert_awaited_once_with("Enter", timeout=5000)
+
+
+async def test_skyvern_press_key_intent_explicit_timeout_is_honored(monkeypatch: pytest.MonkeyPatch) -> None:
+ press = AsyncMock()
+ locator = MagicMock()
+ locator.press = press
+ page = SimpleNamespace(locator=MagicMock(return_value=locator))
+ context = BrowserContext(mode="cloud_session", session_id="pbs_test")
+ monkeypatch.setattr(mcp_browser, "get_page", AsyncMock(return_value=(page, context)))
+
+ result = await mcp_browser.skyvern_press_key(key="Enter", intent="the search box", timeout=1234)
+
+ assert result["ok"] is True
+ press.assert_awaited_once_with("Enter", timeout=1234)
+
+
+async def test_skyvern_press_key_intent_keeps_30s_default_timeout(monkeypatch: pytest.MonkeyPatch) -> None:
+ press = AsyncMock()
+ locator = MagicMock()
+ locator.press = press
+ page = SimpleNamespace(locator=MagicMock(return_value=locator))
+ context = BrowserContext(mode="cloud_session", session_id="pbs_test")
+ monkeypatch.setattr(mcp_browser, "get_page", AsyncMock(return_value=(page, context)))
+
+ result = await mcp_browser.skyvern_press_key(key="Enter", intent="the search box")
+
+ assert result["ok"] is True
+ press.assert_awaited_once_with("Enter", timeout=30000)
+
+
+async def test_skyvern_press_key_direct_failure_reports_element_state(monkeypatch: pytest.MonkeyPatch) -> None:
+ probe_locator = make_probe_locator(count=1, visible=False)
+ raw_page = MagicMock()
+ raw_page.locator = MagicMock(return_value=probe_locator)
+ press_locator = MagicMock()
+ press_locator.press = AsyncMock(side_effect=mcp_browser.PlaywrightTimeoutError("Timeout 5000ms exceeded."))
+ page = SimpleNamespace(page=raw_page, locator=MagicMock(return_value=press_locator))
+ context = BrowserContext(mode="cloud_session", session_id="pbs_test")
+ monkeypatch.setattr(mcp_browser, "get_page", AsyncMock(return_value=(page, context)))
+
+ result = await mcp_browser.skyvern_press_key(key="Enter", selector="#field")
+
+ assert result["ok"] is False
+ assert result["error"]["details"]["element_state"] == "hidden"
+ assert result["error"]["details"]["selector"] == "#field"
+
+
@pytest.mark.asyncio
async def test_skyvern_click_selector_plus_intent_falls_back_by_default(monkeypatch: pytest.MonkeyPatch) -> None:
click = _click_page(monkeypatch)
@@ -385,7 +635,7 @@ async def test_skyvern_click_native_option_selector_uses_parent_select(monkeypat
assert result["ok"] is True
page.click.assert_not_awaited()
- select_option.assert_awaited_once_with(value="east", timeout=30000)
+ select_option.assert_awaited_once_with(value="east", timeout=5000)
assert result["data"]["resolved_selector"] == "#region"
assert result["data"]["selected_option"] == {
"select_selector": "#region",
@@ -425,7 +675,7 @@ async def test_skyvern_click_native_option_selector_selects_by_index(monkeypatch
assert result["ok"] is True
page.click.assert_not_awaited()
- select_option.assert_awaited_once_with(index=3, timeout=30000)
+ select_option.assert_awaited_once_with(index=3, timeout=5000)
assert result["data"]["selected_option"]["selected_by"] == "index"
assert result["data"]["selected_option"]["index"] == 3
assert result["data"]["sdk_equivalent"] == 'await page.select_option("#region", index=3)'
diff --git a/tests/unit/test_mcp_observe_execute.py b/tests/unit/test_mcp_observe_execute.py
index c84068bcf..007f3fe57 100644
--- a/tests/unit/test_mcp_observe_execute.py
+++ b/tests/unit/test_mcp_observe_execute.py
@@ -890,7 +890,7 @@ class TestSkyvernExecuteMCP:
assert result["ok"] is True
assert result["data"]["steps_completed"] == 2
page.click.assert_not_awaited()
- select_option.assert_awaited_once_with(value="east", timeout=30000)
+ select_option.assert_awaited_once_with(value="east", timeout=5000)
assert result["data"]["results"][1]["data"]["resolved_selector"] == "#region"
@pytest.mark.asyncio
@@ -903,6 +903,31 @@ class TestSkyvernExecuteMCP:
assert result["ok"] is False
assert "unknown ref" in result["data"]["results"][0]["error"].lower()
+ @pytest.mark.asyncio
+ async def test_execute_preserves_structured_direct_failure_error(self, monkeypatch: pytest.MonkeyPatch) -> None:
+ page = _make_page()
+ ctx = BrowserContext(mode="local")
+ monkeypatch.setattr(mcp_browser, "get_page", AsyncMock(return_value=(page, ctx)))
+
+ click_result = {
+ "ok": False,
+ "error": {
+ "code": mcp_browser.ErrorCode.ACTION_FAILED,
+ "message": "Selector matched an element that is not visible",
+ "hint": "The element exists but is not visible.",
+ "details": {"element_state": "hidden", "selector": "#field", "actionability_timeout_ms": 5000},
+ },
+ }
+ monkeypatch.setattr(mcp_browser, "skyvern_click", AsyncMock(return_value=click_result))
+
+ result = await mcp_browser.skyvern_execute(steps=[{"tool": "click", "params": {"selector": "#field"}}])
+
+ assert result["ok"] is False
+ step_error = result["data"]["results"][0]["error"]
+ assert step_error["code"] == mcp_browser.ErrorCode.ACTION_FAILED
+ assert step_error["details"]["element_state"] == "hidden"
+ assert step_error["details"]["selector"] == "#field"
+
@pytest.mark.asyncio
async def test_execute_ref_to_unnamed_duplicate_uses_nth(self, monkeypatch: pytest.MonkeyPatch) -> None:
"""SKY-9701: clicking ref=e2 on a page with 4 unnamed comboboxes resolves to the 3rd, not the 1st."""
diff --git a/tests/unit/test_runs_v2_route.py b/tests/unit/test_runs_v2_route.py
index c7904cd37..488dcde4a 100644
--- a/tests/unit/test_runs_v2_route.py
+++ b/tests/unit/test_runs_v2_route.py
@@ -31,6 +31,7 @@ async def test_get_runs_v2_serializes_mapping_rows_from_database(monkeypatch: py
"workflow_permanent_id": "wpid_123",
"workflow_deleted": False,
"script_run": False,
+ "trigger_type": "mcp",
"searchable_text": "Workflow run",
}
]
@@ -66,6 +67,7 @@ async def test_get_runs_v2_serializes_mapping_rows_from_database(monkeypatch: py
"workflow_permanent_id": "wpid_123",
"workflow_deleted": False,
"script_run": False,
+ "trigger_type": "mcp",
}
]