//! 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`/``. #[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, /// Every archetype whose `meta` did not, by name, with the reason. #[serde(default, skip_serializing_if = "BTreeMap::is_empty")] pub refused: BTreeMap, } /// 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>, #[serde(default, skip_serializing_if = "Option::is_none")] pub limits: Option, #[serde(default, skip_serializing_if = "Option::is_none")] pub inference: Option, /// 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, /// 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, /// 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, } /// 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, } 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, records: &BTreeMap, ) -> (Vec, Vec) { let mut agents: BTreeMap<(&str, &str), Vec> = 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 { 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, 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::(&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::(&wire).unwrap(), meta); } }