hyperhive/docs/swarm/archetypes.md

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, inbox, execution: the default set without meta. With execution it can run hive-forge, git and other commands.

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" "inbox" "execution" ];
    limits = { memory_max = "4G"; };
    inference = { effort = "high"; };
  };
};

• meta is plain data: no derivation, no path, no function. The swarm evaluates meta alone.
• Every archetype needs a description. permissions, limits and inference are optional and take the shapes POST /api/agents takes. The swarm ignores other keys in meta.
• module is 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

1. swarm-controller asks the builder for the list on the queue subject $SWARM.builder.archetypes once the queue connects, and every 10 minutes after that.

2. The builder evaluates the meta of each hyperhiveArchetypes entry on its own hyperhive and nixpkgs sources, and answers with the JSON or the last lines nix printed:

   nix eval --json <hyperhive>#hyperhiveArchetypes \
     --apply 'builtins.mapAttrs (_: a: a.meta)'
   

3. The controller checks each archetype the way POST /api/agents checks its settings and stores the result in the agent-archetypes KV bucket, under the key hyperhive, 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's refused map and the controller's journal.

4. GET /api/archetypes answers 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", "inbox", "execution"]
    }
  },
  "refused": { "broken": "limits: …" }
}