//! Container/agent-roster wire shapes: what `HostRequest::AgentStatus` //! returns, plus the per-account matrix identity shape surfaced by //! `GetAgentMeta`. use serde::{Deserialize, Serialize}; /// One row in a `HostRequest::AgentStatus` result — the operator-CLI /// projection of the dashboard's per-agent `ContainerView`. Carries the /// agent's running/health flags plus the technical state an operator /// wants in a roster overview (`hivectl list-agents`). // // Four orthogonal, independently-observed facts about one agent, each // rendered as its own column/token by `hivectl list-agents` and read // individually by `--json` consumers. Any combination is meaningful // (a stopped agent can be paused and need an update), so folding them // into a state machine or nested flag structs would only add // `serde(flatten)` indirection to preserve the same flat JSON. Same // rationale as `LifecycleScope` in hive-host-sock. #[allow( clippy::struct_excessive_bools, reason = "flat wire projection of independent per-agent flags" )] #[derive(Debug, Clone, Serialize, Deserialize)] pub struct AgentStatusRow { /// Logical agent name (no `h-` prefix). pub name: String, /// Whether the container is currently running. pub running: bool, /// The container's unit is in systemd's `failed` state — it exhausted /// its bounded restarts and gave up, as opposed to being stopped /// deliberately. Orthogonal to `running`, like every other flag here: /// a failed unit is not running, but a not-running unit is usually /// just off. #[serde(default)] pub failed: bool, /// The agent has no live claude session and is parked waiting for /// the operator's re-auth flow. pub needs_login: bool, /// Count of this agent's pending reminders. #[serde(default)] pub pending_reminders: u64, /// The agent's turn loop is parked (pause marker present in its /// harness dir): the container may well be up and serving, it just /// drives no turns. Orthogonal to `running` — an agent can be /// paused while stopped, and pause survives a restart. #[serde(default)] pub paused: bool, /// This agent's own web UI, behind the gateway /// (`https:///agent//`) — the same URL the operator /// dashboard's "open" action uses. `None` when the dashboard's domain isn't /// configured (`HYPERHIVE_DASHBOARD_DOMAIN` unset), same condition /// `HostRequest::Urls`'s `HiveUrls::home` is `None` under. Present here /// (not just derivable from `HiveUrls`) so a client never has to build /// this path itself — see `hive-c0re/container_view.rs`'s `agent_url` /// for why a client deriving it is the wrong shape to depend on. #[serde(default, skip_serializing_if = "Option::is_none")] pub url: Option, } /// One matrix identity an agent can act as, surfaced in `GetAgentMeta`'s /// `matrix_accounts`. Field names match the daemon's `matrix-accounts.json` /// snapshot (written by `hive-matrix-mcp`'s account registry) so hive-c0re /// deserializes the snapshot straight into `Vec`; the /// snapshot's `live` / `is_primary` fields are ignored here (only live /// accounts are listed). #[derive(Debug, Clone, Serialize, Deserialize)] pub struct MatrixIdentity { /// Logical account name (the `account` arg on the matrix MCP tools). pub name: String, /// Matrix user id (`@user:server`). `None` if the session restored /// without a known user id yet. #[serde(default, skip_serializing_if = "Option::is_none")] pub user_id: Option, /// Homeserver base URL this account is on. pub homeserver: String, } #[cfg(test)] mod tests { use super::AgentStatusRow; /// The roster row carries exactly these keys; a field added back needs a reader. #[test] fn the_agent_status_row_serialises_exactly_its_fields() { let row = AgentStatusRow { name: "alice".to_owned(), running: true, failed: false, needs_login: false, pending_reminders: 0, paused: false, url: Some("https://example.invalid/agent/alice/".to_owned()), }; let value = serde_json::to_value(&row).unwrap(); let mut keys: Vec<&str> = value .as_object() .unwrap() .keys() .map(String::as_str) .collect(); keys.sort_unstable(); assert_eq!( keys, [ "failed", "name", "needs_login", "paused", "pending_reminders", "running", "url" ] ); } }