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
11 changed files with 389 additions and 7 deletions
|
|
@ -278,6 +278,14 @@ the stored bytes, and 404 means the agent has no icon. swarm-ui's agent cards
|
||||||
load it as an `<img>` and show the dimmed default agent icon (a robot head in a
|
load it as an `<img>` and show the dimmed default agent icon (a robot head in a
|
||||||
round frame, `branding/agent-default.svg`) for an agent without one.
|
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.<agent>` and nothing else of the bucket. The value is a
|
||||||
|
list of `{name, description}`. `GET /api/agents/<name>/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 fourth is its **`AGENTS.md`**, which goes into the `agents-md` bucket under
|
||||||
the key `<agent>`, writable by the agent's own credential alone
|
the key `<agent>`, writable by the agent's own credential alone
|
||||||
(`$KV.agents-md.<agent>`). The swarm reads that copy and edits the file through
|
(`$KV.agents-md.<agent>`). The swarm reads that copy and edits the file through
|
||||||
|
|
|
||||||
|
|
@ -995,6 +995,11 @@ in
|
||||||
# and swarm-controller creates the bucket, so no
|
# and swarm-controller creates the bucket, so no
|
||||||
# `$$JS.API.*` subject.
|
# `$$JS.API.*` subject.
|
||||||
"--agent-token-publish-subject ${lib.escapeShellArg "\$\$KV.subagent-status.{agent}.*"}"
|
"--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
|
# Its bash tasks (`swarm_wire::bash_task`): one status key per
|
||||||
# task in the `bash-task-status` KV bucket and the task's output
|
# task in the `bash-task-status` KV bucket and the task's output
|
||||||
# rows. Publish only and no `$JS.API.*` subject:
|
# rows. Publish only and no `$JS.API.*` subject:
|
||||||
|
|
|
||||||
|
|
@ -545,6 +545,7 @@ let
|
||||||
"'$$KV.agents-md.{agent}'"
|
"'$$KV.agents-md.{agent}'"
|
||||||
"'$$SWARM.term.{agent}.sub.>'"
|
"'$$SWARM.term.{agent}.sub.>'"
|
||||||
"'$$KV.subagent-status.{agent}.*'"
|
"'$$KV.subagent-status.{agent}.*'"
|
||||||
|
"'$$KV.agent-commands.{agent}'"
|
||||||
"'$$KV.bash-task-status.{agent}.*'"
|
"'$$KV.bash-task-status.{agent}.*'"
|
||||||
"'$$SWARM.term.{agent}.bash.>'"
|
"'$$SWARM.term.{agent}.bash.>'"
|
||||||
"'$$JS.API.DIRECT.GET.KV_agent-schedules.$$KV.agent-schedules.{agent}'"
|
"'$$JS.API.DIRECT.GET.KV_agent-schedules.$$KV.agent-schedules.{agent}'"
|
||||||
|
|
|
||||||
207
swarm-controller/src/agent_commands.rs
Normal file
207
swarm-controller/src/agent_commands.rs
Normal file
|
|
@ -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<Skills>) -> Vec<CommandEntry> {
|
||||||
|
let mut entries: Vec<CommandEntry> = COMMANDS
|
||||||
|
.iter()
|
||||||
|
.map(|&(name, description)| CommandEntry {
|
||||||
|
name: name.to_owned(),
|
||||||
|
description: description.to_owned(),
|
||||||
|
kind: CommandKind::Command,
|
||||||
|
})
|
||||||
|
.collect();
|
||||||
|
let mut skills: Vec<CommandEntry> = 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<CommandEntry>),
|
||||||
|
(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<AppState>,
|
||||||
|
Path(agent): Path<String>,
|
||||||
|
) -> Result<Json<Vec<CommandEntry>>, 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::<Skills>(&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<Skill> = (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)
|
||||||
|
);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
@ -22,6 +22,7 @@ use std::sync::{Arc, Mutex};
|
||||||
use anyhow::{Context, Result};
|
use anyhow::{Context, Result};
|
||||||
|
|
||||||
mod agent_archetype;
|
mod agent_archetype;
|
||||||
|
mod agent_commands;
|
||||||
mod agent_config_repo;
|
mod agent_config_repo;
|
||||||
mod agent_control;
|
mod agent_control;
|
||||||
mod agent_custom;
|
mod agent_custom;
|
||||||
|
|
|
||||||
|
|
@ -26,13 +26,13 @@ use crate::jobq::{
|
||||||
use crate::routes::hives::{HiveEntry, ServiceLink};
|
use crate::routes::hives::{HiveEntry, ServiceLink};
|
||||||
use crate::routes::{self, AppState, agents, config_prs, forge_admin, hives, jobq_graph};
|
use crate::routes::{self, AppState, agents, config_prs, forge_admin, hives, jobq_graph};
|
||||||
use crate::{
|
use crate::{
|
||||||
agent_control, agent_custom, agent_icon, agent_input, agent_limits, agent_login,
|
agent_commands, agent_control, agent_custom, agent_icon, agent_input, agent_limits,
|
||||||
agent_permissions, agent_renewal, agent_state_stream, agent_status, agents_md, alerts,
|
agent_login, agent_permissions, agent_renewal, agent_state_stream, agent_status, agents_md,
|
||||||
archetypes, auth, backend_env, bash_task, builder, claude_login, config_drift, config_pr,
|
alerts, archetypes, auth, backend_env, bash_task, builder, claude_login, config_drift,
|
||||||
egress_allow, egress_deny, forge, forge_account, github_account, gitlab_account, inference,
|
config_pr, egress_allow, egress_deny, forge, forge_account, github_account, gitlab_account,
|
||||||
issue_report, linked_accounts, matrix_account, message_stream, notify_flows, notify_router_api,
|
inference, issue_report, linked_accounts, matrix_account, message_stream, notify_flows,
|
||||||
pause_hold, pr_report, pulls, queue_identity, review_classifier, schedules, status,
|
notify_router_api, pause_hold, pr_report, pulls, queue_identity, review_classifier, schedules,
|
||||||
subagent_term, term_stream, wanted, webhook,
|
status, subagent_term, term_stream, wanted, webhook,
|
||||||
};
|
};
|
||||||
|
|
||||||
/// Where the daemon binds, overridable via `SWARM_CONTROLLER_SOCKET`.
|
/// 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!(message_stream::stream_messages))
|
||||||
.routes(routes!(subagent_term::list_subagents))
|
.routes(routes!(subagent_term::list_subagents))
|
||||||
.routes(routes!(bash_task::list_bash_tasks))
|
.routes(routes!(bash_task::list_bash_tasks))
|
||||||
|
.routes(routes!(agent_commands::list_commands))
|
||||||
.routes(routes!(subagent_term::stream_subagent_term))
|
.routes(routes!(subagent_term::stream_subagent_term))
|
||||||
.routes(routes!(agent_state_stream::stream_agent_state))
|
.routes(routes!(agent_state_stream::stream_agent_state))
|
||||||
.routes(routes!(agent_input::post_agent_input))
|
.routes(routes!(agent_input::post_agent_input))
|
||||||
|
|
|
||||||
|
|
@ -85,6 +85,12 @@ pub(crate) fn spawn(client: async_nats::Client, wanted: Arc<WantedWriter>, hives
|
||||||
"bash task status: opening the bucket failed; next pass"
|
"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 {
|
for agent in live_agents(&wanted, &hives).await {
|
||||||
if let Err(e) = swarm_queue_client::bash_task::open_output(&client, &agent).await {
|
if let Err(e) = swarm_queue_client::bash_task::open_output(&client, &agent).await {
|
||||||
tracing::warn!(
|
tracing::warn!(
|
||||||
|
|
|
||||||
18
swarm-queue-client/src/agent_commands.rs
Normal file
18
swarm-queue-client/src/agent_commands.rs
Normal file
|
|
@ -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<async_nats::jetstream::kv::Store, crate::Error> {
|
||||||
|
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
|
||||||
|
}
|
||||||
|
|
@ -214,6 +214,10 @@ pub mod bash_task;
|
||||||
/// `swarm_wire::subagent_status`; opening the bucket needs `kv`.
|
/// `swarm_wire::subagent_status`; opening the bucket needs `kv`.
|
||||||
pub mod subagent_status;
|
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
|
/// 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,
|
/// 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`.
|
/// and why the placement stays out of the key, are in `swarm_wire::agent_icon`.
|
||||||
|
|
|
||||||
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"}]}"#
|
||||||
|
);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
@ -7,6 +7,7 @@
|
||||||
|
|
||||||
pub mod agent_archetype;
|
pub mod agent_archetype;
|
||||||
pub mod agent_closures;
|
pub mod agent_closures;
|
||||||
|
pub mod agent_commands;
|
||||||
pub mod agent_icon;
|
pub mod agent_icon;
|
||||||
pub mod agent_inference;
|
pub mod agent_inference;
|
||||||
pub mod agent_limits;
|
pub mod agent_limits;
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue