Crate terraphim_orchestrator 

Multi-agent orchestration with scheduling, budgeting, and compound review.

This crate provides the core orchestration engine for managing fleets of AI agents with features for resource scheduling, cost tracking, and coordinated review workflows.

Core Components

• AgentOrchestrator: Main orchestrator running the “dark factory” pattern
• DualModeOrchestrator: Real-time and batch processing modes with fairness scheduling
• CompoundReviewWorkflow: Multi-agent review swarm with persona-based specialization
• Scheduler: Time-based and event-driven task scheduling
• HandoffBuffer: Inter-agent state transfer with TTL management
• CostTracker: Budget enforcement and spending monitoring
• NightwatchMonitor: Drift detection and rate limiting
• MetaCoordinator: Cross-project issue-driven agent dispatch with PageRank prioritisation

Example

use terraphim_orchestrator::{AgentOrchestrator, OrchestratorConfig};

let config = OrchestratorConfig::default();
let mut orchestrator = AgentOrchestrator::new(config).await?;

// Run the orchestration loop
orchestrator.run().await?;

Re-exports

pub use agent_run_command::applicable_modes;

pub use agent_run_command::is_cron_schedule_valid;

pub use agent_run_command::parse_agent_args;

pub use agent_run_command::run_synthetic;

pub use agent_run_command::run_validate;

pub use agent_run_command::run_validate_all;

pub use agent_run_command::schedule_for_agent;

pub use agent_run_command::validate_agent_all_modes;

pub use agent_run_command::AgentSubcommand;

pub use agent_run_command::AgentValidateAllReport;

pub use agent_run_command::OutputFormat;

pub use agent_run_record::AgentRunRecord;

pub use agent_run_record::ExitClass;

pub use agent_run_record::ExitClassification;

pub use agent_run_record::ExitClassifier;

pub use agent_run_record::RunTrigger;

pub use agent_runner::probe_cli_tool;

pub use agent_runner::probe_model_available;

pub use agent_runner::run_agent_synthetic;

pub use agent_runner::validate_agent_runtime;

pub use agent_runner::AgentRunRequest;

pub use agent_runner::AgentRuntimeValidationReport;

pub use agent_runner::GiteaTargetReport;

pub use agent_runner::ModeResult;

pub use agent_runner::SyntheticEvent;

pub use agent_runner::TriggerMode;

pub use compound::CompoundReviewResult;

pub use compound::CompoundReviewWorkflow;

pub use compound::ReviewGroupDef;

pub use compound::SwarmConfig;

pub use concurrency::ConcurrencyController;

pub use concurrency::FairnessPolicy;

pub use concurrency::ModeQuotas;

pub use config::QuickwitConfig;

pub use config::AgentDefinition;

pub use config::AgentLayer;

pub use config::CompoundReviewConfig;

pub use config::ConcurrencyConfig;

pub use config::EvolutionConfig;

pub use config::GiteaOutputConfig;

pub use config::LearningConfig;

pub use config::MentionConfig;

pub use config::NightwatchConfig;

pub use config::OrchestratorConfig;

pub use config::PreCheckStrategy;

pub use config::TrackerConfig;

pub use config::TrackerStates;

pub use config::WebhookConfig;

pub use config::WorkflowConfig;

pub use cost_tracker::AgentMetrics;

pub use cost_tracker::BudgetVerdict;

pub use cost_tracker::CostSnapshot;

pub use cost_tracker::CostTracker;

pub use cost_tracker::ExecutionMetrics;

pub use dispatcher::DispatchTask;

pub use dispatcher::Dispatcher;

pub use dispatcher::DispatcherStats;

pub use dual_mode::DualModeOrchestrator;

pub use error::OrchestratorError;

pub use handoff::HandoffBuffer;

pub use handoff::HandoffContext;

pub use handoff::HandoffLedger;

pub use mention::migrate_legacy_mention_cursor;

pub use mention::parse_mention_tokens;

pub use mention::parse_mentions;

pub use mention::resolve_mention;

pub use mention::resolve_persona_mention;

pub use mention::DetectedMention;

pub use mention::MentionCursor;

pub use mention::MentionTokens;

pub use mention::MentionTracker;

pub use mention_chain::MentionChainError;

pub use mention_chain::MentionChainTracker;

pub use mention_chain::MentionContextArgs;

pub use mention_chain::DEFAULT_MAX_MENTION_DEPTH;

pub use metrics_persistence::InMemoryMetricsPersistence;

pub use metrics_persistence::MetricsPersistence;

pub use metrics_persistence::MetricsPersistenceConfig;

pub use metrics_persistence::MetricsPersistenceError;

pub use metrics_persistence::PersistedAgentMetrics;

pub use mode::IssueMode;

pub use mode::TimeMode;

pub use nightwatch::dual_panel_evaluate;

pub use nightwatch::validate_certificate;

pub use nightwatch::Claim;

pub use nightwatch::CorrectionAction;

pub use nightwatch::CorrectionLevel;

pub use nightwatch::DriftAlert;

pub use nightwatch::DriftMetrics;

pub use nightwatch::DriftScore;

pub use nightwatch::DualPanelResult;

pub use nightwatch::NightwatchMonitor;

pub use nightwatch::RateLimitTracker;

pub use nightwatch::RateLimitWindow;

pub use nightwatch::ReasoningCertificate;

pub use output_poster::OutputPoster;

pub use persona::MetapromptRenderError;

pub use persona::MetapromptRenderer;

pub use persona::PersonaRegistry;

pub use project_adf::ProjectAdfConfig;

pub use quickwit_bulk::QuickwitEsBulkSink;

pub use rate_limiter::is_rate_limit_backoff_enabled;

pub use rate_limiter::RateLimiter;

pub use scheduler::ScheduleEvent;

pub use scheduler::TimeScheduler;

pub use worktree_guard::with_worktree_guard;

pub use worktree_guard::with_worktree_guard_async;

pub use worktree_guard::WorktreeGuard;

Modules

adf_commands

ADF Command Parser using terraphim-automata

agent_run_command

agent_run_record

Structured agent run records with KG-boosted exit classification.

agent_runner

compound

concurrency

Global concurrency controller with fairness.

config

control_plane

Control-plane routing decision layer for ADF agent dispatch.

cost_tracker

dispatcher

Unified dispatch queue for both time-driven and issue-driven modes.

dual_mode

Dual-mode orchestrator with full integration.

error

error_signatures

Per-provider stderr classification into throttle / flake / unknown.

evolution

flow

gitea_skill_loader

Fetches SKILL.md files from a Gitea repository and caches them to disk.

handoff

kg_router

KG-driven model routing using markdown-defined rules.

learning

Shared Learning Store for ADF agents.

mention

Mention detection and resolution for @adf:name comments.

mention_chain

Mention chain tracking for depth limiting and cycle detection.

meta_coordinator

Cross-project meta-coordinator for issue-driven agent dispatch.

metrics_persistence

Metrics persistence for agent cost and performance tracking.

mode

Agent execution modes.

nightwatch

output_poster

Posts agent output to Gitea issues after agent exit.

persona

post_merge_gate

ROC v1 Step H — post-merge test gate with git revert on red.

pr_dispatch

Pure helpers for wiring DispatchTask::ReviewPr into the spawn pipeline.

pr_gate

Pure-function module for reconciling PR gate state against branch protection requirements.

pr_poller

Polling helpers for ROC v1 Step F — turn open PRs + reviewer comments into crate::dispatcher::DispatchTask::AutoMerge tasks.

pr_review

Pure-function module for parsing structural PR review comments and evaluating whether a PR meets the auto-merge criteria.

project_adf

project_control

Project-level operational controls: pause flags and circuit breakers.

provider_budget

Provider-level spend tracking with hour and day windows.

provider_probe

Provider availability probing with per-provider circuit breakers.

quickwit

Quickwit log shipping for ADF orchestrator

quickwit_bulk

Quickwit ES-compatible bulk ingestion with retry logic.

rate_limiter

Rate limiter with exponential backoff and circuit breaker integration.

scheduler

scope

webhook

Gitea webhook handler for real-time mention dispatch.

worktree_guard

RAII worktree guard for automatic cleanup on agent crash or panic.

Structs

AgentOrchestrator

The main orchestrator that runs the dark factory.

AgentStatus

Status of a single agent in the fleet.

Enums

PreCheckResult

Result of evaluating a pre-check strategy before spawning an agent.