Watch
0
0
Fork
You've already forked hyperhive
0
hyperhive/hive-agent-sock/README.md

51 lines
2.5 KiB
Markdown

# hive-agent-sock
What's common across the in-container "agent plugins" — the matrix / bash /
subagent MCP daemons and `forge_notify` today, plus any user-configured MCP
server declared in an agent's `agent.nix`. Three things live here:
## Wire types for the in-agent socket
The socket the `hive-agent` harness serves _inside_ the container to those
local producers. Any producer can dial it and push its own todos with an
arbitrary `subsystem` marker — the wire format doesn't restrict the set.
Unlike the host-served sockets, this one **never leaves the container**.
- the loose-ends-v2 **todo** op family
- the harness-local **reminder** op family
More in-agent request families may show up over time — the socket is
deliberately named for the agent, not for the todos.
**Why in-container**: the harness owns the todo + reminder stores locally and
signals its own turn loop directly, so `hive-c0re` isn't in either path: no
broker round-trip, no long-poll, no marker files. That locality is the
point — it's also what lets these stores travel with the agent for hive
portability.
**Don't confuse this with `hive-core-agent-sock`**: that crate is the
_host_-served core↔agent protocol on `/run/hive/mcp.sock` (the harness
talking out to `hive-c0re`). This socket is purely intra-container.
## `extra_mcp`: the `services.hyperhive.agent.extraMcpServers` spec
Not a socket protocol — a shared config type. Parses
`/etc/hyperhive/extra-mcp.json` (the nix-rendered
`services.hyperhive.agent.extraMcpServers` option) and renders each
entry into the shape claude expects in a
`--mcp-config` blob. Shared by `hive-agent` (the main session's servers) and
`hive-subagent-mcp` (the subagent-eligible subset, gated on
`availableToSubagents`) — both already depend on this crate for the socket
types above, so a new plugin-facing shared type belongs here rather than in
a crate of its own.
## `run_cgroup`: one cgroup per run
`hive-bash-mcp` puts each bash task in `<unit>/tasks/<id>/` and
`hive-subagent-mcp` each subagent run in `<unit>/runs/<name>-<n>/`, both with
`memory.oom.group=1`, so the OOM killer takes one whole run and leaves the
daemon alone. A subagent run's cgroup is also killed (`cgroup.kill`) if
processes are still in it 30 seconds after the run ended; a bash task's is
left alone. Both daemons are delegated their cgroup with `Delegate=memory
pids` and `DelegateSubgroup=daemon` (`nix/agent-modules/mcp.nix`); outside such
a unit the module logs one warning and runs stay in the daemon's cgroup.