vinzenz/hyperhive
vinzenz/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
hyperhive/hive-agent
History
Repository files (latest commit first)
Filename Latest commit message Latest commit date
atlas 31008c83df feat: pause an agent's turn loop without stopping its container 
A paused agent keeps its container, its claude session and its
dashboard/todo servers up, but stops driving turns. Messages queue
unacked and are drained on resume.

The whole protocol is a single marker file, `<harness>/paused`. That
directory is already a bind-mount shared between host and container, so
both sides just stat the same path: the harness reads it to decide
whether to drive a turn, hive-c0re reads it to render the badge and
writes/removes it for `hivectl pause|resume`. No new wire protocol, no
container round-trip, and it is sticky across restarts by construction.

Not calling `recv_next` while paused *is* the queueing semantic, so
there is no fencing to get wrong: reminders buffer in their unbounded
channel, the todo `Notify` permit coalesces, and a `request_next_turn`
that raced the pause survives because the gate sits above
`self_continue.take()`.

Graceful stop is handled host-side rather than in the harness: a paused
agent provably has no turn in flight, so `run_signal` skips the fence
entirely instead of eating the full `GRACEFUL_STOP_TIMEOUT` waiting for
a checkpoint turn that will never run.

`paused` is reported on `ContainerView` / `AgentStatusRow` for the
dashboard, orthogonal to `running` and reported for stopped containers
too.

Closes: hyperhive/hyperhive issue 2271
2026-07-26 03:11:33 +02:00
..
prompts docs(#2628): update bash tool descriptions, docs, and system prompt for the todo model (trim impl details for agent) 2026-07-22 17:34:12 +02:00
src feat: pause an agent's turn loop without stopping its container 2026-07-26 03:11:33 +02:00
Cargo.toml remove hive-agent-wake — no shipped consumer 2026-07-25 20:05:32 +02:00
README.md remove hive-agent-wake — no shipped consumer 2026-07-25 20:05:32 +02:00

README.md

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.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.md::Harness binary shape.