hyperhive/docs/swarm/archetypes.md

Agent archetypes

An archetype is a named agent setup: settings to create the agent with, and a NixOS module its container runs. 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.

An agent created from an archetype has no agent-configs/<name> 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.

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.
android-dev	installs android-tools (adb, fastboot), Gradle and a JDK; default permissions.

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 meta flake imports it into each agent created from the archetype.

Today the swarm reads one flake: the hyperhive source the builder's host runs, so only the built-ins appear. The meta flake has one archetype source too, its own hyperhive input, and refuses an archetype from any other source name.

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: …" }
}

Creating an agent from an archetype

The create form sends the picked archetype as archetype on POST /api/agents, { "source": "hyperhive", "name": "reviewer" }. The controller refuses with 400 an archetype the stored list doesn't hold, then:

1. stores the choice in the agent-archetype KV bucket, keyed by agent name, next to the agent's permissions, caps and inference;
2. queues the creation graph without CreateRepo, AddRepoMember and InitAgentConfigRepo. Identity, forge user, docs read, the mints and the wanted state stay, and the deploy waits on those alone.

Destroying the agent deletes its key. Every hive may read any key of the bucket ($JS.API.DIRECT.GET.KV_agent-archetype.>) and write none; only the controller writes it.

Deploy swarm-nats-auth before the hives: every provision reads the agent's key, and a hive whose queue connection predates the grant gets a refused read, so its Provision nodes fail until it reconnects.

swarm-controller renders internal/meta's flake.nix with the hive-meta-flake crate, and reads each agent's archetype from the agent-archetype bucket to do so. For an archetype agent the render:

• adds no agent-<name> input and reads no config repo, and lists the agent as mkAgent { …; archetype = { source = "hyperhive"; name = "<name>"; }; };
• makes mkAgent import hyperhive.hyperhiveArchetypes.<name>.module in place of the agent's own flake, and set HIVE_ARCHETYPE in the harness environment.

The hive builds from internal/meta alone. It reads the agent's key when it provisions the agent and on every rebuild, and keeps the last value read in /var/lib/hyperhive/swarm-agent-archetypes.json. It takes the head of internal/meta only when that flake.nix lists the agent at the archetype it has now. When the read fails, a rebuild keeps the stored value. For an archetype agent the hive also:

• seeds no proposed or applied repo;
• ignores the rev of a swarm deploy request;
• mounts an empty /agents/<name>/config/.

The agent's system prompt says it has no config repo and names its archetype.

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 <name>; update that input. Update the hyperhive pin in internal/meta to fix it.