# 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).