62d1a74929
revert the earlier 'operator must set allowUnfree' move: per-agent containers evaluate their own nixpkgs and the operator's host-level allowUnfree doesn't propagate in. restoring the scoped allowUnfreePredicate inside both the claude-unstable overlay and harness-base.nix; documented in README + gotchas as 'nothing to set on the operator side'. docs: - claude.md file map adds crash_watch.rs, kick_agent on coordinator, /api/model + journald viewer + bind-with-retry references. - scratchpad rewritten to reflect the recent run. - web-ui.md: notification row + browser notifications section, state row (badge + model chip + last-turn chip + cancel button), per-agent inbox, /model slash, /cancel-question + journald endpoints, focus-preservation on refresh. - turn-loop.md: --model is read from Bus::model() per turn (runtime override via /model); recv(wait_seconds) up to 180s with the rationale; ask_operator gains ttl_seconds; new TurnState section; kick_agent inbox-on-startup hint. - approvals.md: ttl/cancel resolution paths for operator questions. - persistence.md: /state/hyperhive-model file. - gotchas.md: web UI port collision policy (rename, don't probe); bind retry + SO_REUSEADDR shape; auto-unfree restored. - todo.md: cleaned up empty sections and stale entries; /model shipped, dropped from the list.
130 lines
6.4 KiB
Markdown
130 lines
6.4 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/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
|
|
src/lifecycle.rs `nixos-container` shellouts, per-agent flake generator
|
|
src/dashboard.rs axum HTTP: static shell + /api/state JSON + actions
|
|
+ journald viewer + bind-with-retry (SO_REUSEADDR)
|
|
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.
|
|
|
|
- 2026-05-15 ish: tombstones, multi-select ask_operator, broker +
|
|
events vacuum, docs split into `docs/`, lifecycle_action helper,
|
|
api_state split.
|
|
- Then: inline +/- diffs on Write/Edit, operator cancel + ttl on
|
|
questions, dashboard back-link, per-agent inbox view, bind-retry
|
|
+ SO_REUSEADDR, journald viewer, server-side TurnState,
|
|
recv(wait_seconds) max 180s, runtime /model switch, crash
|
|
watcher, model persistence, stopped auto-allowing claude-code
|
|
unfree (operator must opt in), pure-hash agent_web_port (port
|
|
files reverted), browser notifications, focus-preserving
|
|
refresh.
|
|
- Open threads: telemetry/charts, custom per-agent MCP tools (the
|
|
groundwork for moving bitburner-agent into hyperhive),
|
|
two-step spawn, unprivileged containers, Bash allow-list.
|