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.

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

//! The roster of Bots and their threads, shared by the shell's commands, the
//! routine scheduler and group chats (the Swift app's `BotStore`).
//!
//! Routines and group chats are the SDK's model (`cua_spaces::routines`,
//! `cua_spaces::groups`); this module is only the live seam: [`Bots`]
//! implements `RoutineRunner` and `GroupMessenger` over the Bots' real agent
//! threads in the one shared Space, with the Swift app's semantics:
//!
//! - a routine firing on a Bot mid-turn is **refused** (the slot is used);
//!   a Bot with a thread that takes a message gets another turn on it; any
//!   other Bot is hired with the routine's text;
//! - a group message hires a member without a thread, and is refused (and
//!   shown) for a member mid-turn.

use crate::thread::{BotThread, Line, Speaker};
use crate::{Core, Result};
use cua_spaces::agents::{Endpoint, RunOptions, RunStatus};
use cua_spaces::groups::{GroupDelivery, GroupMessenger};
use cua_spaces::routines::{Routine, RoutineFiring, RoutineRunner};
use std::collections::HashMap;
use tokio::sync::Mutex;

/// A Bot as the shell names it.
#[derive(Clone, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub struct BotInfo {
    pub id: String,
    pub name: String,
    pub agent: String,
    /// The Space it works in.
    pub space: String,
}

/// A thread as the shell renders it.
#[derive(Clone, Debug, serde::Serialize)]
pub struct ThreadView {
    pub run_id: Option<String>,
    pub status: Option<String>,
    pub accepts_message: bool,
    pub transcript: Vec<Line>,
    /// The roster preview: the agent's last message on one line (the SDK's
    /// `Transcript::preview`; activity never becomes a preview).
    pub preview: Option<String>,
}

impl ThreadView {
    fn of(t: &BotThread) -> Self {
        Self {
            run_id: t.run_id().map(str::to_string),
            status: t.last_status().map(|s| s.status.as_str().to_string()),
            accepts_message: t.last_status().is_none_or(|s| s.accepts_message),
            transcript: t.transcript(),
            preview: t.preview(),
        }
    }
}

/// Agent start options for every run this roster starts: a custom model
/// endpoint and the provider key variables forwarded from this process.
#[derive(Clone, Debug, Default)]
pub struct AgentOptions {
    pub base_url: Option<String>,
    pub model: Option<String>,
    pub env_from_host: Vec<String>,
}

impl AgentOptions {
    /// `OPENKOALABOTS_MODEL_URL`, `OPENKOALABOTS_MODEL`, and
    /// `OPENKOALABOTS_MODEL_KEY_VAR` (a provider key variable to forward).
    pub fn from_env() -> Self {
        let var = |k: &str| std::env::var(k).ok().filter(|v| !v.is_empty());
        Self {
            base_url: var("OPENKOALABOTS_MODEL_URL"),
            model: var("OPENKOALABOTS_MODEL"),
            env_from_host: var("OPENKOALABOTS_MODEL_KEY_VAR").into_iter().collect(),
        }
    }

    /// The run options: the endpoint, and the forwarded keys (a missing or
    /// disallowed variable is an error, never guessed).
    pub fn run_options(&self) -> Result<RunOptions> {
        let (env, missing) = cua_spaces::agents::env_from_host(&self.env_from_host)?;
        if !missing.is_empty() {
            return Err(crate::Error::Invalid(format!(
                "not set in this process: {}",
                missing.join(", ")
            )));
        }
        Ok(RunOptions {
            env,
            endpoint: self.base_url.clone().map(|base_url| Endpoint {
                base_url,
                wire: None,
                model: self.model.clone(),
            }),
            model: self.model.clone(),
            ..Default::default()
        })
    }
}

/// A Bot's avatar color, the same as its cursor: while the Bot is present
/// on the Space, the color the server assigned it (a requested color is kept
/// unless another participant already holds it), read from the presence
/// roster; before that (or with no roster), its stable presence color, the
/// one it requests when it joins. The shell's `botAvatarColor` is the
/// TypeScript twin, fed from the same roster's avatars.
pub fn avatar_color(roster: Option<&cua_spaces::presence::Roster>, bot_id: &str) -> String {
    match roster {
        Some(r) => r.color_of(bot_id).to_lowercase(),
        None => cua_spaces::presence::color_for(bot_id).to_string(),
    }
}

/// The reply of a Bot's latest turn: its agent lines (never the prompt,
/// tool notices or turn markers), `None` before it has said anything.
pub fn latest_reply(transcript: &[Line]) -> Option<String> {
    let turn = transcript.iter().map(|l| l.turn).max()?;
    let text = transcript
        .iter()
        .filter(|l| l.turn == turn && l.speaker == Speaker::Agent)
        .map(|l| l.text.trim())
        .filter(|t| !t.is_empty())
        .collect::<Vec<_>>()
        .join("\n");
    (!text.is_empty()).then_some(text)
}

#[derive(Default)]
struct Inner {
    info: HashMap<String, BotInfo>,
    threads: HashMap<String, BotThread>,
}

/// Every Bot and its thread.
pub struct Bots {
    core: Core,
    options: AgentOptions,
    inner: Mutex<Inner>,
}

impl Bots {
    pub fn new(core: Core, options: AgentOptions) -> Self {
        Self {
            core,
            options,
            inner: Mutex::new(Inner::default()),
        }
    }

    /// Adds or renames Bots (the shell's list).
    pub async fn upsert(&self, bots: Vec<BotInfo>) {
        let mut g = self.inner.lock().await;
        for b in bots {
            g.info.insert(b.id.clone(), b);
        }
    }

    pub async fn info(&self, bot: &str) -> Option<BotInfo> {
        self.inner.lock().await.info.get(bot).cloned()
    }

    /// Sends a user turn: the first starts the Bot's run, later ones go to it.
    pub async fn send(&self, bot: &str, text: &str) -> Result<ThreadView> {
        let mut g = self.inner.lock().await;
        if !g.threads.contains_key(bot) {
            let info = g
                .info
                .get(bot)
                .cloned()
                .ok_or_else(|| crate::Error::Invalid(format!("no Bot {bot}")))?;
            let t = BotThread::new(&self.core.space(&info.space).await?, &info.agent)
                .await?
                .with_options(self.options.run_options()?);
            g.threads.insert(bot.to_string(), t);
        }
        let t = g.threads.get_mut(bot).expect("inserted");
        let sent = t.send(text).await;
        let v = ThreadView::of(t);
        sent.map(|_| v)
    }

    /// One poll of a started thread.
    pub async fn poll(&self, bot: &str) -> Result<ThreadView> {
        let mut g = self.inner.lock().await;
        let t = g
            .threads
            .get_mut(bot)
            .ok_or_else(|| crate::Error::Invalid(format!("no thread for {bot}")))?;
        if t.run_id().is_some() {
            t.poll().await?;
        }
        Ok(ThreadView::of(t))
    }

    /// The thread's current view, without a poll.
    pub async fn view(&self, bot: &str) -> Option<ThreadView> {
        self.inner.lock().await.threads.get(bot).map(ThreadView::of)
    }

    /// Waits for a Bot's current turn (see [`BotThread::wait_turn`]).
    pub async fn wait_turn(
        &self,
        bot: &str,
        expect: Option<&str>,
        every: std::time::Duration,
        max_polls: u32,
    ) -> Result<ThreadView> {
        let mut g = self.inner.lock().await;
        let t = g
            .threads
            .get_mut(bot)
            .ok_or_else(|| crate::Error::Invalid(format!("no thread for {bot}")))?;
        t.wait_turn(expect, every, max_polls).await?;
        Ok(ThreadView::of(t))
    }

    /// Stops every run this roster started.
    pub async fn stop_all(&self) {
        let mut g = self.inner.lock().await;
        for t in g.threads.values_mut() {
            let _ = t.stop().await;
        }
    }

    /// `(has a started thread, last status, accepts a message)` after a fresh poll.
    async fn state(&self, bot: &str) -> (bool, Option<RunStatus>, bool) {
        let mut g = self.inner.lock().await;
        match g.threads.get_mut(bot) {
            Some(t) if t.run_id().is_some() => {
                let _ = t.poll().await;
                let s = t.last_status();
                (
                    true,
                    s.map(|s| s.status),
                    s.is_none_or(|s| s.accepts_message),
                )
            }
            _ => (false, None, false),
        }
    }

    async fn name(&self, bot: &str) -> String {
        self.info(bot)
            .await
            .map(|b| b.name)
            .unwrap_or_else(|| bot.to_string())
    }

    /// Replaces a Bot's thread with a fresh one and sends `text` (a hire).
    async fn hire(&self, bot: &str, text: &str) -> Result<String> {
        self.inner.lock().await.threads.remove(bot);
        let v = self.send(bot, text).await?;
        Ok(v.run_id.unwrap_or_default())
    }
}

#[async_trait::async_trait]
impl RoutineRunner for Bots {
    async fn fire(&self, routine: &Routine) -> RoutineFiring {
        let text = routine.turn_text();
        let (started, status, accepts) = self.state(&routine.bot_id).await;
        if status == Some(RunStatus::Running) {
            return RoutineFiring::Refused {
                reason: format!("{} is mid-turn; the slot was skipped", routine.bot_id),
            };
        }
        let result = if started && accepts {
            self.send(&routine.bot_id, &text)
                .await
                .map(|v| v.run_id.unwrap_or_default())
        } else {
            self.hire(&routine.bot_id, &text).await
        };
        match result {
            Ok(run_id) => RoutineFiring::Started { run_id },
            Err(e) => RoutineFiring::Failed {
                reason: e.to_string(),
            },
        }
    }
}

#[async_trait::async_trait]
impl GroupMessenger for Bots {
    async fn deliver(&self, text: &str, bot_id: &str) -> GroupDelivery {
        let (started, status, _) = self.state(bot_id).await;
        let d = |accepted: bool, reason: String| GroupDelivery {
            bot_id: bot_id.to_string(),
            accepted,
            reason,
        };
        if !started {
            return match self.hire(bot_id, text).await {
                Ok(_) => d(true, "started for this group".into()),
                Err(e) => d(false, e.to_string()),
            };
        }
        if status == Some(RunStatus::Running) {
            let name = self.name(bot_id).await;
            return d(
                false,
                format!("{name} is mid-turn; a message is refused rather than queued"),
            );
        }
        match self.send(bot_id, text).await {
            Ok(_) => d(true, "delivered".into()),
            Err(e) => d(false, e.to_string()),
        }
    }

    async fn latest_reply(&self, bot_id: &str) -> Option<String> {
        let mut g = self.inner.lock().await;
        let t = g.threads.get_mut(bot_id)?;
        if t.run_id().is_some() {
            let _ = t.poll().await;
        }
        latest_reply(&t.transcript())
    }

    async fn is_working(&self, bot_id: &str) -> bool {
        let g = self.inner.lock().await;
        g.threads
            .get(bot_id)
            .and_then(|t| t.last_status())
            .is_some_and(|s| s.status == RunStatus::Running)
    }

    async fn display_name(&self, bot_id: &str) -> String {
        self.name(bot_id).await
    }
}

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

    #[test]
    fn a_bots_avatar_is_its_presence_cursor_color() {
        for bot in ["ada", "bo", "openkoalabots-koala-1"] {
            // The color a Bot's cursor requests when it joins presence.
            let cursor = cua_spaces::presence::Identity::agent(bot, bot).color;
            assert_eq!(avatar_color(None, bot), cursor, "{bot}");
        }
        assert_eq!(
            avatar_color(None, "ada"),
            "#bcf60c",
            "pinned to the TypeScript twin"
        );
    }

    /// The operator holds Ada's stable color, so the server gave Ada another:
    /// Ada's avatar follows her cursor, and falls back once she leaves.
    #[test]
    fn the_avatar_follows_the_server_assigned_color() {
        use cua_spaces::presence::{Participant, PresenceEvent, Roster};
        let stable = cua_spaces::presence::color_for("ada");
        let p = |pid: &str, principal: &str, color: &str, kind: &str| Participant {
            participant_id: pid.into(),
            principal_id: principal.into(),
            display_name: principal.into(),
            color: color.into(),
            kind: kind.into(),
        };
        let mut r = Roster {
            me: "me".into(),
            entries: vec![(p("me", "operator", stable, "human"), None)],
        };
        r.apply(&PresenceEvent::Joined {
            participant: p("p-ada", "ada", "#123456", "agent"),
        });
        let cursor = crate::presence::avatars(&r)
            .into_iter()
            .find(|a| a.principal_id == "ada")
            .unwrap()
            .color;
        assert_eq!(avatar_color(Some(&r), "ada"), cursor);
        assert_eq!(cursor, "#123456");
        r.apply(&PresenceEvent::Left {
            participant_id: "p-ada".into(),
            reason: String::new(),
        });
        assert_eq!(avatar_color(Some(&r), "ada"), stable);
    }

    fn l(turn: usize, speaker: Speaker, text: &str) -> Line {
        Line {
            turn,
            speaker,
            text: text.into(),
            steps: vec![],
        }
    }

    #[test]
    fn the_latest_reply_is_the_last_turns_agent_text_only() {
        assert_eq!(latest_reply(&[]), None);
        let t = vec![
            l(1, Speaker::User, "[routine] Check-in: mock: say one"),
            l(1, Speaker::Agent, "one"),
            l(2, Speaker::User, "again"),
            l(2, Speaker::Activity, "1 step"),
        ];
        assert_eq!(latest_reply(&t), None, "turn 2 has not answered yet");
        let mut t = t;
        t.push(l(2, Speaker::Agent, " two \n"));
        t.push(l(2, Speaker::Agent, "three"));
        assert_eq!(latest_reply(&t).as_deref(), Some("two\nthree"));
    }

    #[test]
    fn agent_options_forward_only_named_keys_and_the_endpoint() {
        let none = AgentOptions::default().run_options().unwrap();
        assert!(none.endpoint.is_none() && none.env.is_empty());
        let o = AgentOptions {
            base_url: Some("http://mock:8787".into()),
            model: Some("claude-mock-1".into()),
            env_from_host: vec![],
        }
        .run_options()
        .unwrap();
        let e = o.endpoint.unwrap();
        assert_eq!(e.base_url, "http://mock:8787");
        assert_eq!(e.model.as_deref(), Some("claude-mock-1"));
        assert!(
            AgentOptions {
                env_from_host: vec!["HOME".into()],
                ..Default::default()
            }
            .run_options()
            .is_err(),
            "HOME is not a provider key"
        );
    }

    #[tokio::test]
    async fn without_a_space_firings_fail_and_deliveries_are_refused_with_reasons() {
        let dir = tempfile::tempdir().unwrap();
        let core = Core::new(crate::CoreConfig::in_dir(dir.path())).unwrap();
        let bots = Bots::new(core, AgentOptions::default());
        bots.upsert(vec![BotInfo {
            id: "ada".into(),
            name: "Ada".into(),
            agent: "claude-code".into(),
            space: "direct:127.0.0.1:1".into(),
        }])
        .await;
        let r = cua_spaces::routines::Routine {
            id: "r".into(),
            bot_id: "ghost".into(),
            title: "T".into(),
            prompt: "p".into(),
            schedule: cua_spaces::routines::Schedule::EveryMinutes { minutes: 1 },
            is_enabled: true,
            created_at: chrono::Utc::now(),
            last_fired_at: None,
            last_run_id: None,
            last_outcome: None,
        };
        match bots.fire(&r).await {
            RoutineFiring::Failed { reason } => {
                assert!(reason.contains("no Bot ghost"), "{reason}")
            }
            other => panic!("{other:?}"),
        }
        let d = bots.deliver("hi", "ada").await;
        assert!(!d.accepted && !d.reason.is_empty());
        assert_eq!(bots.display_name("ada").await, "Ada");
        assert_eq!(bots.display_name("ghost").await, "ghost");
        assert!(!bots.is_working("ada").await);
        assert_eq!(bots.latest_reply("ada").await, None);
    }
}