marona 5.3.0

Agent SDK with coordinated B2A and D2A protocols, realtime device streams, structured responses, MCP and A2A
Documentation
use crate::{A2APolicy, A2ATask, Error, Result};
use serde::{Deserialize, Serialize};
use serde_json::{json, Value};
use sha2::{Digest, Sha256};
use std::{net::IpAddr, path::PathBuf};
use url::Url;
use uuid::Uuid;

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct A2AEvent {
    pub r#type: String,
    pub peer_name: String,
    pub task_id: Option<String>,
    pub state: Option<String>,
    pub output: Value,
    pub data: Value,
}
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct A2ARequestContext {
    pub task_id: String,
    pub context_id: String,
    pub skill: Option<String>,
    pub user_id: Option<String>,
    pub session_id: String,
    pub metadata: Value,
}

/// Durable references to remote tasks; peer credentials are never persisted.
#[derive(Clone, Debug)]
pub struct A2ATaskStore {
    directory: PathBuf,
}
impl Default for A2ATaskStore {
    fn default() -> Self {
        let home = std::env::var_os("HOME")
            .or_else(|| std::env::var_os("USERPROFILE"))
            .map(PathBuf::from)
            .unwrap_or_else(|| PathBuf::from("."));
        Self::new(home.join(".marona/a2a/rust-tasks"))
    }
}
impl A2ATaskStore {
    pub fn new(directory: impl Into<PathBuf>) -> Self {
        Self {
            directory: directory.into(),
        }
    }
    fn file(&self, peer: &str, session: &str) -> PathBuf {
        let key = json!([peer, session]).to_string();
        self.directory
            .join(format!("{:x}.json", Sha256::digest(key.as_bytes())))
    }
    pub async fn save(&self, peer: &str, session: &str, task: &A2ATask) -> Result<()> {
        let map_error = |_| Error::A2A("Could not persist A2A task".into());
        tokio::fs::create_dir_all(&self.directory)
            .await
            .map_err(map_error)?;
        let temporary = self.directory.join(format!(".task-{}.tmp", Uuid::new_v4()));
        let bytes =
            serde_json::to_vec(&task.raw).map_err(|_| Error::A2A("Invalid A2A task".into()))?;
        let result = async {
            let mut options = tokio::fs::OpenOptions::new();
            options.write(true).create_new(true);
            #[cfg(unix)]
            options.mode(0o600);
            let file = options.open(&temporary).await?;
            drop(file);
            tokio::fs::write(&temporary, bytes).await?;
            tokio::fs::rename(&temporary, self.file(peer, session)).await
        }
        .await;
        let _ = tokio::fs::remove_file(&temporary).await;
        result.map_err(map_error)
    }
    pub async fn latest(&self, peer: &str, session: &str) -> Result<Option<A2ATask>> {
        match tokio::fs::read(self.file(peer, session)).await {
            Ok(bytes) => parse_task(
                serde_json::from_slice(&bytes)
                    .map_err(|_| Error::A2A("Invalid persisted A2A task".into()))?,
            )
            .map(Some),
            Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(None),
            Err(_) => Err(Error::A2A("Could not read persisted A2A task".into())),
        }
    }
}
pub(crate) fn valid_url(value: &str, policy: &A2APolicy) -> Result<Url> {
    let url =
        Url::parse(value).map_err(|_| Error::A2A("A2A URL must be absolute HTTP(S)".into()))?;
    if !matches!(url.scheme(), "http" | "https")
        || url.host_str().is_none()
        || !url.username().is_empty()
        || url.password().is_some()
        || url.fragment().is_some()
    {
        return Err(Error::A2A("A2A URL must be credential-free HTTP(S)".into()));
    }
    if policy.require_https
        && url.scheme() != "https"
        && !matches!(url.host_str(), Some("localhost" | "127.0.0.1" | "[::1]"))
    {
        return Err(Error::A2A(
            "A2A peer requires HTTPS outside localhost".into(),
        ));
    }
    Ok(url)
}
pub(crate) async fn validate_host(value: &str, policy: &A2APolicy) -> Result<()> {
    let url = valid_url(value, policy)?;
    let host = url.host_str().unwrap().trim_matches(['[', ']']);
    if policy.allow_private_network || matches!(host, "localhost" | "127.0.0.1" | "::1") {
        return Ok(());
    }
    let addresses = tokio::net::lookup_host((host, url.port_or_known_default().unwrap_or(443)))
        .await
        .map_err(|_| Error::A2A("Could not resolve A2A peer host".into()))?;
    for address in addresses {
        let public = match address.ip() {
            IpAddr::V4(ip) => {
                let [a, b, c, _] = ip.octets();
                !(ip.is_private()
                    || ip.is_loopback()
                    || ip.is_link_local()
                    || ip.is_broadcast()
                    || ip.is_documentation()
                    || a == 0
                    || a >= 224
                    || (a == 100 && (64..=127).contains(&b))
                    || (a == 198 && (b == 18 || b == 19))
                    || (a == 192 && b == 0 && c == 0))
            }
            IpAddr::V6(ip) => {
                let parts = ip.segments();
                (parts[0] & 0xe000) == 0x2000
                    && !(parts[0] == 0x2001 && matches!(parts[1], 0 | 0xdb8))
            }
        };
        if !public {
            return Err(Error::A2A(
                "A2A peer resolves to a non-public address".into(),
            ));
        }
    }
    Ok(())
}
pub(crate) fn validate_card(card: &Value) -> Result<()> {
    if !card.is_object()
        || card["name"].as_str().unwrap_or("").trim().is_empty()
        || card.get("skills").is_some_and(|v| !v.is_array())
        || card
            .get("supportedInterfaces")
            .is_some_and(|v| !v.is_array())
    {
        return Err(Error::A2A("Invalid A2A Agent Card".into()));
    }
    Ok(())
}
pub(crate) fn endpoint(card: &Value, fallback: &str) -> (String, bool) {
    for binding in ["HTTP+JSON", "JSONRPC"] {
        for entry in card["supportedInterfaces"].as_array().into_iter().flatten() {
            if entry["protocolBinding"]
                .as_str()
                .unwrap_or("")
                .to_uppercase()
                .replace('_', "+")
                == binding
            {
                return (
                    entry["url"].as_str().unwrap_or(fallback).into(),
                    binding == "JSONRPC",
                );
            }
        }
    }
    (card["url"].as_str().unwrap_or(fallback).into(), false)
}
pub(crate) fn unwrap(value: Value) -> Result<Value> {
    if !value.is_object() || value.get("error").is_some_and(|v| !v.is_null()) {
        return Err(Error::A2A("A2A peer returned a protocol error".into()));
    }
    let result = value.get("result").cloned().unwrap_or(value);
    if !result.is_object() || result.get("error").is_some_and(|v| !v.is_null()) {
        return Err(Error::A2A("A2A response contains an invalid result".into()));
    }
    Ok(result)
}
pub(crate) fn parts(value: Value) -> Value {
    if value.is_string() {
        json!([{"text":value,"mediaType":"text/plain"}])
    } else if value.as_array().is_some_and(|items| {
        !items.is_empty()
            && items.iter().all(|v| {
                ["text", "data", "raw", "url"]
                    .iter()
                    .any(|key| v.get(key).is_some())
            })
    }) {
        value
    } else {
        json!([{"data":value,"mediaType":"application/json"}])
    }
}
pub(crate) fn parts_output(parts: &Value) -> Value {
    let values: Vec<Value> = parts
        .as_array()
        .into_iter()
        .flatten()
        .filter_map(|part| {
            ["data", "text", "url", "raw"]
                .iter()
                .find_map(|key| part.get(key).filter(|v| !v.is_null()).cloned())
        })
        .collect();
    match values.len() {
        0 => Value::Null,
        1 => values.into_iter().next().unwrap(),
        _ => Value::Array(values),
    }
}
pub(crate) fn parse_task(payload: Value) -> Result<A2ATask> {
    let value = unwrap(payload)?;
    let mut raw = value.get("task").cloned().unwrap_or(value);
    if raw.get("message").is_some() && raw.get("id").is_none() {
        let message = &raw["message"];
        let id = format!(
            "message:{}",
            message["messageId"].as_str().unwrap_or("unknown")
        );
        raw = json!({"id":id,"contextId":message.get("contextId").cloned().unwrap_or(json!(id)),"status":{"state":"TASK_STATE_COMPLETED","message":message}});
    }
    let id = raw
        .get("id")
        .or_else(|| raw.get("taskId"))
        .and_then(Value::as_str)
        .filter(|v| !v.is_empty())
        .ok_or_else(|| Error::A2A("A2A Task is missing id".into()))?
        .to_owned();
    let artifacts = raw["artifacts"].as_array().cloned().unwrap_or_default();
    let outputs: Vec<Value> = artifacts
        .iter()
        .map(|v| parts_output(&v["parts"]))
        .filter(|v| !v.is_null())
        .collect();
    let output = match outputs.len() {
        0 => raw
            .get("output")
            .cloned()
            .unwrap_or_else(|| parts_output(&raw["status"]["message"]["parts"])),
        1 => outputs[0].clone(),
        _ => Value::Array(outputs),
    };
    Ok(A2ATask {
        context_id: Some(
            raw.get("contextId")
                .or_else(|| raw.get("context_id"))
                .and_then(Value::as_str)
                .unwrap_or(&id)
                .into(),
        ),
        id,
        state: raw
            .pointer("/status/state")
            .or_else(|| raw.get("state"))
            .and_then(Value::as_str)
            .unwrap_or("TASK_STATE_UNSPECIFIED")
            .into(),
        output,
        artifacts,
        raw,
    })
}
pub(crate) fn event(peer: &str, payload: Value) -> Result<Option<A2AEvent>> {
    let value = unwrap(payload)?;
    let mut result = A2AEvent {
        r#type: String::new(),
        peer_name: peer.into(),
        task_id: None,
        state: None,
        output: Value::Null,
        data: value.clone(),
    };
    if value.get("task").is_some() {
        let task = parse_task(value)?;
        result.r#type = "a2a.task.started".into();
        result.task_id = Some(task.id);
        result.state = Some(task.state);
        result.output = task.output;
    } else if let Some(update) = value.get("artifactUpdate") {
        result.r#type = "a2a.artifact.updated".into();
        result.task_id = update["taskId"].as_str().map(str::to_owned);
        result.output = parts_output(&update["artifact"]["parts"]);
    } else if let Some(update) = value.get("statusUpdate") {
        let state = update["status"]["state"]
            .as_str()
            .unwrap_or("TASK_STATE_UNSPECIFIED");
        result.state = Some(state.into());
        result.task_id = update["taskId"].as_str().map(str::to_owned);
        result.r#type = if matches!(
            state,
            "TASK_STATE_COMPLETED"
                | "TASK_STATE_FAILED"
                | "TASK_STATE_REJECTED"
                | "TASK_STATE_CANCELED"
        ) {
            "a2a.task.completed"
        } else if matches!(
            state,
            "TASK_STATE_INPUT_REQUIRED" | "TASK_STATE_AUTH_REQUIRED"
        ) {
            "a2a.task.input_required"
        } else {
            "a2a.task.status"
        }
        .into();
    } else if let Some(message) = value.get("message") {
        result.r#type = "a2a.message.received".into();
        result.task_id = message["taskId"].as_str().map(str::to_owned);
        result.output = parts_output(&message["parts"]);
    } else {
        return Ok(None);
    }
    Ok(Some(result))
}