fd74cbd495
Frame the turn loop runtime-neutrally: every turn runs through hive-runtime, on claude (default) or an ACP agent. The loop steps, harness binary shape and hive-agent README now say so; claude-only failure detection gets its own heading; claude-invocation.md opens with its scope and links the ACP side to hive-runtime/README.md. Fact fixes: on-boot file paths (/run/hive-config, not /run/hive), hive-claude is a crates.io dependency with no README here, hive-agent has no client.rs or forge_notify.rs, the claude launch-config layer is hive-agent's mcp_config.rs, agent forge/matrix accounts are swarm-controller's, hive-c0re's dashboard is dashboard/, and the deprecated hyperhive.gui.enable / hyperhive.extraMcpServers spellings. Refs #3902
53 lines
2.5 KiB
Markdown
53 lines
2.5 KiB
Markdown
# 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.
|