Watch
0
0
Fork
You've already forked hyperhive
0

the harness no longer publishes the agent's icon; the controller is its only writer

This commit is contained in:
iris 2026-11-16 23:07:18 +01:00 • committed by mara
commit fe4d68c13f
9 changed files with 15 additions and 170 deletions

View file

@ -271,10 +271,9 @@ The third thing a hive's agent has is its **icon**, the same SVG its own
`<agent>`, with no hive in it, so the swarm can show the icon of an agent that's `<agent>`, 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 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 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 the key from the reply: an agent with no icon has its key deleted. The controller is the only
still publishes the same file once per start, with its own credential's grant of writer: no agent credential has a grant on the bucket, and the write needs no
`$KV.agent-icons.<agent>`; the controller's write is the one that matters, since it running agent. Swarm-side,
doesn't need the agent running. Swarm-side,
`GET /api/agents/<name>/icon` serves `GET /api/agents/<name>/icon` serves
the stored bytes, and 404 means the agent has no icon. swarm-ui's agent cards the stored bytes, and 404 means the agent has no icon. swarm-ui's agent cards
load it as an `<img>` and show the dimmed default agent icon (a robot head in a load it as an `<img>` and show the dimmed default agent icon (a robot head in a

View file

@ -36,7 +36,6 @@ mod state_entry_watch;
mod stats; mod stats;
mod subagent_role_watch; mod subagent_role_watch;
mod swarm_agent_commands; mod swarm_agent_commands;
mod swarm_agent_icon;
mod swarm_agent_state; mod swarm_agent_state;
mod swarm_agent_todos; mod swarm_agent_todos;
mod swarm_agents_md; mod swarm_agents_md;
@ -511,8 +510,6 @@ async fn serve_main<S: Surface>(socket: &Path, poll_ms: u64) -> Result<()> {
// state from this agent's first transition, not from whenever a reader // state from this agent's first transition, not from whenever a reader
// first asked. // first asked.
swarm_agent_state::spawn(&bus, login_state.clone()); 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. // The skills claude reports, published once at the first turn and whenever they change.
swarm_agent_commands::spawn(); swarm_agent_commands::spawn();
// Before the mirror and before any turn reads the file. // Before the mirror and before any turn reads the file.

View file

@ -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<u8>),
/// 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<Icon> {
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"<svg/>\n").expect("write");
assert_eq!(
read_icon(&path).expect("read"),
Icon::Set(b"<svg/>\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());
}
}

View file

@ -9,7 +9,7 @@
//! [`swarm_queue_client::agents_md::subject`] at start, whenever a re-read //! [`swarm_queue_client::agents_md::subject`] at start, whenever a re-read
//! every [`POLL`] finds a new revision, and straight after an applied edit. //! every [`POLL`] finds a new revision, and straight after an applied edit.
//! The write is a `JetStream` publish to the key's subject, as //! 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. //! failed write is retried on the next poll.
//! //!
//! **Edit.** [`handle`] answers an [`Apply`] from the control subject: it //! **Edit.** [`handle`] answers an [`Apply`] from the control subject: it

View file

@ -5,8 +5,8 @@
//! a write can arrive before it exists; that write and any other failed one are //! a write can arrive before it exists; that write and any other failed one are
//! retried with backoff until one is acked. //! retried with backoff until one is acked.
//! //!
//! Shared by the writers of an agent's own keys: [`crate::swarm_agent_icon`] //! Shared by the writers of an agent's own keys, such as
//! and [`crate::swarm_agent_commands`]. //! [`crate::swarm_agent_commands`].
use std::time::Duration; use std::time::Duration;
@ -20,17 +20,10 @@ const FIRST_RETRY: Duration = Duration::from_secs(5);
/// Longest wait between retries. /// Longest wait between retries.
const MAX_RETRY: Duration = Duration::from_mins(5); 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. /// What to write under a key.
pub enum Put<'a> { pub enum Put<'a> {
/// These bytes as the key's value. /// These bytes as the key's value.
Set(&'a [u8]), Set(&'a [u8]),
/// Delete the key.
Delete,
} }
/// Why a write did not land. /// Why a write did not land.
@ -53,15 +46,8 @@ async fn put_once(
// server has announced its own. // server has announced its own.
swarm_queue_client::ensure_connected(client) swarm_queue_client::ensure_connected(client)
.map_err(|e| Failure::Retry(swarm_queue_client::chain(&e)))?; .map_err(|e| Failure::Retry(swarm_queue_client::chain(&e)))?;
let sent = match put { let Put::Set(bytes) = put;
Put::Set(bytes) => js.publish(subject.to_owned(), bytes.to_vec().into()).await, let sent = 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() { let ack = sent.map_err(|e| match e.kind() {
PublishErrorKind::MaxPayloadExceeded => Failure::TooLarge(e), PublishErrorKind::MaxPayloadExceeded => Failure::TooLarge(e),
_ => Failure::Retry(e.to_string()), _ => Failure::Retry(e.to_string()),

View file

@ -971,13 +971,6 @@ in
# responder as the empty expansion of an unset `SWARM`. # 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.term.{agent}"}"
"--agent-token-publish-subject ${lib.escapeShellArg "\$\$SWARM.agent-state.{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.<bucket>.<key>`, 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 # Its own key in the `agents-md` KV bucket
# (`swarm_queue_client::agents_md`), on the same terms: the # (`swarm_queue_client::agents_md`), on the same terms: the
# harness mirrors its `AGENTS.md` there for the swarm to read. # harness mirrors its `AGENTS.md` there for the swarm to read.

View file

@ -541,7 +541,6 @@ let
granted == [ granted == [
"'$$SWARM.term.{agent}'" "'$$SWARM.term.{agent}'"
"'$$SWARM.agent-state.{agent}'" "'$$SWARM.agent-state.{agent}'"
"'$$KV.agent-icons.{agent}'"
"'$$KV.agents-md.{agent}'" "'$$KV.agents-md.{agent}'"
"'$$SWARM.term.{agent}.sub.>'" "'$$SWARM.term.{agent}.sub.>'"
"'$$KV.subagent-status.{agent}.*'" "'$$KV.subagent-status.{agent}.*'"

View file

@ -9,8 +9,8 @@
//! **No hive is named on this path**, because the key does not carry one — //! **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. //! 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 //! This reader is also what creates the bucket, and the controller is the only
//! granted their own key and nothing that could create a stream. //! writer: it sets the key from the builder's reply (`meta_build`).
use anyhow::{Context, Result}; use anyhow::{Context, Result};

View file

@ -14,18 +14,12 @@
//! container is stopped: the value's lifetime is the agent's, not its //! container is stopped: the value's lifetime is the agent's, not its
//! placement's. //! 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 //! 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 //! icon from the agent's config, so the write needs no running agent. An icon
//! agent's harness writes the same key, from the same config, with its own //! that is not set deletes the key. No agent credential may write here, and the
//! queue credential, which the auth callout grants `$KV.agent-icons.<agent>` and //! controller creates the bucket (`swarm_queue_client::agent_icon::open_or_create`).
//! no other key. On either side an icon that is not set deletes the key. //! [`subject`] is the subject a KV put to a key goes to.
//!
//! 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. /// The KV bucket agent icons are published into, keyed by agent name.
/// ///