tokitai_core/

lib.rs

//! # Tokitai Core
//!
//! Core types and traits for the Tokitai AI tool integration library. All
//! tool information is generated at compile time, so the core has zero
//! runtime dependencies and is `no_std`-compatible (with the `serde`
//! feature disabled).
//!
//! See [`ToolDefinition`], [`ToolProvider`], and the [`tokitai`](https://crates.io/crates/tokitai)
//! crate for the high-level overview.
//!
//! # Example
//!
//! ```rust
//! use tokitai_core::{ToolDefinition, ParamType};
//!
//! let tool = ToolDefinition::new(
//!     "add",
//!     "Add two numbers together",
//!     r#"{"type":"object","properties":{"a":{"type":"integer"},"b":{"type":"integer"}},"required":["a","b"]}"#
//! );
//! assert_eq!(tool.name, "add");
//!
//! assert_eq!(ParamType::from_rust_type("i32"), Some(ParamType::Integer));
//! assert_eq!(ParamType::from_rust_type("Vec<i32>"), Some(ParamType::Array));
//! ```
//!
//! # Features
//!
//! | Feature | Description |
//! |---------|-------------|
//! | `serde` (default) | Enable `serde`/`serde_json` integration |
//!
//! For `no_std` usage, depend on the crate with `default-features = false`.
//!
//! # License
//!
//! Dual-licensed under either of:
//!
//! - Apache License, Version 2.0
//! - MIT License
//!
//! at your option.

#![cfg_attr(not(feature = "serde"), no_std)]
#![deny(missing_docs)]
#![allow(dead_code)]

#[cfg(feature = "serde")]
extern crate serde;

#[cfg(feature = "serde")]
extern crate alloc;

#[cfg(feature = "serde")]
pub use serde_types::*;

#[cfg(feature = "serde")]
pub use config::{ToolConfig, ToolConfigRegistry, GLOBAL_CONFIG_REGISTRY};

// T-010: runtime-mutable tool registry. The trait is independent of
// `ToolProvider` so macro-generated providers stay free of runtime
// state. See [`dynamic::DynamicToolProvider`] and
// [`dynamic::DynamicToolRegistry`].
#[cfg(feature = "serde")]
pub mod dynamic;
#[cfg(feature = "serde")]
pub use dynamic::{
    is_tenant_denied, DynamicHandler, DynamicToolProvider, DynamicToolRegistry,
    TENANT_DENIED_KIND_HINT,
};

/// A tool that an AI system can invoke.
///
/// Normally generated by the `#[tool]` macro; rarely created by hand.
///
/// # Example
///
/// ```rust
/// use tokitai_core::ToolDefinition;
///
/// let tool = ToolDefinition::new("add", "Add two numbers", r#"{"type":"object"}"#);
/// assert_eq!(tool.name, "add");
/// ```
#[derive(Debug, Clone)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct ToolDefinition {
    /// Tool name used for identification during AI calls
    #[cfg(feature = "serde")]
    pub name: alloc::string::String,
    #[cfg(not(feature = "serde"))]
    pub name: &'static str,
    /// Tool description helping AI understand its purpose
    #[cfg(feature = "serde")]
    pub description: alloc::string::String,
    #[cfg(not(feature = "serde"))]
    pub description: &'static str,
    /// Input parameter JSON Schema (compile-time generated string)
    #[cfg(feature = "serde")]
    pub input_schema: alloc::string::String,
    #[cfg(not(feature = "serde"))]
    pub input_schema: &'static str,
    /// Tool version (optional)
    #[cfg_attr(feature = "serde", serde(skip_serializing_if = "Option::is_none"))]
    #[cfg(feature = "serde")]
    pub version: Option<alloc::string::String>,
    #[cfg(not(feature = "serde"))]
    pub version: Option<&'static str>,
    /// Version since when the tool is deprecated (optional)
    #[cfg_attr(feature = "serde", serde(skip_serializing_if = "Option::is_none"))]
    #[cfg(feature = "serde")]
    pub deprecated_since: Option<alloc::string::String>,
    #[cfg(not(feature = "serde"))]
    pub deprecated_since: Option<&'static str>,
    /// Version when the tool will be removed (optional)
    #[cfg_attr(feature = "serde", serde(skip_serializing_if = "Option::is_none"))]
    #[cfg(feature = "serde")]
    pub remove_in: Option<alloc::string::String>,
    #[cfg(not(feature = "serde"))]
    pub remove_in: Option<&'static str>,
    /// Tool that replaces this deprecated tool (optional)
    #[cfg_attr(feature = "serde", serde(skip_serializing_if = "Option::is_none"))]
    #[cfg(feature = "serde")]
    pub replaced_by: Option<alloc::string::String>,
    #[cfg(not(feature = "serde"))]
    pub replaced_by: Option<&'static str>,
    /// True when the description was supplied explicitly via
    /// `#[tool(desc = "...")]` at compile time. The runtime
    /// configuration system (`tokitai!`) will NOT override an
    /// explicit description — see [`crate::config::CONFIG_PRIORITY_ORDER`].
    #[cfg(feature = "serde")]
    pub description_explicit: bool,
    #[cfg(not(feature = "serde"))]
    pub description_explicit: bool,
    /// T-016: baked few-shot examples. Each entry is a JSON object
    /// of the shape `{ "input": ..., "output": ... }` (one entry
    /// per `#[tool(example = call!(...))]` /
    /// `#[tool(examples = [call!(...), ...])]` element on the
    /// method). When non-empty, the rendered
    /// `input_schema`/`to_openai_function()` /
    /// `to_anthropic_tool()` / `to_mcp_tool()` output carries an
    /// `examples` array carrying these entries so the LLM sees a
    /// typed, signature-synced example it cannot drift away from.
    ///
    /// The field is populated at `LazyLock` initialization by the
    /// `#[tool]` macro; downstream consumers do not need to set it
    /// directly.
    #[cfg_attr(feature = "serde", serde(skip_serializing_if = "Option::is_none"))]
    #[cfg(feature = "serde")]
    pub baked_examples: Option<serde_json::Value>,
    #[cfg(not(feature = "serde"))]
    pub baked_examples: Option<&'static str>,
    /// T-046: optional free-form usage hint shown to the model alongside
    /// the description. Useful for nudging specific invocation patterns
    /// (e.g. "Always pass `limit` <= 100"). See the
    /// `tokitai-llm` `ToolHintPlacement` enum for delivery options.
    #[cfg_attr(feature = "serde", serde(skip_serializing_if = "Option::is_none"))]
    #[cfg(feature = "serde")]
    pub usage_hint: Option<alloc::string::String>,
    #[cfg(not(feature = "serde"))]
    pub usage_hint: Option<&'static str>,
    /// T-020: lower bound of the tool's schema-evolution interval
    /// (inclusive). Set from `#[tool(since = "1.0")]` on the
    /// method. The dispatcher serves the tool only when
    /// `current_version()` falls inside the `[since, until)`
    /// half-open interval; methods without `since` / `until`
    /// attributes are always served. The strings are compared
    /// using the parse helper when possible, falling back
    /// to lexicographic order otherwise.
    #[cfg_attr(feature = "serde", serde(skip_serializing_if = "Option::is_none"))]
    #[cfg(feature = "serde")]
    pub since: Option<alloc::string::String>,
    #[cfg(not(feature = "serde"))]
    pub since: Option<&'static str>,
    /// T-020: upper bound of the tool's schema-evolution interval
    /// (exclusive). Set from `#[tool(until = "2.0")]` on the
    /// method. The dispatcher hides the tool when
    /// `current_version() >= until` (same ordering rules as
    /// the `since` field above).
    #[cfg_attr(feature = "serde", serde(skip_serializing_if = "Option::is_none"))]
    #[cfg(feature = "serde")]
    pub until: Option<alloc::string::String>,
    #[cfg(not(feature = "serde"))]
    pub until: Option<&'static str>,
}

/// Single source of truth for the priority order of configuration
/// sources that can supply a tool's description.
///
/// The table is also the spec for `tokitai_core::config::CONFIG_PRIORITY_ORDER`
/// (see that module for the full, const-fn version). Keeping the two
/// declarations in lockstep is enforced by a doc test:
/// `cargo test -p tokitai-core CONFIG_PRIORITY_ORDER`.
///
/// Index 0 is the highest-priority source (wins on conflict); the last
/// index is the lowest (used only as a fallback).
pub const CONFIG_PRIORITY_DOC: &[&str] = &[
    "#[tool(desc = \"...\")]  (compile-time, attribute-supplied)",
    "doc comment  (compile-time, /// lines above the method)",
    "tokitai! config block  (runtime, applies via GLOBAL_CONFIG_REGISTRY)",
    "synthesized default  (compile-time, \"调用 <method> 方法\")",
];

/// Compile-time storage for tool definition data, used by the
/// `#[tool]` macro and converted to a `ToolDefinition` at zero cost
/// via [`ToolDefinition::from_const`].
#[doc(hidden)]
pub struct ToolDefinitionConst {
    pub name: &'static str,
    pub description: &'static str,
    pub input_schema: &'static str,
}

impl ToolDefinition {
    /// Build a tool definition from compile-time constants. Optimized for the
    /// `#[tool]` macro: no allocation, just `'static` -> owned-string copies.
    ///
    /// # Example
    ///
    /// ```rust
    /// use tokitai_core::{ToolDefinition, ToolDefinitionConst};
    ///
    /// const TOOL_DATA: ToolDefinitionConst = ToolDefinitionConst {
    ///     name: "get_weather",
    ///     description: "Get weather information for a specified city",
    ///     input_schema: r#"{"type":"object"}"#,
    /// };
    ///
    /// let tool = ToolDefinition::from_const(TOOL_DATA);
    /// ```
    #[inline(always)]
    pub fn from_const(data: ToolDefinitionConst) -> Self {
        Self {
            #[cfg(feature = "serde")]
            name: data.name.into(),
            #[cfg(not(feature = "serde"))]
            name: data.name,
            #[cfg(feature = "serde")]
            description: data.description.into(),
            #[cfg(not(feature = "serde"))]
            description: data.description,
            #[cfg(feature = "serde")]
            input_schema: data.input_schema.into(),
            #[cfg(not(feature = "serde"))]
            input_schema: data.input_schema,
            version: None,
            deprecated_since: None,
            remove_in: None,
            replaced_by: None,
            description_explicit: false,
            baked_examples: None,
            usage_hint: None,
            since: None,
            until: None,
        }
    }

    /// Create a new tool definition at runtime. Each argument can be any
    /// type that implements `Into<String>`.
    ///
    /// # Example
    ///
    /// ```rust
    /// use tokitai_core::ToolDefinition;
    ///
    /// let tool = ToolDefinition::new(
    ///     "get_weather",
    ///     "Get weather information for a specified city",
    ///     r#"{"type":"object","properties":{"city":{"type":"string"}},"required":["city"]}"#
    /// );
    /// ```
    #[cfg(feature = "serde")]
    pub fn new(
        name: impl Into<alloc::string::String>,
        description: impl Into<alloc::string::String>,
        input_schema: impl Into<alloc::string::String>,
    ) -> Self {
        Self {
            name: name.into(),
            description: description.into(),
            input_schema: input_schema.into(),
            version: None,
            deprecated_since: None,
            remove_in: None,
            replaced_by: None,
            description_explicit: false,
            baked_examples: None,
            usage_hint: None,
            since: None,
            until: None,
        }
    }

    /// `no_std` constructor: all three strings must be `'static`.
    ///
    /// # Example
    ///
    /// ```rust
    /// use tokitai_core::ToolDefinition;
    ///
    /// let tool = ToolDefinition::new("add", "Add two numbers", r#"{"type":"object"}"#);
    /// assert_eq!(tool.name, "add");
    /// ```
    #[cfg(not(feature = "serde"))]
    pub fn new(name: &'static str, description: &'static str, input_schema: &'static str) -> Self {
        Self {
            name,
            description,
            input_schema,
            version: None,
            deprecated_since: None,
            remove_in: None,
            replaced_by: None,
            description_explicit: false,
            baked_examples: None,
            usage_hint: None,
            since: None,
            until: None,
        }
    }

    /// Mark the tool's description as having been supplied explicitly via
    /// `#[tool(desc = "...")]` at compile time.
    ///
    /// This makes the description "freeze": subsequent calls to
    /// [`ToolDefinition::apply_configs`] with a `ToolConfig::Desc` will be
    /// ignored. The flag is set by the `#[tool]` macro when the user
    /// supplies `desc = "..."` on the method attribute, and powers the
    /// priority table exposed by
    /// [`crate::config::CONFIG_PRIORITY_ORDER`].
    ///
    /// # Example
    ///
    /// ```rust
    /// use tokitai_core::ToolDefinition;
    ///
    /// let tool = ToolDefinition::new("add", "Add two numbers", "{}")
    ///     .with_description_explicit();
    /// assert!(tool.description_explicit);
    /// ```
    #[must_use]
    pub fn with_description_explicit(mut self) -> Self {
        self.description_explicit = true;
        self
    }

    /// T-046: attach a usage hint that the provider layer can
    /// auto-inject into the system prompt or as a separate message.
    /// See the `tokitai-llm` `ToolHintPlacement` enum for delivery options.
    ///
    /// # Example
    ///
    /// ```rust
    /// use tokitai_core::ToolDefinition;
    ///
    /// let tool = ToolDefinition::new("add", "Add two numbers", r#"{"type":"object"}"#)
    ///     .with_usage_hint("Always pass both `a` and `b` as i64.");
    /// ```
    #[cfg(feature = "serde")]
    pub fn with_usage_hint(mut self, hint: impl Into<alloc::string::String>) -> Self {
        self.usage_hint = Some(hint.into());
        self
    }

    /// T-046: `no_std` variant.
    #[cfg(not(feature = "serde"))]
    pub fn with_usage_hint(mut self, hint: &'static str) -> Self {
        self.usage_hint = Some(hint);
        self
    }

    /// T-016: attach a `serde_json::Value` carrying the
    /// `examples` array (one `{ "input": ..., "output": ... }`
    /// entry per baked example). The macro emits a call to this
    /// method only when the user wrote
    /// `#[tool(example = call!(...))]` (or the plural form) on a
    /// method, so existing tools are unchanged. When the value
    /// is `None` or an empty array, the schema's `examples` field
    /// is omitted entirely.
    #[cfg(feature = "serde")]
    #[must_use]
    pub fn with_baked_examples(mut self, examples: serde_json::Value) -> Self {
        if let serde_json::Value::Array(ref arr) = examples {
            if arr.is_empty() {
                self.baked_examples = None;
                return self;
            }
        }
        self.baked_examples = Some(examples);
        self
    }

    /// T-016: `no_std` variant of [`with_baked_examples`]. Takes
    /// a `'static str` JSON literal; callers in `no_std`
    /// environments do not have access to `serde_json`, so they
    /// must pre-render the examples array. Today the macro
    /// always renders through the `serde`-feature path, so this
    /// stub is unreachable in practice; it exists so the type
    /// stays `cfg`-complete.
    #[cfg(not(feature = "serde"))]
    #[must_use]
    pub fn with_baked_examples(mut self, _examples: &'static str) -> Self {
        // No-op in `no_std`: the macro always uses the
        // serde-feature variant. This stub keeps the public API
        // symmetric across feature flags.
        self
    }

    /// Set the tool version.
    ///
    /// # Example
    ///
    /// ```rust
    /// use tokitai_core::ToolDefinition;
    ///
    /// let tool = ToolDefinition::new("add", "Add two numbers", r#"{"type":"object"}"#)
    ///     .with_version("1.2.0");
    /// assert_eq!(tool.version.as_deref(), Some("1.2.0"));
    /// ```
    #[cfg(feature = "serde")]
    pub fn with_version(mut self, version: impl Into<alloc::string::String>) -> Self {
        self.version = Some(version.into());
        self
    }

    /// `no_std` version setter: `version` must be `'static`.
    ///
    /// # Example
    ///
    /// ```rust
    /// use tokitai_core::ToolDefinition;
    ///
    /// let tool = ToolDefinition::new("add", "Add two numbers", r#"{"type":"object"}"#)
    ///     .with_version("1.2.0");
    /// assert_eq!(tool.version, Some("1.2.0"));
    /// ```
    #[cfg(not(feature = "serde"))]
    pub fn with_version(mut self, version: &'static str) -> Self {
        self.version = Some(version);
        self
    }

    /// T-020: set the lower bound of the schema-evolution interval.
    /// The dispatcher serves the tool only when `current_version()`
    /// is at or after `since` (and before `until`, if set).
    ///
    /// # Example
    ///
    /// ```rust
    /// use tokitai_core::ToolDefinition;
    ///
    /// let tool = ToolDefinition::new("add", "Add two numbers", "{}")
    ///     .with_since("1.0.0");
    /// assert_eq!(tool.since.as_deref(), Some("1.0.0"));
    /// ```
    #[cfg(feature = "serde")]
    #[must_use]
    pub fn with_since(mut self, since: impl Into<alloc::string::String>) -> Self {
        self.since = Some(since.into());
        self
    }

    /// `no_std` `since` setter: `since` must be `'static`.
    #[cfg(not(feature = "serde"))]
    #[must_use]
    pub fn with_since(mut self, since: &'static str) -> Self {
        self.since = Some(since);
        self
    }

    /// T-020: set the upper bound (exclusive) of the
    /// schema-evolution interval. When `current_version() >=
    /// until`, the dispatcher hides the tool.
    ///
    /// # Example
    ///
    /// ```rust
    /// use tokitai_core::ToolDefinition;
    ///
    /// let tool = ToolDefinition::new("legacy", "Old API", "{}")
    ///     .with_since("1.0.0")
    ///     .with_until("2.0.0");
    /// assert_eq!(tool.until.as_deref(), Some("2.0.0"));
    /// ```
    #[cfg(feature = "serde")]
    #[must_use]
    pub fn with_until(mut self, until: impl Into<alloc::string::String>) -> Self {
        self.until = Some(until.into());
        self
    }

    /// `no_std` `until` setter: `until` must be `'static`.
    #[cfg(not(feature = "serde"))]
    #[must_use]
    pub fn with_until(mut self, until: &'static str) -> Self {
        self.until = Some(until);
        self
    }

    /// T-020: returns `true` when `current_version` falls inside
    /// the tool's `[since, until)` half-open interval.
    ///
    /// Returns `true` when:
    /// * `since` is `None` and `until` is `None` (unversioned tool,
    ///   always served — backwards-compatible default).
    /// * `current_version` is `None` (no program-wide version
    ///   configured; the dispatcher falls open to honour the
    ///   legacy `tool_definitions()` contract).
    /// * `current_version >= since` AND `current_version < until`,
    ///   compared via `parse_semver` (the private helper used by
    ///   `remove_in`/`since`/`until`) when possible and
    ///   lexicographically otherwise (so CalVer / commit-SHA
    ///   strings still produce a deterministic dispatch).
    ///
    /// Returns `false` when one bound is set and `current_version`
    /// falls outside the half-open window.
    ///
    /// # Example
    ///
    /// ```rust
    /// use tokitai_core::ToolDefinition;
    ///
    /// let tool = ToolDefinition::new("legacy", "Old API", "{}")
    ///     .with_since("1.0.0")
    ///     .with_until("2.0.0");
    /// assert!(tool.is_in_interval(Some("1.5.0")));
    /// assert!(!tool.is_in_interval(Some("2.0.0")));
    /// assert!(!tool.is_in_interval(Some("0.9.0")));
    /// assert!(tool.is_in_interval(None));
    /// ```
    pub fn is_in_interval(&self, current_version: Option<&str>) -> bool {
        // Both bounds unset => always served.
        if self.since.is_none() && self.until.is_none() {
            return true;
        }
        // No program-wide version => fail open so existing
        // tool_definitions() callers keep working unchanged.
        let Some(current) = current_version else {
            return true;
        };
        // Lower bound: current >= since (when since is set).
        if let Some(since) = self.since.as_deref() {
            if !version_gte(current, since) {
                return false;
            }
        }
        // Upper bound: current < until (when until is set).
        if let Some(until) = self.until.as_deref() {
            if version_gte(current, until) {
                return false;
            }
        }
        true
    }

    /// Mark the tool as deprecated.
    ///
    /// # Example
    ///
    /// ```rust
    /// use tokitai_core::ToolDefinition;
    ///
    /// let tool = ToolDefinition::new("multiply", "Multiply two numbers", r#"{"type":"object"}"#)
    ///     .with_deprecated("0.5.0", "0.7.0", "add_repeated");
    /// assert_eq!(tool.deprecated_since.as_deref(), Some("0.5.0"));
    /// assert_eq!(tool.remove_in.as_deref(), Some("0.7.0"));
    /// assert_eq!(tool.replaced_by.as_deref(), Some("add_repeated"));
    /// ```
    #[cfg(feature = "serde")]
    pub fn with_deprecated(
        mut self,
        deprecated_since: impl Into<alloc::string::String>,
        remove_in: impl Into<alloc::string::String>,
        replaced_by: impl Into<alloc::string::String>,
    ) -> Self {
        self.deprecated_since = Some(deprecated_since.into());
        self.remove_in = Some(remove_in.into());
        self.replaced_by = Some(replaced_by.into());
        self
    }

    /// `no_std` deprecation setter: all three strings must be `'static`.
    ///
    /// # Example
    ///
    /// ```rust
    /// use tokitai_core::ToolDefinition;
    ///
    /// let tool = ToolDefinition::new("multiply", "Multiply two numbers", r#"{"type":"object"}"#)
    ///     .with_deprecated("0.5.0", "0.7.0", "add_repeated");
    /// assert_eq!(tool.deprecated_since, Some("0.5.0"));
    /// assert_eq!(tool.remove_in, Some("0.7.0"));
    /// assert_eq!(tool.replaced_by, Some("add_repeated"));
    /// ```
    #[cfg(not(feature = "serde"))]
    pub fn with_deprecated(
        mut self,
        deprecated_since: &'static str,
        remove_in: &'static str,
        replaced_by: &'static str,
    ) -> Self {
        self.deprecated_since = Some(deprecated_since);
        self.remove_in = Some(remove_in);
        self.replaced_by = Some(replaced_by);
        self
    }

    /// Serialize this tool definition to a JSON string.
    ///
    /// # Example
    ///
    /// ```rust
    /// use tokitai_core::ToolDefinition;
    ///
    /// let tool = ToolDefinition::new("add", "Add two numbers", r#"{"type":"object"}"#);
    /// let json = tool.to_json().unwrap();
    /// assert!(json.contains(r#""name":"add""#));
    /// ```
    ///
    /// # Errors
    ///
    /// Returns a `serde_json::Error` if serialization fails.
    #[cfg(feature = "serde")]
    pub fn to_json(&self) -> Result<String, serde_json::Error> {
        serde_json::to_string(self)
    }

    /// Serialize this tool definition to a `serde_json::Value`.
    ///
    /// # Example
    ///
    /// ```rust
    /// use tokitai_core::ToolDefinition;
    /// use serde_json::json;
    ///
    /// let tool = ToolDefinition::new("add", "Add two numbers", r#"{"type":"object"}"#);
    /// let value = tool.to_value().unwrap();
    /// assert_eq!(value["name"], json!("add"));
    /// ```
    ///
    /// # Errors
    ///
    /// Returns a `serde_json::Error` if serialization fails.
    #[cfg(feature = "serde")]
    pub fn to_value(&self) -> Result<serde_json::Value, serde_json::Error> {
        serde_json::to_value(self)
    }

    /// Return the input schema pretty-printed as a JSON string.
    ///
    /// # Example
    ///
    /// ```rust
    /// use tokitai_core::ToolDefinition;
    ///
    /// let tool = ToolDefinition::new(
    ///     "add",
    ///     "Add two numbers",
    ///     r#"{"type":"object","properties":{"a":{"type":"integer"}}}"#,
    /// );
    /// let pretty = tool.input_schema_pretty().unwrap();
    /// assert!(pretty.contains('\n'));
    /// ```
    ///
    /// # Errors
    ///
    /// Returns a `serde_json::Error` if `input_schema` is not valid JSON or
    /// if pretty-printing fails.
    #[cfg(feature = "serde")]
    pub fn input_schema_pretty(&self) -> Result<String, serde_json::Error> {
        let value: serde_json::Value = serde_json::from_str(&self.input_schema)?;
        serde_json::to_string_pretty(&value)
    }

    /// Parse the input schema into a `serde_json::Value`.
    ///
    /// # Example
    ///
    /// ```rust
    /// use tokitai_core::ToolDefinition;
    /// use serde_json::json;
    ///
    /// let tool = ToolDefinition::new("add", "Add two numbers", r#"{"type":"object"}"#);
    /// let schema = tool.input_schema_value().unwrap();
    /// assert_eq!(schema, json!({"type": "object"}));
    /// ```
    ///
    /// # Errors
    ///
    /// Returns a `serde_json::Error` if `input_schema` is not valid JSON.
    #[cfg(feature = "serde")]
    pub fn input_schema_value(&self) -> Result<serde_json::Value, serde_json::Error> {
        serde_json::from_str(&self.input_schema)
    }

    /// Apply a list of runtime configuration items to this tool definition.
    ///
    /// Used by the configuration system to override compile-time defaults.
    ///
    /// # Example
    ///
    /// ```rust
    /// use tokitai_core::{ToolDefinition, ToolConfig};
    ///
    /// let mut tool = ToolDefinition::new("test", "Original description", "{}");
    /// tool.apply_configs(&[
    ///     ToolConfig::Desc("Overridden description".to_string()),
    /// ]);
    /// assert_eq!(tool.description, "Overridden description");
    /// ```
    #[cfg(feature = "serde")]
    pub fn apply_configs(&mut self, configs: &[ToolConfig]) {
        for config in configs {
            match config {
                ToolConfig::Desc(desc) => {
                    // T-002: respect the priority table.
                    //   `#[tool(desc = "...")]` (compile-time) wins
                    //   over the `tokitai!` config (runtime). If the
                    //   description was supplied explicitly at
                    //   compile time we leave it alone.
                    if !self.description_explicit {
                        self.description = desc.clone();
                    }
                }
                ToolConfig::Tags(tags) => {
                    // Add tags to the schema
                    if let Ok(mut schema) =
                        serde_json::from_str::<serde_json::Value>(&self.input_schema)
                    {
                        if let Some(obj) = schema.as_object_mut() {
                            obj.insert("tags".to_string(), serde_json::json!(tags));
                        }
                        self.input_schema = schema.to_string();
                    }
                }
                ToolConfig::ParamDesc { name, desc } => {
                    self.apply_param_desc(name, desc);
                }
                ToolConfig::ParamExample { name, example } => {
                    self.apply_param_example(name, example);
                }
                ToolConfig::ParamDefault { name, default } => {
                    self.apply_param_default(name, default);
                }
                ToolConfig::ParamRequired { name, required } => {
                    self.apply_param_required(name, *required);
                }
                ToolConfig::ParamMin { name, min } => {
                    self.apply_param_constraint(name, "minimum", serde_json::json!(min));
                }
                ToolConfig::ParamMax { name, max } => {
                    self.apply_param_constraint(name, "maximum", serde_json::json!(max));
                }
                ToolConfig::ParamMinLength { name, min_length } => {
                    self.apply_param_constraint(name, "minLength", serde_json::json!(min_length));
                }
                ToolConfig::ParamMaxLength { name, max_length } => {
                    self.apply_param_constraint(name, "maxLength", serde_json::json!(max_length));
                }
                ToolConfig::ParamPattern { name, pattern } => {
                    self.apply_param_constraint(name, "pattern", serde_json::json!(pattern));
                }
                ToolConfig::ParamMinItems { name, min_items } => {
                    self.apply_param_constraint(name, "minItems", serde_json::json!(min_items));
                }
                ToolConfig::ParamMaxItems { name, max_items } => {
                    self.apply_param_constraint(name, "maxItems", serde_json::json!(max_items));
                }
                ToolConfig::ParamMultipleOf { name, multiple_of } => {
                    self.apply_param_constraint(name, "multipleOf", serde_json::json!(multiple_of));
                }
            }
        }
    }

    /// Set the `description` field of the named parameter in the JSON schema.
    #[cfg(feature = "serde")]
    fn apply_param_desc(&mut self, name: &str, desc: &str) {
        if let Ok(mut schema) = serde_json::from_str::<serde_json::Value>(&self.input_schema) {
            if let Some(obj) = schema.as_object_mut() {
                if let Some(props) = obj.get_mut("properties").and_then(|v| v.as_object_mut()) {
                    if let Some(param) = props.get_mut(name).and_then(|v| v.as_object_mut()) {
                        param.insert("description".to_string(), serde_json::json!(desc));
                    }
                }
            }
            self.input_schema = schema.to_string();
        }
    }

    /// Set the `example` field of the named parameter in the JSON schema.
    #[cfg(feature = "serde")]
    fn apply_param_example(&mut self, name: &str, example: &serde_json::Value) {
        if let Ok(mut schema) = serde_json::from_str::<serde_json::Value>(&self.input_schema) {
            if let Some(obj) = schema.as_object_mut() {
                if let Some(props) = obj.get_mut("properties").and_then(|v| v.as_object_mut()) {
                    if let Some(param) = props.get_mut(name).and_then(|v| v.as_object_mut()) {
                        param.insert("example".to_string(), example.clone());
                    }
                }
            }
            self.input_schema = schema.to_string();
        }
    }

    /// Set the `default` field of the named parameter in the JSON schema.
    #[cfg(feature = "serde")]
    fn apply_param_default(&mut self, name: &str, default: &serde_json::Value) {
        if let Ok(mut schema) = serde_json::from_str::<serde_json::Value>(&self.input_schema) {
            if let Some(obj) = schema.as_object_mut() {
                if let Some(props) = obj.get_mut("properties").and_then(|v| v.as_object_mut()) {
                    if let Some(param) = props.get_mut(name).and_then(|v| v.as_object_mut()) {
                        param.insert("default".to_string(), default.clone());
                    }
                }
            }
            self.input_schema = schema.to_string();
        }
    }

    /// Toggle the `required` flag of the named parameter in the JSON schema.
    #[cfg(feature = "serde")]
    fn apply_param_required(&mut self, name: &str, required: bool) {
        if let Ok(mut schema) = serde_json::from_str::<serde_json::Value>(&self.input_schema) {
            if let Some(obj) = schema.as_object_mut() {
                // Update required array
                let required_arr = obj
                    .entry("required".to_string())
                    .or_insert_with(|| serde_json::json!([]))
                    .as_array_mut();

                if let Some(req_arr) = required_arr {
                    let name_json = serde_json::json!(name);
                    if required && !req_arr.contains(&name_json) {
                        req_arr.push(name_json);
                    } else if !required {
                        req_arr.retain(|v| v != &name_json);
                    }
                }

                // Also update parameter schema
                if let Some(props) = obj.get_mut("properties").and_then(|v| v.as_object_mut()) {
                    if let Some(param) = props.get_mut(name).and_then(|v| v.as_object_mut()) {
                        // Note: individual param "required" is not standard JSON Schema
                        // but we can add it for documentation purposes
                        param.insert("required".to_string(), serde_json::json!(required));
                    }
                }
            }
            self.input_schema = schema.to_string();
        }
    }

    /// Insert a JSON-Schema constraint (e.g. `minimum`, `pattern`) for a
    /// parameter by name.
    #[cfg(feature = "serde")]
    fn apply_param_constraint(
        &mut self,
        name: &str,
        constraint_key: &str,
        value: serde_json::Value,
    ) {
        if let Ok(mut schema) = serde_json::from_str::<serde_json::Value>(&self.input_schema) {
            if let Some(obj) = schema.as_object_mut() {
                if let Some(props) = obj.get_mut("properties").and_then(|v| v.as_object_mut()) {
                    if let Some(param) = props.get_mut(name).and_then(|v| v.as_object_mut()) {
                        param.insert(constraint_key.to_string(), value);
                    }
                }
            }
            self.input_schema = schema.to_string();
        }
    }

    /// Convert this tool definition into the OpenAI function-calling format.
    ///
    /// Spec: <https://platform.openai.com/docs/guides/function-calling>
    ///
    /// Returns a JSON object of the form:
    /// ```json
    /// {
    ///   "type": "function",
    ///   "function": {
    ///     "name": "<tool name>",
    ///     "description": "<tool description>",
    ///     "parameters": { /* full JSON Schema */ }
    ///   }
    /// }
    /// ```
    ///
    /// If the stored `input_schema` is not valid JSON, the `parameters`
    /// field will be emitted as an empty object (`{}`) so the surrounding
    /// envelope remains a valid OpenAI tool descriptor.
    ///
    /// T-013: when the tool has a deprecation marker, the description
    /// is suffixed with a `[DEPRECATED ...]` annotation. The OpenAI
    /// spec does not standardize a `_meta` envelope, so we surface the
    /// deprecation as visible text the LLM can read.
    ///
    /// # Example
    ///
    /// ```rust
    /// use tokitai_core::ToolDefinition;
    /// use serde_json::json;
    ///
    /// let tool = ToolDefinition::new(
    ///     "add",
    ///     "Add two numbers",
    ///     r#"{"type":"object","properties":{"a":{"type":"integer"}}}"#,
    /// );
    /// let openai = tool.to_openai_function();
    /// assert_eq!(openai["type"], json!("function"));
    /// assert_eq!(openai["function"]["name"], json!("add"));
    /// ```
    #[cfg(feature = "serde")]
    pub fn to_openai_function(&self) -> serde_json::Value {
        let parameters = self.merge_baked_examples_into(self.parse_input_schema_or_empty());
        let description = self.deprecated_description_suffix();
        serde_json::json!({
            "type": "function",
            "function": {
                "name": self.name,
                "description": description,
                "parameters": parameters,
            }
        })
    }

    /// Convert this tool definition into the Anthropic tool-use format.
    ///
    /// Spec: <https://docs.anthropic.com/en/docs/build-with-claude/tool-use>
    ///
    /// Returns a JSON object of the form:
    /// ```json
    /// {
    ///   "name": "<tool name>",
    ///   "description": "<tool description>",
    ///   "input_schema": { /* full JSON Schema */ }
    /// }
    /// ```
    ///
    /// If the stored `input_schema` is not valid JSON, the `input_schema`
    /// field will be emitted as an empty object (`{}`) so the surrounding
    /// envelope remains a valid Anthropic tool descriptor.
    ///
    /// T-013: when the tool has a deprecation marker, the description
    /// is suffixed with a `[DEPRECATED ...]` annotation that the LLM
    /// can read. Anthropic does not standardize a top-level
    /// `_meta.deprecated` field for tool definitions, so the
    /// description suffix is the supported carrier.
    ///
    /// # Example
    ///
    /// ```rust
    /// use tokitai_core::ToolDefinition;
    /// use serde_json::json;
    ///
    /// let tool = ToolDefinition::new(
    ///     "add",
    ///     "Add two numbers",
    ///     r#"{"type":"object","properties":{"a":{"type":"integer"}}}"#,
    /// );
    /// let anthropic = tool.to_anthropic_tool();
    /// assert_eq!(anthropic["name"], json!("add"));
    /// assert!(anthropic["input_schema"].is_object());
    /// ```
    #[cfg(feature = "serde")]
    pub fn to_anthropic_tool(&self) -> serde_json::Value {
        let input_schema = self.merge_baked_examples_into(self.parse_input_schema_or_empty());
        let description = self.deprecated_description_suffix();
        serde_json::json!({
            "name": self.name,
            "description": description,
            "input_schema": input_schema,
        })
    }

    /// Convert this tool definition into the Model Context Protocol (MCP)
    /// tool definition format.
    ///
    /// Spec: <https://modelcontextprotocol.io/>
    ///
    /// Returns a JSON object of the form:
    /// ```json
    /// {
    ///   "name": "<tool name>",
    ///   "description": "<tool description>",
    ///   "inputSchema": { /* full JSON Schema */ }
    /// }
    /// ```
    ///
    /// If the stored `input_schema` is not valid JSON, the `inputSchema`
    /// field will be emitted as an empty object (`{}`) so the surrounding
    /// envelope remains a valid MCP tool descriptor.
    ///
    /// T-013: when the tool has a deprecation marker, the envelope
    /// includes a `_meta` object with `deprecated`, `deprecatedSince`,
    /// `removeIn`, and `replacedBy` fields. MCP-aware clients can
    /// surface these directly to the user; the description is also
    /// suffixed with `[DEPRECATED ...]` for older clients.
    ///
    /// # Example
    ///
    /// ```rust
    /// use tokitai_core::ToolDefinition;
    /// use serde_json::json;
    ///
    /// let tool = ToolDefinition::new(
    ///     "add",
    ///     "Add two numbers",
    ///     r#"{"type":"object","properties":{"a":{"type":"integer"}}}"#,
    /// );
    /// let mcp = tool.to_mcp_tool();
    /// assert_eq!(mcp["name"], json!("add"));
    /// assert!(mcp["inputSchema"].is_object());
    /// ```
    #[cfg(feature = "serde")]
    pub fn to_mcp_tool(&self) -> serde_json::Value {
        let input_schema = self.merge_baked_examples_into(self.parse_input_schema_or_empty());
        let description = self.deprecated_description_suffix();
        let mut envelope = serde_json::json!({
            "name": self.name,
            "description": description,
            "inputSchema": input_schema,
        });
        // T-013: surface structured deprecation metadata on the MCP
        // envelope. The object key is `_meta` per the MCP 2025-06-18
        // spec; the absence of any deprecation field means the tool
        // is current.
        if self.deprecated_since.is_some() || self.remove_in.is_some() || self.replaced_by.is_some()
        {
            let mut meta = serde_json::Map::new();
            meta.insert("deprecated".to_string(), serde_json::Value::Bool(true));
            if let Some(since) = self.deprecated_since.as_deref() {
                meta.insert(
                    "deprecatedSince".to_string(),
                    serde_json::Value::String(since.to_string()),
                );
            }
            if let Some(remove_in) = self.remove_in.as_deref() {
                meta.insert(
                    "removeIn".to_string(),
                    serde_json::Value::String(remove_in.to_string()),
                );
            }
            if let Some(replaced_by) = self.replaced_by.as_deref() {
                meta.insert(
                    "replacedBy".to_string(),
                    serde_json::Value::String(replaced_by.to_string()),
                );
            }
            envelope["_meta"] = serde_json::Value::Object(meta);
        }
        envelope
    }

    /// T-013: helper for the provider-envelope emitters. Returns
    /// `self.description` (no copy when no deprecation is set) or
    /// `self.description` suffixed with a `[DEPRECATED ...]` marker
    /// the LLM can read. Kept private so callers always go through
    /// `to_openai_function` / `to_anthropic_tool` / `to_mcp_tool`.
    #[cfg(feature = "serde")]
    fn merge_baked_examples_into(&self, mut schema: serde_json::Value) -> serde_json::Value {
        if let Some(serde_json::Value::Array(arr)) = self.baked_examples.as_ref() {
            if !arr.is_empty() {
                if let serde_json::Value::Object(map) = &mut schema {
                    map.insert(
                        "examples".to_string(),
                        serde_json::Value::Array(arr.clone()),
                    );
                }
            }
        }
        schema
    }
    #[cfg(feature = "serde")]
    fn deprecated_description_suffix(&self) -> alloc::string::String {
        if self.deprecated_since.is_none() && self.remove_in.is_none() && self.replaced_by.is_none()
        {
            return self.description.clone();
        }
        let mut suffix = alloc::string::String::from(" [DEPRECATED");
        if let Some(since) = self.deprecated_since.as_deref() {
            suffix.push_str(&alloc::format!(" since={}", since));
        }
        if let Some(remove_in) = self.remove_in.as_deref() {
            suffix.push_str(&alloc::format!(" remove_in={}", remove_in));
        }
        if let Some(replaced_by) = self.replaced_by.as_deref() {
            if !replaced_by.is_empty() {
                suffix.push_str(&alloc::format!(" replaced_by={}", replaced_by));
            }
        }
        suffix.push(']');
        let mut out = self.description.clone();
        out.push_str(&suffix);
        out
    }

    /// Parse `input_schema` into a `serde_json::Value`, falling back to an
    /// empty object on parse failure. Used by the multi-format exporters
    /// (`to_openai_function`, `to_anthropic_tool`, `to_mcp_tool`) so the
    /// outer envelope is always well-formed JSON regardless of the inner
    /// schema state.
    #[cfg(feature = "serde")]
    fn parse_input_schema_or_empty(&self) -> serde_json::Value {
        serde_json::from_str::<serde_json::Value>(&self.input_schema)
            .unwrap_or_else(|_| serde_json::json!({}))
    }

    /// T-013: returns `true` when this tool's `remove_in` version is at
    /// or before `current_version` and the version strings are
    /// comparable as SemVer (three numeric components separated by
    /// `.`). Returns `false` when:
    ///
    /// * `remove_in` is `None`
    /// * `current_version` is `None` (no version gating configured at
    ///   the dispatcher level)
    /// * either string fails to parse as SemVer — we fail open so a
    ///   typo in a version string never silently removes a live tool.
    ///
    /// # Example
    ///
    /// ```rust
    /// use tokitai_core::ToolDefinition;
    ///
    /// let tool = ToolDefinition::new("legacy", "Old API", "{}")
    ///     .with_deprecated("1.0.0", "2.0.0", "modern");
    /// assert!(tool.is_removed(Some("2.0.0")));
    /// assert!(tool.is_removed(Some("3.0.0")));
    /// assert!(!tool.is_removed(Some("1.5.0")));
    /// assert!(!tool.is_removed(None));
    /// ```
    pub fn is_removed(&self, current_version: Option<&str>) -> bool {
        let (Some(remove_in), Some(current)) = (self.remove_in.as_deref(), current_version) else {
            return false;
        };
        match (parse_semver(remove_in), parse_semver(current)) {
            (Some(rm), Some(cur)) => cur >= rm,
            _ => false,
        }
    }

    /// T-013: returns the structured `Removed` error a caller should
    /// receive when `is_removed(current)` is `true`. The error message
    /// includes the `remove_in` version and, when set, the
    /// `replaced_by` successor so the LLM client (or a human reader)
    /// has the context to retry with the new name.
    ///
    /// # Example
    ///
    /// ```rust
    /// use tokitai_core::ToolDefinition;
    /// use tokitai_core::ToolErrorKind;
    ///
    /// let tool = ToolDefinition::new("legacy", "Old API", "{}")
    ///     .with_deprecated("1.0.0", "2.0.0", "modern");
    /// let err = tool.removed_error(Some("2.5.0"));
    /// assert_eq!(err.kind, ToolErrorKind::Removed);
    /// assert!(err.message.contains("2.0.0"));
    /// assert!(err.message.contains("modern"));
    /// ```
    #[cfg(feature = "serde")]
    pub fn removed_error(&self, current_version: Option<&str>) -> ToolError {
        let remove_in = self.remove_in.as_deref().unwrap_or("?");
        let message = match (current_version, self.replaced_by.as_deref()) {
            (Some(cur), Some(repl)) if !repl.is_empty() => alloc::format!(
                "tool `{}` was removed in version {} (current: {}); use `{}` instead",
                self.name,
                remove_in,
                cur,
                repl
            ),
            (Some(cur), _) => alloc::format!(
                "tool `{}` was removed in version {} (current: {})",
                self.name,
                remove_in,
                cur
            ),
            (None, Some(repl)) if !repl.is_empty() => alloc::format!(
                "tool `{}` was removed in version {}; use `{}` instead",
                self.name,
                remove_in,
                repl
            ),
            (None, _) => {
                alloc::format!("tool `{}` was removed in version {}", self.name, remove_in)
            }
        };
        ToolError::removed(message)
    }
}

/// Parse a SemVer-like version string (three numeric components
/// separated by `.`) into a `(u32, u32, u32)` tuple. Returns `None`
/// on any malformed input — we fail open elsewhere so a typo in a
/// version string never silently removes a live tool.
pub(crate) fn parse_semver(s: &str) -> Option<(u32, u32, u32)> {
    let s = s.trim();
    // Strip an optional `v` prefix and any pre-release / build
    // metadata, since neither affects ordering for T-013's
    // purposes (major.minor.patch only).
    let s = s.strip_prefix('v').unwrap_or(s);
    let core = s.split(['-', '+']).next().unwrap_or(s);
    let mut parts = core.split('.');
    let major = parts.next()?.parse::<u32>().ok()?;
    let minor = parts.next()?.parse::<u32>().ok()?;
    let patch = parts.next()?.parse::<u32>().ok()?;
    if parts.next().is_some() {
        return None;
    }
    Some((major, minor, patch))
}

/// T-020: ordered comparison helper used by `is_in_interval`.
/// Returns `true` when `current >= other` under SemVer ordering
/// when both strings parse as SemVer, otherwise lexicographic
/// `>=` on the trimmed strings. Failing back to lexicographic
/// order keeps CalVer (e.g. `2026.06`) and commit-SHA strings
/// dispatch deterministically — every well-formed version
/// has a total order, even when neither side is SemVer.
pub(crate) fn version_gte(current: &str, other: &str) -> bool {
    match (parse_semver(current), parse_semver(other)) {
        (Some(a), Some(b)) => a >= b,
        _ => current.trim() >= other.trim(),
    }
}

/// T-013: process-wide current version used to gate `remove_in`
/// removal at the dispatcher. Set via [`set_current_version`]; if
/// never set, the macro's `__call_*` wrappers run tools regardless
/// of their `remove_in` field. Wrapped in a `Mutex` so test
/// binaries (and programs that bump their version dynamically) can
/// override the slot; the production hot path takes a brief read
/// lock per call.
#[cfg(feature = "serde")]
static CURRENT_VERSION: std::sync::Mutex<Option<alloc::string::String>> =
    std::sync::Mutex::new(None);

/// T-013: install a process-wide current version. The `#[tool]`
/// macro's sync wrapper compares this value against each tool's
/// `remove_in` field; when `remove_in <= current` the call returns
/// `ToolError::Removed` and the user is directed to `replaced_by`.
///
/// Call once at program startup, or whenever the running version
/// changes. If the version is unknown, simply do not call this
/// function — the call path stays open.
///
/// # Example
///
/// ```rust,ignore
/// use tokitai_core::set_current_version;
///
/// set_current_version("2.5.0");
/// ```
#[cfg(feature = "serde")]
pub fn set_current_version(version: impl Into<alloc::string::String>) {
    if let Ok(mut guard) = CURRENT_VERSION.lock() {
        *guard = Some(version.into());
    }
}

/// T-013: clear any previously-registered current version. After
/// this call the macro stops gating `remove_in` until
/// [`set_current_version`] is called again. Useful in tests that
/// need to exercise the "no gating" path mid-suite.
#[cfg(feature = "serde")]
pub fn clear_current_version() {
    if let Ok(mut guard) = CURRENT_VERSION.lock() {
        *guard = None;
    }
}

/// T-013: return the currently registered program version, or
/// `None` when [`set_current_version`] was never called.
///
/// # Example
///
/// ```rust
/// use tokitai_core::current_version;
///
/// // Without a registered version the result is `None`.
/// // (This doctest runs in a fresh process so it asserts `None`.)
/// let _ = current_version();
/// ```
#[cfg(feature = "serde")]
pub fn current_version() -> Option<alloc::string::String> {
    CURRENT_VERSION.lock().ok().and_then(|guard| guard.clone())
}

impl core::fmt::Display for ToolDefinition {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        write!(f, "{}: {}", self.name, self.description)
    }
}

/// JSON Schema type for a tool parameter.
///
/// # Example
///
/// ```rust
/// use tokitai_core::ParamType;
///
/// assert_eq!(ParamType::from_rust_type("String"), Some(ParamType::String));
/// assert_eq!(ParamType::from_rust_type("i32"), Some(ParamType::Integer));
/// assert_eq!(ParamType::Integer.as_str(), "integer");
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[repr(u8)]
pub enum ParamType {
    /// String type
    String = 0,
    /// Integer type
    Integer = 1,
    /// Number type (floating point)
    Number = 2,
    /// Boolean type
    Boolean = 3,
    /// Array type
    Array = 4,
    /// Object type
    Object = 5,
}

impl ParamType {
    /// Return the JSON-Schema keyword for this variant (e.g. `"string"`).
    ///
    /// # Example
    ///
    /// ```rust
    /// use tokitai_core::ParamType;
    ///
    /// assert_eq!(ParamType::String.as_str(), "string");
    /// assert_eq!(ParamType::Integer.as_str(), "integer");
    /// ```
    pub fn as_str(&self) -> &'static str {
        match self {
            ParamType::String => "string",
            ParamType::Integer => "integer",
            ParamType::Number => "number",
            ParamType::Boolean => "boolean",
            ParamType::Array => "array",
            ParamType::Object => "object",
        }
    }

    /// Best-effort mapping from a Rust type name to a JSON-Schema type.
    /// Returns `None` for `Option<T>` (use [`FromJsonValue`] for those).
    ///
    /// # Example
    ///
    /// ```rust
    /// use tokitai_core::ParamType;
    ///
    /// assert_eq!(ParamType::from_rust_type("String"), Some(ParamType::String));
    /// assert_eq!(ParamType::from_rust_type("i32"), Some(ParamType::Integer));
    /// assert_eq!(ParamType::from_rust_type("f64"), Some(ParamType::Number));
    /// assert_eq!(ParamType::from_rust_type("bool"), Some(ParamType::Boolean));
    /// assert_eq!(ParamType::from_rust_type("Vec<i32>"), Some(ParamType::Array));
    /// ```
    pub fn from_rust_type(type_name: &str) -> Option<Self> {
        match type_name {
            "String" | "str" => Some(ParamType::String),
            "i8" | "i16" | "i32" | "i64" | "i128" | "u8" | "u16" | "u32" | "u64" | "u128"
            | "usize" | "isize" => Some(ParamType::Integer),
            "f32" | "f64" => Some(ParamType::Number),
            "bool" => Some(ParamType::Boolean),
            _ => {
                if type_name.starts_with("Vec<") {
                    Some(ParamType::Array)
                } else if type_name.starts_with("Option<") {
                    None
                } else {
                    Some(ParamType::Object)
                }
            }
        }
    }
}

/// A single parameter definition for a tool.
///
/// # Example
///
/// ```rust
/// use tokitai_core::{ToolParameter, ParamType};
///
/// let param = ToolParameter::new(
///     "city",
///     ParamType::String,
///     "Name of the city",
///     true, // required
/// );
/// ```
#[derive(Debug, Clone)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct ToolParameter {
    /// Parameter name
    pub name: &'static str,
    /// Parameter type
    #[cfg_attr(feature = "serde", serde(rename = "type"))]
    pub param_type: ParamType,
    /// Parameter description
    pub description: &'static str,
    /// Whether the parameter is required
    pub required: bool,
}

impl ToolParameter {
    /// Build a parameter definition.
    ///
    /// # Example
    ///
    /// ```rust
    /// use tokitai_core::{ToolParameter, ParamType};
    ///
    /// let param = ToolParameter::new("limit", ParamType::Integer, "Number of results to return", false);
    /// ```
    pub fn new(
        name: &'static str,
        param_type: ParamType,
        description: &'static str,
        required: bool,
    ) -> Self {
        Self {
            name,
            param_type,
            description,
            required,
        }
    }
}

/// Error returned by tool invocations.
///
/// # Example
///
/// ```rust
/// use tokitai_core::{ToolError, ToolErrorKind};
///
/// let error = ToolError::validation_error("Missing required parameter 'city'");
/// assert_eq!(error.kind, ToolErrorKind::ValidationError);
/// ```
#[derive(Debug, Clone)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct ToolError {
    /// Error type classification
    pub kind: ToolErrorKind,
    /// Error message
    #[cfg(feature = "serde")]
    pub message: crate::serde_types::String,
    #[cfg(not(feature = "serde"))]
    pub message: &'static str,
}

#[cfg(feature = "serde")]
impl std::error::Error for ToolError {}

#[cfg(feature = "serde")]
impl std::fmt::Display for ToolError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "ToolError: {:?} - {}", self.kind, self.message)
    }
}

#[cfg(not(feature = "serde"))]
impl ToolError {
    /// Create a new error with the given `kind` and `message`.
    ///
    /// # Example
    ///
    /// ```rust
    /// use tokitai_core::{ToolError, ToolErrorKind};
    ///
    /// let err = ToolError::new(ToolErrorKind::ValidationError, "field 'name' is required");
    /// assert_eq!(err.kind, ToolErrorKind::ValidationError);
    /// ```
    pub fn new(kind: ToolErrorKind, message: &'static str) -> Self {
        Self { kind, message }
    }

    /// Shortcut to build a `ValidationError` variant with the given message.
    ///
    /// # Example
    ///
    /// ```rust
    /// use tokitai_core::{ToolError, ToolErrorKind};
    ///
    /// let err = ToolError::validation_error("field 'name' is required");
    /// assert_eq!(err.kind, ToolErrorKind::ValidationError);
    /// ```
    pub fn validation_error(message: &'static str) -> Self {
        Self {
            kind: ToolErrorKind::ValidationError,
            message,
        }
    }

    /// Shortcut to build a `NotFound` variant with the given tool name.
    ///
    /// # Example
    ///
    /// ```rust
    /// use tokitai_core::{ToolError, ToolErrorKind};
    ///
    /// let err = ToolError::not_found("unknown_tool");
    /// assert_eq!(err.kind, ToolErrorKind::NotFound);
    /// assert_eq!(err.message, "unknown_tool");
    /// ```
    pub fn not_found(message: &'static str) -> Self {
        Self {
            kind: ToolErrorKind::NotFound,
            message,
        }
    }

    /// Shortcut to build an `InternalError` variant with the given message.
    ///
    /// # Example
    ///
    /// ```rust
    /// use tokitai_core::{ToolError, ToolErrorKind};
    ///
    /// let err = ToolError::internal_error("downstream timed out");
    /// assert_eq!(err.kind, ToolErrorKind::InternalError);
    /// ```
    pub fn internal_error(message: &'static str) -> Self {
        Self {
            kind: ToolErrorKind::InternalError,
            message,
        }
    }

    /// Shortcut to build a `Removed` variant (T-013) with the given
    /// message. Returned by the macro's `__call_*` wrapper when the
    /// tool's `remove_in` version is at or before the program's
    /// current version.
    ///
    /// # Example
    ///
    /// ```rust
    /// use tokitai_core::{ToolError, ToolErrorKind};
    ///
    /// let err = ToolError::removed("tool removed in 1.0.0; use new_thing");
    /// assert_eq!(err.kind, ToolErrorKind::Removed);
    /// ```
    pub fn removed(message: &'static str) -> Self {
        Self {
            kind: ToolErrorKind::Removed,
            message,
        }
    }

    /// T-019: shortcut to build a `Truncated` variant for
    /// `#[tool(result_truncate_bytes = N)]` runs that exceeded the
    /// declared byte budget. The diagnostic message identifies
    /// the result as a truncated payload so the LLM-side harness
    /// can decide whether to retry with a narrower input.
    ///
    /// # Example
    ///
    /// ```rust
    /// use tokitai_core::{ToolError, ToolErrorKind};
    ///
    /// let err = ToolError::truncated();
    /// assert_eq!(err.kind, ToolErrorKind::Truncated);
    /// ```
    pub fn truncated() -> Self {
        Self {
            kind: ToolErrorKind::Truncated,
            message: "tool result exceeded the result_truncate_bytes budget",
        }
    }
}

#[cfg(feature = "serde")]
impl ToolError {
    /// Create a new error with the given `kind` and `message`.
    ///
    /// # Example
    ///
    /// ```rust
    /// use tokitai_core::{ToolError, ToolErrorKind};
    ///
    /// let err = ToolError::new(ToolErrorKind::ValidationError, "field 'name' is required");
    /// assert_eq!(err.kind, ToolErrorKind::ValidationError);
    /// ```
    pub fn new(kind: ToolErrorKind, message: impl Into<crate::serde_types::String>) -> Self {
        Self {
            kind,
            message: message.into(),
        }
    }

    /// Shortcut to build a `ValidationError` variant with the given message.
    ///
    /// # Example
    ///
    /// ```rust
    /// use tokitai_core::{ToolError, ToolErrorKind};
    ///
    /// let err = ToolError::validation_error("field 'name' is required");
    /// assert_eq!(err.kind, ToolErrorKind::ValidationError);
    /// ```
    pub fn validation_error(message: impl Into<crate::serde_types::String>) -> Self {
        Self {
            kind: ToolErrorKind::ValidationError,
            message: message.into(),
        }
    }

    /// Shortcut to build a `NotFound` variant with the given tool name.
    ///
    /// # Example
    ///
    /// ```rust
    /// use tokitai_core::{ToolError, ToolErrorKind};
    ///
    /// let err = ToolError::not_found("unknown_tool");
    /// assert_eq!(err.kind, ToolErrorKind::NotFound);
    /// ```
    pub fn not_found(message: impl Into<crate::serde_types::String>) -> Self {
        Self {
            kind: ToolErrorKind::NotFound,
            message: message.into(),
        }
    }

    /// Shortcut to build an `InternalError` variant with the given message.
    ///
    /// # Example
    ///
    /// ```rust
    /// use tokitai_core::{ToolError, ToolErrorKind};
    ///
    /// let err = ToolError::internal_error("downstream timed out");
    /// assert_eq!(err.kind, ToolErrorKind::InternalError);
    /// ```
    pub fn internal_error(message: impl Into<crate::serde_types::String>) -> Self {
        Self {
            kind: ToolErrorKind::InternalError,
            message: message.into(),
        }
    }

    /// Shortcut to build a `Removed` variant with the given message.
    /// T-013: returned by the macro's `__call_*` wrapper when the
    /// tool's `remove_in` version is at or before the program's
    /// current version.
    ///
    /// # Example
    ///
    /// ```rust
    /// use tokitai_core::{ToolError, ToolErrorKind};
    ///
    /// let err = ToolError::removed("tool removed in 1.0.0; use new_thing");
    /// assert_eq!(err.kind, ToolErrorKind::Removed);
    /// ```
    pub fn removed(message: impl Into<crate::serde_types::String>) -> Self {
        Self {
            kind: ToolErrorKind::Removed,
            message: message.into(),
        }
    }

    /// T-019: shortcut to build a `Truncated` variant for
    /// `#[tool(result_truncate_bytes = N)]` runs that exceeded the
    /// declared byte budget. The `message` includes the original
    /// and kept byte counts so a downstream log scraper can
    /// decide whether the dropped bytes matter.
    ///
    /// # Example
    ///
    /// ```rust
    /// use tokitai_core::{ToolError, ToolErrorKind};
    ///
    /// let err = ToolError::truncated_with(8000, 4096);
    /// assert_eq!(err.kind, ToolErrorKind::Truncated);
    /// assert!(err.message.contains("8000"));
    /// assert!(err.message.contains("4096"));
    /// ```
    pub fn truncated_with(original_bytes: usize, kept_bytes: usize) -> Self {
        Self {
            kind: ToolErrorKind::Truncated,
            message: format!(
                "tool result exceeded the result_truncate_bytes budget: \
                 original {} bytes, kept {} bytes",
                original_bytes, kept_bytes
            ),
        }
    }
}

/// Classification of a [`ToolError`] for structured error handling.
///
/// # Example
///
/// ```rust
/// use tokitai_core::ToolErrorKind;
///
/// // The six classifications:
/// assert_ne!(ToolErrorKind::ValidationError, ToolErrorKind::NotFound);
/// assert_ne!(ToolErrorKind::InternalError, ToolErrorKind::TypeError);
/// assert_ne!(ToolErrorKind::Removed, ToolErrorKind::NotFound);
/// assert_ne!(ToolErrorKind::Truncated, ToolErrorKind::InternalError);
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[repr(u8)]
pub enum ToolErrorKind {
    /// Validation error - parameter validation failed
    ValidationError = 0,
    /// Not found - requested tool does not exist
    NotFound = 1,
    /// Internal error - tool execution failed
    InternalError = 2,
    /// Type error - parameter type mismatch
    TypeError = 3,
    /// Removed - the tool's `remove_in` version is at or before the
    /// program's current version (T-013). Callers should consult
    /// `ToolError::message` (and `replaced_by` if present) to
    /// discover the successor.
    Removed = 4,
    /// T-019: the tool's serialized result exceeded the per-method
    /// `result_truncate_bytes` budget. The error's `message`
    /// carries the diagnostic (`"original N bytes, kept M bytes"`)
    /// and the macro also emits a `tracing::warn!` when the
    /// `trace` feature is on. The original payload is dropped;
    /// downstream callers should treat this as a partial answer
    /// and (where the consumer's contract allows) call the tool
    /// again with a narrower input.
    Truncated = 5,
}

/// Compile-time tool registry trait.
///
/// Auto-implemented by the `#[tool]` macro for any `impl` block it processes.
///
/// # Example
///
/// ```rust,ignore
/// use tokitai_core::ToolProvider;
/// // After `#[tool]` on a type:
/// // let tools = Calculator::tool_definitions();
/// // let count = Calculator::tool_count();
/// // let tool  = Calculator::find_tool("add");
/// ```
pub trait ToolProvider {
    /// All tool definitions produced by this provider.
    fn tool_definitions() -> &'static [ToolDefinition];

    /// Number of tools produced by this provider.
    fn tool_count() -> usize {
        Self::tool_definitions().len()
    }

    /// Look up a tool definition by its `name`.
    fn find_tool(name: &str) -> Option<&'static ToolDefinition> {
        Self::tool_definitions().iter().find(|t| t.name == name)
    }
}

/// Runtime tool invocation trait. Auto-implemented by the `#[tool]` macro.
///
/// # Example
///
/// ```rust,ignore
/// use tokitai_core::{ToolProvider, ToolCaller};
/// use serde_json::json;
///
/// let calc = Calculator;
/// let result = calc.call_tool("add", &json!({"a": 10, "b": 20})).unwrap();
/// assert_eq!(result, json!(30));
/// ```
#[cfg(feature = "serde")]
pub trait ToolCaller {
    /// Invoke a tool by `name` with the given JSON `args`.
    ///
    /// # Example
    ///
    /// ```rust,ignore
    /// use tokitai_core::ToolCaller;
    /// use serde_json::json;
    ///
    /// // After `#[tool]` has been applied to Calculator:
    /// // let result = calc.call_tool("add", &json!({"a": 1, "b": 2})).unwrap();
    /// // assert_eq!(result, json!(3));
    /// ```
    ///
    /// # Errors
    ///
    /// Returns a [`ToolError`] of kind [`ToolErrorKind::NotFound`] if no tool
    /// with the given name is registered, or of kind [`ToolErrorKind::ValidationError`]
    /// / [`ToolErrorKind::InternalError`] if argument parsing or tool
    /// execution fails.
    fn call_tool(
        &self,
        name: &str,
        args: &crate::serde_types::Value,
    ) -> Result<crate::serde_types::Value, ToolError>;
}

/// # From Json Value Trait
///
/// Parses JSON values into Rust types. Implemented once per type and used by
/// the `#[tool]` macro to extract typed parameters from JSON arguments.
///
/// # Example
///
/// ```rust
/// use tokitai_core::FromJsonValue;
/// use serde_json::json;
///
/// let args = json!({"count": 42, "name": "test"});
/// let count = i64::from_json_value(&args, "count").unwrap();
/// let name = String::from_json_value(&args, "name").unwrap();
/// assert_eq!(count, 42);
/// assert_eq!(name, "test");
/// ```
#[cfg(feature = "serde")]
pub trait FromJsonValue: Sized {
    /// Extract a typed value for `key` from a JSON arguments object.
    ///
    /// # Example
    ///
    /// ```rust
    /// use tokitai_core::FromJsonValue;
    /// use serde_json::json;
    ///
    /// let args = json!({"count": 42});
    /// let count = i64::from_json_value(&args, "count").unwrap();
    /// assert_eq!(count, 42);
    /// ```
    ///
    /// # Errors
    ///
    /// Returns a [`ToolError`] of kind [`ToolErrorKind::ValidationError`] when
    /// `key` is missing or its value does not match `Self`'s expected type.
    fn from_json_value(args: &crate::serde_types::Value, key: &str) -> Result<Self, ToolError>;

    /// Extract a typed value for `key`, or `None` if extraction fails.
    ///
    /// Equivalent to `Self::from_json_value(args, key).ok()`. Useful for
    /// optional parameters.
    ///
    /// # Example
    ///
    /// ```rust
    /// use tokitai_core::FromJsonValue;
    /// use serde_json::json;
    ///
    /// let args = json!({});
    /// let missing: Option<i64> = i64::from_json_value_opt(&args, "absent");
    /// assert_eq!(missing, None);
    ///
    /// let args = json!({"count": 7});
    /// let present = i64::from_json_value_opt(&args, "count");
    /// assert_eq!(present, Some(7));
    /// ```
    fn from_json_value_opt(args: &crate::serde_types::Value, key: &str) -> Option<Self> {
        Self::from_json_value(args, key).ok()
    }
}

// ============== Primitive type impls ==============

#[cfg(feature = "serde")]
impl FromJsonValue for i64 {
    #[inline(always)]
    fn from_json_value(args: &crate::serde_types::Value, key: &str) -> Result<Self, ToolError> {
        args.get(key)
            .ok_or_else(|| {
                ToolError::validation_error(format!("Missing required parameter '{}'", key))
            })?
            .as_i64()
            .ok_or_else(|| {
                ToolError::validation_error(format!(
                    "Parameter '{}' has wrong type, expected integer",
                    key
                ))
            })
    }
}

#[cfg(feature = "serde")]
impl FromJsonValue for i32 {
    #[inline(always)]
    fn from_json_value(args: &crate::serde_types::Value, key: &str) -> Result<Self, ToolError> {
        args.get(key)
            .ok_or_else(|| {
                ToolError::validation_error(format!("Missing required parameter '{}'", key))
            })?
            .as_i64()
            .map(|v| v as i32)
            .ok_or_else(|| {
                ToolError::validation_error(format!(
                    "Parameter '{}' has wrong type, expected integer",
                    key
                ))
            })
    }
}

#[cfg(feature = "serde")]
impl FromJsonValue for u64 {
    #[inline(always)]
    fn from_json_value(args: &crate::serde_types::Value, key: &str) -> Result<Self, ToolError> {
        args.get(key)
            .ok_or_else(|| {
                ToolError::validation_error(format!("Missing required parameter '{}'", key))
            })?
            .as_u64()
            .ok_or_else(|| {
                ToolError::validation_error(format!(
                    "Parameter '{}' has wrong type, expected unsigned integer",
                    key
                ))
            })
    }
}

#[cfg(feature = "serde")]
impl FromJsonValue for u32 {
    #[inline(always)]
    fn from_json_value(args: &crate::serde_types::Value, key: &str) -> Result<Self, ToolError> {
        args.get(key)
            .ok_or_else(|| {
                ToolError::validation_error(format!("Missing required parameter '{}'", key))
            })?
            .as_u64()
            .map(|v| v as u32)
            .ok_or_else(|| {
                ToolError::validation_error(format!(
                    "Parameter '{}' has wrong type, expected unsigned integer",
                    key
                ))
            })
    }
}

#[cfg(feature = "serde")]
impl FromJsonValue for f64 {
    #[inline(always)]
    fn from_json_value(args: &crate::serde_types::Value, key: &str) -> Result<Self, ToolError> {
        args.get(key)
            .ok_or_else(|| {
                ToolError::validation_error(format!("Missing required parameter '{}'", key))
            })?
            .as_f64()
            .ok_or_else(|| {
                ToolError::validation_error(format!(
                    "Parameter '{}' has wrong type, expected number",
                    key
                ))
            })
    }
}

#[cfg(feature = "serde")]
impl FromJsonValue for f32 {
    #[inline(always)]
    fn from_json_value(args: &crate::serde_types::Value, key: &str) -> Result<Self, ToolError> {
        args.get(key)
            .ok_or_else(|| {
                ToolError::validation_error(format!("Missing required parameter '{}'", key))
            })?
            .as_f64()
            .map(|v| v as f32)
            .ok_or_else(|| {
                ToolError::validation_error(format!(
                    "Parameter '{}' has wrong type, expected number",
                    key
                ))
            })
    }
}

#[cfg(feature = "serde")]
impl FromJsonValue for bool {
    #[inline(always)]
    fn from_json_value(args: &crate::serde_types::Value, key: &str) -> Result<Self, ToolError> {
        args.get(key)
            .ok_or_else(|| {
                ToolError::validation_error(format!("Missing required parameter '{}'", key))
            })?
            .as_bool()
            .ok_or_else(|| {
                ToolError::validation_error(format!(
                    "Parameter '{}' has wrong type, expected boolean",
                    key
                ))
            })
    }
}

#[cfg(feature = "serde")]
impl FromJsonValue for String {
    #[inline(always)]
    fn from_json_value(args: &crate::serde_types::Value, key: &str) -> Result<Self, ToolError> {
        args.get(key)
            .ok_or_else(|| {
                ToolError::validation_error(format!("Missing required parameter '{}'", key))
            })?
            .as_str()
            .map(|s| s.to_string())
            .ok_or_else(|| {
                ToolError::validation_error(format!(
                    "Parameter '{}' has wrong type, expected string",
                    key
                ))
            })
    }
}

// ============== &str zero-copy support ==============
// Special handling: needs a lifetime, so we expose a standalone function.

/// Borrow a string parameter without copying.
///
/// # Example
///
/// ```rust
/// use tokitai_core::from_json_value_str;
/// use serde_json::json;
///
/// let args = json!({"city": "Paris"});
/// let city: &str = from_json_value_str(&args, "city").unwrap();
/// assert_eq!(city, "Paris");
/// ```
///
/// # Errors
///
/// Returns a [`ToolError`] of kind [`ToolErrorKind::ValidationError`] when
/// `key` is missing or its value is not a string.
#[cfg(feature = "serde")]
#[inline(always)]
pub fn from_json_value_str<'a>(
    args: &'a crate::serde_types::Value,
    key: &str,
) -> Result<&'a str, ToolError> {
    args.get(key)
        .ok_or_else(|| {
            ToolError::validation_error(format!("Missing required parameter '{}'", key))
        })?
        .as_str()
        .ok_or_else(|| {
            ToolError::validation_error(format!("Parameter '{}' type error, expected string", key))
        })
}

// ============== Option impls ==============

#[cfg(feature = "serde")]
impl<T: FromJsonValue> FromJsonValue for Option<T> {
    #[inline(always)]
    fn from_json_value(args: &crate::serde_types::Value, key: &str) -> Result<Self, ToolError> {
        Ok(T::from_json_value_opt(args, key))
    }
}

// ============== Vec impls ==============

#[cfg(feature = "serde")]
impl<T: serde::de::DeserializeOwned> FromJsonValue for Vec<T> {
    #[inline(always)]
    fn from_json_value(args: &crate::serde_types::Value, key: &str) -> Result<Self, ToolError> {
        let value = args.get(key).ok_or_else(|| {
            ToolError::validation_error(format!("Missing required parameter '{}'", key))
        })?;
        serde_json::from_value(value.clone()).map_err(|e| {
            ToolError::validation_error(format!("Parameter '{}' has wrong type: {}", key, e))
        })
    }
}

// ============== Helper: parse any DeserializeOwned type ==============
// For unsupported custom types, users can deserialize manually inside their method.

/// Parse a `DeserializeOwned` value for `key`. Useful for custom types not
/// covered by the [`FromJsonValue`] blanket impls.
///
/// # Example
///
/// ```rust
/// use tokitai_core::from_json_value_generic;
/// use serde_json::json;
/// use serde::Deserialize;
///
/// #[derive(Deserialize, Debug, PartialEq)]
/// struct Point { x: i32, y: i32 }
///
/// let args = json!({"p": {"x": 1, "y": 2}});
/// let p: Point = from_json_value_generic(&args, "p").unwrap();
/// assert_eq!(p, Point { x: 1, y: 2 });
/// ```
///
/// # Errors
///
/// Returns a [`ToolError`] of kind [`ToolErrorKind::ValidationError`] when
/// `key` is missing or its value cannot be deserialized into `T`.
#[cfg(feature = "serde")]
#[inline(always)]
pub fn from_json_value_generic<T: serde::de::DeserializeOwned>(
    args: &crate::serde_types::Value,
    key: &str,
) -> Result<T, ToolError> {
    let value = args.get(key).ok_or_else(|| {
        ToolError::validation_error(format!("Missing required parameter '{}'", key))
    })?;
    serde_json::from_value(value.clone())
        .map_err(|e| ToolError::validation_error(format!("Parameter '{}' type error: {}", key, e)))
}

// ============== HashMap impls ==============
#[cfg(feature = "serde")]
impl<V: serde::de::DeserializeOwned> FromJsonValue for std::collections::HashMap<String, V> {
    #[inline(always)]
    fn from_json_value(args: &crate::serde_types::Value, key: &str) -> Result<Self, ToolError> {
        let value = args.get(key).ok_or_else(|| {
            ToolError::validation_error(format!("Missing required parameter '{}'", key))
        })?;
        serde_json::from_value(value.clone()).map_err(|e| {
            ToolError::validation_error(format!("Parameter '{}' type error: {}", key, e))
        })
    }
}

// ============== BTreeMap impls ==============
#[cfg(feature = "serde")]
impl<V: serde::de::DeserializeOwned> FromJsonValue for std::collections::BTreeMap<String, V> {
    #[inline(always)]
    fn from_json_value(args: &crate::serde_types::Value, key: &str) -> Result<Self, ToolError> {
        let value = args.get(key).ok_or_else(|| {
            ToolError::validation_error(format!("Missing required parameter '{}'", key))
        })?;
        serde_json::from_value(value.clone()).map_err(|e| {
            ToolError::validation_error(format!("Parameter '{}' type error: {}", key, e))
        })
    }
}

/// Runtime configuration types used to override compile-time tool metadata.
#[cfg(feature = "serde")]
pub mod config;

/// # Runtime-Agnostic Async Executor
///
/// Bridge for the `#[tool]` macro's sync-from-async path that decouples
/// Tokitai from Tokio. The macro's sync wrapper delegates to a registered
/// [`AsyncExecutor`]; install one with [`set_async_executor`] to use
/// `async-std`, `smol`, `embassy`, or any custom executor.
///
/// ## Default behaviour
///
/// 1. Custom executor registered via [`set_async_executor`] -> use it.
/// 2. Otherwise, if inside a Tokio runtime, use the active
///    `Handle::block_on` (preserves backward compatibility).
/// 3. Otherwise, return a [`ToolError`] with a descriptive English message.
///
/// ## No-`std` fallback
///
/// When the `serde` feature is disabled the crate is `no_std` and no
/// executor is reachable; [`block_on_async`] always returns a
/// `ToolError::InternalError` so the macro can still type-check.
///
/// [`block_on_async`]: crate::block_on_async
///
/// This trait is **object-safe** so the user-registered executor can be
/// stored as `&'static dyn AsyncExecutor`. The type-erased
/// [`AsyncExecutor::block_on_dyn`] takes a boxed future and returns a boxed
/// output; typed convenience is provided by [`AsyncExecutorExt`].
///
/// ## T-003 per-call override seam
///
/// Implementations may override [`AsyncExecutor::block_on_for`] to return
/// `Some(...)` when an ambient executor (per-`call_tool`, per-thread, etc.)
/// is reachable. The `#[tool]` macro's sync-from-async wrapper probes
/// `block_on_for` first, then the global slot set via
/// [`set_async_executor`], then the active Tokio runtime. This is how
/// `async-std` / `smol` / `embassy` users supply an executor without
/// mutating global state.
pub trait AsyncExecutor: Send + Sync {
    /// Object-safe entry point: drive a boxed future to completion on the
    /// current thread and return its output as a boxed `Any`. Most users
    /// implement [`AsyncExecutorExt::block_on`] and let the blanket impl
    /// derive this; override it directly only for full control.
    ///
    /// # Example
    ///
    /// ```rust,ignore
    /// use tokitai_core::AsyncExecutor;
    /// use core::future::Future;
    /// use core::pin::Pin;
    /// use core::any::Any;
    ///
    /// struct ThreadPoolExecutor;
    /// impl AsyncExecutor for ThreadPoolExecutor {
    ///     fn block_on_dyn(
    ///         &self,
    ///         future: Pin<Box<dyn Future<Output = ()> + Send>>,
    ///     ) -> Box<dyn Any + Send> {
    ///         // ... drive the future to completion ...
    ///         # Box::new(())
    ///     }
    /// }
    /// ```
    fn block_on_dyn(
        &self,
        future: core::pin::Pin<Box<dyn core::future::Future<Output = ()> + Send>>,
    ) -> Box<dyn core::any::Any + Send>;

    /// Per-call override seam (T-003). The `#[tool]` macro's sync
    /// wrapper probes this *before* the global slot, so users who do not
    /// want a process-wide side effect can supply an executor locally.
    ///
    /// Return `None` to indicate "no ambient executor; fall through to
    /// the global slot / Tokio probe." The default implementation always
    /// returns `None`; runtime-aware executors (async-std, smol, embassy)
    /// override it to return `Some(...)` when their runtime is reachable
    /// on the current thread.
    ///
    /// # Example
    ///
    /// ```rust,ignore
    /// use tokitai_core::AsyncExecutor;
    ///
    /// struct AsyncStdExecutor;
    /// impl AsyncExecutor for AsyncStdExecutor {
    ///     fn block_on_dyn(
    ///         &self,
    ///         future: core::pin::Pin<
    ///             Box<dyn core::future::Future<Output = ()> + Send>,
    ///         >,
    ///     ) -> Box<dyn core::any::Any + Send> {
    ///         // ... drive the future ...
    ///         # Box::new(())
    ///     }
    ///
    ///     fn block_on_for(
    ///         &self,
    ///     ) -> Option<&'static dyn AsyncExecutor> {
    ///         // async-std sets a thread-local handle; return `Some(self)`
    ///         // when one is reachable on this thread.
    ///         None
    ///     }
    /// }
    /// ```
    fn block_on_for(&self) -> Option<&'static dyn AsyncExecutor> {
        None
    }
}

/// Typed convenience wrapper around [`AsyncExecutor::block_on_dyn`].
/// Implemented for every `T: AsyncExecutor`; re-introduces the natural
/// `block_on<F: Future>(&self, F) -> F::Output` signature on top of the
/// type-erased entry point.
///
/// # Example
///
/// ```rust,ignore
/// use tokitai_core::{AsyncExecutor, AsyncExecutorExt};
///
/// fn drive<E: AsyncExecutor>(exec: &E) -> String {
///     exec.block_on(async { String::from("typed output") })
/// }
/// ```
pub trait AsyncExecutorExt: AsyncExecutor {
    /// Drive a future to completion and return its output.
    ///
    /// The future must be `Send + 'static` (so it can cross the type-erasure
    /// boundary) and its output must be `Send + 'static` (so it can be
    /// downcast on the call site).
    ///
    /// # Example
    ///
    /// ```rust,ignore
    /// use tokitai_core::{AsyncExecutor, AsyncExecutorExt};
    ///
    /// fn run<E: AsyncExecutor>(exec: &E) -> i32 {
    ///     exec.block_on(async { 21 + 21 })
    /// }
    /// ```
    ///
    /// # Panics
    ///
    /// Panics if the internal output slot mutex is poisoned or if the
    /// underlying [`AsyncExecutor::block_on_dyn`] returns without driving the
    /// future to completion.
    fn block_on<F>(&self, future: F) -> F::Output
    where
        F: core::future::Future + Send + 'static,
        F::Output: Send + 'static,
    {
        use core::any::Any;
        use core::sync::atomic::{AtomicBool, Ordering};
        use std::sync::{Arc, Mutex};

        let slot: Arc<Mutex<Option<F::Output>>> = Arc::new(Mutex::new(None));
        let ran: Arc<AtomicBool> = Arc::new(AtomicBool::new(false));
        let slot_inner = slot.clone();
        let ran_inner = ran.clone();

        let wrapped = async move {
            let output = future.await;
            *slot_inner
                .lock()
                .expect("AsyncExecutor output slot poisoned") = Some(output);
            ran_inner.store(true, Ordering::Release);
        };

        let _: Box<dyn Any + Send> = self.block_on_dyn(Box::pin(wrapped));

        assert!(
            ran.load(Ordering::Acquire),
            "AsyncExecutor did not drive the future to completion"
        );

        let mut guard = slot.lock().expect("AsyncExecutor output slot poisoned");
        guard
            .take()
            .expect("future reported complete but produced no output")
    }
}

impl<T: AsyncExecutor + ?Sized> AsyncExecutorExt for T {}

/// Process-wide slot that holds the user-registered [`AsyncExecutor`].
/// A `OnceLock<Box<dyn AsyncExecutor>>` is the portable, leak-free
/// storage: the box is leaked into the static slot, so the resulting
/// reference is `&'static`.
static ASYNC_EXECUTOR: std::sync::OnceLock<Box<dyn AsyncExecutor>> = std::sync::OnceLock::new();

/// Install a global [`AsyncExecutor`] used by every `#[tool]`-generated sync
/// wrapper. Call once at program startup, before any sync `call_tool` is
/// invoked on an `async` tool. The box is leaked: the executor lives for the
/// lifetime of the program. The first call wins; subsequent calls are
/// silently ignored (best-effort registration).
///
/// # Global fallback role (T-003)
///
/// `set_async_executor` is the **process-wide fallback** used by the
/// `#[tool]` macro. The sync-from-async wrapper resolves an executor in
/// this order:
///
/// 1. [`block_on_for_executor`] — per-call / per-thread override probe
///    (T-003). Lets users wire async-std / smol / embassy without mutating
///    global state.
/// 2. The executor registered via [`set_async_executor`] (this function).
///    This is the slot `async-std` / `smol` / `embassy` users populate
///    when they want a single, program-wide bridge.
/// 3. The active Tokio runtime, when one is reachable on the current
///    thread.
/// 4. Otherwise, [`block_on_async`] returns a [`ToolError`] with the
///    canonical English message.
///
/// Use case: an `async-std` user can call this once at startup with an
/// `async_std::task::Executor` wrapper. The macro then resolves the
/// wrapper on every sync `call_tool` without the user touching the
/// macro.
///
/// # Example
///
/// ```rust,ignore
/// use tokitai_core::{set_async_executor, AsyncExecutor, AsyncExecutorExt};
/// use core::future::Future;
/// use core::pin::Pin;
///
/// struct BlockingExecutor;
/// impl AsyncExecutor for BlockingExecutor {
///     fn block_on_dyn(
///         &self,
///         future: Pin<Box<dyn Future<Output = ()> + Send>>,
///     ) -> Box<dyn core::any::Any + Send> {
///         Box::new(futures::executor::block_on(future))
///     }
/// }
///
/// set_async_executor(Box::new(BlockingExecutor));
/// ```
pub fn set_async_executor<E: AsyncExecutor + 'static>(executor: Box<E>) {
    let trait_obj: Box<dyn AsyncExecutor> = executor;
    // `_ =` to ignore the `AlreadyInitialized` error; the registration
    // is best-effort. The first executor wins.
    let _ = ASYNC_EXECUTOR.set(trait_obj);
}

/// Return the currently registered [`AsyncExecutor`], or `None` if no
/// executor has been installed via [`set_async_executor`]. The returned
/// reference is `&'static` because the registered `Box<dyn AsyncExecutor>`
/// is held inside a `OnceLock` for the program's lifetime.
///
/// # Example
///
/// ```rust,ignore
/// use tokitai_core::current_async_executor;
///
/// // Initially no executor has been installed.
/// assert!(current_async_executor().is_none());
/// ```
pub fn current_async_executor() -> Option<&'static dyn AsyncExecutor> {
    ASYNC_EXECUTOR
        .get()
        .map(|b| b.as_ref() as &'static dyn AsyncExecutor)
}

/// T-003 per-call override probe. Returns an executor that should be
/// preferred over the global slot. The macro's sync-from-async wrapper
/// calls this first; only on `None` does it fall back to
/// [`current_async_executor`] and the active Tokio runtime.
///
/// This hook lets users wire a runtime-aware executor (async-std / smol
/// / embassy) without leaking a global side effect from
/// [`set_async_executor`]. The default implementation returns `None` so
/// existing executors keep their old behaviour.
///
/// # Example
///
/// ```rust,ignore
/// use tokitai_core::block_on_for_executor;
///
/// // Without a registered executor this returns `None`.
/// assert!(block_on_for_executor().is_none());
/// ```
pub fn block_on_for_executor() -> Option<&'static dyn AsyncExecutor> {
    ASYNC_EXECUTOR.get().and_then(|b| b.block_on_for())
}

/// Try to drive `future` to completion using the registered executor, the
/// current Tokio runtime (when available), or a clear English error.
///
/// This is the entry point used by the `#[tool]` macro. It is intentionally
/// panic-free and always returns a [`ToolError`] on failure so the macro
/// can propagate the error through `call_tool_sync` without `unwrap`.
///
/// # Example
///
/// ```rust,ignore
/// use tokitai_core::{block_on_async, set_async_executor, AsyncExecutor, AsyncExecutorExt};
/// use core::future::Future;
/// use core::pin::Pin;
/// use core::any::Any;
///
/// struct InlineExecutor;
/// impl AsyncExecutor for InlineExecutor {
///     fn block_on_dyn(
///         &self,
///         future: Pin<Box<dyn Future<Output = ()> + Send>>,
///     ) -> Box<dyn Any + Send> {
///         futures::executor::block_on(future);
///         Box::new(())
///     }
/// }
///
/// set_async_executor(Box::new(InlineExecutor));
/// let value: i32 = block_on_async(async { 21 + 21 }).unwrap();
/// assert_eq!(value, 42);
/// ```
///
/// # Errors
///
/// Returns a [`ToolError`] of kind [`ToolErrorKind::InternalError`] when no
/// executor is registered and no Tokio runtime is in scope. The `#[tool]`
/// macro also probes for a Tokio runtime and surfaces a richer message via
/// [`block_on_async_error_message`].
#[cfg(feature = "serde")]
pub fn block_on_async<F>(future: F) -> Result<F::Output, ToolError>
where
    F: core::future::Future + Send + 'static,
    F::Output: Send + 'static,
{
    // T-003: probe the per-call override seam *before* the global slot
    // so async-std / smol / embassy users who override `block_on_for`
    // on their registered executor get the per-thread handle when it
    // is reachable.
    if let Some(exec) = block_on_for_executor() {
        return Ok(exec.block_on(future));
    }
    if let Some(exec) = current_async_executor() {
        return Ok(exec.block_on(future));
    }

    // No executor was registered. The `#[tool]` macro's sync wrappers
    // additionally probe the current Tokio runtime as a final fallback;
    // here we only handle the user-registered executor path and return
    // a clear error so the macro can surface a helpful message.
    drop(future);
    Err(ToolError::internal_error(block_on_async_error_message()))
}

/// `no_std`/`no-serde` companion to [`block_on_async`]. Always returns an
/// error because no executor is reachable in a `no_std` build.
///
/// # Errors
///
/// Always returns `Err` with a static explanation string instructing the
/// caller to enable the `serde` feature and register an executor.
#[cfg(not(feature = "serde"))]
pub fn block_on_async<F>(_future: F) -> Result<F, &'static str> {
    Err(
        "no async runtime available in no_std build; enable the `serde` feature \
         and call `tokitai_core::set_async_executor(...)` to enable sync-from-async",
    )
}

/// Canonical English error message returned by the `#[tool]` macro when
/// it cannot find any executor to drive a sync-from-async call. The macro
/// embeds the return value of this function as the error string, so the
/// message is centralised here for consistency and future i18n.
///
/// # Example
///
/// ```rust
/// use tokitai_core::block_on_async_error_message;
///
/// let msg = block_on_async_error_message();
/// assert!(msg.contains("no async runtime"));
/// ```
pub const fn block_on_async_error_message() -> &'static str {
    "no async runtime registered; either call from within an async context, \
     run inside a tokio runtime, or call `tokitai_core::set_async_executor(...)` \
     before invoking"
}

// -------------------------------------------------------------------------
// T-004: runtime-agnostic async sleep.
//
// Resilience decorators (`#[retry]`, `#[rate_limit]`,
// `#[circuit_breaker]`) on `async fn` need to wait between attempts
// without blocking the runtime worker thread. With Tokio that is
// `tokio::time::sleep`; with async-std, `async_std::task::sleep`; with
// smol, `smol::Timer::after`. None of those crates are in scope for
// `tokitai-core` (it is zero-dep / no-`tokio`).
//
// The helper below provides a runtime-agnostic equivalent: spawn a
// thread that parks for the requested duration and wakes the future's
// `Waker` when the deadline elapses. The user-registered executor
// drives the future through `block_on`; the spawned thread is the
// "timer" replacement. This costs one short-lived thread per sleep,
// which is the same trade-off `async-std` / `smol` make internally.
//
// The sleep does NOT pull in any runtime crate — it only uses
// `std::thread` and `std::time`. The future is `Send + 'static` so it
// can cross the `AsyncExecutor` type-erasure boundary, and it is
// `Unpin` so it composes inside `select!`-style macros without an
// unsafe `Pin::get_unsafe_mut`.
// -------------------------------------------------------------------------

/// Runtime-agnostic async sleep future returned by [`async_sleep`].
///
/// Polling the future for the first time spawns a single thread that
/// parks for the requested duration and wakes the registered
/// `Waker` when the deadline elapses. Subsequent polls return
/// `Poll::Pending` until the waker is invoked, at which point the
/// next poll returns `Poll::Ready(())`.
///
/// Used by the resilience decorator macros (`#[retry]`,
/// `#[rate_limit]`, `#[circuit_breaker]`) when wrapped around an
/// `async fn`. The sleep yields to the runtime for the full
/// duration, never blocks the executor thread.
#[cfg(feature = "serde")]
pub struct AsyncSleep {
    /// Deadline measured against `Instant::now()` at construction time.
    deadline: std::time::Instant,
    /// `true` once the timer thread has been spawned.
    armed: bool,
}

#[cfg(feature = "serde")]
impl AsyncSleep {
    /// Construct a sleep that completes after `dur` from "now". The
    /// caller drives the future to completion via whatever executor
    /// it has in scope (Tokio / async-std / smol / custom).
    #[must_use]
    pub fn new(dur: std::time::Duration) -> Self {
        Self {
            deadline: std::time::Instant::now() + dur,
            armed: false,
        }
    }

    /// Time remaining until the deadline elapses. Returns `Duration::ZERO`
    /// once the deadline has passed.
    pub fn remaining(&self) -> std::time::Duration {
        self.deadline
            .saturating_duration_since(std::time::Instant::now())
    }
}

#[cfg(feature = "serde")]
impl core::future::Future for AsyncSleep {
    type Output = ();
    fn poll(
        mut self: core::pin::Pin<&mut Self>,
        cx: &mut core::task::Context<'_>,
    ) -> core::task::Poll<()> {
        // If the deadline has already passed, complete immediately.
        if std::time::Instant::now() >= self.deadline {
            return core::task::Poll::Ready(());
        }
        let remaining = self.remaining();
        if !self.armed {
            // Arm the timer exactly once. The spawned thread parks
            // for `remaining` and then wakes the future's waker.
            // We `clone` the waker so the timer thread can outlive
            // the current `Context` and the future still observes
            // the wake even if it was re-polled in between.
            let waker = cx.waker().clone();
            std::thread::spawn(move || {
                std::thread::park_timeout(remaining);
                waker.wake();
            });
            self.armed = true;
        }
        core::task::Poll::Pending
    }
}

/// Sleep for `dur` without blocking the current thread.
///
/// Returns a future that completes after the given duration. The
/// future is `Send + 'static` and `Unpin`, so it composes with
/// any executor and with `select!`-style combinators.
///
/// This is the **async** counterpart to `std::thread::sleep`:
/// polling the future yields control to the runtime, which is
/// free to drive other tasks while the deadline elapses. The
/// `#[retry]`, `#[rate_limit]`, and `#[circuit_breaker]` macros
/// emit `await tokitai_core::async_sleep(...)` on `async fn`
/// bodies so that backoff between attempts does not stall a
/// runtime worker thread.
///
/// # Example
///
/// ```rust,ignore
/// use tokitai_core::async_sleep;
/// use std::time::Duration;
///
/// async fn retryable() -> Result<(), &'static str> {
///     for attempt in 1..3 {
///         match try_once().await {
///             Ok(()) => return Ok(()),
///             Err(_) if attempt < 3 => {
///                 async_sleep(Duration::from_millis(100 * attempt)).await;
///             }
///             Err(e) => return Err(e),
///         }
///     }
///     Ok(())
/// }
///
/// async fn try_once() -> Result<(), &'static str> { Ok(()) }
/// ```
#[cfg(feature = "serde")]
#[must_use]
pub fn async_sleep(dur: std::time::Duration) -> AsyncSleep {
    AsyncSleep::new(dur)
}

#[cfg(feature = "serde")]
mod executor_internal {
    use super::*;

    /// A no-op executor used as a placeholder. Registered executors must
    /// implement [`AsyncExecutor`]; this stub panics on use so an accidental
    /// `set_async_executor(Box::new(NullExecutor))` is loud rather than
    /// silently broken.
    pub struct NullExecutor;

    impl AsyncExecutor for NullExecutor {
        /// # Panics
        ///
        /// Always panics with a message instructing the caller to install
        /// a real executor via [`crate::set_async_executor`].
        fn block_on_dyn(
            &self,
            _future: core::pin::Pin<Box<dyn core::future::Future<Output = ()> + Send>>,
        ) -> Box<dyn core::any::Any + Send> {
            panic!(
                "NullExecutor::block_on_dyn invoked; \
                 install a real AsyncExecutor via set_async_executor(...)"
            )
        }
    }
}

#[cfg(feature = "serde")]
pub mod serde_types {
    //! Re-exports of `serde_json` and `alloc::string` types under a stable
    //! path. Available when the `serde` feature is enabled.

    pub use alloc::string::String;
    pub use serde_json::Value;
}

/// Compile-time helper for emitting JSON Schema strings without runtime
/// overhead.
///
/// # Example
///
/// ```rust,ignore
/// use tokitai_core::json_schema;
///
/// const SCHEMA: &str = json_schema!({
///     "city": {
///         type: String,
///         description: "Name of the city",
///         required: true,
///     }
/// });
/// ```
#[macro_export]
macro_rules! json_schema {
    (
        {
            $($param_name:literal: {
                type: $param_type:ident,
                description: $description:literal,
                required: $required:literal $(,)?
            }),*
            $(,)?
        }
    ) => {{
        const SCHEMA: &str = concat!(
            "{\"type\":\"object\",\"properties\":{",
            $({
                concat!(
                    "\"", $param_name, "\":",
                    "{\"type\":\"", $crate::ParamType::$param_type.as_str(), "\",\"description\":\"", $description, "\"}"
                )
            },)*
            "},\"required\":[",
            $({
                if $required { concat!("\"", $param_name, "\"") } else { "" }
            },)*
            "]}"
        );
        SCHEMA
    }};
}

// ===========================================================================
// T-023: per-tool capability manifest
//
// Every `#[tool]` method declares the capabilities it requires
// (`db:read:sales`, `net:egress:smtp`, etc.). The macro emits a
// per-method `CAPABILITIES_<NAME>` const plus a per-impl aggregated
// `CAPABILITIES` slice; the MCP server walks that slice at startup
// to enforce the operator-supplied allowlist.
//
// The manifest type below is the on-the-wire shape: a `Vec<(String,
// Vec<String>)>` mapping `tool_name -> required_capabilities`. The
// `Vec<String>` and `Vec<(String, Vec<String>)>` types are the
// minimum surface the server needs to read the manifest without
// pulling in any new external types. The shape is owned (not
// `&'static`) because the manifest is built at server start from
// the macro-emitted const slices; the const slice itself is
// `&'static`, but the on-the-wire `Vec` is filled with cloned
// strings for the allowlist walk.
// ===========================================================================

/// T-023: per-tool capability manifest. Each tuple is
/// `(tool_name, required_capabilities)`. The macro emits an
/// aggregated `CAPABILITIES` slice per impl block; the server
/// folds those slices into a single `CapabilityManifest` at
/// startup before walking the allowlist.
///
/// The shape is `Vec<(String, Vec<String>)>` (no new external
/// types) per the T-023 acceptance criteria. A `Vec<(String,
/// Vec<String>)>` is the minimum surface that lets the
/// `tokitai-mcp-server` enforce the allowlist without depending
/// on a third-party manifest crate (and without violating the
/// "no new top-level deps" rule).
///
/// # Example
///
/// ```rust
/// use tokitai_core::CapabilityManifest;
///
/// let manifest: CapabilityManifest = vec![
///     ("send_email".to_string(), vec!["db:read:sales".to_string(), "net:egress:smtp".to_string()]),
///     ("summarize".to_string(), vec!["db:read:sales".to_string()]),
/// ];
/// assert_eq!(manifest.len(), 2);
/// ```
pub type CapabilityManifest = alloc::vec::Vec<(
    alloc::string::String,
    alloc::vec::Vec<alloc::string::String>,
)>;

/// T-023: trait the `#[tool]` macro auto-implements for any
/// `impl` block it processes. Exposes the aggregated
/// `CAPABILITIES` slice (per-method name + per-method required
/// capability tokens) so the `tokitai-mcp-server` builder can
/// walk it at start time without depending on a per-impl
/// generated type.
///
/// The default implementation returns an empty slice (no
/// capabilities declared) so providers that did not opt in to
/// the manifest path keep working unchanged. The `#[tool]`
/// macro overrides the default to return the per-impl
/// `CAPABILITIES` slice it baked at compile time.
///
/// # Example
///
/// ```rust
/// use tokitai_core::CapabilityManifestProvider;
///
/// fn check<T: CapabilityManifestProvider>() {
///     let manifest = T::capability_manifest();
///     // walk every (method, requires) entry
///     for (tool, caps) in manifest {
///         for c in *caps {
///             // ...
///         }
///         let _ = (tool, caps);
///     }
/// }
/// ```
pub trait CapabilityManifestProvider {
    /// Return the aggregated `(tool_name, requires)` slice for
    /// this provider. The slice is `&'static` so no allocation
    /// happens on the hot path.
    fn capability_manifest() -> &'static [(&'static str, &'static [&'static str])] {
        // Default: no capabilities declared. The `#[tool]`
        // macro overrides this with the aggregated slice it
        // baked at compile time. Providers that have not been
        // processed by `#[tool]` (e.g. an empty unit struct
        // used as a placeholder) keep the empty default.
        &[]
    }
}

/// T-023: returns `true` when `declared` is covered by some entry
/// in `allowlist`. The allowlist supports one wildcard form: a
/// trailing `*` (e.g. `db:read:*`) is treated as a prefix match
/// (so `db:read:*` covers `db:read:sales`, `db:read:any_resource`,
/// and any other `db:read:<X>`). Exact entries (no `*`) must
/// match the declared capability verbatim. The matcher is
/// case-sensitive: capability tokens are typically
/// lowercase-with-colons in the documented category set, and
/// allowing case folding would weaken the allowlist contract
/// without a clear use case.
///
/// The match runs in `O(N * M)` where `N` is the number of
/// declared capabilities and `M` is the allowlist length. Both
/// are expected to be small (a few dozen entries at most), so a
/// linear scan is fine.
///
/// # Example
///
/// ```rust
/// use tokitai_core::capability_in_allowlist;
///
/// let allowlist = vec!["db:read:*".to_string(), "net:egress:smtp".to_string()];
/// assert!(capability_in_allowlist("db:read:sales", &allowlist));
/// assert!(capability_in_allowlist("net:egress:smtp", &allowlist));
/// assert!(!capability_in_allowlist("db:delete:users", &allowlist));
/// ```
pub fn capability_in_allowlist(declared: &str, allowlist: &[alloc::string::String]) -> bool {
    for entry in allowlist {
        if let Some(prefix) = entry.strip_suffix('*') {
            // Wildcard: `db:read:*` matches anything that starts
            // with `db:read:`. We require the prefix to end with
            // a `:` separator (or be empty) so a bare `*` does
            // not silently match every capability.
            if prefix.is_empty() {
                // `*` alone — match everything. Documented as a
                // valid (if risky) operator escape hatch.
                return true;
            }
            if declared.starts_with(prefix) {
                return true;
            }
        } else if entry.as_str() == declared {
            return true;
        }
    }
    false
}

#[cfg(test)]
mod capability_manifest_tests {
    use super::*;

    #[test]
    fn exact_match_succeeds() {
        let allowlist = alloc::vec!["net:egress:smtp".to_string()];
        assert!(capability_in_allowlist("net:egress:smtp", &allowlist));
    }

    #[test]
    fn exact_match_misses() {
        let allowlist = alloc::vec!["net:egress:smtp".to_string()];
        assert!(!capability_in_allowlist("net:egress:http", &allowlist));
    }

    #[test]
    fn wildcard_prefix_matches() {
        let allowlist = alloc::vec!["db:read:*".to_string()];
        assert!(capability_in_allowlist("db:read:sales", &allowlist));
        assert!(capability_in_allowlist("db:read:any_resource", &allowlist));
    }

    #[test]
    fn wildcard_prefix_does_not_match_unrelated() {
        let allowlist = alloc::vec!["db:read:*".to_string()];
        assert!(!capability_in_allowlist("db:write:sales", &allowlist));
        assert!(!capability_in_allowlist("net:egress:smtp", &allowlist));
    }

    #[test]
    fn empty_allowlist_fails_closed() {
        let allowlist: alloc::vec::Vec<alloc::string::String> = alloc::vec::Vec::new();
        assert!(!capability_in_allowlist("db:read:sales", &allowlist));
    }

    #[test]
    fn bare_star_matches_anything() {
        let allowlist = alloc::vec!["*".to_string()];
        assert!(capability_in_allowlist("db:read:sales", &allowlist));
        assert!(capability_in_allowlist("process:exec", &allowlist));
    }
}

// ===========================================================================
// T-024: cross-crate version assertion
//
// A `tokitai-core` consumer pinned to one minor line (say `0.7`) can
// silently drift against another consumer (a third-party crate) that
// pinned a different line (say `0.8`): both compile, but the agent sees
// a tool shape from one version and a call site from the other. The
// fix is structural:
//   1. A compile-time `pub const CORE_VERSION` carrying the exact
//      version of `tokitai-core` that was compiled in (via
//      `env!("CARGO_PKG_VERSION")`). Consumers re-export this from
//      their own build script to compare against their pinned version.
//   2. A `pub const fn assert_compatible_with(expected: &str)` whose
//      body is a `const {}` block. When the function is called from a
//      downstream crate inside a `const` context, a mismatch raises a
//      `compile_error!` naming both versions and the docs.rs migration
//      link. Match rule: exact match for `x.y.z`, prefix match for
//      `x.y` or `x` (e.g. `0.8` matches `0.8.1`).
// ===========================================================================

/// T-024: exact version string of `tokitai-core` that was compiled in
/// (sourced from `CARGO_PKG_VERSION`). The mcp-server build script
/// writes a generated source file with this constant so the running
/// binary can compare against the version that was baked at compile
/// time.
///
/// # Example
///
/// ```rust
/// use tokitai_core::CORE_VERSION;
///
/// let _v: &str = CORE_VERSION;
/// assert!(!CORE_VERSION.is_empty());
/// ```
pub const CORE_VERSION: &str = env!("CARGO_PKG_VERSION");

/// T-024: assert at compile time that the compiled-against
/// `tokitai-core` matches the expected SemVer string under the
/// standard prefix-match rule (`x.y` matches `x.y.z`; `x.y.z` matches
/// exactly). A mismatch raises a `compile_error!` naming both
/// versions and the docs.rs migration link.
///
/// The function is `pub const fn` so the check runs in the caller's
/// `const` context. When called outside a `const` context the check
/// still runs but produces a runtime panic instead of a compile error.
///
/// # Match rule (canonical SemVer)
///
/// | `expected` | `CORE_VERSION` | result |
/// |------------|------------------|--------|
/// | `"0.8.1"`  | `"0.8.1"`        | passes (exact) |
/// | `"0.8"`    | `"0.8.1"`        | passes (prefix) |
/// | `"0.8.1"`  | `"0.8.2"`        | fails |
/// | `"0.9"`    | `"0.8.1"`        | fails |
///
/// # Example (positive)
///
/// ```rust
/// use tokitai_core::assert_compatible_with;
///
/// // Inside your own crate, gated by a `const _: () = ...;` block
/// // so the check fires at compile time:
/// const _: () = {
///     tokitai_core::assert_compatible_with("0.6");
/// };
/// ```
///
/// # Negative example (cross-crate drift)
///
/// A consumer crate that pins `tokitai = "0.7"` and calls
/// `assert_compatible_with("0.8")` would fail to compile with a
/// diagnostic naming both versions and pointing at the docs.rs
/// migration guide. The compile-time guarantee is the whole point
/// of T-024 — drift surfaces before the binary ever runs.
pub const fn assert_compatible_with(expected: &str) {
    // T-024: keep the panic message static so it can be reached
    // inside a `const fn`. Dynamic formatters are not const-stable
    // for non-`'static` references, so we parse the version
    // components inline (no `semver::Version::parse`, which is not
    // a `const fn` in the `semver` crate today) and produce a
    // static drift-category message on mismatch.
    //
    // Match rule (canonical SemVer): 1 component matches any on
    // the same major; 2 components match any on the same
    // major.minor; 3 components must match exactly. The
    // pre-release / build suffix is ignored for ordering.
    //
    // When called from a `const _: () = assert_compatible_with("0.8")`
    // context inside a downstream crate, the compiler evaluates
    // this function at compile time. A mismatch surfaces as a
    // `compile_error!` naming the drift category and the docs.rs
    // migration guide link. When called from a runtime context the
    // same panic fires at run time, which is the documented
    // fallback.

    // Strip the optional `v`/`V` prefix from `expected`.
    let expected_bytes = expected.as_bytes();
    let mut exp_offset: usize = 0;
    let mut exp_new_len = expected_bytes.len();
    if !expected_bytes.is_empty() {
        let first = expected_bytes[0];
        if first == b'v' || first == b'V' {
            exp_offset = 1;
            exp_new_len = expected_bytes.len() - 1;
        }
    }
    let expected_tail = unsafe {
        core::slice::from_raw_parts(expected_bytes.as_ptr().add(exp_offset), exp_new_len)
    };
    // SAFETY: `expected_tail` is a sub-slice of a valid `&str`;
    // the `v`/`V` prefix is single-byte ASCII so removing it
    // cannot break UTF-8 invariants.
    let expected_str = unsafe { core::str::from_utf8_unchecked(expected_tail) };

    // Strip the optional `v`/`V` prefix from `CORE_VERSION`.
    let core_bytes = CORE_VERSION.as_bytes();
    let mut core_offset: usize = 0;
    let mut core_new_len = core_bytes.len();
    if !core_bytes.is_empty() {
        let first = core_bytes[0];
        if first == b'v' || first == b'V' {
            core_offset = 1;
            core_new_len = core_bytes.len() - 1;
        }
    }
    let core_tail =
        unsafe { core::slice::from_raw_parts(core_bytes.as_ptr().add(core_offset), core_new_len) };
    let core_str_stripped = unsafe { core::str::from_utf8_unchecked(core_tail) };

    // Inline SemVer parser (const-stable). Returns the three
    // numeric components and the textual arity. A non-numeric
    // byte inside a component is a parse failure (returns the
    // `Err` arm). The pre-release / build suffix is stripped
    // before parsing so the ordering matches the canonical
    // SemVer 2.0 rule (build metadata ignored for comparison).
    let expected_parts = parse_semver_const(expected_str);
    let core_parts = parse_semver_const(core_str_stripped);

    match (expected_parts, core_parts) {
        (Some(ep), Some(cp)) => {
            let (emaj, emin, epat, eary) = ep;
            let (cmaj, cmin, cpat, _) = cp;
            let _ = cpat; // silence unused-when-not-3 warning
                          // 3-arity requires exact patch match; 2-arity skips
                          // the patch check; 1-arity skips minor and patch.
                          // We always check the major. The arity was computed
                          // from the textual form of `expected` (1, 2, or 3
                          // numeric components).
            if eary >= 1 && cmaj != emaj {
                panic!(concat!(
                    "tokitai-core version mismatch: major drift. ",
                    "compiled CORE_VERSION=",
                    env!("CARGO_PKG_VERSION"),
                    " differs from the caller's `expected` argument on the major component. ",
                    "See https://docs.rs/tokitai-core for the migration guide."
                ));
            }
            if eary >= 2 && cmin != emin {
                panic!(concat!(
                    "tokitai-core version mismatch: minor drift. ",
                    "compiled CORE_VERSION=",
                    env!("CARGO_PKG_VERSION"),
                    " differs from the caller's `expected` argument on the minor component. ",
                    "See https://docs.rs/tokitai-core for the migration guide."
                ));
            }
            if eary >= 3 && cpat != epat {
                panic!(concat!(
                    "tokitai-core version mismatch: patch drift. ",
                    "compiled CORE_VERSION=",
                    env!("CARGO_PKG_VERSION"),
                    " differs from the caller's `expected` argument on the patch component. ",
                    "See https://docs.rs/tokitai-core for the migration guide."
                ));
            }
        }
        _ => {
            // Either side failed to parse. A malformed expected is
            // a typo; a malformed core is an internal
            // inconsistency. Either way, fail loud rather than
            // silently passing.
            panic!(concat!(
                "tokitai-core version mismatch: invalid SemVer literal. ",
                "compiled CORE_VERSION=",
                env!("CARGO_PKG_VERSION"),
                " (one or both sides failed to parse). ",
                "See https://docs.rs/tokitai-core for the migration guide."
            ));
        }
    }
}

/// T-028: non-const runtime companion to [`assert_compatible_with`].
///
/// Same check as the `const fn`, but the panic message uses
/// `format!()` so it can include *both* the `expected` argument and
/// the actual `CORE_VERSION` verbatim. Use this from runtime call
/// sites (typically `fn main` of a downstream binary) when you want
/// the on-panic message to read like
/// `tokitai-core version mismatch: expected="0.7", actual="0.8.1" (major drift)`
/// rather than the static-category message the `const fn` panic
/// emits.
///
/// For the compile-time const-eval use case (`const _: () =
/// assert_compatible_with("...");`) the `const fn` is still the
/// right entry point - `const_format_args!` is not stable, so the
/// `const fn` panic message cannot interpolate runtime strings.
pub fn assert_compatible_with_runtime(expected: &str) {
    // Re-parse both sides so the drift classification matches.
    let expected_str = expected
        .strip_prefix('v')
        .or_else(|| expected.strip_prefix('V'))
        .unwrap_or(expected);
    let core_str_stripped = CORE_VERSION
        .strip_prefix('v')
        .or_else(|| CORE_VERSION.strip_prefix('V'))
        .unwrap_or(CORE_VERSION);
    let expected_parts = parse_semver_const(expected_str);
    let core_parts = parse_semver_const(core_str_stripped);
    match (expected_parts, core_parts) {
        (Some(ep), Some(cp)) => {
            let (emaj, emin, epat, eary) = ep;
            let (cmaj, cmin, cpat, _) = cp;
            if eary >= 1 && cmaj != emaj {
                panic!(
                    "tokitai-core version mismatch: expected={}, actual={} (major drift). See https://docs.rs/tokitai-core for the migration guide.",
                    expected, CORE_VERSION
                );
            }
            if eary >= 2 && cmin != emin {
                panic!(
                    "tokitai-core version mismatch: expected={}, actual={} (minor drift). See https://docs.rs/tokitai-core for the migration guide.",
                    expected, CORE_VERSION
                );
            }
            if eary >= 3 && cpat != epat {
                panic!(
                    "tokitai-core version mismatch: expected={}, actual={} (patch drift). See https://docs.rs/tokitai-core for the migration guide.",
                    expected, CORE_VERSION
                );
            }
        }
        _ => panic!(
            "tokitai-core version mismatch: expected={}, actual={} (invalid SemVer literal on one or both sides). See https://docs.rs/tokitai-core for the migration guide.",
            expected, CORE_VERSION
        ),
    }
}

/// T-024: const-stable SemVer prefix parser. Returns
/// `(major, minor, patch, arity)` when the input parses as
/// `x[.y[.z]]` (each component is a sequence of ASCII digits;
/// pre-release `-...` and build `+...` suffixes are accepted and
/// ignored). `arity` is the number of numeric components found
/// in the textual form (1, 2, or 3).
///
/// Returns `None` when:
/// * the input is empty,
/// * any component is non-numeric,
/// * there are more than three components,
/// * or a component has leading `0` followed by another digit
///   (canonical SemVer disallows this; we enforce it so the
///   comparison is well-defined).
const fn parse_semver_const(s: &str) -> Option<(u64, u64, u64, usize)> {
    let bytes = s.as_bytes();
    let mut i: usize = 0;
    let mut parts: [u64; 3] = [0, 0, 0];
    let mut arity: usize = 0;
    let mut end = bytes.len();
    if end == 0 {
        return None;
    }
    // Strip pre-release / build metadata.
    while i < end {
        let b = bytes[i];
        if b == b'-' || b == b'+' {
            end = i;
            break;
        }
        i += 1;
    }
    i = 0;
    while i <= end {
        let at_end = i == end;
        let is_dot = !at_end && bytes[i] == b'.';
        if at_end || is_dot {
            // Empty component (e.g. ".0" or trailing ".") -> parse
            // failure.
            if i == 0 {
                return None;
            }
            if bytes[i - 1] == b'.' {
                return None;
            }
            if arity >= 3 {
                return None;
            }
            arity += 1;
            if at_end {
                break;
            }
        } else {
            let b = bytes[i];
            if b < b'0' || b > b'9' {
                return None;
            }
            // Reject leading-zero components (`01`) so the
            // ordering is unambiguous. A "leading zero" is a `0`
            // at the very start of a component that is followed
            // by another digit before the next `.` or end.
            if b == b'0' {
                let prev_is_dot = i == 0 || bytes[i - 1] == b'.';
                if prev_is_dot {
                    let next_is_dot_or_end = i + 1 == end || bytes[i + 1] == b'.';
                    if !next_is_dot_or_end {
                        return None;
                    }
                }
            }
            // Refuse to accumulate a fourth component. We must
            // check this BEFORE writing `parts[arity]`, otherwise
            // an input like "0.0.0.0" would silently index past
            // the end of the `parts` array and panic in const
            // context. The `.`-terminated case is caught by the
            // `arity >= 3` guard above; the digit case (no dot
            // before the 4th component) needs its own guard.
            if arity >= 3 {
                return None;
            }
            // Accumulate into the current component. We are
            // guaranteed `arity < 3` because we early-return above
            // when arity would reach 3, and we increment AFTER the
            // component ends (`.` or EOF).
            let slot = &mut parts[arity];
            let mul = match slot.checked_mul(10) {
                Some(v) => v,
                None => return None,
            };
            let add = match mul.checked_add((b - b'0') as u64) {
                Some(v) => v,
                None => return None,
            };
            *slot = add;
        }
        i += 1;
    }
    Some((parts[0], parts[1], parts[2], arity))
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_param_type_from_rust_type() {
        assert_eq!(ParamType::from_rust_type("String"), Some(ParamType::String));
        assert_eq!(ParamType::from_rust_type("i32"), Some(ParamType::Integer));
        assert_eq!(ParamType::from_rust_type("f64"), Some(ParamType::Number));
        assert_eq!(ParamType::from_rust_type("bool"), Some(ParamType::Boolean));
        assert_eq!(
            ParamType::from_rust_type("Vec<i32>"),
            Some(ParamType::Array)
        );
    }

    #[test]
    fn test_tool_definition_const() {
        let tool = ToolDefinition::new("test", "A test tool", "{}");
        assert_eq!(tool.name, "test");
        assert_eq!(tool.description, "A test tool");
    }

    /// C-1: `parse_semver_const` must reject anything with more
    /// than three numeric components. The pre-fix code only
    /// guarded the `.`-terminated branch (`if arity >= 3`),
    /// leaving a hole: an input like `"0.0.0.0"` reaches the
    /// fourth digit, falls into the digit-accumulation branch,
    /// and writes `parts[arity]` with `arity == 3`, panicking
    /// in const context.
    #[test]
    fn parse_semver_const_rejects_extra_component() {
        assert_eq!(parse_semver_const("0.0.0.0"), None);
        assert_eq!(parse_semver_const("1.2.3.4"), None);
        assert_eq!(parse_semver_const("0.5.1.2.3"), None);
        // Sanity: 3-component inputs still parse.
        assert_eq!(parse_semver_const("0.5.1"), Some((0, 5, 1, 3)));
    }

    #[cfg(feature = "serde")]
    #[test]
    fn test_tool_definition_to_json() {
        let tool = ToolDefinition::new("test", "A test tool", r#"{"type":"object"}"#);
        let json = tool.to_json().unwrap();
        assert!(json.contains(r#""name":"test""#));
    }

    // -----------------------------------------------------------------
    // AsyncExecutor unit tests
    //
    // The three scenarios the executor must cover are exercised in a
    // single `#[test]` so the order is deterministic. Splitting them
    // into three `#[test]` functions would not be reliable here:
    // libtest runs tests in alphabetical order, and the global
    // `ASYNC_EXECUTOR` slot is a `OnceLock` that can only be populated
    // once per process. A fresh-process test for the "no executor"
    // case is provided separately in
    // `tests/async_executor_no_executor_test.rs`.
    // -----------------------------------------------------------------

    /// Minimal test executor that drives a boxed future to completion via
    /// `futures::executor::block_on`. The output of the wrapped future is
    /// not used here because the typed `AsyncExecutorExt::block_on` reads
    /// the output from a shared slot.
    #[cfg(feature = "serde")]
    struct TestExecutor;

    #[cfg(feature = "serde")]
    impl AsyncExecutor for TestExecutor {
        fn block_on_dyn(
            &self,
            future: core::pin::Pin<Box<dyn core::future::Future<Output = ()> + Send>>,
        ) -> Box<dyn core::any::Any + Send> {
            futures::executor::block_on(future);
            Box::new(())
        }
    }

    /// Single-threaded executor used by the async-executor tests. We use
    /// `futures::executor::block_on` (no Tokio) so the suite can run
    /// without a Tokio runtime.
    #[cfg(feature = "serde")]
    #[test]
    #[serial_test::serial]
    fn test_async_executor_lifecycle() {
        // Step 1: in a fresh process the `OnceLock` is empty, so a
        // call to `block_on_async` returns the standard English
        // error. (We use a best-effort assertion: if a prior test in
        // the same binary has already set the executor, skip this
        // sub-assertion; the dedicated
        // `async_executor_no_executor_test.rs` integration test
        // exercises this path in a fresh process.)
        if current_async_executor().is_none() {
            let result: Result<(), ToolError> = block_on_async(async {});
            let err = result
                .expect_err("block_on_async should error when no AsyncExecutor is registered");
            assert_eq!(err.kind, ToolErrorKind::InternalError);
            let expected = block_on_async_error_message();
            assert!(
                err.message.contains(expected) || err.message.contains("no async runtime"),
                "expected English error message, got: {:?}",
                err.message
            );
        }

        // Step 2: register a custom executor and verify
        // `current_async_executor` returns it.
        set_async_executor(Box::new(TestExecutor));
        let exec = current_async_executor().expect("executor should be registered");
        // Sanity check: it is a `&'static dyn AsyncExecutor`.
        let _static_ref: &'static dyn AsyncExecutor = exec;

        // Step 3: drive a future with a `String` output through the
        // typed `AsyncExecutorExt::block_on` wrapper.
        let string_result: String = exec.block_on(async { String::from("hello, executor") });
        assert_eq!(string_result, "hello, executor");

        // Step 4: drive a future with a non-`()` typed output
        // (`(i32, String)`) through the type-erased `block_on_dyn`
        // boundary and back. This is the
        // `test_async_executor_typed_output` scenario.
        let tuple_result: (i32, String) = exec.block_on(async { (42, String::from("typed")) });
        assert_eq!(tuple_result, (42, String::from("typed")));
    }
}