diff --git a/docs/4-implementation/swarm/controller.md b/docs/4-implementation/swarm/controller.md
index 7238e96e8..d302f315e 100644
--- a/docs/4-implementation/swarm/controller.md
+++ b/docs/4-implementation/swarm/controller.md
@@ -278,6 +278,14 @@ the stored bytes, and 404 means the agent has no icon. swarm-ui's agent cards
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
+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,
+keeps at most 200, and cuts each description to one line of 200 characters. An agent that published nothing gets
+just the swarm's commands.
+
The fourth is its **`AGENTS.md`**, which goes into the `agents-md` bucket under
the key ``, writable by the agent's own credential alone
(`$KV.agents-md.`). The swarm reads that copy and edits the file through
diff --git a/nix/host-modules/swarm-nats.nix b/nix/host-modules/swarm-nats.nix
index 569f2ce42..327e2a44c 100644
--- a/nix/host-modules/swarm-nats.nix
+++ b/nix/host-modules/swarm-nats.nix
@@ -995,6 +995,11 @@ in
# and swarm-controller creates the bucket, so no
# `$$JS.API.*` subject.
"--agent-token-publish-subject ${lib.escapeShellArg "\$\$KV.subagent-status.{agent}.*"}"
+ # Its own key in the `agent-commands` KV bucket
+ # (`swarm_wire::agent_commands`): the skills the swarm UI offers
+ # in its message box. As for the icon, one put and no
+ # `$$JS.API.*` subject; swarm-controller creates the bucket.
+ "--agent-token-publish-subject ${lib.escapeShellArg "\$\$KV.agent-commands.{agent}"}"
# Its bash tasks (`swarm_wire::bash_task`): one status key per
# task in the `bash-task-status` KV bucket and the task's output
# rows. Publish only and no `$JS.API.*` subject:
diff --git a/nix/module-eval/nats-authelia.nix b/nix/module-eval/nats-authelia.nix
index 7c2e04f80..7392d9294 100644
--- a/nix/module-eval/nats-authelia.nix
+++ b/nix/module-eval/nats-authelia.nix
@@ -545,6 +545,7 @@ let
"'$$KV.agents-md.{agent}'"
"'$$SWARM.term.{agent}.sub.>'"
"'$$KV.subagent-status.{agent}.*'"
+ "'$$KV.agent-commands.{agent}'"
"'$$KV.bash-task-status.{agent}.*'"
"'$$SWARM.term.{agent}.bash.>'"
"'$$JS.API.DIRECT.GET.KV_agent-schedules.$$KV.agent-schedules.{agent}'"
diff --git a/swarm-controller/src/agent_commands.rs b/swarm-controller/src/agent_commands.rs
new file mode 100644
index 000000000..91263a276
--- /dev/null
+++ b/swarm-controller/src/agent_commands.rs
@@ -0,0 +1,207 @@
+//! The commands and skills an agent's message box offers in the swarm UI:
+//! `GET /api/agents/{name}/commands`.
+//!
+//! The list is the swarm's own commands, a table here, followed by the skills
+//! the agent's harness published (`swarm_wire::agent_commands`). Adding a
+//! swarm command is one line of [`COMMANDS`]. The published part comes from
+//! the agent and is untrusted, so [`build`] cuts it down and never lets a skill
+//! take the name of a command.
+
+use axum::Json;
+use axum::extract::{Path, State};
+use axum::http::StatusCode;
+use serde::Serialize;
+use swarm_wire::agent_commands::{self, Skills};
+use utoipa::ToSchema;
+
+use crate::routes::AppState;
+
+/// The commands the swarm UI offers every agent: the name without the slash,
+/// and what it does.
+const COMMANDS: [(&str, &str); 1] = [(
+ "compact",
+ "Compact this agent's context after the current turn",
+)];
+
+/// Whether an entry is one of the swarm's commands or a skill of the agent.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, ToSchema)]
+#[serde(rename_all = "snake_case")]
+pub(crate) enum CommandKind {
+ /// A command of the swarm.
+ Command,
+ /// A skill the agent has.
+ Skill,
+}
+
+/// One entry of the list.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, ToSchema)]
+pub(crate) struct CommandEntry {
+ /// The name without the slash.
+ pub name: String,
+ /// One line saying what it does.
+ pub description: String,
+ pub kind: CommandKind,
+}
+
+/// The list for an agent whose harness published `published` (or nothing):
+/// the swarm's commands, then the skills sorted by name. A skill is dropped when
+/// its name is not a plain word, repeats an earlier name, or is a command's;
+/// the list is cut to [`agent_commands::MAX_SKILLS`] skills and each
+/// description to one short line.
+fn build(published: Option) -> Vec {
+ let mut entries: Vec = COMMANDS
+ .iter()
+ .map(|&(name, description)| CommandEntry {
+ name: name.to_owned(),
+ description: description.to_owned(),
+ kind: CommandKind::Command,
+ })
+ .collect();
+ let mut skills: Vec = Vec::new();
+ for skill in published.unwrap_or_default().skills {
+ let taken = |entries: &[CommandEntry]| entries.iter().any(|e| e.name == skill.name);
+ if !agent_commands::is_plain_name(&skill.name) || taken(&entries) || taken(&skills) {
+ continue;
+ }
+ skills.push(CommandEntry {
+ name: skill.name,
+ description: agent_commands::clip_description(&skill.description),
+ kind: CommandKind::Skill,
+ });
+ if skills.len() >= agent_commands::MAX_SKILLS {
+ break;
+ }
+ }
+ skills.sort_by(|a, b| a.name.cmp(&b.name));
+ entries.extend(skills);
+ entries
+}
+
+#[utoipa::path(
+ get,
+ path = "/api/agents/{name}/commands",
+ params(("name" = String, Path, description = "agent whose commands to list")),
+ responses(
+ (status = 200, description = "the swarm's own commands, then the skills the agent's \
+ harness published, for the message box's command menu; just the swarm's commands \
+ when the agent has published none",
+ body = Vec),
+ (status = 400, description = "the agent name is not shaped like an identifier \
+ (problem+json)", body = String),
+ (status = 503, description = "no swarm queue is configured on this host, or the \
+ queue could not be reached (problem+json)", body = String),
+ (status = 500, description = "reading the agent's skills failed (problem+json)",
+ body = String),
+ ),
+ tag = "agents"
+)]
+pub(crate) async fn list_commands(
+ State(state): State,
+ Path(agent): Path,
+) -> Result>, problem_details::ProblemDetails> {
+ let agent = hive_types::Ident::parse(&agent)
+ .map(hive_types::Ident::into_string)
+ .map_err(|reason| crate::routes::error_problem(StatusCode::BAD_REQUEST, reason))?;
+ let Some(status) = state.status.as_ref() else {
+ // No queue here, so no agent has published skills: the swarm's own
+ // commands still make a useful menu.
+ return Ok(Json(build(None)));
+ };
+ let client = status.queue_client();
+ swarm_queue_client::ensure_connected(&client).map_err(|e| {
+ crate::routes::error_problem(
+ StatusCode::SERVICE_UNAVAILABLE,
+ &swarm_queue_client::chain(&e),
+ )
+ })?;
+ let js = async_nats::jetstream::new(client);
+ // The controller creates the bucket on a pass of `subagent_term::spawn`;
+ // until then nothing has published.
+ let published = match js.get_key_value(agent_commands::BUCKET).await {
+ Ok(store) => match store.get(&agent).await {
+ Ok(Some(bytes)) => serde_json::from_slice::(&bytes)
+ .map_err(|e| {
+ tracing::warn!(%agent, error = %e, "agent commands: the published skills are not readable");
+ })
+ .ok(),
+ Ok(None) => None,
+ Err(e) => return Err(read_failed(&agent, &e)),
+ },
+ Err(e) => {
+ tracing::debug!(%agent, error = %swarm_queue_client::chain(&e), "agent commands: the bucket is not readable");
+ None
+ }
+ };
+ Ok(Json(build(published)))
+}
+
+fn read_failed(agent: &str, e: &dyn std::error::Error) -> problem_details::ProblemDetails {
+ let detail = swarm_queue_client::chain(e);
+ tracing::warn!(%agent, error = %detail, "listing commands: reading the agent's skills failed");
+ crate::routes::error_problem(StatusCode::INTERNAL_SERVER_ERROR, &detail)
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ use swarm_wire::agent_commands::Skill;
+
+ fn skill(name: &str, description: &str) -> Skill {
+ Skill {
+ name: name.to_owned(),
+ description: description.to_owned(),
+ }
+ }
+
+ fn names(entries: &[CommandEntry]) -> Vec<&str> {
+ entries.iter().map(|e| e.name.as_str()).collect()
+ }
+
+ /// An agent that published nothing still gets the swarm's own commands.
+ #[test]
+ fn the_swarms_commands_come_first_and_always() {
+ let list = build(None);
+ assert_eq!(names(&list), ["compact"]);
+ assert!(list.iter().all(|e| e.kind == CommandKind::Command));
+ }
+
+ #[test]
+ fn skills_follow_sorted_by_name() {
+ let list = build(Some(Skills {
+ skills: vec![skill("zeta", "z"), skill("alpha", "a")],
+ }));
+ assert_eq!(names(&list), ["compact", "alpha", "zeta"]);
+ assert_eq!(list[1].kind, CommandKind::Skill);
+ }
+
+ /// What the agent publishes is untrusted: a skill cannot take a command's
+ /// name, repeat a name, or have a name that is not one plain word.
+ #[test]
+ fn a_published_skill_cannot_shadow_or_repeat_or_break_the_box() {
+ let list = build(Some(Skills {
+ skills: vec![
+ skill("compact", "pretends to be the command"),
+ skill("good", "one"),
+ skill("good", "two"),
+ skill("two words", "not a word"),
+ skill("", "empty"),
+ ],
+ }));
+ assert_eq!(names(&list), ["compact", "good"]);
+ assert_eq!(list[0].kind, CommandKind::Command);
+ assert_eq!(list[1].description, "one");
+ }
+
+ #[test]
+ fn the_list_and_the_descriptions_are_cut() {
+ let many: Vec = (0..agent_commands::MAX_SKILLS + 20)
+ .map(|i| skill(&format!("s{i:04}"), &"d ".repeat(300)))
+ .collect();
+ let list = build(Some(Skills { skills: many }));
+ assert_eq!(list.len(), COMMANDS.len() + agent_commands::MAX_SKILLS);
+ assert!(
+ list.iter()
+ .all(|e| e.description.chars().count() <= agent_commands::MAX_DESCRIPTION_CHARS)
+ );
+ }
+}
diff --git a/swarm-controller/src/main.rs b/swarm-controller/src/main.rs
index 341cbdf74..ab9ed7f53 100644
--- a/swarm-controller/src/main.rs
+++ b/swarm-controller/src/main.rs
@@ -22,6 +22,7 @@ use std::sync::{Arc, Mutex};
use anyhow::{Context, Result};
mod agent_archetype;
+mod agent_commands;
mod agent_config_repo;
mod agent_control;
mod agent_custom;
diff --git a/swarm-controller/src/startup.rs b/swarm-controller/src/startup.rs
index cbccdb859..4a12e8039 100644
--- a/swarm-controller/src/startup.rs
+++ b/swarm-controller/src/startup.rs
@@ -26,13 +26,13 @@ use crate::jobq::{
use crate::routes::hives::{HiveEntry, ServiceLink};
use crate::routes::{self, AppState, agents, config_prs, forge_admin, hives, jobq_graph};
use crate::{
- agent_control, agent_custom, agent_icon, agent_input, agent_limits, agent_login,
- agent_permissions, agent_renewal, agent_state_stream, agent_status, agents_md, alerts,
- archetypes, auth, backend_env, bash_task, builder, claude_login, config_drift, config_pr,
- egress_allow, egress_deny, forge, forge_account, github_account, gitlab_account, inference,
- issue_report, linked_accounts, matrix_account, message_stream, notify_flows, notify_router_api,
- pause_hold, pr_report, pulls, queue_identity, review_classifier, schedules, status,
- subagent_term, term_stream, wanted, webhook,
+ agent_commands, agent_control, agent_custom, agent_icon, agent_input, agent_limits,
+ agent_login, agent_permissions, agent_renewal, agent_state_stream, agent_status, agents_md,
+ alerts, archetypes, auth, backend_env, bash_task, builder, claude_login, config_drift,
+ config_pr, egress_allow, egress_deny, forge, forge_account, github_account, gitlab_account,
+ inference, issue_report, linked_accounts, matrix_account, message_stream, notify_flows,
+ notify_router_api, pause_hold, pr_report, pulls, queue_identity, review_classifier, schedules,
+ status, subagent_term, term_stream, wanted, webhook,
};
/// Where the daemon binds, overridable via `SWARM_CONTROLLER_SOCKET`.
@@ -666,6 +666,7 @@ pub(crate) fn build_app(state: AppState) -> axum::Router {
.routes(routes!(message_stream::stream_messages))
.routes(routes!(subagent_term::list_subagents))
.routes(routes!(bash_task::list_bash_tasks))
+ .routes(routes!(agent_commands::list_commands))
.routes(routes!(subagent_term::stream_subagent_term))
.routes(routes!(agent_state_stream::stream_agent_state))
.routes(routes!(agent_input::post_agent_input))
diff --git a/swarm-controller/src/subagent_term.rs b/swarm-controller/src/subagent_term.rs
index 1fe1a320d..9d4676ba4 100644
--- a/swarm-controller/src/subagent_term.rs
+++ b/swarm-controller/src/subagent_term.rs
@@ -85,6 +85,12 @@ pub(crate) fn spawn(client: async_nats::Client, wanted: Arc, hives
"bash task status: opening the bucket failed; next pass"
);
}
+ if let Err(e) = swarm_queue_client::agent_commands::open_or_create(&client).await {
+ tracing::warn!(
+ error = %swarm_queue_client::chain(&e),
+ "agent commands: opening the bucket failed; next pass"
+ );
+ }
for agent in live_agents(&wanted, &hives).await {
if let Err(e) = swarm_queue_client::bash_task::open_output(&client, &agent).await {
tracing::warn!(
diff --git a/swarm-queue-client/src/agent_commands.rs b/swarm-queue-client/src/agent_commands.rs
new file mode 100644
index 000000000..e61a75aea
--- /dev/null
+++ b/swarm-queue-client/src/agent_commands.rs
@@ -0,0 +1,18 @@
+//! The connection side of the agent skill list KV bucket: opening it. The
+//! bucket's name, key and value are `swarm_wire::agent_commands`.
+
+/// Open the bucket, creating it if nothing has yet. `history: 1`: the swarm
+/// wants each agent's current skills, not the ones it had before.
+#[cfg(feature = "kv")]
+pub async fn open_or_create(
+ client: &async_nats::Client,
+) -> Result {
+ let js = async_nats::jetstream::new(client.clone());
+ crate::kv::open_or_create(
+ &js,
+ swarm_wire::agent_commands::BUCKET,
+ "agent-commands",
+ "The skills each agent has, as its harness last published them".to_owned(),
+ )
+ .await
+}
diff --git a/swarm-queue-client/src/lib.rs b/swarm-queue-client/src/lib.rs
index e7173a1fe..4b94d4cc7 100644
--- a/swarm-queue-client/src/lib.rs
+++ b/swarm-queue-client/src/lib.rs
@@ -214,6 +214,10 @@ pub mod bash_task;
/// `swarm_wire::subagent_status`; opening the bucket needs `kv`.
pub mod subagent_status;
+/// Opening the bucket each agent's harness publishes its skills into. The name,
+/// key and value are `swarm_wire::agent_commands`; opening the bucket needs `kv`.
+pub mod agent_commands;
+
/// Opening the bucket agent icons are published into: one key per agent, with
/// no hive in it, unlike [`agent_status`]. The name, media type and subject,
/// and why the placement stays out of the key, are in `swarm_wire::agent_icon`.
diff --git a/swarm-wire/src/agent_commands.rs b/swarm-wire/src/agent_commands.rs
new file mode 100644
index 000000000..405cd0dc0
--- /dev/null
+++ b/swarm-wire/src/agent_commands.rs
@@ -0,0 +1,130 @@
+//! The skills an agent has, which the swarm UI offers in the message box's
+//! command menu beside the swarm's own commands.
+//!
+//! **One key per agent**, ``, in the [`BUCKET`] KV bucket, holding
+//! [`Skills`]. The agent's harness writes its own key with the agent's own
+//! queue credential, which may publish [`subject`] and nothing else of
+//! `JetStream`; `swarm-controller` creates the bucket
+//! (`swarm_queue_client::agent_commands::open_or_create`) and reads the key to
+//! answer `GET /api/agents/{name}/commands`. The writer publishes to the
+//! subject directly instead of opening the bucket, as the agent icon does
+//! (`crate::agent_icon`); a write before the bucket exists is refused and
+//! tried again.
+//!
+//! What the agent publishes is **untrusted**: the controller cuts the list to
+//! [`MAX_SKILLS`], each name to [`MAX_NAME_CHARS`] and each description to
+//! [`MAX_DESCRIPTION_CHARS`], drops a name that is not a plain slash word, and
+//! never lets a skill shadow one of the swarm's own commands.
+
+use serde::{Deserialize, Serialize};
+
+/// The KV bucket the skill lists are published into, keyed by agent name.
+pub const BUCKET: &str = "agent-commands";
+
+/// The most skills one list carries; the rest are dropped.
+pub const MAX_SKILLS: usize = 200;
+
+/// The longest skill name, in characters; a longer one is dropped.
+pub const MAX_NAME_CHARS: usize = 80;
+
+/// The longest description, in characters; a longer one is cut.
+pub const MAX_DESCRIPTION_CHARS: usize = 200;
+
+/// One skill the agent has.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct Skill {
+ /// The name as typed after the slash: `forge-workflow`, `base:pr-review`.
+ pub name: String,
+ /// One line saying what it is for.
+ pub description: String,
+}
+
+/// The value under an agent's key.
+#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
+pub struct Skills {
+ pub skills: Vec,
+}
+
+/// The subject `agent`'s list is written on: `$KV..`, the
+/// agent name alone.
+#[must_use]
+pub fn subject(agent: &str) -> String {
+ format!("$KV.{BUCKET}.{agent}")
+}
+
+/// Whether `name` can follow a slash in the box as one word: not empty, not
+/// longer than [`MAX_NAME_CHARS`], and made of letters, digits and `- _ : .`.
+#[must_use]
+pub fn is_plain_name(name: &str) -> bool {
+ !name.is_empty()
+ && name.chars().count() <= MAX_NAME_CHARS
+ && name
+ .chars()
+ .all(|c| c.is_ascii_alphanumeric() || matches!(c, '-' | '_' | ':' | '.'))
+}
+
+/// `description` as one line of at most [`MAX_DESCRIPTION_CHARS`] characters:
+/// whitespace runs become single spaces, and a longer text is cut with `…`.
+#[must_use]
+pub fn clip_description(description: &str) -> String {
+ let one_line = description.split_whitespace().collect::>().join(" ");
+ if one_line.chars().count() <= MAX_DESCRIPTION_CHARS {
+ return one_line;
+ }
+ let mut cut: String = one_line.chars().take(MAX_DESCRIPTION_CHARS - 1).collect();
+ cut.push('…');
+ cut
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ /// One token after the bucket, the agent name alone: what the per-agent
+ /// grant `$KV.agent-commands.{agent}` expands to.
+ #[test]
+ fn the_published_subject_carries_the_agent_alone() {
+ assert_eq!(subject("iris"), "$KV.agent-commands.iris");
+ }
+
+ #[test]
+ fn a_plain_name_is_a_word_the_box_can_complete() {
+ for ok in ["compact", "base:pr-review", "a_b.c", "x1"] {
+ assert!(is_plain_name(ok), "{ok}");
+ }
+ for bad in [
+ "",
+ "two words",
+ "slash/name",
+ "bell\u{7}",
+ &"x".repeat(MAX_NAME_CHARS + 1),
+ ] {
+ assert!(!is_plain_name(bad), "{bad:?}");
+ }
+ assert!(is_plain_name(&"x".repeat(MAX_NAME_CHARS)));
+ }
+
+ #[test]
+ fn a_description_is_one_line_and_cut() {
+ assert_eq!(clip_description("a\n b\tc"), "a b c");
+ let long = "y".repeat(MAX_DESCRIPTION_CHARS + 30);
+ let cut = clip_description(&long);
+ assert_eq!(cut.chars().count(), MAX_DESCRIPTION_CHARS);
+ assert!(cut.ends_with('…'));
+ }
+
+ #[test]
+ fn the_wire_form_is_plain_json() {
+ let wire = serde_json::to_string(&Skills {
+ skills: vec![Skill {
+ name: "dataviz".to_owned(),
+ description: "charts".to_owned(),
+ }],
+ })
+ .expect("encodes");
+ assert_eq!(
+ wire,
+ r#"{"skills":[{"name":"dataviz","description":"charts"}]}"#
+ );
+ }
+}
diff --git a/swarm-wire/src/lib.rs b/swarm-wire/src/lib.rs
index cbcaac9bd..d552ce8d6 100644
--- a/swarm-wire/src/lib.rs
+++ b/swarm-wire/src/lib.rs
@@ -7,6 +7,7 @@
pub mod agent_archetype;
pub mod agent_closures;
+pub mod agent_commands;
pub mod agent_icon;
pub mod agent_inference;
pub mod agent_limits;