Struct Runtime 

pub struct Runtime {
    pub state: Arc<StateStore>,
    pub tools: Arc<RwLock<HashMap<String, ToolSchema>>>,
    pub policies: Arc<RwLock<PolicyEngine>>,
    pub log: Arc<Mutex<EventLog>>,
    pub rate_limiter: Arc<RateLimiter>,
    pub result_cache: Arc<ResultCache>,
    /* private fields */
}

Common Agent Runtime — deterministic execution layer.

Lock ordering discipline (never hold multiple simultaneously, never hold sync locks across .await):

1. capabilities (RwLock, read-only during execution)
2. tools (RwLock, read-only during execution)
3. policies (RwLock, read-only during execution)
4. cost_budget (RwLock, read-only during execution)
5. log (TokioMutex, acquired/released per event)
6. tool_executor (TokioMutex, clone Arc and drop before await)
7. idempotency_cache (TokioMutex, acquired/released per check)

StateStore uses parking_lot::Mutex (sync) — NEVER hold across .await points.

Fields

state: Arc<StateStore>

tools: Arc<RwLock<HashMap<String, ToolSchema>>>

policies: Arc<RwLock<PolicyEngine>>

log: Arc<Mutex<EventLog>>

rate_limiter: Arc<RateLimiter>

result_cache: Arc<ResultCache>

Implementations

impl Runtime

pub fn new() -> Self

pub fn with_shared( state: Arc<StateStore>, log: Arc<TokioMutex<EventLog>>, policies: Arc<TokioRwLock<PolicyEngine>>, ) -> Self

Create a runtime with shared state, event log, and policies. Each runtime gets its own tool set, executor, and idempotency cache.

pub fn with_inference(self, engine: Arc<InferenceEngine>) -> Self

Attach a local inference engine. Registers infer, embed, classify as built-in tools with real implementations.

pub fn with_learning( self, memgine: Arc<TokioMutex<MemgineEngine>>, auto_distill: bool, ) -> Self

Attach a memgine for automatic skill learning after execution. Enables auto-distillation of execution traces into skills.

pub fn with_executor(self, executor: Arc<dyn ToolExecutor>) -> Self

pub async fn set_executor(&self, executor: Arc<dyn ToolExecutor>)

Set a tool executor for the next execute() call. Used by NAPI bindings where executor varies per call.

pub fn with_event_log(self, log: EventLog) -> Self

pub async fn register_tool(&self, name: &str)

Register a tool with just a name (backward compatible).

pub async fn register_tool_schema(&self, schema: ToolSchema)

Register a tool with full schema.

pub async fn tool_schemas(&self) -> Vec<ToolSchema>

Get all registered tool schemas (for model prompt generation).

pub async fn set_cost_budget(&self, budget: CostBudget)

Set a cost budget that limits proposal execution.

pub async fn set_capabilities(&self, caps: CapabilitySet)

Set per-agent capability permissions that restrict tools, state keys, and action count.

pub async fn set_rate_limit( &self, tool: &str, max_calls: u32, interval_secs: f64, )

Set a per-tool rate limit (token bucket).

max_calls tokens are available per interval_secs window. When the bucket is empty, dispatch() applies backpressure by waiting until a token refills.

pub async fn enable_tool_cache(&self, tool: &str, ttl_secs: u64)

Enable cross-proposal result caching for a tool with a TTL in seconds.

pub async fn execute(&self, proposal: &ActionProposal) -> ProposalResult

Execute a full proposal through the runtime loop.

pub async fn save_checkpoint(&self) -> Checkpoint

Save a checkpoint of the current runtime state.

pub async fn save_checkpoint_to_file(&self, path: &str) -> Result<(), String>

Save checkpoint to a JSON file.

pub async fn load_checkpoint_from_file( &self, path: &str, ) -> Result<Checkpoint, String>

Load a checkpoint from a JSON file and restore state.

pub async fn restore_checkpoint(&self, checkpoint: &Checkpoint)

Restore runtime state from a checkpoint.

Trait Implementations

impl Default for Runtime

fn default() -> Self

Returns the “default value” for a type.