51035eac1d
A flake declares agent archetypes in its `hyperhiveArchetypes` output,
`<name> = { module; meta; }`. The hyperhive flake ships `reviewer`
(default permissions without `execution`).
swarm-builder answers `$SWARM.builder.archetypes` with the `meta` of
every archetype its own hyperhive source declares. swarm-controller asks
once the queue connects and every 10 minutes, checks each archetype as
`POST /api/agents` checks its settings, and stores the result in the
`agent-archetypes` KV bucket when it changed. `GET /api/archetypes`
serves it, and the create form's archetype select prefills permissions,
resource caps and inference from it.
The agent created is an ordinary agent with its own config repo; the
archetype's module is not applied yet.
Refs #5386
3.3 KiB
Agent archetypes
An archetype is a named set of settings to create an agent from. The swarm UI's create form lists the archetypes the swarm knows. Picking one fills the form's permissions, resource caps and inference fields from it, and you can still change each field before you create the agent.
The agent you create this way is an ordinary agent: it gets its own
agent-configs/<name> repo like any other, and the request carries only the
fields as the form shows them. Nothing records which archetype you picked.
The built-in archetypes
The hyperhive flake ships these:
| archetype | what it sets |
|---|---|
reviewer |
permissions messaging, meta, inbox: the default set without execution. It has no shell, so it can't run hive-forge, git or any command. |
Where an archetype comes from
A flake declares archetypes in its hyperhiveArchetypes output:
hyperhiveArchetypes.reviewer = {
module = { };
meta = {
description = "Reviews what it is sent.";
permissions = [ "messaging" "meta" "inbox" ];
limits = { memory_max = "4G"; };
inference = { effort = "high"; };
};
};
metais plain data: no derivation, no path, no function. The swarm evaluatesmetaalone.- Every archetype needs a
description.permissions,limitsandinferenceare optional and take the shapesPOST /api/agentstakes. The swarm ignores other keys inmeta. moduleis a NixOS module for the agent's container. The swarm doesn't apply it yet.
Today the swarm reads one flake: the hyperhive source the builder's host runs, so only the built-ins appear.
How the list stays current
-
swarm-controller asks the builder for the list on the queue subject
$SWARM.builder.archetypesonce the queue connects, and every 10 minutes after that. -
The builder evaluates the
metaof eachhyperhiveArchetypesentry on its own hyperhive and nixpkgs sources, and answers with the JSON or the last linesnixprinted:nix eval --json <hyperhive>#hyperhiveArchetypes \ --apply 'builtins.mapAttrs (_: a: a.meta)' -
The controller checks each archetype the way
POST /api/agentschecks its settings and stores the result in theagent-archetypesKV bucket, under the keyhyperhive, when it differs from the stored one. The list leaves out an archetype that fails the check, and its name and reason go into the record'srefusedmap and the controller's journal. -
GET /api/archetypesanswers from that record, and the create form lists from it.
A builder host redeploy can change the list. The next pass, within 10 minutes, picks it up. When no builder answers, the controller keeps the stored list and logs a warning on each pass. A swarm with no builder enabled shows no archetype select.
The stored value:
{
"source": "/nix/store/…-hyperhive-flake-source",
"archetypes": {
"reviewer": {
"description": "…",
"permissions": ["messaging", "meta", "inbox"]
}
},
"refused": { "broken": "limits: …" }
}