use crate::error::{PackageError, Result};
use crate::reference::{ComponentRef, PinnedRef};
use crate::slot::{ConfigSlot, SlotType};
use serde::{Deserialize, Serialize};
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum TeamRole {
EntryPoint,
Member,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct TeamMember {
pub agent: ComponentRef,
pub role: TeamRole,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct HumanRole {
pub role: String,
pub description: String,
pub responsibilities: Vec<String>,
pub channel_hints: Vec<String>,
}
impl HumanRole {
pub fn to_config_slot(&self) -> ConfigSlot {
ConfigSlot::new(SlotType::HumanRole {
role: self.role.clone(),
description: self.description.clone(),
responsibilities: self.responsibilities.clone(),
channel_hints: self.channel_hints.clone(),
})
}
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct TeamLimits {
pub max_team_depth: i64,
pub max_team_total_tokens: i64,
pub max_team_wall_clock_seconds: i64,
pub poll_interval_ms: i64,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct TeamPackage {
pub name: String,
pub version: semver::Version,
pub entry_point: ComponentRef,
pub members: Vec<TeamMember>,
pub human_roles: Vec<HumanRole>,
pub limits: TeamLimits,
pub built_in_servers: Vec<ComponentRef>,
pub finalizer_agents: Vec<ComponentRef>,
pub budget_defaults: Vec<ConfigSlot>,
pub config_slots: Vec<ConfigSlot>,
}
impl TeamPackage {
fn component_refs(&self) -> impl Iterator<Item = &ComponentRef> {
std::iter::once(&self.entry_point)
.chain(self.members.iter().map(|member| &member.agent))
.chain(self.built_in_servers.iter())
.chain(self.finalizer_agents.iter())
}
pub fn pinned_components(&self) -> Result<Vec<&PinnedRef>> {
self.component_refs()
.map(|component| {
component
.as_pinned()
.ok_or_else(|| PackageError::InvalidReference {
reason: format!(
"component '{}' ({:?}) is a Range, not a Pin — an attested \
TeamPackage may only contain exact pins. This guard is one \
level deep: it covers this team's own entry_point, members' \
agents, built_in_servers and finalizer_agents, and cannot see \
inside a pinned component's own references.",
component.name(),
component.component_type(),
),
})
})
.collect()
}
pub fn validate_all_pinned(&self) -> Result<()> {
self.pinned_components().map(|_| ())
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::digest::ManifestDigest;
use crate::reference::{ComponentType, PinnedRef};
fn sample_human_role() -> HumanRole {
HumanRole {
role: "approver".to_string(),
description: "Approves budget overrides".to_string(),
responsibilities: vec!["review".to_string(), "approve".to_string()],
channel_hints: vec!["slack".to_string()],
}
}
fn sample_team_package() -> TeamPackage {
let entry_point = ComponentRef::Range {
name: "triage-agent".to_string(),
range: semver::VersionReq::parse("^1").unwrap(),
component_type: ComponentType::Agent,
};
let human_role = sample_human_role();
TeamPackage {
name: "support-team".to_string(),
version: semver::Version::parse("1.0.0").unwrap(),
entry_point: entry_point.clone(),
members: vec![TeamMember {
agent: entry_point,
role: TeamRole::EntryPoint,
}],
human_roles: vec![human_role.clone()],
limits: TeamLimits {
max_team_depth: 3,
max_team_total_tokens: 200_000,
max_team_wall_clock_seconds: 600,
poll_interval_ms: 2000,
},
built_in_servers: vec![ComponentRef::Range {
name: "team-fs".to_string(),
range: semver::VersionReq::parse("^1").unwrap(),
component_type: ComponentType::Server,
}],
finalizer_agents: vec![],
budget_defaults: vec![],
config_slots: vec![human_role.to_config_slot()],
}
}
fn sample_pinned(name: &str, component_type: ComponentType) -> ComponentRef {
ComponentRef::Pinned(PinnedRef {
name: name.to_string(),
component_type,
version: semver::Version::parse("1.0.0").unwrap(),
digest: ManifestDigest::from_bytes(name.as_bytes()),
resolved_from: None,
})
}
fn sample_range(name: &str, component_type: ComponentType) -> ComponentRef {
ComponentRef::Range {
name: name.to_string(),
range: semver::VersionReq::parse("^1").unwrap(),
component_type,
}
}
fn fully_pinned_team_package() -> TeamPackage {
let mut team = sample_team_package();
team.entry_point = sample_pinned("triage-agent", ComponentType::Agent);
team.members = vec![
TeamMember {
agent: sample_pinned("triage-agent", ComponentType::Agent),
role: TeamRole::EntryPoint,
},
TeamMember {
agent: sample_pinned("reviewer-agent", ComponentType::Agent),
role: TeamRole::Member,
},
];
team.built_in_servers = vec![sample_pinned("team-fs", ComponentType::Server)];
team.finalizer_agents = vec![sample_pinned("formatter-agent", ComponentType::Agent)];
team
}
fn total_reference_count(team: &TeamPackage) -> usize {
1 + team.members.len() + team.built_in_servers.len() + team.finalizer_agents.len()
}
#[test]
fn pinned_components_returns_every_pin_from_all_four_surfaces() {
let team = fully_pinned_team_package();
let expected = total_reference_count(&team);
assert!(
expected > 3,
"the fixture must carry more references than it has surfaces, or an omitted \
surface would not change the count"
);
let pins = team
.pinned_components()
.expect("a fully pinned team must pass");
assert_eq!(
pins.len(),
expected,
"every reference across entry_point, members[].agent, built_in_servers and \
finalizer_agents must be returned — a short vector means a surface was skipped"
);
let names: Vec<&str> = pins.iter().map(|pin| pin.name.as_str()).collect();
assert_eq!(
names,
vec![
"triage-agent",
"triage-agent",
"reviewer-agent",
"team-fs",
"formatter-agent"
]
);
}
#[test]
fn a_range_entry_point_fails_and_names_that_component() {
let mut team = fully_pinned_team_package();
team.entry_point = sample_range("unresolved-entry", ComponentType::Agent);
let err = team
.pinned_components()
.expect_err("an unresolved entry_point must fail the guard");
assert!(matches!(err, PackageError::InvalidReference { .. }));
let rendered = err.to_string();
assert!(
rendered.contains("unresolved-entry"),
"the error must name the offending component; got: {rendered}"
);
assert!(
rendered.contains("Agent"),
"the error must name the component_type, so a same-named server and agent are \
distinguishable; got: {rendered}"
);
}
#[test]
fn a_range_built_in_server_fails_and_names_that_component() {
let mut team = fully_pinned_team_package();
team.built_in_servers = vec![sample_range("unresolved-server", ComponentType::Server)];
let err = team
.pinned_components()
.expect_err("an unresolved built_in_server must fail the guard");
let rendered = err.to_string();
assert!(
rendered.contains("unresolved-server"),
"a traversal that stopped at entry_point would never reach this; got: {rendered}"
);
assert!(rendered.contains("Server"), "got: {rendered}");
}
#[test]
fn a_range_member_agent_fails_and_names_that_component() {
let mut team = fully_pinned_team_package();
team.members[1].agent = sample_range("unresolved-member", ComponentType::Agent);
let err = team
.pinned_components()
.expect_err("an unresolved member agent must fail the guard");
let rendered = err.to_string();
assert!(
rendered.contains("unresolved-member"),
"a traversal that stopped earlier would never reach this; got: {rendered}"
);
assert!(rendered.contains("Agent"), "got: {rendered}");
}
#[test]
fn a_range_finalizer_agent_fails_and_names_that_component() {
let mut team = fully_pinned_team_package();
team.finalizer_agents = vec![sample_range("unresolved-finalizer", ComponentType::Agent)];
let err = team
.pinned_components()
.expect_err("an unresolved finalizer agent must fail the guard");
let rendered = err.to_string();
assert!(
rendered.contains("unresolved-finalizer"),
"finalizer_agents is the last link in the chain and the easiest to omit; \
got: {rendered}"
);
}
#[test]
fn validate_all_pinned_passes_a_pinned_team_and_fails_any_unpinned_one() {
let pinned = fully_pinned_team_package();
assert!(pinned.validate_all_pinned().is_ok());
let unpinned = sample_team_package();
let err = unpinned
.validate_all_pinned()
.expect_err("a team holding any Range must fail");
assert!(matches!(err, PackageError::InvalidReference { .. }));
}
#[test]
fn the_error_states_the_one_level_depth_limit() {
let mut team = fully_pinned_team_package();
team.entry_point = sample_range("unresolved-entry", ComponentType::Agent);
let rendered = team.pinned_components().unwrap_err().to_string();
assert!(
rendered.contains("one level deep"),
"a caller must not mistake a passing team for a transitively resolved one; \
got: {rendered}"
);
}
#[test]
fn the_returned_pin_order_is_deterministic_across_runs() {
let team = fully_pinned_team_package();
let first: Vec<String> = team
.pinned_components()
.unwrap()
.iter()
.map(|pin| pin.name.clone())
.collect();
for _ in 0..50 {
let next: Vec<String> = team
.pinned_components()
.unwrap()
.iter()
.map(|pin| pin.name.clone())
.collect();
assert_eq!(next, first, "traversal order must not vary between calls");
}
let rebuilt = fully_pinned_team_package();
let rebuilt_names: Vec<String> = rebuilt
.pinned_components()
.unwrap()
.iter()
.map(|pin| pin.name.clone())
.collect();
assert_eq!(rebuilt_names, first);
}
#[test]
fn team_package_round_trips_losslessly() {
let pkg = sample_team_package();
let json = serde_json::to_string(&pkg).unwrap();
let back: TeamPackage = serde_json::from_str(&json).unwrap();
assert_eq!(back, pkg);
}
#[test]
fn team_role_round_trips_with_snake_case_discriminator() {
let json = serde_json::to_value(TeamRole::EntryPoint).unwrap();
assert_eq!(json, serde_json::json!("entry_point"));
let back: TeamRole = serde_json::from_value(json).unwrap();
assert_eq!(back, TeamRole::EntryPoint);
}
#[test]
fn human_role_has_no_identity_field() {
let role = sample_human_role();
let json = serde_json::to_value(&role).unwrap();
let obj = json.as_object().unwrap();
assert!(!obj.contains_key("user_id"));
assert!(!obj.contains_key("userId"));
assert!(!obj.contains_key("channel_id"));
assert!(!obj.contains_key("channelId"));
assert!(!obj.contains_key("email"));
assert!(!obj.contains_key("channel_address"));
assert!(!obj.contains_key("channelAddress"));
}
#[test]
fn human_role_maps_to_human_role_config_slot() {
let role = sample_human_role();
let slot = role.to_config_slot();
assert_eq!(slot.slot.key(), ("human_role", "approver"));
}
}