Automate browser based workflows with AI
Python aiapiautomationbrowserbrowser-automationcomputergptllmplaywrightpowerautomatepuppeteerpythonrpaseleniumvisionworkflow
SKY-10562: scout goal pages with fast MCP browser tools before authoring (#6335)
Andrew Neilson7c52d3268159
diff --git a/skyvern/cli/mcp_tools/browser.py b/skyvern/cli/mcp_tools/browser.pyindex b2b28f2b4..daad841cc 100644--- a/skyvern/cli/mcp_tools/browser.py+++ b/skyvern/cli/mcp_tools/browser.py@@ -5,7 +5,7 @@ import base64import jsonimport refrom datetime import datetime, timezone-from typing import Annotated, Any+from typing import Annotated, Any, Literalimport structlogfrom playwright.async_api import TimeoutError as PlaywrightTimeoutError@@ -59,6 +59,24 @@ _AWAIT_RE = re.compile(r"\bawait\b")_SINGLE_LINE_COMMENT_RE = re.compile(r"//[^\n]*")+def _blank_to_none(value: str | None) -> str | None:+ """Treat a blank/whitespace string as omitted: MCP clients serialize an omitted optional+ selector/intent as "", and a "" target would route a deterministic action onto nothing."""+ return value if value is None or value.strip() else None+++_SelectorMode = Annotated[+ Literal["resilient", "direct"],+ Field(+ description=(+ "Selector resolution when a `selector` is given. 'resilient' (default) tries the selector, then "+ "dismisses overlays and falls back to AI if it breaks. 'direct' acts only on the exact selector with "+ "no overlay-dismiss or AI fall-back — a missed target fails fast. No effect when only `intent` is given."+ )+ ),+]++async def skyvern_navigate(url: Annotated[str, "The URL to navigate to"],session_id: Annotated[str | None, Field(description="Browser session ID (pbs_...)")] = None,@@ -160,6 +178,7 @@ async def skyvern_click("Use standard CSS: 'button.class', 'a[href*=\"pdf\"]', '#id', ':nth-of-type()'."),] = None,+ selector_mode: _SelectorMode = "resilient",timeout: Annotated[int,Field(@@ -181,6 +200,8 @@ async def skyvern_click(error=make_error(ErrorCode.INVALID_INPUT, f"Invalid button: {button}", "Use left, right, or middle"),)+ selector = _blank_to_none(selector)+ intent = _blank_to_none(intent)ai_mode, err = _resolve_ai_mode(selector, intent)if err:return make_result(@@ -198,6 +219,7 @@ async def skyvern_click(except BrowserNotAvailableError:return make_result("skyvern_click", ok=False, error=no_browser_error())+ deterministic = selector is not None and selector_mode == "direct"with Timer() as timer:try:kwargs: dict[str, Any] = {"timeout": timeout}@@ -206,7 +228,11 @@ async def skyvern_click(if click_count is not None:kwargs["click_count"] = click_count- if ai_mode is not None:+ if deterministic:+ # selector_mode="direct": pin the selector, no overlay-dismiss or AI re-target, so a+ # missed target fails fast and the agent re-derives it instead of AI scout-scrolling.+ resolved = await page.click(selector=selector, mode="direct", **kwargs)+ elif ai_mode is not None:resolved = await page.click(selector=selector, prompt=intent, ai=ai_mode, **kwargs) # type: ignore[arg-type]else:assert selector is not None@@ -225,7 +251,7 @@ async def skyvern_click(),)except Exception as e:- code = ErrorCode.AI_FALLBACK_FAILED if ai_mode else ErrorCode.ACTION_FAILED+ code = ErrorCode.AI_FALLBACK_FAILED if (ai_mode and not deterministic) else ErrorCode.ACTION_FAILEDreturn make_result("skyvern_click",ok=False,@@ -626,6 +652,7 @@ async def skyvern_type(),] = None,selector: Annotated[str | None, Field(description="CSS selector or XPath for the input element")] = None,+ selector_mode: _SelectorMode = "resilient",timeout: Annotated[int,Field(@@ -653,6 +680,8 @@ async def skyvern_type(),)+ selector = _blank_to_none(selector)+ intent = _blank_to_none(intent)ai_mode, err = _resolve_ai_mode(selector, intent)if err:return make_result(@@ -693,10 +722,17 @@ async def skyvern_type(),)+ deterministic = selector is not None and selector_mode == "direct"with Timer() as timer:try:+ # selector_mode="direct" pins the selector with no AI fall-back. Resilient (default) and+ # intent-only calls keep AI; emitted scripts keep the selector+prompt fallback via+ # sdk_equivalent for DOM-drift resilience.if clear:- if ai_mode is not None:+ if deterministic:+ assert selector is not None+ await page.fill(selector, text, mode="direct", timeout=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]else:assert selector is not None@@ -705,7 +741,9 @@ async def skyvern_type(kwargs: dict[str, Any] = {"timeout": timeout}if delay is not None:kwargs["delay"] = delay- if ai_mode is not None:+ if deterministic:+ await page.type(selector, text, ai=None, **kwargs)+ elif ai_mode is not None:loc = page.locator(selector=selector, prompt=intent, ai=ai_mode) # type: ignore[arg-type]await loc.type(text, **kwargs)else:@@ -725,7 +763,7 @@ async def skyvern_type(),)except Exception as e:- code = ErrorCode.AI_FALLBACK_FAILED if ai_mode else ErrorCode.ACTION_FAILED+ code = ErrorCode.AI_FALLBACK_FAILED if (ai_mode and not deterministic) else ErrorCode.ACTION_FAILEDreturn make_result("skyvern_type",ok=False,@@ -923,6 +961,7 @@ async def skyvern_select_option(cdp_url: Annotated[str | None, Field(description="CDP WebSocket URL")] = None,intent: Annotated[str | None, Field(description="Natural language description of the dropdown (uses AI)")] = None,selector: Annotated[str | None, Field(description="CSS selector for the select element")] = None,+ selector_mode: _SelectorMode = "resilient",timeout: Annotated[int, Field(description="Max time to wait for the dropdown in ms. Default 30000 (30s)", ge=1000, le=60000)] = 30000,@@ -932,6 +971,8 @@ async def skyvern_select_option(For free-text input fields, use skyvern_type instead. For non-dropdown buttons or links, use skyvern_click."""+ selector = _blank_to_none(selector)+ intent = _blank_to_none(intent)ai_mode, err = _resolve_ai_mode(selector, intent)if err:return make_result(@@ -949,22 +990,25 @@ async def skyvern_select_option(except BrowserNotAvailableError:return make_result("skyvern_select_option", ok=False, error=no_browser_error())+ deterministic = selector is not None and selector_mode == "direct"with Timer() as timer:try:- if ai_mode is not None:- # AI paths: pass value= directly -- the AI interprets the text- # regardless of whether it represents a value or label.+ # 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]else:assert selector is not Noneif by_label:# Bypass SkyvernPage to avoid value="" coercion conflicting with label kwarg.await page.page.locator(selector).select_option(label=value, timeout=timeout)+ elif deterministic:+ await page.select_option(selector, value=value, ai=None, timeout=timeout)else:await page.select_option(selector, value=value, timeout=timeout)timer.mark("sdk")except Exception as e:- code = ErrorCode.AI_FALLBACK_FAILED if ai_mode else ErrorCode.ACTION_FAILED+ code = ErrorCode.AI_FALLBACK_FAILED if (ai_mode and not deterministic) else ErrorCode.ACTION_FAILEDreturn make_result("skyvern_select_option",ok=False,diff --git a/skyvern/forge/prompts/skyvern/workflow-copilot-agent.j2 b/skyvern/forge/prompts/skyvern/workflow-copilot-agent.j2index 7d57b85de..8de4df32e 100644--- a/skyvern/forge/prompts/skyvern/workflow-copilot-agent.j2+++ b/skyvern/forge/prompts/skyvern/workflow-copilot-agent.j2@@ -57,7 +57,7 @@ Prefer workflow-run evidence first. Use navigate_browser, get_browser_screenshot3. You need to validate a specific UI hypothesis before changing the workflow.PAGE EVIDENCE POLICY:-Use the Skyvern MCP browser tools to fill knowledge gaps while building, editing, or debugging a workflow. The purpose is to make your workflow composition evidence-based, not to add defensive verification blocks for every website shape.+Use the Skyvern MCP browser tools to gather ground-truth evidence in ANY phase of building — exploring, composing, editing, and repairing after a failed block run. They are the path of least resistance for figuring out how to build or fix a workflow; the purpose is evidence-based composition, not adding defensive verification blocks for every website shape.- Do not invent website-specific paths, query parameters, form fields, result affordances, or page structure from memory. Ground them in user-supplied information, run evidence, or live MCP observations.- Treat `goto_url` as a page-loading block. A current results URL can be useful evidence, but do not assume it is a reusable entrypoint when it may encode session-only state.- For form/search/result pages, inspect when you do not know the real controls or result layout. Use `inspect_page_for_composition(target_url="current_page")`, `evaluate`, `get_browser_screenshot`, or targeted interaction tools as needed, then compose normal workflow blocks from the observed page.@@ -72,11 +72,14 @@ CRITICAL RULES WHEN USING DIRECT BROWSER TOOLS:- If you call navigate_browser, you MUST call at least one observation tool (evaluate, get_browser_screenshot, click, type_text, scroll, select_option, press_key, or console_messages) before responding.- NEVER answer questions about page content, link counts, link targets, or page structure from memory or training data. Use evaluate or get_browser_screenshot.- Use evaluate for reading/inspection; do NOT use evaluate to click or type. Use click and type_text for interactions.-- CSS SELECTORS AND AI INTENT: Browser tools (click, type_text, scroll, select_option, press_key) accept a CSS selector, an AI intent description, or both. Use intent to describe the element in natural language (e.g. intent="the Submit button") when the CSS selector is unclear. When using CSS selectors, jQuery pseudo-selectors (:contains(), :eq(), :first, :visible, :has()) are NOT valid — use standard selectors like 'button.classname', 'a[href*="keyword"]', '#id', 'tr:nth-of-type(2) td a'.+- CSS SELECTORS vs AI INTENT (cost-aware): a CSS-selector-ONLY click/type is an instant deterministic action. Passing an `intent` (alone, or alongside a selector) routes the action through a slower full-page AI scan that scrolls and screenshots the whole page to locate the element — even when the element is already on screen. So once `evaluate`/inspection evidence has identified the target, act by a CSS selector ALONE; reserve `intent` only for when you genuinely cannot derive a selector. When a shared class matches many elements (e.g. one Add-to-Cart per result row), scope the selector to the specific item (its container, a unique attribute, or `:nth-of-type`) rather than passing an `intent` to disambiguate. Do the "which element" reasoning in `evaluate` (read the DOM), not in a click `intent`. jQuery pseudo-selectors (:contains(), :eq(), :first, :visible, :has()) are NOT valid — use standard selectors like 'button.classname', 'a[href*="keyword"]', '#id', 'tr:nth-of-type(2) td a'.- SCROLL: Use scroll to reveal content below the fold. Provide direction (up/down/left/right) and optionally amount in pixels, a selector for the scrollable container, or intent to scroll a specific element into view.- SELECT_OPTION: Use select_option for <select> dropdowns. Provide the value and use selector or intent to target the element. For free-text inputs, use type_text instead.- PRESS_KEY: Use press_key for keyboard actions — Enter to submit forms, Tab to advance focus, Escape to close dialogs. Optionally provide selector or intent to focus an element first.- CONSOLE_MESSAGES: Use console_messages(level='error') to check for JavaScript errors when diagnosing page issues. This is read-only.+- A FAILED SCOUT CLICK IS NOT A DEAD END: "element is hidden, disabled, or intercepted by another element" usually means an overlay/modal (cookie banner, marketing popup) is covering it — and the click itself often dismisses that overlay. Do NOT abandon the route, navigate away, or redesign the workflow because one scout click failed: re-inspect the current page and retry the same target; the overlay or transient state has typically cleared. (Retrying a click that did NOT act is fine — that is distinct from replaying an earlier add/submit that already succeeded, which would duplicate its effect; see the next rule.)+- A FAILED ACTION MAY HAVE LANDED: if a click/type/submit reports failure but could have changed the page (a navigation, a cart/count change, a new modal), inspect the current page before retrying. Re-firing a non-idempotent action (add to cart, submit) can duplicate its effect — confirm whether it already happened, then decide.+- AFTER A PAGE-CHANGING ACTION: wait for the new state to settle before reading it; if a read fails transiently because the page navigated mid-read, re-observe once rather than restarting the flow.FEASIBILITY CHECK (POST-UPDATE, RESULT-DRIVEN):Assess feasibility after each incremental update using the latest run:@@ -92,7 +95,7 @@ BUILD-TEST-FIX WORKFLOW (ONE NEXT BLOCK AT A TIME):When building or modifying workflows, follow this cycle:1. **Build next step**: Use get_block_schema, then call update_and_run_blocks with the complete workflow YAML and the next small test frontier in `block_labels` (combines update + test in one call; the tool reruns only the invalidated or first unverified frontier).2. **Review results**: Check overall_status, per-block status and failure_reason, failure_categories, action_trace_summary, current_url/page_title, and the failure screenshot when present. For deeper inspection, call get_run_results.-3. **Decide**: Fix current blocks, or stop as infeasible with evidence, or append the next block if current chain is good.+3. **Decide (evidence-first on failure)**: If a block failed, FIRST inspect the reached page (`inspect_page_for_composition(target_url="current_page")`, or `evaluate`/`get_browser_screenshot`) to observe what actually went wrong — do NOT guess a new goal for the same block and re-run blind. Then decide from that evidence: keep the same block with a corrected goal, swap the block type, or redesign the step. Otherwise append the next block if the chain is good, or stop as infeasible with evidence.4. **Verify state**: Use get_browser_screenshot after runs when visual confirmation helps diagnosis.ANTI-BOT / WAF BLOCK HANDLING (ACCESS DENIED, CLOUDFLARE, AKAMAI, CAPTCHA):@@ -154,8 +157,9 @@ IMPORTANT WORKFLOW RULES:- "goto_url" for direct URL navigation grounded in user-provided or observed same-site URLs.* Use `goto_url` for direct URL navigation and for URL patterns grounded in user-provided values or observed same-site evidence. Do NOT invent website-specific paths or query parameters from memory. Put follow-up UI actions in subsequent normal workflow blocks.* When revising after a run, do not replace a discovered/user-requested entrypoint with the browser's current results URL just because it worked once. Current URLs often contain server/session state; preserve the reusable path and use current-page evidence to improve downstream blocks.-* Commit a draft workflow as soon as you have enough evidence for a plausible reusable block sequence. Use Skyvern MCP inspection tools before mutation when they are needed to resolve uncertainty about the page, especially URL-known form/search composition. When an existing workflow draft needs a well-scoped additive edit, update the YAML with update_workflow or update_and_run_blocks using a clear condition plus action target instead of answering with a prose-only block outline. Do not ask for confirmation when the workflow can be updated and tested.-* Keep `navigation_goal` scoped to one coherent page state change grounded in observed evidence, not one guessed site model and not one block per field. Do not pre-author row/detail expansion from the user's words alone: first run or inspect your way to the actual results page, then use live result-page evidence to decide whether expansion controls exist. If requested details are already visible or no explicit expansion affordance is observed, skip the expansion block and go straight to an `extraction` block. The final stage of visible results -> extract should still use an `extraction` block for data capture, not another `navigation` block.+* Commit a draft workflow as soon as you have observed every page its blocks act on — not as soon as a reusable block sequence merely looks plausible. Use Skyvern MCP inspection tools before mutation when they are needed to resolve uncertainty about the page, especially URL-known form/search composition. When an existing workflow draft needs a well-scoped additive edit, update the YAML with update_workflow or update_and_run_blocks using a clear condition plus action target instead of answering with a prose-only block outline. Do not ask for confirmation when the workflow can be updated and tested.+* Scout each page you will act on with the fast browser tools before you author the blocks that act on it. Drive the live browser through the goal path (navigate_browser, click, type_text, scroll, select_option, press_key) and call `inspect_page_for_composition` on every page you will act on — including pages reached only by clicking and pages behind a login — BEFORE authoring those blocks. `inspect_page_for_composition(target_url=...)` navigates to that URL itself and reports the reached `current_url`, so once you have inspected a URL you are already on it — do NOT then call `navigate_browser` to a URL you just inspected. A control or state that appears only after an interaction (a Delete control after an Add click, a cart after add-to-cart, the secure area after login) must be observed live by performing that interaction first; do not assume the post-interaction page from the page before it. Block-runs validate a finished workflow — they do not discover an unknown route, so do not run blocks just to see what a page looks like; for a login wall, author and run the `login` block (referencing a saved credential by id), then resume scouting from the authenticated page.+* Keep `navigation_goal` scoped to one coherent page state change grounded in observed evidence, not one guessed site model and not one block per field. Do not pre-author row/detail expansion from the user's words alone: first run or inspect your way to the actual results page, then use live result-page evidence to decide whether expansion controls exist. If requested details are already visible or no explicit expansion affordance is observed, skip the expansion block and go straight to an `extraction` block. The final stage of visible results -> extract should still use an `extraction` block for data capture, not another `navigation` block. Prefer the most specific block that fits the step — use a more specific block (`action` for a single action, `login` for authentication, `file_download` for downloads, `extraction` for data) over `navigation`, and reach for `navigation` only when the step is best expressed as a goal for the agent to work out rather than a specific named action (see CHOOSING A BLOCK in the knowledge base).* Save the complete reusable workflow, but run only a small verified frontier when the workflow has several page-changing stages. `update_and_run_blocks` accepts the full YAML plus a subset of `block_labels`; for form/search workflows, first run the entry/form-state frontier, then continue with submit/results, then expansion/extraction. After a verified prefix or a budgeted run that leaves the browser on a later page, preserve the upstream workflow text and run only the missing downstream labels. Do not remove later blocks from the YAML just to shorten a test; do not submit a long chain of all blocks at once when each stage can be verified independently.* Set `complete_criterion` on every decomposed `navigation` block to the observable post-action page state — without it, smaller blocks still return vague "continue" verdicts.* Use descriptive, unique labels for blocks (snake_case format).diff --git a/skyvern/forge/prompts/skyvern/workflow_knowledge_base.txt b/skyvern/forge/prompts/skyvern/workflow_knowledge_base.txtindex 973d4c16a..d05e03151 100644--- a/skyvern/forge/prompts/skyvern/workflow_knowledge_base.txt+++ b/skyvern/forge/prompts/skyvern/workflow_knowledge_base.txt@@ -98,6 +98,22 @@ Important Rules:- Set next_block_label to null to mark the end of a flow- continue_on_failure allows graceful error handling+** CHOOSING A BLOCK (use the most specific block that fits the step) **++The interaction blocks differ by how specifically you describe the step — from a general goal down to a single named action:++- navigation — the general, goal-level block. State the outcome you want as a navigation_goal (e.g. "search for {{ query }} and open the first result") and the agent works out and performs the actions to get there. Use it when the step is best expressed as where you want to end up, stated as intent — never as a click-by-click script.+- action — one specific UI action you name directly: a single click, type, or select on the current page (e.g. "click the Add to Cart button"). If you can name the exact action, prefer action over navigation.+- login — authentication. Handles stored credentials and 2FA/TOTP. Whenever the step is logging in, this is the right block; do NOT hand-build a navigation login or avoid login to save steps.+- file_download — the step's purpose is to download a file (detects when the download completes).+- extraction — capturing structured data, validated against data_schema.++For non-interaction steps, use the purpose-built block directly: goto_url (load a known URL), wait, conditional, for_loop/while_loop, http_request, file_url_parser, file_upload, send_email, text_prompt.++Rule of thumb: if you can name the exact action or purpose, use the specific block; fall back to navigation only when the step is genuinely a goal the agent must work out itself. The specific block also carries the right semantics (login handles 2FA, file_download detects completion, extraction enforces a schema) and runs tighter — a loose navigation_goal re-runs the full browser agent (scrape -> plan -> act) for every step it takes, so it is the block most likely to exhaust the per-tool-call run budget on a heavy page.++goto_url vs reaching a page by action: a goto_url replaces a navigation step whose only job was to reach a page you can already name — but only for a stable, reusable URL. Never freeze a session-bound search-results, filter, or cart URL into a goto_url entrypoint; it can encode session-only state and will not replay. Reach those pages via the action that produces them.+** NAVIGATION BLOCK (navigation) **Purpose: Take actions on a page to achieve a focused goal — fill a form, click through a multi-step flow, prepare the page before an extraction.diff --git a/skyvern/forge/sdk/copilot/agent.py b/skyvern/forge/sdk/copilot/agent.pyindex d1d1a218f..576a87183 100644--- a/skyvern/forge/sdk/copilot/agent.py+++ b/skyvern/forge/sdk/copilot/agent.py@@ -2790,6 +2790,7 @@ async def _run_copilot_turn_impl(prior_structured_context = StructuredContext.from_json_str(global_llm_context)ctx.prior_discovery_calls_made = prior_structured_context.discovery_calls_madectx.prior_page_inspection_calls_made = prior_structured_context.page_inspection_calls_made+ ctx.prior_observed_acted_pages = [page.model_dump() for page in prior_structured_context.observed_acted_pages]ctx.build_phase = initial_build_phase(ctx.turn_intent,chat_request.message or "",diff --git a/skyvern/forge/sdk/copilot/build_phase.py b/skyvern/forge/sdk/copilot/build_phase.pyindex d1630e6d1..be87c93ea 100644--- a/skyvern/forge/sdk/copilot/build_phase.py+++ b/skyvern/forge/sdk/copilot/build_phase.py@@ -9,8 +9,12 @@ Phases:- INITIAL: BUILD turn with no known entrypoint URL. Discovery is available;mutation and direct browser primitives are gated off.- DISCOVERING: discover_workflow_entrypoint is running. Same gate as INITIAL.-- COMPOSING: entrypoint resolved. Mutation tools and direct browser primitives- are available; discovery is no longer available.+- COMPOSING: entrypoint resolved and composition under way. Mutation tools,+ block-runs, and direct browser primitives are all available, so the agent+ scouts the goal path (including click-reached and post-login pages) with the+ fast browser tools and authors grounded in that evidence; discovery is no+ longer available. Authoring page-acting blocks is evidence-gated (see+ composition_evidence).- TESTING: post-update; same authority as COMPOSING."""@@ -76,25 +80,25 @@ _DISCOVERY_TOOLS: frozenset[str] = frozenset({"discover_workflow_entrypoint"})_URL_IN_TEXT_RE = re.compile(r"https?://[^\s<>\"\)]+", re.IGNORECASE)-def _yaml_has_target_url(workflow_yaml: str | None) -> bool:- """True when the YAML carries a goto_url or navigation block with a non-empty url."""+def _parse_workflow_blocks(workflow_yaml: str | None) -> list[dict[str, Any]]:if not workflow_yaml:- return False+ return []try:parsed = safe_load_no_dates(workflow_yaml)except yaml.YAMLError:- return False+ return []if not isinstance(parsed, dict):- return False+ return []definition = parsed.get("workflow_definition")if not isinstance(definition, dict):- return False+ return []blocks = definition.get("blocks")- if not isinstance(blocks, list):- return False- for block in blocks:- if not isinstance(block, dict):- continue+ return [block for block in blocks if isinstance(block, dict)] if isinstance(blocks, list) else []+++def _yaml_has_target_url(workflow_yaml: str | None) -> bool:+ """True when the YAML carries a goto_url or navigation block with a non-empty url."""+ for block in _parse_workflow_blocks(workflow_yaml):block_type = block.get("block_type")if block_type not in {"goto_url", "navigation"}:continue@@ -114,8 +118,11 @@ def initial_build_phase(Returns COMPOSING (sentinel — harmless because the existing TurnIntent gatealready blocks mutation for non-BUILD modes) when the mode is one of the- explicitly-non-build values. For BUILD / DRAFT_ONLY / UNKNOWN, returns- COMPOSING when this turn already has a URL signal, else INITIAL.+ explicitly-non-build values. For BUILD / DRAFT_ONLY / UNKNOWN with a URL+ signal, returns COMPOSING: the entrypoint is known, so the agent scouts the+ goal path with the browser tools and authors there (page-acting blocks stay+ evidence-gated). With no URL signal, returns INITIAL so discovery resolves+ the entrypoint first.UNKNOWN deliberately enters INITIAL when no URL is present: a fresh chatwhose latest message dodges every keyword heuristic (e.g. "go to X" with@@ -133,13 +140,14 @@ def initial_build_phase(mode_value = getattr(getattr(turn_intent, "mode", None), "value", None)if mode_value in _PHASE_NON_BUILD_MODE_VALUES:return BuildPhase.COMPOSING- if _URL_IN_TEXT_RE.search(user_message or ""):- return BuildPhase.COMPOSING- if _URL_IN_TEXT_RE.search(agent_user_message or ""):- return BuildPhase.COMPOSING- if _yaml_has_target_url(workflow_yaml):- return BuildPhase.COMPOSING- return BuildPhase.INITIAL+ has_url_signal = bool(+ _URL_IN_TEXT_RE.search(user_message or "")+ or _URL_IN_TEXT_RE.search(agent_user_message or "")+ or _yaml_has_target_url(workflow_yaml)+ )+ if not has_url_signal:+ return BuildPhase.INITIAL+ return BuildPhase.COMPOSINGdef _log_transition(ctx: CopilotContext, *, prev: BuildPhase, new: BuildPhase, reason: str) -> None:@@ -196,11 +204,11 @@ def _phase_blocker_signal(ctx: Any, tool_name: str) -> CopilotToolBlockerSignalreturn CopilotToolBlockerSignal(blocker_kind="phase_gated",agent_steering_text=(- "discover_workflow_entrypoint is only available before composition. "- "The workflow already has a target URL — proceed with update_workflow or update_and_run_blocks. "+ "discover_workflow_entrypoint is only available before the entrypoint is resolved. "+ "The workflow already has a target URL — scout it with the browser tools and author with update_workflow. ""safe_reason_code=build_phase_discovery_disallowed_post_compose."),- user_facing_reason="I already have a target for this workflow — I'll keep editing it instead of starting over.",+ user_facing_reason="I already have a target for this workflow — I'll keep working on it instead of starting over.",recovery_hint="retry_with_different_tool",cleared_by_tools=frozenset({"update_workflow", "update_and_run_blocks"}),internal_reason_code="build_phase_discovery_disallowed_post_compose",diff --git a/skyvern/forge/sdk/copilot/composition_evidence.py b/skyvern/forge/sdk/copilot/composition_evidence.pyindex d3a6676f0..aaea59743 100644--- a/skyvern/forge/sdk/copilot/composition_evidence.py+++ b/skyvern/forge/sdk/copilot/composition_evidence.py@@ -17,8 +17,14 @@ from skyvern.forge.sdk.copilot.verification_evidence import WorkflowVerificationfrom skyvern.utils.yaml_loader import safe_load_no_dates_BUILD_MODE_VALUES: frozenset[str] = frozenset({"build", "draft_only", "edit", "unknown"})-_PAGE_SHAPING_BLOCK_TYPES: frozenset[str] = frozenset({"navigation", "login"})-_PAGE_READING_BLOCK_TYPES: frozenset[str] = frozenset({"extraction"})+# Block types whose acted page, when no url is on the block, is the current+# frontier (observation of the page suffices). navigation without a url is the+# interaction-on-current-page case and is also frontier-anchored.+_FRONTIER_NO_URL_BLOCK_TYPES: frozenset[str] = frozenset({"login", "extraction", "validation"})+# No-url blocks that interact with the live page (not just read it): each runs the browser+# agent against the reached page, so they need the same observed-evidence floor as a no-url+# navigation, otherwise the agent can author an unobserved click/download/upload.+_INTERACTION_NO_URL_BLOCK_TYPES: frozenset[str] = frozenset({"navigation", "action", "file_download", "file_upload"})_GOTO_URL_BLOCK_TYPE = "goto_url"_SCHEMA_EVIDENCE_TOOL = "inspect_page_for_composition"_STRUCTURED_BROWSER_EVIDENCE_TOOLS: frozenset[str] = frozenset({"evaluate"})@@ -250,25 +256,32 @@ def workflow_target_url(workflow_yaml: str | None) -> str | None:return None-def _workflow_target_url_for_new_page_block(- workflow_yaml: str | None, previous_workflow_yaml: str | None-) -> str | None:- previous = {- (str(block.get("label") or ""), str(block.get("block_type") or "").strip().lower())- for block in _parse_workflow_blocks(previous_workflow_yaml)- }- last_url: str | None = None- for block in _parse_workflow_blocks(workflow_yaml):- url = block.get("url")- if isinstance(url, str) and url.strip():- last_url = url.strip()- block_type = str(block.get("block_type") or "").strip().lower()- if block_type not in _PAGE_SHAPING_BLOCK_TYPES | _PAGE_READING_BLOCK_TYPES:- continue- label = str(block.get("label") or "")- if (label, block_type) not in previous:- return last_url- return workflow_target_url(workflow_yaml)+def _block_url(block: dict[str, Any]) -> str | None:+ url = block.get("url")+ return url.strip() if isinstance(url, str) and url.strip() else None+++def _block_acts_on_page(block: dict[str, Any]) -> str | None:+ """How a block acts on a live page, or None if it is page-independent.++ "url" - carries a target url (goto_url, navigation/login with a url, a+ code block referencing a url); acts on that url's page.+ "interaction"- a no-url navigation/action/file_download/file_upload: an+ interaction (click/fill/submit/download/upload) on the current page.+ "frontier" - a no-url login/extraction/validation: reads or authenticates on+ whatever page the workflow has reached.++ A pure code/transform block (no url, not an interaction/reading type) returns+ None and is not gated.+ """+ block_type = str(block.get("block_type") or "").strip().lower()+ if _block_url(block):+ return "url"+ if block_type in _INTERACTION_NO_URL_BLOCK_TYPES:+ return "interaction"+ if block_type in _FRONTIER_NO_URL_BLOCK_TYPES:+ return "frontier"+ return Nonedef _mode_requires_evidence(ctx: Any) -> bool:@@ -285,38 +298,51 @@ def _mode_requires_evidence(ctx: Any) -> bool:)-def _new_page_shaping_blocks(workflow_yaml: str | None, previous_workflow_yaml: str | None) -> list[dict[str, str]]:- previous = {- (str(block.get("label") or ""), str(block.get("block_type") or "").strip().lower())- for block in _parse_workflow_blocks(previous_workflow_yaml)- }- blocks: list[dict[str, str]] = []- for block in _parse_workflow_blocks(workflow_yaml):- block_type = str(block.get("block_type") or "").strip().lower()- if block_type not in _PAGE_SHAPING_BLOCK_TYPES:- continue- label = str(block.get("label") or "<missing label>")- if (label, block_type) in previous:- continue- blocks.append({"label": label, "block_type": block_type})- return blocks+def _gated_page_acting_blocks(workflow_yaml: str | None, previous_workflow_yaml: str | None) -> list[dict[str, Any]]:+ """New-or-url-changed blocks that act on a page and so need observed evidence.+ Block-type-agnostic: any block carrying a url (goto_url past the entrypoint,+ navigation/login/code with a url) is gated, closing the goto_url/code escape;+ no-url navigation/login/extraction/validation blocks act on the current+ frontier. The first goto_url (the entrypoint scaffold) is exempt so the agent+ can record it and scout from it (SKY-10346). A url-bearing block whose url+ changed under the same label is re-gated so an edit cannot retarget a block to+ an unobserved page.-def _new_page_reading_blocks(workflow_yaml: str | None, previous_workflow_yaml: str | None) -> list[dict[str, str]]:- previous = {- (str(block.get("label") or ""), str(block.get("block_type") or "").strip().lower())+ target_url is the page the block acts on (own url, else nearest preceding+ goto_url, else the workflow entrypoint) for path/origin evidence matching.+ """+ previous_by_key = {+ (str(block.get("label") or ""), str(block.get("block_type") or "").strip().lower()): _block_url(block) or ""for block in _parse_workflow_blocks(previous_workflow_yaml)}- blocks: list[dict[str, str]] = []- for block in _parse_workflow_blocks(workflow_yaml):+ gated: list[dict[str, Any]] = []+ nearest_goto: str | None = None+ fallback_url = workflow_target_url(workflow_yaml)+ for index, block in enumerate(_parse_workflow_blocks(workflow_yaml)):block_type = str(block.get("block_type") or "").strip().lower()- if block_type not in _PAGE_READING_BLOCK_TYPES:+ url = _block_url(block)+ if url:+ nearest_goto = url+ if index == 0 and block_type == _GOTO_URL_BLOCK_TYPE:+ # entrypoint scaffold — ungated so the agent can record it and scout from it.continue- label = str(block.get("label") or "<missing label>")- if (label, block_type) in previous:+ acts_via = _block_acts_on_page(block)+ if acts_via is None:continue- blocks.append({"label": label, "block_type": block_type})- return blocks+ label = str(block.get("label") or "<missing label>")+ key = (label, block_type)+ is_new = key not in previous_by_key+ is_changed = (acts_via == "url") and (not is_new) and (previous_by_key.get(key) or "") != (url or "")+ if is_new or is_changed:+ gated.append(+ {+ "label": label,+ "block_type": block_type,+ "target_url": url or nearest_goto or fallback_url,+ }+ )+ return gateddef _changed_goto_url_blocks(workflow_yaml: str | None, previous_workflow_yaml: str | None) -> list[dict[str, str]]:@@ -429,7 +455,7 @@ def _post_run_observed_url_goto_error()-def _has_bounded_page_schema(evidence: dict[str, Any]) -> bool:+def has_bounded_page_schema(evidence: dict[str, Any]) -> bool:for key in ("forms", "navigation_targets", "result_containers", "challenge_controls"):value = evidence.get(key)if isinstance(value, list) and value:@@ -451,10 +477,15 @@ def _evidence_matches_target(inspected_url = evidence.get("inspected_url")current_url = current_url if isinstance(current_url, str) else Noneinspected_url = inspected_url if isinstance(inspected_url, str) else None- if source_tool == _SCHEMA_EVIDENCE_TOOL:+ # A hollow inspection (empty forms/links/result containers, no detected+ # challenge) is not observation — `inspect_page_for_composition` can return an+ # empty schema when the page had not rendered at capture time, so URL match+ # alone must not satisfy the gate. Require a bounded page schema for every+ # evidence source, the inspector included.+ if source_tool == _SCHEMA_EVIDENCE_TOOL and has_bounded_page_schema(evidence):if _same_page(current_url, target_url) or _same_page(inspected_url, target_url):return True- if source_tool in _STRUCTURED_BROWSER_EVIDENCE_TOOLS and _has_bounded_page_schema(evidence):+ if source_tool in _STRUCTURED_BROWSER_EVIDENCE_TOOLS and has_bounded_page_schema(evidence):if _same_page(current_url, target_url) or _same_page(inspected_url, target_url):return Trueif allow_post_run_browser_observation and (@@ -464,20 +495,60 @@ def _evidence_matches_target(if (allow_post_run_browser_observationand source_tool in _POST_RUN_CONTINUATION_EVIDENCE_TOOLS- and (source_tool == _SCHEMA_EVIDENCE_TOOL or _has_bounded_page_schema(evidence))+ and has_bounded_page_schema(evidence)and evidence.get("observed_after_workflow_run") is True):return _same_origin(current_url, target_url) or _same_origin(inspected_url, target_url)return False-def composition_page_evidence_error(ctx: Any, workflow_yaml: str | None) -> str | None:- """Return a mutation error when a build adds page-dependent blocks before inspection.+def _turn_evidence_sources(ctx: Any) -> list[dict[str, Any]]:+ """Every page-evidence packet available this turn: the flow-evidence trajectory+ (one packet per scouted page) plus the legacy single composition_page_evidence+ slot (back-compat for callers and tests that set only it).+ """+ sources: list[dict[str, Any]] = []+ for entry in getattr(ctx, "flow_evidence", None) or []:+ if isinstance(entry, dict):+ packet = entry.get("evidence")+ if isinstance(packet, dict):+ sources.append(packet)+ single = getattr(ctx, "composition_page_evidence", None)+ if isinstance(single, dict):+ sources.append(single)+ return sources+++def _prior_observed_pages(ctx: Any) -> list[dict[str, Any]]:+ return [page for page in (getattr(ctx, "prior_observed_acted_pages", None) or []) if isinstance(page, dict)]- This is deliberately structural rather than semantic: the contract says- page-shaping workflow blocks need inspected page evidence first. Grounding- quality is measured by evals and the page-evidence tool output, not by a- growing natural-language classifier in the mutation path.++def _page_observed(ctx: Any, target_url: str | None, *, allow_post_run: bool) -> bool:+ if not target_url:+ return False+ for evidence in _turn_evidence_sources(ctx):+ if _evidence_matches_target(evidence, target_url, allow_post_run_browser_observation=allow_post_run):+ return True+ # Cross-turn credit requires the SAME page (netloc+path), not just same+ # origin: the compact summary only proves which page was observed, so a+ # same-origin relaxation would credit a gated block on a sibling page the+ # agent never saw. The within-turn post-run same-origin continuation still+ # applies above via _evidence_matches_target.+ for page in _prior_observed_pages(ctx):+ if page.get("had_bounded_schema") and _same_page(page.get("url"), target_url):+ return True+ return False+++def composition_page_evidence_error(ctx: Any, workflow_yaml: str | None) -> str | None:+ """Return a mutation error when a build adds page-acting blocks before observation.++ Deliberately structural rather than semantic: every block that acts on a page+ — block-type-agnostic, including goto_url/code blocks that carry a url, and+ each page across a multi-page flow — needs observed evidence of that page+ first. Whether the agent observed the *right* live state (e.g. a control that+ only appears after a click) is driven by the agent's live scouting and measured+ by evals, not enforced by a classifier in the mutation path."""if not _mode_requires_evidence(ctx):@@ -487,29 +558,23 @@ def composition_page_evidence_error(ctx: Any, workflow_yaml: str | None) -> strif post_run_url_error:return post_run_url_error- page_shaping_blocks = _new_page_shaping_blocks(workflow_yaml, previous_workflow_yaml)- page_reading_blocks = _new_page_reading_blocks(workflow_yaml, previous_workflow_yaml)- if not page_shaping_blocks and not page_reading_blocks:+ gated_blocks = _gated_page_acting_blocks(workflow_yaml, previous_workflow_yaml)+ if not gated_blocks:return None- target_url = _workflow_target_url_for_new_page_block(workflow_yaml, previous_workflow_yaml)- evidence = getattr(ctx, "composition_page_evidence", None)- allow_post_run_browser_observation = bool(previous_workflow_yaml)- if not _evidence_matches_target(- evidence,- target_url,- allow_post_run_browser_observation=allow_post_run_browser_observation,- ):- offending = _format_page_block_findings(page_shaping_blocks + page_reading_blocks)- return (- "Workflow validation failed: page-dependent build blocks need observed page evidence before they are "- f"authored. Call inspect_page_for_composition(target_url={target_url!r}) before composing page-dependent "- "blocks, or save only the initial goto_url block and inspect the reached page before the next mutation. "- f"Offending blocks: {offending}"- )+ allow_post_run = bool(previous_workflow_yaml)+ for block in gated_blocks:+ target_url = block["target_url"]+ if not _page_observed(ctx, target_url, allow_post_run=allow_post_run):+ return (+ "Workflow validation failed: page-dependent build blocks need observed page evidence before they are "+ f"authored. Call inspect_page_for_composition(target_url={target_url!r}) before composing page-dependent "+ "blocks, or save only the initial goto_url block and inspect the reached page before the next mutation. "+ f"Offending blocks: {_format_page_block_findings([block])}"+ )# Matched page evidence may ground a multi-block mutation. This gate enforces- # inspection before page-dependent composition; it does not prescribe a+ # observation before page-dependent composition; it does not prescribe a# one-block-per-observation workflow construction style.return Nonediff --git a/skyvern/forge/sdk/copilot/config.py b/skyvern/forge/sdk/copilot/config.pyindex 9d66c6fc9..add2ca340 100644--- a/skyvern/forge/sdk/copilot/config.py+++ b/skyvern/forge/sdk/copilot/config.py@@ -59,6 +59,20 @@ POST_FAILED_TEST_NUDGE = ("Do NOT resubmit the same workflow — you must change something substantive.")+POST_FAILED_TEST_INSPECT_FIRST_NUDGE = (+ "STOP — your last test run FAILED and the browser is still on the page it reached. "+ "Do NOT respond to the user, and do NOT re-run a changed block goal blind.\n"+ "1. Call get_run_results (pass the workflow_run_id) for the per-block failure_reason.\n"+ '2. Then OBSERVE where it failed: call inspect_page_for_composition(target_url="current_page") '+ "(or evaluate / get_browser_screenshot) on the reached page BEFORE changing anything. A failed "+ "navigation/action often left the page in a state the block's goal did not expect — a popup or "+ "overlay, a different layout, or an effect that already applied.\n"+ "3. Use that observed evidence to decide HOW to change the workflow: keep the same block with a "+ "corrected goal, swap to a different block type, or redesign the step. Do NOT guess a new goal "+ "for the same block and re-run without first observing the page.\n"+ "Do NOT resubmit the same workflow unchanged."+)+POST_EXPLORE_WITHOUT_WORKFLOW_NUDGE = ("STOP — you explored the page using direct browser tools but did NOT engage ""the workflow path. You MUST follow the WORKFLOW-FIRST EXECUTION PATH:\n"@@ -206,6 +220,18 @@ POST_PER_TOOL_BUDGET_NUDGE = ("with a blocker explanation.")+POST_PER_TOOL_BUDGET_STOP_NUDGE = (+ "STOP — you have now hit the per-tool-call time budget MORE THAN ONCE on this goal, "+ "including after you already shrank the frontier. The page is too heavy to finish a "+ "page-changing block within one tool call, and each retry has LESS budget than the last — "+ "running again will fail faster, not succeed.\n"+ "Do NOT call update_and_run_blocks or run_blocks_and_collect_debug again, and do NOT "+ "redesign the workflow hoping a different shape runs faster. Reply to the user now: keep "+ "the verified prefix, name the block that could not finish within the time budget, and "+ "state exactly what was and was not verified end-to-end. Do not repeat this message as the "+ "user-facing answer."+)+POST_NO_WORKFLOW_DELIVERY_NUDGE = ("STOP — you are telling the user you created or are showing a workflow, ""but no workflow update tool has succeeded in this turn. The user will see "@@ -277,6 +303,7 @@ DEFAULT_ENFORCEMENT_NUDGES: dict[str, str] = {"post_navigate": POST_NAVIGATE_NUDGE,"post_intermediate_success": POST_INTERMEDIATE_SUCCESS_NUDGE,"post_failed_test": POST_FAILED_TEST_NUDGE,+ "post_failed_test_inspect_first": POST_FAILED_TEST_INSPECT_FIRST_NUDGE,"post_explore_without_workflow": POST_EXPLORE_WITHOUT_WORKFLOW_NUDGE,"post_suspicious_success": POST_SUSPICIOUS_SUCCESS_NUDGE,"post_repeated_null_data": POST_REPEATED_NULL_DATA_NUDGE,@@ -286,6 +313,7 @@ DEFAULT_ENFORCEMENT_NUDGES: dict[str, str] = {"post_non_retriable_nav_error_stop": POST_NON_RETRIABLE_NAV_ERROR_STOP_NUDGE,"post_parameter_binding_stop": POST_PARAMETER_BINDING_STOP_NUDGE,"post_per_tool_budget": POST_PER_TOOL_BUDGET_NUDGE,+ "post_per_tool_budget_stop": POST_PER_TOOL_BUDGET_STOP_NUDGE,"post_no_workflow_delivery": POST_NO_WORKFLOW_DELIVERY_NUDGE,"post_probable_site_block_stop_prefix": PROBABLE_SITE_BLOCK_STOP_NUDGE_PREFIX,"post_probable_site_block_stop": POST_PROBABLE_SITE_BLOCK_STOP_NUDGE,diff --git a/skyvern/forge/sdk/copilot/context.py b/skyvern/forge/sdk/copilot/context.pyindex 7278fecec..f8dffe2ee 100644--- a/skyvern/forge/sdk/copilot/context.py+++ b/skyvern/forge/sdk/copilot/context.py@@ -92,6 +92,21 @@ class CredentialCheck(BaseModel):found: bool = False+class ObservedPage(BaseModel):+ """Compact cross-turn record of a page the agent scouted (SKY-10562).++ Carries only what the composition gate needs to credit a prior observation:+ the full scheme-bearing url (so urlparse-based _same_page/_same_origin match),+ whether bounded page schema was captured, and how the state was reached. Full+ page schemas stay within-turn; this keeps a resumed turn from re-scouting (or+ deadlocking against a spent inspection budget) for pages already observed.+ """++ url: str = ""+ had_bounded_schema: bool = False+ reached_via: str = ""++class StructuredContext(BaseModel):user_goal: str = ""urls_visited: list[UrlVisit] = Field(default_factory=list)@@ -104,6 +119,7 @@ class StructuredContext(BaseModel):# AgentResult exit by `finalize_discovery_counter_in_global_llm_context`.discovery_calls_made: int = 0page_inspection_calls_made: int = 0+ observed_acted_pages: list[ObservedPage] = Field(default_factory=list)def to_json_str(self) -> str:return self.model_dump_json(indent=2)@@ -174,6 +190,30 @@ class StructuredContext(BaseModel):self.credentials_checked = self.credentials_checked[-40:]+_MAX_OBSERVED_ACTED_PAGES = 20+++def _merge_observed_acted_pages(prior: list[ObservedPage], flow_evidence: list[dict[str, Any]]) -> list[ObservedPage]:+ """Fold this turn's flow-evidence trajectory into the persisted summary.++ Keyed by url; a later observation of the same url replaces the earlier one,+ and a bounded-schema or interaction observation never regresses to a weaker+ one for the same page.+ """+ by_url: dict[str, ObservedPage] = {page.url: page for page in prior if page.url}+ for entry in flow_evidence:+ url = entry.get("url")+ if not isinstance(url, str) or not url.strip():+ continue+ existing = by_url.get(url)+ had_schema = bool(entry.get("had_bounded_schema")) or (existing.had_bounded_schema if existing else False)+ reached_via = str(entry.get("reached_via") or (existing.reached_via if existing else ""))+ if existing and existing.reached_via == "interaction":+ reached_via = "interaction"+ by_url[url] = ObservedPage(url=url, had_bounded_schema=had_schema, reached_via=reached_via)+ return list(by_url.values())[-_MAX_OBSERVED_ACTED_PAGES:]++def finalize_discovery_counter_in_global_llm_context(ctx: Any, raw_context: str | None) -> str | None:"""Fold the per-chat discovery counter into the outgoing global_llm_context.@@ -190,11 +230,13 @@ def finalize_discovery_counter_in_global_llm_context(ctx: Any, raw_context: strthis_turn = int(getattr(ctx, "discovery_calls_this_turn", 0) or 0)prior_inspections = int(getattr(ctx, "prior_page_inspection_calls_made", 0) or 0)inspections_this_turn = int(getattr(ctx, "page_inspection_calls_this_turn", 0) or 0)- if not raw_context and this_turn == 0 and inspections_this_turn == 0:+ flow_evidence = getattr(ctx, "flow_evidence", None) or []+ if not raw_context and this_turn == 0 and inspections_this_turn == 0 and not flow_evidence:return Nonesc = StructuredContext.from_json_str(raw_context)sc.discovery_calls_made = prior + this_turnsc.page_inspection_calls_made = prior_inspections + inspections_this_turn+ sc.observed_acted_pages = _merge_observed_acted_pages(sc.observed_acted_pages, flow_evidence)return sc.to_json_str()diff --git a/skyvern/forge/sdk/copilot/enforcement.py b/skyvern/forge/sdk/copilot/enforcement.pyindex 0a8f144c6..70db226d1 100644--- a/skyvern/forge/sdk/copilot/enforcement.py+++ b/skyvern/forge/sdk/copilot/enforcement.py@@ -19,6 +19,7 @@ from skyvern.forge.sdk.copilot.config import (DEFAULT_TOKEN_BUDGET,POST_ANTI_BOT_FAILED_TEST_NUDGE,POST_EXPLORE_WITHOUT_WORKFLOW_NUDGE,+ POST_FAILED_TEST_INSPECT_FIRST_NUDGE,POST_FAILED_TEST_NUDGE,POST_NAVIGATE_NUDGE,POST_NO_WORKFLOW_DELIVERY_NUDGE,@@ -26,6 +27,7 @@ from skyvern.forge.sdk.copilot.config import (POST_PARAMETER_BINDING_STOP_NUDGE,POST_PARAMETER_BINDING_WARN_NUDGE,POST_PER_TOOL_BUDGET_NUDGE,+ POST_PER_TOOL_BUDGET_STOP_NUDGE,POST_PROBABLE_SITE_BLOCK_STOP_NUDGE,POST_REPEATED_FRONTIER_FAILURE_STOP_NUDGE,POST_REPEATED_FRONTIER_FAILURE_WARN_NUDGE,@@ -640,6 +642,22 @@ def _needs_failed_test_nudge(ctx: Any) -> bool:return nudge_count < MAX_FAILED_TEST_NUDGES+def _needs_inspect_before_repair_nudge(ctx: Any) -> bool:+ """True when a failed run is repairable and the reached page is not yet observed.++ Routes the first post-failure move to observing the reached page before+ re-authoring, instead of guessing a new block goal and re-running blind.+ """+ contract = getattr(ctx, "latest_diagnosis_repair_contract", None)+ if contract is None:+ return False+ if contract.repair_decision.next_action is not RepairNextAction.REPAIR:+ return False+ if not contract.diagnosis_input.browser_page_state.get("has_current_url"):+ return False+ return not _has_post_failed_run_page_observation(ctx)++def _has_post_failed_run_page_observation(ctx: AgentContext) -> bool:if getattr(ctx, "post_run_page_observation_after_failed_test", False) is not True:return False@@ -821,7 +839,13 @@ def _check_enforcement(# chain" advice before the generic repeated-frontier and failed-test paths# can fire.if _needs_per_tool_budget_nudge(ctx):- ctx.per_tool_budget_nudge_count = _get_int(ctx, "per_tool_budget_nudge_count") + 1+ prior = _get_int(ctx, "per_tool_budget_nudge_count")+ ctx.per_tool_budget_nudge_count = prior + 1+ # First budget trip earns one smaller-frontier retry. A second consecutive trip+ # (the shrunk frontier ALSO blew the budget) is a doomed shrinking-budget spiral on a+ # too-heavy page — finalize the verified prefix instead of re-running into less time.+ if prior >= 1:+ return _nudge(config, "post_per_tool_budget_stop")return _nudge(config, "post_per_tool_budget")repeated_frontier_nudge = _repeated_frontier_failure_nudge(ctx, config)@@ -853,6 +877,8 @@ def _check_enforcement(if _needs_failed_test_nudge(ctx):ctx.failed_test_nudge_count += 1+ if _needs_inspect_before_repair_nudge(ctx):+ return _nudge(config, "post_failed_test_inspect_first")return _nudge(config, "post_failed_test")# Response-time gate: peek at the model's final output to tell ASK_QUESTION@@ -1152,8 +1178,10 @@ _NUDGE_TYPE_BY_MESSAGE: dict[str, str] = {POST_ANTI_BOT_FAILED_TEST_NUDGE: "anti_bot_block",POST_PROBABLE_SITE_BLOCK_STOP_NUDGE: "probable_site_block_stop",POST_PER_TOOL_BUDGET_NUDGE: "per_tool_budget_split",+ POST_PER_TOOL_BUDGET_STOP_NUDGE: "per_tool_budget_stop",POST_NO_WORKFLOW_DELIVERY_NUDGE: "no_workflow_delivery",POST_FAILED_TEST_NUDGE: "post_failed_test",+ POST_FAILED_TEST_INSPECT_FIRST_NUDGE: "post_failed_test_inspect_first",SCREENSHOT_DROPPED_NUDGE: "screenshot_dropped_on_recovery",}@@ -1173,8 +1201,10 @@ _NUDGE_TYPE_BY_KEY: dict[str, str] = {"post_probable_site_block_stop": "probable_site_block_stop","post_probable_site_block_stop_prefix": "probable_site_block_stop","post_per_tool_budget": "per_tool_budget_split",+ "post_per_tool_budget_stop": "per_tool_budget_stop","post_no_workflow_delivery": "no_workflow_delivery","post_failed_test": "post_failed_test",+ "post_failed_test_inspect_first": "post_failed_test_inspect_first","screenshot_dropped": "screenshot_dropped_on_recovery","post_intermediate_success": "intermediate_success","post_format": "format",diff --git a/skyvern/forge/sdk/copilot/runtime.py b/skyvern/forge/sdk/copilot/runtime.pyindex f4f3983ac..6201f4261 100644--- a/skyvern/forge/sdk/copilot/runtime.py+++ b/skyvern/forge/sdk/copilot/runtime.py@@ -174,6 +174,15 @@ class AgentContext:completion_verification_result: CompletionVerificationResult | None = Noneoutcome_verification_trace_snapshot: dict[str, Any] = field(default_factory=dict)composition_page_evidence: dict[str, Any] | None = None+ # Ordered, bounded list of typed page-evidence packets — one per page observed+ # while scouting the goal path, each tagged with how that state was reached.+ # Feeds the per-acted-page composition gate; never persisted into workflow YAML.+ flow_evidence: list[dict[str, Any]] = field(default_factory=list)+ # Hydrated at turn start from StructuredContext.observed_acted_pages; lets the+ # composition gate credit a page observed on a prior turn when this turn's+ # flow_evidence does not cover it (closes the spent-inspection-budget+ # deadlock). Each item: {url, had_bounded_schema, reached_via}.+ prior_observed_acted_pages: list[dict[str, Any]] = field(default_factory=list)post_budget_page_inspection_required: bool = Falsepost_budget_page_inspection_url: str | None = Nonepost_budget_page_inspection_run_id: str | None = Nonediff --git a/skyvern/forge/sdk/copilot/tools.py b/skyvern/forge/sdk/copilot/tools.pyindex eb70ec714..633e7065d 100644--- a/skyvern/forge/sdk/copilot/tools.py+++ b/skyvern/forge/sdk/copilot/tools.py@@ -57,6 +57,7 @@ from skyvern.forge.sdk.copilot.completion_verification import ()from skyvern.forge.sdk.copilot.composition_evidence import (composition_page_evidence_error,+ has_bounded_page_schema,merge_visual_composition_evidence,page_evidence_needs_visual_fallback,parse_composition_html,@@ -3061,6 +3062,9 @@ def _frontier_run_size_error("Workflow validation failed: this browser test frontier is too long for a multi-stage ""page-changing workflow. Keep the same complete workflow YAML, but shrink only the "f"block_labels argument to the next 1-2 unverified labels: {suggested!r}. "+ "If a prior run already advanced the browser, inspect that reached page "+ '(inspect_page_for_composition(target_url="current_page")) to ground the next labels in '+ "what is actually there rather than shrinking the frontier blind. "f"Do not remove later blocks from the YAML; test them after this frontier succeeds. "f"Deferred labels: {remaining!r}. Requested labels: {block_labels!r}.")@@ -4673,6 +4677,65 @@ async def _click_post_hook(return result+_TYPE_READBACK_SETTLE_SECONDS = 0.3+++async def _verify_scout_type_landed(+ ctx: AgentContext,+ *,+ selector: str,+ typed_length: Any,+) -> dict[str, Any] | None:+ """Confirm a non-empty type actually entered the field, else return a failure.++ A marketing/cookie overlay can consume the focus or keystrokes — the field+ stays empty while `skyvern_type` still reports success (the first interaction+ on an overlaid page often just dismisses the overlay). Read the field back; a+ field still empty after a non-empty type means the input did not land. Only+ fires when there is a selector to read and a positive typed length, so it never+ second-guesses intent-only types or masked/formatted values, which keep a+ non-empty value.+ """+ if not isinstance(selector, str) or not selector.strip():+ return None+ if not isinstance(typed_length, int) or typed_length <= 0:+ return None+ server = getattr(ctx, "discovery_mcp_server", None)+ if server is None:+ return None++ async def _read_back() -> Any:+ try:+ readback = await asyncio.wait_for(+ server.call_internal_tool("skyvern_get_value", {"selector": selector}),+ timeout=_DISCOVERY_PER_CALL_TIMEOUT_SECONDS,+ )+ except Exception:+ LOG.debug("scout type-landed read-back failed; leaving the type result unverified", exc_info=True)+ return None+ if not isinstance(readback, dict) or not readback.get("ok"):+ return None+ return (readback.get("data") or {}).get("value")++ value = await _read_back()+ if isinstance(value, str) and value.strip() == "":+ # A controlled/React input can mirror its value asynchronously, so a first read may be+ # transiently empty; settle briefly and re-read once before declaring the type lost.+ await asyncio.sleep(_TYPE_READBACK_SETTLE_SECONDS)+ value = await _read_back()+ if isinstance(value, str) and value.strip() == "":+ return {+ "ok": False,+ "error": (+ "type_text reported success but the field is still empty — an overlay "+ "(cookie/marketing popup) likely consumed the keystrokes or focus. "+ "Re-inspect the current page and retry typing into the target field; "+ "the overlay is usually dismissed by that first interaction."+ ),+ }+ return None++async def _type_text_post_hook(result: dict[str, Any],raw: dict[str, Any],@@ -4680,12 +4743,17 @@ async def _type_text_post_hook() -> dict[str, Any]:if result.get("ok") and result.get("data"):data = result["data"]+ selector = data.get("selector", "")+ typed_length = data.get("text_length", 0)url, _ = await _resolve_url_title(raw, ctx)result["data"] = {- "selector": data.get("selector", ""),- "typed_length": data.get("text_length", 0),+ "selector": selector,+ "typed_length": typed_length,"url": url,}+ landing_failure = await _verify_scout_type_landed(ctx, selector=selector, typed_length=typed_length)+ if landing_failure is not None:+ return landing_failurereturn result@@ -4819,14 +4887,21 @@ def _build_skyvern_mcp_overlays() -> dict[str, SchemaOverlay]:),"click": SchemaOverlay(description=(- "Click an element in the browser. Use a CSS selector, an AI intent "- "description, or both for resilient targeting. "+ "Click an element in the browser. Prefer a CSS selector ALONE for a target "+ "you can identify from page evidence — a selector-only click is instant and "+ "deterministic. Use `intent` only when you cannot derive a selector: an "+ "`intent`-only click routes through a slower full-page AI scan, and if you "+ "pass both, the selector wins and the `intent` is ignored. When a shared class "+ "matches many elements (e.g. one button per result row), scope the selector to "+ "the specific item (its container, a unique attribute, or :nth-of-type) instead "+ "of relying on `intent` to disambiguate. ""IMPORTANT: jQuery pseudo-selectors like :contains(), :eq(), :first, "":visible are NOT valid CSS. Use standard selectors: ""'button.download', 'a[href*=\"pdf\"]', '#submit-btn', ""'table tr:nth-of-type(2) td a'."),hide_params=frozenset({"session_id", "cdp_url", "button", "click_count"}),+ forced_args={"selector_mode": "direct"},requires_browser=True,timeout=15,pre_hook=_click_pre_hook,@@ -4834,8 +4909,11 @@ def _build_skyvern_mcp_overlays() -> dict[str, SchemaOverlay]:),"type_text": SchemaOverlay(description=(- "Type text into an input element. Use a CSS selector, an AI intent "- "description, or both to target the field. "+ "Type text into an input element. Prefer a CSS selector ALONE to target the "+ "field — a selector-only type is instant and deterministic. Use `intent` only "+ "when you cannot derive a selector: an `intent`-only type routes through a "+ "slower full-page AI scan, and if you pass both, the selector wins and the "+ "`intent` is ignored. ""Optionally clear the field first. Use this for form filling. ""NEVER type inline passwords, API keys, tokens, cookies, TOTP/OTP ""codes, private keys, or other raw credentials/secrets received in "@@ -4843,6 +4921,7 @@ def _build_skyvern_mcp_overlays() -> dict[str, SchemaOverlay]:"system prompt instead."),hide_params=frozenset({"session_id", "cdp_url", "delay"}),+ forced_args={"selector_mode": "direct"},required_overrides=["text"],arg_transforms={"clear_first": "clear"},requires_browser=True,@@ -4870,11 +4949,13 @@ def _build_skyvern_mcp_overlays() -> dict[str, SchemaOverlay]:),"select_option": SchemaOverlay(description=(- "Select an option from a <select> dropdown. Provide the value to select "- "and use selector or intent to target the element. "- "For free-text inputs, use type_text instead."+ "Select an option from a <select> dropdown. Provide the value to select and a "+ "selector to target the element precisely; use `intent` (alone) only when you "+ "cannot derive a selector — passing both lets the selector win and ignores the "+ "`intent`. For free-text inputs, use type_text instead."),hide_params=frozenset({"session_id", "cdp_url", "timeout"}),+ forced_args={"selector_mode": "direct"},required_overrides=["value"],requires_browser=True,timeout=15,@@ -5577,7 +5658,11 @@ async def update_workflow_tool(loop_error = _tool_loop_error(copilot_ctx, "update_workflow", arguments)if loop_error:return json.dumps({"ok": False, "error": loop_error})- if _request_policy_allows_credential_deferred_draft(copilot_ctx):+ credential_deferred_draft = _request_policy_allows_credential_deferred_draft(copilot_ctx)+ # A credential-deferred draft is redirected to update_and_run_blocks' skip-run+ # save path, which saves the draft and skips the browser run with the required+ # credential setup message.+ if credential_deferred_draft:agent_steering = ("Use update_and_run_blocks for this credential-deferred draft. It will save the workflow draft ""and skip the browser run with the required credential setup message."@@ -6277,17 +6362,34 @@ _DISCOVERY_PER_CALL_TIMEOUT_SECONDS = 20.0_DISCOVERY_NAVIGATION_FALLBACK_CONFIDENCE = 0.2-async def _discovery_navigate(ctx: CopilotContext, url: str) -> dict[str, Any]:+async def _discovery_navigate(+ ctx: CopilotContext,+ url: str,+ *,+ wait_until: str | None = None,+ timeout_seconds: float = _DISCOVERY_PER_CALL_TIMEOUT_SECONDS,+) -> dict[str, Any]:server = getattr(ctx, "discovery_mcp_server", None)if server is None:return {"ok": False, "error": "discovery MCP server not attached to context"}+ nav_args: dict[str, Any] = {"url": url}+ cap = timeout_seconds+ if wait_until:+ # `load` waits for every resource (analytics/marketing beacons on heavy+ # commerce pages keep it pending past the cap, so the navigate aborts before+ # any HTML is captured). `domcontentloaded` returns once the server-rendered+ # DOM is parsed — the forms/links are already present — and the recapture+ # loop settles anything still hydrating.+ nav_args["wait_until"] = wait_until+ nav_args["timeout"] = int(timeout_seconds * 1000)+ cap = timeout_seconds + 5try:return await asyncio.wait_for(- server.call_internal_tool("skyvern_navigate", {"url": url}),- timeout=_DISCOVERY_PER_CALL_TIMEOUT_SECONDS,+ server.call_internal_tool("skyvern_navigate", nav_args),+ timeout=cap,)except asyncio.TimeoutError:- return {"ok": False, "error": f"skyvern_navigate timed out after {_DISCOVERY_PER_CALL_TIMEOUT_SECONDS:g}s"}+ return {"ok": False, "error": f"skyvern_navigate timed out after {timeout_seconds:g}s"}async def _discovery_click_anchor(ctx: CopilotContext, anchor: dict[str, str]) -> dict[str, Any]:@@ -6299,7 +6401,9 @@ async def _discovery_click_anchor(ctx: CopilotContext, anchor: dict[str, str]) -return {"ok": False, "error": "anchor href could not be converted to a bounded CSS selector"}try:return await asyncio.wait_for(- server.call_internal_tool("skyvern_click", {"selector": selector}),+ # call_internal_tool bypasses the schema overlays, so selector_mode="direct" must be+ # passed explicitly here (it is not picked up from the overlay's forced_args).+ server.call_internal_tool("skyvern_click", {"selector": selector, "selector_mode": "direct"}),timeout=_DISCOVERY_PER_CALL_TIMEOUT_SECONDS,)except asyncio.TimeoutError:@@ -6497,14 +6601,17 @@ async def _composition_evidence_after_navigation_failure() -> dict[str, Any] | None:current_url, _ = await _fallback_page_info(ctx)current_url = current_url or inspected_url- html_result = await _discovery_get_html(ctx)- if html_result.get("ok"):- html = _discovery_extract_html_payload(html_result)+ # Same size-cap survival as the success path: a heavy page that rendered before the nav+ # error still parses via the stripped-body evaluate instead of yielding hollow evidence.+ html, html_error, html_truncated = await _composition_get_html(ctx)+ if html_error is None:evidence = parse_composition_html(html, inspected_url=inspected_url, current_url=current_url)evidence = _composition_add_inspection_warning(evidence,f"navigation_error_before_html_capture: {navigation_error}",)+ if html_truncated:+ evidence = _composition_add_inspection_warning(evidence, "html_sliced_at_cap")if page_evidence_needs_visual_fallback(evidence):evidence = await _augment_composition_evidence_with_visual_fallback(ctx, evidence)return evidence@@ -6516,12 +6623,161 @@ async def _composition_evidence_after_navigation_failure()evidence = _composition_add_inspection_warning(evidence,- f"html_capture_failed_after_navigation_error: {html_result.get('error', 'unknown')}",+ f"html_capture_failed_after_navigation_error: {html_error}",)evidence = await _augment_composition_evidence_with_visual_fallback(ctx, evidence)return evidence if evidence.get("screenshot_used") else None+_MAX_FLOW_EVIDENCE = 12+++def _inspection_reached_via(*, use_current_page: bool, post_run: bool) -> str:+ """How the just-inspected state was reached, for the flow-evidence trajectory.++ A target_url inspection navigates there itself ("navigate"); a post-run+ current-page inspection observes the page the run left behind ("post_run"); any+ other current-page inspection follows an in-turn interaction on that page.+ """+ if not use_current_page:+ return "navigate"+ if post_run:+ return "post_run"+ return "interaction"+++def _append_flow_evidence(copilot_ctx: Any, evidence: dict[str, Any], *, reached_via: str) -> None:+ """Append a typed entry to the bounded flow-evidence trajectory (SKY-10562).++ One entry per scouted page: the page-evidence packet plus how it was reached+ and whether bounded schema was captured. Feeds the per-acted-page composition+ gate and the cross-turn observed-page summary; never written into the YAML.+ """+ trajectory = getattr(copilot_ctx, "flow_evidence", None)+ if not isinstance(trajectory, list):+ return+ url = evidence.get("current_url") or evidence.get("inspected_url") or ""+ trajectory.append(+ {+ "evidence": evidence,+ "reached_via": reached_via,+ "url": url if isinstance(url, str) else "",+ "had_bounded_schema": has_bounded_page_schema(evidence),+ "step": len(trajectory),+ }+ )+ if len(trajectory) > _MAX_FLOW_EVIDENCE:+ del trajectory[:-_MAX_FLOW_EVIDENCE]+++_COMPOSITION_HOLLOW_RECAPTURE_RETRIES = 2+_COMPOSITION_HOLLOW_RECAPTURE_DELAY_SECONDS = 2.5+# The composition inspect navigates with `domcontentloaded`, so a heavier cap than+# the discovery walker's is safe — the navigate returns at DOM parse, well before+# this ceiling, and only a genuinely stuck load reaches it.+_COMPOSITION_NAVIGATE_TIMEOUT_SECONDS = 30.0+++# Body HTML stripped of script/style/svg/comments and whitespace-collapsed so the+# evaluate result clears the shared MCP response size cap (MCP_MAX_RESPONSE_CHARS,+# 140k). The aggressive strip is what lets a heavy commerce body (e.g. ~360KB raw,+# ~155k stripped) fit whole (~113k) so the FULL page is parsed; the slice is only a+# last resort for pages still over budget, and is set as high as the cap allows so it+# loses as little below-fold structure (results/cart controls) as possible.+_COMPOSITION_STRIPPED_HTML_MAX_CHARS = 135000+_COMPOSITION_STRIPPED_HTML_EXPRESSION = (+ "(() => {"+ " const b = document.body; if (!b) return '';"+ " const c = b.cloneNode(true);"+ " c.querySelectorAll('script,style,noscript,svg,template,iframe,canvas,link').forEach(n => n.remove());"+ " const w = document.createTreeWalker(c, NodeFilter.SHOW_COMMENT, null);"+ " const comments = []; while (w.nextNode()) comments.push(w.currentNode); comments.forEach(n => n.remove());"+ " const h = c.innerHTML.replace(/>\\s+</g, '><').replace(/\\s{2,}/g, ' ');"+ f" return h.length > {_COMPOSITION_STRIPPED_HTML_MAX_CHARS} ? h.slice(0, {_COMPOSITION_STRIPPED_HTML_MAX_CHARS}) : h;"+ "})()"+)+++async def _composition_get_stripped_html(copilot_ctx: Any) -> tuple[str | None, bool]:+ """Return (stripped_body_html, truncated). truncated is True when the expression sliced+ the body at the cap, so the tail (below-fold forms/controls) is missing from the evidence."""+ server = getattr(copilot_ctx, "discovery_mcp_server", None)+ if server is None:+ return None, False+ try:+ result = await asyncio.wait_for(+ server.call_internal_tool("skyvern_evaluate", {"expression": _COMPOSITION_STRIPPED_HTML_EXPRESSION}),+ timeout=_DISCOVERY_PER_CALL_TIMEOUT_SECONDS,+ )+ except Exception:+ return None, False+ if not isinstance(result, dict) or not result.get("ok"):+ return None, False+ value = (result.get("data") or {}).get("result")+ if not isinstance(value, str):+ return None, False+ return value, len(value) >= _COMPOSITION_STRIPPED_HTML_MAX_CHARS+++async def _composition_get_html(copilot_ctx: Any) -> tuple[str, str | None, bool]:+ """Return body HTML for composition parsing, surviving the MCP response size cap.++ `skyvern_get_html("body")` is the fast path, but the shared size cap DROPS the+ payload (no `html` field, just truncation metadata) when the serialized body+ exceeds the limit — heavy commerce pages routinely do, so the inspector would+ parse an empty string and report hollow evidence. On an empty/capped read, fall+ back to an `evaluate` that returns the body with script/style/svg/etc. stripped+ and length-bounded; that fits under the cap while preserving the form/link+ structure. Returns (html, error, truncated): error is set only on a hard read+ failure; truncated is True when the stripped fallback was sliced at the cap (the+ raw path is never silently truncated — it is dropped over the cap and falls back).+ """+ html_result = await _discovery_get_html(copilot_ctx)+ if html_result.get("ok"):+ html = _discovery_extract_html_payload(html_result)+ if html.strip():+ return html, None, False+ stripped, truncated = await _composition_get_stripped_html(copilot_ctx)+ if stripped and stripped.strip():+ return stripped, None, truncated+ error = html_result.get("error")+ return "", str(error) if error else None, False+++async def _capture_composition_evidence(+ copilot_ctx: Any,+ *,+ inspected_url: str,+ current_url: str,+) -> tuple[dict[str, Any] | None, str | None]:+ """Read page HTML and parse composition evidence, recapturing on a hollow read.++ The capture (`_composition_get_html`) survives the MCP size cap; this loop adds a+ short settle and re-read for the separate case where the page had not finished+ rendering at capture time (a cold cloud session's first navigate to a heavy page+ can hand back a shell). Returns (evidence, html_error); html_error is set only+ when the HTML read itself failed. Stops early once the parse yields a bounded+ schema (forms/links/result containers/challenge), so a genuine challenge page is+ not retried.+ """+ evidence: dict[str, Any] | None = None+ html_truncated = False+ for attempt in range(_COMPOSITION_HOLLOW_RECAPTURE_RETRIES + 1):+ html, html_error, html_truncated = await _composition_get_html(copilot_ctx)+ if html_error is not None:+ return None, html_error+ evidence = parse_composition_html(html, inspected_url=inspected_url, current_url=current_url)+ if has_bounded_page_schema(evidence):+ break+ if attempt < _COMPOSITION_HOLLOW_RECAPTURE_RETRIES:+ await asyncio.sleep(_COMPOSITION_HOLLOW_RECAPTURE_DELAY_SECONDS)+ if evidence is not None and html_truncated:+ evidence = _composition_add_inspection_warning(evidence, "html_sliced_at_cap")+ if evidence is not None and page_evidence_needs_visual_fallback(evidence):+ evidence = await _augment_composition_evidence_with_visual_fallback(copilot_ctx, evidence)+ return evidence, None++async def _inspect_page_for_composition_impl(copilot_ctx: Any,target_url: str,@@ -6595,22 +6851,24 @@ async def _inspect_page_for_composition_impl():if use_current_page:current_url = entry_url- html_result = await _discovery_get_html(copilot_ctx)- if not html_result.get("ok"):+ evidence, html_error = await _capture_composition_evidence(+ copilot_ctx, inspected_url=entry_url, current_url=current_url+ )+ if html_error is not None:result = {"ok": False,"data": None,- "error": f"inspect_page_for_composition could not read page HTML: {html_result.get('error', 'unknown')}",+ "error": f"inspect_page_for_composition could not read page HTML: {html_error}",}record_tool_step_result_for_ctx(copilot_ctx, "inspect_page_for_composition", arguments, result)return result-- html = _discovery_extract_html_payload(html_result)- evidence = parse_composition_html(html, inspected_url=entry_url, current_url=current_url)- if page_evidence_needs_visual_fallback(evidence):- evidence = await _augment_composition_evidence_with_visual_fallback(copilot_ctx, evidence)else:- nav_result = await _discovery_navigate(copilot_ctx, entry_url)+ nav_result = await _discovery_navigate(+ copilot_ctx,+ entry_url,+ wait_until="domcontentloaded",+ timeout_seconds=_COMPOSITION_NAVIGATE_TIMEOUT_SECONDS,+ )if not nav_result.get("ok"):nav_error = str(nav_result.get("error") or "unknown")failure_evidence = await _composition_evidence_after_navigation_failure(@@ -6630,20 +6888,26 @@ async def _inspect_page_for_composition_impl(current_url = str(evidence.get("current_url") or entry_url)else:current_url = _discovery_extract_current_url(nav_result, entry_url)- html_result = await _discovery_get_html(copilot_ctx)- if not html_result.get("ok"):+ evidence, html_error = await _capture_composition_evidence(+ copilot_ctx, inspected_url=entry_url, current_url=current_url+ )+ if html_error is not None:result = {"ok": False,"data": None,- "error": f"inspect_page_for_composition could not read page HTML: {html_result.get('error', 'unknown')}",+ "error": f"inspect_page_for_composition could not read page HTML: {html_error}",}record_tool_step_result_for_ctx(copilot_ctx, "inspect_page_for_composition", arguments, result)return result- html = _discovery_extract_html_payload(html_result)- evidence = parse_composition_html(html, inspected_url=entry_url, current_url=current_url)- if page_evidence_needs_visual_fallback(evidence):- evidence = await _augment_composition_evidence_with_visual_fallback(copilot_ctx, evidence)+ if evidence is None:+ result = {+ "ok": False,+ "data": None,+ "error": "inspect_page_for_composition could not read page HTML.",+ }+ record_tool_step_result_for_ctx(copilot_ctx, "inspect_page_for_composition", arguments, result)+ return resultrun_id = getattr(copilot_ctx, "last_run_blocks_workflow_run_id", None)if isinstance(run_id, str) and run_id:@@ -6661,8 +6925,13 @@ async def _inspect_page_for_composition_impl(if bypass_budget_for_post_run_current_page:copilot_ctx.post_run_current_page_inspection_workflow_run_id = run_idcopilot_ctx.composition_page_evidence = evidence+ reached_via = _inspection_reached_via(use_current_page=use_current_page, post_run=bool(run_id))+ _append_flow_evidence(copilot_ctx, evidence, reached_via=reached_via)_mark_page_inspected(copilot_ctx)- result = {"ok": True, "data": evidence}+ # Surface the reached page at the top level so the model registers that the+ # inspection already navigated there and does not re-issue navigate_browser.+ current_url = evidence.get("current_url") or evidence.get("inspected_url") or ""+ result = {"ok": True, "current_url": current_url, "reached_via": reached_via, "data": evidence}record_tool_step_result_for_ctx(copilot_ctx, "inspect_page_for_composition", arguments, result)return result@@ -6724,8 +6993,11 @@ async def _discovery_walk()current_url = _discovery_extract_current_url(nav_result, current_url)- html_result = await _discovery_get_html(ctx)- html = _discovery_extract_html_payload(html_result) if html_result.get("ok") else ""+ # Survive the MCP size cap: a heavy DOM exceeds it and the html field is dropped, so+ # fall back to a stripped-body evaluate that keeps the links/forms the resolver needs+ # to identify a usable entrypoint. (Discovery only resolves the entrypoint, so a sliced+ # tail does not matter here.)+ html, _, _ = await _composition_get_html(ctx)page_title, anchors, form_fields = _discovery_parse_html(html)evidence_trail.append(diff --git a/tests/unit/test_copilot_build_phase.py b/tests/unit/test_copilot_build_phase.pyindex c42464e9f..2f1c049c6 100644--- a/tests/unit/test_copilot_build_phase.py+++ b/tests/unit/test_copilot_build_phase.py@@ -43,10 +43,16 @@ def _ti(mode: TurnIntentMode) -> TurnIntent:(TurnIntentMode.DIAGNOSE, "the run failed", "the run failed", "", BuildPhase.COMPOSING),(TurnIntentMode.CLARIFY, "anything", "anything", "", BuildPhase.COMPOSING),(TurnIntentMode.REFUSE, "anything", "anything", "", BuildPhase.COMPOSING),- # BUILD with URL in latest user_message -> COMPOSING.+ # BUILD with a URL -> COMPOSING (entrypoint known; scout there, then author).(TurnIntentMode.BUILD, "go to https://example.com/login", "", "", BuildPhase.COMPOSING),# BUILD with URL only in rewritten agent message (request-policy continuation) -> COMPOSING.- (TurnIntentMode.BUILD, "and download it", "earlier: go to https://example.com/file", "", BuildPhase.COMPOSING),+ (+ TurnIntentMode.BUILD,+ "and download it",+ "earlier: go to https://example.com/file",+ "",+ BuildPhase.COMPOSING,+ ),# BUILD with no URL anywhere -> INITIAL.(TurnIntentMode.BUILD, "go to example", "go to example", "", BuildPhase.INITIAL),# DRAFT_ONLY behaves like BUILD for phase init.@@ -78,7 +84,9 @@ def test_initial_build_phase_returns_expected(assert initial_build_phase(_ti(mode), user_message, agent_message, workflow_yaml) == expected-def test_initial_build_phase_yaml_goto_url_unlocks_composing() -> None:+def test_initial_build_phase_lone_goto_url_enters_composing() -> None:+ # A lone entrypoint goto_url carries a URL signal -> COMPOSING, where the agent+ # scouts the page and authors (page-acting blocks stay evidence-gated).yaml_text = """title: Tworkflow_definition:@@ -94,6 +102,42 @@ workflow_definition:)+def test_initial_build_phase_existing_composition_stays_composing() -> None:+ # A draft that already composes a page-acting block resolves to COMPOSING on a+ # later "run it" / edit turn.+ yaml_text = """+title: T+workflow_definition:+ parameters: []+ blocks:+ - block_type: goto_url+ label: open+ url: https://example.com/page+ - block_type: navigation+ label: act+ navigation_goal: do the thing+"""+ assert initial_build_phase(_ti(TurnIntentMode.BUILD), "run it", "run it", yaml_text) == BuildPhase.COMPOSING+++def test_initial_build_phase_goto_url_plus_action_is_composition() -> None:+ # A goto_url + a no-url action turn resolves to COMPOSING, with block-runs and+ # browser tools available.+ yaml_text = """+title: T+workflow_definition:+ parameters: []+ blocks:+ - block_type: goto_url+ label: open+ url: https://example.com/page+ - block_type: action+ label: click_it+ navigation_goal: click the button+"""+ assert initial_build_phase(_ti(TurnIntentMode.BUILD), "run it", "run it", yaml_text) == BuildPhase.COMPOSING++def test_initial_build_phase_yaml_with_empty_url_does_not_unlock() -> None:yaml_text = """title: T@@ -233,6 +277,10 @@ def test_phase_sets_are_disjoint() -> None:("update_workflow", BuildPhase.COMPOSING, False),("update_and_run_blocks", BuildPhase.INITIAL, True),("run_blocks_and_collect_debug", BuildPhase.DISCOVERING, True),+ # COMPOSING: browser primitives AND block-runs are available so the agent+ # scouts with the fast browser tools and validates with block-runs.+ ("update_and_run_blocks", BuildPhase.COMPOSING, False),+ ("run_blocks_and_collect_debug", BuildPhase.COMPOSING, False),# Unknown tool name -> no error.("list_credentials", BuildPhase.INITIAL, False),("list_credentials", BuildPhase.COMPOSING, False),diff --git a/tests/unit/test_copilot_composition_evidence.py b/tests/unit/test_copilot_composition_evidence.pyindex 88632b68f..c62e95aa7 100644--- a/tests/unit/test_copilot_composition_evidence.py+++ b/tests/unit/test_copilot_composition_evidence.py@@ -23,12 +23,30 @@ class _Ctx:turn_intent: TurnIntent = field(default_factory=lambda: TurnIntent(mode=TurnIntentMode.BUILD))composition_page_evidence: dict | None = Noneworkflow_yaml: str | None = None+ flow_evidence: list[dict] = field(default_factory=list)+ prior_observed_acted_pages: list[dict] = field(default_factory=list)per_tool_budget_problem_block_labels: list[str] = field(default_factory=list)workflow_verification_evidence: WorkflowVerificationEvidence = field(default_factory=WorkflowVerificationEvidence)post_run_page_observation_after_failed_test: bool = Falselast_failure_category_top: str | None = None+def _flow_entry(url: str, *, reached_via: str = "navigate", with_form: bool = True) -> dict:+ evidence: dict = {+ "inspected_url": url,+ "current_url": url,+ "source_tool": "inspect_page_for_composition",+ "forms": [{"fields": [_field("X", "x")], "submit_controls": []}] if with_form else [],+ }+ return {+ "evidence": evidence,+ "reached_via": reached_via,+ "url": url,+ "had_bounded_schema": with_form,+ "step": 0,+ }++def _yaml(*blocks: dict) -> str:return yaml.safe_dump({"title": "wf", "workflow_definition": {"parameters": [], "blocks": list(blocks)}})@@ -243,6 +261,23 @@ def test_composition_gate_requires_page_evidence_before_page_dependent_blocks()assert "search_lookup" in error+def test_composition_gate_requires_page_evidence_before_no_url_action_blocks() -> None:+ # action / file_download / file_upload act on the reached page like a no-url navigation,+ # and the KB steers single clicks toward `action`, so they must be gated the same way.+ goto_block = {"block_type": "goto_url", "label": "open_cart", "url": "https://example.com/cart"}+ for acting_type in ("action", "file_download", "file_upload"):+ acting_block = {+ "block_type": acting_type,+ "label": f"do_{acting_type}",+ "navigation_goal": "Click the Add to cart button on the current page.",+ }++ error = composition_page_evidence_error(_Ctx(), _yaml(goto_block, acting_block))++ assert error is not None, f"{acting_type} should require page evidence"+ assert f"do_{acting_type}" in error++def test_composition_gate_names_extraction_only_blocks_missing_evidence() -> None:workflow_yaml = _yaml({"block_type": "goto_url", "label": "open_results", "url": "https://example.com/results"},@@ -525,6 +560,7 @@ def test_composition_gate_allows_post_run_current_page_schema_on_same_origin_con"inspected_url": "current_page","current_url": "https://example.com/results?id=123","forms": [],+ "result_containers": [{"selector": "#results"}],"source_tool": "inspect_page_for_composition","observed_after_workflow_run": True,}@@ -566,7 +602,7 @@ def test_composition_gate_allows_multiple_new_page_changing_blocks_from_one_obseevidence = {"inspected_url": "current_page","current_url": "https://example.com/lookup",- "forms": [],+ "forms": [{"fields": [{"name": "first_name", "selector": "#first_name"}], "submit_controls": []}],"source_tool": "inspect_page_for_composition","observed_after_workflow_run": True,}@@ -578,6 +614,36 @@ def test_composition_gate_allows_multiple_new_page_changing_blocks_from_one_obseassert error is None+def test_composition_gate_rejects_hollow_inspect_evidence() -> None:+ # A pre-render shell parses to empty forms/links/result containers. An inspect+ # that captured nothing is not observation, so a page-acting block on that URL+ # stays gated — URL match alone must not satisfy the gate (SKY-10562).+ existing_yaml = _yaml({"block_type": "goto_url", "label": "open_lookup", "url": "https://example.com/lookup"})+ workflow_yaml = _yaml(+ {"block_type": "goto_url", "label": "open_lookup", "url": "https://example.com/lookup"},+ {+ "block_type": "navigation",+ "label": "search_lookup",+ "navigation_goal": "Fill the observed search fields and submit.",+ },+ )+ evidence = {+ "inspected_url": "https://example.com/lookup",+ "current_url": "https://example.com/lookup",+ "forms": [],+ "navigation_targets": [],+ "result_containers": [],+ "source_tool": "inspect_page_for_composition",+ }+ ctx = _Ctx(composition_page_evidence=evidence)+ ctx.workflow_yaml = existing_yaml++ error = composition_page_evidence_error(ctx, workflow_yaml)++ assert error is not None+ assert "observed page evidence" in error++def test_composition_gate_allows_extraction_added_with_new_page_changing_block() -> None:existing_yaml = _yaml({"block_type": "goto_url", "label": "open_lookup", "url": "https://example.com/lookup"},@@ -809,7 +875,7 @@ def test_composition_gate_targets_nearest_url_before_new_page_block() -> None:evidence = {"inspected_url": "https://example.com/registry/search","current_url": "https://example.com/registry/search",- "forms": [],+ "forms": [{"fields": [{"name": "first_name", "selector": "#first_name"}], "submit_controls": []}],"source_tool": "inspect_page_for_composition",}ctx = _Ctx(composition_page_evidence=evidence)@@ -961,3 +1027,123 @@ def test_composition_gate_allows_separate_form_state_and_submit_blocks_from_one_error = composition_page_evidence_error(_Ctx(composition_page_evidence=_first_last_evidence()), workflow_yaml)assert error is None+++# ---------------- SKY-10562: block-type-agnostic, per-acted-page, multi-page gate ----------------+++def test_composition_gate_gates_non_entrypoint_goto_url_block() -> None:+ # A goto_url past the entrypoint acts on its own page and must be observed —+ # closing the goto_url block-type escape.+ workflow_yaml = _yaml(+ {"block_type": "goto_url", "label": "open_home", "url": "https://example.com/"},+ {"block_type": "goto_url", "label": "open_cart", "url": "https://example.com/cart"},+ {"block_type": "validation", "label": "confirm_item", "complete_criterion": "An item is in the cart."},+ )++ error = composition_page_evidence_error(_Ctx(), workflow_yaml)+ assert error is not None+ assert "open_cart (goto_url)" in error++ ctx = _Ctx(flow_evidence=[_flow_entry("https://example.com/cart")])+ assert composition_page_evidence_error(ctx, workflow_yaml) is None+++def test_composition_gate_entrypoint_goto_url_stays_ungated() -> None:+ # The first goto_url is the scaffold the agent scouts from — never gated.+ workflow_yaml = _yaml({"block_type": "goto_url", "label": "open_home", "url": "https://example.com/"})+ assert composition_page_evidence_error(_Ctx(), workflow_yaml) is None+++def test_composition_gate_pure_code_block_is_ungated() -> None:+ workflow_yaml = _yaml(+ {"block_type": "goto_url", "label": "open_home", "url": "https://example.com/"},+ {"block_type": "code", "label": "transform", "code": "result = 1 + 1"},+ )+ assert composition_page_evidence_error(_Ctx(), workflow_yaml) is None+++def test_composition_gate_multi_page_flow_evidence_grounds_each_acted_page() -> None:+ # Two acted pages (login then a goto_url to /secure); the single-slot evidence+ # could only hold one, but the flow trajectory covers both.+ workflow_yaml = _yaml(+ {"block_type": "goto_url", "label": "open_login", "url": "https://example.com/login"},+ {"block_type": "login", "label": "do_login", "navigation_goal": "Log in with the saved credential."},+ {"block_type": "goto_url", "label": "open_secure", "url": "https://example.com/secure"},+ {"block_type": "validation", "label": "confirm_secure", "complete_criterion": "Secure area is shown."},+ )+ only_login = _Ctx(flow_evidence=[_flow_entry("https://example.com/login")])+ error = composition_page_evidence_error(only_login, workflow_yaml)+ assert error is not None+ assert "open_secure (goto_url)" in error++ both = _Ctx(+ flow_evidence=[+ _flow_entry("https://example.com/login"),+ _flow_entry("https://example.com/secure", reached_via="post_run"),+ ]+ )+ assert composition_page_evidence_error(both, workflow_yaml) is None+++def test_composition_gate_regates_changed_block_url() -> None:+ previous = _yaml(+ {"block_type": "goto_url", "label": "open_home", "url": "https://example.com/"},+ {"block_type": "navigation", "label": "open_page", "url": "https://example.com/old", "navigation_goal": "go"},+ )+ workflow_yaml = _yaml(+ {"block_type": "goto_url", "label": "open_home", "url": "https://example.com/"},+ {"block_type": "navigation", "label": "open_page", "url": "https://example.com/new", "navigation_goal": "go"},+ )+ ctx = _Ctx(flow_evidence=[_flow_entry("https://example.com/old")])+ ctx.workflow_yaml = previous+ error = composition_page_evidence_error(ctx, workflow_yaml)+ assert error is not None+ assert "open_page (navigation)" in error++ ctx_observed = _Ctx(flow_evidence=[_flow_entry("https://example.com/new")])+ ctx_observed.workflow_yaml = previous+ assert composition_page_evidence_error(ctx_observed, workflow_yaml) is None+++def test_composition_gate_credits_cross_turn_observed_page_summary() -> None:+ # A page observed on a prior turn (its inspection budget already spent) is+ # credited from the persisted summary so the gate does not deadlock.+ workflow_yaml = _yaml(+ {"block_type": "goto_url", "label": "open_lookup", "url": "https://example.com/lookup"},+ {"block_type": "navigation", "label": "search_lookup", "navigation_goal": "Fill and submit the form."},+ )+ ctx = _Ctx(+ prior_observed_acted_pages=[+ {"url": "https://example.com/lookup", "had_bounded_schema": True, "reached_via": "navigate"}+ ]+ )+ assert composition_page_evidence_error(ctx, workflow_yaml) is None+++def test_composition_gate_cross_turn_credit_requires_same_page_not_origin() -> None:+ # A page observed on a prior turn credits only the SAME page, never a sibling+ # on the same origin — otherwise the gate would author an unobserved page's+ # block from a same-origin observation.+ workflow_yaml = _yaml(+ {"block_type": "goto_url", "label": "open_home", "url": "https://example.com/"},+ {"block_type": "goto_url", "label": "open_admin", "url": "https://example.com/admin"},+ {"block_type": "validation", "label": "confirm_admin", "complete_criterion": "Admin panel is shown."},+ )+ sibling_only = _Ctx(+ prior_observed_acted_pages=[+ {"url": "https://example.com/lookup", "had_bounded_schema": True, "reached_via": "navigate"}+ ]+ )+ sibling_only.workflow_yaml = _yaml({"block_type": "goto_url", "label": "open_home", "url": "https://example.com/"})+ error = composition_page_evidence_error(sibling_only, workflow_yaml)+ assert error is not None+ assert "open_admin (goto_url)" in error++ exact = _Ctx(+ prior_observed_acted_pages=[+ {"url": "https://example.com/admin", "had_bounded_schema": True, "reached_via": "navigate"}+ ]+ )+ exact.workflow_yaml = _yaml({"block_type": "goto_url", "label": "open_home", "url": "https://example.com/"})+ assert composition_page_evidence_error(exact, workflow_yaml) is Nonediff --git a/tests/unit/test_copilot_discovery.py b/tests/unit/test_copilot_discovery.pyindex 083d02d73..370cdeecc 100644--- a/tests/unit/test_copilot_discovery.py+++ b/tests/unit/test_copilot_discovery.py@@ -293,3 +293,96 @@ async def test_inspect_current_page_uses_existing_browser_page(monkeypatch: pyteassert result["data"]["current_url"] == "https://www.example.com/results"assert result["data"]["workflow_run_id"] == "wr_123"assert result["data"]["observed_after_workflow_run"] is True+++class _SizeCappedHtmlStrippedFallbackServer:+ """Every page's get_html is dropped by the MCP size cap (a heavy DOM exceeds it).+ The stripped-body evaluate fallback recovers each page, so the resolver can still+ follow the intent anchor to the form and resolve an entrypoint instead of parsing+ empty pages and giving up."""++ def __init__(self) -> None:+ self.tools: list[str] = []+ self.urls: list[str] = []++ async def call_internal_tool(self, tool_name: str, arguments: dict[str, Any]) -> dict[str, Any]:+ self.tools.append(tool_name)+ if tool_name == "skyvern_navigate":+ self.urls.append(arguments["url"])+ return {"ok": True, "data": {"url": arguments["url"]}}+ if tool_name == "skyvern_get_html":+ assert arguments == {"selector": "body"}+ return {"ok": True, "data": {"size_capped": True}}+ if tool_name == "skyvern_evaluate":+ if self.urls[-1] == "https://www.example.com":+ stripped = "<body><a href='/registry'>Find a Certificant</a></body>"+ else:+ stripped = "<body><form><input name='firstName'><button>Search</button></form></body>"+ return {"ok": True, "data": {"result": stripped}}+ raise AssertionError(f"unexpected tool: {tool_name}")+++async def test_discovery_recovers_entrypoint_when_get_html_is_size_capped() -> None:+ server = _SizeCappedHtmlStrippedFallbackServer()++ result = await _discovery_walk(_Ctx(server), entry_url="https://www.example.com", intent_hint="find a member")++ assert result["ok"] is True+ assert result["data"]["candidate_url"] == "https://www.example.com/registry"+ assert result["data"]["candidate_form_fields"] == [+ {"label": "", "name": "firstName", "type": "input", "value_hint": ""}+ ]+ assert "skyvern_evaluate" in server.tools+++class _StrippedHtmlServer:+ """get_html is size-capped (dropped); the stripped-body evaluate returns a fixed body so+ the truncation flag can be exercised."""++ def __init__(self, stripped: str) -> None:+ self._stripped = stripped++ async def call_internal_tool(self, tool_name: str, arguments: dict[str, Any]) -> dict[str, Any]:+ if tool_name == "skyvern_navigate":+ return {"ok": True, "data": {"url": arguments["url"]}}+ if tool_name == "skyvern_get_html":+ return {"ok": True, "data": {"size_capped": True}}+ if tool_name == "skyvern_evaluate":+ return {"ok": True, "data": {"result": self._stripped}}+ raise AssertionError(f"unexpected tool: {tool_name}")+++async def test_composition_get_html_flags_truncation_when_stripped_body_hits_cap() -> None:+ from skyvern.forge.sdk.copilot.tools import _COMPOSITION_STRIPPED_HTML_MAX_CHARS, _composition_get_html++ at_cap = "<body>" + "x" * _COMPOSITION_STRIPPED_HTML_MAX_CHARS+ _, error, truncated = await _composition_get_html(_Ctx(_StrippedHtmlServer(at_cap)))+ assert error is None+ assert truncated is True++ under_cap = "<body><form><input name='x'></form></body>"+ _, error, truncated = await _composition_get_html(_Ctx(_StrippedHtmlServer(under_cap)))+ assert error is None+ assert truncated is False+++async def test_capture_composition_evidence_warns_when_html_sliced_at_cap() -> None:+ from skyvern.forge.sdk.copilot.tools import _COMPOSITION_STRIPPED_HTML_MAX_CHARS, _capture_composition_evidence++ # A real form near the top yields bounded schema (no hollow-recapture loop); the trailing+ # padding pushes the stripped body past the cap so the fallback slice is detected as partial.+ body = (+ "<body><form><input name='firstName'><button>Search</button></form>"+ + "x" * _COMPOSITION_STRIPPED_HTML_MAX_CHARS+ )+ evidence, error = await _capture_composition_evidence(+ _Ctx(_StrippedHtmlServer(body)),+ inspected_url="https://www.example.com/search",+ current_url="https://www.example.com/search",+ )+ assert error is None+ assert evidence is not None+ assert "html_sliced_at_cap" in evidence["inspection_warnings"]diff --git a/tests/unit/test_copilot_enforcement_hardening.py b/tests/unit/test_copilot_enforcement_hardening.pyindex c819fb0e6..54b501417 100644--- a/tests/unit/test_copilot_enforcement_hardening.py+++ b/tests/unit/test_copilot_enforcement_hardening.py@@ -24,11 +24,16 @@ import pytestfrom skyvern.forge.sdk.copilot.context import CopilotContextfrom skyvern.forge.sdk.copilot.enforcement import (+ POST_FAILED_TEST_INSPECT_FIRST_NUDGE,+ POST_FAILED_TEST_NUDGE,POST_NAVIGATE_NUDGE,+ POST_PER_TOOL_BUDGET_NUDGE,+ POST_PER_TOOL_BUDGET_STOP_NUDGE,POST_SUSPICIOUS_SUCCESS_NUDGE,SCREENSHOT_PLACEHOLDER,_check_enforcement,_is_context_window_error,+ _needs_inspect_before_repair_nudge,_prune_input_list,_recover_from_context_overflow,_strip_input_images,@@ -69,6 +74,80 @@ def test_failed_test_nudge_counter_increments_on_fresh_context() -> None:assert ctx.failed_test_nudge_count == 1+def _repair_contract(next_action: Any, *, has_current_url: bool = True) -> Any:+ from skyvern.forge.sdk.copilot.diagnosis_repair_contract import (+ DiagnosisInput,+ DiagnosisRepairContract,+ DiagnosisResult,+ RepairDecision,+ VerificationResult,+ )++ return DiagnosisRepairContract(+ diagnosis_input=DiagnosisInput(+ source_tool="update_and_run_blocks",+ browser_page_state={"has_current_url": has_current_url},+ ),+ diagnosis_result=DiagnosisResult(),+ repair_decision=RepairDecision(next_action=next_action),+ verification_result=VerificationResult(),+ )+++def test_needs_inspect_before_repair_nudge_logic() -> None:+ from skyvern.forge.sdk.copilot.diagnosis_repair_contract import RepairNextAction++ ctx = _fresh_context()+ assert _needs_inspect_before_repair_nudge(ctx) is False # no contract+ ctx.latest_diagnosis_repair_contract = _repair_contract(RepairNextAction.REPAIR)+ assert _needs_inspect_before_repair_nudge(ctx) is True # repairable, reached page, unobserved+ ctx.latest_diagnosis_repair_contract = _repair_contract(RepairNextAction.NO_CHANGE)+ assert _needs_inspect_before_repair_nudge(ctx) is False # not a repair+ ctx.latest_diagnosis_repair_contract = _repair_contract(RepairNextAction.REPAIR, has_current_url=False)+ assert _needs_inspect_before_repair_nudge(ctx) is False # no reached page to inspect+++def test_failed_test_routes_to_inspect_first_when_repairable_and_unobserved() -> None:+ from skyvern.forge.sdk.copilot.diagnosis_repair_contract import RepairNextAction++ ctx = _fresh_context()+ ctx.test_after_update_done = True+ ctx.last_test_ok = False+ ctx.latest_diagnosis_repair_contract = _repair_contract(RepairNextAction.REPAIR)+ assert _check_enforcement(ctx) == POST_FAILED_TEST_INSPECT_FIRST_NUDGE+++def test_second_consecutive_per_tool_budget_trip_routes_to_stop_nudge() -> None:+ from skyvern.forge.sdk.copilot.failure_tracking import PER_TOOL_BUDGET_FAILURE_CATEGORY++ ctx = _fresh_context()+ ctx.test_after_update_done = True+ ctx.last_test_ok = False+ ctx.last_failure_category_top = PER_TOOL_BUDGET_FAILURE_CATEGORY+ # First budget trip earns one smaller-frontier retry nudge.+ assert _check_enforcement(ctx) == POST_PER_TOOL_BUDGET_NUDGE+ assert ctx.per_tool_budget_nudge_count == 1+ # Second consecutive budget trip -> finalize/STOP nudge, not another re-run.+ ctx.last_failure_category_top = PER_TOOL_BUDGET_FAILURE_CATEGORY+ assert _check_enforcement(ctx) == POST_PER_TOOL_BUDGET_STOP_NUDGE+ assert ctx.per_tool_budget_nudge_count == 2+++def test_failed_test_is_generic_once_reached_page_observed() -> None:+ from skyvern.forge.sdk.copilot.diagnosis_repair_contract import RepairNextAction++ ctx = _fresh_context()+ ctx.test_after_update_done = True+ ctx.last_test_ok = False+ ctx.latest_diagnosis_repair_contract = _repair_contract(RepairNextAction.REPAIR)+ # The agent already inspected the reached page since the failed run -> generic nudge.+ ctx.post_run_page_observation_after_failed_test = True+ ctx.post_run_page_observation_tool = "inspect_page_for_composition"+ ctx.post_run_page_observation_workflow_run_id = "wr_x"+ ctx.last_run_blocks_workflow_run_id = "wr_x"+ assert _check_enforcement(ctx) == POST_FAILED_TEST_NUDGE++# ---------------------------------------------------------------------------# B1 — tool-call argument compaction# ---------------------------------------------------------------------------diff --git a/tests/unit/test_copilot_hooks.py b/tests/unit/test_copilot_hooks.pyindex 13ed614e6..4d52e8400 100644--- a/tests/unit/test_copilot_hooks.py+++ b/tests/unit/test_copilot_hooks.py@@ -563,6 +563,48 @@ class TestNewToolOverlayConfigs:assert overlay.requires_browser is Trueassert overlay.post_hook is not None+ def test_click_and_type_overlays_steer_selector_first(self) -> None:+ # The tool contract must steer toward selector-only (deterministic) acting;+ # an `intent` routes the action through a slow full-page AI scan, so the+ # description must not invite "both" as the default (regression guard).+ from skyvern.forge.sdk.copilot.tools import _build_skyvern_mcp_overlays++ overlays = _build_skyvern_mcp_overlays()+ for name in ("click", "type_text"):+ desc = overlays[name].description or ""+ assert "selector ALONE" in desc, f"{name} should steer toward selector-only"+ assert "slower full-page AI scan" in desc, f"{name} should name the intent cost"+ assert "or both for resilient targeting" not in desc, f"{name} must not invite both by default"+ # intent must remain available for the genuine no-selector case+ assert "intent" not in overlays[name].hide_params++ def test_browser_action_overlays_force_direct_selector_mode(self) -> None:+ # The copilot keeps deterministic selector actions by binding selector_mode="direct"+ # via forced_args, even though the shared MCP default is resilient (SKY-10562).+ from skyvern.forge.sdk.copilot.tools import _build_skyvern_mcp_overlays++ overlays = _build_skyvern_mcp_overlays()+ for name in ("click", "type_text", "select_option"):+ assert overlays[name].forced_args.get("selector_mode") == "direct", (+ f"{name} overlay must force selector_mode=direct"+ )++ @pytest.mark.asyncio+ async def test_discovery_click_anchor_forces_direct_selector_mode(self) -> None:+ # call_internal_tool bypasses overlays, so the discovery path must pass selector_mode+ # explicitly; without it the anchor click would silently regress to the resilient default.+ from skyvern.forge.sdk.copilot.tools import _discovery_click_anchor++ call_internal_tool = AsyncMock(return_value={"ok": True})+ ctx = SimpleNamespace(discovery_mcp_server=SimpleNamespace(call_internal_tool=call_internal_tool))++ await _discovery_click_anchor(ctx, {"href": "https://example.com/cart"})++ call_internal_tool.assert_awaited_once()+ tool_name, tool_args = call_internal_tool.await_args.args+ assert tool_name == "skyvern_click"+ assert tool_args.get("selector_mode") == "direct"+class TestNewToolSummaries:"""Verify summarize_tool_result handles the 4 new tools."""@@ -600,3 +642,75 @@ class TestObservationToolsSet:expected = {"scroll", "console_messages", "select_option", "press_key"}assert expected.issubset(_OBSERVATION_TOOLS)+++class TestVerifyScoutTypeLanded:+ """A scout type that an overlay silently consumed must surface as a failure."""++ def _ctx_with_value(self, value: Any) -> SimpleNamespace:+ server = SimpleNamespace()+ server.call_internal_tool = AsyncMock(return_value={"ok": True, "data": {"value": value}})+ return SimpleNamespace(discovery_mcp_server=server)++ @pytest.mark.asyncio+ async def test_empty_field_after_nonempty_type_returns_failure(self) -> None:+ from skyvern.forge.sdk.copilot.tools import _verify_scout_type_landed++ ctx = self._ctx_with_value("")+ result = await _verify_scout_type_landed(ctx, selector="#search-input", typed_length=12)++ assert result is not None+ assert result["ok"] is False+ assert "still empty" in result["error"]+ # an empty read settles and re-reads once before declaring the type lost+ assert ctx.discovery_mcp_server.call_internal_tool.await_count == 2+ ctx.discovery_mcp_server.call_internal_tool.assert_awaited_with(+ "skyvern_get_value", {"selector": "#search-input"}+ )++ @pytest.mark.asyncio+ async def test_empty_then_filled_on_reread_passes(self) -> None:+ from skyvern.forge.sdk.copilot.tools import _verify_scout_type_landed++ server = SimpleNamespace()+ server.call_internal_tool = AsyncMock(+ side_effect=[+ {"ok": True, "data": {"value": ""}},+ {"ok": True, "data": {"value": "hello world"}},+ ]+ )+ ctx = SimpleNamespace(discovery_mcp_server=server)++ result = await _verify_scout_type_landed(ctx, selector="#search-input", typed_length=12)++ assert result is None+ assert server.call_internal_tool.await_count == 2++ @pytest.mark.asyncio+ async def test_nonempty_field_passes(self) -> None:+ from skyvern.forge.sdk.copilot.tools import _verify_scout_type_landed++ ctx = self._ctx_with_value("hello world")+ result = await _verify_scout_type_landed(ctx, selector="#search-input", typed_length=12)++ assert result is None++ @pytest.mark.asyncio+ async def test_no_selector_skips_readback(self) -> None:+ from skyvern.forge.sdk.copilot.tools import _verify_scout_type_landed++ ctx = self._ctx_with_value("")+ result = await _verify_scout_type_landed(ctx, selector="", typed_length=12)++ assert result is None+ ctx.discovery_mcp_server.call_internal_tool.assert_not_awaited()++ @pytest.mark.asyncio+ async def test_zero_typed_length_skips_readback(self) -> None:+ from skyvern.forge.sdk.copilot.tools import _verify_scout_type_landed++ ctx = self._ctx_with_value("")+ result = await _verify_scout_type_landed(ctx, selector="#search-input", typed_length=0)++ assert result is None+ ctx.discovery_mcp_server.call_internal_tool.assert_not_awaited()diff --git a/tests/unit/test_copilot_page_evidence_policy.py b/tests/unit/test_copilot_page_evidence_policy.pyindex 4b540b0c7..15459217d 100644--- a/tests/unit/test_copilot_page_evidence_policy.py+++ b/tests/unit/test_copilot_page_evidence_policy.py@@ -37,8 +37,9 @@ def test_agent_prompt_frames_inspection_as_build_time_context_not_workflow_shaperendered = _render_agent_prompt()assert "PAGE EVIDENCE POLICY" in rendered- assert "fill knowledge gaps while building, editing, or debugging a workflow" in rendered- assert "not to add defensive verification blocks for every website shape" in rendered+ assert "gather ground-truth evidence in ANY phase of building" in rendered+ assert "exploring, composing, editing, and repairing after a failed block run" in rendered+ assert "not adding defensive verification blocks for every website shape" in renderedassert "Do not invent website-specific paths, query parameters, form fields" in renderedassert ("Add `validation` blocks only when the reusable workflow's task actually includes a durable check" in rendereddiff --git a/tests/unit/test_mcp_browser_tools.py b/tests/unit/test_mcp_browser_tools.pyindex cfa9bf01e..0d74bd10c 100644--- a/tests/unit/test_mcp_browser_tools.py+++ b/tests/unit/test_mcp_browser_tools.py@@ -147,3 +147,194 @@ async def test_skyvern_run_task_timeout_returns_timeout_code(monkeypatch: pytestassert result["ok"] is Falseassert result["error"]["code"] == mcp_browser.ErrorCode.TIMEOUTassert "45" in result["error"]["message"]+++def _click_page(monkeypatch: pytest.MonkeyPatch) -> AsyncMock:+ click = AsyncMock(return_value="#resolved")+ page = SimpleNamespace(click=click)+ context = BrowserContext(mode="cloud_session", session_id="pbs_test")+ monkeypatch.setattr(mcp_browser, "get_page", AsyncMock(return_value=(page, context)))+ return click+++# 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.+async def test_skyvern_click_selector_is_resilient_by_default(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.get("mode") != "direct"+++async def test_skyvern_click_selector_mode_direct_is_deterministic(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["mode"] == "direct"+ assert "prompt" not in click.await_args.kwargs and "ai" not in click.await_args.kwargs+++async def test_skyvern_click_selector_plus_intent_falls_back_by_default(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.get("ai") == "fallback"+ assert click.await_args.kwargs.get("mode") != "direct"+++async def test_skyvern_click_selector_mode_direct_ignores_intent(monkeypatch: pytest.MonkeyPatch) -> None:+ click = _click_page(monkeypatch)++ result = await mcp_browser.skyvern_click(+ selector="#submit", intent="the blue submit button", selector_mode="direct"+ )++ assert result["ok"] is True+ assert click.await_args.kwargs["mode"] == "direct"+ assert "prompt" not in click.await_args.kwargs+++async def test_skyvern_click_intent_only_uses_proactive_ai(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["ai"] == "proactive"+ assert click.await_args.kwargs.get("mode") != "direct"+++def _action_page(monkeypatch: pytest.MonkeyPatch, **methods: AsyncMock) -> None:+ page = SimpleNamespace(**methods)+ context = BrowserContext(mode="cloud_session", session_id="pbs_test")+ monkeypatch.setattr(mcp_browser, "get_page", AsyncMock(return_value=(page, context)))+++async def test_skyvern_type_selector_is_resilient_by_default(monkeypatch: pytest.MonkeyPatch) -> None:+ fill = AsyncMock(return_value="Noor")+ _action_page(monkeypatch, fill=fill)++ result = await mcp_browser.skyvern_type(selector="#first_name", text="Noor")++ assert result["ok"] is True+ assert fill.await_args.kwargs.get("mode") != "direct"+++async def test_skyvern_type_selector_mode_direct_is_deterministic(monkeypatch: pytest.MonkeyPatch) -> None:+ fill = AsyncMock(return_value="Noor")+ _action_page(monkeypatch, fill=fill)++ result = await mcp_browser.skyvern_type(selector="#first_name", text="Noor", selector_mode="direct")++ assert result["ok"] is True+ assert fill.await_args.kwargs["mode"] == "direct"+ assert "prompt" not in fill.await_args.kwargs and "ai" not in fill.await_args.kwargs+++async def test_skyvern_type_selector_plus_intent_falls_back_by_default(monkeypatch: pytest.MonkeyPatch) -> None:+ fill = AsyncMock(return_value="Noor")+ _action_page(monkeypatch, fill=fill)++ result = await mcp_browser.skyvern_type(selector="#first_name", text="Noor", intent="the first name field")++ assert result["ok"] is True+ assert fill.await_args.kwargs.get("ai") == "fallback"+ assert fill.await_args.kwargs.get("mode") != "direct"+++async def test_skyvern_type_intent_only_uses_proactive_ai(monkeypatch: pytest.MonkeyPatch) -> None:+ fill = AsyncMock(return_value="Noor")+ _action_page(monkeypatch, fill=fill)++ result = await mcp_browser.skyvern_type(intent="the first name field", text="Noor")++ assert result["ok"] is True+ assert fill.await_args.kwargs["ai"] == "proactive"+ assert fill.await_args.kwargs.get("mode") != "direct"+++async def test_skyvern_select_option_selector_is_resilient_by_default(monkeypatch: pytest.MonkeyPatch) -> None:+ select = AsyncMock(return_value="us")+ _action_page(monkeypatch, select_option=select)++ result = await mcp_browser.skyvern_select_option(selector="#country", value="us")++ assert result["ok"] is True+ assert "ai" not in select.await_args.kwargs+++async def test_skyvern_select_option_selector_mode_direct_is_deterministic(monkeypatch: pytest.MonkeyPatch) -> None:+ select = AsyncMock(return_value="us")+ _action_page(monkeypatch, select_option=select)++ result = await mcp_browser.skyvern_select_option(selector="#country", value="us", selector_mode="direct")++ assert result["ok"] is True+ assert select.await_args.kwargs["ai"] is None+++async def test_skyvern_select_option_intent_only_uses_proactive_ai(monkeypatch: pytest.MonkeyPatch) -> None:+ select = AsyncMock(return_value="us")+ _action_page(monkeypatch, select_option=select)++ result = await mcp_browser.skyvern_select_option(intent="the country dropdown", value="United States")++ assert result["ok"] is True+ assert select.await_args.kwargs["ai"] == "proactive"+++# A blank/whitespace selector (how MCP clients serialize an omitted optional arg) must be+# treated as "no selector" so it uses the intent's AI path, not a deterministic action on "".+async def test_skyvern_click_blank_selector_with_intent_uses_proactive_ai(monkeypatch: pytest.MonkeyPatch) -> None:+ click = _click_page(monkeypatch)++ result = await mcp_browser.skyvern_click(selector=" ", intent="the blue submit button")++ assert result["ok"] is True+ assert click.await_args.kwargs["ai"] == "proactive"+ assert click.await_args.kwargs.get("mode") != "direct"+++async def test_skyvern_type_blank_selector_with_intent_uses_proactive_ai(monkeypatch: pytest.MonkeyPatch) -> None:+ fill = AsyncMock(return_value="Noor")+ _action_page(monkeypatch, fill=fill)++ result = await mcp_browser.skyvern_type(selector="", text="Noor", intent="the first name field")++ assert result["ok"] is True+ assert fill.await_args.kwargs["ai"] == "proactive"+ assert fill.await_args.kwargs.get("mode") != "direct"+++async def test_skyvern_select_option_blank_selector_with_intent_uses_proactive_ai(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ select = AsyncMock(return_value="us")+ _action_page(monkeypatch, select_option=select)++ result = await mcp_browser.skyvern_select_option(selector="", intent="the country dropdown", value="US")++ assert result["ok"] is True+ assert select.await_args.kwargs["ai"] == "proactive"