04b274753b
Part of hyperhive#1898 (b): every docs subdir should have a top-level README.md link, achieved by moving/renaming where an existing file already fits the role. docs/turn-loop.md already served as the hub + index for the three sub-pages under turn-loop/ (claude-invocation.md, config.md, mcp.md), so it moves wholesale rather than leaving a redundant top-level pointer stub. Fixes every inbound/relative link across the repo (top-level README.md, CLAUDE.md, docs/persistence.md, docs/tools/scheduling.md, the sub-pages own back-link, hive-agent README + doc comments, hive-agent/Cargo.toml, .prettierignore per-file exemption entry) - grepped the whole tree for both turn-loop.md and turn-loop/ to find every reference rather than trusting a partial list. nix fmt clean, cargo check -p hive-agent clean.
51 lines
2.4 KiB
Markdown
51 lines
2.4 KiB
Markdown
# hive-agent
|
|
|
|
The in-container harness serve-loop binary — one instance per agent.
|
|
Long-polls the broker inbox and drives one `claude --print` turn per
|
|
inbox message, over the `hive-claude` driver. There is one role here
|
|
(agent); the `Surface` trait + `AgentSurface` zero-sized type tag keep
|
|
the turn loop generic and testable for future roles without a
|
|
parallel copy of the loop.
|
|
|
|
## When to use it
|
|
|
|
You don't call into this crate from elsewhere — it's the top-level
|
|
binary systemd starts per agent container. Look here when you need to
|
|
understand or change: what happens between "a message lands in the
|
|
inbox" and "claude produces a reply", how login/auth is bootstrapped,
|
|
how the per-agent web UI is served, or how turn/event stats get
|
|
recorded. Architecture detail lives in
|
|
[`docs/turn-loop/`](../docs/turn-loop/README.md); this README is just the
|
|
map of the module tree.
|
|
|
|
## Shape
|
|
|
|
- **`turn.rs`** — the turn-loop policy layer: renders the system
|
|
prompt + MCP config, invokes `hive-claude`, classifies the outcome,
|
|
and feeds the event/turn-stats sinks.
|
|
- **`client.rs`** — broker client (inbox poll, ack, send) speaking the
|
|
`hive-sh4re` wire protocol.
|
|
- **`login.rs` / `login_session.rs`** — first-run and session-resume
|
|
auth flow for the `claude` CLI.
|
|
- **`mcp_config.rs`** — renders the per-turn `--mcp-config` /
|
|
`--allowedTools` blob from tool groups + capabilities.
|
|
- **`todos.rs` / `reminders.rs` / `todo_server.rs`** — the harness-local
|
|
loose-ends v2 stores (sqlite-backed) and the in-agent socket server
|
|
extra MCP daemons + `hive-agent-mcp` dial into for todo/reminder ops.
|
|
- **`vacuum.rs`** — periodic sqlite vacuum sweep for the harness-local
|
|
stores.
|
|
- **`events.rs` / `turn_stats.rs` / `stats.rs`** — append-only event
|
|
sink and per-turn telemetry recording (context usage, cost, tool
|
|
favorites) under `harness/`.
|
|
- **`forge_notify.rs`** — subscribes to forge notifications and wakes
|
|
the harness on new activity.
|
|
- **`prompt.rs`** — system-prompt renderer (persona + tool docs +
|
|
environment facts).
|
|
- **`web_ui/`** — the per-agent dashboard (terminal pane, status,
|
|
schedules) served over the built-in `hive-agent` web port.
|
|
- **`paths.rs`** — canonical path resolution for state/harness dirs and
|
|
the harness-local sqlite files.
|
|
|
|
Sibling: **`hive-agent-mcp`** (the MCP server this loop points claude
|
|
at every turn). Both are described together in
|
|
[`docs/turn-loop/::Harness binary shape`](../docs/turn-loop/README.md).
|