Automate browser based workflows with AI
Python aiapiautomationbrowserbrowser-automationcomputergptllmplaywrightpowerautomatepuppeteerpythonrpaseleniumvisionworkflow
Resolve Copilot bare-word entrypoints from verified evidence (#7624)
Andrew Neilsone1789f90856f
diff --git a/skyvern/forge/agent_functions.py b/skyvern/forge/agent_functions.pyindex 7297082c3..49e250c6c 100644--- a/skyvern/forge/agent_functions.py+++ b/skyvern/forge/agent_functions.py@@ -1,13 +1,15 @@+from __future__ import annotations+import asyncioimport copyimport hashlibimport osimport timefrom collections.abc import AsyncIterator-from contextlib import asynccontextmanager+from contextlib import AbstractAsyncContextManager, asynccontextmanagerfrom dataclasses import dataclass, fieldfrom datetime import datetime, timedelta, timezone-from typing import TYPE_CHECKING, Any, Dict, List, Literal+from typing import TYPE_CHECKING, Any, Literal, TypedDictimport aiohttpimport httpx@@ -59,6 +61,8 @@ from skyvern.webeye.utils.dom import SkyvernElementfrom skyvern.webeye.utils.page import SkyvernFrameif TYPE_CHECKING:+ from playwright.async_api import BrowserContext+from skyvern.forge.sdk.db.enums import WorkflowRunTriggerTypefrom skyvern.forge.sdk.workflow.context_manager import WorkflowRunContextfrom skyvern.forge.sdk.workflow.models.code_block_recorder import RecordingPage@@ -113,9 +117,30 @@ class TOTPVerificationResponse:@dataclass(frozen=True)-class CopilotAliasResolution:+class CopilotSiteOriginAssociation:+ requested_name: str+ entity_id: str+ entity_label: str+ official_site_url: str+ origin: str+ source: str+ provider_relation_type: str+ provider_relation_text: str+++class CopilotCandidateNetworkHop(TypedDict):+ url: str+ resource_type: str+ resolved_public_ips: list[str]+ connected_peer_ip: str+ enforcement_version: str+++@dataclass(frozen=True)+class CopilotEntrypointCandidate:url: str- kind: str = "canonical_alias"+ source_rank: int+ association: CopilotSiteOriginAssociation@dataclass(frozen=True)@@ -149,7 +174,7 @@ def _remove_rect(element: dict) -> None:del element["rect"]-def _should_css_shape_convert(element: Dict) -> bool:+def _should_css_shape_convert(element: dict) -> bool:if "id" not in element:return False@@ -342,7 +367,7 @@ async def _set_css_shape_cache()-def _remove_skyvern_attributes(element: Dict) -> Dict:+def _remove_skyvern_attributes(element: dict) -> dict:"""To get the original HTML element without skyvern attributes"""@@ -357,7 +382,7 @@ def _remove_skyvern_attributes(element: Dict) -> Dict:if key in USELESS_SHAPE_ATTRIBUTE:del element_copied["attributes"][key]- children: List[Dict] | None = element_copied.get("children", None)+ children: list[dict] | None = element_copied.get("children", None)if children is None:return element_copied@@ -389,7 +414,7 @@ def _mark_element_as_dropped(element: dict, *, hashed_key: str | None) -> None:async def _check_svg_eligibility(skyvern_frame: SkyvernFrame,- element: Dict,+ element: dict,task: Task | None = None,step: Step | None = None,always_drop: bool = False,@@ -435,7 +460,7 @@ async def _check_svg_eligibility(async def _convert_svg_to_string(- element: Dict,+ element: dict,task: Task | None = None,step: Step | None = None,) -> None:@@ -559,7 +584,7 @@ async def _convert_svg_to_string(async def _convert_css_shape_to_string(skyvern_frame: SkyvernFrame,- element: Dict,+ element: dict,task: Task | None = None,step: Step | None = None,) -> None:@@ -767,7 +792,7 @@ class AgentFunction:async def should_use_flex_llm_routing(self,*,- trigger_type: "WorkflowRunTriggerType | None",+ trigger_type: WorkflowRunTriggerType | None,organization: Organization,workflow_permanent_id: str,workflow_run_id: str,@@ -797,16 +822,16 @@ class AgentFunction:async def should_keep_code_mode_for_workflow_run(self,*,- workflow: "Workflow",- workflow_run: "WorkflowRun",+ workflow: Workflow,+ workflow_run: WorkflowRun,) -> bool:return Trueasync def should_upgrade_to_code_mode(self,*,- workflow: "Workflow",- workflow_run: "WorkflowRun",+ workflow: Workflow,+ workflow_run: WorkflowRun,) -> bool:return False@@ -830,7 +855,7 @@ class AgentFunction:*,workflow_run_id: str,workflow_run_block_id: str,- workflow_run_context: "WorkflowRunContext",+ workflow_run_context: WorkflowRunContext,organization_id: str | None,block_label: str | None,browser_session_id: str | None,@@ -869,10 +894,10 @@ class AgentFunction:workflow_run_block_id: str,organization_id: str | None,browser_session_id: str | None,- workflow_run_context: "WorkflowRunContext",+ workflow_run_context: WorkflowRunContext,parameter_values: dict[str, Any],credential_parameter_keys: set[str],- recording_page: "RecordingPage | None" = None,+ recording_page: RecordingPage | None = None,) -> CodeBlockEngineResult | None:"""Run a CodeBlock through the secure runner sidecar, or return None for legacy.@@ -891,7 +916,7 @@ class AgentFunction:"""Base no-op (copilot runs its block test inline); overridden per deployment."""return False- def resolve_copilot_dispatch_trigger_type(self) -> "WorkflowRunTriggerType | None":+ def resolve_copilot_dispatch_trigger_type(self) -> WorkflowRunTriggerType | None:"""Base no-op (no dispatch routing hint); overridden per deployment."""return None@@ -926,7 +951,7 @@ class AgentFunction:"""Fetch per-run analytics metadata. OSS builds have no sidecar table."""return None- async def is_block_scoped_workflow_run(self, workflow_run: "WorkflowRun") -> bool:+ async def is_block_scoped_workflow_run(self, workflow_run: WorkflowRun) -> bool:"""Return whether this workflow run was created for scoped block execution."""return workflow_run.debug_session_id is not None@@ -1338,7 +1363,7 @@ class AgentFunction:workflow_run_id: str | None = None,created_after: datetime | None = None,context: GmailOTPVerificationContext | None = None,- ) -> "OTPValue | None":+ ) -> OTPValue | None:"""Find an OTP in connected Gmail inboxes for a single polling window."""if "@" not in totp_identifier:return None@@ -1792,13 +1817,36 @@ class AgentFunction:"""return ""- def resolve_copilot_entrypoint_alias(+ async def acquire_copilot_entrypoint_candidates(self,*,- site_or_url: str,- normalized_alias: str,- ) -> CopilotAliasResolution | None:- return None+ site_name: str,+ ) -> list[CopilotEntrypointCandidate]:+ del site_name+ return []++ def copilot_candidate_network_guard(+ self,+ browser_context: BrowserContext,+ *,+ expected_origin: str,+ ) -> AbstractAsyncContextManager[list[CopilotCandidateNetworkHop]]:+ return self._unavailable_copilot_candidate_network_guard(browser_context, expected_origin=expected_origin)++ @asynccontextmanager+ async def _unavailable_copilot_candidate_network_guard(+ self,+ browser_context: BrowserContext,+ *,+ expected_origin: str,+ ) -> AsyncIterator[list[CopilotCandidateNetworkHop]]:+ del browser_context, expected_origin+ raise RuntimeError("Copilot candidate pre-connect enforcement is unavailable")+ yield [] # pragma: no cover++ async def wait_for_copilot_candidate_network_idle(self, browser_context: BrowserContext) -> None:+ del browser_context+ raise RuntimeError("Copilot candidate pre-connect enforcement is unavailable")def get_copilot_config(self, code_block_mode: bool | None = None) -> CopilotConfig | None:"""Return an optional workflow copilot config override."""@@ -1990,7 +2038,7 @@ class AgentFunction:self,organization_id: str,workflow_id: str,- status: "WorkflowRunStatus | None" = None,+ status: WorkflowRunStatus | None = None,) -> None:"""Fired after a workflow run reaches a final status. Overrides must be best-effort and never raise."""return Nonediff --git a/skyvern/forge/prompts/skyvern/workflow-copilot-agent.j2 b/skyvern/forge/prompts/skyvern/workflow-copilot-agent.j2index b0391b3f2..63feed6aa 100644--- a/skyvern/forge/prompts/skyvern/workflow-copilot-agent.j2+++ b/skyvern/forge/prompts/skyvern/workflow-copilot-agent.j2@@ -204,9 +204,9 @@ PARAMETERIZED REQUESTS WITHOUT A SAMPLE VALUE:BUILD-TIME DISCOVERY:* If the latest user message names a website but not a specific URL, call `discover_workflow_entrypoint(site_or_url, intent_hint)` BEFORE writing any blocks. Direct browser tools and workflow-mutation tools are gated off until composition; calling them will return a steering error pointing back to discovery.-* `site_or_url` accepts: a URL with or without scheme (`example.com/login` is fine), a bare domain (`example.com`), or a single brand word (resolved as `https://www.<word>.com`). English phrases ("the X website") return `failure_reason=could_not_resolve_site_name` — `ASK_QUESTION` for a URL instead.+* `site_or_url` accepts: a URL with or without scheme (`example.com/login` is fine), a bare domain (`example.com`), or a single brand word. A brand word returns a candidate only after an exact provider-backed official-site association and guarded public-network HTTPS navigation to that associated origin; otherwise it returns `failure_reason=could_not_resolve_site_name`. English phrases ("the X website") also return that failure — `ASK_QUESTION` for a URL instead.* When discovery returns a `candidate_url`, USE IT — call `update_and_run_blocks` immediately with a `goto_url` block whose `url:` is that `candidate_url`. Do NOT `ASK_QUESTION` for confirmation the user already implied by naming the site; confirmation is appropriate only when discovery returned a `failure_reason`.-* Discovery returns `candidate_url`, `candidate_form_fields`, and an `evidence_trail`. Use `candidate_url` as the `url:` value on a `goto_url` block. Do NOT paste evidence verbatim into workflow YAML.+* Discovery v3 returns `contract_version=discover_workflow_entrypoint_v3`, `candidate_url`, `candidate_form_fields`, and an `evidence_trail`; evidence-backed brand candidates also return bounded association provenance, guarded-hop evidence, and final-origin binding. Use `candidate_url` as the `url:` value on a `goto_url` block. Do NOT paste evidence verbatim into workflow YAML.* Budget: one successful call per turn, three per chat, eight page hops, sixty seconds. On any `failure_reason` (`step_limit`, `no_candidate`, `could_not_resolve_site_name`, `login_wall`, `anti_bot_wall`, `discovery_budget_exhausted_for_chat`), `ASK_QUESTION` for a specific URL — do not propose a vendor of your own.* Discovery navigates and reads pages. It will NOT type, click form buttons, run JavaScript, or submit forms.diff --git a/skyvern/forge/sdk/copilot/mcp_adapter.py b/skyvern/forge/sdk/copilot/mcp_adapter.pyindex 37120c5dd..950e71a6c 100644--- a/skyvern/forge/sdk/copilot/mcp_adapter.py+++ b/skyvern/forge/sdk/copilot/mcp_adapter.py@@ -2,11 +2,14 @@from __future__ import annotations+import asyncioimport json-from contextlib import AsyncExitStack+from collections.abc import AsyncIterator+from contextlib import AsyncExitStack, asynccontextmanagerfrom copy import deepcopyfrom dataclasses import dataclass, fieldfrom typing import Any, Awaitable, Callable+from urllib.parse import urlparseimport structlogfrom agents.agent import AgentBase@@ -20,7 +23,10 @@ from mcp.types import (ListPromptsResult,TextContent,)+from playwright.async_api import Browser, BrowserContext+from skyvern.forge import app+from skyvern.forge.agent_functions import CopilotCandidateNetworkHopfrom skyvern.forge.sdk.copilot.blocker_signal import (build_loop_blocker_signal,loop_blocker_evidence_from_ctx,@@ -44,11 +50,13 @@ from skyvern.forge.sdk.copilot.runtime import (ensure_browser_session,mcp_browser_context,mcp_to_copilot,+ resolve_browser_state_for_context,)from skyvern.forge.sdk.copilot.screenshot_utils import enqueue_screenshot_from_resultfrom skyvern.forge.sdk.copilot.secret_scrub import scrub_secrets_from_structurefrom skyvern.forge.sdk.copilot.turn_halt import stash_turn_halt_from_blocker_signalfrom skyvern.forge.sdk.copilot.turn_ownership import emit_blocker_signal_payload+from skyvern.webeye.browser_state import BrowserStatePreHook = Callable[[dict[str, Any], AgentContext], Awaitable[dict[str, Any] | None]]PostHook = Callable[[dict[str, Any], dict[str, Any], AgentContext], Awaitable[dict[str, Any]]]@@ -214,6 +222,58 @@ def _copilot_to_call_tool_result(return CallToolResult(content=content, isError=is_error)+def _evidence_candidate_url_origin(url: str) -> str | None:+ try:+ parsed = urlparse(url)+ if parsed.scheme != "https" or not parsed.hostname or parsed.username or parsed.password:+ return None+ port = f":{parsed.port}" if parsed.port else ""+ except ValueError:+ return None+ return f"https://{parsed.hostname.lower()}{port}"+++@asynccontextmanager+async def _service_worker_blocked_context(+ browser_state: BrowserState,+ *,+ organization_id: str,+) -> AsyncIterator[BrowserContext]:+ original_context = browser_state.browser_context+ if original_context is None:+ raise RuntimeError("Evidence-candidate browser does not support an isolated context")+ original_page = await browser_state.get_working_page()+ browser = original_context.browser+ fallback_browser: Browser | None = None+ if browser is None:+ fallback_browser = await browser_state.pw.chromium.launch()+ browser = fallback_browser+ candidate_context: BrowserContext | None = None+ try:+ candidate_context = await browser.new_context(service_workers="block")+ await app.AGENT_FUNCTION.setup_browser_context_extensions(+ candidate_context,+ organization_id=organization_id,+ copilot_candidate_network_guard=True,+ )+ candidate_page = await candidate_context.new_page()+ browser_state.browser_context = candidate_context+ await browser_state.set_active_page(candidate_page)+ yield candidate_context+ finally:+ try:+ if candidate_context is not None:+ browser_state.browser_context = original_context+ if original_page is None:+ await browser_state.set_working_page(None)+ else:+ await browser_state.set_active_page(original_page)+ await candidate_context.close()+ finally:+ if fallback_browser is not None:+ await fallback_browser.close()++class SkyvernOverlayMCPServer(MCPServer):"""MCP server that wraps a FastMCP transport with schema overlays andcopilot-specific dispatch logic (loop detection, browser injection, hooks).@@ -237,6 +297,8 @@ class SkyvernOverlayMCPServer(MCPServer):self._client: Client | None = Noneself._exit_stack: AsyncExitStack | None = Noneself._cached_raw_tools: list[MCPTool] | None = None+ self._evidence_candidate_origin: str | None = None+ self._evidence_candidate_guarded_hops: list[CopilotCandidateNetworkHop] | None = None@propertydef name(self) -> str:@@ -257,6 +319,80 @@ class SkyvernOverlayMCPServer(MCPServer):self._exit_stack = Noneself._cached_raw_tools = None+ @asynccontextmanager+ async def evidence_candidate_navigation_guard(+ self,+ expected_origin: str,+ ) -> AsyncIterator[list[CopilotCandidateNetworkHop]]:+ if self._evidence_candidate_origin is not None:+ raise RuntimeError("Evidence-candidate navigation guard is already active")+ normalized_origin = _evidence_candidate_url_origin(expected_origin)+ if normalized_origin != expected_origin:+ raise ValueError("Evidence-candidate origin must be an exact HTTPS origin")+ ctx = self._context_provider()+ session_error = await ensure_browser_session(ctx)+ if session_error is not None:+ raise RuntimeError(str(session_error.get("error", "Evidence-candidate browser session unavailable")))+ try:+ browser_state = await resolve_browser_state_for_context(ctx)+ if browser_state is None:+ raise RuntimeError("Evidence-candidate navigation guard requires a browser context")+ async with _service_worker_blocked_context(+ browser_state,+ organization_id=ctx.organization_id,+ ) as browser_context:+ cookies = await browser_context.cookies()+ if (+ cookies+ or browser_context.service_workers+ or any(page.url not in {"", "about:blank"} for page in browser_context.pages)+ ):+ raise RuntimeError("Evidence-candidate navigation guard requires a pristine browser context")+ async with app.AGENT_FUNCTION.copilot_candidate_network_guard(+ browser_context, expected_origin=normalized_origin+ ) as guarded_hops:+ self._evidence_candidate_origin = normalized_origin+ self._evidence_candidate_guarded_hops = guarded_hops+ try:+ yield guarded_hops+ finally:+ await app.AGENT_FUNCTION.wait_for_copilot_candidate_network_idle(browser_context)+ finally:+ self._evidence_candidate_origin = None+ self._evidence_candidate_guarded_hops = None++ async def _drain_evidence_candidate_response_tasks(self) -> None:+ if self._evidence_candidate_origin is None:+ return+ browser_state = await resolve_browser_state_for_context(self._context_provider())+ browser_context = browser_state.browser_context if browser_state is not None else None+ if browser_context is None:+ raise RuntimeError("Evidence-candidate browser context became unavailable")+ await app.AGENT_FUNCTION.wait_for_copilot_candidate_network_idle(browser_context)++ async def evidence_candidate_browser_url(self) -> str:+ if self._evidence_candidate_origin is None:+ raise RuntimeError("Evidence-candidate navigation guard is not active")+ browser_state = await resolve_browser_state_for_context(self._context_provider())+ page = await browser_state.get_working_page() if browser_state is not None else None+ if page is None:+ raise RuntimeError("Evidence-candidate working page is unavailable")+ browser_url = page.url+ last_enforced_url = next(+ (+ hop["url"]+ for hop in reversed(self._evidence_candidate_guarded_hops or [])+ if hop["resource_type"] == "document"+ ),+ None,+ )+ if (+ _evidence_candidate_url_origin(browser_url) != self._evidence_candidate_origin+ or browser_url != last_enforced_url+ ):+ raise RuntimeError("candidate_browser_url_not_peer_verified")+ return browser_url+async def list_tools(self,run_context: RunContextWrapper[Any] | None = None,@@ -459,6 +595,9 @@ class SkyvernOverlayMCPServer(MCPServer):try:async with mcp_browser_context(ctx):raw = await self._client.call_tool(mcp_tool_name, merged_args, raise_on_error=False)+ if self._evidence_candidate_origin is not None:+ await asyncio.sleep(0)+ await self._drain_evidence_candidate_response_tasks()except Exception as exc:LOG.warning("Internal MCP tool call failed",diff --git a/skyvern/forge/sdk/copilot/tools/__init__.py b/skyvern/forge/sdk/copilot/tools/__init__.pyindex 3b750f9d3..790188961 100644--- a/skyvern/forge/sdk/copilot/tools/__init__.py+++ b/skyvern/forge/sdk/copilot/tools/__init__.py@@ -138,6 +138,7 @@ from .discovery import _discovery_detect_anti_bot as _discovery_detect_anti_botfrom .discovery import _discovery_detect_login_wall as _discovery_detect_login_wallfrom .discovery import _discovery_resolve_href as _discovery_resolve_hreffrom .discovery import _discovery_walk as _discovery_walk+from .discovery import _rank_discovery_entrypoint_candidates as _rank_discovery_entrypoint_candidatesfrom .discovery import _resolve_discovery_entry_url as _resolve_discovery_entry_urlfrom .frontier import _CANONICAL_WORKFLOW_SETTING_FIELDS as _CANONICAL_WORKFLOW_SETTING_FIELDSfrom .frontier import _JINJA_LITERAL_ROOTS as _JINJA_LITERAL_ROOTS@@ -874,14 +875,18 @@ async def discover_workflow_entrypoint_tool(Use this BEFORE writing blocks when the user named a website (with a URL,a bare domain, or a single brand word) but no specific page. Accepts:a URL with or without scheme (``example.com/login`` is fine), a bare- domain (``example.com``), or a single brand word. Configured aliases resolve- first; other single brand words resolve as ``https://www.<word>.com``.- English phrases ("the X website") return+ domain (``example.com``), or a single brand word. A brand word is resolved+ only from an exact provider-backed official-site association that safely+ navigates over public-network HTTPS to the associated origin. Results use+ ``contract_version=discover_workflow_entrypoint_v3``. English phrases+ ("the X website") return``failure_reason=could_not_resolve_site_name`` — ASK_QUESTION for a URL.Returns ``candidate_url`` plus a short ``evidence_trail`` and any- ``candidate_form_fields``. Use ``candidate_url`` as the ``url`` value- on a ``goto_url`` block. Do NOT paste the evidence into workflow YAML.+ ``candidate_form_fields``. Evidence-backed brand results also include+ bounded ``candidate_provenance`` and ``navigation_evidence``. Use+ ``candidate_url`` as the ``url`` value on a ``goto_url`` block. Do NOT+ paste the evidence into workflow YAML.Budget: one successful call per turn, three per chat, eight page hops,sixty seconds. On any ``failure_reason``, ASK_QUESTION for a URL — do notdiff --git a/skyvern/forge/sdk/copilot/tools/discovery.py b/skyvern/forge/sdk/copilot/tools/discovery.pyindex 4b610306c..8e85ba520 100644--- a/skyvern/forge/sdk/copilot/tools/discovery.py+++ b/skyvern/forge/sdk/copilot/tools/discovery.py@@ -4,8 +4,9 @@ import asyncioimport reimport timefrom collections.abc import Mapping+from contextlib import AsyncExitStackfrom typing import Any-from urllib.parse import urljoin, urlparse+from urllib.parse import urljoin, urlparse, urlsplit, urlunsplitimport structlogfrom opentelemetry import trace as otel_trace@@ -16,6 +17,7 @@ except ImportError: # pragma: no cover — bs4 is a transitive dep but discoverBeautifulSoup = None # type: ignore[assignment, misc]from skyvern.forge import app+from skyvern.forge.agent_functions import CopilotCandidateNetworkHop, CopilotEntrypointCandidatefrom skyvern.forge.sdk.copilot.build_phase import (BuildPhase,advance_to_composing,@@ -48,6 +50,7 @@ _DISCOVERY_EVIDENCE_TRAIL_MAX = 8_DISCOVERY_CANDIDATE_FORM_FIELDS_MAX = 10_DISCOVERY_HTML_BYTES_MAX = 200_000_DISCOVERY_CONCRETE_HOMEPAGE_CONFIDENCE = 0.6+_DISCOVERY_RESULT_CONTRACT_VERSION = "discover_workflow_entrypoint_v3"_DISCOVERY_URL_SCHEME_RE = re.compile(r"^https?://", re.IGNORECASE)# host + optional path/query/fragment — handles `example.com/login`,@@ -57,7 +60,6 @@ _DISCOVERY_DOMAIN_WITH_PATH_RE = re.compile(re.IGNORECASE,)_DISCOVERY_BARE_WORD_RE = re.compile(r"^[a-z0-9-]{2,32}$", re.IGNORECASE)-_DISCOVERY_ALIAS_SEPARATOR_RE = re.compile(r"[\s_-]+")_DISCOVERY_TOKEN_RE = re.compile(r"[a-z0-9]+", re.IGNORECASE)_DISCOVERY_CANDIDATE_EVIDENCE_STOPWORDS = frozenset({"a", "an", "and", "for", "in", "of", "on", "or", "the", "to"})_DISCOVERY_LOGIN_TITLE_RE = re.compile(r"\b(sign\s*in|log\s*in|login)\b", re.IGNORECASE)@@ -67,15 +69,28 @@ _DISCOVERY_PASSWORD_INPUT_RE = re.compile()-def _normalize_discovery_alias(site_or_url: str) -> str:- return _DISCOVERY_ALIAS_SEPARATOR_RE.sub("", site_or_url.strip().lower())+def _normalize_discovery_name(value: str) -> str:+ return "".join(_DISCOVERY_TOKEN_RE.findall(value.lower()))+++def _discovery_candidate_identity_bound(+ candidate: CopilotEntrypointCandidate,+ requested_name: str | None,+) -> bool:+ association = candidate.association+ normalized_names = {+ _normalize_discovery_name(value)+ for value in (requested_name or "", association.requested_name, association.provider_relation_text)+ }+ return "" not in normalized_names and len(normalized_names) == 1def _resolve_discovery_entry_url(site_or_url: str) -> tuple[str | None, str]:"""Resolve the user-supplied site name/URL into a navigable URL.- Returns ``(resolved_url, kind)`` where ``kind`` is one of:- ``url`` / ``domain`` / ``canonical_alias`` / ``word`` / ``unresolved``.+ Returns ``(resolved_url, kind)`` where ``kind`` is one of+ ``url`` / ``domain`` / ``bare_word`` / ``unresolved``. Bare words are+ classified here but acquired asynchronously by the AgentFunction boundary."""token = (site_or_url or "").strip()if not token:@@ -84,17 +99,48 @@ def _resolve_discovery_entry_url(site_or_url: str) -> tuple[str | None, str]:return token, "url"if _DISCOVERY_DOMAIN_WITH_PATH_RE.match(token):return f"https://{token}", "domain"- alias_resolution = app.AGENT_FUNCTION.resolve_copilot_entrypoint_alias(- site_or_url=token,- normalized_alias=_normalize_discovery_alias(token),- )- if alias_resolution:- return alias_resolution.url, alias_resolution.kindif _DISCOVERY_BARE_WORD_RE.match(token):- return f"https://www.{token.lower()}.com", "word"+ return None, "bare_word"return None, "unresolved"+def _discovery_origin(url: str) -> str | None:+ try:+ parsed = urlparse(url)+ except ValueError:+ return None+ if parsed.scheme != "https" or not parsed.hostname or parsed.username or parsed.password:+ return None+ port = f":{parsed.port}" if parsed.port else ""+ return f"https://{parsed.hostname.lower()}{port}"+++def _rank_discovery_entrypoint_candidates(+ requested_name: str,+ candidates: list[CopilotEntrypointCandidate],+) -> list[CopilotEntrypointCandidate]:+ admitted: list[CopilotEntrypointCandidate] = []+ seen_urls: set[str] = set()+ for candidate in candidates:+ association = candidate.association+ candidate_origin = _discovery_origin(candidate.url)+ official_origin = _discovery_origin(association.official_site_url)+ if (+ not requested_name.strip()+ or requested_name.strip().casefold() != association.requested_name.strip().casefold()+ or requested_name.strip().casefold() != association.provider_relation_text.strip().casefold()+ or candidate_origin is None+ or candidate_origin != official_origin+ or candidate_origin != association.origin+ or candidate.source_rank < 1+ or candidate.url in seen_urls+ ):+ continue+ seen_urls.add(candidate.url)+ admitted.append(candidate)+ return sorted(admitted, key=lambda candidate: (candidate.source_rank, candidate.url))++def _concrete_homepage_entrypoint(entry_url: str | None, kind: str) -> str | None:if kind not in {"domain", "url"} or not entry_url:return None@@ -160,6 +206,8 @@ def _discovery_build_result(evidence_trail: list[dict[str, Any]],confidence: float,failure_reason: str | None,+ candidate_provenance: dict[str, str | int] | None = None,+ navigation_evidence: dict[str, str | bool | list[str] | list[CopilotCandidateNetworkHop]] | None = None,ok: bool = True,error: str | None = None,) -> dict[str, Any]:@@ -172,17 +220,40 @@ def _discovery_build_result(``_request_policy_tool_error`` convention so the eval harness counts acontrolled failure as a successful tool call."""- return {- "ok": ok,- "data": {- "candidate_url": candidate_url,- "candidate_form_fields": candidate_form_fields[:_DISCOVERY_CANDIDATE_FORM_FIELDS_MAX],- "evidence_trail": evidence_trail[:_DISCOVERY_EVIDENCE_TRAIL_MAX],- "confidence": float(confidence),- "failure_reason": failure_reason,- },- "error": error,+ data: dict[str, Any] = {+ "candidate_url": candidate_url,+ "candidate_form_fields": candidate_form_fields[:_DISCOVERY_CANDIDATE_FORM_FIELDS_MAX],+ "evidence_trail": evidence_trail[:_DISCOVERY_EVIDENCE_TRAIL_MAX],+ "confidence": float(confidence),+ "failure_reason": failure_reason,}+ if candidate_provenance is not None:+ data["candidate_provenance"] = candidate_provenance+ if navigation_evidence is not None:+ data["navigation_evidence"] = navigation_evidence+ return {"ok": ok, "data": data, "error": error}+++def _redact_discovery_url_for_log(value: str | None) -> str | None:+ if not value:+ return None+ try:+ parsed = urlsplit(value)+ except ValueError:+ return None+ return urlunsplit((parsed.scheme, parsed.netloc, parsed.path, "", ""))+++def _redact_guarded_hops_for_log(+ value: list[dict[str, str | list[str]]] | None,+) -> list[dict[str, str | list[str] | None]] | None:+ if value is None:+ return None+ redacted: list[dict[str, str | list[str] | None]] = []+ for hop in value:+ hop_url = hop.get("url")+ redacted.append({**hop, "url": _redact_discovery_url_for_log(hop_url if isinstance(hop_url, str) else None)})+ return redacteddef _record_discovery_resolution_on_ctx(ctx: Any, result: Mapping[str, Any]) -> None:@@ -212,7 +283,10 @@ def _record_discovery_resolution_on_ctx(ctx: Any, result: Mapping[str, Any]) ->try:current_span = otel_trace.get_current_span()if ctx.resolved_discovery_entrypoint_url is not None:- current_span.set_attribute("copilot.discovery_candidate_url", ctx.resolved_discovery_entrypoint_url)+ current_span.set_attribute(+ "copilot.discovery_candidate_url",+ _redact_discovery_url_for_log(ctx.resolved_discovery_entrypoint_url),+ )if ctx.resolved_discovery_failure_reason is not None:current_span.set_attribute("copilot.discovery_failure_reason", ctx.resolved_discovery_failure_reason)except Exception:@@ -329,6 +403,14 @@ def _discovery_anchor_selector(anchor: dict[str, str]) -> str | None:return f'a[href="{href}"]'+def _discovery_extract_page_title(result: Mapping[str, Any]) -> str:+ data = result.get("data")+ if not isinstance(data, Mapping):+ return ""+ title = data.get("title")+ return title[:240] if isinstance(title, str) else ""++_DISCOVERY_NAVIGATION_FALLBACK_CONFIDENCE = 0.2# Scorer-miss outcomes (page loaded, no keyword match); wall outcomes are excluded as real blocks._DISCOVERY_SCORER_MISS_REASONS = frozenset({"no_candidate", "step_limit", "wall_clock_limit"})@@ -371,6 +453,9 @@ async def _discovery_walk(*,entry_url: str,intent_hint: str,+ entrypoint_candidate: CopilotEntrypointCandidate | None = None,+ requested_name: str | None = None,+ guarded_hops: list[CopilotCandidateNetworkHop] | None = None,) -> dict[str, Any]:"""Deterministic anchor-scoring walker. No inner LLM call.@@ -383,14 +468,44 @@ async def _discovery_walk(evidence_trail: list[dict[str, Any]] = []current_url = entry_urlcurrent_page_loaded = False+ current_page_title = ""retried_deep_link_from_origin = Falsestarted = ctx.discovery_started_monotonic or time.monotonic()+ candidate_provenance: dict[str, str | int] | None = None+ navigation_evidence: dict[str, str | bool | list[str] | list[CopilotCandidateNetworkHop]] | None = None+ if entrypoint_candidate is not None:+ candidate_provenance = {+ "source": entrypoint_candidate.association.source,+ "source_rank": entrypoint_candidate.source_rank,+ "entity_id": entrypoint_candidate.association.entity_id,+ "associated_origin": entrypoint_candidate.association.origin,+ "provider_relation_type": entrypoint_candidate.association.provider_relation_type,+ "provider_relation_text": entrypoint_candidate.association.provider_relation_text,+ }++ def build_result(+ *,+ candidate_url: str | None,+ candidate_form_fields: list[dict[str, Any]],+ evidence_trail: list[dict[str, Any]],+ confidence: float,+ failure_reason: str | None,+ ) -> dict[str, Any]:+ return _discovery_build_result(+ candidate_url=candidate_url,+ candidate_form_fields=candidate_form_fields,+ evidence_trail=evidence_trail,+ confidence=confidence,+ failure_reason=failure_reason,+ candidate_provenance=candidate_provenance,+ navigation_evidence=navigation_evidence,+ )for step in range(_DISCOVERY_STEP_CAP):ctx.discovery_step_count = step + 1elapsed = time.monotonic() - startedif elapsed > _DISCOVERY_WALL_CLOCK_SECONDS:- return _discovery_build_result(+ return build_result(candidate_url=None,candidate_form_fields=[],evidence_trail=evidence_trail,@@ -400,6 +515,8 @@ async def _discovery_walk(if current_page_loaded:current_page_loaded = False+ navigation_title = current_page_title+ current_page_title = ""else:nav_result = await _discovery_navigate(ctx, current_url)if not nav_result.get("ok"):@@ -410,25 +527,44 @@ async def _discovery_walk("transition_reason": f"navigate_failed: {nav_result.get('error', 'unknown')}"[:240],})- # A pre-composition browser/session failure is not evidence that- # the user omitted a page URL. Return the resolved entry URL so the- # agent can test a minimal goto_url block and gather real run/debug- # evidence before deciding whether to ask a follow-up.- return _discovery_build_result(- candidate_url=current_url,+ strict_candidate = entrypoint_candidate is not None+ return build_result(+ candidate_url=None if strict_candidate else current_url,candidate_form_fields=[],evidence_trail=evidence_trail,- confidence=_DISCOVERY_NAVIGATION_FALLBACK_CONFIDENCE,- failure_reason=None,+ confidence=0.0 if strict_candidate else _DISCOVERY_NAVIGATION_FALLBACK_CONFIDENCE,+ failure_reason="candidate_navigation_failed" if strict_candidate else None,)current_url = _discovery_extract_current_url(nav_result, current_url)+ navigation_title = _discovery_extract_page_title(nav_result)# 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)+ if entrypoint_candidate is not None:+ server = ctx.discovery_mcp_server+ if server is None:+ return build_result(+ candidate_url=None,+ candidate_form_fields=[],+ evidence_trail=evidence_trail,+ confidence=0.0,+ failure_reason="candidate_guard_unavailable",+ )+ try:+ current_url = await server.evidence_candidate_browser_url()+ except Exception:+ return build_result(+ candidate_url=None,+ candidate_form_fields=[],+ evidence_trail=evidence_trail,+ confidence=0.0,+ failure_reason="candidate_browser_url_unverified",+ )+ parsed_title, anchors, form_fields = _discovery_parse_html(html)+ page_title = parsed_title or navigation_titleevidence_trail.append({@@ -492,7 +628,7 @@ async def _discovery_walk(current_url = origin_urlretried_deep_link_from_origin = Truecontinue- return _discovery_build_result(+ return build_result(candidate_url=None,candidate_form_fields=[],evidence_trail=evidence_trail,@@ -500,7 +636,7 @@ async def _discovery_walk(failure_reason="anti_bot_wall",)if login_wall_detected:- return _discovery_build_result(+ return build_result(candidate_url=None,candidate_form_fields=[],evidence_trail=evidence_trail,@@ -508,9 +644,68 @@ async def _discovery_walk(failure_reason="login_wall",)+ if entrypoint_candidate is not None:+ final_origin = _discovery_origin(current_url)+ origin_bound = final_origin == entrypoint_candidate.association.origin+ last_enforced_hop = next(+ (hop for hop in reversed(guarded_hops or []) if hop["resource_type"] == "document"),+ None,+ )+ enforcement_bound = last_enforced_hop is not None and last_enforced_hop["url"] == current_url+ identity_bound = _discovery_candidate_identity_bound(entrypoint_candidate, requested_name)+ navigation_evidence = {+ "requested_name": requested_name or "",+ "final_url": current_url,+ "final_page_title": page_title[:240],+ "https": final_origin is not None,+ "tls_valid": final_origin is not None,+ "resolved_public_ips": list(last_enforced_hop["resolved_public_ips"]) if last_enforced_hop else [],+ "associated_origin": entrypoint_candidate.association.origin,+ "origin_bound": origin_bound,+ "enforcement_bound": enforcement_bound,+ "identity_bound": identity_bound,+ "guarded_hops": list(guarded_hops or [])[:_DISCOVERY_EVIDENCE_TRAIL_MAX],+ }+ evidence_trail[-1]["candidate_source"] = entrypoint_candidate.association.source+ evidence_trail[-1]["candidate_source_rank"] = entrypoint_candidate.source_rank+ evidence_trail[-1]["https"] = final_origin is not None+ evidence_trail[-1]["tls_valid"] = final_origin is not None+ evidence_trail[-1]["origin_bound"] = origin_bound+ if not enforcement_bound:+ return build_result(+ candidate_url=None,+ candidate_form_fields=[],+ evidence_trail=evidence_trail,+ confidence=0.0,+ failure_reason="candidate_final_url_unenforced",+ )+ if not origin_bound:+ return build_result(+ candidate_url=None,+ candidate_form_fields=[],+ evidence_trail=evidence_trail,+ confidence=0.0,+ failure_reason="candidate_origin_mismatch",+ )+ if not identity_bound:+ return build_result(+ candidate_url=None,+ candidate_form_fields=[],+ evidence_trail=evidence_trail,+ confidence=0.0,+ failure_reason="candidate_identity_mismatch",+ )+ return build_result(+ candidate_url=current_url,+ candidate_form_fields=form_fields,+ evidence_trail=evidence_trail,+ confidence=1.0,+ failure_reason=None,+ )+if intent_tokens and title_score >= 2 and (form_fields or best_score <= title_score):confidence = min(1.0, title_score / max(1, len(intent_tokens)))- return _discovery_build_result(+ return build_result(candidate_url=current_url,candidate_form_fields=form_fields,evidence_trail=evidence_trail,@@ -520,7 +715,7 @@ async def _discovery_walk(if form_fields and (title_score >= 1 or step > 0):confidence = 0.6 if title_score >= 1 else 0.4- return _discovery_build_result(+ return build_result(candidate_url=current_url,candidate_form_fields=form_fields,evidence_trail=evidence_trail,@@ -529,7 +724,7 @@ async def _discovery_walk()if not intent_tokens:- return _discovery_build_result(+ return build_result(candidate_url=current_url,candidate_form_fields=form_fields,evidence_trail=evidence_trail,@@ -538,7 +733,7 @@ async def _discovery_walk()if best_score == 0 or best_href is None:- return _discovery_build_result(+ return build_result(candidate_url=None,candidate_form_fields=[],evidence_trail=evidence_trail,@@ -550,6 +745,7 @@ async def _discovery_walk(click_result = await _discovery_click_anchor(ctx, best_anchor)if click_result.get("ok"):current_url = _discovery_extract_current_url(click_result, best_href)+ current_page_title = _discovery_extract_page_title(click_result)# The next loop should inspect the clicked page instead of# navigating back to the original entry URL.current_page_loaded = True@@ -564,7 +760,7 @@ async def _discovery_walk(current_url = best_href- return _discovery_build_result(+ return build_result(candidate_url=None,candidate_form_fields=[],evidence_trail=evidence_trail,@@ -583,21 +779,48 @@ async def _discover_workflow_entrypoint_impl(machinery."""arguments = {"site_or_url": site_or_url, "intent_hint": intent_hint}+ input_kind: str | None = Nonedef finish(result: dict[str, Any], *, site_or_url_kind: str | None = None) -> dict[str, Any]:_record_discovery_resolution_on_ctx(copilot_ctx, result)record_tool_step_result_for_ctx(copilot_ctx, "discover_workflow_entrypoint", arguments, result)data_payload = result.get("data")data = data_payload if isinstance(data_payload, Mapping) else {}+ if isinstance(data_payload, dict) and input_kind == "bare_word":+ data_payload.setdefault("contract_version", _DISCOVERY_RESULT_CONTRACT_VERSION)candidate_url = data.get("candidate_url")+ candidate_provenance = data.get("candidate_provenance")+ provenance = candidate_provenance if isinstance(candidate_provenance, Mapping) else {}+ navigation_payload = data.get("navigation_evidence")+ navigation_evidence = navigation_payload if isinstance(navigation_payload, Mapping) else {}failure_reason = data.get("failure_reason")if not isinstance(failure_reason, str) or not failure_reason:error = result.get("error")failure_reason = error if isinstance(error, str) and error else NoneLOG.info("discover_workflow_entrypoint completed",+ contract_version=data.get("contract_version"),ok=result.get("ok"),- candidate_url=candidate_url if isinstance(candidate_url, str) and candidate_url else None,+ candidate_url=_redact_discovery_url_for_log(candidate_url if isinstance(candidate_url, str) else None),+ candidate_source=provenance.get("source"),+ candidate_source_rank=provenance.get("source_rank"),+ candidate_entity_id=provenance.get("entity_id"),+ candidate_associated_origin=provenance.get("associated_origin"),+ candidate_provider_relation_type=provenance.get("provider_relation_type"),+ candidate_provider_relation_text=provenance.get("provider_relation_text"),+ candidate_final_url=_redact_discovery_url_for_log(+ navigation_evidence.get("final_url") if isinstance(navigation_evidence.get("final_url"), str) else None+ ),+ candidate_https=navigation_evidence.get("https"),+ candidate_tls_valid=navigation_evidence.get("tls_valid"),+ candidate_resolved_public_ips=navigation_evidence.get("resolved_public_ips"),+ candidate_guarded_hops=_redact_guarded_hops_for_log(+ navigation_evidence.get("guarded_hops")+ if isinstance(navigation_evidence.get("guarded_hops"), list)+ else None+ ),+ candidate_origin_bound=navigation_evidence.get("origin_bound"),+ candidate_enforcement_bound=navigation_evidence.get("enforcement_bound"),failure_reason=failure_reason,site_or_url_kind=site_or_url_kind,)@@ -630,6 +853,23 @@ async def _discover_workflow_entrypoint_impl(return finish(result)entry_url, kind = _resolve_discovery_entry_url(site_or_url)+ input_kind = kind+ entrypoint_candidate: CopilotEntrypointCandidate | None = None+ if kind == "bare_word":+ try:+ candidates = await app.AGENT_FUNCTION.acquire_copilot_entrypoint_candidates(+ site_name=site_or_url.strip(),+ )+ except Exception:+ LOG.exception("Copilot entrypoint candidate acquisition raised")+ candidates = []+ ranked_candidates = _rank_discovery_entrypoint_candidates(site_or_url, candidates)+ if ranked_candidates:+ entrypoint_candidate = ranked_candidates[0]+ entry_url = entrypoint_candidate.url+ kind = "evidence_candidate"+ else:+ kind = "unresolved"if entry_url is None:result = _discovery_build_result(candidate_url=None,@@ -690,11 +930,23 @@ async def _discover_workflow_entrypoint_impl(},):try:- result = await _discovery_walk(- copilot_ctx,- entry_url=entry_url,- intent_hint=intent_hint or "",- )+ async with AsyncExitStack() as guard_stack:+ guarded_hops: list[CopilotCandidateNetworkHop] = []+ if entrypoint_candidate is not None:+ server = copilot_ctx.discovery_mcp_server+ if server is None:+ raise RuntimeError("discovery MCP server not attached to context")+ guarded_hops = await guard_stack.enter_async_context(+ server.evidence_candidate_navigation_guard(entrypoint_candidate.association.origin)+ )+ result = await _discovery_walk(+ copilot_ctx,+ entry_url=entry_url,+ intent_hint=intent_hint or "",+ entrypoint_candidate=entrypoint_candidate,+ requested_name=site_or_url.strip() if entrypoint_candidate is not None else None,+ guarded_hops=guarded_hops,+ )except Exception as exc:LOG.exception("discover_workflow_entrypoint walker raised")result = {@@ -715,6 +967,7 @@ async def _discover_workflow_entrypoint_impl(copilot_ctx.discovery_evidence_trail = list(evidence_trail)if (result.get("ok")+ and entrypoint_candidate is Noneand not data.get("candidate_url")and data.get("failure_reason") in _DISCOVERY_SCORER_MISS_REASONS):@@ -727,6 +980,12 @@ async def _discover_workflow_entrypoint_impl(evidence_trail=evidence_trail,confidence=_DISCOVERY_NAVIGATION_FALLBACK_CONFIDENCE,failure_reason=None,+ candidate_provenance=(+ data.get("candidate_provenance") if isinstance(data.get("candidate_provenance"), dict) else None+ ),+ navigation_evidence=(+ data.get("navigation_evidence") if isinstance(data.get("navigation_evidence"), dict) else None+ ),)rebuilt_data = result.get("data")data = rebuilt_data if isinstance(rebuilt_data, dict) else {}diff --git a/tests/unit/test_copilot_candidate_navigation_guard.py b/tests/unit/test_copilot_candidate_navigation_guard.pynew file mode 100644index 000000000..1c3793c4a--- /dev/null+++ b/tests/unit/test_copilot_candidate_navigation_guard.py@@ -0,0 +1,556 @@+from __future__ import annotations++from contextlib import asynccontextmanager+from dataclasses import dataclass+from types import SimpleNamespace+from unittest.mock import AsyncMock++import pytest++from skyvern.forge.sdk.copilot import mcp_adapter+from skyvern.forge.sdk.copilot.mcp_adapter import SkyvernOverlayMCPServer+++class _Request:+ resource_type = "document"+ url = "https://public.test/start"++ class _Frame:+ parent_frame = None++ frame = _Frame()++ def is_navigation_request(self) -> bool:+ return True+++class _Route:+ def __init__(self) -> None:+ self.outcome = ""++ async def fallback(self) -> None:+ self.outcome = "fallback"++ async def abort(self, reason: str) -> None:+ self.outcome = reason+++class _BrowserContext:+ def __init__(self, browser: _Browser | None = None) -> None:+ self.handler = None+ self.unrouted = False+ self.pages = [SimpleNamespace(url="about:blank")]+ self.service_workers = []+ self.browser = browser or _Browser()+ self.closed = False++ async def route(self, _pattern: str, handler) -> None:+ self.handler = handler++ async def unroute(self, _pattern: str, handler) -> None:+ assert handler is self.handler+ self.unrouted = True++ async def cookies(self) -> list[dict[str, str]]:+ return []++ async def new_page(self) -> SimpleNamespace:+ page = SimpleNamespace(url="about:blank")+ self.pages.append(page)+ return page++ async def close(self) -> None:+ self.closed = True+++class _Browser:+ def __init__(self) -> None:+ self.new_context_kwargs: dict[str, str] | None = None+ self.candidate_context: _BrowserContext | None = None+ self.closed = False++ async def new_context(self, **kwargs: str) -> _BrowserContext:+ self.new_context_kwargs = kwargs+ self.candidate_context = _BrowserContext(self)+ return self.candidate_context++ async def close(self) -> None:+ self.closed = True+++class _Page:+ url = "https://public.test/start"+++@dataclass+class _BrowserState:+ browser_context: _BrowserContext+ page: SimpleNamespace | None = None+ pw: SimpleNamespace | None = None+ active_page: SimpleNamespace | None = None+ prefer_context_newest_when_unpinned: bool = False++ async def get_working_page(self) -> _Page | SimpleNamespace:+ if self.active_page is not None:+ if self.active_page in self.browser_context.pages:+ self.page = self.active_page+ return self.active_page+ self.active_page = None+ if self.prefer_context_newest_when_unpinned:+ self.page = self.browser_context.pages[-1]+ return self.page+ return self.page or _Page()++ async def set_working_page(self, page: _Page | SimpleNamespace | None) -> None:+ self.page = page++ async def set_active_page(self, page: SimpleNamespace) -> None:+ self.active_page = page+ self.page = page+++class _AgentFunction:+ def __init__(self) -> None:+ self.active = False+ self.idle_waits = 0++ @asynccontextmanager+ async def copilot_candidate_network_guard(self, _browser_context, *, expected_origin: str):+ assert expected_origin == "https://public.test"+ self.active = True+ hops = [+ {+ "url": "https://public.test/start",+ "resource_type": "document",+ "resolved_public_ips": ["93.184.216.34"],+ "connected_peer_ip": "93.184.216.34",+ "enforcement_version": "copilot_candidate_preconnect_v1",+ }+ ]+ try:+ yield hops+ finally:+ self.active = False++ async def wait_for_copilot_candidate_network_idle(self, _browser_context) -> None:+ self.idle_waits += 1++ async def setup_browser_context_extensions(self, _browser_context, **_kwargs) -> None:+ return None+++def _server() -> SkyvernOverlayMCPServer:+ return SkyvernOverlayMCPServer(+ None,+ {},+ {},+ frozenset(),+ lambda: SimpleNamespace(browser_session_id=None, organization_id="org"),+ )+++async def test_candidate_guard_uses_disposable_service_worker_blocked_context_for_attached_cdp(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ calls: list[str] = []+ browser_context = _BrowserContext()+ original_page = browser_context.pages[0]+ browser_state = _BrowserState(browser_context, page=original_page)++ ctx = SimpleNamespace(browser_session_id="inherited", organization_id="org")++ async def ensure(fresh_ctx):+ assert fresh_ctx.browser_session_id == "inherited"+ calls.append("ensure")+ return None++ async def resolve(_ctx):+ calls.append("resolve")+ return browser_state++ monkeypatch.setattr(mcp_adapter, "ensure_browser_session", ensure)+ monkeypatch.setattr(mcp_adapter, "resolve_browser_state_for_context", resolve)+ close_session = AsyncMock()+ monkeypatch.setattr(mcp_adapter.app, "AGENT_FUNCTION", _AgentFunction())+ monkeypatch.setattr(mcp_adapter.app, "PERSISTENT_SESSIONS_MANAGER", SimpleNamespace(close_session=close_session))++ server = _server()+ server._context_provider = lambda: ctx+ async with server.evidence_candidate_navigation_guard("https://public.test"):+ assert browser_state.browser_context is browser_context.browser.candidate_context+ assert browser_state.page is not original_page++ assert calls[:2] == ["ensure", "resolve"]+ assert ctx.browser_session_id == "inherited"+ assert browser_context.browser.new_context_kwargs == {"service_workers": "block"}+ assert browser_state.browser_context is browser_context+ assert browser_state.page is original_page+ assert browser_context.closed is False+ assert browser_context.browser.candidate_context is not None+ assert browser_context.browser.candidate_context.closed is True+ close_session.assert_not_awaited()+++async def test_candidate_guard_isolates_non_pristine_attached_cdp_context(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ browser_context = _BrowserContext()+ selected_page = SimpleNamespace(url="https://selected.test/")+ newest_page = SimpleNamespace(url="https://newest.test/")+ browser_context.pages = [selected_page, newest_page]+ browser_state = _BrowserState(+ browser_context,+ page=selected_page,+ active_page=selected_page,+ prefer_context_newest_when_unpinned=True,+ )++ async def ensure(_ctx):+ return None++ async def resolve(_ctx):+ return browser_state++ monkeypatch.setattr(mcp_adapter, "ensure_browser_session", ensure)+ monkeypatch.setattr(mcp_adapter, "resolve_browser_state_for_context", resolve)+ monkeypatch.setattr(mcp_adapter.app, "AGENT_FUNCTION", _AgentFunction())++ async with _server().evidence_candidate_navigation_guard("https://public.test"):+ assert browser_state.browser_context is browser_context.browser.candidate_context+ assert browser_state.page is not selected_page+ assert browser_state.page is not newest_page++ assert browser_context.browser.new_context_kwargs == {"service_workers": "block"}+ assert browser_context.browser.candidate_context is not None+ assert browser_context.browser.candidate_context.closed is True+ assert browser_state.browser_context is browser_context+ assert await browser_state.get_working_page() is selected_page+++async def test_candidate_guard_supports_persistent_context_without_browser(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ persistent_context = _BrowserContext()+ persistent_context.browser = None+ original_page = SimpleNamespace(url="https://persistent.test/account")+ fallback_browser = _Browser()+ chromium = SimpleNamespace(launch=AsyncMock(return_value=fallback_browser))+ browser_state = _BrowserState(+ persistent_context,+ page=original_page,+ pw=SimpleNamespace(chromium=chromium),+ )++ async def ensure(_ctx):+ return None++ async def resolve(_ctx):+ return browser_state++ monkeypatch.setattr(mcp_adapter, "ensure_browser_session", ensure)+ monkeypatch.setattr(mcp_adapter, "resolve_browser_state_for_context", resolve)+ monkeypatch.setattr(mcp_adapter.app, "AGENT_FUNCTION", _AgentFunction())++ async with _server().evidence_candidate_navigation_guard("https://public.test"):+ assert browser_state.browser_context is fallback_browser.candidate_context+ assert browser_state.page is not original_page++ chromium.launch.assert_awaited_once_with()+ assert fallback_browser.new_context_kwargs == {"service_workers": "block"}+ assert fallback_browser.closed is True+ assert persistent_context.closed is False+ assert browser_state.browser_context is persistent_context+ assert browser_state.page is original_page+++async def test_candidate_guard_closes_fallback_browser_when_context_creation_fails(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ persistent_context = _BrowserContext()+ persistent_context.browser = None+ fallback_browser = _Browser()+ fallback_browser.new_context = AsyncMock(side_effect=RuntimeError("context creation failed"))+ browser_state = _BrowserState(+ persistent_context,+ pw=SimpleNamespace(chromium=SimpleNamespace(launch=AsyncMock(return_value=fallback_browser))),+ )++ async def ensure(_ctx):+ return None++ async def resolve(_ctx):+ return browser_state++ monkeypatch.setattr(mcp_adapter, "ensure_browser_session", ensure)+ monkeypatch.setattr(mcp_adapter, "resolve_browser_state_for_context", resolve)+ monkeypatch.setattr(mcp_adapter.app, "AGENT_FUNCTION", _AgentFunction())++ with pytest.raises(RuntimeError, match="context creation failed"):+ async with _server().evidence_candidate_navigation_guard("https://public.test"):+ pass++ assert fallback_browser.closed is True+ assert browser_state.browser_context is persistent_context+++async def test_candidate_guard_closes_fallback_browser_when_candidate_context_cleanup_fails(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ persistent_context = _BrowserContext()+ persistent_context.browser = None+ candidate_context = _BrowserContext()+ candidate_context.close = AsyncMock(side_effect=RuntimeError("context close failed"))+ fallback_browser = _Browser()+ fallback_browser.new_context = AsyncMock(return_value=candidate_context)+ browser_state = _BrowserState(+ persistent_context,+ pw=SimpleNamespace(chromium=SimpleNamespace(launch=AsyncMock(return_value=fallback_browser))),+ )++ async def ensure(_ctx):+ return None++ async def resolve(_ctx):+ return browser_state++ monkeypatch.setattr(mcp_adapter, "ensure_browser_session", ensure)+ monkeypatch.setattr(mcp_adapter, "resolve_browser_state_for_context", resolve)+ monkeypatch.setattr(mcp_adapter.app, "AGENT_FUNCTION", _AgentFunction())++ with pytest.raises(RuntimeError, match="context close failed"):+ async with _server().evidence_candidate_navigation_guard("https://public.test"):+ pass++ assert fallback_browser.closed is True+ assert browser_state.browser_context is persistent_context+++async def test_candidate_guard_isolates_inherited_page_state(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ browser_context = _BrowserContext()+ browser_context.browser = None+ browser_context.pages = [SimpleNamespace(url="https://authenticated.test/account")]+ fallback_browser = _Browser()++ async def ensure(_ctx):+ return None++ original_page = SimpleNamespace(url="https://authenticated.test/account")+ browser_state = _BrowserState(+ browser_context,+ page=original_page,+ pw=SimpleNamespace(chromium=SimpleNamespace(launch=AsyncMock(return_value=fallback_browser))),+ )++ async def resolve(_ctx):+ return browser_state++ monkeypatch.setattr(mcp_adapter, "ensure_browser_session", ensure)+ monkeypatch.setattr(mcp_adapter, "resolve_browser_state_for_context", resolve)+ monkeypatch.setattr(mcp_adapter.app, "AGENT_FUNCTION", _AgentFunction())++ async with _server().evidence_candidate_navigation_guard("https://public.test"):+ assert browser_state.browser_context is not browser_context+ assert all(page.url in {"", "about:blank"} for page in browser_state.browser_context.pages)++ assert browser_state.browser_context is browser_context+ assert browser_state.page is original_page+ assert fallback_browser.new_context_kwargs == {"service_workers": "block"}+ assert fallback_browser.closed is True+++async def test_candidate_guard_uses_terminal_agent_function_route_without_overlay_sibling(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ browser_context = _BrowserContext()++ async def ensure(_ctx):+ return None++ async def resolve(_ctx):+ return _BrowserState(browser_context)++ monkeypatch.setattr(mcp_adapter, "ensure_browser_session", ensure)+ monkeypatch.setattr(mcp_adapter, "resolve_browser_state_for_context", resolve)+ monkeypatch.setattr(mcp_adapter.app, "AGENT_FUNCTION", _AgentFunction())++ agent_function = _AgentFunction()+ monkeypatch.setattr(mcp_adapter.app, "AGENT_FUNCTION", agent_function)++ async with _server().evidence_candidate_navigation_guard("https://public.test"):+ assert agent_function.active is True+ assert browser_context.handler is None++ assert agent_function.idle_waits == 1+++async def test_candidate_guard_clears_state_when_network_context_entry_fails(monkeypatch: pytest.MonkeyPatch) -> None:+ browser_context = _BrowserContext()+ server = _server()++ async def ensure(_ctx):+ return None++ async def resolve(_ctx):+ return _BrowserState(browser_context)++ class FailingAgentFunction(_AgentFunction):+ @asynccontextmanager+ async def copilot_candidate_network_guard(self, _browser_context, *, expected_origin: str):+ raise RuntimeError("entry failed")+ yield []++ monkeypatch.setattr(mcp_adapter, "ensure_browser_session", ensure)+ monkeypatch.setattr(mcp_adapter, "resolve_browser_state_for_context", resolve)+ monkeypatch.setattr(mcp_adapter.app, "AGENT_FUNCTION", FailingAgentFunction())++ with pytest.raises(RuntimeError, match="entry failed"):+ async with server.evidence_candidate_navigation_guard("https://public.test"):+ pass++ assert server._evidence_candidate_origin is None+ assert server._evidence_candidate_guarded_hops is None+++async def test_candidate_guard_clears_state_when_idle_wait_times_out(monkeypatch: pytest.MonkeyPatch) -> None:+ browser_context = _BrowserContext()+ server = _server()++ async def ensure(_ctx):+ return None++ async def resolve(_ctx):+ return _BrowserState(browser_context)++ agent_function = _AgentFunction()++ async def fail_idle(_browser_context) -> None:+ raise TimeoutError("idle timeout")++ agent_function.wait_for_copilot_candidate_network_idle = fail_idle+ monkeypatch.setattr(mcp_adapter, "ensure_browser_session", ensure)+ monkeypatch.setattr(mcp_adapter, "resolve_browser_state_for_context", resolve)+ monkeypatch.setattr(mcp_adapter.app, "AGENT_FUNCTION", agent_function)++ with pytest.raises(TimeoutError, match="idle timeout"):+ async with server.evidence_candidate_navigation_guard("https://public.test"):+ pass++ assert server._evidence_candidate_origin is None+ assert server._evidence_candidate_guarded_hops is None+++async def test_candidate_browser_url_uses_last_enforced_document_not_subresource(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ browser_context = _BrowserContext()+ server = _server()+ agent_function = _AgentFunction()++ async def ensure(_ctx):+ return None++ async def resolve(_ctx):+ return _BrowserState(browser_context)++ monkeypatch.setattr(mcp_adapter, "ensure_browser_session", ensure)+ monkeypatch.setattr(mcp_adapter, "resolve_browser_state_for_context", resolve)+ monkeypatch.setattr(mcp_adapter.app, "AGENT_FUNCTION", agent_function)++ async with server.evidence_candidate_navigation_guard("https://public.test") as hops:+ hops.append(+ {+ "url": "https://public.test/favicon.ico",+ "resource_type": "image",+ "resolved_public_ips": ["93.184.216.34"],+ "connected_peer_ip": "93.184.216.34",+ "enforcement_version": "copilot_candidate_preconnect_v1",+ }+ )+ assert await server.evidence_candidate_browser_url() == "https://public.test/start"+++async def test_candidate_browser_url_rejects_fragment_not_in_enforced_document(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ browser_context = _BrowserContext()+ server = _server()+ agent_function = _AgentFunction()++ async def ensure(_ctx):+ return None++ async def resolve(_ctx):+ return _BrowserState(browser_context, page=SimpleNamespace(url="https://public.test/start#after"))++ monkeypatch.setattr(mcp_adapter, "ensure_browser_session", ensure)+ monkeypatch.setattr(mcp_adapter, "resolve_browser_state_for_context", resolve)+ monkeypatch.setattr(mcp_adapter.app, "AGENT_FUNCTION", agent_function)++ async with server.evidence_candidate_navigation_guard("https://public.test"):+ with pytest.raises(RuntimeError, match="candidate_browser_url_not_peer_verified"):+ await server.evidence_candidate_browser_url()+++async def test_candidate_guard_rejects_non_exact_origin_before_activation(monkeypatch: pytest.MonkeyPatch) -> None:+ browser_context = _BrowserContext()++ async def ensure(_ctx):+ return None++ async def resolve(_ctx):+ return _BrowserState(browser_context)++ monkeypatch.setattr(mcp_adapter, "ensure_browser_session", ensure)+ monkeypatch.setattr(mcp_adapter, "resolve_browser_state_for_context", resolve)+ monkeypatch.setattr(mcp_adapter.app, "AGENT_FUNCTION", _AgentFunction())+ with pytest.raises(ValueError, match="exact HTTPS origin"):+ async with _server().evidence_candidate_navigation_guard("https://public.test/path"):+ pass+++async def test_real_adapter_internal_call_drains_candidate_network_before_return(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ browser_context = _BrowserContext()+ agent_function = _AgentFunction()+ server = _server()+ server._context_provider = lambda: SimpleNamespace(browser_session_id="session", organization_id="org")+ server._client = SimpleNamespace(+ call_tool=AsyncMock(return_value=SimpleNamespace(structured_content={"ok": True}, is_error=False, content=[]))+ )++ async def ensure(_ctx):+ return None++ async def resolve(_ctx):+ return _BrowserState(browser_context)++ @asynccontextmanager+ async def browser_scope(_ctx):+ yield++ monkeypatch.setattr(mcp_adapter, "ensure_browser_session", ensure)+ monkeypatch.setattr(mcp_adapter, "resolve_browser_state_for_context", resolve)+ monkeypatch.setattr(mcp_adapter, "mcp_browser_context", browser_scope)+ monkeypatch.setattr(mcp_adapter.app, "AGENT_FUNCTION", agent_function)++ async with server.evidence_candidate_navigation_guard("https://public.test"):+ result = await server.call_internal_tool("skyvern_navigate", {"url": "https://public.test/start"})++ assert result["ok"] is True+ assert agent_function.idle_waits == 2diff --git a/tests/unit/test_copilot_discovery.py b/tests/unit/test_copilot_discovery.pyindex d9270d8ad..4106f8208 100644--- a/tests/unit/test_copilot_discovery.py+++ b/tests/unit/test_copilot_discovery.py@@ -6,15 +6,16 @@ from typing import Anyimport pytest-from skyvern.forge.agent_functions import CopilotAliasResolution+from skyvern.forge.agent_functions import CopilotEntrypointCandidate, CopilotSiteOriginAssociationfrom skyvern.forge.sdk.copilot import tools as tools_modulefrom skyvern.forge.sdk.copilot.runtime import PendingBrowserInteractionObservationfrom skyvern.forge.sdk.copilot.tools import (_discovery_walk,_inspect_page_for_composition_impl,+ _rank_discovery_entrypoint_candidates,_resolve_discovery_entry_url,- discovery,)+from skyvern.forge.sdk.copilot.tools.discovery import _discovery_build_resultfrom skyvern.forge.sdk.copilot.turn_origin import TurnOriginfrom skyvern.forge.sdk.copilot.verification_evidence import WorkflowVerificationEvidence@@ -273,40 +274,22 @@ class _TargetThenCurrentPageServer:raise AssertionError(f"unexpected tool: {tool_name}")-class _AliasAgentFunction:- def __init__(self) -> None:- self.calls: list[tuple[str, str]] = []-- def resolve_copilot_entrypoint_alias(- self,- *,- site_or_url: str,- normalized_alias: str,- ) -> CopilotAliasResolution | None:- self.calls.append((site_or_url, normalized_alias))- if normalized_alias == "publicalias":- return CopilotAliasResolution(url="https://public-alias.test/start")- return None--@pytest.mark.parametrize(- "site_or_url",+ ("site_or_url", "expected"),[- "public-alias",- "public alias",- "PUBLIC_ALIAS",+ ("https://example.com/login", ("https://example.com/login", "url")),+ ("HTTP://example.com/login", ("HTTP://example.com/login", "url")),+ ("example.com", ("https://example.com", "domain")),+ ("example.com/login?x=y", ("https://example.com/login?x=y", "domain")),+ ("example", (None, "bare_word")),+ ("example search portal", (None, "unresolved")),],)-def test_resolve_discovery_entry_url_uses_configured_alias_hook(- monkeypatch: pytest.MonkeyPatch,+def test_resolve_discovery_entry_url_classifies_without_guessing(site_or_url: str,+ expected: tuple[str | None, str],) -> None:- monkeypatch.setattr(discovery.app, "AGENT_FUNCTION", _AliasAgentFunction())-- assert _resolve_discovery_entry_url(site_or_url) == (- "https://public-alias.test/start",- "canonical_alias",- )+ assert _resolve_discovery_entry_url(site_or_url) == expected@pytest.mark.parametrize(@@ -319,35 +302,114 @@ def test_resolve_discovery_entry_url_uses_configured_alias_hook(],)def test_resolve_discovery_entry_url_preserves_url_and_domain_inputs(- monkeypatch: pytest.MonkeyPatch,site_or_url: str,expected: tuple[str, str],) -> None:- agent_function = _AliasAgentFunction()- monkeypatch.setattr(discovery.app, "AGENT_FUNCTION", agent_function)-assert _resolve_discovery_entry_url(site_or_url) == expected- assert agent_function.calls == []-def test_resolve_discovery_entry_url_unknown_bare_word_still_falls_back_to_www(- monkeypatch: pytest.MonkeyPatch,-) -> None:- agent_function = _AliasAgentFunction()- monkeypatch.setattr(discovery.app, "AGENT_FUNCTION", agent_function)-- assert _resolve_discovery_entry_url("example") == ("https://www.example.com", "word")- assert agent_function.calls == [("example", "example")]+def test_legacy_url_domain_result_envelope_has_no_bare_word_contract_version() -> None:+ result = _discovery_build_result(+ candidate_url="https://example.com/",+ candidate_form_fields=[],+ evidence_trail=[],+ confidence=0.6,+ failure_reason=None,+ )+ assert result == {+ "ok": True,+ "data": {+ "candidate_url": "https://example.com/",+ "candidate_form_fields": [],+ "evidence_trail": [],+ "confidence": 0.6,+ "failure_reason": None,+ },+ "error": None,+ }+++def test_rank_discovery_entrypoint_candidates_accepts_provider_association_with_different_entity_label() -> None:+ candidates = [+ CopilotEntrypointCandidate(+ url="https://irrelevant.example/news",+ source_rank=1,+ association=CopilotSiteOriginAssociation(+ requested_name="public alias",+ entity_id="Q1",+ entity_label="Unrelated result",+ official_site_url="https://irrelevant.example/news",+ origin="https://irrelevant.example",+ source="provider_official_site",+ provider_relation_type="label",+ provider_relation_text="public alias",+ ),+ ),+ CopilotEntrypointCandidate(+ url="https://attacker.example/start",+ source_rank=2,+ association=CopilotSiteOriginAssociation(+ requested_name="public alias",+ entity_id="Q2",+ entity_label="Public Alias",+ official_site_url="https://public-alias.test/start",+ origin="https://public-alias.test",+ source="provider_official_site",+ provider_relation_type="alias",+ provider_relation_text="public alias",+ ),+ ),+ CopilotEntrypointCandidate(+ url="https://public-alias.test/start",+ source_rank=3,+ association=CopilotSiteOriginAssociation(+ requested_name="public alias",+ entity_id="Q3",+ entity_label="Public Alias",+ official_site_url="https://public-alias.test/start",+ origin="https://public-alias.test",+ source="provider_official_site",+ provider_relation_type="alias",+ provider_relation_text="public alias",+ ),+ ),+ ]-def test_resolve_discovery_entry_url_unknown_spaced_phrase_remains_unresolved(- monkeypatch: pytest.MonkeyPatch,-) -> None:- agent_function = _AliasAgentFunction()- monkeypatch.setattr(discovery.app, "AGENT_FUNCTION", agent_function)+ assert _rank_discovery_entrypoint_candidates("public alias", candidates) == [candidates[0], candidates[2]]+++def test_rank_discovery_entrypoint_candidates_keeps_unassociated_licensee_enforced() -> None:+ licensor = CopilotEntrypointCandidate(+ url="https://licensor.example/",+ source_rank=1,+ association=CopilotSiteOriginAssociation(+ requested_name="Public Alias",+ entity_id="Q1",+ entity_label="Public Alias",+ official_site_url="https://licensor.example/",+ origin="https://licensor.example",+ source="provider_official_site",+ provider_relation_type="label",+ provider_relation_text="Other Licensor",+ ),+ )+ licensee = CopilotEntrypointCandidate(+ url="https://licensee.example/",+ source_rank=2,+ association=CopilotSiteOriginAssociation(+ requested_name="Public Alias",+ entity_id="Q2",+ entity_label="Unrelated Licensee",+ official_site_url="https://licensee.example/",+ origin="https://licensee.example",+ source="provider_official_site",+ provider_relation_type="alias",+ provider_relation_text="Other Licensee",+ ),+ )- assert _resolve_discovery_entry_url("example search portal") == (None, "unresolved")- assert agent_function.calls == [("example search portal", "examplesearchportal")]+ assert _rank_discovery_entrypoint_candidates("public alias", [licensor, licensee]) == []@pytest.mark.asyncio