diff --git a/docs/swarm/README.md b/docs/swarm/README.md index e67bd379..c09e404e 100644 --- a/docs/swarm/README.md +++ b/docs/swarm/README.md @@ -389,6 +389,20 @@ how it gets there. A hive that hasn't been given the queue's address for its agents sets none of the four and each agent logs that it has none; a half-set environment logs an error and the harness keeps serving. +What an agent does with that connection is publish its terminal. Every row its +own web UI renders also goes to `$SWARM.term..`, one subject per +agent, so a swarm-level terminal can follow one agent without subscribing to +the swarm's whole traffic. The `` is the one the agent's client id names, +which is the same string the broker builds its grant from. Publishing only: an +agent talks about itself here and reads nothing. Rows aren't retained — a +subscriber that wasn't listening missed them, the same as on the agent's own +live stream. + +A row too large for the queue's `max_payload` would be refused outright and +take the connection down with it, so the harness drops such a row's body before +sending and leaves a marker in its place; the summary, level and icon still +arrive. A row that's too large even without its body is logged and skipped. + ### Swarm-wide forge webhooks At startup the controller registers two Forgejo hooks pointing at diff --git a/hive-c0re/src/swarm_agent_status.rs b/hive-c0re/src/swarm_agent_status.rs index 2514927c..54dd1777 100644 --- a/hive-c0re/src/swarm_agent_status.rs +++ b/hive-c0re/src/swarm_agent_status.rs @@ -35,7 +35,7 @@ const FAILURES_BEFORE_BANNER: u32 = 3; /// /// Shares its connect gate with [`crate::swarm_status::spawn`] — both read /// `crate::swarm_queue::client()`, which connects once per process — so a -/// hive with no queue configured pays for this decision once, not twice. +/// hive with no queue coordinates pays for this decision once, not twice. /// /// Takes no `Coordinator` handle, unlike its sibling: this task only reads /// agent state that already exists on disk / in the container runtime diff --git a/hive-c0re/src/swarm_notices.rs b/hive-c0re/src/swarm_notices.rs index d2b9ceb4..914fcd70 100644 --- a/hive-c0re/src/swarm_notices.rs +++ b/hive-c0re/src/swarm_notices.rs @@ -13,8 +13,8 @@ //! [`swarm_queue_client::notices`] for the stream this publishes into. //! //! **Best-effort, never fatal to the caller.** A hive with no queue -//! configured is a silent no-op (the ordinary case). A hive whose queue -//! is unreachable loses the swarm's visibility of the notice, not the +//! coordinates is a silent no-op (the ordinary case). A hive that cannot +//! reach the queue loses the swarm's visibility of the notice, not the //! host's — `warn!` fires on every failed attempt regardless, and the //! dashboard banners only after [`FAILURES_BEFORE_BANNER`] consecutive //! misses, the same debounce shape [`crate::swarm_status`] uses and for diff --git a/nix/host-modules/swarm-nats.nix b/nix/host-modules/swarm-nats.nix index 134faf27..4541fef2 100644 --- a/nix/host-modules/swarm-nats.nix +++ b/nix/host-modules/swarm-nats.nix @@ -677,10 +677,10 @@ in # The most a single publish may be, in bytes, before the # server answers `-ERR 'Maximum Payload Violation'` and # closes the connection — not a truncation, a dropped row - # and a reconnect. This queue is about to carry agent - # terminal rows published whole rather than split, so - # upstream's own default is sized to lose one of those - # rather than merely shorten it. Bounded from above by + # and a reconnect. This queue carries agent terminal rows + # published whole rather than split, so upstream's own + # default is sized to lose one of those rather than merely + # shorten it. Bounded from above by # `max_pending`: nats-server refuses to start once this # exceeds it, and widening that ceiling instead costs # memory per connection, so this stays comfortably under it.