Skip to content

Automate browser based workflows with AI

feat(browser): OSS browser-engine registry/adapter foundation (SKY-12007) (#7511)

LawyZheng6086909ab323
diff --git a/skyvern/webeye/browser_engine.py b/skyvern/webeye/browser_engine.py
new file mode 100644
index 000000000..f870d2eca
--- /dev/null
+++ b/skyvern/webeye/browser_engine.py
@@ -0,0 +1,295 @@
+"""Per-run browser-engine selection seam (OSS foundation).
+
+Model: one worker image can ship more than one browser-driver engine (stock Playwright always;
+Rustwright when the image installs it; a cloud-private engine registered by the cloud layer). The
+engine is chosen PER RUN — resolved once at the run's browser-ownership boundary and pinned to that
+run's browser resources for their whole lifetime (create -> reconnect). There is no process-global
+"active engine": two concurrent runs in one process can pin different engines with no shared mutable
+state, so one run's engine (or its exception identity) can never change underneath another.
+
+The same image holds a small registry of engine *specs*; a resolver picks one spec per run and
+materializes it into an immutable ``BrowserEngineSelection`` that carries the driver factory, the
+driver's public exception identity, and its capability metadata. Constructing a spec never imports
+the driver package, so a spec for an engine this image does not ship is inert until a run selects
+it; selecting an engine whose package is absent fails closed (``BrowserEngineUnavailable``) rather
+than silently falling back.
+
+This is the neutral foundation only. The cloud resolver, the cloud-private engine, and the
+deployment/image changes that would let one image and one queue interleave all engines live in
+later, stacked changes; the legacy build-time source rewrite (``scripts/patch_browser.sh``) still
+ships until that slice lands.
+"""
+
+from __future__ import annotations
+
+import importlib.metadata
+from dataclasses import dataclass, field
+from typing import Awaitable, Callable
+
+from playwright.async_api import Error as _PlaywrightError
+from playwright.async_api import Playwright
+from playwright.async_api import TimeoutError as _PlaywrightTimeoutError
+from playwright.async_api import async_playwright
+
+from skyvern.exceptions import SkyvernException
+
+BrowserDriverStarter = Callable[[], Awaitable[Playwright]]
+BrowserEngineErrorLoader = Callable[[], "tuple[type[BaseException], type[BaseException]]"]
+
+STOCK_ENGINE_NAME = "playwright"
+RUSTWRIGHT_ENGINE_NAME = "rustwright"
+
+# Rustwright is registered so the adapter contract exists, but it is DENY-ALL (empty capability set)
+# and thus not rollout-capable: no production browser source may select it. Paths it would serve
+# still carry stock-Playwright ``except`` clauses (e.g. the cloud browser factory), so a Rustwright
+# error would bypass those recovery branches; every source stays denied until per-run exception
+# normalization and concrete source attribution land. Pinned by a test (SKY-12007 follow-up).
+RUSTWRIGHT_ALLOWED_BROWSER_SOURCES: frozenset[str] = frozenset()
+
+
+def resolve_engine_version(package_name: str) -> str | None:
+ """Best-effort installed version of a driver package, or None when its metadata is absent."""
+ try:
+ return importlib.metadata.version(package_name)
+ except importlib.metadata.PackageNotFoundError:
+ return None
+
+
+class UnknownBrowserEngine(SkyvernException):
+ """Raised when a run selects an engine name that is not in the registry (fail closed)."""
+
+ def __init__(self, name: str, known: tuple[str, ...]) -> None:
+ self.name = name
+ super().__init__(f"Unknown browser engine {name!r}; registered engines are {sorted(known)!r}")
+
+
+class BrowserEngineUnavailable(SkyvernException):
+ """Raised when a selected engine's driver package is not installed in this image (fail closed)."""
+
+ def __init__(self, name: str) -> None:
+ self.name = name
+ super().__init__(f"Browser engine {name!r} is registered but its driver package is not installed")
+
+
+class BrowserSourceNotSupportedByEngine(SkyvernException):
+ """Raised when a resolved browser source is outside the selected engine's capability set."""
+
+ def __init__(self, *, browser_source: str | None, engine: str) -> None:
+ self.browser_source = browser_source
+ self.engine = engine
+ described = repr(browser_source) if browser_source is not None else "an unattributed browser source (None)"
+ super().__init__(f"Browser source {described} is not supported by the selected browser engine {engine!r}")
+
+
+@dataclass(frozen=True)
+class BrowserEngineMetadata:
+ """Attribution + capability for a selected engine.
+
+ ``allowed_browser_sources`` is the fail-closed capability: ``None`` means unrestricted (every
+ source allowed — the unchanged default), a set restricts the engine to exactly those neutral
+ browser-source strings, and the empty set denies every source (a registered-but-not-rollout-able
+ engine).
+ """
+
+ name: str
+ version: str | None = None
+ allowed_browser_sources: frozenset[str] | None = None
+
+ def allows(self, browser_source: str | None) -> bool:
+ return self.allowed_browser_sources is None or browser_source in self.allowed_browser_sources
+
+
+@dataclass(frozen=True)
+class BrowserEngineSelection:
+ """A single run's pinned engine. Immutable; created once and carried through the browser
+ resource's whole lifetime. Concurrent runs hold distinct selections with no shared state, so
+ an engine — and its exception identity — cannot change underneath a live browser resource.
+ """
+
+ name: str
+ start_driver: BrowserDriverStarter
+ error_type: type[BaseException]
+ timeout_error_type: type[BaseException]
+ metadata: BrowserEngineMetadata
+ selection_reason: str
+
+ def is_engine_error(self, exc: BaseException) -> bool:
+ """True if ``exc`` is a driver-family error from THIS run's engine (adapter-bound identity)."""
+ return isinstance(exc, self.error_type)
+
+ def is_engine_timeout_error(self, exc: BaseException) -> bool:
+ return isinstance(exc, self.timeout_error_type)
+
+ def ensure_supports(self, browser_source: str | None) -> None:
+ """Fail closed before any provisioning if this engine cannot serve ``browser_source``.
+
+ A restricted engine (non-``None`` ``allowed_browser_sources``, including the deny-all empty
+ set) also rejects an unattributed (``None``) source: the fail-closed capability treats an
+ unknown source as the most suspicious input, never as implicitly allowed.
+ """
+ if not self.metadata.allows(browser_source):
+ raise BrowserSourceNotSupportedByEngine(browser_source=browser_source, engine=self.name)
+
+ def attribution(self) -> dict[str, str | None]:
+ """Structured attribution for logging every run/browser creation — no hidden fallback."""
+ return {
+ "browser_engine": self.name,
+ "browser_engine_version": self.metadata.version,
+ "browser_engine_selection_reason": self.selection_reason,
+ }
+
+
+@dataclass(frozen=True)
+class BrowserEngineSpec:
+ """Immutable registry entry describing how to materialize one engine.
+
+ Constructing a spec never imports the driver package, so a spec for an engine this image does
+ not ship is inert until a run actually selects it. ``select()`` is the only place the driver's
+ error classes are imported; an absent package fails closed there.
+ """
+
+ name: str
+ _start_driver: BrowserDriverStarter
+ _load_error_types: BrowserEngineErrorLoader
+ allowed_browser_sources: frozenset[str] | None = None
+
+ def is_installed(self) -> bool:
+ try:
+ self._load_error_types()
+ return True
+ except ImportError:
+ return False
+
+ def select(self, *, selection_reason: str) -> BrowserEngineSelection:
+ try:
+ error_type, timeout_error_type = self._load_error_types()
+ except ImportError as exc:
+ raise BrowserEngineUnavailable(self.name) from exc
+ return BrowserEngineSelection(
+ name=self.name,
+ start_driver=self._start_driver,
+ error_type=error_type,
+ timeout_error_type=timeout_error_type,
+ metadata=BrowserEngineMetadata(
+ name=self.name,
+ version=resolve_engine_version(self.name),
+ allowed_browser_sources=self.allowed_browser_sources,
+ ),
+ selection_reason=selection_reason,
+ )
+
+
+@dataclass
+class BrowserEngineRegistry:
+ """Catalog of engine specs, populated once at startup (import time for OSS engines; cloud
+ registers its private engine when ``cloud`` is imported). It holds no *active* engine — there is
+ none — so a run reads it but nothing here is per-run mutable state. Registration is not
+ thread-safe and is expected to complete during single-threaded startup before any run resolves.
+ """
+
+ _specs: dict[str, BrowserEngineSpec] = field(default_factory=dict)
+
+ def register(self, spec: BrowserEngineSpec) -> None:
+ if spec.name in self._specs:
+ raise ValueError(f"Browser engine {spec.name!r} is already registered")
+ self._specs[spec.name] = spec
+
+ def get(self, name: str) -> BrowserEngineSpec:
+ try:
+ return self._specs[name]
+ except KeyError:
+ raise UnknownBrowserEngine(name, tuple(self._specs)) from None
+
+ def names(self) -> frozenset[str]:
+ return frozenset(self._specs)
+
+
+async def _start_stock_driver() -> Playwright:
+ return await async_playwright().start()
+
+
+def _stock_error_types() -> tuple[type[BaseException], type[BaseException]]:
+ return _PlaywrightError, _PlaywrightTimeoutError
+
+
+async def _start_rustwright_driver() -> Playwright:
+ from rustwright.async_api import async_playwright as rustwright_async_playwright
+
+ return await rustwright_async_playwright().start()
+
+
+def _rustwright_error_types() -> tuple[type[BaseException], type[BaseException]]:
+ from rustwright.async_api import Error as RustwrightError
+ from rustwright.async_api import TimeoutError as RustwrightTimeoutError
+
+ return RustwrightError, RustwrightTimeoutError
+
+
+PLAYWRIGHT_SPEC = BrowserEngineSpec(
+ name=STOCK_ENGINE_NAME,
+ _start_driver=_start_stock_driver,
+ _load_error_types=_stock_error_types,
+ allowed_browser_sources=None,
+)
+
+RUSTWRIGHT_SPEC = BrowserEngineSpec(
+ name=RUSTWRIGHT_ENGINE_NAME,
+ _start_driver=_start_rustwright_driver,
+ _load_error_types=_rustwright_error_types,
+ allowed_browser_sources=RUSTWRIGHT_ALLOWED_BROWSER_SOURCES,
+)
+
+REGISTRY = BrowserEngineRegistry()
+REGISTRY.register(PLAYWRIGHT_SPEC)
+REGISTRY.register(RUSTWRIGHT_SPEC)
+
+
+@dataclass(frozen=True)
+class BrowserEngineContext:
+ """Per-run inputs a resolver may use to pick and validate an engine. Available at the browser
+ resource's creation site; ``browser_source`` is the neutral provider/source string the resolver
+ validates against the engine's capability set."""
+
+ organization_id: str | None = None
+ workflow_run_id: str | None = None
+ workflow_permanent_id: str | None = None
+ task_id: str | None = None
+ browser_source: str | None = None
+
+
+BrowserEngineResolver = Callable[[BrowserEngineContext], Awaitable[BrowserEngineSelection]]
+
+
+async def _default_resolver(context: BrowserEngineContext) -> BrowserEngineSelection:
+ """OSS default: stock Playwright, unconditionally. Cloud overrides this to read the multivariate
+ engine flag (see ``cloud.webeye.browser_engine``)."""
+ return REGISTRY.get(STOCK_ENGINE_NAME).select(selection_reason="oss-default-playwright")
+
+
+_resolver: BrowserEngineResolver = _default_resolver
+
+
+def set_browser_engine_resolver(resolver: BrowserEngineResolver) -> None:
+ """Install the per-run resolver strategy (cloud does this at startup). This injects HOW an engine
+ is chosen; it does not hold a chosen engine, so it is not process-global active-engine state."""
+ global _resolver
+ _resolver = resolver
+
+
+def reset_browser_engine_resolver() -> None:
+ """Restore the OSS default resolver (used by tests)."""
+ global _resolver
+ _resolver = _default_resolver
+
+
+async def resolve_browser_engine(context: BrowserEngineContext) -> BrowserEngineSelection:
+ """Resolve an engine for ``context`` via the installed resolver, then validate the run's browser
+ source against the engine's capability set (fail closed before any provisioning). Callers that
+ own a logical run resolve once and reuse the returned selection for every browser resource in
+ that run (see ``RealBrowserManager``), so the engine is pinned per run, not per resource.
+
+ An unrestricted engine (``allowed_browser_sources is None``) may resolve with no attributed
+ source; a restricted engine fails closed on an unattributed source rather than passing the gate."""
+ selection = await _resolver(context)
+ selection.ensure_supports(context.browser_source)
+ return selection
diff --git a/tests/unit/test_browser_engine.py b/tests/unit/test_browser_engine.py
new file mode 100644
index 000000000..582032931
--- /dev/null
+++ b/tests/unit/test_browser_engine.py
@@ -0,0 +1,277 @@
+"""Per-run browser-engine selection (OSS seam).
+
+These tests stay driver-agnostic: they exercise the registry, per-run selection, capability gate,
+and exception-identity classification with fake engine specs, so they hold on an image that ships
+only stock Playwright. Cloud-only concerns (the cloud-private engine, the multivariate flag) are
+left to the cloud wiring slice that introduces them.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import dataclasses
+import re
+from pathlib import Path
+
+import pytest
+from playwright.async_api import Error as PlaywrightError
+from playwright.async_api import TimeoutError as PlaywrightTimeoutError
+
+from skyvern.webeye import browser_engine
+from skyvern.webeye.browser_engine import (
+ RUSTWRIGHT_ALLOWED_BROWSER_SOURCES,
+ STOCK_ENGINE_NAME,
+ BrowserEngineContext,
+ BrowserEngineMetadata,
+ BrowserEngineRegistry,
+ BrowserEngineSelection,
+ BrowserEngineSpec,
+ BrowserSourceNotSupportedByEngine,
+ UnknownBrowserEngine,
+ resolve_browser_engine,
+)
+
+
+class _EngineAError(Exception):
+ pass
+
+
+class _EngineATimeout(_EngineAError):
+ pass
+
+
+class _EngineBError(Exception):
+ pass
+
+
+class _EngineBTimeout(_EngineBError):
+ pass
+
+
+async def _never_start(): # pragma: no cover - must never be awaited in gate tests
+ raise AssertionError("start_driver must not be called when a capability gate rejects the source")
+
+
+def _selection(
+ name: str,
+ error_type: type[BaseException],
+ timeout_type: type[BaseException],
+ *,
+ allowed_sources: frozenset[str] | None = None,
+ start=_never_start,
+) -> BrowserEngineSelection:
+ return BrowserEngineSelection(
+ name=name,
+ start_driver=start,
+ error_type=error_type,
+ timeout_error_type=timeout_type,
+ metadata=BrowserEngineMetadata(name=name, version="0.0.0", allowed_browser_sources=allowed_sources),
+ selection_reason="test",
+ )
+
+
[email protected](autouse=True)
+def _restore_resolver():
+ yield
+ browser_engine.reset_browser_engine_resolver()
+
+
+def test_registry_has_stock_and_rustwright_and_rejects_unknown():
+ names = browser_engine.REGISTRY.names()
+ assert STOCK_ENGINE_NAME in names
+ assert browser_engine.RUSTWRIGHT_ENGINE_NAME in names
+ with pytest.raises(UnknownBrowserEngine):
+ browser_engine.REGISTRY.get("no-such-engine")
+
+
+def test_registry_rejects_duplicate_registration():
+ registry = BrowserEngineRegistry()
+ spec = BrowserEngineSpec(
+ name="dup", _start_driver=_never_start, _load_error_types=lambda: (_EngineAError, _EngineATimeout)
+ )
+ registry.register(spec)
+ with pytest.raises(ValueError):
+ registry.register(spec)
+
+
+def test_selection_is_frozen():
+ sel = _selection("playwright", PlaywrightError, PlaywrightTimeoutError)
+ with pytest.raises(dataclasses.FrozenInstanceError):
+ sel.name = "mutated" # type: ignore[misc]
+
+
+def test_stock_spec_selects_with_playwright_identity():
+ sel = browser_engine.REGISTRY.get(STOCK_ENGINE_NAME).select(selection_reason="test")
+ assert sel.name == STOCK_ENGINE_NAME
+ assert sel.metadata.allowed_browser_sources is None
+ assert sel.is_engine_error(PlaywrightError("boom"))
+ assert sel.is_engine_timeout_error(PlaywrightTimeoutError("slow"))
+ assert not sel.is_engine_error(ValueError("unrelated"))
+
+
+def test_rustwright_spec_fails_closed_when_driver_absent():
+ # rustwright is not installed in the OSS test image: selecting it must fail closed, never fall back.
+ spec = browser_engine.REGISTRY.get(browser_engine.RUSTWRIGHT_ENGINE_NAME)
+ assert spec.is_installed() is False
+ with pytest.raises(browser_engine.BrowserEngineUnavailable):
+ spec.select(selection_reason="explicit-rustwright")
+
+
+# Representative neutral source strings (not a canonical source registry — that belongs to the cloud
+# wiring slice). Deny-all is source-independent: it must reject whatever source it is handed, so the
+# sample only needs to be varied, including the ``None`` unattributed case.
+SAMPLE_BROWSER_SOURCES = ("chromium-headful", "chromium-headless", "cdp-connect", None)
+
+
+async def test_rustwright_deny_all_fails_before_provisioning_regardless_of_source():
+ # Empty capability set = deny-all: the adapter contract exists but no source may select it. Each
+ # source must raise BEFORE start_driver (_never_start) runs, so explicit Rustwright cannot start a
+ # driver in production today — it stays rollout-incapable until exception normalization lands.
+ assert RUSTWRIGHT_ALLOWED_BROWSER_SOURCES == frozenset()
+ denied = _selection(
+ "rustwright", _EngineAError, _EngineATimeout, allowed_sources=RUSTWRIGHT_ALLOWED_BROWSER_SOURCES
+ )
+ browser_engine.set_browser_engine_resolver(lambda ctx: _async(denied))
+ for source in SAMPLE_BROWSER_SOURCES:
+ with pytest.raises(BrowserSourceNotSupportedByEngine):
+ await resolve_browser_engine(BrowserEngineContext(browser_source=source))
+
+
+async def test_unrestricted_engine_allows_unattributed_source():
+ # allowed_browser_sources is None => unrestricted: a run with no attributed source is served.
+ unrestricted = _selection("engine-a", _EngineAError, _EngineATimeout, allowed_sources=None, start=_ok_start)
+ browser_engine.set_browser_engine_resolver(lambda ctx: _async(unrestricted))
+ sel = await resolve_browser_engine(BrowserEngineContext(browser_source=None))
+ assert sel.name == "engine-a"
+
+
+async def test_restricted_engine_rejects_unattributed_source():
+ # A restricted engine must fail closed on an unattributed source, and attribute it honestly (None),
+ # not as the misleading string "None".
+ restricted = _selection("engine-a", _EngineAError, _EngineATimeout, allowed_sources=frozenset({"cdp-connect"}))
+ browser_engine.set_browser_engine_resolver(lambda ctx: _async(restricted))
+ with pytest.raises(BrowserSourceNotSupportedByEngine) as excinfo:
+ await resolve_browser_engine(BrowserEngineContext(browser_source=None))
+ assert excinfo.value.browser_source is None
+
+
+async def test_deny_all_rejects_unattributed_source():
+ denied = _selection(
+ "rustwright", _EngineAError, _EngineATimeout, allowed_sources=RUSTWRIGHT_ALLOWED_BROWSER_SOURCES
+ )
+ browser_engine.set_browser_engine_resolver(lambda ctx: _async(denied))
+ with pytest.raises(BrowserSourceNotSupportedByEngine):
+ await resolve_browser_engine(BrowserEngineContext(browser_source=None))
+
+
+async def test_restricted_engine_allows_known_source():
+ restricted = _selection(
+ "engine-a", _EngineAError, _EngineATimeout, allowed_sources=frozenset({"cdp-connect"}), start=_ok_start
+ )
+ browser_engine.set_browser_engine_resolver(lambda ctx: _async(restricted))
+ sel = await resolve_browser_engine(BrowserEngineContext(browser_source="cdp-connect"))
+ assert sel.name == "engine-a"
+
+
+async def test_restricted_engine_rejects_disallowed_known_source():
+ restricted = _selection("engine-a", _EngineAError, _EngineATimeout, allowed_sources=frozenset({"cdp-connect"}))
+ browser_engine.set_browser_engine_resolver(lambda ctx: _async(restricted))
+ with pytest.raises(BrowserSourceNotSupportedByEngine) as excinfo:
+ await resolve_browser_engine(BrowserEngineContext(browser_source="chromium-headful"))
+ assert excinfo.value.browser_source == "chromium-headful"
+
+
+async def test_rejected_unattributed_source_does_not_start_driver():
+ started = False
+
+ async def _spy_start():
+ nonlocal started
+ started = True
+ return object()
+
+ denied = _selection(
+ "rustwright",
+ _EngineAError,
+ _EngineATimeout,
+ allowed_sources=RUSTWRIGHT_ALLOWED_BROWSER_SOURCES,
+ start=_spy_start,
+ )
+ browser_engine.set_browser_engine_resolver(lambda ctx: _async(denied))
+ with pytest.raises(BrowserSourceNotSupportedByEngine):
+ await resolve_browser_engine(BrowserEngineContext(browser_source=None))
+ assert started is False
+
+
+async def test_default_resolver_is_stock_playwright():
+ sel = await resolve_browser_engine(BrowserEngineContext(browser_source="local-browser"))
+ assert sel.name == STOCK_ENGINE_NAME
+
+
+async def test_unknown_engine_selection_fails_closed():
+ browser_engine.set_browser_engine_resolver(
+ lambda ctx: browser_engine.REGISTRY.get("phantom").select(selection_reason="x") # type: ignore[return-value]
+ )
+ with pytest.raises(UnknownBrowserEngine):
+ await resolve_browser_engine(BrowserEngineContext(browser_source="local-browser"))
+
+
+async def test_concurrent_runs_pin_distinct_engines_without_global_rebinding():
+ a = _selection("engine-a", _EngineAError, _EngineATimeout, start=_ok_start)
+ b = _selection("engine-b", _EngineBError, _EngineBTimeout, start=_ok_start)
+
+ async def resolver(ctx: BrowserEngineContext) -> BrowserEngineSelection:
+ # Simulate interleaving: yield so the two runs overlap inside the resolver.
+ await asyncio.sleep(0)
+ return a if ctx.workflow_run_id == "run-a" else b
+
+ browser_engine.set_browser_engine_resolver(resolver)
+ sel_a, sel_b = await asyncio.gather(
+ resolve_browser_engine(BrowserEngineContext(workflow_run_id="run-a", browser_source="local-browser")),
+ resolve_browser_engine(BrowserEngineContext(workflow_run_id="run-b", browser_source="local-browser")),
+ )
+ assert sel_a.name == "engine-a" and sel_b.name == "engine-b"
+ # Each run's exception identity is its own and cannot be invalidated by the other run.
+ assert sel_a.is_engine_error(_EngineAError()) and not sel_a.is_engine_error(_EngineBError())
+ assert sel_b.is_engine_error(_EngineBError()) and not sel_b.is_engine_error(_EngineAError())
+
+
+def test_selection_pinning_survives_resolver_change_midrun():
+ # Once resolved, a selection object holds its own engine; later resolver swaps cannot mutate it.
+ pinned = _selection("engine-a", _EngineAError, _EngineATimeout)
+ browser_engine.set_browser_engine_resolver(
+ lambda ctx: _async(_selection("engine-b", _EngineBError, _EngineBTimeout))
+ )
+ assert pinned.name == "engine-a"
+ assert pinned.is_engine_error(_EngineAError())
+ assert not pinned.is_engine_error(_EngineBError())
+
+
+def test_oss_module_only_references_oss_safe_driver_packages():
+ # The OSS seam must not name any cloud-private driver package. Assert positively — every
+ # driver import in the module targets an OSS-safe package — so this test file never has to
+ # embed a cloud-private identifier itself (tests/unit/ is synced to the public repo).
+ source = Path(browser_engine.__file__).read_text()
+ driver_packages = set(re.findall(r"from (\w+)\.async_api", source))
+ assert driver_packages <= {"playwright", "rustwright"}, driver_packages
+ assert browser_engine.REGISTRY.names() >= {STOCK_ENGINE_NAME, browser_engine.RUSTWRIGHT_ENGINE_NAME}
+
+
+async def _ok_start():
+ return object()
+
+
+def _async(value):
+ async def _coro(ctx=None):
+ return value
+
+ return _coro()