93 lines
3.5 KiB
Markdown
93 lines
3.5 KiB
Markdown
# Swarm
|
|
|
|
A swarm is a queen agent plus worker agents that coordinate over Nostr to
|
|
solve a problem the admin posts.
|
|
|
|
- `queen/` — the queen. Watches the admin's kind 1 posts; when addressed with
|
|
the phrase **"my queen"** (case-insensitive) she seeds a swarm.
|
|
- `worker1/`, `worker2/` — workers that pick up subtasks.
|
|
- `admin_post.sh` — publish a kind 1 note as the admin (signed by the n_signer).
|
|
|
|
Each agent runs from its own directory with its own `genesis.jsonc` and API
|
|
port:
|
|
|
|
| Agent | Port | Config |
|
|
|---------|------|---------------------------|
|
|
| queen | 8484 | `queen/genesis.jsonc` |
|
|
| worker1 | 8485 | `worker1/genesis.jsonc` |
|
|
| worker2 | 8486 | `worker2/genesis.jsonc` |
|
|
|
|
> **Genesis is consumed once.** After first run, all agent state (skills,
|
|
> profile, relay list) lives on the relay. To change an agent, edit the events
|
|
> on the relay — not `genesis.jsonc`.
|
|
|
|
## Running the queen
|
|
|
|
The launcher runs the binary in the foreground, so output streams to your
|
|
terminal:
|
|
|
|
```bash
|
|
./swarm/queen/run.sh
|
|
```
|
|
|
|
Verify it is up:
|
|
|
|
```bash
|
|
curl -s http://127.0.0.1:8484/api/status
|
|
```
|
|
|
|
## Following the swarm
|
|
|
|
`nak` cannot OR two filters in a single REQ (and `-a` + `-p` in one filter is
|
|
AND, which returns nothing useful), so run two parallel `nak` streams in one
|
|
line. `-a` shows the admin's own posts; `-p` shows every event that tags the
|
|
admin (queen/worker replies).
|
|
|
|
```bash
|
|
nak req --stream -k 1 -a 8ff74724ed641b3c28e5a86d7c5cbc49c37638ace8c6c38935860e7a5eedde0e ws://127.0.0.1:7777 & nak req --stream -k 1 -p 8ff74724ed641b3c28e5a86d7c5cbc49c37638ace8c6c38935860e7a5eedde0e ws://127.0.0.1:7777 & wait
|
|
```
|
|
|
|
With labels and readable formatting (requires `jq`):
|
|
|
|
```bash
|
|
nak req --stream -k 1 -a 8ff74724ed641b3c28e5a86d7c5cbc49c37638ace8c6c38935860e7a5eedde0e ws://127.0.0.1:7777 | jq -r '"ORIG \(.created_at) \(.content[0:80]|gsub("\n";" "))"' & nak req --stream -k 1 -p 8ff74724ed641b3c28e5a86d7c5cbc49c37638ace8c6c38935860e7a5eedde0e ws://127.0.0.1:7777 | jq -r '"REPLY \(.created_at) \(.content[0:80]|gsub("\n";" "))"' & wait
|
|
```
|
|
|
|
Notes:
|
|
|
|
- `--stream` replays existing history first, then stays live. To start from
|
|
*now* only, add `-s $(date +%s)` to each.
|
|
- The admin hex `8ff74724…` is the decoded form of
|
|
`npub13lm5wf8dvsdnc2894pkhch9uf8phvw9varrv8zf4sc885hhdmc8q6lx7ks`. `nak`
|
|
accepts the npub too, but hex is unambiguous.
|
|
- This shows the queen's `root` and `claim` events (both tag the admin with
|
|
`p`), so you see the full swarm activity.
|
|
|
|
## Why the web feed misses replies
|
|
|
|
`feed.html` (in `client_local`) is a feed, not a thread viewer. It fetches
|
|
exactly one level of replies to each top-level post (`#e: [postIds]`), so
|
|
nested replies — e.g. the queen's `claim`, which replies to her own `root`
|
|
rather than to the admin's post — are never fetched. Use the `nak` streams
|
|
above to follow the full thread.
|
|
|
|
## Managing the relay list
|
|
|
|
The relay list is stored on Nostr as replaceable events signed by the agent's
|
|
key: kind `10002` (NIP-65 relay list) and kind `10050` (DM relays). To change
|
|
it, publish new events — editing `genesis.jsonc` only matters on re-bootstrap.
|
|
|
|
Add a relay to the queen (replace `<QUEEN_NSEC>` and the relay URL):
|
|
|
|
```bash
|
|
nak event --sec <QUEEN_NSEC> -k 10002 -t r=ws://127.0.0.1:7777 -t r=wss://example.net/relay ws://127.0.0.1:7777
|
|
nak event --sec <QUEEN_NSEC> -k 10050 -t relay=ws://127.0.0.1:7777 -t relay=wss://example.net/relay ws://127.0.0.1:7777
|
|
```
|
|
|
|
Read the current list back:
|
|
|
|
```bash
|
|
nak req -k 10002 -a <QUEEN_HEX> ws://127.0.0.1:7777
|
|
nak req -k 10050 -a <QUEEN_HEX> ws://127.0.0.1:7777
|
|
```
|