use std::collections::BTreeMap;
use chrono::{DateTime, Utc};
use serde::{Deserialize, Serialize};
use serde_json::Value;
use thiserror::Error;
use crate::durable::{ArtifactContract, ErrorClass};
use crate::llm::Usage;
use crate::record::{Effect, PayloadRef};
pub const AGENT_RECIPIENT_PREFIX: &str = "agent:";
#[derive(Debug, Clone, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize)]
#[serde(transparent)]
pub struct AgentId(pub String);
impl AgentId {
pub fn new(id: impl Into<String>) -> Self {
Self(id.into())
}
pub fn as_str(&self) -> &str {
&self.0
}
pub fn mailbox_recipient(&self) -> String {
format!("{AGENT_RECIPIENT_PREFIX}{}", self.0)
}
pub fn thread_id(&self) -> String {
format!("{AGENT_RECIPIENT_PREFIX}{}", self.0)
}
}
impl std::fmt::Display for AgentId {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.write_str(&self.0)
}
}
pub fn agent_id_from_recipient(recipient: &str) -> Option<&str> {
recipient.strip_prefix(AGENT_RECIPIENT_PREFIX)
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum StateScope {
Private,
Team,
User,
Tenant,
}
#[derive(Debug, Clone, PartialEq, Default, Serialize, Deserialize)]
pub struct AgentBudget {
#[serde(default, skip_serializing_if = "Option::is_none")]
pub max_tokens: Option<u64>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub max_cost_usd: Option<f64>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub deadline: Option<DateTime<Utc>>,
}
pub const ESCALATION_MESSAGE_KIND: &str = "escalated";
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum RestartPolicy {
Permanent,
Transient,
Temporary,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum SupervisionTrigger {
TurnFailed,
DeadlineBreached,
ManualRestart,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct SupervisionAttempt {
pub ordinal: u32,
pub trigger: SupervisionTrigger,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub error_class: Option<ErrorClass>,
pub message: String,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub task_id: Option<String>,
pub at: DateTime<Utc>,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct SupervisionPolicy {
pub restart: RestartPolicy,
pub intensity: u32,
pub period_ms: u64,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub supervisor: Option<String>,
}
impl SupervisionPolicy {
pub fn new(restart: RestartPolicy, intensity: u32, period_ms: u64) -> Self {
Self {
restart,
intensity,
period_ms,
supervisor: None,
}
}
pub fn allows_restart_after(&self, error_class: Option<ErrorClass>) -> bool {
match self.restart {
RestartPolicy::Permanent => true,
RestartPolicy::Transient => {
matches!(error_class, Some(class) if class != ErrorClass::Cancelled)
}
RestartPolicy::Temporary => false,
}
}
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct EscalationNotice {
pub agent_id: String,
pub policy: SupervisionPolicy,
pub attempts: Vec<SupervisionAttempt>,
pub escalated_at: DateTime<Utc>,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct CapabilityManifest {
pub agent_kind: String,
pub manifest_version: String,
#[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
pub accepts: BTreeMap<String, ArtifactContract>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub scopes: Vec<StateScope>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub budget: Option<AgentBudget>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub supervision: Option<SupervisionPolicy>,
}
impl CapabilityManifest {
pub fn new(agent_kind: impl Into<String>, manifest_version: impl Into<String>) -> Self {
Self {
agent_kind: agent_kind.into(),
manifest_version: manifest_version.into(),
accepts: BTreeMap::new(),
scopes: Vec::new(),
budget: None,
supervision: None,
}
}
pub fn accepts_kind(&self, kind: &str) -> Option<&ArtifactContract> {
self.accepts.get(kind)
}
}
pub const COORDINATION_RESULT_KIND: &str = "coordination_result";
pub fn is_coordination_result(kind: &str) -> bool {
kind == COORDINATION_RESULT_KIND
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum CoordinationKind {
Delegate,
FanOut,
Race,
Quorum,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum MemberFailurePolicy {
FailFast,
Partial,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum MemberSettlement {
Completed,
Failed,
Cancelled,
Dead,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum CoordinationStatus {
Completed,
Failed,
Cancelled,
Unreachable,
}
#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
pub struct ContextGrant {
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub scopes: Vec<StateScope>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub channels: Vec<String>,
}
impl ContextGrant {
pub fn narrows(&self, declared: &[StateScope]) -> bool {
self.scopes.iter().all(|scope| declared.contains(scope))
}
}
fn default_effect_non_idempotent() -> Effect {
Effect::NonIdempotent
}
fn is_false(value: &bool) -> bool {
!*value
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct Delegation {
pub member: String,
pub agent_id: String,
pub manifest_version: String,
pub kind: String,
pub input: PayloadRef,
#[serde(default = "default_effect_non_idempotent")]
pub effect: Effect,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub deadline: Option<DateTime<Utc>>,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct DelegateContract {
pub delegate: Delegation,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub context: Option<ContextGrant>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub result_contract: Option<ArtifactContract>,
#[serde(default, skip_serializing_if = "is_false")]
pub handoff: bool,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct FanOutContract {
pub members: Vec<Delegation>,
pub max_in_flight: u32,
pub on_member_failure: MemberFailurePolicy,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct RaceContract {
pub candidates: Vec<Delegation>,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(tag = "resolver", rename_all = "snake_case")]
pub enum QuorumResolver {
MajorityEqual,
FirstK,
Custom {
name: String,
},
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct QuorumContract {
pub members: Vec<Delegation>,
pub threshold: u32,
pub resolver: QuorumResolver,
}
#[derive(Debug, Clone, PartialEq, Eq, Error)]
pub enum CoordinationViolation {
#[error(
"race candidate '{member}' declares effect '{effect}', which is not freely \
repeatable: a race loser may be cancelled at any point, so every candidate \
must be safe to abandon"
)]
RaceEffectNotFreelyRepeatable {
member: String,
effect: String,
},
#[error("{pattern} declares no members")]
EmptyMembers {
pattern: String,
},
#[error(
"{pattern} declares member '{member}' twice; member names label task ids \
and dispositions and must be unique within a pattern"
)]
DuplicateMember {
pattern: String,
member: String,
},
#[error(
"fan-out max_in_flight must be at least 1: the window is the backpressure \
guarantee, and a zero window can never make progress"
)]
MaxInFlightZero,
#[error(
"quorum threshold {threshold} is out of range 1..={members}: the threshold \
is a hard floor and is never silently clamped"
)]
QuorumThresholdOutOfRange {
threshold: u32,
members: usize,
},
#[error(
"custom quorum resolver '{name}' is not supported in wave 3: resolvers are \
majority_equal and first_k; the custom wire shape is pinned for a later \
resolver registry"
)]
CustomResolverUnsupported {
name: String,
},
}
fn effect_wire_name(effect: Effect) -> &'static str {
match effect {
Effect::Pure => "pure",
Effect::ReadOnly => "read_only",
Effect::Idempotent => "idempotent",
Effect::Compensatable => "compensatable",
Effect::NonIdempotent => "non_idempotent",
}
}
fn duplicate_member(members: &[Delegation]) -> Option<&str> {
for (i, m) in members.iter().enumerate() {
if members[..i]
.iter()
.any(|earlier| earlier.member == m.member)
{
return Some(m.member.as_str());
}
}
None
}
impl RaceContract {
pub fn validate(&self) -> Result<(), CoordinationViolation> {
if self.candidates.is_empty() {
return Err(CoordinationViolation::EmptyMembers {
pattern: "race".to_string(),
});
}
if let Some(member) = duplicate_member(&self.candidates) {
return Err(CoordinationViolation::DuplicateMember {
pattern: "race".to_string(),
member: member.to_string(),
});
}
for candidate in &self.candidates {
if !candidate.effect.is_freely_repeatable() {
return Err(CoordinationViolation::RaceEffectNotFreelyRepeatable {
member: candidate.member.clone(),
effect: effect_wire_name(candidate.effect).to_string(),
});
}
}
Ok(())
}
}
impl FanOutContract {
pub fn validate(&self) -> Result<(), CoordinationViolation> {
if self.members.is_empty() {
return Err(CoordinationViolation::EmptyMembers {
pattern: "fan_out".to_string(),
});
}
if let Some(member) = duplicate_member(&self.members) {
return Err(CoordinationViolation::DuplicateMember {
pattern: "fan_out".to_string(),
member: member.to_string(),
});
}
if self.max_in_flight == 0 {
return Err(CoordinationViolation::MaxInFlightZero);
}
Ok(())
}
}
impl QuorumContract {
pub fn validate(&self) -> Result<(), CoordinationViolation> {
if self.members.is_empty() {
return Err(CoordinationViolation::EmptyMembers {
pattern: "quorum".to_string(),
});
}
if let Some(member) = duplicate_member(&self.members) {
return Err(CoordinationViolation::DuplicateMember {
pattern: "quorum".to_string(),
member: member.to_string(),
});
}
if self.threshold == 0 || self.threshold as usize > self.members.len() {
return Err(CoordinationViolation::QuorumThresholdOutOfRange {
threshold: self.threshold,
members: self.members.len(),
});
}
if let QuorumResolver::Custom { name } = &self.resolver {
return Err(CoordinationViolation::CustomResolverUnsupported { name: name.clone() });
}
Ok(())
}
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct QuorumTally {
pub output: Value,
pub votes: u32,
}
#[derive(Debug, Clone, PartialEq)]
pub enum QuorumOutcome {
Decided {
output: Value,
},
FirstK {
outputs: Vec<Value>,
},
NoMajority {
tallies: Vec<QuorumTally>,
},
}
pub fn resolve_quorum(
resolver: &QuorumResolver,
accepted: &[(String, Value)],
) -> Result<QuorumOutcome, CoordinationViolation> {
let mut accepted: Vec<&(String, Value)> = accepted.iter().collect();
accepted.sort_by(|a, b| a.0.cmp(&b.0));
match resolver {
QuorumResolver::FirstK => Ok(QuorumOutcome::FirstK {
outputs: accepted
.iter()
.map(|(_, output)| (*output).clone())
.collect(),
}),
QuorumResolver::MajorityEqual => {
let mut tallies: Vec<QuorumTally> = Vec::new();
for (_, output) in &accepted {
match tallies.iter_mut().find(|t| t.output == *output) {
Some(tally) => tally.votes += 1,
None => tallies.push(QuorumTally {
output: (*output).clone(),
votes: 1,
}),
}
}
tallies.sort_by(|a, b| {
b.votes
.cmp(&a.votes)
.then_with(|| a.output.to_string().cmp(&b.output.to_string()))
});
let total = accepted.len() as u32;
match tallies.first() {
Some(winner) if winner.votes * 2 > total => Ok(QuorumOutcome::Decided {
output: winner.output.clone(),
}),
_ => Ok(QuorumOutcome::NoMajority { tallies }),
}
}
QuorumResolver::Custom { name } => {
Err(CoordinationViolation::CustomResolverUnsupported { name: name.clone() })
}
}
}
pub fn merge_fan_out(results: &[(String, Value)]) -> Vec<Value> {
let mut sorted: Vec<&(String, Value)> = results.iter().collect();
sorted.sort_by(|a, b| a.0.cmp(&b.0));
sorted
.into_iter()
.map(|(_, output)| output.clone())
.collect()
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct MemberDisposition {
pub member: String,
pub task_id: String,
pub settlement: MemberSettlement,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub result: Option<PayloadRef>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub error_class: Option<ErrorClass>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub error: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub tokens: Option<Usage>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub cost_usd: Option<f64>,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct QuorumResolverRecord {
pub resolver: QuorumResolver,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub inputs: Vec<Value>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub output: Option<Value>,
pub decided: bool,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct CoordinationOutcome {
pub coordination_id: String,
pub pattern: CoordinationKind,
pub status: CoordinationStatus,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub result: Option<PayloadRef>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub members: Vec<MemberDisposition>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub wasted_tokens: Option<u64>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub wasted_cost_usd: Option<f64>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub resolver: Option<QuorumResolverRecord>,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(tag = "pattern", rename_all = "snake_case")]
pub enum CoordinationContract {
Delegate(Box<DelegateContract>),
FanOut(FanOutContract),
Race(RaceContract),
Quorum(QuorumContract),
}
impl CoordinationContract {
pub fn kind(&self) -> CoordinationKind {
match self {
Self::Delegate(_) => CoordinationKind::Delegate,
Self::FanOut(_) => CoordinationKind::FanOut,
Self::Race(_) => CoordinationKind::Race,
Self::Quorum(_) => CoordinationKind::Quorum,
}
}
pub fn members(&self) -> Vec<&Delegation> {
match self {
Self::Delegate(c) => vec![&c.delegate],
Self::FanOut(c) => c.members.iter().collect(),
Self::Race(c) => c.candidates.iter().collect(),
Self::Quorum(c) => c.members.iter().collect(),
}
}
pub fn validate(&self) -> Result<(), CoordinationViolation> {
match self {
Self::Delegate(_) => Ok(()),
Self::FanOut(c) => c.validate(),
Self::Race(c) => c.validate(),
Self::Quorum(c) => c.validate(),
}
}
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct CoordinationMessage {
pub coordination_id: String,
pub member: String,
pub pattern: CoordinationKind,
pub input: PayloadRef,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub context: Option<ContextGrant>,
}
#[cfg(test)]
mod tests {
use super::*;
use serde_json::json;
fn sample_manifest() -> CapabilityManifest {
let mut manifest = CapabilityManifest::new("researcher", "researcher/1.4.0");
manifest.accepts.insert(
"summarize".into(),
ArtifactContract {
kind: "application/json".into(),
max_bytes: Some(65_536),
schema: Some(json!({
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {"topic": {"type": "string"}},
"required": ["topic"],
})),
},
);
manifest.scopes = vec![StateScope::Private, StateScope::Team];
manifest.budget = Some(AgentBudget {
max_tokens: Some(250_000),
max_cost_usd: Some(1.50),
deadline: DateTime::<Utc>::from_timestamp_millis(1_800_000_000_000),
});
manifest
}
#[test]
fn agent_id_derives_mailbox_and_thread_addresses() {
let id = AgentId::new("acme/researcher-7");
assert_eq!(id.as_str(), "acme/researcher-7");
assert_eq!(id.mailbox_recipient(), "agent:acme/researcher-7");
assert_eq!(id.thread_id(), "agent:acme/researcher-7");
assert_eq!(
serde_json::to_value(&id).unwrap(),
json!("acme/researcher-7")
);
assert_eq!(id.to_string(), "acme/researcher-7");
}
#[test]
fn recipient_parsing_strips_only_the_agent_prefix() {
assert_eq!(
agent_id_from_recipient("agent:researcher-7"),
Some("researcher-7")
);
assert_eq!(agent_id_from_recipient("pool-default"), None);
assert_eq!(agent_id_from_recipient("agent:"), Some(""));
assert_eq!(agent_id_from_recipient("agents:researcher-7"), None);
}
#[test]
fn state_scope_serde_names_are_snake_case() {
for (scope, name) in [
(StateScope::Private, "private"),
(StateScope::Team, "team"),
(StateScope::User, "user"),
(StateScope::Tenant, "tenant"),
] {
assert_eq!(serde_json::to_value(scope).unwrap(), json!(name));
assert_eq!(
serde_json::from_value::<StateScope>(json!(name)).unwrap(),
scope
);
}
assert!(serde_json::from_value::<StateScope>(json!("global")).is_err());
}
#[test]
fn manifest_serde_roundtrip_and_sparse_wire_shape() {
let manifest = sample_manifest();
let back: CapabilityManifest =
serde_json::from_str(&serde_json::to_string(&manifest).unwrap()).unwrap();
assert_eq!(manifest, back);
let minimal = CapabilityManifest::new("researcher", "researcher/1.4.0");
let value = serde_json::to_value(&minimal).unwrap();
assert_eq!(
value,
json!({"agent_kind": "researcher", "manifest_version": "researcher/1.4.0"})
);
let back: CapabilityManifest = serde_json::from_value(value).unwrap();
assert_eq!(back, minimal);
assert!(back.accepts_kind("summarize").is_none());
}
#[test]
fn manifest_lookup_finds_only_declared_kinds() {
let manifest = sample_manifest();
let contract = manifest.accepts_kind("summarize").expect("declared kind");
assert_eq!(contract.kind, "application/json");
assert!(contract.schema.is_some());
assert!(manifest.accepts_kind("delete_everything").is_none());
}
#[test]
fn artifact_contract_schema_field_is_additive() {
let r06_shape = json!({"kind": "application/json", "max_bytes": 65536});
let contract: ArtifactContract = serde_json::from_value(r06_shape).unwrap();
assert_eq!(contract.schema, None);
assert_eq!(
serde_json::to_value(&contract).unwrap(),
json!({"kind": "application/json", "max_bytes": 65536})
);
let with_schema = ArtifactContract {
kind: "application/json".into(),
max_bytes: None,
schema: Some(json!({"type": "object"})),
};
let back: ArtifactContract =
serde_json::from_str(&serde_json::to_string(&with_schema).unwrap()).unwrap();
assert_eq!(with_schema, back);
}
#[test]
fn agent_event_kinds_stay_additive_to_the_closed_enum() {
use crate::record::RunEventKind;
for (kind, name) in [
(RunEventKind::AgentSpawn, "agent_spawn"),
(RunEventKind::AgentExit, "agent_exit"),
(RunEventKind::MailboxSend, "mailbox_send"),
(RunEventKind::MailboxReceive, "mailbox_receive"),
(RunEventKind::SupervisionEvent, "supervision_event"),
(RunEventKind::CoordinationStart, "coordination_start"),
(RunEventKind::CoordinationEnd, "coordination_end"),
] {
assert_eq!(serde_json::to_value(kind).unwrap(), json!(name));
assert_eq!(
serde_json::from_value::<RunEventKind>(json!(name)).unwrap(),
kind
);
}
assert_eq!(
serde_json::from_value::<RunEventKind>(json!("model_call")).unwrap(),
RunEventKind::ModelCall
);
assert!(serde_json::from_value::<RunEventKind>(json!("agent_magic")).is_err());
}
#[test]
fn restart_policy_and_trigger_serde_names_are_snake_case() {
for (policy, name) in [
(RestartPolicy::Permanent, "permanent"),
(RestartPolicy::Transient, "transient"),
(RestartPolicy::Temporary, "temporary"),
] {
assert_eq!(serde_json::to_value(policy).unwrap(), json!(name));
assert_eq!(
serde_json::from_value::<RestartPolicy>(json!(name)).unwrap(),
policy
);
}
for (trigger, name) in [
(SupervisionTrigger::TurnFailed, "turn_failed"),
(SupervisionTrigger::DeadlineBreached, "deadline_breached"),
(SupervisionTrigger::ManualRestart, "manual_restart"),
] {
assert_eq!(serde_json::to_value(trigger).unwrap(), json!(name));
assert_eq!(
serde_json::from_value::<SupervisionTrigger>(json!(name)).unwrap(),
trigger
);
}
assert!(serde_json::from_value::<RestartPolicy>(json!("always")).is_err());
}
#[test]
fn allows_restart_after_maps_the_otp_vocabulary_onto_error_class() {
let permanent = SupervisionPolicy::new(RestartPolicy::Permanent, 3, 60_000);
let transient = SupervisionPolicy::new(RestartPolicy::Transient, 3, 60_000);
let temporary = SupervisionPolicy::new(RestartPolicy::Temporary, 3, 60_000);
assert!(permanent.allows_restart_after(Some(ErrorClass::Transient)));
assert!(permanent.allows_restart_after(Some(ErrorClass::Cancelled)));
assert!(permanent.allows_restart_after(None));
assert!(transient.allows_restart_after(Some(ErrorClass::Timeout)));
assert!(!transient.allows_restart_after(Some(ErrorClass::Cancelled)));
assert!(!transient.allows_restart_after(None));
assert!(!temporary.allows_restart_after(Some(ErrorClass::Unknown)));
assert!(!temporary.allows_restart_after(None));
}
#[test]
fn supervision_policy_wire_shape_is_sparse_and_additive() {
let root = SupervisionPolicy::new(RestartPolicy::Permanent, 3, 60_000);
assert_eq!(
serde_json::to_value(&root).unwrap(),
json!({"restart": "permanent", "intensity": 3, "period_ms": 60000})
);
let back: SupervisionPolicy =
serde_json::from_str(&serde_json::to_string(&root).unwrap()).unwrap();
assert_eq!(root, back);
let with_supervisor = SupervisionPolicy {
supervisor: Some("boss".into()),
..root.clone()
};
assert_eq!(
serde_json::to_value(&with_supervisor).unwrap(),
json!({
"restart": "permanent",
"intensity": 3,
"period_ms": 60000,
"supervisor": "boss",
})
);
let minimal = CapabilityManifest::new("researcher", "researcher/1.4.0");
assert_eq!(minimal.supervision, None);
assert_eq!(
serde_json::to_value(&minimal).unwrap(),
json!({"agent_kind": "researcher", "manifest_version": "researcher/1.4.0"})
);
}
#[test]
fn attempt_history_and_escalation_notice_round_trip() {
let t0 = DateTime::<Utc>::from_timestamp_millis(1_800_000_000_000).unwrap();
let attempts = vec![
SupervisionAttempt {
ordinal: 1,
trigger: SupervisionTrigger::TurnFailed,
error_class: Some(ErrorClass::Transient),
message: "model timed out".into(),
task_id: Some("task-1".into()),
at: t0,
},
SupervisionAttempt {
ordinal: 2,
trigger: SupervisionTrigger::ManualRestart,
error_class: None,
message: "operator reset".into(),
task_id: None,
at: t0 + chrono::Duration::seconds(5),
},
];
let manual = serde_json::to_value(&attempts[1]).unwrap();
assert!(manual.get("error_class").is_none());
assert!(manual.get("task_id").is_none());
let notice = EscalationNotice {
agent_id: "looper".into(),
policy: SupervisionPolicy {
supervisor: Some("boss".into()),
..SupervisionPolicy::new(RestartPolicy::Permanent, 2, 60_000)
},
attempts,
escalated_at: t0 + chrono::Duration::seconds(9),
};
let back: EscalationNotice =
serde_json::from_str(&serde_json::to_string(¬ice).unwrap()).unwrap();
assert_eq!(notice, back);
assert_eq!(back.attempts.len(), 2);
assert_eq!(back.attempts[0].ordinal, 1);
assert_eq!(back.attempts[0].error_class, Some(ErrorClass::Transient));
assert_eq!(back.attempts[0].task_id.as_deref(), Some("task-1"));
}
fn delegation(member: &str, effect: Effect) -> Delegation {
Delegation {
member: member.into(),
agent_id: format!("agent-{member}"),
manifest_version: "researcher/1.4.0".into(),
kind: "summarize".into(),
input: PayloadRef::inline(json!({"topic": member})),
effect,
deadline: None,
}
}
#[test]
fn race_effect_gate_fails_closed() {
for effect in [Effect::Pure, Effect::ReadOnly, Effect::Idempotent] {
let contract = RaceContract {
candidates: vec![delegation("a", effect), delegation("b", Effect::Pure)],
};
assert!(contract.validate().is_ok(), "{effect:?} must be raceable");
}
let undeclared: Delegation = serde_json::from_value(json!({
"member": "a",
"agent_id": "agent-a",
"manifest_version": "researcher/1.4.0",
"kind": "summarize",
"input": {"kind": "inline", "value": {"topic": "a"}},
}))
.unwrap();
assert_eq!(undeclared.effect, Effect::NonIdempotent);
let contract = RaceContract {
candidates: vec![undeclared, delegation("b", Effect::Pure)],
};
assert_eq!(
contract.validate(),
Err(CoordinationViolation::RaceEffectNotFreelyRepeatable {
member: "a".into(),
effect: "non_idempotent".into(),
})
);
let contract = RaceContract {
candidates: vec![delegation("a", Effect::Compensatable)],
};
assert!(matches!(
contract.validate(),
Err(CoordinationViolation::RaceEffectNotFreelyRepeatable { .. })
));
}
#[test]
fn pattern_contracts_validate_structure() {
let race = RaceContract { candidates: vec![] };
assert_eq!(
race.validate(),
Err(CoordinationViolation::EmptyMembers {
pattern: "race".into()
})
);
let fan_out = FanOutContract {
members: vec![delegation("a", Effect::Pure), delegation("a", Effect::Pure)],
max_in_flight: 1,
on_member_failure: MemberFailurePolicy::Partial,
};
assert_eq!(
fan_out.validate(),
Err(CoordinationViolation::DuplicateMember {
pattern: "fan_out".into(),
member: "a".into(),
})
);
let fan_out = FanOutContract {
members: vec![delegation("a", Effect::Pure)],
max_in_flight: 0,
on_member_failure: MemberFailurePolicy::FailFast,
};
assert_eq!(
fan_out.validate(),
Err(CoordinationViolation::MaxInFlightZero)
);
let quorum = QuorumContract {
members: vec![delegation("a", Effect::Pure)],
threshold: 0,
resolver: QuorumResolver::MajorityEqual,
};
assert_eq!(
quorum.validate(),
Err(CoordinationViolation::QuorumThresholdOutOfRange {
threshold: 0,
members: 1,
})
);
let quorum = QuorumContract {
threshold: 2,
..quorum
};
assert!(matches!(
quorum.validate(),
Err(CoordinationViolation::QuorumThresholdOutOfRange { .. })
));
let quorum = QuorumContract {
members: vec![delegation("a", Effect::Pure)],
threshold: 1,
resolver: QuorumResolver::Custom {
name: "semantic_vote".into(),
},
};
assert_eq!(
quorum.validate(),
Err(CoordinationViolation::CustomResolverUnsupported {
name: "semantic_vote".into(),
})
);
}
#[test]
fn context_grant_only_narrows() {
let declared = vec![StateScope::Private, StateScope::Team];
let grant = ContextGrant {
scopes: vec![StateScope::Team],
channels: vec!["thread:team".into()],
};
assert!(grant.narrows(&declared));
let widening = ContextGrant {
scopes: vec![StateScope::Tenant],
channels: vec![],
};
assert!(!widening.narrows(&declared));
assert!(ContextGrant::default().narrows(&[]));
}
#[test]
fn merge_fan_out_orders_by_task_id_not_completion_order() {
let results = vec![
("t--c--b".to_string(), json!("B")),
("t--c--d".to_string(), json!("D")),
("t--c--a".to_string(), json!("A")),
];
assert_eq!(
merge_fan_out(&results),
vec![json!("A"), json!("B"), json!("D")]
);
let mut reversed = results.clone();
reversed.reverse();
assert_eq!(merge_fan_out(&reversed), merge_fan_out(&results));
}
#[test]
fn resolve_quorum_majority_decides_and_tallies_ties() {
let accepted = vec![
("t--c--a".to_string(), json!("X")),
("t--c--b".to_string(), json!("Y")),
("t--c--c".to_string(), json!("X")),
];
let outcome = resolve_quorum(&QuorumResolver::MajorityEqual, &accepted).unwrap();
assert_eq!(outcome, QuorumOutcome::Decided { output: json!("X") });
let tied = vec![
("t--c--a".to_string(), json!("X")),
("t--c--b".to_string(), json!("Y")),
("t--c--c".to_string(), json!("Y")),
("t--c--d".to_string(), json!("X")),
];
let outcome = resolve_quorum(&QuorumResolver::MajorityEqual, &tied).unwrap();
assert_eq!(
outcome,
QuorumOutcome::NoMajority {
tallies: vec![
QuorumTally {
output: json!("X"),
votes: 2,
},
QuorumTally {
output: json!("Y"),
votes: 2,
},
]
}
);
let objects = vec![
("t--c--a".to_string(), json!({"p": 1, "q": 2})),
("t--c--b".to_string(), json!({"q": 2, "p": 1})),
("t--c--c".to_string(), json!({"p": 9})),
];
let outcome = resolve_quorum(&QuorumResolver::MajorityEqual, &objects).unwrap();
assert_eq!(
outcome,
QuorumOutcome::Decided {
output: json!({"p": 1, "q": 2})
}
);
}
#[test]
fn resolve_quorum_first_k_is_task_id_ordered_and_deterministic() {
let accepted = vec![
("t--c--b".to_string(), json!(2)),
("t--c--a".to_string(), json!(1)),
("t--c--c".to_string(), json!(3)),
];
let outcome = resolve_quorum(&QuorumResolver::FirstK, &accepted).unwrap();
assert_eq!(
outcome,
QuorumOutcome::FirstK {
outputs: vec![json!(1), json!(2), json!(3)]
}
);
let mut permuted = accepted.clone();
permuted.reverse();
assert_eq!(
resolve_quorum(&QuorumResolver::FirstK, &permuted).unwrap(),
outcome
);
assert!(matches!(
resolve_quorum(&QuorumResolver::Custom { name: "x".into() }, &accepted),
Err(CoordinationViolation::CustomResolverUnsupported { .. })
));
}
#[test]
fn coordination_contract_dispatch_and_sparse_wire() {
let contract = CoordinationContract::Delegate(Box::new(DelegateContract {
delegate: delegation("only", Effect::Pure),
context: None,
result_contract: None,
handoff: false,
}));
assert_eq!(contract.kind(), CoordinationKind::Delegate);
assert_eq!(contract.members().len(), 1);
assert!(contract.validate().is_ok());
let wire = serde_json::to_value(&contract).unwrap();
assert_eq!(wire["pattern"], json!("delegate"));
assert!(wire["delegate"].get("context").is_none());
assert!(wire["delegate"].get("result_contract").is_none());
assert!(wire["delegate"].get("handoff").is_none());
assert_eq!(wire["delegate"]["effect"], json!("pure"));
let back: CoordinationContract =
serde_json::from_str(&serde_json::to_string(&contract).unwrap()).unwrap();
assert_eq!(contract, back);
}
#[test]
fn coordination_message_and_outcome_round_trip() {
let message = CoordinationMessage {
coordination_id: "c1".into(),
member: "a".into(),
pattern: CoordinationKind::FanOut,
input: PayloadRef::inline(json!({"topic": "a"})),
context: None,
};
let back: CoordinationMessage =
serde_json::from_str(&serde_json::to_string(&message).unwrap()).unwrap();
assert_eq!(message, back);
assert!(is_coordination_result(COORDINATION_RESULT_KIND));
assert!(!is_coordination_result("summarize"));
let outcome = CoordinationOutcome {
coordination_id: "c1".into(),
pattern: CoordinationKind::FanOut,
status: CoordinationStatus::Completed,
result: Some(PayloadRef::inline(json!(["A"]))),
members: vec![MemberDisposition {
member: "a".into(),
task_id: "t--c1--a".into(),
settlement: MemberSettlement::Completed,
result: Some(PayloadRef::inline(json!("A"))),
error_class: None,
error: None,
tokens: None,
cost_usd: None,
}],
wasted_tokens: None,
wasted_cost_usd: None,
resolver: None,
};
let wire = serde_json::to_value(&outcome).unwrap();
assert!(wire.get("wasted_tokens").is_none());
assert!(wire.get("wasted_cost_usd").is_none());
assert!(wire.get("resolver").is_none());
let back: CoordinationOutcome =
serde_json::from_str(&serde_json::to_string(&outcome).unwrap()).unwrap();
assert_eq!(outcome, back);
}
}