marona 5.2.0

Agent SDK with coordinated B2A and D2A protocols, realtime device streams, structured responses, MCP and A2A
Documentation
use crate::{Error, Result};
use futures_util::{Stream, StreamExt};
use serde::{Deserialize, Serialize};
use serde_json::{json, Value};
use std::{
    pin::Pin,
    time::{Duration, SystemTime, UNIX_EPOCH},
};
use tokio::io::{AsyncWrite, AsyncWriteExt};

#[derive(Debug, Clone)]
pub struct RealtimeMedia {
    pub audio_formats: Vec<String>,
}
impl Default for RealtimeMedia {
    fn default() -> Self {
        Self {
            audio_formats: vec![
                "audio/ogg;codecs=opus".into(),
                "audio/mpeg".into(),
                "audio/webm;codecs=opus".into(),
            ],
        }
    }
}
impl RealtimeMedia {
    pub fn to_json(&self) -> Result<Value> {
        if self.audio_formats.is_empty()
            || self.audio_formats.len() > 8
            || self.audio_formats.iter().any(|v| v.trim().is_empty())
        {
            return Err(Error::Validation(
                "Provide one to eight audio MIME types".into(),
            ));
        }
        Ok(json!({"version":"1.0","audio_formats":self.audio_formats}))
    }
    pub fn validate_negotiation(&self, capabilities: &Value) -> Result<()> {
        let media = &capabilities["media"];
        if media["version"] != "1.0"
            || media["delivery"] != "http"
            || !media["audio_format"]["mime_type"]
                .as_str()
                .is_some_and(|mime| self.audio_formats.iter().any(|f| f == mime))
        {
            return Err(Error::Protocol(
                "The runtime did not negotiate a supported realtime media format".into(),
            ));
        }
        Ok(())
    }
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct RealtimeAudioFormat {
    pub mime_type: String,
    pub codec: String,
    pub sample_rate: u32,
    pub channels: u32,
}
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct RealtimeAudio {
    pub version: String,
    pub stream_id: String,
    pub response_id: String,
    pub uri: String,
    pub format: RealtimeAudioFormat,
    pub expires_at: u64,
    pub max_bytes: u64,
}
impl RealtimeAudio {
    pub fn from_json(value: Value) -> Result<Self> {
        let audio: Self = serde_json::from_value(value)
            .map_err(|_| Error::Protocol("Invalid realtime audio descriptor".into()))?;
        audio.validate()?;
        Ok(audio)
    }
    fn validate(&self) -> Result<()> {
        let invalid = || Error::Protocol("Invalid realtime audio descriptor".into());
        if self.version != "1.0"
            || self.stream_id.trim().is_empty()
            || self.response_id.trim().is_empty()
            || self.expires_at == 0
            || self.expires_at > 9_007_199_254_740_991
            || self.max_bytes == 0
            || self.max_bytes > 2 * 1024 * 1024
        {
            return Err(invalid());
        }
        let uri = url::Url::parse(&self.uri).map_err(|_| invalid())?;
        let loopback = match uri.host() {
            Some(url::Host::Domain(name)) => name == "localhost",
            Some(url::Host::Ipv4(ip)) => ip.is_loopback(),
            Some(url::Host::Ipv6(ip)) => ip.is_loopback(),
            _ => false,
        };
        if uri.host().is_none()
            || !uri.username().is_empty()
            || uri.password().is_some()
            || uri.fragment().is_some()
            || self.uri.split_once("://").is_some_and(|(_, rest)| {
                rest.split(['/', '?', '#'])
                    .next()
                    .unwrap_or("")
                    .contains('@')
            })
            || !(uri.scheme() == "https" || uri.scheme() == "http" && loopback)
        {
            return Err(invalid());
        }
        let expected = match self.format.mime_type.as_str() {
            "audio/ogg;codecs=opus" | "audio/webm;codecs=opus" => ("opus", 48000),
            "audio/mpeg" => ("mp3", 24000),
            _ => return Err(invalid()),
        };
        if self.format.codec != expected.0
            || self.format.sample_rate != expected.1
            || self.format.channels != 1
        {
            return Err(invalid());
        }
        Ok(())
    }
    pub fn content(&self) -> Result<Value> {
        self.validate()?;
        if !self.uri.starts_with("https:") {
            return Err(Error::Protocol("B2A media references require HTTPS".into()));
        }
        Ok(
            json!({"type":"audio","mime_type":self.format.mime_type,"uri":self.uri,"representation_id":self.response_id}),
        )
    }
    pub fn chunks(&self) -> Pin<Box<dyn Stream<Item = Result<Vec<u8>>> + Send + '_>> {
        Box::pin(async_stream::try_stream! {
            self.validate()?;
            if self.expires_at <= SystemTime::now().duration_since(UNIX_EPOCH).map_err(|_| Error::Protocol("Invalid system time".into()))?.as_secs() { Err(Error::Protocol("The audio stream has expired".into()))?; }
            let client = reqwest::Client::builder().connect_timeout(Duration::from_secs(30)).read_timeout(Duration::from_secs(30)).redirect(reqwest::redirect::Policy::none()).build()?;
            let response = client.get(&self.uri).header("Accept", &self.format.mime_type).send().await?;
            let mime = response.headers().get(reqwest::header::CONTENT_TYPE).and_then(|h|h.to_str().ok()).unwrap_or("").split(';').next().unwrap_or("");
            if response.status().as_u16() != 200 || Some(mime) != self.format.mime_type.split(';').next() { Err(Error::Protocol("Audio stream is unavailable or has an unexpected MIME type".into()))?; }
            let mut stream = response.bytes_stream(); let mut count = 0u64;
            while let Some(chunk) = stream.next().await {
                let chunk = chunk?; count += chunk.len() as u64;
                if count > self.max_bytes { Err(Error::Protocol("Audio exceeds its resource limit".into()))?; }
                yield chunk.to_vec();
            }
        })
    }
    pub async fn write_to<W: AsyncWrite + Unpin>(&self, destination: &mut W) -> Result<u64> {
        let mut stream = self.chunks();
        let mut count = 0;
        while let Some(chunk) = stream.next().await {
            let chunk = chunk?;
            destination
                .write_all(&chunk)
                .await
                .map_err(|e| Error::Realtime(e.to_string()))?;
            count += chunk.len() as u64;
        }
        Ok(count)
    }
}