Trait ToolServerConnection 

pub trait ToolServerConnection: Send + Sync {
    // Required methods
    fn server_id(&self) -> &str;
    fn tool_names(&self) -> Vec<String>;
    fn invoke<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        tool_name: &'life1 str,
        arguments: Value,
        nested_flow_bridge: Option<&'life2 mut dyn NestedFlowBridge>,
    ) -> Pin<Box<dyn Future<Output = Result<Value, KernelError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait;

    // Provided methods
    fn tool_is_read_only(&self, _tool_name: &str) -> bool { ... }
    fn invoke_with_cost<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        tool_name: &'life1 str,
        arguments: Value,
        nested_flow_bridge: Option<&'life2 mut dyn NestedFlowBridge>,
    ) -> Pin<Box<dyn Future<Output = Result<(Value, Option<ToolInvocationCost>), KernelError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait { ... }
    fn measures_realized_cost(&self) -> bool { ... }
    fn invoke_stream<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        tool_name: &'life1 str,
        arguments: Value,
        nested_flow_bridge: Option<&'life2 mut dyn NestedFlowBridge>,
    ) -> Pin<Box<dyn Future<Output = Result<Option<ToolServerStreamResult>, KernelError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait { ... }
    fn drain_events<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<ToolServerEvent>, KernelError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait { ... }
}

Trait representing a connection to a tool server.

The kernel holds one ToolServerConnection per registered server. In production this is an mTLS connection over UDS or TCP. For testing, an in-process implementation can be used.

Required Methods

fn server_id(&self) -> &str

The server’s unique identifier.

fn tool_names(&self) -> Vec<String>

List the tool names available on this server.

fn invoke<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, tool_name: &'life1 str, arguments: Value, nested_flow_bridge: Option<&'life2 mut dyn NestedFlowBridge>, ) -> Pin<Box<dyn Future<Output = Result<Value, KernelError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Invoke a tool on this server. The kernel has already validated the capability and run guards before calling this.

Provided Methods

fn tool_is_read_only(&self, _tool_name: &str) -> bool

Return whether the registered tool is explicitly declared read-only.

The conservative default keeps unannotated tools side-effecting for durable admission. Implementations should return true only from authenticated manifest metadata owned by the registered connection.

fn invoke_with_cost<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, tool_name: &'life1 str, arguments: Value, nested_flow_bridge: Option<&'life2 mut dyn NestedFlowBridge>, ) -> Pin<Box<dyn Future<Output = Result<(Value, Option<ToolInvocationCost>), KernelError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Invoke a tool and optionally report the actual cost of the invocation.

Tool servers that track monetary costs should override this method. The default implementation delegates to invoke and returns None cost, meaning the kernel will charge max_cost_per_invocation as the worst-case debit.

fn measures_realized_cost(&self) -> bool

Whether this server measures the realized cost of an invocation it dispatches.

The default is true: a server that returns None cost from invoke_with_cost is asserting that the realized cost equals the authorized ceiling, and the kernel reconciles and settles that as a completed spend.

A server that returns false does not execute the target tool and cannot measure a realized cost (for example a pre-execution authorization gate that dispatches a pass-through while the real tool runs elsewhere). For such a server the kernel reverses the pre-execution hold and signs a provisional, unreconciled receipt instead of a settled authoritative spend, since no cost was realized on this path. Real reconciliation happens at the execution site.

fn invoke_stream<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, tool_name: &'life1 str, arguments: Value, nested_flow_bridge: Option<&'life2 mut dyn NestedFlowBridge>, ) -> Pin<Box<dyn Future<Output = Result<Option<ToolServerStreamResult>, KernelError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Invoke a tool that can emit multiple streamed chunks before its final terminal state.

Servers that do not support streaming can ignore this and rely on invoke.

fn drain_events<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<Vec<ToolServerEvent>, KernelError>> + Send + 'async_trait>>

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

Drain asynchronous events emitted after a tool invocation has already returned.

Native tool servers can use this to surface late URL-elicitation completions and catalog/resource notifications without depending on a still-live request-local bridge.

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors