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()));
}