tuls 0.1.4

A compact Rust MCP toolbox for filesystem access, HTTP fetches, persistent memory, local process execution, reusable skills, and provider-backed local subagents.
use crate::agents::definition::*;
use anyhow::{Context, Result, bail};
use noyalib::{Mapping, Value};
use std::{collections::BTreeMap, path::PathBuf};
use url::Url;

const SUPPORTED_FIELDS: &[&str] = &[
    "name",
    "description",
    "subagent",
    "provider",
    "model",
    "base_url",
    "credential_env",
    "api",
    "temperature",
    "reasoning_effort",
    "max_turns",
    "tools",
    "disallowed_tools",
    "skills",
    "mcp_servers",
];

pub(crate) fn parse_markdown(path: PathBuf, input: &str) -> Result<AgentDefinition> {
    if input.len() > MAX_AGENT_FILE_BYTES {
        bail!("agent markdown exceeds 1 MiB")
    }
    let (frontmatter, instructions) = split_frontmatter(input)?;
    let map: Mapping = noyalib::from_str(frontmatter).context("invalid agent YAML frontmatter")?;
    reject_provider_secrets(&map)?;
    reject_unknown_fields(&map)?;
    validate_supported_field_types(&map)?;

    let name = required(&map, "name")?;
    validate_name(&name)?;
    let description = required(&map, "description")?;
    validate_description(&description)?;
    let subagent = boolean(&map, "subagent")?.unwrap_or(true);
    validate_instructions(instructions)?;
    if instructions.trim().is_empty() {
        bail!("agent instructions body must be nonempty")
    }

    let model = required(&map, "model")?;
    let provider = parse_provider(&required(&map, "provider")?)?;
    let (base_url, env_key, wire_api) = resolve_endpoint(
        &provider,
        string(&map, "base_url").as_deref(),
        string(&map, "credential_env").as_deref(),
        string(&map, "api").as_deref(),
    )?;

    let temperature = number(&map, "temperature");
    if let Some(value) = temperature {
        validate_temperature(value, &wire_api)?;
    }
    let reasoning_effort = string(&map, "reasoning_effort")
        .map(|value| normalize_reasoning_effort(&value, &wire_api))
        .transpose()?;
    let max_turns = integer(&map, "max_turns").unwrap_or(DEFAULT_MAX_TURNS as i64);
    if !(1..=MAX_TURNS as i64).contains(&max_turns) {
        bail!("max_turns must be between 1 and {MAX_TURNS}")
    }

    let tool_policy =
        ChildToolPolicy::new(strings(&map, "tools")?, strings(&map, "disallowed_tools")?)?;
    let mcp_servers = mcp_servers(&map)?;
    tool_policy.validate_servers(mcp_servers.keys().map(String::as_str))?;
    let skills = strings(&map, "skills")?;
    validate_skills(&skills)?;

    Ok(AgentDefinition {
        name,
        description,
        subagent,
        instructions: instructions.into(),
        model,
        base_url,
        env_key,
        wire_api,
        reasoning_effort,
        temperature,
        max_turns: max_turns as u32,
        tool_policy,
        skills,
        mcp_servers,
        source_path: path,
    })
}

fn reject_unknown_fields(map: &Mapping) -> Result<()> {
    for key in map.keys() {
        if !SUPPORTED_FIELDS.contains(&key.as_str()) {
            bail!("unknown agent field {key:?}")
        }
    }
    Ok(())
}

fn validate_supported_field_types(map: &Mapping) -> Result<()> {
    for key in [
        "name",
        "description",
        "provider",
        "model",
        "base_url",
        "credential_env",
        "api",
        "reasoning_effort",
    ] {
        if map.contains_key(key) && map.get(key).and_then(Value::as_str).is_none() {
            bail!("{key} must be a string")
        }
    }
    if map.contains_key("max_turns") && map.get("max_turns").and_then(Value::as_i64).is_none() {
        bail!("max_turns must be an integer")
    }
    if map.contains_key("temperature") {
        let value = map.get("temperature").context("temperature is missing")?;
        if value.as_f64().is_none() && value.as_i64().is_none() {
            bail!("temperature must be a number")
        }
    }
    Ok(())
}

fn split_frontmatter(input: &str) -> Result<(&str, &str)> {
    let rest = input
        .strip_prefix("---\n")
        .or_else(|| input.strip_prefix("---\r\n"))
        .context("agent markdown must begin with YAML frontmatter")?;
    for marker in ["\n---\n", "\n---\r\n"] {
        if let Some(pair) = rest.split_once(marker) {
            return Ok(pair);
        }
    }
    bail!("agent YAML frontmatter is not terminated")
}

fn string(map: &Mapping, key: &str) -> Option<String> {
    map.get(key).and_then(Value::as_str).map(str::to_owned)
}

fn required(map: &Mapping, key: &str) -> Result<String> {
    string(map, key)
        .filter(|value| !value.trim().is_empty())
        .with_context(|| format!("{key} is required"))
}

fn integer(map: &Mapping, key: &str) -> Option<i64> {
    map.get(key).and_then(Value::as_i64)
}

fn number(map: &Mapping, key: &str) -> Option<f32> {
    map.get(key)
        .and_then(|value| {
            value
                .as_f64()
                .or_else(|| value.as_i64().map(|value| value as f64))
        })
        .map(|value| value as f32)
}

fn boolean(map: &Mapping, key: &str) -> Result<Option<bool>> {
    match map.get(key) {
        None => Ok(None),
        Some(value) => value
            .as_bool()
            .map(Some)
            .with_context(|| format!("{key} must be a boolean")),
    }
}

fn strings(map: &Mapping, key: &str) -> Result<Vec<String>> {
    match map.get(key) {
        None => Ok(Vec::new()),
        Some(Value::Sequence(values)) => values
            .iter()
            .map(|value| {
                value
                    .as_str()
                    .map(str::to_owned)
                    .context("array entries must be strings")
            })
            .collect(),
        Some(_) => bail!("{key} must be an array"),
    }
}

fn reject_provider_secrets(map: &Mapping) -> Result<()> {
    for key in ["api_key", "apiKey", "token", "access_token", "accessToken"] {
        if map.contains_key(key) {
            bail!("literal secret field {key} is prohibited")
        }
    }
    if let Some(Value::Mapping(provider)) = map.get("provider") {
        for key in ["api_key", "apiKey", "token", "access_token", "accessToken"] {
            if provider.contains_key(key) {
                bail!("literal provider secret field {key} is prohibited")
            }
        }
    }
    Ok(())
}

fn mcp_servers(map: &Mapping) -> Result<BTreeMap<String, McpServerDefinition>> {
    let Some(Value::Mapping(servers)) = map.get("mcp_servers") else {
        if map.contains_key("mcp_servers") {
            bail!("mcp_servers must be a map")
        }
        return Ok(BTreeMap::new());
    };
    servers
        .iter()
        .map(|(name, value)| {
            validate_mcp_server_name(name)?;
            let config = value.as_mapping().context("MCP server must be a map")?;
            Ok((name.clone(), parse_mcp_server(config)?))
        })
        .collect()
}

fn parse_mcp_server(config: &Mapping) -> Result<McpServerDefinition> {
    reject_unknown_mcp_fields(config)?;
    match string(config, "type").as_deref() {
        Some("http") => Ok(McpServerDefinition::Http {
            url: checked_url(&required(config, "url")?)?,
            headers: string_map(config, "headers")?,
        }),
        Some("stdio") | None if config.contains_key("command") => Ok(McpServerDefinition::Stdio {
            command: required(config, "command")?,
            args: strings(config, "args")?,
            env: string_map(config, "env")?,
        }),
        _ => bail!("unsupported MCP server type"),
    }
}

fn reject_unknown_mcp_fields(map: &Mapping) -> Result<()> {
    const SUPPORTED: &[&str] = &["type", "command", "args", "env", "url", "headers"];
    for key in map.keys() {
        if !SUPPORTED.contains(&key.as_str()) {
            bail!("unknown MCP server field {key:?}")
        }
    }
    Ok(())
}

fn checked_url(value: &str) -> Result<Url> {
    let url = Url::parse(value)?;
    validate_endpoint(&url)?;
    Ok(url)
}

fn string_map(map: &Mapping, key: &str) -> Result<BTreeMap<String, String>> {
    match map.get(key) {
        None => Ok(BTreeMap::new()),
        Some(Value::Mapping(values)) => values
            .iter()
            .map(|(name, value)| {
                Ok((
                    name.clone(),
                    value.as_str().context("map value must be a string")?.into(),
                ))
            })
            .collect(),
        Some(_) => bail!("{key} must be a map"),
    }
}

#[cfg(test)]
mod tests;