Struct ToolContext 

pub struct ToolContext { /* private fields */ }

Context passed to Rust tools during dispatch.

Provides access to the current conversation ID, a shared key-value state store (SharedState) that persists across tool calls within the same agent turn, and typed extensions via set_ext / get_ext.

Implementations

impl ToolContext

pub fn new() -> Self

Create a new, empty context: no conversation ID and a fresh state store.

Customize it with with_conversation_id and with_shared_state.

pub fn with_conversation_id(self, conversation_id: impl Into<String>) -> Self

Set the conversation ID. Chainable.

pub fn with_caller(&self, conversation_id: impl Into<String>) -> Self

Derive a new context that carries a different conversation ID while sharing this context’s state store and typed extensions.

Both the shared state (SharedState) and the typed extension map are held behind Arc, so the returned context reads and writes the same underlying stores — only the conversation identity differs. This is the primitive a single MCP server uses to serve many callers: each connection derives its own identity from the shared, session-wide context without duplicating extensions like injected session state.

use std::sync::Arc;

use llm_tool::ToolContext;

let session = ToolContext::new().with_conversation_id("server");
session.set_ext(Arc::new(42u64)).unwrap();

let alice = session.with_caller("alice");
assert_eq!(alice.conversation_id(), Some("alice"));
// Extensions are shared, not copied.
assert_eq!(alice.get_ext::<Arc<u64>>().as_deref(), Some(&42));

pub fn with_shared_state(self, state: SharedState) -> Self

Use an externally-provided SharedState as this context’s state store.

Use this when multiple ToolContext instances (e.g. successive tool calls within the same agent) must read/write the same state store. Obtain a handle from an existing context via shared_state.

pub fn shared_state(&self) -> SharedState

Return a cloneable handle to this context’s shared state store.

Pass the returned handle to with_shared_state on another context to share the same underlying store.

pub fn conversation_id(&self) -> Option<&str>

Return the conversation ID, if one has been set.

pub fn get_state(&self, key: &str, default: Value) -> Value

Retrieve a value from the shared state, returning default if the key is absent or the lock is poisoned.

This method never fails — on a poisoned lock it logs a warning and returns default. See the struct-level docs for rationale.

pub fn set_state(&self, key: &str, value: Value) -> Result<(), ToolError>

Insert or update a value in the shared state.

Unlike get_state, this method returns Err on a poisoned lock because silently dropping a write can cause subtle bugs. See the struct-level docs for rationale.

Errors

Returns ToolError if the lock is poisoned.

pub fn set_ext<T: Send + Sync + 'static>( &self, value: T, ) -> Result<(), ToolError>

Store a typed value in the extensions map.

Values are keyed by TypeId, so each concrete type can only appear once. Typically used to store Arc<T> for shared, cloneable access.

Errors

Returns ToolError if the lock is poisoned.

pub fn get_ext<T: Clone + Send + Sync + 'static>(&self) -> Option<T>

Retrieve a clone of a typed value from the extensions map.

Returns None if no value of type T has been stored via set_ext.

pub fn with_surrogate_vault(self, vault: SurrogateVault) -> Self

Attach a pre-constructed SurrogateVault to this context. Chainable.

pub fn surrogate_vault(&self) -> Result<SurrogateVault, ToolError>

Obtain the session’s SurrogateVault, lazily initializing and storing one in extensions if not yet present.

Errors

Returns ToolError if the extensions lock is poisoned.

pub fn mint_surrogate( &self, kind: &str, raw_value: impl Into<String>, ) -> Result<SurrogateHandle, ToolError>

Mint an opaque SurrogateHandle (<surrogate:kind:id>) in this context’s SurrogateVault.

Errors

Returns ToolError if kind or raw_value is invalid or a lock is poisoned.

pub fn resolve_surrogates(&self, input: &str) -> Result<String, ToolError>

Resolve all <surrogate:kind:id> tokens in input using this context’s SurrogateVault.

Fails closed with ToolError if any surrogate token in input was not minted in this session.

Errors

Returns ToolError if an unknown/malformed surrogate token is present or a lock is poisoned.

pub fn redact_surrogates(&self, output: &str) -> Result<String, ToolError>

Redact any registered raw secret/handle values in output back to their <surrogate:kind:id> tokens.

Errors

Returns ToolError if a lock is poisoned.

Trait Implementations

impl Clone for ToolContext

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for ToolContext

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

Formats the value using the given formatter.

impl Default for ToolContext

fn default() -> Self

Returns the “default value” for a type.