Skip to main content

rusty_agent_runtime/
tool.rs

1//! Tool abstraction, registry, and parallel tool-call dispatch.
2//!
3//! A [`Tool`] is an async callable with a JSON-schema-described parameter
4//! surface. [`ToolRegistry`] holds the tools available to an agent and emits
5//! OpenAI-format tool schemas for the chat API. [`ToolExecutor`] dispatches
6//! a batch of [`crate::llm::ToolCall`]s **in parallel** (the `ToolNode`
7//! pattern of the prebuilt ReAct agent) and returns one `role: "tool"`
8//! message per call, preserving call order.
9
10use std::collections::HashMap;
11use std::sync::Arc;
12
13use async_trait::async_trait;
14use futures::FutureExt;
15use serde_json::{json, Value};
16
17use crate::effects::{EffectAdmissionContext, EffectRequest};
18use crate::error::{Result, RustyError};
19use crate::llm::{ChatMessage, ToolCall};
20use crate::middleware::{MiddlewareChain, ToolInvocation};
21
22/// An invocable tool.
23///
24/// Implement directly for stateful tools, or wrap async closures with a
25/// small adapter struct. `parameters_schema` should be a JSON Schema object
26/// (`{"type": "object", "properties": {...}, "required": [...]}`).
27#[async_trait]
28pub trait Tool: Send + Sync {
29    /// The tool name — must match what the model emits in `tool_calls`.
30    fn name(&self) -> &str;
31
32    /// Human/model-facing description used in the tool schema.
33    fn description(&self) -> &str;
34
35    /// JSON Schema for the tool's arguments.
36    fn parameters_schema(&self) -> Value;
37
38    /// The declared effect classification of calling this tool (Flight
39    /// Recorder, R0.5): recorded on tool-call journal events and used by
40    /// retry/replay policy.
41    ///
42    /// The default is [`crate::record::Effect::NonIdempotent`] — the runtime
43    /// cannot prove a tool call is safely repeatable, so it assumes the
44    /// restrictive class. Override to `ReadOnly` for pure lookups or
45    /// `Idempotent` for keyed writes; never declare a weaker class than the
46    /// tool's real behavior.
47    fn effect(&self) -> crate::record::Effect {
48        crate::record::Effect::NonIdempotent
49    }
50
51    /// Stable effect kind used for deterministic effect ids and compensation
52    /// lookup. Defaults to the tool name.
53    fn effect_kind(&self) -> &str {
54        self.name()
55    }
56
57    /// Stable idempotency key for this call, when [`Tool::effect`] declares
58    /// [`crate::record::Effect::Idempotent`]. The admission boundary rejects
59    /// an idempotent call that returns `None` here.
60    fn idempotency_key(&self, _args: &Value) -> Option<String> {
61        None
62    }
63
64    /// Describe this concrete call for the runtime admission boundary.
65    ///
66    /// The default combines the tool's declared class and stable kind with a
67    /// canonical hash of the post-middleware arguments and tool-call id. The
68    /// call id is the occurrence discriminator: two identical irreversible
69    /// calls cannot spend the same approval. Wrappers that override this
70    /// method must delegate it to remain transparent.
71    fn effect_request(&self, call: &ToolCall) -> EffectRequest {
72        let input = json!({
73            "arguments": &call.arguments,
74            "tool_call_id": &call.id,
75        });
76        EffectRequest::new(
77            self.effect_kind(),
78            self.effect(),
79            &input,
80            self.idempotency_key(&call.arguments),
81        )
82    }
83
84    /// Execute the tool with model-supplied arguments.
85    async fn call(&self, args: Value) -> Result<Value>;
86}
87
88/// A registry of tools, shared cheaply via `Arc<dyn Tool>`.
89#[derive(Default, Clone)]
90pub struct ToolRegistry {
91    tools: HashMap<String, Arc<dyn Tool>>,
92}
93
94impl std::fmt::Debug for ToolRegistry {
95    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
96        f.debug_struct("ToolRegistry")
97            .field("tools", &self.tools.keys().collect::<Vec<_>>())
98            .finish()
99    }
100}
101
102impl ToolRegistry {
103    /// An empty registry.
104    pub fn new() -> Self {
105        Self::default()
106    }
107
108    /// Register a tool. Re-registering the same name replaces the tool.
109    pub fn register<T: Tool + 'static>(&mut self, tool: T) -> &mut Self {
110        self.tools.insert(tool.name().to_owned(), Arc::new(tool));
111        self
112    }
113
114    /// Register a pre-shared tool.
115    pub fn register_shared(&mut self, tool: Arc<dyn Tool>) -> &mut Self {
116        self.tools.insert(tool.name().to_owned(), tool);
117        self
118    }
119
120    /// Look up a tool by name.
121    pub fn get(&self, name: &str) -> Option<Arc<dyn Tool>> {
122        self.tools.get(name).cloned()
123    }
124
125    /// `true` if a tool with this name is registered.
126    pub fn contains(&self, name: &str) -> bool {
127        self.tools.contains_key(name)
128    }
129
130    /// All registered tool names.
131    pub fn names(&self) -> impl Iterator<Item = &str> {
132        self.tools.keys().map(String::as_str)
133    }
134
135    /// Number of registered tools.
136    pub fn len(&self) -> usize {
137        self.tools.len()
138    }
139
140    /// `true` if no tools are registered.
141    pub fn is_empty(&self) -> bool {
142        self.tools.is_empty()
143    }
144
145    /// OpenAI-format tool schemas for the chat API, one per registered tool:
146    /// `{"type": "function", "function": {"name", "description", "parameters"}}`.
147    /// Pass directly as the `tools` argument of
148    /// [`crate::llm::ChatModel::chat`].
149    pub fn schemas(&self) -> Vec<Value> {
150        self.tools
151            .values()
152            .map(|tool| {
153                json!({
154                    "type": "function",
155                    "function": {
156                        "name": tool.name(),
157                        "description": tool.description(),
158                        "parameters": tool.parameters_schema(),
159                    }
160                })
161            })
162            .collect()
163    }
164}
165
166/// Dispatches tool calls against a registry, in parallel.
167///
168/// Typical use in a ReAct `tools` node: take the assistant message's
169/// `tool_calls`, `execute_batch` them, and append the resulting tool
170/// messages to the `messages` channel via the `AddMessages` reducer.
171///
172/// Attach a [`MiddlewareChain`] via [`ToolExecutor::with_middleware`] to run
173/// every dispatched call through the chain's tool hooks (Middleware /
174/// Interceptor SDK): a layer may mutate the call, reject it (surfacing as an
175/// `ERROR:` tool message under the same failure-isolation contract below),
176/// or short-circuit it with a substitute result.
177#[derive(Debug, Clone, Default)]
178pub struct ToolExecutor {
179    registry: ToolRegistry,
180    middleware: MiddlewareChain,
181    effect_admission: Option<EffectAdmissionContext>,
182    thread_id: String,
183    node: String,
184}
185
186impl ToolExecutor {
187    /// An executor over `registry`.
188    pub fn new(registry: ToolRegistry) -> Self {
189        Self {
190            registry,
191            ..Self::default()
192        }
193    }
194
195    /// The underlying registry.
196    pub fn registry(&self) -> &ToolRegistry {
197        &self.registry
198    }
199
200    /// Builder-style: run every dispatched call through `chain`'s tool
201    /// hooks. Typically handed the chain from
202    /// [`crate::node::NodeContext::middleware`].
203    pub fn with_middleware(mut self, chain: MiddlewareChain) -> Self {
204        self.middleware = chain;
205        self
206    }
207
208    /// Builder-style: enforce the run-scoped effect boundary on every tool
209    /// body this executor dispatches.
210    pub fn with_effect_admission(mut self, context: EffectAdmissionContext) -> Self {
211        self.effect_admission = Some(context);
212        self
213    }
214
215    /// Builder-style: label dispatched calls with the thread and node they
216    /// originate from (flowing into the [`ToolInvocation`] context).
217    pub fn with_call_context(
218        mut self,
219        thread_id: impl Into<String>,
220        node: impl Into<String>,
221    ) -> Self {
222        self.thread_id = thread_id.into();
223        self.node = node.into();
224        self
225    }
226
227    /// The attached middleware chain (empty when none was added).
228    pub fn middleware(&self) -> &MiddlewareChain {
229        &self.middleware
230    }
231
232    /// The attached effect boundary, if enforcement is enabled.
233    pub fn effect_admission(&self) -> Option<&EffectAdmissionContext> {
234        self.effect_admission.as_ref()
235    }
236
237    /// Execute a batch of tool calls concurrently.
238    ///
239    /// Returns one [`ChatMessage::tool_result`] per call, **in the same
240    /// order as `calls`** (order stability matters for conversation
241    /// reconstruction). Individual failures do not abort the batch: a failed
242    /// call yields a tool message whose content is the error description
243    /// (prefixed with `ERROR:`), so the model can observe and recover from
244    /// tool failures — matching `ToolNode`'s default `handle_tool_errors`
245    /// behavior. A *panicking* tool is contained the same way: the unwind is
246    /// caught and reported as an `ERROR:` tool message instead of taking
247    /// down the batch (and the executor task driving it).
248    pub async fn execute_batch(&self, calls: &[ToolCall]) -> Vec<ChatMessage> {
249        let futures = calls.iter().map(|call| {
250            let registry = self.registry.clone();
251            let chain = self.middleware.clone();
252            let effect_admission = self.effect_admission.clone();
253            let thread_id = self.thread_id.clone();
254            let node = self.node.clone();
255            async move {
256                let result = std::panic::AssertUnwindSafe(async {
257                    let value = if chain.is_empty() {
258                        dispatch_tool(&registry, call, effect_admission.as_ref()).await?
259                    } else {
260                        let mut invocation = ToolInvocation::new(thread_id, node, call.clone());
261                        chain
262                            .run_tool(&mut invocation, |invocation| {
263                                let registry = registry.clone();
264                                let effect_admission = effect_admission.clone();
265                                let call = invocation.call().clone();
266                                async move {
267                                    // The lookup happens after before-hooks,
268                                    // so a layer may rewrite the arguments —
269                                    // or the target tool name itself.
270                                    dispatch_tool(&registry, &call, effect_admission.as_ref()).await
271                                }
272                            })
273                            .await?
274                    };
275                    Ok::<String, RustyError>(match value {
276                        Value::String(s) => s,
277                        other => other.to_string(),
278                    })
279                })
280                .catch_unwind()
281                .await;
282                match result {
283                    Ok(Ok(content)) => ChatMessage::tool_result(&call.id, content),
284                    Ok(Err(e)) => ChatMessage::tool_result(&call.id, format!("ERROR: {e}")),
285                    Err(payload) => ChatMessage::tool_result(
286                        &call.id,
287                        format!(
288                            "ERROR: tool `{}` panicked: {}",
289                            call.name,
290                            // `&*`: `&payload` would unsize-coerce the *Box*
291                            // itself into `&dyn Any`, hiding the real payload.
292                            panic_message(&*payload)
293                        ),
294                    ),
295                }
296            }
297        });
298        futures::future::join_all(futures).await
299    }
300}
301
302/// Resolve, admit, and invoke one finalized call. Middleware reaches this
303/// function only after its before-hooks have settled the tool name and
304/// arguments, so admission cannot be bypassed by rewriting a call after it
305/// was approved.
306async fn dispatch_tool(
307    registry: &ToolRegistry,
308    call: &ToolCall,
309    effect_admission: Option<&EffectAdmissionContext>,
310) -> Result<Value> {
311    let tool = registry
312        .get(&call.name)
313        .ok_or_else(|| RustyError::Tool(format!("unknown tool `{}`", call.name)))?;
314    let _permit = effect_admission
315        .map(|context| context.admit(&tool.effect_request(call)))
316        .transpose()
317        .map_err(|violation| RustyError::Tool(format!("effect admission denied: {violation}")))?;
318    tool.call(call.arguments.clone()).await
319}
320
321/// Best-effort extraction of a panic payload for error reporting.
322fn panic_message(payload: &(dyn std::any::Any + Send)) -> String {
323    if let Some(s) = payload.downcast_ref::<&str>() {
324        (*s).to_owned()
325    } else if let Some(s) = payload.downcast_ref::<String>() {
326        s.clone()
327    } else {
328        "<non-string payload>".to_owned()
329    }
330}
331
332#[cfg(test)]
333mod tests {
334    use super::*;
335    use serde_json::json;
336
337    struct Echo;
338
339    #[async_trait]
340    impl Tool for Echo {
341        fn name(&self) -> &str {
342            "echo"
343        }
344        fn description(&self) -> &str {
345            "Echoes its input."
346        }
347        fn parameters_schema(&self) -> Value {
348            json!({"type": "object", "properties": {"text": {"type": "string"}}})
349        }
350        async fn call(&self, args: Value) -> Result<Value> {
351            Ok(json!(args.get("text").cloned().unwrap_or(Value::Null)))
352        }
353    }
354
355    struct Fail;
356
357    #[async_trait]
358    impl Tool for Fail {
359        fn name(&self) -> &str {
360            "fail"
361        }
362        fn description(&self) -> &str {
363            "Always fails."
364        }
365        fn parameters_schema(&self) -> Value {
366            json!({"type": "object"})
367        }
368        async fn call(&self, _args: Value) -> Result<Value> {
369            Err(RustyError::Tool("boom".into()))
370        }
371    }
372
373    #[test]
374    fn registry_schemas_are_openai_shaped() {
375        let mut registry = ToolRegistry::new();
376        registry.register(Echo);
377        let schemas = registry.schemas();
378        assert_eq!(schemas.len(), 1);
379        assert_eq!(schemas[0]["type"], json!("function"));
380        assert_eq!(schemas[0]["function"]["name"], json!("echo"));
381        assert!(schemas[0]["function"]["parameters"]["properties"].is_object());
382    }
383
384    #[tokio::test]
385    async fn batch_preserves_order_and_isolates_failures() {
386        let mut registry = ToolRegistry::new();
387        registry.register(Echo);
388        registry.register(Fail);
389        let executor = ToolExecutor::new(registry);
390
391        let calls = vec![
392            ToolCall::new("c1", "echo", json!({"text": "hello"})),
393            ToolCall::new("c2", "fail", json!({})),
394            ToolCall::new("c3", "missing", json!({})),
395        ];
396        let results = executor.execute_batch(&calls).await;
397
398        assert_eq!(results.len(), 3);
399        assert_eq!(results[0].tool_call_id.as_deref(), Some("c1"));
400        assert_eq!(results[0].content.as_deref(), Some("hello"));
401        assert_eq!(results[1].tool_call_id.as_deref(), Some("c2"));
402        assert!(results[1].content.as_deref().unwrap().starts_with("ERROR:"));
403        assert_eq!(results[2].tool_call_id.as_deref(), Some("c3"));
404        assert!(results[2]
405            .content
406            .as_deref()
407            .unwrap()
408            .contains("unknown tool"));
409    }
410
411    struct Panic;
412
413    #[async_trait]
414    impl Tool for Panic {
415        fn name(&self) -> &str {
416            "panic"
417        }
418        fn description(&self) -> &str {
419            "Always panics."
420        }
421        fn parameters_schema(&self) -> Value {
422            json!({"type": "object"})
423        }
424        async fn call(&self, _args: Value) -> Result<Value> {
425            panic!("kaboom");
426        }
427    }
428
429    #[tokio::test]
430    async fn panicking_tool_is_contained_as_error_message() {
431        let mut registry = ToolRegistry::new();
432        registry.register(Echo);
433        registry.register(Panic);
434        let executor = ToolExecutor::new(registry);
435
436        let calls = vec![
437            ToolCall::new("c1", "panic", json!({})),
438            ToolCall::new("c2", "echo", json!({"text": "still alive"})),
439        ];
440        let results = executor.execute_batch(&calls).await;
441
442        // The panic joins the same ERROR: channel as ordinary failures, and
443        // the rest of the batch completes normally.
444        assert_eq!(results.len(), 2);
445        let msg = results[0].content.as_deref().unwrap();
446        assert!(msg.starts_with("ERROR:"), "got: {msg}");
447        assert!(msg.contains("panicked"), "got: {msg}");
448        assert!(msg.contains("kaboom"), "got: {msg}");
449        assert_eq!(results[1].content.as_deref(), Some("still alive"));
450    }
451}