forge-tool

use forge_tool;

pub mod approval;

pub mod definition;

pub mod error;

pub mod execution;

pub mod registry;

pub mod tiers;

pub mod prelude;

pub use crate::approval::{ApprovalHandler, AutoApprove, DenyAll, TierBasedApproval};

pub use crate::definition::ToolBuilder;

pub use crate::error::{ForgeToolError, ForgeToolResult};

pub use crate::execution::{execute_tool_call, FnToolExecutor, ToolExecutor};

pub use crate::registry::ToolRegistry;

pub use crate::tiers::{
        classify_tier, execution_context_for, requires_authorization, ExecutionContext,
        TierClassification,
    };

#[async_trait]
pub trait ApprovalHandler: Send + Sync {
    /// Checks whether a tool call should be approved, denied, or modified.
    ///
    /// # Arguments
    ///
    /// * `call` - The tool call to evaluate.
    /// * `tier` - The tool's tier classification, which may influence the decision.
    ///
    /// # Returns
    ///
    /// A [`ToolApproval`] indicating the decision:
    /// - [`ToolApproval::Approve`] -- proceed with execution as-is.
    /// - [`ToolApproval::Deny`] -- reject the call with a reason.
    /// - [`ToolApproval::Modify`] -- approve but with modified arguments.
    async fn check(&self, call: &ToolCall, tier: ToolTier) -> ToolApproval;
}

pub struct AutoApprove;

pub struct DenyAll {

}

pub fn new(reason: impl Into<String>) -> Self;

pub struct TierBasedApproval;

pub struct ToolBuilder {

}

pub fn new(name: impl Into<String>) -> Self;

pub fn description(mut self, description: impl Into<String>) -> Self;

pub fn tier(mut self, tier: ToolTier) -> Self;

pub fn parameters(mut self, schema: JsonSchema) -> Self;

pub fn executor(mut self, executor: Arc<dyn ToolExecutor>) -> Self;

pub fn handler<F>(self, handler: F) -> Self
    where
        F: Fn(
                &forge_core::tool::ToolCall,
            ) -> Result<forge_core::tool::ToolResult, crate::error::ForgeToolError>
            + Send
            + Sync
            + 'static,;

pub fn build(self) -> (ToolDefinition, Option<Arc<dyn ToolExecutor>>);

#[derive(Debug, Error)]
pub enum ForgeToolError {
    /// A tool was looked up by name but does not exist in the registry.
    ///
    /// # Remediation
    ///
    /// Register the tool with [`crate::registry::ToolRegistry::register`] before use.
    #[error("tool '{name}' not found in registry; register it with ToolRegistry::register() before invoking")]
    ToolNotFound {
        /// The tool name that was looked up.
        name: String,
    },

    /// A tool execution failed at runtime.
    ///
    /// This wraps errors produced by [`crate::execution::ToolExecutor`] implementations.
    #[error("tool '{name}' execution failed: {reason}")]
    ExecutionFailed {
        /// The tool that failed.
        name: String,
        /// What went wrong during execution.
        reason: String,
    },

    /// A tool invocation was denied by the approval handler.
    ///
    /// See ANVIL Spec SS8.6 -- the approval step is mandatory in the tool execution lifecycle.
    #[error("tool '{name}' invocation denied by approval handler: {reason}")]
    ApprovalDenied {
        /// The tool that was denied.
        name: String,
        /// Why the invocation was denied.
        reason: String,
    },

    /// Schema validation failed for tool arguments.
    ///
    /// The arguments provided to a tool call did not conform to the tool's
    /// declared parameter schema.
    #[error("schema validation failed for tool '{name}' at path '{path}': {reason}")]
    SchemaValidation {
        /// The tool whose schema was violated.
        name: String,
        /// JSON pointer path to the failing field.
        path: String,
        /// Human-readable description of what was expected.
        reason: String,
    },

    /// A tool was registered or invoked with an incorrect tier classification.
    ///
    /// See ANVIL Spec SS8.1--8.4 -- tool tier classification is immutable.
    #[error(
        "tool '{name}' has invalid tier: expected {expected}, got {actual} (see ANVIL Spec SS8.1)"
    )]
    InvalidTier {
        /// The tool whose tier is mismatched.
        name: String,
        /// The expected tier classification.
        expected: String,
        /// The actual tier classification provided.
        actual: String,
    },

    /// A registry operation failed (e.g., duplicate registration, capacity exceeded).
    #[error("tool registry error: {reason}")]
    RegistryError {
        /// What went wrong with the registry operation.
        reason: String,
    },
}

pub type ForgeToolResult<T> = Result<T, ForgeToolError>;

#[async_trait]
pub trait ToolExecutor: Send + Sync {
    /// Executes the tool with the given call arguments.
    ///
    /// # Arguments
    ///
    /// * `call` - The tool call containing the call ID, tool name, and JSON arguments.
    ///
    /// # Returns
    ///
    /// A [`ToolResult`] with the execution output on success, or a
    /// [`ForgeToolError::ExecutionFailed`] on failure.
    ///
    /// # Errors
    ///
    /// Returns [`ForgeToolError::ExecutionFailed`] if the tool logic fails for
    /// any reason (network timeout, invalid state, computation error, etc.).
    async fn execute(&self, call: &ToolCall) -> Result<ToolResult, ForgeToolError>;

    /// Returns the name of the tool this executor handles.
    ///
    /// This must match the [`ToolDefinition::name`](forge_core::tool::ToolDefinition::name)
    /// of the corresponding tool definition.
    fn name(&self) -> &str;
}

pub struct FnToolExecutor<F>
where
    F: Fn(&ToolCall) -> Result<ToolResult, ForgeToolError> + Send + Sync + 'static, {

}

pub fn new(name: impl Into<String>, handler: F) -> Self;

pub async fn execute_tool_call(
    call: &ToolCall,
    definition: &forge_core::tool::ToolDefinition,
    executor: &dyn ToolExecutor,
    approval_handler: &dyn crate::approval::ApprovalHandler,
) -> Result<ToolResult, ForgeToolError>;

pub mod approval;

pub mod definition;

pub mod error;

pub mod execution;

pub mod registry;

pub mod tiers;

pub mod prelude;

pub use crate::approval::{ApprovalHandler, AutoApprove, DenyAll, TierBasedApproval};

pub use crate::definition::ToolBuilder;

pub use crate::error::{ForgeToolError, ForgeToolResult};

pub use crate::execution::{execute_tool_call, FnToolExecutor, ToolExecutor};

pub use crate::registry::ToolRegistry;

pub use crate::tiers::{
        classify_tier, execution_context_for, requires_authorization, ExecutionContext,
        TierClassification,
    };

#[derive(Clone)]
pub struct ToolRegistry {

}

pub fn new() -> Self;

pub fn register(
        &mut self,
        definition: ToolDefinition,
        executor: Arc<dyn ToolExecutor>,
    ) -> Result<(), ForgeToolError>;

pub fn get(&self, name: &str) -> Option<(&ToolDefinition, &Arc<dyn ToolExecutor>)>;

pub fn list(&self) -> Vec<&ToolDefinition>;

pub fn definitions(&self) -> Vec<ToolDefinition>;

pub fn len(&self) -> usize;

pub fn is_empty(&self) -> bool;

pub fn remove(&mut self, name: &str) -> Option<(ToolDefinition, Arc<dyn ToolExecutor>)>;

pub fn contains(&self, name: &str) -> bool;

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub enum ExecutionContext {
    /// The tool executes inside the WASM sandbox.
    ///
    /// Applies to Platform (Tier 1) and Embedded (Tier 3) tools. These tools
    /// cannot access external resources without going through host functions.
    InSandbox,

    /// The tool executes outside the WASM sandbox via host functions.
    ///
    /// Applies to Host (Tier 2) tools. These tools have access to external
    /// resources and MUST be authorized via Arsenal ACTs.
    OutOfSandbox,
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub struct TierClassification {
/// The name of the tool that was classified.

pub tool_name: String,
/// The tool's tier classification.

pub tier: ToolTier,
/// Whether this tool requires Arsenal ACT authorization before execution.

///

/// Only `true` for Host (Tier 2) tools.

pub requires_authorization: bool,
/// The execution context (sandbox or host) for this tool.

pub execution_context: ExecutionContext
}

pub fn classify_tier(tool_name: &str, tier: ToolTier) -> TierClassification;

pub fn requires_authorization(tier: ToolTier) -> bool;

pub fn execution_context_for(tier: ToolTier) -> ExecutionContext;