203 lines
10 KiB
Markdown
203 lines
10 KiB
Markdown
# hyperhive — claude entry point
|
|
|
|
Hey claude. This is your starting page. The detailed docs live in
|
|
[`docs/`](docs/) and are written for humans + you both — read them
|
|
when you need depth on a subsystem. This file is the index +
|
|
scratchpad.
|
|
|
|
- High-level project intro: **[README.md](README.md)**.
|
|
- Open work + backlog: **[TODO.md](TODO.md)**.
|
|
|
|
## File map
|
|
|
|
```
|
|
hive-c0re/ host daemon + CLI (one binary, subcommand-dispatched)
|
|
src/main.rs clap setup; serve / spawn / kill / rebuild / list /
|
|
pending / approve / deny / destroy [--purge] /
|
|
request-spawn; periodic vacuum tasks
|
|
src/server.rs host admin socket (HostRequest → dispatch)
|
|
src/client.rs admin-socket client
|
|
src/manager_server.rs manager-privileged socket (ManagerRequest)
|
|
src/agent_server.rs per-sub-agent socket listener (long-poll Recv)
|
|
src/broker.rs sqlite Message store + broadcast channel for SSE +
|
|
hourly vacuum of delivered>30d
|
|
src/approvals.rs sqlite Approval queue + kinds
|
|
src/operator_questions.rs sqlite question queue backing `ask_operator`
|
|
src/reminder_scheduler.rs 5s poll loop: drains due reminders,
|
|
resolves file_path container→host, persists
|
|
payload + delivers pointer string
|
|
src/events_vacuum.rs host-side hourly sweep of every agent's
|
|
/state/hyperhive-events.sqlite
|
|
src/crash_watch.rs poll every 10s; fire HelperEvent::ContainerCrash
|
|
when a previously-running container disappears
|
|
without an operator-initiated transient
|
|
src/coordinator.rs shared state (broker/approvals/questions/transient/
|
|
sockets) + tombstone enumeration + kick_agent
|
|
src/actions.rs approve/deny/destroy (transient-aware)
|
|
src/auto_update.rs startup rebuild scan + ensure_manager +
|
|
meta::lock_update_hyperhive bump
|
|
src/lifecycle.rs `nixos-container` shellouts; per-agent applied
|
|
+ proposed git repo seeding; tag plumbing
|
|
src/meta.rs single hive-c0re-owned flake at /var/lib/
|
|
hyperhive/meta/ — sync_agents, two-phase
|
|
prepare/finalize/abort, lock_update_*
|
|
src/migrate.rs startup auto-migration from pre-meta layout
|
|
(idempotent, marker-guarded phase 4)
|
|
src/dashboard.rs axum HTTP: static shell + /api/state JSON + actions
|
|
+ journald viewer + bind-with-retry (SO_REUSEADDR)
|
|
+ deployed_sha chip per container
|
|
assets/ index.html, dashboard.css, app.js (include_str!)
|
|
|
|
hive-ag3nt/ in-container harness crate; produces TWO binaries
|
|
src/lib.rs re-exports + DEFAULT_SOCKET, DEFAULT_WEB_PORT
|
|
src/client.rs generic JSON-line request/response over unix socket
|
|
src/web_ui.rs per-container axum HTTP page (incl /api/cancel,
|
|
/api/compact, /api/model, /events/history)
|
|
src/events.rs LiveEvent + broadcast Bus + sqlite-backed history
|
|
(/state/hyperhive-events.sqlite) + TurnState +
|
|
model selection (persisted at /state/hyperhive-model)
|
|
src/turn.rs claude --print + stream-json pump; --compact retry
|
|
src/mcp.rs embedded MCP server (rmcp): AgentServer + ManagerServer
|
|
src/login.rs probe /root/.claude/ for a valid session
|
|
src/login_session.rs drives `claude auth login` over stdio pipes
|
|
src/bin/hive-ag3nt.rs sub-agent main (Serve + Mcp subcommands)
|
|
src/bin/hive-m1nd.rs manager main (Serve + Mcp subcommands)
|
|
assets/ index.html, agent.css, app.js (include_str!)
|
|
prompts/ static role/tools/settings for claude (include_str!):
|
|
agent.md — sub-agent system prompt
|
|
manager.md — manager system prompt
|
|
claude-settings.json — --settings JSON
|
|
|
|
hive-sh4re/ wire types (HostRequest/Response, AgentRequest/Response,
|
|
ManagerRequest/Response, Message, Approval, HelperEvent)
|
|
|
|
nix/
|
|
modules/hive-c0re.nix systemd service + firewall + git wiring
|
|
templates/harness-base.nix shared scaffolding for sub-agents + manager
|
|
templates/agent-base.nix sub-agent nixosConfiguration
|
|
templates/manager.nix manager nixosConfiguration
|
|
|
|
docs/
|
|
conventions.md naming, identity=socket, async forms, commit style
|
|
gotchas.md NixOS / nspawn lessons learned the hard way
|
|
web-ui.md dashboard + per-agent page layouts and endpoints
|
|
turn-loop.md claude invocation, wake prompt, MCP tool surface
|
|
approvals.md approval flow, manager policy, helper events
|
|
persistence.md sqlite dbs, retention, state dir layout
|
|
```
|
|
|
|
## Reading paths
|
|
|
|
Pick the doc that matches your task. None depend on the others —
|
|
read them à la carte.
|
|
|
|
- **"What does the dashboard look like?"** →
|
|
[`docs/web-ui.md`](docs/web-ui.md).
|
|
- **"How does claude get its prompt and what tools does it have?"** →
|
|
[`docs/turn-loop.md`](docs/turn-loop.md).
|
|
- **"How do config changes flow from manager to operator to
|
|
container?"** → [`docs/approvals.md`](docs/approvals.md).
|
|
- **"What state survives destroy / purge / restart?"** →
|
|
[`docs/persistence.md`](docs/persistence.md).
|
|
- **"Naming, commit style, wire protocol, the `data-async`
|
|
pattern."** → [`docs/conventions.md`](docs/conventions.md).
|
|
- **"Why does the nspawn flag look like that?"** →
|
|
[`docs/gotchas.md`](docs/gotchas.md).
|
|
|
|
## Quick reminders
|
|
|
|
- **Commit before test.** Stage and commit when work *looks*
|
|
ready, then run validation. Failures get a follow-up commit
|
|
rather than an amend.
|
|
- **Commit messages: short, lowercase, no `Co-Authored-By`
|
|
trailer.** Imperative mood.
|
|
- **`rebuild` is the reconcile verb.** Anything that changes
|
|
per-container state on the host should be re-applied there so
|
|
the dashboard's `↻ R3BU1LD` is sufficient to recover.
|
|
- **Identity = socket.** No auth tokens — the socket path
|
|
identifies the principal.
|
|
- **Actions are factored** between admin socket and dashboard via
|
|
`actions.rs` and `dashboard.rs::lifecycle_action`, so the two
|
|
surfaces never drift.
|
|
|
|
## Scratchpad
|
|
|
|
In-flight or recent context that hasn't earned a section yet.
|
|
Prune freely.
|
|
|
|
- **Just landed:** meta-flake overhaul. Each agent's applied
|
|
repo is a module-only flake (forwards every `inputs.*`
|
|
through to `agent.nix` as the `flakeInputs` module arg —
|
|
manager edits `inputs` to pull in external flakes like an
|
|
MCP server's own flake; the new sha lands in the agent's
|
|
own `flake.lock` and rolls up to meta's). A single
|
|
hive-c0re-owned repo at `/var/lib/hyperhive/meta/`
|
|
declares one input per agent and one
|
|
`nixosConfigurations.<n>` output, wrapping the agent's
|
|
`nixosModules.default` with identity + `HIVE_PORT` /
|
|
`HIVE_LABEL` / `HIVE_DASHBOARD_PORT` /
|
|
`HIVE_OPERATOR_PRONOUNS`. Containers run against
|
|
`meta#<n>`. Every approve uses two-phase staging
|
|
(prepare → build → finalize/abort) so meta's git log only
|
|
records successful deploys; failures + denials live as
|
|
annotated tags in applied. All meta operations
|
|
serialize behind a tokio mutex; stale `.git/index.lock`
|
|
is cleared on hive-c0re startup. Manager has `/applied`
|
|
+ `/meta` RO-bound + the `applied` remote pre-wired in
|
|
every proposed repo. Migration runs idempotently on
|
|
startup (`HIVE_SKIP_META_MIGRATION=1` skips). Operator
|
|
pronouns are a NixOS module option
|
|
(`services.hive-c0re.operatorPronouns`, default
|
|
`"she/her"`); the harness substitutes them into the
|
|
system prompt at boot.
|
|
- **Just landed:** per-agent extra MCP servers via the
|
|
`hyperhive.extraMcpServers.<key>` NixOS option in
|
|
`agent.nix`. Declares `{ command, args, env,
|
|
allowedTools }`; the module writes the whole map to
|
|
`/etc/hyperhive/extra-mcp.json`; the harness reads that
|
|
file and merges each entry into both `--mcp-config`
|
|
and `--allowedTools` (mapped to `mcp__<key>__<pattern>`).
|
|
Unblocks matrix / bitburner / any agent with rich
|
|
domain tooling — the agent flake's `inputs` block pulls
|
|
the external flake, `agent.nix` references it via
|
|
`flakeInputs.<name>.packages.${pkgs.system}.default`.
|
|
- **Just landed:** `mcp__hyperhive__ask_operator` is now on
|
|
the sub-agent surface too (not just the manager). Answer
|
|
routes back to whichever agent asked via
|
|
`coord.notify_agent`; the dashboard already shows the
|
|
asker on each question row.
|
|
- **Just landed:** dashboard now has a terminal-style
|
|
compose textbox under the message-flow stream — `@name`
|
|
picks the recipient (sticky in localStorage, auto-
|
|
completed from `containers[]`), POSTs `/op-send`. New
|
|
per-agent `↻ new session` button drops `--continue` for
|
|
one turn. Claude spawns with `cwd = /state` so relative
|
|
paths in tool calls land in the durable dir.
|
|
- **Just landed (prior overhaul still underneath):** tag-
|
|
driven config-apply. Two-repo split (proposed = manager
|
|
RW, applied = core-only); `request_apply_commit` fetches
|
|
the manager's commit into applied and pins it as
|
|
`proposal/<id>`; approve / deny / build walk through
|
|
tags on the same commit; `applied/main` only fast-
|
|
forwards on `deployed/`. `failed/` + `denied/` are
|
|
annotated. See `docs/approvals.md`.
|
|
- **Recent (since last compaction):** inline +/- diffs on
|
|
Write/Edit, send full body via collapsed details, operator
|
|
cancel + ttl on questions, deny-with-reason, dashboard
|
|
back-link + last-turn timing + model chip, per-agent inbox
|
|
view, bind-retry + SO_REUSEADDR, journald viewer,
|
|
agent.nix viewer, server-side TurnState, recv(wait_seconds)
|
|
max 180s, runtime /model switch + persistence to /state,
|
|
crash watcher + ContainerCrash / NeedsLogin / LoggedIn /
|
|
NeedsUpdate events, manager `update` tool, pure-hash
|
|
agent_web_port + collision banner + spawn/rebuild preflight,
|
|
browser notifications, focus-preserving refresh, generalised
|
|
<details data-restore-key> survival, prompt-on-submit pattern.
|
|
- **Open threads:** custom per-agent MCP tools (groundwork for
|
|
moving bitburner-agent into hyperhive), two-step spawn,
|
|
per-agent send allow-list, telemetry/charts, notes
|
|
compaction, unprivileged containers, Bash allow-list,
|
|
xterm.js. **Known bug** (in TODO.md): question id=5 was
|
|
queued but didn't render — likely a `pending()` row-decode
|
|
error swallowed by `unwrap_or_default`; investigate by curl
|
|
/api/state | jq '.questions' + browser console.
|