VOXOrchestrator

File: vox/orchestration/base.py

The orchestrator is the runtime kernel of VOX. It owns all agent and capability state and is the single source of truth for the fleet. It is a facade that delegates to specialised service components (VOXRegistry, AgentGraph, FleetController, VOXWarRoom, AgentFileWatcher).

Responsibilities

Concern	Detail
Capability discovery	Scans vox/capabilities/ for capability modules, loads each, runs health_check(), stores in the registry
Agent discovery	Scans agent directories for agent.yml, resolves master/child hierarchy, creates agents in topological order
Lifecycle management	start, stop, pause, resume, restart for every agent
Hierarchy resolution	Parent-child chain via master_id; ensures a child is only created after its parent
Inbound routing	dispatch_inbound_message() sanitizes and routes webhook/event payloads to the correct agent
Identity & security	VOXSpeakerProfile for voice verification; InputSanitizer guardrail; per-agent rate limiting
War Room	VOXWarRoom / VOXWarRoomMaster for incident alerting, mirrored to a Telegram channel via FleetMessenger

Key Methods

Method	Returns	Purpose
get_fleet_snapshot()	dict	Complete system state: system info, capabilities, agent tree, degraded agents, hierarchy
get_capability_instance(cap_id)	VOXCapability | None	Capability singleton from the registry
resolve_agent_id(name)	str | None	Name → UUID lookup
get_hierarchy_snapshot()	dict[str, list[str]]	Hierarchy map (parent → children UUIDs)
get_children(agent_id)	list	Direct subordinates (list of VOXAgent)
_resolve_agent(identifier)	VOXAgent | None	Resolve UUID or name to an agent
stop_agent / restart_agent / start_agent_by_name / pause_agent / resume_agent	bool	Lifecycle operations (delegated to FleetController)
dispatch_inbound_message(source, payload)	None	Sanitize and route an inbound payload to the owning agent (inbound_message event) or the war room (alert type)
panic_shutdown()	None	Synchronous emergency stop: freezes tasks, purges vault keys, flushes war room

Agents access the orchestrator via self.agent.orchestrator.

Discovery Order

1. Capabilities are loaded from vox/capabilities/**/capability.py and registered keyed by CAPABILITY_NAME.
2. Every capability runs health_check(); unhealthy ones are flagged but still registered.
3. Agent directories are scanned for agent.yml. The master/child hierarchy is resolved via master_id.
4. Agents are constructed in topological order (root first, then children).
5. Each agent's roles are loaded; required capabilities are mounted as VOXBoundCapability proxies.
6. agent.boot() is called on each to transition to ACTIVE.