Skip to content
Python
15.4 KB
Raw Blame
//! First-class team coordination rules. Storage adapters must execute these decisions
//! atomically; this module does not provision sessions or advertise runtime tools.
//! Message authors come from the authenticated caller, never a model-supplied field.
use anyhow::{ensure, Context, Result};
use serde::{Deserialize, Serialize};
use std::collections::{BTreeMap, BTreeSet};

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct Communication {
    pub board: bool,
    pub direct_messages: bool,
}
impl Default for Communication {
    fn default() -> Self {
        Self {
            board: true,
            direct_messages: false,
        }
    }
}
#[derive(Clone, Debug, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Policy {
    pub communication: Communication,
    pub max_instances: usize,
}
impl Default for Policy {
    fn default() -> Self {
        Self {
            communication: Communication::default(),
            max_instances: 32,
        }
    }
}
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct SpawnRequest {
    pub agent_type: String,
    pub agent_id: String,
    pub message: String,
    #[serde(default)]
    pub title: Option<String>,
    #[serde(default)]
    pub background: Option<String>,
    #[serde(default)]
    pub context: crate::team_briefing::Context,
    #[serde(default)]
    pub workspace: crate::team_workspace::Selection,
    #[serde(default)]
    pub model: Option<crate::connections::Choice>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub sandbox: Option<crate::team_definition::Sandbox>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub source: Option<crate::coding_handoff::config::Choice>,
}
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum Phase {
    Reserved,
    Ready,
    Retiring,
    Closed,
}
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Instance {
    pub agent_type: String,
    pub agent_id: String,
    pub session_id: String,
    pub phase: Phase,
}
#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct Roster {
    policy: Policy,
    spawn_types: BTreeSet<String>,
    instances: BTreeMap<String, Instance>,
    requests: BTreeMap<String, SpawnRequest>,
}
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct Reservation {
    pub instance: Instance,
    pub created: bool,
}
fn identifier(id: &str) -> Result<()> {
    ensure!(
        !id.is_empty()
            && id.len() <= 64
            && id != "all"
            && id.as_bytes()[0].is_ascii_alphabetic()
            && id
                .bytes()
                .all(|b| b.is_ascii_alphanumeric() || b == b'-' || b == b'_'),
        "Invalid instance/type identifier or reserved @all identifier"
    );
    Ok(())
}
fn text(body: &str, max: usize) -> Result<()> {
    ensure!(
        !body.trim().is_empty() && body.len() <= max && !body.contains('\0'),
        "Empty or oversized message"
    );
    Ok(())
}
fn session_id(id: &str) -> Result<()> {
    ensure!(
        !id.is_empty() && id.len() <= 200 && !id.chars().any(char::is_control),
        "Invalid session reference"
    );
    Ok(())
}
impl Roster {
    pub fn policy(&self) -> &Policy {
        &self.policy
    }
    pub fn spawn_types(&self) -> &BTreeSet<String> {
        &self.spawn_types
    }
    /// Trusted catalog resolution calls this only after persisting an exact
    /// approved definition in the same transaction. It grants no host authority.
    pub fn register_type(&mut self, name: &str) -> Result<()> {
        identifier(name)?;
        ensure!(
            self.spawn_types.contains(name) || self.spawn_types.len() < 96,
            "Team type capacity reached"
        );
        self.spawn_types.insert(name.into());
        Ok(())
    }
    pub fn new(lead: Instance, spawn_types: BTreeSet<String>, policy: Policy) -> Result<Self> {
        ensure!(
            (1..=1024).contains(&policy.max_instances),
            "Invalid team capacity"
        );
        identifier(&lead.agent_id)?;
        identifier(&lead.agent_type)?;
        session_id(&lead.session_id)?;
        ensure!(lead.phase == Phase::Ready, "Lead must be a ready instance");
        ensure!(
            !spawn_types.is_empty() && spawn_types.len() <= 128,
            "Invalid registered agent types"
        );
        for kind in &spawn_types {
            identifier(kind)?;
        }
        Ok(Self {
            policy,
            spawn_types,
            instances: BTreeMap::from([(lead.agent_id.clone(), lead)]),
            requests: BTreeMap::new(),
        })
    }
    pub fn instance(&self, id: &str) -> Option<&Instance> {
        self.instances.get(id)
    }
    pub fn request(&self, id: &str) -> Option<&SpawnRequest> {
        self.requests.get(id)
    }
    pub fn instances(&self) -> impl Iterator<Item = &Instance> {
        self.instances.values()
    }
    /// Must run within the adapter's serialized team transaction. Allocate the
    /// canonical child session reference only for the first reservation; duplicates
    /// cannot launch more work, even if the original instance is now closed.
    pub fn reserve(
        &mut self,
        request: SpawnRequest,
        allocate_session: impl FnOnce() -> String,
    ) -> Result<Reservation> {
        request.workspace.validate()?;
        if let Some(source) = &request.source {
            source.validate()?;
        }
        if let Some(model) = &request.model {
            model.validate()?;
        }
        identifier(&request.agent_id)?;
        identifier(&request.agent_type)?;
        text(&request.message, 16000)?;
        crate::team_briefing::validate(
            request.title.as_deref(),
            &request.message,
            request.background.as_deref(),
        )?;
        ensure!(
            self.spawn_types.contains(&request.agent_type),
            "Agent type is not registered for this team"
        );
        if let Some(instance) = self.instances.get(&request.agent_id) {
            ensure!(self.requests.get(&request.agent_id) == Some(&request), "Instance ID already belongs to a different spawn request; use send_message for follow-up work");
            return Ok(Reservation {
                instance: instance.clone(),
                created: false,
            });
        }
        ensure!(
            self.instances.len() < 4096
                && self
                    .instances
                    .values()
                    .filter(|i| i.phase != Phase::Closed)
                    .count()
                    < self.policy.max_instances,
            "Team instance capacity reached"
        );
        let sid = allocate_session();
        session_id(&sid)?;
        ensure!(
            !self.instances.values().any(|i| i.session_id == sid),
            "Session already belongs to an instance"
        );
        let instance = Instance {
            agent_type: request.agent_type.clone(),
            agent_id: request.agent_id.clone(),
            session_id: sid,
            phase: Phase::Reserved,
        };
        self.requests.insert(request.agent_id.clone(), request);
        self.instances
            .insert(instance.agent_id.clone(), instance.clone());
        Ok(Reservation {
            instance,
            created: true,
        })
    }
    pub fn ready(&mut self, id: &str, sid: &str) -> Result<()> {
        let i = self.instances.get_mut(id).context("Unknown instance")?;
        ensure!(
            i.session_id == sid && matches!(i.phase, Phase::Reserved | Phase::Ready),
            "Instance reference changed or was closed"
        );
        i.phase = Phase::Ready;
        Ok(())
    }
    pub fn retire(&mut self, id: &str) -> Result<()> {
        let i = self.instances.get_mut(id).context("Unknown instance")?;
        ensure!(i.phase != Phase::Closed, "Instance already closed");
        i.phase = Phase::Retiring;
        Ok(())
    }
    pub fn close(&mut self, id: &str) -> Result<()> {
        self.instances
            .get_mut(id)
            .context("Unknown instance")?
            .phase = Phase::Closed;
        Ok(())
    }
    fn sender(&self, id: &str) -> Result<()> {
        ensure!(
            self.instances
                .get(id)
                .is_some_and(|i| matches!(i.phase, Phase::Ready | Phase::Retiring)),
            "Sender is not an active team instance"
        );
        Ok(())
    }
    fn recipient(&self, id: &str) -> Result<Instance> {
        self.instances
            .get(id)
            .filter(|i| matches!(i.phase, Phase::Ready | Phase::Reserved))
            .cloned()
            .context("Mention/recipient is not a current team instance")
    }
    /// Resolve once when posting and persist this exact recipient snapshot with
    /// the board message. Do not expand @all again when reading or delivering it.
    pub fn board_recipients(&self, sender: &str, body: &str) -> Result<Vec<Instance>> {
        ensure!(
            self.policy.communication.board,
            "Board communication is disabled"
        );
        self.sender(sender)?;
        text(body, 4000)?;
        let mut recipients = BTreeSet::new();
        for mention in mentions(body) {
            if mention == "all" {
                recipients.extend(
                    self.instances
                        .values()
                        .filter(|i| {
                            i.agent_id != sender
                                && matches!(i.phase, Phase::Ready | Phase::Reserved)
                        })
                        .map(|i| i.agent_id.clone()),
                );
            } else {
                self.recipient(&mention)?;
                recipients.insert(mention);
            }
        }
        recipients
            .into_iter()
            .map(|id| self.recipient(&id))
            .collect()
    }
    pub fn direct_recipient(&self, sender: &str, target: &str, body: &str) -> Result<Instance> {
        ensure!(
            self.policy.communication.direct_messages,
            "Direct communication is disabled; no board message was posted"
        );
        self.sender(sender)?;
        text(body, 4000)?;
        self.recipient(target)
    }
}
/// Mentions are exact instance tokens, not email addresses. Escaped @ and code
/// literals are ordinary board text. No fuzzy matching or implicit role broadcast.
fn mentions(body: &str) -> Vec<String> {
    let bytes = body.as_bytes();
    let mut out = vec![];
    let mut i = 0;
    let mut code = 0;
    while i < bytes.len() {
        if bytes[i] == b'\\' {
            i += 2;
            continue;
        }
        if bytes[i] == b'`' {
            let start = i;
            while i < bytes.len() && bytes[i] == b'`' {
                i += 1;
            }
            let run = i - start;
            if code == 0 {
                code = run;
            } else if code == run {
                code = 0;
            }
            continue;
        }
        if code == 0
            && bytes[i] == b'@'
            && (i == 0 || bytes[i - 1].is_ascii_whitespace() || b"([{,:;".contains(&bytes[i - 1]))
        {
            let start = i + 1;
            let mut end = start;
            while end < bytes.len()
                && (bytes[end].is_ascii_alphanumeric() || b"_-".contains(&bytes[end]))
            {
                end += 1;
            }
            if end > start {
                out.push(body[start..end].to_owned());
            }
            i = end;
        } else {
            i += 1;
        }
    }
    out
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum Activity {
    Busy,
    Idle,
    Waiting,
    Starting,
    Paused,
    Stopped,
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum Delivery {
    NextModelCall,
    Wake,
    Retain,
}
pub fn delivery(activity: Activity) -> Delivery {
    match activity {
        Activity::Busy => Delivery::NextModelCall,
        Activity::Idle | Activity::Waiting => Delivery::Wake,
        Activity::Starting | Activity::Paused | Activity::Stopped => Delivery::Retain,
    }
}
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum Direction {
    #[default]
    Before,
    After,
}
fn default_limit() -> usize {
    20
}
#[derive(Clone, Debug, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct HistoryQuery {
    pub message_id: Option<String>,
    #[serde(default)]
    pub direction: Direction,
    #[serde(default = "default_limit")]
    pub limit: usize,
}
impl HistoryQuery {
    pub fn direction(&self) -> Direction {
        if self.message_id.is_none() {
            Direction::Before
        } else {
            self.direction
        }
    }
    pub fn validate(&self) -> Result<()> {
        ensure!(
            (1..=50).contains(&self.limit),
            "History limit must be 1..50"
        );
        if let Some(id) = &self.message_id {
            session_id(id)?;
        }
        Ok(())
    }
}
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub struct BoardMessage {
    pub id: String,
    pub sequence: u64,
    pub sender: String,
    pub body: String,
    pub recipients: Vec<String>,
}
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub struct HistoryPage {
    pub messages: Vec<BoardMessage>,
    pub has_more: bool,
    pub next_message_id: Option<String>,
}
/// Adapters fetch at most limit+1 rows in query order, within this team's range.
/// Normalize to chronological order without loading a team's entire history.
/// An unresolved anchor is an error, never a fallback to another team's history.
pub fn history_page(
    query: &HistoryQuery,
    anchor_sequence: Option<u64>,
    mut rows: Vec<BoardMessage>,
) -> Result<HistoryPage> {
    query.validate()?;
    ensure!(
        query.message_id.is_some() == anchor_sequence.is_some(),
        "History anchor was not resolved in this team"
    );
    ensure!(
        anchor_sequence != Some(0),
        "Invalid history anchor sequence"
    );
    ensure!(
        rows.len() <= query.limit + 1,
        "History adapter exceeded bounded fetch"
    );
    let dir = query.direction();
    let mut ids = BTreeSet::new();
    for (n, row) in rows.iter().enumerate() {
        ensure!(
            row.sequence > 0 && ids.insert(&row.id),
            "Invalid or duplicate board message"
        );
        if let Some(anchor) = anchor_sequence {
            ensure!(
                match dir {
                    Direction::Before => row.sequence < anchor,
                    Direction::After => row.sequence > anchor,
                },
                "History anchor must be exclusive"
            );
        }
        if n > 0 {
            ensure!(
                match dir {
                    Direction::Before => rows[n - 1].sequence > row.sequence,
                    Direction::After => rows[n - 1].sequence < row.sequence,
                },
                "History adapter returned unordered messages"
            );
        }
    }
    let has_more = rows.len() > query.limit;
    rows.truncate(query.limit);
    if dir == Direction::Before {
        rows.reverse();
    }
    let next_message_id = if has_more {
        match dir {
            Direction::Before => rows.first(),
            Direction::After => rows.last(),
        }
        .map(|m| m.id.clone())
    } else {
        None
    };
    Ok(HistoryPage {
        messages: rows,
        has_more,
        next_message_id,
    })
}