chore: import upstream snapshot with attribution

libs/python/cua/.bumpversion.cfg

@@ -0,0 +1,14 @@
+[bumpversion]
+current_version = 0.1.6
+commit = True
+tag = True
+tag_name = cua-v{new_version}
+message = Bump cua to v{new_version}
+
+[bumpversion:file:pyproject.toml]
+search = version = "{current_version}"
+replace = version = "{new_version}"
+
+[bumpversion:file:cua/__init__.py]
+search = __version__ = "{current_version}"
+replace = __version__ = "{new_version}"

libs/python/cua/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Cua AI, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

libs/python/cua/README.md

@@ -0,0 +1,69 @@
+# cua
+
+The unified Python SDK for Computer-Use Agents.
+
+## Installation
+
+```bash
+pip install cua
+```
+
+## Quick Start
+
+```python
+from cua import Sandbox, Image, ComputerAgent
+
+# Ephemeral local sandbox with an agent
+async with Sandbox.ephemeral(Image.linux(), local=True) as sb:
+    await sb.shell.run("uname -a")
+
+    agent = ComputerAgent(model="anthropic/claude-sonnet-4-5", tools=[sb])
+    async for response in agent.run("Open the browser and go to example.com"):
+        print(response)
+```
+
+## What's included
+
+| Package | Import | Purpose |
+|---|---|---|
+| `cua-sandbox` | `from cua import Sandbox, Image` | VM/container sandboxes |
+| `cua-agent` | `from cua import ComputerAgent` | LLM-driven computer-use agent |
+| `cua-cli` | `cua` command | CLI for managing sandboxes and images |
+
+`cua-agent[cloud]` extras are included by default (OpenAI, Anthropic, Gemini API backends).
+
+## Extras
+
+```bash
+pip install cua[omni]       # SOM-based visual grounding
+pip install cua[uitars-mlx] # UiTars via MLX (Apple Silicon)
+pip install cua[uitars-hf]  # UiTars via HuggingFace
+pip install cua[all]        # Everything
+```
+
+## Python Version
+
+Requires Python 3.12 or 3.13. For Python 3.11, install `cua-sandbox` directly.
+
+## Telemetry
+
+Cua collects anonymous usage statistics by default. Opt out with:
+
+```bash
+export CUA_TELEMETRY_ENABLED=false
+```
+
+Or per-instance:
+
+```python
+async with Sandbox.ephemeral(Image.linux(), telemetry_enabled=False) as sb:
+    ...
+
+agent = ComputerAgent(..., telemetry_enabled=False)
+```
+
+## Links
+
+- [Documentation](https://docs.trycua.com)
+- [GitHub](https://github.com/trycua/cua)
+- [Issues](https://github.com/trycua/cua/issues)

libs/python/cua/cua/__init__.py

@@ -0,0 +1,154 @@
+"""cua — Computer-Use Agents unified SDK.
+
+Quick start::
+
+    from cua import Sandbox, Image, ComputerAgent
+
+    # Configure API access (optional for local sandboxes)
+    import cua
+    cua.configure(api_key="sk-...")
+
+    # Start an ephemeral sandbox and run an agent inside it
+    async with Sandbox.ephemeral(Image.linux()) as sb:
+        screenshot = await sb.screenshot()
+
+        agent = ComputerAgent(model="anthropic/claude-sonnet-4-5", tools=[sb])
+        async for response in agent.run("Open the browser"):
+            print(response)
+
+Opt out of telemetry::
+
+    export CUA_TELEMETRY_ENABLED=false
+"""
+
+__version__ = "0.1.6"  # managed by bump2version — do not edit manually
+
+# ---------------------------------------------------------------------------
+# cua-sandbox surface
+# ---------------------------------------------------------------------------
+from cua_sandbox import (
+    CloudTransport,
+    Image,
+    Localhost,
+    Sandbox,
+    SandboxInfo,
+    configure,
+    localhost,
+    login,
+    sandbox,
+    whoami,
+)
+
+# ---------------------------------------------------------------------------
+# Runtime compatibility helpers — lazily imported so older cua-sandbox
+# releases that pre-date compat.py still work.
+# ---------------------------------------------------------------------------
+try:
+    from cua_sandbox.runtime.compat import (
+        RuntimeSupport,
+        check_local_support,
+        skip_if_unsupported,
+    )
+except ImportError:  # cua-sandbox < compat.py introduction
+
+    def _missing_compat(*_args, **_kwargs):  # type: ignore[misc]
+        raise ImportError(
+            "cua_sandbox.runtime.compat is not available in this version of cua-sandbox. "
+            "Upgrade cua-sandbox to use RuntimeSupport, check_local_support, or skip_if_unsupported."
+        )
+
+    RuntimeSupport = _missing_compat  # type: ignore[assignment,misc]
+    check_local_support = _missing_compat  # type: ignore[assignment]
+    skip_if_unsupported = _missing_compat  # type: ignore[assignment]
+
+# ---------------------------------------------------------------------------
+# Lazy imports — runtime classes, interface types, agent surface.
+# These are pulled in on first attribute access so that `import cua` stays
+# fast even when heavy optional deps (grpcio, vncdotool, …) are not installed.
+# ---------------------------------------------------------------------------
+
+_RUNTIME_NAMES: dict[str, tuple[str, str]] = {
+    # name -> (module, attr)
+    "DockerRuntime": ("cua_sandbox.runtime.docker", "DockerRuntime"),
+    "QEMURuntime": ("cua_sandbox.runtime.qemu", "QEMURuntime"),
+    "LumeRuntime": ("cua_sandbox.runtime.lume", "LumeRuntime"),
+    "AndroidEmulatorRuntime": ("cua_sandbox.runtime.android_emulator", "AndroidEmulatorRuntime"),
+    "HyperVRuntime": ("cua_sandbox.runtime.hyperv", "HyperVRuntime"),
+    "RuntimeInfo": ("cua_sandbox.runtime.base", "RuntimeInfo"),
+}
+
+_INTERFACE_NAMES: dict[str, tuple[str, str]] = {
+    "Shell": ("cua_sandbox.interfaces.shell", "Shell"),
+    "CommandResult": ("cua_sandbox.interfaces.shell", "CommandResult"),
+    "Mouse": ("cua_sandbox.interfaces.mouse", "Mouse"),
+    "Keyboard": ("cua_sandbox.interfaces.keyboard", "Keyboard"),
+    "Screen": ("cua_sandbox.interfaces.screen", "Screen"),
+    "Clipboard": ("cua_sandbox.interfaces.clipboard", "Clipboard"),
+    "Tunnel": ("cua_sandbox.interfaces.tunnel", "Tunnel"),
+    "TunnelInfo": ("cua_sandbox.interfaces.tunnel", "TunnelInfo"),
+    "Mobile": ("cua_sandbox.interfaces.mobile", "Mobile"),
+    "Terminal": ("cua_sandbox.interfaces.terminal", "Terminal"),
+    "Window": ("cua_sandbox.interfaces.window", "Window"),
+}
+
+_AGENT_NAMES: dict[str, tuple[str, str]] = {
+    "ComputerAgent": ("cua_agent", "ComputerAgent"),
+    "AgentResponse": ("cua_agent", "AgentResponse"),
+    "Messages": ("cua_agent", "Messages"),
+    "register_agent": ("cua_agent", "register_agent"),
+}
+
+_LAZY: dict[str, tuple[str, str]] = {**_RUNTIME_NAMES, **_INTERFACE_NAMES, **_AGENT_NAMES}
+
+
+def __getattr__(name: str):
+    if name in _LAZY:
+        mod_path, attr = _LAZY[name]
+        import importlib
+
+        mod = importlib.import_module(mod_path)
+        return getattr(mod, attr)
+    raise AttributeError(f"module 'cua' has no attribute {name!r}")
+
+
+__all__ = [
+    # cua-sandbox core
+    "configure",
+    "login",
+    "whoami",
+    "Image",
+    "Sandbox",
+    "SandboxInfo",
+    "sandbox",
+    "Localhost",
+    "localhost",
+    "CloudTransport",
+    # runtime compat (always available)
+    "RuntimeSupport",
+    "check_local_support",
+    "skip_if_unsupported",
+    # runtime classes (lazy)
+    "DockerRuntime",
+    "QEMURuntime",
+    "LumeRuntime",
+    "AndroidEmulatorRuntime",
+    "HyperVRuntime",
+    "RuntimeInfo",
+    # interface types (lazy)
+    "Shell",
+    "CommandResult",
+    "Mouse",
+    "Keyboard",
+    "Screen",
+    "Clipboard",
+    "Tunnel",
+    "TunnelInfo",
+    "Mobile",
+    "Terminal",
+    "Window",
+    # cua-agent (lazy)
+    "ComputerAgent",
+    "AgentResponse",
+    "Messages",
+    "register_agent",
+]

libs/python/cua/cua/callbacks.py

@@ -0,0 +1,32 @@
+"""cua.callbacks — agent lifecycle callback handlers.
+
+Usage::
+
+    from cua.callbacks import LoggingCallback, BudgetManagerCallback
+"""
+
+from cua_agent.callbacks import (
+    AsyncCallbackHandler,
+    BudgetManagerCallback,
+    ImageRetentionCallback,
+    LoggingCallback,
+    OperatorNormalizerCallback,
+    OtelCallback,
+    OtelErrorCallback,
+    PromptInstructionsCallback,
+    TelemetryCallback,
+    TrajectorySaverCallback,
+)
+
+__all__ = [
+    "AsyncCallbackHandler",
+    "ImageRetentionCallback",
+    "LoggingCallback",
+    "TrajectorySaverCallback",
+    "BudgetManagerCallback",
+    "TelemetryCallback",
+    "OtelCallback",
+    "OtelErrorCallback",
+    "OperatorNormalizerCallback",
+    "PromptInstructionsCallback",
+]

libs/python/cua/cua/runtime.py

@@ -0,0 +1,34 @@
+"""cua.runtime — sandbox runtime backends.
+
+Usage::
+
+    from cua.runtime import QEMURuntime, TartRuntime
+"""
+
+from cua_sandbox.runtime import (
+    AndroidEmulatorRuntime,
+    DockerRuntime,
+    HyperVRuntime,
+    LumeRuntime,
+    QEMUBaremetalRuntime,
+    QEMUDockerRuntime,
+    QEMURuntime,
+    QEMUWSL2Runtime,
+    Runtime,
+    RuntimeInfo,
+    TartRuntime,
+)
+
+__all__ = [
+    "Runtime",
+    "RuntimeInfo",
+    "DockerRuntime",
+    "QEMURuntime",
+    "QEMUDockerRuntime",
+    "QEMUBaremetalRuntime",
+    "QEMUWSL2Runtime",
+    "LumeRuntime",
+    "HyperVRuntime",
+    "AndroidEmulatorRuntime",
+    "TartRuntime",
+]

libs/python/cua/cua/tools.py

@@ -0,0 +1,29 @@
+"""cua.tools — agent tool classes and registry.
+
+Usage::
+
+    from cua.tools import BrowserTool, BaseTool, register_tool
+"""
+
+from cua_agent.tools import (
+    TOOL_REGISTRY,
+    BaseComputerTool,
+    BaseTool,
+    BrowserTool,
+    get_registered_tools,
+    get_tool,
+    register_tool,
+)
+from cua_agent.types import IllegalArgumentError, ToolError
+
+__all__ = [
+    "BaseTool",
+    "BaseComputerTool",
+    "register_tool",
+    "get_registered_tools",
+    "get_tool",
+    "TOOL_REGISTRY",
+    "BrowserTool",
+    "ToolError",
+    "IllegalArgumentError",
+]

libs/python/cua/pyproject.toml

@@ -0,0 +1,73 @@
+[project]
+name = "cua"
+version = "0.1.6"
+description = "Cua — Computer-Use Agents: unified SDK meta-package"
+readme = "README.md"
+license = "MIT"
+authors = [
+    { name = "TryCua", email = "hello@trycua.com" }
+]
+keywords = [
+    "computer-use",
+    "sandbox",
+    "agents",
+    "automation",
+    "vm",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries",
+]
+# Intersection of sub-package constraints: agent/cli require >=3.12
+requires-python = ">=3.12,<3.14"
+
+dependencies = [
+    "cua-sandbox>=0.1.11",
+    "cua-agent[cloud]>=0.8.0",
+    "cua-cli>=0.1.8",
+]
+
+[project.optional-dependencies]
+omni    = ["cua-agent[omni]"]
+cloud   = ["cua-agent[cloud]"]
+ui      = ["cua-agent[ui]"]
+uitars  = ["cua-agent[uitars]"]
+uitars-mlx = ["cua-agent[uitars-mlx]"]
+uitars-hf  = ["cua-agent[uitars-hf]"]
+all     = ["cua-agent[all]", "cua-cli[all]"]
+
+[project.urls]
+Homepage      = "https://github.com/trycua/cua"
+Documentation = "https://docs.trycua.com"
+Repository    = "https://github.com/trycua/cua"
+Issues        = "https://github.com/trycua/cua/issues"
+
+# No [project.scripts] — cua-cli already registers 'cua = "cua_cli.main:main"'
+
+[build-system]
+requires      = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build]
+include = [
+    "cua/**",
+    "README.md",
+    "LICENSE",
+]
+exclude = [
+    "cua/**/__pycache__",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["cua"]
+
+[tool.uv.sources]
+cua-sandbox = { path = "../cua-sandbox", editable = true }
+cua-agent   = { path = "../agent",       editable = true }
+cua-cli     = { path = "../cua-cli",     editable = true }