agent-client-protocol 0.11.0

//! Capability management for the `_meta.symposium` object in ACP messages.
//!
//! This module provides traits and types for working with capabilities stored in
//! the `_meta.symposium` field of `InitializeRequest` and `InitializeResponse`.
//!
//! # Example
//!
//! ```rust,no_run
//! use agent_client_protocol::{MetaCapabilityExt, McpAcpTransport};
//! # use agent_client_protocol::schema::InitializeResponse;
//! # let init_response: InitializeResponse = unimplemented!();
//!
//! let response = init_response.add_meta_capability(McpAcpTransport);
//! if response.has_meta_capability(McpAcpTransport) {
//!     // Agent supports MCP-over-ACP bridging
//! }
//! ```

use crate::schema::{InitializeRequest, InitializeResponse};
use serde_json::json;

/// Trait for capabilities stored in the `_meta.symposium` object.
///
/// Capabilities are key-value pairs that signal features or context to components
/// in the proxy chain. Implement this trait to define new capabilities.
pub trait MetaCapability {
    /// The key name in the `_meta.symposium` object (e.g., "proxy", "mcp_acp_transport")
    fn key(&self) -> &'static str;

    /// The value to set when adding this capability (defaults to `true`)
    fn value(&self) -> serde_json::Value {
        serde_json::Value::Bool(true)
    }
}

/// The mcp_acp_transport capability - indicates support for MCP-over-ACP bridging.
///
/// When present in `_meta.symposium.mcp_acp_transport`, signals that the agent
/// supports having MCP servers with `acp:UUID` transport proxied through the conductor.
#[derive(Debug)]
pub struct McpAcpTransport;

impl MetaCapability for McpAcpTransport {
    fn key(&self) -> &'static str {
        "mcp_acp_transport"
    }
}

/// Extension trait for checking and modifying capabilities in `InitializeRequest`.
pub trait MetaCapabilityExt {
    /// Check if a capability is present in `_meta.symposium`
    fn has_meta_capability(&self, capability: impl MetaCapability) -> bool;

    /// Add a capability to `_meta.symposium`, creating the structure if needed
    #[must_use]
    fn add_meta_capability(self, capability: impl MetaCapability) -> Self;

    /// Remove a capability from `_meta.symposium` if present
    #[must_use]
    fn remove_meta_capability(self, capability: impl MetaCapability) -> Self;
}

impl MetaCapabilityExt for InitializeRequest {
    fn has_meta_capability(&self, capability: impl MetaCapability) -> bool {
        self.client_capabilities
            .meta
            .as_ref()
            .and_then(|meta| meta.get("symposium"))
            .and_then(|symposium| symposium.get(capability.key()))
            .is_some()
    }

    fn add_meta_capability(mut self, capability: impl MetaCapability) -> Self {
        let meta = self
            .client_capabilities
            .meta
            .get_or_insert_with(Default::default);

        let symposium = meta.entry("symposium").or_insert_with(|| json!({}));

        if let Some(symposium_obj) = symposium.as_object_mut() {
            symposium_obj.insert("version".to_string(), json!("1.0"));
            symposium_obj.insert(capability.key().to_string(), capability.value());
        }

        self
    }

    fn remove_meta_capability(mut self, capability: impl MetaCapability) -> Self {
        if let Some(ref mut meta) = self.client_capabilities.meta
            && let Some(symposium) = meta.get_mut("symposium")
            && let Some(symposium_obj) = symposium.as_object_mut()
        {
            symposium_obj.remove(capability.key());
        }
        self
    }
}

impl MetaCapabilityExt for InitializeResponse {
    fn has_meta_capability(&self, capability: impl MetaCapability) -> bool {
        self.agent_capabilities
            .meta
            .as_ref()
            .and_then(|meta| meta.get("symposium"))
            .and_then(|symposium| symposium.get(capability.key()))
            .is_some()
    }

    fn add_meta_capability(mut self, capability: impl MetaCapability) -> Self {
        let meta = self
            .agent_capabilities
            .meta
            .get_or_insert_with(Default::default);

        let symposium = meta.entry("symposium").or_insert_with(|| json!({}));

        if let Some(symposium_obj) = symposium.as_object_mut() {
            symposium_obj.insert("version".to_string(), json!("1.0"));
            symposium_obj.insert(capability.key().to_string(), capability.value());
        }

        self
    }

    fn remove_meta_capability(mut self, capability: impl MetaCapability) -> Self {
        if let Some(ref mut meta) = self.agent_capabilities.meta
            && let Some(symposium) = meta.get_mut("symposium")
            && let Some(symposium_obj) = symposium.as_object_mut()
        {
            symposium_obj.remove(capability.key());
        }
        self
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::schema::{ClientCapabilities, ProtocolVersion};
    use serde_json::json;

    #[test]
    fn test_add_capability_to_request() {
        let request = InitializeRequest::new(ProtocolVersion::LATEST);

        let request = request.add_meta_capability(McpAcpTransport);

        assert!(request.has_meta_capability(McpAcpTransport));
        assert_eq!(
            request.client_capabilities.meta.as_ref().unwrap()["symposium"]["mcp_acp_transport"],
            json!(true)
        );
    }

    #[test]
    fn test_remove_capability_from_request() {
        let mut meta = serde_json::Map::new();
        meta.insert(
            "symposium".to_string(),
            json!({
                "version": "1.0",
                "mcp_acp_transport": true
            }),
        );
        let client_capabilities = ClientCapabilities::new().meta(meta);

        let request = InitializeRequest::new(ProtocolVersion::LATEST)
            .client_capabilities(client_capabilities);

        let request = request.remove_meta_capability(McpAcpTransport);

        assert!(!request.has_meta_capability(McpAcpTransport));
    }

    #[test]
    fn test_add_capability_to_response() {
        let response = InitializeResponse::new(ProtocolVersion::LATEST);

        let response = response.add_meta_capability(McpAcpTransport);

        assert!(response.has_meta_capability(McpAcpTransport));
        assert_eq!(
            response.agent_capabilities.meta.as_ref().unwrap()["symposium"]["mcp_acp_transport"],
            json!(true)
        );
    }
}