# hive-agent

The in-container harness serve-loop binary — one instance per agent.
Long-polls the broker inbox and drives one turn per inbox message
through `hive-runtime`, on the agent's runtime (`claude --print` by
default, or an ACP agent). It has one role
(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 landing in the
inbox and the agent's reply, how the harness bootstraps login/auth,
how it serves the per-agent web UI, 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

- **`main.rs`** — the serve loop and the `Surface` trait; broker calls
  (inbox poll, ack, send) go through `hive-sock-client` with
  `hive-core-agent-sock` wire types.
- **`turn.rs`** — the turn-loop policy layer: renders the system
  prompt + MCP config, runs the turn through `hive-runtime`, classifies
  the outcome, and feeds the event/turn-stats sinks.
- **`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/`.
- **`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.

Siblings: **`hive-agent-mcp`** (the MCP server this loop points the
agent at every turn) and **`hive-runtime`** (the library a turn runs
through).
[`docs/turn-loop/::Harness binary shape`](../docs/turn-loop/README.md#harness-binary-shape)
covers all three together.