car-multi 0.24.0

//! 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.
//!
//! ```rust,ignore
//! 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!()
//!     }
//! }
//! ```

pub mod budget;
pub mod error;
pub mod mailbox;
pub mod patterns;
pub mod runner;
pub mod shared;
pub mod task_context;
pub mod types;
pub mod workspace;

// Re-exports for convenience
pub use budget::{
    budget_skipped_output, is_budget_skipped, BudgetError, BudgetLimits, BudgetSnapshot,
    CoordinationBudget,
};
pub use error::MultiError;
pub use mailbox::Mailbox;
pub use runner::AgentRunner;
pub use shared::SharedInfra;
pub use task_context::{AgentContext, TaskScope};
pub use types::{AgentOutput, AgentSpec, Message, MessageKind};
pub use workspace::{AgentWorkspace, WorkspaceConfig, WorkspaceMode, WORKSPACE_METADATA_KEY};

pub use patterns::adversarial_review::{
    AdversarialReview, AdversarialReviewResult, ReviewFinding,
};
pub use patterns::advisor::{
    Advisor, AdvisorResult, AdvisorTriggerContext, AdvisorTriggerDecision, AdvisorTriggerPolicy,
    AdvisorVerdict, TaskRisk,
};
pub use patterns::delegator::{Delegator, DelegatorResult};
pub use patterns::fleet::{Fleet, FleetResult};
pub use patterns::foreman::{
    decide, decompose, integrate_and_verify, parse_plan, partition_by_files, regional_replan,
    run_farm_out, run_farm_out_with_progress, run_foreman, verify_changes, AcceptanceBasis,
    AgentRunSummary, ApplyConflict, BuildTestFailure, BuildTestStatus, ChangeKind, ChangedSymbol,
    DuplicateBlame, ForemanProgress, ForemanProgressSink, ForemanRunOutcome, RunMode,
    CheckOutcome, ContainmentViolation, DeclaredFootprint, DecomposeResult, DuplicateDeclaration,
    FarmOutConfig, FarmOutResult, FileChange, ForemanError, GateConfig, GateEvidence,
    IntegrationBlame, IntegrationResult, MergeVerdict, NoVerifyWaiver, PolicyDecision, Subtask,
    SubtaskOutcome, SymbolRef, WorktreeAgent, WorktreeAgentRequest,
};
pub use patterns::foreman::report::{
    AcceptanceBasisDto, ApplyConflictDto, BuildTestDto, BuildTestFailureDto, DuplicateBlameDto,
    DuplicateDto, ForemanReport, GateEvidenceDto, IntegrationBlameDto, IntegrationReportDto,
    MergeVerdictDto, PlanReport, PlanSubtaskDto, SubtaskReportDto, SymbolRefDto,
    FOREMAN_SCHEMA_VERSION,
};
pub use patterns::map_reduce::{MapReduce, MapReduceResult};
pub use patterns::pipeline::{Pipeline, PipelineResult};
pub use patterns::spawn_subtask::{
    spawn_subtask_schema, SpawnSubtask, SpawnSubtaskResult, SubtaskRecord,
};
pub use patterns::supervisor::{Supervisor, SupervisorResult};
pub use patterns::swarm::{Swarm, SwarmMode, SwarmResult};
pub use patterns::tournament::{MatchResult, Tournament, TournamentResult};
pub use patterns::vote::{Vote, VoteResult};

// === Umbrella re-exports (car#205) ===
//
// car-multi re-exports the built-in commodity agents from
// car-agents so external Rust consumers (tokhn) can construct a
// coordinated agent system from a single crate dep. car-agents
// stays in the workspace as a separate compile unit; this is a
// publish-set boundary, not a workspace boundary.

pub use car_agents::{
    coordinator::{CoordinationPlan, Pattern},
    Coordinator, PlannerAgent, Researcher, Summarizer, Verifier,
};