Skip to content

Open-source Python library for AI browser agents, plus Browser Use Cloud: stealth browsers and a hosted agent API.

v1 remote

Gregor Žunič1399d4b2571f
diff --git a/browser_use/__init__.py b/browser_use/__init__.py
index 7882c7ffe..4ad3cc7e3 100644
--- a/browser_use/__init__.py
+++ b/browser_use/__init__.py
@@ -60,6 +60,7 @@ if TYPE_CHECKING:
from browser_use.llm.oci_raw.chat import ChatOCIRaw
from browser_use.llm.ollama.chat import ChatOllama
from browser_use.llm.openai.chat import ChatOpenAI
+ from browser_use.remote_execute import remote_execute
from browser_use.tools.service import Controller, Tools
@@ -92,6 +93,8 @@ _LAZY_IMPORTS = {
'ChatOllama': ('browser_use.llm.ollama.chat', 'ChatOllama'),
# LLM models module
'models': ('browser_use.llm.models', None),
+ # Remote execution
+ 'remote_execute': ('browser_use.remote_execute', 'remote_execute'),
}
@@ -141,4 +144,6 @@ __all__ = [
'Controller',
# LLM models module
'models',
+ # Remote execution
+ 'remote_execute',
]
diff --git a/browser_use/remote_execute/__init__.py b/browser_use/remote_execute/__init__.py
new file mode 100644
index 000000000..59e60ab0d
--- /dev/null
+++ b/browser_use/remote_execute/__init__.py
@@ -0,0 +1,41 @@
+"""Remote execution package for browser-use
+
+This package provides type-safe remote code execution with SSE streaming.
+
+Example:
+ from browser_use.remote_execute import remote_execute, SSEEvent, SSEEventType
+
+ @remote_execute(log_level="INFO")
+ async def my_task(browser: Browser) -> str:
+ page = await browser.get_current_page()
+ await page.goto("https://example.com")
+ return await page.title()
+
+ result = await my_task()
+"""
+
+from browser_use.remote_execute.remote import RemoteExecutionError, remote_execute
+from browser_use.remote_execute.views import (
+ BrowserCreatedData,
+ ErrorData,
+ ExecutionResponse,
+ LogData,
+ ResultData,
+ SSEEvent,
+ SSEEventType,
+)
+
+__all__ = [
+ # Main decorator
+ 'remote_execute',
+ 'RemoteExecutionError',
+ # Event types
+ 'SSEEvent',
+ 'SSEEventType',
+ # Event data models
+ 'BrowserCreatedData',
+ 'LogData',
+ 'ResultData',
+ 'ErrorData',
+ 'ExecutionResponse',
+]
diff --git a/browser_use/remote_execute/remote.py b/browser_use/remote_execute/remote.py
new file mode 100644
index 000000000..31470391e
--- /dev/null
+++ b/browser_use/remote_execute/remote.py
@@ -0,0 +1,625 @@
+import ast
+import base64
+import inspect
+import json
+import os
+import sys
+from functools import wraps
+from typing import Any, Callable, Coroutine, TypeVar, Union, cast, get_args, get_origin
+
+import httpx
+
+from browser_use.remote_execute.views import (
+ BrowserCreatedData,
+ ErrorData,
+ LogData,
+ RemoteExecutionError,
+ ResultData,
+ SSEEvent,
+ SSEEventType,
+)
+
+T = TypeVar('T')
+
+
+def get_terminal_width() -> int:
+ """Get terminal width, default to 80 if unable to detect"""
+ try:
+ return os.get_terminal_size().columns
+ except (AttributeError, OSError):
+ return 80
+
+
+def remote_execute(
+ BROWSER_USE_API_KEY: str | None = None,
+ server_url: str | None = None,
+ log_level: str = 'INFO',
+ on_browser_created: Callable[[BrowserCreatedData], None] | None = None,
+ on_instance_ready: Callable[[], None] | None = None,
+ on_log: Callable[[LogData], None] | None = None,
+ on_result: Callable[[ResultData], None] | None = None,
+ on_error: Callable[[ErrorData], None] | None = None,
+ **env_vars: str,
+):
+ """Decorator to execute browser automation code remotely.
+
+ Args:
+ BROWSER_USE_API_KEY: Browser-Use API key (defaults to BROWSER_USE_API_KEY env var)
+ server_url: Remote execution server URL (defaults to localhost:8080)
+ log_level: Logging level for remote execution. Options:
+ - "INFO" (default): Shows important logs from browser-use agent
+ - "DEBUG": Shows all debug logs including internal browser operations
+ - "WARNING": Shows only warnings and errors
+ - "ERROR": Shows only errors
+ on_browser_created: Callback when browser session is created. Receives BrowserCreatedData with live_url.
+ on_instance_ready: Callback when instance is ready for execution.
+ on_log: Callback for log events. Receives LogData.
+ on_result: Callback when execution completes. Receives ResultData.
+ on_error: Callback for error events. Receives ErrorData.
+ **env_vars: Additional environment variables to pass to remote execution
+
+ Example:
+ @remote_execute(
+ log_level="DEBUG",
+ on_browser_created=lambda data: print(f"Watch browser: {data.live_url}")
+ )
+ async def my_task(browser: Browser) -> str:
+ page = await browser.get_current_page()
+ await page.goto("https://example.com")
+ return await page.get_title()
+
+ Event Callbacks Example:
+ def show_live_url(data: BrowserCreatedData):
+ print(f"Browser session: {data.session_id}")
+ print(f"Live URL: {data.live_url}")
+
+ @remote_execute(on_browser_created=show_live_url)
+ async def my_task(browser: Browser):
+ ...
+ """
+
+ def decorator(func: Callable[..., Coroutine[Any, Any, T]]) -> Callable[..., Coroutine[Any, Any, T]]:
+ @wraps(func)
+ async def wrapper(*args, **kwargs) -> T:
+ # Get API key
+ api_key = BROWSER_USE_API_KEY or os.getenv('BROWSER_USE_API_KEY')
+ if not api_key:
+ raise RemoteExecutionError('BROWSER_USE_API_KEY is required')
+
+ # Extract function source and create execution code
+ source = inspect.getsource(func)
+ tree = ast.parse(source)
+
+ # Find and clean the function
+ for node in tree.body:
+ if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+ node.decorator_list = [] # Remove decorators
+ break
+
+ # Use cleaned source (without decorators) for extraction
+ cleaned_source = ast.unparse(tree)
+
+ # Extract imports and classes used in the function
+ local_classes = _extract_local_classes_from_source(func, cleaned_source)
+
+ # Get combined source (function + classes) for import detection
+ class_sources = [ast.unparse(cls) for cls in local_classes]
+ combined_source = cleaned_source + '\n'.join(class_sources)
+ used_imports = _extract_used_imports(func, combined_source)
+
+ # Add necessary imports
+ imports = [
+ ast.ImportFrom(module='browser_use', names=[ast.alias(name='Browser')], level=0),
+ ast.ImportFrom(module='browser_use', names=[ast.alias(name='Agent')], level=0),
+ ]
+
+ # Add extracted imports
+ imports.extend(used_imports)
+
+ function_code = ast.unparse(ast.Module(body=imports + local_classes + tree.body, type_ignores=[]))
+
+ # Create execution wrapper that expects browser parameter
+ # The executor now captures the return value directly, no need for RESULT: marker
+ execution_code = f"""
+{function_code}
+
+async def runner(browser):
+ \"\"\"Wrapper function that calls the user function with browser\"\"\"
+ result = await {func.__name__}(browser)
+ return result
+"""
+
+ # Send to server
+ payload: dict[str, Any] = {
+ 'code': base64.b64encode(execution_code.encode()).decode(),
+ }
+ # Combine env_vars with LOG_LEVEL
+ combined_env: dict[str, str] = env_vars.copy() if env_vars else {}
+ combined_env['LOG_LEVEL'] = log_level.upper()
+ payload['env'] = combined_env
+
+ # Use custom server URL or default to localhost with SSE streaming endpoint
+ url = server_url or 'https://remote.api.browser-use.com/remote-execute-stream'
+
+ # Headers with API key
+ headers = {
+ 'X-API-Key': api_key,
+ }
+
+ # Handle SSE streaming
+ # Use sentinel to distinguish "no result received" from "result is None"
+ _NO_RESULT = object()
+ execution_result = _NO_RESULT
+ live_url_shown = False
+ execution_started = False
+
+ async with httpx.AsyncClient(timeout=1800.0) as client:
+ async with client.stream('POST', url, json=payload, headers=headers) as response:
+ response.raise_for_status()
+
+ # Parse SSE events line by line
+ async for line in response.aiter_lines():
+ if not line or not line.startswith('data: '):
+ continue
+
+ # Extract JSON from "data: {...}"
+ event_json = line[6:] # Remove "data: " prefix
+ try:
+ # Parse into type-safe event model
+ event = SSEEvent.from_json(event_json)
+
+ # Handle different event types with type safety
+ if event.type == SSEEventType.BROWSER_CREATED:
+ # Type-safe access to BrowserCreatedData
+ assert isinstance(event.data, BrowserCreatedData)
+
+ # Call user callback if provided
+ if on_browser_created:
+ try:
+ on_browser_created(event.data)
+ except Exception as e:
+ print(f'⚠️ Error in on_browser_created callback: {e}')
+
+ # Show live URL in console (unless user wants to handle it)
+ if event.data.live_url and not live_url_shown:
+ width = get_terminal_width()
+ print('\n' + '━' * width)
+ print('👁️ LIVE BROWSER VIEW (Click to watch)')
+ print(f'🔗 {event.data.live_url}')
+ print('━' * width)
+ live_url_shown = True
+
+ elif event.type == SSEEventType.LOG:
+ # Type-safe access to LogData
+ assert isinstance(event.data, LogData)
+ message = event.data.message
+ level = event.data.level
+
+ # Call user callback if provided
+ if on_log:
+ try:
+ on_log(event.data)
+ except Exception as e:
+ print(f'⚠️ Error in on_log callback: {e}')
+
+ # Handle different log levels
+ if level == 'stdout':
+ # Print stdout with prefix to show it's from remote execution
+ if not execution_started:
+ width = get_terminal_width()
+ print('\n' + '─' * width)
+ print('⚡ Runtime Output')
+ print('─' * width)
+ execution_started = True
+ print(f' {message}', end='')
+ elif level == 'stderr':
+ # Print stderr with prefix
+ if not execution_started:
+ width = get_terminal_width()
+ print('\n' + '─' * width)
+ print('⚡ Runtime Output')
+ print('─' * width)
+ execution_started = True
+ print(
+ f'⚠️ {message}',
+ end='',
+ file=sys.stderr,
+ )
+ elif level == 'info':
+ # System info messages (credit check, etc)
+ if 'credit' in message.lower():
+ # Extract amount from message
+ import re
+
+ match = re.search(r'\$[\d,]+\.?\d*', message)
+ if match:
+ print(f'💰 You have {match.group()} credits')
+ else:
+ print(f'ℹ️ {message}')
+ else:
+ print(f' {message}')
+
+ elif event.type == SSEEventType.INSTANCE_READY:
+ # Call user callback if provided
+ if on_instance_ready:
+ try:
+ on_instance_ready()
+ except Exception as e:
+ print(f'⚠️ Error in on_instance_ready callback: {e}')
+
+ # Print separator before execution starts
+ print('✅ Browser ready, starting execution...\n')
+
+ elif event.type == SSEEventType.RESULT:
+ # Type-safe access to ResultData
+ assert isinstance(event.data, ResultData)
+ exec_response = event.data.execution_response
+
+ # Call user callback if provided
+ if on_result:
+ try:
+ on_result(event.data)
+ except Exception as e:
+ print(f'⚠️ Error in on_result callback: {e}')
+
+ if exec_response.success:
+ # The result is now in the 'result' field, not stdout
+ execution_result = exec_response.result
+ # Print closing separator with spacing
+ if execution_started:
+ width = get_terminal_width()
+ print('\n' + '─' * width)
+ print() # Extra newline for spacing
+ else:
+ error_msg = exec_response.error or 'Unknown error'
+ raise RemoteExecutionError(f'Execution failed: {error_msg}')
+
+ elif event.type == SSEEventType.ERROR:
+ # Type-safe access to ErrorData
+ assert isinstance(event.data, ErrorData)
+
+ # Call user callback if provided
+ if on_error:
+ try:
+ on_error(event.data)
+ except Exception as e:
+ print(f'⚠️ Error in on_error callback: {e}')
+
+ raise RemoteExecutionError(f'Execution failed: {event.data.error}')
+
+ except (json.JSONDecodeError, ValueError) as e:
+ # Skip malformed events
+ continue
+
+ # Reconstruct based on return type annotation
+ if execution_result is not _NO_RESULT:
+ # We received a result (even if it's None)
+ return_annotation = func.__annotations__.get('return')
+ if return_annotation:
+ parsed_result = _parse_with_type_annotation(execution_result, return_annotation)
+ return parsed_result
+ return execution_result # type: ignore[return-value]
+
+ raise RemoteExecutionError('No result received from execution')
+
+ # Preserve type info
+ wrapper.__annotations__ = func.__annotations__.copy()
+ if 'browser' in wrapper.__annotations__:
+ del wrapper.__annotations__['browser']
+
+ # Update signature to remove browser parameter
+ sig = inspect.signature(func)
+ params = [p for p in sig.parameters.values() if p.name != 'browser']
+ wrapper.__signature__ = sig.replace(parameters=params) # type: ignore[attr-defined]
+
+ return cast(Callable[..., Coroutine[Any, Any, T]], wrapper)
+
+ return decorator
+
+
+def _parse_with_type_annotation(data: Any, annotation: Any) -> Any:
+ """Parse data with type annotation (FastAPI-style parsing)
+
+ This function recursively reconstructs Pydantic models from serialized data,
+ handling nested structures properly.
+ """
+ try:
+ # Handle None
+ if data is None:
+ return None
+
+ # Get origin and args for generic types
+ origin = get_origin(annotation)
+ args = get_args(annotation)
+
+ # Handle Union types (both typing.Union and | syntax)
+ if origin is Union or (hasattr(annotation, '__class__') and annotation.__class__.__name__ == 'UnionType'):
+ # Try each union member until one works
+ union_args = args or getattr(annotation, '__args__', [])
+ for arg in union_args:
+ if arg is type(None) and data is None:
+ return None
+ if arg is not type(None):
+ try:
+ return _parse_with_type_annotation(data, arg)
+ except Exception:
+ continue
+ return data
+
+ # Handle List types - recursively parse elements
+ if origin is list:
+ if not isinstance(data, list):
+ return data
+ if args:
+ return [_parse_with_type_annotation(item, args[0]) for item in data]
+ return data
+
+ # Handle Dict types - recursively parse keys and values
+ if origin is dict:
+ if not isinstance(data, dict):
+ return data
+ if len(args) == 2:
+ # Dict[key_type, value_type]
+ return {_parse_with_type_annotation(k, args[0]): _parse_with_type_annotation(v, args[1]) for k, v in data.items()}
+ return data
+
+ # Handle Optional (which is Union[T, None])
+ if hasattr(annotation, '__origin__') and annotation.__origin__ is Union:
+ union_args = annotation.__args__
+ if len(union_args) == 2 and type(None) in union_args:
+ # This is Optional[T]
+ non_none_type = union_args[0] if union_args[1] is type(None) else union_args[1]
+ return _parse_with_type_annotation(data, non_none_type)
+
+ # Handle Pydantic v2 models (model_validate method)
+ if hasattr(annotation, 'model_validate'):
+ try:
+ # First try with strict validation
+ return annotation.model_validate(data)
+ except Exception:
+ # If strict validation fails, try to recursively reconstruct nested models
+ # This handles cases where nested Pydantic models have extra fields
+ try:
+ if hasattr(annotation, 'model_fields') and isinstance(data, dict):
+ # Recursively parse nested Pydantic models
+ parsed_data = {}
+ for field_name, field_info in annotation.model_fields.items():
+ if field_name in data:
+ field_type = field_info.annotation
+ parsed_data[field_name] = _parse_with_type_annotation(data[field_name], field_type)
+ # Use model_construct to bypass validation
+ if hasattr(annotation, 'model_construct'):
+ return annotation.model_construct(**parsed_data)
+ except Exception:
+ pass
+
+ # Handle Pydantic v1 models (parse_obj method)
+ if hasattr(annotation, 'parse_obj'):
+ try:
+ return annotation.parse_obj(data)
+ except Exception:
+ # Try construct method for Pydantic v1 with recursive parsing
+ try:
+ if hasattr(annotation, '__fields__') and isinstance(data, dict):
+ # Recursively parse nested Pydantic models (v1)
+ parsed_data = {}
+ for field_name, field_info in annotation.__fields__.items():
+ if field_name in data:
+ field_type = field_info.outer_type_
+ parsed_data[field_name] = _parse_with_type_annotation(data[field_name], field_type)
+ if hasattr(annotation, 'construct'):
+ return annotation.construct(**parsed_data)
+ except Exception:
+ pass
+
+ # Handle regular classes with constructor (fallback)
+ if inspect.isclass(annotation) and isinstance(data, dict):
+ try:
+ return annotation(**data)
+ except Exception:
+ pass
+
+ # Return as-is for basic types
+ return data
+
+ except Exception:
+ # If parsing fails, return original data
+ return data
+
+
+def _extract_local_classes_from_source(func: Callable, cleaned_source: str) -> list:
+ """Extract local class and function definitions used by the function
+
+ Args:
+ func: The function being decorated
+ cleaned_source: The source code without decorators
+ """
+ definitions = []
+
+ # List of known external packages to skip
+ external_packages = {
+ 'browser_use',
+ 'pydantic',
+ 'typing',
+ 'requests',
+ 'httpx',
+ 'json',
+ 'datetime',
+ 'asyncio',
+ 'os',
+ 'sys',
+ 're',
+ 'time',
+ 'collections',
+ 'itertools',
+ 'functools',
+ 'base64',
+ 'logging',
+ 'numpy',
+ 'pandas',
+ 'beautifulsoup4',
+ 'bs4',
+ 'scrapy',
+ 'lxml',
+ }
+
+ # Get the module where the function is defined
+ module = inspect.getmodule(func)
+ if not module:
+ return definitions
+
+ # Use the cleaned source (without decorators) to find referenced names
+ source = cleaned_source
+
+ # Get the main function name to exclude it from extraction
+ main_func_name = func.__name__
+
+ # Parse the entire module to find definitions and imports
+ try:
+ module_source = inspect.getsource(module)
+ module_tree = ast.parse(module_source)
+
+ # Find all class and function definitions in the current module
+ for node in ast.walk(module_tree):
+ if isinstance(node, (ast.ClassDef, ast.FunctionDef, ast.AsyncFunctionDef)):
+ # Skip the main function itself
+ if node.name == main_func_name:
+ continue
+
+ # Check if this definition is referenced in the function
+ if node.name in source:
+ # Strip decorators from extracted definitions
+ node.decorator_list = []
+ definitions.append(node)
+
+ # Handle local imports like "from views import Result"
+ import_files = []
+ for node in module_tree.body: # Only check top-level imports
+ if isinstance(node, ast.ImportFrom):
+ # Skip if it's a relative import or external package
+ if node.level > 0 or not node.module:
+ continue
+
+ package_name = node.module.split('.')[0]
+ if package_name in external_packages:
+ continue
+
+ # Try to find the module file in the same directory
+ try:
+ if not module.__file__:
+ continue
+ module_dir = os.path.dirname(module.__file__)
+ import_file = os.path.join(module_dir, f'{node.module}.py')
+ if os.path.exists(import_file):
+ import_files.append((import_file, [alias.name for alias in node.names]))
+ except Exception:
+ pass
+
+ # Extract definitions from imported local files
+ for import_file, imported_names in import_files:
+ try:
+ with open(import_file, 'r') as f:
+ imported_source = f.read()
+ imported_tree = ast.parse(imported_source)
+
+ for node in ast.walk(imported_tree):
+ if isinstance(node, (ast.ClassDef, ast.FunctionDef, ast.AsyncFunctionDef)):
+ # Include if explicitly imported or used in source
+ if node.name in imported_names or node.name in source:
+ # Strip decorators from imported definitions too
+ node.decorator_list = []
+ definitions.append(node)
+
+ except Exception:
+ pass
+
+ except Exception:
+ pass
+
+ return definitions
+
+
+def _extract_used_imports(func: Callable, source: str) -> list:
+ """Extract all imports from the function's module that are used in the function"""
+ imports = []
+
+ # List of known safe packages that should be imported
+ # These are packages that are likely to be installed in the remote environment
+ safe_packages = {
+ 'browser_use',
+ 'pydantic',
+ 'typing',
+ 'requests',
+ 'httpx',
+ 'json',
+ 'datetime',
+ 'asyncio',
+ 'os',
+ 'sys',
+ 're',
+ 'time',
+ 'collections',
+ 'itertools',
+ 'functools',
+ 'base64',
+ 'logging',
+ 'numpy',
+ 'pandas',
+ 'beautifulsoup4',
+ 'bs4',
+ 'scrapy',
+ 'lxml',
+ }
+
+ # Get the module where the function is defined
+ module = inspect.getmodule(func)
+ if not module:
+ return imports
+
+ try:
+ # Parse the module source to extract imports
+ module_source = inspect.getsource(module)
+ module_tree = ast.parse(module_source)
+
+ # Extract all imports and check if they're used in the function
+ for node in ast.walk(module_tree):
+ if isinstance(node, ast.Import):
+ # Handle: import xxx
+ for alias in node.names:
+ package_name = alias.name.split('.')[0] # Get root package
+ if (alias.name in source or (alias.asname and alias.asname in source)) and package_name in safe_packages:
+ imports.append(node)
+ break
+ elif isinstance(node, ast.ImportFrom):
+ # Skip relative imports (level > 0 means relative)
+ if node.level > 0:
+ continue
+
+ # Skip local module imports
+ if node.module:
+ package_name = node.module.split('.')[0]
+ if package_name not in safe_packages:
+ continue
+
+ # Handle: from xxx import yyy
+ # Check if any imported names are used
+ used_names = []
+ for alias in node.names:
+ name_to_check = alias.asname if alias.asname else alias.name
+ if name_to_check in source:
+ used_names.append(alias)
+
+ if used_names and node.module:
+ # Create a new ImportFrom with only the used names
+ imports.append(
+ ast.ImportFrom(
+ module=node.module,
+ names=used_names,
+ level=0, # Always use absolute imports
+ )
+ )
+ except Exception:
+ # If we can't parse the module, continue without imports
+ pass
+
+ return imports
diff --git a/browser_use/remote_execute/views.py b/browser_use/remote_execute/views.py
new file mode 100644
index 000000000..557bdf968
--- /dev/null
+++ b/browser_use/remote_execute/views.py
@@ -0,0 +1,131 @@
+"""Type-safe event models for remote execution SSE streaming"""
+
+import json
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel
+
+
+class RemoteExecutionError(Exception):
+ pass
+
+
+class SSEEventType(str, Enum):
+ """Event types for Server-Sent Events"""
+
+ BROWSER_CREATED = 'browser_created'
+ INSTANCE_CREATED = 'instance_created'
+ INSTANCE_READY = 'instance_ready'
+ LOG = 'log'
+ RESULT = 'result'
+ ERROR = 'error'
+
+
+class BrowserCreatedData(BaseModel):
+ """Data for browser_created event"""
+
+ session_id: str
+ live_url: str
+ status: str
+
+
+class LogData(BaseModel):
+ """Data for log event"""
+
+ message: str
+ level: str = 'info' # stdout, stderr, info, warning, error
+
+
+class ExecutionResponse(BaseModel):
+ """Execution result from the executor"""
+
+ success: bool
+ result: Any = None
+ error: str | None = None
+ traceback: str | None = None
+
+
+class ResultData(BaseModel):
+ """Data for result event"""
+
+ execution_response: ExecutionResponse
+
+
+class ErrorData(BaseModel):
+ """Data for error event"""
+
+ error: str
+ traceback: str | None = None
+ status_code: int = 500
+
+
+class SSEEvent(BaseModel):
+ """Type-safe SSE Event
+
+ Usage:
+ # Parse from JSON
+ event = SSEEvent.from_json(event_json_string)
+
+ # Type-safe access with type guards
+ if event.is_browser_created():
+ assert isinstance(event.data, BrowserCreatedData)
+ print(event.data.live_url)
+
+ # Or check event type directly
+ if event.type == SSEEventType.LOG:
+ assert isinstance(event.data, LogData)
+ print(event.data.message)
+ """
+
+ type: SSEEventType
+ data: BrowserCreatedData | LogData | ResultData | ErrorData | dict[str, Any]
+ timestamp: str | None = None
+
+ @classmethod
+ def from_json(cls, event_json: str) -> 'SSEEvent':
+ """Parse SSE event from JSON string with proper type discrimination
+
+ Args:
+ event_json: JSON string from SSE stream
+
+ Returns:
+ Typed SSEEvent with appropriate data model
+
+ Raises:
+ json.JSONDecodeError: If JSON is malformed
+ ValueError: If event type is invalid
+ """
+ raw_data = json.loads(event_json)
+ event_type = SSEEventType(raw_data.get('type'))
+ data_dict = raw_data.get('data', {})
+
+ # Parse data based on event type
+ if event_type == SSEEventType.BROWSER_CREATED:
+ data = BrowserCreatedData(**data_dict)
+ elif event_type == SSEEventType.LOG:
+ data = LogData(**data_dict)
+ elif event_type == SSEEventType.RESULT:
+ data = ResultData(**data_dict)
+ elif event_type == SSEEventType.ERROR:
+ data = ErrorData(**data_dict)
+ else:
+ data = data_dict
+
+ return cls(type=event_type, data=data, timestamp=raw_data.get('timestamp'))
+
+ def is_browser_created(self) -> bool:
+ """Type guard for BrowserCreatedData"""
+ return self.type == SSEEventType.BROWSER_CREATED and isinstance(self.data, BrowserCreatedData)
+
+ def is_log(self) -> bool:
+ """Type guard for LogData"""
+ return self.type == SSEEventType.LOG and isinstance(self.data, LogData)
+
+ def is_result(self) -> bool:
+ """Type guard for ResultData"""
+ return self.type == SSEEventType.RESULT and isinstance(self.data, ResultData)
+
+ def is_error(self) -> bool:
+ """Type guard for ErrorData"""
+ return self.type == SSEEventType.ERROR and isinstance(self.data, ErrorData)