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.
130 lines
4.5 KiB
Rust
130 lines
4.5 KiB
Rust
//! 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**, `<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<Skill>,
|
|
}
|
|
|
|
/// The subject `agent`'s list is written on: `$KV.<bucket>.<agent>`, 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::<Vec<_>>().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"}]}"#
|
|
);
|
|
}
|
|
}
|