diff --git a/docs/4-implementation/swarm/controller.md b/docs/4-implementation/swarm/controller.md index bee6a590a..94abd7c3b 100644 --- a/docs/4-implementation/swarm/controller.md +++ b/docs/4-implementation/swarm/controller.md @@ -271,9 +271,10 @@ The third thing a hive's agent has is its **icon**, the same SVG its own ``, with no hive in it, so the swarm can show the icon of an agent that's stopped or has moved hives. The [builder](builder.md) reads it from the agent's evaluated config when it builds the agent for a deploy, and the controller writes -the key from the reply: an agent with no icon has its key deleted. The controller is the only -writer: no agent credential has a grant on the bucket, and the write needs no -running agent. Swarm-side, +the key from the reply: an agent with no icon has its key deleted. The harness +still publishes the same file once per start, with its own credential's grant of +`$KV.agent-icons.`; the controller's write is the one that matters, since it +doesn't need the agent running. Swarm-side, `GET /api/agents//icon` serves the stored bytes, and 404 means the agent has no icon. swarm-ui's agent cards load it as an `` and show the dimmed default agent icon (a robot head in a diff --git a/hive-agent/src/main.rs b/hive-agent/src/main.rs index 28eef49eb..a94f273fb 100644 --- a/hive-agent/src/main.rs +++ b/hive-agent/src/main.rs @@ -36,6 +36,7 @@ mod state_entry_watch; mod stats; mod subagent_role_watch; mod swarm_agent_commands; +mod swarm_agent_icon; mod swarm_agent_state; mod swarm_agent_todos; mod swarm_agents_md; @@ -510,6 +511,8 @@ async fn serve_main(socket: &Path, poll_ms: u64) -> Result<()> { // state from this agent's first transition, not from whenever a reader // first asked. swarm_agent_state::spawn(&bus, login_state.clone()); + // Once per start: a new icon only arrives with a new harness process. + swarm_agent_icon::spawn(); // The skills claude reports, published once at the first turn and whenever they change. swarm_agent_commands::spawn(); // Before the mirror and before any turn reads the file. diff --git a/hive-agent/src/swarm_agent_commands.rs b/hive-agent/src/swarm_agent_commands.rs index 75513be6d..fe8ad2193 100644 --- a/hive-agent/src/swarm_agent_commands.rs +++ b/hive-agent/src/swarm_agent_commands.rs @@ -26,7 +26,7 @@ use serde_json::Value; use swarm_wire::agent_commands::{self, Skill, Skills}; use tokio::sync::watch; -use crate::swarm_kv_put::{Failure, put_retrying}; +use crate::swarm_kv_put::{Failure, Put, put_retrying}; /// The newest list claude reported, for [`run`] to publish. `None` until the /// first init event of this process. @@ -102,7 +102,7 @@ async fn run(agent: String) { continue; } }; - match put_retrying(&client, &subject, &payload, "the agent's skills").await { + match put_retrying(&client, &subject, Put::Set(&payload), "the agent's skills").await { Ok(()) => tracing::info!( subject, count = skills.skills.len(), diff --git a/hive-agent/src/swarm_agent_icon.rs b/hive-agent/src/swarm_agent_icon.rs new file mode 100644 index 000000000..d3d7130de --- /dev/null +++ b/hive-agent/src/swarm_agent_icon.rs @@ -0,0 +1,123 @@ +//! Publishing this agent's icon into the swarm's `agent-icons` bucket. +//! +//! The bytes are the file the harness's own `GET /icon` serves +//! ([`ICON_PATH`]), unmodified. The key is the agent name, so the swarm can +//! show the icon while the agent is stopped or after it has moved hives. +//! +//! **Once per harness start.** The icon comes from the agent's NixOS config, +//! and a config change is applied by stopping the container, switching it and +//! starting it again, so a new icon always arrives with a new harness process. +//! An agent with no icon deletes its key, so an icon removed from the config +//! also disappears from the swarm. +//! +//! The agent's own queue credential is granted exactly this agent's key. +//! +//! The write is a `JetStream` publish straight to the key's subject, the same +//! message `kv::Store::put` sends, without opening the bucket first. That +//! keeps the grant to the one subject. swarm-controller creates the bucket, +//! so a write can arrive before it exists; that write and any other failed +//! one are retried with backoff until one is acked. + +use std::path::Path; + +use crate::swarm_kv_put::{Failure, Put, put_retrying}; + +/// Where the agent's NixOS config puts the icon +/// (`services.hyperhive.agent.icon`), and the file `GET /icon` serves. Absent +/// when none is configured. +const ICON_PATH: &str = "/etc/hyperhive/icon.svg"; + +/// What to write under this agent's key. +#[derive(Debug, PartialEq, Eq)] +enum Icon { + /// The SVG's bytes. + Set(Vec), + /// No icon is configured, so the key is deleted. + Unset, +} + +/// Read the icon at `path`. A missing file is [`Icon::Unset`]; any other read +/// error is returned, and the key is left as it is. +fn read_icon(path: &Path) -> std::io::Result { + match std::fs::read(path) { + Ok(bytes) => Ok(Icon::Set(bytes)), + Err(e) if e.kind() == std::io::ErrorKind::NotFound => Ok(Icon::Unset), + Err(e) => Err(e), + } +} + +/// Start the publish task, if this agent has a label. +pub fn spawn() { + let agent = crate::identity::label(); + if agent.is_empty() { + tracing::warn!("this agent has no label; not publishing its icon upward"); + return; + } + tokio::spawn(run(agent)); +} + +async fn run(agent: String) { + let client = crate::swarm_queue::client().await; + let subject = swarm_wire::agent_icon::subject(&agent); + let icon = match read_icon(Path::new(ICON_PATH)) { + Ok(icon) => icon, + Err(e) => { + tracing::warn!(path = ICON_PATH, error = %e, "reading the agent icon failed; not publishing it"); + return; + } + }; + let put = match &icon { + Icon::Set(bytes) => Put::Set(bytes), + Icon::Unset => Put::Delete, + }; + let written = put_retrying(&client, &subject, put, "the agent icon").await; + match written { + Ok(()) => tracing::info!( + subject, + set = matches!(icon, Icon::Set(_)), + "published this agent's icon" + ), + Err(Failure::TooLarge(e)) => { + tracing::warn!(error = %e, "the agent icon is over the queue's payload limit; not publishing it"); + } + // Only a `TooLarge` ends the retries. + Err(Failure::Retry(e)) => { + tracing::error!(error = e, "gave up publishing the agent icon"); + } + } +} + +#[cfg(test)] +mod tests { + use super::{Icon, read_icon}; + + #[test] + fn a_configured_icon_is_published_byte_for_byte() { + let dir = tempfile::tempdir().expect("tempdir"); + let path = dir.path().join("icon.svg"); + std::fs::write(&path, b"\n").expect("write"); + assert_eq!( + read_icon(&path).expect("read"), + Icon::Set(b"\n".to_vec()) + ); + } + + /// No file is the unconfigured state, which clears the key rather than + /// leaving a removed icon in the swarm. + #[test] + fn no_icon_file_clears_the_key() { + let dir = tempfile::tempdir().expect("tempdir"); + assert_eq!( + read_icon(&dir.path().join("icon.svg")).expect("read"), + Icon::Unset + ); + } + + /// Any other read failure is an error, so a transient one does not delete + /// an icon the agent still has. + #[test] + fn an_unreadable_icon_is_an_error_not_an_unset_icon() { + let dir = tempfile::tempdir().expect("tempdir"); + assert!(read_icon(dir.path()).is_err()); + } +} diff --git a/hive-agent/src/swarm_agent_todos.rs b/hive-agent/src/swarm_agent_todos.rs index 8288067b4..3fbcc9da8 100644 --- a/hive-agent/src/swarm_agent_todos.rs +++ b/hive-agent/src/swarm_agent_todos.rs @@ -17,7 +17,7 @@ use swarm_wire::agent_todos::{ self, MAX_LABEL_CHARS, MAX_SUMMARY_CHARS, MAX_TODOS, Todo as WireTodo, Todos as WireTodos, }; -use crate::swarm_kv_put::{Failure, put_retrying}; +use crate::swarm_kv_put::{Failure, Put, put_retrying}; use crate::todos::{Todo, Todos}; /// How often the open todos are read. @@ -85,7 +85,7 @@ async fn publish(client: &async_nats::Client, subject: &str, list: &WireTodos) { return; } }; - match put_retrying(client, subject, &payload, "the agent's todos").await { + match put_retrying(client, subject, Put::Set(&payload), "the agent's todos").await { Ok(()) => { tracing::debug!( subject, diff --git a/hive-agent/src/swarm_agents_md.rs b/hive-agent/src/swarm_agents_md.rs index 0482a1d34..292358e81 100644 --- a/hive-agent/src/swarm_agents_md.rs +++ b/hive-agent/src/swarm_agents_md.rs @@ -9,7 +9,7 @@ //! [`swarm_queue_client::agents_md::subject`] at start, whenever a re-read //! every [`POLL`] finds a new revision, and straight after an applied edit. //! The write is a `JetStream` publish to the key's subject, as -//! [`crate::swarm_agent_commands`] does it, so the grant is that one subject; a +//! [`crate::swarm_agent_icon`] does it, so the grant is that one subject; a //! failed write is retried on the next poll. //! //! **Edit.** [`handle`] answers an [`Apply`] from the control subject: it diff --git a/hive-agent/src/swarm_kv_put.rs b/hive-agent/src/swarm_kv_put.rs index 6e5456b9c..ee3fe4ba2 100644 --- a/hive-agent/src/swarm_kv_put.rs +++ b/hive-agent/src/swarm_kv_put.rs @@ -5,8 +5,8 @@ //! a write can arrive before it exists; that write and any other failed one are //! retried with backoff until one is acked. //! -//! Shared by the writers of an agent's own keys, such as -//! [`crate::swarm_agent_commands`]. +//! Shared by the writers of an agent's own keys: [`crate::swarm_agent_icon`] +//! and [`crate::swarm_agent_commands`]. use std::time::Duration; @@ -20,6 +20,19 @@ const FIRST_RETRY: Duration = Duration::from_secs(5); /// Longest wait between retries. const MAX_RETRY: Duration = Duration::from_mins(5); +/// The KV header and value that mark an entry deleted. `kv::Store::get` +/// answers `None` for an entry carrying them. +const KV_OPERATION: &str = "KV-Operation"; +const KV_OPERATION_DELETE: &str = "DEL"; + +/// What to write under a key. +pub enum Put<'a> { + /// These bytes as the key's value. + Set(&'a [u8]), + /// Delete the key. + Delete, +} + /// Why a write did not land. pub enum Failure { /// The payload can never fit; retrying cannot help. @@ -28,19 +41,27 @@ pub enum Failure { Retry(String), } -/// One acked write of `bytes` to `subject`. +/// One acked write of `put` to `subject`. async fn put_once( client: &async_nats::Client, js: &async_nats::jetstream::Context, subject: &str, - bytes: &[u8], + put: &Put<'_>, ) -> Result<(), Failure> { // An unconnected client does not fail a publish, it buffers it, and the // payload limit it checks against is the library default until the // server has announced its own. swarm_queue_client::ensure_connected(client) .map_err(|e| Failure::Retry(swarm_queue_client::chain(&e)))?; - let sent = js.publish(subject.to_owned(), bytes.to_vec().into()).await; + let sent = match put { + Put::Set(bytes) => js.publish(subject.to_owned(), bytes.to_vec().into()).await, + Put::Delete => { + let mut headers = async_nats::HeaderMap::new(); + headers.insert(KV_OPERATION, KV_OPERATION_DELETE); + js.publish_with_headers(subject.to_owned(), headers, Vec::new().into()) + .await + } + }; let ack = sent.map_err(|e| match e.kind() { PublishErrorKind::MaxPayloadExceeded => Failure::TooLarge(e), _ => Failure::Retry(e.to_string()), @@ -55,11 +76,11 @@ async fn put_once( pub async fn put_retrying( client: &async_nats::Client, subject: &str, - bytes: &[u8], + put: Put<'_>, what: &str, ) -> Result<(), Failure> { let js = async_nats::jetstream::new(client.clone()); - (|| put_once(client, &js, subject, bytes)) + (|| put_once(client, &js, subject, &put)) .retry( ExponentialBuilder::default() .with_min_delay(FIRST_RETRY) diff --git a/nix/host-modules/swarm-nats.nix b/nix/host-modules/swarm-nats.nix index 4230f1499..1dccaa884 100644 --- a/nix/host-modules/swarm-nats.nix +++ b/nix/host-modules/swarm-nats.nix @@ -971,6 +971,13 @@ in # responder as the empty expansion of an unset `SWARM`. "--agent-token-publish-subject ${lib.escapeShellArg "\$\$SWARM.term.{agent}"}" "--agent-token-publish-subject ${lib.escapeShellArg "\$\$SWARM.agent-state.{agent}"}" + # Its own key in the `agent-icons` KV bucket, and nothing else + # of JetStream. A KV put is a JetStream publish to + # `$KV..`, acked on the client's inbox, so this + # one subject is the whole write. The harness publishes to the + # subject directly instead of opening the bucket, so it needs + # no `$JS.API.*` subject; swarm-controller creates the bucket. + "--agent-token-publish-subject ${lib.escapeShellArg "\$\$KV.agent-icons.{agent}"}" # Its own key in the `agents-md` KV bucket # (`swarm_queue_client::agents_md`), on the same terms: the # harness mirrors its `AGENTS.md` there for the swarm to read. diff --git a/nix/module-eval/nats-authelia.nix b/nix/module-eval/nats-authelia.nix index 587561aaf..685cf5a03 100644 --- a/nix/module-eval/nats-authelia.nix +++ b/nix/module-eval/nats-authelia.nix @@ -541,6 +541,7 @@ let granted == [ "'$$SWARM.term.{agent}'" "'$$SWARM.agent-state.{agent}'" + "'$$KV.agent-icons.{agent}'" "'$$KV.agents-md.{agent}'" "'$$SWARM.term.{agent}.sub.>'" "'$$KV.subagent-status.{agent}.*'" diff --git a/swarm-controller/src/agent_icon.rs b/swarm-controller/src/agent_icon.rs index 7d0b93687..ee871925c 100644 --- a/swarm-controller/src/agent_icon.rs +++ b/swarm-controller/src/agent_icon.rs @@ -9,8 +9,8 @@ //! **No hive is named on this path**, because the key does not carry one — //! see `swarm_wire::agent_icon` for why, and for who writes it. //! -//! This reader is also what creates the bucket, and the controller is the only -//! writer: it sets the key from the builder's reply (`meta_build`). +//! This reader is also what creates the bucket: the agents that write it are +//! granted their own key and nothing that could create a stream. use anyhow::{Context, Result}; diff --git a/swarm-wire/src/agent_icon.rs b/swarm-wire/src/agent_icon.rs index a0f645ce6..200f740f2 100644 --- a/swarm-wire/src/agent_icon.rs +++ b/swarm-wire/src/agent_icon.rs @@ -14,12 +14,18 @@ //! container is stopped: the value's lifetime is the agent's, not its //! placement's. //! -//! **The swarm controller is the only writer.** It writes the key from the +//! **Two writers, one value.** The swarm controller writes the key from the //! builder's reply when it builds the agent for a deploy: the builder reads the -//! icon from the agent's config, so the write needs no running agent. An icon -//! that is not set deletes the key. No agent credential may write here, and the -//! controller creates the bucket (`swarm_queue_client::agent_icon::open_or_create`). -//! [`subject`] is the subject a KV put to a key goes to. +//! icon from the agent's config, so this write needs no running agent. The +//! agent's harness writes the same key, from the same config, with its own +//! queue credential, which the auth callout grants `$KV.agent-icons.` and +//! no other key. On either side an icon that is not set deletes the key. +//! +//! The harness publishes to [`subject`] directly instead of opening the +//! bucket, so that one subject is its whole grant. Creating the bucket is left +//! to the reader (`swarm_queue_client::agent_icon::open_or_create`). A write +//! that arrives before the bucket exists is refused with "no stream", and the +//! harness retries. /// The KV bucket agent icons are published into, keyed by agent name. /// @@ -40,8 +46,8 @@ pub const MEDIA_TYPE: &str = "image/svg+xml"; /// The subject `agent`'s entry is written on: `$KV..`, where the /// key is the agent name and nothing else. /// -/// A KV put is a `JetStream` publish to this subject, and the bucket's `get` -/// reads the same one. +/// A KV put is a `JetStream` publish to this subject, so a writer that +/// publishes directly has to use the same subject the bucket's `get` reads. #[must_use] pub fn subject(agent: &str) -> String { format!("$KV.{BUCKET}.{agent}") @@ -51,8 +57,9 @@ pub fn subject(agent: &str) -> String { mod tests { use super::subject; - /// One token after the bucket, the agent name alone: no hive in the key, so - /// a hive-scoped subject (`$KV...*`, two tokens) cannot match. + /// One token after the bucket, the agent name alone. That is what the + /// per-agent grant `$KV.agent-icons.{agent}` expands to, and what a + /// hive-scoped grant (`$KV...*`, two tokens) cannot match. #[test] fn the_published_subject_carries_the_agent_and_no_placement() { assert_eq!(subject("iris"), "$KV.agent-icons.iris");