From 49719842b049a1dcfb6216940a6fcee2a106cb83 Mon Sep 17 00:00:00 2001 From: damocles Date: Sun, 15 Nov 2026 20:51:16 +0100 Subject: [PATCH] publish the agent's skills to the agent-commands bucket --- docs/4-implementation/swarm/controller.md | 5 +- hive-agent/src/main.rs | 4 + hive-agent/src/swarm_agent_commands.rs | 304 ++++++++++++++++++++++ hive-agent/src/swarm_agent_icon.rs | 74 +----- hive-agent/src/swarm_kv_put.rs | 97 +++++++ hive-agent/src/turn.rs | 1 + 6 files changed, 416 insertions(+), 69 deletions(-) create mode 100644 hive-agent/src/swarm_agent_commands.rs create mode 100644 hive-agent/src/swarm_kv_put.rs diff --git a/docs/4-implementation/swarm/controller.md b/docs/4-implementation/swarm/controller.md index d302f315e..199e11e5f 100644 --- a/docs/4-implementation/swarm/controller.md +++ b/docs/4-implementation/swarm/controller.md @@ -279,7 +279,10 @@ load it as an `` and show the dimmed default agent icon (a robot head in a round frame, `branding/agent-default.svg`) for an agent without one. The skills the agent has go to its key of the `agent-commands` bucket, for the swarm UI's command menu. -The agent's credential may publish `$KV.agent-commands.` and nothing else of the bucket. The value is a +The agent's credential may publish `$KV.agent-commands.` and nothing else of the bucket. The harness +publishes the list that claude reports in a turn's `system`/`init` event, with each description read from the +skill's `SKILL.md`. It writes when the first turn reports a list and again only when a later turn reports a +different one, and retries a failed write in the background. The value is a list of `{name, description}`. `GET /api/agents//commands` answers with the swarm's own commands first (a table in `agent_commands.rs`, today `compact`), then the agent's skills sorted by name. The skills come from the agent, so the controller drops a name that isn't one plain word, a repeat, and any that takes a command's name, diff --git a/hive-agent/src/main.rs b/hive-agent/src/main.rs index 0081ee149..62a5e6504 100644 --- a/hive-agent/src/main.rs +++ b/hive-agent/src/main.rs @@ -35,11 +35,13 @@ mod sqlite_writer; mod state_entry_watch; mod stats; mod subagent_role_watch; +mod swarm_agent_commands; mod swarm_agent_icon; mod swarm_agent_state; mod swarm_agents_md; mod swarm_inference; mod swarm_input; +mod swarm_kv_put; mod swarm_permissions; mod swarm_queue; mod swarm_queue_gauge; @@ -508,6 +510,8 @@ async fn serve_main(socket: &Path, poll_ms: u64) -> Result<()> { swarm_agent_state::spawn(&bus, login_state.clone()); // Once per start: a new icon only arrives with a new harness process. swarm_agent_icon::spawn(); + // The skills claude reports, published once at the first turn and whenever they change. + swarm_agent_commands::spawn(); // Before the mirror and before any turn reads the file. swarm_agents_md::seed_initial().await; // At start and on every change, so the swarm can read it while the diff --git a/hive-agent/src/swarm_agent_commands.rs b/hive-agent/src/swarm_agent_commands.rs new file mode 100644 index 000000000..9ff8c9c14 --- /dev/null +++ b/hive-agent/src/swarm_agent_commands.rs @@ -0,0 +1,304 @@ +//! 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 a different one, so an unchanged +//! list costs nothing. 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 a different skill list than +/// the last one makes the new list the one to publish. Every other event is +/// ignored. +pub fn observe_init(event: &Value) { + if !is_init(event) { + return; + } + let Some(skills) = skills_from_init(event, &home_skills_dir()) else { + return; + }; + latest().send_if_modified(|current| { + if current.as_ref() == Some(&skills) { + return false; + } + *current = Some(skills); + true + }); +} + +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_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 + ); + } +} diff --git a/hive-agent/src/swarm_agent_icon.rs b/hive-agent/src/swarm_agent_icon.rs index 3427fe104..d3d7130de 100644 --- a/hive-agent/src/swarm_agent_icon.rs +++ b/hive-agent/src/swarm_agent_icon.rs @@ -19,28 +19,14 @@ //! one are retried with backoff until one is acked. use std::path::Path; -use std::time::Duration; -use async_nats::jetstream::context::PublishErrorKind; -use backon::{ExponentialBuilder, Retryable}; +use crate::swarm_kv_put::{Failure, Put, put_retrying}; /// Where the agent's NixOS config puts the icon /// (`services.hyperhive.agent.icon`), and the file `GET /icon` serves. Absent /// when none is configured. const ICON_PATH: &str = "/etc/hyperhive/icon.svg"; -/// First retry delay after a failed write, doubled per failure up to -/// [`MAX_RETRY`], with no cap on the number of tries. -const FIRST_RETRY: Duration = Duration::from_secs(5); - -/// Longest wait between retries. -const MAX_RETRY: Duration = Duration::from_mins(5); - -/// The KV header and value that mark an entry deleted. `kv::Store::get` -/// answers `None` for an entry carrying them. -const KV_OPERATION: &str = "KV-Operation"; -const KV_OPERATION_DELETE: &str = "DEL"; - /// What to write under this agent's key. #[derive(Debug, PartialEq, Eq)] enum Icon { @@ -80,21 +66,11 @@ async fn run(agent: String) { return; } }; - let js = async_nats::jetstream::new(client.clone()); - let written = (|| write(&client, &js, &subject, &icon)) - .retry( - ExponentialBuilder::default() - .with_min_delay(FIRST_RETRY) - .with_max_delay(MAX_RETRY) - .without_max_times(), - ) - .when(|failure| matches!(failure, Failure::Retry(_))) - .notify(|failure, delay| { - if let Failure::Retry(e) = failure { - tracing::warn!(error = e, retry_in = ?delay, "publishing the agent icon failed"); - } - }) - .await; + let put = match &icon { + Icon::Set(bytes) => Put::Set(bytes), + Icon::Unset => Put::Delete, + }; + let written = put_retrying(&client, &subject, put, "the agent icon").await; match written { Ok(()) => tracing::info!( subject, @@ -111,44 +87,6 @@ async fn run(agent: String) { } } -/// Why a write did not land. -enum Failure { - /// The payload can never fit; retrying cannot help. - TooLarge(async_nats::jetstream::context::PublishError), - /// Anything else, rendered for the log. - Retry(String), -} - -/// One acked write of `icon` to `subject`. -async fn write( - client: &async_nats::Client, - js: &async_nats::jetstream::Context, - subject: &str, - icon: &Icon, -) -> Result<(), Failure> { - // An unconnected client does not fail a publish, it buffers it, and the - // payload limit it checks against is the library default until the - // server has announced its own. - swarm_queue_client::ensure_connected(client) - .map_err(|e| Failure::Retry(swarm_queue_client::chain(&e)))?; - let sent = match icon { - Icon::Set(bytes) => js.publish(subject.to_owned(), bytes.clone().into()).await, - Icon::Unset => { - let mut headers = async_nats::HeaderMap::new(); - headers.insert(KV_OPERATION, KV_OPERATION_DELETE); - js.publish_with_headers(subject.to_owned(), headers, Vec::new().into()) - .await - } - }; - let ack = sent.map_err(|e| match e.kind() { - PublishErrorKind::MaxPayloadExceeded => Failure::TooLarge(e), - _ => Failure::Retry(e.to_string()), - })?; - // `StreamNotFound` here is the bucket not existing yet. - ack.await.map_err(|e| Failure::Retry(e.to_string()))?; - Ok(()) -} - #[cfg(test)] mod tests { use super::{Icon, read_icon}; diff --git a/hive-agent/src/swarm_kv_put.rs b/hive-agent/src/swarm_kv_put.rs new file mode 100644 index 000000000..ee3fe4ba2 --- /dev/null +++ b/hive-agent/src/swarm_kv_put.rs @@ -0,0 +1,97 @@ +//! One acked write to a key of a KV bucket the swarm-controller owns, by a +//! `JetStream` publish straight to the key's subject: the same message +//! `kv::Store::put` sends, without opening the bucket first, so the agent's +//! credential needs only the one subject. The controller creates the bucket, so +//! a write can arrive before it exists; that write and any other failed one are +//! retried with backoff until one is acked. +//! +//! Shared by the writers of an agent's own keys: [`crate::swarm_agent_icon`] +//! and [`crate::swarm_agent_commands`]. + +use std::time::Duration; + +use async_nats::jetstream::context::PublishErrorKind; +use backon::{ExponentialBuilder, Retryable}; + +/// First retry delay after a failed write, doubled per failure up to +/// [`MAX_RETRY`], with no cap on the number of tries. +const FIRST_RETRY: Duration = Duration::from_secs(5); + +/// Longest wait between retries. +const MAX_RETRY: Duration = Duration::from_mins(5); + +/// The KV header and value that mark an entry deleted. `kv::Store::get` +/// answers `None` for an entry carrying them. +const KV_OPERATION: &str = "KV-Operation"; +const KV_OPERATION_DELETE: &str = "DEL"; + +/// What to write under a key. +pub enum Put<'a> { + /// These bytes as the key's value. + Set(&'a [u8]), + /// Delete the key. + Delete, +} + +/// Why a write did not land. +pub enum Failure { + /// The payload can never fit; retrying cannot help. + TooLarge(async_nats::jetstream::context::PublishError), + /// Anything else, rendered for the log. + Retry(String), +} + +/// One acked write of `put` to `subject`. +async fn put_once( + client: &async_nats::Client, + js: &async_nats::jetstream::Context, + subject: &str, + put: &Put<'_>, +) -> Result<(), Failure> { + // An unconnected client does not fail a publish, it buffers it, and the + // payload limit it checks against is the library default until the + // server has announced its own. + swarm_queue_client::ensure_connected(client) + .map_err(|e| Failure::Retry(swarm_queue_client::chain(&e)))?; + let sent = match put { + Put::Set(bytes) => js.publish(subject.to_owned(), bytes.to_vec().into()).await, + Put::Delete => { + let mut headers = async_nats::HeaderMap::new(); + headers.insert(KV_OPERATION, KV_OPERATION_DELETE); + js.publish_with_headers(subject.to_owned(), headers, Vec::new().into()) + .await + } + }; + let ack = sent.map_err(|e| match e.kind() { + PublishErrorKind::MaxPayloadExceeded => Failure::TooLarge(e), + _ => Failure::Retry(e.to_string()), + })?; + // `StreamNotFound` here is the bucket not existing yet. + ack.await.map_err(|e| Failure::Retry(e.to_string()))?; + Ok(()) +} + +/// [`put_once`] until it is acked, or fails with [`Failure::TooLarge`], which +/// ends the retries. `what` names the value in the log. +pub async fn put_retrying( + client: &async_nats::Client, + subject: &str, + put: Put<'_>, + what: &str, +) -> Result<(), Failure> { + let js = async_nats::jetstream::new(client.clone()); + (|| put_once(client, &js, subject, &put)) + .retry( + ExponentialBuilder::default() + .with_min_delay(FIRST_RETRY) + .with_max_delay(MAX_RETRY) + .without_max_times(), + ) + .when(|failure| matches!(failure, Failure::Retry(_))) + .notify(|failure, delay| { + if let Failure::Retry(e) = failure { + tracing::warn!(error = e, retry_in = ?delay, "publishing {what} failed"); + } + }) + .await +} diff --git a/hive-agent/src/turn.rs b/hive-agent/src/turn.rs index 9a7c5bd32..f39e1d68b 100644 --- a/hive-agent/src/turn.rs +++ b/hive-agent/src/turn.rs @@ -788,6 +788,7 @@ impl Sink for BusSink<'_> { // → `apply_telemetry`). self.bus.observe_stream(event); self.bus.observe_mcp_health(event); + crate::swarm_agent_commands::observe_init(event); self.bus.emit(LiveEvent::Stream(event.clone())); }