Enum ToolEvent 

pub enum ToolEvent {
    Start {
        tool_id: String,
        call_id: Option<u64>,
        metadata: Option<Value>,
    },
    Progress {
        pct: Option<f32>,
        message: Option<String>,
    },
    Delta {
        data: Value,
    },
    Result {
        data: Value,
    },
    Error {
        code: String,
        message: String,
        details: Option<Value>,
    },
}

Wire envelope every server-streaming AI tool emits, one envelope per chunk on the underlying crate::adapter::net::mesh_rpc::RpcStream.

Unary tools synthesize a single ToolEvent::Result under the hood; client-side call_tool unwraps so unary callers never see envelopes directly. Streaming callers (call_tool_streaming) see each event as it arrives.

JSON-encoded per chunk (not postcard) so dumps stay readable and clients can use whatever JSON parser they already have for the typed request body. The envelope is the ONE convention every provider adapter (OpenAI / Anthropic / Gemini / MCP / Hermes / custom) lowers into the framework’s native streaming protocol.

Plan: locked decision #4 in docs/plans/NRPC_AI_TOOL_CALLING_AND_AGENT_DX.md.

Variants

Start

Fires once on stream open. Carries the substrate’s call_id so clients can correlate later events to the outstanding invocation (useful when an agent has multiple tool calls in flight at once).

Fields

tool_id: String

nRPC service name the call is targeting.

call_id: Option<u64>

Substrate call id (matches RpcContext::call_id on the server side). Optional because not every host knows the call id at envelope-construction time.

metadata: Option<Value>

Optional free-form metadata the host wants the agent to see at stream open (model name, version, etc.).

Progress

Coarse progress for spinner UIs. pct is 0.0..=100.0.

Fields

pct: Option<f32>

Optional fractional progress in 0.0..=100.0. Adapters surface this as a UI progress hint (loading bar, spinner label).

message: Option<String>

Optional human-readable progress message (e.g. "indexing", "step 2 of 5").

Delta

Partial output — model tokens, file bytes, log lines. The adapter decides how to lower these into the provider’s streaming protocol (Anthropic tool_use_block_delta, etc.).

Fields

data: Value

Partial output payload. Schema is tool-defined; common shapes are {"token": "..."} for LLM streaming and {"chunk": "<base64>"} for binary file chunks.

Result

Terminal full result. Client sees exactly one Result OR one Error per stream — never both.

Fields

data: Value

Final result payload. Conforms to the tool’s output_schema when one is published.

Error

Terminal failure with structured detail. Adapter lowers this to the provider’s tool-error block.

Fields

code: String

Machine-parseable error code (e.g. "invalid_input", "upstream_timeout", "cancelled").

message: String

Human-readable message; surfaced to the model.

details: Option<Value>

Optional structured detail for debugging (e.g. {"upstream": "anthropic"}).

Implementations

impl ToolEvent

pub fn is_terminal(&self) -> bool

True if self is a terminal envelope (Result or Error). Used by the SDK’s streaming wrapper to detect end-of-stream when the underlying RpcStream is still open (e.g. a misbehaving handler that emitted Result but didn’t close).

Trait Implementations

impl Clone for ToolEvent

fn clone(&self) -> ToolEvent

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for ToolEvent

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for ToolEvent

fn deserialize<__D>( __deserializer: __D, ) -> Result<ToolEvent, <__D as Deserializer<'de>>::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl PartialEq for ToolEvent

fn eq(&self, other: &ToolEvent) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for ToolEvent

fn serialize<__S>( &self, __serializer: __S, ) -> Result<<__S as Serializer>::Ok, <__S as Serializer>::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for ToolEvent