Struct Engine 

pub struct Engine { /* private fields */ }

Cloneable in-process engine handle. It contains no transport concerns and is safe for tool providers to call while their parent call is executing.

Implementations

impl Engine

pub fn list_mcp_servers(&self) -> Vec<McpServerInfo>

pub async fn add_mcp_server( &self, name: String, definition: McpServerDefinition, ) -> Result<Option<McpServerInfo>, EngineError>

pub async fn edit_mcp_server( &self, name: String, definition: McpServerDefinition, ) -> Result<Option<McpServerInfo>, EngineError>

pub async fn remove_mcp_server( &self, name: String, ) -> Result<Option<McpServerInfo>, EngineError>

pub async fn set_mcp_server_enabled( &self, name: String, enabled: bool, ) -> Result<Option<McpServerInfo>, EngineError>

pub async fn reconnect_mcp_server( &self, name: String, ) -> Result<Option<McpServerInfo>, EngineError>

pub async fn begin_mcp_auth(&self, name: String) -> Result<String, EngineError>

pub async fn cancel_mcp_auth(&self, name: String) -> Result<(), EngineError>

pub async fn persist_mcp_server( &self, name: String, target: McpConfigTarget, ) -> Result<Option<McpServerInfo>, EngineError>

impl Engine

pub fn get_session_permissions( &self, session_id: SessionId, ) -> Result<SessionPermissionGetResult, EngineError>

pub async fn set_session_permission( &self, session_id: SessionId, action: PermissionAction, resource: WildcardPattern, effect: PermissionEffect, origin: EventOrigin, ) -> Result<SessionPermissionMutationResult, EngineError>

pub async fn clear_session_permission( &self, session_id: SessionId, action: PermissionAction, resource: &WildcardPattern, origin: EventOrigin, ) -> Result<SessionPermissionMutationResult, EngineError>

impl Engine

pub async fn approval_respond( &self, params: ApprovalRespondParams, origin: EventOrigin, ) -> Result<ApprovalRespondResult, EngineError>

pub fn list_approvals( &self, root_session_id: SessionId, status: Option<ApprovalStatus>, ) -> ApprovalListResult

impl Engine

pub fn read_artifact( &self, path: &str, offset: u64, limit: u64, ) -> Result<ArtifactReadPage, ToolError>

Read a public artifact URI by possession, without a session ownership lookup. This synchronous API blocks; async tool executors use ToolExecutionContext::read_artifact.

impl Engine

pub async fn compact_session( &self, session: SessionId, focus: Option<&str>, origin: EventOrigin, ) -> Result<bool, EngineError>

pub async fn compact_session_result( &self, session: SessionId, focus: Option<&str>, origin: EventOrigin, ) -> Result<SessionCompactResult, EngineError>

impl Engine

pub async fn delegate_invoke( &self, invocation: DelegateInvocation, ) -> Result<DelegateHandle, EngineError>

Admits a delegate invocation, creates/attaches its child, and starts the invocation-derived child run exactly once.

pub fn await_delegate(&self, handle: DelegateHandle) -> DelegateAwait

Waits for a child terminal state and returns the bounded model-visible delegate result. Cancellation retains the child session identity.

pub async fn cancel_delegate( &self, handle: DelegateHandle, ) -> Result<ToolResult, EngineError>

Cancels the child run and returns the structured delegate cancellation result used by the parent tool invocation.

pub fn subagent_agent_type( &self, caller_session_id: SessionId, child_session_id: SessionId, ) -> Result<AgentId, EngineError>

pub async fn get_subagent_result( &self, caller_session_id: SessionId, reference: impl Display, wait: bool, offset: u32, limit: u32, cancellation: CancellationToken, ) -> Result<ToolResult, EngineError>

Reports session liveness, not delegation lifecycle. A running (including queued/starting, or finished-then-woken) subagent reports “running”; once it ends, the result is the last assistant message of its most recent turn, paginated by offset/limit.

pub async fn steer_subagent( &self, caller_session_id: SessionId, child_session_id: SessionId, message: String, ) -> Result<ToolResult, EngineError>

pub async fn cancel_subagent( &self, caller_session_id: SessionId, reference: impl Display, reason: Option<String>, ) -> Result<ToolResult, EngineError>

impl Engine

pub async fn get_history( &self, session: SessionId, view: EngineHistoryView, ) -> Result<Vec<HistoryTurn>, EngineError>

Returns a live history projection for the given session.

Callable by anything holding an engine reference. The result reflects state at query time and may include events appended after the current model request started, such as earlier tool results from the same in-flight turn. Tool providers needing history should retain an Engine handle, following the delegate-provider pattern; the engine is deliberately not injected into every tool context.

impl Engine

pub fn resolve_subagent_target( &self, caller: SessionId, reference: impl Display, scope: SubagentScope, ) -> Result<SessionId, EngineError>

Resolves a full UUID or a complete handle within caller’s addressable set (its direct children, or every tree peer).

There is deliberately no prefix matching: a partial handle is an error. An unresolvable reference never falls through to creating a subagent.

impl Engine

pub async fn subscribe( &self, session: SessionId, cursor: Option<u64>, ) -> Result<(EventsSubscribeResult, Receiver<EventSubscriptionMessage>), EngineError>

pub fn snapshot_events( &self, session: SessionId, cursor: Option<u64>, ) -> Result<EventsSubscribeResult, EngineError>

pub fn subscribe_tool_output( &self, call: ToolCallId, stream: OutputStream, ) -> Option<(OutputSnapshot, Receiver<OutputMessage>)>

Subscribes to a currently running call’s retained output and live tail. Output is ephemeral and intentionally separate from event cursors.

pub fn tool_output_streams( &self, call_id: ToolCallId, ) -> Option<Vec<OutputStream>>

pub async fn append( &self, session: SessionId, run: Option<RunId>, origin: EventOrigin, event: Event, ) -> Result<(), EngineError>

pub fn append_blocking( &self, session: SessionId, run: Option<RunId>, origin: EventOrigin, event: Event, ) -> Result<(), EngineError>

Synchronous setup/CLI wrapper. Do not call from a Tokio runtime.

pub async fn submit_tool_result( &self, session: SessionId, run: RunId, tool_call_id: ToolCallId, result: Result<ToolResult, String>, ) -> Result<(), EngineError>

Commits a completed tool invocation through its session actor.

impl Engine

pub fn message_relationship( &self, sender: SessionId, recipient: SessionId, ) -> Result<&'static str, EngineError>

Relationship label used as the message permission resource for a sender→recipient pair: parent, child, sibling, or *.

Errors

Returns EngineError::Messaging with send_message:unknown_session when either session does not exist.

pub async fn send_agent_message( &self, invocation: AgentMessageInvocation, ) -> Result<AgentMessageHandle, EngineError>

Durably accepts one agent message into the recipient’s producer inbox.

The sender’s ProducerOwner::Agent registration on the recipient is found-or-registered per send; registrations are runtime-only by contract, so re-registration after a process restart is expected and cheap. The idempotency key derives from (sender session, run, tool call): a retried call returns the original message_id and delivers once. The inbox-cap check, the pair-window check, the hop guard, and the acceptance run atomically inside the recipient’s actor (ProducerCommand::SendAgentMessage).

Chain depth is computed here, from the sender’s log, because the hop basis is the sender run’s own durable observation of agent mail — a different actor’s state that the recipient must not reach into. Depth is monotonic within a run, so two concurrent sends from one run resolve to the same value, which is the correct answer for both.

Errors

Returns EngineError::Messaging stable codes for disabled messaging, invalid bodies, unknown recipients, non-tree-peer recipients, self sends, full inboxes, exhausted pair windows, chains past max_hops, and shutdown races; EngineError::Producer for idempotency payload conflicts.

impl Engine

pub async fn get_session_goal( &self, params: SessionGoalGetParams, ) -> Result<SessionGoalGetResult, EngineError>

pub async fn set_session_goal( &self, params: SessionGoalSetParams, origin: EventOrigin, ) -> Result<SessionGoalSetResult, EngineError>

pub async fn change_session_goal_lifecycle( &self, params: SessionGoalLifecycleParams, origin: EventOrigin, ) -> Result<SessionGoalLifecycleResult, EngineError>

pub async fn session_producers( &self, params: SessionProducersParams, ) -> Result<SessionProducersResult, EngineError>

pub async fn goal_get( &self, session: SessionId, ) -> Result<GoalGetResult, EngineError>

pub async fn goal_update( &self, session: SessionId, params: GoalUpdateParams, ) -> Result<GoalUpdateResult, EngineError>

impl Engine

pub async fn start_run( &self, params: RunStartParams, origin: EventOrigin, ) -> Result<RunStartResult, EngineError>

pub fn start_run_blocking( &self, params: RunStartParams, origin: EventOrigin, ) -> Result<RunStartResult, EngineError>

Synchronous setup/CLI wrapper. Do not call from a Tokio runtime.

pub async fn steer( &self, run_id: RunId, input: String, origin: EventOrigin, ) -> Result<RunSteerResult, EngineError>

pub fn steer_blocking( &self, run_id: RunId, input: String, origin: EventOrigin, ) -> Result<RunSteerResult, EngineError>

Synchronous setup/CLI wrapper. Do not call from a Tokio runtime.

pub async fn recall_steer( &self, run_id: RunId, ) -> Result<RunRecallSteerResult, EngineError>

pub async fn cancel_run( &self, run_id: RunId, ) -> Result<RunCancelResult, EngineError>

pub async fn tool_stdin( &self, params: RunToolStdinParams, ) -> Result<RunToolStdinResult, EngineError>

impl Engine

pub fn session_model_selection( &self, session: SessionId, ) -> Result<RunSelection, EngineError>

The accepted selection, advanced only by a committed fallback model turn.

pub fn create_session( &self, selection: RunSelection, ) -> Result<SessionMeta, EngineError>

pub fn list_sessions(&self) -> Vec<SessionMeta>

Top-level session listing: delegation roots only. Delegated children are selected through their root’s tree and stay reachable via Engine::get_session, Engine::children, Engine::tree and resume.

pub fn get_session(&self, id: SessionId) -> Result<SessionMeta, EngineError>

pub fn session_usage( &self, id: SessionId, ) -> Result<SessionUsageResult, EngineError>

pub fn agent_usage(&self, agent_id: AgentId) -> AgentUsageResult

pub fn global_usage(&self) -> GlobalUsageResult

pub fn session_tree_usage( &self, id: SessionId, ) -> Result<SessionTreeUsageResult, EngineError>

pub fn delegate_targets( &self, id: SessionId, ) -> Result<Vec<AgentId>, EngineError>

pub fn children(&self, id: SessionId) -> Result<Vec<ChildSummary>, EngineError>

pub fn tree(&self, id: SessionId) -> Result<SessionTree, EngineError>

pub async fn resume(&self, id: SessionId) -> Result<SessionMeta, EngineError>

Adopts id and resolves the work its adoption found interrupted.

Adoption schedules delegation recovery instead of running it inline, so the wait below is what makes the ordering observable: when this returns, every delegation record under the session’s root that the adoption classified as running without a live run here has been resolved, and the root’s background-delegation capacity reads settled rather than transiently over-counted.

The wait happens here, after the actor has replied, and never inside the Resume handler: resolving a recovered delegate goes through its parent session’s mailbox, which is the very mailbox that handler occupies.

pub async fn revert_session( &self, session_id: SessionId, through_seq: u64, origin: EventOrigin, ) -> Result<SessionRevertResult, EngineError>

pub async fn fork_session( &self, session_id: SessionId, through_seq: u64, origin: EventOrigin, ) -> Result<SessionForkResult, EngineError>

pub fn set_permission_mode( &self, session_id: SessionId, mode: PermissionMode, ) -> Result<(), EngineError>

pub async fn rename_session( &self, params: SessionRenameParams, origin: EventOrigin, ) -> Result<SessionRenameResult, EngineError>

impl Engine

pub fn is_reserved_staged_skill_prompt(prompt: &str) -> bool

pub fn skill_tool_available( &self, session: SessionId, ) -> Result<bool, EngineError>

pub fn list_skills( &self, session: SessionId, ) -> Result<SkillsListResult, EngineError>

pub fn get_skill( &self, session: SessionId, name: &str, args: &str, ) -> Result<SkillsGetResult, EngineError>

pub fn get_user_skill( &self, session: SessionId, name: &str, args: &str, ) -> Result<SkillsGetResult, EngineError>

pub fn get_model_skill( &self, session: SessionId, name: &str, args: &str, ) -> Result<SkillsGetResult, EngineError>

pub async fn invoke_skill( &self, session: SessionId, run: Option<RunId>, name: &str, args: &str, permission_preapproved: bool, ) -> Result<SkillInvocation, EngineError>

pub fn skill_invocation_context( &self, name: &str, ) -> Result<Option<SkillContext>, EngineError>

pub fn is_direct_skill_call(&self, call_id: ToolCallId) -> bool

pub async fn execute_skill_fork( &self, session: SessionId, run: RunId, call_id: ToolCallId, name: &str, args: &str, ) -> Result<PersistedToolResult, EngineError>

pub fn take_skill_model_override(&self, session: SessionId) -> Option<ModelKey>

impl Engine

pub fn open(options: EngineOptions) -> Result<Self, EngineError>

pub fn current_runtime(&self) -> Arc<PublishedRuntime>

pub fn runtime_snapshot(&self) -> Result<RuntimeSnapshotResult, EngineError>

pub fn subscribe_runtime_changes(&self) -> Receiver<RuntimeChangedNotification>

pub fn subscribe_engine_events(&self) -> Receiver<EngineEvent>

pub fn connect_provider( &self, params: ProviderConnectParams, ) -> Result<ProviderConnectResult, EngineError>

pub fn disconnect_provider( &self, params: ProviderDisconnectParams, ) -> Result<ProviderDisconnectResult, EngineError>

pub fn reconcile_provider_store(&self) -> Result<bool, EngineError>

pub fn refresh_catalog( &self, catalog: Arc<CatalogSnapshot>, ) -> Result<RuntimeSnapshotResult, EngineError>

Atomically recompiles and publishes a newly acquired catalog snapshot.

pub fn register_tool_provider(&self, provider: Arc<dyn ToolProvider>)

Registers a tool provider after engine open, allowing providers that require an Engine (notably delegate) to break the construction cycle.

pub fn try_register_tool_provider( &self, provider: Arc<dyn ToolProvider>, ) -> Result<(), EngineError>

pub fn mcp_statuses(&self) -> Vec<McpServerStatus>

pub fn plugin_statuses(&self) -> Vec<PluginStatus>

pub async fn ping_plugin(&self, name: &str) -> Result<(), String>

pub async fn shutdown(&self)

Stops new session mailbox traffic and cancels active work. Existing client clones may keep a session mailbox alive.

Trait Implementations

impl Clone for Engine

fn clone(&self) -> Engine

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.