hyperhive/docs/conventions.md

Conventions

Code-style and process expectations across the workspace. Most of these exist because something already went wrong without them.

Naming

• Containers are length-bounded by nixos-container (≤ 11 chars).
• Sub-agents are h-<name> with <name> ≤ 9 chars.
• The manager is ruth (fixed name).
• MAX_AGENT_NAME in lifecycle.rs enforces the cap.
• Per-agent web UI port = WEB_PORT_BASE + FNV1a(name) % WEB_PORT_RANGE (8100..8999) for every agent including the manager; dashboard cfg.dashboardPort (default 7000).

Hive identity (label + domain + display names)

Four env vars cover the identity surface, read by hive_ag3nt::identity:

• HIVE_LABEL — short, hive-local agent label (iris, damocles). label() returns it; falls back to empty string if the env var is missing so downstream callers can decide how to surface "unknown agent" rather than getting a panic from this module.
• HYPERHIVE_HIVE_DOMAIN — the hive's canonical DNS domain (e.g. darkest.space), set by hive-c0re.nix from services.hyperhive.domain. When configured, qualified_label() returns ${label}@${domain} (e.g. iris@darkest.space); when unset (single-hive deployments, dev/test) it degrades to just the short label so existing callers see no change. The qualified form surfaces in the per-agent web UI title, the system-prompt template, and /api/state.qualified_label.
• HYPERHIVE_HIVE_NAME — human display name of this hive (pr1ma). Read by hive_name(); None when unset.
• HYPERHIVE_SWARM_NAME — human display name of the wider swarm this hive belongs to (constellat1on). Read by swarm_name(); federated hives at different DNS domains can share a swarm name.

hive_name + swarm_name are distinct from HYPERHIVE_HIVE_DOMAIN: the domain may carry the hive name as its leftmost label by convention, but the convention isn't machine-readable, and federated hives at different DNS domains can share a swarm name. Humans want both: the address (@darkest.space) AND the prose name (pr1ma). Matrix MXIDs still use the domain-based convention untouched.

qualify(label) is the same shape as qualified_label() but applies to an arbitrary label the caller already has (e.g. a peer name from the broker); it's the right surface when rendering a peer's name when the caller knows it's hive-local.

Identity = socket

There are no auth tokens on the per-agent unix sockets. The socket path identifies the principal; perms come from "who has the bind-mount." A sub-agent only sees its own /run/hive/mcp.sock; the manager has access to its privileged socket; hive-c0re owns the host admin socket.

Wake injection

AgentRequest::Wake { from, body } (and the manager-flavour mirror) is the wake-event-injection surface. Recipient is implicit — the agent the socket belongs to — and from is caller-chosen so the wake prompt can label the source verbatim ("matrix: new message in #general", "forge: PR #42 opened", etc.). Typical caller: an in-container background task (the matrix daemon, a scraper, the forge-notify webhook subscriber) that needs to signal "external work has arrived" without going through the broker as a peer agent.

Identity = socket means anything that can connect to /run/hive/mcp.sock is implicitly trusted to inject wakes. That's fine: the bind-mount only exposes the socket inside the agent's own container, so the trust boundary is the container's process namespace, not the wire surface.

Recipient sentinels

A few recipient names are reserved by the broker and have special meaning that ordinary agent labels can never collide with — agent name validation rejects any character outside [a-z0-9_-], so the angle-bracket and asterisk shapes below are structurally safe.

• * — broadcast: deliver to every running agent except the sender (agent_server::handle_send fans out via Coordinator::broadcast_send).
• operator — the human at the dashboard. Messages accumulate in the inbox view; no agent ever recv's them.
• <parent> — the sender's parent per topology.json. Rewritten at send time by topology::resolve_recipient: looks up parent_of(sender) and falls back to operator when the sender is a root agent (or absent from topology entirely). Lets agents address their parent without learning the label, so runtime reparenting propagates with zero agent-side restart.
• <children> — fan-out to every direct descendant of the sender per topology.json. Resolved in agent_server::handle_send via topology::children_of(sender): one message is delivered to each child, bypassing the allow-list check (structural fan-out targets are never user-listed peers). No-op for leaf agents (returns Ok when the child set is empty). Lets a sub-manager nudge its subtree without enumerating labels.

When a <children> or <parent> send resolves to real recipients, the broker stores the resolved label(s) as the message recipient(s) — the dashboard and recv side see the real routes. The sentinels are purely send-time addressing conveniences.

Wire protocol

JSON line-delimited over unix sockets in both directions (host admin / manager / agent). SSE streams (/dashboard/stream on hive-c0re, /events/stream on the per-agent web UIs) are text/event-stream; each frame carries a seq field for the snapshot-dedupe dance (see docs/web-ui.md). Request/response types live in hive-sh4re — change them in one place. The dashboard event vocabulary lives in hive-c0re::dashboard_events::DashboardEvent.

Broker delivery + ack cycle

AgentRequest::Recv is the only path that delivers messages to an agent. Always returns a list (Messages { messages }) — empty when nothing's pending, single-pop when max = None (default 1, the single-message behaviour), batched up to max when caller asks for more (server-side cap is 32; values above clamp silently). wait_seconds long-polls for the first message; once one arrives — or one is already pending — the call drains up to max in total before returning, so a single Recv call coalesces a burst.

Per-row bookkeeping inside the broker:

• delivered_at = NOW set on every popped row.
• Each recipient has an in-memory unacked_ids list of every row delivered since the last AckTurn.
• redelivered = true on a row if RequeueInflight resurfaced it (the harness prepends a "may already be handled" hint when this flag is set so the per-message warning is visible).

AgentRequest::AckTurn closes out the in-memory list — the harness fires it after TurnOutcome::Ok, marking every message popped since the last ack as fully handled. Claude doesn't see this surface; it's strictly a harness↔broker pairing. On TurnOutcome::Failed the harness intentionally skips the ack so the unacked rows stay in-flight in the DB and get picked up by the next requeue sweep.

AgentRequest::RequeueInflight is the recovery pair: fired by the harness exactly once at boot, before the serve loop starts. Catches the crashed-mid-turn / OOM-killed / container-restarted cases where a previous harness session popped messages but never drove them to a clean turn-end. Resets delivered_at back to NULL on every unacked row (so the next Recv pops them again), and remembers each id in a per-recipient in-memory set so the next Recv can tag the row with redelivered: true. Idempotent + cheap when there's nothing in flight, so the at-boot fire is unconditional.

Question routing (Ask / Answer)

AgentRequest::Ask (and the manager-flavour mirror) surfaces a structured question that either lands in the operator's dashboard queue or in a peer agent's inbox. The recipient is the to field:

• to = None or to = Some("operator") — routes to the operator-question queue. The dashboard renders the question with any options as a chip strip plus a free-text fallback (Other…) so the operator is never trapped by an incomplete list. The legacy AskOperator variant collapses into this case.
• to = Some(<agent>) — peer Q&A. The target agent receives a HelperEvent::QuestionAsked { id, asker, question, options, multi } in their inbox. They reply via AgentRequest::Answer (or ManagerRequest::Answer if they're the manager); the answer threads back to the asker as a HelperEvent::QuestionAnswered event.

Shape fields are uniform across both targets:

• options is advisory — the dashboard chips are decoration over a free-text fallback; peer-agent recipients see the list in their QuestionAsked event and can return any string.
• multi = true lets the answerer pick multiple options (checkboxes in the dashboard, a hint in the peer-agent event). The answer comes back as a single string with selections joined by ", ".
• ttl_seconds auto-cancels with answer [expired] (and answerer: "ttl-watchdog") when the wait becomes moot. None = wait indefinitely or until manual cancel.

Response shape is always QuestionQueued { id } — the asker stores the id and correlates the asynchronous answer event when it lands. Authorisation on Answer: only the question's target agent (or the operator via the dashboard) is permitted to reply; an answer attempt from anyone else fails the wire-side check.

Loose-ends wire shape

LooseEnd is the per-row response shape for GetLooseEnds (both the agent-flavour and manager-flavour requests). Tagged enum so new thread kinds (forge PRs, long-running approvals from a privileged bot, etc.) can land later without breaking existing handlers. Each row carries enough context that the caller renders it directly as a bulleted list, no follow-up fetch needed.

Per-flavour scoping is uniform across the three variants:

• agent-flavour GetLooseEnds only surfaces rows the calling agent has standing in. Approval rows only appear when the calling agent is the manager (sub-agents don't submit approvals). Question rows surface where the agent is asker OR target (the routing semantics from the Ask/Answer subsection above). Reminder rows are scoped to owner == self.
• manager-flavour GetLooseEnds lists every pending row in the swarm — full audit view.

Per-variant fields:

• Approval { id, agent, commit_ref, description?, age_seconds } — agent is the affected agent (target of the spawn / config commit), not the asker. description is the manager's free-text blurb shown on the dashboard card. commit_ref is the kind-specific payload (see docs/approvals.md::Approval kinds (wire shapes)).
• Question { id, asker, target?, question, age_seconds } — target = None = operator-routed (dashboard); Some(agent) = peer-to-peer thread.
• Reminder { id, owner, message, due_at, age_seconds } — due_at is the absolute unix timestamp the scheduler is targeting; clients compute time-until-fire as due_at - now.

age_seconds saturates at zero on any clock anomaly (back-step, unsynchronised wall clock, etc.) so the bulleted list never shows nonsense ages.

CancelLooseEnd { kind, id } is the matching write surface. The kind enum (Question / Reminder / Approval) selects which underlying store the dispatcher reaches into. Question and Reminder cancel from either surface subject to ownership checks (asker for the question, scheduler for the reminder). Approval is manager-only — sub-agents don't submit approvals so they have nothing of their own to withdraw; their wire surface returns a clear error if they try. Cancelling an approval 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.

Tool groups

The MCP tool surface an agent receives is derived from a set of named ToolGroup values (hive_sh4re::ToolGroup), not from a hardcoded binary flavor.

Group	Tools
messaging	send, recv, ask, answer
meta	set_status, get_agent_meta
inbox	get_loose_ends, cancel_loose_end, remind, request_next_turn
execution	run, status (mcp__bash__run, mcp__bash__status)
lifecycle	kill, start, restart, update (privileged)
approvals	request_init_config, request_apply_commit, request_update_meta_inputs (privileged)
scheduling	request_schedule_prompt, fire_schedule_now, cancel_schedule, edit_schedule, list_schedules (privileged)
diagnostics	get_logs (privileged)

Config storage — per-agent tool groups live in /var/lib/hyperhive/meta/tool-groups.json (hive-c0re-owned, committed to the meta repo alongside topology.json). Format: { "alice": ["messaging", "meta", "inbox", "lifecycle"], "bob": ["messaging", "meta", "inbox"] }. An absent entry means "use role default". Tool permissions are intentionally NOT configurable from agent.nix — that file goes through the manager's approval flow, so letting it declare its own groups would let the manager grant itself any tool by submitting a config commit, bypassing the operator gate.

Setting groups — the operator sets groups via the dashboard or hive-c0re::tool_groups::set_groups(name, groups). After a change meta::sync_agents commits the updated file; the next agent rebuild picks up the new HIVE_TOOL_GROUPS env var. Agents with no entry get no var.

Runtime resolution — at session start the harness reads HIVE_TOOL_GROUPS (a comma-separated list of snake_case group names injected by the meta renderer from tool-groups.json). Unrecognised tokens are logged and skipped. Falls back to ToolGroup::AGENT_DEFAULT (messaging, meta, inbox, execution) when the var is absent or empty.

Updating the surface — when a new #[tool] fn is added to HiveServer in hive-ag3nt/src/mcp.rs, add its name to the matching ToolGroup::tools() slice in hive-sh4re/src/lib.rs. That's the single source of truth; allowed_mcp_tools reads it at session start.

Capabilities

Capabilities gate system-level access that goes beyond the MCP tool surface — things an agent can access, not just call. Parallel to tool groups but orthogonal: an agent can have a tool group that registers a tool AND a capability that allows the underlying resource access.

Capability	Effect
manage_root_agent	may lifecycle-manage the root/manager agent via kill/start/restart
read_host_journal	get_host_journal MCP tool is registered + GET /journal-host requests are served
query_agent_state	may call get_loose_ends / CountPendingReminders targeting non-child agents

Config storage — per-agent capabilities live in /var/lib/hyperhive/meta/capabilities.json alongside tool-groups.json. Format: { "atlas": ["read_host_journal"], "ruth": ["manage_root_agent"] }. An absent entry means "no extra capabilities". render_flake in meta.rs reads this file and injects HIVE_CAPABILITIES (comma-separated snake_case names) into each agent's systemd service env; absent entries emit no env var so agents without capabilities don't trigger a spurious rebuild.

Setting capabilities — the operator sets capabilities via the C4P4B1L1T13S section in the dashboard's P3RM1SS10NS tab. hive-c0re::capabilities::set_caps(name, caps) is the write path. After a change meta::sync_agents commits the updated file; the next agent rebuild picks up the new HIVE_CAPABILITIES env var.

Runtime resolution — at session start the harness reads HIVE_CAPABILITIES and resolves each token to a Capability variant. Unrecognised tokens are logged and skipped. An absent or empty var means no extra capabilities.

Capability NOT configurable from agent.nix — same reasoning as tool groups: an agent that could grant its own capabilities via a config commit would bypass the operator approval gate.

Adding a new capability — add a variant to Capability in hive-sh4re/src/lib.rs + an arm to as_str. Add it to Capability::ALL (the source of truth for the permissions UI columns). Implement the access check in the relevant handler (agent_server.rs, mcp.rs, or dashboard.rs).

Async forms

Dashboard + per-agent mutating forms carry data-async; a delegated submit listener in assets/tabs.js intercepts, shows a spinner, POSTs application/x-www-form-urlencoded (axum's Form extractor rejects multipart), calls refreshState() on success. New mutating forms should add data-async and optionally data-confirm (for a JS-side confirm() prompt) or data-prompt="…" (for a window.prompt() whose answer goes into a hidden input named by data-prompt-field, default note).

refreshState defers automatically when document.activeElement sits inside a managed section so the operator's typing isn't lost; collapsible <details data-restore-key=…> survive the re-render via snapshotOpenDetails / restoreOpenDetails.

rebuild is the reconcile verb

lifecycle::rebuild idempotently rewrites /etc/nixos-containers/<C>.conf (PRIVATE_NETWORK=0, clears HOST_ADDRESS / LOCAL_ADDRESS, sets EXTRA_NSPAWN_FLAGS), regenerates applied/<name>/flake.nix, writes the systemd limits drop-in, then nixos-container update + stop + start.

Anything that changes per-container state on the host should be re-applied here so a manual ↻ R3BU1LD from the dashboard is sufficient to recover.

Actions are factored

approve / deny / destroy (and the lifecycle helper) live in actions.rs / dashboard.rs. The admin socket and the dashboard POST handlers both call into them so the two surfaces never drift.

Commit messages

Short, lowercase, no Co-Authored-By trailer. Imperative mood, no period. Body explains why if non-obvious; otherwise the subject alone is fine. Wrap at ~72 cols.

Commit before test

Stage and commit when work looks ready, then run validation (cargo check, nix flake check, real deploy). Failures get a follow-up commit rather than an amend. The commit history is the work log; rewriting it loses signal.

Best-effort oneshot services

The harness ships a family of one-shot systemd services that configure agent-side surfaces from values hive-c0re writes into the state dir at provisioning time:

• tea-login — writes ~/.config/tea/config.yml from the forge-token written by hive-c0re::forge::ensure_user_for, so tea repos create / tea pulls create work without interactive prompts.
• forge-avatar-sync — uploads hyperhive.icon SVG to the agent's Forgejo profile, so the icon shows up on commits / PRs / issue comments.
• matrix-avatar-sync — same idea for matrix profile avatars (two-step media upload → set avatar_url dance — see docs/persistence.md::matrix-avatar-sync for the protocol detail).

Shape contract — every one of these:

1. Always exit 0, even on internal failure. A non-zero exit would mark the unit failed, which in turn aborts nixos-container update and blocks rebuilds. The agent's capability surface is not allowed to gate the container build.
2. No set -e in the script body. Subshell failures must not propagate. Use ... || true on every external call that can fail (forge unreachable, missing icon, parse error, etc.)
3. Skip silently when prerequisites are missing: no token file, no icon, no reachable upstream → echo a short skip line + exit 0. The next boot tries again.
4. Wired to multi-user.target so they run on every boot (lets a rotated token / new icon take effect without systemctl restart gymnastics).
5. Re-runnable: a second invocation produces the same final state (idempotent uploads, idempotent config rewrites). Used by the .path watchers that re-fire on token appearance (see docs/persistence.md::matrix-avatar-sync).

The artefact lives under the agent user's home where applicable (~/.config/tea/config.yml) and is chown'd to that user, but the service itself stays root-owned so the bootstrap ordering doesn't need a user-existence check before each fire.

This pattern keeps the rebuild path resilient: any failure inside these services degrades the corresponding surface (no tea config, no avatar) but never blocks the container from coming up. The operator notices through journalctl -u <unit> rather than a broken switch-to-configuration.