vox-orchestrator API Reference (generated)

`vox-orchestrator`

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

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

User Request
│
▼
Orchestrator ──► FileAffinityMap ──► route to Agent
│                                    │
▼                                    ▼
BulletinBoard ◄──── AgentQueue ──► FileLockManager

Features

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).

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

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

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_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`	—
`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.
`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.
`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`	—