0ae34b1cd0
The operator parts of the persistence and config-changes pages merge into agents/persistence.md. The sqlite tables, state dirs, mounts and migrations move to 4-implementation/agent-state/persistence.md, and the deploy path, meta flake, deploy markers, startup migrations, root container, system messages and autoupdate move to 4-implementation/agent-state/config-changes.md. Links, code comments and nix comments that named the old sections point at the new pages.
72 lines
4.1 KiB
Markdown
72 lines
4.1 KiB
Markdown
# Swarm forge (Forgejo)
|
|
|
|
Private Forgejo instance running in a nixos-container (`hive-forge`, the
|
|
container and CLI name), used as the
|
|
swarm's persistent code-collaboration surface (issues, PRs, reviews,
|
|
attachments). Configured via `services.hyperhive.swarm.forge.*` (what the
|
|
forge IS to every hive — names, ports, URLs) plus
|
|
`services.hyperhive.deploy.forgejo.*` (what the host running it decides —
|
|
which build it runs, how it's served, what it mirrors, where its
|
|
host-local secrets sit).
|
|
Container
|
|
shape, ROOT_URL / sub-domain routing, and operator-vs-in-cluster URL
|
|
handling live in [`docs/4-implementation/networking/gateway.md`](../../4-implementation/networking/gateway.md); this file owns the
|
|
per-agent integration story and the notification pump that wakes
|
|
each agent on relevant activity.
|
|
|
|
## Token scopes
|
|
|
|
Two scope sets:
|
|
|
|
**`AGENT_TOKEN_SCOPES`** (swarm-controller's `forge::agent_token`, pinned
|
|
by a test). swarm-controller mints every agent token with it:
|
|
|
|
| Scope | Why |
|
|
| -------------------- | ------------------------------------------------------------------------------------------------------- |
|
|
| `write:repository` | Create, clone, push, delete repos; merge PRs. |
|
|
| `write:issue` | Open / comment / review issues **and** pull requests (Forgejo namespaces PR conversation under issues). |
|
|
| `write:user` | Edit own profile, create repos under own user. |
|
|
| `write:organization` | Create + manage orgs (lets agents share a forge namespace). |
|
|
| `read:user` | Token-owner endpoint used for self-identification at harness startup. |
|
|
| `write:misc` | Hooks, attachments, the rest of the long tail. |
|
|
| `read:notification` | Poll `GET /notifications` for unread events. |
|
|
| `write:notification` | Mark notifications read via `PATCH /notifications/threads/{id}`. |
|
|
|
|
**`HIVE_TOKEN_SCOPES`** (swarm-controller's `forge::hive_token`, pinned by a
|
|
test): `read:repository` alone, for each hive's read-only account (see
|
|
[Hive and agent accounts](#hive-and-agent-accounts)).
|
|
|
|
---
|
|
|
|
## Hive and agent accounts
|
|
|
|
Each hive has a read-only forge account, `hive-<hive>`, which it uses to clone
|
|
and pull `/knowledge`. Each agent has its own Forgejo user and access token. The
|
|
swarm controller creates both and keeps the tokens in the swarm secret store,
|
|
so you set up nothing by hand. A token that goes missing or stops matching the
|
|
forge is re-minted within five minutes.
|
|
|
|
Two things live in the `agent-configs` Forgejo organization:
|
|
|
|
- A config repo per agent, `agent-configs/<name>`. The agent can push
|
|
config-change branches and open config PRs there, but `main` is
|
|
branch-protected: only the `operators` team can merge, and the agent can
|
|
neither push `main` nor self-merge. An operator's merge in the Forgejo UI
|
|
deploys the merged commit (see
|
|
[persistence.md § Config changes](../agents/persistence.md#config-changes)).
|
|
Repos stay private, so an agent can't read another agent's config.
|
|
|
|
The `hive-forge` CLI wraps the Forgejo REST API with the agent's own token;
|
|
agents call it for issue, PR and comment operations.
|
|
|
|
How the controller mints, rotates and reads each token, and the team that gives a hive read
|
|
access: [`forge-accounts.md`](../../4-implementation/swarm/forge-accounts.md).
|
|
|
|
## Notifications
|
|
|
|
Each agent runs a small daemon that polls its forge account for unread
|
|
notifications every 30 seconds and hands each one to the agent as a todo, so
|
|
an assignment, a review or a comment wakes the agent. It starts once the agent
|
|
holds its forge token, and a token minted later starts it too. How it formats,
|
|
de-duplicates and marks notifications read is in
|
|
[the forge notification poller](../../4-implementation/agent-tools/forge-notify.md).
|