use std::collections::HashMap;
use std::sync::Arc;
use async_trait::async_trait;
use futures::FutureExt;
use serde_json::{json, Value};
use crate::effects::{EffectAdmissionContext, EffectRequest};
use crate::error::{Result, RustyError};
use crate::llm::{ChatMessage, ToolCall};
use crate::middleware::{MiddlewareChain, ToolInvocation};
#[async_trait]
pub trait Tool: Send + Sync {
fn name(&self) -> &str;
fn description(&self) -> &str;
fn parameters_schema(&self) -> Value;
fn effect(&self) -> crate::record::Effect {
crate::record::Effect::NonIdempotent
}
fn effect_kind(&self) -> &str {
self.name()
}
fn idempotency_key(&self, _args: &Value) -> Option<String> {
None
}
fn effect_request(&self, call: &ToolCall) -> EffectRequest {
let input = json!({
"arguments": &call.arguments,
"tool_call_id": &call.id,
});
EffectRequest::new(
self.effect_kind(),
self.effect(),
&input,
self.idempotency_key(&call.arguments),
)
}
async fn call(&self, args: Value) -> Result<Value>;
}
#[derive(Default, Clone)]
pub struct ToolRegistry {
tools: HashMap<String, Arc<dyn Tool>>,
}
impl std::fmt::Debug for ToolRegistry {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("ToolRegistry")
.field("tools", &self.tools.keys().collect::<Vec<_>>())
.finish()
}
}
impl ToolRegistry {
pub fn new() -> Self {
Self::default()
}
pub fn register<T: Tool + 'static>(&mut self, tool: T) -> &mut Self {
self.tools.insert(tool.name().to_owned(), Arc::new(tool));
self
}
pub fn register_shared(&mut self, tool: Arc<dyn Tool>) -> &mut Self {
self.tools.insert(tool.name().to_owned(), tool);
self
}
pub fn get(&self, name: &str) -> Option<Arc<dyn Tool>> {
self.tools.get(name).cloned()
}
pub fn contains(&self, name: &str) -> bool {
self.tools.contains_key(name)
}
pub fn names(&self) -> impl Iterator<Item = &str> {
self.tools.keys().map(String::as_str)
}
pub fn len(&self) -> usize {
self.tools.len()
}
pub fn is_empty(&self) -> bool {
self.tools.is_empty()
}
pub fn schemas(&self) -> Vec<Value> {
self.tools
.values()
.map(|tool| {
json!({
"type": "function",
"function": {
"name": tool.name(),
"description": tool.description(),
"parameters": tool.parameters_schema(),
}
})
})
.collect()
}
}
#[derive(Debug, Clone, Default)]
pub struct ToolExecutor {
registry: ToolRegistry,
middleware: MiddlewareChain,
effect_admission: Option<EffectAdmissionContext>,
thread_id: String,
node: String,
}
impl ToolExecutor {
pub fn new(registry: ToolRegistry) -> Self {
Self {
registry,
..Self::default()
}
}
pub fn registry(&self) -> &ToolRegistry {
&self.registry
}
pub fn with_middleware(mut self, chain: MiddlewareChain) -> Self {
self.middleware = chain;
self
}
pub fn with_effect_admission(mut self, context: EffectAdmissionContext) -> Self {
self.effect_admission = Some(context);
self
}
pub fn with_call_context(
mut self,
thread_id: impl Into<String>,
node: impl Into<String>,
) -> Self {
self.thread_id = thread_id.into();
self.node = node.into();
self
}
pub fn middleware(&self) -> &MiddlewareChain {
&self.middleware
}
pub fn effect_admission(&self) -> Option<&EffectAdmissionContext> {
self.effect_admission.as_ref()
}
pub async fn execute_batch(&self, calls: &[ToolCall]) -> Vec<ChatMessage> {
let futures = calls.iter().map(|call| {
let registry = self.registry.clone();
let chain = self.middleware.clone();
let effect_admission = self.effect_admission.clone();
let thread_id = self.thread_id.clone();
let node = self.node.clone();
async move {
let result = std::panic::AssertUnwindSafe(async {
let value = if chain.is_empty() {
dispatch_tool(®istry, call, effect_admission.as_ref()).await?
} else {
let mut invocation = ToolInvocation::new(thread_id, node, call.clone());
chain
.run_tool(&mut invocation, |invocation| {
let registry = registry.clone();
let effect_admission = effect_admission.clone();
let call = invocation.call().clone();
async move {
dispatch_tool(®istry, &call, effect_admission.as_ref()).await
}
})
.await?
};
Ok::<String, RustyError>(match value {
Value::String(s) => s,
other => other.to_string(),
})
})
.catch_unwind()
.await;
match result {
Ok(Ok(content)) => ChatMessage::tool_result(&call.id, content),
Ok(Err(e)) => ChatMessage::tool_result(&call.id, format!("ERROR: {e}")),
Err(payload) => ChatMessage::tool_result(
&call.id,
format!(
"ERROR: tool `{}` panicked: {}",
call.name,
panic_message(&*payload)
),
),
}
}
});
futures::future::join_all(futures).await
}
}
async fn dispatch_tool(
registry: &ToolRegistry,
call: &ToolCall,
effect_admission: Option<&EffectAdmissionContext>,
) -> Result<Value> {
let tool = registry
.get(&call.name)
.ok_or_else(|| RustyError::Tool(format!("unknown tool `{}`", call.name)))?;
let _permit = effect_admission
.map(|context| context.admit(&tool.effect_request(call)))
.transpose()
.map_err(|violation| RustyError::Tool(format!("effect admission denied: {violation}")))?;
tool.call(call.arguments.clone()).await
}
fn panic_message(payload: &(dyn std::any::Any + Send)) -> String {
if let Some(s) = payload.downcast_ref::<&str>() {
(*s).to_owned()
} else if let Some(s) = payload.downcast_ref::<String>() {
s.clone()
} else {
"<non-string payload>".to_owned()
}
}
#[cfg(test)]
mod tests {
use super::*;
use serde_json::json;
struct Echo;
#[async_trait]
impl Tool for Echo {
fn name(&self) -> &str {
"echo"
}
fn description(&self) -> &str {
"Echoes its input."
}
fn parameters_schema(&self) -> Value {
json!({"type": "object", "properties": {"text": {"type": "string"}}})
}
async fn call(&self, args: Value) -> Result<Value> {
Ok(json!(args.get("text").cloned().unwrap_or(Value::Null)))
}
}
struct Fail;
#[async_trait]
impl Tool for Fail {
fn name(&self) -> &str {
"fail"
}
fn description(&self) -> &str {
"Always fails."
}
fn parameters_schema(&self) -> Value {
json!({"type": "object"})
}
async fn call(&self, _args: Value) -> Result<Value> {
Err(RustyError::Tool("boom".into()))
}
}
#[test]
fn registry_schemas_are_openai_shaped() {
let mut registry = ToolRegistry::new();
registry.register(Echo);
let schemas = registry.schemas();
assert_eq!(schemas.len(), 1);
assert_eq!(schemas[0]["type"], json!("function"));
assert_eq!(schemas[0]["function"]["name"], json!("echo"));
assert!(schemas[0]["function"]["parameters"]["properties"].is_object());
}
#[tokio::test]
async fn batch_preserves_order_and_isolates_failures() {
let mut registry = ToolRegistry::new();
registry.register(Echo);
registry.register(Fail);
let executor = ToolExecutor::new(registry);
let calls = vec![
ToolCall::new("c1", "echo", json!({"text": "hello"})),
ToolCall::new("c2", "fail", json!({})),
ToolCall::new("c3", "missing", json!({})),
];
let results = executor.execute_batch(&calls).await;
assert_eq!(results.len(), 3);
assert_eq!(results[0].tool_call_id.as_deref(), Some("c1"));
assert_eq!(results[0].content.as_deref(), Some("hello"));
assert_eq!(results[1].tool_call_id.as_deref(), Some("c2"));
assert!(results[1].content.as_deref().unwrap().starts_with("ERROR:"));
assert_eq!(results[2].tool_call_id.as_deref(), Some("c3"));
assert!(results[2]
.content
.as_deref()
.unwrap()
.contains("unknown tool"));
}
struct Panic;
#[async_trait]
impl Tool for Panic {
fn name(&self) -> &str {
"panic"
}
fn description(&self) -> &str {
"Always panics."
}
fn parameters_schema(&self) -> Value {
json!({"type": "object"})
}
async fn call(&self, _args: Value) -> Result<Value> {
panic!("kaboom");
}
}
#[tokio::test]
async fn panicking_tool_is_contained_as_error_message() {
let mut registry = ToolRegistry::new();
registry.register(Echo);
registry.register(Panic);
let executor = ToolExecutor::new(registry);
let calls = vec![
ToolCall::new("c1", "panic", json!({})),
ToolCall::new("c2", "echo", json!({"text": "still alive"})),
];
let results = executor.execute_batch(&calls).await;
assert_eq!(results.len(), 2);
let msg = results[0].content.as_deref().unwrap();
assert!(msg.starts_with("ERROR:"), "got: {msg}");
assert!(msg.contains("panicked"), "got: {msg}");
assert!(msg.contains("kaboom"), "got: {msg}");
assert_eq!(results[1].content.as_deref(), Some("still alive"));
}
}