Teams

The teams module provides team management for multi-agent collaboration, enabling structured teamwork with lifecycle management, plan approval, and task tracking.

Overview

Teams enables:

• Team creation — Define teams of agents with a designated leader and members
• Strategic coordination ("Team Strata") — The leader plans first; the plan is welded into every member's prompt
• Coord Tasks — Per-member task assignment with a Pending → InProgress → WaitingReview → Completed lifecycle
• Verification loop — The leader accepts or rejects member deliverables before they are considered done
• Lifecycle management — Track team state from formation to completion
• SQLite persistence — Durable storage for team data

Architecture

TeamStore (SQLite)
  ├── Team — Team definition and metadata
  ├── TeamMember — Membership and roles
  ├── Plans — Team plans and approval state
  ├── Sessions — Active team sessions
  └── Artifacts — Deliverables and outputs

Core Components

TeamStore

SQLite-backed storage for team data:

// src/teams/store.rs
pub trait TeamStore: Send + Sync {
    fn create_team(&self, team: NewTeam) -> Result<TeamId>;
    fn get_team(&self, id: TeamId) -> Result<Option<Team>>;
    fn list_teams(&self) -> Result<Vec<TeamSummary>>;
    fn add_member(
        &self, 
        team_id: TeamId, 
        member: NewTeamMember
    ) -> Result<()>;
    fn update_status(
        &self, 
        id: TeamId, 
        status: TeamStatus
    ) -> Result<()>;
}

pub struct SqliteTeamStore {
    conn: rusqlite::Connection,
}

Team Types

// src/teams/types.rs
pub struct Team {
    pub id: TeamId,
    pub name: String,
    pub description: String,
    pub status: TeamStatus,
    pub created_at: DateTime<Utc>,
}

pub struct TeamMember {
    pub id: MemberId,
    pub team_id: TeamId,
    pub agent_id: AgentId,
    pub role: TeamRole,
    pub permissions: Permissions,
}

pub enum TeamStatus {
    Forming,
    Active,
    Paused,
    Completed,
    Disbanded,
}

Lifecycle

Team lifecycle management:

// src/teams/lifecycle.rs
pub struct TeamLifecycle;

impl TeamLifecycle {
    pub fn can_transition(
        from: TeamStatus,
        to: TeamStatus,
    ) -> bool;
    
    pub fn on_forming(team: &mut Team);
    pub fn on_active(team: &mut Team);
    pub fn on_completed(team: &mut Team);
}

Plans

Plan approval workflow:

// src/teams/plans.rs
pub struct TeamPlan {
    pub id: PlanId,
    pub team_id: TeamId,
    pub title: String,
    pub steps: Vec<PlanStep>,
    pub approval_state: ApprovalState,
}

pub enum ApprovalState {
    Draft,
    PendingReview,
    Approved,
    Rejected,
}

Strategic Coordination ("Team Strata")

Teams have a leader and members. On a team's first message, the leader plans first — before any member begins work. This planning pass fires once per team (a fire-once strategy keyed by the team), and the resulting plan is welded into every member's prompt so that all members share the same strategic context.

First message to a team
        │
        ▼
  Leader plans first  ──►  Strategy (fire-once, keyed by team)
        │
        ▼
  Plan welded into every member's prompt
        │
        ▼
  Members work under assigned Coord Tasks

Members do not act independently of the plan: each member operates against an assigned Coord Task, and the welded plan keeps their work aligned with the leader's strategy.

Coord Tasks & the Verification Loop

Each member works under a Coord Task whose status moves through a fixed lifecycle:

Pending → InProgress → WaitingReview → Completed

When a member submits a deliverable, the task enters WaitingReview and a synthetic re-dispatch deterministically routes the submission back to the leader for review. The leader accepts or rejects the deliverable using the task_review tool:

// task_review tool call
{
  "task_id": "<coord-task-id>",
  "verdict": "approve",   // or "reject"
  "feedback": "..."        // optional
}

An approve verdict advances the task to Completed; a reject verdict sends it back for rework. This loop keeps deliverables under the leader's control rather than being auto-accepted on submission.

Coord Tasks & the group-chat broadcaster

CoordTaskStore is threaded into the group-chat broadcaster, so task state and the team work-thread stay in sync. A member task submit is the trigger for the deterministic re-dispatch described above: the broadcaster routes the submission to the leader, who reviews it via task_review. The durable team work-thread is what later powers the attribution-bubble replay in the group chat window.

Configuration

[teams]
enabled = true
max_team_size = 10
require_plan_approval = true

JSON-RPC Surface

Teams are driven over JSON-RPC. The confirmed teams.* methods:

The durable per-team group-chat thread is exposed through teams.chat.send / teams.chat.thread / teams.chat.history; this history powers the attribution-bubble replay in the group chat window. The agents.teams method returns a team list augmented with a small members_preview and last_message.

The leader's accept/reject decision is taken via the task_review tool (not a JSON-RPC method). Members work under Coord Tasks created/updated through teams.create_task / teams.update_task.

Code Location

• src/teams/mod.rs — Module entry point
• src/teams/store.rs — SQLite storage
• src/teams/types.rs — Core types
• src/teams/lifecycle.rs — Lifecycle management
• src/teams/plans.rs — Plan approval
• src/teams/sessions.rs — Active sessions
• src/teams/artifacts.rs — Deliverables
• src/teams/messages.rs — Team messaging
• src/teams/context.rs — Shared context
• src/teams/events.rs — Team events

See Also

• Group Chat — Multi-persona conversations
• A2A — Agent-to-Agent protocol
• Orchestrator — Agent orchestration