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

docs: repoint agent-tier option paths to services.hyperhive.agent.*

Browse source 
Refs #4479
This commit is contained in:
atlas 2026-09-18 00:55:51 +02:00 • committed by mara
commit 7570597190
18 changed files with 78 additions and 78 deletions
Download patch file Download diff file Expand all files Collapse all files

6
docs/tools/bash.md
View file

@ -2,7 +2,7 @@
Background shell execution via `hive-bash-daemon`. Tools land as
`mcp__bash__<tool>` (the MCP server name is `bash`, not `hyperhive`).
`nix/agent-modules/mcp.nix` registers bash into `hyperhive.extraMcpServers`
`nix/agent-modules/mcp.nix` registers bash into `services.hyperhive.agent.extraMcpServers`
by default (`lib.mkDefault`, with `allowedTools = ["*"]`) — an `agent.nix`
can override or drop the entry, so this is a default, not an
unconditional grant. Even where the entry is present, the server is only
@ -101,8 +101,8 @@ this structured path so tasks get task-id tracking and structured output.
container, systemd service in `nix/agent-modules/mcp.nix`) — no stdio
bridge. It owns subprocess management, output file writing, todo delivery
on the harness's in-agent socket, **and** serves the `run`/`status`/`kill`
MCP tools directly over streamable-http on `hyperhive.mcp.bashHttpPort`
(declared in `hyperhive.extraMcpServers.bash` as `{ type = "http"; url =
MCP tools directly over streamable-http on `services.hyperhive.agent.mcp.bashHttpPort`
(declared in `services.hyperhive.agent.extraMcpServers.bash` as `{ type = "http"; url =
...; }`). Same shape as the built-in `hyperhive` surface (`hive-mcp-http`)
— claude reconnects to the stable URL every turn instead of respawning a
stdio child, so there's no per-turn MCP re-registration race and no

2
docs/tools/hivectl.md
View file

@ -97,7 +97,7 @@ agent's token file so its `gh` wrapper + git credential helper can act as
the bot account. Unlike forge/matrix there is no account creation — the PAT
is for an existing GitHub account. A CLI alternative to the dashboard
credentials tab; the [GitHub integration](../integrations/github.md) is on by default
(`hyperhive.github.enable`), so no per-agent config is needed.
(`services.hyperhive.agent.github.enable`), so no per-agent config is needed.
```bash
hivectl github set-token damocles --token-stdin # paste the PAT on stdin (preferred)

18
docs/tools/matrix.md
View file

@ -2,7 +2,7 @@
## Built-in matrix MCP (`mcp__matrix__*`)
When `hyperhive.matrix.enable = true` and the host-level matrix
When `services.hyperhive.agent.matrix.enable = true` and the host-level matrix
tuwunel is configured, 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>`:
@ -69,17 +69,17 @@ room you haven't read yet.
## Multiple accounts
`hyperhive.matrixAccounts` (declared in `agent.nix`) gives an agent
`services.hyperhive.agent.matrixAccounts` (declared in `agent.nix`) gives an agent
*additional* matrix identities beyond the hive-internal one — for example an
external-facing account alongside the internal one. 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 +
cache), and an optional `homeserver` (defaults to
`hyperhive.matrix.url`). The hive-internal account is always named
`main`, synthesized from `hyperhive.matrix.url` + agent state — this
`services.hyperhive.agent.matrix.url`). The hive-internal account is always named
`main`, synthesized from `services.hyperhive.agent.matrix.url` + agent state — this
option only declares extras, and `main` is a reserved key here.
Requires `hyperhive.matrix.enable = true`.
Requires `services.hyperhive.agent.matrix.enable = true`.
Every matrix tool above takes an optional `account` parameter (a name
from this map) to act as that identity instead of the primary one.
@ -94,8 +94,8 @@ bodies and invite todos gain an `[acct:<name>]` prefix — see
container, systemd service in `nix/agent-modules/matrix.nix`) — no
stdio bridge, no separate bin. It owns the matrix-sdk `Client` + sync
loop per configured account **and** serves the matrix tool surface
directly over streamable-http on `hyperhive.mcp.matrixHttpPort`
(declared in `hyperhive.extraMcpServers.matrix` as
directly over streamable-http on `services.hyperhive.agent.mcp.matrixHttpPort`
(declared in `services.hyperhive.agent.extraMcpServers.matrix` as
`{ type = "http"; url = ...; }`). Same shape as `hive-bash-daemon` and
the built-in `hyperhive` surface (`hive-mcp-http`) — claude reconnects
to the stable URL every turn instead of respawning a stdio child.
@ -115,7 +115,7 @@ Incoming room events wake the agent via `AgentRequest::Wake` with
per room)
**Multi-account prefix**: when the daemon serves more than one account
(`hyperhive.matrixAccounts`), it prefixes every wake body and every invite todo
(`services.hyperhive.agent.matrixAccounts`), it prefixes every wake body and every invite todo
below with `[acct:<name>] `, so a wake arrives as
`[acct:ccc] [matrix] <sender> in <room>: …`. A single-account agent gets the
formats exactly as written — the daemon adds nothing — which is why matching
@ -147,7 +147,7 @@ provisioning flow, and federation config.
## Extra MCP servers (per-agent)
Each agent's NixOS config can declare additional MCP servers via
`hyperhive.extraMcpServers.<key> = { type, command, args, env, url,
`services.hyperhive.agent.extraMcpServers.<key> = { type, command, args, env, url,
allowedTools }` — `type = "stdio"` (the default, uses `command`/`args`/
`env`) or `type = "http"` (uses `url`, a long-lived streamable-http
endpoint — see `hive-bash-daemon` and `hive-matrix-daemon` above for

6
docs/tools/subagent.md
View file

@ -8,7 +8,7 @@ capability than a background shell command, so it gets its own
deployable/restartable unit rather than living inside the bash daemon.
Shipped default-on for every agent — `nix/agent-modules/mcp.nix` injects
`subagent` into `hyperhive.extraMcpServers` via `lib.mkDefault`
`subagent` into `services.hyperhive.agent.extraMcpServers` via `lib.mkDefault`
(`allowedTools = ["*"]`), same as `bash`. Default-on rather than
unconditional: an `agent.nix` can override or drop the entry, which is
what `mkDefault` is there for. The operator's own framing: default-on for
@ -210,7 +210,7 @@ assumption stops holding.
## Configuration
`hyperhive.mcp.subagentHttpPort` — the daemon's streamable-http listen
`services.hyperhive.agent.mcp.subagentHttpPort` — the daemon's streamable-http listen
port. Same pattern as `bashHttpPort`/`matrixHttpPort`: a per-agent default
assigned by `nix/agent-modules/mcp.nix`, only worth overriding for an
agent that needs a stable or non-default port.
@ -284,7 +284,7 @@ all, and the automatically injected `bash`/`subagent` entries default to exclude
too (a subagent can't spawn hive-bash tasks or its own nested subagents
unless an operator opts them in explicitly, same as anything else).
Set `hyperhive.extraMcpServers.<name>.availableToSubagents = true` on a
Set `services.hyperhive.agent.extraMcpServers.<name>.availableToSubagents = true` on a
specific entry to hand that one server to subagents as well — useful for,
say, a read-only lookup or scraper MCP a subagent's bounded, single-batch
task might need. `hive-subagent-mcp`'s `mcp_config` module renders the