//! 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"}]}"# ); } }