diff --git a/docs/conventions.md b/docs/conventions.md index 7d380ade..864ddf44 100644 --- a/docs/conventions.md +++ b/docs/conventions.md @@ -196,6 +196,39 @@ transitions the row to `ApprovalStatus::Cancelled` and fires `ApprovalResolved { status: "cancelled" }` so the dashboard pulls the card out of the pending pane. +### Agent metadata + +`AgentRequest::GetAgentMeta { name }` returns identity + status for +an agent. Self-introspection when `name = None` (replaces the older +`Whoami` request); target query when `name = Some`. The +manager-flavour mirror has the same shape. + +Response is `AgentMeta { name, role, running, hyperhive_rev, +status_text, status_set_at, hive_name, swarm_name }`: + +- `role`: best-effort — `"manager"` for the manager agent, + `"agent"` for everyone else. Reflects the responding daemon's + view (the host-side flavour can't always introspect the target's + config). +- `hyperhive_rev`: `None` only when the configured flake URL has + no canonical path. Otherwise carries the rev the target is + currently pinned at. +- `running`: whether the target's container is currently up. When + `false`, the host clears `status_text` / `status_set_at` — + on-disk values from before the stop are stale snapshots and + shouldn't be shown as live status. Defaults to `true` on the + wire (older harnesses never serialised it, and the host only + knew how to ask about live containers — keeps backwards-compat + with pre-running-field payloads). +- `status_text` / `status_set_at`: last value written via + `SetStatus`, plus its unix timestamp. Both `None` when the + target has never set a status, when the agent name is unknown, + or when `running = false` (see above). +- `hive_name` / `swarm_name`: display names read from + `HYPERHIVE_HIVE_NAME` / `HYPERHIVE_SWARM_NAME` env (sourced from + `services.hyperhive.hiveName` / `services.hyperhive.swarmName`). + Both `None` when the options aren't configured. + ## Async forms Dashboard + per-agent mutating forms carry `data-async`; a delegated diff --git a/hive-sh4re/src/lib.rs b/hive-sh4re/src/lib.rs index 2fd1c544..f317ea4b 100644 --- a/hive-sh4re/src/lib.rs +++ b/hive-sh4re/src/lib.rs @@ -389,15 +389,9 @@ pub enum AgentRequest { /// to `{state_dir}/hyperhive-status` so it survives harness restarts. /// Pass an empty string to clear the status. SetStatus { text: String }, - /// Fetch metadata for an agent: identity (name + role + hyperhive - /// rev) and current status. When `name` is `None` the caller's own - /// identity is returned (self-introspection — replaces the old - /// `Whoami` request). When `name` is `Some`, the target agent's - /// status fields are populated but `role`/`hyperhive_rev` reflect - /// the responding daemon's view (`role` is best-effort: `"manager"` - /// for the manager agent, `"agent"` for everyone else). - /// `status_text` / `status_set_at` are `None` when the target has - /// never set a status or the agent name is unknown. + /// Fetch identity + status for an agent. `name = None` = + /// self-introspection; `Some()` = target query. See + /// `docs/conventions.md::Agent metadata`. GetAgentMeta { #[serde(default, skip_serializing_if = "Option::is_none")] name: Option, @@ -446,18 +440,8 @@ pub enum AgentResponse { PendingRemindersCount { count: u64 }, /// `ReminderRollup` result: reminder activity stats for the agent. ReminderRollup(ReminderStats), - /// `GetAgentMeta` result: identity + status metadata for an agent. - /// `role` is `"agent"` for sub-agents and `"manager"` for the - /// manager. `hyperhive_rev` is `None` only when the configured - /// flake URL has no canonical path. `running` reflects whether the - /// target's container is currently up (#432); when it's false, - /// `status_text` / `status_set_at` are intentionally cleared by the - /// host because the on-disk values are stale snapshots from before - /// the stop. `status_text` is the last value written via - /// `SetStatus`, or `None` when none has been set or the agent name - /// is unknown. `status_set_at` is a Unix timestamp (seconds since - /// epoch) of when the status was last written; `None` when no - /// status is set. + /// `GetAgentMeta` result. Per-field semantics + serde defaults + /// live in `docs/conventions.md::Agent metadata`. AgentMeta { name: String, role: String, @@ -469,24 +453,16 @@ pub enum AgentResponse { status_text: Option, #[serde(default, skip_serializing_if = "Option::is_none")] status_set_at: Option, - /// Hive display name (#701 / #710) — e.g. `"pr1ma"`. Host - /// reads from its own `HYPERHIVE_HIVE_NAME` env (set by - /// `services.hyperhive.hiveName`); `None` when the option - /// isn't configured. #[serde(default, skip_serializing_if = "Option::is_none")] hive_name: Option, - /// Swarm display name (#701 / #710) — e.g. `"constellat1on"`. - /// Source mirrors `hive_name` (`HYPERHIVE_SWARM_NAME` env / - /// `services.hyperhive.swarmName`). #[serde(default, skip_serializing_if = "Option::is_none")] swarm_name: Option, }, } -/// Serde default for the `running` field on legacy wire payloads that -/// predate #432 — older harnesses never serialised it, and `true` -/// matches the historical assumption (the host only knew how to ask -/// about live containers). +/// Serde default for the `running` field; keeps wire backwards-compat +/// with pre-running-field payloads. See +/// `docs/conventions.md::Agent metadata`. fn default_true() -> bool { true } @@ -744,8 +720,7 @@ pub enum ManagerRequest { /// Mirror of `AgentRequest::SetStatus` on the manager surface. SetStatus { text: String }, /// Mirror of `AgentRequest::GetAgentMeta` on the manager surface. - /// `None` returns the manager's own identity (replaces the old - /// `Whoami` request). + /// See `docs/conventions.md::Agent metadata`. GetAgentMeta { #[serde(default, skip_serializing_if = "Option::is_none")] name: Option, @@ -950,11 +925,7 @@ pub enum ManagerResponse { /// `ReminderRollup` result: reminder activity stats for the manager. ReminderRollup(ReminderStats), /// Mirror of `AgentResponse::AgentMeta` on the manager surface. - /// `role` is `"manager"` for the manager and `"agent"` for any - /// sub-agent looked up by name. `running` is false when the - /// target's container is stopped (#432) — in that case - /// `status_text` / `status_set_at` are cleared by the host so - /// stale pre-stop values don't leak through. + /// See `docs/conventions.md::Agent metadata`. AgentMeta { name: String, role: String, @@ -966,13 +937,8 @@ pub enum ManagerResponse { status_text: Option, #[serde(default, skip_serializing_if = "Option::is_none")] status_set_at: Option, - /// Hive display name (#701 / #710), same source + semantics - /// as on `AgentResponse::AgentMeta`. Read from the host's - /// `HYPERHIVE_HIVE_NAME` env so manager + agent surfaces - /// return the same view. #[serde(default, skip_serializing_if = "Option::is_none")] hive_name: Option, - /// Swarm display name (#701 / #710), mirror of `hive_name`. #[serde(default, skip_serializing_if = "Option::is_none")] swarm_name: Option, },