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

docs(turn-loop): fix crate-count claim, trim historical framing

Browse source
This commit is contained in:
iris 2026-08-15 11:51:22 +02:00 • committed by mara
commit f500863f2f
1 changed files with 14 additions and 22 deletions
Download patch file Download diff file Expand all files Collapse all files

36
docs/turn-loop/README.md
View file

@ -65,11 +65,10 @@ agents) runs:
## Harness binary shape
Two sibling binaries out of the one `hive-ag3nt` crate, all
role-agnostic. (The earlier split into `hive-ag3nt` + `hive-m1nd`
was collapsed because the privilege boundary lives server-side at
the broker socket (`/run/hive/mcp.sock`): `ManagerRequest` calls are
refused by the standard agent socket regardless of who sends them.)
Two sibling crates, both role-agnostic (there is one role: agent —
the privilege boundary lives server-side at the broker socket
(`/run/hive/mcp.sock`), which refuses `ManagerRequest` calls regardless
of who sends them):
- `hive-agent` — long-running harness loop (the inbox poll +
claude-pump + ack/requeue cycle described above).
@ -80,18 +79,11 @@ refused by the standard agent socket regardless of who sends them.)
transport — no per-turn stdio child (eliminates the re-registration
race).
### `Surface` trait + zero-sized type tags
`AgentRequest` / `AgentResponse` (= `ManagerRequest` / `ManagerResponse` —
type aliases) are the wire types. There is one role: agent.
`bin/hive-agent.rs` factors the turn loop through a `Surface` trait
with one zero-sized impl (`AgentSurface`) wrapping:
- One async method per wire op: `ack_turn`, `requeue_inflight`,
`inbox_unread`, `post_turn_counts`, `send_to_parent`, `recv_next`.
`main()` calls `serve_main::<AgentSurface>` for all roles. The turn
loop (`serve_loop` / `handle_turn`) has no per-role branches.
`hive-agent`'s wire types (`AgentRequest` / `AgentResponse`, aliased as
`ManagerRequest` / `ManagerResponse`) and its turn loop are factored
through a small `Surface` trait with one zero-sized impl, so the loop
itself has no per-role branches. See `hive-agent/src/main.rs`'s module
doc for the trait shape.
### Boot wiring
@ -103,12 +95,12 @@ opens turn-stats sqlite, prepares the on-boot files (see
[claude-invocation](claude-invocation.md#on-boot-files)),
installs claude plugins, spawns `web_ui::serve` + `vacuum::run`,
and either drops into `serve_loop` directly (`Online`) or parks on
the login flow first (`NeedsLogin`). (The forge notification poller
used to be spawned here too; it is its own process now —
`hive-forge-notify`, see [`forge.md`](../forge.md).)
the login flow first (`NeedsLogin`). Forge notifications are polled by
their own process, not this loop — see `hive-forge-notify` in
[`forge.md`](../forge.md).
`spawn_todo_socket` opens the todos store and the socket the in-container
producers dial. Matrix / bash / forge-notify daemons and the in-process
Boot also opens the todos store and the socket in-container producers
dial. Matrix / bash / forge-notify daemons and the in-process
`disk_watch` todo producer (low state-disk space) are the built-in
producers, but the socket accepts any `subsystem` marker — a
user-configured MCP server can push its own todos the same way. See