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.

14.7 KB
Raw Blame
"""Local runtimes on the ``cua`` SDK (cua-vmm): containers (gVisor), QEMU, Lume.

``DockerRuntime``, the QEMU runtimes and ``LumeRuntime`` are thin adapters
over :class:`NativeRuntime`: the SDK provisions the backend (``runsc`` for
containers, QEMU firmware/accel, ``lume serve``), starts the instance, publishes
its ports and persists ``~/.cua/sandboxes/<name>.json`` in the format
``sandbox_state`` reads. Readiness is daemon-agnostic: the backend reports
the instance running, plus the image's own ``server_port`` probe when one is
declared.

Image layers (``pip_install``, ``run``, ``copy``, ``env``, ...) on a container
image are built into the local container engine before boot (cached by
content hash, ``cua-b-<hash>``), so they work on any image. A VM image takes them after
boot through cua-spacesd, and only when it runs one (otherwise
:class:`~cua_sandbox.Unsupported`).
"""

from __future__ import annotations

import logging
import os
import secrets
from typing import Any, Optional

from cua_sandbox._sdk import (
    ENV_SERVICE,
    SPACESD_PORT,
    daemon_runtime,
    local_runtime,
    millis,
    native,
)
from cua_sandbox.image import Image
from cua_sandbox.runtime.base import Runtime, RuntimeInfo

logger = logging.getLogger(__name__)

#: runtime_type values the SDK writes to state files.
NATIVE_RUNTIME_TYPES = frozenset({"container", "qemu", "lume", "qemu-docker", "managed"})


def _require_spacesd_for_layers(ref: str) -> None:
    """VM images take layers after boot through cua-spacesd: refuse one
    that does not run it (or whose registry cannot say) before booting."""
    from cua_sandbox._sdk import Unsupported

    kind, _, reference = ref.partition(":")
    backend = {"vm": "vm", "lume": "lume", "container": "container", "docker": "container"}
    has = None
    if kind in backend and reference:
        n = native()
        try:
            has = n.resolve_image(reference, backend[kind], None).spacesd
        except n.CuaError as error:
            logger.debug("could not read %s for cua-spacesd: %s", reference, error)
    if has is not True:
        what = "a VM image" if kind in ("vm", "lume", "disk") else "these layers"
        raise Unsupported(
            f"image layers on {what} ({ref}) are applied after boot through "
            "cua-spacesd, which this image does not run. Use a container image "
            "with pip_install/uv_install/apt_install/run/copy/env (they build locally), "
            "or bake them into the image"
        )


def is_native_state(state: Optional[dict]) -> bool:
    """Whether a state file was written by the SDK (it records ``services``)."""
    return bool(state) and "services" in state


def _status_word(status: Any) -> str:
    n = native()
    return {
        n.SandboxStatus.RUNNING: "running",
        n.SandboxStatus.SUSPENDED: "suspended",
        n.SandboxStatus.STOPPED: "stopped",
        n.SandboxStatus.PROVISIONING: "provisioning",
    }.get(status, "unknown")


def runtime_info_from_state(
    name: str, state: dict, *, handle: Any = None, environment: Optional[str] = None
) -> RuntimeInfo:
    """``RuntimeInfo`` from an SDK-written state file."""
    exposed = {int(g): int(h) for g, h in (state.get("exposed_ports") or {}).items()}
    token = state.get("env_token")
    # The SDK records `env` only when the image carries cua-spacesd (its
    # port is published); older state files have no services at all.
    services = state["services"] if "services" in state else {ENV_SERVICE: SPACESD_PORT}
    has_env = ENV_SERVICE in services
    env_guest = int(services.get(ENV_SERVICE) or SPACESD_PORT)
    api_port = (exposed.get(env_guest) or state.get("api_port") or 0) if has_env else 0
    info = RuntimeInfo(
        host=state.get("host") or "127.0.0.1",
        api_port=int(api_port),
        vnc_port=state.get("vnc_port"),
        qmp_port=state.get("qmp_port"),
        name=name,
        environment=environment or state.get("os_type"),
        guest_server_port=env_guest if has_env else None,
        exposed_ports={g: h for g, h in exposed.items() if g != env_guest or not has_env} or None,
        native=handle,
        env_token=token,
    )
    return info


class NativeRuntime(Runtime):
    """A local runtime backed by the SDK's ``Sandboxes`` (provider = local).

    Subclasses choose the backend with :meth:`_image_ref` (``container:<ref>``,
    ``vm:<ref>``, ``disk:<path>`` or ``lume:<ref>``).
    """

    #: runtime_type label kept in Python-facing listings.
    runtime_type = "local"
    #: The SDK provider (``ProviderKind`` member name) and ``on`` word.
    provider_kind = "LOCAL"
    on: Optional[str] = None
    #: How long the first interface call waits for cua-spacesd after boot.
    env_ready_timeout = 120.0

    def __init__(
        self,
        *,
        ephemeral: bool = True,
        cpus: Optional[int] = None,
        memory_mb: Optional[int] = None,
        ready_timeout: float = 900.0,
        server_port: Optional[int] = None,
        environment: Optional[dict[str, str]] = None,
    ) -> None:
        self.ephemeral = ephemeral
        self.cpus = cpus
        self.memory_mb = memory_mb
        self.ready_timeout = ready_timeout
        self.server_port = server_port
        self.environment = dict(environment or {})

    # ── subclass hooks ───────────────────────────────────────────────────

    async def _image_ref(self, image: Image, name: str, **opts: Any) -> str:
        raise NotImplementedError

    def _os(self, image: Image) -> str:
        return image.os_type or "linux"

    #: Whether this runtime mints the spacesd token itself (containers).
    #: Otherwise the SDK mints one for Linux VMs (cloud-init, the
    #: /run/cua/env-token contract) and macOS VMs (the Lume setup share) and
    #: keeps it in the sandbox record, which ``_info`` reads back.
    delivers_guest_env = False

    def _env_token(self) -> Optional[str]:
        """The spacesd token for a new sandbox.

        ``CUA_SANDBOX_ENV_TOKEN`` (a token baked into the image as
        /etc/cua/env-token) wins; otherwise a fresh per-sandbox token when the
        backend delivers it to the guest (libs/images ensure-env-token.sh reads
        CUA_ENV_TOKEN), else none.
        """
        configured = os.environ.get("CUA_SANDBOX_ENV_TOKEN")
        if configured:
            return configured
        return secrets.token_urlsafe(24) if self.delivers_guest_env else None

    # ── Runtime API ──────────────────────────────────────────────────────

    async def start(self, image: Image, name: str, **opts: Any) -> RuntimeInfo:
        ephemeral = opts.pop("ephemeral", True)
        # The portable sandbox options (Sandbox.create(command=, env=,
        # services=, wait_for=)).
        command = opts.pop("command", None)
        extra_env = dict(opts.pop("env", None) or {})
        services = dict(opts.pop("services", None) or {})
        wait_for = list(opts.pop("wait_for", None) or [])
        from cua_sandbox.containers import sidecars_of

        sidecars = sidecars_of(opts.pop("sidecars", None))
        # What kind and which engine (Sandbox.create(kind=, runtime=)); the
        # SDK checks them against the image prefix this adapter picks.
        kind = opts.pop("kind", None)
        legacy_engine = opts.pop("container_runtime", None)
        engine = opts.pop("runtime", None) or legacy_engine
        # "none" cuts guest egress (QEMU); the backend refuses it where it
        # cannot (containers, Lume). Unset: outbound network.
        network = opts.pop("network", None)
        # A pool to take a ready sandbox from (`create_pool`; `cua daemon`
        # keeps it).
        pool = opts.pop("pool", None)
        n = native()
        ref = await self._image_ref(image, name, **opts)
        # Layers on a container image: a local build before boot (any
        # image). On a VM: applied after boot, which needs cua-spacesd.
        build = None
        if image._layers or image._files or image._env:
            from cua_sandbox.containers import buildable

            if ref.startswith(("container:", "docker:")) and buildable(image):
                from cua_sandbox.containers import image_build

                build = image_build(image)
            else:
                # A VM, or layers a container build cannot run (app_install,
                # brew_install, ...): after boot, through cua-spacesd.
                _require_spacesd_for_layers(ref)
        # 3211 is published (and `env` reported) only when the image carries
        # cua-spacesd: the SDK decides from the image, so `env` is implicit.
        ports = sorted({SPACESD_PORT, *image._ports, *services.values()})
        probes = [p.native() for p in wait_for]
        if self.server_port is not None:
            ports = sorted({*ports, self.server_port})
            probes.append(n.ReadinessProbe(port=self.server_port))
            services["server"] = self.server_port
        token = self._env_token()
        options = n.SandboxCreateOptions(
            on=self.on or "local",
            image=ref,
            name=name,
            token=token,
            os=self._os(image),
            cpus=opts.get("cpu_count") or self.cpus,
            memory_mb=opts.get("memory_mb") or self.memory_mb,
            ports=ports,
            services=services,
            wait_for=probes,
            ready_timeout_ms=millis(self.ready_timeout),
            env={
                **self.environment,
                **dict(image._env),
                **extra_env,
                **({"CUA_ENV_TOKEN": token} if token else {}),
            },
            command=list(command) if command else None,
            sidecars=[c.native() for c in sidecars],
            registry_secret=image._secret.native() if image._secret is not None else None,
            kind=kind,
            runtime=engine,
            network=network,
            build=build,
            pool=pool,
        )
        logger.info("Starting %s sandbox %r from %s", type(self).__name__, name, ref)
        try:
            # Pools live in `cua daemon`: a create from one goes there (same
            # state directory, so it connects as a local one).
            cua = daemon_runtime() if pool is not None else local_runtime()
            handle = await cua.sandboxes().create(options)
        except (n.CuaError.InvalidPlacement, n.CuaError.InvalidArgument) as error:
            from cua_sandbox._placement import translate

            raise translate(error) from None
        if token:
            _remember_token(name, token)
        info = self._info(name, handle, image)
        try:
            if build is None:
                await self._apply_layers(info, image)
        except BaseException:
            await self._delete_quietly(name)
            raise
        if ephemeral:
            logger.debug("sandbox %r is ephemeral; it is deleted on destroy()", name)
        return info

    def _info(self, name: str, handle: Any, image: Optional[Image]) -> RuntimeInfo:
        from cua_sandbox import sandbox_state

        state = sandbox_state.load(name) or {}
        if not state:
            record = handle.info()
            state = {
                "host": "127.0.0.1",
                "services": dict(record.services),
                "os_type": image.os_type if image else None,
            }
        info = runtime_info_from_state(
            name, state, handle=handle, environment=image.os_type if image else None
        )
        info.env_ready_timeout = self.env_ready_timeout
        return info

    async def _apply_layers(self, info: RuntimeInfo, image: Image) -> None:
        if not (image._layers or image._files or image._env):
            return
        from cua_sandbox.builder.build import _apply_env
        from cua_sandbox.builder.executor import LayerExecutor

        executor = await LayerExecutor.for_sandbox(
            info.native,
            os_type=image.os_type,
            ready_timeout=self.env_ready_timeout,
        )
        await _apply_env(executor, image)
        for src, dst in image._files:
            await executor.execute_layers([{"type": "copy", "src": src, "dst": dst}])
        if image._layers:
            await executor.execute_layers(list(image._layers))

    async def _handle(self, name: str) -> Any:
        return await local_runtime().sandboxes().connect(name)

    async def _delete_quietly(self, name: str) -> None:
        try:
            await local_runtime().sandboxes().delete(name)
        except Exception as error:  # noqa: BLE001 - cleanup after a failed start
            logger.warning("Failed to remove sandbox %r after a failed start: %s", name, error)

    async def stop(self, name: str) -> None:
        if self.ephemeral:
            await self.delete(name)
        else:
            await self.suspend(name)

    async def delete(self, name: str) -> None:
        await local_runtime().sandboxes().delete(name)

    async def suspend(self, name: str) -> None:
        await (await self._handle(name)).suspend()

    async def resume(self, image: Optional[Image], name: str, **opts: Any) -> RuntimeInfo:
        handle = await self._handle(name)
        await handle.resume()
        return self._info(name, await self._handle(name), image)

    async def is_ready(self, info: RuntimeInfo, timeout: float = 120) -> bool:
        # Daemon-agnostic: the SDK returned the instance running (and passed
        # any declared server_port probe) before start() returned.
        handle = getattr(info, "native", None)
        if handle is not None and self.server_port is not None:
            n = native()
            await handle.wait_ready([n.ReadinessProbe(port=self.server_port)], millis(timeout))
        return True

    async def list(self) -> list[dict]:
        rows = []
        for record in await local_runtime().sandboxes().list("local"):
            if record.runtime_type not in NATIVE_RUNTIME_TYPES:
                continue
            rows.append(
                {
                    "name": record.name,
                    "status": _status_word(record.status),
                    "runtime_type": record.runtime_type,
                    "image": record.image,
                }
            )
        return rows


def _remember_token(name: str, token: str) -> None:
    """Keep the spacesd token with the sandbox record (owner-only file).

    The SDK holds tokens in memory only, so a later ``Sandbox.connect(name,
    local=True)`` from another process reads it from here.
    """
    from cua_sandbox import sandbox_state

    if sandbox_state.load(name) is None:
        return
    sandbox_state.update(name, env_token=token)
    try:
        os.chmod(sandbox_state._state_path(name), 0o600)
    except OSError:
        pass