1use 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#[async_trait]
28pub trait Tool: Send + Sync {
29 fn name(&self) -> &str;
31
32 fn description(&self) -> &str;
34
35 fn parameters_schema(&self) -> Value;
37
38 fn effect(&self) -> crate::record::Effect {
48 crate::record::Effect::NonIdempotent
49 }
50
51 fn effect_kind(&self) -> &str {
54 self.name()
55 }
56
57 fn idempotency_key(&self, _args: &Value) -> Option<String> {
61 None
62 }
63
64 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 async fn call(&self, args: Value) -> Result<Value>;
86}
87
88#[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 pub fn new() -> Self {
105 Self::default()
106 }
107
108 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 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 pub fn get(&self, name: &str) -> Option<Arc<dyn Tool>> {
122 self.tools.get(name).cloned()
123 }
124
125 pub fn contains(&self, name: &str) -> bool {
127 self.tools.contains_key(name)
128 }
129
130 pub fn names(&self) -> impl Iterator<Item = &str> {
132 self.tools.keys().map(String::as_str)
133 }
134
135 pub fn len(&self) -> usize {
137 self.tools.len()
138 }
139
140 pub fn is_empty(&self) -> bool {
142 self.tools.is_empty()
143 }
144
145 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#[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 pub fn new(registry: ToolRegistry) -> Self {
189 Self {
190 registry,
191 ..Self::default()
192 }
193 }
194
195 pub fn registry(&self) -> &ToolRegistry {
197 &self.registry
198 }
199
200 pub fn with_middleware(mut self, chain: MiddlewareChain) -> Self {
204 self.middleware = chain;
205 self
206 }
207
208 pub fn with_effect_admission(mut self, context: EffectAdmissionContext) -> Self {
211 self.effect_admission = Some(context);
212 self
213 }
214
215 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 pub fn middleware(&self) -> &MiddlewareChain {
229 &self.middleware
230 }
231
232 pub fn effect_admission(&self) -> Option<&EffectAdmissionContext> {
234 self.effect_admission.as_ref()
235 }
236
237 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(®istry, 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 dispatch_tool(®istry, &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 panic_message(&*payload)
293 ),
294 ),
295 }
296 }
297 });
298 futures::future::join_all(futures).await
299 }
300}
301
302async 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
321fn 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 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}