Watch
0
0
Fork
You've already forked hyperhive
0
hyperhive/hive-agent/src/web_ui/state.rs

538 lines
22 KiB
Rust

//! `/api/state` + `/api/dashboard-state` snapshot builders.
use axum::extract::State;
use serde::Serialize;
use swarm_queue_client::agent_inference::Source;
use crate::login::LoginState;
use crate::login_session::drop_if_finished;
use super::AppState;
pub(super) async fn api_state(State(state): State<AppState>) -> axum::Json<StateSnapshot> {
// Capture seq *before* any reads so the dedupe contract is
// "events with seq > snapshot.seq are post-snapshot, never missed."
let seq = state.bus.current_seq();
drop_if_finished(&state.session);
let login = *state.login.lock().unwrap();
let session_snapshot = state.session.lock().unwrap().clone();
let (status, session_view) = match (login, session_snapshot) {
(LoginState::Online, _) if state.bus.is_rate_limited() => ("rate_limited", None),
(LoginState::Online, _) => ("online", None),
(LoginState::NeedsLogin, None) => ("needs_login_idle", None),
(LoginState::NeedsLogin, Some(s)) => (
"needs_login_in_progress",
Some(SessionView {
url: s.url(),
output: s.output(),
finished: s.finished(),
exit_note: s.exit_note(),
}),
),
};
let dashboard_port = std::env::var("HIVE_DASHBOARD_PORT")
.ok()
.and_then(|s| s.parse::<u16>().ok())
.unwrap_or(7000);
let inbox = recent_inbox(&state.socket).await;
let (turn_state, turn_state_since) = state.bus.state_snapshot();
let model = state.bus.model();
// The alias the operator selected (e.g. "sonnet") vs. what the last
// turn actually ran on (e.g. "claude-sonnet-4-5-20260805") — mara:
// "i cannot see if sonnet became claude-sonnet-5 or something else".
// `None` until the first turn completes (no assistant event to
// resolve from yet); same source `serve_common.rs`'s turn-stats
// rollup already prefers over the requested alias.
let resolved_model = state.bus.last_resolved_model();
let context_window_tokens = state.bus.effective_context_window(&model);
let ctx_usage = state.bus.last_ctx_usage();
let cost_usage = state.bus.last_cost_usage();
let shown = shown(&state.bus);
axum::Json(StateSnapshot {
seq,
label: state.label.clone(),
qualified_label: crate::identity::qualify(&state.label),
dashboard_port,
status,
session: session_view,
inbox,
turn_state,
turn_state_since,
model: shown.model,
model_source: state.bus.model_source(),
resolved_model,
context_window_tokens,
ctx_usage,
cost_usage,
links: agent_links(&state.label, state.gui_vnc_port.is_some()),
forge_public_url: std::env::var("HIVE_FORGE_PUBLIC_URL")
.ok()
.filter(|s| !s.is_empty()),
hive_name: crate::identity::hive_name(),
swarm_name: crate::identity::swarm_name(),
effort: shown.effort,
effort_source: state.bus.effort_source(),
paused: crate::paths::paused_marker().exists(),
})
}
/// Lean snapshot of the agent-owned fields that the dashboard card
/// needs. Served at `GET /api/dashboard-state` (accessible through the
/// gateway at `/agent/<name>/api/dashboard-state`). The dashboard
/// fetches this once per running agent to get fresh, agent-authoritative
/// values instead of relying on hive-c0re's periodic file-reads.
///
/// Structural fields (running, `needs_update`, `deployed_sha`, parent, …)
/// continue to come from hive-c0re's `/api/state`; this endpoint covers
/// only the fields the agent itself is the source of truth for.
pub(super) async fn api_dashboard_state(
State(state): State<AppState>,
) -> axum::Json<DashboardState> {
let (status_text, status_set_at) = read_own_status();
let rate_limited = state.bus.is_rate_limited();
let model = state.bus.model();
let context_window_tokens = state.bus.effective_context_window(&model);
// Full context-window size = input + cache-read + cache-creation. Using
// raw `input_tokens` here reported only the *uncached* sliver, which is
// ~0 once prompt caching kicks in — so every card showed `ctx·0k`. Match
// the agent page (which ships the whole `ctx_usage` and sums it) and the
// cache-TTL logic in turn.rs, both of which use `context_tokens()`.
let ctx_tokens = state.bus.last_ctx_usage().map(|u| u.context_tokens());
axum::Json(DashboardState {
status_text,
status_set_at,
ctx_tokens,
context_window_tokens,
rate_limited,
links: agent_links(&state.label, state.gui_vnc_port.is_some()),
})
}
#[derive(Serialize)]
pub(super) struct StateSnapshot {
/// Bus seq at the moment this snapshot was assembled. Clients dedupe
/// their buffered SSE traffic against this value: events with
/// `seq <= snapshot.seq` are already reflected (or pre-date the
/// snapshot); `seq > snapshot.seq` is post-snapshot. Reset to 0 on
/// harness restart — clients treat reconnect as a fresh world.
seq: u64,
label: String,
/// Hive-qualified long name (`${label}@${hyperhive.domain}`) when
/// the host has been configured for a multi-hive swarm; falls back
/// to the short label when the hive domain env var is unset.
/// The frontend uses this for the page title / agent self-introduction;
/// when it equals `label`, the page renders the short form unchanged.
qualified_label: String,
dashboard_port: u16,
/// `"online"` | `"rate_limited"` | `"needs_login_idle"` | `"needs_login_in_progress"`.
status: &'static str,
/// Present when `status == "needs_login_in_progress"`.
session: Option<SessionView>,
/// Last N messages addressed to this agent, newest-first. Pulled
/// from the broker via the per-agent socket on each render.
/// Empty on transport failure.
inbox: Vec<hive_sh4re::inbox::InboxRow>,
/// Authoritative turn-loop state from the harness and the unix
/// timestamp the state was entered. The JS computes the age
/// client-side off this rather than tracking it from SSE events.
turn_state: crate::events::TurnState,
turn_state_since: i64,
/// Currently-active claude model name, shown on the page. The swarm
/// sets it (`crate::swarm_inference`); the page cannot.
model: String,
/// Where `model` comes from.
model_source: Source,
/// The concrete model id the most recent completed turn actually
/// ran on (e.g. `"claude-sonnet-4-5-20260805"`), resolved from that
/// turn's assistant events — `model` above is the alias the
/// operator picked, which claude itself maps to a specific dated
/// snapshot. `None` before any turn has completed.
resolved_model: Option<String>,
/// Effective context-window token budget for the current model.
/// Primary source: API-reported `modelUsage.*.contextWindow` from
/// the last result event (authoritative per-inference active window).
/// Falls back to `HIVE_CONTEXT_WINDOW_TOKENS_*` env vars, then 200 000.
/// Consumers (e.g. dashboard badge) use this to render ctx-usage %.
context_window_tokens: u64,
/// Last-inference token usage from the most recent completed
/// turn — represents the current context-window size at turn-end.
/// `null` until the first turn finishes.
ctx_usage: Option<hive_claude::TokenUsage>,
/// Cumulative token usage across the most recent turn's inferences
/// (cost signal). `null` until the first turn finishes.
cost_usage: Option<hive_claude::TokenUsage>,
/// Navigation links for this agent page. Also served via
/// `DashboardState.links` (`GET /api/dashboard-state`) for the
/// dashboard card's icon strip. Both are produced by `agent_links()`
/// — single source of truth. See [`docs/web-ui/dashboard.md::Container row`]
/// for the frontend resolver + which links appear in which conditions.
links: Vec<AgentLink>,
/// Public URL of the forge (e.g.
/// `"https://forge.pr1ma.darkest.space"`). Sourced from
/// `HIVE_FORGE_PUBLIC_URL` (set from
/// `services.hyperhive.swarm.forge.publicUrl`); `None` when unset. The frontend uses this to build
/// forge nav-strip links, and **hides** the forge link entirely
/// when absent rather than guessing `<hostname>:3000`.
forge_public_url: Option<String>,
/// Human name of this hive instance (e.g. `"pr1ma"`). Sourced
/// from `HYPERHIVE_HIVE_NAME`; `None` when unset. The frontend
/// uses this for the page `<title>` and header label so browser
/// tabs disambiguate when multiple hives are open in parallel.
hive_name: Option<String>,
/// Human name of the swarm (e.g. `"constellat1on"`). Sourced from
/// `HYPERHIVE_SWARM_NAME`; `None` when unset.
swarm_name: Option<String>,
/// Currently-active claude effort level, shown on the page; `None` per
/// [`Shown`]. The swarm sets it (`crate::swarm_inference`); the page
/// cannot.
effort: Option<String>,
/// Where `effort` comes from.
effort_source: Source,
/// Whether this agent's turn loop is currently parked (the harness
/// keeps serving this page + its MCP daemons but drives no turns).
/// Same on-disk marker hive-c0re's `Coordinator::is_paused` checks
/// (`crate::paths::paused_marker`) — read directly here rather than
/// asking hive-c0re over the socket, since the harness already has
/// the file locally. hive-c0re owns the actual pause/resume *writes*
/// (via hive-priv, this process runs unprivileged) — the per-agent
/// page's own `⋯` menu POSTs to hive-c0re's existing
/// `/api/pause/<name>` / `/api/resume/<name>` (same endpoints
/// `<hive-agent-menu>` on the dashboard already uses), this field
/// only tells the frontend which of the two to show.
paused: bool,
}
#[derive(Serialize)]
struct SessionView {
/// First `https://…` claude emitted on stdout, if any.
url: Option<String>,
/// Accumulated stdout + stderr.
output: String,
finished: bool,
exit_note: Option<String>,
}
/// One navigation link in the agent page header row. The same JSON
/// shape appears in both `StateSnapshot.links` (`GET /api/state`,
/// per-agent page) and `DashboardState.links` (`GET /api/dashboard-state`,
/// dashboard card icon strip). `agent_links()` is the single source
/// of truth for what links an agent exposes.
#[derive(Serialize)]
struct AgentLink {
/// `kind = Container | Forge` → path; `kind = External` → full URL.
/// The frontend prepends the right base before rendering.
url: String,
icon: String,
label: String,
kind: AgentLinkKind,
}
/// Resolution hint for `AgentLink.url`. The agent backend can't know
/// which hostname the browser sees (especially when the dashboard
/// proxies the call from a different origin), so it labels each link
/// and lets the frontend prepend the right base.
#[derive(Serialize, Clone, Copy)]
#[serde(rename_all = "snake_case")]
enum AgentLinkKind {
/// `url` is a path on the agent's container web UI (`/stats`,
/// `/screen`). Agent page: same-origin path. Dashboard:
/// `http://<host>:<container.port><url>`.
Container,
/// `url` is a path on the local Forgejo (`/<label>`,
/// `/agent-configs/<label>`). Both surfaces:
/// `http://<host>:3000<url>`.
Forge,
/// `url` is already a fully-qualified absolute URL — use as-is.
/// Agent-declared `services.hyperhive.agent.dashboardLinks` extras arrive here.
External,
}
#[derive(serde::Serialize)]
pub(super) struct DashboardState {
/// Free-text status set by `set_status`, read directly from the
/// `hyperhive-status` file the harness writes. `None` when unset.
#[serde(skip_serializing_if = "Option::is_none")]
status_text: Option<String>,
/// Unix timestamp (seconds) when the status file was last written.
/// `None` when no status is set.
#[serde(skip_serializing_if = "Option::is_none")]
status_set_at: Option<i64>,
/// Full context-window size from the most recent completed turn
/// (`ctx_usage.context_tokens()` = input + cache-read + cache-creation).
/// `None` until the first turn finishes. Drives the `ctx·Nk` card badge.
#[serde(skip_serializing_if = "Option::is_none")]
ctx_tokens: Option<u64>,
/// Effective context-window budget for the current model. Same
/// derivation as `StateSnapshot::context_window_tokens`.
context_window_tokens: u64,
/// True while the harness is parked after a rate-limit response.
rate_limited: bool,
/// Navigation links for the dashboard card's icon strip. This is
/// the authoritative source — includes the screen link (GUI agents)
/// which hive-c0re's disk-based fallback cannot determine.
links: Vec<AgentLink>,
}
/// Read the agent's own free-text status and the timestamp when it was
/// set, directly from the `hyperhive-status` file in the state dir.
/// Mirrors `hive_c0re::container_view::read_agent_status` but runs
/// inside the agent container using its own state dir.
fn read_own_status() -> (Option<String>, Option<i64>) {
let path = crate::paths::state_dir().join("hyperhive-status");
let meta = std::fs::metadata(&path).ok();
let text = std::fs::read_to_string(&path)
.ok()
.as_deref()
.map(str::trim)
.filter(|t| !t.is_empty())
.map(str::to_owned);
let mtime = meta.and_then(|m| {
m.modified().ok().and_then(|t| {
t.duration_since(std::time::UNIX_EPOCH)
.ok()
.and_then(|d| i64::try_from(d.as_secs()).ok())
})
});
if text.is_none() {
(None, None)
} else {
(text, mtime)
}
}
/// Build the navigation link list for the agent page header. URLs
/// are paths (relative) for `Container`/`Forge` targets and absolute
/// for `External`; the frontend resolves each against its `kind`
/// against the right base so the backend never has to guess the
/// operator's browser host. See
/// `docs/web-ui/dashboard.md::Container row` for
/// the resolver + how `deployed:<sha>` ships alongside.
///
/// Icons are real emoji, not unicode arrow/geometric glyphs — mara:
/// operator-declared `dashboardLinks` extras are already free-choice
/// emoji, so the built-ins should read as the same family rather than
/// mixing in plain text glyphs (which also don't reliably render as a
/// hexagon/arrow across fonts to begin with). `config` went through two
/// rounds on this: gear (`⚙`, with and without a variation selector)
/// still rendered broken in mara's browser either way — same
/// font-unreliable codepoint `icons.tsx` already documents avoiding.
/// Landed on the wrench (`🔧`) instead: a supplementary-plane pictograph
/// with `Emoji_Presentation=Yes`, same category as every other icon
/// here (`📊`/`🖥`/`🔨`/`🧭`), so it doesn't need a variation selector to
/// render as color emoji in the first place.
fn agent_links(label: &str, gui_enabled: bool) -> Vec<AgentLink> {
let mut links = Vec::new();
links.push(AgentLink {
url: "stats.html".to_owned(),
icon: "📊".to_owned(),
label: "stats".to_owned(),
kind: AgentLinkKind::Container,
});
if gui_enabled {
links.push(AgentLink {
url: "screen.html".to_owned(),
icon: "🖥".to_owned(),
label: "screen".to_owned(),
kind: AgentLinkKind::Container,
});
}
// Either copy of the forge token: the one fetched from the swarm secret
// store (`HIVE_FORGE_TOKEN_FILE`), or the state-dir file the hive used
// to write.
let fetched_token = std::env::var_os("HIVE_FORGE_TOKEN_FILE")
.is_some_and(|p| std::path::Path::new(&p).is_file());
if fetched_token || crate::paths::state_dir().join("forge-token").is_file() {
links.push(AgentLink {
url: format!("/{label}"),
icon: "🔨".to_owned(),
label: "forge".to_owned(),
kind: AgentLinkKind::Forge,
});
links.push(AgentLink {
url: format!("/agent-configs/{label}"),
icon: "🔧".to_owned(),
label: "config".to_owned(),
kind: AgentLinkKind::Forge,
});
}
// Agent-declared extras (`services.hyperhive.agent.dashboardLinks` → the
// `hive-dashboard-links` NixOS oneshot writes them to
// `{state_dir}/hyperhive-dashboard-links.json`). Shape on disk
// is `{label, icon, url}` with absolute URLs — those become
// `kind = External` links, passed through verbatim.
let extras_path = crate::paths::state_dir().join("hyperhive-dashboard-links.json");
if let Ok(text) = std::fs::read_to_string(&extras_path)
&& !text.trim().is_empty()
&& let Ok(extras) = serde_json::from_str::<Vec<ExtraLink>>(&text)
{
for e in extras {
links.push(AgentLink {
url: e.url,
icon: e.icon,
label: e.label,
kind: AgentLinkKind::External,
});
}
}
links
}
/// On-disk shape of `hyperhive-dashboard-links.json` (the
/// `hive-dashboard-links` NixOS oneshot's output). Mapped to
/// `AgentLink { kind: External }` inside `agent_links`.
#[derive(serde::Deserialize)]
struct ExtraLink {
label: String,
#[serde(default)]
icon: String,
url: String,
}
/// Best-effort: pull the last 30 messages addressed to us via the
/// per-agent socket. Empty list on any transport / decode
/// failure — the inbox section is decorative, not authoritative.
async fn recent_inbox(socket: &std::path::Path) -> Vec<hive_sh4re::inbox::InboxRow> {
const LIMIT: u64 = 30;
// Deadline-bounded (via `broker_request`): `/api/state` must render even
// when hive-c0re is busy — an empty inbox section beats a hung snapshot.
match super::broker_request(
socket,
&hive_core_agent_sock::Request::Recent { limit: LIMIT },
)
.await
{
Ok(hive_core_agent_sock::Response::Recent { rows }) => rows,
_ => Vec::new(),
}
}
/// The model and effort the page shows. No effort on an ACP agent whose
/// session offers no effort level now.
#[derive(Debug, PartialEq, Eq)]
pub(super) struct Shown {
pub(super) model: String,
pub(super) effort: Option<String>,
}
/// On claude, the requested model and effort. On ACP, see [`offered_shown`].
pub(super) fn shown(bus: &crate::events::Bus) -> Shown {
let (model, effort) = (bus.model(), bus.effort());
match bus.session_choices() {
Some(choices) => offered_shown(model, effort, choices.get()),
None => Shown {
model,
effort: Some(effort),
},
}
}
/// What an ACP agent shows. The runtime sets a requested value on the next
/// turn, and only if the session offers it, so the model and the effort each
/// show the requested value when offered and not refused by the agent, and
/// the session's own otherwise. The effort levels on offer come with the
/// model, so while a new model waits for the next turn no effort shows.
fn offered_shown(model: String, effort: String, offered: hive_runtime::SessionChoices) -> Shown {
let settable = |wanted: &String, c: &hive_runtime::Choice| {
c.values.contains(wanted) && c.refused.as_ref() != Some(wanted)
};
let pick = |wanted: String, choice: Option<&hive_runtime::Choice>| match choice {
Some(c) if !settable(&wanted, c) => c.current.clone(),
_ => wanted,
};
let model_pending = offered
.model
.as_ref()
.is_some_and(|c| c.current != model && settable(&model, c));
let effort_choice = offered.effort.filter(|_| !model_pending);
Shown {
model: pick(model, offered.model.as_ref()),
effort: effort_choice.map(|c| pick(effort, Some(&c))),
}
}
#[cfg(test)]
mod tests {
use hive_runtime::{Choice, SessionChoices};
use super::{Shown, offered_shown};
fn choice(current: &str, values: &[&str]) -> Choice {
Choice {
current: current.to_owned(),
values: values.iter().map(|v| (*v).to_owned()).collect(),
refused: None,
}
}
fn shown(model: &str, effort: Option<&str>) -> Shown {
Shown {
model: model.to_owned(),
effort: effort.map(str::to_owned),
}
}
#[test]
fn acp_shows_the_requested_values_the_session_offers() {
let offered = SessionChoices {
model: Some(choice("m/think", &["m/think", "m/plain"])),
effort: Some(choice("low", &["low", "high"])),
};
// `haiku` and `max` are not on offer: the session's own values show.
assert_eq!(
offered_shown("haiku".into(), "max".into(), offered.clone()),
shown("m/think", Some("low"))
);
assert_eq!(
offered_shown("m/think".into(), "high".into(), offered),
shown("m/think", Some("high"))
);
}
#[test]
fn acp_shows_no_effort_without_one_on_offer_or_while_a_model_is_pending() {
let think = SessionChoices {
model: Some(choice("m/think", &["m/think", "m/plain"])),
effort: Some(choice("low", &["low", "high"])),
};
assert_eq!(
offered_shown("m/plain".into(), "max".into(), think),
shown("m/plain", None)
);
let plain = SessionChoices {
model: Some(choice("m/plain", &["m/think", "m/plain"])),
effort: None,
};
assert_eq!(
offered_shown("m/plain".into(), "high".into(), plain),
shown("m/plain", None)
);
}
#[test]
fn acp_shows_the_session_s_model_once_the_agent_refuses_the_wanted_one() {
let refused = SessionChoices {
model: Some(Choice {
refused: Some("m/plain".into()),
..choice("m/think", &["m/think", "m/plain"])
}),
effort: Some(choice("low", &["low", "high"])),
};
assert_eq!(
offered_shown("m/plain".into(), "high".into(), refused),
shown("m/think", Some("high"))
);
}
#[test]
fn acp_shows_the_requested_model_and_no_effort_before_a_session_offers_anything() {
assert_eq!(
offered_shown("haiku".into(), "high".into(), SessionChoices::default()),
shown("haiku", None)
);
}
}