Automate browser based workflows with AI
Python aiapiautomationbrowserbrowser-automationcomputergptllmplaywrightpowerautomatepuppeteerpythonrpaseleniumvisionworkflow
Bound workflow idempotency waits (SKY-13795) (#8174)
Aaron Perezcb658301849b
diff --git a/docs/api-reference/openapi.json b/docs/api-reference/openapi.jsonindex 8f6a81ece..ac59f0d01 100644--- a/docs/api-reference/openapi.json+++ b/docs/api-reference/openapi.json@@ -509,6 +509,22 @@},"description": "Optional folder ID to assign the workflow to"},+ {+ "name": "Idempotency-Key",+ "in": "header",+ "required": false,+ "schema": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "null"+ }+ ],+ "title": "Idempotency-Key"+ }+ },{"name": "x-api-key","in": "header",@@ -549,6 +565,9 @@}}},+ "409": {+ "description": "A create with this idempotency key is still in progress"+ },"422": {"description": "Invalid agent definition"}diff --git a/skyvern/browser_extension/broker/__init__.py b/skyvern/browser_extension/broker/__init__.pynew file mode 100644index 000000000..1eec9bc53--- /dev/null+++ b/skyvern/browser_extension/broker/__init__.py@@ -0,0 +1,25 @@+from skyvern.browser_extension.broker.leases import LeaseTable+from skyvern.browser_extension.broker.protocol import (+ BROKER_FRAME_VERSION,+ BROKER_PROTOCOL_VERSION,+ BROKER_WS_PATH,+ BrokerFrame,+ build_broker_challenge,+ compute_broker_client_proof,+ compute_broker_server_proof,+ parse_broker_frame,+ verify_broker_client_proof,+)++__all__ = [+ "BROKER_FRAME_VERSION",+ "BROKER_PROTOCOL_VERSION",+ "BROKER_WS_PATH",+ "BrokerFrame",+ "LeaseTable",+ "build_broker_challenge",+ "compute_broker_client_proof",+ "compute_broker_server_proof",+ "parse_broker_frame",+ "verify_broker_client_proof",+]diff --git a/skyvern/browser_extension/broker/client.py b/skyvern/browser_extension/broker/client.pynew file mode 100644index 000000000..a906eb8aa--- /dev/null+++ b/skyvern/browser_extension/broker/client.py@@ -0,0 +1,426 @@+from __future__ import annotations++import asyncio+import itertools+import os+import secrets+import time+from collections.abc import Awaitable, Callable+from contextlib import suppress++import aiohttp+import structlog++from skyvern.browser_extension.broker.daemon import spawn_daemon+from skyvern.browser_extension.broker.protocol import (+ BROKER_FRAME_VERSION,+ BROKER_PROTOCOL_VERSION,+ BROKER_WS_PATH,+ EXTENSION_NOT_CONNECTED_CODE,+ PAIRING_NONCE_OP,+ STATUS_OP,+ BrokerFrame,+ build_broker_nonce,+ build_request_frame,+ compute_broker_client_proof,+ compute_broker_server_proof,+ parse_broker_frame,+)+from skyvern.browser_extension.errors import (+ BrowserExtensionError,+ BrowserExtensionNotConnectedError,+ ExtensionRequestError,+)+from skyvern.browser_extension.relay import _MAX_WS_MESSAGE_BYTES++LOG = structlog.get_logger(__name__)++_CONNECT_TIMEOUT_SECONDS = 5.0+_HANDSHAKE_TIMEOUT_SECONDS = 10.0+_SPAWN_ATTEMPTS = 40+_SPAWN_POLL_SECONDS = 0.25+_SPAWN_EVERY_N_ATTEMPTS = 4+_RECONNECT_INITIAL_SECONDS = 0.5+_RECONNECT_MAX_SECONDS = 10.0+_REQUEST_GRACE_SECONDS = 5.0+_STEP_DOWN_COOLDOWN_SECONDS = 60.0+++class LegacyBridgeOwnerError(BrowserExtensionError):+ """Raised when the bridge port is held by a pre-broker single-owner MCP instance."""+++class BrokerTransport:+ """Client side of the broker daemon, shaped like ExtensionRelayServer.++ ExtensionCdpAdapter and BrowserExtensionRuntime only ever touch a handful of relay members, so+ an MCP process can swap in this transport and drive a browser it does not own.+ """++ def __init__(+ self,+ token: str,+ port: int,+ on_event: Callable[[str, dict], Awaitable[None]],+ on_disconnect: Callable[[], Awaitable[None]] | None = None,+ ) -> None:+ self._token = token+ self._port = port+ self._on_event = on_event+ self._on_disconnect = on_disconnect+ self._session: aiohttp.ClientSession | None = None+ self._websocket: aiohttp.ClientWebSocketResponse | None = None+ self._reader_task: asyncio.Task[None] | None = None+ self._request_ids = itertools.count(1)+ self._pending: dict[str, asyncio.Future[dict]] = {}+ self._connected_event = asyncio.Event()+ self._extension_connected = False+ self._stopped = False+ self._last_step_down_at: float | None = None+ self.bound_port = port+ self.scoped_tabs: list[dict] = []+ self.daemon_pid: int | None = None+ self.daemon_protocol: int | None = None++ @property+ def connected(self) -> bool:+ websocket = self._websocket+ return self._extension_connected and websocket is not None and not websocket.closed++ async def start(self) -> None:+ await self._connect_with_spawn()+ self._reader_task = asyncio.create_task(self._run_reader())++ async def stop(self) -> None:+ self._stopped = True+ task = self._reader_task+ self._reader_task = None+ if task is not None:+ task.cancel()+ with suppress(asyncio.CancelledError):+ await task+ await self._teardown_connection()++ async def wait_connected(self, timeout: float) -> bool:+ if self.connected:+ return True+ try:+ await asyncio.wait_for(self._connected_event.wait(), timeout)+ except TimeoutError:+ return False+ return self.connected++ async def request(self, op: str, args: dict, timeout: float = 30.0) -> dict:+ websocket = self._websocket+ if websocket is None or websocket.closed:+ raise BrowserExtensionNotConnectedError("Skyvern browser extension is not connected")++ request_id = f"b-{next(self._request_ids)}"+ future: asyncio.Future[dict] = asyncio.get_running_loop().create_future()+ self._pending[request_id] = future+ try:+ await websocket.send_json(build_request_frame(request_id, op, args, timeout))+ except (ConnectionError, RuntimeError, ValueError):+ self._discard_pending(request_id)+ raise BrowserExtensionNotConnectedError("Skyvern browser extension is not connected") from None++ try:+ return await asyncio.wait_for(asyncio.shield(future), timeout + _REQUEST_GRACE_SECONDS)+ except TimeoutError:+ self._discard_pending(request_id)+ raise ExtensionRequestError("INTERNAL", f"extension request timed out: {op}") from None+ except asyncio.CancelledError:+ self._discard_pending(request_id)+ raise++ async def acquire_pairing_nonce(self) -> str:+ result = await self.request(PAIRING_NONCE_OP, {}, timeout=10.0)+ nonce = result.get("nonce")+ if not isinstance(nonce, str) or not nonce:+ raise BrowserExtensionError("The browser extension broker returned an invalid pairing response")+ port = result.get("port")+ if type(port) is int:+ self.bound_port = port+ return nonce++ async def broker_status(self) -> dict:+ return await self.request(STATUS_OP, {}, timeout=10.0)++ async def _connect_with_spawn(self) -> None:+ last_error: BaseException | None = None+ for attempt in range(_SPAWN_ATTEMPTS):+ try:+ await self._connect()+ return+ except LegacyBridgeOwnerError:+ raise+ except (OSError, BrowserExtensionError) as exc:+ last_error = exc+ # Re-spawn periodically rather than once: the first daemon may have lost the bind race+ # to an outgoing instance that has since exited.+ if attempt % _SPAWN_EVERY_N_ATTEMPTS == 0:+ spawn_daemon(self._port)+ await asyncio.sleep(_SPAWN_POLL_SECONDS)+ raise BrowserExtensionError(+ f"Could not reach or start the Skyvern browser-extension broker on port {self._port}"+ ) from last_error++ async def _connect(self) -> None:+ session = aiohttp.ClientSession(+ timeout=aiohttp.ClientTimeout(+ total=None, connect=_CONNECT_TIMEOUT_SECONDS, sock_connect=_CONNECT_TIMEOUT_SECONDS+ )+ )+ try:+ websocket = await session.ws_connect(+ f"ws://127.0.0.1:{self._port}{BROKER_WS_PATH}",+ max_msg_size=_MAX_WS_MESSAGE_BYTES,+ heartbeat=20.0,+ autoping=True,+ )+ except aiohttp.WSServerHandshakeError as exc:+ await session.close()+ # A live listener that does not speak the broker protocol is a pre-broker MCP instance+ # holding the port; spawning another daemon would only lose the bind.+ raise LegacyBridgeOwnerError(+ f"Port {self._port} is held by an older Skyvern MCP session that does not share the "+ "browser-extension bridge"+ ) from exc+ except (aiohttp.ClientConnectionError, OSError) as exc:+ await session.close()+ raise OSError(f"broker connect failed: {type(exc).__name__}") from exc++ try:+ await asyncio.wait_for(self._handshake(websocket), _HANDSHAKE_TIMEOUT_SECONDS)+ except BaseException:+ await websocket.close()+ await session.close()+ raise++ self._session = session+ self._websocket = websocket++ async def _handshake(self, websocket: aiohttp.ClientWebSocketResponse) -> None:+ challenge = await self._receive_frame(websocket)+ if challenge is None or challenge.kind != "auth.challenge" or challenge.server_nonce is None:+ raise BrowserExtensionError("The browser-extension broker sent an invalid challenge")++ client_nonce = build_broker_nonce()+ await websocket.send_json(+ {+ "v": BROKER_FRAME_VERSION,+ "type": "auth.proof",+ "clientNonce": client_nonce,+ "proof": compute_broker_client_proof(self._token, challenge.server_nonce, client_nonce),+ }+ )++ auth_ok = await self._receive_frame(websocket)+ if auth_ok is None or auth_ok.kind != "auth.ok" or auth_ok.proof is None or auth_ok.protocol is None:+ raise BrowserExtensionError("The browser-extension broker rejected this session")+ expected = compute_broker_server_proof(self._token, client_nonce, challenge.server_nonce)+ if not secrets.compare_digest(expected, auth_ok.proof):+ raise BrowserExtensionError("The browser-extension broker failed authentication")++ if auth_ok.protocol < BROKER_PROTOCOL_VERSION and self._may_request_step_down():+ LOG.info(+ "browser_extension_broker_step_down_requested",+ daemon_protocol=auth_ok.protocol,+ protocol=BROKER_PROTOCOL_VERSION,+ daemon_root=auth_ok.root,+ )+ self._last_step_down_at = time.monotonic()+ await websocket.send_json(+ {"v": BROKER_FRAME_VERSION, "type": "broker.stepDown", "protocol": BROKER_PROTOCOL_VERSION}+ )+ raise OSError("broker is stepping down for a newer client")++ self.daemon_pid = auth_ok.pid+ self.daemon_protocol = auth_ok.protocol+ await websocket.send_json(+ {+ "v": BROKER_FRAME_VERSION,+ "type": "client.hello",+ "protocol": BROKER_PROTOCOL_VERSION,+ "pid": os.getpid(),+ }+ )++ state = await self._receive_frame(websocket)+ if state is None or state.kind != "broker.state" or state.extension_connected is None:+ raise BrowserExtensionError("The browser-extension broker sent an invalid state frame")+ self._apply_state(state.extension_connected, state.scoped_tabs or [])++ def _may_request_step_down(self) -> bool:+ last = self._last_step_down_at+ return last is None or time.monotonic() - last >= _STEP_DOWN_COOLDOWN_SECONDS++ async def _receive_frame(self, websocket: aiohttp.ClientWebSocketResponse) -> BrokerFrame | None:+ message = await websocket.receive()+ if message.type is not aiohttp.WSMsgType.TEXT:+ return None+ try:+ return parse_broker_frame(message.data, from_client=False)+ except BrowserExtensionError:+ return None++ async def _run_reader(self) -> None:+ delay = _RECONNECT_INITIAL_SECONDS+ while not self._stopped:+ websocket = self._websocket+ if websocket is not None:+ try:+ await self._read_until_closed(websocket)+ except asyncio.CancelledError:+ raise+ except Exception:+ LOG.exception("browser_extension_broker_reader_failed")+ await self._teardown_connection()+ if self._stopped:+ return+ try:+ await self._connect()+ except LegacyBridgeOwnerError:+ LOG.warning("browser_extension_broker_reconnect_blocked_by_legacy_owner", port=self._port)+ await asyncio.sleep(delay)+ delay = min(delay * 2, _RECONNECT_MAX_SECONDS)+ continue+ except (OSError, BrowserExtensionError):+ spawn_daemon(self._port)+ await asyncio.sleep(delay)+ delay = min(delay * 2, _RECONNECT_MAX_SECONDS)+ continue+ delay = _RECONNECT_INITIAL_SECONDS+ LOG.info("browser_extension_broker_reconnected", port=self._port, daemon_pid=self.daemon_pid)++ async def _read_until_closed(self, websocket: aiohttp.ClientWebSocketResponse) -> None:+ async for message in websocket:+ if message.type is not aiohttp.WSMsgType.TEXT:+ if message.type in {aiohttp.WSMsgType.CLOSE, aiohttp.WSMsgType.CLOSED, aiohttp.WSMsgType.ERROR}:+ return+ continue+ try:+ frame = parse_broker_frame(message.data, from_client=False)+ except BrowserExtensionError:+ LOG.warning("browser_extension_broker_invalid_frame")+ continue+ await self._handle_frame(websocket, frame)++ async def _handle_frame(self, websocket: aiohttp.ClientWebSocketResponse, frame: BrokerFrame) -> None:+ if frame.kind == "ping":+ with suppress(ConnectionError, RuntimeError, ValueError):+ await websocket.send_json({"v": BROKER_FRAME_VERSION, "type": "pong"})+ return+ if frame.kind == "pong":+ return+ if frame.kind == "response":+ self._complete_request(frame)+ return+ if frame.kind == "broker.state" and frame.extension_connected is not None:+ was_connected = self._extension_connected+ self._apply_state(frame.extension_connected, frame.scoped_tabs or [])+ if was_connected and not frame.extension_connected:+ self._fail_pending()+ await self._call_on_disconnect()+ return+ if frame.kind == "event" and frame.event is not None and frame.params is not None:+ self._update_scoped_tabs(frame.event, frame.params)+ if frame.event == "extension.hello":+ self._extension_connected = True+ self._connected_event.set()+ try:+ await self._on_event(frame.event, frame.params)+ except Exception:+ LOG.exception("browser extension event callback failed", event=frame.event)++ def _apply_state(self, extension_connected: bool, scoped_tabs: list[dict]) -> None:+ self._extension_connected = extension_connected+ if not extension_connected:+ self._connected_event.clear()+ self.scoped_tabs = []+ return+ self.scoped_tabs = [tab for tab in scoped_tabs if type(tab.get("tabId")) is int]+ self._connected_event.set()++ def _update_scoped_tabs(self, event: str, params: dict) -> None:+ if event == "extension.hello":+ tabs = params.get("scopedTabs")+ self.scoped_tabs = (+ [tab for tab in tabs if isinstance(tab, dict) and type(tab.get("tabId")) is int]+ if isinstance(tabs, list)+ else []+ )+ return+ if event in {"scope.tabAdded", "tabs.created"}:+ tab_id = params.get("tabId")+ if type(tab_id) is not int:+ return+ url = params.get("url")+ title = params.get("title")+ snapshot = {+ "tabId": tab_id,+ "url": url if isinstance(url, str) else "",+ "title": title if isinstance(title, str) else "",+ }+ self.scoped_tabs = [tab for tab in self.scoped_tabs if tab.get("tabId") != tab_id]+ self.scoped_tabs.append(snapshot)+ return+ if event == "scope.tabRemoved":+ tab_id = params.get("tabId")+ if type(tab_id) is int:+ self.scoped_tabs = [tab for tab in self.scoped_tabs if tab.get("tabId") != tab_id]++ def _complete_request(self, frame: BrokerFrame) -> None:+ if frame.request_id is None:+ return+ future = self._pending.pop(frame.request_id, None)+ if future is None or future.done():+ return+ if frame.ok:+ future.set_result(frame.result or {})+ return+ code = frame.error_code or "INTERNAL"+ message = frame.error_message or "broker request failed"+ if code == EXTENSION_NOT_CONNECTED_CODE:+ future.set_exception(BrowserExtensionNotConnectedError(message))+ return+ future.set_exception(ExtensionRequestError(code, message))++ def _discard_pending(self, request_id: str) -> None:+ pending = self._pending.pop(request_id, None)+ if pending is not None and not pending.done():+ pending.cancel()++ def _fail_pending(self) -> None:+ pending = list(self._pending.values())+ self._pending.clear()+ for future in pending:+ if not future.done():+ future.set_exception(BrowserExtensionNotConnectedError("Skyvern browser extension is not connected"))++ async def _teardown_connection(self) -> None:+ websocket = self._websocket+ session = self._session+ self._websocket = None+ self._session = None+ was_connected = self._extension_connected+ self._extension_connected = False+ self._connected_event.clear()+ self.scoped_tabs = []+ self._fail_pending()+ if websocket is not None and not websocket.closed:+ with suppress(Exception):+ await websocket.close()+ if session is not None:+ with suppress(Exception):+ await session.close()+ if was_connected:+ await self._call_on_disconnect()++ async def _call_on_disconnect(self) -> None:+ if self._on_disconnect is None:+ return+ try:+ await self._on_disconnect()+ except Exception:+ LOG.exception("browser extension disconnect callback failed")diff --git a/skyvern/browser_extension/broker/daemon.py b/skyvern/browser_extension/broker/daemon.pynew file mode 100644index 000000000..79c5bce06--- /dev/null+++ b/skyvern/browser_extension/broker/daemon.py@@ -0,0 +1,203 @@+from __future__ import annotations++import argparse+import asyncio+import errno+import os+import signal+import subprocess+import sys+import time+from contextlib import suppress+from pathlib import Path+from typing import IO, Any++import structlog++from skyvern.browser_extension.auth import load_or_create_pairing_token+from skyvern.browser_extension.broker.server import BrokerServer+from skyvern.browser_extension.errors import BrowserExtensionError++LOG = structlog.get_logger(__name__)++DAEMON_MODULE = "skyvern.browser_extension.broker.daemon"+IDLE_TIMEOUT_ENV = "SKYVERN_BROWSER_EXTENSION_BROKER_IDLE_SECONDS"+DEFAULT_IDLE_TIMEOUT_SECONDS = 300.0++_SPAWN_LOCK_NAME = "browser_extension_broker.lock"+_LOG_NAME = "browser_extension_broker.log"+_MAX_LOG_BYTES = 4 * 1024 * 1024+_SPAWN_COOLDOWN_SECONDS = 2.0+++def _state_dir() -> Path:+ return Path.home() / ".skyvern"+++def resolve_idle_timeout_seconds() -> float:+ raw = os.environ.get(IDLE_TIMEOUT_ENV)+ if raw is None:+ return DEFAULT_IDLE_TIMEOUT_SECONDS+ try:+ value = float(raw)+ except ValueError as exc:+ raise BrowserExtensionError(f"{IDLE_TIMEOUT_ENV} must be a number of seconds") from exc+ if value <= 0:+ raise BrowserExtensionError(f"{IDLE_TIMEOUT_ENV} must be greater than zero")+ return value+++def spawn_daemon(port: int) -> bool:+ """Launch a detached broker daemon.++ Returns False when another process is already bringing one up — the caller should just keep+ retrying its connection. Losing this race stays harmless regardless: only one daemon can bind+ the port and the rest exit quietly. The lock and its timestamp exist so a workstation running+ dozens of agents does not start dozens of interpreters that immediately exit.+ """+ lock = _acquire_spawn_lock()+ if lock is None:+ return False+ try:+ if _spawned_recently(lock):+ return False+ _stamp_spawn(lock)+ log_file = _open_daemon_log()+ options: dict[str, Any] = {+ "stdin": subprocess.DEVNULL,+ "stdout": log_file if log_file is not None else subprocess.DEVNULL,+ "stderr": subprocess.STDOUT if log_file is not None else subprocess.DEVNULL,+ "close_fds": True,+ }+ if sys.platform == "win32":+ options["creationflags"] = 0x00000208+ else:+ options["start_new_session"] = True+ try:+ subprocess.Popen([sys.executable, "-m", DAEMON_MODULE, "--port", str(port)], **options)+ except OSError:+ return False+ finally:+ if log_file is not None:+ log_file.close()+ return True+ finally:+ _release_spawn_lock(lock)+++def _open_daemon_log() -> IO[bytes] | None:+ try:+ _state_dir().mkdir(parents=True, exist_ok=True, mode=0o700)+ path = _state_dir() / _LOG_NAME+ if path.exists() and path.stat().st_size > _MAX_LOG_BYTES:+ path.unlink()+ descriptor = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_APPEND, 0o600)+ return os.fdopen(descriptor, "ab")+ except OSError:+ return None+++class _UnlockedSpawnLock:+ """Stand-in for platforms or filesystems where the advisory lock is unavailable."""++ def close(self) -> None:+ return+++_SpawnLock = IO[bytes] | _UnlockedSpawnLock+++def _acquire_spawn_lock() -> _SpawnLock | None:+ try:+ import fcntl # noqa: PLC0415+ except ImportError:+ # Windows has no flock; bind election alone still guarantees a single daemon.+ return _UnlockedSpawnLock()++ try:+ _state_dir().mkdir(parents=True, exist_ok=True, mode=0o700)+ descriptor = os.open(_state_dir() / _SPAWN_LOCK_NAME, os.O_RDWR | os.O_CREAT, 0o600)+ except OSError:+ return _UnlockedSpawnLock()+ handle = os.fdopen(descriptor, "r+b")+ try:+ fcntl.flock(handle.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)+ except OSError:+ handle.close()+ return None+ return handle+++def _spawned_recently(lock: _SpawnLock) -> bool:+ if isinstance(lock, _UnlockedSpawnLock):+ return False+ try:+ lock.seek(0)+ stamp = float(lock.read(64) or b"0")+ except (OSError, ValueError):+ return False+ # _stamp_spawn rounds to milliseconds, so a stamp can read fractionally ahead of now.+ # A negative elapsed means someone stamped it a moment ago, not that the clock is wrong;+ # only a jump larger than the cooldown is treated as stale enough to spawn again.+ elapsed = time.time() - stamp+ return abs(elapsed) < _SPAWN_COOLDOWN_SECONDS+++def _stamp_spawn(lock: _SpawnLock) -> None:+ if isinstance(lock, _UnlockedSpawnLock):+ return+ with suppress(OSError):+ lock.seek(0)+ lock.truncate()+ lock.write(f"{time.time():.3f}".encode("ascii"))+ lock.flush()+++def _release_spawn_lock(lock: _SpawnLock) -> None:+ with suppress(OSError, ValueError):+ lock.close()+++async def run_daemon(port: int, idle_timeout_seconds: float) -> int:+ token = load_or_create_pairing_token()+ server = BrokerServer(token, port, idle_timeout_seconds=idle_timeout_seconds)+ try:+ await server.start()+ except OSError as exc:+ if exc.errno == errno.EADDRINUSE:+ LOG.info("browser_extension_broker_election_lost", port=port)+ return 0+ raise++ loop = asyncio.get_running_loop()+ for signal_name in ("SIGINT", "SIGTERM"):+ handled_signal = getattr(signal, signal_name, None)+ if handled_signal is None:+ continue+ with suppress(NotImplementedError, ValueError):+ loop.add_signal_handler(handled_signal, server.request_shutdown, "signal")++ try:+ await server.wait_for_shutdown()+ finally:+ await server.stop()+ return 0+++def main(argv: list[str] | None = None) -> int:+ parser = argparse.ArgumentParser(prog=DAEMON_MODULE, description="Skyvern browser-extension bridge broker")+ parser.add_argument("--port", type=int, required=True)+ parser.add_argument("--idle-timeout-seconds", type=float, default=None)+ arguments = parser.parse_args(argv)++ idle_timeout = arguments.idle_timeout_seconds+ if idle_timeout is None:+ idle_timeout = resolve_idle_timeout_seconds()+ try:+ return asyncio.run(run_daemon(arguments.port, idle_timeout))+ except KeyboardInterrupt:+ return 0+++if __name__ == "__main__":+ raise SystemExit(main())diff --git a/skyvern/browser_extension/broker/leases.py b/skyvern/browser_extension/broker/leases.pynew file mode 100644index 000000000..041ebd86a--- /dev/null+++ b/skyvern/browser_extension/broker/leases.py@@ -0,0 +1,166 @@+from __future__ import annotations++from dataclasses import dataclass++DEFAULT_OFFER_TTL_SECONDS = 30.0+++@dataclass(frozen=True, slots=True)+class OfferChange:+ client_id: str+ tab: dict+++class LeaseTable:+ """Assigns each shared Chrome tab to at most one broker client.++ A client sees a tab only once the tab is leased to it or offered to it, so two agents never+ race for the same tab. Tabs an agent opens are leased to it outright; tabs the user shares by+ hand start unowned and are offered, one at a time, to an agent that currently holds nothing.+ """++ def __init__(self, offer_ttl_seconds: float = DEFAULT_OFFER_TTL_SECONDS) -> None:+ self._offer_ttl_seconds = offer_ttl_seconds+ self._tabs: dict[int, dict] = {}+ self._leases: dict[int, str] = {}+ self._offers: dict[int, str] = {}+ self._offer_deadlines: dict[int, float] = {}+ self._queue: list[str] = []++ def add_client(self, client_id: str) -> None:+ if client_id not in self._queue:+ self._queue.append(client_id)++ def remove_client(self, client_id: str) -> tuple[list[int], list[int]]:+ """Release everything the client held, as (leased, offered).++ Only the leased tabs were ever attached, so only those need detaching.+ """+ if client_id in self._queue:+ self._queue.remove(client_id)+ leased = [tab_id for tab_id, owner in self._leases.items() if owner == client_id]+ offered = [tab_id for tab_id, owner in self._offers.items() if owner == client_id]+ for tab_id in leased:+ del self._leases[tab_id]+ for tab_id in offered:+ self._release_offer(tab_id)+ return leased, offered++ def register_tab(self, tab: dict) -> None:+ tab_id = tab.get("tabId")+ if type(tab_id) is not int:+ return+ self._tabs[tab_id] = dict(tab)++ def forget_tab(self, tab_id: int) -> str | None:+ self._tabs.pop(tab_id, None)+ owner = self._leases.pop(tab_id, None) or self._offers.get(tab_id)+ self._release_offer(tab_id)+ return owner++ def reset(self, tabs: list[dict]) -> None:+ """Drop every lease and offer, then re-register the extension's current scope.++ Called when the extension reconnects: Chrome tore down every debugger attachment, so no+ client's claim on a tab survived.+ """+ self._tabs = {}+ self._leases = {}+ self._offers = {}+ self._offer_deadlines = {}+ for tab in tabs:+ self.register_tab(tab)++ def owner(self, tab_id: int) -> str | None:+ return self._leases.get(tab_id) or self._offers.get(tab_id)++ def lessee(self, tab_id: int) -> str | None:+ return self._leases.get(tab_id)++ def knows_tab(self, tab_id: int) -> bool:+ return tab_id in self._tabs++ def grant(self, tab_id: int, client_id: str, tab: dict | None = None) -> None:+ """Lease a tab to a client unconditionally — used for tabs that client just opened."""+ if tab is not None:+ self.register_tab(tab)+ elif tab_id not in self._tabs:+ self._tabs[tab_id] = {"tabId": tab_id, "url": "", "title": ""}+ self._release_offer(tab_id)+ self._leases[tab_id] = client_id++ def claim(self, tab_id: int, client_id: str) -> bool:+ """Convert this client's offer into a lease, or confirm a lease it already holds."""+ current = self._leases.get(tab_id)+ if current is not None:+ return current == client_id+ if self._offers.get(tab_id) != client_id:+ return False+ self._release_offer(tab_id)+ self._leases[tab_id] = client_id+ return True++ def release(self, tab_id: int, client_id: str) -> bool:+ if self._leases.get(tab_id) != client_id:+ return False+ del self._leases[tab_id]+ return True++ def visible_tabs(self, client_id: str) -> list[dict]:+ return [+ dict(tab)+ for tab_id, tab in self._tabs.items()+ if self._leases.get(tab_id) == client_id or self._offers.get(tab_id) == client_id+ ]++ def rotate(self, now: float) -> tuple[list[OfferChange], list[OfferChange]]:+ """Expire stale offers and hand unowned tabs to idle clients.++ Returns the offers granted and the offers revoked, so the caller can tell each client+ which tabs entered or left its scope.+ """+ revoked = [+ OfferChange(client_id=self._offers[tab_id], tab=dict(self._tabs.get(tab_id, {"tabId": tab_id})))+ for tab_id, deadline in list(self._offer_deadlines.items())+ if deadline <= now+ ]+ for change in revoked:+ self._release_offer(change.tab["tabId"])++ granted: list[OfferChange] = []+ for tab_id in list(self._tabs):+ if tab_id in self._leases or tab_id in self._offers:+ continue+ client_id = self._next_eligible_client()+ if client_id is None:+ break+ self._offers[tab_id] = client_id+ self._offer_deadlines[tab_id] = now + self._offer_ttl_seconds+ self._queue.remove(client_id)+ self._queue.append(client_id)+ granted.append(OfferChange(client_id=client_id, tab=dict(self._tabs[tab_id])))++ # When the only candidate is the client whose offer just lapsed, its view never changed.+ # Cancelling the pair keeps a lone idle agent from churning the tab out of scope and back.+ renewed = {_key(change) for change in granted} & {_key(change) for change in revoked}+ if not renewed:+ return granted, revoked+ return (+ [change for change in granted if _key(change) not in renewed],+ [change for change in revoked if _key(change) not in renewed],+ )++ def next_rotation_deadline(self) -> float | None:+ return min(self._offer_deadlines.values(), default=None)++ def _next_eligible_client(self) -> str | None:+ busy = set(self._leases.values()) | set(self._offers.values())+ return next((client_id for client_id in self._queue if client_id not in busy), None)++ def _release_offer(self, tab_id: int) -> None:+ self._offers.pop(tab_id, None)+ self._offer_deadlines.pop(tab_id, None)+++def _key(change: OfferChange) -> tuple[str, int]:+ return change.client_id, change.tab["tabId"]diff --git a/skyvern/browser_extension/broker/protocol.py b/skyvern/browser_extension/broker/protocol.pynew file mode 100644index 000000000..02d3de3ad--- /dev/null+++ b/skyvern/browser_extension/broker/protocol.py@@ -0,0 +1,278 @@+from __future__ import annotations++import base64+import hashlib+import hmac+import json+import secrets+from dataclasses import dataclass+from typing import Literal, cast++from skyvern.browser_extension.errors import BrowserExtensionError++BROKER_WS_PATH = "/broker/v1"+BROKER_HEALTH_PATH = "/broker/health"++# Envelope shape ({"v": ..., "type": ...}). Never bumped: a client and a daemon must be able to+# complete the handshake before they can negotiate anything else.+BROKER_FRAME_VERSION = 1++# Broker semantics. Bumped whenever client and daemon behaviour stops being interchangeable;+# exchanged only after authentication so version skew can never be probed anonymously.+BROKER_PROTOCOL_VERSION = 1++_CLIENT_PROOF_CONTEXT = "skyvern-broker-v1"+_SERVER_PROOF_CONTEXT = "skyvern-broker-srv-v1"++# Broker-only operations. They never reach the extension, so they sit outside ALLOWED_OPS.+PAIRING_NONCE_OP = "broker.pairingNonce"+STATUS_OP = "broker.status"++# Reported when the daemon is healthy but no extension is attached to it.+EXTENSION_NOT_CONNECTED_CODE = "EXTENSION_NOT_CONNECTED"++BrokerFrameKind = Literal[+ "auth.challenge",+ "auth.proof",+ "auth.ok",+ "client.hello",+ "broker.state",+ "broker.stepDown",+ "request",+ "response",+ "event",+ "ping",+ "pong",+]++_CLIENT_FRAME_KINDS = frozenset({"auth.proof", "client.hello", "broker.stepDown", "request", "ping", "pong"})+_SERVER_FRAME_KINDS = frozenset({"auth.challenge", "auth.ok", "broker.state", "response", "event", "ping", "pong"})+++@dataclass(frozen=True, slots=True)+class BrokerFrame:+ kind: BrokerFrameKind+ request_id: str | None = None+ op: str | None = None+ args: dict | None = None+ timeout_seconds: float | None = None+ ok: bool | None = None+ result: dict | None = None+ error_code: str | None = None+ error_message: str | None = None+ event: str | None = None+ params: dict | None = None+ client_nonce: str | None = None+ server_nonce: str | None = None+ proof: str | None = None+ protocol: int | None = None+ pid: int | None = None+ root: str | None = None+ extension_connected: bool | None = None+ scoped_tabs: list[dict] | None = None+++def build_broker_nonce() -> str:+ return _b64url(secrets.token_bytes(32))+++def build_broker_challenge() -> tuple[str, dict]:+ server_nonce = build_broker_nonce()+ return server_nonce, {"v": BROKER_FRAME_VERSION, "type": "auth.challenge", "serverNonce": server_nonce}+++def compute_broker_client_proof(token: str, server_nonce: str, client_nonce: str) -> str:+ return _compute_proof(token, f"{_CLIENT_PROOF_CONTEXT}|{server_nonce}|{client_nonce}")+++def compute_broker_server_proof(token: str, client_nonce: str, server_nonce: str) -> str:+ return _compute_proof(token, f"{_SERVER_PROOF_CONTEXT}|{client_nonce}|{server_nonce}")+++def verify_broker_client_proof(token: str, server_nonce: str, client_nonce: str, proof: str) -> bool:+ expected = compute_broker_client_proof(token, server_nonce, client_nonce)+ try:+ return hmac.compare_digest(expected, proof)+ except TypeError:+ return False+++def is_valid_broker_nonce(nonce: str) -> bool:+ if not nonce or "=" in nonce:+ return False+ padding = "=" * (-len(nonce) % 4)+ try:+ decoded = base64.b64decode(nonce + padding, altchars=b"-_", validate=True)+ except (ValueError, TypeError):+ return False+ return len(decoded) == 32 and _b64url(decoded) == nonce+++def build_request_frame(request_id: str, op: str, args: dict, timeout_seconds: float) -> dict:+ return {+ "v": BROKER_FRAME_VERSION,+ "type": "request",+ "id": request_id,+ "op": op,+ "args": args,+ "timeoutMs": int(max(timeout_seconds, 0.0) * 1000),+ }+++def build_response_frame(request_id: str, result: dict) -> dict:+ return {"v": BROKER_FRAME_VERSION, "type": "response", "id": request_id, "ok": True, "result": result}+++def build_error_frame(request_id: str, code: str, message: str) -> dict:+ return {+ "v": BROKER_FRAME_VERSION,+ "type": "response",+ "id": request_id,+ "ok": False,+ "error": {"code": code, "message": message},+ }+++def build_event_frame(event: str, params: dict) -> dict:+ return {"v": BROKER_FRAME_VERSION, "type": "event", "event": event, "params": params}+++def build_state_frame(extension_connected: bool, scoped_tabs: list[dict]) -> dict:+ return {+ "v": BROKER_FRAME_VERSION,+ "type": "broker.state",+ "extensionConnected": extension_connected,+ "scopedTabs": scoped_tabs,+ }+++def parse_broker_frame(raw: str, *, from_client: bool) -> BrokerFrame:+ try:+ payload = json.loads(raw)+ except (json.JSONDecodeError, TypeError, UnicodeDecodeError) as exc:+ raise BrowserExtensionError("Broker frame is not valid JSON") from exc+ if not isinstance(payload, dict):+ raise BrowserExtensionError("Broker frame must be an object")+ if type(payload.get("v")) is not int or payload["v"] != BROKER_FRAME_VERSION:+ raise BrowserExtensionError("Unsupported broker frame version")++ raw_kind = payload.get("type")+ allowed = _CLIENT_FRAME_KINDS if from_client else _SERVER_FRAME_KINDS+ if not isinstance(raw_kind, str) or raw_kind not in allowed:+ raise BrowserExtensionError("Unknown broker frame type")+ kind = cast(BrokerFrameKind, raw_kind)++ if kind in {"ping", "pong"}:+ return BrokerFrame(kind=kind)+ if kind == "auth.challenge":+ return BrokerFrame(kind=kind, server_nonce=_required_string(payload, "serverNonce"))+ if kind == "auth.proof":+ return BrokerFrame(+ kind=kind,+ client_nonce=_required_string(payload, "clientNonce"),+ proof=_required_string(payload, "proof"),+ )+ if kind == "auth.ok":+ return BrokerFrame(+ kind=kind,+ proof=_required_string(payload, "serverProof"),+ protocol=_required_int(payload, "protocol"),+ pid=_required_int(payload, "pid"),+ root=_required_string(payload, "root"),+ )+ if kind == "client.hello":+ return BrokerFrame(kind=kind, protocol=_required_int(payload, "protocol"), pid=_required_int(payload, "pid"))+ if kind == "broker.stepDown":+ return BrokerFrame(kind=kind, protocol=_required_int(payload, "protocol"))+ if kind == "broker.state":+ return BrokerFrame(+ kind=kind,+ extension_connected=_required_bool(payload, "extensionConnected"),+ scoped_tabs=_tab_list(payload.get("scopedTabs")),+ )+ if kind == "request":+ return _parse_request(payload)+ if kind == "response":+ return _parse_response(payload)+ return _parse_event(payload)+++def _parse_request(payload: dict) -> BrokerFrame:+ timeout_ms = payload.get("timeoutMs")+ if type(timeout_ms) is not int or timeout_ms <= 0:+ raise BrowserExtensionError("Broker request timeout must be a positive integer")+ return BrokerFrame(+ kind="request",+ request_id=_required_string(payload, "id"),+ op=_required_string(payload, "op"),+ args=_required_dict(payload, "args"),+ timeout_seconds=timeout_ms / 1000,+ )+++def _parse_response(payload: dict) -> BrokerFrame:+ request_id = _required_string(payload, "id")+ ok = payload.get("ok")+ if type(ok) is not bool:+ raise BrowserExtensionError("Broker response ok must be a boolean")+ if ok:+ return BrokerFrame(kind="response", request_id=request_id, ok=True, result=_required_dict(payload, "result"))+ error = _required_dict(payload, "error")+ return BrokerFrame(+ kind="response",+ request_id=request_id,+ ok=False,+ error_code=_required_string(error, "code"),+ error_message=_required_string(error, "message"),+ )+++def _parse_event(payload: dict) -> BrokerFrame:+ return BrokerFrame(+ kind="event",+ event=_required_string(payload, "event"),+ params=_required_dict(payload, "params"),+ )+++def _tab_list(value: object) -> list[dict]:+ if not isinstance(value, list):+ raise BrowserExtensionError("Broker frame field scopedTabs must be an array")+ return [tab for tab in value if isinstance(tab, dict) and type(tab.get("tabId")) is int]+++def _required_string(payload: dict, field: str) -> str:+ value = payload.get(field)+ if not isinstance(value, str) or not value:+ raise BrowserExtensionError(f"Broker frame field {field} must be a non-empty string")+ return value+++def _required_dict(payload: dict, field: str) -> dict:+ value = payload.get(field)+ if not isinstance(value, dict):+ raise BrowserExtensionError(f"Broker frame field {field} must be an object")+ return value+++def _required_int(payload: dict, field: str) -> int:+ value = payload.get(field)+ if type(value) is not int:+ raise BrowserExtensionError(f"Broker frame field {field} must be an integer")+ return value+++def _required_bool(payload: dict, field: str) -> bool:+ value = payload.get(field)+ if type(value) is not bool:+ raise BrowserExtensionError(f"Broker frame field {field} must be a boolean")+ return value+++def _compute_proof(token: str, message: str) -> str:+ digest = hmac.new(token.encode("utf-8"), message.encode("utf-8"), hashlib.sha256).digest()+ return _b64url(digest)+++def _b64url(value: bytes) -> str:+ return base64.urlsafe_b64encode(value).rstrip(b"=").decode("ascii")diff --git a/skyvern/browser_extension/broker/server.py b/skyvern/browser_extension/broker/server.pynew file mode 100644index 000000000..1ab54a51f--- /dev/null+++ b/skyvern/browser_extension/broker/server.py@@ -0,0 +1,621 @@+from __future__ import annotations++import asyncio+import itertools+import os+import time+from collections.abc import Awaitable, Callable, Coroutine+from contextlib import suppress+from pathlib import Path++import structlog+from aiohttp import WSMsgType, web++from skyvern.browser_extension.broker.leases import LeaseTable+from skyvern.browser_extension.broker.protocol import (+ BROKER_FRAME_VERSION,+ BROKER_HEALTH_PATH,+ BROKER_PROTOCOL_VERSION,+ BROKER_WS_PATH,+ EXTENSION_NOT_CONNECTED_CODE,+ PAIRING_NONCE_OP,+ STATUS_OP,+ BrokerFrame,+ build_broker_challenge,+ build_error_frame,+ build_event_frame,+ build_response_frame,+ build_state_frame,+ compute_broker_server_proof,+ is_valid_broker_nonce,+ parse_broker_frame,+ verify_broker_client_proof,+)+from skyvern.browser_extension.errors import (+ BrowserExtensionError,+ BrowserExtensionNotConnectedError,+ ExtensionRequestError,+)+from skyvern.browser_extension.protocol import ALLOWED_OPS+from skyvern.browser_extension.relay import _MAX_WS_MESSAGE_BYTES, ExtensionRelayServer++LOG = structlog.get_logger(__name__)++_AUTH_TIMEOUT_SECONDS = 10.0+_HELLO_TIMEOUT_SECONDS = 10.0+_MAINTENANCE_INTERVAL_SECONDS = 5.0+_MAX_REQUEST_TIMEOUT_SECONDS = 600.0+_AUTH_CLOSE_CODE = 4403+_STEP_DOWN_CLOSE_CODE = 4001++RelayFactory = Callable[+ [str, int, Callable[[str, dict], Awaitable[None]], Callable[[], Awaitable[None]] | None],+ ExtensionRelayServer,+]+++class _ClientConnection:+ def __init__(self, client_id: str, websocket: web.WebSocketResponse) -> None:+ self.client_id = client_id+ self.websocket = websocket+ self.protocol = BROKER_PROTOCOL_VERSION+ self.pid = 0+ self.tasks: set[asyncio.Task[None]] = set()+ self._send_lock = asyncio.Lock()++ def spawn(self, coroutine: Coroutine[None, None, None]) -> None:+ task = asyncio.create_task(coroutine)+ self.tasks.add(task)+ task.add_done_callback(self.tasks.discard)++ async def cancel_tasks(self) -> None:+ tasks = list(self.tasks)+ self.tasks.clear()+ for task in tasks:+ task.cancel()+ for task in tasks:+ with suppress(asyncio.CancelledError, Exception):+ await task++ async def send(self, frame: dict) -> bool:+ if self.websocket.closed:+ return False+ async with self._send_lock:+ try:+ await self.websocket.send_json(frame)+ except (ConnectionError, RuntimeError, ValueError):+ return False+ return True+++class BrokerServer:+ """Singleton owner of the extension bridge port, fronting many local MCP clients.++ The Chrome extension still dials one socket; every `skyvern run mcp --browser-extension`+ process attaches as an authenticated loopback client and gets its own leased slice of the+ shared tabs.+ """++ def __init__(+ self,+ token: str,+ port: int,+ *,+ idle_timeout_seconds: float = 300.0,+ relay_factory: RelayFactory = ExtensionRelayServer,+ ) -> None:+ self._token = token+ self._idle_timeout_seconds = idle_timeout_seconds+ self._leases = LeaseTable()+ self._clients: dict[str, _ClientConnection] = {}+ self._client_ids = itertools.count(1)+ self._relay = relay_factory(token, port, self._handle_extension_event, self._handle_extension_disconnect)+ self._relay.add_route(BROKER_WS_PATH, self._handle_client_websocket)+ self._relay.add_route(BROKER_HEALTH_PATH, self._handle_health)+ self._lease_lock = asyncio.Lock()+ self._tab_creates_in_flight = 0+ self._deferred_tab_added: dict[int, dict] = {}+ self._deferred_tab_created: dict[int, dict] = {}+ self._discarded_tab_ids: set[int] = set()+ self._extension_generation = 0+ self._maintenance_task: asyncio.Task[None] | None = None+ self._shutdown_event = asyncio.Event()+ self._shutdown_reason = "stopped"+ self._idle_since: float | None = None+ self._started = False++ @property+ def bound_port(self) -> int:+ return self._relay.bound_port++ @property+ def client_count(self) -> int:+ return len(self._clients)++ @property+ def shutdown_reason(self) -> str:+ return self._shutdown_reason++ async def start(self) -> None:+ await self._relay.start()+ self._started = True+ self._idle_since = time.monotonic()+ self._maintenance_task = asyncio.create_task(self._run_maintenance())+ LOG.info(+ "browser_extension_broker_started",+ port=self._relay.bound_port,+ protocol=BROKER_PROTOCOL_VERSION,+ pid=os.getpid(),+ )++ async def stop(self) -> None:+ if not self._started:+ return+ self._started = False+ task = self._maintenance_task+ self._maintenance_task = None+ if task is not None:+ task.cancel()+ with suppress(asyncio.CancelledError):+ await task+ for client in list(self._clients.values()):+ if not client.websocket.closed:+ await client.websocket.close(code=1001, message=b"broker stopped")+ await self._relay.stop()+ LOG.info("browser_extension_broker_stopped", reason=self._shutdown_reason)++ async def wait_for_shutdown(self) -> str:+ await self._shutdown_event.wait()+ return self._shutdown_reason++ def request_shutdown(self, reason: str) -> None:+ if not self._shutdown_event.is_set():+ self._shutdown_reason = reason+ self._shutdown_event.set()++ async def _handle_health(self, _request: web.Request) -> web.Response:+ # Deliberately inert: it tells a caller a broker owns this port and nothing else. No token,+ # nonce, pid, client count, or tab data — the same posture as a bare GET /pair.+ return web.json_response(+ {"v": BROKER_FRAME_VERSION, "broker": True, "protocol": BROKER_PROTOCOL_VERSION},+ headers={"Cache-Control": "no-store", "X-Content-Type-Options": "nosniff"},+ )++ async def _handle_client_websocket(self, request: web.Request) -> web.WebSocketResponse:+ # The heartbeat is what releases a SIGKILLed agent's tab leases.+ websocket = web.WebSocketResponse(max_msg_size=_MAX_WS_MESSAGE_BYTES, heartbeat=20.0)+ # Browsers always attach an Origin to a WebSocket handshake, so requiring its absence keeps+ # a malicious page from reaching the broker even though WebSockets bypass CORS.+ if request.headers.get("Origin") is not None:+ await websocket.prepare(request)+ LOG.info("browser_extension_broker_client_rejected", reason="origin_present")+ await websocket.close(code=_AUTH_CLOSE_CODE, message=b"authentication failed")+ return websocket++ await websocket.prepare(request)+ client = await self._authenticate(websocket)+ if client is None:+ return websocket++ await self._register_client(client)+ try:+ async for message in websocket:+ if message.type is WSMsgType.TEXT:+ if not await self._handle_client_text(client, message.data):+ break+ elif message.type in {WSMsgType.CLOSE, WSMsgType.CLOSED, WSMsgType.ERROR}:+ break+ else:+ await websocket.close(code=1003, message=b"text frames required")+ break+ finally:+ await client.cancel_tasks()+ await self._unregister_client(client)+ return websocket++ async def _authenticate(self, websocket: web.WebSocketResponse) -> _ClientConnection | None:+ server_nonce, challenge = build_broker_challenge()+ await websocket.send_json(challenge)+ proof = await self._receive_frame(websocket, _AUTH_TIMEOUT_SECONDS)+ if proof is None or proof.kind != "auth.proof" or proof.client_nonce is None or proof.proof is None:+ await self._reject(websocket, "bad_payload")+ return None+ if not is_valid_broker_nonce(proof.client_nonce):+ await self._reject(websocket, "bad_nonce")+ return None+ if not verify_broker_client_proof(self._token, server_nonce, proof.client_nonce, proof.proof):+ await self._reject(websocket, "bad_proof")+ return None++ await websocket.send_json(+ {+ "v": BROKER_FRAME_VERSION,+ "type": "auth.ok",+ "serverProof": compute_broker_server_proof(self._token, proof.client_nonce, server_nonce),+ "protocol": BROKER_PROTOCOL_VERSION,+ "pid": os.getpid(),+ "root": str(Path(__file__).resolve().parents[3]),+ }+ )++ hello = await self._receive_frame(websocket, _HELLO_TIMEOUT_SECONDS)+ if hello is None:+ await self._reject(websocket, "bad_payload")+ return None+ if hello.kind == "broker.stepDown":+ await self._handle_step_down(websocket, hello)+ return None+ if hello.kind != "client.hello" or hello.protocol is None or hello.pid is None:+ await self._reject(websocket, "bad_payload")+ return None++ client = _ClientConnection(f"c-{next(self._client_ids)}", websocket)+ client.protocol = hello.protocol+ client.pid = hello.pid+ return client++ async def _receive_frame(self, websocket: web.WebSocketResponse, timeout: float) -> BrokerFrame | None:+ try:+ message = await websocket.receive(timeout=timeout)+ except TimeoutError:+ return None+ if message.type is not WSMsgType.TEXT:+ return None+ try:+ return parse_broker_frame(message.data, from_client=True)+ except BrowserExtensionError:+ return None++ async def _reject(self, websocket: web.WebSocketResponse, reason: str) -> None:+ LOG.info("browser_extension_broker_client_rejected", reason=reason)+ await websocket.close(code=_AUTH_CLOSE_CODE, message=b"authentication failed")++ async def _handle_step_down(self, websocket: web.WebSocketResponse, frame: BrokerFrame) -> None:+ requested = frame.protocol or 0+ if requested <= BROKER_PROTOCOL_VERSION:+ LOG.info(+ "browser_extension_broker_step_down_declined",+ requested_protocol=requested,+ protocol=BROKER_PROTOCOL_VERSION,+ )+ await websocket.close(code=_STEP_DOWN_CLOSE_CODE, message=b"step down declined")+ return+ LOG.info(+ "browser_extension_broker_step_down_accepted",+ requested_protocol=requested,+ protocol=BROKER_PROTOCOL_VERSION,+ )+ await websocket.close(code=_STEP_DOWN_CLOSE_CODE, message=b"stepping down")+ self.request_shutdown("version_skew")++ async def _register_client(self, client: _ClientConnection) -> None:+ self._clients[client.client_id] = client+ self._idle_since = None+ async with self._lease_lock:+ self._leases.add_client(client.client_id)+ visible = self._leases.visible_tabs(client.client_id)+ LOG.info(+ "browser_extension_broker_client_connected",+ client_id=client.client_id,+ client_pid=client.pid,+ client_protocol=client.protocol,+ clients=len(self._clients),+ )+ await client.send(build_state_frame(self._relay.connected, visible))+ await self._rotate_offers()++ async def _unregister_client(self, client: _ClientConnection) -> None:+ if self._clients.pop(client.client_id, None) is None:+ return+ async with self._lease_lock:+ leased, offered = self._leases.remove_client(client.client_id)+ if not self._clients:+ self._idle_since = time.monotonic()+ LOG.info(+ "browser_extension_broker_client_disconnected",+ client_id=client.client_id,+ released_leases=len(leased),+ released_offers=len(offered),+ clients=len(self._clients),+ )+ await self._detach_released_tabs(leased)+ await self._rotate_offers()++ async def _detach_released_tabs(self, tab_ids: list[int]) -> None:+ for tab_id in tab_ids:+ try:+ await self._relay.request("debugger.detach", {"tabId": tab_id}, timeout=2.0)+ except Exception as exc:+ LOG.debug(+ "browser_extension_broker_release_detach_failed",+ tab_id=tab_id,+ error_type=type(exc).__name__,+ )++ async def _handle_client_text(self, client: _ClientConnection, raw: str) -> bool:+ try:+ frame = parse_broker_frame(raw, from_client=True)+ except BrowserExtensionError:+ LOG.warning("browser_extension_broker_invalid_frame", client_id=client.client_id)+ return True++ if frame.kind == "ping":+ await client.send({"v": BROKER_FRAME_VERSION, "type": "pong"})+ return True+ if frame.kind == "pong":+ return True+ if frame.kind == "broker.stepDown":+ await self._handle_step_down(client.websocket, frame)+ return False+ if frame.kind == "request" and frame.request_id is not None and frame.op is not None:+ client.spawn(self._run_request(client, frame))+ return True+ return True++ async def _run_request(self, client: _ClientConnection, frame: BrokerFrame) -> None:+ request_id = frame.request_id or ""+ op = frame.op or ""+ args = frame.args or {}+ timeout = min(frame.timeout_seconds or 30.0, _MAX_REQUEST_TIMEOUT_SECONDS)+ try:+ result = await self._dispatch(client, op, args, timeout)+ except ExtensionRequestError as exc:+ await client.send(build_error_frame(request_id, exc.code, exc.message))+ except BrowserExtensionNotConnectedError:+ await client.send(+ build_error_frame(+ request_id, EXTENSION_NOT_CONNECTED_CODE, "Skyvern browser extension is not connected"+ )+ )+ except asyncio.CancelledError:+ raise+ except Exception as exc:+ LOG.exception("browser_extension_broker_request_failed", client_id=client.client_id, op=op)+ await client.send(build_error_frame(request_id, "INTERNAL", f"broker request failed: {type(exc).__name__}"))+ else:+ await client.send(build_response_frame(request_id, result))++ async def _dispatch(self, client: _ClientConnection, op: str, args: dict, timeout: float) -> dict:+ if op == PAIRING_NONCE_OP:+ LOG.info("browser_extension_broker_pairing_nonce_issued", client_id=client.client_id)+ return {"nonce": self._relay.create_pairing_nonce(), "port": self._relay.bound_port}+ if op == STATUS_OP:+ return {+ "extensionConnected": self._relay.connected,+ "clients": len(self._clients),+ "protocol": BROKER_PROTOCOL_VERSION,+ "pid": os.getpid(),+ }+ if op not in ALLOWED_OPS:+ raise ExtensionRequestError("OP_NOT_ALLOWED", f"Operation is not allowed: {op}")++ if op == "tabs.create":+ async with self._lease_lock:+ self._tab_creates_in_flight += 1+ extension_generation = self._extension_generation+ try:+ result = await self._relay.request(op, args, timeout)+ tab_id = result.get("tabId")+ deferred_event = None+ deferred_created_events: list[dict] = []+ granted = False+ if type(tab_id) is int:+ url = args.get("url")+ async with self._lease_lock:+ deferred_event = self._deferred_tab_added.pop(tab_id, None)+ deferred_created_events = self._pop_deferred_descendants(tab_id)+ discarded = (+ tab_id in self._discarded_tab_ids or extension_generation != self._extension_generation+ )+ self._discarded_tab_ids.discard(tab_id)+ if not discarded:+ self._leases.grant(+ tab_id,+ client.client_id,+ _tab_snapshot(deferred_event)+ if deferred_event is not None+ else {+ "tabId": tab_id,+ "url": url if isinstance(url, str) else "about:blank",+ "title": "",+ },+ )+ for event in deferred_created_events:+ self._leases.grant(event["tabId"], client.client_id, _tab_snapshot(event))+ granted = True+ if granted:+ if deferred_event is not None:+ await self._send_to(client.client_id, build_event_frame("scope.tabAdded", deferred_event))+ for event in deferred_created_events:+ await self._send_to(client.client_id, build_event_frame("tabs.created", event))+ return result+ finally:+ async with self._lease_lock:+ self._tab_creates_in_flight -= 1+ deferred_tabs = []+ if self._tab_creates_in_flight == 0:+ deferred_tabs = [+ *self._deferred_tab_added.values(),+ *self._deferred_tab_created.values(),+ ]+ self._deferred_tab_added.clear()+ self._deferred_tab_created.clear()+ self._discarded_tab_ids.clear()+ for deferred_tab in deferred_tabs:+ self._leases.register_tab(_tab_snapshot(deferred_tab))+ if deferred_tabs:+ await self._rotate_offers()++ if op == "tabs.list":+ result = await self._relay.request(op, args, timeout)+ async with self._lease_lock:+ visible = {tab["tabId"] for tab in self._leases.visible_tabs(client.client_id)}+ tabs = result.get("tabs")+ if isinstance(tabs, list):+ return {+ **result,+ "tabs": [tab for tab in tabs if isinstance(tab, dict) and tab.get("tabId") in visible],+ }+ return result++ tab_id = args.get("tabId")+ if type(tab_id) is float and tab_id.is_integer():+ tab_id = int(tab_id)+ if type(tab_id) is not int:+ raise ExtensionRequestError("TAB_NOT_SCOPED", "Another Skyvern agent controls this tab.")+ async with self._lease_lock:+ claimed = self._leases.claim(tab_id, client.client_id)+ if not claimed:+ raise ExtensionRequestError("TAB_NOT_SCOPED", "Another Skyvern agent controls this tab.")+ return await self._relay.request(op, {**args, "tabId": tab_id}, timeout)++ async def _handle_extension_event(self, event: str, params: dict) -> None:+ if event == "extension.hello":+ await self._handle_extension_hello(params)+ return+ if event == "scope.tabAdded":+ tab_id = params.get("tabId")+ if type(tab_id) is not int:+ return+ async with self._lease_lock:+ owner = self._leases.owner(tab_id)+ if owner is None and self._tab_creates_in_flight:+ if tab_id in self._discarded_tab_ids:+ return+ self._deferred_tab_added[tab_id] = dict(params)+ return+ self._leases.register_tab(_tab_snapshot(params))+ # A tab an agent just opened is already leased to it; only a hand-shared tab is+ # unowned and needs an offer.+ if owner is not None:+ await self._send_to(owner, build_event_frame(event, params))+ return+ await self._rotate_offers()+ return+ if event == "tabs.created":+ await self._handle_tab_created(params)+ return+ if event in {"scope.tabRemoved", "debugger.detached"}:+ tab_id = params.get("tabId")+ if type(tab_id) is not int:+ return+ async with self._lease_lock:+ deferred = self._deferred_tab_added.pop(tab_id, None)+ deferred_created = self._deferred_tab_created.pop(tab_id, None)+ deferred_descendants = self._pop_deferred_descendants(tab_id)+ if deferred is not None or deferred_created is not None or deferred_descendants:+ self._discarded_tab_ids.add(tab_id)+ owner = self._leases.forget_tab(tab_id)+ if owner is not None:+ await self._send_to(owner, build_event_frame(event, params))+ await self._rotate_offers()+ return+ if event == "debugger.event":+ tab_id = params.get("tabId")+ if type(tab_id) is not int:+ return+ async with self._lease_lock:+ owner = self._leases.lessee(tab_id)+ if owner is not None:+ await self._send_to(owner, build_event_frame(event, params))++ async def _handle_extension_hello(self, params: dict) -> None:+ tabs = params.get("scopedTabs")+ candidates = tabs if isinstance(tabs, list) else []+ snapshots = [tab for tab in candidates if isinstance(tab, dict) and type(tab.get("tabId")) is int]+ async with self._lease_lock:+ self._deferred_tab_added.clear()+ self._deferred_tab_created.clear()+ self._discarded_tab_ids.clear()+ self._leases.reset(snapshots)+ per_client = {client_id: self._leases.visible_tabs(client_id) for client_id in list(self._clients)}+ for client_id, visible in per_client.items():+ await self._send_to(client_id, build_event_frame("extension.hello", {**params, "scopedTabs": visible}))+ await self._rotate_offers()++ async def _handle_tab_created(self, params: dict) -> None:+ tab_id = params.get("tabId")+ if type(tab_id) is not int:+ return+ opener_tab_id = params.get("openerTabId")+ async with self._lease_lock:+ owner = self._leases.lessee(opener_tab_id) if type(opener_tab_id) is int else None+ if owner is not None:+ self._leases.grant(tab_id, owner, _tab_snapshot(params))+ elif type(opener_tab_id) is int and self._tab_creates_in_flight:+ self._deferred_tab_created[tab_id] = dict(params)+ return+ else:+ self._leases.register_tab(_tab_snapshot(params))+ if owner is not None:+ await self._send_to(owner, build_event_frame("tabs.created", params))+ return+ await self._rotate_offers()++ async def _handle_extension_disconnect(self) -> None:+ async with self._lease_lock:+ self._extension_generation += 1+ self._deferred_tab_added.clear()+ self._deferred_tab_created.clear()+ self._discarded_tab_ids.clear()+ self._leases.reset([])+ LOG.info("browser_extension_broker_extension_disconnected", clients=len(self._clients))+ for client_id in list(self._clients):+ await self._send_to(client_id, build_state_frame(False, []))++ def _pop_deferred_descendants(self, opener_tab_id: int) -> list[dict]:+ descendants: list[dict] = []+ pending_openers = [opener_tab_id]+ while pending_openers:+ current_opener = pending_openers.pop()+ children = [+ event for event in self._deferred_tab_created.values() if event.get("openerTabId") == current_opener+ ]+ for child in children:+ child_id = child["tabId"]+ self._deferred_tab_created.pop(child_id)+ pending_openers.append(child_id)+ descendants.extend(children)+ return descendants++ async def _rotate_offers(self) -> None:+ async with self._lease_lock:+ granted, revoked = self._leases.rotate(time.monotonic())+ for change in revoked:+ await self._send_to(+ change.client_id,+ build_event_frame("scope.tabRemoved", {"tabId": change.tab["tabId"], "reason": "unshared"}),+ )+ for change in granted:+ await self._send_to(change.client_id, build_event_frame("scope.tabAdded", change.tab))++ async def _send_to(self, client_id: str, frame: dict) -> None:+ client = self._clients.get(client_id)+ if client is None:+ return+ await client.send(frame)++ async def _run_maintenance(self) -> None:+ while True:+ await asyncio.sleep(_MAINTENANCE_INTERVAL_SECONDS)+ try:+ await self._rotate_offers()+ except Exception:+ LOG.exception("browser_extension_broker_offer_rotation_failed")+ idle_since = self._idle_since+ if idle_since is None or self._clients:+ continue+ if time.monotonic() - idle_since >= self._idle_timeout_seconds:+ LOG.info("browser_extension_broker_idle_shutdown", idle_seconds=self._idle_timeout_seconds)+ self.request_shutdown("idle")+ return+++def _tab_snapshot(params: dict) -> dict:+ url = params.get("url")+ title = params.get("title")+ return {+ "tabId": params["tabId"],+ "url": url if isinstance(url, str) else "",+ "title": title if isinstance(title, str) else "",+ }diff --git a/skyvern/browser_extension/cdp_adapter.py b/skyvern/browser_extension/cdp_adapter.pyindex 1b8ab773b..f84c5f475 100644--- a/skyvern/browser_extension/cdp_adapter.py+++ b/skyvern/browser_extension/cdp_adapter.py@@ -5,7 +5,6 @@ import jsonimport secretsfrom collections.abc import Coroutinefrom functools import partial-from typing import TYPE_CHECKINGimport structlogfrom aiohttp import WSMsgType, web@@ -14,10 +13,7 @@ from skyvern.browser_extension.errors import BrowserExtensionError, ExtensionReqfrom skyvern.browser_extension.protocol import is_cdp_method_allowedfrom skyvern.browser_extension.relay import _MAX_WS_MESSAGE_BYTESfrom skyvern.browser_extension.target_registry import VirtualTargetRegistry--if TYPE_CHECKING:- from skyvern.browser_extension.relay import ExtensionRelayServer-+from skyvern.browser_extension.transport import ExtensionTransportLOG = structlog.get_logger()@@ -59,7 +55,7 @@ _ROOT_TARGET_GATE_METHODS = {class ExtensionCdpAdapter:- def __init__(self, registry: VirtualTargetRegistry, relay: ExtensionRelayServer) -> None:+ def __init__(self, registry: VirtualTargetRegistry, relay: ExtensionTransport) -> None:self._registry = registryself._relay = relayself._capability = secrets.token_urlsafe(32)diff --git a/skyvern/browser_extension/relay.py b/skyvern/browser_extension/relay.pyindex a17131321..de8f96cb3 100644--- a/skyvern/browser_extension/relay.py+++ b/skyvern/browser_extension/relay.py@@ -539,6 +539,12 @@ class ExtensionRelayServer:self.bound_port = portself.scoped_tabs: list[dict] = []+ def add_route(self, path: str, handler: Callable[[web.Request], Awaitable[web.StreamResponse]]) -> None:+ """Share the relay's loopback listener with another GET endpoint. Must precede start()."""+ if self._runner is not None:+ raise BrowserExtensionError("Routes must be registered before the relay starts")+ self._app.router.add_get(path, handler)+def create_pairing_nonce(self) -> str:nonce = secrets.token_urlsafe(32)self._pairing_nonce = nonce@@ -552,6 +558,9 @@ class ExtensionRelayServer:return noncereturn self.create_pairing_nonce()+ async def acquire_pairing_nonce(self) -> str:+ return self.get_or_create_pairing_nonce()+def _is_interactive_pairing_request(self, request: web.Request) -> bool:try:origin = urlsplit(request.headers.get("Origin", ""))diff --git a/skyvern/browser_extension/runtime.py b/skyvern/browser_extension/runtime.pyindex eaf9f152f..f408114b8 100644--- a/skyvern/browser_extension/runtime.py+++ b/skyvern/browser_extension/runtime.py@@ -13,14 +13,18 @@ from typing import Any, Protocolimport structlogfrom skyvern.browser_extension.auth import load_or_create_pairing_token+from skyvern.browser_extension.broker.client import BrokerTransport, LegacyBridgeOwnerErrorfrom skyvern.browser_extension.errors import BrowserExtensionErrorfrom skyvern.browser_extension.relay import ExtensionRelayServerfrom skyvern.browser_extension.target_registry import VirtualTargetRegistry+from skyvern.browser_extension.transport import ExtensionTransportLOG = structlog.get_logger(__name__)_PORT_ENV = "SKYVERN_BROWSER_EXTENSION_PORT"+_BROKER_ENV = "SKYVERN_BROWSER_EXTENSION_BROKER"_DEFAULT_PORT = 19777+_DISABLED_VALUES = frozenset({"0", "false", "no", "off"})class _Adapter(Protocol):@@ -36,11 +40,18 @@ class _Adapter(Protocol):async def on_extension_disconnect(self) -> None: ...-_relay_factory: Callable[+TransportFactory = Callable[[str, int, Callable[[str, dict], Awaitable[None]], Callable[[], Awaitable[None]] | None],- ExtensionRelayServer,-] = ExtensionRelayServer-_adapter_factory: Callable[[VirtualTargetRegistry, ExtensionRelayServer], _Adapter] | None = None+ ExtensionTransport,+]++_relay_factory: TransportFactory = ExtensionRelayServer+_broker_factory: TransportFactory = BrokerTransport+_adapter_factory: Callable[[VirtualTargetRegistry, ExtensionTransport], _Adapter] | None = None+++def broker_enabled() -> bool:+ return os.environ.get(_BROKER_ENV, "").strip().lower() not in _DISABLED_VALUESdef _open_browser_process(command: list[str], *, windows: bool) -> bool:@@ -62,9 +73,10 @@ class BrowserExtensionRuntime:_instance: BrowserExtensionRuntime | None = None_lock = asyncio.Lock()- def __init__(self, relay: ExtensionRelayServer, adapter: _Adapter) -> None:- self._relay = relay+ def __init__(self, transport: ExtensionTransport, adapter: _Adapter, *, brokered: bool) -> None:+ self._transport = transportself._adapter = adapter+ self._brokered = brokeredself._stopped = False@classmethod@@ -84,15 +96,24 @@ class BrowserExtensionRuntime:async def on_disconnect() -> None:await adapter_holder[0].on_extension_disconnect()- relay = _relay_factory(token, resolved_port, handle_event, on_disconnect)- adapter = _create_adapter(registry, relay)+ brokered = broker_enabled()+ factory = _broker_factory if brokered else _relay_factory+ transport = factory(token, resolved_port, handle_event, on_disconnect)+ adapter = _create_adapter(registry, transport)adapter_holder.append(adapter)try:await adapter.start()- await relay.start()+ await transport.start()+ except LegacyBridgeOwnerError as exc:+ await _cleanup_failed_start(transport, adapter)+ raise BrowserExtensionError(+ f"An older Skyvern MCP session owns the browser-extension bridge on port {resolved_port} and "+ "cannot share it; restart that session on this version so every agent can attach, or set "+ f"{_PORT_ENV} to a free port and update the bridge port in the Skyvern extension popup to match"+ ) from excexcept OSError as exc:- await _cleanup_failed_start(relay, adapter)+ await _cleanup_failed_start(transport, adapter)if exc.errno == errno.EADDRINUSE:raise BrowserExtensionError(f"Another Skyvern MCP session likely owns the browser-extension bridge on port {resolved_port}; "@@ -101,10 +122,10 @@ class BrowserExtensionRuntime:) from excraiseexcept BaseException:- await _cleanup_failed_start(relay, adapter)+ await _cleanup_failed_start(transport, adapter)raise- runtime = cls(relay, adapter)+ runtime = cls(transport, adapter, brokered=brokered)cls._instance = runtimereturn runtime@@ -118,10 +139,14 @@ class BrowserExtensionRuntime:@propertydef extension_connected(self) -> bool:- return self._relay.connected+ return self._transport.connected++ @property+ def brokered(self) -> bool:+ return self._brokeredasync def wait_for_extension(self, timeout: float = 10.0) -> bool:- return await self._relay.wait_connected(timeout)+ return await self._transport.wait_connected(timeout)@staticmethoddef open_extension_url(url: str) -> bool:@@ -167,9 +192,13 @@ class BrowserExtensionRuntime:return Truereturn False- def open_pairing_page(self) -> bool:- nonce = self._relay.get_or_create_pairing_nonce()- url = f"http://127.0.0.1:{self._relay.bound_port}/pair#{nonce}"+ async def open_pairing_page(self) -> bool:+ try:+ nonce = await self._transport.acquire_pairing_nonce()+ except BrowserExtensionError as exc:+ LOG.info("browser_extension_pairing_page_unavailable", error_type=type(exc).__name__)+ return False+ url = f"http://127.0.0.1:{self._transport.bound_port}/pair#{nonce}"return self.open_extension_url(url)async def shutdown(self) -> None:@@ -179,7 +208,7 @@ class BrowserExtensionRuntime:returnself._stopped = Truetry:- await self._relay.stop()+ await self._transport.stop()finally:try:await self._adapter.stop()@@ -196,12 +225,12 @@ class BrowserExtensionRuntime:return _resolve_port(None)-def _create_adapter(registry: VirtualTargetRegistry, relay: ExtensionRelayServer) -> _Adapter:+def _create_adapter(registry: VirtualTargetRegistry, transport: ExtensionTransport) -> _Adapter:if _adapter_factory is not None:- return _adapter_factory(registry, relay)+ return _adapter_factory(registry, transport)from skyvern.browser_extension.cdp_adapter import ExtensionCdpAdapter- return ExtensionCdpAdapter(registry, relay)+ return ExtensionCdpAdapter(registry, transport)def _resolve_port(port: int | None) -> int:@@ -221,9 +250,9 @@ def _resolve_port(port: int | None) -> int:return resolved_port-async def _cleanup_failed_start(relay: ExtensionRelayServer, adapter: _Adapter) -> None:+async def _cleanup_failed_start(transport: ExtensionTransport, adapter: _Adapter) -> None:try:- await relay.stop()+ await transport.stop()except Exception:LOG.exception("failed to stop browser extension relay after startup error")try:diff --git a/skyvern/browser_extension/transport.py b/skyvern/browser_extension/transport.pynew file mode 100644index 000000000..e3b9a8915--- /dev/null+++ b/skyvern/browser_extension/transport.py@@ -0,0 +1,27 @@+from __future__ import annotations++from typing import Protocol+++class ExtensionTransport(Protocol):+ """What the CDP adapter and the runtime need from whatever owns the extension socket.++ Satisfied both by ExtensionRelayServer, which owns the socket in-process, and by+ BrokerTransport, which reaches it through the shared broker daemon.+ """++ bound_port: int+ scoped_tabs: list[dict]++ @property+ def connected(self) -> bool: ...++ async def start(self) -> None: ...++ async def stop(self) -> None: ...++ async def wait_connected(self, timeout: float) -> bool: ...++ async def request(self, op: str, args: dict, timeout: float = 30.0) -> dict: ...++ async def acquire_pairing_nonce(self) -> str: ...diff --git a/skyvern/cli/commands/browser.py b/skyvern/cli/commands/browser.pyindex 9b4131769..c7cfa2f82 100644--- a/skyvern/cli/commands/browser.py+++ b/skyvern/cli/commands/browser.py@@ -23,8 +23,9 @@ import typerfrom skyvern._cli_bootstrap import prepare_cli_runtimefrom skyvern.browser_extension.auth import load_or_create_pairing_token+from skyvern.browser_extension.broker.protocol import BROKER_HEALTH_PATHfrom skyvern.browser_extension.errors import BrowserExtensionError-from skyvern.browser_extension.runtime import BrowserExtensionRuntime+from skyvern.browser_extension.runtime import BrowserExtensionRuntime, broker_enabledfrom skyvern.cli.commands._output import (console,)@@ -281,6 +282,26 @@ def _bridge_is_listening(port: int) -> bool:return True+def _bridge_mode(port: int) -> Literal["broker", "legacy", "none"]:+ """Tell a shared broker daemon apart from a pre-broker single-owner MCP session."""+ connection = http.client.HTTPConnection("127.0.0.1", port, timeout=1.0)+ try:+ connection.request("GET", BROKER_HEALTH_PATH)+ response = connection.getresponse()+ body = response.read(4096)+ except OSError:+ return "none"+ finally:+ connection.close()+ if response.status != 200:+ return "legacy"+ try:+ payload = json.loads(body)+ except (json.JSONDecodeError, UnicodeDecodeError):+ return "legacy"+ return "broker" if isinstance(payload, dict) and payload.get("broker") is True else "legacy"++def _request_pairing_nonce(port: int, token: str) -> str:proof = hmac.new(token.encode("utf-8"), b"skyvern-pair-begin-v1", hashlib.sha256).hexdigest()body = json.dumps({"v": 1, "proof": proof}, separators=(",", ":"))@@ -368,10 +389,16 @@ def extension_status() -> None:console.print(f"bridge configuration invalid ({exc})")return- if not _bridge_is_listening(port):+ console.print(f"shared broker: {'enabled' if broker_enabled() else 'disabled (SKYVERN_BROWSER_EXTENSION_BROKER)'}")++ mode = _bridge_mode(port)+ if mode == "none":console.print("bridge not running (start your MCP server with --browser-extension)")+ elif mode == "broker":+ console.print(f"bridge listening on {port} (shared broker daemon)")else:- console.print(f"bridge listening on {port}")+ console.print(f"bridge listening on {port} (single-owner session)")+ console.print("restart that session on this version so every agent can share the bridge")@browser_app.command("extension-pair")diff --git a/skyvern/cli/mcp_tools/session.py b/skyvern/cli/mcp_tools/session.pyindex e5ed60bc9..ef9878bb5 100644--- a/skyvern/cli/mcp_tools/session.py+++ b/skyvern/cli/mcp_tools/session.py@@ -152,7 +152,7 @@ async def skyvern_browser_session_create(try:runtime = await BrowserExtensionRuntime.get_or_start()if not await runtime.wait_for_extension(10.0):- pairing_opened = runtime.open_pairing_page()+ pairing_opened = await runtime.open_pairing_page()timer.mark("sdk")return make_result("skyvern_browser_session_create",diff --git a/skyvern/forge/sdk/db/agent_db.py b/skyvern/forge/sdk/db/agent_db.pyindex 2d512645d..bcb0ef624 100644--- a/skyvern/forge/sdk/db/agent_db.py+++ b/skyvern/forge/sdk/db/agent_db.py@@ -368,10 +368,20 @@ class AgentDB(BaseAlchemyDB):self._sqlite_schedule_lock: asyncio.Lock | None = (asyncio.Lock() if self.engine.dialect.name == "sqlite" else None)+ # ponytail: Embedded SQLite is single-user; use keyed locks if concurrent local creates become material.+ self._sqlite_workflow_creation_lock: asyncio.Lock | None = (+ asyncio.Lock() if self.engine.dialect.name == "sqlite" else None+ )# -- Zero-dependency repositories --self.tasks = TasksRepository(self.Session, debug_enabled, self.is_retryable_error)- self.workflows = WorkflowsRepository(self.Session, debug_enabled, self.is_retryable_error)+ self.workflows = WorkflowsRepository(+ self.Session,+ debug_enabled,+ self.is_retryable_error,+ db_engine=self.engine,+ sqlite_workflow_creation_lock=self._sqlite_workflow_creation_lock,+ )self.workflow_params = WorkflowParametersRepository(self.Session, debug_enabled, self.is_retryable_error)self.workflow_run_credential_selections = WorkflowRunCredentialSelectionsRepository(self.Session, debug_enabled, self.is_retryable_errordiff --git a/skyvern/forge/sdk/db/base_alchemy_db.py b/skyvern/forge/sdk/db/base_alchemy_db.pyindex e16305899..83cdf939e 100644--- a/skyvern/forge/sdk/db/base_alchemy_db.py+++ b/skyvern/forge/sdk/db/base_alchemy_db.py@@ -7,7 +7,7 @@ from typing import Any, AsyncContextManager, AsyncIterator, Callableimport structlogfrom sqlalchemy.exc import SQLAlchemyError-from sqlalchemy.ext.asyncio import AsyncEngine, AsyncSession, async_sessionmaker+from sqlalchemy.ext.asyncio import AsyncConnection, AsyncEngine, AsyncSession, async_sessionmakerLOG = structlog.get_logger()@@ -90,6 +90,16 @@ class _SessionFactory:def __getattr__(self, name: str) -> Any:return getattr(self._sessionmaker, name)+ @asynccontextmanager+ async def bind_connection(self, connection: AsyncConnection) -> AsyncIterator[AsyncSession]:+ session = self._sessionmaker(bind=connection, join_transaction_mode="rollback_only")+ token = self._session_ctx.set(_SessionEntry(session=session, task=asyncio.current_task()))+ try:+ yield session+ finally:+ self._session_ctx.reset(token)+ await session.close()+@asynccontextmanagerasync def _session(self) -> AsyncIterator[AsyncSession]:existing = self._session_ctx.get()diff --git a/skyvern/forge/sdk/db/repositories/workflows.py b/skyvern/forge/sdk/db/repositories/workflows.pyindex 0c3a7500e..49847943e 100644--- a/skyvern/forge/sdk/db/repositories/workflows.py+++ b/skyvern/forge/sdk/db/repositories/workflows.py@@ -1,11 +1,16 @@from __future__ import annotations+import asyncio+from collections.abc import AsyncIterator, Callable+from contextlib import AsyncExitStack, asynccontextmanagerfrom dataclasses import dataclassfrom datetime import datetime, timezone-from typing import Any, cast+from typing import TYPE_CHECKING, Any, castimport structlog-from sqlalchemy import exists, func, or_, select, update+from sqlalchemy import exists, func, or_, select, text, update+from sqlalchemy.exc import SQLAlchemyError+from sqlalchemy.ext.asyncio import AsyncEnginefrom skyvern.constants import DEFAULT_SCRIPT_RUN_ID, DEFAULT_WORKFLOW_TITLESfrom skyvern.forge.sdk.browser_action_policy import BrowserActionPolicy, declare_policy@@ -47,7 +52,15 @@ from skyvern.forge.sdk.workflow.runtime_completion import carried_contract, withfrom skyvern.schemas.runs import ProxyLocationInputfrom skyvern.schemas.workflows import WorkflowStatus+if TYPE_CHECKING:+ from skyvern.forge.sdk.db.base_alchemy_db import _SessionFactory+LOG = structlog.get_logger()+WORKFLOW_CREATION_LOCK_TIMEOUT_SECONDS = 10+++class WorkflowCreationLockTimeout(Exception):+ pass@dataclass(frozen=True)@@ -95,6 +108,60 @@ def _align_block_output_parameters(workflow_definition: WorkflowDefinition) -> Nclass WorkflowsRepository(BaseRepository):"""Database operations for workflow management."""+ def __init__(+ self,+ session_factory: _SessionFactory,+ debug_enabled: bool = False,+ is_retryable_error_fn: Callable[[SQLAlchemyError], bool] | None = None,+ db_engine: AsyncEngine | None = None,+ sqlite_workflow_creation_lock: asyncio.Lock | None = None,+ ) -> None:+ super().__init__(session_factory, debug_enabled, is_retryable_error_fn)+ self._db_engine = db_engine+ self._sqlite_workflow_creation_lock = sqlite_workflow_creation_lock++ @asynccontextmanager+ async def acquire_workflow_creation_lock(self, lock_key: str) -> AsyncIterator[None]:+ if self._sqlite_workflow_creation_lock is None and self._db_engine is None:+ raise RuntimeError("Workflow creation locking requires a database engine")++ async with AsyncExitStack() as stack:+ try:+ async with asyncio.timeout(WORKFLOW_CREATION_LOCK_TIMEOUT_SECONDS):+ if self._sqlite_workflow_creation_lock is not None:+ await stack.enter_async_context(self._sqlite_workflow_creation_lock)+ await stack.enter_async_context(+ self._workflow_creation_transaction(+ None if self._sqlite_workflow_creation_lock is not None else lock_key+ )+ )+ except TimeoutError as exc:+ raise WorkflowCreationLockTimeout from exc+ yield++ @asynccontextmanager+ async def _workflow_creation_transaction(self, lock_key: str | None = None) -> AsyncIterator[None]:+ if self._db_engine is None:+ raise RuntimeError("Workflow creation locking requires a database engine")+ if lock_key is not None:+ while True:+ async with self._db_engine.connect() as connection:+ async with connection.begin():+ acquired = await connection.scalar(+ text("SELECT pg_try_advisory_xact_lock(hashtext(:key))"),+ {"key": lock_key},+ )+ if acquired:+ async with self.Session.bind_connection(connection):+ yield+ return+ # ponytail: Polling frees the SQL pool; use a lock service if this key becomes hot.+ await asyncio.sleep(0.1)+ async with self._db_engine.connect() as connection:+ async with connection.begin():+ async with self.Session.bind_connection(connection):+ yield+async def _policy_of_latest_version(self, session: Any, workflow_permanent_id: str, organization_id: str | None) -> object | None:diff --git a/skyvern/forge/sdk/routes/agent_protocol.py b/skyvern/forge/sdk/routes/agent_protocol.pyindex 6c8c1e7bd..001756544 100644--- a/skyvern/forge/sdk/routes/agent_protocol.py+++ b/skyvern/forge/sdk/routes/agent_protocol.py@@ -42,6 +42,7 @@ from skyvern.exceptions import ()from skyvern.forge import appfrom skyvern.forge.prompts import prompt_engine+from skyvern.forge.sdk.api.crypto import calculate_sha256from skyvern.forge.sdk.api.llm.custom_llm_registry import (CUSTOM_LLM_KEY_PREFIX,ensure_custom_llm_registered_for_org,@@ -69,6 +70,7 @@ from skyvern.forge.sdk.db.repositories.tags import (TagValueRenameCollision,TagValueRenameResult,)+from skyvern.forge.sdk.db.repositories.workflows import WorkflowCreationLockTimeoutfrom skyvern.forge.sdk.enterprise_features import collect_enterprise_gated_run_featuresfrom skyvern.forge.sdk.executor.factory import AsyncExecutorFactoryfrom skyvern.forge.sdk.models import Step@@ -821,6 +823,7 @@ async def create_workflow_legacy(summary="Create a new agent",responses={200: {"description": "Successfully created agent"},+ 409: {"description": "A create with this idempotency key is still in progress"},422: {"description": "Invalid agent definition"},},)@@ -833,6 +836,7 @@ async def create_workflow(folder_id: str | None = Query(None, description="Optional folder ID to assign the workflow to"),current_org: Organization = Depends(org_auth_service.get_current_org),user_id: str | None = Depends(org_auth_service.get_current_user_id_or_none),+ idempotency_key: Annotated[str | None, Header(alias="Idempotency-Key")] = None,) -> Workflow:analytics.capture("skyvern-oss-agent-workflow-create")try:@@ -851,6 +855,47 @@ async def create_workflow(# Override folder_id if provided as query parameterif folder_id is not None:workflow_definition.folder_id = folder_id+ if idempotency_key is not None and idempotency_key.strip():+ digest = calculate_sha256(f"create_workflow\0{current_org.organization_id}\0{idempotency_key}")+ workflow_permanent_id = f"wpid_{digest}"+ try:+ return await app.WORKFLOW_SERVICE.get_workflow_by_permanent_id(+ workflow_permanent_id=workflow_permanent_id,+ organization_id=current_org.organization_id,+ version=1,+ filter_deleted=False,+ )+ except WorkflowNotFound:+ pass+ resolved_title = await app.WORKFLOW_SERVICE.resolve_workflow_creation_title(+ current_org.organization_id,+ workflow_definition,+ )+ created_workflow: Workflow+ async with app.DATABASE.workflows.acquire_workflow_creation_lock(workflow_permanent_id):+ try:+ return await app.WORKFLOW_SERVICE.get_workflow_by_permanent_id(+ workflow_permanent_id=workflow_permanent_id,+ organization_id=current_org.organization_id,+ version=1,+ filter_deleted=False,+ )+ except WorkflowNotFound:+ pass+ created_workflow = await app.WORKFLOW_SERVICE.create_workflow_from_request(+ organization=current_org,+ request=workflow_definition,+ new_workflow_permanent_id=workflow_permanent_id,+ created_by=user_id,+ edited_by=user_id,+ notify_workflow_saved=False,+ resolved_title=resolved_title,+ )+ app.WORKFLOW_SERVICE.schedule_workflow_saved_hook(+ organization_id=created_workflow.organization_id,+ edited_by=user_id,+ )+ return created_workflowreturn await app.WORKFLOW_SERVICE.create_workflow_from_request(organization=current_org,request=workflow_definition,@@ -859,6 +904,11 @@ async def create_workflow()except yaml.YAMLError as exc:raise HTTPException(status_code=422, detail=format_yaml_error(exc))+ except WorkflowCreationLockTimeout as exc:+ raise HTTPException(+ status_code=http_status.HTTP_409_CONFLICT,+ detail="Workflow creation with this idempotency key is still in progress.",+ ) from excexcept WorkflowDefinitionValidationException as e:raise eexcept (SkyvernHTTPException, ValidationError) as e:diff --git a/skyvern/forge/sdk/workflow/service.py b/skyvern/forge/sdk/workflow/service.pyindex b74962389..9dfd6ee55 100644--- a/skyvern/forge/sdk/workflow/service.py+++ b/skyvern/forge/sdk/workflow/service.py@@ -7504,6 +7504,16 @@ class WorkflowService:workflow_tags=workflow_tags,)+ def schedule_workflow_saved_hook(self, *, organization_id: str, edited_by: str | None) -> None:+ task = asyncio.create_task(+ app.AGENT_FUNCTION.on_workflow_saved(+ organization_id=organization_id,+ edited_by=edited_by,+ ),+ )+ self._background_tasks.add(task)+ task.add_done_callback(self._background_tasks.discard)+async def update_workflow_definition(self,workflow_id: str,@@ -7535,6 +7545,7 @@ class WorkflowService:sequential_key: str | None | object = _UNSET,created_by: str | None | object = _UNSET,edited_by: str | None | object = _UNSET,+ notify_workflow_saved: bool = True,) -> Workflow:if workflow_definition is not None:if organization_id is not None:@@ -7609,15 +7620,11 @@ class WorkflowService:edited_by=edited_by,)- _edited_by: str | None = cast("str | None", edited_by) if edited_by is not _UNSET else None- task = asyncio.create_task(- app.AGENT_FUNCTION.on_workflow_saved(+ if notify_workflow_saved:+ self.schedule_workflow_saved_hook(organization_id=updated_workflow.organization_id,- edited_by=_edited_by,- ),- )- self._background_tasks.add(task)- task.add_done_callback(self._background_tasks.discard)+ edited_by=cast("str | None", edited_by) if edited_by is not _UNSET else None,+ )return updated_workflow@@ -10597,18 +10604,11 @@ class WorkflowService:return workflow_definition- async def create_workflow_from_request(+ async def resolve_workflow_creation_title(self,- organization: Organization,+ organization_id: str,request: WorkflowCreateYAMLRequest,- workflow_permanent_id: str | None = None,- delete_script: bool = True,- created_by: str | None = None,- edited_by: str | None = None,- ) -> Workflow:- organization_id = organization.organization_id-- # Generate meaningful title if using default and has blocks+ ) -> str:title = request.titleif title in DEFAULT_WORKFLOW_TITLES and request.workflow_definition.blocks:generated_title = await generate_workflow_title(@@ -10622,6 +10622,24 @@ class WorkflowService:organization_id=organization_id,generated_title=title,)+ return title++ async def create_workflow_from_request(+ self,+ organization: Organization,+ request: WorkflowCreateYAMLRequest,+ workflow_permanent_id: str | None = None,+ delete_script: bool = True,+ created_by: str | None = None,+ edited_by: str | None = None,+ new_workflow_permanent_id: str | None = None,+ notify_workflow_saved: bool = True,+ resolved_title: str | None = None,+ ) -> Workflow:+ organization_id = organization.organization_id+ title = resolved_title+ if title is None:+ title = await self.resolve_workflow_creation_title(organization_id, request)LOG.info("Creating workflow from request",@@ -10741,6 +10759,8 @@ class WorkflowService:max_elapsed_time_minutes=request.max_elapsed_time_minutes,extra_http_headers=request.extra_http_headers,cdp_connect_headers=new_cdp_connect_headers,+ workflow_permanent_id=new_workflow_permanent_id,+ version=1 if new_workflow_permanent_id else None,is_saved_task=request.is_saved_task,status=request.status,run_with=request.run_with,@@ -10779,6 +10799,7 @@ class WorkflowService:description=request.description,workflow_definition=workflow_definition,edited_by=edited_by,+ notify_workflow_saved=notify_workflow_saved,)await self.maybe_delete_cached_code(diff --git a/tests/unit/browser_extension/_broker_fakes.py b/tests/unit/browser_extension/_broker_fakes.pynew file mode 100644index 000000000..7a32342e4--- /dev/null+++ b/tests/unit/browser_extension/_broker_fakes.py@@ -0,0 +1,144 @@+from __future__ import annotations++import asyncio+import base64+import json+import secrets+from collections.abc import Callable+from contextlib import suppress++import aiohttp++from skyvern.browser_extension.auth import compute_ext_proof++EXTENSION_ORIGIN = "chrome-extension://fake-extension-id"++Responder = Callable[[str, dict], dict]+++class FakeExtension:+ """Minimal stand-in for the Chrome extension's side of /extension/v1.++ Speaks the real HMAC handshake and the real request/response frames so broker tests exercise+ the production relay rather than a mock of it.+ """++ def __init__(self, port: int, token: str, responder: Responder | None = None) -> None:+ self._port = port+ self._token = token+ self._responder = responder or _default_responder()+ self._session: aiohttp.ClientSession | None = None+ self._websocket: aiohttp.ClientWebSocketResponse | None = None+ self._reader: asyncio.Task[None] | None = None+ self.create_response_gate: asyncio.Event | None = None+ self.requests: list[tuple[str, dict]] = []++ async def connect(self, scoped_tabs: list[dict] | None = None) -> None:+ session = aiohttp.ClientSession()+ websocket = await session.ws_connect(+ f"ws://127.0.0.1:{self._port}/extension/v1",+ headers={"Origin": EXTENSION_ORIGIN},+ )+ challenge = json.loads((await websocket.receive()).data)+ assert challenge["type"] == "auth.challenge"+ client_nonce = base64.urlsafe_b64encode(secrets.token_bytes(32)).rstrip(b"=").decode("ascii")+ await websocket.send_json(+ {+ "v": 1,+ "type": "auth.proof",+ "clientNonce": client_nonce,+ "proof": compute_ext_proof(self._token, challenge["serverNonce"], client_nonce),+ }+ )+ auth_ok = json.loads((await websocket.receive()).data)+ assert auth_ok["type"] == "auth.ok"++ self._session = session+ self._websocket = websocket+ self._reader = asyncio.create_task(self._run_reader(websocket))+ await self.send_event("extension.hello", {"scopedTabs": scoped_tabs or []})++ async def close(self) -> None:+ reader = self._reader+ self._reader = None+ if reader is not None:+ reader.cancel()+ with suppress(asyncio.CancelledError):+ await reader+ if self._websocket is not None and not self._websocket.closed:+ await self._websocket.close()+ if self._session is not None:+ await self._session.close()++ async def send_event(self, event: str, params: dict) -> None:+ websocket = self._websocket+ assert websocket is not None+ await websocket.send_json({"v": 1, "type": "event", "event": event, "params": params})++ async def _run_reader(self, websocket: aiohttp.ClientWebSocketResponse) -> None:+ async for message in websocket:+ if message.type is not aiohttp.WSMsgType.TEXT:+ continue+ frame = json.loads(message.data)+ if frame.get("type") == "ping":+ await websocket.send_json({"v": 1, "type": "pong"})+ continue+ if frame.get("type") != "request":+ continue+ operation = frame["op"]+ arguments = frame["args"]+ self.requests.append((operation, arguments))+ try:+ result = self._responder(operation, arguments)+ except _ExtensionFailure as failure:+ await websocket.send_json(+ {+ "v": 1,+ "type": "response",+ "id": frame["id"],+ "ok": False,+ "error": {"code": failure.code, "message": failure.message},+ }+ )+ continue+ if operation == "tabs.create":+ # The real extension announces the scoped tab before its create handler returns.+ await self.send_event(+ "scope.tabAdded",+ {"tabId": result["tabId"], "url": arguments.get("url", "about:blank"), "title": ""},+ )+ if self.create_response_gate is not None:+ await self.create_response_gate.wait()+ await websocket.send_json({"v": 1, "type": "response", "id": frame["id"], "ok": True, "result": result})+++class _ExtensionFailure(Exception):+ def __init__(self, code: str, message: str) -> None:+ self.code = code+ self.message = message+ super().__init__(f"{code}: {message}")+++def _default_responder() -> Responder:+ next_tab_id = iter(range(101, 1000))++ def respond(operation: str, arguments: dict) -> dict:+ if operation == "tabs.create":+ return {"tabId": next(next_tab_id)}+ if operation == "tabs.list":+ return {"tabs": []}+ if operation == "debugger.send":+ return {"result": {"method": arguments.get("method")}}+ return {}++ return respond+++async def wait_for(predicate: Callable[[], bool], timeout: float = 3.0) -> None:+ loop = asyncio.get_running_loop()+ deadline = loop.time() + timeout+ while loop.time() < deadline:+ if predicate():+ return+ await asyncio.sleep(0.01)+ raise AssertionError("condition was not met before the timeout")diff --git a/tests/unit/browser_extension/test_broker_daemon.py b/tests/unit/browser_extension/test_broker_daemon.pynew file mode 100644index 000000000..b44eb235c--- /dev/null+++ b/tests/unit/browser_extension/test_broker_daemon.py@@ -0,0 +1,152 @@+from __future__ import annotations++import errno+import subprocess+import sys+from pathlib import Path+from unittest.mock import MagicMock++import pytest++import skyvern.browser_extension.broker.daemon as daemon_module+from skyvern.browser_extension.broker.daemon import (+ DAEMON_MODULE,+ DEFAULT_IDLE_TIMEOUT_SECONDS,+ IDLE_TIMEOUT_ENV,+ resolve_idle_timeout_seconds,+ run_daemon,+ spawn_daemon,+)+from skyvern.browser_extension.errors import BrowserExtensionError+++def state_home(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> Path:+ monkeypatch.setattr(daemon_module.Path, "home", staticmethod(lambda: tmp_path))+ return tmp_path+++def test_the_daemon_is_launched_detached_from_the_agent_that_spawned_it(+ monkeypatch: pytest.MonkeyPatch, state_home: Path+) -> None:+ popen = MagicMock()+ monkeypatch.setattr(daemon_module.subprocess, "Popen", popen)+ monkeypatch.setattr(daemon_module.sys, "platform", "darwin")++ assert spawn_daemon(19777)++ command, options = popen.call_args.args[0], popen.call_args.kwargs+ assert command == [sys.executable, "-m", DAEMON_MODULE, "--port", "19777"]+ assert options["start_new_session"] is True+ assert options["stdin"] is subprocess.DEVNULL+ assert options["close_fds"] is True+++def test_a_spawn_storm_collapses_to_a_single_launch(monkeypatch: pytest.MonkeyPatch, state_home: Path) -> None:+ popen = MagicMock()+ monkeypatch.setattr(daemon_module.subprocess, "Popen", popen)++ results = [spawn_daemon(19777) for _ in range(12)]++ assert results.count(True) == 1+ assert popen.call_count == 1+++def test_a_stamp_a_hair_in_the_future_still_blocks_a_second_spawn(+ monkeypatch: pytest.MonkeyPatch, state_home: Path+) -> None:+ """Millisecond rounding can put the stamp marginally ahead of the next read of the clock."""+ popen = MagicMock()+ monkeypatch.setattr(daemon_module.subprocess, "Popen", popen)+ clock = [1_000.0]+ monkeypatch.setattr(daemon_module.time, "time", lambda: clock[0])++ assert spawn_daemon(19777)+ clock[0] -= 0.0005+ assert not spawn_daemon(19777)++ assert popen.call_count == 1+++def test_a_second_spawn_is_allowed_once_the_cooldown_lapses(monkeypatch: pytest.MonkeyPatch, state_home: Path) -> None:+ popen = MagicMock()+ monkeypatch.setattr(daemon_module.subprocess, "Popen", popen)+ clock = [1_000.0]+ monkeypatch.setattr(daemon_module.time, "time", lambda: clock[0])++ assert spawn_daemon(19777)+ assert not spawn_daemon(19777)+ clock[0] += daemon_module._SPAWN_COOLDOWN_SECONDS+ assert spawn_daemon(19777)++ assert popen.call_count == 2+++def test_the_daemon_log_is_private_to_the_operator(monkeypatch: pytest.MonkeyPatch, state_home: Path) -> None:+ monkeypatch.setattr(daemon_module.subprocess, "Popen", MagicMock())++ assert spawn_daemon(19777)++ log_path = state_home / ".skyvern" / "browser_extension_broker.log"+ lock_path = state_home / ".skyvern" / "browser_extension_broker.lock"+ assert log_path.stat().st_mode & 0o777 == 0o600+ assert lock_path.stat().st_mode & 0o777 == 0o600+++def test_a_failed_launch_is_reported_rather_than_raised(monkeypatch: pytest.MonkeyPatch, state_home: Path) -> None:+ monkeypatch.setattr(daemon_module.subprocess, "Popen", MagicMock(side_effect=OSError("no exec")))++ assert not spawn_daemon(19777)+++async def test_losing_the_bind_race_exits_quietly(monkeypatch: pytest.MonkeyPatch) -> None:+ class LosingServer:+ def __init__(self, *args: object, **kwargs: object) -> None:+ self.stopped = False++ async def start(self) -> None:+ raise OSError(errno.EADDRINUSE, "address in use")++ async def stop(self) -> None:+ self.stopped = True++ monkeypatch.setattr(daemon_module, "BrokerServer", LosingServer)+ monkeypatch.setattr(daemon_module, "load_or_create_pairing_token", lambda: "daemon-test-token")++ assert await run_daemon(19777, 300.0) == 0+++async def test_a_real_bind_failure_is_not_swallowed(monkeypatch: pytest.MonkeyPatch) -> None:+ class BrokenServer:+ def __init__(self, *args: object, **kwargs: object) -> None:+ pass++ async def start(self) -> None:+ raise OSError(errno.EACCES, "permission denied")++ async def stop(self) -> None:+ return++ monkeypatch.setattr(daemon_module, "BrokerServer", BrokenServer)+ monkeypatch.setattr(daemon_module, "load_or_create_pairing_token", lambda: "daemon-test-token")++ with pytest.raises(OSError, match="permission denied"):+ await run_daemon(19777, 300.0)+++def test_the_idle_window_is_configurable_and_validated(monkeypatch: pytest.MonkeyPatch) -> None:+ monkeypatch.delenv(IDLE_TIMEOUT_ENV, raising=False)+ assert resolve_idle_timeout_seconds() == DEFAULT_IDLE_TIMEOUT_SECONDS++ monkeypatch.setenv(IDLE_TIMEOUT_ENV, "45")+ assert resolve_idle_timeout_seconds() == 45.0++ monkeypatch.setenv(IDLE_TIMEOUT_ENV, "0")+ with pytest.raises(BrowserExtensionError, match="greater than zero"):+ resolve_idle_timeout_seconds()++ monkeypatch.setenv(IDLE_TIMEOUT_ENV, "soon")+ with pytest.raises(BrowserExtensionError, match="number of seconds"):+ resolve_idle_timeout_seconds()diff --git a/tests/unit/browser_extension/test_broker_leases.py b/tests/unit/browser_extension/test_broker_leases.pynew file mode 100644index 000000000..892087532--- /dev/null+++ b/tests/unit/browser_extension/test_broker_leases.py@@ -0,0 +1,142 @@+from __future__ import annotations++from skyvern.browser_extension.broker.leases import LeaseTable+++def tab(tab_id: int, url: str = "https://example.test") -> dict:+ return {"tabId": tab_id, "url": url, "title": ""}+++def test_a_tab_an_agent_opened_is_leased_to_it_alone() -> None:+ leases = LeaseTable()+ leases.add_client("a")+ leases.add_client("b")++ leases.grant(1, "a", tab(1))++ assert leases.lessee(1) == "a"+ assert leases.visible_tabs("a") == [tab(1)]+ assert leases.visible_tabs("b") == []+ assert not leases.claim(1, "b")+ assert leases.claim(1, "a")+++def test_an_unowned_tab_is_offered_to_exactly_one_idle_client() -> None:+ leases = LeaseTable()+ leases.add_client("a")+ leases.add_client("b")+ leases.register_tab(tab(1))++ granted, revoked = leases.rotate(now=0.0)++ assert revoked == []+ assert [change.client_id for change in granted] == ["a"]+ assert leases.visible_tabs("a") == [tab(1)]+ assert leases.visible_tabs("b") == []+++def test_an_offer_nobody_claims_moves_on_to_the_next_client() -> None:+ leases = LeaseTable()+ leases.add_client("a")+ leases.add_client("b")+ leases.register_tab(tab(1))++ first, _ = leases.rotate(now=0.0)+ assert [change.client_id for change in first] == ["a"]++ second, revoked = leases.rotate(now=30.0)+ assert [change.client_id for change in revoked] == ["a"]+ assert [change.client_id for change in second] == ["b"]+ assert leases.visible_tabs("a") == []+ assert leases.visible_tabs("b") == [tab(1)]+++def test_a_lone_idle_client_keeps_its_offer_instead_of_churning() -> None:+ leases = LeaseTable()+ leases.add_client("a")+ leases.register_tab(tab(1))+ leases.rotate(now=0.0)++ granted, revoked = leases.rotate(now=30.0)++ assert granted == []+ assert revoked == []+ assert leases.owner(1) == "a"+++def test_claiming_an_offer_turns_it_into_a_lease_that_does_not_expire() -> None:+ leases = LeaseTable()+ leases.add_client("a")+ leases.register_tab(tab(1))+ leases.rotate(now=0.0)++ assert leases.claim(1, "a")++ granted, revoked = leases.rotate(now=10_000.0)+ assert granted == []+ assert revoked == []+ assert leases.lessee(1) == "a"+++def test_a_busy_client_is_skipped_when_another_shared_tab_appears() -> None:+ leases = LeaseTable()+ leases.add_client("a")+ leases.grant(1, "a", tab(1))+ leases.register_tab(tab(2))++ granted, _ = leases.rotate(now=0.0)++ assert granted == []+ assert leases.owner(2) is None+++def test_disconnecting_reports_leases_and_offers_separately_so_only_leases_are_detached() -> None:+ leases = LeaseTable()+ leases.add_client("a")+ leases.add_client("b")+ leases.grant(1, "a", tab(1))+ leases.grant(2, "a", tab(2))+ leases.register_tab(tab(3))+ leases.rotate(now=0.0)+ assert leases.owner(3) == "b"++ assert leases.remove_client("a") == ([1, 2], [])+ assert leases.remove_client("b") == ([], [3])+ assert all(leases.owner(tab_id) is None for tab_id in (1, 2, 3))+++def test_forgetting_a_tab_reports_whoever_held_it() -> None:+ leases = LeaseTable()+ leases.add_client("a")+ leases.grant(1, "a", tab(1))++ assert leases.forget_tab(1) == "a"+ assert leases.forget_tab(1) is None+ assert leases.visible_tabs("a") == []+++def test_an_extension_reconnect_voids_every_claim() -> None:+ leases = LeaseTable()+ leases.add_client("a")+ leases.add_client("b")+ leases.grant(1, "a", tab(1))+ leases.grant(2, "b", tab(2))++ leases.reset([tab(1), tab(3)])++ assert leases.owner(1) is None+ assert leases.owner(2) is None+ assert leases.knows_tab(3)+ assert leases.visible_tabs("a") == []+ assert leases.visible_tabs("b") == []+++def test_release_only_drops_the_holder_s_own_lease() -> None:+ leases = LeaseTable()+ leases.add_client("a")+ leases.grant(1, "a", tab(1))++ assert not leases.release(1, "b")+ assert leases.lessee(1) == "a"+ assert leases.release(1, "a")+ assert leases.lessee(1) is Nonediff --git a/tests/unit/browser_extension/test_broker_protocol.py b/tests/unit/browser_extension/test_broker_protocol.pynew file mode 100644index 000000000..257978922--- /dev/null+++ b/tests/unit/browser_extension/test_broker_protocol.py@@ -0,0 +1,128 @@+from __future__ import annotations++import json++import pytest++from skyvern.browser_extension.auth import compute_ext_proof, compute_server_proof+from skyvern.browser_extension.broker.protocol import (+ BROKER_FRAME_VERSION,+ build_broker_challenge,+ build_broker_nonce,+ build_error_frame,+ build_event_frame,+ build_request_frame,+ build_response_frame,+ build_state_frame,+ compute_broker_client_proof,+ compute_broker_server_proof,+ is_valid_broker_nonce,+ parse_broker_frame,+ verify_broker_client_proof,+)+from skyvern.browser_extension.errors import BrowserExtensionError++TOKEN = "broker-protocol-test-token"+++def test_broker_proofs_do_not_interchange_with_extension_proofs() -> None:+ server_nonce = build_broker_nonce()+ client_nonce = build_broker_nonce()++ broker_proof = compute_broker_client_proof(TOKEN, server_nonce, client_nonce)+ extension_proof = compute_ext_proof(TOKEN, server_nonce, client_nonce)++ assert broker_proof != extension_proof+ assert verify_broker_client_proof(TOKEN, server_nonce, client_nonce, broker_proof)+ assert not verify_broker_client_proof(TOKEN, server_nonce, client_nonce, extension_proof)+ assert compute_broker_server_proof(TOKEN, client_nonce, server_nonce) != compute_server_proof(+ TOKEN, client_nonce, server_nonce+ )+++def test_broker_client_proof_is_bound_to_both_nonces_and_the_token() -> None:+ server_nonce = build_broker_nonce()+ client_nonce = build_broker_nonce()+ proof = compute_broker_client_proof(TOKEN, server_nonce, client_nonce)++ assert not verify_broker_client_proof("other-token", server_nonce, client_nonce, proof)+ assert not verify_broker_client_proof(TOKEN, build_broker_nonce(), client_nonce, proof)+ assert not verify_broker_client_proof(TOKEN, server_nonce, build_broker_nonce(), proof)+++ "nonce",+ ["", "not base64!", "c2hvcnQ", build_broker_nonce() + "=", build_broker_nonce()[:-1]],+)+def test_only_a_full_length_urlsafe_nonce_is_accepted(nonce: str) -> None:+ assert not is_valid_broker_nonce(nonce)+++def test_a_generated_nonce_is_accepted() -> None:+ assert is_valid_broker_nonce(build_broker_nonce())+++def test_challenge_carries_a_fresh_nonce_every_time() -> None:+ first_nonce, first_frame = build_broker_challenge()+ second_nonce, _ = build_broker_challenge()++ assert first_nonce != second_nonce+ assert first_frame == {"v": BROKER_FRAME_VERSION, "type": "auth.challenge", "serverNonce": first_nonce}+++def test_request_and_response_frames_round_trip() -> None:+ request = parse_broker_frame(+ json.dumps(build_request_frame("r-1", "tabs.create", {"url": "https://example.test"}, 12.5)),+ from_client=True,+ )+ assert request.request_id == "r-1"+ assert request.op == "tabs.create"+ assert request.args == {"url": "https://example.test"}+ assert request.timeout_seconds == pytest.approx(12.5)++ ok = parse_broker_frame(json.dumps(build_response_frame("r-1", {"tabId": 7})), from_client=False)+ assert ok.ok is True+ assert ok.result == {"tabId": 7}++ failed = parse_broker_frame(json.dumps(build_error_frame("r-1", "TAB_NOT_SCOPED", "nope")), from_client=False)+ assert failed.ok is False+ assert failed.error_code == "TAB_NOT_SCOPED"+ assert failed.error_message == "nope"+++def test_event_and_state_frames_round_trip() -> None:+ event = parse_broker_frame(json.dumps(build_event_frame("scope.tabAdded", {"tabId": 5})), from_client=False)+ assert event.event == "scope.tabAdded"+ assert event.params == {"tabId": 5}++ state = parse_broker_frame(+ json.dumps(build_state_frame(True, [{"tabId": 5, "url": "", "title": ""}, {"tabId": "bad"}])),+ from_client=False,+ )+ assert state.extension_connected is True+ assert state.scoped_tabs == [{"tabId": 5, "url": "", "title": ""}]+++def test_each_direction_only_accepts_its_own_frame_kinds() -> None:+ with pytest.raises(BrowserExtensionError, match="Unknown broker frame type"):+ parse_broker_frame(json.dumps(build_response_frame("r-1", {})), from_client=True)+ with pytest.raises(BrowserExtensionError, match="Unknown broker frame type"):+ parse_broker_frame(json.dumps(build_request_frame("r-1", "tabs.list", {}, 1.0)), from_client=False)+++ "raw",+ [+ "not json",+ json.dumps([1, 2, 3]),+ json.dumps({"v": 2, "type": "ping"}),+ json.dumps({"v": 1, "type": "unknown"}),+ json.dumps({"v": 1, "type": "request", "id": "", "op": "tabs.list", "args": {}, "timeoutMs": 1}),+ json.dumps({"v": 1, "type": "request", "id": "r", "op": "tabs.list", "args": {}, "timeoutMs": 0}),+ json.dumps({"v": 1, "type": "request", "id": "r", "op": "tabs.list", "args": [], "timeoutMs": 1}),+ json.dumps({"v": 1, "type": "client.hello", "protocol": "1", "pid": 1}),+ ],+)+def test_malformed_frames_are_rejected(raw: str) -> None:+ with pytest.raises(BrowserExtensionError):+ parse_broker_frame(raw, from_client=True)diff --git a/tests/unit/browser_extension/test_broker_server.py b/tests/unit/browser_extension/test_broker_server.pynew file mode 100644index 000000000..f42f4b03d--- /dev/null+++ b/tests/unit/browser_extension/test_broker_server.py@@ -0,0 +1,525 @@+from __future__ import annotations++import asyncio+import json+from collections.abc import AsyncGenerator+from contextlib import suppress++import aiohttp+import pytest+import pytest_asyncio++import skyvern.browser_extension.broker.client as client_module+from skyvern.browser_extension.broker.client import BrokerTransport, LegacyBridgeOwnerError+from skyvern.browser_extension.broker.protocol import (+ BROKER_FRAME_VERSION,+ BROKER_HEALTH_PATH,+ BROKER_PROTOCOL_VERSION,+ BROKER_WS_PATH,+ build_broker_nonce,+ compute_broker_client_proof,+)+from skyvern.browser_extension.broker.server import BrokerServer+from skyvern.browser_extension.errors import BrowserExtensionNotConnectedError, ExtensionRequestError+from skyvern.browser_extension.relay import ExtensionRelayServer++from ._broker_fakes import EXTENSION_ORIGIN, FakeExtension, wait_for++TOKEN = "broker-server-test-token"+++class BrokerHarness:+ def __init__(self, server: BrokerServer) -> None:+ self.server = server+ self.extension: FakeExtension | None = None+ self._transports: list[BrokerTransport] = []+ self.events: dict[str, list[tuple[str, dict]]] = {}+ self.disconnects: dict[str, int] = {}++ @property+ def port(self) -> int:+ return self.server.bound_port++ async def attach_extension(self, scoped_tabs: list[dict] | None = None) -> FakeExtension:+ extension = FakeExtension(self.port, TOKEN)+ await extension.connect(scoped_tabs)+ self.extension = extension+ return extension++ async def add_client(self, name: str) -> BrokerTransport:+ self.events[name] = []+ self.disconnects[name] = 0++ async def on_event(event: str, params: dict) -> None:+ self.events[name].append((event, params))++ async def on_disconnect() -> None:+ self.disconnects[name] += 1++ transport = BrokerTransport(TOKEN, self.port, on_event, on_disconnect)+ await transport.start()+ self._transports.append(transport)+ return transport++ async def close(self) -> None:+ for transport in self._transports:+ await transport.stop()+ if self.extension is not None:+ await self.extension.close()+ await self.server.stop()++ def events_for(self, name: str, event: str) -> list[dict]:+ return [params for recorded, params in self.events[name] if recorded == event]++[email protected](autouse=True)+def never_spawn_a_real_daemon(monkeypatch: pytest.MonkeyPatch) -> None:+ monkeypatch.setattr(client_module, "spawn_daemon", lambda port: False)+++@pytest_asyncio.fixture+async def harness() -> AsyncGenerator[BrokerHarness]:+ server = BrokerServer(TOKEN, 0, idle_timeout_seconds=3600.0)+ await server.start()+ harness = BrokerHarness(server)+ try:+ yield harness+ finally:+ await harness.close()+++async def test_two_agents_each_drive_their_own_tab_through_one_extension_socket(harness: BrokerHarness) -> None:+ extension = await harness.attach_extension()+ first = await harness.add_client("first")+ second = await harness.add_client("second")++ first_tab = (await first.request("tabs.create", {"url": "https://first.test"}))["tabId"]+ second_tab = (await second.request("tabs.create", {"url": "https://second.test"}))["tabId"]++ assert first_tab != second_tab+ await wait_for(lambda: bool(first.scoped_tabs) and bool(second.scoped_tabs))+ assert [tab["tabId"] for tab in first.scoped_tabs] == [first_tab]+ assert [tab["tabId"] for tab in second.scoped_tabs] == [second_tab]++ await first.request("debugger.attach", {"tabId": first_tab})+ await second.request("debugger.attach", {"tabId": second_tab})+ assert ("tabs.create", {"url": "https://first.test"}) in extension.requests+ assert ("debugger.attach", {"tabId": second_tab}) in extension.requests+++async def test_a_new_tab_is_never_offered_to_another_idle_agent(harness: BrokerHarness) -> None:+ extension = await harness.attach_extension()+ first = await harness.add_client("first")+ second = await harness.add_client("second")++ extension.create_response_gate = asyncio.Event()+ creating = asyncio.create_task(second.request("tabs.create", {"url": "https://second.test"}))+ await wait_for(lambda: bool(harness.server._deferred_tab_added))+ await harness.server._rotate_offers()+ extension.create_response_gate.set()++ second_tab = (await creating)["tabId"]+ await wait_for(lambda: [tab["tabId"] for tab in second.scoped_tabs] == [second_tab])++ assert first.scoped_tabs == []+++async def test_a_new_tab_removed_before_create_returns_is_not_reintroduced(harness: BrokerHarness) -> None:+ extension = await harness.attach_extension()+ first = await harness.add_client("first")+ second = await harness.add_client("second")++ extension.create_response_gate = asyncio.Event()+ creating = asyncio.create_task(second.request("tabs.create", {"url": "https://second.test"}))+ await wait_for(lambda: bool(harness.server._deferred_tab_added))+ tab_id = next(iter(harness.server._deferred_tab_added))+ await extension.send_event(+ "tabs.created",+ {"tabId": 900, "openerTabId": tab_id, "url": "https://popup.test"},+ )+ await extension.send_event(+ "tabs.created",+ {"tabId": 901, "openerTabId": 900, "url": "https://nested-popup.test"},+ )+ await wait_for(lambda: len(harness.server._deferred_tab_created) == 2)++ await extension.send_event("scope.tabRemoved", {"tabId": tab_id, "reason": "closed"})+ await wait_for(lambda: tab_id in harness.server._discarded_tab_ids)+ extension.create_response_gate.set()+ assert (await creating)["tabId"] == tab_id+ await asyncio.sleep(0.05)++ assert first.scoped_tabs == []+ assert second.scoped_tabs == []+ assert not harness.server._leases.knows_tab(tab_id)+ assert not harness.server._leases.knows_tab(900)+ assert not harness.server._leases.knows_tab(901)+++async def test_a_popup_tree_created_before_its_opener_response_follows_the_creator(harness: BrokerHarness) -> None:+ extension = await harness.attach_extension()+ first = await harness.add_client("first")+ second = await harness.add_client("second")++ extension.create_response_gate = asyncio.Event()+ creating = asyncio.create_task(second.request("tabs.create", {"url": "https://second.test"}))+ await wait_for(lambda: bool(harness.server._deferred_tab_added))+ opener_tab_id = next(iter(harness.server._deferred_tab_added))+ await extension.send_event(+ "tabs.created",+ {"tabId": 900, "openerTabId": opener_tab_id, "url": "https://popup.test"},+ )+ await extension.send_event(+ "tabs.created",+ {"tabId": 901, "openerTabId": 900, "url": "https://nested-popup.test"},+ )+ await wait_for(lambda: len(harness.server._deferred_tab_created) == 2)+ await harness.server._rotate_offers()+ extension.create_response_gate.set()++ assert (await creating)["tabId"] == opener_tab_id+ await wait_for(lambda: {tab["tabId"] for tab in second.scoped_tabs} == {opener_tab_id, 900, 901})++ assert first.scoped_tabs == []+ assert [event["tabId"] for event in harness.events_for("second", "tabs.created")] == [900, 901]+++async def test_an_extension_disconnect_drops_a_deferred_created_tab(harness: BrokerHarness) -> None:+ extension = await harness.attach_extension()+ await harness.add_client("first")+ second = await harness.add_client("second")++ extension.create_response_gate = asyncio.Event()+ creating = asyncio.create_task(second.request("tabs.create", {"url": "https://second.test"}))+ await wait_for(lambda: bool(harness.server._deferred_tab_added))+ tab_id = next(iter(harness.server._deferred_tab_added))+ await extension.close()++ with pytest.raises(BrowserExtensionNotConnectedError):+ await creating+ await wait_for(lambda: not second.connected)+ assert second.scoped_tabs == []+ assert not harness.server._leases.knows_tab(tab_id)+++async def test_an_agent_cannot_touch_a_tab_another_agent_leased(harness: BrokerHarness) -> None:+ extension = await harness.attach_extension()+ first = await harness.add_client("first")+ second = await harness.add_client("second")+ leased_tab = (await first.request("tabs.create", {"url": "https://first.test"}))["tabId"]+ extension.requests.clear()++ for operation in ("debugger.attach", "debugger.detach", "tabs.activate", "tabs.remove"):+ with pytest.raises(ExtensionRequestError) as error_info:+ await second.request(operation, {"tabId": leased_tab})+ assert error_info.value.code == "TAB_NOT_SCOPED"++ with pytest.raises(ExtensionRequestError):+ await second.request("debugger.send", {"tabId": leased_tab, "method": "Page.navigate", "params": {}})+ assert extension.requests == []+++async def test_the_lease_gate_normalizes_integer_floats_and_rejects_other_types(harness: BrokerHarness) -> None:+ extension = await harness.attach_extension()+ first = await harness.add_client("first")+ second = await harness.add_client("second")+ leased_tab = (await first.request("tabs.create", {"url": "https://first.test"}))["tabId"]+ extension.requests.clear()++ await first.request("debugger.attach", {"tabId": float(leased_tab)})+ assert extension.requests == [("debugger.attach", {"tabId": leased_tab})]++ for invalid_tab_id in (str(leased_tab), None, True, leased_tab + 0.5):+ with pytest.raises(ExtensionRequestError) as error_info:+ await second.request("debugger.attach", {"tabId": invalid_tab_id})+ assert error_info.value.code == "TAB_NOT_SCOPED"++ with pytest.raises(ExtensionRequestError) as error_info:+ await second.request("debugger.attach", {"tabId": float(leased_tab)})+ assert error_info.value.code == "TAB_NOT_SCOPED"+ assert extension.requests == [("debugger.attach", {"tabId": leased_tab})]+++async def test_debugger_events_reach_only_the_agent_that_leased_the_tab(harness: BrokerHarness) -> None:+ extension = await harness.attach_extension()+ first = await harness.add_client("first")+ await harness.add_client("second")+ leased_tab = (await first.request("tabs.create", {"url": "https://first.test"}))["tabId"]++ await extension.send_event(+ "debugger.event",+ {"tabId": leased_tab, "method": "Page.loadEventFired", "params": {}},+ )+ await wait_for(lambda: bool(harness.events_for("first", "debugger.event")))++ assert harness.events_for("second", "debugger.event") == []+ assert harness.events_for("first", "debugger.event")[0]["tabId"] == leased_tab+++async def test_a_popup_follows_the_agent_that_owns_its_opener(harness: BrokerHarness) -> None:+ extension = await harness.attach_extension()+ first = await harness.add_client("first")+ await harness.add_client("second")+ opener_tab = (await first.request("tabs.create", {"url": "https://first.test"}))["tabId"]++ await extension.send_event(+ "tabs.created",+ {"tabId": 900, "openerTabId": opener_tab, "url": "https://popup.test"},+ )+ await wait_for(lambda: {tab["tabId"] for tab in first.scoped_tabs} == {opener_tab, 900})++ assert harness.events_for("second", "tabs.created") == []+ assert harness.events_for("first", "tabs.created")[0]["tabId"] == 900+++async def test_a_hand_shared_tab_is_offered_to_exactly_one_idle_agent(harness: BrokerHarness) -> None:+ extension = await harness.attach_extension()+ first = await harness.add_client("first")+ second = await harness.add_client("second")++ await extension.send_event("scope.tabAdded", {"tabId": 500, "url": "https://shared.test", "title": "Shared"})+ await wait_for(lambda: bool(first.scoped_tabs) or bool(second.scoped_tabs))+ await asyncio.sleep(0.05)++ offered = [transport for transport in (first, second) if transport.scoped_tabs]+ assert len(offered) == 1+ assert offered[0].scoped_tabs[0]["tabId"] == 500++ # The offer is only a candidacy until the agent actually acts on the tab.+ await offered[0].request("debugger.attach", {"tabId": 500})+ other = second if offered[0] is first else first+ with pytest.raises(ExtensionRequestError) as error_info:+ await other.request("debugger.attach", {"tabId": 500})+ assert error_info.value.code == "TAB_NOT_SCOPED"+++async def test_a_departing_agent_releases_its_tabs_for_the_next_one(harness: BrokerHarness) -> None:+ extension = await harness.attach_extension()+ first = await harness.add_client("first")+ leased_tab = (await first.request("tabs.create", {"url": "https://first.test"}))["tabId"]+ await first.request("debugger.attach", {"tabId": leased_tab})+ extension.requests.clear()++ await first.stop()+ await wait_for(lambda: harness.server.client_count == 0)+ await wait_for(lambda: ("debugger.detach", {"tabId": leased_tab}) in extension.requests)++ second = await harness.add_client("second")+ await extension.send_event("scope.tabAdded", {"tabId": leased_tab, "url": "https://first.test", "title": ""})+ await wait_for(lambda: bool(second.scoped_tabs))+ assert second.scoped_tabs[0]["tabId"] == leased_tab+++async def test_closing_a_tab_notifies_only_its_holder_and_frees_the_lease(harness: BrokerHarness) -> None:+ extension = await harness.attach_extension()+ first = await harness.add_client("first")+ await harness.add_client("second")+ leased_tab = (await first.request("tabs.create", {"url": "https://first.test"}))["tabId"]++ await extension.send_event("scope.tabRemoved", {"tabId": leased_tab, "reason": "closed"})+ await wait_for(lambda: bool(harness.events_for("first", "scope.tabRemoved")))++ assert harness.events_for("second", "scope.tabRemoved") == []+ assert first.scoped_tabs == []+++async def test_an_extension_reconnect_voids_every_agent_s_claims(harness: BrokerHarness) -> None:+ extension = await harness.attach_extension()+ first = await harness.add_client("first")+ leased_tab = (await first.request("tabs.create", {"url": "https://first.test"}))["tabId"]++ await extension.close()+ await wait_for(lambda: not first.connected)+ assert harness.disconnects["first"] == 1+ assert first.scoped_tabs == []++ replacement = await harness.attach_extension(scoped_tabs=[{"tabId": leased_tab, "url": "", "title": ""}])+ await wait_for(lambda: first.connected)+ # The tab survived the reconnect but its debugger attachment did not, so it is unowned again+ # and reoffered rather than silently still leased.+ await wait_for(lambda: [tab["tabId"] for tab in first.scoped_tabs] == [leased_tab])+ assert replacement is harness.extension+++async def test_requests_fail_cleanly_while_no_extension_is_attached(harness: BrokerHarness) -> None:+ transport = await harness.add_client("first")++ with pytest.raises(BrowserExtensionNotConnectedError):+ await transport.request("tabs.create", {"url": "https://example.test"})+ assert not transport.connected+++async def test_a_client_can_mint_a_pairing_nonce_without_the_token_crossing_the_wire(+ harness: BrokerHarness,+) -> None:+ transport = await harness.add_client("first")++ first_nonce = await transport.acquire_pairing_nonce()+ second_nonce = await transport.acquire_pairing_nonce()++ assert first_nonce and second_nonce and first_nonce != second_nonce+ assert TOKEN not in first_nonce+ assert transport.bound_port == harness.port+++async def test_status_reports_the_daemon_without_leaking_tab_contents(harness: BrokerHarness) -> None:+ await harness.attach_extension()+ transport = await harness.add_client("first")+ await transport.request("tabs.create", {"url": "https://secret.test"})++ status = await transport.broker_status()++ assert status["extensionConnected"] is True+ assert status["clients"] == 1+ assert status["protocol"] == BROKER_PROTOCOL_VERSION+ assert "secret.test" not in json.dumps(status)+++async def test_broker_only_operations_stay_off_the_extension_socket(harness: BrokerHarness) -> None:+ extension = await harness.attach_extension()+ transport = await harness.add_client("first")++ await transport.acquire_pairing_nonce()+ await transport.broker_status()+ with pytest.raises(ExtensionRequestError) as error_info:+ await transport.request("tabs.shareEverything", {})++ assert error_info.value.code == "OP_NOT_ALLOWED"+ assert extension.requests == []+++async def test_a_client_without_the_token_is_rejected(harness: BrokerHarness) -> None:+ async with aiohttp.ClientSession() as session:+ async with session.ws_connect(f"ws://127.0.0.1:{harness.port}{BROKER_WS_PATH}") as websocket:+ challenge = json.loads((await websocket.receive()).data)+ client_nonce = build_broker_nonce()+ await websocket.send_json(+ {+ "v": BROKER_FRAME_VERSION,+ "type": "auth.proof",+ "clientNonce": client_nonce,+ "proof": compute_broker_client_proof("wrong-token", challenge["serverNonce"], client_nonce),+ }+ )+ closed = await websocket.receive()++ assert closed.type is aiohttp.WSMsgType.CLOSE+ assert websocket.close_code == 4403+++async def test_a_web_page_cannot_reach_the_broker_endpoint(harness: BrokerHarness) -> None:+ async with aiohttp.ClientSession() as session:+ async with session.ws_connect(+ f"ws://127.0.0.1:{harness.port}{BROKER_WS_PATH}",+ headers={"Origin": "https://evil.test"},+ ) as websocket:+ closed = await websocket.receive()++ assert closed.type is aiohttp.WSMsgType.CLOSE+ assert websocket.close_code == 4403+++async def test_the_extension_origin_is_also_refused_on_the_broker_endpoint(harness: BrokerHarness) -> None:+ async with aiohttp.ClientSession() as session:+ async with session.ws_connect(+ f"ws://127.0.0.1:{harness.port}{BROKER_WS_PATH}",+ headers={"Origin": EXTENSION_ORIGIN},+ ) as websocket:+ closed = await websocket.receive()++ assert closed.type is aiohttp.WSMsgType.CLOSE+ assert websocket.close_code == 4403+++async def test_the_health_endpoint_is_inert(harness: BrokerHarness) -> None:+ await harness.attach_extension()+ transport = await harness.add_client("first")+ await transport.request("tabs.create", {"url": "https://secret.test"})++ async with aiohttp.ClientSession() as session:+ async with session.get(f"http://127.0.0.1:{harness.port}{BROKER_HEALTH_PATH}") as response:+ body = await response.text()+ payload = json.loads(body)++ assert response.status == 200+ assert payload == {"v": BROKER_FRAME_VERSION, "broker": True, "protocol": BROKER_PROTOCOL_VERSION}+ assert TOKEN not in body+ assert "secret.test" not in body+++async def test_a_pre_broker_bridge_is_reported_instead_of_spawning_a_second_daemon() -> None:+ relay = ExtensionRelayServer(TOKEN, 0, _ignore_event)+ await relay.start()+ try:+ transport = BrokerTransport(TOKEN, relay.bound_port, _ignore_event)+ with pytest.raises(LegacyBridgeOwnerError):+ await transport.start()+ finally:+ await relay.stop()+++async def test_a_newer_client_makes_the_daemon_step_down(+ harness: BrokerHarness, monkeypatch: pytest.MonkeyPatch+) -> None:+ monkeypatch.setattr(client_module, "BROKER_PROTOCOL_VERSION", BROKER_PROTOCOL_VERSION + 1)+ transport = BrokerTransport(TOKEN, harness.port, _ignore_event)+ connecting = asyncio.create_task(transport.start())++ try:+ assert await asyncio.wait_for(harness.server.wait_for_shutdown(), 5.0) == "version_skew"+ finally:+ connecting.cancel()+ with suppress(asyncio.CancelledError, Exception):+ await connecting+ await transport.stop()+++async def test_an_older_client_leaves_the_daemon_alone(harness: BrokerHarness, monkeypatch: pytest.MonkeyPatch) -> None:+ monkeypatch.setattr(client_module, "BROKER_PROTOCOL_VERSION", BROKER_PROTOCOL_VERSION - 1)++ transport = await harness.add_client("older")++ assert transport.daemon_protocol == BROKER_PROTOCOL_VERSION+ assert harness.server.client_count == 1+++async def test_the_daemon_shuts_itself_down_once_the_last_agent_leaves() -> None:+ server = BrokerServer(TOKEN, 0, idle_timeout_seconds=0.0)+ await server.start()+ try:+ transport = BrokerTransport(TOKEN, server.bound_port, _ignore_event)+ await transport.start()+ await transport.stop()++ assert await asyncio.wait_for(server.wait_for_shutdown(), 15.0) == "idle"+ finally:+ await server.stop()+++async def _ignore_event(event: str, params: dict) -> None:+ returndiff --git a/tests/unit/browser_extension/test_mcp_glue.py b/tests/unit/browser_extension/test_mcp_glue.pyindex 5a424d4a8..11baf319e 100644--- a/tests/unit/browser_extension/test_mcp_glue.py+++ b/tests/unit/browser_extension/test_mcp_glue.py@@ -141,7 +141,7 @@ async def test_session_create_extension_not_connected_returns_pinned_guidance() -> None:runtime = SimpleNamespace(wait_for_extension=AsyncMock(return_value=False),- open_pairing_page=MagicMock(return_value=pairing_opened),+ open_pairing_page=AsyncMock(return_value=pairing_opened),)get_or_start = AsyncMock(return_value=runtime)resolve_browser = AsyncMock()@@ -156,7 +156,7 @@ async def test_session_create_extension_not_connected_returns_pinned_guidance(assert "extension-token" not in result["error"]["message"]assert "paste the token" not in result["error"]["message"]get_or_start.assert_awaited_once_with()- runtime.open_pairing_page.assert_called_once_with()+ runtime.open_pairing_page.assert_awaited_once_with()runtime.wait_for_extension.assert_awaited_once_with(10.0)resolve_browser.assert_not_awaited()@@ -427,12 +427,12 @@ def test_browser_extension_status_reports_configuration_without_printing_token(token_path = token_dir / "browser_extension_token"token_path.write_text(token)token_path.chmod(0o600)- connection = MagicMock()- connect = MagicMock(return_value=connection)+ probe = MagicMock(return_value="broker")monkeypatch.setenv("HOME", str(tmp_path))monkeypatch.setenv("SKYVERN_BROWSER_EXTENSION_PORT", "20123")monkeypatch.delenv("SKYVERN_BROWSER_EXTENSION_TOKEN", raising=False)- monkeypatch.setattr(browser_commands.socket, "create_connection", connect)+ monkeypatch.delenv("SKYVERN_BROWSER_EXTENSION_BROKER", raising=False)+ monkeypatch.setattr(browser_commands, "_bridge_mode", probe)result = CliRunner().invoke(browser_app, ["extension-status"])@@ -440,10 +440,27 @@ def test_browser_extension_status_reports_configuration_without_printing_token(assert str(BrowserExtensionRuntime.extension_dir().resolve()) in result.stdoutassert "pairing token: configured (file exists)" in result.stdoutassert "pairing token file permissions: OK" in result.stdout- assert "bridge listening on 20123" in result.stdout+ assert "shared broker: enabled" in result.stdout+ assert "bridge listening on 20123 (shared broker daemon)" in result.stdoutassert token not in result.stdout- connect.assert_called_once_with(("127.0.0.1", 20123), timeout=0.5)- connection.close.assert_called_once_with()+ probe.assert_called_once_with(20123)+++def test_browser_extension_status_flags_a_single_owner_bridge_as_unshareable(+ monkeypatch: pytest.MonkeyPatch,+ tmp_path: Path,+) -> None:+ monkeypatch.setenv("HOME", str(tmp_path))+ monkeypatch.setenv("SKYVERN_BROWSER_EXTENSION_PORT", "20124")+ monkeypatch.delenv("SKYVERN_BROWSER_EXTENSION_TOKEN", raising=False)+ monkeypatch.delenv("SKYVERN_BROWSER_EXTENSION_BROKER", raising=False)+ monkeypatch.setattr(browser_commands, "_bridge_mode", MagicMock(return_value="legacy"))++ result = CliRunner().invoke(browser_app, ["extension-status"])++ assert result.exit_code == 0+ assert "bridge listening on 20124 (single-owner session)" in result.stdout+ assert "share the bridge" in result.stdoutdef test_browser_extension_status_is_informational_when_bridge_is_not_running(@@ -453,12 +470,14 @@ def test_browser_extension_status_is_informational_when_bridge_is_not_running(monkeypatch.setenv("HOME", str(tmp_path))monkeypatch.delenv("SKYVERN_BROWSER_EXTENSION_TOKEN", raising=False)monkeypatch.delenv("SKYVERN_BROWSER_EXTENSION_PORT", raising=False)- monkeypatch.setattr(browser_commands.socket, "create_connection", MagicMock(side_effect=OSError))+ monkeypatch.setenv("SKYVERN_BROWSER_EXTENSION_BROKER", "0")+ monkeypatch.setattr(browser_commands, "_bridge_mode", MagicMock(return_value="none"))result = CliRunner().invoke(browser_app, ["extension-status"])assert result.exit_code == 0assert "pairing token: not configured" in result.stdout+ assert "shared broker: disabled (SKYVERN_BROWSER_EXTENSION_BROKER)" in result.stdoutassert "bridge not running (start your MCP server with --browser-extension)" in result.stdoutdiff --git a/tests/unit/browser_extension/test_runtime.py b/tests/unit/browser_extension/test_runtime.pyindex 9d7776531..342408338 100644--- a/tests/unit/browser_extension/test_runtime.py+++ b/tests/unit/browser_extension/test_runtime.py@@ -11,6 +11,7 @@ import pytestimport pytest_asyncioimport skyvern.browser_extension.runtime as runtime_module+from skyvern.browser_extension.broker.client import LegacyBridgeOwnerErrorfrom skyvern.browser_extension.errors import BrowserExtensionErrorfrom skyvern.browser_extension.runtime import BrowserExtensionRuntime@@ -24,7 +25,7 @@ class StubRelay:on_disconnect: Callable[[], Awaitable[None]] | None = None,*,calls: list[str],- start_error: OSError | None = None,+ start_error: BaseException | None = None,) -> None:self.token = tokenself.port = port@@ -36,7 +37,7 @@ class StubRelay:self.connected = Trueself.stop_count = 0- def get_or_create_pairing_nonce(self) -> str:+ async def acquire_pairing_nonce(self) -> str:return "runtime-pairing-nonce"async def start(self) -> None:@@ -89,7 +90,7 @@ async def reset_runtime() -> AsyncGenerator[None]:def install_stubs(monkeypatch: pytest.MonkeyPatch,*,- relay_start_error: OSError | None = None,+ relay_start_error: BaseException | None = None,) -> tuple[list[StubRelay], list[StubAdapter], list[str]]:relays: list[StubRelay] = []adapters: list[StubAdapter] = []@@ -113,6 +114,7 @@ def install_stubs(return adaptermonkeypatch.setattr(runtime_module, "_relay_factory", relay_factory)+ monkeypatch.setattr(runtime_module, "_broker_factory", relay_factory)monkeypatch.setattr(runtime_module, "_adapter_factory", adapter_factory)monkeypatch.setattr(runtime_module, "load_or_create_pairing_token", lambda: "runtime-test-token")return relays, adapters, calls@@ -149,13 +151,62 @@ async def test_open_pairing_page_uses_relay_nonce_without_exposing_token(monkeypmonkeypatch.setattr(BrowserExtensionRuntime, "open_extension_url", staticmethod(opener))runtime = await BrowserExtensionRuntime.get_or_start(21003)- assert runtime.open_pairing_page()- assert runtime.open_pairing_page()+ assert await runtime.open_pairing_page()+ assert await runtime.open_pairing_page()opener.assert_called_with("http://127.0.0.1:21003/pair#runtime-pairing-nonce")assert opener.call_count == 2assert "runtime-test-token" not in opener.call_args.args[0]+async def test_broker_is_the_default_transport_and_the_env_flag_opts_back_out(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ chosen: list[str] = []++ def make_factory(name: str):+ def factory(token, port, on_event, on_disconnect) -> StubRelay:+ chosen.append(name)+ return StubRelay(token, port, on_event, on_disconnect, calls=[])++ return factory++ monkeypatch.setattr(runtime_module, "_relay_factory", make_factory("relay"))+ monkeypatch.setattr(runtime_module, "_broker_factory", make_factory("broker"))+ monkeypatch.setattr(+ runtime_module, "_adapter_factory", lambda registry, relay: StubAdapter(registry, relay, calls=[])+ )+ monkeypatch.setattr(runtime_module, "load_or_create_pairing_token", lambda: "runtime-test-token")++ brokered = await BrowserExtensionRuntime.get_or_start(21010)+ assert brokered.brokered+ await brokered.shutdown()++ monkeypatch.setenv("SKYVERN_BROWSER_EXTENSION_BROKER", "0")+ legacy = await BrowserExtensionRuntime.get_or_start(21011)+ assert not legacy.brokered+ await legacy.shutdown()++ assert chosen == ["broker", "relay"]+++async def test_legacy_bridge_owner_explains_that_the_other_session_cannot_share(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ _, adapters, _ = install_stubs(monkeypatch, relay_start_error=LegacyBridgeOwnerError("held"))++ with pytest.raises(BrowserExtensionError) as error_info:+ await BrowserExtensionRuntime.get_or_start(23002)++ message = str(error_info.value)+ assert "23002" in message+ assert "older Skyvern MCP session" in message+ assert "restart that session" in message+ assert adapters[0].stop_count == 1+ assert BrowserExtensionRuntime.instance() is None++def test_open_extension_url_targets_google_chrome_on_macos(monkeypatch: pytest.MonkeyPatch) -> None:run = MagicMock()monkeypatch.setattr(runtime_module.sys, "platform", "darwin")diff --git a/tests/unit/test_agent_protocol_idempotency.py b/tests/unit/test_agent_protocol_idempotency.pynew file mode 100644index 000000000..06a0d0aad--- /dev/null+++ b/tests/unit/test_agent_protocol_idempotency.py@@ -0,0 +1,314 @@+import asyncio+from collections.abc import AsyncIterator+from contextlib import asynccontextmanager+from pathlib import Path++import httpx+import pytest+from fastapi import FastAPI+from sqlalchemy import func, select++from skyvern.forge import app+from skyvern.forge.sdk.db.agent_db import AgentDB+from skyvern.forge.sdk.db.models import Base, WorkflowModel+from skyvern.forge.sdk.db.repositories import workflows as workflows_repository+from skyvern.forge.sdk.routes import agent_protocol+from skyvern.forge.sdk.services import org_auth_service+from skyvern.forge.sdk.workflow.exceptions import FailedToCreateWorkflow+from skyvern.forge.sdk.workflow.models.workflow import WorkflowDefinition+from skyvern.forge.sdk.workflow.service import WorkflowService+from skyvern.schemas.workflows import WorkflowDefinitionYAML, WorkflowRequest+from tests.unit.force_stub_app import start_forge_stub_app++start_forge_stub_app()++WORKFLOW_CREATE_PAYLOAD = {+ "json_definition": {+ "title": "Replay test agent",+ "workflow_definition": {+ "parameters": [],+ "blocks": [{"label": "visit_page", "block_type": "task", "url": "https://example.com"}],+ },+ }+}+++async def test_create_workflow_honors_idempotency_key(+ monkeypatch: pytest.MonkeyPatch,+ tmp_path: Path,+) -> None:+ database = AgentDB(f"sqlite+aiosqlite:///{tmp_path / 'idempotency.db'}")+ async with database.engine.begin() as connection:+ await connection.run_sync(Base.metadata.create_all)+ organization = await database.organizations.create_organization(+ organization_name="Test",+ organization_id="o_test",+ )+ workflow_service = WorkflowService()+ creation_started = asyncio.Event()+ allow_creation_to_finish = asyncio.Event()+ replay_reached_creation = asyncio.Event()+ make_workflow_definition = workflow_service.make_workflow_definition+ workflow_creation_lock = getattr(database.workflows, "acquire_workflow_creation_lock", None)+ definition_calls = 0+ lock_calls = 0++ if workflow_creation_lock is not None:++ @asynccontextmanager+ async def tracked_workflow_creation_lock(lock_key: str) -> AsyncIterator[None]:+ nonlocal lock_calls+ lock_calls += 1+ if lock_calls == 2:+ replay_reached_creation.set()+ async with workflow_creation_lock(lock_key):+ yield++ monkeypatch.setattr(database.workflows, "acquire_workflow_creation_lock", tracked_workflow_creation_lock)++ async def delayed_make_workflow_definition(+ workflow_id: str,+ workflow_definition_yaml: WorkflowDefinitionYAML,+ ) -> WorkflowDefinition:+ nonlocal definition_calls+ definition_calls += 1+ if definition_calls == 1:+ creation_started.set()+ else:+ replay_reached_creation.set()+ await allow_creation_to_finish.wait()+ return await make_workflow_definition(workflow_id, workflow_definition_yaml)++ monkeypatch.setattr(workflow_service, "make_workflow_definition", delayed_make_workflow_definition)+ monkeypatch.setattr(app, "DATABASE", database)+ monkeypatch.setattr(app, "WORKFLOW_SERVICE", workflow_service)++ fastapi_app = FastAPI()+ fastapi_app.dependency_overrides[org_auth_service.get_current_org] = lambda: organization+ fastapi_app.dependency_overrides[org_auth_service.get_current_user_id_or_none] = lambda: "u_test"+ fastapi_app.include_router(agent_protocol.base_router, prefix="/v1")+ try:+ transport = httpx.ASGITransport(app=fastapi_app)+ async with httpx.AsyncClient(transport=transport, base_url="http://test") as client:+ original_request = asyncio.create_task(+ client.post(+ "/v1/agents",+ headers={"Idempotency-Key": "replay-key"},+ json=WORKFLOW_CREATE_PAYLOAD,+ )+ )+ await asyncio.wait_for(creation_started.wait(), timeout=5)+ replay_request = asyncio.create_task(+ client.post(+ "/v1/agents",+ headers={"Idempotency-Key": "replay-key"},+ json=WORKFLOW_CREATE_PAYLOAD,+ )+ )+ await asyncio.wait_for(replay_reached_creation.wait(), timeout=5)+ allow_creation_to_finish.set()+ original, replay = await asyncio.gather(original_request, replay_request)++ assert original.status_code == 200+ assert replay.status_code == 200+ assert replay.json() == original.json()+ assert len(original.json()["workflow_definition"]["blocks"]) == 1+ assert replay.json()["workflow_id"] == original.json()["workflow_id"]+ assert replay.json()["workflow_permanent_id"] == original.json()["workflow_permanent_id"]+ async with database.Session() as session:+ active_row_count = await session.scalar(+ select(func.count())+ .select_from(WorkflowModel)+ .where(WorkflowModel.organization_id == organization.organization_id)+ .where(WorkflowModel.deleted_at.is_(None))+ )+ assert active_row_count == 1++ distinct = await client.post(+ "/v1/agents",+ headers={"Idempotency-Key": "distinct-key"},+ json=WORKFLOW_CREATE_PAYLOAD,+ )++ assert distinct.status_code == 200+ assert distinct.json()["workflow_id"] != original.json()["workflow_id"]+ assert distinct.json()["workflow_permanent_id"] != original.json()["workflow_permanent_id"]+ async with database.Session() as session:+ active_row_count = await session.scalar(+ select(func.count())+ .select_from(WorkflowModel)+ .where(WorkflowModel.organization_id == organization.organization_id)+ .where(WorkflowModel.deleted_at.is_(None))+ )+ assert active_row_count == 2++ await workflow_service.delete_workflow_by_permanent_id(+ original.json()["workflow_permanent_id"],+ organization.organization_id,+ )+ deleted_replay = await client.post(+ "/v1/agents",+ headers={"Idempotency-Key": "replay-key"},+ json=WORKFLOW_CREATE_PAYLOAD,+ )+ blank_one = await client.post(+ "/v1/agents",+ headers={"Idempotency-Key": " "},+ json=WORKFLOW_CREATE_PAYLOAD,+ )+ blank_two = await client.post(+ "/v1/agents",+ headers={"Idempotency-Key": " "},+ json=WORKFLOW_CREATE_PAYLOAD,+ )++ assert deleted_replay.status_code == 200+ assert deleted_replay.json()["workflow_id"] == original.json()["workflow_id"]+ assert blank_one.status_code == 200+ assert blank_two.status_code == 200+ assert blank_one.json()["workflow_id"] != blank_two.json()["workflow_id"]+ finally:+ await database.engine.dispose()+++async def test_create_workflow_idempotency_wait_deadline_returns_conflict(+ monkeypatch: pytest.MonkeyPatch,+ tmp_path: Path,+) -> None:+ database = AgentDB(f"sqlite+aiosqlite:///{tmp_path / 'idempotency-timeout.db'}")+ async with database.engine.begin() as connection:+ await connection.run_sync(Base.metadata.create_all)+ organization = await database.organizations.create_organization(+ organization_name="Test",+ organization_id="o_test",+ )+ monkeypatch.setattr(app, "DATABASE", database)+ monkeypatch.setattr(app, "WORKFLOW_SERVICE", WorkflowService())++ fastapi_app = FastAPI()+ fastapi_app.dependency_overrides[org_auth_service.get_current_org] = lambda: organization+ fastapi_app.dependency_overrides[org_auth_service.get_current_user_id_or_none] = lambda: "u_test"+ fastapi_app.include_router(agent_protocol.base_router, prefix="/v1")++ try:+ transport = httpx.ASGITransport(app=fastapi_app)+ async with database.workflows.acquire_workflow_creation_lock("held"):+ monkeypatch.setattr(+ workflows_repository,+ "WORKFLOW_CREATION_LOCK_TIMEOUT_SECONDS",+ 0,+ raising=False,+ )+ async with httpx.AsyncClient(transport=transport, base_url="http://test") as client:+ response = await asyncio.wait_for(+ client.post(+ "/v1/agents",+ headers={"Idempotency-Key": "blocked-key"},+ json=WORKFLOW_CREATE_PAYLOAD,+ ),+ timeout=1,+ )++ assert response.status_code == 409+ assert response.json() == {"detail": "Workflow creation with this idempotency key is still in progress."}+ finally:+ await database.engine.dispose()+++async def test_create_workflow_idempotency_failure_does_not_record_first_save(+ monkeypatch: pytest.MonkeyPatch,+ tmp_path: Path,+) -> None:+ database = AgentDB(f"sqlite+aiosqlite:///{tmp_path / 'idempotency-rollback.db'}")+ async with database.engine.begin() as connection:+ await connection.run_sync(Base.metadata.create_all)+ organization = await database.organizations.create_organization(+ organization_name="Test",+ organization_id="o_test",+ )+ workflow_service = WorkflowService()+ hook_started = asyncio.Event()+ first_save_at: object | None = None++ async def record_first_save_at(*, organization_id: str, edited_by: str | None) -> None:+ nonlocal first_save_at+ first_save_at = object()+ hook_started.set()++ async def fail_cache_invalidation(*_args: object, **_kwargs: object) -> None:+ try:+ await asyncio.wait_for(hook_started.wait(), timeout=0.1)+ except TimeoutError:+ pass+ raise RuntimeError("cache invalidation failed")++ monkeypatch.setattr(app, "DATABASE", database)+ monkeypatch.setattr(app, "WORKFLOW_SERVICE", workflow_service)+ monkeypatch.setattr(app.AGENT_FUNCTION, "on_workflow_saved", record_first_save_at)+ monkeypatch.setattr(workflow_service, "maybe_delete_cached_code", fail_cache_invalidation)++ try:+ with pytest.raises(FailedToCreateWorkflow, match="cache invalidation failed"):+ await agent_protocol.create_workflow(+ data=WorkflowRequest.model_validate(WORKFLOW_CREATE_PAYLOAD),+ folder_id=None,+ current_org=organization,+ user_id="u_test",+ idempotency_key="rollback-key",+ )++ assert first_save_at is None+ finally:+ await database.engine.dispose()+++async def test_create_workflow_idempotency_generates_title_before_lock(+ monkeypatch: pytest.MonkeyPatch,+ tmp_path: Path,+) -> None:+ database = AgentDB(f"sqlite+aiosqlite:///{tmp_path / 'idempotency-title.db'}")+ async with database.engine.begin() as connection:+ await connection.run_sync(Base.metadata.create_all)+ organization = await database.organizations.create_organization(+ organization_name="Test",+ organization_id="o_test",+ )+ workflow_service = WorkflowService()+ workflow_creation_lock = database.workflows.acquire_workflow_creation_lock+ events: list[str] = []++ async def generate_title(*_args: object, **_kwargs: object) -> str:+ events.append("title")+ return "Generated title"++ @asynccontextmanager+ async def tracked_workflow_creation_lock(lock_key: str) -> AsyncIterator[None]:+ events.append("lock")+ async with workflow_creation_lock(lock_key):+ yield++ monkeypatch.setattr(app, "DATABASE", database)+ monkeypatch.setattr(app, "WORKFLOW_SERVICE", workflow_service)+ monkeypatch.setattr(database.workflows, "acquire_workflow_creation_lock", tracked_workflow_creation_lock)+ monkeypatch.setattr("skyvern.forge.sdk.workflow.service.generate_workflow_title", generate_title)+ request = WorkflowRequest.model_validate(WORKFLOW_CREATE_PAYLOAD)+ assert request.json_definition is not None+ request.json_definition.title = "New Agent"++ try:+ workflow = await agent_protocol.create_workflow(+ data=request,+ folder_id=None,+ current_org=organization,+ user_id="u_test",+ idempotency_key="title-key",+ )++ assert workflow.title == "Generated title"+ assert events == ["title", "lock"]+ finally:+ await database.engine.dispose()