VOXCapability

File: vox/capabilities/base.py

A capability is the atomic unit of system permission in VOX. It wraps an external service or resource behind a clean async interface. Agents hold no implicit system power — every I/O operation must go through a capability.

The Split: Definition vs Binding

VOXCapability        →  stateless singleton, shared across agents
VOXBoundCapability   →  per-agent proxy with resolved config params

When a role requires a capability, the CapabilityBinder:

1. Obtains the capability singleton from the orchestrator registry.
2. Calls capability.mount(agent, config) which extracts params and creates a VOXBoundCapability.
3. Stores agent.capabilities[cap_id] = bound — the agent talks to the bound proxy.
4. Injects vault secrets for SENSITIVE_PARAMS.
5. Validates required params and registers EXPOSED_COMMANDS.

Contract (per VOXCapability)

Member	Required?	Purpose
CAPABILITY_NAME	Yes	Unique dotted ID (e.g. "ai.llm")
PARAMS	Yes	{name: [description, default]} — None default = required
SENSITIVE_PARAMS	No	set[str] of credential params injected from the vault
EXPOSED_COMMANDS	No	[{name, description, method}] registered as agent commands
health_check()	No	Classmethod, returns bool, run at discovery
boot()	No	Async, called when agent boots
shutdown()	No	Async, called on teardown
Public methods	Yes	Named async methods agents call (e.g. generate(), send_text())

VOXBoundCapability

The per-agent proxy returned by VOXCapability.mount(). It is a frozen object — once freeze() is called, public attributes cannot be mutated. It provides:

• self.PARAM_NAME — resolved configuration values (e.g. self.LLM_API_URL)
• self.log() / self.warning() / self.error() / self.ok() — logging with capability prefix
• self._agent — reference to the owning agent
• self.validate_params() — returns list of missing required params
• self.initialize() — raises ValueError if required params are missing
• self.method() — delegated to the underlying VOXCapability, with self injected as bound proxy

The __getattr__ wrapper on VOXBoundCapability automatically injects the bound proxy as self — so method code has access to resolved params, the logger, and the owning agent without any additional wiring.

Configuration sentinels

In bound capability params, None means required (agent flagged DEGRADED if missing) and "" means unconfigured / feature inactive. Optional credentials MUST default to "", never None. See Capabilities Reference.

Existing Capabilities

ID	Module	Service
ai.llm	vox/capabilities/ai/llm/	LLM inference (local & cloud)
comm.email	vox/capabilities/comm/email/	SMTP email dispatch
comm.gateway	vox/capabilities/comm/gateway/	Multi-channel messaging (Telegram, WhatsApp, webhook)
comm.voicetotext	vox/capabilities/comm/voicetotext/	Speech-to-text
net.browser	vox/capabilities/net/browser/	Headless browser

See Capabilities Reference and Comm Gateway.

Writing a New Capability

See the Capability Contract for the full checklist and template structure.