Skip to content

armgit / cua

Public Imported from GitHub
0

Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.

Add /dev/kvm support on WSL2 for QEMU Docker, add default check=True for setup / evaluator commands (#796)

dduponta58ab39a37b1
diff --git a/docs/content/docs/cuabench/guide/fundamentals/app-helpers.mdx b/docs/content/docs/cuabench/guide/fundamentals/app-helpers.mdx
new file mode 100644
index 0000000000..576215b5b4
--- /dev/null
+++ b/docs/content/docs/cuabench/guide/fundamentals/app-helpers.mdx
@@ -0,0 +1,92 @@
+---
+title: App Helpers
+description: Reusable primitives for installing, launching, and evaluating native apps
+---
+
+App helpers provide reusable methods for working with native applications. Beyond install/launch, apps can define custom getters and utilities that simplify writing evaluators.
+
+## Basic Usage
+
+```python
[email protected]_task(split="train")
+async def start(task_cfg: cb.Task, session: cb.DesktopSession):
+ await session.apps.chrome.install(with_shortcut=True)
+ await session.apps.chrome.launch(url="https://example.com")
+
[email protected]_task(split="train")
+async def evaluate(task_cfg: cb.Task, session: cb.DesktopSession) -> list[float]:
+ # Use app-specific getters for evaluation
+ current_url = await session.apps.chrome.get_current_url()
+ tabs = await session.apps.chrome.get_open_tabs()
+ bookmarks = await session.apps.chrome.get_bookmarks()
+
+ if "google.com" in current_url and len(tabs) >= 3:
+ return [1.0]
+ return [0.0]
+```
+
+## Available Apps
+
+| App | Name | Platforms |
+|-----|------|-----------|
+| Godot | `godot` | Linux, Windows, macOS |
+| Unity | `unity` | Linux, Windows, macOS |
+| Adobe Photoshop | `adobe_photoshop` | Linux (WINE), Windows |
+
+## Contributing Apps
+
+Apps live in `cua_bench/apps/`. Each app can define:
+
+- **install** - Install the application
+- **launch** - Launch with options
+- **uninstall** - Remove the application
+- **Custom methods** - Getters/utilities for evaluators
+
+```python
+from .registry import App, install, launch
+
+class Chrome(App):
+ name = "chrome"
+ description = "Google Chrome browser"
+
+ @install("linux")
+ async def install_linux(self, *, with_shortcut=True):
+ await self.session.run_command("sudo apt install -y google-chrome-stable")
+
+ @launch("linux", "windows")
+ async def launch_app(self, *, url=None):
+ cmd = "google-chrome &" if self.platform == "linux" else "start chrome.exe"
+ if url:
+ cmd = f"{cmd} {url}"
+ await self.session.run_command(cmd)
+
+ # Custom getters for evaluators
+ async def get_current_url(self) -> str:
+ """Get Chrome's current URL."""
+ result = await self.session.run_command("xdotool getactivewindow getwindowname")
+ return result["stdout"].strip()
+
+ async def get_open_tabs(self) -> list[str]:
+ """Get list of open tab titles."""
+ ...
+
+ async def get_bookmarks(self) -> list[dict]:
+ """Get user's bookmarks."""
+ ...
+```
+
+Register in `cua_bench/apps/__init__.py`:
+
+```python
+from . import chrome # noqa: F401
+```
+
+## Platform Matrix
+
+| Method | Linux | Windows | macOS |
+|--------|-------|---------|-------|
+| `install` | ✅ | ✅ | ✅ |
+| `launch` | ✅ | ✅ | ✅ |
+| `uninstall` | ✅ | ⚠️ | ⚠️ |
+
+✅ = Supported, ⚠️ = Partial support
diff --git a/docs/content/docs/cuabench/guide/fundamentals/meta.json b/docs/content/docs/cuabench/guide/fundamentals/meta.json
index cb14cd6a51..ab2dbc6363 100644
--- a/docs/content/docs/cuabench/guide/fundamentals/meta.json
+++ b/docs/content/docs/cuabench/guide/fundamentals/meta.json
@@ -2,5 +2,5 @@
"title": "Fundamentals",
"description": "Core concepts of tasks and environments",
"icon": "Lightbulb",
- "pages": ["tasks", "universal-gui", "simulated-desktop", "agent-traces", "adapters", "registry"]
+ "pages": ["tasks", "app-helpers", "universal-gui", "simulated-desktop", "agent-traces", "adapters", "registry"]
}
diff --git a/libs/cua-bench/cua_bench/apps/__init__.py b/libs/cua-bench/cua_bench/apps/__init__.py
new file mode 100644
index 0000000000..7733102f74
--- /dev/null
+++ b/libs/cua-bench/cua_bench/apps/__init__.py
@@ -0,0 +1,72 @@
+"""App Registry for cua-bench.
+
+A decorator-based API for registering platform-specific app installers and launchers.
+Makes it easy for contributors to add support for new applications.
+
+Example - Defining an app:
+
+ # cua_bench/apps/godot.py
+ from cua_bench.apps import App, install, launch
+
+ class Godot(App):
+ name = "godot"
+ description = "Godot game engine"
+
+ @install("linux")
+ async def install_linux(session, *, with_shortcut=True, version="4.2.1"):
+ await session.run_command(
+ f"cd ~/Desktop && "
+ f"wget -q https://github.com/godotengine/godot/releases/download/{version}-stable/Godot_v{version}-stable_linux.x86_64.zip && "
+ f"unzip -q Godot_v{version}-stable_linux.x86_64.zip"
+ )
+ if with_shortcut:
+ await session.run_command(
+ "ln -sf ~/Desktop/Godot_v*_linux.x86_64 ~/Desktop/Godot"
+ )
+
+ @install("windows")
+ async def install_windows(session, *, with_shortcut=True, version="4.2.1"):
+ await session.run_command(f"choco install godot --version={version} -y")
+
+ @launch("linux", "windows")
+ async def launch_editor(session, *, project_path=None):
+ cmd = "~/Desktop/Godot" if session.os_type == "linux" else "godot"
+ if project_path:
+ cmd += f" --editor --path {project_path}"
+ await session.run_command(f"{cmd} &")
+
+Example - Using in a task:
+
+ @cb.setup_task(split="train")
+ async def start(task_cfg: cb.Task, session: cb.DesktopSession):
+ # Install app (auto-selects platform)
+ await session.install_app("godot", with_shortcut=True, version="4.2.1")
+
+ # Launch app
+ await session.launch_app("godot", project_path="~/project")
+"""
+
+from .registry import (
+ App,
+ install,
+ launch,
+ uninstall,
+ get_app,
+ list_apps,
+ AppRegistry,
+)
+
+# Import app modules to trigger auto-registration via AppMeta metaclass
+from . import godot # noqa: F401
+from . import adobe_photoshop # noqa: F401
+from . import unity # noqa: F401
+
+__all__ = [
+ "App",
+ "install",
+ "launch",
+ "uninstall",
+ "get_app",
+ "list_apps",
+ "AppRegistry",
+]
diff --git a/libs/cua-bench/cua_bench/apps/adobe_photoshop.py b/libs/cua-bench/cua_bench/apps/adobe_photoshop.py
new file mode 100644
index 0000000000..4c3e812f30
--- /dev/null
+++ b/libs/cua-bench/cua_bench/apps/adobe_photoshop.py
@@ -0,0 +1,244 @@
+"""Adobe Photoshop app definition (via WINE on Linux)."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import TYPE_CHECKING, Optional
+
+from .registry import App, install, launch, uninstall
+
+if TYPE_CHECKING:
+ from .registry import BoundApp
+
+
+class AdobePhotoshop(App):
+ """Adobe Photoshop running via WINE.
+
+ Supports Photoshop CS6 Portable (commonly used for WINE compatibility).
+
+ Note: This requires a legitimate Photoshop installer/portable version.
+ The installer expects the Photoshop files to be available or downloadable.
+
+ Install options:
+ - version: Photoshop version ("cs6", "cc2019", etc.) - default "cs6"
+ - with_shortcut: Create desktop shortcut (default True)
+ - wine_prefix: Custom WINE prefix (default "~/.wine-photoshop")
+
+ Launch options:
+ - file_path: Optional PSD file to open
+ - wine_prefix: Custom WINE prefix if different from install
+ """
+
+ name = "adobe_photoshop"
+ description = "Adobe Photoshop image editor (via WINE on Linux, native on Windows)"
+
+ # =========================================================================
+ # Linux (via WINE)
+ # =========================================================================
+
+ @install("linux")
+ async def install_linux(
+ self: "BoundApp",
+ *,
+ with_shortcut: bool = True,
+ version: str = "cs6",
+ wine_prefix: str = "~/.wine-photoshop",
+ ) -> None:
+ """Install Photoshop on Linux via WINE.
+
+ This installs:
+ 1. WINE and dependencies
+ 2. Required Windows components via winetricks
+ 3. Photoshop CS6 Portable (user must provide installer or use portable)
+ """
+ # Install WINE and winetricks
+ await self.session.run_command(
+ "sudo dpkg --add-architecture i386 && "
+ "sudo apt-get update && "
+ "sudo apt-get install -y wine64 wine32 winetricks cabextract",
+ check=False,
+ )
+
+ # Create dedicated WINE prefix for Photoshop
+ await self.session.run_command(f"mkdir -p {wine_prefix}", check=False)
+
+ # Initialize 64-bit WINE prefix
+ await self.session.run_command(
+ f"WINEPREFIX={wine_prefix} WINEARCH=win64 wineboot --init",
+ check=False,
+ )
+ await asyncio.sleep(5) # Wait for wineboot to complete
+
+ # Install required dependencies via winetricks
+ # Photoshop needs: vcrun2008, vcrun2010, vcrun2012, corefonts, msxml3/6
+ deps = [
+ "corefonts",
+ "vcrun2008",
+ "vcrun2010",
+ "vcrun2012",
+ "vcrun2013",
+ "msxml3",
+ "msxml6",
+ "gdiplus",
+ "atmlib",
+ ]
+
+ for dep in deps:
+ await self.session.run_command(
+ f"WINEPREFIX={wine_prefix} winetricks -q {dep}",
+ check=False,
+ )
+ await asyncio.sleep(2)
+
+ # Set Windows version to Windows 10 for better compatibility
+ await self.session.run_command(
+ f"WINEPREFIX={wine_prefix} winetricks -q win10",
+ check=False,
+ )
+
+ # Create Photoshop directory
+ photoshop_dir = f"{wine_prefix}/drive_c/Program Files/Adobe/Photoshop"
+ await self.session.run_command(f'mkdir -p "{photoshop_dir}"', check=False)
+
+ # Download Photoshop CS6 Portable (using a common portable distribution)
+ # Note: In production, this would point to a legitimate source
+ # For now, we'll set up the structure and user can copy files manually
+ await self.session.run_command(
+ f'echo "Place Photoshop.exe and required files in {photoshop_dir}" > '
+ f'"{photoshop_dir}/README.txt"',
+ check=False,
+ )
+
+ # Try to download a portable version if available from a configured source
+ # This is a placeholder - in real usage, point to your own hosted files
+ portable_url = "https://example.com/photoshop-cs6-portable.zip" # Placeholder
+
+ # Create launcher script
+ launcher_script = f"""#!/bin/bash
+export WINEPREFIX="{wine_prefix}"
+export WINEDEBUG=-all
+cd "{photoshop_dir}"
+wine64 Photoshop.exe "$@"
+"""
+
+ await self.session.run_command(
+ f"echo '{launcher_script}' > ~/Desktop/photoshop.sh && "
+ f"chmod +x ~/Desktop/photoshop.sh",
+ check=False,
+ )
+
+ if with_shortcut:
+ # Create .desktop file for proper desktop integration
+ desktop_entry = f"""[Desktop Entry]
+Name=Adobe Photoshop CS6
+Comment=Image Editor (WINE)
+Exec=env WINEPREFIX={wine_prefix} wine64 "{photoshop_dir}/Photoshop.exe"
+Type=Application
+Categories=Graphics;2DGraphics;RasterGraphics;
+Icon=photoshop
+Terminal=false
+"""
+ await self.session.run_command(
+ f"echo '{desktop_entry}' > ~/.local/share/applications/photoshop.desktop && "
+ f"cp ~/.local/share/applications/photoshop.desktop ~/Desktop/",
+ check=False,
+ )
+
+ @launch("linux")
+ async def launch_linux(
+ self: "BoundApp",
+ *,
+ file_path: Optional[str] = None,
+ wine_prefix: str = "~/.wine-photoshop",
+ ) -> None:
+ """Launch Photoshop on Linux via WINE."""
+ photoshop_dir = f"{wine_prefix}/drive_c/Program Files/Adobe/Photoshop"
+
+ cmd = (
+ f'WINEPREFIX={wine_prefix} WINEDEBUG=-all '
+ f'wine64 "{photoshop_dir}/Photoshop.exe"'
+ )
+
+ if file_path:
+ # Convert Linux path to Windows path for WINE
+ cmd += f' "Z:{file_path}"'
+
+ await self.session.run_command(f"{cmd} &", check=False)
+ await asyncio.sleep(8) # Photoshop takes longer to start via WINE
+
+ @uninstall("linux")
+ async def uninstall_linux(
+ self: "BoundApp",
+ *,
+ wine_prefix: str = "~/.wine-photoshop",
+ ) -> None:
+ """Uninstall Photoshop from Linux."""
+ await self.session.run_command(
+ f"rm -rf {wine_prefix} && "
+ f"rm -f ~/Desktop/photoshop.sh && "
+ f"rm -f ~/Desktop/photoshop.desktop && "
+ f"rm -f ~/.local/share/applications/photoshop.desktop",
+ check=False,
+ )
+
+ # =========================================================================
+ # Windows (native)
+ # =========================================================================
+
+ @install("windows")
+ async def install_windows(
+ self: "BoundApp",
+ *,
+ with_shortcut: bool = True,
+ version: str = "cs6",
+ ) -> None:
+ """Install Photoshop on Windows.
+
+ Note: This is a placeholder. In production, you would either:
+ 1. Use a pre-installed image with Photoshop
+ 2. Run the actual installer silently
+ 3. Use a portable version
+ """
+ # For WinArena-style tasks, Photoshop is typically pre-installed
+ # This just verifies it exists
+ result = await self.session.run_command(
+ 'if exist "%ProgramFiles%\\Adobe\\Adobe Photoshop*\\Photoshop.exe" '
+ '(echo FOUND) else (echo NOT_FOUND)',
+ check=False,
+ )
+
+ stdout = result.get("stdout", "") if isinstance(result, dict) else str(result)
+ if "NOT_FOUND" in stdout:
+ # Could attempt to install via chocolatey or other means
+ # For now, just note that it needs manual installation
+ await self.session.run_command(
+ 'echo Photoshop not found. Please install manually. > '
+ '%USERPROFILE%\\Desktop\\photoshop_install_note.txt',
+ check=False,
+ )
+
+ @launch("windows")
+ async def launch_windows(
+ self: "BoundApp",
+ *,
+ file_path: Optional[str] = None,
+ ) -> None:
+ """Launch Photoshop on Windows."""
+ # Find Photoshop executable
+ cmd = 'start "" "%ProgramFiles%\\Adobe\\Adobe Photoshop 2024\\Photoshop.exe"'
+
+ if file_path:
+ cmd += f' "{file_path}"'
+
+ await self.session.run_command(cmd, check=False)
+ await asyncio.sleep(5)
+
+ @uninstall("windows")
+ async def uninstall_windows(self: "BoundApp", **kwargs) -> None:
+ """Uninstall Photoshop from Windows."""
+ # Use Adobe's uninstaller
+ await self.session.run_command(
+ 'if exist "%ProgramFiles%\\Common Files\\Adobe\\Installers\\*\\Setup.exe" '
+ '("%ProgramFiles%\\Common Files\\Adobe\\Installers\\*\\Setup.exe" /uninstall)',
+ check=False,
+ )
diff --git a/libs/cua-bench/cua_bench/apps/godot.py b/libs/cua-bench/cua_bench/apps/godot.py
new file mode 100644
index 0000000000..fd9056348b
--- /dev/null
+++ b/libs/cua-bench/cua_bench/apps/godot.py
@@ -0,0 +1,249 @@
+"""Godot game engine app definition."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import TYPE_CHECKING, Optional
+
+from .registry import App, install, launch, uninstall
+
+if TYPE_CHECKING:
+ from .registry import BoundApp
+
+
+class Godot(App):
+ """Godot game engine.
+
+ A free and open-source game engine for 2D and 3D game development.
+
+ Install options:
+ - version: Godot version (default "4.2.1")
+ - with_shortcut: Create desktop shortcut (default True)
+ - mono: Install Mono/.NET version (default False)
+
+ Launch options:
+ - project_path: Path to project directory
+ - editor: Open in editor mode (default True)
+ - scene: Specific scene to open
+ - headless: Run in headless mode (default False)
+ """
+
+ name = "godot"
+ description = "Godot game engine for 2D and 3D game development"
+
+ # =========================================================================
+ # Linux
+ # =========================================================================
+
+ @install("linux")
+ async def install_linux(
+ self: "BoundApp",
+ *,
+ with_shortcut: bool = True,
+ version: str = "4.2.1",
+ mono: bool = False,
+ ) -> None:
+ """Install Godot on Linux."""
+ variant = "mono_linux_x86_64" if mono else "linux.x86_64"
+ filename = f"Godot_v{version}-stable_{variant}"
+ zip_file = f"{filename}.zip"
+ download_url = (
+ f"https://github.com/godotengine/godot/releases/download/"
+ f"{version}-stable/{zip_file}"
+ )
+
+ # Download and extract
+ await self.session.run_command(
+ f"cd ~/Desktop && "
+ f"wget -q {download_url} && "
+ f"unzip -q {zip_file} && "
+ f"rm {zip_file}",
+ check=False,
+ )
+
+ # Make executable
+ await self.session.run_command(f"chmod +x ~/Desktop/{filename}", check=False)
+
+ if with_shortcut:
+ # Create a simpler symlink name
+ await self.session.run_command(
+ f"ln -sf ~/Desktop/{filename} ~/Desktop/Godot",
+ check=False,
+ )
+
+ @launch("linux")
+ async def launch_linux(
+ self: "BoundApp",
+ *,
+ project_path: Optional[str] = None,
+ editor: bool = True,
+ scene: Optional[str] = None,
+ headless: bool = False,
+ ) -> None:
+ """Launch Godot on Linux."""
+ cmd = "~/Desktop/Godot"
+
+ if headless:
+ cmd += " --headless"
+ if editor:
+ cmd += " --editor"
+ if project_path:
+ cmd += f" --path {project_path}"
+ if scene:
+ cmd += f" {scene}"
+
+ await self.session.run_command(f"{cmd} &", check=False)
+ await asyncio.sleep(3) # Wait for Godot to start
+
+ @uninstall("linux")
+ async def uninstall_linux(self: "BoundApp", **kwargs) -> None:
+ """Uninstall Godot from Linux."""
+ await self.session.run_command(
+ "rm -f ~/Desktop/Godot ~/Desktop/Godot_v*",
+ check=False,
+ )
+
+ # =========================================================================
+ # Windows
+ # =========================================================================
+
+ @install("windows")
+ async def install_windows(
+ self: "BoundApp",
+ *,
+ with_shortcut: bool = True,
+ version: str = "4.2.1",
+ mono: bool = False,
+ ) -> None:
+ """Install Godot on Windows using winget or direct download."""
+ # Try winget first, fall back to direct download
+ variant = "mono_win64" if mono else "win64.exe"
+ filename = f"Godot_v{version}-stable_{variant}"
+
+ if mono:
+ zip_file = f"{filename}.zip"
+ else:
+ zip_file = f"{filename}.zip"
+
+ download_url = (
+ f"https://github.com/godotengine/godot/releases/download/"
+ f"{version}-stable/{zip_file}"
+ )
+
+ # Download and extract to Desktop
+ await self.session.run_command(
+ f'cd %USERPROFILE%\\Desktop && '
+ f'curl -L -o {zip_file} {download_url} && '
+ f'tar -xf {zip_file} && '
+ f'del {zip_file}',
+ check=False,
+ )
+
+ if with_shortcut:
+ # Rename to simpler name
+ exe_name = f"Godot_v{version}-stable_win64.exe"
+ await self.session.run_command(
+ f'ren "%USERPROFILE%\\Desktop\\{exe_name}" "Godot.exe"',
+ check=False,
+ )
+
+ @launch("windows")
+ async def launch_windows(
+ self: "BoundApp",
+ *,
+ project_path: Optional[str] = None,
+ editor: bool = True,
+ scene: Optional[str] = None,
+ headless: bool = False,
+ ) -> None:
+ """Launch Godot on Windows."""
+ cmd = '"%USERPROFILE%\\Desktop\\Godot.exe"'
+
+ if headless:
+ cmd += " --headless"
+ if editor:
+ cmd += " --editor"
+ if project_path:
+ cmd += f" --path {project_path}"
+ if scene:
+ cmd += f" {scene}"
+
+ await self.session.run_command(f"start /B {cmd}", check=False)
+ await asyncio.sleep(3)
+
+ @uninstall("windows")
+ async def uninstall_windows(self: "BoundApp", **kwargs) -> None:
+ """Uninstall Godot from Windows."""
+ await self.session.run_command(
+ 'del "%USERPROFILE%\\Desktop\\Godot*.exe"',
+ check=False,
+ )
+
+ # =========================================================================
+ # macOS
+ # =========================================================================
+
+ @install("macos")
+ async def install_macos(
+ self: "BoundApp",
+ *,
+ with_shortcut: bool = True,
+ version: str = "4.2.1",
+ mono: bool = False,
+ ) -> None:
+ """Install Godot on macOS."""
+ variant = "macos.universal"
+ filename = f"Godot_v{version}-stable_{variant}"
+ zip_file = f"{filename}.zip"
+ download_url = (
+ f"https://github.com/godotengine/godot/releases/download/"
+ f"{version}-stable/{zip_file}"
+ )
+
+ # Download and extract
+ await self.session.run_command(
+ f"cd ~/Desktop && "
+ f"curl -L -o {zip_file} {download_url} && "
+ f"unzip -q {zip_file} && "
+ f"rm {zip_file}",
+ check=False,
+ )
+
+ if with_shortcut:
+ # Create alias
+ await self.session.run_command(
+ f'ln -sf ~/Desktop/Godot.app ~/Desktop/Godot',
+ check=False,
+ )
+
+ @launch("macos")
+ async def launch_macos(
+ self: "BoundApp",
+ *,
+ project_path: Optional[str] = None,
+ editor: bool = True,
+ scene: Optional[str] = None,
+ headless: bool = False,
+ ) -> None:
+ """Launch Godot on macOS."""
+ cmd = "open -a ~/Desktop/Godot.app --args"
+
+ if headless:
+ cmd += " --headless"
+ if editor:
+ cmd += " --editor"
+ if project_path:
+ cmd += f" --path {project_path}"
+ if scene:
+ cmd += f" {scene}"
+
+ await self.session.run_command(cmd, check=False)
+ await asyncio.sleep(3)
+
+ @uninstall("macos")
+ async def uninstall_macos(self: "BoundApp", **kwargs) -> None:
+ """Uninstall Godot from macOS."""
+ await self.session.run_command(
+ "rm -rf ~/Desktop/Godot.app ~/Desktop/Godot",
+ check=False,
+ )
diff --git a/libs/cua-bench/cua_bench/apps/registry.py b/libs/cua-bench/cua_bench/apps/registry.py
new file mode 100644
index 0000000000..3f1ffa199a
--- /dev/null
+++ b/libs/cua-bench/cua_bench/apps/registry.py
@@ -0,0 +1,403 @@
+"""App registry implementation."""
+
+from __future__ import annotations
+
+from typing import (
+ TYPE_CHECKING,
+ Any,
+ Callable,
+ Dict,
+ List,
+ Literal,
+ Optional,
+ Set,
+ TypeVar,
+ Union,
+)
+
+if TYPE_CHECKING:
+ from ..computers.base import DesktopSession
+
+Platform = Literal["linux", "windows", "macos"]
+ALL_PLATFORMS: Set[Platform] = {"linux", "windows", "macos"}
+
+# Global registry
+_registry: Dict[str, "App"] = {}
+
+
+class AppMethod:
+ """Descriptor for platform-specific app methods."""
+
+ def __init__(
+ self,
+ method_type: str,
+ platforms: Set[Platform],
+ func: Callable,
+ ):
+ self.method_type = method_type
+ self.platforms = platforms
+ self.func = func
+
+ async def __call__(self, bound_app: "BoundApp", **kwargs) -> Any:
+ """Call the method with bound app context."""
+ return await self.func(bound_app, **kwargs)
+
+
+def _platform_decorator(method_type: str):
+ """Factory for creating platform-specific method decorators."""
+
+ def decorator(
+ *platforms: Platform,
+ ) -> Callable[[Callable], AppMethod]:
+ """Decorator to register a platform-specific method.
+
+ Args:
+ *platforms: Platform names (linux, windows, macos).
+ If empty, applies to all platforms.
+ """
+ platform_set = set(platforms) if platforms else ALL_PLATFORMS
+
+ def wrapper(func: Callable) -> AppMethod:
+ return AppMethod(method_type, platform_set, func)
+
+ return wrapper
+
+ return decorator
+
+
+# Public decorators
+install = _platform_decorator("install")
+launch = _platform_decorator("launch")
+uninstall = _platform_decorator("uninstall")
+
+
+class AppMeta(type):
+ """Metaclass for App that auto-registers apps."""
+
+ def __new__(mcs, name: str, bases: tuple, namespace: dict):
+ cls = super().__new__(mcs, name, bases, namespace)
+
+ # Don't register the base App class
+ if name != "App" and hasattr(cls, "name") and cls.name:
+ _registry[cls.name] = cls()
+
+ return cls
+
+
+class App(metaclass=AppMeta):
+ """Base class for app definitions.
+
+ Subclass this and define platform-specific methods using decorators:
+
+ class MyApp(App):
+ name = "myapp"
+ description = "My application"
+
+ @install("linux")
+ async def install_linux(session, **kwargs):
+ ...
+
+ @install("windows")
+ async def install_windows(session, **kwargs):
+ ...
+
+ @launch("linux", "windows")
+ async def launch(session, **kwargs):
+ ...
+ """
+
+ name: str = ""
+ description: str = ""
+
+ def get_method(
+ self,
+ method_type: str,
+ platform: Platform,
+ ) -> Optional[AppMethod]:
+ """Get a method for the given type and platform."""
+ for attr_name in dir(self):
+ attr = getattr(self, attr_name)
+ if isinstance(attr, AppMethod):
+ if attr.method_type == method_type and platform in attr.platforms:
+ return attr
+ return None
+
+ def get_install(self, platform: Platform) -> Optional[AppMethod]:
+ """Get the install method for a platform."""
+ return self.get_method("install", platform)
+
+ def get_launch(self, platform: Platform) -> Optional[AppMethod]:
+ """Get the launch method for a platform."""
+ return self.get_method("launch", platform)
+
+ def get_uninstall(self, platform: Platform) -> Optional[AppMethod]:
+ """Get the uninstall method for a platform."""
+ return self.get_method("uninstall", platform)
+
+ def supported_platforms(self, method_type: str = "install") -> Set[Platform]:
+ """Get platforms supported for a method type."""
+ platforms: Set[Platform] = set()
+ for attr_name in dir(self):
+ attr = getattr(self, attr_name)
+ if isinstance(attr, AppMethod) and attr.method_type == method_type:
+ platforms.update(attr.platforms)
+ return platforms
+
+
+def get_app(name: str) -> Optional[App]:
+ """Get a registered app by name."""
+ return _registry.get(name)
+
+
+def list_apps() -> List[str]:
+ """List all registered app names."""
+ return list(_registry.keys())
+
+
+class BoundApp:
+ """An app instance bound to a specific session.
+
+ Provides access to `self.session` and `self.platform` in app methods,
+ and exposes all app methods directly (install, launch, custom getters, etc.).
+
+ Usage:
+ url = await session.apps.chrome.get_current_url()
+ await session.apps.chrome.install(with_shortcut=True)
+ """
+
+ def __init__(self, app: App, session: Any):
+ self._app = app
+ self._session = session
+ self._platform = _get_platform(session)
+
+ @property
+ def session(self) -> Any:
+ """The bound session."""
+ return self._session
+
+ @property
+ def platform(self) -> Platform:
+ """The current platform (linux, windows, macos)."""
+ return self._platform
+
+ @property
+ def name(self) -> str:
+ """App name."""
+ return self._app.name
+
+ @property
+ def description(self) -> str:
+ """App description."""
+ return self._app.description
+
+ async def install(self, *, with_shortcut: bool = True, **kwargs) -> None:
+ """Install the app."""
+ method = self._app.get_install(self._platform)
+ if method is None:
+ raise NotImplementedError(
+ f"App '{self._app.name}' does not support install on {self._platform}. "
+ f"Supported: {self._app.supported_platforms('install')}"
+ )
+ await method(self, with_shortcut=with_shortcut, **kwargs)
+
+ async def launch(self, **kwargs) -> None:
+ """Launch the app."""
+ method = self._app.get_launch(self._platform)
+ if method is None:
+ raise NotImplementedError(
+ f"App '{self._app.name}' does not support launch on {self._platform}. "
+ f"Supported: {self._app.supported_platforms('launch')}"
+ )
+ await method(self, **kwargs)
+
+ async def uninstall(self, **kwargs) -> None:
+ """Uninstall the app."""
+ method = self._app.get_uninstall(self._platform)
+ if method is None:
+ raise NotImplementedError(
+ f"App '{self._app.name}' does not support uninstall on {self._platform}. "
+ f"Supported: {self._app.supported_platforms('uninstall')}"
+ )
+ await method(self, **kwargs)
+
+ def __getattr__(self, name: str) -> Any:
+ """Proxy custom methods from the app.
+
+ Allows accessing custom getters like:
+ await session.apps.chrome.get_current_url()
+ """
+ # Check if the app has this attribute
+ attr = getattr(self._app, name, None)
+ if attr is None:
+ raise AttributeError(
+ f"App '{self._app.name}' has no attribute '{name}'"
+ )
+
+ # If it's a callable (custom method), wrap it to pass self (BoundApp)
+ if callable(attr):
+ async def bound_method(**kwargs):
+ return await attr(self, **kwargs)
+ return bound_method
+
+ return attr
+
+
+class AppsProxy:
+ """Proxy for accessing apps via session.apps.{app_name}.
+
+ Usage:
+ await session.apps.chrome.install()
+ await session.apps.chrome.get_current_url()
+ await session.apps.godot.launch(project_path="~/project")
+ """
+
+ def __init__(self, session: Any):
+ self._session = session
+ self._cache: Dict[str, BoundApp] = {}
+
+ def __getattr__(self, name: str) -> BoundApp:
+ """Get a bound app by name."""
+ if name.startswith("_"):
+ raise AttributeError(name)
+
+ if name not in self._cache:
+ app = get_app(name)
+ if app is None:
+ raise AttributeError(
+ f"Unknown app: '{name}'. Available: {list_apps()}"
+ )
+ self._cache[name] = BoundApp(app, self._session)
+
+ return self._cache[name]
+
+ def __dir__(self) -> List[str]:
+ """List available apps."""
+ return list_apps()
+
+
+class AppRegistry:
+ """Registry access for DesktopSession integration.
+
+ This class provides the interface used by DesktopSession to install/launch apps.
+ """
+
+ @staticmethod
+ async def install_app(
+ session: Any,
+ app_name: str,
+ *,
+ with_shortcut: bool = True,
+ **kwargs,
+ ) -> None:
+ """Install an app on the session's platform.
+
+ Args:
+ session: DesktopSession instance
+ app_name: Name of the app to install
+ with_shortcut: Whether to create desktop shortcut (default True)
+ **kwargs: Additional app-specific arguments
+ """
+ app = get_app(app_name)
+ if app is None:
+ raise ValueError(
+ f"Unknown app: {app_name}. Available: {list_apps()}"
+ )
+
+ # Get platform from session config
+ platform = _get_platform(session)
+
+ method = app.get_install(platform)
+ if method is None:
+ raise NotImplementedError(
+ f"App '{app_name}' does not support install on {platform}. "
+ f"Supported: {app.supported_platforms('install')}"
+ )
+
+ # Create BoundApp wrapper for the method call
+ bound_app = BoundApp(app, session)
+ await method(bound_app, with_shortcut=with_shortcut, **kwargs)
+
+ @staticmethod
+ async def launch_app(
+ session: Any,
+ app_name: str,
+ **kwargs,
+ ) -> None:
+ """Launch an app on the session's platform.
+
+ Args:
+ session: DesktopSession instance
+ app_name: Name of the app to launch
+ **kwargs: App-specific launch arguments
+ """
+ app = get_app(app_name)
+ if app is None:
+ raise ValueError(
+ f"Unknown app: {app_name}. Available: {list_apps()}"
+ )
+
+ platform = _get_platform(session)
+
+ method = app.get_launch(platform)
+ if method is None:
+ raise NotImplementedError(
+ f"App '{app_name}' does not support launch on {platform}. "
+ f"Supported: {app.supported_platforms('launch')}"
+ )
+
+ # Create BoundApp wrapper for the method call
+ bound_app = BoundApp(app, session)
+ await method(bound_app, **kwargs)
+
+ @staticmethod
+ async def uninstall_app(
+ session: Any,
+ app_name: str,
+ **kwargs,
+ ) -> None:
+ """Uninstall an app from the session's platform.
+
+ Args:
+ session: DesktopSession instance
+ app_name: Name of the app to uninstall
+ **kwargs: App-specific arguments
+ """
+ app = get_app(app_name)
+ if app is None:
+ raise ValueError(
+ f"Unknown app: {app_name}. Available: {list_apps()}"
+ )
+
+ platform = _get_platform(session)
+
+ method = app.get_uninstall(platform)
+ if method is None:
+ raise NotImplementedError(
+ f"App '{app_name}' does not support uninstall on {platform}. "
+ f"Supported: {app.supported_platforms('uninstall')}"
+ )
+
+ # Create BoundApp wrapper for the method call
+ bound_app = BoundApp(app, session)
+ await method(bound_app, **kwargs)
+
+
+def _get_platform(session: Any) -> Platform:
+ """Extract platform from session configuration."""
+ # Try to get from session's config
+ if hasattr(session, "_config") and session._config:
+ os_type = session._config.get("os_type", "linux")
+ elif hasattr(session, "os_type"):
+ os_type = session.os_type
+ else:
+ os_type = "linux"
+
+ # Normalize os_type to platform
+ if os_type in ("linux",):
+ return "linux"
+ elif os_type in ("windows", "win11", "win10", "win7", "winxp", "win98"):
+ return "windows"
+ elif os_type in ("macos",):
+ return "macos"
+ else:
+ return "linux" # Default
diff --git a/libs/cua-bench/cua_bench/apps/unity.py b/libs/cua-bench/cua_bench/apps/unity.py
new file mode 100644
index 0000000000..7d37715449
--- /dev/null
+++ b/libs/cua-bench/cua_bench/apps/unity.py
@@ -0,0 +1,263 @@
+"""Unity game engine app definition."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import TYPE_CHECKING, Optional
+
+from .registry import App, install, launch, uninstall
+
+if TYPE_CHECKING:
+ from .registry import BoundApp
+
+
+class Unity(App):
+ """Unity game engine.
+
+ A cross-platform game engine for 2D, 3D, VR, and AR development.
+
+ Install options:
+ - version: Unity version (default "2022.3.0f1" LTS)
+ - with_shortcut: Create desktop shortcut (default True)
+
+ Launch options:
+ - project_path: Path to project directory
+ - create_project: Create new project at path (default False)
+ - execute_method: Method to execute on launch
+ - batch_mode: Run in batch mode (default False)
+ - quit: Quit after execution (default False)
+ """
+
+ name = "unity"
+ description = "Unity game engine for 2D, 3D, VR, and AR development"
+
+ # =========================================================================
+ # Linux
+ # =========================================================================
+
+ @install("linux")
+ async def install_linux(
+ self: "BoundApp",
+ *,
+ with_shortcut: bool = True,
+ version: str = "2022.3.0f1",
+ ) -> None:
+ """Install Unity Hub on Linux.
+
+ Unity is typically installed via Unity Hub which manages versions.
+ """
+ # Install Unity Hub via .deb package
+ await self.session.run_command(
+ "wget -qO - https://hub.unity3d.com/linux/keys/public | sudo apt-key add - && "
+ 'sudo sh -c \'echo "deb https://hub.unity3d.com/linux/repos/deb stable main" > '
+ "/etc/apt/sources.list.d/unityhub.list' && "
+ "sudo apt-get update && "
+ "sudo apt-get install -y unityhub",
+ check=False,
+ )
+
+ if with_shortcut:
+ # Download Unity icon and create .desktop file
+ await self.session.run_command(
+ "mkdir -p ~/.local/share/icons && "
+ "wget -q -O ~/.local/share/icons/unity-hub.png "
+ "'https://img.icons8.com/ios-filled/512/unity.png'",
+ check=False,
+ )
+
+ desktop_entry = """[Desktop Entry]
+Name=Unity Hub
+Comment=Unity Game Engine Hub
+Exec=/opt/unityhub/unityhub
+Icon=~/.local/share/icons/unity-hub.png
+Type=Application
+Categories=Development;IDE;
+Terminal=false
+"""
+ await self.session.run_command(
+ f"echo '{desktop_entry}' > ~/Desktop/UnityHub.desktop && "
+ f"chmod +x ~/Desktop/UnityHub.desktop",
+ check=False,
+ )
+
+ @launch("linux")
+ async def launch_linux(
+ self: "BoundApp",
+ *,
+ project_path: Optional[str] = None,
+ create_project: bool = False,
+ execute_method: Optional[str] = None,
+ batch_mode: bool = False,
+ quit: bool = False,
+ ) -> None:
+ """Launch Unity on Linux."""
+ # Find Unity Editor (typically in ~/Unity/Hub/Editor/<version>/Editor/)
+ cmd = "unityhub"
+
+ if project_path:
+ cmd = f"unity-editor -projectPath {project_path}"
+ if create_project:
+ cmd += " -createProject"
+ if batch_mode:
+ cmd += " -batchmode"
+ if quit:
+ cmd += " -quit"
+ if execute_method:
+ cmd += f" -executeMethod {execute_method}"
+
+ await self.session.run_command(f"{cmd} &", check=False)
+ await asyncio.sleep(5)
+
+ @uninstall("linux")
+ async def uninstall_linux(self: "BoundApp", **kwargs) -> None:
+ """Uninstall Unity from Linux."""
+ await self.session.run_command(
+ "sudo apt-get remove -y unityhub && "
+ "rm -f ~/Desktop/UnityHub",
+ check=False,
+ )
+
+ # =========================================================================
+ # Windows
+ # =========================================================================
+
+ @install("windows")
+ async def install_windows(
+ self: "BoundApp",
+ *,
+ with_shortcut: bool = True,
+ version: str = "2022.3.0f1",
+ ) -> None:
+ """Install Unity Hub on Windows.
+
+ Uses winget or direct download of Unity Hub installer.
+ """
+ # Try winget first
+ result = await self.session.run_command(
+ "winget install -e --id Unity.UnityHub --accept-package-agreements --accept-source-agreements",
+ check=False,
+ )
+
+ stdout = result.get("stdout", "") if isinstance(result, dict) else str(result)
+
+ # If winget fails, try direct download
+ if "error" in stdout.lower() or "failed" in stdout.lower():
+ await self.session.run_command(
+ 'curl -L -o "%TEMP%\\UnityHubSetup.exe" '
+ '"https://public-cdn.cloud.unity3d.com/hub/prod/UnityHubSetup.exe" && '
+ '"%TEMP%\\UnityHubSetup.exe" /S',
+ check=False,
+ )
+ await asyncio.sleep(30) # Wait for installation
+
+ @launch("windows")
+ async def launch_windows(
+ self: "BoundApp",
+ *,
+ project_path: Optional[str] = None,
+ create_project: bool = False,
+ execute_method: Optional[str] = None,
+ batch_mode: bool = False,
+ quit: bool = False,
+ ) -> None:
+ """Launch Unity on Windows."""
+ if project_path:
+ # Launch Unity Editor directly with project
+ # Find Unity Editor path (default location)
+ cmd = '"%ProgramFiles%\\Unity\\Hub\\Editor\\2022.3.0f1\\Editor\\Unity.exe"'
+ cmd += f' -projectPath "{project_path}"'
+
+ if create_project:
+ cmd += " -createProject"
+ if batch_mode:
+ cmd += " -batchmode"
+ if quit:
+ cmd += " -quit"
+ if execute_method:
+ cmd += f" -executeMethod {execute_method}"
+
+ await self.session.run_command(f"start /B {cmd}", check=False)
+ else:
+ # Launch Unity Hub
+ await self.session.run_command(
+ 'start "" "%ProgramFiles%\\Unity Hub\\Unity Hub.exe"',
+ check=False,
+ )
+
+ await asyncio.sleep(5)
+
+ @uninstall("windows")
+ async def uninstall_windows(self: "BoundApp", **kwargs) -> None:
+ """Uninstall Unity from Windows."""
+ await self.session.run_command(
+ 'winget uninstall -e --id Unity.UnityHub',
+ check=False,
+ )
+
+ # =========================================================================
+ # macOS
+ # =========================================================================
+
+ @install("macos")
+ async def install_macos(
+ self: "BoundApp",
+ *,
+ with_shortcut: bool = True,
+ version: str = "2022.3.0f1",
+ ) -> None:
+ """Install Unity Hub on macOS."""
+ # Download Unity Hub DMG
+ await self.session.run_command(
+ "curl -L -o ~/Downloads/UnityHubSetup.dmg "
+ '"https://public-cdn.cloud.unity3d.com/hub/prod/UnityHubSetup.dmg" && '
+ "hdiutil attach ~/Downloads/UnityHubSetup.dmg && "
+ 'cp -R "/Volumes/Unity Hub/Unity Hub.app" /Applications/ && '
+ 'hdiutil detach "/Volumes/Unity Hub" && '
+ "rm ~/Downloads/UnityHubSetup.dmg",
+ check=False,
+ )
+
+ if with_shortcut:
+ await self.session.run_command(
+ 'ln -sf "/Applications/Unity Hub.app" ~/Desktop/UnityHub',
+ check=False,
+ )
+
+ @launch("macos")
+ async def launch_macos(
+ self: "BoundApp",
+ *,
+ project_path: Optional[str] = None,
+ create_project: bool = False,
+ execute_method: Optional[str] = None,
+ batch_mode: bool = False,
+ quit: bool = False,
+ ) -> None:
+ """Launch Unity on macOS."""
+ if project_path:
+ # Launch Unity Editor with project
+ cmd = 'open -a "/Applications/Unity/Hub/Editor/2022.3.0f1/Unity.app" --args'
+ cmd += f' -projectPath "{project_path}"'
+
+ if create_project:
+ cmd += " -createProject"
+ if batch_mode:
+ cmd += " -batchmode"
+ if quit:
+ cmd += " -quit"
+ if execute_method:
+ cmd += f" -executeMethod {execute_method}"
+
+ await self.session.run_command(cmd, check=False)
+ else:
+ await self.session.run_command('open -a "Unity Hub"', check=False)
+
+ await asyncio.sleep(5)
+
+ @uninstall("macos")
+ async def uninstall_macos(self: "BoundApp", **kwargs) -> None:
+ """Uninstall Unity from macOS."""
+ await self.session.run_command(
+ 'rm -rf "/Applications/Unity Hub.app" ~/Desktop/UnityHub',
+ check=False,
+ )
diff --git a/libs/cua-bench/cua_bench/cli/commands/image.py b/libs/cua-bench/cua_bench/cli/commands/image.py
index 92d8f2897b..fd5665ec10 100644
--- a/libs/cua-bench/cua_bench/cli/commands/image.py
+++ b/libs/cua-bench/cua_bench/cli/commands/image.py
@@ -1179,7 +1179,7 @@ def _shell_qemu(args, info, name, writable: bool) -> int:
for vol in volumes:
docker_cmd.extend(["-v", vol])
- if os.path.exists("/dev/kvm") and not getattr(args, "no_kvm", False):
+ if check_kvm() and not getattr(args, "no_kvm", False):
docker_cmd.extend(["--device=/dev/kvm"])
else:
docker_cmd.extend(["-e", "KVM=N"])
diff --git a/libs/cua-bench/cua_bench/cli/commands/interact.py b/libs/cua-bench/cua_bench/cli/commands/interact.py
index b1464815dc..a60be70a94 100644
--- a/libs/cua-bench/cua_bench/cli/commands/interact.py
+++ b/libs/cua-bench/cua_bench/cli/commands/interact.py
@@ -21,28 +21,30 @@ def execute(args):
return asyncio.run(_execute_async(args))
-def _detect_provider_type(env_path: Path) -> str:
- """Detect provider type from task configuration.
+def _detect_task_config(env_path: Path) -> dict:
+ """Detect provider type and os_type from task configuration.
Args:
env_path: Path to task environment directory
Returns:
- Provider type ("simulated", "webtop", "native", "computer", or "unknown")
+ Dict with "provider" and "os_type" keys
"""
import importlib.util
import sys
+ result = {"provider": "unknown", "os_type": "linux"}
+
# Try to import and inspect the task
try:
# Load main.py module
main_file = env_path / "main.py"
if not main_file.exists():
- return "unknown"
+ return result
spec = importlib.util.spec_from_file_location("env_module", main_file)
if spec is None or spec.loader is None:
- return "unknown"
+ return result
module = importlib.util.module_from_spec(spec)
@@ -61,10 +63,11 @@ def _detect_provider_type(env_path: Path) -> str:
if tasks and len(tasks) > 0:
task = tasks[0]
if hasattr(task, "computer") and task.computer:
- provider = task.computer.get("provider", "unknown")
- return provider
+ result["provider"] = task.computer.get("provider", "unknown")
+ setup_config = task.computer.get("setup_config", {})
+ result["os_type"] = setup_config.get("os_type", "linux")
- return "unknown"
+ return result
finally:
sys.path.pop(0)
@@ -73,25 +76,42 @@ def _detect_provider_type(env_path: Path) -> str:
del sys.modules["env_module"]
except Exception as e:
- print(f"{YELLOW}Warning: Could not detect provider type: {e}{RESET}")
- return "unknown"
+ print(f"{YELLOW}Warning: Could not detect task config: {e}{RESET}")
+ return result
+
+
+def _detect_provider_type(env_path: Path) -> str:
+ """Detect provider type from task configuration.
+
+ Args:
+ env_path: Path to task environment directory
+ Returns:
+ Provider type ("simulated", "webtop", "native", "computer", or "unknown")
+ """
+ return _detect_task_config(env_path)["provider"]
-def _get_env_type_from_provider(provider: str) -> str:
- """Map provider type to env_type for task runner.
+
+def _get_env_type_from_task(env_path: Path) -> str:
+ """Get env_type for task runner based on task configuration.
Args:
- provider: Provider type (simulated, webtop, native, computer)
+ env_path: Path to task environment directory
Returns:
env_type for task runner (linux-docker, windows-qemu, etc.)
"""
- # For native providers, default to linux-docker
- # Users can override via platform detection or args
- if provider in ("native", "computer"):
+ config = _detect_task_config(env_path)
+ os_type = config.get("os_type", "linux")
+
+ # Map os_type to env_type
+ if os_type in ("windows", "win11", "win10", "win7", "winxp", "win98"):
+ return "windows-qemu"
+ elif os_type == "android":
+ return "android-qemu"
+ else:
+ # Default to linux-docker for linux and other types
return "linux-docker"
- return "linux-docker"
-
async def _execute_async(args):
"""Execute the interact command asynchronously."""
@@ -268,8 +288,8 @@ async def _execute_native_interactive(args, env_path: Path, provider_type: str)
from cua_bench.runner.task_runner import TaskRunner
try:
- # Determine env_type (linux-docker, windows-qemu, etc.)
- env_type = getattr(args, "env_type", None) or _get_env_type_from_provider(provider_type)
+ # Determine env_type (linux-docker, windows-qemu, etc.) from task's os_type config
+ env_type = getattr(args, "env_type", None) or _get_env_type_from_task(env_path)
print(f"{CYAN}Starting environment with task runner (env_type: {env_type})...{RESET}")
diff --git a/libs/cua-bench/cua_bench/cli/commands/platform.py b/libs/cua-bench/cua_bench/cli/commands/platform.py
index bed277984f..9d900193ab 100644
--- a/libs/cua-bench/cua_bench/cli/commands/platform.py
+++ b/libs/cua-bench/cua_bench/cli/commands/platform.py
@@ -94,8 +94,26 @@ def check_docker() -> bool:
def check_kvm() -> bool:
- """Check if KVM is available."""
- return os.path.exists("/dev/kvm")
+ """Check if KVM is available.
+
+ On Linux: checks /dev/kvm directly
+ On Windows/macOS with Docker: checks if KVM is available inside Docker's VM
+ (Docker Desktop with WSL2 backend may have KVM available)
+ """
+ # On Linux, check directly
+ if sys_platform.system() == "Linux":
+ return os.path.exists("/dev/kvm")
+
+ # On Windows/macOS, check if Docker can access KVM (WSL2 or Docker VM)
+ try:
+ result = subprocess.run(
+ ["docker", "run", "--rm", "--device=/dev/kvm", "alpine", "test", "-e", "/dev/kvm"],
+ capture_output=True,
+ timeout=30,
+ )
+ return result.returncode == 0
+ except Exception:
+ return False
def check_lume() -> bool:
diff --git a/libs/cua-bench/cua_bench/computers/base.py b/libs/cua-bench/cua_bench/computers/base.py
index 3a372857f1..5d446ae675 100644
--- a/libs/cua-bench/cua_bench/computers/base.py
+++ b/libs/cua-bench/cua_bench/computers/base.py
@@ -1,9 +1,12 @@
from __future__ import annotations
-from typing import Any, List, Literal, Optional, Protocol, TypedDict
+from typing import TYPE_CHECKING, Any, List, Literal, Optional, Protocol, TypedDict
from ..types import Snapshot
+if TYPE_CHECKING:
+ from ..apps.registry import AppsProxy
+
_DEFAULT_SESSION_NAME = "simulated"
@@ -171,6 +174,20 @@ class DesktopSession(Protocol):
"""Return the VNC URL for accessing the desktop environment."""
...
+ @property
+ def apps(self) -> "AppsProxy":
+ """Access registered apps via session.apps.{app_name}.
+
+ Provides a clean API for working with native applications:
+ await session.apps.chrome.install()
+ await session.apps.chrome.launch(url="https://example.com")
+ url = await session.apps.chrome.get_current_url()
+
+ Returns:
+ AppsProxy that provides access to bound app instances
+ """
+ ...
+
# --- Playwright-like Automation API ---
async def click_element(self, pid: int | str, selector: str) -> None:
@@ -193,3 +210,96 @@ class DesktopSession(Protocol):
selector: CSS selector for the element
"""
...
+
+ # --- Native Provider Commands ---
+
+ async def run_command(
+ self,
+ command: str,
+ *,
+ timeout: Optional[float] = None,
+ check: bool = True,
+ ) -> "CommandResult":
+ """Execute a shell command on the native desktop environment.
+
+ This method is only available with the native provider (Docker/QEMU).
+ It will raise NotImplementedError on simulated sessions.
+
+ Args:
+ command: Shell command to execute
+ timeout: Optional timeout in seconds
+ check: If True (default), raise an exception if the command fails
+ (non-zero return code). If False, return the result regardless.
+
+ Returns:
+ CommandResult with stdout, stderr, and return_code
+
+ Raises:
+ NotImplementedError: If called on simulated provider
+ RuntimeError: If check=True and command returns non-zero exit code
+
+ Example:
+ result = await session.run_command("ls -la /home/user")
+ print(result.stdout)
+ """
+ ...
+
+ # --- App Management ---
+
+ async def install_app(
+ self,
+ app_name: str,
+ *,
+ with_shortcut: bool = True,
+ **kwargs,
+ ) -> None:
+ """Install a registered app on the native desktop environment.
+
+ Uses the app registry to find platform-specific install functions.
+ This method is only available with the native provider (Docker/QEMU).
+
+ Args:
+ app_name: Name of the app to install (e.g., "godot", "firefox")
+ with_shortcut: Create desktop shortcut (default True)
+ **kwargs: App-specific arguments (e.g., version="4.2.1")
+
+ Raises:
+ ValueError: If app is not registered
+ NotImplementedError: If app doesn't support the current platform
+
+ Example:
+ await session.install_app("godot", version="4.2.1")
+ await session.install_app("firefox", with_shortcut=True)
+ """
+ ...
+
+ async def launch_app(
+ self,
+ app_name: str,
+ **kwargs,
+ ) -> None:
+ """Launch a registered app on the native desktop environment.
+
+ Uses the app registry to find platform-specific launch functions.
+ This method is only available with the native provider (Docker/QEMU).
+
+ Args:
+ app_name: Name of the app to launch
+ **kwargs: App-specific arguments (e.g., project_path="/path")
+
+ Raises:
+ ValueError: If app is not registered
+ NotImplementedError: If app doesn't support the current platform
+
+ Example:
+ await session.launch_app("godot", project_path="~/project", editor=True)
+ """
+ ...
+
+
+class CommandResult(TypedDict):
+ """Result from run_command execution."""
+
+ stdout: str
+ stderr: str
+ return_code: int
diff --git a/libs/cua-bench/cua_bench/computers/remote.py b/libs/cua-bench/cua_bench/computers/remote.py
index c0fa3db71e..d7b492a469 100644
--- a/libs/cua-bench/cua_bench/computers/remote.py
+++ b/libs/cua-bench/cua_bench/computers/remote.py
@@ -15,9 +15,12 @@ from __future__ import annotations
import asyncio
import time
from pathlib import Path
-from typing import Any, Dict, Literal, Optional
+from typing import TYPE_CHECKING, Any, Dict, Literal, Optional
from urllib.parse import urlparse
+if TYPE_CHECKING:
+ from ..apps.registry import AppsProxy
+
from ..types import (
Action,
ClickAction,
@@ -682,6 +685,23 @@ class RemoteDesktopSession:
# Generate URL from port
return f"http://localhost:{self._vnc_port}/?autoconnect=true"
+ @property
+ def apps(self) -> "AppsProxy":
+ """Access registered apps via session.apps.{app_name}.
+
+ Provides a clean API for working with native applications:
+ await session.apps.chrome.install()
+ await session.apps.chrome.launch(url="https://example.com")
+ url = await session.apps.chrome.get_current_url()
+
+ Returns:
+ AppsProxy that provides access to bound app instances
+ """
+ if not hasattr(self, "_apps_proxy"):
+ from ..apps.registry import AppsProxy
+ self._apps_proxy = AppsProxy(self)
+ return self._apps_proxy
+
async def click_element(self, pid: int | str, selector: str) -> None:
"""Find element by CSS selector and click its center.
@@ -716,23 +736,45 @@ class RemoteDesktopSession:
except (AttributeError, NotImplementedError):
return {}
- async def shell_command(self, command: str) -> Dict[str, Any]:
+ async def shell_command(
+ self,
+ command: str,
+ *,
+ check: bool = True,
+ ) -> Dict[str, Any]:
"""Execute a shell command.
Args:
command: Shell command to execute
+ check: If True (default), raise an exception if the command fails
+ (non-zero return code). If False, return the result regardless.
Returns:
Command result with stdout/stderr
+
+ Raises:
+ RuntimeError: If check=True and command returns non-zero exit code
"""
await self._ensure_computer()
result = await self.interface.run_command(command)
# Convert CommandResult to dict
+ return_code = result.return_code if hasattr(result, "return_code") else 0
+ stdout = result.stdout if hasattr(result, "stdout") else str(result)
+ stderr = result.stderr if hasattr(result, "stderr") else ""
+
+ if check and return_code != 0:
+ raise RuntimeError(
+ f"Command failed with return code {return_code}.\n"
+ f"Command: {command}\n"
+ f"Stdout: {stdout}\n"
+ f"Stderr: {stderr}"
+ )
+
return {
- "success": result.return_code == 0 if hasattr(result, "return_code") else True,
- "stdout": result.stdout if hasattr(result, "stdout") else str(result),
- "stderr": result.stderr if hasattr(result, "stderr") else "",
- "return_code": result.return_code if hasattr(result, "return_code") else 0,
+ "success": return_code == 0,
+ "stdout": stdout,
+ "stderr": stderr,
+ "return_code": return_code,
}
async def read_file(self, path: str) -> str:
@@ -770,9 +812,26 @@ class RemoteDesktopSession:
await self._ensure_computer()
return await self.interface.list_dir(path)
- async def run_command(self, command: str) -> Dict[str, Any]:
- """Execute a shell command (alias for shell_command)."""
- return await self.shell_command(command)
+ async def run_command(
+ self,
+ command: str,
+ *,
+ check: bool = True,
+ ) -> Dict[str, Any]:
+ """Execute a shell command (alias for shell_command).
+
+ Args:
+ command: Shell command to execute
+ check: If True (default), raise an exception if the command fails
+ (non-zero return code). If False, return the result regardless.
+
+ Returns:
+ Command result with stdout/stderr
+
+ Raises:
+ RuntimeError: If check=True and command returns non-zero exit code
+ """
+ return await self.shell_command(command, check=check)
async def launch_application(self, app_name: str) -> None:
"""Launch an application by name."""
@@ -856,6 +915,69 @@ class RemoteDesktopSession:
"""Drag from one position to another."""
await self.execute_action(DragAction(from_x=from_x, from_y=from_y, to_x=to_x, to_y=to_y))
+ # =========================================================================
+ # App Registry Integration
+ # =========================================================================
+
+ @property
+ def os_type(self) -> str:
+ """Return the OS type for this session."""
+ return self._os_type
+
+ async def install_app(
+ self,
+ app_name: str,
+ *,
+ with_shortcut: bool = True,
+ **kwargs,
+ ) -> None:
+ """Install a registered app on the native desktop environment.
+
+ Uses the app registry to find platform-specific install functions.
+
+ Args:
+ app_name: Name of the app to install (e.g., "godot", "firefox")
+ with_shortcut: Create desktop shortcut (default True)
+ **kwargs: App-specific arguments (e.g., version="4.2.1")
+
+ Raises:
+ ValueError: If app is not registered
+ NotImplementedError: If app doesn't support the current platform
+
+ Example:
+ await session.install_app("godot", version="4.2.1")
+ await session.install_app("firefox", with_shortcut=True)
+ """
+ await self._ensure_computer()
+ from ..apps import AppRegistry
+
+ await AppRegistry.install_app(self, app_name, with_shortcut=with_shortcut, **kwargs)
+
+ async def launch_app(
+ self,
+ app_name: str,
+ **kwargs,
+ ) -> None:
+ """Launch a registered app on the native desktop environment.
+
+ Uses the app registry to find platform-specific launch functions.
+
+ Args:
+ app_name: Name of the app to launch
+ **kwargs: App-specific arguments (e.g., project_path="/path")
+
+ Raises:
+ ValueError: If app is not registered
+ NotImplementedError: If app doesn't support the current platform
+
+ Example:
+ await session.launch_app("godot", project_path="~/project", editor=True)
+ """
+ await self._ensure_computer()
+ from ..apps import AppRegistry
+
+ await AppRegistry.launch_app(self, app_name, **kwargs)
+
def create_remote_session(
api_url: str,
diff --git a/libs/cua-bench/cua_bench/runner/docker_utils.py b/libs/cua-bench/cua_bench/runner/docker_utils.py
index 7149085c3d..fd4e4f07d2 100644
--- a/libs/cua-bench/cua_bench/runner/docker_utils.py
+++ b/libs/cua-bench/cua_bench/runner/docker_utils.py
@@ -1,6 +1,7 @@
"""Docker utilities for 2-container task execution."""
import asyncio
+import platform
import shutil
import subprocess
import uuid
@@ -13,7 +14,8 @@ def create_overlay_copy(golden_path: Path, overlay_path: Path, verbose: bool = F
"""Copy golden image to overlay directory for COW-like behavior.
This is a temporary workaround until proper QEMU overlay support is added.
- Uses native `cp -a` for speed (5x faster than Python shutil).
+ Uses native `cp -a` on Unix for speed (5x faster than Python shutil).
+ Falls back to shutil.copytree on Windows.
WIP: https://github.com/trycua/cua/issues/699
@@ -36,12 +38,27 @@ def create_overlay_copy(golden_path: Path, overlay_path: Path, verbose: bool = F
print(" (This may take a while for large images)")
print(" WIP: https://github.com/trycua/cua/issues/699")
- # Use native cp -a for speed (5x faster than Python shutil)
- result = subprocess.run(
- ["cp", "-a", f"{golden_path}/.", str(overlay_path)], capture_output=True, text=True
- )
- if result.returncode != 0:
- raise RuntimeError(f"Failed to create overlay: {result.stderr or 'cp failed'}")
+ # Use platform-specific copy method
+ if platform.system() == "Windows":
+ # On Windows, use shutil.copytree (robocopy would be faster but more complex)
+ try:
+ # copytree expects dest to not exist, but we need to copy contents into it
+ for item in golden_path.iterdir():
+ src = golden_path / item.name
+ dst = overlay_path / item.name
+ if src.is_dir():
+ shutil.copytree(src, dst)
+ else:
+ shutil.copy2(src, dst)
+ except Exception as e:
+ raise RuntimeError(f"Failed to create overlay: {e}")
+ else:
+ # On Unix, use native cp -a for speed (5x faster than Python shutil)
+ result = subprocess.run(
+ ["cp", "-a", f"{golden_path}/.", str(overlay_path)], capture_output=True, text=True
+ )
+ if result.returncode != 0:
+ raise RuntimeError(f"Failed to create overlay: {result.stderr or 'cp failed'}")
def find_free_port(start: int = 5000, end: int = 9000) -> int: