cap_rs_orchestrator/
lib.rs

1//! cap-rs-orchestrator — headless engine that runs N collaborating CLI agents
2//! in one process, driven by a declarative `fleet.yaml`.
3//!
4//! See `docs/cap-orchestrator-engine-design.md`.
5#![warn(missing_debug_implementations)]
6
7pub mod audit;
8pub mod config;
9pub mod event;
10pub mod executor;
11pub mod factory;
12pub mod real_factory;
13pub mod registry;
14pub mod routing;
15pub mod session;
16#[cfg(any(test, feature = "testing"))]
17pub mod testing;
18pub mod worktree;
19
20/// Errors surfaced by the orchestrator engine.
21#[derive(Debug, thiserror::Error)]
22#[non_exhaustive]
23pub enum OrchestratorError {
24    #[error("config error: {0}")]
25    Config(String),
26    #[error("worktree error: {0}")]
27    Worktree(String),
28    #[error("driver error: {0}")]
29    Driver(#[from] cap_rs::driver::DriverError),
30}
31
32use crate::config::FleetSpec;
33use crate::event::OrchestratorEvent;
34use crate::executor::{Executor, ExecutorHandle};
35use crate::real_factory::RealDriverFactory;
36use crate::routing::RoutingStrategy;
37use crate::worktree::GitWorktreeManager;
38
39/// Convenience façade: run a fleet against real CLI agents in `repo`
40/// with the default static YAML routing strategy.
41pub async fn run(
42    spec: FleetSpec,
43    repo: impl AsRef<std::path::Path>,
44    task: &str,
45) -> Result<
46    (
47        ExecutorHandle,
48        tokio::sync::mpsc::Receiver<OrchestratorEvent>,
49    ),
50    OrchestratorError,
51> {
52    let worktree = GitWorktreeManager::new(repo);
53    Executor::start(spec, RealDriverFactory, worktree, task).await
54}
55
56/// Convenience façade: run an interactive chat fleet against real CLI agents in `repo`.
57pub async fn chat(
58    spec: FleetSpec,
59    repo: impl AsRef<std::path::Path>,
60    task: &str,
61) -> Result<
62    (
63        ExecutorHandle,
64        tokio::sync::mpsc::Receiver<OrchestratorEvent>,
65    ),
66    OrchestratorError,
67> {
68    let worktree = GitWorktreeManager::new(repo);
69    Executor::start_chat(spec, RealDriverFactory, worktree, task).await
70}
71
72/// Convenience façade: run a fleet with a custom routing strategy.
73pub async fn run_with_strategy<S>(
74    spec: FleetSpec,
75    repo: impl AsRef<std::path::Path>,
76    task: &str,
77    strategy: S,
78) -> Result<
79    (
80        ExecutorHandle,
81        tokio::sync::mpsc::Receiver<OrchestratorEvent>,
82    ),
83    OrchestratorError,
84>
85where
86    S: RoutingStrategy,
87{
88    let worktree = GitWorktreeManager::new(repo);
89    Executor::start_with_strategy(spec, RealDriverFactory, worktree, task, strategy).await
90}
cap_rs_orchestrator/lib.rs

cap_rs_orchestrator/
lib.rs
