marona 4.2.0

Agent SDK with extensible communication protocols, B2A, structured responses, MCP tools and A2A
Documentation
use std::{future::Future, sync::Arc};

use async_trait::async_trait;
use serde::{Deserialize, Serialize};
use serde_json::{json, Value};

use crate::{Error, Result};

#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct ToolContext {
    pub user_id: Option<String>,
    pub session_id: String,
    pub developer_id: Option<String>,
    #[serde(default)]
    pub permissions: Vec<String>,
    #[serde(default)]
    pub approved_tools: Vec<String>,
    #[serde(default)]
    pub metadata: serde_json::Map<String, Value>,
}

#[async_trait]
pub trait ToolExecutor: Send + Sync {
    async fn execute(&self, arguments: Value, context: ToolContext) -> Result<Value>;
}

struct ClosureExecutor<F>(F);

#[async_trait]
impl<F, Fut> ToolExecutor for ClosureExecutor<F>
where
    F: Fn(Value, ToolContext) -> Fut + Send + Sync,
    Fut: Future<Output = Result<Value>> + Send,
{
    async fn execute(&self, arguments: Value, context: ToolContext) -> Result<Value> {
        (self.0)(arguments, context).await
    }
}

#[derive(Clone)]
pub struct FunctionTool {
    pub name: String,
    pub description: String,
    pub input_schema: Value,
    pub output_schema: Option<Value>,
    pub timeout_ms: u64,
    pub permissions: Vec<String>,
    pub requires_approval: bool,
    executor: Arc<dyn ToolExecutor>,
}

impl std::fmt::Debug for FunctionTool {
    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        formatter
            .debug_struct("FunctionTool")
            .field("name", &self.name)
            .field("description", &self.description)
            .field("input_schema", &self.input_schema)
            .field("output_schema", &self.output_schema)
            .field("timeout_ms", &self.timeout_ms)
            .field("permissions", &self.permissions)
            .field("requires_approval", &self.requires_approval)
            .finish_non_exhaustive()
    }
}

impl FunctionTool {
    pub fn new<F, Fut>(
        name: impl Into<String>,
        description: impl Into<String>,
        input_schema: Value,
        execute: F,
    ) -> Self
    where
        F: Fn(Value, ToolContext) -> Fut + Send + Sync + 'static,
        Fut: Future<Output = Result<Value>> + Send + 'static,
    {
        Self {
            name: name.into(),
            description: description.into(),
            input_schema,
            output_schema: None,
            timeout_ms: 30_000,
            permissions: vec![],
            requires_approval: false,
            executor: Arc::new(ClosureExecutor(execute)),
        }
    }

    pub fn output_schema(mut self, value: Value) -> Self {
        self.output_schema = Some(value);
        self
    }
    pub fn timeout_ms(mut self, value: u64) -> Self {
        self.timeout_ms = value;
        self
    }
    pub fn permissions(mut self, values: impl IntoIterator<Item = impl Into<String>>) -> Self {
        self.permissions = values.into_iter().map(Into::into).collect();
        self
    }
    pub fn requires_approval(mut self, value: bool) -> Self {
        self.requires_approval = value;
        self
    }

    pub fn definition(&self) -> Value {
        json!({
            "name": self.name, "description": self.description,
            "input_schema": self.input_schema, "output_schema": self.output_schema,
            "timeout_ms": self.timeout_ms, "permissions": self.permissions,
            "requires_approval": self.requires_approval,
        })
    }

    pub async fn invoke(&self, arguments: Value, context: ToolContext) -> Result<Value> {
        crate::schema::validate(&arguments, &self.input_schema, "Function input")?;
        for permission in &self.permissions {
            if !context.permissions.iter().any(|value| value == permission) {
                return Err(Error::PermissionRequired(permission.clone()));
            }
        }
        if self.requires_approval
            && !context
                .approved_tools
                .iter()
                .any(|value| value == &self.name)
        {
            return Err(Error::ApprovalRequired(self.name.clone()));
        }
        let output = tokio::time::timeout(
            std::time::Duration::from_millis(self.timeout_ms),
            self.executor.execute(arguments, context),
        )
        .await
        .map_err(|_| Error::Timeout(self.timeout_ms))??;
        if let Some(schema) = &self.output_schema {
            crate::schema::validate(&output, schema, "Function output")?;
        }
        Ok(output)
    }
}

pub fn function_tool<F, Fut>(
    name: impl Into<String>,
    description: impl Into<String>,
    input_schema: Value,
    execute: F,
) -> FunctionTool
where
    F: Fn(Value, ToolContext) -> Fut + Send + Sync + 'static,
    Fut: Future<Output = Result<Value>> + Send + 'static,
{
    FunctionTool::new(name, description, input_schema, execute)
}