tuls 0.1.0

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 std::{collections::BTreeMap, path::PathBuf};
use toml::Table;
use url::Url;

pub(crate) fn parse_toml(path: PathBuf, input: &str) -> Result<AgentDefinition> {
    if input.len() > MAX_AGENT_FILE_BYTES {
        bail!("agent TOML exceeds 1 MiB")
    }

    let table: Table = toml::from_str(input).context("invalid agent TOML")?;
    reject_provider_secrets(&table)?;
    reject_unknown_fields(&table)?;

    let name = required(&table, "name")?;
    validate_name(&name)?;
    let description = required(&table, "description")?;
    validate_description(&description)?;
    let instructions = required(&table, "instructions")?;
    validate_instructions(&instructions)?;
    let model = required(&table, "model")?;
    let provider = parse_provider(&required(&table, "model_provider")?)?;

    let (base_url, env_key, wire_api) = resolve_endpoint(
        &provider,
        string(&table, "base_url")?.as_deref(),
        string(&table, "env_key")?.as_deref(),
        string(&table, "wire_api")?.as_deref(),
    )?;

    let temperature = number(&table, "temperature")?;
    if let Some(value) = temperature {
        validate_temperature(value, &wire_api)?;
    }

    let reasoning_effort = string(&table, "reasoning_effort")?
        .map(|value| normalize_reasoning_effort(&value, &wire_api))
        .transpose()?;

    let max_turns = integer(&table, "max_turns")?.unwrap_or(i64::from(DEFAULT_MAX_TURNS));
    if !(1..=i64::from(MAX_TURNS)).contains(&max_turns) {
        bail!("max_turns must be between 1 and {MAX_TURNS}")
    }

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

    Ok(AgentDefinition {
        name,
        description,
        instructions,
        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(table: &Table) -> Result<()> {
    const SUPPORTED: &[&str] = &[
        "name",
        "description",
        "instructions",
        "model_provider",
        "model",
        "base_url",
        "env_key",
        "wire_api",
        "temperature",
        "reasoning_effort",
        "max_turns",
        "allow_tools",
        "deny_tools",
        "skills",
        "mcp_servers",
    ];
    for key in table.keys() {
        if !SUPPORTED.contains(&key.as_str()) {
            bail!("unknown canonical agent field {key:?}")
        }
    }
    Ok(())
}

fn string(table: &Table, key: &str) -> Result<Option<String>> {
    match table.get(key) {
        None => Ok(None),
        Some(value) => value
            .as_str()
            .map(|value| Some(value.to_owned()))
            .with_context(|| format!("{key} must be a string")),
    }
}

fn required(table: &Table, key: &str) -> Result<String> {
    string(table, key)?
        .filter(|value| !value.trim().is_empty())
        .with_context(|| format!("{key} is required and must be nonempty"))
}

fn integer(table: &Table, key: &str) -> Result<Option<i64>> {
    match table.get(key) {
        None => Ok(None),
        Some(value) => value
            .as_integer()
            .map(Some)
            .with_context(|| format!("{key} must be an integer")),
    }
}

fn number(table: &Table, key: &str) -> Result<Option<f32>> {
    match table.get(key) {
        None => Ok(None),
        Some(value) => {
            let number = value
                .as_float()
                .or_else(|| value.as_integer().map(|integer| integer as f64))
                .with_context(|| format!("{key} must be a number"))?;
            if !number.is_finite() || number < f64::from(f32::MIN) || number > f64::from(f32::MAX) {
                bail!("{key} is outside the supported numeric range")
            }
            Ok(Some(number as f32))
        }
    }
}

fn strings(table: &Table, key: &str) -> Result<Vec<String>> {
    match table.get(key) {
        None => Ok(Vec::new()),
        Some(value) => value
            .as_array()
            .with_context(|| format!("{key} must be an array"))?
            .iter()
            .map(|value| {
                value
                    .as_str()
                    .map(str::to_owned)
                    .context("array entries must be strings")
            })
            .collect(),
    }
}

fn reject_provider_secrets(table: &Table) -> Result<()> {
    for key in ["api_key", "apiKey", "token", "access_token", "accessToken"] {
        if table.contains_key(key) {
            bail!("literal secret field {key} is prohibited")
        }
    }
    if let Some(provider) = table.get("provider").and_then(|value| value.as_table()) {
        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(table: &Table) -> Result<BTreeMap<String, McpServerDefinition>> {
    let Some(servers) = table.get("mcp_servers") else {
        return Ok(BTreeMap::new());
    };

    servers
        .as_table()
        .context("mcp_servers must be a table")?
        .iter()
        .map(|(name, value)| {
            validate_mcp_server_name(name)?;
            let config = value.as_table().context("MCP server must be a table")?;
            reject_unknown_mcp_fields(config)?;
            let server_type = string(config, "type")?;
            let server = match server_type.as_deref() {
                Some("http") => McpServerDefinition::Http {
                    url: checked_url(&required(config, "url")?)?,
                    headers: string_map(config, "headers")?,
                },
                Some("stdio") | None if config.contains_key("command") => {
                    McpServerDefinition::Stdio {
                        command: required(config, "command")?,
                        args: strings(config, "args")?,
                        env: string_map(config, "env")?,
                    }
                }
                _ => bail!("unsupported MCP server type"),
            };
            Ok((name.clone(), server))
        })
        .collect()
}

fn reject_unknown_mcp_fields(table: &Table) -> Result<()> {
    const SUPPORTED: &[&str] = &["type", "command", "args", "env", "url", "headers"];
    for key in table.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(table: &Table, key: &str) -> Result<BTreeMap<String, String>> {
    match table.get(key) {
        None => Ok(BTreeMap::new()),
        Some(value) => value
            .as_table()
            .with_context(|| format!("{key} must be a table"))?
            .iter()
            .map(|(name, value)| {
                Ok((
                    name.clone(),
                    value
                        .as_str()
                        .context("map values must be strings")?
                        .to_owned(),
                ))
            })
            .collect(),
    }
}

#[cfg(test)]
mod tests;