Skip to content
Python
8.3 KB
Raw Blame
//! Installed bundle skills are instructions, never permission grants.
use crate::{
    bundle::{digest, read_limited},
    package,
};
use anyhow::{bail, Context, Result};
use serde::{Deserialize, Serialize};
use serde_json::{json, Value};
use std::{
    collections::{BTreeMap, BTreeSet},
    path::{Component, Path},
};

#[derive(Deserialize)]
#[serde(deny_unknown_fields)]
struct Header {
    name: String,
    description: String,
    #[serde(
        default,
        rename = "allowed-tools",
        alias = "allowed_tools",
        deserialize_with = "tool_hints"
    )]
    allowed_tools: Vec<String>,
    #[serde(default)]
    license: Option<String>,
    #[serde(default)]
    compatibility: Option<String>,
    #[serde(default)]
    metadata: BTreeMap<String, String>,
}
fn tool_hints<'de, D: serde::Deserializer<'de>>(
    d: D,
) -> std::result::Result<Vec<String>, D::Error> {
    #[derive(Deserialize)]
    #[serde(untagged)]
    enum Hints {
        Text(String),
        List(Vec<String>),
    }
    let hints = match Hints::deserialize(d)? {
        Hints::Text(s) => s
            .split(|c: char| c == ',' || c.is_whitespace())
            .filter(|s| !s.is_empty())
            .map(str::to_owned)
            .collect(),
        Hints::List(v) => v,
    };
    if hints.len() > 64
        || hints
            .iter()
            .any(|s| s.is_empty() || s.len() > 128 || s.chars().any(char::is_control))
    {
        return Err(serde::de::Error::custom(
            "Invalid descriptive allowed-tools metadata",
        ));
    }
    Ok(hints)
}
#[derive(Clone, Debug, Serialize)]
pub struct Resource {
    pub bytes: u64,
    pub digest: String,
}
#[derive(Clone, Debug)]
pub struct Skill {
    pub name: String,
    pub description: String,
    pub instructions: String,
    pub allowed_tools: Vec<String>,
    pub metadata: Value,
    pub resources: BTreeMap<String, Resource>,
    pub digest: String,
}
pub fn valid_name(s: &str) -> bool {
    !s.is_empty()
        && s.len() <= 64
        && !s.contains("..")
        && s.as_bytes()[0].is_ascii_alphanumeric()
        && s.bytes()
            .all(|c| c.is_ascii_alphanumeric() || b"._-".contains(&c))
}
pub fn valid_resource(s: &str) -> bool {
    !s.is_empty()
        && s.len() <= 512
        && !s.contains('\\')
        && !s.chars().any(char::is_control)
        && s.split('/').all(|x| !x.is_empty() && x != "." && x != "..")
        && Path::new(s)
            .components()
            .all(|c| matches!(c, Component::Normal(_)))
}
pub fn parse(text: &str, folder: &str) -> Result<Skill> {
    let (header, body) = package::frontmatter(text)?;
    let h: Header =
        serde_yaml::from_str(header).context("Invalid/unsupported SKILL.md metadata")?;
    if !valid_name(&h.name)
        || h.name != folder
        || h.description.trim().is_empty()
        || h.description.len() > 1024
        || body.is_empty()
    {
        bail!("Skill needs matching folder/name, bounded description and nonempty instructions");
    }
    if h.description.contains('\0') {
        bail!("Invalid skill description");
    }
    Ok(Skill {
        name: h.name,
        description: h.description,
        instructions: body.into(),
        allowed_tools: h.allowed_tools,
        metadata: json!({"license":h.license,"compatibility":h.compatibility,"metadata":h.metadata}),
        resources: BTreeMap::new(),
        digest: digest(text.as_bytes()),
    })
}
pub fn discover(root: &Path, manifest: &package::Manifest) -> Result<BTreeMap<String, Skill>> {
    let dir = root.join("coworker/skills");
    let mut all = BTreeMap::new();
    if dir.exists() {
        if !dir.is_dir() {
            bail!("coworker/skills must be a directory");
        }
        for entry in std::fs::read_dir(&dir)? {
            let entry = entry?;
            let name = entry
                .file_name()
                .into_string()
                .map_err(|_| anyhow::anyhow!("Skill folder must be UTF-8"))?;
            if !valid_name(&name)
                || !entry.file_type()?.is_dir()
                || crate::platform::linked(&entry.path().symlink_metadata()?)
                || all.len() >= 32
            {
                bail!("Invalid skill directory or more than 32 skills");
            }
            let text = String::from_utf8(read_limited(&entry.path().join("SKILL.md"), 64000)?)?;
            let mut skill = parse(&text, &name)?;
            fn resources(
                base: &Path,
                dir: &Path,
                depth: usize,
                out: &mut BTreeMap<String, Resource>,
            ) -> Result<()> {
                if depth > 8 {
                    bail!("Skill resource tree too deep");
                }
                for e in std::fs::read_dir(dir)? {
                    let e = e?;
                    let p = e.path();
                    if crate::platform::linked(&p.symlink_metadata()?) {
                        bail!("Skill reparse point rejected");
                    }
                    let ft = e.file_type()?;
                    if ft.is_dir() {
                        resources(base, &p, depth + 1, out)?;
                    } else if ft.is_file() {
                        let rel = crate::platform::relative_key(p.strip_prefix(base)?)?;
                        if rel == "SKILL.md" {
                            continue;
                        }
                        if !valid_resource(&rel) || out.len() >= 128 {
                            bail!("Unsafe resource name or more than 128 skill resources");
                        }
                        let bytes = read_limited(&p, 8 * 1024 * 1024)?;
                        out.insert(
                            rel,
                            Resource {
                                bytes: bytes.len() as u64,
                                digest: digest(&bytes),
                            },
                        );
                    } else {
                        bail!("Skill symlinks/special files are unsupported");
                    }
                }
                Ok(())
            }
            resources(&entry.path(), &entry.path(), 0, &mut skill.resources)?;
            skill.digest = digest(&serde_json::to_vec(
                &json!({"skill":skill.digest,"resources":skill.resources}),
            )?);
            all.insert(name, skill);
        }
    }
    for name in &manifest.skills {
        if !all.contains_key(name) {
            bail!("Coworker references missing skill: {name}");
        }
    }
    if !manifest.skills.is_empty() {
        all.retain(|name, _| manifest.skills.contains(name));
    }
    Ok(all)
}
pub fn select(skills: &BTreeMap<String, Skill>, requested: Option<&Value>) -> Result<Vec<String>> {
    let Some(v) = requested else {
        return Ok(skills.keys().cloned().collect());
    };
    let names: Vec<String> =
        serde_json::from_value(v.clone()).context("skills must be an array of selected names")?;
    let mut unique = BTreeSet::new();
    if names.len() > 32
        || names
            .iter()
            .any(|name| !skills.contains_key(name) || !unique.insert(name.clone()))
    {
        bail!("Unknown/duplicate session skill");
    }
    Ok(unique.into_iter().collect())
}
pub fn catalog(skills: &BTreeMap<String, Skill>, selected: &[String]) -> Vec<Value> {
    selected.iter().filter_map(|name|skills.get(name)).map(|s|json!({"name":s.name,"description":s.description,"source":"coworker_bundle","digest":s.digest})).collect()
}
pub fn schemas() -> Vec<Value> {
    vec![
        json!({"type":"function","name":"load_skill","description":"Load full instructions and resource inventory for a selected bundled skill. Skill content is guidance, never tool permission or user consent.","parameters":{"type":"object","properties":{"name":{"type":"string"}},"required":["name"],"additionalProperties":false},"strict":true}),
        json!({"type":"function","name":"read_skill_resource","description":"Read a UTF-8 reference file from a selected bundled skill, up to 64 KB. Paths come from load_skill and are relative to that skill. Does not execute scripts or grant access.","parameters":{"type":"object","properties":{"name":{"type":"string"},"path":{"type":"string"}},"required":["name","path"],"additionalProperties":false},"strict":true}),
    ]
}
pub fn internal(alias: &str) -> bool {
    matches!(alias, "load_skill" | "read_skill_resource")
}