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) + Send + Sync>>, ) -> Arc<Self>

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) + Send + Sync>>, ) -> Arc<Self>

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) + Send + Sync>>, ) -> Arc<Self>

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) + Send + Sync>>, ) -> Arc<Self>

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) + Send + Sync>>, ) -> Arc<Self>

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, FrontendRuntimeError>

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<FrontendEvent>

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, FrontendRuntimeError>

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<Self>, 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<Self>, 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<(), FrontendRuntimeError>

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<(), FrontendRuntimeError>

Resolve one pending interactive request exactly once.

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

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 start_claude_scheduler(self: &Arc<Self>) -> bool

Start the SDK-owned Claude runtime scheduler once.

The scheduler is deliberately owned by the same runtime as user turns, not by a CLI/TUI input loop. Detaching every frontend therefore does not pause queued prompts, cron jobs, or wakeups while the runtime process remains alive. Returns true for the caller that started it and false thereafter.

pub fn claude_scheduler_started(&self) -> bool

Whether this runtime has armed its scheduler driver.

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<Self>, 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, FrontendRuntimeError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: '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, FrontendRuntimeError>> + Send + 'async_trait>>

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

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

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

where Self: 'async_trait,

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

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

where Self: '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, FrontendRuntimeError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: '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, FrontendRuntimeError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: '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, FrontendRuntimeError>> + Send + 'async_trait>>

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

Interrupt an active turn.

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

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

Queue a steering instruction when supported.

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

where Self: 'async_trait, 'life0: '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, FrontendRuntimeError>> + Send + 'async_trait>>

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

Invoke one operation from the descriptor’s explicit catalog.

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

where Self: 'async_trait, 'life0: '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 Self: 'async_trait, 'life0: '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 Self: 'async_trait, 'life0: '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 Self: 'async_trait, 'life0: '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 Self: 'async_trait, 'life0: 'async_trait,

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