car_multi/
lib.rs

1// Raise above the default 128: the async coordination fixtures sit at the
2// recursion-limit edge for async-fn layout ("queries overflow the depth
3// limit") — the documented fix car-server/-core already carry.
4#![recursion_limit = "512"]
5
6//! Multi-agent coordination for Common Agent Runtime.
7//!
8//! Provides these coordination patterns:
9//!
10//! | Pattern | Description |
11//! |---------|-------------|
12//! | **Swarm** | N agents on the same problem (parallel, sequential, or debate) |
13//! | **Pipeline** | Linear chain — each agent's output feeds the next |
14//! | **Supervisor** | One agent reviews workers, iterates until approval |
15//! | **Delegator** | Main agent routes to fixed, named specialists via a tool |
16//! | **SpawnSubtask** | Main agent spawns ephemeral sub-agents with a *subset* of its own tools (subset enforced by the tool schema's `enum`) |
17//! | **MapReduce** | Fan-out to N mappers, reduce into a single result |
18//! | **Vote** | N agents answer independently, majority wins |
19//! | **Tournament** | N competitors ranked by single-elimination pairwise judging |
20//! | **Advisor** | Main executor stays in control, stronger model returns bounded guidance |
21//!
22//! ## How agents communicate
23//!
24//! Agents communicate through three mechanisms:
25//!
26//! 1. **Shared state** — all agents in a coordination group share the same
27//!    `Arc<StateStore>` and `Arc<EventLog>` via `SharedInfra`. Agents can read
28//!    each other's state writes.
29//!
30//! 2. **Task enrichment** — orchestrators pass prior agents' outputs into the
31//!    next agent's task prompt (e.g., sequential swarm, supervisor feedback).
32//!
33//! 3. **Mailbox** — async channel-based messaging for real-time inter-agent
34//!    communication during execution.
35//!
36//! ## The AgentRunner trait
37//!
38//! Since the runtime doesn't own the model, the caller implements `AgentRunner`
39//! to drive the model loop. `car-multi` orchestrates *when* and *how* agents run;
40//! the caller decides *what* each agent does.
41//!
42//! ```rust,ignore
43//! use car_multi::{AgentRunner, AgentSpec, AgentOutput, Mailbox, MultiError};
44//! use car_engine::Runtime;
45//!
46//! struct MyRunner { /* OpenAI client, etc. */ }
47//!
48//! #[async_trait::async_trait]
49//! impl AgentRunner for MyRunner {
50//!     async fn run(
51//!         &self,
52//!         spec: &AgentSpec,
53//!         task: &str,
54//!         runtime: &Runtime,
55//!         mailbox: &Mailbox,
56//!     ) -> Result<AgentOutput, MultiError> {
57//!         // 1. Call your LLM with spec.system_prompt + task
58//!         // 2. Parse response into ActionProposal
59//!         // 3. runtime.execute(&proposal).await
60//!         // 4. Return AgentOutput
61//!         todo!()
62//!     }
63//! }
64//! ```
65
66pub mod budget;
67pub mod concurrency;
68pub mod error;
69pub mod mailbox;
70pub mod patterns;
71pub mod runner;
72pub mod shared;
73pub mod task_context;
74pub mod topology;
75pub mod types;
76pub mod workspace;
77
78// Re-exports for convenience
79pub use budget::{
80    budget_skipped_output, is_budget_skipped, BudgetError, BudgetLimits, BudgetSnapshot,
81    CoordinationBudget,
82};
83pub use concurrency::{ConcurrencyControl, ConcurrencyGuard};
84pub use error::MultiError;
85pub use mailbox::Mailbox;
86pub use runner::AgentRunner;
87pub use shared::SharedInfra;
88pub use task_context::{AgentContext, TaskScope};
89pub use topology::{
90    execution_record, execution_record_for, measured_tokens, outcome_utility, record_run,
91    record_run_from_outcomes, run_utility, scorer_advice, select_shape, team_homogeneity,
92    UtilityAggregation, UtilityEvidence,
93};
94pub use types::{AgentOutput, AgentSpec, Message, MessageKind};
95pub use workspace::{AgentWorkspace, WorkspaceConfig, WorkspaceMode, WORKSPACE_METADATA_KEY};
96
97pub use patterns::adversarial_review::{AdversarialReview, AdversarialReviewResult, ReviewFinding};
98pub use patterns::advisor::{
99    Advisor, AdvisorResult, AdvisorTriggerContext, AdvisorTriggerDecision, AdvisorTriggerPolicy,
100    AdvisorVerdict, TaskRisk,
101};
102pub use patterns::delegator::{Delegator, DelegatorResult};
103pub use patterns::fleet::{Fleet, FleetResult};
104pub use patterns::foreman::report::{
105    AcceptanceBasisDto, ApplyConflictDto, BuildTestDto, BuildTestFailureDto, DuplicateBlameDto,
106    DuplicateDto, ForemanReport, GateEvidenceDto, IntegrationBlameDto, IntegrationReportDto,
107    MergeVerdictDto, PlanReport, PlanSubtaskDto, SubtaskReportDto, SymbolRefDto,
108    FOREMAN_SCHEMA_VERSION,
109};
110pub use patterns::foreman::{
111    capture_patch, decide, decompose, files_in_patch, git_apply, integrate_and_verify, parse_plan,
112    partition_by_files, regional_replan, run_farm_out, run_farm_out_with_progress, run_foreman,
113    verify_changes, AcceptanceBasis, AgentRunSummary, ApplyConflict, BuildTestFailure,
114    BuildTestStatus, ChangeKind, ChangedSymbol, CheckOutcome, ContainmentViolation,
115    DeclaredFootprint, DecomposeResult, DuplicateBlame, DuplicateDeclaration, FailedAttempt,
116    FarmOutConfig, FarmOutResult, FileChange, FleetPool, FleetWorker, ForemanError,
117    ForemanProgress, ForemanProgressSink, ForemanRunOutcome, GateConfig, GateEvidence,
118    IntegrationBlame, IntegrationResult, MergeVerdict, NoVerifyWaiver, Placement, PolicyDecision,
119    RunMode, Subtask, SubtaskOutcome, SymbolRef, WorktreeAgent, WorktreeAgentRequest,
120};
121pub use patterns::map_reduce::{MapReduce, MapReduceResult};
122pub use patterns::pipeline::{Pipeline, PipelineResult};
123pub use patterns::spawn_subtask::{
124    spawn_subtask_schema, SpawnSubtask, SpawnSubtaskResult, SubtaskRecord,
125};
126pub use patterns::supervisor::{Supervisor, SupervisorResult};
127pub use patterns::swarm::{Swarm, SwarmMode, SwarmResult};
128pub use patterns::tournament::{MatchResult, Tournament, TournamentResult};
129pub use patterns::vote::{Vote, VoteResult};
130
131// === Umbrella re-exports (car#205) ===
132//
133// car-multi re-exports the built-in commodity agents from
134// car-agents so external Rust consumers (tokhn) can construct a
135// coordinated agent system from a single crate dep. car-agents
136// stays in the workspace as a separate compile unit; this is a
137// publish-set boundary, not a workspace boundary.
138
139pub use car_agents::{
140    coordinator::{CoordinationPlan, Pattern},
141    Coordinator, PlannerAgent, Researcher, Summarizer, Verifier,
142};
car_multi/lib.rs

car_multi/
lib.rs
