Automate browser based workflows with AI
Python aiapiautomationbrowserbrowser-automationcomputergptllmplaywrightpowerautomatepuppeteerpythonrpaseleniumvisionworkflow
Extract shared core from MCP tools, add CLI browser commands (#4768)
Marc Kelechava7c5be8fefe31
diff --git a/skyvern/cli/commands.py b/skyvern/cli/commands/__init__.pysimilarity index 60%rename from skyvern/cli/commands.pyrename to skyvern/cli/commands/__init__.pyindex cb9f1ca33..97ede4df0 100644--- a/skyvern/cli/commands.py+++ b/skyvern/cli/commands/__init__.py@@ -1,23 +1,51 @@+import logging+import typerfrom dotenv import load_dotenv+from skyvern.forge.sdk.forge_log import setup_logger as _setup_loggerfrom skyvern.utils.env_paths import resolve_backend_env_path-from .credentials import credentials_app-from .docs import docs_app-from .init_command import init_browser, init_env-from .quickstart import quickstart_app-from .run_commands import run_app-from .status import status_app-from .stop_commands import stop_app-from .tasks import tasks_app-from .workflow import workflow_app+from ..credentials import credentials_app+from ..docs import docs_app+from ..init_command import init_browser, init_env+from ..quickstart import quickstart_app+from ..run_commands import run_app+from ..status import status_app+from ..stop_commands import stop_app+from ..tasks import tasks_app+from ..workflow import workflow_app+from .browser import browser_app++_cli_logging_configured = False+++def configure_cli_logging() -> None:+ """Configure CLI log levels once at runtime (not at import time)."""+ global _cli_logging_configured+ if _cli_logging_configured:+ return+ _cli_logging_configured = True++ # Suppress noisy SDK/third-party logs for CLI execution only.+ for logger_name in ("skyvern", "httpx", "litellm", "playwright", "httpcore"):+ logging.getLogger(logger_name).setLevel(logging.WARNING)+ _setup_logger()+cli_app = typer.Typer(help=("""[bold]Skyvern CLI[/bold]\nManage and run your local Skyvern environment."""),no_args_is_help=True,rich_markup_mode="rich",)+++@cli_app.callback()+def cli_callback() -> None:+ """Configure CLI logging before command execution."""+ configure_cli_logging()++cli_app.add_typer(run_app,name="run",@@ -40,6 +68,9 @@ cli_app.add_typer(quickstart_app, name="quickstart", help="One-command setup and start for Skyvern (combines init and run).")+# Browser automation commands+cli_app.add_typer(browser_app, name="browser", help="Browser automation commands.")+@init_app.callback()def init_callback(diff --git a/skyvern/cli/commands/__main__.py b/skyvern/cli/commands/__main__.pynew file mode 100644index 000000000..3ab570f15--- /dev/null+++ b/skyvern/cli/commands/__main__.py@@ -0,0 +1,9 @@+from dotenv import load_dotenv++from skyvern.utils.env_paths import resolve_backend_env_path++from . import cli_app++if __name__ == "__main__": # pragma: no cover - manual CLI invocation+ load_dotenv(resolve_backend_env_path())+ cli_app()diff --git a/skyvern/cli/commands/_output.py b/skyvern/cli/commands/_output.pynew file mode 100644index 000000000..e99ccec94--- /dev/null+++ b/skyvern/cli/commands/_output.py@@ -0,0 +1,52 @@+from __future__ import annotations++import json+import sys+from typing import Any++from rich.console import Console+from rich.table import Table++console = Console()+++def output(+ data: Any,+ *,+ action: str = "",+ json_mode: bool = False,+) -> None:+ if json_mode:+ envelope: dict[str, Any] = {"ok": True, "action": action, "data": data, "error": None}+ json.dump(envelope, sys.stdout, indent=2, default=str)+ sys.stdout.write("\n")+ return+ if isinstance(data, list) and data and isinstance(data[0], dict):+ table = Table()+ for key in data[0]:+ table.add_column(key.replace("_", " ").title())+ for row in data:+ table.add_row(*[str(v) for v in row.values()])+ console.print(table)+ elif isinstance(data, dict):+ for key, value in data.items():+ console.print(f"[bold]{key}:[/bold] {value}")+ else:+ console.print(str(data))+++def output_error(message: str, *, hint: str = "", json_mode: bool = False, exit_code: int = 1) -> None:+ if json_mode:+ envelope: dict[str, Any] = {+ "ok": False,+ "action": "",+ "data": None,+ "error": {"message": message, "hint": hint},+ }+ json.dump(envelope, sys.stdout, indent=2, default=str)+ sys.stdout.write("\n")+ raise SystemExit(exit_code)+ console.print(f"[red]Error: {message}[/red]")+ if hint:+ console.print(f"[yellow]Hint: {hint}[/yellow]")+ raise SystemExit(exit_code)diff --git a/skyvern/cli/commands/_state.py b/skyvern/cli/commands/_state.pynew file mode 100644index 000000000..96482c85d--- /dev/null+++ b/skyvern/cli/commands/_state.py@@ -0,0 +1,48 @@+from __future__ import annotations++import json+from dataclasses import asdict, dataclass+from datetime import datetime, timezone+from pathlib import Path++STATE_DIR = Path.home() / ".skyvern"+STATE_FILE = STATE_DIR / "state.json"++_TTL_SECONDS = 86400 # 24 hours+++@dataclass+class CLIState:+ session_id: str | None = None+ cdp_url: str | None = None+ mode: str | None = None # "cloud", "local", or "cdp"+ created_at: str | None = None+++def save_state(state: CLIState) -> None:+ STATE_DIR.mkdir(parents=True, exist_ok=True)+ STATE_DIR.chmod(0o700)+ data = asdict(state)+ data["created_at"] = datetime.now(timezone.utc).isoformat()+ STATE_FILE.write_text(json.dumps(data))+ STATE_FILE.chmod(0o600)+++def load_state() -> CLIState | None:+ if not STATE_FILE.exists():+ return None+ try:+ data = json.loads(STATE_FILE.read_text())+ created_at = data.get("created_at")+ if created_at:+ age = (datetime.now(timezone.utc) - datetime.fromisoformat(created_at)).total_seconds()+ if age > _TTL_SECONDS:+ return None+ return CLIState(**{k: v for k, v in data.items() if k in CLIState.__dataclass_fields__})+ except Exception:+ return None+++def clear_state() -> None:+ if STATE_FILE.exists():+ STATE_FILE.unlink()diff --git a/skyvern/cli/commands/browser.py b/skyvern/cli/commands/browser.pynew file mode 100644index 000000000..1c66d59d5--- /dev/null+++ b/skyvern/cli/commands/browser.py@@ -0,0 +1,325 @@+from __future__ import annotations++import asyncio+from dataclasses import asdict, dataclass+from datetime import datetime, timezone+from pathlib import Path+from typing import Any, Literal++import typer++from skyvern.cli.commands._output import output, output_error+from skyvern.cli.commands._state import CLIState, clear_state, load_state, save_state+from skyvern.cli.core.artifacts import save_artifact+from skyvern.cli.core.browser_ops import do_act, do_extract, do_navigate, do_screenshot+from skyvern.cli.core.client import get_skyvern+from skyvern.cli.core.guards import GuardError, check_password_prompt, validate_wait_until+from skyvern.cli.core.session_ops import do_session_close, do_session_create, do_session_list++browser_app = typer.Typer(help="Browser automation commands.", no_args_is_help=True)+session_app = typer.Typer(help="Manage browser sessions.", no_args_is_help=True)+browser_app.add_typer(session_app, name="session")+++@dataclass(frozen=True)+class ConnectionTarget:+ mode: Literal["cloud", "cdp"]+ session_id: str | None = None+ cdp_url: str | None = None+++def _resolve_connection(session: str | None, cdp: str | None) -> ConnectionTarget:+ if session and cdp:+ raise typer.BadParameter("Pass only one of --session or --cdp.")++ if session:+ return ConnectionTarget(mode="cloud", session_id=session)+ if cdp:+ return ConnectionTarget(mode="cdp", cdp_url=cdp)++ state = load_state()+ if state:+ if state.mode == "cdp" and state.cdp_url:+ return ConnectionTarget(mode="cdp", cdp_url=state.cdp_url)+ if state.session_id:+ return ConnectionTarget(mode="cloud", session_id=state.session_id)+ if state.cdp_url:+ return ConnectionTarget(mode="cdp", cdp_url=state.cdp_url)++ raise typer.BadParameter(+ "No active browser connection. Create one with: skyvern browser session create\n"+ "Or connect with: skyvern browser session connect --cdp ws://...\n"+ "Or specify: --session pbs_... / --cdp ws://..."+ )+++async def _connect_browser(connection: ConnectionTarget) -> Any:+ skyvern = get_skyvern()+ if connection.mode == "cloud":+ if not connection.session_id:+ raise typer.BadParameter("Cloud mode requires --session or an active cloud session in state.")+ return await skyvern.connect_to_cloud_browser_session(connection.session_id)+ if not connection.cdp_url:+ raise typer.BadParameter("CDP mode requires --cdp or an active CDP URL in state.")+ return await skyvern.connect_to_browser_over_cdp(connection.cdp_url)+++# ---------------------------------------------------------------------------+# Session commands+# ---------------------------------------------------------------------------+++@session_app.command("create")+def session_create(+ timeout: int = typer.Option(60, help="Session timeout in minutes."),+ proxy: str | None = typer.Option(None, help="Proxy location (e.g. RESIDENTIAL)."),+ local: bool = typer.Option(False, "--local", help="Launch a local browser instead of cloud."),+ headless: bool = typer.Option(False, "--headless", help="Run local browser headless."),+ json_output: bool = typer.Option(False, "--json", help="Output as JSON."),+) -> None:+ """Create a new browser session."""+ if local:+ output_error(+ "Local browser sessions are not yet supported in CLI mode.",+ hint="Use MCP (skyvern run mcp) for local browser sessions, or omit --local for cloud sessions.",+ json_mode=json_output,+ )++ async def _run() -> dict:+ skyvern = get_skyvern()+ _browser, result = await do_session_create(+ skyvern,+ timeout=timeout,+ proxy_location=proxy,+ )+ save_state(CLIState(session_id=result.session_id, cdp_url=None, mode="cloud"))+ return {+ "session_id": result.session_id,+ "mode": "cloud",+ "timeout_minutes": result.timeout_minutes,+ }++ try:+ data = asyncio.run(_run())+ output(data, action="session_create", json_mode=json_output)+ except GuardError as e:+ output_error(str(e), hint=e.hint, json_mode=json_output)+ except typer.BadParameter:+ raise+ except Exception as e:+ output_error(str(e), hint="Check your API key and network connection.", json_mode=json_output)+++@session_app.command("close")+def session_close(+ session: str | None = typer.Option(None, help="Browser session ID to close."),+ cdp: str | None = typer.Option(None, "--cdp", help="CDP WebSocket URL to detach from."),+ json_output: bool = typer.Option(False, "--json", help="Output as JSON."),+) -> None:+ """Close a browser session."""++ async def _run() -> dict:+ connection = _resolve_connection(session, cdp)+ if connection.mode == "cdp":+ clear_state()+ return {"cdp_url": connection.cdp_url, "closed": False, "detached": True}++ if not connection.session_id:+ raise typer.BadParameter("Cloud mode requires a browser session ID.")++ skyvern = get_skyvern()+ result = await do_session_close(skyvern, connection.session_id)+ clear_state()+ return {"session_id": result.session_id, "closed": result.closed}++ try:+ data = asyncio.run(_run())+ output(data, action="session_close", json_mode=json_output)+ except typer.BadParameter:+ raise+ except Exception as e:+ output_error(str(e), hint="Verify the session ID or CDP URL is correct.", json_mode=json_output)+++@session_app.command("connect")+def session_connect(+ session: str | None = typer.Option(None, help="Cloud browser session ID."),+ cdp: str | None = typer.Option(None, "--cdp", help="CDP WebSocket URL."),+ json_output: bool = typer.Option(False, "--json", help="Output as JSON."),+) -> None:+ """Connect to an existing browser session (cloud or CDP) and persist it as active state."""+ if not session and not cdp:+ raise typer.BadParameter("Specify one of --session or --cdp.")++ async def _run() -> dict:+ connection = _resolve_connection(session, cdp)+ browser = await _connect_browser(connection)+ await browser.get_working_page()++ if connection.mode == "cdp":+ save_state(CLIState(session_id=None, cdp_url=connection.cdp_url, mode="cdp"))+ return {"connected": True, "mode": "cdp", "cdp_url": connection.cdp_url}++ save_state(CLIState(session_id=connection.session_id, cdp_url=None, mode="cloud"))+ return {"connected": True, "mode": "cloud", "session_id": connection.session_id}++ try:+ data = asyncio.run(_run())+ output(data, action="session_connect", json_mode=json_output)+ except typer.BadParameter:+ raise+ except Exception as e:+ output_error(str(e), hint="Verify the session ID or CDP URL is reachable.", json_mode=json_output)+++@session_app.command("list")+def session_list(+ json_output: bool = typer.Option(False, "--json", help="Output as JSON."),+) -> None:+ """List all browser sessions."""++ async def _run() -> list[dict]:+ skyvern = get_skyvern()+ sessions = await do_session_list(skyvern)+ return [asdict(s) for s in sessions]++ try:+ data = asyncio.run(_run())+ output(data, action="session_list", json_mode=json_output)+ except Exception as e:+ output_error(str(e), hint="Check your API key and network connection.", json_mode=json_output)+++# ---------------------------------------------------------------------------+# Browser commands+# ---------------------------------------------------------------------------+++@browser_app.command("navigate")+def navigate(+ url: str = typer.Option(..., help="URL to navigate to."),+ session: str | None = typer.Option(None, help="Browser session ID."),+ cdp: str | None = typer.Option(None, "--cdp", help="CDP WebSocket URL."),+ timeout: int = typer.Option(30000, help="Navigation timeout in milliseconds."),+ wait_until: str | None = typer.Option(None, help="Wait condition: load, domcontentloaded, networkidle, commit."),+ json_output: bool = typer.Option(False, "--json", help="Output as JSON."),+) -> None:+ """Navigate to a URL in the browser session."""++ async def _run() -> dict:+ validate_wait_until(wait_until)+ connection = _resolve_connection(session, cdp)+ browser = await _connect_browser(connection)+ page = await browser.get_working_page()+ result = await do_navigate(page, url, timeout=timeout, wait_until=wait_until)+ return {"url": result.url, "title": result.title}++ try:+ data = asyncio.run(_run())+ output(data, action="navigate", json_mode=json_output)+ except GuardError as e:+ output_error(str(e), hint=e.hint, json_mode=json_output)+ except typer.BadParameter:+ raise+ except Exception as e:+ output_error(str(e), hint="Check the URL is valid and the session is active.", json_mode=json_output)+++@browser_app.command("screenshot")+def screenshot(+ session: str | None = typer.Option(None, help="Browser session ID."),+ cdp: str | None = typer.Option(None, "--cdp", help="CDP WebSocket URL."),+ full_page: bool = typer.Option(False, "--full-page", help="Capture the full scrollable page."),+ selector: str | None = typer.Option(None, help="CSS selector to screenshot."),+ output_path: str | None = typer.Option(None, "--output", help="Custom output file path."),+ json_output: bool = typer.Option(False, "--json", help="Output as JSON."),+) -> None:+ """Take a screenshot of the current page."""++ async def _run() -> dict:+ connection = _resolve_connection(session, cdp)+ browser = await _connect_browser(connection)+ page = await browser.get_working_page()+ result = await do_screenshot(page, full_page=full_page, selector=selector)++ if output_path:+ path = Path(output_path)+ path.parent.mkdir(parents=True, exist_ok=True)+ path.write_bytes(result.data)+ return {"path": str(path), "bytes": len(result.data), "full_page": result.full_page}++ timestamp = datetime.now(timezone.utc).strftime("%Y%m%d_%H%M%S")+ artifact = save_artifact(+ content=result.data,+ kind="screenshot",+ filename=f"screenshot_{timestamp}.png",+ mime="image/png",+ session_id=connection.session_id,+ )+ return {"path": artifact.path, "bytes": artifact.bytes, "full_page": result.full_page}++ try:+ data = asyncio.run(_run())+ output(data, action="screenshot", json_mode=json_output)+ except GuardError as e:+ output_error(str(e), hint=e.hint, json_mode=json_output)+ except typer.BadParameter:+ raise+ except Exception as e:+ output_error(str(e), hint="Ensure the session is active and the page has loaded.", json_mode=json_output)+++@browser_app.command("act")+def act(+ prompt: str = typer.Option(..., help="Natural language action to perform."),+ session: str | None = typer.Option(None, help="Browser session ID."),+ cdp: str | None = typer.Option(None, "--cdp", help="CDP WebSocket URL."),+ json_output: bool = typer.Option(False, "--json", help="Output as JSON."),+) -> None:+ """Perform a natural language action on the current page."""++ async def _run() -> dict:+ check_password_prompt(prompt)+ connection = _resolve_connection(session, cdp)+ browser = await _connect_browser(connection)+ page = await browser.get_working_page()+ result = await do_act(page, prompt)+ return {"prompt": result.prompt, "completed": result.completed}++ try:+ data = asyncio.run(_run())+ output(data, action="act", json_mode=json_output)+ except GuardError as e:+ output_error(str(e), hint=e.hint, json_mode=json_output)+ except typer.BadParameter:+ raise+ except Exception as e:+ output_error(str(e), hint="Simplify the prompt or break into steps.", json_mode=json_output)+++@browser_app.command("extract")+def extract(+ prompt: str = typer.Option(..., help="What data to extract from the page."),+ session: str | None = typer.Option(None, help="Browser session ID."),+ cdp: str | None = typer.Option(None, "--cdp", help="CDP WebSocket URL."),+ schema: str | None = typer.Option(None, help="JSON schema for structured extraction."),+ json_output: bool = typer.Option(False, "--json", help="Output as JSON."),+) -> None:+ """Extract data from the current page using natural language."""++ async def _run() -> dict:+ connection = _resolve_connection(session, cdp)+ browser = await _connect_browser(connection)+ page = await browser.get_working_page()+ result = await do_extract(page, prompt, schema=schema)+ return {"prompt": prompt, "extracted": result.extracted}++ try:+ data = asyncio.run(_run())+ output(data, action="extract", json_mode=json_output)+ except GuardError as e:+ output_error(str(e), hint=e.hint, json_mode=json_output)+ except typer.BadParameter:+ raise+ except Exception as e:+ output_error(str(e), hint="Simplify the prompt or provide a JSON schema.", json_mode=json_output)diff --git a/skyvern/cli/core/browser_ops.py b/skyvern/cli/core/browser_ops.pynew file mode 100644index 000000000..e034bad5f--- /dev/null+++ b/skyvern/cli/core/browser_ops.py@@ -0,0 +1,87 @@+"""Shared browser operations for MCP tools and CLI commands.++Each function: validate inputs -> call SDK -> return typed result.+Session resolution and output formatting are caller responsibilities.+"""++from __future__ import annotations++import json+from dataclasses import dataclass+from typing import Any++from .guards import GuardError+++@dataclass+class NavigateResult:+ url: str+ title: str+++@dataclass+class ScreenshotResult:+ data: bytes+ full_page: bool = False+++@dataclass+class ActResult:+ prompt: str+ completed: bool = True+++@dataclass+class ExtractResult:+ extracted: Any = None+++def parse_extract_schema(schema: str | dict[str, Any] | None) -> dict[str, Any] | None:+ """Parse and validate an extraction schema payload."""+ if schema is None:+ return None+ if isinstance(schema, dict):+ return schema++ try:+ return json.loads(schema)+ except (json.JSONDecodeError, TypeError) as e:+ raise GuardError(f"Invalid JSON schema: {e}", "Provide schema as a valid JSON string")+++async def do_navigate(+ page: Any,+ url: str,+ timeout: int = 30000,+ wait_until: str | None = None,+) -> NavigateResult:+ await page.goto(url, timeout=timeout, wait_until=wait_until)+ return NavigateResult(url=page.url, title=await page.title())+++async def do_screenshot(+ page: Any,+ full_page: bool = False,+ selector: str | None = None,+) -> ScreenshotResult:+ if selector:+ element = page.locator(selector)+ data = await element.screenshot()+ else:+ data = await page.screenshot(full_page=full_page)+ return ScreenshotResult(data=data, full_page=full_page)+++async def do_act(page: Any, prompt: str) -> ActResult:+ await page.act(prompt)+ return ActResult(prompt=prompt, completed=True)+++async def do_extract(+ page: Any,+ prompt: str,+ schema: str | dict[str, Any] | None = None,+) -> ExtractResult:+ parsed_schema = parse_extract_schema(schema)+ extracted = await page.extract(prompt=prompt, schema=parsed_schema)+ return ExtractResult(extracted=extracted)diff --git a/skyvern/cli/core/guards.py b/skyvern/cli/core/guards.pynew file mode 100644index 000000000..773ab8ac2--- /dev/null+++ b/skyvern/cli/core/guards.py@@ -0,0 +1,81 @@+"""Shared input validation guards for both MCP and CLI surfaces."""++from __future__ import annotations++import re++PASSWORD_PATTERN = re.compile(+ r"\bpass(?:word|phrase|code)s?\b|\bsecret\b|\bcredential\b|\bpin\s*(?:code)?\b|\bpwd\b|\bpasswd\b",+ re.IGNORECASE,+)++JS_PASSWORD_PATTERN = re.compile(+ r"""(?:type\s*=\s*['"]?password|\.type\s*===?\s*['"]password|input\[type=password\]).*?\.value\s*=""",+ re.IGNORECASE,+)++CREDENTIAL_HINT = (+ "Use skyvern_login with a stored credential to authenticate. "+ "Create credentials via CLI: skyvern credentials add. "+ "Never pass passwords through tool calls."+)++VALID_WAIT_UNTIL = ("load", "domcontentloaded", "networkidle", "commit")+VALID_BUTTONS = ("left", "right", "middle")+VALID_ELEMENT_STATES = ("visible", "hidden", "attached", "detached")+++class GuardError(Exception):+ """Raised when an input guard blocks an operation."""++ def __init__(self, message: str, hint: str = "") -> None:+ super().__init__(message)+ self.hint = hint+++def check_password_prompt(text: str) -> None:+ """Block prompts containing password/credential terms."""+ if PASSWORD_PATTERN.search(text):+ raise GuardError(+ "Cannot perform password/credential actions — credentials must not be passed through tool calls",+ CREDENTIAL_HINT,+ )+++def check_js_password(expression: str) -> None:+ """Block JS expressions that set password field values."""+ if JS_PASSWORD_PATTERN.search(expression):+ raise GuardError(+ "Cannot set password field values via JavaScript — credentials must not be passed through tool calls",+ CREDENTIAL_HINT,+ )+++def validate_wait_until(value: str | None) -> None:+ if value is not None and value not in VALID_WAIT_UNTIL:+ raise GuardError(+ f"Invalid wait_until: {value}",+ "Use load, domcontentloaded, networkidle, or commit",+ )+++def validate_button(value: str | None) -> None:+ if value is not None and value not in VALID_BUTTONS:+ raise GuardError(f"Invalid button: {value}", "Use left, right, or middle")+++def resolve_ai_mode(+ selector: str | None,+ intent: str | None,+) -> tuple[str | None, str | None]:+ """Determine AI mode from selector/intent combination.++ Returns (ai_mode, error_code) -- if error_code is set, the call should fail.+ """+ if intent and not selector:+ return "proactive", None+ if intent and selector:+ return "fallback", None+ if selector and not intent:+ return None, None+ return None, "INVALID_INPUT"diff --git a/skyvern/cli/core/session_ops.py b/skyvern/cli/core/session_ops.pynew file mode 100644index 000000000..4e3014eb2--- /dev/null+++ b/skyvern/cli/core/session_ops.py@@ -0,0 +1,74 @@+"""Shared session operations for MCP tools and CLI commands."""++from __future__ import annotations++from dataclasses import dataclass+from typing import Any++from skyvern.schemas.runs import ProxyLocation+++@dataclass+class SessionCreateResult:+ session_id: str | None+ local: bool = False+ headless: bool = False+ timeout_minutes: int | None = None+++@dataclass+class SessionCloseResult:+ session_id: str | None+ closed: bool = True+++@dataclass+class SessionInfo:+ session_id: str+ status: str | None+ started_at: str | None+ timeout: int | None+ runnable_id: str | None = None+ available: bool = False+++async def do_session_create(+ skyvern: Any,+ timeout: int = 60,+ proxy_location: str | None = None,+ local: bool = False,+ headless: bool = False,+) -> tuple[Any, SessionCreateResult]:+ """Create browser session. Returns (browser, result)."""+ if local:+ browser = await skyvern.launch_local_browser(headless=headless)+ return browser, SessionCreateResult(session_id=None, local=True, headless=headless)++ proxy = ProxyLocation(proxy_location) if proxy_location else None+ browser = await skyvern.launch_cloud_browser(timeout=timeout, proxy_location=proxy)+ return browser, SessionCreateResult(+ session_id=browser.browser_session_id,+ timeout_minutes=timeout,+ )+++async def do_session_close(skyvern: Any, session_id: str) -> SessionCloseResult:+ """Close a browser session by ID."""+ await skyvern.close_browser_session(session_id)+ return SessionCloseResult(session_id=session_id)+++async def do_session_list(skyvern: Any) -> list[SessionInfo]:+ """List all browser sessions."""+ sessions = await skyvern.get_browser_sessions()+ return [+ SessionInfo(+ session_id=s.browser_session_id,+ status=s.status,+ started_at=s.started_at.isoformat() if s.started_at else None,+ timeout=s.timeout,+ runnable_id=s.runnable_id,+ available=s.runnable_id is None and s.browser_address is not None,+ )+ for s in sessions+ ]diff --git a/skyvern/cli/mcp_tools/browser.py b/skyvern/cli/mcp_tools/browser.pyindex 61ee5c33f..9c41b9994 100644--- a/skyvern/cli/mcp_tools/browser.py+++ b/skyvern/cli/mcp_tools/browser.py@@ -4,13 +4,24 @@ import asyncioimport base64import jsonimport logging-import refrom datetime import datetime, timezonefrom typing import Annotated, Anyfrom playwright.async_api import TimeoutError as PlaywrightTimeoutErrorfrom pydantic import Field+from skyvern.cli.core.browser_ops import do_act, do_extract, do_navigate, do_screenshot, parse_extract_schema+from skyvern.cli.core.guards import (+ CREDENTIAL_HINT,+ JS_PASSWORD_PATTERN,+ PASSWORD_PATTERN,+ GuardError,+ check_password_prompt,+)+from skyvern.cli.core.guards import resolve_ai_mode as _resolve_ai_mode+from skyvern.cli.core.guards import (+ validate_wait_until,+)from skyvern.schemas.run_blocks import CredentialTypefrom ._common import (@@ -24,39 +35,6 @@ from ._session import BrowserNotAvailableError, get_page, no_browser_errorLOG = logging.getLogger(__name__)-_PASSWORD_PATTERN = re.compile(- r"\bpass(?:word|phrase|code)s?\b|\bsecret\b|\bcredential\b|\bpin\s*(?:code)?\b|\bpwd\b|\bpasswd\b",- re.IGNORECASE,-)--_CREDENTIAL_ERROR_HINT = (- "Use skyvern_login with a stored credential to authenticate. "- "Create credentials via CLI: skyvern credentials add. "- "Never pass passwords through tool calls."-)--_JS_PASSWORD_PATTERN = re.compile(- r"""(?:type\s*=\s*['"]?password|\.type\s*===?\s*['"]password|input\[type=password\]).*?\.value\s*=""",- re.IGNORECASE,-)---def _resolve_ai_mode(- selector: str | None,- intent: str | None,-) -> tuple[str | None, str | None]:- """Determine AI mode from selector/intent combination.-- Returns (ai_mode, error_code) — if error_code is set, the call should fail.- """- if intent and not selector:- return "proactive", None- if intent and selector:- return "fallback", None- if selector and not intent:- return None, None- return None, "INVALID_INPUT"-async def skyvern_navigate(url: Annotated[str, "The URL to navigate to"],@@ -80,15 +58,13 @@ async def skyvern_navigate(Returns the final URL (after redirects) and page title.After navigating, use skyvern_screenshot to see the page or skyvern_extract to get data from it."""- if wait_until is not None and wait_until not in ("load", "domcontentloaded", "networkidle", "commit"):+ try:+ validate_wait_until(wait_until)+ except GuardError as e:return make_result("skyvern_navigate",ok=False,- error=make_error(- ErrorCode.INVALID_INPUT,- f"Invalid wait_until: {wait_until}",- "Use load, domcontentloaded, networkidle, or commit",- ),+ error=make_error(ErrorCode.INVALID_INPUT, str(e), e.hint),)try:@@ -98,10 +74,16 @@ async def skyvern_navigate(with Timer() as timer:try:- await page.goto(url, timeout=timeout, wait_until=wait_until)+ result = await do_navigate(page, url, timeout=timeout, wait_until=wait_until)timer.mark("sdk")- final_url = page.url- title = await page.title()+ except GuardError as e:+ return make_result(+ "skyvern_navigate",+ ok=False,+ browser_context=ctx,+ timing_ms=timer.timing_ms,+ error=make_error(ErrorCode.INVALID_INPUT, str(e), e.hint),+ )except Exception as e:return make_result("skyvern_navigate",@@ -114,7 +96,7 @@ async def skyvern_navigate(return make_result("skyvern_navigate",browser_context=ctx,- data={"url": final_url, "title": title, "sdk_equivalent": f'await page.goto("{url}")'},+ data={"url": result.url, "title": result.title, "sdk_equivalent": f'await page.goto("{url}")'},timing_ms=timer.timing_ms,)@@ -355,14 +337,14 @@ async def skyvern_type("""# Block password entry — redirect to skyvern_logintarget_text = f"{intent or ''} {selector or ''}"- if _PASSWORD_PATTERN.search(target_text):+ if PASSWORD_PATTERN.search(target_text):return make_result("skyvern_type",ok=False,error=make_error(ErrorCode.INVALID_INPUT,"Cannot type into password fields — credentials must not be passed through tool calls",- _CREDENTIAL_ERROR_HINT,+ CREDENTIAL_HINT,),)@@ -402,7 +384,7 @@ async def skyvern_type(error=make_error(ErrorCode.INVALID_INPUT,"Cannot type into password fields — credentials must not be passed through tool calls",- _CREDENTIAL_ERROR_HINT,+ CREDENTIAL_HINT,),)@@ -491,11 +473,7 @@ async def skyvern_screenshot(with Timer() as timer:try:- if selector:- element = page.locator(selector)- screenshot_bytes = await element.screenshot()- else:- screenshot_bytes = await page.screenshot(full_page=full_page)+ result = await do_screenshot(page, full_page=full_page, selector=selector)timer.mark("sdk")except Exception as e:return make_result(@@ -507,7 +485,7 @@ async def skyvern_screenshot()if inline:- data_b64 = base64.b64encode(screenshot_bytes).decode("utf-8")+ data_b64 = base64.b64encode(result.data).decode("utf-8")return make_result("skyvern_screenshot",browser_context=ctx,@@ -515,7 +493,7 @@ async def skyvern_screenshot("inline": True,"data": data_b64,"mime": "image/png",- "bytes": len(screenshot_bytes),+ "bytes": len(result.data),"sdk_equivalent": "await page.screenshot()",},timing_ms=timer.timing_ms,@@ -525,7 +503,7 @@ async def skyvern_screenshot(ts = datetime.now(timezone.utc).strftime("%H%M%S_%f")filename = f"screenshot_{ts}.png"artifact = save_artifact(- screenshot_bytes,+ result.data,kind="screenshot",filename=filename,mime="image/png",@@ -896,14 +874,14 @@ async def skyvern_evaluate(Security: This executes arbitrary JS in the page context. Only use with trusted expressions."""# Block JS that sets password field values- if _JS_PASSWORD_PATTERN.search(expression):+ if JS_PASSWORD_PATTERN.search(expression):return make_result("skyvern_evaluate",ok=False,error=make_error(ErrorCode.INVALID_INPUT,"Cannot set password field values via JavaScript — credentials must not be passed through tool calls",- _CREDENTIAL_ERROR_HINT,+ CREDENTIAL_HINT,),)@@ -947,20 +925,17 @@ async def skyvern_extract(For visual inspection instead of structured data, use skyvern_screenshot.Optionally provide a JSON `schema` to enforce the output structure (pass as a JSON string)."""- parsed_schema: dict[str, Any] | None = Noneif schema is not None:try:- parsed_schema = json.loads(schema)- except (json.JSONDecodeError, TypeError) as e:+ parsed_schema = parse_extract_schema(schema)+ except GuardError as e:return make_result("skyvern_extract",ok=False,- error=make_error(- ErrorCode.INVALID_INPUT,- f"Invalid JSON schema: {e}",- "Provide schema as a valid JSON string",- ),+ error=make_error(ErrorCode.INVALID_INPUT, str(e), e.hint),)+ else:+ parsed_schema = Nonetry:page, ctx = await get_page(session_id=session_id, cdp_url=cdp_url)@@ -969,8 +944,16 @@ async def skyvern_extract(with Timer() as timer:try:- extracted = await page.extract(prompt=prompt, schema=parsed_schema)+ result = await do_extract(page, prompt, schema=parsed_schema)timer.mark("sdk")+ except GuardError as e:+ return make_result(+ "skyvern_extract",+ ok=False,+ browser_context=ctx,+ timing_ms=timer.timing_ms,+ error=make_error(ErrorCode.INVALID_INPUT, str(e), e.hint),+ )except Exception as e:return make_result("skyvern_extract",@@ -983,7 +966,10 @@ async def skyvern_extract(return make_result("skyvern_extract",browser_context=ctx,- data={"extracted": extracted, "sdk_equivalent": f'await page.extract(prompt="{prompt}")'},+ data={+ "extracted": result.extracted,+ "sdk_equivalent": f'await page.extract(prompt="{prompt}")',+ },timing_ms=timer.timing_ms,)@@ -1037,16 +1023,13 @@ async def skyvern_act(For multi-step automations (4+ pages), use skyvern_workflow_create with one block per step.For quick one-off multi-page tasks, use skyvern_run_task."""- # Block login/password actions — redirect to skyvern_login- if _PASSWORD_PATTERN.search(prompt):+ try:+ check_password_prompt(prompt)+ except GuardError as e:return make_result("skyvern_act",ok=False,- error=make_error(- ErrorCode.INVALID_INPUT,- "Cannot perform password/credential actions — credentials must not be passed through tool calls",- _CREDENTIAL_ERROR_HINT,- ),+ error=make_error(ErrorCode.INVALID_INPUT, str(e), e.hint),)try:@@ -1056,8 +1039,16 @@ async def skyvern_act(with Timer() as timer:try:- await page.act(prompt)+ result = await do_act(page, prompt)timer.mark("sdk")+ except GuardError as e:+ return make_result(+ "skyvern_act",+ ok=False,+ browser_context=ctx,+ timing_ms=timer.timing_ms,+ error=make_error(ErrorCode.INVALID_INPUT, str(e), e.hint),+ )except Exception as e:return make_result("skyvern_act",@@ -1070,7 +1061,11 @@ async def skyvern_act(return make_result("skyvern_act",browser_context=ctx,- data={"prompt": prompt, "completed": True, "sdk_equivalent": f'await page.act("{prompt}")'},+ data={+ "prompt": result.prompt,+ "completed": result.completed,+ "sdk_equivalent": f'await page.act("{prompt}")',+ },timing_ms=timer.timing_ms,)@@ -1099,14 +1094,14 @@ async def skyvern_run_task(For simple single-step actions on the current page, use skyvern_act instead."""# Block password/credential actions — redirect to skyvern_login- if _PASSWORD_PATTERN.search(prompt):+ if PASSWORD_PATTERN.search(prompt):return make_result("skyvern_run_task",ok=False,error=make_error(ErrorCode.INVALID_INPUT,"Cannot perform password/credential actions — credentials must not be passed through tool calls",- _CREDENTIAL_ERROR_HINT,+ CREDENTIAL_HINT,),)diff --git a/skyvern/cli/mcp_tools/session.py b/skyvern/cli/mcp_tools/session.pyindex 67e5b8e8c..3366f460b 100644--- a/skyvern/cli/mcp_tools/session.py+++ b/skyvern/cli/mcp_tools/session.py@@ -4,7 +4,7 @@ from typing import Annotated, Anyfrom pydantic import Field-from skyvern.schemas.runs import ProxyLocation+from skyvern.cli.core.session_ops import do_session_close, do_session_create, do_session_listfrom ._common import BrowserContext, ErrorCode, Timer, make_error, make_resultfrom ._session import (@@ -30,24 +30,20 @@ async def skyvern_session_create(with Timer() as timer:try:skyvern = get_skyvern()+ browser, result = await do_session_create(+ skyvern,+ timeout=timeout or 60,+ proxy_location=proxy_location,+ local=local,+ headless=headless,+ )+ timer.mark("sdk")- if local:- browser = await skyvern.launch_local_browser(headless=headless)+ if result.local:ctx = BrowserContext(mode="local")- set_current_session(SessionState(browser=browser, context=ctx))- timer.mark("sdk")- return make_result(- "skyvern_session_create",- browser_context=ctx,- data={"local": True, "headless": headless},- timing_ms=timer.timing_ms,- )-- proxy = ProxyLocation(proxy_location) if proxy_location else None- browser = await skyvern.launch_cloud_browser(timeout=timeout, proxy_location=proxy)- ctx = BrowserContext(mode="cloud_session", session_id=browser.browser_session_id)+ else:+ ctx = BrowserContext(mode="cloud_session", session_id=result.session_id)set_current_session(SessionState(browser=browser, context=ctx))- timer.mark("sdk")except ValueError as e:return make_result(@@ -68,12 +64,20 @@ async def skyvern_session_create(error=make_error(ErrorCode.SDK_ERROR, str(e), "Failed to create browser session"),)+ if result.local:+ return make_result(+ "skyvern_session_create",+ browser_context=ctx,+ data={"local": True, "headless": result.headless},+ timing_ms=timer.timing_ms,+ )+return make_result("skyvern_session_create",browser_context=ctx,data={- "session_id": browser.browser_session_id,- "timeout_minutes": timeout,+ "session_id": result.session_id,+ "timeout_minutes": result.timeout_minutes,},timing_ms=timer.timing_ms,)@@ -92,13 +96,13 @@ async def skyvern_session_close(try:if session_id:skyvern = get_skyvern()- await skyvern.close_browser_session(session_id)+ result = await do_session_close(skyvern, session_id)if current.context and current.context.session_id == session_id:set_current_session(SessionState())timer.mark("sdk")return make_result("skyvern_session_close",- data={"session_id": session_id, "closed": True},+ data={"session_id": result.session_id, "closed": result.closed},timing_ms=timer.timing_ms,)@@ -138,17 +142,17 @@ async def skyvern_session_list() -> dict[str, Any]:with Timer() as timer:try:skyvern = get_skyvern()- sessions = await skyvern.get_browser_sessions()+ sessions = await do_session_list(skyvern)timer.mark("sdk")session_data = [{- "session_id": s.browser_session_id,+ "session_id": s.session_id,"status": s.status,- "started_at": s.started_at.isoformat() if s.started_at else None,+ "started_at": s.started_at,"timeout": s.timeout,"runnable_id": s.runnable_id,- "available": s.runnable_id is None and s.browser_address is not None,+ "available": s.available,}for s in sessions]diff --git a/tests/unit/test_cli_commands.py b/tests/unit/test_cli_commands.pynew file mode 100644index 000000000..3f142b4a7--- /dev/null+++ b/tests/unit/test_cli_commands.py@@ -0,0 +1,149 @@+"""Tests for CLI commands infrastructure: _state.py and _output.py."""++from __future__ import annotations++import json+from pathlib import Path++import pytest+import typer++from skyvern.cli.commands._state import CLIState, clear_state, load_state, save_state++# ---------------------------------------------------------------------------+# _state.py+# ---------------------------------------------------------------------------+++def _patch_state_dir(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:+ monkeypatch.setattr("skyvern.cli.commands._state.STATE_DIR", tmp_path)+ monkeypatch.setattr("skyvern.cli.commands._state.STATE_FILE", tmp_path / "state.json")+++class TestCLIState:+ def test_save_load_roundtrip(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:+ _patch_state_dir(monkeypatch, tmp_path)+ save_state(CLIState(session_id="pbs_123", cdp_url=None, mode="cloud"))+ loaded = load_state()+ assert loaded is not None+ assert loaded.session_id == "pbs_123"+ assert loaded.cdp_url is None+ assert loaded.mode == "cloud"++ def test_save_load_roundtrip_cdp(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:+ _patch_state_dir(monkeypatch, tmp_path)+ save_state(CLIState(session_id=None, cdp_url="ws://localhost:9222/devtools/browser/abc", mode="cdp"))+ loaded = load_state()+ assert loaded is not None+ assert loaded.session_id is None+ assert loaded.cdp_url == "ws://localhost:9222/devtools/browser/abc"+ assert loaded.mode == "cdp"++ def test_load_returns_none_when_missing(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:+ monkeypatch.setattr("skyvern.cli.commands._state.STATE_FILE", tmp_path / "nonexistent.json")+ assert load_state() is None++ def test_24h_ttl_expires(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:+ _patch_state_dir(monkeypatch, tmp_path)+ state_file = tmp_path / "state.json"+ state_file.write_text(+ json.dumps(+ {+ "session_id": "pbs_old",+ "mode": "cloud",+ "created_at": "2020-01-01T00:00:00+00:00",+ }+ )+ )+ assert load_state() is None++ def test_clear_state(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:+ _patch_state_dir(monkeypatch, tmp_path)+ save_state(CLIState(session_id="pbs_123"))+ clear_state()+ assert not (tmp_path / "state.json").exists()++ def test_load_ignores_corrupt_file(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:+ state_file = tmp_path / "state.json"+ monkeypatch.setattr("skyvern.cli.commands._state.STATE_FILE", state_file)+ state_file.write_text("not-json")+ assert load_state() is None+++# ---------------------------------------------------------------------------+# _output.py+# ---------------------------------------------------------------------------+++class TestOutput:+ def test_json_envelope(self, capsys: pytest.CaptureFixture) -> None:+ from skyvern.cli.commands._output import output++ output({"key": "value"}, action="test", json_mode=True)+ parsed = json.loads(capsys.readouterr().out)+ assert parsed["ok"] is True+ assert parsed["action"] == "test"+ assert parsed["data"]["key"] == "value"++ def test_json_error(self, capsys: pytest.CaptureFixture) -> None:+ from skyvern.cli.commands._output import output_error++ with pytest.raises(SystemExit, match="1"):+ output_error("bad thing", hint="fix it", json_mode=True)+ parsed = json.loads(capsys.readouterr().out)+ assert parsed["ok"] is False+ assert parsed["error"]["message"] == "bad thing"+++# ---------------------------------------------------------------------------+# Connection resolution+# ---------------------------------------------------------------------------+++class TestResolveConnection:+ def test_explicit_session_wins(self) -> None:+ from skyvern.cli.commands.browser import _resolve_connection++ result = _resolve_connection("pbs_explicit", None)+ assert result.mode == "cloud"+ assert result.session_id == "pbs_explicit"+ assert result.cdp_url is None++ def test_explicit_cdp_wins(self) -> None:+ from skyvern.cli.commands.browser import _resolve_connection++ result = _resolve_connection(None, "ws://localhost:9222/devtools/browser/abc")+ assert result.mode == "cdp"+ assert result.session_id is None+ assert result.cdp_url == "ws://localhost:9222/devtools/browser/abc"++ def test_rejects_both_connection_flags(self) -> None:+ from skyvern.cli.commands.browser import _resolve_connection++ with pytest.raises(typer.BadParameter, match="Pass only one of --session or --cdp"):+ _resolve_connection("pbs_explicit", "ws://localhost:9222/devtools/browser/abc")++ def test_state_fallback(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:+ from skyvern.cli.commands.browser import _resolve_connection++ _patch_state_dir(monkeypatch, tmp_path)+ save_state(CLIState(session_id="pbs_from_state", mode="cloud"))+ result = _resolve_connection(None, None)+ assert result.mode == "cloud"+ assert result.session_id == "pbs_from_state"++ def test_state_fallback_cdp(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:+ from skyvern.cli.commands.browser import _resolve_connection++ _patch_state_dir(monkeypatch, tmp_path)+ save_state(CLIState(session_id=None, cdp_url="ws://localhost:9222/devtools/browser/abc", mode="cdp"))+ result = _resolve_connection(None, None)+ assert result.mode == "cdp"+ assert result.cdp_url == "ws://localhost:9222/devtools/browser/abc"++ def test_no_session_raises(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:+ from skyvern.cli.commands.browser import _resolve_connection++ monkeypatch.setattr("skyvern.cli.commands._state.STATE_FILE", tmp_path / "nonexistent.json")+ with pytest.raises(typer.BadParameter, match="No active browser connection"):+ _resolve_connection(None, None)diff --git a/tests/unit/test_cli_commands_logging.py b/tests/unit/test_cli_commands_logging.pynew file mode 100644index 000000000..b714838d4--- /dev/null+++ b/tests/unit/test_cli_commands_logging.py@@ -0,0 +1,37 @@+from __future__ import annotations++import logging++import skyvern.cli.commands as cli_commands+++def test_configure_cli_logging_is_idempotent(monkeypatch) -> None:+ setup_calls: list[str] = []+ monkeypatch.setattr(cli_commands, "_setup_logger", lambda: setup_calls.append("called"))+ monkeypatch.setattr(cli_commands, "_cli_logging_configured", False)++ logger_names = ("skyvern", "httpx", "litellm", "playwright", "httpcore")+ previous_levels = {name: logging.getLogger(name).level for name in logger_names}+ try:+ cli_commands.configure_cli_logging()+ assert setup_calls == ["called"]+ for name in logger_names:+ assert logging.getLogger(name).level == logging.WARNING++ cli_commands.configure_cli_logging()+ assert setup_calls == ["called"]+ finally:+ for name, level in previous_levels.items():+ logging.getLogger(name).setLevel(level)+++def test_cli_callback_configures_logging(monkeypatch) -> None:+ called = False++ def _fake_configure() -> None:+ nonlocal called+ called = True++ monkeypatch.setattr(cli_commands, "configure_cli_logging", _fake_configure)+ cli_commands.cli_callback()+ assert calleddiff --git a/tests/unit/test_cli_shared_core.py b/tests/unit/test_cli_shared_core.pynew file mode 100644index 000000000..5c265c553--- /dev/null+++ b/tests/unit/test_cli_shared_core.py@@ -0,0 +1,234 @@+"""Tests for skyvern.cli.core shared modules (guards, browser_ops, session_ops)."""++from __future__ import annotations++from unittest.mock import AsyncMock, MagicMock++import pytest++from skyvern.cli.core.browser_ops import do_act, do_extract, do_navigate, do_screenshot, parse_extract_schema+from skyvern.cli.core.guards import (+ GuardError,+ check_js_password,+ check_password_prompt,+ resolve_ai_mode,+ validate_button,+ validate_wait_until,+)+from skyvern.cli.core.session_ops import do_session_close, do_session_create, do_session_list++# ---------------------------------------------------------------------------+# guards.py+# ---------------------------------------------------------------------------+++ "text",+ [+ "enter your password",+ "use credential to login",+ "type the secret",+ "enter passphrase",+ "enter passcode",+ "enter your pin code",+ "type pwd here",+ "enter passwd",+ ],+)+def test_password_guard_blocks_sensitive_text(text: str) -> None:+ with pytest.raises(GuardError) as exc_info:+ check_password_prompt(text)+ assert exc_info.value.hint # hint should always be populated++[email protected]("text", ["click the submit button", "fill in the email field", ""])+def test_password_guard_allows_normal_text(text: str) -> None:+ check_password_prompt(text) # should not raise+++def test_js_password_guard() -> None:+ with pytest.raises(GuardError):+ check_js_password('input[type=password].value = "secret"')+ with pytest.raises(GuardError):+ check_js_password('.type === "password"; el.value = "x"')+ check_js_password("document.title") # allowed++[email protected]("value", ["load", "domcontentloaded", "networkidle", "commit", None])+def test_wait_until_accepts_valid(value: str | None) -> None:+ validate_wait_until(value)+++def test_wait_until_rejects_invalid() -> None:+ with pytest.raises(GuardError, match="Invalid wait_until"):+ validate_wait_until("badvalue")++[email protected]("value", ["left", "right", "middle", None])+def test_button_accepts_valid(value: str | None) -> None:+ validate_button(value)+++def test_button_rejects_invalid() -> None:+ with pytest.raises(GuardError, match="Invalid button"):+ validate_button("double")+++ "selector,intent,expected",+ [+ (None, "click it", ("proactive", None)),+ ("#btn", "click it", ("fallback", None)),+ ("#btn", None, (None, None)),+ (None, None, (None, "INVALID_INPUT")),+ ],+)+def test_resolve_ai_mode(selector: str | None, intent: str | None, expected: tuple) -> None:+ assert resolve_ai_mode(selector, intent) == expected+++# ---------------------------------------------------------------------------+# browser_ops.py+# ---------------------------------------------------------------------------+++async def test_do_navigate_success() -> None:+ page = MagicMock()+ page.goto = AsyncMock()+ page.url = "https://example.com/final"+ page.title = AsyncMock(return_value="Example")++ result = await do_navigate(page, "https://example.com")+ assert result.url == "https://example.com/final"+ assert result.title == "Example"+++async def test_do_navigate_passes_wait_until_through() -> None:+ page = MagicMock()+ page.goto = AsyncMock()+ page.url = "https://example.com/final"+ page.title = AsyncMock(return_value="Example")++ result = await do_navigate(page, "https://example.com", wait_until="badvalue")+ assert result.url == "https://example.com/final"+ page.goto.assert_awaited_once_with("https://example.com", timeout=30000, wait_until="badvalue")+++async def test_do_screenshot_full_page() -> None:+ page = MagicMock()+ page.screenshot = AsyncMock(return_value=b"png-data")++ result = await do_screenshot(page, full_page=True)+ assert result.data == b"png-data"+ assert result.full_page is True+++async def test_do_screenshot_with_selector() -> None:+ page = MagicMock()+ element = MagicMock()+ element.screenshot = AsyncMock(return_value=b"element-data")+ page.locator.return_value = element++ result = await do_screenshot(page, selector="#header")+ assert result.data == b"element-data"+++async def test_do_act_success() -> None:+ page = MagicMock()+ page.act = AsyncMock()+ result = await do_act(page, "enter the password")+ assert result.prompt == "enter the password"+ assert result.completed is True+++async def test_do_extract_rejects_bad_schema() -> None:+ with pytest.raises(GuardError, match="Invalid JSON schema"):+ await do_extract(MagicMock(), "get data", schema="not-json")+++async def test_do_extract_success() -> None:+ page = MagicMock()+ page.extract = AsyncMock(return_value={"title": "Example"})++ result = await do_extract(page, "get the title")+ assert result.extracted == {"title": "Example"}+++def test_parse_extract_schema_accepts_preparsed_dict() -> None:+ schema = {"type": "object", "properties": {"title": {"type": "string"}}}+ parsed = parse_extract_schema(schema)+ assert parsed is schema+++async def test_do_extract_accepts_preparsed_dict() -> None:+ page = MagicMock()+ page.extract = AsyncMock(return_value={"title": "Example"})+ schema = {"type": "object", "properties": {"title": {"type": "string"}}}++ result = await do_extract(page, "get the title", schema=schema)+ assert result.extracted == {"title": "Example"}+ page.extract.assert_awaited_once_with(prompt="get the title", schema=schema)+++# ---------------------------------------------------------------------------+# session_ops.py+# ---------------------------------------------------------------------------+++async def test_do_session_create_local() -> None:+ skyvern = MagicMock()+ skyvern.launch_local_browser = AsyncMock(return_value=MagicMock())++ browser, result = await do_session_create(skyvern, local=True, headless=True)+ assert result.local is True+ assert result.session_id is None+++async def test_do_session_create_cloud() -> None:+ skyvern = MagicMock()+ browser_mock = MagicMock()+ browser_mock.browser_session_id = "pbs_123"+ skyvern.launch_cloud_browser = AsyncMock(return_value=browser_mock)++ browser, result = await do_session_create(skyvern, timeout=30)+ assert result.session_id == "pbs_123"+ assert result.timeout_minutes == 30+++async def test_do_session_close() -> None:+ skyvern = MagicMock()+ skyvern.close_browser_session = AsyncMock()++ result = await do_session_close(skyvern, "pbs_123")+ assert result.session_id == "pbs_123"+ assert result.closed is True+++async def test_do_session_list() -> None:+ session = MagicMock()+ session.browser_session_id = "pbs_1"+ session.status = "active"+ session.started_at = None+ session.timeout = 60+ session.runnable_id = None+ session.browser_address = "ws://localhost:1234"++ skyvern = MagicMock()+ skyvern.get_browser_sessions = AsyncMock(return_value=[session])++ result = await do_session_list(skyvern)+ assert len(result) == 1+ assert result[0].session_id == "pbs_1"+ assert result[0].available is Truediff --git a/tests/unit/test_mcp_browser_tools.py b/tests/unit/test_mcp_browser_tools.pynew file mode 100644index 000000000..7485db869--- /dev/null+++ b/tests/unit/test_mcp_browser_tools.py@@ -0,0 +1,65 @@+"""Tests for MCP browser tool preflight validation behavior."""++from __future__ import annotations++from types import SimpleNamespace+from unittest.mock import AsyncMock++import pytest++from skyvern.cli.core.result import BrowserContext+from skyvern.cli.mcp_tools import browser as mcp_browser+++async def test_skyvern_extract_invalid_schema_preflight_before_session(monkeypatch: pytest.MonkeyPatch) -> None:+ get_page = AsyncMock(side_effect=AssertionError("get_page should not be called for invalid schema"))+ monkeypatch.setattr(mcp_browser, "get_page", get_page)++ result = await mcp_browser.skyvern_extract(prompt="extract data", schema="{invalid")++ assert result["ok"] is False+ assert result["error"]["code"] == mcp_browser.ErrorCode.INVALID_INPUT+ assert "Invalid JSON schema" in result["error"]["message"]+ get_page.assert_not_awaited()+++async def test_skyvern_extract_preparsed_schema_passed_to_core(monkeypatch: pytest.MonkeyPatch) -> None:+ page = object()+ context = BrowserContext(mode="cloud_session", session_id="pbs_test")+ monkeypatch.setattr(mcp_browser, "get_page", AsyncMock(return_value=(page, context)))++ do_extract = AsyncMock(return_value=SimpleNamespace(extracted={"ok": True}))+ monkeypatch.setattr(mcp_browser, "do_extract", do_extract)++ result = await mcp_browser.skyvern_extract(prompt="extract data", schema='{"type":"object"}')++ assert result["ok"] is True+ await_args = do_extract.await_args+ assert await_args is not None+ assert isinstance(await_args.kwargs["schema"], dict)+++async def test_skyvern_navigate_invalid_wait_until_preflight_before_session(monkeypatch: pytest.MonkeyPatch) -> None:+ get_page = AsyncMock(side_effect=AssertionError("get_page should not be called for invalid wait_until"))+ monkeypatch.setattr(mcp_browser, "get_page", get_page)++ result = await mcp_browser.skyvern_navigate(url="https://example.com", wait_until="not-a-real-wait-until")++ assert result["ok"] is False+ assert result["error"]["code"] == mcp_browser.ErrorCode.INVALID_INPUT+ get_page.assert_not_awaited()+++async def test_skyvern_act_password_prompt_preflight_before_session(monkeypatch: pytest.MonkeyPatch) -> None:+ get_page = AsyncMock(side_effect=AssertionError("get_page should not be called for password prompt"))+ monkeypatch.setattr(mcp_browser, "get_page", get_page)++ result = await mcp_browser.skyvern_act(prompt="enter the password and submit")++ assert result["ok"] is False+ assert result["error"]["code"] == mcp_browser.ErrorCode.INVALID_INPUT+ get_page.assert_not_awaited()