Watch
0
0
Fork
You've already forked hyperhive
0
hyperhive/hive-agent/src/swarm_agent_commands.rs

360 lines
13 KiB
Rust

//! 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`
//! `<plugin dir>/skills/<skill>/SKILL.md`, for a bare name the agent's own
//! `~/.claude/skills/<skill>/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<watch::Sender<Option<Skills>>> = OnceLock::new();
fn latest() -> &'static watch::Sender<Option<Skills>> {
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<Option<Skills>>, 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<Vec<&str>> {
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<Vec<&str>> {
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<Skills> {
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<PathBuf> {
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<String> {
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::<Vec<_>>()
.join(" ")
} else {
value.trim_matches(['"', '\'']).to_owned()
};
let text = text.split_whitespace().collect::<Vec<_>>().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
);
}
}