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.

75.4 KB
Raw Blame
// SPDX-License-Identifier: FSL-1.1-MIT
// Copyright (c) 2026 Cua AI, Inc.

//! The app's command layer over the cua SDK, free of Tauri.
//!
//! Every Tauri command in [`crate::commands`] is a one-line call into
//! [`AppCore`], so the whole surface is testable (and drivable from an
//! integration harness) without a window, a webview or an `AppHandle`.
//!
//! - Spaces come from `cua-spaces` in-process: the registry lives in
//!   `~/.cua/spaces.json` (shared with `cua daemon`, the `cua` CLI and
//!   `cua daemon mcp`), and the primitives (files, streams, teleport,
//!   hotspot, agents) are SDK calls. No ssh, no rcdp CLI, no Python.
//! - The signed-in user ([`SessionHandle`], the device-authorization grant)
//!   drives the relay account and this device's enrollment. There is no
//!   other credential source: Cua Cloud has ended, so the app calls no Cua
//!   Cloud API.
//! - `cua daemon` is connected (or started) so CLI and MCP clients share
//!   Spaces with the app. Every Space's media tickets are safe in a URL, so
//!   the webview attaches to them directly.

use std::path::{Path, PathBuf};
use std::sync::atomic::{AtomicBool, Ordering};
use std::sync::{Arc, Mutex, RwLock};
use std::time::Duration;

use base64::Engine;
use cua_daemon::client::{DaemonAddress, DaemonClient};
use cua_sandbox_core::placement::{Kind, On, Runtime};
use cua_sandbox_core::settings::{Settings, Source};
use cua_sandbox_core::LocalRuntime;
use cua_spaces::files::SendFileOptions;
use cua_spaces::hotspot::HotspotOptions;
use cua_spaces::operator::OperatorDisplay;
use cua_spaces::{Provider, Space, SpaceCreate, SpaceInfo, Spaces};
use cua_spaces_ext::teleport::{
    AppSessions, ImportOptions, SpaceTeleport as _, TeleportManifest, TeleportScope,
};
use cua_spaces_ext::teleport_app::{SpaceAppTeleport as _, SpaceAppTeleportFacts as _};
use cua_spacesd_client::pb;
use serde::{Deserialize, Serialize};

use crate::auth::{Credentials, SessionHandle, Store};

/// Result type of every command: the error is the user-facing message.
pub type CmdResult<T> = Result<T, String>;

fn msg(e: impl std::fmt::Display) -> String {
    e.to_string()
}

/// POSIX single-quoting.
fn sh_quote(s: &str) -> String {
    format!("'{}'", s.replace('\'', "'\\''"))
}

/// The guest script that opens `cli` in an xterm on the Space's desktop,
/// with the cua tool bins first on PATH.
fn agent_terminal_script(title: &str, cli: &str) -> String {
    let inner = format!("PATH=\"$HOME/.cua/bin:$PATH\"; export PATH; exec {cli}");
    format!(
        "export DISPLAY=\"${{DISPLAY:-:1}}\"; exec xterm -T {} -e sh -c {}",
        sh_quote(title),
        sh_quote(&inner)
    )
}

/// Bounded wait for one Space's handshake while listing.
const LIST_PROBE: Duration = Duration::from_secs(3);
/// How long `cua daemon start` may take.
const DAEMON_START_BUDGET: Duration = Duration::from_secs(20);

// ---------------------------------------------------------------- config

/// How the app reaches `cua daemon`.
#[derive(Clone, Debug)]
pub enum DaemonMode {
    /// Never talk to a daemon (tests).
    Disabled,
    /// Connect through `<home>/daemon.json`; when nothing answers and
    /// `cua_bin` is set, run `<cua_bin> daemon start` once.
    Auto {
        /// The `cua` binary used to start the daemon.
        cua_bin: Option<PathBuf>,
    },
}

/// Everything [`AppCore`] is built from. [`CoreConfig::from_env`] is the
/// app; tests replace the pieces that would touch the host.
pub struct CoreConfig {
    /// `~/.cua` (or `$CUA_HOME`): registry, daemon discovery, control file.
    pub home: PathBuf,
    /// Where the signed-in user's session is persisted.
    pub token_store: Store,
    /// Local runtime (`cua-vmm`: containers, gVisor, QEMU, Lume).
    pub local_runtime: Option<Arc<dyn LocalRuntime>>,
    /// sandbox-core state directory; `None` shares the SDK default with
    /// the daemon and the CLI.
    pub state_dir: Option<PathBuf>,
    /// Teleport senders (real host in the app; `FakeHost` in tests).
    pub app_sessions: Arc<AppSessions>,
    /// Presenting Spaces on this desktop (the app's own windows).
    pub operator_display: Option<Arc<dyn OperatorDisplay>>,
    /// Where `download` lands.
    pub download_dir: Option<PathBuf>,
    /// spacesd handshake budget.
    pub probe_timeout: Duration,
    /// `cua daemon`.
    pub daemon: DaemonMode,
    /// Image for "Local" container Spaces.
    pub local_container_image: String,
    /// Image for "Local" macOS Spaces (Lume), when configured.
    pub local_macos_image: Option<String>,
    /// The cua.ai relay machines of the signed-in account appear in the
    /// roster as `relay:<id>`. `None`: the default relay
    /// (`CUA_RELAY_URL` or https://relay.cua.ai) with the app's session,
    /// once signed in. Tests pass a relay and tokens explicitly.
    pub relay: Option<cua_spaces::RelayAccount>,
    /// "Teleport an app…" app roots; `None` scans this machine's
    /// (`/Applications`, `~/Applications`). Tests pass fixture directories.
    pub teleport_app_roots: Option<Vec<PathBuf>>,
    /// Teleport recents file; `None` is `~/.cua/teleport-recents.json`.
    pub teleport_recents: Option<PathBuf>,
}

fn non_empty_env(name: &str) -> Option<String> {
    std::env::var(name)
        .ok()
        .map(|v| v.trim().to_string())
        .filter(|v| !v.is_empty())
}

/// `$CUA_HOME` or `~/.cua`.
pub fn cua_home() -> PathBuf {
    cua_daemon::cua_home()
}

/// The canonical Linux image (`CUA_IMAGE_LINUX` overrides it).
fn canonical_linux_image() -> String {
    use cua_image::canonical::{canonical_for, canonical_image, CanonicalOs};
    canonical_image("linux", None).unwrap_or_else(|_| canonical_for(CanonicalOs::Linux, None))
}

/// The `cua` binary: `$CUA_BIN`, a `cua` next to the app executable
/// (bundled sidecar), then `cua` on `PATH`.
pub fn find_cua_bin() -> Option<PathBuf> {
    if let Some(p) = non_empty_env("CUA_BIN").map(PathBuf::from) {
        if p.is_file() {
            return Some(p);
        }
    }
    if let Some(dir) = std::env::current_exe()
        .ok()
        .and_then(|e| e.parent().map(Path::to_path_buf))
    {
        let sidecar = dir.join("cua");
        if sidecar.is_file() {
            return Some(sidecar);
        }
    }
    let path = std::env::var_os("PATH")?;
    std::env::split_paths(&path)
        .map(|d| d.join("cua"))
        .find(|p| p.is_file())
}

impl CoreConfig {
    /// The app's configuration: real host, the signed-in user's session.
    pub fn from_env() -> Self {
        let home = cua_home();
        Self {
            // The credential store shared with the cua CLI and daemon; the
            // app's former session file moves into it.
            token_store: {
                let store = Store::from_env();
                if let Err(e) = store.migrate_legacy(&home) {
                    tracing::warn!("could not migrate the old Spaces session: {e}");
                }
                store
            },
            local_runtime: Some(Arc::new(cua_daemon::local::VmmLocal::default())),
            state_dir: None,
            app_sessions: Arc::new(AppSessions::builtin()),
            operator_display: None,
            download_dir: None,
            probe_timeout: Duration::from_secs(15),
            daemon: DaemonMode::Auto {
                cua_bin: find_cua_bin(),
            },
            // The canonical Linux image (`CUA_IMAGE_LINUX` overrides it); kind
            // `auto` picks its container rootfs variant.
            local_container_image: non_empty_env("CUA_SPACES_LOCAL_IMAGE")
                .unwrap_or_else(canonical_linux_image),
            local_macos_image: non_empty_env("CUA_SPACES_MACOS_IMAGE")
                .or_else(|| non_empty_env("CUA_LUME_GOLDEN_IMAGE"))
                .map(|i| {
                    if i.starts_with("lume:") {
                        i
                    } else {
                        format!("lume:{i}")
                    }
                }),
            relay: None,
            teleport_app_roots: None,
            teleport_recents: Some(home.join("teleport-recents.json")),
            home,
        }
    }

    /// A hermetic configuration rooted at `home`: no signed-in user, no
    /// local runtime, no daemon, fake teleport host. Tests adjust from here.
    pub fn hermetic(home: &Path) -> Self {
        Self {
            home: home.to_path_buf(),
            token_store: Store::File(home.join("no-user-session.json")),
            local_runtime: None,
            state_dir: Some(home.join("sandboxes")),
            app_sessions: Arc::new(AppSessions::with_host(Arc::new(
                cua_spaces_ext::teleport::providers::FakeHost::new().with_home(home),
            ))),
            operator_display: Some(Arc::new(cua_spaces::operator::NoDisplay)),
            download_dir: Some(home.join("downloads")),
            probe_timeout: Duration::from_secs(10),
            daemon: DaemonMode::Disabled,
            relay: None,
            local_container_image: "cua-e2e-local/linux:docker-local-arm64".into(),
            local_macos_image: None,
            teleport_app_roots: Some(vec![home.join("Applications")]),
            teleport_recents: Some(home.join("teleport-recents.json")),
        }
    }
}

// ------------------------------------------------------------- wire types

/// Whether a user is signed in (Settings and the sidebar show the account).
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize)]
#[serde(rename_all = "kebab-case")]
pub enum AuthMode {
    /// A signed-in user's device-grant session.
    User,
    /// Nobody is signed in.
    None,
}

/// `account_status`: the signed-in account. It reads the local session and
/// makes no network call.
#[derive(Clone, Debug, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct AccountStatus {
    /// A user is signed in.
    pub configured: bool,
    pub auth_mode: AuthMode,
    /// The signed-in user (email or subject), when the session names one.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub identity: Option<String>,
}

/// `daemon_status` / `ensure_daemon`.
#[derive(Clone, Debug, Default, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct DaemonStatus {
    pub connected: bool,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub version: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub socket_path: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub loopback_url: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub error: Option<String>,
}

/// `local_status`.
#[derive(Clone, Debug, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct LocalStatus {
    pub available: bool,
    pub backends: Vec<String>,
    pub container_image: String,
    pub macos_image: Option<String>,
    pub error: Option<String>,
    /// This Mac's architecture (`arm64`, `amd64`).
    pub host_arch: String,
    /// Free space where local Spaces are written and what is pulled (the
    /// New Space wizard's Resources step).
    pub storage: Option<cua_spaces_app_core::wizard::LocalStorage>,
}

/// The SDK's storage probe as the wizard env takes it.
fn wizard_storage(
    r: cua_daemon::storage::StorageReport,
) -> cua_spaces_app_core::wizard::LocalStorage {
    let vol = |v: Option<cua_daemon::storage::Volume>| {
        v.map(|v| cua_spaces_app_core::wizard::StorageVolume {
            available_bytes: v.available,
            total_bytes: v.total,
            name: v.name,
        })
    };
    cua_spaces_app_core::wizard::LocalStorage {
        reserve_bytes: r.reserve,
        lume: vol(r.lume),
        qemu: vol(r.qemu),
        container: vol(r.container),
        pulled: r.pulled,
        linux_runtime_download_bytes: r.linux_runtime_download_bytes,
    }
}

/// `arm64` / `amd64`, as the image catalog spells them (the app core's).
pub fn host_arch() -> String {
    cua_spaces_app_core::model::this_host_arch().into()
}

/// One registered Space as the switcher shows it.
#[derive(Clone, Debug, Serialize, PartialEq)]
#[serde(rename_all = "camelCase")]
pub struct SpaceRow {
    pub id: String,
    pub name: String,
    pub provider: Provider,
    pub spacesd_version: String,
    pub features: Vec<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub added_at: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub os: Option<String>,
    /// OS product or distribution ("Ubuntu"), for the OS icon.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub os_name: Option<String>,
    /// The full OS string ("Ubuntu 24.04.3 LTS").
    #[serde(skip_serializing_if = "Option::is_none")]
    pub os_pretty_name: Option<String>,
    /// The image it runs and its digest, when known.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub image: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub image_digest: Option<String>,
    /// `container` or `vm`, and the guest's CPU architecture, when known.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub kind: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub arch: Option<String>,
    pub reachable: bool,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub error: Option<String>,
    /// For a Space one of your machines provides: that machine's relay id
    /// and name.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub host: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub host_name: Option<String>,
    /// How it turns off and on (`suspend`, `stop`), and how cua last left
    /// it (`running`, `suspended`, `stopped`); absent when it cannot or
    /// unknown.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub power: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub power_state: Option<String>,
    /// For a Space in your cloud: the provider word, its account and
    /// region in words, and where Delete permanently can delete it
    /// (`here`, `host:<machine>`, `elsewhere`).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub cloud: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub cloud_place: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub cloud_delete: Option<String>,
    /// Why a local Space stopped without being asked to ("out of memory").
    #[serde(skip_serializing_if = "Option::is_none")]
    pub stop_reason: Option<String>,
}

/// The name to show for a registered Space: the app core's rule (a
/// container's 12-hex hostname defers to the name in the id).
pub fn display_name(id: &str, reported: &str) -> String {
    cua_spaces_app_core::spaces::name_of(id, reported)
}

impl SpaceRow {
    fn from_info(info: SpaceInfo) -> Self {
        // Renamed elsewhere (the Cua app, `cua spaces rename`): that name.
        let name = if info.display_name.is_empty() {
            display_name(&info.id, &info.name)
        } else {
            info.display_name.clone()
        };
        Self {
            id: info.id,
            name,
            provider: info.provider,
            spacesd_version: info.spacesd_version,
            features: info.features,
            os_name: (!info.os_name.is_empty()).then_some(info.os_name),
            os_pretty_name: (!info.os_pretty_name.is_empty()).then_some(info.os_pretty_name),
            image: (!info.image.is_empty()).then_some(info.image),
            image_digest: (!info.image_digest.is_empty()).then_some(info.image_digest),
            kind: (!info.kind.is_empty()).then_some(info.kind),
            arch: (!info.arch.is_empty()).then_some(info.arch),
            added_at: info.added_at,
            os: matches!(info.os.as_str(), "macos" | "windows" | "linux").then_some(info.os),
            reachable: false,
            error: None,
            host: (!info.host.is_empty()).then_some(info.host),
            host_name: (!info.host_name.is_empty()).then_some(info.host_name),
            power: (!info.power.is_empty()).then_some(info.power),
            power_state: (!info.power_state.is_empty()).then_some(info.power_state),
            cloud: (!info.cloud.is_empty()).then_some(info.cloud),
            cloud_place: (!info.cloud_place.is_empty()).then_some(info.cloud_place),
            cloud_delete: (!info.cloud_delete.is_empty()).then_some(info.cloud_delete),
            stop_reason: (!info.stop_reason.is_empty()).then_some(info.stop_reason),
        }
    }

    fn connected(info: SpaceInfo, space: &Space) -> Self {
        let mut row = Self::from_info(info);
        if let Some((family, name, pretty_name)) = space.reported_os() {
            row.os = (!family.is_empty()).then(|| family.to_string());
            row.os_name = (!name.is_empty()).then(|| name.to_string());
            row.os_pretty_name = (!pretty_name.is_empty()).then(|| pretty_name.to_string());
        }
        if let Some((image, digest)) = space.image() {
            row.image = Some(image.to_string());
            row.image_digest = (!digest.is_empty()).then(|| digest.to_string());
        }
        // The guest's own runtime and arch beat the record.
        let (kind, arch) = space.platform();
        if !kind.is_empty() {
            row.kind = Some(kind);
        }
        if !arch.is_empty() {
            row.arch = Some(arch);
        }
        row.reachable = true;
        // Live capabilities beat the registry snapshot.
        row.features = space
            .capabilities()
            .features
            .iter()
            .filter(|f| f.supported)
            .map(|f| f.name.clone())
            .collect();
        row
    }
}

/// `create_space` input: where (`on`), what (`kind`) and which engine
/// (`runtime`), as the SDK's placement model spells them. Every field is
/// optional: `on` defaults to the configured default location
/// (`default.on`), `kind` and `runtime` to `auto`.
#[derive(Clone, Debug, Default, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct SpaceCreateConfig {
    pub image: Option<String>,
    /// `local`, or a machine or cloud of your own (`aws`, `gcp`, `modal`).
    /// `cloud` (Cua Cloud) has ended and fails with the SDK's message.
    pub on: Option<String>,
    /// `auto`, `container` or `vm`.
    pub kind: Option<String>,
    /// `auto`, or an engine the location offers (local: gvisor, runc, qemu,
    /// lume).
    pub runtime: Option<String>,
    pub name: Option<String>,
    /// vCPUs.
    pub cpus: Option<u32>,
    /// Memory MB.
    pub memory_mb: Option<u64>,
    /// Local VMs only: grow the disk to this many GB.
    pub disk_gb: Option<u32>,
    /// Whether the image runs cua-spacesd (the shared image list says). None:
    /// the SDK decides from the image.
    pub spacesd: Option<bool>,
    /// Return a reachable registered Space in that location instead of
    /// creating one.
    pub reuse: Option<bool>,
    /// A GPU option of the runtime (`paravirtual`, from [`AppCore::gpu_support`]);
    /// `None`: no GPU.
    #[serde(default)]
    pub gpu: Option<String>,
}

/// What a cancelled create's error starts with (the SDK's `cancelled` tag),
/// so the webview tells a cancel from a failure.
pub const CANCELLED_PREFIX: &str = "cancelled: ";

/// A create's error for the webview: the SDK's message, prefixed with
/// [`CANCELLED_PREFIX`] when the create was cancelled.
pub fn create_error(e: &cua_spaces::Error) -> String {
    if e.tag() == "cancelled" {
        format!("{CANCELLED_PREFIX}{e}")
    } else {
        e.to_string()
    }
}

/// The wizard's GPU choices from the SDK's `gpu_support`: the first option
/// of each runtime that has one (a runtime with none gets no GPU row).
pub fn gpu_choices(
    support: &[cua_sandbox_core::gpu::GpuSupport],
) -> Vec<cua_spaces_app_core::wizard::GpuChoice> {
    support
        .iter()
        .filter_map(|s| {
            let o = s.options.first()?;
            Some(cua_spaces_app_core::wizard::GpuChoice {
                runtime: s.runtime.clone(),
                id: o.id.clone(),
                label: o.label.clone(),
                experimental: o.experimental,
                supported: o.supported,
                reason: Some(o.reason.clone()).filter(|r| !r.trim().is_empty()),
                learn_more: o.learn_more.clone(),
            })
        })
        .collect()
}

/// One of your machines that provides Spaces, as the wizard reads it.
pub fn space_host(h: cua_spaces::host_spaces::HostOffer) -> cua_spaces_app_core::wizard::SpaceHost {
    cua_spaces_app_core::wizard::SpaceHost {
        id: h.id,
        name: h.name,
        via: h.via,
        online: h.online,
        os: h.os,
        limits: h
            .limits
            .into_iter()
            .map(|l| cua_spaces_app_core::wizard::HostLimit {
                resource: l.resource,
                used: l.used,
                limit: l.limit,
                reason: l.reason,
            })
            .collect(),
        load: h.node.map(|n| cua_spaces_app_core::wizard::HostLoad {
            millicpus_total: n.millicpus_total,
            millicpus_free: n.millicpus_free,
            memory_total_mb: n.memory_total_mb,
            memory_free_mb: n.memory_free_mb,
            spaces: n.running.values().sum(),
            problem: n.problem,
            kinds: n.kinds,
        }),
    }
}

/// `get_default_location` / `set_default_location`.
#[derive(Clone, Debug, Serialize, PartialEq, Eq)]
#[serde(rename_all = "camelCase")]
pub struct DefaultLocation {
    /// `local` or `cloud` (or a registered provider).
    pub value: String,
    /// `env`, `config` or `default`.
    pub source: String,
    /// The environment variable, when `source` is `env` (the app cannot
    /// change it).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub env: Option<String>,
    /// The config file the value is stored in.
    pub path: String,
}

/// Splits a legacy engine prefix (`container:`, `vm:`, `lume:`) off an
/// image reference into the placement it meant.
fn split_image_prefix(image: &str) -> (&str, Option<Kind>, Option<Runtime>) {
    if let Some(rest) = image.strip_prefix("container:") {
        (rest, Some(Kind::Container), None)
    } else if let Some(rest) = image.strip_prefix("vm:") {
        (rest, Some(Kind::Vm), None)
    } else if let Some(rest) = image.strip_prefix("lume:") {
        (rest, Some(Kind::Vm), Some(Runtime::Lume))
    } else {
        (image, None, None)
    }
}

/// What to stream.
#[derive(Clone, Debug, Deserialize, PartialEq)]
#[serde(tag = "kind", rename_all = "camelCase")]
pub enum StreamTargetArg {
    /// A display (`None` = primary).
    #[serde(rename_all = "camelCase")]
    Display { display_id: Option<String> },
    /// One window.
    #[serde(rename_all = "camelCase")]
    Window { window_id: String },
}

/// Stream options from the webview.
#[derive(Clone, Debug, Default, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct StreamOpts {
    pub max_fps: Option<u32>,
    pub max_dimension: Option<u32>,
    pub audio: Option<bool>,
    pub codecs: Option<Vec<String>>,
    /// `view_only`, `background_only` or `allow_activation` (default).
    pub policy: Option<String>,
    pub geometry_control: Option<bool>,
}

/// A media ticket the webview attaches to.
#[derive(Clone, Debug, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct StreamTicketInfo {
    pub space_id: String,
    pub media_session_id: String,
    pub ws_url: String,
    pub ticket: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub ticket_expires_at: Option<String>,
    pub codec: String,
    pub wire_version: u32,
    pub frame_size: [u32; 2],
    /// Always `direct`: the spacesd ticket URL, safe in a URL. (`daemon`
    /// named the loopback bridge Cua Cloud streams needed.)
    pub via: &'static str,
    pub audio: bool,
}

/// A remote window (the picker's "This Mac" tab).
#[derive(Clone, Debug, Serialize, PartialEq)]
#[serde(rename_all = "camelCase")]
pub struct RemoteWindow {
    pub id: String,
    pub app_name: String,
    pub title: String,
    pub visible: bool,
    pub app_id: String,
    pub target_epoch: u64,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub width_px: Option<u32>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub height_px: Option<u32>,
    /// Owning process (the SDK's app icon lookup), when known.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub pid: Option<u32>,
}

/// One window's app, for `space_app_icons`.
#[derive(Clone, Debug, Default, Deserialize, PartialEq)]
#[serde(rename_all = "camelCase")]
pub struct AppIconRequest {
    pub app_name: String,
    #[serde(default)]
    pub app_id: String,
    #[serde(default)]
    pub pid: u32,
}

/// The primary display's size (the Stream section's "Desktop (W×H)").
#[derive(Clone, Copy, Debug, Serialize, PartialEq)]
#[serde(rename_all = "camelCase")]
pub struct DisplaySize {
    pub width_px: u32,
    pub height_px: u32,
}

/// One file landed in a Space (`send_files_to_space`).
#[derive(Clone, Debug, Serialize, PartialEq)]
#[serde(rename_all = "camelCase")]
pub struct SentFile {
    pub name: String,
    pub dest: String,
    pub bytes: u64,
    pub sha256: String,
}

/// Consent-sheet item (snake_case: the webview's `ManifestItem`).
#[derive(Clone, Debug, Serialize, PartialEq)]
pub struct ManifestItem {
    pub label: String,
    pub rel_path: String,
    pub est_bytes: u64,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub count: Option<u64>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub count_noun: Option<String>,
    pub sensitive: bool,
    pub default_checked: bool,
}

/// Consent-sheet manifest (the webview's `TransferManifest`).
#[derive(Clone, Debug, Serialize, PartialEq)]
pub struct TransferManifest {
    pub provider_id: String,
    pub app_display_name: String,
    pub scope: &'static str,
    pub items: Vec<ManifestItem>,
    pub total_est_bytes: u64,
    pub notes: Vec<String>,
    pub supports_hotspot: bool,
}

impl TransferManifest {
    fn from_sdk(m: &TeleportManifest) -> Self {
        Self {
            provider_id: m.app.clone(),
            app_display_name: m.display_name.clone(),
            scope: match m.scope {
                TeleportScope::Full => "full_profile",
                TeleportScope::Tabs => "tabs_only",
            },
            items: m
                .items
                .iter()
                .map(|i| ManifestItem {
                    label: i.label.clone(),
                    rel_path: i.relative_path.clone(),
                    est_bytes: i.estimated_bytes,
                    count: i.count,
                    count_noun: i.count_noun.clone(),
                    sensitive: i.is_sensitive,
                    default_checked: i.is_checked_by_default,
                })
                .collect(),
            total_est_bytes: m.total_estimated_bytes,
            notes: m.notes.clone(),
            // Browsers can route through the hotspot (SOCKS proxy).
            supports_hotspot: matches!(m.app.as_str(), "chrome" | "google-chrome" | "firefox"),
        }
    }
}

/// `teleport_push` result (the webview's `TeleportResult`).
#[derive(Clone, Debug, Serialize, PartialEq)]
pub struct TeleportResult {
    pub ok: bool,
    pub provider_id: String,
    pub launched: bool,
    pub pid: Option<u32>,
    pub imported: Vec<String>,
    pub skipped: Vec<String>,
}

/// `hotspot_*`.
#[derive(Clone, Debug, Serialize, PartialEq)]
#[serde(rename_all = "camelCase")]
pub struct HotspotStatus {
    pub active: bool,
    pub space_id: Option<String>,
}

// ------------------------------------------------------------------ core

/// The app's SDK state. Cheap to share (`Arc<AppCore>`).
pub struct AppCore {
    home: PathBuf,
    session: Arc<SessionHandle>,
    signed_in: Arc<AtomicBool>,
    spaces: RwLock<Spaces>,
    app_sessions: Arc<AppSessions>,
    teleport_app_roots: Option<Vec<PathBuf>>,
    teleport_recents: Option<PathBuf>,
    daemon_mode: DaemonMode,
    daemon: tokio::sync::Mutex<Option<DaemonClient>>,
    hotspot: Mutex<Option<String>>,
    local_container_image: String,
    local_macos_image: Option<String>,
    has_local: bool,
    // Kept for rebuilding `spaces` after sign-in / sign-out.
    rebuild: SpacesParts,
    /// This device on the relay (one per identity, so its cached session is
    /// shared by listing, connecting and the Devices page).
    device: Mutex<Option<Arc<cua_host::DeviceAuth>>>,
}

struct SpacesParts {
    local_runtime: Option<Arc<dyn LocalRuntime>>,
    state_dir: Option<PathBuf>,
    operator_display: Option<Arc<dyn OperatorDisplay>>,
    download_dir: Option<PathBuf>,
    probe_timeout: Duration,
    relay: Option<cua_spaces::RelayAccount>,
    /// Where this device's relay key lives (the session's vault).
    device_keys: Store,
}

impl AppCore {
    /// Builds the core. No I/O beyond reading the stored user session.
    pub fn new(cfg: CoreConfig) -> Arc<Self> {
        let device_keys = cfg.token_store.clone();
        let (session, restored) = SessionHandle::new(cfg.token_store);
        let signed_in = Arc::new(AtomicBool::new(restored));
        let rebuild = SpacesParts {
            local_runtime: cfg.local_runtime,
            state_dir: cfg.state_dir,
            operator_display: cfg.operator_display,
            download_dir: cfg.download_dir,
            probe_timeout: cfg.probe_timeout,
            relay: cfg.relay,
            device_keys,
        };
        let core = Self {
            has_local: rebuild.local_runtime.is_some(),
            spaces: RwLock::new(Spaces::builder().build()),
            home: cfg.home,
            session,
            signed_in,
            app_sessions: cfg.app_sessions,
            teleport_app_roots: cfg.teleport_app_roots,
            teleport_recents: cfg.teleport_recents,
            daemon_mode: cfg.daemon,
            daemon: tokio::sync::Mutex::new(None),
            hotspot: Mutex::new(None),
            local_container_image: cfg.local_container_image,
            local_macos_image: cfg.local_macos_image,
            rebuild,
            device: Mutex::new(None),
        };
        let spaces = core.build_spaces();
        *core.spaces.write().unwrap_or_else(|p| p.into_inner()) = spaces;
        Arc::new(core)
    }

    fn build_spaces(&self) -> Spaces {
        let p = &self.rebuild;
        // The Cua Spaces extensions: teleport over this app's providers, the
        // Cua Volume tools and persistent agents over the local drive.
        let mut b = cua_spaces_ext::register(
            Spaces::builder()
                .home(&self.home)
                .probe_timeout(p.probe_timeout),
            cua_volume::Drive::open_local(&self.home),
            Some(self.app_sessions.clone()),
        );
        let mut sandboxes = cua_sandbox_core::Sandboxes::builder();
        if let Some(l) = &p.local_runtime {
            b = b.local_runtime(l.clone());
            sandboxes = sandboxes.local(l.clone());
        }
        if let Some(d) = &p.state_dir {
            sandboxes = sandboxes.state_dir(d);
        }
        b = b.sandboxes(sandboxes.build());
        if let Some(d) = &p.operator_display {
            b = b.operator_display(d.clone());
        } else {
            b = b.operator_display(Arc::new(cua_spaces::operator::ControlServerDisplay::new(
                self.home.join("spaces-control.json"),
            )));
        }
        if let Some(d) = &p.download_dir {
            b = b.download_dir(d);
        }
        // Relay machines of the signed-in account (`relay:<id>`).
        if let Some(relay) = &p.relay {
            b = b.relay(relay.clone());
        } else if self.signed_in.load(Ordering::Relaxed) {
            let url = cua_host::relay_url_from_env();
            let mut account = cua_spaces::RelayAccount::new(url, self.session_tokens());
            // This device's enrollment (key in the session's vault, shared
            // with the cua CLI and daemon): the relay needs its session.
            if let Some(device) = self.device_auth() {
                account = account.with_device(device);
            }
            b = b.relay(account);
        }
        b = b.share_consent(Arc::new(crate::share::AppShareConsent));
        b.build()
    }

    fn session_tokens(&self) -> Arc<dyn cua_host::AccountTokens> {
        Arc::new(crate::host_backend::SessionTokens(self.session.clone()))
    }

    /// This device on the default relay as the signed-in account (its key
    /// in the session's vault), made once per identity.
    fn device_auth(&self) -> Option<Arc<cua_host::DeviceAuth>> {
        let mut slot = self.device.lock().unwrap_or_else(|p| p.into_inner());
        if slot.is_none() {
            *slot = cua_host::DeviceAuth::new(
                &cua_host::relay_url_from_env(),
                self.session_tokens(),
                Arc::new(self.rebuild.device_keys.clone()),
                cua_host::device_name(),
            )
            .map(Arc::new)
            .ok();
        }
        slot.clone()
    }

    /// The Devices page's relay calls: the configured relay's device, else
    /// this device on the default relay once signed in.
    pub fn devices(&self) -> Result<crate::devices::DevicesService, String> {
        if let Some(relay) = &self.rebuild.relay {
            return relay
                .device
                .clone()
                .map(|d| crate::devices::DevicesService::new(d, relay.tokens.clone()))
                .ok_or_else(|| "this relay has no device".to_string());
        }
        if !self.signed_in.load(Ordering::Relaxed) {
            return Err("sign in to Cua to see your devices".into());
        }
        let device = self
            .device_auth()
            .ok_or_else(|| "the relay URL is invalid".to_string())?;
        Ok(crate::devices::DevicesService::new(
            device,
            self.session_tokens(),
        ))
    }

    /// The live Spaces handle.
    pub fn spaces(&self) -> Spaces {
        self.spaces
            .read()
            .unwrap_or_else(|p| p.into_inner())
            .clone()
    }

    /// `~/.cua` this core uses.
    pub fn home(&self) -> &Path {
        &self.home
    }

    /// Rebuilds the Spaces handle after the signed-in identity changed (the
    /// relay account follows it). Hotspots stop.
    async fn identity_changed(&self) {
        let old = self.spaces();
        let _ = old.hotspot_stop(None).await;
        *self.hotspot.lock().unwrap_or_else(|p| p.into_inner()) = None;
        // A new identity gets a fresh device session.
        *self.device.lock().unwrap_or_else(|p| p.into_inner()) = None;
        let fresh = self.build_spaces();
        *self.spaces.write().unwrap_or_else(|p| p.into_inner()) = fresh;
    }

    // --------------------------------------------------------- account

    /// `account_status`: who is signed in. Reads the local session; no
    /// network call.
    pub async fn account_status(&self) -> AccountStatus {
        let signed_in = self.signed_in.load(Ordering::Relaxed);
        let identity = if signed_in {
            self.session.identity().await
        } else {
            None
        };
        AccountStatus {
            configured: signed_in,
            auth_mode: if signed_in {
                AuthMode::User
            } else {
                AuthMode::None
            },
            identity,
        }
    }

    /// The shared user session (device-grant sign-in drives it).
    pub fn session(&self) -> Arc<SessionHandle> {
        self.session.clone()
    }

    /// Installs a freshly approved user session.
    pub async fn install_user_session(&self, c: Credentials) -> CmdResult<Option<String>> {
        let identity = self.session.install(c).await?;
        self.signed_in.store(true, Ordering::Relaxed);
        self.identity_changed().await;
        self.sync_usage_link().await;
        Ok(identity)
    }

    /// Links usage data to the signed-in account when the Spaces API offers
    /// an account id (CUA-1881); none unlinks. Best effort: offline or
    /// signed out, nothing changes. Called at launch and after a sign-in.
    pub async fn sync_usage_link(&self) {
        crate::telemetry::sync_account(&self.session).await;
    }

    /// Signs out.
    pub async fn sign_out(&self) {
        // Usage data goes back to a new anonymous install id.
        let _ = cua_telemetry::global().forget_account();
        self.session.clear().await;
        self.signed_in.store(false, Ordering::Relaxed);
        self.identity_changed().await;
    }

    // ---------------------------------------------------------- daemon

    fn discovered_address(&self) -> DaemonAddress {
        match cua_daemon::Discovery::read(&self.home.join("daemon.json")) {
            Some(d) if cfg!(unix) && d.socket_path.is_some() => {
                DaemonAddress::Socket(PathBuf::from(d.socket_path.unwrap_or_default()))
            }
            Some(cua_daemon::Discovery {
                loopback_url: Some(url),
                token: Some(token),
                ..
            }) => DaemonAddress::Url { url, token },
            _ => DaemonAddress::Socket(self.home.join("cua.sock")),
        }
    }

    async fn try_daemon(&self) -> Option<DaemonClient> {
        let client = DaemonClient::new(self.discovered_address()).ok()?;
        tokio::time::timeout(Duration::from_secs(3), client.info())
            .await
            .ok()?
            .ok()?;
        Some(client)
    }

    /// A connected daemon client; starts `cua daemon` when allowed.
    pub async fn daemon(&self, start: bool) -> CmdResult<DaemonClient> {
        let mut slot = self.daemon.lock().await;
        if let Some(c) = slot.as_ref() {
            if tokio::time::timeout(Duration::from_secs(3), c.info())
                .await
                .is_ok_and(|r| r.is_ok())
            {
                return Ok(c.clone());
            }
            *slot = None;
        }
        let cua_bin = match &self.daemon_mode {
            DaemonMode::Disabled => return Err("the cua daemon is disabled in this build".into()),
            DaemonMode::Auto { cua_bin } => cua_bin.clone(),
        };
        if let Some(c) = self.try_daemon().await {
            *slot = Some(c.clone());
            return Ok(c);
        }
        if !start {
            return Err(cua_daemon::DAEMON_NOT_RUNNING.into());
        }
        let bin = cua_bin.ok_or(
            "the cua daemon is not running and no `cua` binary was found (set CUA_BIN or put \
             `cua` on PATH)",
        )?;
        let home = self.home.clone();
        let status = tokio::time::timeout(
            DAEMON_START_BUDGET,
            tokio::process::Command::new(&bin)
                .args(["daemon", "start"])
                .env("CUA_HOME", &home)
                .stdin(std::process::Stdio::null())
                .stdout(std::process::Stdio::null())
                .stderr(std::process::Stdio::piped())
                .output(),
        )
        .await
        .map_err(|_| format!("`{} daemon start` timed out", bin.display()))?
        .map_err(|e| format!("could not run {}: {e}", bin.display()))?;
        if !status.status.success() {
            return Err(format!(
                "`cua daemon start` failed: {}",
                String::from_utf8_lossy(&status.stderr).trim()
            ));
        }
        let c = self
            .try_daemon()
            .await
            .ok_or("the cua daemon started but does not answer")?;
        *slot = Some(c.clone());
        Ok(c)
    }

    /// `daemon_status` (`start` = `ensure_daemon`).
    pub async fn daemon_status(&self, start: bool) -> DaemonStatus {
        match self.daemon(start).await {
            Ok(c) => match c.info().await {
                Ok(info) => DaemonStatus {
                    connected: true,
                    version: Some(info.version),
                    socket_path: Some(info.socket_path).filter(|s| !s.is_empty()),
                    loopback_url: Some(info.loopback_url).filter(|s| !s.is_empty()),
                    error: None,
                },
                Err(e) => DaemonStatus {
                    error: Some(e.to_string()),
                    ..Default::default()
                },
            },
            Err(e) => DaemonStatus {
                error: Some(e),
                ..Default::default()
            },
        }
    }

    // ----------------------------------------------------------- local

    /// `local_status`: which local backends are usable (read-only probe).
    pub async fn local_status(&self) -> LocalStatus {
        if !self.has_local {
            return LocalStatus {
                available: false,
                backends: vec![],
                container_image: self.local_container_image.clone(),
                macos_image: self.local_macos_image.clone(),
                error: Some("no local runtime in this build".into()),
                host_arch: host_arch(),
                storage: None,
            };
        }
        let (report, storage) = tokio::join!(
            cua_daemon::local::doctor_report(),
            cua_daemon::storage::storage_report()
        );
        let backends: Vec<String> = report
            .backends
            .iter()
            .filter(|b| b.ready)
            .map(|b| format!("{:?}", b.backend).to_ascii_lowercase())
            .collect();
        LocalStatus {
            available: !backends.is_empty(),
            error: backends
                .is_empty()
                .then(|| "no local runtime is ready (run `cua runtime doctor`)".to_string()),
            backends,
            container_image: self.local_container_image.clone(),
            macos_image: self.local_macos_image.clone(),
            host_arch: host_arch(),
            storage: Some(wizard_storage(storage)),
        }
    }

    // ---------------------------------------------------------- roster

    /// Every registered Space, each probed for at most [`LIST_PROBE`].
    pub async fn list_spaces(&self) -> CmdResult<Vec<SpaceRow>> {
        let spaces = self.spaces();
        let infos = spaces.list_all().await.map_err(msg)?;
        let rows = futures_util::future::join_all(infos.into_iter().map(|info| {
            let spaces = spaces.clone();
            async move {
                match tokio::time::timeout(LIST_PROBE, spaces.space(&info.id)).await {
                    Ok(Ok(space)) => SpaceRow::connected(info, &space),
                    Ok(Err(e)) => SpaceRow {
                        error: Some(e.to_string()),
                        ..SpaceRow::from_info(info)
                    },
                    Err(_) => SpaceRow {
                        error: Some("did not answer within 3 s".into()),
                        ..SpaceRow::from_info(info)
                    },
                }
            }
        }))
        .await;
        Ok(rows)
    }

    /// One registered Space, connected (the viewer reads its features).
    pub async fn space_info(&self, space: &str) -> CmdResult<SpaceRow> {
        let spaces = self.spaces();
        let id = spaces.resolve(space).map_err(msg)?.to_string();
        let info = spaces
            .list()
            .map_err(msg)?
            .into_iter()
            .find(|i| i.id == id)
            .ok_or_else(|| format!("{id} is not registered"))?;
        Ok(self.row(info).await)
    }

    async fn row(&self, info: SpaceInfo) -> SpaceRow {
        match self.spaces().space(&info.id).await {
            Ok(s) => SpaceRow::connected(info, &s),
            Err(e) => SpaceRow {
                error: Some(e.to_string()),
                ..SpaceRow::from_info(info)
            },
        }
    }

    /// "Add Space by address".
    pub async fn add_space(
        &self,
        url: &str,
        token: Option<String>,
        name: Option<String>,
    ) -> CmdResult<SpaceRow> {
        let token = token.filter(|t| !t.trim().is_empty());
        let name = name.filter(|n| !n.trim().is_empty());
        let info = self.spaces().add(url, token, name).await.map_err(msg)?;
        Ok(self.row(info).await)
    }

    /// The settings this core reads: `<home>/config.toml` and the process
    /// environment (`CUA_DEFAULT_ON`, ...).
    fn settings(&self) -> CmdResult<Settings> {
        Settings::load_with(self.home.join("config.toml"), |k| std::env::var(k).ok()).map_err(msg)
    }

    /// Where new Spaces go when the create names no location.
    pub fn default_location(&self) -> CmdResult<DefaultLocation> {
        let settings = self.settings()?;
        let (on, source) = settings.default_on().map_err(msg)?;
        Ok(DefaultLocation {
            value: on.to_string(),
            source: source.kind().into(),
            env: match source {
                Source::Env(v) => Some(v.to_string()),
                _ => None,
            },
            path: settings.path().display().to_string(),
        })
    }

    /// Stores the default location (`local` or `cloud`) in
    /// `<home>/config.toml`, as `cua config set default.on` does. An
    /// environment override still wins; the result says so.
    pub fn set_default_location(&self, on: &str) -> CmdResult<DefaultLocation> {
        let parsed = On::parse(on).map_err(msg)?;
        if parsed.is_existing_machine() {
            return Err(format!(
                "{parsed} names one computer; the default location is local or a cloud of yours"
            ));
        }
        let mut settings = self.settings()?;
        let key = cua_sandbox_core::settings::key("default.on").map_err(msg)?;
        settings.set(key, &parsed.to_string()).map_err(msg)?;
        self.default_location()
    }

    /// Creates a Space where `cfg.on` says (the default location when
    /// unset) and blocks until its spacesd answers. Invalid location / kind
    /// / runtime combinations come back as the SDK's placement error, which
    /// lists the valid values.
    pub async fn create_space(&self, cfg: SpaceCreateConfig) -> CmdResult<SpaceRow> {
        self.create_space_with_progress(cfg, None, None).await
    }

    /// [`Self::create_space`], reporting the SDK's create progress (pulling,
    /// booting, waiting for cua-spacesd, connecting) to `progress`.
    /// `create_id` (the webview's pending row id) is what
    /// [`Self::cancel_create`] finds it by; a cancelled create's error
    /// starts with [`CANCELLED_PREFIX`].
    pub async fn create_space_with_progress(
        &self,
        cfg: SpaceCreateConfig,
        progress: Option<cua_spaces::ProgressSink>,
        create_id: Option<String>,
    ) -> CmdResult<SpaceRow> {
        let text = |v: Option<String>| v.map(|s| s.trim().to_string()).filter(|s| !s.is_empty());
        let on = match text(cfg.on) {
            Some(on) => On::parse(&on).map_err(msg)?,
            None => self.settings()?.default_on().map_err(msg)?.0,
        };
        let mut kind = match text(cfg.kind) {
            Some(k) => Kind::parse(&k).map_err(msg)?,
            None => Kind::Auto,
        };
        let mut runtime = match text(cfg.runtime) {
            Some(r) => Runtime::parse(&r).map_err(msg)?,
            None => Runtime::Auto,
        };
        let image = match (text(cfg.image), &on) {
            (Some(i), _) => Some(i),
            (None, On::Local) if runtime == Runtime::Lume => {
                Some(self.local_macos_image.clone().ok_or(
                    "no macOS Space image is configured (set CUA_SPACES_MACOS_IMAGE to a Lume \
                     image with cua-spacesd, e.g. the golden built by \
                     scripts/build-macos-golden.sh)",
                )?)
            }
            (None, On::Local) if kind != Kind::Vm => Some(self.local_container_image.clone()),
            _ => None,
        };
        let image = image.map(|i| {
            let (bare, k, r) = split_image_prefix(&i);
            if kind == Kind::Auto {
                kind = k.unwrap_or(Kind::Auto);
            }
            if runtime == Runtime::Auto {
                runtime = r.unwrap_or(Runtime::Auto);
            }
            bare.to_string()
        });
        let local = on == On::Local;
        let info = self
            .spaces()
            .create(SpaceCreate {
                on: Some(on),
                image,
                kind,
                runtime,
                name: text(cfg.name),
                cpus: cfg.cpus,
                memory_mb: cfg.memory_mb,
                disk_gb: if local { cfg.disk_gb } else { None },
                wait: Some(true),
                reuse: cfg.reuse.unwrap_or(false),
                spacesd: cfg.spacesd,
                progress,
                create_id: text(create_id),
                gpu: text(cfg.gpu),
                ..Default::default()
            })
            .await
            .map_err(|e| create_error(&e))?
            .ready()
            .map_err(|p| format!("{} is still starting", p.id))?;
        Ok(self.row(info).await)
    }

    /// Cancels a create still running, by the `create_id` it was started
    /// with (or the Space's id or name). Returns once what it made is
    /// removed; idempotent (`not_creating` when nothing is in flight).
    pub async fn cancel_create(&self, key: &str) -> CmdResult<cua_spaces::CancelOutcome> {
        self.spaces().cancel_create(key).await.map_err(msg)
    }

    /// The New Space wizard's GPU choices on this machine: the first GPU
    /// option of each local runtime that has one.
    pub async fn gpu_support(&self) -> Vec<cua_spaces_app_core::wizard::GpuChoice> {
        gpu_choices(&self.spaces().gpu_support(&On::Local).await)
    }

    /// Your machines that provide Spaces (`WizardEnv.hosts`, the New Space
    /// "Run on" menu); none when they cannot be listed.
    pub async fn list_hosts(&self) -> Vec<cua_spaces_app_core::wizard::SpaceHost> {
        self.spaces()
            .hosts()
            .await
            .unwrap_or_default()
            .into_iter()
            .map(space_host)
            .collect()
    }

    /// Deletes a Space the app created (its instance is deleted). A Space
    /// added by address is only forgotten; a legacy Cua Cloud Space answers
    /// the ended message (use [`Self::remove_space`] to drop it).
    pub async fn delete_space(&self, space: &str) -> CmdResult<String> {
        let spaces = self.spaces();
        let id = spaces.resolve(space).map_err(msg)?.to_string();
        self.forget_hotspot(&id);
        spaces.delete(&id).await.map_err(msg)
    }

    /// Turns a Space off (`on` false: suspended or stopped, as its provider
    /// can) or on again. A hotspot on it ends when it goes off.
    pub async fn set_space_power(
        &self,
        space: &str,
        on: bool,
    ) -> CmdResult<cua_spaces::SpacePower> {
        let spaces = self.spaces();
        let id = spaces.resolve(space).map_err(msg)?.to_string();
        if on {
            spaces.start(&id).await.map_err(msg)
        } else {
            self.forget_hotspot(&id);
            spaces.stop(&id).await.map_err(msg)
        }
    }

    /// Unregisters without touching the sandbox.
    pub async fn remove_space(&self, space: &str) -> CmdResult<()> {
        let spaces = self.spaces();
        let id = spaces.resolve(space).map_err(msg)?.to_string();
        self.forget_hotspot(&id);
        spaces.remove(&id).await.map(drop).map_err(msg)
    }

    async fn space(&self, space: &str) -> CmdResult<Space> {
        self.spaces().space(space).await.map_err(msg)
    }

    // ------------------------------------------------------- space ops

    /// A PNG/JPEG `data:` URL of the primary display.
    pub async fn space_screenshot(
        &self,
        space: &str,
        max_dimension: Option<u32>,
    ) -> CmdResult<String> {
        let s = self.space(space).await?;
        let shot = s
            .spacesd()
            .map_err(msg)?
            .screenshot(cua_spacesd_client::ScreenshotOptions {
                max_dimension: max_dimension.unwrap_or(1280),
                ..Default::default()
            })
            .await
            .map_err(msg)?;
        Ok(data_url(shot.format, &shot.image))
    }

    /// Sends host files into `~/Downloads[/subdir]`, sha256-verified by the
    /// Space.
    pub async fn send_files(
        &self,
        space: &str,
        paths: &[String],
        subdir: Option<String>,
    ) -> CmdResult<Vec<SentFile>> {
        if paths.is_empty() {
            return Err("nothing to send".into());
        }
        let s = self.space(space).await?;
        let mut out = Vec::new();
        for p in paths {
            let report = s
                .send_file(
                    Path::new(p),
                    SendFileOptions {
                        subdir: subdir.clone().unwrap_or_default(),
                        ..Default::default()
                    },
                )
                .await
                .map_err(msg)?;
            for f in report.files {
                out.push(SentFile {
                    name: Path::new(&f.path)
                        .file_name()
                        .map(|n| n.to_string_lossy().into_owned())
                        .unwrap_or_default(),
                    dest: f.path,
                    bytes: f.size,
                    sha256: f.sha256,
                });
            }
        }
        Ok(out)
    }

    /// The Space's windows.
    pub async fn list_remote_windows(&self, space: &str) -> CmdResult<Vec<RemoteWindow>> {
        let s = self.space(space).await?;
        let windows = s.windows(None).await.map_err(msg)?;
        Ok(windows
            .into_iter()
            .map(|w| RemoteWindow {
                width_px: (w.bounds[2] > 0.0).then_some(w.bounds[2].round() as u32),
                height_px: (w.bounds[3] > 0.0).then_some(w.bounds[3].round() as u32),
                id: w.window_id,
                app_name: w.app_name.clone(),
                title: w.title,
                visible: w.on_screen,
                app_id: if w.app_id.is_empty() {
                    w.app_name.to_ascii_lowercase().replace(' ', "-")
                } else {
                    w.app_id
                },
                target_epoch: w.epoch,
                pid: (w.pid > 0).then_some(w.pid),
            })
            .collect())
    }

    /// Processor, memory and storage use now (the app core's `SpaceUsage`
    /// shape).
    pub async fn space_usage(&self, space: &str) -> CmdResult<serde_json::Value> {
        let s = self.space(space).await?;
        let u = s.usage().await.map_err(msg)?;
        Ok(serde_json::json!({
            "cpuCount": u.cpu_count,
            "cpuPercent": u.cpu_percent,
            "loadAverage1m": u.load_average_1m,
            "memoryUsed": u.memory_used,
            "memoryTotal": u.memory_total,
            "memoryLimited": u.memory_limited,
            "diskUsed": u.disk_used,
            "diskTotal": u.disk_total,
            "diskLimited": u.disk_limited,
        }))
    }

    /// The Space's primary display size, from its display list.
    pub async fn space_primary_display(&self, space: &str) -> CmdResult<Option<DisplaySize>> {
        let s = self.space(space).await?;
        let displays = s.displays().await.map_err(msg)?;
        Ok(displays
            .first()
            .filter(|d| d.width_px > 0 && d.height_px > 0)
            .map(|d| DisplaySize {
                width_px: d.width_px,
                height_px: d.height_px,
            }))
    }

    /// The icon the Space's desktop shows for an app, as a `data:` URL, or
    /// `None` (see [`Core::space_app_icons`]).
    pub async fn space_app_icon(
        &self,
        space: &str,
        app_name: &str,
        app_id: &str,
        pid: u32,
    ) -> CmdResult<Option<String>> {
        let request = AppIconRequest {
            app_name: app_name.into(),
            app_id: app_id.into(),
            pid,
        };
        Ok(self
            .space_app_icons(space, vec![request])
            .await?
            .pop()
            .flatten())
    }

    /// Icons for many windows' apps (the SDK's `Space::app_icons`, through
    /// its one icon cache) as `data:` URLs, in request order.
    pub async fn space_app_icons(
        &self,
        space: &str,
        requests: Vec<AppIconRequest>,
    ) -> CmdResult<Vec<Option<String>>> {
        let s = self.space(space).await?;
        let requests: Vec<cua_spaces::IconRequest> = requests
            .into_iter()
            .map(|r| cua_spaces::IconRequest {
                app_name: r.app_name,
                app_id: r.app_id,
                pid: r.pid,
            })
            .collect();
        let icons = s.app_icons(&requests).await.map_err(msg)?;
        Ok(icons
            .into_iter()
            .map(|i| {
                i.map(|i| {
                    format!(
                        "data:{};base64,{}",
                        i.content_type,
                        base64::engine::general_purpose::STANDARD.encode(&i.bytes)
                    )
                })
            })
            .collect())
    }

    /// A small capture of one remote window (the SDK's
    /// `Space::window_thumbnail`, reused for a few seconds), or `None`.
    pub async fn remote_window_thumbnail(
        &self,
        space: &str,
        window_id: &str,
        epoch: u64,
    ) -> CmdResult<Option<String>> {
        let s = self.space(space).await?;
        let jpeg = s
            .window_thumbnail(window_id, epoch, 480)
            .await
            .ok()
            .flatten();
        Ok(jpeg.map(|b| data_url(pb::ImageFormat::Jpeg, &b)))
    }

    /// Agent runs in a Space.
    pub async fn list_space_agents(
        &self,
        space: &str,
    ) -> CmdResult<Vec<crate::agents::SpaceAgentRun>> {
        let s = self.space(space).await?;
        let runs = s.agents().await.map_err(msg)?.list().await.map_err(msg)?;
        Ok(runs.iter().map(crate::agents::space_agent_run).collect())
    }

    /// Installs `harness` in a Linux Space (pinned tools in `~/.cua/tools`,
    /// bins in `~/.cua/bin`, plus the cua skills), then opens its
    /// interactive CLI in a terminal on the Space's desktop. The user signs
    /// in inside that terminal: no host credential is read or copied.
    pub async fn launch_agent_terminal(&self, space: &str, harness: &str) -> CmdResult<()> {
        let h = cua_spaces::agents::harness::harness(harness)
            .ok_or_else(|| format!("unknown coding agent {harness:?}"))?;
        let cli = h.cli.ok_or_else(|| {
            format!(
                "{} has no interactive terminal; start it with `cua agent run` instead",
                h.name
            )
        })?;
        let s = self.space(space).await?;
        if matches!(s.os_family(), pb::OsFamily::Macos | pb::OsFamily::Windows) {
            return Err(format!(
                "{} opens in a terminal only in Linux Spaces for now",
                h.name
            ));
        }
        let agents = s.agents().await.map_err(msg)?;
        agents
            .ensure(h.installs, |p| {
                tracing::debug!(id = %p.id, phase = %p.phase, "installing {}: {}", h.id, p.detail)
            })
            .await
            .map_err(|e| format!("could not install {}: {e}", h.name))?;
        if let Err(e) = agents.install_skills(h).await {
            tracing::warn!("cua skills for {}: {e}", h.id);
        }
        let guest = s.spacesd().map_err(msg)?;
        let has_xterm = guest
            .run(
                cua_spacesd_client::Command::shell("command -v xterm >/dev/null 2>&1")
                    .timeout(Duration::from_secs(30)),
            )
            .await
            .map_err(msg)?
            .status
            .success();
        if !has_xterm {
            return Err(format!(
                "{} is installed, but this Space has no xterm to open it in",
                h.name
            ));
        }
        let handle = guest
            .spawn(
                cua_spacesd_client::Command::shell(agent_terminal_script(h.name, cli))
                    .tag(format!("cua-agent-terminal/{}", h.id)),
            )
            .await
            .map_err(msg)?;
        handle.detach();
        Ok(())
    }

    // --------------------------------------------------------- streams

    /// Mints a media ticket the webview attaches to (wire v2).
    pub async fn open_stream(
        &self,
        space: &str,
        target: StreamTargetArg,
        opts: StreamOpts,
    ) -> CmdResult<StreamTicketInfo> {
        let s = self.space(space).await?;
        let req = open_media_request(&s, &target, &opts)?;
        let audio = req.audio.is_some();
        let raw = s
            .spacesd()
            .map_err(msg)?
            .stream()
            .open_media(req)
            .await
            .map_err(|st| msg(cua_spacesd_client::Error::from(st)))?
            .into_inner();
        let ws_path = if raw.ws_path.is_empty() {
            format!("/media?ticket={}", raw.ticket)
        } else {
            raw.ws_path.clone()
        };
        let ws_url = s.websocket_url(&ws_path).map_err(msg)?;
        let ticket = raw.ticket.clone();
        Ok(ticket_info(&s, raw, ws_url, ticket, audio))
    }

    /// `CloseMedia`.
    pub async fn close_stream(&self, space: &str, media_session_id: &str) -> CmdResult<()> {
        self.space(space)
            .await?
            .close_stream(media_session_id)
            .await
            .map_err(msg)
    }

    // -------------------------------------------------------- teleport

    /// What `app` would send (read-only, host side).
    pub async fn teleport_manifest(&self, app: &str, scope: &str) -> CmdResult<TransferManifest> {
        let scope = TeleportScope::parse(Some(scope)).map_err(msg)?;
        let sessions = self.app_sessions.clone();
        let app = app.to_string();
        let m = tokio::task::spawn_blocking(move || sessions.manifest(&app, scope))
            .await
            .map_err(msg)?
            .map_err(msg)?;
        Ok(TransferManifest::from_sdk(&m))
    }

    /// Exports the consented items and imports them into the Space. The
    /// consent ladder's outcome becomes a `cua_spaces` `Approval`, which
    /// refuses items not in the manifest and sensitive items without
    /// `acknowledge_sensitive`.
    pub async fn teleport_push(
        &self,
        app: &str,
        scope: &str,
        space: &str,
        include: &[String],
        acknowledge_sensitive: bool,
    ) -> CmdResult<TeleportResult> {
        let scope = TeleportScope::parse(Some(scope)).map_err(msg)?;
        let s = self.space(space).await?;
        let sessions = self.app_sessions.clone();
        let app_c = app.to_string();
        let manifest = tokio::task::spawn_blocking(move || sessions.manifest(&app_c, scope))
            .await
            .map_err(msg)?
            .map_err(msg)?;
        let space_id = s.id().to_string();
        let approval = if include.is_empty() {
            manifest.approving_default(&space_id, acknowledge_sensitive)
        } else {
            manifest.approving(&space_id, include, acknowledge_sensitive)
        }
        .map_err(msg)?;
        let receipt = s
            .teleport(
                self.app_sessions.clone(),
                &approval,
                ImportOptions {
                    replace_existing: false,
                    close_running_app: true,
                    launch_after: true,
                    // This simpler drag/drop teleport has no review sheet to
                    // offer "Save to Keyvault" from; `teleport_app_run`'s
                    // picker flow is the one that does.
                    save_to_keyvault: false,
                    // This push path has no relay-plaintext consent screen:
                    // an unsealed relay delivery is refused (S1).
                    relay_plaintext_ack: false,
                },
            )
            .await
            .map_err(msg)?;
        Ok(TeleportResult {
            ok: true,
            provider_id: receipt.app,
            launched: receipt.launched,
            pid: None,
            imported: receipt.imported,
            skipped: receipt.skipped,
        })
    }

    /// Teleport providers on this host.
    pub fn teleport_providers(&self) -> Vec<cua_spaces_ext::teleport::ProviderInfo> {
        self.app_sessions.catalog()
    }

    // ------------------------------------------- "Teleport an app…"

    /// The catalog of apps on this machine (the SDK's `cua_teleport::ux`),
    /// narrowed to `space`'s OS and CPU when given.
    pub async fn teleport_app_catalog(
        &self,
        space: Option<&str>,
    ) -> CmdResult<Vec<cua_teleport::ux::CatalogEntry>> {
        let hint = match space {
            // OS and CPU from the Space's capabilities: no guest round trip.
            Some(id) => self
                .space(id)
                .await?
                .app_teleport_hint()
                .await
                .map_err(msg)?,
            None => Default::default(),
        };
        let req = cua_teleport::ux::CatalogRequest {
            probe_providers: self.teleport_app_roots.is_none(),
            roots: self.teleport_app_roots.clone(),
            hint,
            recents_path: self.teleport_recents.clone(),
        };
        let sessions = self.app_sessions.clone();
        tokio::task::spawn_blocking(move || cua_teleport::ux::catalog(sessions.registry(), &req))
            .await
            .map_err(msg)?
            .map_err(msg)
    }

    /// Warms the picker's app list and icons in the background (the SDK's
    /// caches), so the first "Teleport an app…" opens on cached ones.
    pub fn teleport_prefetch(&self) {
        let roots = self.teleport_app_roots.clone();
        let _ = std::thread::Builder::new()
            .name("cua-teleport-prefetch".into())
            .spawn(move || cua_teleport::ux::prefetch(roots));
    }

    /// The catalog row for a dropped app (bundle, `.desktop`, shortcut).
    pub fn teleport_entry_for_path(&self, path: &str) -> CmdResult<cua_teleport::ux::CatalogEntry> {
        cua_teleport::ux::entry_for_path(self.app_sessions.registry(), path, &Default::default())
            .map_err(msg)
    }

    /// The catalog row for a dragged window: its bundle when known, else its
    /// owner's name.
    pub fn teleport_entry_for_window(
        &self,
        bundle_path: Option<&str>,
        app_name: &str,
    ) -> cua_teleport::ux::CatalogEntry {
        let registry = self.app_sessions.registry();
        bundle_path
            .and_then(|p| cua_teleport::ux::entry_for_path(registry, p, &Default::default()).ok())
            .unwrap_or_else(|| {
                cua_teleport::ux::entry_for_name(registry, app_name, &Default::default())
            })
    }

    /// What teleporting `entry` into `space` will do (steps and consent).
    pub async fn teleport_app_plan(
        &self,
        space: &str,
        entry: &cua_teleport::ux::CatalogEntry,
        options: &cua_teleport::ux::PlanOptions,
    ) -> CmdResult<cua_teleport::ux::TeleportPlan> {
        let s = self.space(space).await?;
        s.plan_app_teleport(self.app_sessions.clone(), entry, options)
            .await
            .map_err(msg)
    }

    /// Runs an approved plan, reporting each [`cua_teleport::ux::RunEvent`],
    /// then records the app in the recents.
    pub async fn teleport_app_run(
        &self,
        space: &str,
        plan: cua_teleport::ux::TeleportPlan,
        consent: cua_teleport::ux::Consent,
        progress: impl FnMut(cua_teleport::ux::RunEvent) + Send,
    ) -> CmdResult<cua_teleport::ux::RunReport> {
        let approved = plan.approve(consent).map_err(msg)?;
        let s = self.space(space).await?;
        let report = s
            .run_app_teleport(self.app_sessions.clone(), &approved, progress)
            .await
            .map_err(msg)?;
        if let Err(e) =
            cua_teleport::ux::record_recent(self.teleport_recents.clone(), &report.app_id)
        {
            tracing::warn!("could not record the teleport recent: {e}");
        }
        Ok(report)
    }

    // --------------------------------------------------------- hotspot

    fn forget_hotspot(&self, id: &str) {
        let mut h = self.hotspot.lock().unwrap_or_else(|p| p.into_inner());
        if h.as_deref() == Some(id) {
            *h = None;
        }
    }

    /// Shares this machine's network with one Space (replaces any other).
    pub async fn start_hotspot(&self, space: &str) -> CmdResult<HotspotStatus> {
        let spaces = self.spaces();
        let id = spaces.resolve(space).map_err(msg)?.to_string();
        let _ = spaces.hotspot_stop(None).await;
        spaces
            .hotspot_start(&id, HotspotOptions::default())
            .await
            .map_err(msg)?;
        *self.hotspot.lock().unwrap_or_else(|p| p.into_inner()) = Some(id);
        Ok(self.hotspot_status())
    }

    /// Stops sharing. Idempotent.
    pub async fn stop_hotspot(&self) -> CmdResult<HotspotStatus> {
        self.spaces().hotspot_stop(None).await.map_err(msg)?;
        *self.hotspot.lock().unwrap_or_else(|p| p.into_inner()) = None;
        Ok(self.hotspot_status())
    }

    /// Current hotspot.
    pub fn hotspot_status(&self) -> HotspotStatus {
        let id = self
            .hotspot
            .lock()
            .unwrap_or_else(|p| p.into_inner())
            .clone();
        HotspotStatus {
            active: id.is_some(),
            space_id: id,
        }
    }
}

fn data_url(format: pb::ImageFormat, bytes: &[u8]) -> String {
    let mime = match format {
        pb::ImageFormat::Jpeg => "image/jpeg",
        pb::ImageFormat::Webp => "image/webp",
        _ => "image/png",
    };
    format!(
        "data:{mime};base64,{}",
        base64::engine::general_purpose::STANDARD.encode(bytes)
    )
}

fn codec_of(name: &str) -> CmdResult<pb::MediaCodec> {
    match name {
        "h264" => Ok(pb::MediaCodec::H264),
        "bgra" => Ok(pb::MediaCodec::Bgra),
        "png" => Ok(pb::MediaCodec::Png),
        other => Err(format!("unknown codec {other:?}")),
    }
}

fn codec_name(codec: i32) -> String {
    match pb::MediaCodec::try_from(codec).unwrap_or_default() {
        pb::MediaCodec::H264 => "h264",
        pb::MediaCodec::Bgra => "bgra",
        pb::MediaCodec::Png => "png",
        pb::MediaCodec::Unspecified => "unspecified",
    }
    .into()
}

/// The one `OpenMediaRequest` both paths (direct and daemon bridge) send.
pub fn open_media_request(
    space: &Space,
    target: &StreamTargetArg,
    o: &StreamOpts,
) -> CmdResult<pb::OpenMediaRequest> {
    let target = match target {
        StreamTargetArg::Display { display_id } => {
            space.require("desktop_stream").map_err(msg)?;
            pb::media_target::Target::DisplayId(
                display_id.clone().unwrap_or_else(|| "primary".into()),
            )
        }
        StreamTargetArg::Window { window_id } => {
            space.require("window_stream").map_err(msg)?;
            pb::media_target::Target::Window(pb::WindowRef {
                id: window_id.clone(),
                epoch: 0,
            })
        }
    };
    let audio = o.audio.unwrap_or(false);
    if audio {
        space.require("audio.desktop").map_err(msg)?;
    }
    let policy = match o.policy.as_deref() {
        None | Some("allow_activation") => pb::SessionPolicy::AllowActivation,
        Some("background_only") => pb::SessionPolicy::BackgroundOnly,
        Some("view_only") => pb::SessionPolicy::ViewOnly,
        Some(other) => return Err(format!("unknown stream policy {other:?}")),
    };
    Ok(pb::OpenMediaRequest {
        target: Some(pb::MediaTarget {
            target: Some(target),
        }),
        codecs: o
            .codecs
            .as_deref()
            .unwrap_or(&[])
            .iter()
            .map(|c| codec_of(c).map(|c| c as i32))
            .collect::<CmdResult<_>>()?,
        max_fps: o.max_fps.unwrap_or(0),
        max_dimension: o.max_dimension.unwrap_or(0),
        bitrate_kbps: 0,
        policy: policy as i32,
        geometry_control: if o.geometry_control.unwrap_or(false) {
            pb::GeometryControl::Bidirectional as i32
        } else {
            pb::GeometryControl::ObserveOnly as i32
        },
        ticket_ttl: Some(pbjson_duration(Duration::from_secs(120))),
        prefer_quic: false,
        audio: audio.then(|| pb::AudioOptions {
            enabled: true,
            ..Default::default()
        }),
        disable_video: false,
        // Attribute this viewer's input to its presence identity.
        presence_participant_id: space.presence_participant().unwrap_or_default(),
    })
}

fn pbjson_duration(d: Duration) -> cua_proto::wkt::Duration {
    cua_proto::wkt::Duration {
        seconds: d.as_secs() as i64,
        nanos: 0,
    }
}

fn ticket_info(
    s: &Space,
    raw: pb::OpenMediaResponse,
    ws_url: String,
    ticket: String,
    audio: bool,
) -> StreamTicketInfo {
    let size = raw
        .geometry
        .as_ref()
        .and_then(|g| g.frame_size.as_ref())
        .map(|s| [s.width, s.height])
        .unwrap_or([0, 0]);
    StreamTicketInfo {
        space_id: s.id().to_string(),
        media_session_id: raw.media_session_id.clone(),
        ws_url,
        ticket,
        ticket_expires_at: raw.ticket_expires_at.as_ref().map(|t| {
            let at = std::time::UNIX_EPOCH + Duration::from_secs(t.seconds.max(0) as u64);
            format_rfc3339(at)
        }),
        codec: codec_name(raw.codec),
        wire_version: raw.wire_version,
        frame_size: size,
        via: "direct",
        audio,
    }
}

fn format_rfc3339(at: std::time::SystemTime) -> String {
    // Seconds precision, UTC, without a date crate.
    let secs = at
        .duration_since(std::time::UNIX_EPOCH)
        .unwrap_or_default()
        .as_secs() as i64;
    let days = secs.div_euclid(86_400);
    let rem = secs.rem_euclid(86_400);
    let (y, m, d) = civil_from_days(days);
    format!(
        "{y:04}-{m:02}-{d:02}T{:02}:{:02}:{:02}Z",
        rem / 3600,
        (rem % 3600) / 60,
        rem % 60
    )
}

/// Howard Hinnant's days-to-civil.
fn civil_from_days(z: i64) -> (i64, u32, u32) {
    let z = z + 719_468;
    let era = z.div_euclid(146_097);
    let doe = z.rem_euclid(146_097);
    let yoe = (doe - doe / 1460 + doe / 36_524 - doe / 146_096) / 365;
    let y = yoe + era * 400;
    let doy = doe - (365 * yoe + yoe / 4 - yoe / 100);
    let mp = (5 * doy + 2) / 153;
    let d = (doy - (153 * mp + 2) / 5 + 1) as u32;
    let m = if mp < 10 { mp + 3 } else { mp - 9 } as u32;
    (if m <= 2 { y + 1 } else { y }, m, d)
}

#[cfg(test)]
mod tests {
    #[test]
    fn agent_terminal_script_quotes_and_puts_cua_bin_first() {
        let s = super::agent_terminal_script("Bob's Agent", "goose");
        assert_eq!(
            s,
            "export DISPLAY=\"${DISPLAY:-:1}\"; exec xterm -T 'Bob'\\''s Agent' -e sh -c \
             'PATH=\"$HOME/.cua/bin:$PATH\"; export PATH; exec goose'"
        );
    }

    use super::*;

    #[test]
    fn rfc3339_matches_known_instants() {
        let at = std::time::UNIX_EPOCH + Duration::from_secs(1_758_300_000);
        assert_eq!(format_rfc3339(at), "2025-09-19T16:40:00Z");
        assert_eq!(
            format_rfc3339(std::time::UNIX_EPOCH),
            "1970-01-01T00:00:00Z"
        );
        let leap = std::time::UNIX_EPOCH + Duration::from_secs(951_782_400); // 2000-02-29
        assert_eq!(format_rfc3339(leap), "2000-02-29T00:00:00Z");
    }

    #[test]
    fn stream_targets_deserialize_from_the_webview_shape() {
        let d: StreamTargetArg = serde_json::from_str(r#"{"kind":"display"}"#).unwrap();
        assert_eq!(d, StreamTargetArg::Display { display_id: None });
        let w: StreamTargetArg =
            serde_json::from_str(r#"{"kind":"window","windowId":"0x1f"}"#).unwrap();
        assert_eq!(
            w,
            StreamTargetArg::Window {
                window_id: "0x1f".into()
            }
        );
    }

    #[test]
    fn codecs_map_and_refuse_unknown_names() {
        assert_eq!(codec_of("h264").unwrap(), pb::MediaCodec::H264);
        assert!(codec_of("vp9").is_err());
        assert_eq!(codec_name(pb::MediaCodec::Png as i32), "png");
    }
}

#[cfg(test)]
mod display_name_tests {
    use super::display_name;

    #[test]
    fn a_container_hostname_gives_way_to_the_given_name() {
        assert_eq!(
            display_name("local:cua-e2e-desk", "69af41d9344c"),
            "cua-e2e-desk"
        );
        assert_eq!(display_name("local:desk", "My desk"), "My desk");
        assert_eq!(
            display_name("direct:10.0.0.5:3211", "69af41d9344c"),
            "69af41d9344c"
        );
    }
}