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.

28.7 KB
Raw Blame
"""Image builder — pure-data immutable chained builder for sandbox images.

Supports Linux, macOS, and Windows constructors. Serializes to a spec dict
or a cloud-init script.

Usage::

    from cua_sandbox import Image

    img = (
        Image.linux("ubuntu", "24.04")
        .apt_install("curl", "git", "build-essential")
        .pip_install("numpy", "pandas")
        .env(MY_VAR="hello")
        .run("echo 'setup complete'")
        .expose(8080)
    )

    spec = img.to_dict()
"""

from __future__ import annotations

import logging
from dataclasses import dataclass, field
from pathlib import Path
from typing import Any, Dict, Optional, Tuple

from cua_sandbox._paths import cua_home, patched_or

logger = logging.getLogger(__name__)

#: The canonical images (``cua_image::canonical`` in the native SDK):
#: ``Image.linux()`` is ``ghcr.io/trycua/linux:24.04``, ``Image.windows()``
#: ``ghcr.io/trycua/windows:2022``, ``Image.macos()`` ``ghcr.io/trycua/macos:26``
#: (``"15"``/``"sequoia"``: ``macos:15``). One override per OS:
#: ``CUA_IMAGE_LINUX`` / ``CUA_IMAGE_WINDOWS`` / ``CUA_IMAGE_MACOS`` (the old
#: ``CUA_DEFAULT_LINUX_IMAGE`` / ``CUA_DEFAULT_WINDOWS_IMAGE`` /
#: ``CUA_SANDBOX_LINUX_CONTAINER_IMAGE`` still work, deprecated). The one
#: resolver then picks the variant a backend runs: the rootfs for containers,
#: the ``-disk`` containerDisk for VMs (``kind="vm"``), Lume on a Mac.
CANONICAL_DISTROS: Dict[str, Tuple[str, ...]] = {
    "linux": ("ubuntu",),
    "windows": ("windows",),
    "macos": ("macos",),
}
#: Windows versions with a canonical image; others (``"11"``) install locally
#: from an evaluation ISO.
CANONICAL_WINDOWS_VERSIONS = ("2022",)
MACOS_VERSIONS = ("15", "sequoia", "26", "tahoe")


def canonical_image(os_type: str, version: Optional[str] = None) -> str:
    """The canonical image for ``os_type`` (native ``cua.canonical_image``)."""
    from cua_sandbox._sdk import native

    return native().canonical_image(os_type, version)


def _tier_ref(os_type: str, version: Optional[str], tier: Optional[str]) -> Optional[str]:
    """The registry ref of a non-default tier (``slim``, macOS ``xcode``), or
    ``None`` for the full default. Raises the native
    ``CuaError.ImageNotPublished`` for a tier CI has not published yet."""
    if tier is None or tier.strip().lower() in ("", "full", "default"):
        return None
    from cua_sandbox._sdk import native

    return native().canonical_image_tier(os_type, version, tier)


_IMAGE_CACHE = cua_home() / "cua-sandbox" / "image-cache"
_IMAGE_CACHE_DEFAULT = _IMAGE_CACHE


def _image_cache() -> Path:
    return patched_or(_IMAGE_CACHE, _IMAGE_CACHE_DEFAULT, "cua-sandbox", "image-cache")


def _download_image(url: str) -> str:
    """Download an image URL to the local cache, extract if zipped.

    Returns the path to the final disk image (qcow2, img, etc.).
    Skips download if the file already exists in the cache.
    """
    import hashlib
    import urllib.request

    _image_cache().mkdir(parents=True, exist_ok=True)

    # Determine filename from URL
    url_filename = url.rsplit("/", 1)[-1].split("?")[0]
    # Use hash prefix to avoid collisions
    url_hash = hashlib.sha256(url.encode()).hexdigest()[:12]
    download_path = _image_cache() / f"{url_hash}_{url_filename}"

    # Check if we already have the extracted result
    if download_path.suffix.lower() == ".zip":
        # Look for an already-extracted disk image
        extracted = _find_disk_image(_image_cache() / url_hash)
        if extracted:
            logger.info(f"Using cached image: {extracted}")
            return str(extracted)

    if not download_path.exists():
        logger.info(f"Downloading {url} → {download_path}")
        urllib.request.urlretrieve(url, str(download_path))
        logger.info(f"Download complete: {download_path}")

    # Extract zip files
    if download_path.suffix.lower() == ".zip":
        import zipfile

        extract_dir = _image_cache() / url_hash
        extract_dir.mkdir(parents=True, exist_ok=True)
        logger.info(f"Extracting {download_path} → {extract_dir}")
        with zipfile.ZipFile(download_path) as zf:
            zf.extractall(extract_dir)
        # Find the disk image inside
        disk = _find_disk_image(extract_dir)
        if not disk:
            raise FileNotFoundError(
                f"No disk image found in {download_path}. "
                f"Contents: {[f.name for f in extract_dir.rglob('*') if f.is_file()]}"
            )
        logger.info(f"Extracted disk image: {disk}")
        return str(disk)

    return str(download_path)


def _find_disk_image(directory: Path) -> Optional[Path]:
    """Find a disk image file in a directory."""
    for ext in (".qcow2", ".img", ".raw", ".vhdx", ".vmdk"):
        for f in directory.rglob(f"*{ext}"):
            return f
    return None


_INSTALL_OS_MAP: Dict[str, Tuple[str, ...]] = {
    "apt_install": ("linux",),
    "brew_install": ("macos",),
    "choco_install": ("windows",),
    "winget_install": ("windows",),
    "apk_install": ("android",),
    "pwa_install": ("android",),
}


@dataclass(frozen=True)
class ImageInfo:
    """The image a sandbox runs, as resolved and pinned at create time.

    ``reference`` is the reference as requested (normalised, e.g.
    ``docker.io/library/python:3.12-slim``), ``pinned_ref`` the
    ``registry/repo@sha256:...`` that ran, ``variant`` one of ``rootfs``,
    ``containerdisk`` or ``lume``, ``arch`` the architecture that
    ran (``amd64``/``arm64``, when known), ``os`` the guest OS and
    ``emulated`` whether it ran under emulation.
    """

    reference: str
    pinned_ref: str
    digest: str
    variant: str
    arch: Optional[str]
    os: str
    emulated: bool

    @classmethod
    def _from_native(cls, obj: Any) -> Optional["ImageInfo"]:
        """From the SDK's ``ImageInfo`` or ``ResolvedImage`` (same fields);
        ``None`` for ``None`` or anything unreadable. Never raises."""
        if obj is None:
            return None
        try:
            pinned = str(obj.pinned_ref)
            digest = getattr(obj, "digest", None) or pinned.partition("@")[2]
            arch = getattr(obj, "arch", None)
            return cls(
                reference=str(obj.reference),
                pinned_ref=pinned,
                digest=str(digest),
                variant=str(obj.variant),
                arch=str(arch) if arch else None,
                os=str(getattr(obj, "os", "") or ""),
                emulated=bool(getattr(obj, "emulated", False)),
            )
        except Exception:  # noqa: BLE001 - informational; never fail the caller
            return None


@dataclass(frozen=True)
class Image:
    """Immutable, chainable image specification.

    Each mutation method returns a new Image instance so that builders
    can be forked at any point.
    """

    os_type: str  # "linux" | "macos" | "windows" | "android"
    distro: str  # e.g. "ubuntu", "macos", "windows"
    version: str  # e.g. "24.04", "15", "11"
    kind: Optional[str] = None  # "container" | "vm" | None (resolved after registry pull)
    _layers: Tuple[Dict[str, Any], ...] = ()
    _env: Tuple[Tuple[str, str], ...] = ()
    _ports: Tuple[int, ...] = ()
    _files: Tuple[Tuple[str, str], ...] = ()  # (src, dst)
    _registry: Optional[str] = None  # OCI registry reference
    _disk_path: Optional[str] = None  # local disk file path (qcow2, vhdx, raw)
    _agent_type: Optional[str] = None  # e.g. "osworld" for OSWorld Flask server
    # Private-registry credentials (RegistrySecret); never serialized.
    _secret: Optional[Any] = field(default=None, compare=False, repr=False)
    # What the native resolver pinned (resolve_image_kind); never serialized.
    _resolved: Optional[ImageInfo] = field(default=None, compare=False, repr=False)

    def __post_init__(self) -> None:
        # ``kind`` is "container", "vm" or None (auto); "auto" means None.
        if isinstance(self.kind, str):
            word = self.kind.strip().lower()
            if word in ("", "auto"):
                object.__setattr__(self, "kind", None)
            elif word in ("container", "vm"):
                object.__setattr__(self, "kind", word)

    # ── Constructors ─────────────────────────────────────────────────────

    @classmethod
    def linux(
        cls,
        distro: str = "ubuntu",
        version: str = "24.04",
        kind: Optional[str] = None,
        tier: Optional[str] = None,
    ) -> Image:
        """Linux: the canonical ``ghcr.io/trycua/linux:<version>`` image.

        ``kind=None`` (or ``"auto"``) runs what the image is (the rootfs: a
        gVisor container); ``kind="vm"`` its ``-disk`` containerDisk (QEMU);
        ``kind="container"`` the rootfs. ``Sandbox.create(kind=...)``
        overrides it.

        ``tier``: ``"full"`` (the default: dev tooling) or ``"slim"``
        (``24.04-slim``: cua-spacesd and Chromium only; what CI runs). A tier
        CI has not published yet raises ``CuaError.ImageNotPublished``; use
        ``Image.from_registry(ref)`` to run it anyway.
        """
        ref = _tier_ref("linux", version, tier)
        return cls(os_type="linux", distro=distro, version=version, kind=kind, _registry=ref)

    @classmethod
    def macos(cls, version: str = "26", kind: str = "vm", tier: Optional[str] = None) -> Image:
        """macOS: the canonical ``ghcr.io/trycua/macos:<version>`` image (Lume locally).

        Supported versions: ``"15"`` / ``"sequoia"``, ``"26"`` / ``"tahoe"``.
        ``tier``: ``"full"`` (the default), ``"slim"`` or ``"xcode"`` /
        ``"xcode-<X.Y>"`` (full plus one pinned Xcode); unpublished tiers
        raise ``CuaError.ImageNotPublished``.
        """
        if version not in MACOS_VERSIONS:
            supported = ", ".join(f'"{v}"' for v in MACOS_VERSIONS)
            raise ValueError(f"Unsupported macOS version {version!r}. Supported: {supported}")
        ref = _tier_ref("macos", version, tier)
        return cls(os_type="macos", distro="macos", version=version, kind=kind, _registry=ref)

    @classmethod
    def windows(cls, version: str = "2022", kind: str = "vm", tier: Optional[str] = None) -> Image:
        """Windows: the canonical ``ghcr.io/trycua/windows:2022`` containerDisk.

        Other versions, including ``"11"``, have no canonical image: they are
        installed from a downloaded evaluation ISO. ``tier="slim"`` names
        ``2022-slim`` once published.
        """
        ref = _tier_ref("windows", version, tier)
        return cls(os_type="windows", distro="windows", version=version, kind=kind, _registry=ref)

    @classmethod
    def omarchy(cls, channel: Optional[str] = None) -> Image:
        """Omarchy (Arch Linux, Hyprland) with cua-spacesd:
        ``ghcr.io/trycua/omarchy:edge`` (or ``"rc"``/``"stable"``).

        An amd64 VM: QEMU (emulated on arm64 hosts, so slow there). Until CI
        publishes it this raises
        ``CuaError.ImageNotPublished``; use
        ``Image.from_registry("ghcr.io/trycua/omarchy:edge", kind="vm")`` to
        run it anyway.
        """
        from cua_sandbox._sdk import native

        ref = native().omarchy_image(channel)
        return cls(
            os_type="linux", distro="omarchy", version=channel or "edge", kind="vm", _registry=ref
        )

    @classmethod
    def android(cls, version: str = "14", kind: str = "vm") -> Image:
        """Android image. Always a VM (QEMU emulator)."""
        return cls(os_type="android", distro="android", version=version, kind=kind)

    @classmethod
    def from_registry(
        cls,
        ref: str,
        *,
        os_type: str = "linux",
        kind: Optional[str] = None,
        agent_type: Optional[str] = None,
        secret: Optional[Any] = None,
    ) -> Image:
        """Create an image from a registry reference.

        ``secret`` (a :class:`~cua_sandbox.RegistrySecret`) pulls a private
        image. It is never logged or saved.

        os_type selects the firmware: Windows guest disks are built UEFI-only,
        so a Windows containerDisk pulled from a registry must say so or it is
        handed BIOS and will not boot. kind is resolved after pull when omitted.
        agent_type names the guest control server the disk already runs, the
        same hint as ``from_file``: ``"osworld"`` selects the OSWorld Flask
        server on port 5000 instead of the computer-server on 8000, for local
        QEMU.
        """
        return cls(
            os_type=os_type,
            distro="registry",
            version="latest",
            kind=kind,
            _registry=ref,
            _agent_type=agent_type,
            _secret=secret,
        )

    @classmethod
    def from_file(
        cls,
        path: str,
        *,
        os_type: str = "windows",
        kind: str = "vm",
        agent_type: Optional[str] = None,
    ) -> Image:
        """Create an image from a local disk, ISO file, or URL.

        Supported formats: qcow2, vhdx, raw, img, iso.
        URLs (http/https) are downloaded automatically. Zip files are extracted.
        For ISOs, the runtime will create a qcow2 disk and attach the ISO
        as a CD-ROM for installation/boot.

        Args:
            path: Local file path or URL (http/https).
            os_type: OS type hint ("linux", "windows", "macos", "android").
            kind: "vm" or "container".
            agent_type: Agent type hint (e.g. "osworld" for OSWorld Flask server).
        """
        if path.startswith(("http://", "https://")):
            path = _download_image(path)
        return cls(
            os_type=os_type,
            distro="local",
            version="local",
            kind=kind,
            _disk_path=path,
            _agent_type=agent_type,
        )

    @classmethod
    def from_dict(cls, data: Dict[str, Any]) -> Image:
        """Reconstruct an Image from a serialized spec dict."""
        img = cls(
            os_type=data["os_type"],
            distro=data["distro"],
            version=data["version"],
            kind=data.get("kind"),
            _registry=data.get("registry"),
            _agent_type=data.get("agent_type"),
        )
        # Replay layers
        for layer in data.get("layers", []):
            img = img._add_layer(layer)
        for k, v in data.get("env", {}).items():
            img = img.env(**{k: v})
        for p in data.get("ports", []):
            img = img.expose(p)
        for src, dst in data.get("files", []):
            img = img.copy(src, dst)
        return img

    def _check_os(self, layer_type: str) -> None:
        """Raise ValueError if this install method is incompatible with os_type."""
        allowed = _INSTALL_OS_MAP.get(layer_type)
        if allowed and self.os_type not in allowed:
            raise ValueError(
                f"{layer_type} is not supported on {self.os_type!r} images. "
                f"Supported OS types: {', '.join(allowed)}"
            )

    # ── Chainable mutations (return new Image) ───────────────────────────

    def _add_layer(self, layer: Dict[str, Any]) -> Image:
        return self._with(_layers=self._layers + (layer,))

    def _with(self, **kwargs) -> Image:
        """Return a new Image with specific fields overridden."""
        fields = {
            "os_type": self.os_type,
            "distro": self.distro,
            "version": self.version,
            "kind": self.kind,
            "_layers": self._layers,
            "_env": self._env,
            "_ports": self._ports,
            "_files": self._files,
            "_registry": self._registry,
            "_disk_path": self._disk_path,
            "_agent_type": self._agent_type,
            "_secret": self._secret,
            "_resolved": self._resolved,
        }
        fields.update(kwargs)
        return Image(**fields)

    def apt_install(self, *packages: str) -> Image:
        """Install packages via apt (Linux only)."""
        self._check_os("apt_install")
        return self._add_layer({"type": "apt_install", "packages": list(packages)})

    def brew_install(self, *packages: str) -> Image:
        """Install packages via Homebrew (macOS)."""
        self._check_os("brew_install")
        return self._add_layer({"type": "brew_install", "packages": list(packages)})

    def choco_install(self, *packages: str) -> Image:
        """Install packages via Chocolatey (Windows)."""
        self._check_os("choco_install")
        return self._add_layer({"type": "choco_install", "packages": list(packages)})

    def winget_install(self, *packages: str) -> Image:
        """Install packages via winget (Windows)."""
        self._check_os("winget_install")
        return self._add_layer({"type": "winget_install", "packages": list(packages)})

    def apk_install(self, *apk_paths: str) -> Image:
        """Install APK files via adb (Android only)."""
        self._check_os("apk_install")
        return self._add_layer({"type": "apk_install", "packages": list(apk_paths)})

    def pwa_install(
        self,
        manifest_url: str,
        package_name: Optional[str] = None,
        keystore: Optional[str] = None,
        keystore_alias: str = "android",
        keystore_password: str = "android",
        builder: str = "pwa2apk",
        push_timeout: Optional[float] = None,
    ) -> "Image":
        """Build an APK from a PWA manifest URL and install it (Android only).

        Two builder backends are supported:

        * ``"pwa2apk"`` (default) — generates a lightweight WebView-based APK.
          No Chrome dependency, no "Running in Chrome" banner, no Digital Asset
          Links needed.  ~10 KB APK.
        * ``"bubblewrap"`` — generates a Chrome Trusted Web Activity (TWA) APK.
          Requires Chrome on the device and a matching
          ``/.well-known/assetlinks.json`` on the server.  Shows a mandatory
          "Running in Chrome" privacy disclosure on every launch.

        Args:
            manifest_url: Full URL to the PWA's ``manifest.json`` or
                          ``manifest.webmanifest``.
                          Example: ``"http://10.0.2.2:3000/manifest.json"``
            package_name: Android package ID.  Defaults to a reversed-hostname
                          derivation (e.g. ``"com.example.app"``).
            keystore:     Path to a ``*.keystore`` / ``*.jks`` file.  When
                          omitted a fresh keystore is generated and cached.
                          Pass the keystore bundled with your PWA repo so the
                          fingerprint is deterministic.
            keystore_alias:    Key alias inside the keystore (default ``"android"``).
            keystore_password: Password for both the store and the key
                               (default ``"android"``).
            builder:      ``"pwa2apk"`` (default) or ``"bubblewrap"``.
            push_timeout: Optional seconds for the ``write_bytes`` ``adb push``
                          of the built APK.  When ``None`` the server default
                          applies.
        """
        if builder not in ("pwa2apk", "bubblewrap"):
            raise ValueError(f"builder must be 'pwa2apk' or 'bubblewrap', got {builder!r}")
        self._check_os("pwa_install")
        layer: dict = {"type": "pwa_install", "manifest_url": manifest_url, "builder": builder}
        if package_name:
            layer["package_name"] = package_name
        if keystore:
            layer["keystore"] = keystore
        layer["keystore_alias"] = keystore_alias
        layer["keystore_password"] = keystore_password
        if push_timeout is not None:
            layer["push_timeout"] = push_timeout
        return self._add_layer(layer)

    def uv_install(self, *packages: str) -> Image:
        """Install Python packages via uv add into the cua-server project."""
        return self._add_layer({"type": "uv_install", "packages": list(packages)})

    def pip_install(self, *packages: str) -> Image:
        """Install Python packages via pip."""
        return self._add_layer({"type": "pip_install", "packages": list(packages)})

    def app_install(self, app_id: str) -> Image:
        """Install an app from the cua-sandbox-apps catalog.

        Requires ``cua-sandbox-apps`` to be installed. The app's install
        script for this image's OS is executed as a build layer.
        """
        return self._add_layer({"type": "app_install", "app_id": app_id})

    def run(self, command: str) -> Image:
        """Run a shell command during image build."""
        return self._add_layer({"type": "run", "command": command})

    def env(self, **variables: str) -> Image:
        """Set environment variables."""
        new_env = self._env + tuple(variables.items())
        return self._with(_env=new_env)

    def copy(self, src: str, dst: str) -> Image:
        """Copy a file into the image."""
        new_files = self._files + ((src, dst),)
        return self._with(_files=new_files)

    def expose(self, port: int) -> Image:
        """Expose a port."""
        new_ports = self._ports + (port,)
        return self._with(_ports=new_ports)

    # ── Serialization ────────────────────────────────────────────────────

    def to_dict(self) -> Dict[str, Any]:
        """Serialize to a plain dict suitable for JSON."""
        d: Dict[str, Any] = {
            "os_type": self.os_type,
            "distro": self.distro,
            "version": self.version,
            "kind": self.kind,
            "layers": list(self._layers),
        }
        if self._env:
            d["env"] = dict(self._env)
        if self._ports:
            d["ports"] = list(self._ports)
        if self._files:
            d["files"] = [list(f) for f in self._files]
        if self._registry:
            d["registry"] = self._registry
        if self._agent_type:
            d["agent_type"] = self._agent_type
        return d

    def to_cloud_init(self) -> str:
        """Generate a cloud-init user-data script from the image layers."""
        lines = ["#!/bin/bash", "set -e"]
        for k, v in self._env:
            lines.append(f"export {k}={v!r}")
        for layer in self._layers:
            lt = layer["type"]
            if lt == "apt_install":
                pkgs = " ".join(layer["packages"])
                lines.append(f"apt-get update && apt-get install -y {pkgs}")
            elif lt == "brew_install":
                pkgs = " ".join(layer["packages"])
                lines.append(f"brew install {pkgs}")
            elif lt == "winget_install":
                for pkg in layer["packages"]:
                    lines.append(
                        f"winget install --accept-source-agreements --accept-package-agreements -e --id {pkg}"
                    )
            elif lt == "uv_install":
                pkgs = " ".join(layer["packages"])
                lines.append(f"uv add --directory ~/cua-server {pkgs}")
            elif lt == "choco_install":
                pkgs = " ".join(layer["packages"])
                lines.append(f"choco install -y {pkgs}")
            elif lt == "pip_install":
                pkgs = " ".join(layer["packages"])
                lines.append(f"pip install {pkgs}")
            elif lt == "apk_install":
                for apk in layer["packages"]:
                    lines.append(f"adb install {apk}")
            elif lt == "pwa_install":
                manifest_url = layer["manifest_url"]
                builder = layer.get("builder", "pwa2apk")
                if builder == "pwa2apk":
                    lines.append(
                        f"# pwa2apk: WebView APK (no Chrome dependency)\n"
                        f"if [ ! -d /tmp/pwa2apk ]; then git clone https://github.com/trycua/pwa2apk.git /tmp/pwa2apk; fi\n"
                        f"node /tmp/pwa2apk/src/cli.js '{manifest_url}' --output /tmp/pwa.apk\n"
                        f"adb install /tmp/pwa.apk"
                    )
                else:
                    lines.append(
                        f"# bubblewrap: Chrome TWA APK\n"
                        f"npm install -g @bubblewrap/cli 2>/dev/null || true\n"
                        f"_BWW_DIR=$(mktemp -d)\n"
                        f"(cd \"$_BWW_DIR\" && bubblewrap init --manifest '{manifest_url}' --directory . --skipPwaValidation && bubblewrap build --skipSigning)\n"
                        f'adb install "$_BWW_DIR/app-release-unsigned.apk"'
                    )
            elif lt == "run":
                lines.append(layer["command"])
        return "\n".join(lines) + "\n"

    def local_support(self):  # -> RuntimeSupport (lazy import avoids circular dep)
        """Check whether this image can run locally on the current host.

        Returns a :class:`~cua_sandbox.runtime.compat.RuntimeSupport` describing:

        - ``supported``  — runtime is available or auto-installable on this OS
        - ``hw_accel``   — hardware acceleration (HVF / KVM / Hyper-V) is available
        - ``runtime_installed`` — runtime binary found right now (no install needed)
        - ``auto_installable`` — SDK can install the runtime automatically
        - ``reason``     — human-readable explanation

        In tests, use the bundled helper instead of checking manually::

            from cua_sandbox.runtime.compat import skip_if_unsupported

            async def test_something():
                skip_if_unsupported(Image.macos())
                async with Sandbox.ephemeral(Image.macos(), local=True) as sb:
                    ...
        """
        from cua_sandbox.runtime.compat import (  # noqa: F401
            RuntimeSupport,
            check_local_support,
        )

        return check_local_support(self)

    def __repr__(self) -> str:
        reg = f", registry={self._registry!r}" if self._registry else ""
        return (
            f"Image({self.os_type}/{self.distro}:{self.version}, "
            f"kind={self.kind}, {len(self._layers)} layers{reg})"
        )


def registry_image(image: Image) -> Optional[str]:
    """The registry reference an image runs from.

    An explicit ``Image.from_registry(...)`` reference always wins; the
    built-in descriptors (``Image.linux()``, ``Image.windows()`` for 2022,
    ``Image.macos()``) are the canonical images (see :func:`canonical_image`).
    Other descriptors (custom distros, ``Image.windows("11")``) return ``None``.
    """
    if image._registry is not None:
        return image._registry
    if image.distro not in CANONICAL_DISTROS.get(image.os_type, ()):
        return None
    if image.os_type == "windows" and image.version not in CANONICAL_WINDOWS_VERSIONS:
        return None
    return canonical_image(image.os_type, image.version)


#: What each resolved variant means for :attr:`Image.kind`.
_VARIANT_KIND = {"rootfs": "container", "containerdisk": "vm", "lume": "vm"}


def resolve_image_kind(image: Image) -> Image:
    """Resolve an image's kind (and OS) with the one native resolver.

    Returns the image unchanged when its kind is set or it has no registry
    reference. Short refs are docker.io (``python:3.12-slim``); the registry
    is read with the docker/ghcr/ECR credential chain; a containerDisk runs
    as a VM (QEMU), a rootfs as a container, a Lume image on Lume. A tag the
    registry does not know (one only the local engine has) runs as a
    container. An image no local backend runs raises.
    Blocks while the registry is read.
    """
    if image.kind is not None:
        return image
    ref = registry_image(image)
    if ref is None:
        return image
    from cua_sandbox._sdk import native

    n = native()
    try:
        if image._secret is not None:
            # A private image: its credentials head the registry auth chain.
            resolved = n.resolve_image_with_secret(ref, "local", None, image._secret.native())
        else:
            resolved = n.resolve_image(ref, "local", None)
    except n.CuaError.NotFound:
        logger.debug("%s is not in a registry; running it as a local container image", ref)
        return image._with(kind="container")
    except n.CuaError.Unauthenticated as error:
        raise PermissionError(
            f"cannot read {ref}: {error}. Log in to its registry (`docker login`), "
            "or set CUA_REGISTRY_USERNAME/CUA_REGISTRY_PASSWORD"
        ) from error
    except n.CuaError.Unsupported as error:
        raise ValueError(str(error)) from error
    except n.CuaError as error:
        # Offline, or resolution switched off (CUA_IMAGE_RESOLVE=0): the
        # local backend decides from the reference (a container).
        logger.warning("could not resolve %s (%s); running it as a container", ref, error)
        return image._with(kind="container")
    kind = _VARIANT_KIND.get(resolved.variant, "container")
    os_type = image.os_type
    if resolved.os != "linux" or resolved.variant == "lume":
        os_type = resolved.os
    # Kept for Sandbox.image_info on runtimes that do not report it.
    return image._with(kind=kind, os_type=os_type, _resolved=ImageInfo._from_native(resolved))