diff --git a/README.md b/README.md index a81a5d8f..ed56da66 100644 --- a/README.md +++ b/README.md @@ -1,48 +1,101 @@ # hyperhive -> a swarm of claude-code agents, each in its own nspawn cage, gossiping -> over unix sockets. config changes flow as git commits, the operator -> approves them in a browser, every deploy is a tag. cyberpunk-themed -> dashboard included. 💜⚡ +Multi-Claude-Code-agent orchestration on **nixos-containers**. -Claude code is great in one window, *exponentielle* across many — but -only if you can keep the agents from stepping on each other, give them -durable identity, and stop them from eating production. hyperhive is -the substrate. - -- identity = unix socket -- communication = sqlite-backed broker (`send` / `recv` / `ask` / - `answer` / `remind`) -- config = git (manager proposes, operator approves, deploys land as - tagged commits) -- blast radius = container +A host-side Rust daemon (`hive-c0re`) spawns nspawn-isolated agent +containers and brokers messages between them. A manager agent (`hm1nd`) +coordinates the swarm and gates lifecycle changes on user approval via git +commits, surfaced through a vibec0re-styled HTTP dashboard. ``` host (NixOS, runs hive-c0re.service) │ ├── operator -│ ├── browser → :7000 hive-c0re dashboard -│ ├── browser → :8000 / :8100-8999 per-agent web UIs -│ └── CLI → /run/hyperhive/host.sock admin protocol +│ ├── browser → :7000 hive-c0re dashboard (containers, approvals) +│ ├── browser → :8000 / :8100-8999 per-agent web UIs (live SSE, send, login) +│ └── CLI → /run/hyperhive/host.sock JSON-line admin protocol │ -├── hive-c0re (Rust daemon: lifecycle / broker / approvals / -│ auto-update / dashboard / sockets) +├── hive-c0re (Rust daemon) +│ ├── lifecycle nixos-container CRUD + per-agent flake generation +│ ├── broker sqlite messages + tokio broadcast (powers SSE + wake-ups) +│ ├── approvals sqlite queue, two kinds: ApplyCommit (config) + Spawn +│ ├── auto_update rebuilds any container whose recorded flake rev is stale +│ ├── dashboard axum HTTP + async-form actions + SSE message flow +│ └── sockets /run/hyperhive/{host,manager,agents/}/mcp.sock │ -└── nixos-containers - ├── hm1nd manager agent (privileged MCP surface) - └── h- sub-agent (vanilla MCP surface + per-agent extras) +└── nixos-containers (each bind-mounts its socket dir → /run/hive, + │ credentials dir → /root/.claude, + │ durable notes dir → /state; + │ manager additionally gets /agents RW, + │ /applied RO (deployed-tag mirror), + │ /meta RO (swarm-wide deploy flake)) + │ + ├── hm1nd hive-m1nd serve : claude turn loop + + │ MCP (send / recv / request_spawn / kill / start / + │ restart / update / request_apply_commit / + │ ask / answer / remind) + web UI on :8000 + │ + └── h- hive-ag3nt serve : claude turn loop + + MCP (send / recv / ask / answer / remind + agent-declared + extras via hyperhive.extraMcpServers) + web UI + on a hashed :8100-8999 ``` -Depth lives in [`docs/`](docs/) — pick the one matching your task: +Each turn: harness pops one inbox message (Recv long-polls server-side and +wakes on a broker Sent event) → builds a wake prompt → spawns +`claude --print --continue --output-format stream-json --mcp-config …` → +streams JSON events into the per-agent SSE bus + a sqlite history db → +claude drives any further `recv`/`send` itself via the embedded MCP server. -| reading path | doc | -| --- | --- | -| dashboard layout + endpoints | [`docs/web-ui.md`](docs/web-ui.md) | -| claude turn loop + MCP tools | [`docs/turn-loop.md`](docs/turn-loop.md) | -| config-edit + approval state machine | [`docs/approvals.md`](docs/approvals.md) | -| what survives destroy / purge / restart | [`docs/persistence.md`](docs/persistence.md) | -| naming, wire protocol, commit style | [`docs/conventions.md`](docs/conventions.md) | -| NixOS / nspawn gotchas | [`docs/gotchas.md`](docs/gotchas.md) | +Operator surface per agent: terminal-themed live tail with a textarea +prompt; slash commands `/help` `/clear` `/cancel` `/compact` +`/model ` `/new-session`; granular state badge (idle / thinking +/ compacting / offline) with age timer + last-turn duration chip + +model chip; cancel-turn + new-session buttons in the state row; +sticky-bottom auto-scroll with "↓ N new" pill; event history +backfilled on page load; collapsible inbox + collapsible journald +viewer + collapsible `agent.nix` viewer per agent on the dashboard; +deployed-sha chip per container (read from meta's `flake.lock`). + +Operator surface on the dashboard itself: a terminal compose box +under the message-flow stream — `@name` picks the recipient with +auto-complete from the live container list, sticky across sends, +POSTs `/op-send` which drops the message into the broker as +`{from:"operator", to:, body}`. Same shape any sub-agent +sees as a regular inbox message. + +Config changes flow the other way: manager edits files under +`/agents//config/` — `agent.nix` is a plain NixOS module function +`{ config, pkgs, lib, ... }: { ... }`, and arbitrary sibling files in +the commit are preserved → commits → submits the sha via +`request_apply_commit`. Hive-c0re immediately fetches that commit from +the proposed repo into the applied repo and pins it as `proposal/` +— immutable from the manager's side from then on. Operator clicks +◆ APPR0VE → hive-c0re fast-forwards `applied//main` to the proposal, +runs `nix flake lock --update-input agent-` against the host-wide +meta flake at `/var/lib/hyperhive/meta/`, builds via +`nixos-container update --flake meta#`, and either commits +the lock + tags `deployed/` on success or `git restore`s the lock + +annotates `failed/` with the build error + rolls back +`applied//main` on failure. Denials leave a `denied/` annotated +tag carrying the operator's note. + +Meta's git log is the swarm-wide deploy audit trail (one commit per +successful deploy). Per-agent applied repos carry the tag-rich state +machine for inside-baseball decisions. The manager sees both — proposed +repos ship with an `applied` remote pre-wired, and `/meta/` is RO-bound +inside the container — so `git fetch applied`, +`git show applied/refs/tags/deployed/`, `git log /meta`, +`cat /meta/flake.lock` all just work without constructing paths by +hand. See [`docs/approvals.md`](docs/approvals.md) for the full state +machine + lock-flow walkthrough. +For decisions any agent (manager or sub) needs structured signal on, +`ask(question, options?, multi?, ttl_seconds?, to?)` queues a question: +default recipient is the operator (dashboard renders a free-text / +checkbox / radio form), or pass `to: ""` to route a structured +peer question into another agent's inbox. The answer arrives later as +a `HelperEvent::QuestionAnswered { id, question, answer, answerer }` +in the asker's inbox. Peer recipients respond via `answer(id, answer)`. ## Host config @@ -62,9 +115,12 @@ Minimal `flake.nix` for a host that runs hive-c0re: hyperhive.nixosModules.hive-c0re ({ ... }: { services.hive-c0re.enable = true; - # services.hive-c0re.operatorPronouns = "they/them"; # default: "she/her" + # Free-text operator pronouns — defaults to "she/her", threaded + # through to every agent's system prompt as HIVE_OPERATOR_PRONOUNS + # so claude refers to you naturally in third person. + # services.hive-c0re.operatorPronouns = "they/them"; - # ... rest of your host config + # ... rest of your host config (hardware, networking, users, …) system.stateVersion = "25.11"; }) ]; @@ -73,18 +129,35 @@ Minimal `flake.nix` for a host that runs hive-c0re: } ``` -hive-c0re opens its admin socket + dashboard, auto-creates the -manager container, and auto-rebuilds any container whose hyperhive -rev goes stale. `claude-code` is unfree — hyperhive scopes the -whitelist to itself, nothing for the operator to set. +hive-c0re will then: +- open its admin socket at `/run/hyperhive/host.sock` + dashboard on + `:7000`, +- auto-create the manager container (`hm1nd`) if missing, +- auto-rebuild any managed container whose hyperhive rev is stale. + +`claude-code` is unfree; hyperhive whitelists it for itself +(scoped: only `claude-code`, nothing else) inside the +`claude-unstable` overlay and `harness-base.nix`. Per-agent +containers evaluate their own nixpkgs instance so the operator's +host-level `allowUnfree` doesn't propagate in — the predicate has +to live inline. Nothing to set on the operator side. ## Build / deploy ```sh +# inside the repo (devshell first; no global cargo) nix develop -c cargo check -nix flake check # rust + nix + toml fmt + clippy +nix develop -c cargo clippy --workspace --all-targets -- -D warnings -# deploy from a host config that imports hyperhive.nixosModules.hive-c0re +# evaluate everything (rust+nix+toml fmt + clippy) +nix flake check + +# deploy to a host that imports `hyperhive.nixosModules.hive-c0re` +cd ~/Repos/ nix flake update --update-input hyperhive sudo nixos-rebuild switch --flake .# ``` + +No overlays on the host's `pkgs` — the module pulls hive-c0re's package +straight from `hyperhive.packages..default`. Just import the +module and the service is wired up. diff --git a/TODO.md b/TODO.md index fcbd796c..54d5442a 100644 --- a/TODO.md +++ b/TODO.md @@ -9,9 +9,6 @@ - **Multi-agent restart coordination**: when rebuilding all agents, manager should start first so it can coordinate post-restart confusion (notify agents, suppress unnecessary retries, etc) - **Shared docs/skills repo (RO)**: a single repo on the hive forge that every agent has read-only access to — common references, prompts, runbooks, "skills" the operator wants every agent to inherit without baking into the system prompt or `/shared`. Implementation likely: seed an `org-shared/docs` repo on first hive-forge boot, grant every per-agent user a read membership in the org. Agents `git clone` it (or use the API) to read; only the manager + operator can push. - **Loose-ends tracker + `get_open_threads` tool**: hive-c0re already knows about pending approvals + unanswered questions; soon will also know about open PRs on hive-forge. Aggregate these into a per-agent "open threads" view (e.g. `[{kind: "approval", id: 7, summary: "spawn alice"}, {kind: "question", id: 12, asker: "alice", summary: "deploy now?"}]`). New MCP tool `mcp__hyperhive__get_open_threads` returns the list so an agent can see what's still pending against it without rebuilding context from inbox history. Manager's version includes hive-wide threads. **Also surface this list on the per-agent web UI** so the operator can see at a glance what each agent has hanging open — same data source as the MCP tool, just rendered into the existing per-agent dashboard page (next to inbox view / model chip / etc). - - **Scope per agent X (confirmed with operator):** include BOTH (a) unanswered questions where `asker == X` (X is waiting on someone) AND (b) unanswered questions where `target == X` (X owes an answer). Distinguish via a `role: "asker" | "target"` field on the question variant so the agent can render "waiting on" vs "owe a reply" appropriately. Approvals: include rows where the submitter is X (waiting on the operator). Forge PRs (future): include open PRs where X is author OR reviewer. - - **Wire shape sketch:** new `AgentRequest::GetOpenThreads` / `ManagerRequest::GetOpenThreads` returning `Response::OpenThreads { threads: Vec }` with `OpenThread` as a tagged enum (`{kind: "approval", id, summary, age_seconds}` / `{kind: "question", id, role, counterparty, summary, age_seconds}` / future `{kind: "pr", ...}`). Manager flavour returns hive-wide threads (no asker/target filter). MCP tool `get_open_threads` takes no args. - - **Aggregator location:** new helper on `Coordinator` (or a dedicated `open_threads.rs`) so both surfaces share the query logic; queries `approvals` + `operator_questions` tables with a single per-call sweep (no caching — call frequency is low). ## Reminder Tool