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.
This commit is contained in:
parent
06c338ff40
commit
8f11a38d17
1 changed files with 389 additions and 7 deletions
130
swarm-wire/src/agent_commands.rs
Normal file
130
swarm-wire/src/agent_commands.rs
Normal file
|
|
@ -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**, `<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"}]}"#
|
||||
);
|
||||
}
|
||||
}
|
||||
Loading…
Reference in a new issue