Struct RuntimeClient 

pub struct RuntimeClient { /* private fields */ }

Implementations

impl RuntimeClient

pub async fn spawn(command: Command) -> Result<Self>

Spawn the Runtime child process (stdin / stdout taken over, stderr inherited to the host log) and wait for its ready line.

pub fn over<R, W>(reader: R, writer: W) -> Self

where R: AsyncRead + Send + Unpin + 'static, W: AsyncWrite + Send + Unpin + 'static,

A connection over any pair of streams. One frame per line on reader; one line per frame on writer.

pub fn over_with_handler<R, W>( reader: R, writer: W, handler: Option<RequestHandler>, ) -> Self

where R: AsyncRead + Send + Unpin + 'static, W: AsyncWrite + Send + Unpin + 'static,

Same as above, and also serves requests sent by the peer: a module subprocess is exactly such a “client that also gets called”.

pub fn emit(&self, event: Value) -> Result<(), ResponseError>

Send an event frame ({"type": ...}). Events sent by a module are wrapped by Runtime as {"type":"module"} and broadcast to apps.

pub fn events(&self) -> UnboundedReceiver<ClientEvent>

Subscribe to events. One unbounded queue per subscriber: nothing is lost in-process, None means the client has been dropped. Session events arrive in order, exactly once (see ClientEvent); a hole that cannot be refilled is ClientEvent::Gap.

pub async fn request( &self, method: &str, params: Option<Value>, ) -> Result<Value, ResponseError>

Any method, including host extensions. An error is the error in the response frame (code / message / data unchanged); a lost connection is ResponseError::CONNECTION_LOST.

pub async fn start( &self, agent_id: &str, launch: Value, owner: Option<&str>, ) -> Result<(), ResponseError>

owner: sub-owner under the connection (desktop window label); None means the connection itself, which has write access to the agents of all sub-owners. launch is the launch parameters on top of Runtime’s engine table {engine, cwd, args, env, provider, model, connection}. Start an agent process. Errors if a process of the same name is still alive: switching engine is “stop first, wait for the Exit event, then start”.

pub async fn send( &self, agent_id: &str, line: &str, owner: Option<&str>, ) -> Result<(), ResponseError>

pub async fn stop( &self, agent_id: &str, owner: Option<&str>, ) -> Result<(), ResponseError>

pub async fn attach_session( &self, session_id: &str, owner: Option<&str>, ) -> Result<Option<AttachInfo>, ResponseError>

pub async fn release_session( &self, session_id: &str, owner: Option<&str>, ) -> Result<(), ResponseError>

pub async fn stop_session( &self, session_id: &str, owner: Option<&str>, ) -> Result<(), ResponseError>

pub async fn detach_owner(&self, owner: &str) -> Result<(), ResponseError>

pub async fn release_execution( &self, execution_id: &str, ) -> Result<bool, ResponseError>

pub async fn agent_for_session( &self, session_id: &str, ) -> Result<Option<String>, ResponseError>

pub async fn session_replay( &self, session_id: &str, ) -> Result<Vec<String>, ResponseError>

pub async fn set_slow_mode(&self, delay_ms: u64) -> Result<(), ResponseError>

pub async fn mark_read( &self, session_id: &str, version: Option<u64>, ) -> Result<(), ResponseError>

version: the state the reader saw; an older confirmation does not clear a newer done. None confirms whatever is current.

pub async fn set_session_title( &self, session_id: &str, title: &str, ) -> Result<(), ResponseError>

pub async fn session_lifecycle( &self, session_id: &str, ) -> Result<Vec<SessionLifecycleFrame>, ResponseError>

pub async fn session_events( &self, session_id: &str, after_sequence: Option<u64>, limit: Option<usize>, ) -> Result<Vec<SessionEventFrame>, ResponseError>

pub async fn run_states(&self) -> Result<Vec<SessionRunState>, ResponseError>

pub async fn version(&self) -> Result<String, ResponseError>

Runtime’s own version (the same number as alwith-runtime --version).

pub async fn agents(&self) -> Result<Vec<Value>, ResponseError>

pub async fn ping(&self) -> Result<(), ResponseError>

pub async fn acp_request( &self, agent_id: &str, method: &str, params: Value, request_id: Option<Value>, owner: Option<&str>, ) -> Result<Value, ResponseError>

Any ACP request; Runtime assigns the id and awaits the response. request_id: pick your own id (needed only to retract with $/cancel_request).

pub async fn acp_notify( &self, agent_id: &str, method: &str, params: Value, owner: Option<&str>, ) -> Result<(), ResponseError>

pub async fn acp_respond( &self, agent_id: &str, id: Value, result: Option<Value>, error: Option<Value>, owner: Option<&str>, ) -> Result<(), ResponseError>

Answer an agent request (the id in RuntimeEvent::AcpAgentRequest).

pub async fn initialize( &self, agent_id: &str, info: Option<Value>, capabilities: Option<Value>, owner: Option<&str>, ) -> Result<Value, ResponseError>

ACP handshake, optionally with your own client info and capabilities; returns the cached result if already done. Session methods handshake automatically with a default identity; call this only to declare capabilities.

pub async fn session_new( &self, agent_id: &str, cwd: &str, mcp_servers: Vec<Value>, owner: Option<&str>, ) -> Result<Value, ResponseError>

Create a session (handshaking first if needed). Returns the ACP session/new result, containing sessionId.

pub async fn session_load( &self, agent_id: &str, session_id: &str, cwd: &str, mcp_servers: Vec<Value>, owner: Option<&str>, ) -> Result<Value, ResponseError>

pub async fn session_resume( &self, agent_id: &str, session_id: &str, cwd: &str, replay_from: Option<Value>, owner: Option<&str>, ) -> Result<Value, ResponseError>

pub async fn session_fork( &self, agent_id: &str, session_id: &str, cwd: &str, mcp_servers: Vec<Value>, owner: Option<&str>, ) -> Result<Value, ResponseError>

pub async fn prompt( &self, agent_id: &str, session_id: &str, prompt: Value, owner: Option<&str>, ) -> Result<Value, ResponseError>

One turn, returns only when the turn ends (the ACP result); progress arrives as AcpNotification events.

pub async fn cancel( &self, agent_id: &str, session_id: &str, owner: Option<&str>, ) -> Result<(), ResponseError>

pub fn kill(&self)

Kill the child process immediately (exit fallback; the normal path uses shutdown). No-op if there is no child process.

pub fn closed(&self) -> Option<String>

Whether the connection is already down (read side ended or child process exited).

pub async fn close(&self, grace: Duration)

Exit chain: first ask Runtime to leave (the shutdown method; it gives modules and agents a 2-second wind-down window and then kill_all), and wait for the connection to end; if it has not ended within grace, force-kill the child process. Killing directly would leave the agent’s spawned process groups alive, so courtesy first, force second. Difference from Self::shutdown: it does not consume self, so a host holding an Arc<RuntimeClient> can call it too.

pub async fn shutdown(self)

Close the write end (Runtime kill_all’s and exits on EOF), wait for the read side to end; reap the child process if there is one.

Trait Implementations

impl Drop for RuntimeClient

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.