mara/hyperhive
mara/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Activity

an archetype carries its own notification-router flows for its agents

Browse source 
ArchetypeMeta gets flows, checked when the controller stores the record: every todo must go to the new members recipient, which the router expands to the agents of the archetype. The operator's flows document refuses members. The router reads the archetype records and each roster agent's archetype key, and its NATS grant gains read on both buckets.
This commit is contained in:
atlas 2026-11-11 04:36:25 +01:00 • committed by mara
commit 1efbb72fdd
1 changed files with 883 additions and 29 deletions
Download patch file Download diff file Expand all files Collapse all files

52
docs/2-handbook/swarm/archetypes.md
View file

@ -61,7 +61,9 @@ hyperhiveArchetypes.reviewer.meta.prompt = builtins.readFile ./prompts/reviewer.
`prompt` is optional text that prefills `AGENTS.md`, [below](#the-prompt).
`icon` is optional SVG text, at most 16 KiB, that the create form shows on the
archetype's tile; `builtins.readFile ./icon.svg` gives it. The swarm refuses an
`icon` that isn't SVG text or is over the limit, like any bad `meta`, and ignores
`icon` that isn't SVG text or is over the limit, like any bad `meta`.
`flows` is an optional list of notification router flows,
[below](#notification-flows). 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.
@ -93,6 +95,54 @@ archetype without `prompt` leaves the box alone.
Where the files live:
[the implementation page](../../4-implementation/swarm/archetypes.md#the-built-in-prompts).
## Notification flows
An archetype's `meta.flows` lists [notification router
flows](../../4-implementation/swarm/notify-router.md#flows) that run for every
agent of the archetype, next to the built-in flows and the ones in the
operator's document. A `todo` node in them sends to `members`: every agent
created from the archetype.
```nix
hyperhiveArchetypes.triage.meta.flows = [
{
id = "new-issues";
name = "new issues go to triage";
nodes = [
{ id = "src"; kind = "source"; events = [ "issues" ]; }
{ id = "opened"; kind = "match"; when = [ { field = "action"; equals = "opened"; } ]; }
{
id = "tell";
kind = "todo";
to = "members";
op = "upsert";
key = "forge:{{ repo }}#{{ number }}:triage";
text = "triage {{ repo }}#{{ number }}: {{ title }}";
}
];
edges = [
{ from = "src"; to = "opened"; }
{ from = "opened"; to = "tell"; }
];
}
];
```
- A flow here has the shape of a flow in the operator's document, with two
differences. Every `todo` must send to `members`. A flow that names an agent
or an event field's agents, or asks for a review, belongs in the operator's
document, and the swarm refuses it as it refuses any bad `meta`: the
archetype leaves the list and the reason goes into `refused`. The operator's
document in turn refuses `members`, since it has no archetype.
- Flow ids are unique within the archetype.
- Use a todo key that starts with `forge:{{ repo }}#{{ number }}:`, as the example
does. The built-in `closed` flow clears todos by that prefix when the issue
or PR closes.
- A change to the archetype's flows, or to who belongs to it, takes effect within
about 10 seconds of the next forge event. An agent outside the swarm gets
nothing.
- Custom agents have no archetype and get no archetype flows.
## How the list stays current
The swarm controller asks the builder for the list when the queue connects and