Watch
0
0
Fork
You've already forked hyperhive
0
hyperhive/swarm-wire/src/agent_commands.rs
iris 8f11a38d17 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.
2026-11-15 20:05:54 +01:00

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