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.

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

//! openkoalabots's app logic on the cua Spaces runtime (`cua-spaces`, the Rust
//! crate behind the cua SDK), headless so the Tauri shell, its tests and the
//! scenario runner share one implementation.
//!
//! The flows mirror the Swift app (`examples/openkoalabot-example-swift`):
//!
//! | Flow | Module |
//! |---|---|
//! | pick / add / create / delete a Space | [`Core`] |
//! | desktop stream (PiP): keyframe-first frames, or a media ticket for the webview | [`stream`] |
//! | one long-lived agent thread per Bot, roster, transcript | [`thread`] |
//! | drop a file into the Space, SHA-256 verified by the guest | [`files`] |
//! | teleport an app session behind an explicit approval (ships with Cua Spaces) | [`teleport`] |
//! | presence: who else is in the Space, cursors | [`presence`] |
//! | routines and group chats over the Bots' threads | [`bots`] |
//! | the New Space wizard: a plan to one `Spaces::create` call | [`plan`] |
//! | the page's saved state, in the app's data directory | [`ui_state`] |
//!
//! Host safety: [`CoreConfig`] always names the Spaces registry directory;
//! tests and the scenario runner pass temp directories.
//!
//! App teleport (the "Teleport an app..." picker and window drags) ships with
//! Cua Spaces (source-available) and is not part of this sample; session
//! teleport goes through the Spaces tools and says the same when the runtime
//! has no teleport extension (see [`teleport`]).

pub mod bots;
pub mod error;
pub mod files;
pub mod plan;
pub mod presence;
pub mod scenario;
pub mod stream;
pub mod teleport;
pub mod thread;
pub mod ui_state;

pub use error::{Error, Result};

use cua_sandbox_core::{LocalRuntime, Sandboxes};
pub use cua_spaces;
pub use cua_spaces::{Space, SpaceInfo};
use cua_spaces::{SpaceCreate, Spaces};
use std::path::PathBuf;
use std::sync::Arc;
use std::time::Duration;

/// Where the core keeps its state.
#[derive(Clone)]
pub struct CoreConfig {
    /// The Spaces registry directory (`spaces.json` + stored tokens).
    pub spaces_home: PathBuf,
    /// Where `download` lands.
    pub download_dir: PathBuf,
    /// spacesd handshake timeout.
    pub probe_timeout: Duration,
    /// The runtime behind local Spaces (the Tauri shell passes the SDK's
    /// `VmmLocal`: containers, QEMU and Lume). `None`: local Spaces are
    /// unavailable.
    pub local_runtime: Option<Arc<dyn LocalRuntime>>,
    /// Where local sandboxes keep their state (never `~/.cua`).
    pub sandboxes_home: PathBuf,
}

impl std::fmt::Debug for CoreConfig {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("CoreConfig")
            .field("spaces_home", &self.spaces_home)
            .field("download_dir", &self.download_dir)
            .field(
                "local_runtime",
                &self.local_runtime.as_ref().map(|r| r.backend()),
            )
            .finish()
    }
}

impl CoreConfig {
    /// A config rooted at `dir` (registry in `dir/spaces`, downloads in
    /// `dir/downloads`).
    pub fn in_dir(dir: impl Into<PathBuf>) -> Self {
        let dir = dir.into();
        Self {
            spaces_home: dir.join("spaces"),
            download_dir: dir.join("downloads"),
            probe_timeout: Duration::from_secs(20),
            local_runtime: None,
            sandboxes_home: dir.join("sandboxes"),
        }
    }

    /// Enable local Spaces on `runtime`.
    pub fn with_local_runtime(mut self, runtime: Arc<dyn LocalRuntime>) -> Self {
        self.local_runtime = Some(runtime);
        self
    }
}

/// The app's handle on the Spaces runtime.
#[derive(Clone)]
pub struct Core {
    spaces: Spaces,
    config: CoreConfig,
}

impl Core {
    /// Builds the runtime. No I/O until the first call, except creating
    /// the registry directory.
    pub fn new(config: CoreConfig) -> Result<Self> {
        std::fs::create_dir_all(&config.spaces_home)?;
        std::fs::create_dir_all(&config.download_dir)?;
        // The streaming client behind `StreamSession` (Cua Spaces).
        cua_spaces_ext::stream::register();
        // #region docs:rs-open
        let mut builder = Spaces::builder()
            .home(config.spaces_home.clone())
            .download_dir(config.download_dir.clone())
            // Never draw on the operator's desktop: the app renders streams
            // itself (PiP), from frames or a media ticket.
            .operator_display(Arc::new(cua_spaces::operator::NoDisplay))
            .probe_timeout(config.probe_timeout);
        // #endregion docs:rs-open
        if let Some(local) = &config.local_runtime {
            // Local sandboxes, with their state in the app's directory.
            builder = builder.sandboxes(
                Sandboxes::builder()
                    .local(local.clone())
                    .state_dir(config.sandboxes_home.clone())
                    .build(),
            );
        }
        Ok(Self {
            spaces: builder.build(),
            config,
        })
    }

    /// The underlying runtime.
    pub fn spaces(&self) -> &Spaces {
        &self.spaces
    }

    /// The configuration.
    pub fn config(&self) -> &CoreConfig {
        &self.config
    }

    /// Every registered Space (the picker's list).
    pub fn list_spaces(&self) -> Result<Vec<SpaceInfo>> {
        Ok(self.spaces.list()?)
    }

    /// Adds a machine that runs cua-spacesd (`host:port`, `http(s)://…`
    /// or a Space id such as `local:<name>`) after a capabilities handshake. Never creates a sandbox.
    // #region docs:rs-add
    pub async fn add_space(
        &self,
        url: &str,
        token: Option<String>,
        name: Option<String>,
    ) -> Result<SpaceInfo> {
        Ok(self.spaces.add(url, token, name).await?)
    }
    // #endregion docs:rs-add

    /// Creates a Space in the cloud. Cua Cloud has ended: this always fails
    /// with [`cua_sandbox_core::CLOUD_ENDED`]; create it on this machine
    /// instead ([`Core::create_space`] with [`plan::Target::Local`]).
    pub async fn create_cloud_space(
        &self,
        image: Option<String>,
        name: Option<String>,
    ) -> Result<SpaceInfo> {
        self.spaces
            .create(SpaceCreate {
                on: Some(cua_sandbox_core::placement::On::Cloud),
                image,
                name,
                wait: Some(true),
                ..Default::default()
            })
            .await?
            .ready()
            .map_err(|p| Error::Invalid(format!("Space {} is still {}", p.id, p.phase)))
    }

    /// Creates a Space from the New Space wizard's plan: one
    /// `Spaces::create` call. A local plan creates the Space on this machine;
    /// a cloud plan fails with [`cua_sandbox_core::CLOUD_ENDED`]; see
    /// [`plan::plan_call`].
    pub async fn create_space(&self, plan: &plan::SpacePlan) -> Result<SpaceInfo> {
        let create = plan::plan_call(plan)?;
        if create.on == Some(cua_sandbox_core::placement::On::Local)
            && self.config.local_runtime.is_none()
        {
            return Err(Error::Invalid(
                "local Spaces need a local runtime (CoreConfig::with_local_runtime)".into(),
            ));
        }
        self.spaces
            .create(create)
            .await?
            .ready()
            .map_err(|p| Error::Invalid(format!("Space {} is still {}", p.id, p.phase)))
    }

    /// A connected handle.
    pub async fn space(&self, id: &str) -> Result<Space> {
        Ok(self.spaces.space(id).await?)
    }

    /// Deletes a Space's sandbox (a Space added by address is only
    /// forgotten).
    pub async fn delete_space(&self, id: &str) -> Result<String> {
        Ok(self.spaces.delete(id).await?)
    }

    /// Runs a shell line in the Space.
    pub async fn bash(&self, space: &Space, line: &str, timeout: Duration) -> Result<String> {
        let out = space.bash(line, timeout).await?;
        if !out.success() {
            return Err(Error::Invalid(format!("`{line}` failed: {}", out.render())));
        }
        Ok(out.stdout)
    }
}

/// 8 random hex chars.
pub fn nonce() -> String {
    format!("{:08x}", rand::random::<u32>())
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn config_in_dir_never_points_at_the_real_home() {
        let c = CoreConfig::in_dir("/tmp/x");
        assert_eq!(c.spaces_home, PathBuf::from("/tmp/x/spaces"));
    }

    #[test]
    fn nonce_is_eight_hex() {
        let n = nonce();
        assert_eq!(n.len(), 8);
        assert!(n.chars().all(|c| c.is_ascii_hexdigit()));
    }
}