The document's disabled list takes archetype:<archetype>/<flow> (off for every member) and the same with @<agent> (off for one member); a key naming nothing is ignored. GET /api/notify/flows lists the archetype flows with their members, the board draws a card for each with a switch, a checkbox per agent and duplicate, and the dry run counts their hits. The flows keep following the archetype.
271 lines
10 KiB
Rust
271 lines
10 KiB
Rust
//! The agent archetype KV bucket: one key per archetype source flake, holding
|
|
//! the `meta` of every archetype that flake's `hyperhiveArchetypes` output
|
|
//! declares, as swarm-controller last checked it.
|
|
//!
|
|
//! **swarm-controller is the only writer and the only reader.** The swarm
|
|
//! builder evaluates the source and answers on
|
|
//! `swarm_wire::builder::ARCHETYPES_SUBJECT`; the controller checks each
|
|
//! archetype's settings the way `POST /api/agents` checks them and writes the
|
|
//! result here, so the create screen lists archetypes from a value that a
|
|
//! create would accept.
|
|
|
|
use std::collections::{BTreeMap, BTreeSet};
|
|
|
|
use swarm_wire::agent_archetype::ArchetypeRef;
|
|
use swarm_wire::agent_inference::AgentInference;
|
|
use swarm_wire::agent_limits::AgentCaps;
|
|
use swarm_wire::notify_flows::{Flow, archetype_flow_key};
|
|
|
|
/// The KV bucket archetype sources are published into, keyed by source name.
|
|
pub const BUCKET: &str = "agent-archetypes";
|
|
|
|
/// The key of the archetypes the hyperhive flake itself ships, the one source
|
|
/// there is so far.
|
|
pub const BUILTIN_SOURCE: &str = "hyperhive";
|
|
|
|
/// The most bytes an archetype's `meta.prompt` may hold: the limit of an
|
|
/// agent's initial `AGENTS.md`, which the prompt prefills.
|
|
pub const MAX_PROMPT_BYTES: usize = crate::agents_md_initial::MAX_BYTES;
|
|
|
|
/// The most bytes an archetype's `meta.icon` may hold. The swarm stores the SVG
|
|
/// text in the record and the create form shows it beside the archetype.
|
|
pub const MAX_ICON_BYTES: usize = 16 * 1024;
|
|
|
|
/// One source's archetypes: the value under `BUCKET`/`<source>`.
|
|
#[derive(Debug, Clone, Default, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
|
|
pub struct SourceRecord {
|
|
/// The flake reference the builder evaluated.
|
|
pub source: String,
|
|
/// Every archetype whose `meta` passed the controller's checks, by name.
|
|
#[serde(default)]
|
|
pub archetypes: BTreeMap<String, ArchetypeMeta>,
|
|
/// Every archetype whose `meta` did not, by name, with the reason.
|
|
#[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
|
|
pub refused: BTreeMap<String, String>,
|
|
}
|
|
|
|
/// One archetype's `meta`, as checked: the settings a create takes, in the
|
|
/// shapes the per-agent buckets store them in.
|
|
#[derive(Debug, Clone, Default, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
|
|
pub struct ArchetypeMeta {
|
|
pub description: String,
|
|
/// Permission names, `snake_case`. Absent leaves the default set.
|
|
#[serde(default, skip_serializing_if = "Option::is_none")]
|
|
pub permissions: Option<Vec<String>>,
|
|
#[serde(default, skip_serializing_if = "Option::is_none")]
|
|
pub limits: Option<AgentCaps>,
|
|
#[serde(default, skip_serializing_if = "Option::is_none")]
|
|
pub inference: Option<AgentInference>,
|
|
/// The text the create form prefills an agent's initial `AGENTS.md` with,
|
|
/// at most [`MAX_PROMPT_BYTES`]. Absent prefills nothing.
|
|
#[serde(default, skip_serializing_if = "Option::is_none")]
|
|
pub prompt: Option<String>,
|
|
/// The archetype's icon as SVG text, at most [`MAX_ICON_BYTES`]. Absent shows
|
|
/// none.
|
|
#[serde(default, skip_serializing_if = "Option::is_none")]
|
|
pub icon: Option<String>,
|
|
/// The notification-router flows every agent of this archetype gets, next
|
|
/// to the operator's document and the built-ins. Their todos go to
|
|
/// `Recipients::Members`; the router runs them, and absent means none.
|
|
#[serde(default, skip_serializing_if = "Vec::is_empty")]
|
|
pub flows: Vec<Flow>,
|
|
}
|
|
|
|
/// One flow an archetype carries, with the agents of that archetype.
|
|
#[derive(Debug, Clone, PartialEq, Eq)]
|
|
pub struct ArchetypeFlow {
|
|
pub archetype: String,
|
|
/// As the archetype declares it, under its own `id`.
|
|
pub flow: Flow,
|
|
/// The agents whose archetype this is, by name.
|
|
pub members: Vec<String>,
|
|
}
|
|
|
|
impl ArchetypeFlow {
|
|
/// The name the flow goes by, see [`archetype_flow_key`].
|
|
#[must_use]
|
|
pub fn key(&self) -> String {
|
|
archetype_flow_key(&self.archetype, &self.flow.id)
|
|
}
|
|
}
|
|
|
|
/// The flows to run: each enabled flow of each archetype that has an agent
|
|
/// in `refs` (agent to archetype), with those agents, and why any flow was
|
|
/// left out. A flow that fails [`Flow::validate_archetype`] or repeats an id
|
|
/// of its archetype is left out.
|
|
#[must_use]
|
|
pub fn flows_of(
|
|
refs: &BTreeMap<String, ArchetypeRef>,
|
|
records: &BTreeMap<String, SourceRecord>,
|
|
) -> (Vec<ArchetypeFlow>, Vec<String>) {
|
|
let mut agents: BTreeMap<(&str, &str), Vec<String>> = BTreeMap::new();
|
|
for (agent, r) in refs {
|
|
agents
|
|
.entry((r.source.as_str(), r.name.as_str()))
|
|
.or_default()
|
|
.push(agent.clone());
|
|
}
|
|
let mut active = Vec::new();
|
|
let mut skipped = Vec::new();
|
|
for ((source, name), members) in agents {
|
|
let Some(meta) = records
|
|
.get(source)
|
|
.and_then(|record| record.archetypes.get(name))
|
|
else {
|
|
continue;
|
|
};
|
|
let mut ids = BTreeSet::new();
|
|
for flow in meta.flows.iter().filter(|f| f.enabled) {
|
|
if !ids.insert(flow.id.as_str()) {
|
|
skipped.push(format!("{name}: flow {}: its id is used twice", flow.id));
|
|
} else if let Err(why) = flow.validate_archetype() {
|
|
skipped.push(format!("{name}: flow {}: {why}", flow.id));
|
|
} else {
|
|
active.push(ArchetypeFlow {
|
|
archetype: name.to_owned(),
|
|
flow: flow.clone(),
|
|
members: members.clone(),
|
|
});
|
|
}
|
|
}
|
|
}
|
|
(active, skipped)
|
|
}
|
|
|
|
/// Open the archetype bucket for writing, creating it if nothing has yet.
|
|
///
|
|
/// **Controller-side only.** `history: 1`: a reader wants the current value.
|
|
#[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,
|
|
BUCKET,
|
|
"agent-archetypes",
|
|
"Agent archetypes the swarm builder evaluated, one key per source flake".to_owned(),
|
|
)
|
|
.await
|
|
}
|
|
|
|
/// Open the archetype bucket for reading, or `None` when nothing has created
|
|
/// it yet, which reads the same as no archetypes.
|
|
///
|
|
/// # Errors
|
|
///
|
|
/// [`crate::Error::OpenBucket`] for every failure other than the bucket not
|
|
/// existing.
|
|
#[cfg(feature = "kv")]
|
|
pub async fn open(
|
|
client: &async_nats::Client,
|
|
) -> Result<Option<async_nats::jetstream::kv::Store>, crate::Error> {
|
|
let js = async_nats::jetstream::new(client.clone());
|
|
match js.get_key_value(BUCKET).await {
|
|
Ok(store) => Ok(Some(store)),
|
|
Err(e) if crate::wanted::is_bucket_not_found(&e) => Ok(None),
|
|
Err(source) => Err(crate::Error::OpenBucket {
|
|
bucket: BUCKET.to_owned(),
|
|
source,
|
|
}),
|
|
}
|
|
}
|
|
|
|
#[cfg(test)]
|
|
mod tests {
|
|
use super::*;
|
|
|
|
/// An unset setting is left out on the wire, and so is an empty refusal
|
|
/// list.
|
|
#[test]
|
|
fn unset_fields_are_absent() {
|
|
let mut archetypes = BTreeMap::new();
|
|
archetypes.insert(
|
|
"reviewer".to_owned(),
|
|
ArchetypeMeta {
|
|
description: "reads".to_owned(),
|
|
permissions: Some(vec!["messaging".to_owned()]),
|
|
..ArchetypeMeta::default()
|
|
},
|
|
);
|
|
let record = SourceRecord {
|
|
source: "/nix/store/h".to_owned(),
|
|
archetypes,
|
|
refused: BTreeMap::new(),
|
|
};
|
|
assert_eq!(
|
|
serde_json::to_string(&record).unwrap(),
|
|
r#"{"source":"/nix/store/h","archetypes":{"reviewer":{"description":"reads","permissions":["messaging"]}}}"#
|
|
);
|
|
}
|
|
|
|
/// A record stored before `prompt` existed still parses, with no prompt;
|
|
/// one with a prompt round-trips it.
|
|
#[test]
|
|
fn prompt_is_optional_on_the_wire() {
|
|
let old = r#"{"source":"s","archetypes":{"reviewer":{"description":"reads"}}}"#;
|
|
let mut record: SourceRecord = serde_json::from_str(old).unwrap();
|
|
assert_eq!(record.archetypes["reviewer"].prompt, None);
|
|
|
|
record.archetypes.get_mut("reviewer").unwrap().prompt = Some("be brief".to_owned());
|
|
let wire = serde_json::to_string(&record).unwrap();
|
|
assert!(wire.contains(r#""prompt":"be brief""#), "{wire}");
|
|
assert_eq!(serde_json::from_str::<SourceRecord>(&wire).unwrap(), record);
|
|
}
|
|
|
|
fn members_flow() -> Flow {
|
|
use swarm_wire::notify_flows::{Edge, Node, NodeKind, Recipients, TodoSink};
|
|
use swarm_wire::router_todo::Op;
|
|
|
|
Flow {
|
|
id: "new-issues".to_owned(),
|
|
name: "new issues".to_owned(),
|
|
enabled: true,
|
|
nodes: vec![
|
|
Node {
|
|
id: "src".to_owned(),
|
|
kind: NodeKind::Source {
|
|
events: vec!["issues".to_owned()],
|
|
},
|
|
},
|
|
Node {
|
|
id: "tell".to_owned(),
|
|
kind: NodeKind::Todo(TodoSink {
|
|
to: Recipients::Members,
|
|
op: Op::Upsert,
|
|
key: "forge:{{ repo }}#{{ number }}:new".to_owned(),
|
|
prefix: false,
|
|
text: "new issue {{ title }}".to_owned(),
|
|
}),
|
|
},
|
|
],
|
|
edges: vec![Edge {
|
|
from: "src".to_owned(),
|
|
to: "tell".to_owned(),
|
|
}],
|
|
}
|
|
}
|
|
|
|
/// A record stored before `flows` existed reads as an archetype with none,
|
|
/// and an archetype with none is stored without the key.
|
|
#[test]
|
|
fn a_record_without_flows_parses_and_encodes_without_them() {
|
|
let old = r#"{"source":"s","archetypes":{"reviewer":{"description":"reads"}}}"#;
|
|
let record: SourceRecord = serde_json::from_str(old).unwrap();
|
|
assert!(record.archetypes["reviewer"].flows.is_empty());
|
|
assert_eq!(serde_json::to_string(&record).unwrap(), old);
|
|
}
|
|
|
|
/// An archetype's flows survive the bucket, `members` recipient included.
|
|
#[test]
|
|
fn flows_round_trip_with_the_members_recipient() {
|
|
let meta = ArchetypeMeta {
|
|
description: "triage".to_owned(),
|
|
flows: vec![members_flow()],
|
|
..ArchetypeMeta::default()
|
|
};
|
|
let wire = serde_json::to_string(&meta).unwrap();
|
|
assert!(wire.contains(r#""to":"members""#), "{wire}");
|
|
assert_eq!(serde_json::from_str::<ArchetypeMeta>(&wire).unwrap(), meta);
|
|
}
|
|
}
|