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.
306///
307/// Under a shadow boundary (R0.12 wave 4) a refused call is not an error
308/// by default: the admission context serves the recorded outcome from the
309/// source run's journal — the hybrid-replay rule, pin the effect and
310/// re-run the decision — and reports the refusal to its sink either way.
311/// Only a call the recorded world never saw surfaces as a failure, and a
312/// non-shadow context answers `None` from
313/// [`EffectAdmissionContext::serve_shadow`] unchanged.
314async fn dispatch_tool(
315    registry: &ToolRegistry,
316    call: &ToolCall,
317    effect_admission: Option<&EffectAdmissionContext>,
318) -> Result<Value> {
319    let tool = registry
320        .get(&call.name)
321        .ok_or_else(|| RustyError::Tool(format!("unknown tool `{}`", call.name)))?;
322    if let Some(context) = effect_admission {
323        let request = tool.effect_request(call);
324        if let Err(violation) = context.admit(&request) {
325            return match context.serve_shadow(
326                &request,
327                &crate::replay::tool_call_request(&call.name, &call.arguments),
328                &violation,
329            ) {
330                Some(recorded) => Ok(recorded),
331                None => Err(RustyError::Tool(format!(
332                    "effect admission denied: {violation}"
333                ))),
334            };
335        }
336    }
337    tool.call(call.arguments.clone()).await
338}
339
340/// Best-effort extraction of a panic payload for error reporting.
341fn panic_message(payload: &(dyn std::any::Any + Send)) -> String {
342    if let Some(s) = payload.downcast_ref::<&str>() {
343        (*s).to_owned()
344    } else if let Some(s) = payload.downcast_ref::<String>() {
345        s.clone()
346    } else {
347        "<non-string payload>".to_owned()
348    }
349}
350
351#[cfg(test)]
352mod tests {
353    use super::*;
354    use serde_json::json;
355
356    struct Echo;
357
358    #[async_trait]
359    impl Tool for Echo {
360        fn name(&self) -> &str {
361            "echo"
362        }
363        fn description(&self) -> &str {
364            "Echoes its input."
365        }
366        fn parameters_schema(&self) -> Value {
367            json!({"type": "object", "properties": {"text": {"type": "string"}}})
368        }
369        async fn call(&self, args: Value) -> Result<Value> {
370            Ok(json!(args.get("text").cloned().unwrap_or(Value::Null)))
371        }
372    }
373
374    struct Fail;
375
376    #[async_trait]
377    impl Tool for Fail {
378        fn name(&self) -> &str {
379            "fail"
380        }
381        fn description(&self) -> &str {
382            "Always fails."
383        }
384        fn parameters_schema(&self) -> Value {
385            json!({"type": "object"})
386        }
387        async fn call(&self, _args: Value) -> Result<Value> {
388            Err(RustyError::Tool("boom".into()))
389        }
390    }
391
392    #[test]
393    fn registry_schemas_are_openai_shaped() {
394        let mut registry = ToolRegistry::new();
395        registry.register(Echo);
396        let schemas = registry.schemas();
397        assert_eq!(schemas.len(), 1);
398        assert_eq!(schemas[0]["type"], json!("function"));
399        assert_eq!(schemas[0]["function"]["name"], json!("echo"));
400        assert!(schemas[0]["function"]["parameters"]["properties"].is_object());
401    }
402
403    #[tokio::test]
404    async fn batch_preserves_order_and_isolates_failures() {
405        let mut registry = ToolRegistry::new();
406        registry.register(Echo);
407        registry.register(Fail);
408        let executor = ToolExecutor::new(registry);
409
410        let calls = vec![
411            ToolCall::new("c1", "echo", json!({"text": "hello"})),
412            ToolCall::new("c2", "fail", json!({})),
413            ToolCall::new("c3", "missing", json!({})),
414        ];
415        let results = executor.execute_batch(&calls).await;
416
417        assert_eq!(results.len(), 3);
418        assert_eq!(results[0].tool_call_id.as_deref(), Some("c1"));
419        assert_eq!(results[0].content.as_deref(), Some("hello"));
420        assert_eq!(results[1].tool_call_id.as_deref(), Some("c2"));
421        assert!(results[1].content.as_deref().unwrap().starts_with("ERROR:"));
422        assert_eq!(results[2].tool_call_id.as_deref(), Some("c3"));
423        assert!(results[2]
424            .content
425            .as_deref()
426            .unwrap()
427            .contains("unknown tool"));
428    }
429
430    struct Panic;
431
432    #[async_trait]
433    impl Tool for Panic {
434        fn name(&self) -> &str {
435            "panic"
436        }
437        fn description(&self) -> &str {
438            "Always panics."
439        }
440        fn parameters_schema(&self) -> Value {
441            json!({"type": "object"})
442        }
443        async fn call(&self, _args: Value) -> Result<Value> {
444            panic!("kaboom");
445        }
446    }
447
448    #[tokio::test]
449    async fn panicking_tool_is_contained_as_error_message() {
450        let mut registry = ToolRegistry::new();
451        registry.register(Echo);
452        registry.register(Panic);
453        let executor = ToolExecutor::new(registry);
454
455        let calls = vec![
456            ToolCall::new("c1", "panic", json!({})),
457            ToolCall::new("c2", "echo", json!({"text": "still alive"})),
458        ];
459        let results = executor.execute_batch(&calls).await;
460
461        // The panic joins the same ERROR: channel as ordinary failures, and
462        // the rest of the batch completes normally.
463        assert_eq!(results.len(), 2);
464        let msg = results[0].content.as_deref().unwrap();
465        assert!(msg.starts_with("ERROR:"), "got: {msg}");
466        assert!(msg.contains("panicked"), "got: {msg}");
467        assert!(msg.contains("kaboom"), "got: {msg}");
468        assert_eq!(results[1].content.as_deref(), Some("still alive"));
469    }
470}