Struct AgentClient 

pub struct AgentClient { /* private fields */ }

Client for communicating with agentd through the agent relay.

See the module-level docs for an overview of the two API tiers.

Implementations

impl AgentClient

pub async fn close(self)

Close the connection. Drops the writer and aborts the reader task; any in-flight requests resolve with AgentClientError::Closed.

impl AgentClient

pub async fn request_raw( &self, flags: u8, body: Vec<u8>, ) -> AgentClientResult<RawFrame>

One-shot raw request: alloc id, send a frame with (flags, body), await one response frame with the matching id.

Use this for protocol RPCs that produce exactly one terminal response (e.g. FsRequest → FsResponse).

pub async fn stream_raw( &self, flags: u8, body: Vec<u8>, ) -> AgentClientResult<(u32, Receiver<RawFrame>)>

Open a streaming raw session: alloc id, register a subscription, send the opening frame, return (id, receiver).

The receiver yields every frame the relay forwards for this id until a frame with [FLAG_TERMINAL] arrives or the receiver is dropped. Use send_raw with the returned id to send follow-up frames within the session.

pub async fn send_raw( &self, id: u32, flags: u8, body: &[u8], ) -> AgentClientResult<()>

Send a follow-up raw frame on an existing correlation id.

Use for messages that belong to a session started via stream_raw (e.g. ExecStdin, ExecSignal, ExecResize, FsData chunks).

pub fn ready_bytes(&self) -> &[u8]

The cached core.ready handshake frame body bytes (CBOR-encoded).

Useful for bindings that want to deserialize the ready payload with their own CBOR tooling. For typed access, use ready.

pub fn protocol(&self) -> AgentProtocol

Agent protocol generation for this connection.

pub fn is_legacy_protocol(&self) -> bool

Returns true if this connection is using the legacy pre-0.5 protocol.

pub fn negotiated_version(&self) -> u8

The negotiated protocol generation for this connection: the lower of what this client speaks and what the sandbox advertised at handshake.

pub fn agent_version(&self) -> &str

The runtime’s self-reported package version, taken from its core.ready frame. Empty when the runtime predates this field (an older agent), in which case fall back to the generation for diagnostics.

pub fn supports(&self, t: MessageType) -> bool

Whether the connected sandbox is new enough to handle the given message type. The single source of truth for feature gating: callers that can’t gate by sending (e.g. the SSH/SFTP layer) consult this instead of inspecting the protocol generation directly.

pub fn ensure_version_compat(&self, t: MessageType) -> AgentClientResult<()>

Reject a message type the connected sandbox is too old to handle, against this connection’s negotiated generation. Fails before any bytes are sent, so only that one operation fails and the session continues.

pub fn ensure_version_compat_for( t: MessageType, negotiated: u8, ) -> AgentClientResult<()>

Check a message type against an explicit negotiated generation.

The single place the rule lives. Exposed for callers that hold the negotiated generation but not the live client (e.g. the SSH/SFTP layer).

impl AgentClient

pub async fn request<T: Serialize>( &self, t: MessageType, payload: &T, ) -> AgentClientResult<Message>

One-shot typed request. Flags are derived from the message type.

pub async fn stream<T: Serialize>( &self, t: MessageType, payload: &T, ) -> AgentClientResult<(u32, Receiver<Message>)>

Open a streaming typed session. Flags are derived from the message type. Returns the assigned id and a typed receiver.

pub async fn send<T: Serialize>( &self, id: u32, t: MessageType, payload: &T, ) -> AgentClientResult<()>

Send a follow-up typed message on an existing correlation id.

pub fn ready(&self) -> AgentClientResult<Ready>

Decode the cached handshake core.ready payload.

Trait Implementations

impl Drop for AgentClient

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.