Skip to content

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.

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.

User Request
│
▼
Orchestrator ──► FileAffinityMap ──► route to Agent
│ │
▼ ▼
BulletinBoard ◄──── AgentQueue ──► FileLockManager
  • runtime — Actor-based agents using vox-actor-runtime Scheduler/Supervisor
  • toestub-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).

FeatureDefault / Enables
corpus-dbvox-corpus/database
defaulttoestub-gate, runtime, json-schema, jj, corpus-db, http-server
http-serverdep:axum
jjvox-vcs/jj, runtime
json-schemavox-repository/json-schema
lspdep:tower-lsp-server
news-publishdep:vox-publisher, vox-publisher/scientia-reddit, vox-publisher/scientia-youtube, vox-publisher/scholarly-external-jobs
oratio-rerankdep:vox-speech
populi-transportdep:vox-populi, vox-populi/transport, dep:aes-gcm, dep:vox-mesh-transport, dep:iroh
runtimevox-actor-runtime, vox-populi/mens, lsp
system-metricsdep:sysinfo
test-support—
toestub-gatevox-code-audit, vox-lsp, lsp
token-countingdep:tiktoken-rs
vox-actor-runtimedep:vox-actor-runtime
vox-code-auditdep:vox-code-audit
vox-lspdep:vox-lsp
DependencyKind
vox-actor-runtimeNormal
vox-bounded-fsNormal
vox-code-auditNormal
vox-configNormal
vox-corpusNormal
vox-cryptoNormal
vox-dbNormal
vox-foundationNormal
vox-gamifyNormal
vox-http-clientNormal
vox-lspNormal
vox-mcp-registryNormal
vox-mesh-policyNormal
vox-mesh-transportNormal
vox-mesh-typesNormal
vox-orchestrator-modelsNormal
vox-orchestrator-queueNormal
vox-orchestrator-typesNormal
vox-packageNormal
vox-populiNormal
vox-publisherNormal
vox-repositoryNormal
vox-research-eventsNormal
vox-searchNormal
vox-secretsNormal
vox-skill-runtimeNormal
vox-skillsNormal
vox-speechNormal
vox-telemetryNormal
vox-vcsNormal
vox-actor-runtimeDevelopment
vox-test-harnessDevelopment
ModuleDescription
activity—
agentosAgentOS: ACI-aligned mutation classification, guardrails, checkpoint hints.
attachment_manifest—
json_vcs_facadeJSON-shaped VCS / workspace views for MCP and CLI parity.
merge_conflictsPure conflict-recording core for workspace merge-back.
feedback—
lineage—
route_policyVOX_ROUTE_* alignment helpers for registry/MCP paths (see contracts orchestration routing YAML).
routingCentralized model-routing policy + Thompson exploration (see contracts/orchestration/model-routing.v1.yaml).
a2aAgent-to-agent messaging types and helpers.
drain_oplogDurable orchestrator state logs (drain records, etc.).
spot_checkSubmitter-side spot-check sampler for result verification (P5-T5).
attentionDeveloper attention budget tracking — treats pilot attention as a first-class resource (Phase 15).
attention_trackerVoxDB persistence layer for attention events and agent trust scores (Phase 15).
bootstrapShared bootstrap helpers for repository-aware orchestrator construction.
budgetToken and cost budgets per agent and orchestrator-wide tracking.
budget_gateOrchestrator-policy token/cost budget gate (D7).
bulletinShared bulletin board for cross-agent notices.
cache_predictorPrefix-cache hit predictor (D7).
capability_probeHost capability probing and merge with OrchestratorConfig::default_agent_capabilities.
catalogDynamic model catalogs.
catalog_classifier—
catalog_live—
circuit_breakerFive-signal circuit breaker for doom-loop detection (D6).
clarification_db_inbox_pollDB-backed clarification inbox drain (Codex a2a_messages).
compactionContext window compaction for long-running agent sessions.
compaction_triggerCompaction strategy selector by context utilization (D7).
confidence_fusionComposite confidence fusion for Socrates invocation decision (D3).
configOrchestrator configuration load, merge, and validation.
conflictsFile conflict detection and resolution hooks.
contextEphemeral context store for orchestrator-visible state.
context_envelopeCanonical context envelope contract for cross-surface context payloads.
context_handoffStructured 5-strategy cross-agent context handoff (T3-HANDOFF-MCP-01).
context_lifecycleContext envelope ingest validation, merge policy, and lifecycle hooks.
continuationContinuation strategies when tasks pause or hand off.
contractCanonical orchestration contract types (v2 payloads, plan surface alignment).
eventsAgent activity events and pub/sub bus.
events_severity—
external_importerExternal AI session scanner & importer (~/.claude, ~/.codex, ~/.cursor) (T3-WEBHOOK-IMPORT-03).
fatigue_monitorDeveloper mental fatigue monitoring and cognitive pacing.
gatePre/post task gates (including TOESTUB quality checks).
generated—
groundingCompletion citation grounding against session context envelopes.
groupsAffinity group registry built from repository layout.
handoffStructured handoff payloads between agents.
legacy—
orchestrator_policyUnified orchestrator policy façade composing all D1–D10.
platform_ssot_generatedPolyglot cross-repo Platform SSOT v2.1 (synced from ngi.video/packages/platform-ssot).
privacy_classifierSensitivity classifier and privacy-level-aware routing (D8).
process_util—
research_gateSCIENTIA pre-registration gate — refuses campaigns without a signed prereg (§5.1).
risk_matrixFour-dimension risk scorer and HITL escalation matrix (D5 + D9).
subagent_dispatchSub-agent dispatch router: spawn vs. inline decision (D4).
tier_cascadeThree-tier model cascade for autonomous model-routing (D1).
entropy_scorerEntropy-based hallucination detection.
heartbeatAgent liveness heartbeats and staleness policy.
judge_modelCross-model consensus and judge logic.
hopperUnified task hopper — intake funnel for developer-sourced work (Hp-T1).
interruptInterrupt infrastructure for stopping in-progress local tasks (Track B partial).
isolationMulti-agent isolation strategy model + decision (spec §5.1).
mcp_toolsMCP tool surface and plugin-skills bridge stubs (implementation pending SP6).
memoryLong-term and daily agent memory backed by Codex when enabled.
meshLive mesh node registry — authoritative in-memory topology view for the dashboard.
mesh_federation_pollPopuli control-plane poll loop shared by MCP and vox-orchestrator-d.
mesh_federation_poll—
modelsLLM model registry and provider configuration.
monitorLightweight AI usage / behavior monitor hooks.
observerFile and task observer: real-time structural health evaluation (Wave 2).
controlDrive Console control SSOT — ClutchProfile/RiskPosture parity gate.
mode—
orch_daemonTCP JSON-line orchestrator daemon (vox-orchestrator-d) and client helpers.
orchestration_feature_flags—
orchestratorCore multi-agent orchestrator implementation.
oversightOversight composition: safety floor, policy enforcement, and approval tiers.
pii_filterPII-aware redacting filter for sensitive data.
planningDynamic planning domain (router, synthesis, policies, replanning).
populi_federationRead-only mens HTTP federation snapshot types (filled by MCP / embedders).
populi_remotePopuli remote execution gating and lease-class helpers.
privacy_routerPII-aware privacy routing and data isolation policies.
qaQuestion/answer routing between agents.
queuePriority task queues and overflow handling.
rebalanceLoad-based agent scale-up/down suggestions.
reconstructionReconstruction campaign tiers, evidence scoring, and resumable campaign state.
registry_model_resolve—
retrieval—
schemaJSON schemas for persisted orchestrator artifacts.
scopeTask path scopes and enforcement guards.
search_bridgeOrchestrator ↔ vox-search adapters (lexical fallback, future native retrieval).
securitySecurity policies, audit log, and guard checks.
servicesEmbeddings, routing, scaling, policy, and gateway services.
sessionDurable agent session records and managers.
snapshotWorkspace snapshots and content hashing for diffs.
socratesSocrates evidence gate and shared task context types.
stateSerializable orchestrator state snapshots for UI and persistence.
summaryRolling summarization of agent interactions.
tool_receiptCryptographic receipts for tool execution grounding.
topology—
typesCore identifiers, tasks, messages, and shared value types.
workspacePer-agent workspace views and pending change tracking.
validationTOESTUB-based output validation gate integration.
victoryAggregate multi-tier verification signals.
skill_runtime_inprocIn-process SkillRuntime implementation (P0-T7).
runtimeTokio scheduler bridge for running tasks against a live crate::Orchestrator.
routing_processorGeneric 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).
lspLSP-facing helpers for ownership and diagnostics surfacing.
preregistration—
secretary—
command_output_hubDedicated CommandOutputHub & \r terminal progress-bar normalization.
context_sanitizerReasoning tag parser (<think>, <thinking>, <reason>, <reasoning>), <WebSearch> compactor & prompt-token sanitizer.
guest_shareHost-moderated Live Guest Share (GuestShareService & GuestShareDecider).
id_allocatorDeterministic Entity ID Allocator (VoxIdAllocatorV2 — { allocate, derive }).
thread_run_queuePer-thread run queue, mid-turn promote_to_steer, LimitRecoveryState & awaited: bool settlement.
wire_compatForward-compatible discriminated union envelope (ForwardCompatibleEnvelope<T>).
wire_compressionWire Snapshot & Event Stream Compression (WireIdTableInterner, LiveBodyDeduper, and omit_idle_subagents).
Dependency Topology, diagram 125 nodes, 24 edges: vox-orchestrator → vox-actor-runtime; vox-orchestrator → vox-bounded-fs; vox-orchestrator → vox-code-audit; vox-orchestrator → vox-config; vox-orchestrator → vox-corpus; vox-orchestrator → vox-crypto; vox-orchestrator → vox-db; vox-orchestrator → vox-foundation; vox-orchestrator…vox-orchestratorvox-actor-runtimevox-bounded-fsvox-code-auditvox-configvox-corpusvox-cryptovox-dbvox-foundationvox-gamifyvox-http-clientvox-lspvox-mcp-registryvox-clivox-cli-civox-cli-corevox-cli-researchvox-guivox-integration-testsvox-ml-clivox-orchestrator-dvox-orchestrator-drivervox-orchestrator-mcpvox-orchestrator-test-helpersvox-research-shim
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
}
Consumer CrateRole
vox-cliDirect workspace dependent
vox-cli-ciDirect workspace dependent
vox-cli-coreDirect workspace dependent
vox-cli-researchDirect workspace dependent
vox-guiDirect workspace dependent
vox-integration-testsDirect workspace dependent
vox-ml-cliDirect workspace dependent
vox-orchestrator-dDirect workspace dependent
vox-orchestrator-driverDirect workspace dependent
vox-orchestrator-mcpDirect workspace dependent
vox-orchestrator-test-helpersDirect workspace dependent
vox-research-shimDirect workspace dependent
vox-terminal-coreDirect workspace dependent
KindSymbolSignatureSourceDescription
fnactivity::is_loggablepub fn is_loggable(kind: &AgentEventKind) -> boolcrates/vox-orchestrator/src/activity/mod.rs#L12-L39SSOT: true for high-signal lifecycle/resource/build events; false for high-frequency telemetry (heartbeats, throughput/cost ticks, file-diag churn). TASK-2.0
structattachment_manifest::AttachmentManifestpub struct AttachmentManifestcrates/vox-orchestrator/src/attachment_manifest.rs#L6-L8AttachmentManifest: Explicit routing for visual and blob attachments. Eradicates heuristic-based vision inference in favor of SHA-256 gated capabilities.
structattachment_manifest::AttachmentEntrypub struct AttachmentEntrycrates/vox-orchestrator/src/attachment_manifest.rs#L11-L20—
structattachment_manifest::VisualSegmentpub struct VisualSegmentcrates/vox-orchestrator/src/attachment_manifest.rs#L23-L29—
fnattachment_manifest::has_vision_vitalspub fn has_vision_vitals(&self) -> boolcrates/vox-orchestrator/src/attachment_manifest.rs#L33-L37Returns true if the manifest contains any vision-eligible attachments (images).
structattention_tracker::AttentionSessionSummarypub struct AttentionSessionSummarycrates/vox-orchestrator/src/attention_tracker.rs#L14-L22Summary returned by [AttentionTracker::session_summary()].
structattention_tracker::AttentionTrackerpub struct AttentionTracker<'a>crates/vox-orchestrator/src/attention_tracker.rs#L25-L27Persists attention metrics to Arca (VoxDB) collections.
fnattention_tracker::newpub fn new(db: &'a vox_db::VoxDb) -> Selfcrates/vox-orchestrator/src/attention_tracker.rs#L30-L32—
fnattention_tracker::record_eventpub async fn record_event(crates/vox-orchestrator/src/attention_tracker.rs#L37Record a single attention event. Append-only log.
fnattention_tracker::list_eventspub async fn list_events(crates/vox-orchestrator/src/attention_tracker.rs#L64Retrieve the most recent attention events up to a given limit.
fnattention_tracker::session_summarypub async fn session_summary(crates/vox-orchestrator/src/attention_tracker.rs#L84Session summary: total spent, efficiency, auto-approve ratio.
fnattention_tracker::upsert_trustpub async fn upsert_trust(crates/vox-orchestrator/src/attention_tracker.rs#L144Persist or update the trust score for an agent.
fnattention_tracker::load_trustpub async fn load_trust(crates/vox-orchestrator/src/attention_tracker.rs#L176Load trust score for a single agent.
fnattention_tracker::load_all_trustpub async fn load_all_trust(crates/vox-orchestrator/src/attention_tracker.rs#L212Load all trust scores keyed by AgentId (for routing injection).
structbootstrap::RepoScopedOrchestratorBuildpub struct RepoScopedOrchestratorBuildcrates/vox-orchestrator/src/bootstrap.rs#L11-L16Single 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.
fnbootstrap::build_repo_scoped_orchestratorpub fn build_repo_scoped_orchestrator(crates/vox-orchestrator/src/bootstrap.rs#L20Discover repository from start_dir (or process CWD), then build [Orchestrator] with repo-scoped config.
fnbootstrap::build_repo_scoped_orchestrator_for_repositorypub fn build_repo_scoped_orchestrator_for_repository(crates/vox-orchestrator/src/bootstrap.rs#L32Build [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).
fnbootstrap::discover_repository_from_cwdpub fn discover_repository_from_cwd(start_dir: Option<&Path>) -> vox_repository::RepositoryContextcrates/vox-orchestrator/src/bootstrap.rs#L47-L54Discover repository context from start_dir, falling back to process CWD then ”.”.
fnbootstrap::repo_scoped_orchestrator_partspub fn repo_scoped_orchestrator_parts(crates/vox-orchestrator/src/bootstrap.rs#L60Build 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).
fnbootstrap::repo_scoped_orchestrator_configpub fn repo_scoped_orchestrator_config(crates/vox-orchestrator/src/bootstrap.rs#L79Convenience helper when only the repository-scoped config is needed.
structbudget::AgentBudgetAllocationpub struct AgentBudgetAllocationcrates/vox-orchestrator/src/budget/mod.rs#L16-L22Per-agent budget allocation cap.
fnbudget::newpub fn new(max_tokens: usize, max_cost_usd: f64) -> Selfcrates/vox-orchestrator/src/budget/mod.rs#L25-L43—
fnbudget::with_rolloverpub fn with_rollover(mut self, fraction: f64) -> Selfcrates/vox-orchestrator/src/budget/mod.rs#L45-L48—
fnbudget::with_alert_thresholdspub fn with_alert_thresholds(mut self, token: f64, cost: f64) -> Selfcrates/vox-orchestrator/src/budget/mod.rs#L50-L54—
structbudget::ContextBudgetpub struct ContextBudgetcrates/vox-orchestrator/src/budget/mod.rs#L59-L69Configuration for an agent’s context budget.
fnbudget::newpub fn new(agent_id: AgentId, max_tokens: usize) -> Selfcrates/vox-orchestrator/src/budget/mod.rs#L72-L82—
fnbudget::effective_max_tokenspub fn effective_max_tokens(&self) -> usizecrates/vox-orchestrator/src/budget/mod.rs#L84-L91—
fnbudget::tokens_availablepub fn tokens_available(&self) -> usizecrates/vox-orchestrator/src/budget/mod.rs#L93-L95—
fnbudget::should_summarizepub fn should_summarize(&self) -> boolcrates/vox-orchestrator/src/budget/mod.rs#L97-L104—
fnbudget::token_alertpub fn token_alert(&self) -> boolcrates/vox-orchestrator/src/budget/mod.rs#L106-L108—
fnbudget::cost_alertpub fn cost_alert(&self) -> boolcrates/vox-orchestrator/src/budget/mod.rs#L110-L116—
fnbudget::cost_exceededpub fn cost_exceeded(&self) -> boolcrates/vox-orchestrator/src/budget/mod.rs#L118-L124—
fnbudget::rolloverpub fn rollover(&mut self) -> usizecrates/vox-orchestrator/src/budget/mod.rs#L126-L136—
enumbudget::BudgetSignalpub enum BudgetSignalcrates/vox-orchestrator/src/budget/mod.rs#L141-L183Unified budget signal for behavioral gating (tokens, cost, and attention).
fnbudget::no_auto_reload_guaranteedpub const fn no_auto_reload_guaranteed(&self) -> boolcrates/vox-orchestrator/src/budget/mod.rs#L189-L191Vox’s structural anti-extractive guarantee: BudgetSignal::CostExceeded never triggers a silent credit auto-reload or overage billing.
fnbudget::cost_exceeded_recommendationpub const fn cost_exceeded_recommendation(&self) -> Option<&'static str>crates/vox-orchestrator/src/budget/mod.rs#L195-L202Actionable, non-coercive recommendation when a user’s explicit cost cap is reached.
structbudget::TurnCostReceiptpub struct TurnCostReceiptcrates/vox-orchestrator/src/budget/mod.rs#L211-L221Zero-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).
fnbudget::newpub fn new(crates/vox-orchestrator/src/budget/mod.rs#L230—
fnbudget::format_footerpub fn format_footer(&self) -> Stringcrates/vox-orchestrator/src/budget/mod.rs#L257-L268Format a concise, honest 1-line receipt footer for CLI and telemetry surfaces.
structbudget::DriftRecordpub struct DriftRecordcrates/vox-orchestrator/src/budget/mod.rs#L273-L278A record of a single agent iteration for drift detection.
enumbudget::DriftDecisionpub enum DriftDecisioncrates/vox-orchestrator/src/budget/mod.rs#L282-L286Decision from the drift detector.
structbudget::DriftStatepub struct DriftStatecrates/vox-orchestrator/src/budget/mod.rs#L290-L295Internal state for tracking agent semantic drift.
structbudget::BudgetManagerpub struct BudgetManagercrates/vox-orchestrator/src/budget/mod.rs#L306-L333Tracks agent context budgets globally.
fnbudget::newpub fn new(db: Option<Arc<vox_db::VoxDb>>) -> Selfcrates/vox-orchestrator/src/budget/mod.rs#L336-L378—
fnbudget::dbpub fn db(&self) -> Option<Arc<vox_db::VoxDb>>crates/vox-orchestrator/src/budget/mod.rs#L380-L382—