Struct RpcEngine 

pub struct RpcEngine { /* private fields */ }

The out-of-process RPC driver: wraps one already-constructed crate::Agent with the submit/interrupt/status/shutdown method set (§ module doc). Shared by both transports (run_stdio, run_http) so the method semantics — including the fail-closed permission behavior — can never drift between them.

Implementations

impl RpcEngine

pub fn new( agent: impl Into<SdkAgent>, on_turn_complete: Option<Box<dyn Fn(&SdkAgent) + Sync + Send>>, ) -> Arc<RpcEngine>

Wrap agent (already fully built by the caller — same Config, same permission/sandbox posture as a local session) for out-of- process driving. Installs its OWN event sink via Agent::set_event_sink, overwriting whatever sink agent may already have had wired (callers of this module drive an agent exclusively through the RPC surface, so there is never a second, competing consumer of its events).

pub fn new_named( agent: impl Into<SdkAgent>, session_id: impl Into<String>, on_turn_complete: Option<Box<dyn Fn(&SdkAgent) + Sync + Send>>, ) -> Arc<RpcEngine>

Construct the canonical SDK runtime with an explicit durable session identity. Every frontend must use this identity when referring to the same live agent; transport-local connection ids are not session ids.

pub fn new_named_with_frontend_metadata( agent: impl Into<SdkAgent>, session_id: impl Into<String>, frontend_metadata: FrontendRuntimeMetadata, on_turn_complete: Option<Box<dyn Fn(&SdkAgent) + Sync + Send>>, ) -> Arc<RpcEngine>

Construct the canonical runtime with explicit source-harness and emulation-profile identity for every attached frontend.

pub fn new_named_with_frontend_requests( agent: impl Into<SdkAgent>, session_id: impl Into<String>, frontend_metadata: FrontendRuntimeMetadata, on_turn_complete: Option<Box<dyn Fn(&SdkAgent) + Sync + Send>>, ) -> Arc<RpcEngine>

Construct a canonical runtime whose attached frontends may answer policy-authorized approval requests. Existing constructors retain the historical fail-closed headless behavior and report respond=false.

pub fn new_named_with_frontend_bridge( agent: impl Into<SdkAgent>, session_id: impl Into<String>, frontend_metadata: FrontendRuntimeMetadata, bridge: FrontendRequestBridge, on_turn_complete: Option<Box<dyn Fn(&SdkAgent) + Sync + Send>>, ) -> Arc<RpcEngine>

Bind a pre-created request bridge after its elicitation handler has been installed on MCP clients.

pub fn subscribe(&self) -> Receiver<Value>

Subscribe to this engine’s event-notification stream (already AgentEvent::to_json-projected) — each subscriber gets every event emitted from this point on, independent of any other subscriber.

pub fn frontend_descriptor(&self) -> FrontendRuntimeDescriptor

Describe the SDK-owned runtime without locking the active agent turn.

pub fn frontend_attach( &self, history_limit: usize, ) -> Result<FrontendAttachment, SdkError>

Attach to one atomic history/replay/live boundary. The live receiver is created before the projection snapshot is locked; events racing the snapshot therefore appear either in replay or in the receiver, and FrontendAttachment::next_event removes any overlap by sequence.

pub fn frontend_subscribe(&self) -> Receiver<SdkEvent>

Subscribe to sequenced frontend events. Transport adapters subscribe before taking Self::frontend_snapshot so boundary events cannot be missed.

pub fn frontend_snapshot( &self, history_limit: usize, ) -> Result<FrontendAttachSnapshot, SdkError>

Capture the serializable history/replay half of a frontend attachment.

pub fn session_id(&self) -> &str

Stable SDK session identity shared by every frontend.

pub async fn submit( &self, prompt: impl Into<String>, ) -> Result<String, RuntimeSubmitError>

Submit one prompt through the canonical runtime and wait for its reply.

pub async fn submit_with_images( &self, prompt: impl Into<String>, image_urls: Vec<String>, ) -> Result<String, RuntimeSubmitError>

Submit one prompt with runtime-owned multimodal image inputs.

pub fn send_input( self: &Arc<RpcEngine>, prompt: String, ) -> Result<(), RuntimeSubmitError>

Atomically claim one prompt, then run it on the SDK owner while the caller consumes the canonical event stream.

pub fn send_input_with_images( self: &Arc<RpcEngine>, prompt: String, image_urls: Vec<String>, ) -> Result<(), RuntimeSubmitError>

Atomically claim one multimodal prompt, then run it while callers consume the canonical event stream.

pub fn steer(&self, prompt: impl Into<String>) -> Result<(), SdkError>

Queue steering for the active agent loop without waiting for its long-held async lock. The agent consumes it at the next model-loop boundary according to the configured steering mode.

pub fn respond(&self, response: FrontendResponse) -> Result<(), SdkError>

Resolve one pending interactive request exactly once.

pub async fn invoke( &self, operation: FrontendOperationInvocation, ) -> Result<FrontendOperationResult, SdkError>

Invoke one operation after resolving its opaque identifier solely against the trusted catalog captured at runtime construction.

pub async fn interrupt(&self) -> bool

Cancel the current turn through the shared runtime handle.

pub fn status(&self) -> RuntimeStatus

Return a lock-free runtime snapshot, including while a turn is active.

pub async fn history(&self, limit: usize) -> Vec<ChatMessage>

Return the tail of the canonical conversation for newly attached frontends. This is SDK state, not a transport-local replay buffer, and remains answerable while a turn owns the agent lock.

pub async fn finalize_with<R>(&self, finalize: impl FnOnce(&SdkAgent) -> R) -> R

Run one caller-owned finalization projection while holding the agent at a quiescent boundary. This is the persistence/inspection seam for local frontends that transfer Agent ownership into the SDK runtime; it does not expose a second way to drive the model loop.

pub async fn shutdown(&self)

Request graceful runtime shutdown. All connected frontends observe the same transition and any in-flight turn is interrupted.

pub fn is_shutting_down(&self) -> bool

Whether shutdown has been requested — callers use this to stop accepting new work/connections.

pub async fn wait_for_shutdown(&self)

Resolves once shutdown has been requested. Cheap to call repeatedly/concurrently — every waiter is woken.

pub async fn handle_request(self: &Arc<RpcEngine>, req: RpcRequest) -> Value

Dispatch one already-parsed RpcRequest to the right method handler. Every recognized method is fully wired to real Agent behavior — there is no method that parses but no-ops.

Trait Implementations

impl SdkRuntime for RpcEngine

fn describe<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<FrontendRuntimeDescriptor, SdkError>> + Send + 'async_trait>>

where 'life0: 'async_trait, RpcEngine: 'async_trait,

Describe runtime identity, modules, commands, actions, and state.

fn attach<'life0, 'async_trait>( &'life0 self, history_limit: usize, ) -> Pin<Box<dyn Future<Output = Result<FrontendAttachment, SdkError>> + Send + 'async_trait>>

where 'life0: 'async_trait, RpcEngine: 'async_trait,

Atomically attach at the canonical history/live-event boundary.

fn send_input<'async_trait>( self: Arc<RpcEngine>, prompt: String, ) -> Pin<Box<dyn Future<Output = Result<(), SdkError>> + Send + 'async_trait>>

where RpcEngine: 'async_trait,

Atomically accept a new user turn and return once ownership is claimed.

fn send_input_with_images<'async_trait>( self: Arc<RpcEngine>, prompt: String, image_urls: Vec<String>, ) -> Pin<Box<dyn Future<Output = Result<(), SdkError>> + Send + 'async_trait>>

where RpcEngine: 'async_trait,

Atomically accept a multimodal user turn and return once ownership is claimed. Implementations must preserve images natively or reject the action; silently folding them into text is never allowed.

fn submit<'life0, 'async_trait>( &'life0 self, prompt: String, ) -> Pin<Box<dyn Future<Output = Result<String, SdkError>> + Send + 'async_trait>>

where 'life0: 'async_trait, RpcEngine: 'async_trait,

Submit a new user turn.

fn submit_with_images<'life0, 'async_trait>( &'life0 self, prompt: String, image_urls: Vec<String>, ) -> Pin<Box<dyn Future<Output = Result<String, SdkError>> + Send + 'async_trait>>

where 'life0: 'async_trait, RpcEngine: 'async_trait,

Submit a new user turn with canonical multimodal image inputs.

fn interrupt<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<bool, SdkError>> + Send + 'async_trait>>

where 'life0: 'async_trait, RpcEngine: 'async_trait,

Interrupt an active turn.

fn steer<'life0, 'async_trait>( &'life0 self, prompt: String, ) -> Pin<Box<dyn Future<Output = Result<(), SdkError>> + Send + 'async_trait>>

where 'life0: 'async_trait, RpcEngine: 'async_trait,

Queue a steering instruction when supported.

fn respond<'life0, 'async_trait>( &'life0 self, response: FrontendResponse, ) -> Pin<Box<dyn Future<Output = Result<(), SdkError>> + Send + 'async_trait>>

where 'life0: 'async_trait, RpcEngine: 'async_trait,

Answer a typed runtime request when supported.

fn invoke<'life0, 'async_trait>( &'life0 self, operation: FrontendOperationInvocation, ) -> Pin<Box<dyn Future<Output = Result<FrontendOperationResult, SdkError>> + Send + 'async_trait>>

where 'life0: 'async_trait, RpcEngine: 'async_trait,

Invoke one operation from the descriptor’s explicit catalog.

fn close<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<(), SdkError>> + Send + 'async_trait>>

where 'life0: 'async_trait, RpcEngine: 'async_trait,

Explicitly close the SDK-owned runtime when the negotiated descriptor grants that owner-level action. Dropping an attachment is always a detach and never calls this operation implicitly.

fn lease_snapshot<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<RuntimeLeaseSnapshot, SdkError>> + Send + 'async_trait>>

where 'life0: 'async_trait, Self: 'async_trait,

Read the one-controller/many-observer ownership state.

fn take_control<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<RuntimeLeaseSnapshot, SdkError>> + Send + 'async_trait>>

where 'life0: 'async_trait, Self: 'async_trait,

Explicitly acquire the controller lease from another interactive client. Ordinary mutations never perform an implicit takeover.

fn heartbeat<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<RuntimeLeaseSnapshot, SdkError>> + Send + 'async_trait>>

where 'life0: 'async_trait, Self: 'async_trait,

Refresh observer activity and a controller lease owned by this client.

fn detach<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<RuntimeLeaseSnapshot, SdkError>> + Send + 'async_trait>>

where 'life0: 'async_trait, Self: 'async_trait,

Release this client’s observer/controller state without stopping the runtime.