Teams

The teams module provides types and a SQLite-backed store for managing teams of agents. It handles team creation, membership, per-team task tracking, lifecycle management, and plan approval workflows.

Design Philosophy

1. Persistence-first — All team state is stored in SQLite for durability
2. Lifecycle-aware — Teams have explicit states (active, disbanded, archived)
3. Task integration — Teams can have shared tasks with per-member assignments

Core Types

Team

pub struct Team {
    pub id: TeamId,
    pub name: String,
    pub description: String,
    pub status: TeamStatus,
    pub members: Vec<TeamMember>,
    pub created_at: DateTime<Utc>,
}

TeamStatus

pub enum TeamStatus {
    Active,
    Disbanded,
    Archived,
}

TeamMember

pub struct TeamMember {
    pub id: MemberId,
    pub name: String,
    pub role: TeamRole,
    pub status: MemberStatus,
}

pub enum TeamRole {
    Leader,
    Member,
    Observer,
}

TeamTask

pub struct TeamTask {
    pub id: TaskId,
    pub title: String,
    pub assignee: Option<MemberId>,
    pub status: TeamTaskStatus,
}

pub enum TeamTaskStatus {
    Pending,
    InProgress,
    Completed,
    Blocked,
}

TeamStore

SQLite-backed persistence:

pub trait TeamStore: Send + Sync {
    async fn create_team(
        &self,
        team: &NewTeam,
    ) -> Result<TeamId>;

    async fn add_member(
        &self,
        team_id: TeamId,
        member: &NewTeamMember,
    ) -> Result<()>;

    async fn get_team(
        &self,
        team_id: TeamId,
    ) -> Result<Option<Team>>;

    async fn list_teams(
        &self,
    ) -> Result<Vec<TeamSummary>>;

    async fn create_task(
        &self,
        team_id: TeamId,
        task: &NewTeamTask,
    ) -> Result<TaskId>;
}

SqliteTeamStore

pub struct SqliteTeamStore {
    pool: SqlitePool,
}

Safety:

• All queries use parameterized params![]
• TeamStatus and TeamTaskStatus implement FromSql for proper error propagation (no unwrap_or_default)
• Uses tokio::sync::Mutex (no poisoning)

Lifecycle

Created → Active → [Disbanded | Archived]

Transitions:

• Created → Active — Team is ready for use
• Active → Disbanded — Team is disbanded (members removed)
• Active → Archived — Team is archived (read-only)

Validation: Operations check team status before proceeding. Adding members to a disbanded team returns an error.

Events

pub enum TeamEvent {
    TeamCreated { team_id: TeamId },
    MemberJoined { team_id: TeamId, member_id: MemberId },
    MemberLeft { team_id: TeamId, member_id: MemberId },
    TaskCreated { team_id: TeamId, task_id: TaskId },
    TaskCompleted { team_id: TeamId, task_id: TaskId },
}

Artifacts

Teams can produce shared artifacts:

pub struct TeamArtifact {
    pub id: ArtifactId,
    pub name: String,
    pub content_type: String,
    pub content: Vec<u8>,
}

Safety Properties

• No SQL injection — Parameterized queries throughout
• No lock poisoning — Uses tokio::sync::Mutex
• Type-safe status — FromSql implementations prevent silent parsing failures
• No unwrap in production — All database operations return Result

Code Location

• src/teams/mod.rs — Module entry point
• src/teams/store.rs — TeamStore trait and SQLite implementation
• src/teams/types.rs — Core types
• src/teams/lifecycle.rs — Lifecycle management
• src/teams/events.rs — Event definitions
• src/teams/artifacts.rs — Artifact management
• src/teams/plans.rs — Plan approval workflow
• src/teams/context.rs — Team context for agents
• src/teams/sessions/ — Session management
• src/teams/messages/ — Team messaging

See Also

• Agent Runtime — How agents spawn and manage tasks
• Group Chat — Multi-persona discussions
• Arena — Multi-agent collaboration workspace