Skip to content

vox-actor-runtime API Reference (generated)

Crate: vox-actor-runtime · Version: 0.6.0 · Target: Library (lib.rs)

Process-oriented runtime: actors, mailboxes, supervision, scheduling, LLM/Mens activity primitives.

Process-oriented runtime primitives for Vox: actors, mailboxes, supervision, and scheduling.

Submodules implement the durable / distributed process story; this crate root mostly re-exports stable names for embedders. Detailed behavior is documented on the defining types inside each module; blanket Rustdoc on every pub use alias would add noise without semantic value.

FeatureDefault / Enables
databasedep:vox-db, vox-db/host-integration
default—
DependencyKind
vox-bounded-fsNormal
vox-configNormal
vox-dbNormal
vox-foundationNormal
vox-http-clientNormal
vox-llm-egressNormal
vox-openaiNormal
vox-openclaw-runtimeNormal
vox-orchestrator-typesNormal
vox-plugin-hostNormal
vox-secretsNormal
vox-shell-stdlib-typesNormal
vox-skillsNormal
vox-telemetryNormal
vox-cryptoDevelopment
ModuleDescription
semcov_wave28_testsAdversarial semantic-coverage tests (wave 28).
activityDurable activity execution: retries, timeouts, and backoff around async work.
authAuthentication helpers for generated Vox services: API key / bearer validation and retry-after parsing.
builtinsHost-callable builtins surfaced to generated code (hashing, small helpers).
credential_brokerZero-trust capability-scoped credential broker for agents and MCP tools (CLAVIS-05).
dbOptional Codex / Turso database handle when the database feature is enabled.
durable_schedulerDurable / cron scheduler primitives for @scheduled + @durable (GA-11).
gcGarbage collection arena and !Send pointers for actor memory isolation.
inference_envHugging Face router, Hub listings, and Mens/Ollama capability probes.
llmOpenAI-compatible chat/embed clients, registry entries, and usage metrics.
llm_resultTyped result wrapper for structured LLM activity returns (parse-safe).
mailboxActor mailboxes: envelopes, messages, requests, and process signals.
mensMens/Ollama HTTP client for generate, embed, classify, and RAG helpers.
model_resolutionSSOT chat routing: manual URL, Mens, HF dedicated/router, OpenRouter.
notifyMulti-channel notification dispatch (GA-14): Email / SMS / WebPush.
pidOpaque process identifiers for actors and messaging.
presenceCursor-presence channel for real-time multiplayer (GA-25).
processActor ProcessContext, ProcessHandle, and spawn_process.
prompt_canonicalPrompt normalization, conflict detection, and safety pass for LLM ingress.
registryGlobal map of live actors by [Pid] and optional name.
resilient_httpRetry policy and HTTP client with fallback endpoints.
retrievalRAG-style chunk retrieval, context budgets, and provenance records.
route_capability_policyVOX_ROUTE_* capability policy snapshot (shared with orchestrator explain/MCP paths).
routing_telemetryShared routing decision telemetry for DB joins (bounded reason_json).
schedulerCooperative Tokio-backed scheduler registering spawned actors.
state_machineReactive state-machine instance helper consumed by emitted state-machine hooks (Phase G of the Svelte-mineable features plan).
subscriptionPer-table reactive mutation notifications (broadcast channels for reactive queries).
supervisorSupervision strategies and child restart loops for actor trees.
Dependency Topology, diagram 125 nodes, 24 edges: vox-actor-runtime → vox-bounded-fs; vox-actor-runtime → vox-config; vox-actor-runtime → vox-crypto; vox-actor-runtime → vox-db; vox-actor-runtime → vox-foundation; vox-actor-runtime → vox-http-client; vox-actor-runtime → vox-llm-egress; vox-actor-runtime → vox-openai; vox-actor-…vox-actor-runtimevox-bounded-fsvox-configvox-cryptovox-dbvox-foundationvox-http-clientvox-llm-egressvox-openaivox-openclaw-runtimevox-orchestrator-typesvox-plugin-hostvox-secretsvox-clivox-cli-researchvox-effort-auditvox-effort-routevox-gamifyvox-guivox-integration-testsvox-ml-clivox-orchestratorvox-orchestrator-mcpvox-research-shimvox-scientia
Diagram source
graph {
direction: right
node vox_actor_runtime: "vox-actor-runtime"
node vox_bounded_fs: "vox-bounded-fs"
vox_actor_runtime -> vox_bounded_fs
node vox_config: "vox-config"
vox_actor_runtime -> vox_config
node vox_crypto: "vox-crypto"
vox_actor_runtime -> vox_crypto
node vox_db: "vox-db"
vox_actor_runtime -> vox_db
node vox_foundation: "vox-foundation"
vox_actor_runtime -> vox_foundation
node vox_http_client: "vox-http-client"
vox_actor_runtime -> vox_http_client
node vox_llm_egress: "vox-llm-egress"
vox_actor_runtime -> vox_llm_egress
node vox_openai: "vox-openai"
vox_actor_runtime -> vox_openai
node vox_openclaw_runtime: "vox-openclaw-runtime"
vox_actor_runtime -> vox_openclaw_runtime
node vox_orchestrator_types: "vox-orchestrator-types"
vox_actor_runtime -> vox_orchestrator_types
node vox_plugin_host: "vox-plugin-host"
vox_actor_runtime -> vox_plugin_host
node vox_secrets: "vox-secrets"
vox_actor_runtime -> vox_secrets
node vox_cli: "vox-cli"
vox_cli -> vox_actor_runtime
node vox_cli_research: "vox-cli-research"
vox_cli_research -> vox_actor_runtime
node vox_effort_audit: "vox-effort-audit"
vox_effort_audit -> vox_actor_runtime
node vox_effort_route: "vox-effort-route"
vox_effort_route -> vox_actor_runtime
node vox_gamify: "vox-gamify"
vox_gamify -> vox_actor_runtime
node vox_gui: "vox-gui"
vox_gui -> vox_actor_runtime
node vox_integration_tests: "vox-integration-tests"
vox_integration_tests -> vox_actor_runtime
node vox_ml_cli: "vox-ml-cli"
vox_ml_cli -> vox_actor_runtime
node vox_orchestrator: "vox-orchestrator"
vox_orchestrator -> vox_actor_runtime
node vox_orchestrator_mcp: "vox-orchestrator-mcp"
vox_orchestrator_mcp -> vox_actor_runtime
node vox_research_shim: "vox-research-shim"
vox_research_shim -> vox_actor_runtime
node vox_scientia: "vox-scientia"
vox_scientia -> vox_actor_runtime
}
Consumer CrateRole
vox-cliDirect workspace dependent
vox-cli-researchDirect workspace dependent
vox-effort-auditDirect workspace dependent
vox-effort-routeDirect workspace dependent
vox-gamifyDirect workspace dependent
vox-guiDirect workspace dependent
vox-integration-testsDirect workspace dependent
vox-ml-cliDirect workspace dependent
vox-orchestratorDirect workspace dependent
vox-orchestrator-mcpDirect workspace dependent
vox-research-shimDirect workspace dependent
vox-scientiaDirect workspace dependent
vox-searchDirect workspace dependent
vox-tensorDirect workspace dependent
KindSymbolSignatureSourceDescription
structactivity::ActivityOptionspub struct ActivityOptionscrates/vox-actor-runtime/src/activity.rs#L42-L55Options that control activity execution behavior. These map directly to the with { ... } syntax in Vox source.
fnactivity::newpub fn new() -> Selfcrates/vox-actor-runtime/src/activity.rs#L72-L74Returns default options (no retries, no per-attempt timeout).
fnactivity::with_retriespub fn with_retries(mut self, retries: u32) -> Selfcrates/vox-actor-runtime/src/activity.rs#L77-L80Sets how many retries to perform after the first failed attempt.
fnactivity::with_timeoutpub fn with_timeout(mut self, timeout: Duration) -> Selfcrates/vox-actor-runtime/src/activity.rs#L83-L86Sets a wall-clock timeout for each attempt.
fnactivity::with_timeout_secspub fn with_timeout_secs(mut self, secs: u64) -> Selfcrates/vox-actor-runtime/src/activity.rs#L89-L92Sets the per-attempt timeout from a whole number of seconds.
fnactivity::with_initial_backoffpub fn with_initial_backoff(mut self, backoff: Duration) -> Selfcrates/vox-actor-runtime/src/activity.rs#L95-L98Sets the delay before the first retry after a failure.
fnactivity::with_max_backoffpub fn with_max_backoff(mut self, max: Duration) -> Selfcrates/vox-actor-runtime/src/activity.rs#L101-L104Sets the upper bound for exponential backoff growth.
fnactivity::with_backoff_multiplierpub fn with_backoff_multiplier(mut self, multiplier: f64) -> Selfcrates/vox-actor-runtime/src/activity.rs#L107-L110Sets the multiplicative factor applied between backoff steps.
fnactivity::with_activity_idpub fn with_activity_id(mut self, id: String) -> Selfcrates/vox-actor-runtime/src/activity.rs#L113-L116Sets a stable idempotency key for this activity run.
fnactivity::parse_durationpub fn parse_duration(s: &str) -> Option<Duration>crates/vox-actor-runtime/src/activity.rs#L119-L137Parse a duration string like ”10s”, “500ms”, “2m”.
enumactivity::ActivityResultpub enum ActivityResult<T>crates/vox-actor-runtime/src/activity.rs#L142-L149Result of an activity execution.
enumactivity::ActivityErrorpub enum ActivityErrorcrates/vox-actor-runtime/src/activity.rs#L153-L170Error from activity execution.
structactivity::ActivityExecutionpub struct ActivityExecutioncrates/vox-actor-runtime/src/activity.rs#L174-L185Tracks the state of an activity execution for observability.
enumactivity::ActivityStatuspub enum ActivityStatuscrates/vox-actor-runtime/src/activity.rs#L189-L200Coarse lifecycle state of an activity for metrics and tracing.
fnactivity::execute_activitypub async fn execute_activity<F, Fut, T, E>(crates/vox-actor-runtime/src/activity.rs#L206Execute an async activity function with the given options. This is the core runtime function that compiled with { ... } expressions call into. It handles retries, timeouts, and exponential backoff.
fnactivity::execute_activity_resultpub async fn execute_activity_result<F, Fut, T, E>(crates/vox-actor-runtime/src/activity.rs#L321Execute an activity and return a standard Result envelope for generated code paths. This keeps failure/cancellation on the value channel instead of forcing panic-based handling.
structauth::ServiceAuthConfigpub struct ServiceAuthConfigcrates/vox-actor-runtime/src/auth.rs#L5-L9Authentication configuration used by generated Vox services.
fnauth::from_envpub fn from_env() -> Selfcrates/vox-actor-runtime/src/auth.rs#L17-L35Build auth config from environment variables. - VOX_API_KEY - VOX_BEARER_TOKEN - VOX_ALLOW_UNAUTHENTICATED (true/false, defaults to true when no key/token set)
fnauth::authorize_requestpub fn authorize_request(crates/vox-actor-runtime/src/auth.rs#L39Validate an incoming API key and/or bearer token.
fnauth::parse_bearer_tokenpub fn parse_bearer_token(header: Option<&str>) -> Option<&str>crates/vox-actor-runtime/src/auth.rs#L63-L66Parse Authorization: Bearer <token>.
fnauth::parse_retry_after_secondspub fn parse_retry_after_seconds(value: Option<&str>) -> Option<Duration>crates/vox-actor-runtime/src/auth.rs#L81-L85Parse an optional header duration used by throttling.
fnbuiltins::vox_flush_exit_commandspub fn vox_flush_exit_commands()crates/vox-actor-runtime/src/builtins/mod.rs#L71-L74—
fnbuiltins::vox_hash_fastpub fn vox_hash_fast(input: &str) -> Stringcrates/vox-actor-runtime/src/builtins/mod.rs#L95-L99Fast non-cryptographic hash (XXH3-128, 128-bit output) for object identity, dedup keys, and ephemeral cache keying. Use for: HashMap keys, cache keys, dedup within a process, activity IDs in hot workflow paths where you control the input (no adversarial keys). Output: 32-char lowercase hex string (128-bit → 2 × u64 in hex). Deterministic for the same input within a process; also cross-machine deterministic (XXH3-128 is unkeyed / uses a fixed internal secret). For provenance, signatures, or any security-sensitive hashing, use vox_hash_secure (BLAKE3-based) instead. Algorithmically identical to vox_crypto::hash_fast_hex (used by the interp’s crypto.hash_fast and native codegen’s crypto.hash_fast emit — see builtin_registry.rs), but implemented independently here because this crate cannot take a normal dependency on vox-crypto (would require a crate-edges ledger entry). Equivalence is enforced by a same-file dev test: hash_fast_matches_vox_crypto_hash_fast_hex in builtins/tests.rs.
fnbuiltins::vox_hash_securepub fn vox_hash_secure(input: &str) -> Stringcrates/vox-actor-runtime/src/builtins/mod.rs#L110-L113Cryptographic hash using BLAKE3 (256-bit output). Use for: input_hash provenance stored in DB, content-addressable IDs shared across machines / process lifetimes, data integrity verification. Output: 64-char lowercase hex string (256-bit). Fully deterministic, cross-machine stable, collision probability ≈ 2^-128. ✅ Cryptographically secure. Safe to store permanently.
fnbuiltins::vox_uuidpub fn vox_uuid() -> Stringcrates/vox-actor-runtime/src/builtins/mod.rs#L122-L130Generate a unique identifier. Combines nanosecond-precision UNIX timestamp with a monotonic atomic counter to guarantee uniqueness even within the same nanosecond (parallel workflow steps). Format: vox-{nanos_hex}-{counter_hex} Example: vox-17a8c3f2d8b00000-0000000000000001
fnbuiltins::vox_now_mspub fn vox_now_ms() -> u64crates/vox-actor-runtime/src/builtins/mod.rs#L133-L138Current UNIX time in milliseconds.
fnbuiltins::vox_process_cwdpub fn vox_process_cwd() -> Stringcrates/vox-actor-runtime/src/builtins/mod.rs#L146-L150Native-codegen backing for bare process.cwd() (Task 2, interpreter-first execution PR 2). Mirrors the interpreter’s Some("process") => "cwd" arm in crates/vox-compiler/src/eval/builtins.rs — both swallow the error case to an empty string rather than surfacing a Result, since cwd failing (deleted CWD, permissions) is rare enough that stdlib treats it as best-effort, matching fs.cwd’s native emit in builtin_registry.rs.
fnbuiltins::vox_secrets_resolvepub fn vox_secrets_resolve(key: &str) -> Option<String>crates/vox-actor-runtime/src/builtins/mod.rs#L157-L161Native-codegen backing for bare secrets.resolve(key) (Task 2). key is looked up by canonical env name / alias / Debug spelling via SecretId::from_str (see vox-secrets/src/spec/ids.rs); an unknown key or a key with no resolved value both yield None — same shape as the interpreter’s Some("secrets") => "resolve" arm.
fnbuiltins::vox_log_debugpub fn vox_log_debug(message: &str)crates/vox-actor-runtime/src/builtins/mod.rs#L163-L165—
fnbuiltins::vox_log_infopub fn vox_log_info(message: &str)crates/vox-actor-runtime/src/builtins/mod.rs#L167-L169—
fnbuiltins::vox_log_warnpub fn vox_log_warn(message: &str)crates/vox-actor-runtime/src/builtins/mod.rs#L171-L173—
fnbuiltins::vox_log_errorpub fn vox_log_error(message: &str)crates/vox-actor-runtime/src/builtins/mod.rs#L175-L177—
structbuiltins::VoxRegexpub struct VoxRegex(pub regex::Regex)crates/vox-actor-runtime/src/builtins/mod.rs#L183Compiled regex value handed back to Vox as Result[Regex].
structbuiltins::VoxMatchpub struct VoxMatchcrates/vox-actor-runtime/src/builtins/mod.rs#L187-L189One match in a haystack — exposes captures via group(idx).
fnbuiltins::matchespub fn matches(&self, text: impl AsRef<str>) -> boolcrates/vox-actor-runtime/src/builtins/mod.rs#L193-L195—
fnbuiltins::findpub fn find(&self, text: impl AsRef<str>) -> Option<VoxMatch>crates/vox-actor-runtime/src/builtins/mod.rs#L196-L198—
fnbuiltins::find_allpub fn find_all(&self, text: impl AsRef<str>) -> Vec<VoxMatch>crates/vox-actor-runtime/src/builtins/mod.rs#L199-L204—
fnbuiltins::grouppub fn group(&self, idx: i64) -> Option<String>crates/vox-actor-runtime/src/builtins/mod.rs#L208-L213—
fnbuiltins::vox_regex_compilepub fn vox_regex_compile(pattern: &str) -> Result<VoxRegex, String>crates/vox-actor-runtime/src/builtins/mod.rs#L224-L228Compile a Vox regex pattern. Returns Err(message) on invalid pattern.
structbuiltins::VoxJsonpub struct VoxJson(pub serde_json::Value)crates/vox-actor-runtime/src/builtins/mod.rs#L234Opaque JSON value handed back to Vox as Result[Json]. Wraps serde_json::Value.
fnbuiltins::getpub fn get(&self, key: String) -> Option<VoxJson>crates/vox-actor-runtime/src/builtins/mod.rs#L255-L260Object key access. None if receiver is not an object or key is absent.
fnbuiltins::atpub fn at(&self, idx: i64) -> Option<VoxJson>crates/vox-actor-runtime/src/builtins/mod.rs#L264-L272Array index access. None if receiver is not an array or index is OOB. Negative indices are not supported and yield None.
fnbuiltins::pointerpub fn pointer(&self, path: String) -> Option<VoxJson>crates/vox-actor-runtime/src/builtins/mod.rs#L276-L278RFC 6901 JSON Pointer navigation. None if the path does not resolve. data.pointer("/products/0/name") is the canonical deep-access tool.
fnbuiltins::as_strpub fn as_str(&self) -> Option<String>crates/vox-actor-runtime/src/builtins/mod.rs#L283-L285—
fnbuiltins::as_intpub fn as_int(&self) -> Option<i64>crates/vox-actor-runtime/src/builtins/mod.rs#L286-L288—