diff --git a/docs/swarm/README.md b/docs/swarm/README.md index 8c7e92ed..71f8bb2b 100644 --- a/docs/swarm/README.md +++ b/docs/swarm/README.md @@ -94,6 +94,11 @@ below. A hive without them reads | `never_reported` | this hive has never reported at all — normally a deployment that hasn't happened, not an outage | | `unknown` | something is publishing under a name that's not in `swarm.hives` — a typo in the roster, or a hive removed from the roster but still running | +The snapshot is the hive's `/health/ready` document plus `capabilities`, a list +of names for what the hive's release can do. Two exist: `tolerant-permissions`, and `no-config-checkout`, which +[turning an archetype agent into a custom one](archetypes.md#turn-into-custom) +needs. A hive on an older release lists none. + Every row also carries `last_seen_unix` and `age_seconds` if you want to apply your own threshold. The timestamp is the one the queue recorded on arrival, not one the hive put in its own payload. A roster hive's row diff --git a/docs/swarm/archetypes.md b/docs/swarm/archetypes.md index 6ae72a29..6494599a 100644 --- a/docs/swarm/archetypes.md +++ b/docs/swarm/archetypes.md @@ -9,7 +9,9 @@ field before you create the agent. An agent created from an archetype has no `agent-configs/` repo of its own. The swarm's `internal/meta` flake builds it from the archetype's module, so every agent of that archetype runs the same configuration. To change what it runs, change the -archetype. Picking "none" creates a custom agent, with its own config repo. +archetype. Picking "none" creates a custom agent, with its own config repo. The +swarm can also turn an archetype agent into a custom one later +([below](#turn-into-custom)). ## The built-in archetypes @@ -139,3 +141,57 @@ The module comes from the `hyperhive` input that `internal/meta` pins, not from the hive's own. When that pin predates the archetype, the agent's build fails with `this hive's hyperhive input has no archetype ; update that input`. Update the `hyperhive` pin in `internal/meta` to fix it. + +## Turn into custom + +An archetype agent can become a custom agent with its own +`agent-configs/` repo, either from the agent's overview in the swarm UI +(the "turn into custom" button asks first) or with `POST /api/agents/{name}/custom`. +The agent keeps its state, permissions, caps, inference settings and accounts. +Its configuration stays the same, except that it no longer has `HIVE_ARCHETYPE` +in its environment. Keeping the config current is then up to the repo's owner. +Nothing here undoes it. + +The controller refuses with 409 an agent that no hive or more than one hive +places, and one whose hive doesn't list the +`no-config-checkout` capability (see below). Otherwise it queues a job graph: + +1. `CreateRepo`, `CreateForgeUser` and `AddRepoMember`: the repo and the + agent's access to the repo, as for any custom agent. Each is a no-op for what + exists. +2. `SeedArchetypeConfig` commits two files to the repo. It copies nothing from + the archetype: + - `flake.nix` declares the archetype's source as an input, at the URL + `internal/meta` holds for that source today (a pinned rev, which is the input's only pin: the repo has no lock, and a source meta doesn't pin to a commit fails the node), and imports + `inputs..hyperhiveArchetypes..module` next to `./agent.nix`; + - `agent.nix` is an empty module for the owner's edits. + + The node leaves a repo whose `flake.nix` already is this file alone, whatever + URL it pins. Any other `flake.nix` fails the node. + +3. `DropArchetype` deletes the agent's `agent-archetype` key, only after the + seed and the member grant succeeded. A failure before it leaves the agent + archetype-built and working, and you can send the same request again. +4. `UpdateMeta`, then the build and the deploy, as for a merged config PR. + If the build fails, the agent is custom and has no key. Sending the request + again then queues only this step, as the earlier ones have run. + +When the source is `hyperhive`, the meta flake sets +`agent-.inputs.hyperhive.follows = "hyperhive"` for an agent whose +`flake.nix` or `flake.lock` declares a `hyperhive` input, so the lock holds one +hyperhive, and the module comes from the pin `internal/meta` holds. Any other +source keeps the pinned URL from its seeded `flake.nix`, and the meta lock +records that rev. The `follows` applies to every custom agent whose `flake.nix` +declares a `hyperhive` input, not only converted ones. A `hyperhive` node left +in a lock doesn't count. + +### Which hives may convert + +A hive that keeps a checkout of a custom agent's config would create one for +the converted agent, under the container's running mount. A hive that lists +`no-config-checkout` under `capabilities` in the status it publishes (the +document `GET /api/hives/status` serves as `snapshot`) keeps none: it builds a +custom agent from `internal/meta` alone, and the agent clones its own repo from +the forge. The controller reads the agent's hive's latest status and refuses +unless it's `fresh` and lists the capability; an older hive lists none. Deploy +the release to every hive that places archetype agents before converting theirs.