//! The run state of an agent's subagents: one key per subagent in the //! `subagent-status` KV bucket, holding whether it is running and since when. //! //! The terminal rows of a subagent (`crate::subagent_term`) say what it //! printed, not whether it is still going: a subagent that thinks quietly //! publishes nothing, and one that finished leaves its last row behind. The //! swarm UI used to guess from the age of the newest row. This bucket says it //! outright, and keeps it apart from the rows so listing the subagents of an //! agent reads one small value each and never touches a terminal stream. //! //! **Each agent's subagent daemon writes its own keys**, with the agent's own //! queue credential. The auth callout grants that credential //! `$KV.subagent-status..*` and nothing else of `JetStream`. The writer //! publishes to [`subject`] directly instead of opening the bucket, as the //! agent icon writer does (`crate::agent_icon`); `swarm-controller` creates the //! bucket (`swarm_queue_client::subagent_status::open_or_create`). A write that //! arrives before the bucket exists is refused with "no stream", and the //! writer tries again on its next heartbeat. //! //! **Keyed by the agent and the subagent**, `.`, so an agent //! moving between hives keeps its entries, for the reason //! `crate::agent_icon` gives. A subagent name is a single subject token, the //! same rule `crate::subagent_term::subagent_from_subject` applies to the //! terminal subjects. use serde::{Deserialize, Serialize}; /// The KV bucket the statuses are published into. /// /// A constant and not an option, for the reason `crate::agent_status::BUCKET` /// gives: writer and reader must name the same bucket. pub const BUCKET: &str = "subagent-status"; /// How often the writer republishes a `running` status while the subagent's /// process lives, so a writer that died shows up as stale instead of running /// forever. pub const HEARTBEAT_S: i64 = 60; /// A `running` status whose [`Status::ts`] is older than this is stale: the /// writer missed three heartbeats in a row. Readers show it as not running. pub const STALE_AFTER_S: i64 = 3 * HEARTBEAT_S; /// Whether a subagent's process is alive. #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] #[serde(rename_all = "snake_case")] pub enum State { /// A run is in progress. Running, /// The last run ended; [`Status::exit`] says how. Finished, } /// The value under one subagent's key. #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] pub struct Status { /// Whether the subagent is running. pub state: State, /// Unix seconds when the subagent entered [`Self::state`]. pub since: i64, /// The process's exit status once it finished. `None` while running, and /// when the process was killed by a signal. pub exit: Option, /// The model it runs; `None` on the harness's default. pub model: Option, /// Its reasoning effort; `None` when not set. pub effort: Option, /// Unix seconds when the writer published this value. A `running` status /// refreshes it every [`HEARTBEAT_S`]. pub ts: i64, } impl Status { /// Whether a reader at `now_s` (unix seconds) should show the subagent as /// running: [`State::Running`] and refreshed within [`STALE_AFTER_S`]. #[must_use] pub fn is_running(&self, now_s: i64) -> bool { self.state == State::Running && now_s - self.ts <= STALE_AFTER_S } } /// The key of `subagent` under `agent`: `.`. #[must_use] pub fn key(agent: &str, subagent: &str) -> String { format!("{agent}.{subagent}") } /// The subject `subagent`'s status is written on: `$KV..`. /// /// 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. #[must_use] pub fn subject(agent: &str, subagent: &str) -> String { format!("$KV.{BUCKET}.{}", key(agent, subagent)) } /// The subagent a bucket key names under `agent`, or `None` for a key that is /// not exactly one subagent token below `agent`. #[must_use] pub fn subagent_from_key<'a>(agent: &str, key: &'a str) -> Option<&'a str> { let name = key.strip_prefix(agent)?.strip_prefix('.')?; (!name.is_empty() && !name.contains('.')).then_some(name) } #[cfg(test)] mod tests { use super::*; /// Two tokens after the bucket, the agent and the subagent: what the /// per-agent grant `$KV.subagent-status.{agent}.*` expands to. #[test] fn the_published_subject_carries_the_agent_and_the_subagent() { assert_eq!(subject("iris", "scout"), "$KV.subagent-status.iris.scout"); } #[test] fn a_key_names_one_subagent_of_its_agent_or_nothing() { assert_eq!(subagent_from_key("iris", "iris.scout"), Some("scout")); assert_eq!(subagent_from_key("iris", "iris.a.b"), None); assert_eq!(subagent_from_key("iris", "iris."), None); assert_eq!(subagent_from_key("iris", "irisx.scout"), None); assert_eq!(subagent_from_key("iris", "other.scout"), None); } fn status(state: State, ts: i64) -> Status { Status { state, since: 1_000, exit: None, model: None, effort: None, ts, } } #[test] fn a_running_status_goes_stale_after_three_missed_heartbeats() { let s = status(State::Running, 10_000); assert!(s.is_running(10_000)); assert!(s.is_running(10_000 + STALE_AFTER_S)); assert!(!s.is_running(10_000 + STALE_AFTER_S + 1)); } #[test] fn a_finished_status_is_never_running() { assert!(!status(State::Finished, 10_000).is_running(10_000)); } #[test] fn the_wire_form_is_snake_case_json() { let wire = serde_json::to_string(&Status { state: State::Finished, since: 5, exit: Some(0), model: Some("opus".to_owned()), effort: None, ts: 6, }) .expect("encodes"); assert_eq!( wire, r#"{"state":"finished","since":5,"exit":0,"model":"opus","effort":null,"ts":6}"# ); } }