214 lines
12 KiB
Markdown
214 lines
12 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.
|
|
|
|
- High-level project intro: **[README.md](README.md)**.
|
|
- Open work + backlog: the **[forge issue
|
|
tracker](http://localhost:3000/hyperhive/hyperhive/issues)**.
|
|
- Operator/agent trust-boundary design:
|
|
**[docs/boundary.md](docs/boundary.md)** (`area:ops` issues
|
|
for the deployment/gateway/privsep work).
|
|
|
|
## 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 + intra-process broadcast
|
|
channel (`MessageEvent`) for `recv_blocking_batch` +
|
|
the dashboard forwarder; hourly vacuum of acked>30d
|
|
src/dashboard_events.rs unified wire-facing event channel feeding
|
|
`/dashboard/stream`. Carries broker `Sent` /
|
|
`Delivered` (mirrored by the forwarder task
|
|
in main.rs) + mutation events
|
|
(`ApprovalAdded` / `ApprovalResolved`,
|
|
`QuestionAdded` / `QuestionResolved`,
|
|
`TransientSet` / `TransientCleared`). Each
|
|
frame carries a monotonic per-process `seq`
|
|
clients use to dedupe against snapshot reads.
|
|
src/approvals.rs sqlite Approval queue + kinds
|
|
src/operator_questions.rs sqlite question queue backing `ask` /
|
|
`answer` (both operator + agent-to-agent)
|
|
src/questions.rs shared dispatch for `Ask` / `Answer` —
|
|
used by both agent + manager surfaces
|
|
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/container_view.rs ContainerView struct + build_all helper;
|
|
shared between dashboard.rs (cold-load via
|
|
/api/state) and coordinator.rs's
|
|
rescan_containers_and_emit
|
|
src/coordinator.rs shared state (broker/approvals/operator_questions/
|
|
transient/sockets) + tombstone enumeration +
|
|
kick_agent + notify_agent (helper-event push) +
|
|
last_containers cache + rescan_and_emit diff helper
|
|
src/loose_ends.rs loose-ends aggregator (pending approvals +
|
|
unanswered questions + pending reminders) —
|
|
for_agent (filtered) and hive_wide (manager
|
|
surface). Backs AgentRequest::GetLooseEnds +
|
|
ManagerRequest::GetLooseEnds (the
|
|
get_loose_ends MCP tool).
|
|
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/forge.rs optional Forgejo wiring: per-agent users +
|
|
tokens, the `agent-configs` org, and
|
|
`push_config` — mirrors each applied repo
|
|
into `agent-configs/<n>` on the local forge
|
|
src/dashboard.rs axum HTTP: static shell + /api/state JSON + actions
|
|
+ journald viewer + bind-with-retry (SO_REUSEADDR)
|
|
+ deployed_sha chip per container +
|
|
/dashboard/{stream,history} subscribing to the
|
|
unified DashboardEvent channel
|
|
assets/ index.html, dashboard.css, app.js (include_str!)
|
|
|
|
hive-fr0nt/ shared frontend-assets crate (browser only).
|
|
src/lib.rs pub const BASE_CSS / TERMINAL_CSS / TERMINAL_JS /
|
|
MARKED_JS re-exports; both binaries
|
|
`include_str!` them and prepend to their per-
|
|
page serving routes.
|
|
assets/base.css Catppuccin palette + body typography (one source
|
|
of truth, no per-page redeclaration).
|
|
assets/terminal.css `.terminal-wrap` + `.live` + `.tail-pill` +
|
|
`.row` / `details.row` styling for both
|
|
pages' lit log panes. Unified prefix-column
|
|
(padding-left + negative text-indent) so glyph
|
|
alignment is consistent across row kinds + a
|
|
`.md` block scope for marked-rendered bodies.
|
|
assets/terminal.js `window.HiveTerminal.create(opts)`: scroll-
|
|
sticky log + "↓ N new" pill + history
|
|
backfill + SSE subscribe-buffer-snapshot-
|
|
dedupe dance. Pages register a kind→renderer
|
|
map; the terminal owns the lifecycle.
|
|
assets/marked.min.js vendored marked v4.0.2 UMD bundle. Per-agent
|
|
terminal uses the global `marked.parse` for
|
|
markdown bodies on send / recv / ask / answer
|
|
/ assistant text rows.
|
|
|
|
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,
|
|
/screen, /screen/ws)
|
|
src/turn_stats.rs per-turn analytics sink (one sqlite row per
|
|
turn at /state/hyperhive-turn-stats.sqlite);
|
|
schema + best-effort writer
|
|
src/stats.rs read-side aggregations over turn-stats.sqlite
|
|
backing the /stats page (bucketed Snapshot:
|
|
turns / duration / tokens / model mix)
|
|
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;
|
|
proactive compaction + auto session-reset
|
|
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, stats.html,
|
|
stats.js, screen.html (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;
|
|
`contextWindowTokens` attrset (per-model,
|
|
injected as env vars into all containers);
|
|
imports hive-forge.nix
|
|
modules/hive-forge.nix optional in-container Forgejo
|
|
(`hyperhive.forge.enable`, default on);
|
|
Catppuccin Mocha theme via tmpfiles C+ copy
|
|
templates/harness-base.nix shared scaffolding for sub-agents + manager;
|
|
`hyperhive.model` option (HIVE_DEFAULT_MODEL)
|
|
templates/agent-base.nix sub-agent nixosConfiguration
|
|
templates/manager.nix manager nixosConfiguration
|
|
templates/weston-vnc.nix optional `hyperhive.gui.enable`
|
|
— weston + VNC backend systemd unit; writes
|
|
/etc/hyperhive/gui.json (vnc_port + auth) for
|
|
the harness WebSocket relay (/screen/ws)
|
|
forge-theme/theme-catppuccin-vibec0re.css Catppuccin Mocha forge theme
|
|
|
|
docs/
|
|
conventions.md naming, identity=socket, async forms, commit style
|
|
gotchas.md NixOS / nspawn quirks and lessons learned
|
|
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
|
|
terminal-rendering.md per-agent terminal row taxonomy (as built)
|
|
boundary.md operator/agent trust model rationale
|
|
damocles-migration.md future migration plan for damocles → hyperhive
|
|
```
|
|
|
|
## 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 the per-agent terminal classify + colour
|
|
events?"** → [`docs/terminal-rendering.md`](docs/terminal-rendering.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.
|
|
- **Two-step spawn:** `request_init_config` → edit `agent.nix` →
|
|
`request_spawn`. Never submit a Spawn approval without first
|
|
reviewing the config template.
|
|
- **Rate-limit sentinel:** `{state_dir}/hyperhive-rate-limited`
|
|
is written by the harness on 429 and cleared on retry.
|
|
`ContainerView.rate_limited` reads it for the dashboard badge.
|
|
- **Context window:** defaults are in `services.hive-c0re.contextWindowTokens`
|
|
(host nix, affects all agents). Per-agent default model via
|
|
`hyperhive.model` in `agent.nix`. Watermarks are 75%/50% of the
|
|
effective window.
|