From fe4d68c13f06223d6502b8e412ce70b5b48bc0e2 Mon Sep 17 00:00:00 2001 From: iris Date: Mon, 16 Nov 2026 23:07:18 +0100 Subject: [PATCH 1/3] the harness no longer publishes the agent's icon; the controller is its only writer --- docs/4-implementation/swarm/controller.md | 7 +- hive-agent/src/main.rs | 3 - hive-agent/src/swarm_agent_icon.rs | 123 ---------------------- hive-agent/src/swarm_agents_md.rs | 2 +- hive-agent/src/swarm_kv_put.rs | 22 +--- nix/host-modules/swarm-nats.nix | 7 -- nix/module-eval/nats-authelia.nix | 1 - swarm-controller/src/agent_icon.rs | 4 +- swarm-wire/src/agent_icon.rs | 16 +-- 9 files changed, 15 insertions(+), 170 deletions(-) delete mode 100644 hive-agent/src/swarm_agent_icon.rs diff --git a/docs/4-implementation/swarm/controller.md b/docs/4-implementation/swarm/controller.md index 94abd7c3b..bee6a590a 100644 --- a/docs/4-implementation/swarm/controller.md +++ b/docs/4-implementation/swarm/controller.md @@ -271,10 +271,9 @@ 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 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, +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, `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 a94f273fb..28eef49eb 100644 --- a/hive-agent/src/main.rs +++ b/hive-agent/src/main.rs @@ -36,7 +36,6 @@ 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; @@ -511,8 +510,6 @@ 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_icon.rs b/hive-agent/src/swarm_agent_icon.rs deleted file mode 100644 index d3d7130de..000000000 --- a/hive-agent/src/swarm_agent_icon.rs +++ /dev/null @@ -1,123 +0,0 @@ -//! 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_agents_md.rs b/hive-agent/src/swarm_agents_md.rs index 292358e81..0482a1d34 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_icon`] does it, so the grant is that one subject; a +//! [`crate::swarm_agent_commands`] 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 ee3fe4ba2..7651f3ade 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: [`crate::swarm_agent_icon`] -//! and [`crate::swarm_agent_commands`]. +//! Shared by the writers of an agent's own keys, such as +//! [`crate::swarm_agent_commands`]. use std::time::Duration; @@ -20,17 +20,10 @@ 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. @@ -53,15 +46,8 @@ async fn put_once( // server has announced its own. swarm_queue_client::ensure_connected(client) .map_err(|e| Failure::Retry(swarm_queue_client::chain(&e)))?; - 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 Put::Set(bytes) = put; + let sent = js.publish(subject.to_owned(), bytes.to_vec().into()).await; let ack = sent.map_err(|e| match e.kind() { PublishErrorKind::MaxPayloadExceeded => Failure::TooLarge(e), _ => Failure::Retry(e.to_string()), diff --git a/nix/host-modules/swarm-nats.nix b/nix/host-modules/swarm-nats.nix index 1dccaa884..4230f1499 100644 --- a/nix/host-modules/swarm-nats.nix +++ b/nix/host-modules/swarm-nats.nix @@ -971,13 +971,6 @@ 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 685cf5a03..587561aaf 100644 --- a/nix/module-eval/nats-authelia.nix +++ b/nix/module-eval/nats-authelia.nix @@ -541,7 +541,6 @@ 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 ee871925c..7d0b93687 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: the agents that write it are -//! granted their own key and nothing that could create a stream. +//! 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`). use anyhow::{Context, Result}; diff --git a/swarm-wire/src/agent_icon.rs b/swarm-wire/src/agent_icon.rs index 200f740f2..d0230b916 100644 --- a/swarm-wire/src/agent_icon.rs +++ b/swarm-wire/src/agent_icon.rs @@ -14,18 +14,12 @@ //! container is stopped: the value's lifetime is the agent's, not its //! placement's. //! -//! **Two writers, one value.** The swarm controller writes the key from the +//! **The swarm controller is the only writer.** It 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 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. +//! 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. /// The KV bucket agent icons are published into, keyed by agent name. /// From f6a265421fd28529ff128c5dcf8585d771ae6921 Mon Sep 17 00:00:00 2001 From: iris Date: Mon, 16 Nov 2026 23:21:17 +0100 Subject: [PATCH 2/3] swarm_kv_put takes the bytes, not a one-variant enum --- hive-agent/src/swarm_agent_commands.rs | 4 ++-- hive-agent/src/swarm_agent_todos.rs | 4 ++-- hive-agent/src/swarm_kv_put.rs | 15 ++++----------- 3 files changed, 8 insertions(+), 15 deletions(-) diff --git a/hive-agent/src/swarm_agent_commands.rs b/hive-agent/src/swarm_agent_commands.rs index fe8ad2193..75513be6d 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, put_retrying}; +use crate::swarm_kv_put::{Failure, 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, Put::Set(&payload), "the agent's skills").await { + match put_retrying(&client, &subject, &payload, "the agent's skills").await { Ok(()) => tracing::info!( subject, count = skills.skills.len(), diff --git a/hive-agent/src/swarm_agent_todos.rs b/hive-agent/src/swarm_agent_todos.rs index 3fbcc9da8..8288067b4 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, put_retrying}; +use crate::swarm_kv_put::{Failure, 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, Put::Set(&payload), "the agent's todos").await { + match put_retrying(client, subject, &payload, "the agent's todos").await { Ok(()) => { tracing::debug!( subject, diff --git a/hive-agent/src/swarm_kv_put.rs b/hive-agent/src/swarm_kv_put.rs index 7651f3ade..6e5456b9c 100644 --- a/hive-agent/src/swarm_kv_put.rs +++ b/hive-agent/src/swarm_kv_put.rs @@ -20,12 +20,6 @@ const FIRST_RETRY: Duration = Duration::from_secs(5); /// Longest wait between retries. const MAX_RETRY: Duration = Duration::from_mins(5); -/// What to write under a key. -pub enum Put<'a> { - /// These bytes as the key's value. - Set(&'a [u8]), -} - /// Why a write did not land. pub enum Failure { /// The payload can never fit; retrying cannot help. @@ -34,19 +28,18 @@ pub enum Failure { Retry(String), } -/// One acked write of `put` to `subject`. +/// One acked write of `bytes` to `subject`. async fn put_once( client: &async_nats::Client, js: &async_nats::jetstream::Context, subject: &str, - put: &Put<'_>, + bytes: &[u8], ) -> 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 Put::Set(bytes) = put; let sent = js.publish(subject.to_owned(), bytes.to_vec().into()).await; let ack = sent.map_err(|e| match e.kind() { PublishErrorKind::MaxPayloadExceeded => Failure::TooLarge(e), @@ -62,11 +55,11 @@ async fn put_once( pub async fn put_retrying( client: &async_nats::Client, subject: &str, - put: Put<'_>, + bytes: &[u8], what: &str, ) -> Result<(), Failure> { let js = async_nats::jetstream::new(client.clone()); - (|| put_once(client, &js, subject, &put)) + (|| put_once(client, &js, subject, bytes)) .retry( ExponentialBuilder::default() .with_min_delay(FIRST_RETRY) From f8a03884579c82b42eaf4edd95f774402292d8ac Mon Sep 17 00:00:00 2001 From: iris Date: Mon, 16 Nov 2026 23:45:09 +0100 Subject: [PATCH 3/3] agent_icon: the subject's docs no longer mention a writer that publishes directly --- swarm-wire/src/agent_icon.rs | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/swarm-wire/src/agent_icon.rs b/swarm-wire/src/agent_icon.rs index d0230b916..a0f645ce6 100644 --- a/swarm-wire/src/agent_icon.rs +++ b/swarm-wire/src/agent_icon.rs @@ -40,8 +40,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, so a writer that -/// publishes directly has to use the same subject the bucket's `get` reads. +/// A KV put is a `JetStream` publish to this subject, and the bucket's `get` +/// reads the same one. #[must_use] pub fn subject(agent: &str) -> String { format!("$KV.{BUCKET}.{agent}") @@ -51,9 +51,8 @@ pub fn subject(agent: &str) -> String { mod tests { use super::subject; - /// 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. + /// One token after the bucket, the agent name alone: no hive in the key, so + /// a hive-scoped subject (`$KV...*`, two tokens) cannot match. #[test] fn the_published_subject_carries_the_agent_and_no_placement() { assert_eq!(subject("iris"), "$KV.agent-icons.iris");