# hive-runtime

The layer an agent's turns are driven through: one `Runtime` interface
(`run`, `compact`, `archive`) with a backend per runtime.

- **claude** — `claude --print` through the `hive-claude` crate's
  `InfiniteSession`. A pass-through: same spawn, same session handling, same
  errors.
- **acp** — any [Agent Client Protocol](https://agentclientprotocol.com)
  agent, spawned from a command, args and env handed to it (`RuntimeSpec`,
  read from `HIVE_RUNTIME` / `HIVE_ACP_COMMAND` / `HIVE_ACP_ARGS` /
  `HIVE_ACP_ENV`). It knows no agent by name; which agent runs, and how it is
  configured, is decided in nix (`services.hyperhive.agent.runtime`,
  `services.hyperhive.agent.acp.*`).

Both backends report a turn through `hive_claude::Sink` in claude's
`stream-json` shape. The ACP backend translates `session/update`
notifications into it (text and thought chunks as whole blocks, tool calls as
`tool_use` + `tool_result`, MCP tools named `mcp__<server>__<tool>`), so the
harness's stream consumers read either backend unchanged. Context usage comes
from ACP `usage_update`.

The crate depends on no hyperhive binary crate, so `hive-agent` and
`hive-subagent-mcp` can both drive turns through it.

## ACP backend: what it needs from the agent

- `mcpCapabilities.http` in its `initialize` response. The hyperhive tools
  are only served over HTTP, so an agent without it is refused at startup.
- `loadSession`, to pick its session back up after a harness restart.
  Without it every restart starts a new session.

## ACP backend: not yet

`compact` returns `Error::Unsupported`, there is no cancel, and no idle
watchdog (`Config::idle_timeout` is ignored). An agent that retries a failing
provider on its own keeps the turn open until it gives up.