From 8f11a38d1728cf9ccecfbe39772da6544bc70540 Mon Sep 17 00:00:00 2001 From: iris Date: Sun, 15 Nov 2026 19:42:17 +0100 Subject: [PATCH] swarm: the commands and skills an agent's message box offers GET /api/agents/{name}/commands answers with the swarm's own commands, a table in the controller, then the skills the agent's harness published to its key of the agent-commands bucket. The published part is untrusted and cut down: plain names only, no repeats, never a command's name, a capped list and one short line per description. The agent credential may publish its own key. Nothing publishes yet; the harness half and the swarm UI menu follow. --- docs/4-implementation/swarm/controller.md | 8 + nix/host-modules/swarm-nats.nix | 5 + nix/module-eval/nats-authelia.nix | 1 + swarm-controller/src/agent_commands.rs | 207 ++++++++++++++++++++++ swarm-controller/src/main.rs | 1 + swarm-controller/src/startup.rs | 15 +- swarm-controller/src/subagent_term.rs | 6 + swarm-queue-client/src/agent_commands.rs | 18 ++ swarm-queue-client/src/lib.rs | 4 + swarm-wire/src/agent_commands.rs | 130 ++++++++++++++ swarm-wire/src/lib.rs | 1 + 11 files changed, 389 insertions(+), 7 deletions(-) create mode 100644 swarm-controller/src/agent_commands.rs create mode 100644 swarm-queue-client/src/agent_commands.rs create mode 100644 swarm-wire/src/agent_commands.rs 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;