Watch
0
0
Fork
You've already forked hyperhive
0
hyperhive/swarm-queue-client/src/archetypes.rs
atlas 68c24643f6 archetype flows behave like the built-ins: switch off per archetype or per agent, board cards, duplicate
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.
2026-11-11 21:40:17 +01:00

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);
}
}