Watch
0
0
Fork
You've already forked hyperhive
0

swarm: an agent's open todos, mirrored to the queue and served by the controller

This commit is contained in:
iris 2026-11-16 00:28:54 +01:00 • committed by mara
commit b239500f88
13 changed files with 478 additions and 6 deletions

View file

@ -291,6 +291,14 @@ just the swarm's commands. A command is plain operator input to the harness, whi
body is exactly `/clear-todos` marks every open todo done (an ack, like the agent's own `mark_todos_done`) and
writes a note with the count to the terminal, and starts no turn.
The agent's open todos go to its key of the `agent-todos` bucket, for the agent card in the swarm UI. The
agent's credential may publish `$KV.agent-todos.<agent>` and nothing else of the bucket. The harness reads its
open todos every five seconds and writes the list when it differs from the one it last wrote, and once at
start, so an agent with no todos clears an older list. The value is a list of
`{id, subsystem, summary, source, updated_unix}`, a copy for display: the harness's own database stays the
source of truth. `GET /api/agents/<name>/todos` answers with the list newest first, cut to 200 todos with each
text on one short line, since it comes from the agent. An agent that published nothing has an empty list.
The fourth is its **`AGENTS.md`**, which goes into the `agents-md` bucket under
the key `<agent>`, writable by the agent's own credential alone
(`$KV.agents-md.<agent>`). The swarm reads that copy and edits the file through

View file

@ -38,6 +38,7 @@ mod subagent_role_watch;
mod swarm_agent_commands;
mod swarm_agent_icon;
mod swarm_agent_state;
mod swarm_agent_todos;
mod swarm_agents_md;
mod swarm_inference;
mod swarm_input;
@ -455,6 +456,8 @@ fn spawn_todo_socket(
// swarm keeps for this agent.
// Open-todo count for the OTEL gauge.
tokio::spawn(todos_gauge::run(store.clone()));
// The open todos, mirrored to the swarm for the swarm UI.
swarm_agent_todos::spawn(store.clone());
tokio::spawn(schedule_timer::run(store.clone(), todo_wake.clone()));
// And so do the todos the swarm notification router queues for
// this agent.

View file

@ -0,0 +1,140 @@
//! Publishing this agent's open todos into the swarm's `agent-todos` bucket,
//! which the swarm UI shows on the agent's card (`swarm_wire::agent_todos`).
//!
//! **A mirror, read on a timer.** Todos arrive from a dozen producers, some of
//! them out of process, so there is no one place to hook a change. [`run`]
//! reads the open todos every [`TICK`] and publishes the list when it differs
//! from the one last published, and once at start so an agent with no todos
//! clears whatever an earlier run left. An unchanged list costs one sqlite
//! read. Best-effort: [`crate::swarm_kv_put`] retries a failed write, and
//! nothing here ever blocks the todo store or a turn. The agent's own queue
//! credential is granted exactly this agent's key.
use std::sync::Arc;
use std::time::Duration;
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::todos::{Todo, Todos};
/// How often the open todos are read.
const TICK: Duration = Duration::from_secs(5);
/// Start the publish task, if this agent has a label.
pub fn spawn(store: Arc<Todos>) {
let agent = crate::identity::label();
if agent.is_empty() {
tracing::warn!("this agent has no label; not publishing its todos upward");
return;
}
tokio::spawn(run(agent, store));
}
/// The list as the swarm gets it: newest first as the store lists them, cut
/// to [`MAX_TODOS`], each text one line of bounded length.
fn wire_list(todos: &[Todo]) -> WireTodos {
WireTodos {
todos: todos
.iter()
.take(MAX_TODOS)
.map(|t| WireTodo {
id: t.id,
subsystem: agent_todos::clip(&t.subsystem, MAX_LABEL_CHARS),
summary: agent_todos::clip(&t.summary, MAX_SUMMARY_CHARS),
source: t
.source
.as_deref()
.map(|s| agent_todos::clip(s, MAX_LABEL_CHARS))
.filter(|s| !s.is_empty()),
updated_unix: t.updated_at.timestamp(),
})
.collect(),
}
}
async fn run(agent: String, store: Arc<Todos>) {
let client = crate::swarm_queue::client().await;
let subject = agent_todos::subject(&agent);
let mut published: Option<WireTodos> = None;
loop {
match store.list(None) {
Ok(open) => {
let list = wire_list(&open);
if published.as_ref() != Some(&list) {
publish(&client, &subject, &list).await;
// Also after a list that can never fit: the same list is
// not tried again until it changes.
published = Some(list);
}
}
Err(e) => tracing::warn!(error = %e, "reading the open todos to publish failed"),
}
tokio::time::sleep(TICK).await;
}
}
/// Write `list`; a failure is logged, not returned.
async fn publish(client: &async_nats::Client, subject: &str, list: &WireTodos) {
let payload = match serde_json::to_vec(list) {
Ok(payload) => payload,
Err(e) => {
tracing::warn!(error = %e, "serialising the agent's todos failed; not publishing");
return;
}
};
match put_retrying(client, subject, Put::Set(&payload), "the agent's todos").await {
Ok(()) => {
tracing::debug!(
subject,
count = list.todos.len(),
"published this agent's todos"
);
}
Err(Failure::TooLarge(e)) => {
tracing::warn!(error = %e, "the agent's todos are over the queue's payload limit; not publishing them");
}
// Only a `TooLarge` ends the retries.
Err(Failure::Retry(e)) => {
tracing::error!(error = e, "gave up publishing the agent's todos");
}
}
}
#[cfg(test)]
mod tests {
use super::*;
use hive_sh4re::wire_time;
fn todo(id: i64, summary: &str, source: Option<&str>) -> Todo {
Todo {
id,
subsystem: "forge".to_owned(),
subsystem_key: Some(format!("k{id}")),
summary: summary.to_owned(),
source: source.map(str::to_owned),
updated_at: wire_time::from_secs(1_000 + id),
}
}
#[test]
fn a_todo_is_published_as_one_clipped_line_without_its_dedup_key() {
let list = wire_list(&[todo(3, "two\nlines", Some(" "))]);
assert_eq!(list.todos.len(), 1);
assert_eq!(list.todos[0].summary, "two lines");
assert_eq!(list.todos[0].source, None, "a blank source is left out");
assert_eq!(list.todos[0].updated_unix, 1_003);
}
#[test]
fn the_list_is_cut_and_the_texts_are_bounded() {
let many: Vec<Todo> = (0..i64::try_from(MAX_TODOS).expect("fits") + 30)
.map(|i| todo(i, &"s ".repeat(500), None))
.collect();
let list = wire_list(&many);
assert_eq!(list.todos.len(), MAX_TODOS);
assert!(list.todos[0].summary.chars().count() <= MAX_SUMMARY_CHARS);
}
}

View file

@ -1000,6 +1000,11 @@ in
# in its message box. As for the icon, one put and no
# `$$JS.API.*` subject; swarm-controller creates the bucket.
"--agent-token-publish-subject ${lib.escapeShellArg "\$\$KV.agent-commands.{agent}"}"
# Its own key in the `agent-todos` KV bucket
# (`swarm_wire::agent_todos`): the open todos the swarm UI
# shows on its card. One put and no `$$JS.API.*` subject;
# swarm-controller creates the bucket.
"--agent-token-publish-subject ${lib.escapeShellArg "\$\$KV.agent-todos.{agent}"}"
# Its bash tasks (`swarm_wire::bash_task`): one status key per
# task in the `bash-task-status` KV bucket and the task's output
# rows. Publish only and no `$JS.API.*` subject:

View file

@ -546,6 +546,7 @@ let
"'$$SWARM.term.{agent}.sub.>'"
"'$$KV.subagent-status.{agent}.*'"
"'$$KV.agent-commands.{agent}'"
"'$$KV.agent-todos.{agent}'"
"'$$KV.bash-task-status.{agent}.*'"
"'$$SWARM.term.{agent}.bash.>'"
"'$$JS.API.DIRECT.GET.KV_agent-schedules.$$KV.agent-schedules.{agent}'"

View file

@ -0,0 +1,171 @@
//! The open todos an agent holds, for the swarm UI's agent card:
//! `GET /api/agents/{name}/todos`.
//!
//! The list is what the agent's harness last published into the `agent-todos`
//! bucket (`swarm_wire::agent_todos`); the controller only reads it. It comes
//! from the agent and is untrusted, so [`build`] cuts it down before serving
//! it. An agent that never published, or a host with no swarm queue, has no
//! todos to show: an empty list, not an error.
use axum::Json;
use axum::extract::{Path, State};
use axum::http::StatusCode;
use serde::Serialize;
use swarm_wire::agent_todos::{self, Todos};
use utoipa::ToSchema;
use crate::routes::AppState;
/// One open todo.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, ToSchema)]
pub(crate) struct TodoEntry {
/// The harness's own id for it.
pub id: i64,
/// What produced it: `matrix`, `forge`, `bash`, …
pub subsystem: String,
/// What it says, as one line.
pub summary: String,
/// Where it came from, when the producer says.
#[serde(skip_serializing_if = "Option::is_none")]
pub source: Option<String>,
/// When it was last updated, in seconds since the Unix epoch.
pub updated_unix: i64,
}
/// The list for an agent whose harness published `published` (or nothing),
/// newest first, cut to [`agent_todos::MAX_TODOS`] with each text one short
/// line.
fn build(published: Option<Todos>) -> Vec<TodoEntry> {
let mut entries: Vec<TodoEntry> = published
.unwrap_or_default()
.todos
.into_iter()
.map(|t| TodoEntry {
id: t.id,
subsystem: agent_todos::clip(&t.subsystem, agent_todos::MAX_LABEL_CHARS),
summary: agent_todos::clip(&t.summary, agent_todos::MAX_SUMMARY_CHARS),
source: t
.source
.map(|s| agent_todos::clip(&s, agent_todos::MAX_LABEL_CHARS))
.filter(|s| !s.is_empty()),
updated_unix: t.updated_unix,
})
.collect();
entries.sort_by_key(|e| std::cmp::Reverse(e.updated_unix));
entries.truncate(agent_todos::MAX_TODOS);
entries
}
#[utoipa::path(
get,
path = "/api/agents/{name}/todos",
params(("name" = String, Path, description = "agent whose open todos to list")),
responses(
(status = 200, description = "the open todos the agent's harness last published, \
newest first; empty when it has published none and on a host with no swarm queue",
body = Vec<TodoEntry>),
(status = 400, description = "the agent name is not shaped like an identifier \
(problem+json)", body = String),
(status = 503, description = "the swarm queue could not be reached \
(problem+json)", body = String),
(status = 500, description = "reading the agent's todos failed (problem+json)",
body = String),
),
tag = "agents"
)]
pub(crate) async fn list_todos(
State(state): State<AppState>,
Path(agent): Path<String>,
) -> Result<Json<Vec<TodoEntry>>, problem_details::ProblemDetails> {
let agent = hive_types::Ident::parse(&agent)
.map(hive_types::Ident::into_string)
.map_err(|reason| crate::routes::error_problem(StatusCode::BAD_REQUEST, reason))?;
let Some(status) = state.status.as_ref() else {
return Ok(Json(build(None)));
};
let client = status.queue_client();
swarm_queue_client::ensure_connected(&client).map_err(|e| {
crate::routes::error_problem(
StatusCode::SERVICE_UNAVAILABLE,
&swarm_queue_client::chain(&e),
)
})?;
let js = async_nats::jetstream::new(client);
// The controller creates the bucket on a pass of `subagent_term::spawn`;
// until then nothing has published.
let published = match js.get_key_value(agent_todos::BUCKET).await {
Ok(store) => match store.get(&agent).await {
Ok(Some(bytes)) => serde_json::from_slice::<Todos>(&bytes)
.map_err(|e| {
tracing::warn!(%agent, error = %e, "agent todos: the published list is not readable");
})
.ok(),
Ok(None) => None,
Err(e) => return Err(read_failed(&agent, &e)),
},
Err(e) => {
tracing::debug!(%agent, error = %swarm_queue_client::chain(&e), "agent todos: the bucket is not readable");
None
}
};
Ok(Json(build(published)))
}
fn read_failed(agent: &str, e: &dyn std::error::Error) -> problem_details::ProblemDetails {
let detail = swarm_queue_client::chain(e);
tracing::warn!(%agent, error = %detail, "listing todos: reading the agent's todos failed");
crate::routes::error_problem(StatusCode::INTERNAL_SERVER_ERROR, &detail)
}
#[cfg(test)]
mod tests {
use super::*;
use swarm_wire::agent_todos::Todo;
fn todo(id: i64, summary: &str, updated_unix: i64) -> Todo {
Todo {
id,
subsystem: "forge".to_owned(),
summary: summary.to_owned(),
source: None,
updated_unix,
}
}
/// An agent that published nothing has nothing to show.
#[test]
fn nothing_published_is_an_empty_list() {
assert!(build(None).is_empty());
}
#[test]
fn the_newest_todo_comes_first() {
let list = build(Some(Todos {
todos: vec![
todo(1, "old", 100),
todo(2, "new", 300),
todo(3, "mid", 200),
],
}));
let ids: Vec<i64> = list.iter().map(|e| e.id).collect();
assert_eq!(ids, [2, 3, 1]);
}
/// What the agent publishes is untrusted: the list and each text are cut.
#[test]
fn the_list_and_the_texts_are_cut() {
let many: Vec<Todo> = (0..i64::try_from(agent_todos::MAX_TODOS).expect("fits") + 20)
.map(|i| todo(i, &"w ".repeat(1000), i))
.collect();
let list = build(Some(Todos { todos: many }));
assert_eq!(list.len(), agent_todos::MAX_TODOS);
assert!(list[0].summary.chars().count() <= agent_todos::MAX_SUMMARY_CHARS);
}
#[test]
fn a_blank_source_is_left_out() {
let mut t = todo(1, "x", 1);
t.source = Some(" ".to_owned());
assert_eq!(build(Some(Todos { todos: vec![t] }))[0].source, None);
}
}

View file

@ -37,6 +37,7 @@ mod agent_renewal;
mod agent_role_ttl;
mod agent_state_stream;
mod agent_status;
mod agent_todos;
mod agents_md;
mod agents_md_initial;
mod alerts;

View file

@ -27,12 +27,12 @@ use crate::routes::hives::{HiveEntry, ServiceLink};
use crate::routes::{self, AppState, agents, config_prs, forge_admin, hives, jobq_graph};
use crate::{
agent_commands, agent_control, agent_custom, agent_icon, agent_input, agent_limits,
agent_login, agent_permissions, agent_renewal, agent_state_stream, agent_status, agents_md,
alerts, archetypes, auth, backend_env, bash_task, builder, claude_login, config_drift,
config_pr, egress_allow, egress_deny, forge, forge_account, github_account, gitlab_account,
inference, issue_report, linked_accounts, matrix_account, message_stream, notify_flows,
notify_router_api, pause_hold, pr_report, pulls, queue_identity, review_classifier, schedules,
status, subagent_term, term_stream, wanted, webhook,
agent_login, agent_permissions, agent_renewal, agent_state_stream, agent_status, agent_todos,
agents_md, alerts, archetypes, auth, backend_env, bash_task, builder, claude_login,
config_drift, config_pr, egress_allow, egress_deny, forge, forge_account, github_account,
gitlab_account, inference, issue_report, linked_accounts, matrix_account, message_stream,
notify_flows, notify_router_api, pause_hold, pr_report, pulls, queue_identity,
review_classifier, schedules, status, subagent_term, term_stream, wanted, webhook,
};
/// Where the daemon binds, overridable via `SWARM_CONTROLLER_SOCKET`.
@ -668,6 +668,7 @@ pub(crate) fn build_app(state: AppState) -> axum::Router {
.routes(routes!(subagent_term::list_subagents))
.routes(routes!(bash_task::list_bash_tasks))
.routes(routes!(agent_commands::list_commands))
.routes(routes!(agent_todos::list_todos))
.routes(routes!(subagent_term::stream_subagent_term))
.routes(routes!(agent_state_stream::stream_agent_state))
.routes(routes!(agent_input::post_agent_input))

View file

@ -91,6 +91,12 @@ pub(crate) fn spawn(client: async_nats::Client, wanted: Arc<WantedWriter>, hives
"agent commands: opening the bucket failed; next pass"
);
}
if let Err(e) = swarm_queue_client::agent_todos::open_or_create(&client).await {
tracing::warn!(
error = %swarm_queue_client::chain(&e),
"agent todos: opening the bucket failed; next pass"
);
}
for agent in live_agents(&wanted, &hives).await {
if let Err(e) = swarm_queue_client::bash_task::open_output(&client, &agent).await {
tracing::warn!(

View file

@ -0,0 +1,18 @@
//! The connection side of the agent todo list KV bucket: opening it. The
//! bucket's name, key and value are `swarm_wire::agent_todos`.
/// Open the bucket, creating it if nothing has yet. `history: 1`: the swarm
/// wants each agent's current todos, not the lists it had before.
#[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,
swarm_wire::agent_todos::BUCKET,
"agent-todos",
"The open todos each agent holds, as its harness last published them".to_owned(),
)
.await
}

View file

@ -218,6 +218,10 @@ pub mod subagent_status;
/// key and value are `swarm_wire::agent_commands`; opening the bucket needs `kv`.
pub mod agent_commands;
/// Opening the bucket each agent's harness publishes its open todos into. The name,
/// key and value are `swarm_wire::agent_todos`; opening the bucket needs `kv`.
pub mod agent_todos;
/// Opening the bucket agent icons are published into: one key per agent, with
/// no hive in it, unlike [`agent_status`]. The name, media type and subject,
/// and why the placement stays out of the key, are in `swarm_wire::agent_icon`.

View file

@ -0,0 +1,113 @@
//! The open todos an agent holds, which the swarm UI shows on the agent's
//! card.
//!
//! **One key per agent**, `<agent>`, in the [`BUCKET`] KV bucket, holding
//! [`Todos`]. The agent's harness writes its own key with the agent's own
//! queue credential, which may publish [`subject`] and nothing else of
//! `JetStream`; `swarm-controller` creates the bucket
//! (`swarm_queue_client::agent_todos::open_or_create`) and reads the key to
//! answer `GET /api/agents/{name}/todos`. The writer publishes to the subject
//! directly instead of opening the bucket, as the agent icon does
//! (`crate::agent_icon`); a write before the bucket exists is refused and
//! tried again.
//!
//! The value is a mirror for display: the harness's own database stays the
//! source of truth, and each write replaces the whole list.
//!
//! What the agent publishes is **untrusted**: the controller cuts the list to
//! [`MAX_TODOS`] and each text to its limit before it serves them.
use serde::{Deserialize, Serialize};
/// The KV bucket the todo lists are published into, keyed by agent name.
pub const BUCKET: &str = "agent-todos";
/// The most todos one list carries; the rest are dropped.
pub const MAX_TODOS: usize = 200;
/// The longest summary, in characters; a longer one is cut.
pub const MAX_SUMMARY_CHARS: usize = 400;
/// The longest subsystem or source text, in characters; a longer one is cut.
pub const MAX_LABEL_CHARS: usize = 80;
/// One open todo.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct Todo {
/// The harness's own id for it, the number `mark_todos_done` takes.
pub id: i64,
/// What produced it: `matrix`, `forge`, `bash`, `schedule`, …
pub subsystem: String,
/// What it says, as one line.
pub summary: String,
/// Where it came from, when the producer says (a room name, a task
/// label).
#[serde(default, skip_serializing_if = "Option::is_none")]
pub source: Option<String>,
/// When it was last updated, in seconds since the Unix epoch.
pub updated_unix: i64,
}
/// The value under an agent's key: its open todos, newest first.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct Todos {
pub todos: Vec<Todo>,
}
/// The subject `agent`'s list is written on: `$KV.<bucket>.<agent>`, the
/// agent name alone.
#[must_use]
pub fn subject(agent: &str) -> String {
format!("$KV.{BUCKET}.{agent}")
}
/// `text` as one line of at most `max` characters: whitespace runs become
/// single spaces, and a longer text is cut with `…`.
#[must_use]
pub fn clip(text: &str, max: usize) -> String {
let one_line = text.split_whitespace().collect::<Vec<_>>().join(" ");
if one_line.chars().count() <= max {
return one_line;
}
let mut cut: String = one_line.chars().take(max.saturating_sub(1)).collect();
cut.push('…');
cut
}
#[cfg(test)]
mod tests {
use super::*;
/// One token after the bucket, the agent name alone: what the per-agent
/// grant `$KV.agent-todos.{agent}` expands to.
#[test]
fn the_published_subject_carries_the_agent_alone() {
assert_eq!(subject("iris"), "$KV.agent-todos.iris");
}
#[test]
fn a_text_is_one_line_and_cut() {
assert_eq!(clip("a\n b\tc", 10), "a b c");
let cut = clip(&"y".repeat(50), 10);
assert_eq!(cut.chars().count(), 10);
assert!(cut.ends_with('…'));
}
#[test]
fn the_wire_form_is_plain_json_and_omits_an_absent_source() {
let wire = serde_json::to_string(&Todos {
todos: vec![Todo {
id: 7,
subsystem: "forge".to_owned(),
summary: "review".to_owned(),
source: None,
updated_unix: 100,
}],
})
.expect("encodes");
assert_eq!(
wire,
r#"{"todos":[{"id":7,"subsystem":"forge","summary":"review","updated_unix":100}]}"#
);
}
}

View file

@ -17,6 +17,7 @@ pub mod agent_permissions;
pub mod agent_schedules;
pub mod agent_status;
pub mod agent_term;
pub mod agent_todos;
pub mod bash_task;
pub mod builder;
pub mod claude_login;