diff --git a/docs/2-handbook/swarm/ui.md b/docs/2-handbook/swarm/ui.md index 99ada1a61..5286c2322 100644 --- a/docs/2-handbook/swarm/ui.md +++ b/docs/2-handbook/swarm/ui.md @@ -30,9 +30,11 @@ updates the agent, from the moment the update stops its container until the container is back up, so the stopped agent doesn't read as lost. Type `/` in an agent's message box and a menu lists what that agent accepts: -the swarm's own commands (`/compact`) and the skills the agent's harness -published. Arrow keys move, Tab completes, Esc closes. Skills are per agent, so -two agents can offer different lists. +the swarm's own commands (`/compact`, `/clear-todos`) and the skills the +agent's harness published. Arrow keys move, Tab completes, Esc closes. Skills +are per agent, so two agents can offer different lists. `/clear-todos` marks all +of the agent's todos done without starting a turn, and the terminal shows how +many it cleared. Each page, its controls and what they send are in [the swarm UI reference](../../4-implementation/web-ui/swarm-ui.md). diff --git a/docs/4-implementation/swarm/controller.md b/docs/4-implementation/swarm/controller.md index 199e11e5f..7f768525d 100644 --- a/docs/4-implementation/swarm/controller.md +++ b/docs/4-implementation/swarm/controller.md @@ -284,10 +284,12 @@ publishes the list that claude reports in a turn's `system`/`init` event, with e skill's `SKILL.md`. It writes when the first turn reports a list and again only when a later turn reports a different one, and retries a failed write in the background. The value is a list of `{name, description}`. `GET /api/agents//commands` answers with the swarm's own commands first (a -table in `agent_commands.rs`, today `compact`), then the agent's skills sorted by name. The skills come from the +table in `agent_commands.rs`, today `compact` and `clear-todos`), then the agent's skills sorted by name. The skills come from the agent, so the controller drops a name that isn't one plain word, a repeat, and any that takes a command's name, keeps at most 200, and cuts each description to one line of 200 characters. An agent that published nothing gets -just the swarm's commands. +just the swarm's commands. A command is plain operator input to the harness, which reads it: an input message whose +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 fourth is its **`AGENTS.md`**, which goes into the `agents-md` bucket under the key ``, writable by the agent's own credential alone diff --git a/hive-agent/src/main.rs b/hive-agent/src/main.rs index 62a5e6504..64d4f16cc 100644 --- a/hive-agent/src/main.rs +++ b/hive-agent/src/main.rs @@ -570,15 +570,10 @@ async fn serve_main(socket: &Path, poll_ms: u64) -> Result<()> { }); // Before the first turn, so claude's own auto-load finds `AGENTS.md`. agents_md_migrate::run(&paths::state_dir()); - // Harness-local reminders: a due reminder fires - // straight into an mpsc channel the serve loop races against the - // broker long-poll (unlike todos, a fire carries real per-row data, - // so a bare `Notify` doesn't fit — see `reminder_timer` docs). - // Best-effort: `reminder_timer::run` parks forever (never sends) - // instead of exiting when the store can't open, so the channel - // never observes a "closed" state. Opened before the todo socket - // below so the same `Arc` can be handed to its request dispatch - // (reminder ops share the todo socket/listener). + // Harness-local reminders fire into an mpsc channel the serve loop races + // against the broker long-poll (see `reminder_timer`). Best-effort: it + // parks forever instead of closing the channel when the store can't open. + // Opened before the todo socket, which shares the same `Arc`. // Fold the pre-consolidation per-concern db files into the single // `hyperhive-state.sqlite`, if this is the first boot since the // upgrade — see `db_migrate` module docs. Best-effort: a failure here @@ -595,16 +590,9 @@ async fn serve_main(socket: &Path, poll_ms: u64) -> Result<()> { // Messages made inside this container rather than by the broker: // reminders and the swarm UI's operator input. let (local_msg_tx, local_msg_rx) = tokio::sync::mpsc::unbounded_channel(); - swarm_input::spawn(local_msg_tx.clone(), bus.clone(), interrupted.clone()); - let reminder_store = match reminders::Reminders::open(&paths::state_db()) { - Ok(store) => Some(Arc::new(store)), - Err(e) => { - tracing::error!(error = ?e, "open reminders db failed — reminder delivery disabled"); - None - } - }; - tokio::spawn(reminder_timer::run(reminder_store.clone(), local_msg_tx)); - let (todo_wake, todos_store) = spawn_todo_socket(reminder_store.clone(), &bus); + let reminder_store = open_reminders(); + let (todo_wake, todos_store) = + start_local_inputs(reminder_store, local_msg_tx, &bus, &interrupted); // Self-announce this boot as a todo instead of relying on hive-c0re's // old `kick_agent` broker messages — see `boot_announce`'s module doc // for why this is strictly better than a host-side kick. @@ -641,6 +629,32 @@ async fn serve_main(socket: &Path, poll_ms: u64) -> Result<()> { .await } +/// Start what feeds the serve loop from inside the container: the reminder +/// timer, the todo socket and the swarm UI's input, which also needs the todo +/// store for `/clear-todos`. +fn start_local_inputs( + reminders: Option>, + tx: tokio::sync::mpsc::UnboundedSender, + bus: &Bus, + interrupted: &Arc, +) -> (Arc, Option>) { + tokio::spawn(reminder_timer::run(reminders.clone(), tx.clone())); + let (todo_wake, todos) = spawn_todo_socket(reminders, bus); + swarm_input::spawn(tx, bus.clone(), interrupted.clone(), todos.clone()); + (todo_wake, todos) +} + +/// The reminder store, or `None` (logged, reminders off) when it can't open. +fn open_reminders() -> Option> { + match reminders::Reminders::open(&paths::state_db()) { + Ok(store) => Some(Arc::new(store)), + Err(e) => { + tracing::error!(error = ?e, "open reminders db failed — reminder delivery disabled"); + None + } + } +} + /// Hand the bus the session's handles the web UI reads from outside a turn. fn share_session_handles(bus: &Bus, session: &turn::AgentSession) { if let Some(canceller) = hive_runtime::Runtime::canceller(session) { diff --git a/hive-agent/src/swarm_input.rs b/hive-agent/src/swarm_input.rs index 5f9ba9499..9bc817a97 100644 --- a/hive-agent/src/swarm_input.rs +++ b/hive-agent/src/swarm_input.rs @@ -12,14 +12,15 @@ //! publish on the subject (`swarm-nats-auth`'s reader grant), and it names //! the sender from the swarm gateway's authelia answer. //! -//! **Own credential only.** The queue grants subscribe on this subject to the -//! agent's own credential alone. +//! **Own credential only.** Subscribe on this subject is the agent's alone. //! //! **Core NATS, no reply to input.** A message sent while this task is not //! subscribed is gone; the controller sends it as a request so the operator //! gets a 503 for that instead. Input is not answered: the controller reads a //! request that times out as "a subscriber held it". //! +//! **`/clear-todos` never reaches claude:** it marks every todo done instead. +//! //! **Commands are a separate subject and are answered.** The swarm UI's //! cancel and `AGENTS.md` edits arrive on //! [`swarm_queue_client::agent_control_subject`], never on the input subject, @@ -32,20 +33,25 @@ use futures_util::{Stream, StreamExt as _}; use hive_sh4re::inbox::DeliveredMessage; use tokio::sync::mpsc::UnboundedSender; -use crate::events::Bus; +use crate::events::{Bus, LiveEvent}; +use crate::todos::Todos; + +/// The operator input that clears the agent's todos instead of reaching claude. +const CLEAR_TODOS: &str = "/clear-todos"; /// Start the subscribers, if this agent has a label to name its subjects with. pub fn spawn( tx: UnboundedSender, bus: Bus, interrupted: std::sync::Arc, + todos: Option>, ) { let agent = crate::identity::label(); if agent.is_empty() { tracing::warn!("this agent has no label; not taking input from the swarm queue"); return; } - tokio::spawn(run(tx, agent.clone())); + tokio::spawn(run(tx, agent.clone(), bus.clone(), todos)); tokio::spawn(run_control(agent, bus, interrupted)); } @@ -113,7 +119,12 @@ where Some(encoded.expect("a reply encodes")) } -async fn run(tx: UnboundedSender, agent: String) { +async fn run( + tx: UnboundedSender, + agent: String, + bus: Bus, + todos: Option>, +) { let client = crate::swarm_queue::client().await; let subject = swarm_queue_client::agent_input_subject(&agent); let subscriber = match client.subscribe(subject.clone()).await { @@ -124,19 +135,43 @@ async fn run(tx: UnboundedSender, agent: String) { } }; tracing::info!(subject, "taking operator input from the swarm queue"); - forward(subscriber.map(|msg| msg.payload), &tx).await; + forward(subscriber.map(|msg| msg.payload), &tx, |body| { + clear_todos(body, todos.as_deref(), &bus) + }) + .await; } -/// Push each decodable payload into `tx` until either end closes. +/// Run `body` if it is the `/clear-todos` command: every open todo is marked +/// done, and a note in the terminal says how many. Whether it was the command, +/// in which case no turn is started for it. +fn clear_todos(body: &str, todos: Option<&Todos>, bus: &Bus) -> bool { + if body.trim() != CLEAR_TODOS { + return false; + } + let text = match todos.map(Todos::mark_all_done) { + Some(Ok(n)) => format!("operator: /clear-todos - marked {n} todo(s) done"), + Some(Err(e)) => format!("operator: /clear-todos failed: {e}"), + None => "operator: /clear-todos failed: the todo store is not open".to_owned(), + }; + bus.emit(LiveEvent::Note { text }); + true +} + +/// Push each decodable payload into `tx` until either end closes, except one +/// whose body `command` takes (and says so with `true`). async fn forward>( payloads: impl Stream, tx: &UnboundedSender, + command: impl Fn(&str) -> bool, ) { let mut payloads = std::pin::pin!(payloads); while let Some(payload) = payloads.next().await { let Some(dm) = delivered(payload.as_ref()) else { continue; }; + if command(&dm.body) { + continue; + } if tx.send(dm).is_err() { // The serve loop is gone: the harness is shutting down. return; @@ -167,7 +202,9 @@ fn delivered(payload: &[u8]) -> Option { #[cfg(test)] mod tests { - use super::{act, forward}; + use super::{act, clear_todos, forward}; + use crate::events::{Bus, BusEvent, LiveEvent}; + use crate::todos::Todos; use swarm_queue_client::agents_md::{Apply, ApplyReply}; use swarm_queue_client::{AgentControl, AgentControlReply, AgentInput}; @@ -187,7 +224,7 @@ mod tests { b"not json".to_vec(), payload("argus", "second"), ]; - forward(futures_util::stream::iter(payloads), &tx).await; + forward(futures_util::stream::iter(payloads), &tx, |_| false).await; drop(tx); let mut got = Vec::new(); @@ -208,13 +245,74 @@ mod tests { assert!(got.iter().all(|dm| dm.id == 0 && dm.in_reply_to.is_none())); } + /// The command clears the todos, says so in the terminal and starts no + /// turn; any other body, even one that merely mentions it, goes through. + #[tokio::test] + async fn clear_todos_takes_its_message_and_marks_every_todo_done() { + let dir = tempfile::tempdir().expect("a dir"); + let todos = Todos::open(&dir.path().join("todos.sqlite")).expect("a store"); + todos.upsert("router", Some("a"), "a", None, true).unwrap(); + todos.upsert("matrix", None, "b", None, false).unwrap(); + let bus = Bus::new(); + let mut events = bus.subscribe(); + + let (tx, mut rx) = tokio::sync::mpsc::unbounded_channel(); + let payloads = vec![ + payload("mara", "/clear-todos"), + payload("mara", " /clear-todos \n"), + payload("mara", "please /clear-todos"), + ]; + forward(futures_util::stream::iter(payloads), &tx, |body| { + clear_todos(body, Some(&todos), &bus) + }) + .await; + drop(tx); + + let mut got = Vec::new(); + while let Some(dm) = rx.recv().await { + got.push(dm.body); + } + assert_eq!(got, ["please /clear-todos"]); + assert!(!todos.has_any().unwrap()); + let mut notes = Vec::new(); + while let Ok(BusEvent { + event: LiveEvent::Note { text }, + .. + }) = events.try_recv() + { + notes.push(text); + } + assert_eq!( + notes, + [ + "operator: /clear-todos - marked 2 todo(s) done", + "operator: /clear-todos - marked 0 todo(s) done" + ] + ); + } + + #[test] + fn clear_todos_without_a_store_says_so() { + let bus = Bus::new(); + let mut events = bus.subscribe(); + assert!(clear_todos("/clear-todos", None, &bus)); + let Ok(BusEvent { + event: LiveEvent::Note { text }, + .. + }) = events.try_recv() + else { + panic!("no note"); + }; + assert!(text.contains("the todo store is not open"), "{text}"); + } + #[tokio::test] async fn a_closed_serve_loop_stops_the_forwarder() { let (tx, rx) = tokio::sync::mpsc::unbounded_channel(); drop(rx); // An endless stream: returning at all proves the closed channel ended it. let payloads = futures_util::stream::repeat(payload("mara", "hi")); - forward(payloads, &tx).await; + forward(payloads, &tx, |_| false).await; } #[tokio::test] diff --git a/hive-agent/src/todos.rs b/hive-agent/src/todos.rs index 0cbd30eae..452a8c71b 100644 --- a/hive-agent/src/todos.rs +++ b/hive-agent/src/todos.rs @@ -323,6 +323,27 @@ impl Todos { Ok(total) } + /// The agent's operator dismisses every open todo at once: each is acked + /// exactly as [`Todos::mark_done`] would, so a reconciled producer's next + /// `upsert` still tells "unchanged" from "different". Returns the number + /// of rows newly acked. + /// + /// # Errors + /// + /// Propagates the sqlite update failure. + /// + /// # Panics + /// + /// Panics if the connection mutex is poisoned. + pub fn mark_all_done(&self) -> Result { + let conn = self.conn.lock().unwrap(); + let n = conn.execute( + "UPDATE todos SET acked = 1, acked_at = ?1 WHERE acked = 0", + params![Utc::now().timestamp()], + )?; + Ok(n) + } + /// List todos, newest-updated first. `subsystem = Some(..)` filters to /// one producer's set; `None` returns all. Excludes acked rows — once /// the agent has dismissed a todo it stays out of its own list, even @@ -466,6 +487,23 @@ mod tests { assert_eq!(left, ["c", "d", "e"]); } + #[test] + fn mark_all_done_acks_every_open_todo_once_and_keeps_the_rows() { + let (_dir, s) = store(); + let (done, _) = s.upsert("router", Some("a"), "a", None, true).unwrap(); + s.mark_done(done).unwrap(); + s.upsert("router", Some("b"), "b", None, true).unwrap(); + s.upsert("matrix", None, "c", None, false).unwrap(); + + // The already-acked one is not counted again. + assert_eq!(s.mark_all_done().unwrap(), 2); + assert_eq!(s.mark_all_done().unwrap(), 0); + assert!(!s.has_any().unwrap()); + // Acked, not deleted: an unchanged re-push is not new. + let (_, changed) = s.upsert("router", Some("b"), "b", None, false).unwrap(); + assert!(!changed); + } + #[test] fn keyed_upsert_dedups_and_reports_changed() { let (_dir, s) = store(); diff --git a/swarm-controller/src/agent_commands.rs b/swarm-controller/src/agent_commands.rs index 4a0329687..12c32b77f 100644 --- a/swarm-controller/src/agent_commands.rs +++ b/swarm-controller/src/agent_commands.rs @@ -18,10 +18,13 @@ use crate::routes::AppState; /// The commands the swarm UI offers every agent: the name without the slash, /// and what it does. -const COMMANDS: [(&str, &str); 1] = [( - "compact", - "Compact this agent's context after the current turn", -)]; +const COMMANDS: [(&str, &str); 2] = [ + ( + "compact", + "Compact this agent's context after the current turn", + ), + ("clear-todos", "Mark all of this agent's todos done"), +]; /// Whether an entry is one of the swarm's commands or a skill of the agent. #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, ToSchema)] @@ -161,7 +164,7 @@ mod tests { #[test] fn the_swarms_commands_come_first_and_always() { let list = build(None); - assert_eq!(names(&list), ["compact"]); + assert_eq!(names(&list), ["compact", "clear-todos"]); assert!(list.iter().all(|e| e.kind == CommandKind::Command)); } @@ -170,8 +173,8 @@ mod tests { let list = build(Some(Skills { skills: vec![skill("zeta", "z"), skill("alpha", "a")], })); - assert_eq!(names(&list), ["compact", "alpha", "zeta"]); - assert_eq!(list[1].kind, CommandKind::Skill); + assert_eq!(names(&list), ["compact", "clear-todos", "alpha", "zeta"]); + assert_eq!(list[2].kind, CommandKind::Skill); } /// What the agent publishes is untrusted: a skill cannot take a command's @@ -187,9 +190,9 @@ mod tests { skill("", "empty"), ], })); - assert_eq!(names(&list), ["compact", "good"]); + assert_eq!(names(&list), ["compact", "clear-todos", "good"]); assert_eq!(list[0].kind, CommandKind::Command); - assert_eq!(list[1].description, "one"); + assert_eq!(list[2].description, "one"); } #[test]