//! Publishing the skills this agent's claude has into the swarm's //! `agent-commands` bucket, which the swarm UI's command menu reads //! (`swarm_wire::agent_commands`). //! //! **The list is what claude reports.** Every turn's `system`/`init` event //! carries `skills`, the names claude can invoke (`base:pr-review`, //! `dataviz`), and `plugins`, each with the directory it was installed to. //! [`observe_init`] reads both from the event, so the list follows the plugins //! and skills the turn really ran with; nothing is filtered for the menu, the //! controller cuts the list. The init event has no descriptions, so each one //! comes from the `description` of the skill's `SKILL.md`: for `plugin:skill` //! `/skills//SKILL.md`, for a bare name the agent's own //! `~/.claude/skills//SKILL.md`. A skill with no such file is listed //! with an empty description. //! //! **Once per change.** The list is published when the first turn reports it //! and again whenever a later turn reports different names, so an unchanged //! list costs nothing, not even the reads of the skill files. Best-effort: [`crate::swarm_kv_put`] retries a failed //! write, and the harness never waits on it. The agent's own queue credential //! is granted exactly this agent's key. use std::path::{Path, PathBuf}; use std::sync::OnceLock; use serde_json::Value; use swarm_wire::agent_commands::{self, Skill, Skills}; use tokio::sync::watch; use crate::swarm_kv_put::{Failure, Put, put_retrying}; /// The newest list claude reported, for [`run`] to publish. `None` until the /// first init event of this process. static LATEST: OnceLock>> = OnceLock::new(); fn latest() -> &'static watch::Sender> { LATEST.get_or_init(|| watch::channel(None).0) } /// Start the publish task, if this agent has a label. pub fn spawn() { let agent = crate::identity::label(); if agent.is_empty() { tracing::warn!("this agent has no label; not publishing its skills upward"); return; } tokio::spawn(run(agent)); } /// Hear about one stream event: an init event with different skill names than /// the last one makes the new list the one to publish. Every other event is /// ignored, and an init event with the same names as the last one costs no file /// reads: a description changes only with a plugin update, which restarts claude. pub fn observe_init(event: &Value) { if !is_init(event) { return; } let tx = latest(); if init_names(event).is_some_and(|names| names_of(tx.borrow().as_ref()) == Some(names)) { return; } let Some(skills) = skills_from_init(event, &home_skills_dir()) else { return; }; offer(tx, skills); } /// Make `skills` the list to publish, unless it already is. Whether it changed. fn offer(tx: &watch::Sender>, skills: Skills) -> bool { tx.send_if_modified(|current| { if current.as_ref() == Some(&skills) { return false; } *current = Some(skills); true }) } /// The skill names of an init event, in its order, or `None` without a `skills` /// array. fn init_names(event: &Value) -> Option> { let names = event.get("skills")?.as_array()?; Some(names.iter().filter_map(Value::as_str).collect()) } /// The names of a list, in order, or `None` before there is one. fn names_of(skills: Option<&Skills>) -> Option> { skills.map(|s| s.skills.iter().map(|s| s.name.as_str()).collect()) } async fn run(agent: String) { let client = crate::swarm_queue::client().await; let subject = agent_commands::subject(&agent); let mut changes = latest().subscribe(); while changes.changed().await.is_ok() { let Some(skills) = changes.borrow_and_update().clone() else { continue; }; let payload = match serde_json::to_vec(&skills) { Ok(payload) => payload, Err(e) => { tracing::warn!(error = %e, "serialising the agent's skills failed; not publishing"); continue; } }; match put_retrying(&client, &subject, Put::Set(&payload), "the agent's skills").await { Ok(()) => tracing::info!( subject, count = skills.skills.len(), "published this agent's skills" ), Err(Failure::TooLarge(e)) => { tracing::warn!(error = %e, "the agent's skills are over the queue's payload limit; not publishing them"); } // Only a `TooLarge` ends the retries. Err(Failure::Retry(e)) => { tracing::error!(error = e, "gave up publishing the agent's skills"); } } } } /// The agent's own skills directory, where a bare skill name is looked up. fn home_skills_dir() -> PathBuf { std::env::var_os("HOME") .map_or_else(|| PathBuf::from("/root"), PathBuf::from) .join(".claude/skills") } /// Whether `event` is claude's `system`/`init` event. fn is_init(event: &Value) -> bool { event.get("type").and_then(Value::as_str) == Some("system") && event.get("subtype").and_then(Value::as_str) == Some("init") } /// The skills a `system`/`init` event reports, with their descriptions read /// from the skill files (`own_skills` is where a name without a plugin is /// looked up), or `None` for any other event or an init event without a /// `skills` array. fn skills_from_init(event: &Value, own_skills: &Path) -> Option { if !is_init(event) { return None; } let names = event.get("skills")?.as_array()?; let plugins = plugin_dirs(event); let skills = names .iter() .filter_map(Value::as_str) .map(|name| Skill { name: name.to_owned(), description: skill_file(name, &plugins, own_skills) .and_then(|path| std::fs::read_to_string(path).ok()) .and_then(|text| frontmatter_description(&text)) .map(|d| agent_commands::clip_description(&d)) .unwrap_or_default(), }) .collect(); Some(Skills { skills }) } /// The init event's installed plugins as `(name, directory)`. A built-in /// plugin has no directory and is left out. fn plugin_dirs(event: &Value) -> Vec<(String, PathBuf)> { event .get("plugins") .and_then(Value::as_array) .into_iter() .flatten() .filter_map(|p| { let name = p.get("name")?.as_str()?; let path = p.get("path")?.as_str().filter(|p| *p != "builtin")?; Some((name.to_owned(), PathBuf::from(path))) }) .collect() } /// Where the `SKILL.md` of `name` is: under its plugin's directory for /// `plugin:skill`, else under `own_skills`. fn skill_file(name: &str, plugins: &[(String, PathBuf)], own_skills: &Path) -> Option { match name.split_once(':') { Some((plugin, skill)) => plugins .iter() .find(|(n, _)| n == plugin) .map(|(_, dir)| dir.join("skills").join(skill).join("SKILL.md")), None => Some(own_skills.join(name).join("SKILL.md")), } } /// The `description` of a skill file's front matter, as one line, or `None` /// when there is none. Handles a plain, a quoted and a folded (`>` or `|`) /// value; nothing else of YAML. fn frontmatter_description(text: &str) -> Option { let mut lines = text.lines(); if lines.next()?.trim() != "---" { return None; } let mut front = Vec::new(); for line in lines { if line.trim() == "---" { break; } front.push(line); } let at = front.iter().position(|l| l.starts_with("description:"))?; let value = front[at]["description:".len()..].trim(); let folded = matches!(value, "" | ">" | "|" | ">-" | "|-"); let text = if folded { front[at + 1..] .iter() .take_while(|l| l.starts_with(' ') || l.starts_with('\t') || l.is_empty()) .map(|l| l.trim()) .collect::>() .join(" ") } else { value.trim_matches(['"', '\'']).to_owned() }; let text = text.split_whitespace().collect::>().join(" "); (!text.is_empty()).then_some(text) } #[cfg(test)] mod tests { use super::*; use serde_json::json; fn write_skill(dir: &Path, name: &str, front: &str) { let skill = dir.join(name); std::fs::create_dir_all(&skill).unwrap(); std::fs::write( skill.join("SKILL.md"), format!("---\n{front}\n---\n\nbody\n"), ) .unwrap(); } #[test] fn a_description_is_read_whether_plain_quoted_or_folded() { let plain = "---\nname: x\ndescription: Does a thing.\n---\nbody"; assert_eq!( frontmatter_description(plain).as_deref(), Some("Does a thing.") ); let quoted = "---\ndescription: \"Does: a thing\"\n---\n"; assert_eq!( frontmatter_description(quoted).as_deref(), Some("Does: a thing") ); let folded = "---\nname: x\ndescription: >\n First line\n second line.\nother: 1\n---\n"; assert_eq!( frontmatter_description(folded).as_deref(), Some("First line second line.") ); assert_eq!(frontmatter_description("no front matter"), None); assert_eq!(frontmatter_description("---\nname: x\n---\n"), None); } /// The names are the init event's, in its order, each with the description of /// its own file: a plugin skill from its plugin's directory, a bare name from /// the agent's own skills, and an empty one when there is no file. #[test] fn the_skills_are_the_init_events_with_their_descriptions() { let dir = tempfile::tempdir().unwrap(); let plugin = dir.path().join("plugin-base"); write_skill( &plugin.join("skills"), "pr-review", "description: Review a PR.", ); let own = dir.path().join("own"); write_skill(&own, "dataviz", "description: Make a chart."); let event = json!({ "type": "system", "subtype": "init", "skills": ["base:pr-review", "dataviz", "debug", "base:missing"], "plugins": [ {"name": "base", "path": plugin}, {"name": "cc-plugin-privacy", "path": "builtin"}, ], }); let skills = skills_from_init(&event, &own) .expect("an init event") .skills; let got: Vec<(&str, &str)> = skills .iter() .map(|s| (s.name.as_str(), s.description.as_str())) .collect(); assert_eq!( got, [ ("base:pr-review", "Review a PR."), ("dataviz", "Make a chart."), ("debug", ""), ("base:missing", ""), ] ); } #[test] fn only_an_init_event_with_skills_yields_a_list() { let own = Path::new("/nonexistent"); assert!(skills_from_init(&json!({"type": "assistant"}), own).is_none()); assert!( skills_from_init(&json!({"type": "system", "subtype": "plugin_install"}), own) .is_none() ); assert!(skills_from_init(&json!({"type": "system", "subtype": "init"}), own).is_none()); let none = skills_from_init( &json!({"type": "system", "subtype": "init", "skills": []}), own, ); assert_eq!(none, Some(Skills::default())); } #[test] fn a_list_is_offered_once_however_often_it_is_reported() { let (tx, _rx) = watch::channel(None); let one = Skills { skills: vec![Skill { name: "a".into(), description: String::new(), }], }; assert!(offer(&tx, one.clone())); assert!(!offer(&tx, one.clone())); let mut two = one.clone(); two.skills[0].description = "now described".into(); assert!(offer(&tx, two)); } #[test] fn the_names_decide_whether_a_list_needs_its_files_read() { let event = json!({"type": "system", "subtype": "init", "skills": ["b", "a"]}); let list = |names: &[&str]| Skills { skills: names .iter() .map(|n| Skill { name: (*n).into(), description: String::new(), }) .collect(), }; assert_eq!(init_names(&event), names_of(Some(&list(&["b", "a"])))); assert_ne!(init_names(&event), names_of(Some(&list(&["a", "b"])))); assert_ne!(init_names(&event), names_of(None)); assert_eq!(init_names(&json!({"type": "system"})), None); } #[test] fn a_long_description_is_cut_to_one_line() { let long = format!("description: {}", "word ".repeat(100)); let dir = tempfile::tempdir().unwrap(); write_skill(dir.path(), "wordy", &long); let event = json!({"type": "system", "subtype": "init", "skills": ["wordy"]}); let skills = skills_from_init(&event, dir.path()).unwrap().skills; assert_eq!( skills[0].description.chars().count(), agent_commands::MAX_DESCRIPTION_CHARS ); } }