sua-runtime

sua-runtime is the transport-neutral execution kernel for the Software Use ecosystem. It registers providers, selects one deterministically, enforces policy and JSON Schema contracts, and exposes an asynchronous job lifecycle.

It is deliberately not an MCP server, HTTP service, CLI, DCC adapter, or UI driver. Those responsibilities live at the edges of the ecosystem.

Runtime guarantees

• Provider discovery is deterministic.
• Selection prefers Typed, then SemanticUi, then VisualUi.
• Task constraints can require a provider and/or an interaction mode.
• The default policy permits capabilities declared ReadOnly and denies those declared Mutating.
• Custom policy errors and panics fail closed as PolicyDenied before provider invocation.
• Inputs are validated before a provider is called; outputs are validated before success is reported.
• Events have strictly increasing sequence numbers and can be replayed.
• Once execution starts, the selected provider is pinned. A failure never causes an implicit fallback to another provider.
• PID/HWND binding and equivalent target-integrity checks remain provider-owned.
• One runtime retains at most 10,000 invocations by default and fails closed with ResourceExhausted; callers can configure a different non-zero bound.

Trust and execution boundary

Registered providers are trusted in-process native code. The host must admit providers from authenticated, integrity-verified packages; passing sua-registry validation is structural evidence, not endorsement. The built-in policy enforces the canonical safety declaration for a capability contract. It cannot sandbox a malicious provider that lies about its behavior or executes outside the selected invocation.

Every CapabilityId@Version has one canonical CapabilitySpec within a runtime. Conflicting schemas, safety, or metadata from another provider are rejected. Schemas use the SDK's explicit Draft 2020-12 dialect. Provider-originated error messages and instance values are not copied into agent-facing diagnostics.

start requires an active Tokio runtime. Dropping the last Runtime handle sends a best-effort cancellation signal to active providers, including when the retained-job lock was poisoned; providers remain responsible for cooperative shutdown.

Example

use std::sync::Arc;

use sua_runtime::{CapabilityProvider, InvocationId, Runtime};

# async fn example(provider: Arc<dyn CapabilityProvider>) -> Result<(), Box<dyn std::error::Error>> {
let runtime = Runtime::new();
runtime.register(provider)?;
let invocation_id: InvocationId = "example-1".parse()?;

// A transport adapter constructs `InvocationRequest` and calls `start`.
// It can then call `get`, `events`, or `cancel` with `invocation_id`.
# let _ = (runtime, invocation_id);
# Ok(())
# }

The exact SDK contract is defined by sua-sdk. See System architecture for ownership and data flow.

Development

The minimum supported Rust version is 1.85.

vx cargo fmt --all -- --check
vx cargo check --locked --all-targets
vx cargo test --locked --all-targets
vx cargo clippy --locked --all-targets -- -D warnings

License

MIT