car_multi/
lib.rs

1//! Multi-agent coordination for Common Agent Runtime.
2//!
3//! Provides these coordination patterns:
4//!
5//! | Pattern | Description |
6//! |---------|-------------|
7//! | **Swarm** | N agents on the same problem (parallel, sequential, or debate) |
8//! | **Pipeline** | Linear chain — each agent's output feeds the next |
9//! | **Supervisor** | One agent reviews workers, iterates until approval |
10//! | **Delegator** | Main agent routes to fixed, named specialists via a tool |
11//! | **SpawnSubtask** | Main agent spawns ephemeral sub-agents with a *subset* of its own tools (subset enforced by the tool schema's `enum`) |
12//! | **MapReduce** | Fan-out to N mappers, reduce into a single result |
13//! | **Vote** | N agents answer independently, majority wins |
14//! | **Tournament** | N competitors ranked by single-elimination pairwise judging |
15//! | **Advisor** | Main executor stays in control, stronger model returns bounded guidance |
16//!
17//! ## How agents communicate
18//!
19//! Agents communicate through three mechanisms:
20//!
21//! 1. **Shared state** — all agents in a coordination group share the same
22//!    `Arc<StateStore>` and `Arc<EventLog>` via `SharedInfra`. Agents can read
23//!    each other's state writes.
24//!
25//! 2. **Task enrichment** — orchestrators pass prior agents' outputs into the
26//!    next agent's task prompt (e.g., sequential swarm, supervisor feedback).
27//!
28//! 3. **Mailbox** — async channel-based messaging for real-time inter-agent
29//!    communication during execution.
30//!
31//! ## The AgentRunner trait
32//!
33//! Since the runtime doesn't own the model, the caller implements `AgentRunner`
34//! to drive the model loop. `car-multi` orchestrates *when* and *how* agents run;
35//! the caller decides *what* each agent does.
36//!
37//! ```rust,ignore
38//! use car_multi::{AgentRunner, AgentSpec, AgentOutput, Mailbox, MultiError};
39//! use car_engine::Runtime;
40//!
41//! struct MyRunner { /* OpenAI client, etc. */ }
42//!
43//! #[async_trait::async_trait]
44//! impl AgentRunner for MyRunner {
45//!     async fn run(
46//!         &self,
47//!         spec: &AgentSpec,
48//!         task: &str,
49//!         runtime: &Runtime,
50//!         mailbox: &Mailbox,
51//!     ) -> Result<AgentOutput, MultiError> {
52//!         // 1. Call your LLM with spec.system_prompt + task
53//!         // 2. Parse response into ActionProposal
54//!         // 3. runtime.execute(&proposal).await
55//!         // 4. Return AgentOutput
56//!         todo!()
57//!     }
58//! }
59//! ```
60
61pub mod budget;
62pub mod error;
63pub mod mailbox;
64pub mod patterns;
65pub mod runner;
66pub mod shared;
67pub mod task_context;
68pub mod types;
69pub mod workspace;
70
71// Re-exports for convenience
72pub use budget::{
73    budget_skipped_output, is_budget_skipped, BudgetError, BudgetLimits, BudgetSnapshot,
74    CoordinationBudget,
75};
76pub use error::MultiError;
77pub use mailbox::Mailbox;
78pub use runner::AgentRunner;
79pub use shared::SharedInfra;
80pub use task_context::{AgentContext, TaskScope};
81pub use types::{AgentOutput, AgentSpec, Message, MessageKind};
82pub use workspace::{AgentWorkspace, WorkspaceConfig, WorkspaceMode, WORKSPACE_METADATA_KEY};
83
84pub use patterns::adversarial_review::{
85    AdversarialReview, AdversarialReviewResult, ReviewFinding,
86};
87pub use patterns::advisor::{
88    Advisor, AdvisorResult, AdvisorTriggerContext, AdvisorTriggerDecision, AdvisorTriggerPolicy,
89    AdvisorVerdict, TaskRisk,
90};
91pub use patterns::delegator::{Delegator, DelegatorResult};
92pub use patterns::fleet::{Fleet, FleetResult};
93pub use patterns::map_reduce::{MapReduce, MapReduceResult};
94pub use patterns::pipeline::{Pipeline, PipelineResult};
95pub use patterns::spawn_subtask::{
96    spawn_subtask_schema, SpawnSubtask, SpawnSubtaskResult, SubtaskRecord,
97};
98pub use patterns::supervisor::{Supervisor, SupervisorResult};
99pub use patterns::swarm::{Swarm, SwarmMode, SwarmResult};
100pub use patterns::tournament::{MatchResult, Tournament, TournamentResult};
101pub use patterns::vote::{Vote, VoteResult};
102
103// === Umbrella re-exports (car#205) ===
104//
105// car-multi re-exports the built-in commodity agents from
106// car-agents so external Rust consumers (tokhn) can construct a
107// coordinated agent system from a single crate dep. car-agents
108// stays in the workspace as a separate compile unit; this is a
109// publish-set boundary, not a workspace boundary.
110
111pub use car_agents::{
112    coordinator::{CoordinationPlan, Pattern},
113    Coordinator, PlannerAgent, Researcher, Summarizer, Verifier,
114};
car_multi/lib.rs

car_multi/
lib.rs
