c74249f371
`matrixAccounts` is meant to be the agent's full account list, but the hive-internal `main` account was outside it: the nix module emitted only the extras and `hive-matrix-daemon` prepended a `main` it synthesized from the per-agent paths, with the option schema forbidding the name outright. nix/agent-modules/matrix.nix now declares `main` itself, as an ordinary entry under `matrix.enable`, from the state-dir paths the module already used for its token path-watcher (now a shared `stateDir` binding) plus `matrix.url`. The whole set, `main` included, is serialized to HIVE_MATRIX_ACCOUNTS. accounts::configured therefore synthesizes `main` only when the parsed list carries none, and otherwise takes the declared one verbatim — hoisting it to index 0, since the daemon reads index 0 as the primary and nix serializes an attrset, so `main` sorts wherever its key falls. Declared xor synthesized: an agent whose harness predates this entry keeps working, a current one gets its own, and there is no arrangement where `main` is duplicated or missing. The reserved-name assertion is replaced rather than dropped: the name must now be legal (the module uses it), but `main`'s tokenFile stays pinned to `<state>/matrix-token`, since hive-c0re provisions the hive-internal token there and nowhere else — a retarget would evaluate fine and then never restore. The other two fields are mkDefault and free to override. Refs #4475
368 lines
18 KiB
Nix
368 lines
18 KiB
Nix
# Per-agent matrix integration: the `services.hyperhive.agent.matrix.*` +
|
|
# `services.hyperhive.agent.matrixAccounts` options, the long-running
|
|
# hive-matrix-daemon (serves its MCP tools directly over
|
|
# streamable-http), its token-arrival path trigger, and the
|
|
# auto-injected extraMcpServers entry.
|
|
{
|
|
pkgs,
|
|
lib,
|
|
config,
|
|
...
|
|
}:
|
|
let
|
|
userName = config.services.hyperhive.agent.user.name;
|
|
# This agent's own state dir, where hive-c0re provisions the
|
|
# hive-internal account's token (`matrix-token`) and the daemon keeps
|
|
# its matrix-sdk store. Shared by the `main` account entry below and
|
|
# the path-watcher glob at the bottom of this file.
|
|
stateDir = "/agents/${userName}/state";
|
|
# Rasterize the operator-set agent icon (`services.hyperhive.agent.icon`, an SVG) to a
|
|
# 512x512 PNG so the matrix daemon can upload it as each account's avatar
|
|
# over the live authenticated Client (see hive-matrix-mcp::client::sync_avatar).
|
|
# Only forced when an icon is configured — the `HIVE_ICON_PNG` daemon-env
|
|
# entry is gated on `services.hyperhive.agent.icon != null`, so this binding stays lazy
|
|
# when no icon is set.
|
|
iconPng = pkgs.runCommand "hive-agent-icon.png" { nativeBuildInputs = [ pkgs.librsvg ]; } ''
|
|
rsvg-convert -f png -w 512 -h 512 ${config.services.hyperhive.agent.icon} -o $out
|
|
'';
|
|
in
|
|
{
|
|
options.services.hyperhive.agent.matrix.enable = lib.mkOption {
|
|
type = lib.types.bool;
|
|
default = true;
|
|
description = ''
|
|
Enable per-agent matrix integration via `hive-matrix-daemon`.
|
|
When true (the default), the harness:
|
|
|
|
- runs `hive-matrix-daemon` as a systemd unit that holds a
|
|
matrix-sdk Client + sync against the homeserver named by
|
|
`HIVE_MATRIX_URL` (see `services.hyperhive.agent.matrix.url` — there is no
|
|
default, since an agent's own netns makes a loopback guess
|
|
wrong). The daemon auto-skips when that URL or
|
|
`<state>/matrix-token` is missing, and a `systemd.paths`
|
|
watcher restarts it the moment hive-c0re provisions the token
|
|
(same path-trigger shape as `forge-avatar-sync`).
|
|
- exposes the matrix tool surface (send_message, send_dm,
|
|
send_reaction, send_reply, mark_read, list_rooms,
|
|
list_room_members, read_room) to claude via an auto-injected
|
|
`extraMcpServers.matrix` entry pointed at the daemon's own
|
|
streamable-http listener (`services.hyperhive.agent.mcp.matrixHttpPort`) — no
|
|
stdio bridge, no per-turn respawn, same shape as the built-in
|
|
hyperhive surface and `hive-bash-daemon`.
|
|
- wakes the agent on incoming room events via a short teaser
|
|
Wake signal (`[matrix] <sender> in <room>: <first 100c>…`)
|
|
to the hyperhive control socket; the full event stays
|
|
unread server-side until `read_room` consumes it.
|
|
|
|
Set to `false` for agents that should NOT have matrix tools at
|
|
all (e.g. agents on a host without `services.hyperhive.agent.matrix.enable` on
|
|
the meta side). When token file is absent the daemon and MCP
|
|
both no-op cleanly anyway, so `false` is rarely necessary.
|
|
'';
|
|
};
|
|
|
|
options.services.hyperhive.agent.matrix.url = lib.mkOption {
|
|
type = lib.types.nullOr lib.types.str;
|
|
default = null;
|
|
example = "https://matrix.darkest.space";
|
|
description = ''
|
|
Matrix homeserver URL the agent's `hive-matrix-daemon` connects
|
|
to. hive-c0re writes this per agent from the hive's own
|
|
isolation-aware URL (`gatewayHost`'s vhost via the gateway,
|
|
`chat.<swarm-domain>` by default), so a
|
|
generated agent config always carries a real value; set it by
|
|
hand only when an agent should talk to an external homeserver
|
|
instead (a federation-only setup, or a remote hive's tuwunel
|
|
reached over a vpn).
|
|
|
|
**`null` means "no matrix", not "guess one".** There is
|
|
deliberately no loopback default: the homeserver may run on a
|
|
different host from the agents, and inside an agent's network
|
|
namespace `localhost` reaches the agent rather than the
|
|
homeserver, so a default would be a value that builds fine and
|
|
then talks to the wrong machine. When this is `null` the daemon
|
|
is left without a homeserver and no-ops, exactly as it does when
|
|
the token file is absent --- an absent integration, never a
|
|
misdirected one.
|
|
'';
|
|
};
|
|
|
|
options.services.hyperhive.agent.matrixAccounts = lib.mkOption {
|
|
type = lib.types.attrsOf (
|
|
lib.types.submodule {
|
|
options = {
|
|
tokenFile = lib.mkOption {
|
|
type = lib.types.str;
|
|
example = "/agents/dmatrix/state/matrix-token-ccc";
|
|
description = ''
|
|
Path to this account's bearer-token file. The daemon reads
|
|
the token from here to restore the matrix session; how the
|
|
file gets populated is the provisioner's concern
|
|
(hive-c0re for the hive-internal `main` account, an
|
|
operator-supplied secret for an external one). The daemon
|
|
skips an extra account whose token file is absent, and
|
|
exits cleanly to wait on the path watcher when `main`'s is.
|
|
'';
|
|
};
|
|
sessionDir = lib.mkOption {
|
|
type = lib.types.str;
|
|
example = "/agents/dmatrix/state/matrix-sdk-state-ccc";
|
|
description = ''
|
|
Per-account matrix-sdk sqlite store directory (crypto keys
|
|
+ event cache). Must differ between accounts so their
|
|
sessions do not collide.
|
|
'';
|
|
};
|
|
homeserver = lib.mkOption {
|
|
type = lib.types.nullOr lib.types.str;
|
|
default = null;
|
|
example = "https://matrix.example.org";
|
|
description = ''
|
|
Homeserver URL for this account. When null (the default),
|
|
the account falls back to `services.hyperhive.agent.matrix.url`. Set it for
|
|
an account on a different homeserver than the agent's
|
|
default (e.g. an external public-matrix account).
|
|
'';
|
|
};
|
|
};
|
|
}
|
|
);
|
|
default = { };
|
|
example = lib.literalExpression ''
|
|
{
|
|
ccc = {
|
|
tokenFile = "/agents/dmatrix/state/matrix-token-ccc";
|
|
sessionDir = "/agents/dmatrix/state/matrix-sdk-state-ccc";
|
|
homeserver = "https://matrix.example.org";
|
|
};
|
|
}
|
|
'';
|
|
description = ''
|
|
Every matrix account served by the single `hive-matrix-daemon`
|
|
(one matrix-sdk Client + sync loop each). The attribute name keys
|
|
each account (unique by construction) and is the handle the matrix
|
|
MCP tools target via their `account` argument.
|
|
|
|
The **hive-internal account is always present and is the primary**:
|
|
it is named `main`, and this module declares it for you (when
|
|
`services.hyperhive.agent.matrix.enable` is set) from
|
|
`services.hyperhive.agent.matrix.url` + `<state>/matrix-token` +
|
|
`<state>/matrix-sdk-state`. It is the account a tool call acts as
|
|
when it omits `account`. It is an ordinary entry of this option
|
|
like any other, so it shows up in the account list --- what you
|
|
add here are the *further* accounts (e.g. an external
|
|
public-matrix account). Its `tokenFile` stays pinned to
|
|
`<state>/matrix-token` (an assertion; that is the one path
|
|
hive-c0re provisions the hive-internal token to), and the
|
|
dashboard's link-account route refuses to create an account named
|
|
`main` --- the entry belongs to the module, not to a provisioner.
|
|
|
|
Leave it alone (the default) for the common single-account case:
|
|
the agent then has only `main`. The whole set is serialized to the
|
|
daemon's `HIVE_MATRIX_ACCOUNTS` environment variable, `main`
|
|
first. Declaring extras requires
|
|
`services.hyperhive.agent.matrix.enable` (there is no `main` to extend otherwise).
|
|
'';
|
|
};
|
|
|
|
options.services.hyperhive.agent.mcp.matrixHttpPort = lib.mkOption {
|
|
type = lib.types.port;
|
|
default = 8792;
|
|
example = 8793;
|
|
description = ''
|
|
Loopback port `hive-matrix-daemon` serves its MCP tools
|
|
(`send_message`, `list_rooms`, `read_room`, …) on. Same shape as
|
|
`services.hyperhive.agent.mcp.bashHttpPort`: HTTP is the *sole* transport (no
|
|
stdio bridge — the daemon that owns the matrix-sdk `Client`
|
|
registry serves the MCP tools directly in-process),
|
|
`Restart = "always"` keeps the listener self-healing, and
|
|
loopback-only binding means no auth token is needed (same
|
|
`allowed_hosts` reasoning as `services.hyperhive.agent.mcp.httpPort`). Safe as a
|
|
single fixed default across all agents (private per-container
|
|
network namespace — see docs/networking/network.md).
|
|
'';
|
|
};
|
|
|
|
config = {
|
|
assertions = [
|
|
# Extra matrix accounts only make sense alongside the hive-internal
|
|
# `main` account they extend, which exists only when matrix is
|
|
# enabled.
|
|
{
|
|
assertion =
|
|
config.services.hyperhive.agent.matrixAccounts == { }
|
|
|| config.services.hyperhive.agent.matrix.enable;
|
|
message =
|
|
"services.hyperhive.agent.matrixAccounts requires services.hyperhive.agent.matrix.enable = true "
|
|
+ "(the extras extend the hive-internal `main` account, which only "
|
|
+ "exists when matrix is enabled).";
|
|
}
|
|
# `main` is no longer a forbidden key --- this module declares it
|
|
# itself (see the `matrixAccounts.main` definition below), so the
|
|
# name must be allowed. What stays rejected is retargeting *its
|
|
# token file*: hive-c0re writes the hive-internal account's token
|
|
# to `<state>/matrix-token` and nowhere else, so an override there
|
|
# is an account that evaluates fine and then never restores. The
|
|
# other two fields are free to override (a `mkDefault` each).
|
|
{
|
|
assertion =
|
|
!config.services.hyperhive.agent.matrix.enable
|
|
|| config.services.hyperhive.agent.matrixAccounts.main.tokenFile == "${stateDir}/matrix-token";
|
|
message =
|
|
"services.hyperhive.agent.matrixAccounts.main.tokenFile must stay "
|
|
+ "\"${stateDir}/matrix-token\" --- that is where hive-c0re provisions the "
|
|
+ "hive-internal account's token. Declare a separate account instead of "
|
|
+ "pointing `main` elsewhere.";
|
|
}
|
|
# Token files must land at the `matrix-token*` name the daemon
|
|
# path-watcher globs (`matrix-token*` inside this agent's own state
|
|
# dir), or the account never gets picked up live (it loads only on a
|
|
# full daemon restart).
|
|
# Enforce the basename prefix so a deviating name (e.g.
|
|
# `matrix-catgirl-token`) is caught at build time, not silently.
|
|
{
|
|
assertion = lib.all (a: lib.hasPrefix "matrix-token" (baseNameOf a.tokenFile)) (
|
|
lib.attrValues config.services.hyperhive.agent.matrixAccounts
|
|
);
|
|
message =
|
|
"every services.hyperhive.agent.matrixAccounts.<name>.tokenFile basename must start with "
|
|
+ "\"matrix-token\" so the daemon path-watcher glob "
|
|
+ "(matrix-token* in the agent's state dir) picks it up live. Offending: "
|
|
+ lib.concatStringsSep ", " (
|
|
lib.mapAttrsToList (n: a: "${n}=${baseNameOf a.tokenFile}") (
|
|
lib.filterAttrs (
|
|
_n: a: !lib.hasPrefix "matrix-token" (baseNameOf a.tokenFile)
|
|
) config.services.hyperhive.agent.matrixAccounts
|
|
)
|
|
)
|
|
+ ".";
|
|
}
|
|
];
|
|
|
|
# The hive-internal account as an ordinary `matrixAccounts` entry,
|
|
# rather than something the daemon conjures behind the option's
|
|
# back: `matrixAccounts` is the list of *all* this agent's accounts,
|
|
# so the one it always has belongs in it. `mkDefault` per field so an
|
|
# operator can retarget e.g. the homeserver without a
|
|
# conflicting-definition error (the token file is pinned by an
|
|
# assertion above, since hive-c0re owns that path).
|
|
services.hyperhive.agent.matrixAccounts = lib.mkIf config.services.hyperhive.agent.matrix.enable {
|
|
main = {
|
|
tokenFile = lib.mkDefault "${stateDir}/matrix-token";
|
|
sessionDir = lib.mkDefault "${stateDir}/matrix-sdk-state";
|
|
homeserver = lib.mkDefault config.services.hyperhive.agent.matrix.url;
|
|
};
|
|
};
|
|
|
|
# Auto-inject the matrix MCP entry alongside the bash entry from
|
|
# ./mcp.nix. `lib.mkDefault` so the operator's own agent.nix can
|
|
# override it. Points at the daemon's own persistent
|
|
# streamable-http listener — no stdio bridge, no per-turn spawn.
|
|
services.hyperhive.agent.extraMcpServers = lib.mkIf config.services.hyperhive.agent.matrix.enable {
|
|
matrix = lib.mkDefault {
|
|
type = "http";
|
|
url = "http://127.0.0.1:${toString config.services.hyperhive.agent.mcp.matrixHttpPort}/mcp";
|
|
allowedTools = [ "*" ];
|
|
};
|
|
};
|
|
|
|
# Long-running matrix-sdk client + sync per agent. Serves the MCP
|
|
# tools directly over streamable-http + emits hyperhive wake
|
|
# signals on incoming room events via `/run/hive/mcp.sock`. See
|
|
# `docs/agent-lifecycle/persistence.md::Matrix per-agent daemon + token-arrival
|
|
# trigger` for the first-boot-ordering rationale.
|
|
systemd.services.hive-matrix-daemon = lib.mkIf config.services.hyperhive.agent.matrix.enable {
|
|
description = "long-running matrix-sdk Client + MCP daemon";
|
|
wantedBy = [ "multi-user.target" ];
|
|
before = [ "hive-agent.service" ];
|
|
after = [ "network-online.target" ];
|
|
wants = [ "network-online.target" ];
|
|
environment = {
|
|
# In-agent todo socket the harness serves (loose-ends v2): the
|
|
# matrix sweep pushes unread-room + pending-invite todos here
|
|
# instead of firing wakes at hive-c0re's mcp.sock.
|
|
HIVE_AGENT_SOCKET = "/run/hive-agent/${userName}/agent.sock";
|
|
RUST_LOG = "info";
|
|
}
|
|
# Homeserver URL. hive-c0re writes this option per agent from the
|
|
# hive's own gateway URL (`gatewayHost`'s vhost, `chat.<swarm-domain>`
|
|
# by default — agents run in a private
|
|
# netns and cannot reach host loopback), so on a real hive it is
|
|
# always set; `null` is the honest "this agent has no homeserver"
|
|
# and leaves the daemon without one, which it treats like a missing
|
|
# token and no-ops. Nothing here falls back to loopback: that would
|
|
# be a value that evaluates fine and then addresses the agent's own
|
|
# netns instead of the homeserver.
|
|
// lib.optionalAttrs (config.services.hyperhive.agent.matrix.url != null) {
|
|
HIVE_MATRIX_URL = config.services.hyperhive.agent.matrix.url;
|
|
}
|
|
# Serialize the whole account set --- `main` included --- to the
|
|
# JSON the daemon parses (`accounts::configured`). Each entry is in
|
|
# the daemon's `AccountCfg` serde shape: name (the attr key) /
|
|
# token_file / state_dir / optional homeserver. The daemon hoists
|
|
# `main` to primary wherever the attr key sorted, and falls back to
|
|
# synthesizing it from the per-agent paths only when this JSON
|
|
# carries no `main` --- which is how an agent whose harness
|
|
# predates this entry keeps working.
|
|
// lib.optionalAttrs (config.services.hyperhive.agent.matrixAccounts != { }) {
|
|
HIVE_MATRIX_ACCOUNTS = builtins.toJSON (
|
|
lib.mapAttrsToList (
|
|
name: a:
|
|
{
|
|
inherit name;
|
|
token_file = a.tokenFile;
|
|
state_dir = a.sessionDir;
|
|
}
|
|
// lib.optionalAttrs (a.homeserver != null) { inherit (a) homeserver; }
|
|
) config.services.hyperhive.agent.matrixAccounts
|
|
);
|
|
}
|
|
# Rasterized agent icon path for the daemon's avatar sync. Only set
|
|
# when an icon is configured; absent → the daemon skips avatar setting
|
|
# (hive-matrix-mcp::client::sync_avatar returns early on unset env).
|
|
// lib.optionalAttrs (config.services.hyperhive.agent.icon != null) {
|
|
HIVE_ICON_PNG = "${iconPng}";
|
|
};
|
|
serviceConfig = {
|
|
ExecStart = "${config.services.hyperhive.agent.packages.hive-matrix-daemon}/bin/hive-matrix-daemon --http 127.0.0.1:${toString config.services.hyperhive.agent.mcp.matrixHttpPort}";
|
|
SyslogIdentifier = "hive-matrix-daemon";
|
|
# `on-failure`, not `always`: the daemon deliberately exits 0
|
|
# (a clean, non-failure exit) when no token is provisioned yet
|
|
# (see the module doc above) — the `systemd.paths` watcher
|
|
# below re-fires it the moment hive-c0re provisions one,
|
|
# instead of `always` busy-looping every `RestartSec` until
|
|
# then. Once a token exists this is no different from
|
|
# `hive-bash-daemon`'s reasoning (a down window loses the MCP
|
|
# tools with no stdio fallback) — a genuine crash is a
|
|
# non-zero exit, which `on-failure` already restarts.
|
|
Restart = "on-failure";
|
|
RestartSec = 5;
|
|
User = userName;
|
|
Group = userName;
|
|
};
|
|
};
|
|
|
|
# Re-fire the daemon when the matrix token appears (hive-c0re
|
|
# provisions it after agent containers come up). Without this
|
|
# the daemon would exit 0 silently on first boot and the MCP
|
|
# would have no backend until next restart. See
|
|
# `docs/agent-lifecycle/persistence.md` (same section as above).
|
|
systemd.paths.hive-matrix-daemon = lib.mkIf config.services.hyperhive.agent.matrix.enable {
|
|
description = "trigger hive-matrix-daemon when a matrix token appears";
|
|
wantedBy = [ "multi-user.target" ];
|
|
# `matrix-token*` (not just `matrix-token`) so a secondary
|
|
# multi-account token (e.g. `matrix-token-ccc`) landing also
|
|
# re-fires the daemon to pick up the freshly-provisioned account.
|
|
#
|
|
# ⚠️ This agent's own state dir, not a glob over `/agents/*/`. Every
|
|
# agent's state dir is visible from inside every container, so a
|
|
# wildcard is satisfied by a sibling's token — and this daemon exits 0
|
|
# when it has no token of its own (see `Restart = "on-failure"`
|
|
# above), so the unit deactivates, the path unit re-arms, the
|
|
# sibling's token still matches, and it fires again until the start
|
|
# limit stops it. Scoped to this agent, the condition is false exactly
|
|
# when the daemon would have nothing to do.
|
|
pathConfig.PathExistsGlob = "${stateDir}/matrix-token*";
|
|
};
|
|
};
|
|
}
|