/// Unified Tool trait for Lumina Framework
/// 
/// All tools must implement this trait. Tools are event-driven and
/// operate as microservices within the runtime.

use async_trait::async_trait;
use lumina_engine::Event;
use serde_json::Value;
use std::fmt::Debug;

/// Unified Tool trait
/// 
/// Tools are stateless, thread-safe, and deterministic.
/// They operate independently of agent logic.
#[async_trait]
pub trait Tool: Send + Sync + 'static + Debug {
    /// Get the tool's name (must be static/constant)
    fn name(&self) -> &'static str;
    
    /// Execute the tool with input and the triggering event
    /// 
    /// # Arguments
    /// * `input` - Tool input parameters as JSON Value
    /// * `event` - The Event that triggered this tool execution
    /// 
    /// # Returns
    /// * `Ok(Value)` - Tool execution result as JSON
    /// * `Err(String)` - Error message if execution fails
    async fn execute(&self, input: Value, event: &Event) -> Result<Value, String>;
    
    /// Get tool description (optional, for documentation)
    fn description(&self) -> &'static str {
        ""
    }
    
    /// Get tool schema (optional, for validation)
    fn schema(&self) -> Option<Value> {
        None
    }
}

/// Tool execution result
#[derive(Debug, Clone)]
pub struct ToolExecutionResult {
    pub tool_name: String,
    pub success: bool,
    pub output: Value,
    pub error: Option<String>,
    pub execution_time_ms: u64,
}

/// Tool error type (deprecated, use registry::ToolError instead)
#[deprecated(note = "Use registry::ToolError instead")]
pub type ToolError = String;

