115 lines
4.7 KiB
Rust
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"
|
|
]
|
|
);
|
|
}
|
|
}
|