| Filename | Latest commit message | Latest commit date |
|---|---|---|
d1f82e725e
Fixes #2822. `swarm.js` had two independent per-agent "is this in flight" sources: `transientsState` (operator/worker-initiated ops the backend chose to flag) and `inFlightOpsByAgent()`, a separate derivation straight from `rebuildQueueState` covering everything else. Since #3010/#3016, `running_transients()` is a status-only test — any `Running` job-queue node naming a non-empty agent lights a transient pill, not just a curated subset — so the second source's Running-state handling is now provably redundant: a Running node with an agent always already has a transient by the time `queuedOpsByAgent()` (renamed from `inFlightOpsByAgent`) would be consulted. ## What changed - `transientsState`: `Map<name, {kind, since_unix}>` (one pill per agent) -> `Map<name, Map<kind, since_unix>>` (several pills per agent). `applyTransientSet`/`applyTransientCleared` now add/remove by `(name, kind)` rather than overwrite/delete by name alone, using `TransientCleared`'s `transient_kind` field (landed in #3016) to know which pill cleared. `syncTransientsFromSnapshot` groups the now-flat `TransientView` list by name instead of assuming one row per agent. - `inFlightOpsByAgent()` -> `queuedOpsByAgent()`: trimmed to the `Pending` (queued, not yet started) case only. The `Running` branch and its "running beats queued" priority logic are gone entirely — dead weight now that transients cover every running case unconditionally. - Render loop: an agent's transients win outright whenever any exist (rendered as **one badge per pill**, not collapsed into one label — mara: "show all running nodes that name the agent"); the queued fallback only applies when a agent has zero transients. `opRunning` simplifies to "does this agent have at least one transient". - `docs/web-ui/dashboard.md`'s Container-row section rewritten to match — it described a "transient, then in-flight-queue, in priority order" model that's no longer accurate now that the second source only ever fires for the one case the first can't represent. ## Verification `npm run build` clean for both packages (dashboard + agent). Standalone re-derivation of the transient-map + queued-fallback logic (`/tmp/verify-swarm-transients.mjs`, not part of this diff) run against constructed event sequences: single-pill lifecycle, two simultaneous pills on one agent with independent clear-by-kind, clearing an unknown kind is a safe no-op, a flat snapshot with duplicate agent names groups correctly, the queued fallback only fires when no transient exists and steps aside the instant one arrives, and a Running-state rebuild-queue entry produces no queued badge (confirming the Pending-only trim is correct, not just assumed). All 17 checks passed. Verified directly against the merged backend rather than trusting summaries: `job_queue/mod.rs::running_transients()` filters `State::Running` only (not Pending — an earlier note of mine claiming otherwise was imprecise paraphrasing), and `NodeView.agent` / `running_transients()`'s agent both resolve through the same `payload.agent()`, so a Running node's presence in `rebuild_queue` and its presence as a transient are guaranteed consistent, not just usually so. #2985 (DagView/NodeView deletion) unblocks once this merges — atlas is waiting on a ping. |
||
| .. | ||
| tools | ||
| turn-loop | ||
| web-ui | ||
| agent-hierarchy.md | ||
| approvals.md | ||
| boundary.md | ||
| ci.md | ||
| conventions.md | ||
| coordinator.md | ||
| forge.md | ||
| gateway.md | ||
| github.md | ||
| gotchas.md | ||
| knowledge.md | ||
| matrix.md | ||
| network.md | ||
| observability.md | ||
| persistence.md | ||
| README.md | ||
| security.md | ||
| setup.md | ||
| snapshot-store.md | ||
| swarm.md | ||
| terminal-rendering.md | ||
| web-ui.md | ||
hyperhive docs
Depth reference for hyperhive — the substrate, not the pitch (that's the
top-level README / website).
Every page here stands alone; pick the one matching your task rather than
reading top to bottom. For the auto-generated NixOS options reference
(every services.hyperhive.* / hyperhive.* option, host and agent), see
the options site instead —
this tree is prose, that one's generated straight from the module
declarations.
Getting started
- Bringing a fresh hive online? →
setup.md(first-runhivectlbootstrap). - What does the dashboard look like, and how do I use it? →
web-ui/— the operator-facing starting point; its own sub-pages (shape,dashboard,agent,css-vars) go deeper into implementation. - What tools does an agent (or the operator) have available? →
tools/—hivectl(yours) plus every agent's MCP tool surface (bash, forge, lifecycle, matrix, scheduling).
Dashboard & agent UI internals
- How does the per-agent terminal classify + colour events? →
terminal-rendering.md.
Turn loop, config, approvals
- How does claude get its prompt, and what tools does it have? →
turn-loop/— the loop, binary shape, turn outcomes; sub-pages:claude-invocation,config,mcp. - How do config changes flow from manager to operator to container? →
approvals.md(two-step spawn, approval state machine,flake.lockvalidation). - What state survives destroy / purge / restart? →
persistence.md.
Trust boundary & security
- What's the operator/agent trust boundary? What's a capability? →
boundary.md. - Agent trust model, prompt-injection threat model, credential
isolation? →
security.md. - Who can do what to whom — agent hierarchy and privilege? →
agent-hierarchy.md.
Accounts & integrations
- How do per-agent forge accounts work? What does
forge_notifypoll, and how does it format wake messages? →forge.md(the hive's own Forgejo);tools/forge.mdfor thehive-forgeCLI verbs agents actually call. - How does the matrix-tuwunel container work? Multiple accounts per
agent? →
matrix.md(the homeserver);tools/matrix.mdfor the MCP tool surface andhyperhive.matrixAccounts. - How do I give an agent a GitHub account (
gh+git push)? How is the PAT injected? →github.md. - What does
hivectldo? Provisioning, gateway users, container shells? →tools/hivectl.md(the curated guide);tools/hivectl-cli.mdfor the exhaustive, auto-generated flag reference.
Networking & swarms
- What nginx vhosts does the gateway serve? How does matrix
discovery work? →
gateway.md. - How does DNS resolution work in agent containers? What's the
bridge network for? →
network.md. - How do I connect two hives into a swarm? →
swarm.md(peer hives, TLS trust). - Where do agent snapshots go? How does the swarm's
btrfs receiveendpoint authenticate a pushing hive? →snapshot-store.md.
Scheduler, CI, observability
- How does the rebuild queue work? What are queue kinds and
sources? →
coordinator.md. - How does the CI runner work? What's the auto-registration flow? →
ci.md. - How do I export Claude Code metrics (tokens, cost, tool calls) to
Prometheus/Grafana? →
observability.md.
Process & conventions
- Naming, commit style, wire protocol, the
data-asyncpattern? →conventions.md. - Why does the nspawn flag look like that? →
gotchas.md(bind mounts, conf flags, other NixOS/nspawn quirks). - What is
/knowledge? How does the hive-wide knowledge repo sync, and how do I contribute a document? →knowledge.md.