Skip to content

Automate browser based workflows with AI

Bound workflow idempotency waits (SKY-13795) (#8174)

Aaron Perezcb658301849b
diff --git a/docs/api-reference/openapi.json b/docs/api-reference/openapi.json
index 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__.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
index 1b8ab773b..f84c5f475 100644
--- a/skyvern/browser_extension/cdp_adapter.py
+++ b/skyvern/browser_extension/cdp_adapter.py
@@ -5,7 +5,6 @@ import json
import secrets
from collections.abc import Coroutine
from functools import partial
-from typing import TYPE_CHECKING
import structlog
from aiohttp import WSMsgType, web
@@ -14,10 +13,7 @@ from skyvern.browser_extension.errors import BrowserExtensionError, ExtensionReq
from skyvern.browser_extension.protocol import is_cdp_method_allowed
from skyvern.browser_extension.relay import _MAX_WS_MESSAGE_BYTES
from skyvern.browser_extension.target_registry import VirtualTargetRegistry
-
-if TYPE_CHECKING:
- from skyvern.browser_extension.relay import ExtensionRelayServer
-
+from skyvern.browser_extension.transport import ExtensionTransport
LOG = 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 = registry
self._relay = relay
self._capability = secrets.token_urlsafe(32)
diff --git a/skyvern/browser_extension/relay.py b/skyvern/browser_extension/relay.py
index a17131321..de8f96cb3 100644
--- a/skyvern/browser_extension/relay.py
+++ b/skyvern/browser_extension/relay.py
@@ -539,6 +539,12 @@ class ExtensionRelayServer:
self.bound_port = port
self.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 nonce
return 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.py
index eaf9f152f..f408114b8 100644
--- a/skyvern/browser_extension/runtime.py
+++ b/skyvern/browser_extension/runtime.py
@@ -13,14 +13,18 @@ from typing import Any, Protocol
import structlog
from skyvern.browser_extension.auth import load_or_create_pairing_token
+from skyvern.browser_extension.broker.client import BrokerTransport, LegacyBridgeOwnerError
from skyvern.browser_extension.errors import BrowserExtensionError
from skyvern.browser_extension.relay import ExtensionRelayServer
from skyvern.browser_extension.target_registry import VirtualTargetRegistry
+from skyvern.browser_extension.transport import ExtensionTransport
LOG = 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_VALUES
def _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 = transport
self._adapter = adapter
+ self._brokered = brokered
self._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 exc
except 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 exc
raise
except 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 = runtime
return runtime
@@ -118,10 +139,14 @@ class BrowserExtensionRuntime:
@property
def extension_connected(self) -> bool:
- return self._relay.connected
+ return self._transport.connected
+
+ @property
+ def brokered(self) -> bool:
+ return self._brokered
async def wait_for_extension(self, timeout: float = 10.0) -> bool:
- return await self._relay.wait_connected(timeout)
+ return await self._transport.wait_connected(timeout)
@staticmethod
def open_extension_url(url: str) -> bool:
@@ -167,9 +192,13 @@ class BrowserExtensionRuntime:
return True
return 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:
return
self._stopped = True
try:
- 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.py
new file mode 100644
index 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.py
index 9b4131769..c7cfa2f82 100644
--- a/skyvern/cli/commands/browser.py
+++ b/skyvern/cli/commands/browser.py
@@ -23,8 +23,9 @@ import typer
from skyvern._cli_bootstrap import prepare_cli_runtime
from skyvern.browser_extension.auth import load_or_create_pairing_token
+from skyvern.browser_extension.broker.protocol import BROKER_HEALTH_PATH
from skyvern.browser_extension.errors import BrowserExtensionError
-from skyvern.browser_extension.runtime import BrowserExtensionRuntime
+from skyvern.browser_extension.runtime import BrowserExtensionRuntime, broker_enabled
from 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.py
index 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.py
index 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_error
diff --git a/skyvern/forge/sdk/db/base_alchemy_db.py b/skyvern/forge/sdk/db/base_alchemy_db.py
index 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, Callable
import structlog
from sqlalchemy.exc import SQLAlchemyError
-from sqlalchemy.ext.asyncio import AsyncEngine, AsyncSession, async_sessionmaker
+from sqlalchemy.ext.asyncio import AsyncConnection, AsyncEngine, AsyncSession, async_sessionmaker
LOG = 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()
+
@asynccontextmanager
async 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.py
index 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, asynccontextmanager
from dataclasses import dataclass
from datetime import datetime, timezone
-from typing import Any, cast
+from typing import TYPE_CHECKING, Any, cast
import 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 AsyncEngine
from skyvern.constants import DEFAULT_SCRIPT_RUN_ID, DEFAULT_WORKFLOW_TITLES
from skyvern.forge.sdk.browser_action_policy import BrowserActionPolicy, declare_policy
@@ -47,7 +52,15 @@ from skyvern.forge.sdk.workflow.runtime_completion import carried_contract, with
from skyvern.schemas.runs import ProxyLocationInput
from 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) -> N
class 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.py
index 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 app
from skyvern.forge.prompts import prompt_engine
+from skyvern.forge.sdk.api.crypto import calculate_sha256
from 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 WorkflowCreationLockTimeout
from skyvern.forge.sdk.enterprise_features import collect_enterprise_gated_run_features
from skyvern.forge.sdk.executor.factory import AsyncExecutorFactory
from 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 parameter
if 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_workflow
return 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 exc
except WorkflowDefinitionValidationException as e:
raise e
except (SkyvernHTTPException, ValidationError) as e:
diff --git a/skyvern/forge/sdk/workflow/service.py b/skyvern/forge/sdk/workflow/service.py
index 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.title
if 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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 None
diff --git a/tests/unit/browser_extension/test_broker_protocol.py b/tests/unit/browser_extension/test_broker_protocol.py
new file mode 100644
index 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.py
new file mode 100644
index 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:
+ return
diff --git a/tests/unit/browser_extension/test_mcp_glue.py b/tests/unit/browser_extension/test_mcp_glue.py
index 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.stdout
assert "pairing token: configured (file exists)" in result.stdout
assert "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.stdout
assert 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.stdout
def 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 == 0
assert "pairing token: not configured" in result.stdout
+ assert "shared broker: disabled (SKYVERN_BROWSER_EXTENSION_BROKER)" in result.stdout
assert "bridge not running (start your MCP server with --browser-extension)" in result.stdout
diff --git a/tests/unit/browser_extension/test_runtime.py b/tests/unit/browser_extension/test_runtime.py
index 9d7776531..342408338 100644
--- a/tests/unit/browser_extension/test_runtime.py
+++ b/tests/unit/browser_extension/test_runtime.py
@@ -11,6 +11,7 @@ import pytest
import pytest_asyncio
import skyvern.browser_extension.runtime as runtime_module
+from skyvern.browser_extension.broker.client import LegacyBridgeOwnerError
from skyvern.browser_extension.errors import BrowserExtensionError
from 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 = token
self.port = port
@@ -36,7 +37,7 @@ class StubRelay:
self.connected = True
self.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 adapter
monkeypatch.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(monkeyp
monkeypatch.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 == 2
assert "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.py
new file mode 100644
index 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()