Watch
0
0
Fork
You've already forked hyperhive
0

Compare commits

...
Author SHA1 Message Date
atlas
6dd9d0086e refuse an agentNatsUrl that hive-priv would reject at container start
on deploy, deploy.hive-controller.queue.agentNatsUrl must be one
scheme://host:port; an IPv6 literal or a comma list now fails at evaluation
instead of failing every container start.
2026-10-24 21:13:25 +02:00
atlas
bbc6174361 leave an agent with no config commit out of internal/meta; read config heads from main
on deploy, one agent whose agent-configs repo has no commit on main is
skipped and logged instead of failing the whole internal/meta render, so the
other agents' pin moves go through. the controller reads each config head
from main, the branch hive-c0re compares against, not the repo's default
branch.
2026-10-24 21:13:25 +02:00
atlas
4697740a7e build an archetype agent from internal/meta only at the archetype it has now
on deploy, hive-c0re takes the internal/meta head for an archetype agent only
when the head lists that same archetype, and for a custom agent only when the
head lists it as custom, so a switch between the two, or to another archetype,
builds from the hive's own flake until the swarm commits the new flake.
the record location is described in the same docs paragraph.
2026-10-24 21:13:25 +02:00
atlas
4323097964 keep the meta-rev record in hive-c0re's state, written by rename
on deploy, the commit a rebuild builds an agent from is recorded under
/var/lib/hyperhive/meta-rev/<agent> instead of the agent's runtime dir, which
is mounted read-write into its container. an agent can no longer pick or
redirect the record. the file is written to a temp name and renamed over.
2026-10-24 21:13:25 +02:00
atlas
51866929d5 split render_flake into per-section helpers; no runtime change
Pure refactor of hive-meta-flake: render_flake now calls one helper per section of the flake, so the too_many_lines allow is gone. The rendered text is unchanged.
2026-10-24 21:13:25 +02:00
atlas
7c0a622d41 build agents from internal/meta when it pins their config
A rebuild's MetaSync resolves the head of the swarm's internal/meta once and
records it; the prebuild and the swap build that flake instead of the hive's
own, and a first deploy does the same in Create. hive-priv takes the commit as
a validated meta_rev on UpdateContainer and CreateContainer and builds from its
own forge URL (HIVE_PRIV_FORGE_URL).

The head is used only when its flake lists the agent at the config commit the
forge's main is at; otherwise, and when the repo has no commit or this hive has
no core token file for nix's git, the hive renders locally as before.

hive-c0re's and hive-priv's gitconfig now share the forge credential helper and
rewrite the forge's https URLs to http, which hive-priv lacked.
2026-10-24 21:13:24 +02:00
atlas
22e2d30581 pin internal/meta's hyperhive on the controller's rev and rebuild agents when it moves
The swarm controller offers its own running rev (services.hyperhive.c0re.
hyperhiveRev) as the hyperhive pin of internal/meta and takes it only when
the forge compare API shows it descends from the committed pin; merges to
hyperhive main no longer move the pin, and the first commit pins main's head.
When a commit moves the pin, every placed agent gets a TriggerDeploy.

A deploy after a meta update no longer waits on it succeeding (after_any), so
a down builder does not hold back hives that render locally.
2026-10-24 21:13:24 +02:00
atlas
5950363a10 swarm-controller: render, lock and commit internal/meta
A new update_meta node renders internal/meta's flake.nix with
hive-meta-flake, the renderer hive-c0re uses: hyperhive pinned to its
forge main, each custom agent a hive places pinned to its agent-configs
main, all over https, and the swarm-wide values from
SWARM_CONTROLLER_META_FLAKE (set by swarm-controller.nix from
services.hyperhive.swarm.*). The swarm builder locks it, and the
controller commits flake.nix and flake.lock in one commit and gives
every hive's forge account read on the repo. A render equal to the
committed flake.nix sends no lock and commits nothing.

It runs at start, when hyperhive's main moves, before the deploy of a
merged config PR and before the first deploy of a new agent; those
deploys now wait for it. agent_web_port moves into hive-meta-flake so
both callers compute the same port; hive-c0re re-exports it.

On deploy: internal/meta appears on the forge and follows every merge.
No hive builds from it yet.

Refs #4857
2026-10-24 21:13:24 +02:00
atlas
f3c0a87c0f hand agents the queue address at container start
HIVE_AGENT_NATS_URL now reaches each container in its hive facts, from
the host's deploy.hive-controller.queue.agentNatsUrl, instead of being
rendered into the meta flake. The agent option
services.hyperhive.agent.queue.natsUrl is removed; the harness unit
imports the queue credential whenever the token endpoint is set.

On deploy every agent rebuilds once (the rendered flake loses the
address), and the harness reads the address from the facts file
hive-priv writes before each start.

Refs #4857
2026-10-24 21:13:24 +02:00
atlas
ba97c64dda move the meta flake render into the hive-meta-flake crate
hive-c0re's render_flake and the pieces it needs (AgentSpec, AgentPin,
pinned_git_url, the forwarded-var tables, canonical_inputs_in_lock) move
into a new crate with no IO. The forwarded values and the GitHub switch
are now arguments; hive-c0re passes what it read from its own unit env,
as before. Nothing changes on deploy: the rendered flake is byte-for-byte
the same, and hive-c0re's render tests pass unchanged.

Refs #4857
2026-10-24 21:13:24 +02:00
atlas
de323a72dd swarm-builder: lock the swarm meta flake on request
A request on $SWARM.builder.lock-meta carries a rendered flake.nix. The
builder writes it into a scratch directory, runs `nix flake lock` there
with the same forge credential helper its builds use, answers with the
flake.lock nix wrote, and removes the directory. It commits nothing; the
controller commits the lock beside the flake.

Locks are answered in their own loop, like archetype evaluations, so one
does not wait behind an hour-long build. The auth callout grants the
subject to the builder (subscribe) and the controller (publish) only.

Ported from c574a1694 onto the swarm-wire crate.

Refs #4857
2026-10-24 21:13:24 +02:00
57 changed files with 3765 additions and 578 deletions

View file

@ -94,6 +94,9 @@ Per-hive (host + in-container):
both (under a unit, stdout already is the journal). Do not grow it into a
utility crate.
- **`hive-metric/`** — one-shot CLI pushing a labeled metric over OTLP.
- **`hive-meta-flake/`** — the meta flake's `flake.nix` text, a pure
render, and the reads of its pins. hive-c0re and swarm-controller both call
it.
Wire types + socket plumbing:

12
Cargo.lock generated
View file

@ -1781,6 +1781,7 @@ dependencies = [
"hive-jobq",
"hive-jobq-wire",
"hive-log",
"hive-meta-flake",
"hive-priv-sock",
"hive-sh4re",
"hive-sock-client",
@ -1959,6 +1960,15 @@ dependencies = [
"tracing-subscriber",
]
[[package]]
name = "hive-meta-flake"
version = "0.1.0"
dependencies = [
"anyhow",
"serde_json",
"swarm-wire",
]
[[package]]
name = "hive-metric"
version = "0.1.0"
@ -1988,6 +1998,7 @@ name = "hive-priv-sock"
version = "0.1.0"
dependencies = [
"serde",
"serde_json",
]
[[package]]
@ -4880,6 +4891,7 @@ dependencies = [
"hive-jobq-metrics",
"hive-jobq-wire",
"hive-log",
"hive-meta-flake",
"hive-types",
"hmac 0.13.0",
"http",

View file

@ -15,6 +15,7 @@ members = [
"hive-jobq-metrics",
"hive-jobq-wire",
"hive-log",
"hive-meta-flake",
"hive-matrix-mcp",
"hive-metric",
"hive-priv",
@ -107,6 +108,7 @@ hive-jobq = { path = "hive-jobq" }
hive-jobq-metrics = { path = "hive-jobq-metrics" }
hive-jobq-wire = { path = "hive-jobq-wire" }
hive-log = { path = "hive-log" }
hive-meta-flake = { path = "hive-meta-flake" }
hive-core-agent-sock = { path = "hive-core-agent-sock" }
hive-claude = "0.1.4"
hive-host-sock = { path = "hive-host-sock" }

View file

@ -119,10 +119,12 @@ declares one flake input per agent (`agent-<n>.url =
`nixosConfigurations.<n>` output per agent. Each output wraps
`inputs.agent-<n>.nixosModules.default` with the identity +
`HIVE_PORT` / `HIVE_LABEL` injection module. Values that differ per host
(the dashboard port, the pinned claude-code, extra OTEL labels) aren't in it:
(the dashboard port, the pinned claude-code, extra OTEL labels, the queue
address) aren't in it:
`hive-priv` writes them to the container's `/etc/hyperhive-hive-facts` at
start (see `docs/process/conventions.md`).
Containers run against `--flake /var/lib/hyperhive/meta#<n>`.
Containers run against `--flake /var/lib/hyperhive/meta#<n>`, or against
`internal/meta` when it pins the agent ([below](#the-swarms-meta-flake)).
The declared input url is the head of `main` on the agent's forge config repo
(`agent-configs/<n>`, the one config PRs merge into), which `sync_agents`
@ -160,6 +162,46 @@ resolves which sha the flake pins each agent at right now.
Dashboard surfaces the same info as a `deployed:<sha12>` chip
per container row.
## The swarm's meta flake
swarm-controller also commits a meta flake of its own, `internal/meta`, with
the same renderer: one `flake.nix` and `flake.lock` for every agent any hive
places (the pins: [`docs/swarm/builder.md`](../swarm/builder.md#meta-flake-lock)).
A hive builds an agent from it when the repo has a commit that pins the
agent's current config, and from its own meta flake above otherwise, so a hive
older or newer than the controller keeps building.
- **Choosing the commit.** The rebuild's `MetaSync` node reads the repo's
default-branch head with the hive's read token (`forge::reader_token()`)
and takes it when its `flake.nix` builds the agent the way the agent needs now:
a custom agent from the config commit at the head of `agent-configs/<n>`
`main`, an archetype agent from the archetype it has now. An agent switched
between custom and archetype, or to another archetype, fails that test.
A hive without the `core` token file that nix's git reads, a repo with no
commit, a head that lacks the agent and a head behind the config all select
the hive's own flake. `MetaSync` records the commit in `hive-c0re`'s own state,
`/var/lib/hyperhive/meta-rev/<n>`, which the agent can't write (the container mounts its runtime
directory read-write); `Prebuild` and `Swap` read that
record, so both build one flake. A first deploy resolves the commit in its `Create`
node, since it has no `MetaSync`.
- **The build.** `hive-c0re` prebuilds
`git+<forge>/internal/meta.git?rev=<commit>#nixosConfigurations.<n>…` and
names the commit to `hive-priv` (`meta_rev` on `UpdateContainer` and
`CreateContainer`). `hive-priv` accepts only a 40-digit lowercase hex
commit and builds the flake from its own forge URL
(`HIVE_PRIV_FORGE_URL`); the URL never comes from a request. On the wire the
`hive_priv_sock::PrivRequest` variants carry an optional field:
`{"op":"update_container","name":"atlas","stream":true,"meta_rev":"<40 hex>"}`.
Without it, as from a hive-c0re that predates the field, hive-priv builds the
hive's own flake.
- **Fetching.** nix fetches the forge's inputs with `git`. Both `hive-c0re`
and `hive-priv` carry a `$HOME/.gitconfig` that answers for the forge host
through `git-credential-hive-forge` (the `core` token file) and rewrites the
forge's `https` URL, which `internal/meta`'s lock names its inputs by, to
`http`.
- **Hyperhive.** The commit pins one hyperhive rev for the swarm, so an agent
runs the hyperhive of the controller's deploy, not its hive's.
## Two repos per agent
```
@ -194,7 +236,7 @@ proposed tree. The applied repo is never bind-mounted (except
the read-only `.git` exposure described below) so a destructive
move inside the container can't reach it.
The container's `--flake` ref is `/var/lib/hyperhive/meta#<name>`
The container's `--flake` ref is `/var/lib/hyperhive/meta#<name>` (or `internal/meta`)
(see "Meta flake" above). The agent's own `applied/<n>/flake.nix`
is a fixed boilerplate that exports `nixosModules.default =
import ./agent.nix`; the meta flake imports that module and

View file

@ -80,6 +80,12 @@ forge container:
- seeding `proposed` from `agent-configs/<agent>` on first deploy
- cloning and pulling `/knowledge`
The builds themselves read as `core`. nix fetches the config inputs and
`internal/meta` with `git`, and `git` gets its credential from
`git-credential-hive-forge`, which reads the `core` token file. A hive without
that file fetches nothing private through nix, whatever its own token reads, so
it builds from its own meta flake rather than `internal/meta`.
Roll a change to any of this out store host first (its granter writes the
controller's grant on `swarm/hives/+/forge/token`), then the controller host,
then the hives. A hive that starts before its token exists reads with the

View file

@ -41,8 +41,9 @@ Four env vars cover the identity surface, read by
Inside an agent container, the hive's name and domain don't come from the
agent's build, and neither do the hive's other per-host values: the dashboard
port (`HIVE_DASHBOARD_PORT`), the pinned claude-code
(`HYPERHIVE_CLAUDE_CODE_PATH`) and extra OTEL labels
(`HYPERHIVE_OTEL_EXTRA_RESOURCE_ATTRIBUTES`). `hive-priv` writes them to
(`HYPERHIVE_CLAUDE_CODE_PATH`), extra OTEL labels
(`HYPERHIVE_OTEL_EXTRA_RESOURCE_ATTRIBUTES`) and the queue's address
(`HIVE_AGENT_NATS_URL`, from `deploy.hive-controller.queue.agentNatsUrl`). `hive-priv` writes them to
`/etc/hyperhive-hive-facts` before every container start, leaving out any the
hive doesn't set; the agent then uses its own default. The agent's environment
generator (`nix/agent-modules/hive-facts.nix`) passes them to every unit,

View file

@ -176,8 +176,12 @@ holds it in memory only. The one thing to configure is where the queue is:
| ------------------------------------------- | ------------------------------------------------------------- |
| `deploy.hive-controller.queue.agentNatsUrl` | where the queue listens, as an agent **container** reaches it |
On every hive, `agentNatsUrl` defaults to the same
`tls://<swarm.nats.domain>:<swarm.nats.port>` as the hive's own. On the queue's
It reaches each container at start, as `HIVE_AGENT_NATS_URL` in
`/etc/hyperhive-hive-facts`, so no agent build carries it. On every hive,
`agentNatsUrl` defaults to the same
`tls://<swarm.nats.domain>:<swarm.nats.port>` as the hive's own. The option takes one
`<scheme>://<host>:<port>` (a hostname or IPv4 address), not an IPv6 literal or a
list: evaluation refuses anything else. On the queue's
host the name resolves inside a container to the bridge address, where the
firewall opens the port; on any other hive it resolves through the host's DNS,
like the store's name. ⚠️ **Never a loopback address here**: an agent has its

View file

@ -115,6 +115,46 @@ forge token, and answers with the JSON. An evaluation doesn't wait for a
build in progress and has two minutes. What the controller does with the
answer: [`archetypes.md`](archetypes.md).
## Meta-flake lock
The builder also answers `$SWARM.builder.lock-meta`. The request carries a
rendered `flake.nix`. The builder writes it into a scratch directory, runs
`nix flake lock` there with the same forge credential helper its builds use,
answers with the `flake.lock` that `nix` wrote, and removes the directory. A
lock doesn't wait for a build in progress and has ten minutes. The builder
commits nothing.
swarm-controller sends the request. It renders `internal/meta`'s `flake.nix`
with the same renderer hive-c0re uses (`hive-meta-flake`), all over `https`.
Each custom agent that a hive places pins to its `agent-configs/<agent>`
`main`; the controller omits and logs one whose repo has no commit on `main`, so it
doesn't block the rest. Hyperhive pins to one rev, a ratchet on the controller's own
running rev (`services.hyperhive.c0re.hyperhiveRev`, from `self.rev`):
- the first commit pins hyperhive's forge `main`;
- later, the pin moves to the controller's rev only when the forge's compare
API shows that rev is a strict descendant of the committed pin: commits
ahead of it, and none the pin has that it lacks. The compare endpoint counts
histories with no common ancestor as zero commits ahead, so the check needs
both directions;
- an older controller, a rev on another line, a controller built from a dirty
tree or a forge that can't answer leaves the pin. A merge to hyperhive's
`main` moves nothing.
The controller commits `flake.nix` and the returned `flake.lock` to
`internal/meta` in one commit, and gives each hive's forge account read on the
repo. It re-renders when it starts, before it deploys a merged config PR, and
before the first deploy of a new agent. Those deploys run whether or not the
update succeeded: a hive that builds from `internal/meta` does so only while it
pins the agent's current config (see
[Config changes](../agent-lifecycle/config-changes.md#the-swarms-meta-flake)). A render
equal to the committed `flake.nix` sends no lock.
When a commit moves the pin from one rev to another, the controller sends a
deploy to every agent a hive places, so they rebuild on the new hyperhive. A
restart that moves nothing deploys nothing, and the first commit deploys
nothing.
## Credentials
| What | Where | Who reads it |

View file

@ -39,6 +39,7 @@ hive-host-sock.workspace = true
hive-jobq.workspace = true
hive-jobq-wire.workspace = true
hive-log.workspace = true
hive-meta-flake.workspace = true
hive-priv-sock.workspace = true
hive-sock-client.workspace = true
hive-types.workspace = true

View file

@ -367,7 +367,7 @@ fn read_active_model(name: &hive_types::Ident) -> Option<String> {
/// The agent-side
/// `hive-agent::identity::{hive_name, swarm_name}` accessors read the
/// same env vars after they're forwarded into each sub-agent's
/// harness service environment by `meta::render_flake`; surfacing
/// harness service environment by `hive_meta_flake::render_flake`; surfacing
/// them here from c0re's own env keeps the manager + agent
/// `GetAgentMeta` paths consistent without a round-trip to the
/// target container.

View file

@ -0,0 +1,108 @@
//! This hive's reads of `internal/meta` and of an agent's config head, as
//! [`crate::meta_rev::MetaSource`], under the hive's forge read token.
use forgejo_api::structs::RepoGetRawFileQuery;
use forgejo_api::{ApiErrorKind, Forgejo, ForgejoError};
use reqwest::StatusCode;
use super::reader::ReaderToken;
use super::{CONFIG_ORG, bounded};
use crate::meta_rev::MetaSource;
/// The org and repo the swarm commits its meta flake to.
const META_OWNER: &str = "internal";
const META_REPO: &str = "meta";
/// The branch an agent's config is deployed from, which `fetch_forge_main`
/// and the swarm controller's pins both read.
const CONFIG_BRANCH: &str = "main";
/// [`MetaSource`] over the forge API.
pub(crate) struct ForgeSource {
api: Forgejo,
}
/// A source reading as this hive, or `None` when it holds no forge token.
pub(crate) async fn internal_meta_source() -> Option<ForgeSource> {
let token: ReaderToken = super::reader_token().await?;
match token.api() {
Ok(api) => Some(ForgeSource { api }),
Err(e) => {
tracing::warn!(error = ?e, "internal/meta: cannot build a forge client");
None
}
}
}
fn is_not_found(e: &ForgejoError) -> bool {
match e {
ForgejoError::ApiError(api) => match api.error_kind() {
ApiErrorKind::NotFound { .. } => true,
ApiErrorKind::Other(s) => *s == StatusCode::NOT_FOUND,
_ => false,
},
ForgejoError::UnexpectedStatusCode(s) => *s == StatusCode::NOT_FOUND,
_ => false,
}
}
impl ForgeSource {
/// The head commit of `branch` in `owner/repo`; `None` when the repo or
/// the branch is not there.
async fn branch_head(
&self,
owner: &str,
repo: &str,
branch: &str,
) -> anyhow::Result<Option<String>> {
let op = format!("read branch {branch} of {owner}/{repo}");
match bounded(&op, self.api.repo_get_branch(owner, repo, branch)).await? {
Ok(branch) => Ok(branch.commit.and_then(|c| c.id)),
Err(e) if is_not_found(&e) => Ok(None),
Err(e) => Err(anyhow::Error::new(e).context(op)),
}
}
}
impl MetaSource for ForgeSource {
fn nix_can_fetch(&self) -> bool {
super::core_token().is_some()
}
async fn meta_head(&self) -> anyhow::Result<Option<String>> {
use anyhow::Context as _;
let op = format!("read repo {META_OWNER}/{META_REPO}");
let repo = match bounded(&op, self.api.repo_get(META_OWNER, META_REPO)).await? {
Ok(repo) => repo,
Err(e) if is_not_found(&e) => return Ok(None),
Err(e) => return Err(anyhow::Error::new(e).context(op)),
};
if repo.empty.unwrap_or(false) {
return Ok(None);
}
let branch = repo
.default_branch
.with_context(|| format!("{META_OWNER}/{META_REPO} names no default branch"))?;
self.branch_head(META_OWNER, META_REPO, &branch).await
}
async fn flake_at(&self, rev: &str) -> anyhow::Result<String> {
let op = format!("read flake.nix of {META_OWNER}/{META_REPO} at {rev}");
let query = RepoGetRawFileQuery {
r#ref: Some(rev.to_owned()),
};
let raw = bounded(
&op,
self.api
.repo_get_raw_file(META_OWNER, META_REPO, "flake.nix", query),
)
.await?
.map_err(|e| anyhow::Error::new(e).context(op))?;
Ok(String::from_utf8_lossy(&raw).into_owned())
}
async fn config_head(&self, agent: &str) -> anyhow::Result<Option<String>> {
self.branch_head(CONFIG_ORG, agent, CONFIG_BRANCH).await
}
}

View file

@ -5,11 +5,13 @@
//! `internal/docs`, are swarm-controller's. Full design:
//! `docs/integrations/forge.md`.
mod internal_meta;
mod reader;
mod reconcile;
mod repos;
mod users;
pub(crate) use internal_meta::internal_meta_source;
pub use reader::reader_token;
pub(crate) use reconcile::FORGE_MAIN_REF;
pub use reconcile::{fetch_forge_main, reconcile_config_apply, reconcile_config_status};

View file

@ -34,6 +34,11 @@ impl ReaderToken {
pub fn auth_header(&self) -> String {
basic_auth_header(&self.login, &self.value)
}
/// A forge API client acting as this token's account.
pub(crate) fn api(&self) -> anyhow::Result<forgejo_api::Forgejo> {
super::api(&self.value)
}
}
/// The token to read the forge with, or `None` when this hive has neither.

View file

@ -55,7 +55,7 @@ fn extract_token(output: &str) -> Option<String> {
}
/// Canonical email address for a hive agent's Forgejo account.
/// Must match the `user.email` set by `meta::render_flake` so commits
/// Must match the `user.email` set by `hive_meta_flake::render_flake` so commits
/// by the agent link back to their Forgejo profile page.
fn agent_email(name: &str) -> String {
format!("{name}@hyperhive.local")

View file

@ -412,6 +412,11 @@ async fn run_meta_sync(coord: &Arc<Coordinator>, name: &str, relock: bool) -> Re
if relock && crate::archetypes::of(name)?.is_none() {
crate::meta::lock_update_for_rebuild(name).await?;
}
// The commit of the swarm's `internal/meta` that `Prebuild` and `Swap`
// build this agent from, resolved once here so both build the same flake;
// none leaves them on the hive's own flake rendered above.
let meta_rev = crate::meta_rev::resolve(name).await;
crate::meta_rev::record(name, meta_rev.as_deref())?;
Ok(())
}
@ -428,7 +433,10 @@ async fn run_prebuild(name: &str, id: NodeId) -> Result<()> {
// stopped agent has no uptime to preserve, so skip the (expensive)
// eval and let the downstream `Swap` build inline.
if crate::lifecycle::is_running(name).await {
let flake_ref = format!("{}#{name}", crate::paths::meta_root().display());
let flake_ref = match crate::meta_rev::recorded(name) {
Some(rev) => crate::meta_rev::flake_ref(name, &rev),
None => format!("{}#{name}", crate::paths::meta_root().display()),
};
crate::lifecycle::prebuild_toplevel(name, &flake_ref, Some(id.get())).await?;
}
Ok(())
@ -445,7 +453,10 @@ async fn run_swap(coord: &Arc<Coordinator>, name: &str, id: NodeId) -> Result<()
let agent_dir = crate::paths::agent_runtime_dir(name);
let hive = coord.hive_env();
let paths = Coordinator::agent_paths(name, agent_dir)?;
let result = crate::lifecycle::swap_update(name, &hive, &paths, Some(id.get())).await;
let meta_rev = crate::meta_rev::recorded(name);
let result =
crate::lifecycle::swap_update(name, &hive, &paths, meta_rev.as_deref(), Some(id.get()))
.await;
// On success the Ok-only bookkeeping tail (rev marker, forge/matrix
// sync, kick, rescan, snapshot) runs in the sibling `RebuildBookkeeping` node,
// which deps `AfterOk(Swap)`. On failure `RebuildBookkeeping` is cancel-cascaded
@ -512,7 +523,8 @@ async fn run_provision(coord: &Arc<Coordinator>, name: &str) -> Result<()> {
/// `Reconcile` (`converge_start_preamble` + `register_agent`) so this
/// node stays purely "create", not "create + start".
async fn run_create(name: &str) -> Result<()> {
crate::lifecycle::create_only(name).await?;
let meta_rev = crate::meta_rev::resolve(name).await;
crate::lifecycle::create_only(name, meta_rev.as_deref()).await?;
Ok(())
}

View file

@ -53,34 +53,7 @@ pub fn container_claude_mount(name: &str) -> String {
/// willing to lose (other agents may delete them).
pub const CONTAINER_SHARED_MOUNT: &str = "/shared";
/// Web UI port range, shared by every agent including the manager.
/// Deterministic from the agent's name (FNV-1a hash mod range size), so the
/// dashboard can compute the same port without asking hive-c0re.
const WEB_PORT_BASE: u16 = 8100;
const WEB_PORT_RANGE: u16 = 900;
/// FNV-1a hash of a string — used by `agent_web_port`.
fn fnv1a(s: &str) -> u32 {
let mut hash: u32 = 2_166_136_261;
for b in s.bytes() {
hash ^= u32::from(b);
hash = hash.wrapping_mul(16_777_619);
}
hash
}
/// Per-agent web UI port — `WEB_PORT_BASE + FNV-1a(name) %
/// WEB_PORT_RANGE` for every agent including the manager. The port
/// allocation rule reads the same for every name; collisions are
/// possible (birthday paradox at ~30 agents) and the operator
/// resolves them by renaming an agent (different hash → different
/// port). Stable across hosts, restarts, and dashboard renders —
/// no state-file dance.
#[must_use]
pub fn agent_web_port(name: &str) -> u16 {
// Modulo of a u32 by a u16's value is guaranteed < u16::MAX, so try_from never fails.
WEB_PORT_BASE + u16::try_from(fnv1a(name) % u32::from(WEB_PORT_RANGE)).unwrap_or(0)
}
pub use hive_meta_flake::agent_web_port;
/// Extract the bridge gateway IP from `HIVE_NETWORK_SUBNET`.
///
@ -170,8 +143,8 @@ pub fn network_isolation_from_env() -> Result<hive_priv_sock::NetworkIsolation>
}
/// The hive's facts every container is handed at runtime, so that no agent
/// build carries a value that differs between hosts. The name, domain and
/// OTEL resource labels come from hive-c0re's own unit environment
/// build carries a value that differs between hosts. The name, domain, OTEL
/// resource labels and queue address come from hive-c0re's own unit environment
/// (`nix/host-modules/hive-c0re/environment.nix`), where an unset or empty
/// variable is `None`; the dashboard port and pinned claude from `hive`.
fn hive_facts(hive: &HiveEnv) -> hive_priv_sock::HiveFacts {
@ -190,6 +163,7 @@ fn hive_facts_from(
dashboard_port: Some(hive.dashboard_port),
claude_code_path: hive.claude_code_path.clone(),
otel_extra_resource_attributes: read("HYPERHIVE_OTEL_EXTRA_RESOURCE_ATTRIBUTES"),
agent_nats_url: read("HIVE_AGENT_NATS_URL"),
}
}
@ -263,8 +237,10 @@ pub async fn provision_container(name: &str, hive: &HiveEnv, paths: &AgentPaths)
/// The `nixos-container create` proper — the job queue's `Create` node.
/// Assumes `provision_container` already registered the agent in meta.
pub async fn create_only(name: &str) -> Result<()> {
priv_run("create", name).await
/// `meta_rev` is the `internal/meta` commit to build from; none builds from the
/// hive's own meta flake (`crate::meta_rev`).
pub async fn create_only(name: &str, meta_rev: Option<&str>) -> Result<()> {
priv_run_inner("create", name, meta_rev, None).await
}
/// Rebuild-path preamble, run by the job queue's `Prebuild` node: fail fast on
@ -316,15 +292,17 @@ pub async fn prepare_rebuild_dirs(name: &str, paths: &AgentPaths) -> Result<()>
/// drop-ins, then `nixos-container update`. The job queue's `Swap`
/// node. Requires the container stopped (the queue's `StopForUpdate`
/// upstream); does NOT start it — the DAG's tail `Reconcile` owns
/// bringing the agent back to its wanted power state.
/// bringing the agent back to its wanted power state. `meta_rev` is as for
/// [`create_only`].
pub async fn swap_update(
name: &str,
hive: &HiveEnv,
paths: &AgentPaths,
meta_rev: Option<&str>,
node_id: Option<u64>,
) -> Result<()> {
write_dropins(name, hive, paths).await?;
priv_run_inner("update", name, node_id).await
priv_run_inner("update", name, meta_rev, node_id).await
}
/// Build the `AgentSpec` list for the meta flake from `nixos-container
@ -998,7 +976,7 @@ fn make_log_callback(
/// is appended to the build-log row as it arrives, so the dashboard
/// shows live progress during long `nixos-container create` / `update` runs.
async fn priv_run(kind: &str, name: &str) -> Result<()> {
priv_run_inner(kind, name, None).await
priv_run_inner(kind, name, None, None).await
}
/// Like `priv_run` but stamps `node_id` onto the build-log row it opens, so
@ -1008,7 +986,12 @@ async fn priv_run(kind: &str, name: &str) -> Result<()> {
/// This used to be a `Fn(i64)` callback that handed the row id *back* to the
/// queue, which then held it in a side map. The row carries the link itself
/// now, so the id only ever travels one way.
async fn priv_run_inner(kind: &str, name: &str, node_id: Option<u64>) -> Result<()> {
async fn priv_run_inner(
kind: &str,
name: &str,
meta_rev: Option<&str>,
node_id: Option<u64>,
) -> Result<()> {
let container = container_name(name);
let cmdline = format!("nixos-container {kind} {container}");
@ -1027,6 +1010,7 @@ async fn priv_run_inner(kind: &str, name: &str, node_id: Option<u64>) -> Result<
"create" => {
crate::priv_client::create_container_streaming(
name,
meta_rev,
make_log_callback(logs.clone(), log_id, cmdline.clone()),
)
.await
@ -1034,6 +1018,7 @@ async fn priv_run_inner(kind: &str, name: &str, node_id: Option<u64>) -> Result<
"update" => {
crate::priv_client::update_container_streaming(
name,
meta_rev,
make_log_callback(logs.clone(), log_id, cmdline.clone()),
)
.await

View file

@ -528,9 +528,9 @@ async fn run_with_deadline_returns_output_of_a_fast_child() {
assert_eq!(String::from_utf8_lossy(&out.stdout).trim(), "hi");
}
/// The three per-host values reach the container as facts: the dashboard
/// port and pinned claude from the hive's config, the OTEL labels from the
/// daemon's environment.
/// The per-host values reach the container as facts: the dashboard port and
/// pinned claude from the hive's config, the OTEL labels and the queue
/// address from the daemon's environment.
#[test]
fn hive_facts_carry_the_per_host_values() {
let hive = HiveEnv {
@ -538,8 +538,10 @@ fn hive_facts_carry_the_per_host_values() {
claude_code_path: Some("/nix/store/0abc-claude-code".to_owned()),
..HiveEnv::default()
};
let facts = hive_facts_from(&hive, |name| {
(name == "HYPERHIVE_OTEL_EXTRA_RESOURCE_ATTRIBUTES").then(|| "team=a".to_owned())
let facts = hive_facts_from(&hive, |name| match name {
"HYPERHIVE_OTEL_EXTRA_RESOURCE_ATTRIBUTES" => Some("team=a".to_owned()),
"HIVE_AGENT_NATS_URL" => Some("tls://nats.t.local:4222".to_owned()),
_ => None,
});
assert_eq!(facts.dashboard_port, Some(7123));
assert_eq!(
@ -550,6 +552,10 @@ fn hive_facts_carry_the_per_host_values() {
facts.otel_extra_resource_attributes.as_deref(),
Some("team=a")
);
assert_eq!(
facts.agent_nats_url.as_deref(),
Some("tls://nats.t.local:4222")
);
}
/// Unset and empty both leave a fact out, so the agent falls back to its
@ -561,5 +567,6 @@ fn hive_facts_leave_unset_values_out() {
});
assert_eq!(facts.claude_code_path, None);
assert_eq!(facts.otel_extra_resource_attributes, None);
assert_eq!(facts.agent_nats_url, None);
assert_eq!(facts.name, None);
}

View file

@ -26,6 +26,7 @@ mod lifecycle;
mod loose_ends;
mod matrix;
mod meta;
mod meta_rev;
mod migrate;
mod paths;
mod priv_client;

View file

@ -13,6 +13,11 @@ use tokio::process::Command;
use tokio::sync::{Mutex, MutexGuard};
use tokio::time::Instant;
pub use hive_meta_flake::{AgentPin, AgentSpec};
#[cfg(test)]
use hive_meta_flake::{FORWARDED_VAR_OPTIONS, push_forwarded_var_options};
use hive_meta_flake::{FORWARDED_VARS, canonical_inputs_in_lock, pinned_git_url};
use crate::coordinator::HiveEnv;
use crate::lifecycle;
@ -112,30 +117,6 @@ async fn lock_notifying<'a>(
/// Where the manager sees this directory inside its container (RO bind).
pub const CONTAINER_MANAGER_META_MOUNT: &str = "/meta";
#[derive(Debug, Clone)]
pub struct AgentSpec {
pub name: String,
pub port: u16,
/// The archetype the agent is built from (`crate::archetypes`), `None`
/// for a custom agent built from its own config repo.
pub archetype: Option<swarm_queue_client::agent_archetype::ArchetypeRef>,
/// The pin of a custom agent's config input. `None` until [`sync_agents`]
/// resolves it; an archetype agent has no config input and keeps `None`.
pub pin: Option<AgentPin>,
}
/// What the rendered flake needs to know about one agent's config input, all
/// of it read from the agent's config repo at one commit. The rendered text
/// is a function of this and nothing on the host.
#[derive(Debug, Clone)]
pub struct AgentPin {
/// `git+<forge>/agent-configs/<n>.git?rev=<rev>`, `<rev>` being the head of
/// `main` on the forge when the flake was rendered.
pub url: String,
/// The `CANONICAL_INPUTS` the agent's `flake.lock` declares at that commit.
pub canonical_inputs: Vec<&'static str>,
}
/// Stage topology.json if it exists: it is regenerated by `reconcile`
/// whenever the agent set changed. Without staging, an
/// existing-but-untracked file shows up as untracked in the meta repo,
@ -422,15 +403,6 @@ fn hyperhive_input_url(hive: &HiveEnv) -> Result<String> {
)
}
/// The pure half of [`hyperhive_input_url`], testable without `HIVE_FORGE_URL`.
fn pinned_git_url(forge_git_url: &str, rev: Option<&str>) -> Result<String> {
let rev = rev.filter(|r| !r.is_empty()).context(
"hyperhive rev unknown: the host was built from a dirty tree \
(`self.rev` unset) and `services.hyperhive.c0re.hyperhiveRev` is not set",
)?;
Ok(format!("git+{forge_git_url}?rev={rev}"))
}
/// [`render_flake`] with the hyperhive pin taken from `hive`, as
/// [`sync_agents`] renders it. Nothing else in `hive` reaches the flake: the
/// values that differ per host go to the container at start
@ -439,113 +411,15 @@ fn render_hive_flake(hive: &HiveEnv, agents: &[AgentSpec]) -> Result<String> {
render_flake(&hyperhive_input_url(hive)?, agents)
}
/// Canonical inputs meta knows how to dedup. An agent that declares one
/// of these as a top-level input in its own `flake.nix` will get a
/// `follows = "<name>"` line emitted in meta — collapsing the
/// otherwise-separate-but-identical `nixpkgs_N` nodes into a single
/// meta-level reference.
const CANONICAL_INPUTS: &[&str] = &["nixpkgs"];
/// Env vars hive-c0re forwards from its own systemd unit env into every
/// sub-agent's harness service env. Each entry is `(env_var_name,
/// host_value)`. Empty / unset vars are filtered out so absent options
/// don't render no-op `FOO = ""` lines into the meta flake.
///
/// Returns owned `String` values so the result is `'static`-friendly +
/// trivial to stub from tests (which build their own slice instead of
/// touching process-wide env).
const FORWARDED_VARS: &[&str] = &[
// Where the swarm queue is, as an agent container reaches it. An address
// the *host* computes, never a loopback address, which inside a container
// is the agent itself.
"HIVE_AGENT_NATS_URL",
// Where the swarm secret store listens. The hive's own `BAO_ADDR` value,
// forwarded under a separate name so the container never inherits the
// hive's store environment wholesale — the address is the only part of it
// an agent may have, the certificate beside it being the hive's own.
"HIVE_AGENT_BAO_ADDR",
// The mount path of the store's services `pki` engine, whose root an agent
// fetches to trust the swarm. Forwarded with the address, under the same gate.
"HIVE_AGENT_BAO_SERVICES_PKI_MOUNT",
// Where an agent's `swarm-logs` queries, computed by the host for the
// same reason as the queue's: it is a gateway address, and a container
// cannot derive it from anything it holds.
"HIVE_AGENT_LOGS_QUERY_URL",
// The metrics store's origin, for `swarm-metrics`, for the same reason.
"HIVE_AGENT_METRICS_URL",
"HIVE_FORGE_URL",
"HIVE_FORGE_PUBLIC_URL",
"HIVE_MATRIX_URL",
"HYPERHIVE_SWARM_NAME",
];
/// Map of forwarded env var -> the agent option carrying the same value.
///
/// Both exist because they're consumed at different times: the option is baked
/// into scripts at build time (forge-avatar-sync bakes `FORGE_URL` from it), the env
/// var is read at runtime. Setting only one leaves the other on its default,
/// which is how a hive ends up with two disagreeing answers for one value.
///
/// The swarm display name is here for that reason: `otel.nix` reads the option
/// at eval time for the `swarm=` resource label, and with the env var alone
/// that label evaluates to `unknown` while the process env holds the right
/// name. Half-wiring this map is a value that evaluates fine and is silently
/// wrong.
const FORWARDED_VAR_OPTIONS: &[(&str, &str)] = &[
// Read at build time to decide whether the in-container identity check is
// generated at all — see `nix/agent-modules/bao.nix`. Both halves wired
// for this map's own reason: the unit bakes the address into its own
// environment, so an agent whose option says no store and whose env says
// otherwise would have a check that is simply not there.
("HIVE_AGENT_BAO_ADDR", "services.hyperhive.agent.bao.addr"),
// Read at build time to bake the root-fetch URL into
// `nix/agent-modules/hive-ca.nix`'s unit.
(
"HIVE_AGENT_BAO_SERVICES_PKI_MOUNT",
"services.hyperhive.agent.bao.servicesPkiMount",
),
// Read at build time to decide whether `swarm-logs` is installed at all —
// see `nix/agent-modules/logs.nix`. Both halves wired for this map's own
// reason: an agent whose option says no log store and whose env says
// otherwise has a binary that is not on PATH and coordinates that claim
// it is.
(
"HIVE_AGENT_LOGS_QUERY_URL",
"services.hyperhive.agent.logs.queryUrl",
),
// The same for `swarm-metrics`: see `nix/agent-modules/metrics.nix`.
(
"HIVE_AGENT_METRICS_URL",
"services.hyperhive.agent.metrics.url",
),
("HIVE_FORGE_URL", "services.hyperhive.agent.forge.url"),
("HIVE_MATRIX_URL", "services.hyperhive.agent.matrix.url"),
("HYPERHIVE_SWARM_NAME", "services.hyperhive.agent.swarmName"),
];
/// Render the forwarded-var option assignments for one agent's module block.
///
/// Split out of `render_flake` so it can be tested without touching process
/// env: the render-level tests have to `set_var`, which forces them to
/// serialise on the crate's `test_env` lock (a `#[cfg(test)]` module, so this
/// deliberately isn't an intra-doc link). A pure function over the
/// already-collected pairs has no such hazard.
///
/// A var that isn't present emits nothing rather than a guess. For an optional
/// service that is the whole point — the agent option defaults to `null`,
/// meaning "not configured", and the units that would use it aren't generated.
/// For a service the hive cannot run without, silence would instead produce a
/// fleet of agents quietly missing an integration, so those are checked by
/// [`require_service_urls`] before this is called.
fn push_forwarded_var_options(out: &mut String, vars: &[(&'static str, String)]) {
use std::fmt::Write as _;
for (var, val) in vars {
let Some((_, option)) = FORWARDED_VAR_OPTIONS.iter().find(|(name, _)| name == var) else {
continue;
};
let escaped = val.replace('\\', "\\\\").replace('"', "\\\"");
let _ = writeln!(out, " {option} = \"{escaped}\";");
}
/// [`hive_meta_flake::render_flake`] with the forwarded values and the GitHub
/// switch read from this process's environment.
fn render_flake(hyperhive_url: &str, agents: &[AgentSpec]) -> Result<String> {
hive_meta_flake::render_flake(
hyperhive_url,
agents,
&forwarded_env_vars(),
std::env::var_os("HYPERHIVE_GITHUB_DISABLED").is_some(),
)
}
/// Service URLs a running hive must always supply, checked before rendering.
@ -562,7 +436,7 @@ const REQUIRED_SERVICE_URL_VARS: &[&str] = &["HIVE_FORGE_URL"];
/// `vars`.
///
/// Pure over the already-collected pairs so it can be tested without touching
/// process env (the same reason [`push_forwarded_var_options`] is split out).
/// process env (the same reason [`hive_meta_flake::push_forwarded_var_options`] is split out).
///
/// Checked by `sync_agents` — the point at which the hive commits a rendered
/// flake to disk — rather than inside the renderer. Rendering is a pure string
@ -693,252 +567,6 @@ where
})
}
/// The subset of `CANONICAL_INPUTS` that the `flake.lock` text `raw` declares
/// as direct (root-level) inputs. Empty when the lock is unparsable — safe
/// degradation, the worst case is no dedup for that agent.
fn canonical_inputs_in_lock(raw: &str) -> Vec<&'static str> {
let Ok(json) = serde_json::from_str::<serde_json::Value>(raw) else {
return Vec::new();
};
let Some(nodes) = json.get("nodes").and_then(|v| v.as_object()) else {
return Vec::new();
};
let Some(root_name) = json.get("root").and_then(|v| v.as_str()) else {
return Vec::new();
};
let Some(root_inputs) = nodes
.get(root_name)
.and_then(|n| n.get("inputs"))
.and_then(|v| v.as_object())
else {
return Vec::new();
};
CANONICAL_INPUTS
.iter()
.copied()
.filter(|canon| root_inputs.contains_key(*canon))
.collect()
}
/// Render the meta flake. Errors on a custom agent without a [`AgentPin`].
#[allow(
clippy::too_many_lines,
reason = "templated string-builder for the meta flake — the length is one \
contiguous fmt block, splitting it would just hide the shape"
)]
fn render_flake(hyperhive_url: &str, agents: &[AgentSpec]) -> Result<String> {
use std::fmt::Write as _;
let mut out = String::new();
out.push_str("{\n description = \"hyperhive deployed agents\";\n inputs = {\n");
// `hyperhive` is pinned by forge URL and rev, so the flake resolves on
// any machine that can reach the forge. `nixpkgs` follows hyperhive's
// own pin, which cascades to every agent because
// `agent-<n>.inputs.nixpkgs.follows = "nixpkgs"` resolves to this node.
let _ = writeln!(out, " hyperhive.url = \"{hyperhive_url}\";");
out.push_str(" nixpkgs.follows = \"hyperhive/nixpkgs\";\n");
// Each agent's config input is its forge repo at the pinned commit, so
// the flake text depends only on (agent, rev) and resolves anywhere that
// can reach the forge.
for spec in agents {
// An archetype agent has no config repo, so no input: `mkAgent`
// takes its module from the archetype.
if spec.archetype.is_some() {
continue;
}
let pin = spec.pin.as_ref().with_context(|| {
format!(
"agent {}: no pinned rev, refusing to render an unpinned config input",
spec.name
)
})?;
let _ = writeln!(
out,
" agent-{name}.url = \"{url}\";",
name = spec.name,
url = pin.url,
);
// For each canonical input the agent's `flake.lock` declares at the
// pinned commit, emit
// `inputs.agent-<name>.inputs.<canon>.follows = "<canon>"`.
// Collapses otherwise-separate-but-identical nixpkgs nodes
// (root + every agent's own nixpkgs) into one. Skipped
// silently for agents that don't declare the input — emitting
// follows on a non-existent input would error at
// `nix flake lock` time.
for canon in &pin.canonical_inputs {
let _ = writeln!(
out,
" agent-{}.inputs.{canon}.follows = \"{canon}\";",
spec.name,
);
}
}
out.push_str(
" };\n outputs =\n { self, hyperhive, ... }@inputs:\n let\n mkAgent = { name, port, archetype ? null }:\n",
);
out.push_str(
r#" let
base = hyperhive.nixosConfigurations.agent-base;
# Every flake an archetype can come from, by its source name.
archetypeSources = { inherit hyperhive; };
agentModule =
if archetype == null then
inputs."agent-${name}".nixosModules.default
else
(archetypeSources.${archetype.source}
or (throw "agent ${name}: archetype source ${archetype.source} is not an input of this hive's meta flake")
).hyperhiveArchetypes.${archetype.name}.module
or (throw "agent ${name}: this hive's ${archetype.source} input has no archetype ${archetype.name}; update that input");
service = "hive-agent";
in
base.extendModules {
modules = [
agentModule
{
"#,
);
// Agent-facing service URLs (`services.hyperhive.agent.forge.url`, `services.hyperhive.agent.matrix.url`):
// emit the host's real values as build-time agent config, the same
// host-state -> agent-module shape as the CA block above.
//
// These options exist already, but until now *nothing set them*, so every
// agent silently fell back to their `localhost:<port>` defaults while the
// true value reached the container only as an env var (below). Two sources
// of truth that disagree, with the winner decided by which code path
// happens to read which one --- the option default is baked into scripts
// at build time, the env var is read at runtime.
//
// Rendering them here makes the option the single source, which is the
// precondition for removing those defaults: a loopback address is only
// ever correct when the callee shares the caller's netns, and the forge
// and homeserver are moving to swarm level, possibly on other hosts.
//
// Absent vars emit nothing rather than a guess, and the agent option
// treats "unset" as "this service is not configured" rather than
// substituting a loopback address — an absent integration instead of a
// misdirected one.
//
// That is the right default for an optional service and the wrong one for
// the forge, which a running hive always has — so `sync_agents` rejects a
// missing `HIVE_FORGE_URL` before it writes anything (`require_service_urls`).
// The check lives there rather than here because rendering is a pure string
// operation the tests exercise directly.
push_forwarded_var_options(&mut out, &forwarded_env_vars());
// GitHub integration is on by default in every agent
// (`services.hyperhive.agent.github.enable`); the host turns it off swarm-wide via
// `services.hyperhive.swarm.github.enable = false`, surfaced here as the
// `HYPERHIVE_GITHUB_DISABLED` env on hive-c0re's unit. Only the OFF
// override is propagated — the enabled default needs no per-agent line.
if std::env::var_os("HYPERHIVE_GITHUB_DISABLED").is_some() {
out.push_str(" services.hyperhive.agent.github.enable = false;\n");
}
out.push_str(
r#" # The harness service inside the container runs as a
# non-root unix user named after the agent (`damocles`,
# `iris`, `root`, …). UID auto-assigned by NixOS; the
# per-agent override here is what makes
# `services.hyperhive.agent.user.name` match the agent's identity
# instead of the harness default of `"agent"`.
services.hyperhive.agent.user.name = name;
# Without this an agent container is called `nixos` and ships
# every log line under that: nixpkgs sets the hostname from the
# attr name in the `containers.<name>` submodule, and an
# agent's system is its own `nixosSystem` off this flake, which
# never evaluates that option. The machine name, not the
# logical one — it is what `container.name` on our metrics and
# nspawn itself already call this container, so logs join to
# both without a prefix transform.
networking.hostName = "h-${name}";
programs.git.config.user = {
name = name;
email = "${name}@hyperhive.local";
};
# Container-wide env: every service + co-process daemon can
# resolve the agent's durable state dir without hard-coding it.
# `environment.variables` only writes /etc/environment (login
# shells); `systemd.globalEnvironment` is the analogue for
# systemd units so forge-avatar-sync /
# hive-matrix-daemon etc. can read `$HYPERHIVE_STATE_DIR`
# without each service having to redeclare it.
environment.variables = {
HIVE_LABEL = name;
HYPERHIVE_STATE_DIR = "/agents/${name}/state";
HYPERHIVE_HARNESS_DIR = "/agents/${name}/harness";
};
systemd.globalEnvironment = {
HIVE_LABEL = name;
HYPERHIVE_STATE_DIR = "/agents/${name}/state";
HYPERHIVE_HARNESS_DIR = "/agents/${name}/harness";
"#,
);
// Forwarded vars (HIVE_FORGE_URL etc.) also go into globalEnvironment,
// not just the harness service env below, so EVERY service + shell in
// the container inherits them — crucially the bash-task runner (where
// `hive-forge` + `git` actually run), plus the matrix daemon, forge-avatar-sync
// and interactive shells. Scoped to the harness service alone they were
// invisible to bash tasks: harmless in shared netns (the localhost
// default works) but broken under isolation, where the in-cluster
// `forge.<domain>` URL is the only reachable path.
for (var, val) in forwarded_env_vars() {
let escaped = val.replace('\\', "\\\\").replace('"', "\\\"");
let _ = writeln!(out, " {var} = \"{escaped}\";");
}
out.push_str(
r" };
systemd.services.${service}.environment = {
HIVE_PORT = toString port;
HIVE_LABEL = name;
",
);
// Forwarded env vars — picked up from hive-c0re's own systemd unit
// env (`services.hyperhive.*` options flow through the hyperhive
// NixOS module into the host process). We copy whatever's set into
// each sub-agent's harness service env so the in-container surfaces
// (`identity.rs`, `forge_notify`) see a consistent view across the
// whole hive. Absent host-side env (option not set) → skip emission
// → in-container accessors fall back to None / defaults gracefully.
//
// - HIVE_FORGE_URL: agents poll this for Forgejo notifications.
// - HYPERHIVE_SWARM_NAME: human display name for the swarm.
for (var, val) in forwarded_env_vars() {
let escaped = val.replace('\\', "\\\\").replace('"', "\\\"");
let _ = writeln!(out, " {var} = \"{escaped}\";");
}
out.push_str(
r#" HYPERHIVE_STATE_DIR = "/agents/${name}/state";
HYPERHIVE_HARNESS_DIR = "/agents/${name}/harness";
};
}
# Tells the harness the agent has no config repo of its own.
(if archetype == null then { } else {
systemd.services.${service}.environment.HIVE_ARCHETYPE = archetype.name;
})
];
};
in
{
nixosConfigurations = {
"#,
);
for spec in agents {
// `source` and `name` are identifiers (`archetypes::store_read`), so
// they need no escaping.
let archetype = spec.archetype.as_ref().map_or(String::new(), |a| {
format!(
" archetype = {{ source = \"{}\"; name = \"{}\"; }};",
a.source, a.name
)
});
let _ = writeln!(
out,
" {} = mkAgent {{ name = \"{}\"; port = {};{archetype} }};",
spec.name, spec.name, spec.port,
);
}
out.push_str(" };\n };\n}\n");
Ok(out)
}
/// Return the list of file names that are currently staged (index differs
/// from HEAD). On the initial commit (`HEAD` doesn't exist yet) falls back
/// to `git diff --cached --name-only HEAD` failing gracefully by using
@ -1547,12 +1175,12 @@ mod tests {
);
}
/// The queue address reaches the harness as env only. The agent module
/// declares no `services.hyperhive.agent.queue.*` option, so rendering one
/// into the meta flake fails every agent's evaluation.
/// The queue address reaches the container in its hive facts, so the render
/// carries neither it nor any `services.hyperhive.agent.queue.*` option,
/// which no agent module declares.
#[test]
fn queue_address_is_forwarded_as_env_and_no_option() {
assert!(FORWARDED_VARS.contains(&"HIVE_AGENT_NATS_URL"));
fn queue_address_is_not_rendered_into_the_flake() {
assert!(!FORWARDED_VARS.contains(&"HIVE_AGENT_NATS_URL"));
assert!(
!FORWARDED_VARS.contains(&"HIVE_AGENT_OIDC_TOKEN_ENDPOINT"),
"no agent reads a token endpoint"

395
hive-c0re/src/meta_rev.rs Normal file
View file

@ -0,0 +1,395 @@
//! The `internal/meta` commit a hive builds an agent from.
//!
//! `internal/meta` is the swarm's meta flake, committed by swarm-controller.
//! A rebuild's `MetaSync` node resolves its head once ([`resolve`]) and
//! records it ([`record`]); `Prebuild` and `Swap` read the record
//! ([`recorded`]), so both build the same flake. A create resolves and uses
//! the rev directly. No rev, whether because the repo or its commit is absent
//! or because the commit does not pin this agent's current config, leaves the
//! build on the hive's own meta flake.
use anyhow::{Context, Result};
use hive_priv_sock::{meta_flake_url, valid_meta_rev};
use swarm_queue_client::agent_archetype::ArchetypeRef;
/// What the forge says about `internal/meta` and an agent's config repo.
pub(crate) trait MetaSource {
/// Whether nix's own `git` can authenticate to the forge: it reads as
/// `core`, from the token file, whatever token this hive reads with.
fn nix_can_fetch(&self) -> bool;
/// The default branch's head commit of `internal/meta`; `None` when the
/// repo is absent or has no commit.
async fn meta_head(&self) -> Result<Option<String>>;
/// `internal/meta`'s `flake.nix` at `rev`.
async fn flake_at(&self, rev: &str) -> Result<String>;
/// The head of `agent-configs/<agent>`'s `main`; `None` when it has none.
async fn config_head(&self, agent: &str) -> Result<Option<String>>;
}
/// The `internal/meta` commit to build `agent` from, or `None` for the hive's
/// own flake.
///
/// `internal/meta` is private, so a hive whose nix cannot authenticate
/// ([`MetaSource::nix_can_fetch`]) builds from its own flake. The head is
/// taken only when its `flake.nix` builds the agent the way it is wanted now:
/// from `archetype` when that is set, otherwise from the config commit the
/// forge's `main` is at. A head that is behind (the swarm's update has not
/// run, or failed), lacks the agent or lists it under another archetype would
/// build an older module than the one being deployed.
///
/// # Errors
/// A forge read that failed.
pub(crate) async fn choose(
source: &impl MetaSource,
agent: &str,
archetype: Option<&ArchetypeRef>,
) -> Result<Option<String>> {
if !source.nix_can_fetch() {
return Ok(None);
}
let Some(rev) = source.meta_head().await? else {
return Ok(None);
};
if !valid_meta_rev(&rev) {
return Ok(None);
}
let flake = source.flake_at(&rev).await?;
let config_head = if archetype.is_some() {
None
} else {
let Some(head) = source.config_head(agent).await? else {
return Ok(None);
};
Some(head)
};
Ok(
hive_meta_flake::builds_agent_at(&flake, agent, archetype, config_head.as_deref())
.then_some(rev),
)
}
/// [`choose`] against the forge this hive reads. `None`, logged, whenever the
/// hive cannot tell: no forge credential, a failed read, no usable commit.
pub(crate) async fn resolve(agent: &str) -> Option<String> {
let archetype = match crate::archetypes::of(agent) {
Ok(archetype) => archetype,
Err(e) => {
tracing::warn!(%agent, error = ?e, "internal/meta: cannot read the agent's archetype; building from the hive's own flake");
return None;
}
};
let Some(source) = crate::forge::internal_meta_source().await else {
tracing::info!(%agent, "internal/meta: no forge read token; building from the hive's own flake");
return None;
};
match choose(&source, agent, archetype.as_ref()).await {
Ok(Some(rev)) => {
tracing::info!(%agent, %rev, "internal/meta: building from the swarm's meta flake");
Some(rev)
}
Ok(None) => {
tracing::info!(%agent, "internal/meta: absent or not pinning this agent's config; building from the hive's own flake");
None
}
Err(e) => {
tracing::warn!(%agent, error = %format!("{e:#}"), "internal/meta: cannot read it; building from the hive's own flake");
None
}
}
}
/// Record `rev` as the commit `agent`'s build reads, or clear the record for
/// `None`. The record is in hive-c0re's own state ([`crate::paths::meta_rev_dir`]),
/// where the agent cannot write.
///
/// # Errors
/// The record file could not be written or removed.
pub(crate) fn record(agent: &str, rev: Option<&str>) -> Result<()> {
record_in(&crate::paths::meta_rev_dir(), agent, rev)
}
/// The commit [`record`] stored for `agent`, if it is a valid one.
pub(crate) fn recorded(agent: &str) -> Option<String> {
recorded_in(&crate::paths::meta_rev_dir(), agent)
}
/// Written whole to a temp file beside the record and renamed over it, so a
/// reader sees the old record or the new one and a crash leaves no partial
/// file.
fn record_in(dir: &std::path::Path, agent: &str, rev: Option<&str>) -> Result<()> {
let path = dir.join(agent);
match rev {
Some(rev) => {
std::fs::create_dir_all(dir).with_context(|| format!("create {}", dir.display()))?;
let tmp = dir.join(format!(".{agent}.tmp"));
std::fs::write(&tmp, rev).with_context(|| format!("write {}", tmp.display()))?;
std::fs::rename(&tmp, &path)
.with_context(|| format!("rename {} to {}", tmp.display(), path.display()))
}
None => match std::fs::remove_file(&path) {
Err(e) if e.kind() != std::io::ErrorKind::NotFound => {
Err(e).with_context(|| format!("remove {}", path.display()))
}
_ => Ok(()),
},
}
}
fn recorded_in(dir: &std::path::Path, agent: &str) -> Option<String> {
let rev = std::fs::read_to_string(dir.join(agent)).ok()?;
valid_meta_rev(rev.trim()).then(|| rev.trim().to_owned())
}
/// The `<flake>#<agent>` ref [`crate::lifecycle::prebuild_toplevel`] builds
/// for `rev`: the same flake hive-priv builds, from the same forge URL.
pub(crate) fn flake_ref(agent: &str, rev: &str) -> String {
flake_ref_at(crate::forge::forge_http_base(), agent, rev)
}
fn flake_ref_at(forge_base: &str, agent: &str, rev: &str) -> String {
format!("{}#{agent}", meta_flake_url(forge_base, rev))
}
#[cfg(test)]
mod tests {
use super::*;
const HYPERHIVE: &str = "1111111111111111111111111111111111111111";
const META: &str = "3333333333333333333333333333333333333333";
const ARGUS_HEAD: &str = "2222222222222222222222222222222222222222";
const STALE: &str = "4444444444444444444444444444444444444444";
/// A forge holding `internal/meta` at [`META`] with the given flake, and
/// `agent-configs/argus` at `config_head`.
struct Forge {
head: Option<&'static str>,
flake: String,
config_head: Option<&'static str>,
fetchable: bool,
}
impl MetaSource for Forge {
fn nix_can_fetch(&self) -> bool {
self.fetchable
}
async fn meta_head(&self) -> Result<Option<String>> {
Ok(self.head.map(str::to_owned))
}
async fn flake_at(&self, rev: &str) -> Result<String> {
assert_eq!(Some(rev), self.head, "the flake is read at the head");
Ok(self.flake.clone())
}
async fn config_head(&self, _: &str) -> Result<Option<String>> {
Ok(self.config_head.map(str::to_owned))
}
}
/// `internal/meta`'s flake as swarm-controller renders it: argus pinned at
/// [`ARGUS_HEAD`], and a reviewer from an archetype.
fn flake() -> String {
use swarm_wire::agent_archetype::ArchetypeRef;
let url = |repo: &str, rev: &str| {
hive_meta_flake::pinned_git_url(&format!("https://f.t/{repo}.git"), Some(rev)).unwrap()
};
let spec = |name: &str, archetype, pin| hive_meta_flake::AgentSpec {
name: name.to_owned(),
port: hive_meta_flake::agent_web_port(name),
archetype,
pin,
};
hive_meta_flake::render_flake(
&url("hyperhive/hyperhive", HYPERHIVE),
&[
spec(
"argus",
None,
Some(hive_meta_flake::AgentPin {
url: url("agent-configs/argus", ARGUS_HEAD),
canonical_inputs: vec![],
}),
),
spec(
"rev",
Some(ArchetypeRef {
source: "hyperhive".to_owned(),
name: "reviewer".to_owned(),
}),
None,
),
],
&[],
false,
)
.unwrap()
}
fn forge(config_head: Option<&'static str>) -> Forge {
Forge {
head: Some(META),
flake: flake(),
config_head,
fetchable: true,
}
}
#[tokio::test]
async fn the_head_is_taken_when_it_pins_the_agents_current_config() {
assert_eq!(
choose(&forge(Some(ARGUS_HEAD)), "argus", None)
.await
.unwrap(),
Some(META.to_owned())
);
}
#[tokio::test]
async fn a_head_behind_the_agents_config_is_not_taken() {
assert_eq!(
choose(&forge(Some(STALE)), "argus", None).await.unwrap(),
None
);
}
#[tokio::test]
async fn a_head_without_the_agent_is_not_taken() {
let mut source = forge(Some(ARGUS_HEAD));
source.flake = source.flake.replace("argus", "someone");
assert_eq!(choose(&source, "argus", None).await.unwrap(), None);
}
fn reviewer() -> ArchetypeRef {
ArchetypeRef {
source: "hyperhive".to_owned(),
name: "reviewer".to_owned(),
}
}
#[tokio::test]
async fn an_archetype_agent_is_taken_when_the_head_lists_that_archetype() {
struct Archetypes(Forge);
impl MetaSource for Archetypes {
fn nix_can_fetch(&self) -> bool {
self.0.nix_can_fetch()
}
async fn meta_head(&self) -> Result<Option<String>> {
self.0.meta_head().await
}
async fn flake_at(&self, rev: &str) -> Result<String> {
self.0.flake_at(rev).await
}
async fn config_head(&self, _: &str) -> Result<Option<String>> {
panic!("an archetype agent has no config repo to read")
}
}
let source = Archetypes(forge(None));
assert_eq!(
choose(&source, "rev", Some(&reviewer())).await.unwrap(),
Some(META.to_owned())
);
let other = ArchetypeRef {
name: "planner".to_owned(),
..reviewer()
};
assert_eq!(
choose(&source, "rev", Some(&other)).await.unwrap(),
None,
"the head lists another archetype"
);
assert_eq!(
choose(&source, "ghost", Some(&reviewer())).await.unwrap(),
None
);
}
/// The head lists argus as a custom agent and rev as an archetype agent;
/// an agent switched either way is not what the head builds.
#[tokio::test]
async fn an_agent_switched_between_custom_and_archetype_is_not_taken() {
let source = forge(Some(ARGUS_HEAD));
assert_eq!(
choose(&source, "argus", Some(&reviewer())).await.unwrap(),
None,
"custom in the head, archetype now"
);
assert_eq!(
choose(&source, "rev", None).await.unwrap(),
None,
"archetype in the head, custom now"
);
}
/// A hive without the credential nix's git reads builds from its own flake
/// even though its own token reads the repo; the first test is the control.
#[tokio::test]
async fn a_hive_whose_nix_cannot_authenticate_builds_from_its_own_flake() {
let mut source = forge(Some(ARGUS_HEAD));
source.fetchable = false;
assert_eq!(choose(&source, "argus", None).await.unwrap(), None);
}
#[tokio::test]
async fn no_repo_or_no_commit_is_the_hives_own_flake() {
let mut source = forge(Some(ARGUS_HEAD));
source.head = None;
assert_eq!(choose(&source, "argus", None).await.unwrap(), None);
}
#[tokio::test]
async fn a_custom_agent_with_no_config_commit_is_the_hives_own_flake() {
assert_eq!(choose(&forge(None), "argus", None).await.unwrap(), None);
}
#[test]
fn a_record_is_read_back_and_cleared() {
let dir = tempfile::tempdir().unwrap();
assert_eq!(recorded_in(dir.path(), "argus"), None);
record_in(dir.path(), "argus", Some(META)).unwrap();
assert_eq!(recorded_in(dir.path(), "argus"), Some(META.to_owned()));
assert_eq!(
recorded_in(dir.path(), "rev"),
None,
"a record is one agent's"
);
record_in(dir.path(), "argus", Some(STALE)).unwrap();
assert_eq!(recorded_in(dir.path(), "argus"), Some(STALE.to_owned()));
record_in(dir.path(), "argus", None).unwrap();
assert_eq!(recorded_in(dir.path(), "argus"), None);
record_in(dir.path(), "argus", None).unwrap();
}
#[test]
fn a_record_leaves_no_temp_file_and_creates_its_dir() {
let dir = tempfile::tempdir().unwrap();
let records = dir.path().join("meta-rev");
record_in(&records, "argus", Some(META)).unwrap();
let names: Vec<_> = std::fs::read_dir(&records)
.unwrap()
.map(|e| e.unwrap().file_name())
.collect();
assert_eq!(names, ["argus"]);
}
#[test]
fn a_record_that_is_not_a_commit_id_is_no_record() {
let dir = tempfile::tempdir().unwrap();
std::fs::write(dir.path().join("argus"), "main\n").unwrap();
assert_eq!(recorded_in(dir.path(), "argus"), None);
}
/// The record is hive-c0re's own state, never the agent-writable runtime
/// dir bind-mounted into the container.
#[test]
fn the_record_is_outside_the_agents_runtime_dir() {
assert!(!crate::paths::meta_rev_dir().starts_with(crate::paths::runtime_root()));
assert!(crate::paths::meta_rev_dir().starts_with(crate::paths::state_root()));
}
#[test]
fn the_prebuild_ref_is_the_flake_hive_priv_builds() {
assert_eq!(
flake_ref_at("http://forge.t.local", "argus", META),
format!("git+http://forge.t.local/internal/meta.git?rev={META}#argus")
);
}
}

Some files were not shown because too many files have changed in this diff Show more