Watch
0
0
Fork
You've already forked hyperhive
0
hyperhive/hive-sh4re/src/container.rs

115 lines
4.7 KiB
Rust

//! 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://<dashboard-domain>/agent/<name>/`) — 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<String>,
}
/// 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<MatrixIdentity>`; 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<String>,
/// 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"
]
);
}
}