Struct AgentRuntime 

pub struct AgentRuntime<P: LlmProvider> { /* private fields */ }

The main agent runtime.

Implementations

impl<P: LlmProvider + 'static> AgentRuntime<P>

pub async fn run_turn_streaming<F: Frontend + 'static>( &self, session: &mut AgentSession, input: &str, frontend: Arc<F>, ) -> RuntimeResult<()>

Run a single turn with streaming output.

The frontend parameter is wrapped in Arc so it can be registered as an approval handler for the duration of the turn.

Errors

Returns an error if:

• The LLM provider fails to generate a response
• An MCP tool call fails
• An approval request fails
• Session persistence fails

pub async fn run_subagent_turn<F: Frontend + 'static>( &self, session: &mut AgentSession, prompt: &str, frontend: Arc<F>, parent_subagent_id: Option<SubAgentId>, ) -> RuntimeResult<()>

Run a single turn for a sub-agent session.

Like run_turn_streaming but without hooks, summarization, or session persistence. The session is ephemeral and owned by the caller (SubAgentExecutor).

parent_subagent_id is the pool handle ID of this sub-agent, passed so that nested sub-agents (if the sub-agent calls task tool) can declare their parent.

Errors

Returns an error if the LLM or tool execution fails.

impl<P: LlmProvider + 'static> AgentRuntime<P>

pub fn new( llm: P, mcp: McpClient, audit: AuditLog, sessions: SessionStore, crypto: KeyPair, config: RuntimeConfig, ) -> Self

Create a new runtime.

pub fn with_capsule_registry( self, registry: Arc<RwLock<CapsuleRegistry>>, ) -> Self

Set the capsule registry for capsule tool integration.

pub fn new_arc( llm: P, mcp: McpClient, audit: AuditLog, sessions: SessionStore, crypto: KeyPair, config: RuntimeConfig, hooks: Option<HookManager>, capsule_registry: Option<Arc<RwLock<CapsuleRegistry>>>, ) -> Arc<Self>

Create a new runtime wrapped in Arc with the self-reference pre-set.

Uses Arc::new_cyclic to avoid the two-step new() + set_self_arc() pattern. Accepts an optional HookManager since with_hooks() can’t be chained after Arc wrapping. Accepts an optional PluginRegistry for capsule tool integration.

pub fn create_session(&self, workspace_override: Option<&Path>) -> AgentSession

Create a new session.

Uses build_system_prompt() to dynamically assemble a workspace-aware prompt with tool guidelines and project instructions. If the user has explicitly set a custom system_prompt in config, that takes priority.

An optional workspace_override can be supplied to use a different workspace root than the one in the runtime config (e.g. the CLI client’s actual working directory).

pub fn save_session(&self, session: &AgentSession) -> RuntimeResult<()>

Save a session.

Errors

Returns an error if the session cannot be serialized or written to disk.

pub fn load_session( &self, id: &SessionId, ) -> RuntimeResult<Option<AgentSession>>

Load a session.

Errors

Returns an error if the session file cannot be read or deserialized.

pub fn list_sessions(&self) -> RuntimeResult<Vec<SessionSummary>>

List sessions.

Errors

Returns an error if the session directory cannot be read or session files cannot be parsed.

pub fn config(&self) -> &RuntimeConfig

Get runtime configuration.

pub fn audit(&self) -> &Arc<AuditLog>

Get the audit log.

pub fn mcp(&self) -> &McpClient

Get the MCP client.

pub fn key_id(&self) -> [u8; 8]

Get the runtime key ID.

pub fn boundary(&self) -> &WorkspaceBoundary

Get the workspace boundary.

pub fn cleanup_capsule_kv_stores(&self, session_id: &SessionId)

Remove plugin KV stores for a session that has ended.

Should be called when a session is finished to prevent unbounded growth of the capsule_kv_stores map in long-running processes.

pub fn with_security_policy(self, policy: SecurityPolicy) -> Self

Set a custom security policy.

pub fn with_hooks(self, hooks: HookManager) -> Self

Set a pre-configured hook manager.

pub fn hooks(&self) -> &Arc<HookManager>

Get the hook manager.

pub fn subagent_pool(&self) -> &Arc<SubAgentPool>

Get the sub-agent pool.

pub async fn set_self_arc(self: &Arc<Self>)

Store a weak self-reference for sub-agent spawner injection.

Important: Callers must wrap the runtime in Arc and call this method for sub-agent support to work. Without it, the task tool will return “not available in this context”.

let runtime = Arc::new(AgentRuntime::new(/* ... */));
runtime.set_self_arc(&runtime).await;