areev 0.2.0

//! `Tools` resource — Tool grain lifecycle + invocation.
//!
//! Mirrors the Python SDK's `client.tools.*` surface: `bind`, `list`,
//! `unbind`, `invoke`, `parse`, `wait_for_resolution`.
//!
//! Two execution flows share this resource:
//!
//! - **Sync**: `invoke()` returns `{"status": "completed", "result": …}`
//!   directly.
//! - **Async**: `invoke()` returns `{"status": "pending",
//!   "audit_grain_id": …}`; the caller then polls with
//!   [`Tools::wait_for_resolution`] until the audit grain reaches
//!   `completed` or `failed`.

use std::time::{Duration, Instant};

use serde_json::{json, Map, Value};

use crate::error::{AreevError, Result};
use crate::http::HttpClient;
use crate::resources::connectors::Connectors;

/// Tool grain lifecycle + invocation.
///
/// Access via [`crate::Areev::tools`].
pub struct Tools<'a> {
    http: &'a HttpClient,
    memory_id: String,
}

impl<'a> Tools<'a> {
    /// Internal constructor — use [`crate::Areev::tools`].
    pub(crate) fn new(http: &'a HttpClient, memory_id: String) -> Self {
        Self { http, memory_id }
    }

    /// Start a [`BindBuilder`] for binding a tool to a harness.
    ///
    /// Chain optional knobs (`output_schema`, `description`, …) and
    /// call `send()`.
    pub fn bind<'b>(
        &'b self,
        slug: &str,
        executor: Value,
        param_schema: Value,
    ) -> BindBuilder<'b, 'a> {
        BindBuilder::new(self, slug, executor, param_schema)
    }

    /// Bind an Axtion connector action as a tool — schema fetched for you.
    ///
    /// Looks up `action`'s parameter schema from the connector catalog (so
    /// the caller never hand-writes JSON Schema), then binds it with an
    /// Axtion executor (`{"type": "axtion", "connector": …, "action": …}`).
    /// `action` is the action *key* (e.g. `"send-email"`), as returned by
    /// [`Connectors::actions`]`(connector)[*].name`.
    ///
    /// ```no_run
    /// # #[tokio::main]
    /// # async fn main() -> areev::Result<()> {
    /// let areev = areev::Areev::from_env();
    /// areev
    ///     .tools()
    ///     .bind_axtion("sales-bot", "gmail", "send-email")
    ///     .description("Send an email via Gmail")
    ///     .send()
    ///     .await?;
    /// # Ok(())
    /// # }
    /// ```
    ///
    /// # Errors
    ///
    /// The returned builder's `send()` raises [`AreevError::NotFound`]
    /// (`SDK-E010`) — listing the available actions — when `action` is not
    /// in the connector's catalog.
    pub fn bind_axtion<'b>(
        &'b self,
        slug: &str,
        connector: &str,
        action: &str,
    ) -> BindAxtionBuilder<'b, 'a> {
        BindAxtionBuilder::new(self, slug, connector, action)
    }

    /// List all bound tools on a harness.
    ///
    /// Returns the raw server response:
    /// `{"harness_slug", "namespace", "hipaa_active", "tools": [...]}`
    /// where each tool entry has `tool_hash`, `tool_id`,
    /// `description`, `axtion_uri`, `baa_ok`, etc.
    pub async fn list(&self, slug: &str) -> Result<Value> {
        let path = format!("/memories/{}/harnesses/{}/tools", self.memory_id, slug);
        self.http._get(&path, None).await
    }

    /// Remove a bound tool from a harness.
    ///
    /// Pass either `tool_id` (human-readable — will be resolved to
    /// `tool_hash` via [`Tools::list`]) or `tool_hash` directly.
    /// Returns `Ok(())` on success; raises
    /// [`AreevError::Validation`] if neither is provided, and
    /// [`AreevError::NotFound`] if the tool isn't bound.
    pub async fn unbind(
        &self,
        slug: &str,
        tool_id: Option<&str>,
        tool_hash: Option<&str>,
    ) -> Result<()> {
        if tool_id.is_none() && tool_hash.is_none() {
            return Err(AreevError::Validation {
                code: Some("SDK-E001".to_string()),
                http_status: 400,
                message: "tools.unbind requires either tool_id or tool_hash".to_string(),
                body: Value::Null,
                request_id: None,
            });
        }

        let hash = match tool_hash {
            Some(h) => h.to_string(),
            None => {
                // Safe: tool_id is Some when tool_hash is None (validated above).
                let target = tool_id.unwrap();
                let listing = self.list(slug).await?;
                let tools = listing
                    .get("tools")
                    .and_then(|v| v.as_array())
                    .cloned()
                    .unwrap_or_default();
                let found = tools.iter().find(|t| {
                    t.get("tool_id")
                        .and_then(|v| v.as_str())
                        .map(|s| s == target)
                        .unwrap_or(false)
                });
                let Some(entry) = found else {
                    return Err(AreevError::NotFound {
                        code: Some("SDK-E011".to_string()),
                        http_status: 404,
                        message: format!(
                            "no bound tool with tool_id={target:?} on harness {slug:?}"
                        ),
                        body: Value::Null,
                        request_id: None,
                    });
                };
                entry
                    .get("tool_hash")
                    .and_then(|v| v.as_str())
                    .ok_or_else(|| AreevError::Other {
                        http_status: 0,
                        code: None,
                        message: format!(
                            "tool listing for tool_id={target:?} is missing tool_hash"
                        ),
                        body: Value::Null,
                        request_id: None,
                    })?
                    .to_string()
            }
        };

        let path = format!(
            "/memories/{}/harnesses/{}/tools/{}",
            self.memory_id, slug, hash
        );
        self.http._delete(&path).await.map(|_| ())
    }

    /// Start an [`InvokeBuilder`] for the given tool.
    pub fn invoke<'b>(&'b self, slug: &str, tool_id: &str, args: Value) -> InvokeBuilder<'b, 'a> {
        InvokeBuilder::new(self, slug, tool_id, args)
    }

    /// Parse LLM output into tool calls.
    ///
    /// `format` is **required by the server** and must be one of:
    /// `openai-tools`, `openai-responses`, `anthropic-tools`,
    /// `gemini-tools`, `mcp-tools`, `hermes`, `llama31`, `markdown-tools`,
    /// `sml-tools`. Any other value (including `auto`) is rejected with
    /// HTTP 400 `MEM-E107`. An empty string defaults to `openai-tools`.
    pub async fn parse(&self, text: &str, format: &str) -> Result<Value> {
        let fmt = if format.is_empty() {
            "openai-tools"
        } else {
            format
        };
        let body = json!({ "raw_output": text, "format": fmt });
        self.http._post("/v1/tools/parse", Some(&body)).await
    }

    /// Poll an async Pending audit grain until it resolves to
    /// `completed` / `failed`.
    ///
    /// Returns the resolved grain. Raises [`AreevError::Other`] with
    /// `http_status = 408` if the deadline is hit (so it surfaces
    /// through the same `AreevError` match arms as other timeouts).
    pub async fn wait_for_resolution(
        &self,
        audit_grain_id: &str,
        timeout_s: f64,
        poll_interval_s: f64,
    ) -> Result<Value> {
        let deadline = Instant::now() + Duration::from_secs_f64(timeout_s);
        let poll = Duration::from_secs_f64(poll_interval_s.max(0.05));
        loop {
            let path = format!("/memories/{}/grains/{}", self.memory_id, audit_grain_id);
            let grain = self.http._get(&path, None).await?;
            let status = grain.get("status").and_then(|v| v.as_str()).or_else(|| {
                grain
                    .get("fields")
                    .and_then(|f| f.get("status"))
                    .and_then(|v| v.as_str())
            });
            if matches!(status, Some("completed") | Some("failed")) {
                return Ok(grain);
            }
            if Instant::now() >= deadline {
                return Err(AreevError::Other {
                    http_status: 408,
                    code: Some("SDK-E408".to_string()),
                    message: format!(
                        "pending grain {audit_grain_id} not resolved within {timeout_s}s"
                    ),
                    body: Value::Null,
                    request_id: None,
                });
            }
            tokio::time::sleep(poll).await;
        }
    }
}

/// Builder for [`Tools::bind`].
pub struct BindBuilder<'b, 'a> {
    tools: &'b Tools<'a>,
    slug: String,
    body: Map<String, Value>,
}

impl<'b, 'a> BindBuilder<'b, 'a> {
    fn new(tools: &'b Tools<'a>, slug: &str, executor: Value, param_schema: Value) -> Self {
        let mut body = Map::new();
        body.insert("executor".to_string(), executor);
        body.insert("description".to_string(), Value::String(String::new()));
        body.insert("param_schema".to_string(), param_schema);
        body.insert("output_schema".to_string(), json!({ "type": "object" }));
        body.insert("locked_params".to_string(), Value::Object(Map::new()));
        body.insert("async_mode".to_string(), Value::Bool(false));
        body.insert("examples".to_string(), Value::Array(Vec::new()));
        Self {
            tools,
            slug: slug.to_string(),
            body,
        }
    }

    /// Override the tool's `output_schema` (default `{ "type": "object" }`).
    pub fn output_schema(mut self, schema: Value) -> Self {
        self.body.insert("output_schema".to_string(), schema);
        self
    }

    /// Set a human-readable description (default empty).
    pub fn description(mut self, description: &str) -> Self {
        self.body.insert(
            "description".to_string(),
            Value::String(description.to_string()),
        );
        self
    }

    /// Pin server-side parameter values (cannot be overridden by the LLM).
    pub fn locked_params(mut self, locked: Value) -> Self {
        self.body.insert("locked_params".to_string(), locked);
        self
    }

    /// Mark the tool as long-running — invocations return `pending`
    /// and resolve asynchronously.
    pub fn async_mode(mut self, async_mode: bool) -> Self {
        self.body
            .insert("async_mode".to_string(), Value::Bool(async_mode));
        self
    }

    /// Provide few-shot examples surfaced to the LLM.
    pub fn examples(mut self, examples: Vec<Value>) -> Self {
        self.body
            .insert("examples".to_string(), Value::Array(examples));
        self
    }

    /// Server-supplied spec hash for the tool definition.
    pub fn spec_hash(mut self, spec_hash: &str) -> Self {
        self.body.insert(
            "spec_hash".to_string(),
            Value::String(spec_hash.to_string()),
        );
        self
    }

    /// Issue the bind request.
    pub async fn send(self) -> Result<Value> {
        let path = format!(
            "/memories/{}/harnesses/{}/tools",
            self.tools.memory_id, self.slug
        );
        self.tools
            .http
            ._post(&path, Some(&Value::Object(self.body)))
            .await
    }
}

/// Builder for [`Tools::bind_axtion`].
///
/// Defers the connector-catalog schema lookup to [`Self::send`] (the
/// `actions()` call is async). Chain `description` / `locked_params` /
/// `async_mode` like [`BindBuilder`], then `send()`.
pub struct BindAxtionBuilder<'b, 'a> {
    tools: &'b Tools<'a>,
    slug: String,
    connector: String,
    action: String,
    description: Option<String>,
    locked_params: Option<Value>,
    async_mode: bool,
}

impl<'b, 'a> BindAxtionBuilder<'b, 'a> {
    fn new(tools: &'b Tools<'a>, slug: &str, connector: &str, action: &str) -> Self {
        Self {
            tools,
            slug: slug.to_string(),
            connector: connector.to_string(),
            action: action.to_string(),
            description: None,
            locked_params: None,
            async_mode: false,
        }
    }

    /// Override the tool description (defaults to the action's catalog
    /// description when unset).
    pub fn description(mut self, description: &str) -> Self {
        self.description = Some(description.to_string());
        self
    }

    /// Pin server-side parameter values (cannot be overridden by the LLM).
    pub fn locked_params(mut self, locked: Value) -> Self {
        self.locked_params = Some(locked);
        self
    }

    /// Mark the tool as long-running — invocations return `pending` and
    /// resolve asynchronously.
    pub fn async_mode(mut self, async_mode: bool) -> Self {
        self.async_mode = async_mode;
        self
    }

    /// Look up the action's schema, then issue the bind request.
    pub async fn send(self) -> Result<Value> {
        let connectors = Connectors::new(self.tools.http);
        let descriptors = connectors.actions(&self.connector).await?;
        let Some(matched) = descriptors.iter().find(|d| d.name == self.action) else {
            let available = if descriptors.is_empty() {
                "(none)".to_string()
            } else {
                descriptors
                    .iter()
                    .map(|d| d.name.as_str())
                    .collect::<Vec<_>>()
                    .join(", ")
            };
            return Err(AreevError::NotFound {
                code: Some("SDK-E010".to_string()),
                http_status: 404,
                message: format!(
                    "connector {:?} has no action {:?}; available: {available}",
                    self.connector, self.action
                ),
                body: Value::Null,
                request_id: None,
            });
        };

        let param_schema = if matched.param_schema.is_null() {
            json!({ "type": "object" })
        } else {
            matched.param_schema.clone()
        };
        let executor = json!({
            "type": "axtion",
            "connector": self.connector,
            "action": self.action,
        });
        let description = self
            .description
            .unwrap_or_else(|| matched.description.clone());

        let mut builder = self
            .tools
            .bind(&self.slug, executor, param_schema)
            .description(&description)
            .async_mode(self.async_mode);
        if let Some(locked) = self.locked_params {
            builder = builder.locked_params(locked);
        }
        builder.send().await
    }
}

/// Builder for [`Tools::invoke`].
pub struct InvokeBuilder<'b, 'a> {
    tools: &'b Tools<'a>,
    slug: String,
    body: Map<String, Value>,
}

impl<'b, 'a> InvokeBuilder<'b, 'a> {
    fn new(tools: &'b Tools<'a>, slug: &str, tool_id: &str, args: Value) -> Self {
        let mut body = Map::new();
        body.insert("tool_name".to_string(), Value::String(tool_id.to_string()));
        body.insert("arguments".to_string(), args);
        Self {
            tools,
            slug: slug.to_string(),
            body,
        }
    }

    /// Tie this invocation to an existing Flow-B session.
    pub fn session_id(mut self, session_id: &str) -> Self {
        self.body.insert(
            "session_id".to_string(),
            Value::String(session_id.to_string()),
        );
        self
    }

    /// Mark this invocation as the final answer — short-circuits the
    /// LLM loop on the cell side.
    pub fn final_answer(mut self, final_answer: bool) -> Self {
        self.body
            .insert("final_answer".to_string(), Value::Bool(final_answer));
        self
    }

    /// Issue the invoke request.
    pub async fn send(self) -> Result<Value> {
        let path = format!(
            "/memories/{}/harnesses/{}/tools/invoke",
            self.tools.memory_id, self.slug
        );
        self.tools
            .http
            ._post(&path, Some(&Value::Object(self.body)))
            .await
    }
}