Crate car_multi 

Multi-agent coordination for Common Agent Runtime.

Provides these coordination patterns:

Pattern	Description
Swarm	N agents on the same problem (parallel, sequential, or debate)
Pipeline	Linear chain — each agent’s output feeds the next
Supervisor	One agent reviews workers, iterates until approval
Delegator	Main agent routes to fixed, named specialists via a tool
SpawnSubtask	Main agent spawns ephemeral sub-agents with a subset of its own tools (subset enforced by the tool schema’s enum)
MapReduce	Fan-out to N mappers, reduce into a single result
Vote	N agents answer independently, majority wins
Tournament	N competitors ranked by single-elimination pairwise judging
Advisor	Main executor stays in control, stronger model returns bounded guidance

How agents communicate

Agents communicate through three mechanisms:

1. Shared state — all agents in a coordination group share the same Arc<StateStore> and Arc<EventLog> via SharedInfra. Agents can read each other’s state writes.

2. Task enrichment — orchestrators pass prior agents’ outputs into the next agent’s task prompt (e.g., sequential swarm, supervisor feedback).

3. Mailbox — async channel-based messaging for real-time inter-agent communication during execution.

The AgentRunner trait

Since the runtime doesn’t own the model, the caller implements AgentRunner to drive the model loop. car-multi orchestrates when and how agents run; the caller decides what each agent does.

use car_multi::{AgentRunner, AgentSpec, AgentOutput, Mailbox, MultiError};
use car_engine::Runtime;

struct MyRunner { /* OpenAI client, etc. */ }

#[async_trait::async_trait]
impl AgentRunner for MyRunner {
    async fn run(
        &self,
        spec: &AgentSpec,
        task: &str,
        runtime: &Runtime,
        mailbox: &Mailbox,
    ) -> Result<AgentOutput, MultiError> {
        // 1. Call your LLM with spec.system_prompt + task
        // 2. Parse response into ActionProposal
        // 3. runtime.execute(&proposal).await
        // 4. Return AgentOutput
        todo!()
    }
}

Re-exports

pub use budget::budget_skipped_output;

pub use budget::is_budget_skipped;

pub use budget::BudgetError;

pub use budget::BudgetLimits;

pub use budget::BudgetSnapshot;

pub use budget::CoordinationBudget;

pub use concurrency::ConcurrencyControl;

pub use concurrency::ConcurrencyGuard;

pub use error::MultiError;

pub use mailbox::Mailbox;

pub use runner::AgentRunner;

pub use shared::SharedInfra;

pub use task_context::AgentContext;

pub use task_context::TaskScope;

pub use topology::execution_record;

pub use topology::execution_record_for;

pub use topology::measured_tokens;

pub use topology::outcome_utility;

pub use topology::record_run;

pub use topology::record_run_from_outcomes;

pub use topology::run_utility;

pub use topology::scorer_advice;

pub use topology::select_shape;

pub use topology::team_homogeneity;

pub use topology::UtilityAggregation;

pub use topology::UtilityEvidence;

pub use types::AgentOutput;

pub use types::AgentSpec;

pub use types::Message;

pub use types::MessageKind;

pub use workspace::AgentWorkspace;

pub use workspace::WorkspaceConfig;

pub use workspace::WorkspaceMode;

pub use workspace::WORKSPACE_METADATA_KEY;

pub use patterns::adversarial_review::AdversarialReview;

pub use patterns::adversarial_review::AdversarialReviewResult;

pub use patterns::adversarial_review::ReviewFinding;

pub use patterns::advisor::Advisor;

pub use patterns::advisor::AdvisorResult;

pub use patterns::advisor::AdvisorTriggerContext;

pub use patterns::advisor::AdvisorTriggerDecision;

pub use patterns::advisor::AdvisorTriggerPolicy;

pub use patterns::advisor::AdvisorVerdict;

pub use patterns::advisor::TaskRisk;

pub use patterns::delegator::Delegator;

pub use patterns::delegator::DelegatorResult;

pub use patterns::fleet::Fleet;

pub use patterns::fleet::FleetResult;

pub use patterns::foreman::report::AcceptanceBasisDto;

pub use patterns::foreman::report::ApplyConflictDto;

pub use patterns::foreman::report::BuildTestDto;

pub use patterns::foreman::report::BuildTestFailureDto;

pub use patterns::foreman::report::DuplicateBlameDto;

pub use patterns::foreman::report::DuplicateDto;

pub use patterns::foreman::report::ForemanReport;

pub use patterns::foreman::report::GateEvidenceDto;

pub use patterns::foreman::report::IntegrationBlameDto;

pub use patterns::foreman::report::IntegrationReportDto;

pub use patterns::foreman::report::MergeVerdictDto;

pub use patterns::foreman::report::PlanReport;

pub use patterns::foreman::report::PlanSubtaskDto;

pub use patterns::foreman::report::SubtaskReportDto;

pub use patterns::foreman::report::SymbolRefDto;

pub use patterns::foreman::report::FOREMAN_SCHEMA_VERSION;

pub use patterns::foreman::capture_patch;

pub use patterns::foreman::decide;

pub use patterns::foreman::decompose;

pub use patterns::foreman::files_in_patch;

pub use patterns::foreman::git_apply;

pub use patterns::foreman::integrate_and_verify;

pub use patterns::foreman::parse_plan;

pub use patterns::foreman::partition_by_files;

pub use patterns::foreman::regional_replan;

pub use patterns::foreman::run_farm_out;

pub use patterns::foreman::run_farm_out_with_progress;

pub use patterns::foreman::run_foreman;

pub use patterns::foreman::verify_changes;

pub use patterns::foreman::AcceptanceBasis;

pub use patterns::foreman::AgentRunSummary;

pub use patterns::foreman::ApplyConflict;

pub use patterns::foreman::BuildTestFailure;

pub use patterns::foreman::BuildTestStatus;

pub use patterns::foreman::ChangeKind;

pub use patterns::foreman::ChangedSymbol;

pub use patterns::foreman::CheckOutcome;

pub use patterns::foreman::ContainmentViolation;

pub use patterns::foreman::DeclaredFootprint;

pub use patterns::foreman::DecomposeResult;

pub use patterns::foreman::DuplicateBlame;

pub use patterns::foreman::DuplicateDeclaration;

pub use patterns::foreman::FailedAttempt;

pub use patterns::foreman::FarmOutConfig;

pub use patterns::foreman::FarmOutResult;

pub use patterns::foreman::FileChange;

pub use patterns::foreman::FleetPool;

pub use patterns::foreman::FleetWorker;

pub use patterns::foreman::ForemanError;

pub use patterns::foreman::ForemanProgress;

pub use patterns::foreman::ForemanProgressSink;

pub use patterns::foreman::ForemanRunOutcome;

pub use patterns::foreman::GateConfig;

pub use patterns::foreman::GateEvidence;

pub use patterns::foreman::IntegrationBlame;

pub use patterns::foreman::IntegrationResult;

pub use patterns::foreman::MergeVerdict;

pub use patterns::foreman::NoVerifyWaiver;

pub use patterns::foreman::Placement;

pub use patterns::foreman::PolicyDecision;

pub use patterns::foreman::RunMode;

pub use patterns::foreman::Subtask;

pub use patterns::foreman::SubtaskOutcome;

pub use patterns::foreman::WorktreeAgent;

pub use patterns::foreman::WorktreeAgentRequest;

pub use patterns::map_reduce::MapReduce;

pub use patterns::map_reduce::MapReduceResult;

pub use patterns::pipeline::Pipeline;

pub use patterns::pipeline::PipelineResult;

pub use patterns::spawn_subtask::spawn_subtask_schema;

pub use patterns::spawn_subtask::SpawnSubtask;

pub use patterns::spawn_subtask::SpawnSubtaskResult;

pub use patterns::spawn_subtask::SubtaskRecord;

pub use patterns::supervisor::Supervisor;

pub use patterns::supervisor::SupervisorResult;

pub use patterns::swarm::Swarm;

pub use patterns::swarm::SwarmMode;

pub use patterns::swarm::SwarmResult;

pub use patterns::tournament::MatchResult;

pub use patterns::tournament::Tournament;

pub use patterns::tournament::TournamentResult;

pub use patterns::vote::Vote;

pub use patterns::vote::VoteResult;

Modules

budget

Runtime-enforced coordination budget.

concurrency

Runtime concurrency-anomaly gating for multi-agent coordination (EPIC A / task A5 — arXiv 2606.17182).

error

Error types for multi-agent coordination.

mailbox

Async channel-based mailbox for inter-agent messaging.

patterns

Coordination patterns for multi-agent systems.

runner

AgentRunner trait — the caller’s model loop abstraction.

shared

Shared infrastructure — creates Runtimes that share state, log, and policies.

task_context

Task-local agent context using tokio::task_local!

topology

Turning coordination runs into topology-selection records.

types

Core types for multi-agent coordination.

workspace

Per-agent filesystem workspace isolation.

Structs

CoordinationPlan

Coordinator’s decision: which agents in what pattern.

Coordinator

Coordinator: goal → which agents + which pattern.

PlannerAgent

Planner: goal → ordered action steps.

Researcher

Researcher: search, read, gather → structured findings.

Summarizer

Summarizer: long context → compressed handoff.

SymbolRef

A (file, symbol) location. file is repo-relative.

Verifier

Verifier: output + spec → pass/fail with reasons.

Enums

Pattern

Coordination patterns available.