vox-orchestrator API Reference (generated)
Crate: vox-orchestrator · Version: 0.6.0 · Target: Library (lib.rs)
Multi-agent file-affinity task router. Queue/lock/oplog in vox-orchestrator-queue; MCP protocol tools in vox-orchestrator-mcp.
Crate Overview
Section titled “Crate Overview”vox-orchestrator
Section titled “vox-orchestrator”Multi-agent file-affinity queue system for the Vox programming language.
Routes tasks to agents based on file ownership — ensuring only one agent writes to any given file at a time. Prevents race conditions and lost updates when multiple AI agents work concurrently across a Vox workspace.
Architecture
Section titled “Architecture”User Request│▼Orchestrator ──► FileAffinityMap ──► route to Agent│ │▼ ▼BulletinBoard ◄──── AgentQueue ──► FileLockManagerFeatures
Section titled “Features”runtime— Actor-based agents usingvox-actor-runtimeScheduler/Supervisortoestub-gate— Post-task quality validation using TOESTUB (on by default)lsp— LSP diagnostic integration for file ownership info
Module-level behavior is documented in each submodule; the crate root is a large re-export surface for the orchestrator binary and integration tests.
Embedding: the usual MCP host is the vox-mcp crate (stdio server), which
holds Orchestrator plus optional Turso VoxDb for Codex/Arca. Training and model SSOT for
Mens live in mdBook mens-training-ssot.md
(three levels up from src/ to repo root).
Features
Section titled “Features”| Feature | Default / Enables |
|---|---|
corpus-db | vox-corpus/database |
default | toestub-gate, runtime, json-schema, jj, corpus-db, http-server |
http-server | dep:axum |
jj | vox-vcs/jj, runtime |
json-schema | vox-repository/json-schema |
lsp | dep:tower-lsp-server |
news-publish | dep:vox-publisher, vox-publisher/scientia-reddit, vox-publisher/scientia-youtube, vox-publisher/scholarly-external-jobs |
oratio-rerank | dep:vox-speech |
populi-transport | dep:vox-populi, vox-populi/transport, dep:aes-gcm, dep:vox-mesh-transport, dep:iroh |
runtime | vox-actor-runtime, vox-populi/mens, lsp |
system-metrics | dep:sysinfo |
test-support | — |
toestub-gate | vox-code-audit, vox-lsp, lsp |
token-counting | dep:tiktoken-rs |
vox-actor-runtime | dep:vox-actor-runtime |
vox-code-audit | dep:vox-code-audit |
vox-lsp | dep:vox-lsp |
Workspace Dependencies
Section titled “Workspace Dependencies”| Dependency | Kind |
|---|---|
vox-actor-runtime | Normal |
vox-bounded-fs | Normal |
vox-code-audit | Normal |
vox-config | Normal |
vox-corpus | Normal |
vox-crypto | Normal |
vox-db | Normal |
vox-foundation | Normal |
vox-gamify | Normal |
vox-http-client | Normal |
vox-lsp | Normal |
vox-mcp-registry | Normal |
vox-mesh-policy | Normal |
vox-mesh-transport | Normal |
vox-mesh-types | Normal |
vox-orchestrator-models | Normal |
vox-orchestrator-queue | Normal |
vox-orchestrator-types | Normal |
vox-package | Normal |
vox-populi | Normal |
vox-publisher | Normal |
vox-repository | Normal |
vox-research-events | Normal |
vox-search | Normal |
vox-secrets | Normal |
vox-skill-runtime | Normal |
vox-skills | Normal |
vox-speech | Normal |
vox-telemetry | Normal |
vox-vcs | Normal |
vox-actor-runtime | Development |
vox-test-harness | Development |
Public API Surface
Section titled “Public API Surface”Modules
Section titled “Modules”| Module | Description |
|---|---|
activity | — |
agentos | AgentOS: ACI-aligned mutation classification, guardrails, checkpoint hints. |
attachment_manifest | — |
json_vcs_facade | JSON-shaped VCS / workspace views for MCP and CLI parity. |
merge_conflicts | Pure conflict-recording core for workspace merge-back. |
feedback | — |
lineage | — |
route_policy | VOX_ROUTE_* alignment helpers for registry/MCP paths (see contracts orchestration routing YAML). |
routing | Centralized model-routing policy + Thompson exploration (see contracts/orchestration/model-routing.v1.yaml). |
a2a | Agent-to-agent messaging types and helpers. |
drain_oplog | Durable orchestrator state logs (drain records, etc.). |
spot_check | Submitter-side spot-check sampler for result verification (P5-T5). |
attention | Developer attention budget tracking — treats pilot attention as a first-class resource (Phase 15). |
attention_tracker | VoxDB persistence layer for attention events and agent trust scores (Phase 15). |
bootstrap | Shared bootstrap helpers for repository-aware orchestrator construction. |
budget | Token and cost budgets per agent and orchestrator-wide tracking. |
budget_gate | Orchestrator-policy token/cost budget gate (D7). |
bulletin | Shared bulletin board for cross-agent notices. |
cache_predictor | Prefix-cache hit predictor (D7). |
capability_probe | Host capability probing and merge with OrchestratorConfig::default_agent_capabilities. |
catalog | Dynamic model catalogs. |
catalog_classifier | — |
catalog_live | — |
circuit_breaker | Five-signal circuit breaker for doom-loop detection (D6). |
clarification_db_inbox_poll | DB-backed clarification inbox drain (Codex a2a_messages). |
compaction | Context window compaction for long-running agent sessions. |
compaction_trigger | Compaction strategy selector by context utilization (D7). |
confidence_fusion | Composite confidence fusion for Socrates invocation decision (D3). |
config | Orchestrator configuration load, merge, and validation. |
conflicts | File conflict detection and resolution hooks. |
context | Ephemeral context store for orchestrator-visible state. |
context_envelope | Canonical context envelope contract for cross-surface context payloads. |
context_handoff | Structured 5-strategy cross-agent context handoff (T3-HANDOFF-MCP-01). |
context_lifecycle | Context envelope ingest validation, merge policy, and lifecycle hooks. |
continuation | Continuation strategies when tasks pause or hand off. |
contract | Canonical orchestration contract types (v2 payloads, plan surface alignment). |
events | Agent activity events and pub/sub bus. |
events_severity | — |
external_importer | External AI session scanner & importer (~/.claude, ~/.codex, ~/.cursor) (T3-WEBHOOK-IMPORT-03). |
fatigue_monitor | Developer mental fatigue monitoring and cognitive pacing. |
gate | Pre/post task gates (including TOESTUB quality checks). |
generated | — |
grounding | Completion citation grounding against session context envelopes. |
groups | Affinity group registry built from repository layout. |
handoff | Structured handoff payloads between agents. |
legacy | — |
orchestrator_policy | Unified orchestrator policy façade composing all D1–D10. |
platform_ssot_generated | Polyglot cross-repo Platform SSOT v2.1 (synced from ngi.video/packages/platform-ssot). |
privacy_classifier | Sensitivity classifier and privacy-level-aware routing (D8). |
process_util | — |
research_gate | SCIENTIA pre-registration gate — refuses campaigns without a signed prereg (§5.1). |
risk_matrix | Four-dimension risk scorer and HITL escalation matrix (D5 + D9). |
subagent_dispatch | Sub-agent dispatch router: spawn vs. inline decision (D4). |
tier_cascade | Three-tier model cascade for autonomous model-routing (D1). |
entropy_scorer | Entropy-based hallucination detection. |
heartbeat | Agent liveness heartbeats and staleness policy. |
judge_model | Cross-model consensus and judge logic. |
hopper | Unified task hopper — intake funnel for developer-sourced work (Hp-T1). |
interrupt | Interrupt infrastructure for stopping in-progress local tasks (Track B partial). |
isolation | Multi-agent isolation strategy model + decision (spec §5.1). |
mcp_tools | MCP tool surface and plugin-skills bridge stubs (implementation pending SP6). |
memory | Long-term and daily agent memory backed by Codex when enabled. |
mesh | Live mesh node registry — authoritative in-memory topology view for the dashboard. |
mesh_federation_poll | Populi control-plane poll loop shared by MCP and vox-orchestrator-d. |
mesh_federation_poll | — |
models | LLM model registry and provider configuration. |
monitor | Lightweight AI usage / behavior monitor hooks. |
observer | File and task observer: real-time structural health evaluation (Wave 2). |
control | Drive Console control SSOT — ClutchProfile/RiskPosture parity gate. |
mode | — |
orch_daemon | TCP JSON-line orchestrator daemon (vox-orchestrator-d) and client helpers. |
orchestration_feature_flags | — |
orchestrator | Core multi-agent orchestrator implementation. |
oversight | Oversight composition: safety floor, policy enforcement, and approval tiers. |
pii_filter | PII-aware redacting filter for sensitive data. |
planning | Dynamic planning domain (router, synthesis, policies, replanning). |
populi_federation | Read-only mens HTTP federation snapshot types (filled by MCP / embedders). |
populi_remote | Populi remote execution gating and lease-class helpers. |
privacy_router | PII-aware privacy routing and data isolation policies. |
qa | Question/answer routing between agents. |
queue | Priority task queues and overflow handling. |
rebalance | Load-based agent scale-up/down suggestions. |
reconstruction | Reconstruction campaign tiers, evidence scoring, and resumable campaign state. |
registry_model_resolve | — |
retrieval | — |
schema | JSON schemas for persisted orchestrator artifacts. |
scope | Task path scopes and enforcement guards. |
search_bridge | Orchestrator ↔ vox-search adapters (lexical fallback, future native retrieval). |
security | Security policies, audit log, and guard checks. |
services | Embeddings, routing, scaling, policy, and gateway services. |
session | Durable agent session records and managers. |
snapshot | Workspace snapshots and content hashing for diffs. |
socrates | Socrates evidence gate and shared task context types. |
state | Serializable orchestrator state snapshots for UI and persistence. |
summary | Rolling summarization of agent interactions. |
tool_receipt | Cryptographic receipts for tool execution grounding. |
topology | — |
types | Core identifiers, tasks, messages, and shared value types. |
workspace | Per-agent workspace views and pending change tracking. |
validation | TOESTUB-based output validation gate integration. |
victory | Aggregate multi-tier verification signals. |
skill_runtime_inproc | In-process SkillRuntime implementation (P0-T7). |
runtime | Tokio scheduler bridge for running tasks against a live crate::Orchestrator. |
routing_processor | Generic TaskProcessor wrapper that dispatches by AgentTask::task_category (see runtime’s TaskProcessor trait, which this implements). Not hardcoded to any specific processor type — runtime.rs currently constructs it with the same AiTaskProcessor instance in both slots (Fix Task 4, gui-axis-chat-harness-fixes: the previous dedicated chat-only ChatTaskProcessor was deleted — it had no tool-calling loop, never read active_skill, and nothing produces TaskCategory::Chat in a way that expects that special handling anymore). |
lsp | LSP-facing helpers for ownership and diagnostics surfacing. |
preregistration | — |
secretary | — |
command_output_hub | Dedicated CommandOutputHub & \r terminal progress-bar normalization. |
context_sanitizer | Reasoning tag parser (<think>, <thinking>, <reason>, <reasoning>), <WebSearch> compactor & prompt-token sanitizer. |
guest_share | Host-moderated Live Guest Share (GuestShareService & GuestShareDecider). |
id_allocator | Deterministic Entity ID Allocator (VoxIdAllocatorV2 — { allocate, derive }). |
thread_run_queue | Per-thread run queue, mid-turn promote_to_steer, LimitRecoveryState & awaited: bool settlement. |
wire_compat | Forward-compatible discriminated union envelope (ForwardCompatibleEnvelope<T>). |
wire_compression | Wire Snapshot & Event Stream Compression (WireIdTableInterner, LiveBodyDeduper, and omit_idle_subagents). |
Dependency Topology
Section titled “Dependency Topology”Diagram source
graph { direction: right node vox_orchestrator: "vox-orchestrator" node vox_actor_runtime: "vox-actor-runtime" vox_orchestrator -> vox_actor_runtime node vox_bounded_fs: "vox-bounded-fs" vox_orchestrator -> vox_bounded_fs node vox_code_audit: "vox-code-audit" vox_orchestrator -> vox_code_audit node vox_config: "vox-config" vox_orchestrator -> vox_config node vox_corpus: "vox-corpus" vox_orchestrator -> vox_corpus node vox_crypto: "vox-crypto" vox_orchestrator -> vox_crypto node vox_db: "vox-db" vox_orchestrator -> vox_db node vox_foundation: "vox-foundation" vox_orchestrator -> vox_foundation node vox_gamify: "vox-gamify" vox_orchestrator -> vox_gamify node vox_http_client: "vox-http-client" vox_orchestrator -> vox_http_client node vox_lsp: "vox-lsp" vox_orchestrator -> vox_lsp node vox_mcp_registry: "vox-mcp-registry" vox_orchestrator -> vox_mcp_registry node vox_cli: "vox-cli" vox_cli -> vox_orchestrator node vox_cli_ci: "vox-cli-ci" vox_cli_ci -> vox_orchestrator node vox_cli_core: "vox-cli-core" vox_cli_core -> vox_orchestrator node vox_cli_research: "vox-cli-research" vox_cli_research -> vox_orchestrator node vox_gui: "vox-gui" vox_gui -> vox_orchestrator node vox_integration_tests: "vox-integration-tests" vox_integration_tests -> vox_orchestrator node vox_ml_cli: "vox-ml-cli" vox_ml_cli -> vox_orchestrator node vox_orchestrator_d: "vox-orchestrator-d" vox_orchestrator_d -> vox_orchestrator node vox_orchestrator_driver: "vox-orchestrator-driver" vox_orchestrator_driver -> vox_orchestrator node vox_orchestrator_mcp: "vox-orchestrator-mcp" vox_orchestrator_mcp -> vox_orchestrator node vox_orchestrator_test_helpers: "vox-orchestrator-test-helpers" vox_orchestrator_test_helpers -> vox_orchestrator node vox_research_shim: "vox-research-shim" vox_research_shim -> vox_orchestrator}Reverse Dependents (Used By)
Section titled “Reverse Dependents (Used By)”| Consumer Crate | Role |
|---|---|
vox-cli | Direct workspace dependent |
vox-cli-ci | Direct workspace dependent |
vox-cli-core | Direct workspace dependent |
vox-cli-research | Direct workspace dependent |
vox-gui | Direct workspace dependent |
vox-integration-tests | Direct workspace dependent |
vox-ml-cli | Direct workspace dependent |
vox-orchestrator-d | Direct workspace dependent |
vox-orchestrator-driver | Direct workspace dependent |
vox-orchestrator-mcp | Direct workspace dependent |
vox-orchestrator-test-helpers | Direct workspace dependent |
vox-research-shim | Direct workspace dependent |
vox-terminal-core | Direct workspace dependent |
Deep Public Symbols (Source-Anchored)
Section titled “Deep Public Symbols (Source-Anchored)”| Kind | Symbol | Signature | Source | Description |
|---|---|---|---|---|
fn | activity::is_loggable | pub fn is_loggable(kind: &AgentEventKind) -> bool | crates/vox-orchestrator/src/activity/mod.rs#L12-L39 | SSOT: true for high-signal lifecycle/resource/build events; false for high-frequency telemetry (heartbeats, throughput/cost ticks, file-diag churn). TASK-2.0 |
struct | attachment_manifest::AttachmentManifest | pub struct AttachmentManifest | crates/vox-orchestrator/src/attachment_manifest.rs#L6-L8 | AttachmentManifest: Explicit routing for visual and blob attachments. Eradicates heuristic-based vision inference in favor of SHA-256 gated capabilities. |
struct | attachment_manifest::AttachmentEntry | pub struct AttachmentEntry | crates/vox-orchestrator/src/attachment_manifest.rs#L11-L20 | — |
struct | attachment_manifest::VisualSegment | pub struct VisualSegment | crates/vox-orchestrator/src/attachment_manifest.rs#L23-L29 | — |
fn | attachment_manifest::has_vision_vitals | pub fn has_vision_vitals(&self) -> bool | crates/vox-orchestrator/src/attachment_manifest.rs#L33-L37 | Returns true if the manifest contains any vision-eligible attachments (images). |
struct | attention_tracker::AttentionSessionSummary | pub struct AttentionSessionSummary | crates/vox-orchestrator/src/attention_tracker.rs#L14-L22 | Summary returned by [AttentionTracker::session_summary()]. |
struct | attention_tracker::AttentionTracker | pub struct AttentionTracker<'a> | crates/vox-orchestrator/src/attention_tracker.rs#L25-L27 | Persists attention metrics to Arca (VoxDB) collections. |
fn | attention_tracker::new | pub fn new(db: &'a vox_db::VoxDb) -> Self | crates/vox-orchestrator/src/attention_tracker.rs#L30-L32 | — |
fn | attention_tracker::record_event | pub async fn record_event( | crates/vox-orchestrator/src/attention_tracker.rs#L37 | Record a single attention event. Append-only log. |
fn | attention_tracker::list_events | pub async fn list_events( | crates/vox-orchestrator/src/attention_tracker.rs#L64 | Retrieve the most recent attention events up to a given limit. |
fn | attention_tracker::session_summary | pub async fn session_summary( | crates/vox-orchestrator/src/attention_tracker.rs#L84 | Session summary: total spent, efficiency, auto-approve ratio. |
fn | attention_tracker::upsert_trust | pub async fn upsert_trust( | crates/vox-orchestrator/src/attention_tracker.rs#L144 | Persist or update the trust score for an agent. |
fn | attention_tracker::load_trust | pub async fn load_trust( | crates/vox-orchestrator/src/attention_tracker.rs#L176 | Load trust score for a single agent. |
fn | attention_tracker::load_all_trust | pub async fn load_all_trust( | crates/vox-orchestrator/src/attention_tracker.rs#L212 | Load all trust scores keyed by AgentId (for routing injection). |
struct | bootstrap::RepoScopedOrchestratorBuild | pub struct RepoScopedOrchestratorBuild | crates/vox-orchestrator/src/bootstrap.rs#L11-L16 | Single factory output for embedding Orchestrator in MCP, CLI, daemons, and tests. Construct via [build_repo_scoped_orchestrator] or [build_repo_scoped_orchestrator_for_repository] so all surfaces share identical repo-scoped config, affinity groups, and memory paths. |
fn | bootstrap::build_repo_scoped_orchestrator | pub fn build_repo_scoped_orchestrator( | crates/vox-orchestrator/src/bootstrap.rs#L20 | Discover repository from start_dir (or process CWD), then build [Orchestrator] with repo-scoped config. |
fn | bootstrap::build_repo_scoped_orchestrator_for_repository | pub fn build_repo_scoped_orchestrator_for_repository( | crates/vox-orchestrator/src/bootstrap.rs#L32 | Build [Orchestrator] for an already-resolved [vox_repository::RepositoryContext]. Use when the repository root was discovered out-of-band (for example with_workspace_root in MCP). |
fn | bootstrap::discover_repository_from_cwd | pub fn discover_repository_from_cwd(start_dir: Option<&Path>) -> vox_repository::RepositoryContext | crates/vox-orchestrator/src/bootstrap.rs#L47-L54 | Discover repository context from start_dir, falling back to process CWD then ”.”. |
fn | bootstrap::repo_scoped_orchestrator_parts | pub fn repo_scoped_orchestrator_parts( | crates/vox-orchestrator/src/bootstrap.rs#L60 | Build repository-scoped config and affinity groups: - affinity_groups from Vox.toml when present, else repository-layout detection - memory rooted at .vox/memory (canonical workspace path; legacy shard migrated at startup). |
fn | bootstrap::repo_scoped_orchestrator_config | pub fn repo_scoped_orchestrator_config( | crates/vox-orchestrator/src/bootstrap.rs#L79 | Convenience helper when only the repository-scoped config is needed. |
struct | budget::AgentBudgetAllocation | pub struct AgentBudgetAllocation | crates/vox-orchestrator/src/budget/mod.rs#L16-L22 | Per-agent budget allocation cap. |
fn | budget::new | pub fn new(max_tokens: usize, max_cost_usd: f64) -> Self | crates/vox-orchestrator/src/budget/mod.rs#L25-L43 | — |
fn | budget::with_rollover | pub fn with_rollover(mut self, fraction: f64) -> Self | crates/vox-orchestrator/src/budget/mod.rs#L45-L48 | — |
fn | budget::with_alert_thresholds | pub fn with_alert_thresholds(mut self, token: f64, cost: f64) -> Self | crates/vox-orchestrator/src/budget/mod.rs#L50-L54 | — |
struct | budget::ContextBudget | pub struct ContextBudget | crates/vox-orchestrator/src/budget/mod.rs#L59-L69 | Configuration for an agent’s context budget. |
fn | budget::new | pub fn new(agent_id: AgentId, max_tokens: usize) -> Self | crates/vox-orchestrator/src/budget/mod.rs#L72-L82 | — |
fn | budget::effective_max_tokens | pub fn effective_max_tokens(&self) -> usize | crates/vox-orchestrator/src/budget/mod.rs#L84-L91 | — |
fn | budget::tokens_available | pub fn tokens_available(&self) -> usize | crates/vox-orchestrator/src/budget/mod.rs#L93-L95 | — |
fn | budget::should_summarize | pub fn should_summarize(&self) -> bool | crates/vox-orchestrator/src/budget/mod.rs#L97-L104 | — |
fn | budget::token_alert | pub fn token_alert(&self) -> bool | crates/vox-orchestrator/src/budget/mod.rs#L106-L108 | — |
fn | budget::cost_alert | pub fn cost_alert(&self) -> bool | crates/vox-orchestrator/src/budget/mod.rs#L110-L116 | — |
fn | budget::cost_exceeded | pub fn cost_exceeded(&self) -> bool | crates/vox-orchestrator/src/budget/mod.rs#L118-L124 | — |
fn | budget::rollover | pub fn rollover(&mut self) -> usize | crates/vox-orchestrator/src/budget/mod.rs#L126-L136 | — |
enum | budget::BudgetSignal | pub enum BudgetSignal | crates/vox-orchestrator/src/budget/mod.rs#L141-L183 | Unified budget signal for behavioral gating (tokens, cost, and attention). |
fn | budget::no_auto_reload_guaranteed | pub const fn no_auto_reload_guaranteed(&self) -> bool | crates/vox-orchestrator/src/budget/mod.rs#L189-L191 | Vox’s structural anti-extractive guarantee: BudgetSignal::CostExceeded never triggers a silent credit auto-reload or overage billing. |
fn | budget::cost_exceeded_recommendation | pub const fn cost_exceeded_recommendation(&self) -> Option<&'static str> | crates/vox-orchestrator/src/budget/mod.rs#L195-L202 | Actionable, non-coercive recommendation when a user’s explicit cost cap is reached. |
struct | budget::TurnCostReceipt | pub struct TurnCostReceipt | crates/vox-orchestrator/src/budget/mod.rs#L211-L221 | Zero-markup per-turn cost and savings receipt (HUMANE-01). Proves that Vox applies $0.00 platform markup over upstream BYOK/local inference and quantifies how much developer budget was preserved compared to frontier cloud rates ($15.00/M input, $75.00/M output). |
fn | budget::new | pub fn new( | crates/vox-orchestrator/src/budget/mod.rs#L230 | — |
fn | budget::format_footer | pub fn format_footer(&self) -> String | crates/vox-orchestrator/src/budget/mod.rs#L257-L268 | Format a concise, honest 1-line receipt footer for CLI and telemetry surfaces. |
struct | budget::DriftRecord | pub struct DriftRecord | crates/vox-orchestrator/src/budget/mod.rs#L273-L278 | A record of a single agent iteration for drift detection. |
enum | budget::DriftDecision | pub enum DriftDecision | crates/vox-orchestrator/src/budget/mod.rs#L282-L286 | Decision from the drift detector. |
struct | budget::DriftState | pub struct DriftState | crates/vox-orchestrator/src/budget/mod.rs#L290-L295 | Internal state for tracking agent semantic drift. |
struct | budget::BudgetManager | pub struct BudgetManager | crates/vox-orchestrator/src/budget/mod.rs#L306-L333 | Tracks agent context budgets globally. |
fn | budget::new | pub fn new(db: Option<Arc<vox_db::VoxDb>>) -> Self | crates/vox-orchestrator/src/budget/mod.rs#L336-L378 | — |
fn | budget::db | pub fn db(&self) -> Option<Arc<vox_db::VoxDb>> | crates/vox-orchestrator/src/budget/mod.rs#L380-L382 | — |