vinzenz/hyperhive
vinzenz/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 2

matrix: drop the per-agent matrix.enable; accounts are the enable signal

Browse source 
`services.hyperhive.agent.matrix.enable` was a second source of truth for
a fact the account set already carried: after ①-③ the hive-internal
`main` account is an ordinary `matrixAccounts` entry, so "does this agent
have matrix" and "does this agent have an account" were the same question
asked twice, with the boolean able to disagree.

The option is gone and a non-empty `matrixAccounts` now gates the daemon
unit, its token path-watcher and the injected `extraMcpServers.matrix`
entry.

That is only a real condition because `matrixAccounts.main` is itself
gated: it is declared when `matrix.url != null`, never unconditionally. A
`main` with no homeserver is an account the daemon can never log in as,
so declaring one always would have made the signal trivially true and
turned matrix on for every agent in every hive. With the URL gate, the
empty set is reachable exactly for an agent the hive gave no homeserver
and whose operator declared no account of its own — the state the old
`enable = false` expressed.

Assertions: "extras require enable" is deleted, having become the
definition of the thing it checked (an external-only account with its own
homeserver is now rendered rather than rejected). `main.tokenFile` stays
pinned, re-guarded on `? main` instead of on the flag, since `main` is
absent whenever the URL is null and an unguarded index would throw there.

Both spellings of the option get `mkRemovedOptionModule`, following
../host-modules/deploy.nix's registrationTokenFile pair rather than a
silent delete: the definition whose meaning changes is `false`, and left
undeclared it would be ignored and hand the agent the tools its operator
turned off. Failing the eval with the replacement spelling is the only
outcome that cannot.

module-eval gains the three arms — URL, nothing, external-only — with the
middle one carrying why it exists: it is the only thing in the suite that
would notice `main` becoming unconditional again.

Refs #4475
This commit is contained in:
atlas 2026-09-18 09:42:23 +02:00
commit 99b141f5f2
7 changed files with 254 additions and 92 deletions
Download patch file Download diff file Expand all files Collapse all files

12
docs/agent-lifecycle/persistence.md
View file

@ -546,9 +546,15 @@ the body + marker check at that point.
process per agent. Serves its MCP tools directly over
streamable-http (`services.hyperhive.agent.mcp.matrixHttpPort`, no stdio bridge —
same shape as `hive-bash-daemon`), emits hyperhive wake signals
on incoming room events via `/run/hive/mcp.sock`. Conditional on
`services.hyperhive.agent.matrix.enable` (which both the daemon AND the
autoinjected `extraMcpServers.matrix` entry read).
on incoming room events via `/run/hive/mcp.sock`. Conditional on the
agent having at least one `services.hyperhive.agent.matrixAccounts`
entry — there is no separate enable switch, and the same condition gates
the daemon, its path watcher AND the autoinjected
`extraMcpServers.matrix` entry. The module declares the hive-internal
`main` entry whenever `services.hyperhive.agent.matrix.url` is non-null,
so on a real hive (where hive-c0re renders that URL per agent) every
agent has one; a `null` URL with no operator-declared account is the
"this agent has no matrix" state.
**First-boot ordering**: hive-c0re provisions the matrix token AFTER
agent containers come up. Without the path-trigger sibling

26
docs/tools/matrix.md
View file

@ -2,10 +2,14 @@
## Built-in matrix MCP (`mcp__matrix__*`)
When `services.hyperhive.agent.matrix.enable = true` and the host-level matrix
tuwunel is configured, the harness autoinjects `hive-matrix-daemon`'s
When the agent has at least one `services.hyperhive.agent.matrixAccounts`
entry, the harness autoinjects `hive-matrix-daemon`'s
streamable-http endpoint as a second MCP server (no stdio bridge —
see Architecture below). Tools land as `mcp__matrix__<name>`:
see Architecture below). There is no `matrix.enable` switch: the account
set *is* the switch, and the module declares the hive-internal `main`
account for you as soon as `services.hyperhive.agent.matrix.url` is
non-null — which hive-c0re fills in per agent whenever the host-level
matrix tuwunel is configured. Tools land as `mcp__matrix__<name>`:
### Messaging
@ -71,7 +75,8 @@ room you haven't read yet.
`services.hyperhive.agent.matrixAccounts` (declared in `agent.nix`) is
the agent's full set of matrix identities — for example an
external-facing account alongside the internal one. Each entry is
external-facing account alongside the internal one — **and, being
non-empty, is what turns matrix on for the agent at all.** Each entry is
keyed by account name and specifies `tokenFile` (bearer token,
provisioned out-of-band; basename must start with `matrix-token`),
`sessionDir` (per-account matrix-sdk sqlite state — crypto keys +
@ -83,8 +88,17 @@ declares it for you as an ordinary entry of this map, from
here are the *further* accounts. Its `tokenFile` is pinned to
`<state>/matrix-token` (hive-c0re provisions it there), and the
dashboard's link-account route refuses to create an account by that
name. Declaring extras requires
`services.hyperhive.agent.matrix.enable = true`.
name.
`main` is present exactly when that URL is non-null, which is the whole
mechanism behind "accounts are the enable signal": an agent with no
homeserver and no account of its own has an empty set, so it gets no
daemon, no path watcher and no injected MCP entry. That is how you give
an agent no matrix tools — it replaces the removed
`services.hyperhive.agent.matrix.enable = false`, which now fails
evaluation with a message saying so. Declaring an external account with
its own `homeserver` is enough on its own; a hive homeserver is not
required.
Every matrix tool above takes an optional `account` parameter (a name
from this map) to act as that identity instead of the primary one.