From f500863f2f03673dc471396fae03da4e1d3e89f7 Mon Sep 17 00:00:00 2001 From: iris Date: Sat, 15 Aug 2026 11:51:22 +0200 Subject: [PATCH] docs(turn-loop): fix crate-count claim, trim historical framing --- docs/turn-loop/README.md | 36 ++++++++++++++---------------------- 1 file changed, 14 insertions(+), 22 deletions(-) diff --git a/docs/turn-loop/README.md b/docs/turn-loop/README.md index ee382050..71baa55c 100644 --- a/docs/turn-loop/README.md +++ b/docs/turn-loop/README.md @@ -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::` 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