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/; 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 the agent's permissions.
• 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 covers all three together.