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(
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
340fn 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 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}