Skip to content

Automate browser based workflows with AI

Let an MCP agent wait on two page states at once (SKY-13252) (#7941)

Andrew Neilson3891f4c41438
diff --git a/skyvern-frontend/src/routes/workflows/copilot/narrativeState.ts b/skyvern-frontend/src/routes/workflows/copilot/narrativeState.ts
index e5df4c912..2b9f8c3a4 100644
--- a/skyvern-frontend/src/routes/workflows/copilot/narrativeState.ts
+++ b/skyvern-frontend/src/routes/workflows/copilot/narrativeState.ts
@@ -365,6 +365,7 @@ const ACTIVITY_TOOL_DISPLAY_LABELS: Record<string, string> = {
select_option: "Selecting option",
press_key: "Interacting with page",
navigate_browser: "Opening page",
+ wait_for_either_state: "Waiting for the page",
get_block_schema: "Checking workflow block options",
inspect_current_workflow: "Inspecting workflow",
discover_workflow_entrypoint: "Finding the entry page",
diff --git a/skyvern/cli/core/browser_ops.py b/skyvern/cli/core/browser_ops.py
index 4aad0655d..d4d37bde4 100644
--- a/skyvern/cli/core/browser_ops.py
+++ b/skyvern/cli/core/browser_ops.py
@@ -1177,6 +1177,7 @@ _ALLOWED_EXECUTE_TOOLS = frozenset(
"hover",
"scroll",
"wait",
+ "wait_for_either_state",
"observe",
"screenshot",
"evaluate",
diff --git a/skyvern/cli/mcp_tools/__init__.py b/skyvern/cli/mcp_tools/__init__.py
index 06c0c0d3f..c12a6d6f7 100644
--- a/skyvern/cli/mcp_tools/__init__.py
+++ b/skyvern/cli/mcp_tools/__init__.py
@@ -44,6 +44,8 @@ except ImportError as fastmcp_import_error:
else:
_FASTMCP_IMPORT_ERROR = None
+from skyvern.cli.mcp_tools.browser import EITHER_STATE_OUTPUT_SCHEMA
+
from .blocks import (
skyvern_block_schema,
skyvern_block_validate,
@@ -78,6 +80,7 @@ from .browser import (
skyvern_type,
skyvern_validate,
skyvern_wait,
+ skyvern_wait_for_either_state,
)
from .browser_profiles import (
skyvern_browser_profile_create,
@@ -449,6 +452,11 @@ mcp.tool(tags={"browser_primitive"}, annotations=_web_mut("Scroll Page"))(skyver
mcp.tool(tags={"browser_primitive"}, annotations=_web_dest("Select Option"))(skyvern_select_option)
mcp.tool(tags={"browser_primitive"}, annotations=_web_dest("Press Key"))(skyvern_press_key)
mcp.tool(tags={"browser_primitive"}, annotations=_web_ro("Wait"))(skyvern_wait)
+mcp.tool(
+ tags={"browser_primitive"},
+ annotations=_web_ro("Wait For Either State"),
+ output_schema=EITHER_STATE_OUTPUT_SCHEMA,
+)(skyvern_wait_for_either_state)
mcp.tool(tags={"browser_primitive"}, annotations=_web_ro("Find Element"))(skyvern_find)
# -- Tab management (multi-tab) --
@@ -594,6 +602,7 @@ __all__ = [
"skyvern_select_option",
"skyvern_press_key",
"skyvern_wait",
+ "skyvern_wait_for_either_state",
"skyvern_find",
# Tab management
"skyvern_tab_list",
diff --git a/skyvern/cli/mcp_tools/browser.py b/skyvern/cli/mcp_tools/browser.py
index b227ec347..eee462fca 100644
--- a/skyvern/cli/mcp_tools/browser.py
+++ b/skyvern/cli/mcp_tools/browser.py
@@ -1867,6 +1867,42 @@ async def skyvern_press_key(
)
+async def _wait_for_either_selector(
+ page: Any,
+ selectors: tuple[str, str],
+ *,
+ state: str | None,
+ timeout: int,
+) -> tuple[str | None, BaseException | None]:
+ """Return the first selector to reach ``state``, or ``(None, error)`` if neither did. A waiter
+ that raises does not end the wait, so a malformed selector cannot beat a slow-but-valid one, and
+ ties go to the declared-first selector since both land in one ``done`` batch when both are ready.
+ """
+ tasks = {asyncio.create_task(page.wait_for_selector(sel, state=state, timeout=timeout)): sel for sel in selectors}
+ pending = set(tasks)
+ last_error: BaseException | None = None
+ try:
+ while pending:
+ done, pending = await asyncio.wait(pending, return_when=asyncio.FIRST_COMPLETED)
+ for task in sorted(done, key=lambda settled: selectors.index(tasks[settled])):
+ error = task.exception()
+ if error is None:
+ return tasks[task], None
+ # A malformed selector names the caller's mistake; a timeout only says the other
+ # side never appeared. Keep the diagnosable one when both sides fail.
+ if last_error is None or (
+ isinstance(last_error, PlaywrightTimeoutError) and not isinstance(error, PlaywrightTimeoutError)
+ ):
+ last_error = error
+ return None, last_error
+ finally:
+ for task in tasks:
+ task.cancel()
+ # asyncio.wait does not reap its children: drain every task so none outlives the call and
+ # no exception is left unretrieved.
+ await asyncio.gather(*tasks, return_exceptions=True)
+
+
async def skyvern_wait(
selector: Annotated[str | None, Field(description=f"{DIRECT_TARGET_DESCRIPTION} CSS selector to wait for.")] = None,
state: Annotated[str | None, Field(description="Element state: visible, hidden, attached, detached")] = "visible",
@@ -1958,6 +1994,15 @@ async def skyvern_wait(
waited_for = "selector"
timer.mark("sdk")
except Exception as e:
+ # A single-selector timeout is the one failure the caller can convert into a decision:
+ # it just spent the ceiling learning the page is not in the state it guessed.
+ hint = "Condition was not met within timeout"
+ if selector and state in (None, "visible", "attached"):
+ hint += (
+ ". The page was not in the state you named. If you were deciding between two states, "
+ "skyvern_wait_for_either_state takes both and returns the moment either appears, "
+ "instead of spending the ceiling on a wrong guess"
+ )
return action_result(
"skyvern_wait",
ok=False,
@@ -1966,22 +2011,114 @@ async def skyvern_wait(
error=make_error(
ErrorCode.TIMEOUT,
_exception_message(e),
- "Condition was not met within timeout",
+ hint,
details=_exception_details(e),
),
)
sdk_eq = ""
+ data: dict[str, Any] = {"waited_for": waited_for}
if waited_for == "time":
sdk_eq = f"await page.wait_for_timeout({time_ms})"
elif waited_for == "intent":
sdk_eq = f"await page.validate({intent!r})"
elif waited_for == "selector":
sdk_eq = f"await page.wait_for_selector({selector!r})"
+ data["sdk_equivalent"] = sdk_eq
return action_result(
"skyvern_wait",
browser_context=ctx,
- data={"waited_for": waited_for, "sdk_equivalent": sdk_eq},
+ data=data,
+ timing_ms=timer.timing_ms,
+ )
+
+
+EITHER_STATE_OUTPUT_SCHEMA: dict[str, Any] = {
+ "type": "object",
+ "properties": {
+ "ok": {"type": "boolean"},
+ "data": {
+ "type": ["object", "null"],
+ "properties": {
+ "matched_selector": {
+ "type": "string",
+ "description": "The selector that reached the state first. Branch on it.",
+ },
+ "matched": {
+ "type": "string",
+ "enum": ["selector_a", "selector_b"],
+ "description": "Which argument matched_selector came from.",
+ },
+ },
+ },
+ "error": {"type": ["object", "null"]},
+ },
+}
+
+
+async def skyvern_wait_for_either_state(
+ selector_a: Annotated[str, Field(description="CSS selector for the first page state, e.g. the sign-in form.")],
+ selector_b: Annotated[
+ str, Field(description="CSS selector for the second page state, e.g. an element only present once signed in.")
+ ],
+ state: Annotated[str | None, Field(description="Element state to wait for: visible or attached")] = "visible",
+ 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 wait time in milliseconds", ge=1000, le=120000)] = 90000,
+) -> dict[str, Any]:
+ """Find out which of two page states the page settled into — a sign-in form or an already
+ signed-in view, a challenge or the page behind it.
+
+ Returns as soon as either selector reaches `state`, with `matched_selector` naming the one that
+ did, so you can branch on the answer without inspecting the page again. Waiting on a single
+ selector instead spends the whole timeout proving that state is absent whenever it is the wrong
+ guess, which is why this takes both.
+ """
+ if state not in (None, "visible", "attached"):
+ return make_result(
+ "skyvern_wait_for_either_state",
+ ok=False,
+ error=make_error(
+ ErrorCode.INVALID_INPUT,
+ f"state must be visible or attached, not {state}",
+ "A selector matching nothing satisfies hidden and detached at once, so the absent side would win",
+ ),
+ )
+
+ try:
+ page, ctx = await get_page(session_id=session_id, cdp_url=cdp_url)
+ except BrowserNotAvailableError:
+ return make_result("skyvern_wait_for_either_state", ok=False, error=no_browser_error())
+
+ with Timer() as timer:
+ matched_selector, wait_error = await _wait_for_either_selector(
+ page, (selector_a, selector_b), state=state, timeout=timeout
+ )
+ timer.mark("sdk")
+
+ if matched_selector is None:
+ # A cancelled waiter surfaces as BaseException; only a real failure carries a reportable message.
+ failure = wait_error if isinstance(wait_error, Exception) else None
+ return _action_result_factory(ctx=ctx, page=page, selector=selector_a)(
+ "skyvern_wait_for_either_state",
+ ok=False,
+ browser_context=ctx,
+ timing_ms=timer.timing_ms,
+ error=make_error(
+ ErrorCode.TIMEOUT,
+ _exception_message(failure) if failure else f"Neither selector reached {state!r}",
+ "The page settled into neither state; both selectors may be wrong for this page",
+ details=_exception_details(failure) if failure else None,
+ ),
+ )
+
+ return _action_result_factory(ctx=ctx, page=page, selector=matched_selector)(
+ "skyvern_wait_for_either_state",
+ browser_context=ctx,
+ data={
+ "matched_selector": matched_selector,
+ "matched": "selector_a" if matched_selector == selector_a else "selector_b",
+ },
timing_ms=timer.timing_ms,
)
@@ -3160,6 +3297,7 @@ _TOOL_NAME_MAP: dict[str, str] = {
"hover": "skyvern_hover",
"scroll": "skyvern_scroll",
"wait": "skyvern_wait",
+ "wait_for_either_state": "skyvern_wait_for_either_state",
"screenshot": "skyvern_screenshot",
"evaluate": "skyvern_evaluate",
}
@@ -3174,6 +3312,7 @@ _TOOL_ACCEPTED_PARAMS: dict[str, frozenset[str]] = {
"hover": frozenset({"intent", "selector", "timeout"}),
"scroll": frozenset({"direction", "amount", "intent", "selector"}),
"wait": frozenset({"time_ms", "intent", "selector", "state", "timeout", "poll_interval_ms"}),
+ "wait_for_either_state": frozenset({"selector_a", "selector_b", "state", "timeout"}),
"screenshot": frozenset({"full_page", "selector", "inline"}),
"evaluate": frozenset({"expression"}),
}
diff --git a/skyvern/forge/sdk/copilot/build_phase.py b/skyvern/forge/sdk/copilot/build_phase.py
index 77a1bb831..1da6d17b1 100644
--- a/skyvern/forge/sdk/copilot/build_phase.py
+++ b/skyvern/forge/sdk/copilot/build_phase.py
@@ -72,6 +72,7 @@ _BROWSER_PRIMITIVE_TOOLS: frozenset[str] = frozenset(
"press_key",
"console_messages",
"get_browser_screenshot",
+ "wait_for_either_state",
}
)
_MUTATION_TOOLS: frozenset[str] = frozenset(
diff --git a/skyvern/forge/sdk/copilot/narration.py b/skyvern/forge/sdk/copilot/narration.py
index d267ec40b..04a6d56f6 100644
--- a/skyvern/forge/sdk/copilot/narration.py
+++ b/skyvern/forge/sdk/copilot/narration.py
@@ -105,6 +105,7 @@ _TOOL_ACTIVITY_DISPLAY_LABELS = {
"list_credentials": "Checking saved credentials",
"validate_block": "Checking the block",
"console_messages": "Reading the browser console",
+ "wait_for_either_state": "Waiting for the page",
"fill_credential_field": "Entering saved credentials",
"edit_block": "Editing block",
"delete_block": "Deleting block",
diff --git a/skyvern/forge/sdk/copilot/self_heal_recovery.py b/skyvern/forge/sdk/copilot/self_heal_recovery.py
index bfffb03d5..712123eaf 100644
--- a/skyvern/forge/sdk/copilot/self_heal_recovery.py
+++ b/skyvern/forge/sdk/copilot/self_heal_recovery.py
@@ -32,6 +32,7 @@ _SELF_HEAL_MCP_TOOL_ALLOWLIST = frozenset(
"console_messages",
"select_option",
"press_key",
+ "wait_for_either_state",
}
)
diff --git a/skyvern/forge/sdk/copilot/tools/banned_blocks.py b/skyvern/forge/sdk/copilot/tools/banned_blocks.py
index 85070fbe3..756dbde5d 100644
--- a/skyvern/forge/sdk/copilot/tools/banned_blocks.py
+++ b/skyvern/forge/sdk/copilot/tools/banned_blocks.py
@@ -224,7 +224,7 @@ def _code_only_browser_schema_guidance() -> list[str]:
_code_only_browser_validation_guidance(),
"Keep block outputs JSON-safe and include visible evidence text when extracting records, products, totals, confirmations, or identifiers.",
"Wait for the value the block returns, not for a URL or a navigation. A page reaches its final URL while it is still rendering, so a URL check passes before the value exists and a navigation wait fails on a page that has already arrived.",
- "Deciding which of two page states you are in costs no wait: wait once on `a.or_(b).first`, then branch with `is_visible()` or `count()`. That combined entry wait is the only one that gets a long ceiling — give it `timeout=90000`, because a cold first load can hydrate for a minute and the wait returns the instant either state appears, so a fast page pays nothing for the generous window. Do not reuse that ceiling anywhere else: every later wait gets a short one such as `timeout=30000`, because a `wait_for` on a branch that may legitimately be absent spends its whole timeout proving the absence, and every repair attempt pays it again.",
+ "Deciding which of two page states you are in costs no wait: wait once on `a.or_(b).first`, then branch with `is_visible()` or `count()`. Build each side to match only visible elements — `page.locator('#x >> visible=true')` — because `.first` is the first match in DOM order, not the first to become visible, so a hidden sign-in form that precedes the signed-in view captures the wait and spends the whole ceiling. That combined entry wait is the only one that gets a long ceiling — give it `timeout=90000`, because a cold first load can hydrate for a minute and the wait returns the instant either state appears, so a fast page pays nothing for the generous window. Do not reuse that ceiling anywhere else: every later wait gets a short one such as `timeout=30000`, because a `wait_for` on a branch that may legitimately be absent spends its whole timeout proving the absence, and every repair attempt pays it again.",
"For saved credentials: bind the credential as a workflow parameter with workflow_parameter_type credential_id and the credential ID in default_value. At runtime the parameter key resolves to a credential object — read <key>.username and <key>.password, and use await <key>.otp() for authenticator, email, or SMS one-time codes. Never put literal secret values in code; scout credential fields with fill_credential_field.",
]
@@ -259,7 +259,12 @@ Runtime facts:
`<key>.username`, `<key>.password`, and `await <key>.otp()` for one-time codes; scout fields with
`fill_credential_field`, never embed literal secrets.
- Credentialed login code must be idempotent. After `goto`, wait once on the two
- states together, then branch without waiting again:
+ states together, then branch without waiting again. Build each side to match only
+ visible elements, since `.first` takes the first match in DOM order rather than the
+ first to become visible, and a sign-in form that is present but hidden on an
+ already-authenticated page would otherwise capture the wait and hold it to the ceiling:
+ `login_form = page.locator("#login-form >> visible=true")`,
+ `authenticated_anchor = page.locator("#account-menu >> visible=true")`, then
`await login_form.or_(authenticated_anchor).first.wait_for(state="visible", timeout=90000)`,
then `if await login_form.is_visible():` to fill username/password. The generous window
covers a cold first load whose hydration lands well after Playwright's default, and the
diff --git a/skyvern/forge/sdk/copilot/tools/mcp_hooks.py b/skyvern/forge/sdk/copilot/tools/mcp_hooks.py
index 9802703b1..5011a8f16 100644
--- a/skyvern/forge/sdk/copilot/tools/mcp_hooks.py
+++ b/skyvern/forge/sdk/copilot/tools/mcp_hooks.py
@@ -1100,6 +1100,7 @@ def get_skyvern_mcp_alias_map() -> dict[str, str]:
"console_messages": "skyvern_console_messages",
"select_option": "skyvern_select_option",
"press_key": "skyvern_press_key",
+ "wait_for_either_state": "skyvern_wait_for_either_state",
}
@@ -1252,4 +1253,8 @@ def _build_skyvern_mcp_overlays(
pre_hook=_press_key_pre_hook,
post_hook=_press_key_post_hook,
),
+ "wait_for_either_state": SchemaOverlay(
+ hide_params=frozenset({"session_id", "cdp_url"}),
+ requires_browser=True,
+ ),
}
diff --git a/skyvern/forge/sdk/copilot/unrecoverable_tool_error.py b/skyvern/forge/sdk/copilot/unrecoverable_tool_error.py
index 9bfed44dd..3b350ad71 100644
--- a/skyvern/forge/sdk/copilot/unrecoverable_tool_error.py
+++ b/skyvern/forge/sdk/copilot/unrecoverable_tool_error.py
@@ -33,6 +33,7 @@ _BROWSER_SESSION_TOOL_NAMES = frozenset(
"console_messages",
"select_option",
"press_key",
+ "wait_for_either_state",
}
)
_UNRECOVERABLE_TOOL_ERROR_CATEGORY = "UNRECOVERABLE_TOOL_ERROR"
diff --git a/tests/unit/copilot/test_self_heal_recovery.py b/tests/unit/copilot/test_self_heal_recovery.py
index 08ad50502..cdcad6607 100644
--- a/tests/unit/copilot/test_self_heal_recovery.py
+++ b/tests/unit/copilot/test_self_heal_recovery.py
@@ -134,6 +134,7 @@ async def test_recovery_uses_browser_only_surface_and_no_native_tools(monkeypatc
"console_messages",
"select_option",
"press_key",
+ "wait_for_either_state",
}
assert "get_block_schema" not in alias_map
diff --git a/tests/unit/test_copilot_banned_block_policy.py b/tests/unit/test_copilot_banned_block_policy.py
index 34a6795f7..49ee54304 100644
--- a/tests/unit/test_copilot_banned_block_policy.py
+++ b/tests/unit/test_copilot_banned_block_policy.py
@@ -257,6 +257,9 @@ def test_code_only_authoring_prompt_requires_idempotent_credential_login() -> No
# spends the whole timeout proving it is absent on an already-authenticated session.
assert ".or_(" in prompt
assert re.search(r"\.or_\([^)]*\)\.first\.wait_for\([^)]*timeout=90000(?!\d)", prompt)
+ # `.first` is the first match in DOM order, not the first to become visible, so an unconstrained
+ # union binds to a hidden sign-in form and holds the wait to the ceiling.
+ assert "visible=true" in prompt
assert "is_visible()" in prompt
assert "await solve_captcha(page)" in prompt
assert "platform-managed verification challenge" in prompt
@@ -772,6 +775,7 @@ def test_schema_guidance_teaches_a_no_wait_branch_between_two_page_states() -> N
guidance = " ".join(_code_only_browser_schema_guidance())
assert ".or_(" in guidance
+ assert "visible=true" in guidance
assert "is_visible()" in guidance or "count()" in guidance
entry_ceiling = re.search(r"entry wait[^.]*?timeout=(\d+)(?!\d)", guidance)
diff --git a/tests/unit/test_copilot_hooks.py b/tests/unit/test_copilot_hooks.py
index 71689c06c..cecd81aba 100644
--- a/tests/unit/test_copilot_hooks.py
+++ b/tests/unit/test_copilot_hooks.py
@@ -717,6 +717,7 @@ class TestMCPToolOverlayCompleteness:
"console_messages",
"select_option",
"press_key",
+ "wait_for_either_state",
}
assert set(alias_map.keys()) == expected_aliases
assert all(v.startswith("skyvern_") for v in alias_map.values())
@@ -746,10 +747,22 @@ class TestMCPToolOverlayCompleteness:
"console_messages",
"select_option",
"press_key",
+ "wait_for_either_state",
}
for name in browser_tools:
assert overlays[name].requires_browser, f"{name} should have requires_browser=True"
+ def test_wait_for_either_state_exposes_the_two_selector_branch(self) -> None:
+ """Without selector_or the copilot must guess one state and pay the timeout when it is wrong."""
+ from skyvern.forge.sdk.copilot.tools import _build_skyvern_mcp_overlays, get_skyvern_mcp_alias_map
+
+ assert get_skyvern_mcp_alias_map()["wait_for_either_state"] == "skyvern_wait_for_either_state"
+ overlay = _build_skyvern_mcp_overlays()["wait_for_either_state"]
+
+ # Both states are required by the tool itself, so a single-selector call — the shape that
+ # spends the whole ceiling on a wrong guess — is not expressible here at all.
+ assert not overlay.hide_params & {"selector_a", "selector_b"}
+
def test_intent_hidden_on_element_action_tools(self) -> None:
"""An `intent` runs a second LLM agent to pick the element, duplicating reasoning the
copilot loop already did. The element-action tools take a selector only."""
@@ -1924,3 +1937,16 @@ class TestClickPostHookReachedDownloadTarget:
await _click_post_hook(result, {}, ctx)
assert ctx.reached_download_target is None
+
+
+def test_browser_overlays_are_gated_by_phase_and_session_classification() -> None:
+ """A requires_browser overlay provisions a session, so leaving one out of these sets lets it run
+ before composition and stops a dead-session failure from being classified unrecoverable."""
+ from skyvern.forge.sdk.copilot.build_phase import _BROWSER_PRIMITIVE_TOOLS
+ from skyvern.forge.sdk.copilot.tools import _build_skyvern_mcp_overlays
+ from skyvern.forge.sdk.copilot.unrecoverable_tool_error import _BROWSER_SESSION_TOOL_NAMES
+
+ browser_overlays = {name for name, o in _build_skyvern_mcp_overlays().items() if o.requires_browser}
+
+ assert browser_overlays <= _BROWSER_PRIMITIVE_TOOLS, browser_overlays - _BROWSER_PRIMITIVE_TOOLS
+ assert browser_overlays <= _BROWSER_SESSION_TOOL_NAMES, browser_overlays - _BROWSER_SESSION_TOOL_NAMES
diff --git a/tests/unit/test_mcp_browser_tools.py b/tests/unit/test_mcp_browser_tools.py
index 1ad47caac..42ac905f5 100644
--- a/tests/unit/test_mcp_browser_tools.py
+++ b/tests/unit/test_mcp_browser_tools.py
@@ -2748,3 +2748,98 @@ async def test_inline_screenshot_is_also_persisted(monkeypatch: pytest.MonkeyPat
assert result["data"]["path"] == artifact.path
assert result["artifacts"] == [artifact.to_dict()]
+
+
+def _either_wait_page(
+ monkeypatch: pytest.MonkeyPatch,
+ outcomes: dict[str, float | Exception],
+) -> list[asyncio.Task]:
+ """Fake a page whose per-selector waits resolve after a delay, raise, or time out: an outcome of
+ None means the selector never appears, so that waiter times out the way Playwright's does. Returns
+ the waiter tasks so a caller can assert the tool drained them.
+ """
+ waiters: list[asyncio.Task] = []
+
+ async def wait_for_selector(selector: str, timeout: float = 30000, **_: object) -> SimpleNamespace:
+ task = asyncio.current_task()
+ if task is not None:
+ waiters.append(task)
+ outcome = outcomes.get(selector)
+ if isinstance(outcome, Exception):
+ raise outcome
+ if outcome is None:
+ await asyncio.sleep(timeout / 1000)
+ raise mcp_browser.PlaywrightTimeoutError(f"Timeout {timeout}ms exceeded waiting for {selector}")
+ await asyncio.sleep(outcome)
+ return SimpleNamespace(selector=selector)
+
+ _action_page(monkeypatch, wait_for_selector=AsyncMock(side_effect=wait_for_selector))
+ return waiters
+
+
+async def test_wait_timeout_on_one_selector_points_at_the_two_state_form(monkeypatch: pytest.MonkeyPatch) -> None:
+ """The timeout is the moment the caller learns its guess was wrong — the error is where MCP puts
+ feedback a model can act on, so it names the form that would not have cost the ceiling."""
+ _either_wait_page(monkeypatch, {"#login": None})
+
+ result = await mcp_browser.skyvern_wait(selector="#login", timeout=1000)
+
+ assert result["ok"] is False
+ assert "skyvern_wait_for_either_state" in result["error"]["hint"]
+
+
[email protected](("appears", "expected"), [("#login", "selector_a"), ("#home", "selector_b")])
+async def test_wait_for_either_state_names_the_side_that_matched(
+ monkeypatch: pytest.MonkeyPatch,
+ appears: str,
+ expected: str,
+) -> None:
+ """One tool, one operation: both states are required, so the answer is always which one it is."""
+ absent = "#home" if appears == "#login" else "#login"
+ _either_wait_page(monkeypatch, {appears: 0.01, absent: None})
+
+ result = await mcp_browser.skyvern_wait_for_either_state(selector_a="#login", selector_b="#home", timeout=120000)
+
+ assert result["ok"] is True
+ assert result["data"]["matched_selector"] == appears
+ assert result["data"]["matched"] == expected
+
+
+async def test_wait_for_either_state_rejects_states_where_absence_wins(monkeypatch: pytest.MonkeyPatch) -> None:
+ _either_wait_page(monkeypatch, {"#login": 0.01, "#home": 0.01})
+
+ result = await mcp_browser.skyvern_wait_for_either_state(selector_a="#a", selector_b="#b", state="hidden")
+
+ assert result["ok"] is False
+ assert result["error"]["code"] == mcp_browser.ErrorCode.INVALID_INPUT
+
+
[email protected]("concise", [True, False])
+def test_either_state_output_schema_accepts_both_envelope_modes(concise: bool) -> None:
+ """Declared schemas are enforced at runtime, and the two envelope modes disagree on absent fields."""
+ import jsonschema
+
+ from skyvern.cli.core.result import set_concise_responses
+
+ set_concise_responses(concise)
+ try:
+ for envelope in (
+ mcp_browser.make_result(
+ "skyvern_wait_for_either_state",
+ browser_context=BrowserContext(mode="local"),
+ data={"matched_selector": "#home", "matched": "selector_b"},
+ timing_ms={"total": 5},
+ ),
+ mcp_browser.make_result(
+ "skyvern_wait_for_either_state",
+ ok=False,
+ browser_context=BrowserContext(mode="local"),
+ error=mcp_browser.make_error(mcp_browser.ErrorCode.TIMEOUT, "nope", "hint"),
+ ),
+ ):
+ jsonschema.validate(envelope, mcp_browser.EITHER_STATE_OUTPUT_SCHEMA)
+ finally:
+ set_concise_responses(False)
diff --git a/tests/unit/test_mcp_observe_execute.py b/tests/unit/test_mcp_observe_execute.py
index 1b7638208..3c18f1cb8 100644
--- a/tests/unit/test_mcp_observe_execute.py
+++ b/tests/unit/test_mcp_observe_execute.py
@@ -1839,6 +1839,26 @@ class TestSkyvernExecuteMCP:
assert step_error["details"]["element_state"] == "hidden"
assert step_error["details"]["selector"] == "#field"
+ @pytest.mark.asyncio
+ async def test_execute_forwards_both_selectors_to_the_two_state_wait(self, monkeypatch: pytest.MonkeyPatch) -> None:
+ """_TOOL_ACCEPTED_PARAMS drops unlisted params silently, degrading the wait to one selector."""
+ page = _make_page()
+ ctx = BrowserContext(mode="local")
+ monkeypatch.setattr(mcp_browser, "get_page", AsyncMock(return_value=(page, ctx)))
+ wait = AsyncMock(return_value={"ok": True, "data": {}})
+ monkeypatch.setattr(mcp_browser, "skyvern_wait_for_either_state", wait)
+
+ await mcp_browser.skyvern_execute(
+ steps=[
+ {
+ "tool": "wait_for_either_state",
+ "params": {"selector_a": "#login", "selector_b": "#home", "timeout": 90000},
+ }
+ ]
+ )
+
+ assert wait.await_args.kwargs["selector_b"] == "#home"
+
@pytest.mark.asyncio
async def test_execute_wait_error_does_not_leak_headers(self, monkeypatch: pytest.MonkeyPatch) -> None:
page = _make_page()