From 04e27c4fb6ccef8d9f1918b2f14c5b05eb616913 Mon Sep 17 00:00:00 2001 From: iris Date: Sun, 20 Sep 2026 15:07:46 +0200 Subject: [PATCH] docs: suppress reviewed write-good.Passive false positives MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 133 hits across 38 files, all previously classified during #4548's sweep and deliberately left un-rewritten (predicate-adjective state/necessity description, design-intent idiom, structural/type-description idiom, no-single-actor topology claim, parallel-triple exception, vale substring-match artifact — see hyperhive#4548's per-PR bodies for the per-hit reasoning). Wraps each one in a scoped pair (the supported mechanism — TokenIgnores has a known offset-drift bug) rather than a blanket per-file or per-rule silence, so a *new* passive-voice hit anywhere in these files still fails once the rule gates CI (next commit). Table/list false positives (docs/swarm/credentials.md's renewal-table cells) wrap the whole block, not each cell. Part of #4546. --- docs/agent-lifecycle/agent-hierarchy.md | 35 ++++++++++++++++--------- docs/agent-lifecycle/approvals.md | 6 +++-- docs/agent-lifecycle/persistence.md | 12 +++++++++ docs/getting-started/setup.md | 21 +++++++++------ docs/integrations/github.md | 4 +++ docs/integrations/knowledge.md | 15 ++++++++--- docs/integrations/matrix.md | 16 +++++++---- docs/networking/gateway.md | 24 ++++++++++++++++- docs/networking/network.md | 8 ++++-- docs/networking/snapshot-store.md | 16 +++++++---- docs/process/conventions.md | 4 ++- docs/process/gotchas.md | 18 ++++++++++++- docs/process/pr-review-gate.md | 4 +++ docs/scheduler/ci.md | 12 +++++++++ docs/scheduler/coordinator.md | 26 ++++++++++++------ docs/scheduler/jobq.md | 4 +++ docs/scheduler/observability.md | 28 ++++++++++++++++++++ docs/swarm/README.md | 14 +++++++--- docs/swarm/ca.md | 12 +++++++++ docs/swarm/credentials.md | 8 ++++++ docs/swarm/secrets.md | 10 +++---- docs/swarm/services.md | 4 +++ docs/swarm/sso.md | 4 +++ docs/swarm/ui.md | 8 ++++++ docs/tools/forge.md | 6 +++++ docs/tools/hivectl.md | 8 ++++-- docs/tools/matrix.md | 4 +++ docs/tools/scheduling.md | 8 ++++++ docs/tools/subagent.md | 8 ++++++ docs/tools/swarm-logs-cli.md | 2 ++ docs/trust-boundary/boundary.md | 8 ++++++ docs/trust-boundary/security.md | 14 +++++++++- docs/turn-loop/claude-invocation.md | 19 ++++++++------ docs/turn-loop/config.md | 4 +++ docs/web-ui/agent.md | 4 +++ docs/web-ui/dashboard.md | 20 ++++++++++++++ docs/web-ui/design-guide.md | 13 ++++++--- docs/web-ui/shape.md | 8 ++++++ 38 files changed, 368 insertions(+), 71 deletions(-) diff --git a/docs/agent-lifecycle/agent-hierarchy.md b/docs/agent-lifecycle/agent-hierarchy.md index 6fcafe2e..e4b75733 100644 --- a/docs/agent-lifecycle/agent-hierarchy.md +++ b/docs/agent-lifecycle/agent-hierarchy.md @@ -1,11 +1,15 @@ # Agent hierarchy & privileges + + Every agent has a place in an operator-editable parent/child tree, used to scope which agents can manage which others. This doc covers how hive-c0re stores and edits the tree today, the rules that are meant to run on top of it once enforcement is finished, and where the manager still gets special-cased in the meantime, as a tracked cleanup. + + ## Where the tree lives Topology lives in the hive-c0re-owned **meta repo**, alongside @@ -31,7 +35,7 @@ not its tree position (see _Manager special-casing today_ below). ### Reparenting - CLI: `hivectl agent set-parent --parent ` (or `--root` - to promote). Exactly one of `--parent` / `--root` is required. + to promote). Pass exactly one of `--parent` / `--root`. - Dashboard: `POST /api/topology/set-parent` (form fields `child`, optional `new_parent` — absent / empty ⇒ promote to root). - Wire: `HostRequest::SetParent { child, new_parent: Option }`. @@ -104,6 +108,8 @@ Enforcement of the ancestor rules above isn't fully wired yet, so the **manager (`ruth`) still gets some hard-coded special treatment** other agents don't: + + - **Naming/bootstrap** — the manager's broker recipient name, state-dir key, and nixos-container name are all `ruth` (container `h-ruth`). `hive-c0re` spawns it directly at boot if missing, with no operator @@ -143,17 +149,18 @@ Manager}` switch picks the MCP tool allow-list claude sees. Both are container including the manager, so all token/state paths resolve through it the same way everywhere. - **Scattered ownership checks** — a handful of independent - manager-only overrides exist across `hive-c0re` today: loose-ends - visibility (manager sees hive-wide, sub-agents only their own), - `destroy` refusing to act on the manager, and crash-watch skipping - the manager (it autorestarts via systemd instead of going through - the crash-watch loop). Each is planned to become an - ancestor/descendant check instead of a manager-name check — see the - module docs for `loose_ends.rs`, `stores/broker.rs`, `actions.rs`, - and `workers/crash_watch.rs` for the current owner-check logic in - each. (The harness handles reminder cancellation fully in-agent — see - the note on `CancelLooseEndKind::Reminder` in - `hive-c0re/src/socket_server/mod.rs`.) +manager-only overrides exist across `hive-c0re` today: loose-ends +visibility (manager sees hive-wide, sub-agents only their own), +`destroy` refusing to act on the manager, and crash-watch skipping +the manager (it autorestarts via systemd instead of going through +the crash-watch loop). Each is planned to become an +ancestor/descendant check instead of a manager-name check — see the +module docs for `loose_ends.rs`, `stores/broker.rs`, `actions.rs`, +and `workers/crash_watch.rs` for the current owner-check logic in +each. (The harness handles reminder cancellation fully in-agent — see +the note on `CancelLooseEndKind::Reminder` in +`hive-c0re/src/socket_server/mod.rs`.) + None of the above is a stable interface — treat the module doc comments as the source of truth for exactly which checks exist today. @@ -204,6 +211,8 @@ direct mentions, reviews, and assignments. path = [ "/run/wrappers" "/run/current-system/sw" ]; ``` + + `/run/wrappers` (not `/run/wrappers/bin`) comes first so setuid wrappers — notably `sudo` — resolve before bare nix-store binaries; see [`docs/process/gotchas.md`](../process/gotchas.md) ("`systemd.services.*.path` appends @@ -214,6 +223,8 @@ the non-setuid nix-store binary and every `services.hyperhive.agent.user.passwordlessSudo` grant fails with "must be owned by uid 0 and have the setuid bit set." + + ### `serviceConfig` highlights - `ExecStart = pkgs.hyperhive/bin/hive-agent` — same binary for every diff --git a/docs/agent-lifecycle/approvals.md b/docs/agent-lifecycle/approvals.md index fa401402..9cd7d632 100644 --- a/docs/agent-lifecycle/approvals.md +++ b/docs/agent-lifecycle/approvals.md @@ -148,9 +148,10 @@ through the web UI or the forge. ### Approval kinds (wire shapes) `ApprovalKind` carries four variants; each maps to a different -`commit_ref` encoding because that field is overloaded as the -kind-specific payload carrier. +`commit_ref` encoding because `ApprovalKind` overloads that field as +the kind-specific payload carrier. + - `MergeConfigPr` — the config-change flow. Triggered automatically: when an agent opens (or force-pushes) a PR on its `agent-configs/` forge repo, hive-c0re's `/webhook/config-pr` @@ -187,6 +188,7 @@ kind-specific payload carrier. `source = approval:`; the worker fans the body out as inbox messages to each target at the scheduled time, recurring when `interval_seconds` is set. + ### Scheduled prompts (submit paths) diff --git a/docs/agent-lifecycle/persistence.md b/docs/agent-lifecycle/persistence.md index df72cc73..3ac0ef61 100644 --- a/docs/agent-lifecycle/persistence.md +++ b/docs/agent-lifecycle/persistence.md @@ -108,6 +108,7 @@ One table: - `events(id, ts, kind, payload_json)` — every `LiveEvent` the harness emits during turn loop execution. + The harness both writes and vacuums it — this used to be a host-side sweep, but hive-c0re runs as the unprivileged `hive-core` user under privsep and can't delete agent-owned files (host-side deletes hit @@ -128,6 +129,7 @@ host-side sweep was meant to prevent — but a compromised harness is already inside the container trust boundary ([`docs/trust-boundary/security.md`](../trust-boundary/security.md)), and these are ephemeral local artifacts, so cleaning them up where they live is the honest fix. + Path overridable via `HYPERHIVE_EVENTS_DB` (for dev / no-`/harness` setups). On open failure the `Bus` falls back to no-store mode @@ -238,6 +240,7 @@ harness keeps serving its web UI and MCP daemons but drives no turns, and inbox messages queue unacked until it's removed (see [turn loop](../turn-loop/README.md#the-loop)). + Unusually, it's read and written from **both** sides of the harness bind-mount, and that's the whole design: the harness stats it in-container via `hive-agent`'s `paths::paused_marker`, while hive-c0re @@ -248,6 +251,7 @@ dashboard toggle. Because the file itself is the only shared state there's no protocol between them, no round-trip into the container, and pause keeps working when the harness is wedged or the container is stopped. + It lives in `/harness/` rather than `/state/` deliberately: `/state/` is the agent's own space to fill, and this is harness control state. @@ -346,19 +350,23 @@ nothing argues for a parent reading it, let alone writing it. hive-c0re reads a child's harness dir **directly on the host** when it wants those stats, which needs no mount into the parent. + **`config` is read-only, including for the parent.** A config change is a PR on the child's config repo, made from a clone and merged after review — so the bind-mounted `config` dir is a *copy to read*, never a tree anyone edits in place. Mounting it writable would leave a second path to the same file that skips the review entirely, which makes the boundary a convention rather than a permission. + + ⚠️ Don't confuse it with the config-repo seeding hive-c0re does at spawn (`lifecycle::setup_proposed`): that writes the child's initial config repo as **hive-c0re, against the host path**, and `read_only` on a bind constrains writers *inside* a container only. The two are unrelated — conflating them can lead you to reason your way into thinking this mount should be writable when it shouldn't. + Per-child isolation still holds: a container only ever has its *own* dirs plus its direct children's bind-mounted, never a sibling's. @@ -481,10 +489,12 @@ so it survives restarts and redeploys. verification until the hook is re-registered with the new value. It's generated automatically on first start; there's nothing to configure. + If the file is unreadable at startup the daemon still starts and logs `webhook secret unavailable`; the webhook endpoint then answers 503 rather than accepting deliveries it can't verify. Everything else the controller serves is unaffected. + ## Run-time dirs @@ -587,6 +597,7 @@ librsvg) and forwards its store path as `HIVE_ICON_PNG` on the daemon unit, gated on `services.hyperhive.agent.icon != null`. No icon configured → the env is unset → `sync_avatar` returns early and sets no avatar. + Idempotency is **per-account**: an `avatar-icon-hash` file in each account's matrix-sdk `state_dir`. The daemon hashes the PNG bytes and skips the upload when unchanged, because every upload mints a fresh @@ -596,4 +607,5 @@ account gets its avatar when the `systemd.paths.hive-matrix-daemon` token watcher restarts the daemon (which re-runs the per-account bring-up), so no separate avatar trigger is needed. The daemon swallows avatar failures (logged, non-fatal) so they never break account bring-up or sync. + diff --git a/docs/getting-started/setup.md b/docs/getting-started/setup.md index 278f8ab1..cd284449 100644 --- a/docs/getting-started/setup.md +++ b/docs/getting-started/setup.md @@ -10,12 +10,16 @@ sequence. All `hivectl` commands below run as **root on the host** (not inside an agent container); the `request_*` steps run from ruth's own turn via the MCP tools. + + **Bringing up a hive that doesn't host its own swarm services?** Read [`swarm/secrets.md`](../swarm/secrets.md) first. Everything below assumes each credential is generated where it's read, which is true on an all-local deploy and not otherwise — that page says which files an operator has to place, and where. + + ## Step-by-step ### 1 · Forge @@ -157,7 +161,7 @@ leaves it alone. -Whether anything more is needed depends on +What else you need depends on `services.hyperhive.deploy.bao.seal`: - **`pkcs11`** (the default) — pkcs11 binds the key to the host's TPM, and @@ -180,8 +184,6 @@ the store can't hand you, being what opens it. ⚠️ Not the gateway's HTTPS ce store that took its identity from an authority it will itself distribute could never come up before that authority. -Making even the `init` unnecessary is tracked as a follow-up. - ### 4 · Swarm SSO (only when `deploy.authelia`) ⚠️ **Required to finish the install, not optional.** Authelia treats an @@ -287,17 +289,20 @@ See [`tools/hivectl.md`](../tools/hivectl.md) for every `hivectl` verb. ## Security notes + + - **No forge admin token is stored in any agent state dir.** Agents hold a regular agent token in their `forge-token` file; sensitive creds (the core token, the matrix admin token) live on the host. - All config changes (forge PRs on `agent-configs/`) go through operator approval — agents can't unilaterally rebuild containers, by design. See [`boundary.md`](../trust-boundary/boundary.md) and [`security.md`](../trust-boundary/security.md). -- **Telemetry ingest is authenticated per hive**, and the `hive` label comes - from which hive authenticated rather than from the payload — so no hive can - report metrics as another. A first-run all-local hive gets this with nothing - to configure; joining a swarm you don't host needs one secret copied across. - See [`observability.md`](../scheduler/observability.md#authenticated-ingest). +- **Each hive authenticates its own telemetry ingest**, and the `hive` label comes +from which hive authenticated rather than from the payload — so no hive can +report metrics as another. A first-run all-local hive gets this with nothing +to configure; joining a swarm you don't host needs one secret copied across. +See [`observability.md`](../scheduler/observability.md#authenticated-ingest). + Once the hive is running, ruth records anything it needs to remember across restarts in `/agents/ruth/state/notes.md`. diff --git a/docs/integrations/github.md b/docs/integrations/github.md index 8ea4fc4a..aefec8ae 100644 --- a/docs/integrations/github.md +++ b/docs/integrations/github.md @@ -12,11 +12,15 @@ injects the token into the agent's state dir out of band. ## Enabling + + The integration is **on by default** for every agent (`services.hyperhive.agent.github.enable = true`), inert until the operator provisions a PAT. No per-agent declaration is needed — an agent gains GitHub by having a PAT written to its token file. + + To turn it off for the whole hive, set the host option: ```nix diff --git a/docs/integrations/knowledge.md b/docs/integrations/knowledge.md index 47d36fc3..120ef6be 100644 --- a/docs/integrations/knowledge.md +++ b/docs/integrations/knowledge.md @@ -14,6 +14,8 @@ Inside any agent container: /knowledge/README.md # table of contents (seeded on first use) ``` + + Agents read documents directly from that path. The mount is read-only — agents never write through it. To contribute, use the `hive-forge` AGit flow (no fork needed — see @@ -21,6 +23,8 @@ read-only — agents never write through it. To contribute, use the the local clone updates automatically (see [Sync mechanism](#sync-mechanism) below). + + ## Repository layout Canonical forge location: `internal/knowledge` (org `internal`, @@ -53,8 +57,8 @@ pull`, so agents see the new content on their next turn. URL, so a second registration against the same repo doesn't add a recipient — it takes delivery away from whoever registered first. Earlier versions had each hive register its own; hive-c0re now - removes its own leftover at startup, so no operator step is needed - to migrate. + removes its own leftover at startup, so migrating needs no operator + step. 2. **Periodic pull** — a background task in `hive-c0re::main` pulls on a fixed cadence as a fallback (webhook missed, c0re @@ -86,12 +90,15 @@ before returning. ## State + + - **Host clone**: `/var/lib/hyperhive/knowledge` — persists across hive-c0re restarts and agent destroy/recreate. Deleted only by manual operator action. - **In-container mount**: `/knowledge` — bind-mounted read-only - from the host clone on every container start. Gone when container - is stopped; reappears on next start with the current clone state. +from the host clone on every container start. Gone when container +is stopped; reappears on next start with the current clone state. + The mount deliberately **excludes `.git`**: the host clone embeds the `core` token in `.git/config` (it rides the clone URL), so hive-priv overlays an empty diff --git a/docs/integrations/matrix.md b/docs/integrations/matrix.md index 1802bc4b..cb3870ef 100644 --- a/docs/integrations/matrix.md +++ b/docs/integrations/matrix.md @@ -92,9 +92,11 @@ delegation (the latter lives in `gateway.md::Discovery flow`). ## Provisioning flow (appservice) + Registration is closed. The hive's own **appservice** creates accounts: hive-c0re holds the appservice token, agents never see it, and an agent only ever receives its own `access_token`. + The appservice has no URL (`url: null` in its registration), so the homeserver never calls out to it and there is no service to run. What the @@ -175,6 +177,7 @@ Nothing to do, and nothing to time. The activation script mints the appservice token and renders the registration before the homeserver restarts, so the first boot after the switch already has both halves. + - **Existing accounts keep working.** An access token lives on the device that minted it; removing the registration token touches no device, no account and no session. `login_with_password` stays on, so @@ -198,6 +201,7 @@ restarts, so the first boot after the switch already has both halves. token only until the first successful read. See [`../swarm/secrets.md`](../swarm/secrets.md) for how that mint stays idempotent across runs. + @@ -239,6 +243,7 @@ into it. This gives the operator a single Space in FluffyChat or any Matrix client that groups all agent-to-agent + operator rooms in one place. + The sweep also provisions a default **`hive-chat` room** as an `m.space.child` of the Space. Joining a Space doesn't autojoin child rooms — the explicit room entry ensures the operator and every @@ -246,6 +251,7 @@ agent can find a common chat room without manual setup. Room join is restricted (any Space member including the operator can join; agents are explicitly invited). Room version pinned to 10 for the restricted join floor. + **State**: hive-c0re persists both room IDs to `/var/lib/hyperhive/matrix/` (mode `0600`, owned by the hive-c0re service user): @@ -270,9 +276,9 @@ services.hyperhive.swarm.matrix = { ``` **`trustedServers`** (default `[]`) — list of peer homeserver names -whose signing keys tuwunel will fetch and trust. Federation is enabled +whose signing keys tuwunel will fetch and trust. tuwunel enables federation at the protocol level from first boot (`allow_federation = true`) but -tuwunel trusts no remote homeserver until you list it here. For a closed +trusts no remote homeserver until you list it here. For a closed single-hive deployment the default empty list is correct — add peer hive domains here when connecting hives into a swarm (see [`docs/swarm/`](../swarm/README.md)). @@ -296,14 +302,14 @@ surprising behaviour: SSO is unconditional, so the three below are requirements of running a homeserver at all rather than of a setting: -- **`sso.clientSecretFile` is required** — fails at eval, not at boot: +- **Set `sso.clientSecretFile`** — fails at eval, not at boot: tuwunel reads its identity providers from the config file, so a half-configured one can stop the homeserver from starting outright rather than merely hiding a login button. On a host that also runs the swarm's authelia it's wired up for you. -- **`swarm.authelia.url` is required** — without a provider URL there +- **Set `swarm.authelia.url`** — without a provider URL there is nothing to discover against. -- **`gatewayHost != null` is required** — the SSO callback URL is +- **Set `gatewayHost != null`** — the SSO callback URL is format-locked to `/_matrix/client/unstable/login/sso/callback/`, and the identity provider needs a public name to redirect the browser to. diff --git a/docs/networking/gateway.md b/docs/networking/gateway.md index d2035515..eb344256 100644 --- a/docs/networking/gateway.md +++ b/docs/networking/gateway.md @@ -19,7 +19,9 @@ This host's nginx fronts the hyperhive web surfaces running on it — next to hi Only the host that **runs** authelia declares the authelia vhost, not every hive that uses it — a client hive knows the swarm's `authelia.url` but must not answer for a name it doesn't serve. Its server name is exactly `swarm.authelia.domain`: authelia validates `authelia_url ⊂ session cookie domain` at startup, so a near-miss is a container that refuses to boot. It carries no `auth_basic` — the login page must not sit behind the login mechanism it replaces — and sets the four `X-Forwarded-{Proto,Host,Uri,For}` headers, since authelia decides by the *original* request rather than the hop it sees. + ⚠️ **A `502` from this vhost typically means authelia has no users yet, not that the proxy is misconfigured.** Authelia treats an empty user store as a fatal startup error, so an enabled-but-unbootstrapped swarm crash-loops the container while the vhost in front of it works perfectly. Check `journalctl -M swarm-authelia -u authelia-swarm` before suspecting anything here; the bootstrap step is in [`swarm/sso.md`](../swarm/sso.md). + Per-agent UIs stay sub-path, forge and matrix get sub-domains — see [Sub-domain shape (rationale)](#sub-domain-shape-rationale) below for why. @@ -34,7 +36,9 @@ Operator points client at ``. Sequence: matrix-dart-sdk (FluffyChat etc.) hardcodes `https` for the well-known fetch regardless of input scheme, so the discovery endpoint MUST be https — see "Self-signed TLS" below for the cert generation that backs the default-on path. + Federation peers fetch `.well-known/matrix/server` → `{"m.server":"chat.:"}` (the federation delegation always carries an explicit port, even the HTTPS default 443 — the https-implies-443 elision only applies to the client base_url above). Gateway only listens on configured `port` (+ `httpsPort` when TLS on); cross-hive federation needs either an SRV record (`_matrix._tcp.chat.` → port 80 / 443) OR `matrix.openFirewall = true` so peers reach tuwunel's federation port directly. Hyperhive is closed/internal in most deployments, so this rarely bites. + ## SPA fallback (Accept-header pattern) @@ -134,12 +138,14 @@ now set unconditionally for every agent. The mechanism: retry and report on (`RELOAD_PENDING`), not two units racing on an inotify event. + c0re regenerates `agents.conf` (and triggers a reload) on two triggers: every topology change (new/removed agents) and every 10s marker poll tick (`agent_sockets::spawn_poll`). `write()` is idempotent — skips the rename when content is unchanged. `gateway_nginx::reload_if_pending` automatically retries failed reloads on subsequent poll ticks. + `agents.conf` uses atomic `.tmp` + `rename()` writes so a crashing c0re process never leaves a partial or unparseable file behind. @@ -229,7 +235,9 @@ swarm-services fallback below is for. **Cert shape**: leaf subject CN = bare hive domain; subjectAltName is `` plus wildcard `*.`, so all current and future sub-domain vhosts validate under the same leaf + the hive CA. You can't add a swarm service whose name is *not* under this hive's domain here — the hive CA is name-constrained to ``, and a violating SAN invalidates the whole leaf, not just that name. Those names get the swarm-services leaf instead ([`swarm/ca.md`](../swarm/ca.md)). + **Rotation**: `hive-tls-ca.service` is idempotent — it re-signs the leaf when it's missing or within 30 days of expiry, always under the same CA (so consumer trust is undisturbed). It regenerates the CA itself only if missing or already expired. To force a leaf rotation, delete `gateway.pem` under the state dir and restart the unit, then reload `nginx`. + **Cert prompts**: browsers still warn once per host until the operator adds the hive's `trust-bundle.pem` to the browser/OS trust store (an anchor, not the leaf, is the thing to trust). A separate mechanism wires agent trust (see the agent-trust work for `/run/hive-ca`). @@ -292,6 +300,7 @@ TLS (see [TLS modes](#tls-modes) above). Every agent hashes into the same port range (no special case), so one range opening covers every container. + The dashboard port (`services.hyperhive.c0re.dashboardPort`, default 7000) is *not* listed in either case — it binds `127.0.0.1` only, so a firewall hole would be a no-op. Remote dashboard access flows through the @@ -299,6 +308,7 @@ gateway. Operators who opt out of the gateway lose external dashboard reach by design — the surface is privileged (approve / deny / destroy), and operators must not expose it without a real reverse proxy in front. + ## `HIVE_FORGE_URL`: agents reach the forge via the gateway by domain @@ -308,7 +318,7 @@ shared-netns mode no longer exists), so agents run in a private netns and can never reach the host's loopback. `nix/host-modules/hive-c0re/environment.nix` sets `HIVE_FORGE_URL` to `http://` (default `forge.` — a swarm runs -one forge; `services.hyperhive.domain` is required). Agents +one forge; you must set `services.hyperhive.domain`). Agents get the bridge dnsmasq as their resolver, resolve the hostname → bridge IP, then reach nginx on port 80 (the bridge firewall opens 80+443). nginx proxies to forgejo — the same path an operator browser @@ -357,6 +367,7 @@ only if you already have another process bound to 3000. uses for `git clone/push/pull` over SSH (`git@:owner/repo.git` via `-p 2222`). Port 22 stays alone on the host for openssh. + `openFirewall` (default **false**) controls whether the host firewall opens `httpPort` and `sshPort`. Off by default (secure by default): agents reach Forgejo through the gateway (`forge.` on @@ -365,6 +376,7 @@ the bridge), not the raw port, so no firewall hole is needed. Flip to - The operator's browser to reach `http://:/` directly (not behind the gateway). - External git clients that push/pull via SSH directly to the host. + Forgejo served through the gateway (`deploy.forgejo.behindGateway = true`) does not need `openFirewall` — the gateway's own `openFirewall` option covers @@ -495,12 +507,14 @@ palette (`#1e1e2e` bg, `#cdd6f4` text, `#cba6f7` heading). No dependencies on the frontend dist — these pages render even when hive-c0re itself is down. + Scope is intentionally narrow: a route earns a custom page when the default status code would point at the wrong component. The per-agent routes qualify (a 502 there means the harness is restarting, not that the gateway is broken), and so does `auth.` — a dead authelia upstream almost always means the user store was never bootstrapped, and a bare 502 blames the proxy, which is the one part that's working. + Forge / matrix / fluffychat still get nginx defaults: their upstreams being down means what the status code says, so a themed page would add @@ -508,10 +522,12 @@ styling and no information. ## HTTP Basic auth + `services.hyperhive.gateway.auth.enable = true` gates every request to the main vhost (`_`) behind HTTP Basic auth. nginx's built-in `auth_basic` module validates credentials; no extra service or host-side daemon is required. + **Setup:** @@ -522,10 +538,12 @@ services.hyperhive.gateway.auth = { }; ``` + The credential store lives at the fixed path `/var/lib/hive-gateway/conf/gateway.htpasswd` on the host. A tmpfiles rule pre-creates the file on first boot; no manual path configuration is required. nginx reads it at that path directly. + Manage users with `hivectl gateway`. `hivectl` sends the request over the host admin socket and the `hive-c0re` daemon performs the write at its @@ -545,9 +563,11 @@ hivectl gateway delete-user bob hivectl gateway list-users ``` + The daemon hashes passwords with BCrypt (cost 12) and writes `$2y$`-prefixed hashes that nginx accepts natively. No external `htpasswd` binary is required. + **What's not gated:** per-agent UI routes emitted into `agents.conf` (served under `/agent//`) inherit no auth from `/` — nginx @@ -612,6 +632,7 @@ TLS-less mode that could violate it. ## Dialing another vhost by name (`verifiedProxyTo`) + `vhost-lib.nix`'s `verifiedProxyTo` builds the `proxy_ssl_*` / `proxy_set_header` block a module uses to dial another service on this same gateway BY NAME over https, verified. One definition rather than a @@ -619,6 +640,7 @@ copy per module: nginx verifies nothing by default (`proxy_ssl_verify` is off), so a `proxy_pass https://…` without these lines is encrypted and unauthenticated. That failure is invisible — it works, and keeps working, against any certificate at all. + Every line earns its place, each confirmed against a real nginx with the opposite arm run as a control: diff --git a/docs/networking/network.md b/docs/networking/network.md index 5a49f16b..a288374c 100644 --- a/docs/networking/network.md +++ b/docs/networking/network.md @@ -15,8 +15,8 @@ Configured via `services.hyperhive.network.*`. One picture of the whole hive — two planes: **infra containers share the host netns** and bind host ports directly; **compute containers (agents + CI) each get a private netns** behind -the bridge. The unix-socket control plane rides the VFS and is -untouched by any of it. +the bridge. The unix-socket control plane rides the VFS, and none of +that touches it. ``` internet @@ -192,12 +192,16 @@ listed TCP port `P` on the bridge-interface `allowedTCPPorts`, so an agent can connect to `:P` (point the collector endpoint at `http://:4318`, default `http://10.42.0.1:4318`). + + This is **firewall-only**: the host service must bind an address reachable from the bridge — `0.0.0.0` or the bridge IP — not loopback only. The bridge→`127.0.0.0/8` DROP rule (below) is unchanged, so a service bound to `127.0.0.1` only stays unreachable; rebind it to `0.0.0.0`. + + The port is reachable by **every** agent on the bridge subnet (like DNS/gateway), so only expose services safe for any agent to reach. diff --git a/docs/networking/snapshot-store.md b/docs/networking/snapshot-store.md index d06f171b..2eb733db 100644 --- a/docs/networking/snapshot-store.md +++ b/docs/networking/snapshot-store.md @@ -188,25 +188,31 @@ of `state/`, `claude/` and `harness/` (see section](../agent-lifecycle/persistence.md#btrfs-subvolumes-for-varlibhyperhiveagentsname) for how and when hive-c0re creates that subvolume). Consequences: + + - The Claude session (`claude/`) travels, so a restored agent keeps its live `--continue` session rather than needing to log in again. - `harness/` travels too, including `harness/bash-tasks/`. Task output - is part of an agent's working continuity, so this is wanted --- but it - means anything that has ever leaked into a task's captured output is - in the retained snapshots as well. +is part of an agent's working continuity, so this is wanted --- but it +means anything that has ever leaked into a task's captured output is +in the retained snapshots as well. + It does **not** cover the agent's applied config (`/applied//`) or its topology entry, both of which live outside the subvolume. A restore -therefore yields an agent's memory without its definition; closing that -gap is tracked separately. +therefore yields an agent's memory without its definition. ### Retention + + Retention lives on the _sending_ side (last-N by count, swept periodically), not here. Count rather than age is deliberate: a count is bounded by construction, whereas an age policy silently scales disk usage with how hot a hive runs. + + Per-agent or per-hive `btrfs qgroup` quotas aren't configured yet. Without them one runaway hive can fill the store and take out every other hive's snapshots. diff --git a/docs/process/conventions.md b/docs/process/conventions.md index 4ea19ec5..8bbffe1a 100644 --- a/docs/process/conventions.md +++ b/docs/process/conventions.md @@ -132,12 +132,14 @@ always passes `wait_seconds: None`, an immediate peek. Per-row bookkeeping inside the broker: + - `delivered_at = NOW` set on every popped row. - Each recipient has an in-memory `unacked_ids` list of every row delivered since the last `AckTurn`. - `redelivered = true` on a row if `RequeueInflight` resurfaced it (the harness prepends a "may already be handled" hint when this flag is set so the per-message warning is visible). + `AgentRequest::AckTurn` closes out the in-memory list — the harness fires it after `TurnOutcome::Ok`, marking every message popped since @@ -269,7 +271,7 @@ changes, and deserialization leniently accepts both the string form and the legacy bare integer (rolling-deploy skew, persisted blobs). **Input-direction** fields agents compute as epoch (`first_fire_at_unix`, schedule-edit `next_fire_at_unix`, `Wakeup::At`) stay integers. The -`*_unix` field *names* are kept for now — renaming is the wire-types +`*_unix` field *names* stay for now — renaming is the wire-types refactor's concern. The dashboard frontend parses via `util.js::epochSec` wherever it needs arithmetic and feeds the string straight to `new Date(s)` for display. diff --git a/docs/process/gotchas.md b/docs/process/gotchas.md index 9ed59f4b..6401176e 100644 --- a/docs/process/gotchas.md +++ b/docs/process/gotchas.md @@ -93,6 +93,8 @@ Two things to get right when a daemon needs outbound TCP: enumerate local addresses before it returns any, so name resolution fails without it even when the unit allows `AF_INET`. + + **The directive is a claim about what the program does, and nothing re-checks it when the program changes.** A unit that only served a unix socket when it was written is correct at `[ "AF_UNIX" ]` and silently wrong @@ -101,6 +103,8 @@ the client — and when narrowing it, prefer a test that derives the required families from the code (which fails on the _next_ client too) over one that asserts today's list. + + ### `register_agent` is idempotent Drops any prior socket task before rebinding. Required so a @@ -114,7 +118,7 @@ socket without needing a clean reinstall. `claude-code` comes from the flake's main `nixpkgs` (nixos-26.05). It's unfree, so the agent modules set `config.allowUnfreePredicate` at the container level to allowlist `claude-code` specifically — -scoped, only this one package. This is needed because each per-agent +scoped, only this one package, because each per-agent `nixosConfiguration` evaluates its own nixpkgs instance and the operator's host-level `allowUnfree` does **not** propagate in. Operators don't need to set anything on their side. @@ -138,6 +142,8 @@ reference-less `-source` (so the runtime closure never arrives), and pure evaluation rejects. `services.hyperhive.agent.docs.source` gets away with being an input only because a docs tree has no runtime dependencies. + + The `storePath` trap is worth spelling out, because it's not confined to options the operator writes: **any** option of type `package` fed a store-path _string_ coerces through `lib.toDerivation`, i.e. @@ -149,6 +155,10 @@ container as text in a real derivation — a symlink farm built from the interpolated string — before it can go anywhere a package is expected. + + + + The catch is that a path written into a generated flake is text, not a reference — the container's closure doesn't keep the binary alive. The **host** does: it interpolates the package into @@ -160,6 +170,8 @@ the hive's `claude` out from under it. The price of the root is that `nix-collect-garbage` can't reclaim an old `claude-code` until every agent has rebuilt past it and the old generations are gone. + + ### Claude credentials are per-agent `/var/lib/hyperhive/agents//claude/` bind-mounts to @@ -315,6 +327,8 @@ CI on drift). ### Split asset derivations away from the rust workspace + + `nix/packages/assets.nix` builds the branding SVG/PNG family + claude system-prompt template + claude-settings JSON as its own derivation, separate from the hive-ag3nt / hive-c0re crates. Reason: when the @@ -327,6 +341,8 @@ its own — the split breaks the coupling at the derivation boundary. build time; librsvg dependency lives here, not in the rust derivation's `nativeBuildInputs`. + + ### `nix fmt` fails in a git worktree with "object not found" `nix fmt` (and any `nix` command that fetches a `git+file://` flake diff --git a/docs/process/pr-review-gate.md b/docs/process/pr-review-gate.md index d8fd1960..1dc605a6 100644 --- a/docs/process/pr-review-gate.md +++ b/docs/process/pr-review-gate.md @@ -38,6 +38,8 @@ independently. ## What arming automerge actually means + + Automerge isn't "no human ever looked at this." Whoever arms it has already judged the PR sound at a coarse level — the signal it sends is roughly _"apart from maybe minor tweaks a reviewer can still catch, @@ -46,6 +48,8 @@ already happened. No large changes are expected to surface after that point — a reviewer's job past that point is to flag it if one does, not to assume none ever will. + + The practical consequence for a reviewer: on a repo where someone with write access may already have armed automerge before your review lands, a plain `APPROVED` can diff --git a/docs/scheduler/ci.md b/docs/scheduler/ci.md index 983f166e..47be274b 100644 --- a/docs/scheduler/ci.md +++ b/docs/scheduler/ci.md @@ -31,6 +31,8 @@ writeup. ## CI checks + + Several jobs run on every PR (and on `workflow_dispatch` for manual re-triggers), defined in [`.forgejo/workflows/ci.yml`](../../.forgejo/workflows/ci.yml). The first four @@ -41,6 +43,8 @@ gating on the full job's standing warning/suggestion backlog, but flipping that switch on the forge is a separate operator action, not something this table can assert ahead of it happening. + + | Job | What it runs | Required? | | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | | **nix flake check** | treefmt formatting, `cargo clippy -D warnings`, `cargo test`, module evaluation | yes | @@ -54,6 +58,8 @@ table can assert ahead of it happening. `hive-forge ci-rerun --pr N` dispatches a `workflow_dispatch` retrigger without an empty commit. + + **`ci-rerun --pr` verifies the code but doesn't reliably move the PR's own status checks.** Measured directly (raw `GET /repos/.../actions/tasks` JSON): a genuine PR-triggered run carries `event: pull_request` with the @@ -70,6 +76,8 @@ ci-log --run --job 0` shows the code green (verdict is the last line) but the status is stuck, ask the operator to select "rerun" in the forge web UI — it's CSRF-gated, so only they can do it. + + ### Running checks locally Don't run `nix flake check` directly — it dispatches to the shared build farm and @@ -144,12 +152,16 @@ Gated on `HYPERHIVE_FORGE_CI_ENABLED` (the nix module sets it on `hive-c0re.serv ## Actions checkout mirror + + When `deploy.forgejo.ci.enable` is set, hive-c0re autoseeds an `actions/checkout` pull-mirror on the local forge and sets Forgejo's `DEFAULT_ACTIONS_URL` to point at the local instance. This means CI `uses: actions/checkout@vN` steps resolve entirely on loopback — no external DNS on the CI critical path. + + **hive-c0re** itself seeds the mirror during its forge provisioning sweep (`forge/repos.rs::ensure_mirrors`). The nix module forwards the effective mirror list as `HYPERHIVE_FORGE_MIRRORS` in the diff --git a/docs/scheduler/coordinator.md b/docs/scheduler/coordinator.md index b4e38c6f..34fcf982 100644 --- a/docs/scheduler/coordinator.md +++ b/docs/scheduler/coordinator.md @@ -53,6 +53,8 @@ Nix-heavy — hold one of the `buildSlots` permits for the node's duration: Cheap — no build slot: + + | Node | Behavior | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `MergeVerify` | the deploy's pre-merge gate — PR-head drift check, fetch, `verify_commit` eval. Mutates nothing, so a rejection here needs no compensation | @@ -85,6 +87,8 @@ Cheap — no build slot: | `KnowledgePull` | one-shot boot-time `/knowledge` pull (`knowledge::pull`), reconciling commits that landed while `hive-c0re` was down. Same rationale as `MatrixSweep`: the periodic hourly re-pull stays a background loop | | `WantedPull` | one-shot boot-time pull of the agent set the swarm controller declares for this hive (`wanted::pull`), converging the agents it names. No background loop behind this one — boot is the whole cadence; the deploy event (`swarm_status`) is the fast path, this repairs a missed one. Agentless | + + Deliberately, **no `GitCommit` node** exists: `meta.rs` fuses each mutation with its commit under its internal `META_LOCK` mutex, so a standalone commit node would open a dirty-working-tree window between nodes. @@ -206,9 +210,13 @@ they surface under that DAG's id in the same loop — no separate child DAGs. ### Scheduler semantics + + A node is **ready** when it's `Queued`, every dep is satisfied, and its resources are free. Resources: + + 1. **Build slots** — `services.hyperhive.c0re.buildSlots` permits (default 1), held by nix-heavy nodes for the node's duration. 2. **Per-agent lifecycle lease** — keyed on the **node's** agent (agent is @@ -251,18 +259,21 @@ node, with the omission below it documented on the brace itself. Two consequences worth knowing: + + - **Flattening a chain under a brace is safe.** The stop chain used to nest `Signal` over `Drain` over `StopForUpdate` specifically so the lease stayed continuous — as independent siblings each would acquire it separately and leave a gap another DAG could claim the agent in, mid-bounce. A brace supplies that continuity directly, so the nesting is no longer load-bearing. - **Observability is unaffected.** `running_transients` keys off a node's - _payload_ agent, not off a declared lease edge, so every child still lights its - own dashboard pill and still reports its own `takes_container_down` to the - crash watcher. A brace itself reports `false`: it parents the stopping nodes - but doesn't stop anything, and claiming otherwise would widen crash - suppression across the build and tail, where a vanished container is still a - real crash. +_payload_ agent, not off a declared lease edge, so every child still lights its +own dashboard pill and still reports its own `takes_container_down` to the +crash watcher. A brace itself reports `false`: it parents the stopping nodes +but doesn't stop anything, and claiming otherwise would widen crash +suppression across the build and tail, where a vanished container is still a +real crash. + Among simultaneously ready nodes competing for a resource, DAG-submit order wins (FIFO) so bulk operations drain predictably. The scheduler also owns the @@ -276,8 +287,7 @@ reconcile_), so there is no durable-recovery machinery to go wrong. ### Cancel, history The agent-per-node move removed submit-time dedup (a multi-agent DAG -has no single agent to key a dedup on), so every submit enqueues a fresh DAG; -whether any dedup needs reintroducing is tracked as a follow-up. +has no single agent to key a dedup on), so every submit enqueues a fresh DAG. Cancel only applies to DAGs that are still fully queued (an in-flight nix build isn't interruptible) — each op is one DAG now, so there are no child DAGs to cascade to. diff --git a/docs/scheduler/jobq.md b/docs/scheduler/jobq.md index 9035f987..2aab248e 100644 --- a/docs/scheduler/jobq.md +++ b/docs/scheduler/jobq.md @@ -37,6 +37,8 @@ Each **row** you see in a queue view (the **BU1LDS** page's R3BU1LD QU3U3 nested under it are that job's steps, in order (occasionally a couple run side by side). A step shows one of: + + | Glyph | Meaning | | ----- | ------------------------------------------------------- | | `⏸` | queued, waiting its turn | @@ -47,6 +49,8 @@ side by side). A step shows one of: | `⊘` | cancelled | | `·` | skipped (not needed for this run) | + + A step that isn't needed for a given run stays in the graph as `·` rather than being absent from it, so the same kind of operation keeps a recognizable shape run to run, whichever steps it actually needed. diff --git a/docs/scheduler/observability.md b/docs/scheduler/observability.md index b7d17749..6172a469 100644 --- a/docs/scheduler/observability.md +++ b/docs/scheduler/observability.md @@ -68,6 +68,8 @@ doesn't change that.** Treat it as a convenience for grouping dashboards, never as evidence of which container produced a sample: any agent that can reach this hive's collector can label its data as any other agent. + + **Logs ride the same hop, and a journal carries more than a counter does.** Each agent container forwards its own journal through this port — every unit in it at `info` and above, not an allowlist. That's the harness, the MCP daemons and @@ -76,6 +78,8 @@ container where before only counts did. The trust boundary is unchanged (same destination, same credential, and an agent could already send arbitrary OTLP); what changes is how much detail leaves by default. + + Worth spelling out, because two different hops are in play and only one of them carries a credential: @@ -190,9 +194,13 @@ the `hive-br0` bridge. The service must also bind an address the bridge can reach — a `127.0.0.1`-only listener stays unreachable no matter what the firewall allows. See `docs/networking/network.md::Reaching host services` for details. + + ⚠️ **None of this is needed for hyperhive's own telemetry** — `otel.enable` contributes the collector's port and derives the agent-facing endpoint itself. + + ## Built-in resource labels The harness sets the OTLP variables (`OTEL_EXPORTER_OTLP_ENDPOINT`, `_PROTOCOL`, @@ -250,12 +258,16 @@ while lines that never had one signal nothing of the sort. ## Host-emitted container-resource metrics (hive-c0re) + + When OTEL is enabled, **hive-c0re itself** also exports each agent container's resource load — the same cgroup gauges shown on the dashboard LOAD tab — to this hive's own collector, exactly like an agent does and with no separate toggle. These come from the host, not the in-container Claude SDK, so they cover containers even when their agent is idle. + + Emitted via the OpenTelemetry Rust SDK, using the [semconv `container.*`](https://opentelemetry.io/docs/specs/semconv/system/container-metrics/) metric names + the standard `container.name` attribute where a spec metric @@ -278,13 +290,19 @@ alongside the spec `container.cpu.time` counter for convenience). Hive labels (`hive`, `swarm`, …) ride on the resource via `extraResourceAttributes`. + + Cadence follows `metricIntervalMs` (default 60s). Transport is OTLP/HTTP (JSON) to the hive collector's bridge address, with no auth header — that first hop is unauthenticated for every producer on this host, and the upstream credential stays on the swarm tier. + + ## Agent-emitted per-turn metrics (`hive-agent`) + + When OTEL is enabled, the harness itself (`hive-agent`) exports one small set of metrics per claude turn, recorded the moment the turn ends (not polled). These are deliberately the fields Claude Code's own built-in export (see @@ -293,6 +311,8 @@ turn, its own outcome classification, the loose-ends backlog, and session boundaries. Token usage, cost, and tool-call counts are **not** duplicated here; that's already covered by Claude's own export. + + | Metric | Unit | Kind | Attributes | | -------------------------------------- | ---- | --------- | ----------------------------------------------------------------------------------------------------------- | | `hyperhive.agent.turn.duration` | `ms` | histogram | `wake_from`, `result_kind`, `model` | @@ -312,6 +332,8 @@ records them (every turn, always). ## Hive-scoped metrics (hive-c0re) + + hive-c0re measures everything above **per agent**, tagged with the hive it runs in. It measures these three per **hive** instead, and they carry no `agent` label — so a hive @@ -319,6 +341,8 @@ that hosts no agents still reports, and "this hive is quiet" is distinguishable from "this hive is gone." Select them with `{hive!="",agent=""}`. + + | Metric | Unit | Kind | Meaning | | ------------------------- | ---- | ----- | -------------------------------------------------------------------------------------------------------------------- | | `process.uptime` | `s` | gauge | seconds since this hive's `hive-c0re` started exporting; a restart reads as a drop to ~0 | @@ -420,6 +444,8 @@ overriding Claude Code's default of DELTA. This avoids silent metric drops in Prometheus-family backends (including Grafana LGTM / Mimir) that don't ship a delta-to-cumulative processor. + + **`hive-metric` counters are the one exception**, reporting delta by default (see above) — programmatically set on the exporter, which overrides this container-wide env var for that tool specifically. `--type gauge` is @@ -428,3 +454,5 @@ runs a `deltatocumulative` processor ahead of export, so a delta `hive-metric` counter still lands in VictoriaMetrics as a cumulative series — the standard `rate()`/`increase()` idioms work on it exactly like any other counter in this system, no special query needed. + + diff --git a/docs/swarm/README.md b/docs/swarm/README.md index 1177afd3..be110ce7 100644 --- a/docs/swarm/README.md +++ b/docs/swarm/README.md @@ -40,6 +40,8 @@ services.hyperhive = { }; ``` + + `swarm.domain` and `hiveName` are **required** whenever hyperhive is enabled; eval fails with a hint naming each. Neither defaults, because a guessed value here is a wrong hostname that evaluates cleanly @@ -47,7 +49,9 @@ and deploys — an eval failure asking the operator to write the address down is the cheaper outcome. **Upgrading past this release means setting both once.** -`domain` is required too, but you no longer _write_ it: it's read from + + +You must still set `domain` too, but you no longer _write_ it: it's read from this hive's own entry in the directory, whose `domain` defaults to `.`. A conventional swarm states no addresses at all, and a hive addressed by something else states it in the one place @@ -276,8 +280,8 @@ If one host is behind NAT and can't accept incoming connections, only that host needs a null `wireguardEndpoint` on the peer config — the other side initiates. With keepalive on, the NAT hole stays open. -If both hosts are behind NAT, a STUN relay or a third host (exit node) -is required. Out of scope for v0. +If both hosts are behind NAT, you need a STUN relay or a third host +(exit node). Out of scope for v0. ## Snapshot store @@ -458,12 +462,16 @@ leftover at startup. A webhook has exactly one target URL, so per-hive registration never added a recipient — it took delivery away from whichever hive registered before it. + + **The `agent-configs` org isn't yet.** Each hive still registers its own `pull_request` hook there, so that repo has two — the hive's and the controller's — and **both are expected; don't delete either.** Removing a hive's stops it acting on config PRs; removing the controller's just gets recreated on its next start. + + Nothing to configure. The controller registers the hooks only when this host also serves the swarm UI vhost — that's what publishes the endpoint, and a hook the forge can't reach would collect failed diff --git a/docs/swarm/ca.md b/docs/swarm/ca.md index ec21ec5d..0778d1d1 100644 --- a/docs/swarm/ca.md +++ b/docs/swarm/ca.md @@ -71,9 +71,13 @@ its own subdomain — enforced by every verifier rather than by convention. The constraint excludes both IP families as well, since a permitted-DNS-only constraint says nothing about IP SANs. + + The root is issued with `pathlen:1`: it may sign hive CAs, and those may sign leaves, and the chain stops there. + + ## What to hand a peer `hivectl peer-config` prints the `services.hyperhive.swarm.hives.""` @@ -103,6 +107,8 @@ per-hive file. ## Adopting the hierarchy on an existing hive + + A hive that predates the swarm root carries a self-signed `ca.pem`, and adopting the hierarchy means replacing it. That invalidates an anchor consumers already trust, and they refresh on their own schedule — agents @@ -110,6 +116,8 @@ only pick up new trust when their container restarts, peers only on their own rebuild. **Who is allowed to decide that's what splits the two cases.** + + ### Where this host owns the root (`autoConfigure`) Adoption happens by itself, once. `hive-tls-ca.service` notices that @@ -141,10 +149,14 @@ rm /ca.pem + Failing rather than warning is deliberate: a hive whose CA doesn't chain to the root it received is misconfigured, and a warning in a build log isn't something anyone reads twice. + + To keep the current CA on purpose — a hive that deliberately stays outside the hierarchy, or one mid-migration — `touch` the marker file named in the message. That's a decision, and it's recorded as one. diff --git a/docs/swarm/credentials.md b/docs/swarm/credentials.md index 1f6c9ea3..c1bace54 100644 --- a/docs/swarm/credentials.md +++ b/docs/swarm/credentials.md @@ -1,11 +1,15 @@ # Credentials: the target shape + + The swarm's credential store is bao. This page describes the shape every credential is meant to have — who mints it, who reads it, and how it renews — not what's on disk today. [`secrets.md`](secrets.md) remains the map of the files that exist right now; this page replaces it, and `secrets.md` gets deleted, once the swarm's credential path matches what's described below. + + **Public material is a value.** The store hands a certificate or a public nkey to every client that connects, so it's a fine place for that material. Nothing below is about those. @@ -48,6 +52,8 @@ path at runtime — not a path on disk, and not a unit whose job is to turn a store value into a file. A renewal cell may never read `NONE`: state the strategy for every credential, including the mTLS leaf. + + | store path | minter | reader — pulls at runtime, holds in memory | renewal | | -------------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- | -------------- | | `swarm/agents//matrix/` | `swarm-controller` | the agent container itself, under the certificate its hive passed in | must be stated | @@ -57,6 +63,8 @@ strategy for every credential, including the mTLS leaf. | `swarm/services//oidc/client` | authelia | the service process that presents the client secret, under the certificate of the host it runs on | must be stated | | _(not in the store)_ a hive's mTLS leaf | the store's own PKI, or an operator placing it by hand | its own client, off disk — the exception above, because it's what makes every other row's pull possible | must be stated | + + **An agent's mTLS leaf is in the store; a hive's isn't, and the difference isn't an inconsistency.** The rule the exception protects is that nothing can fetch from the store the credential it would need in order to fetch. A diff --git a/docs/swarm/secrets.md b/docs/swarm/secrets.md index a1de5c0a..e3c2e0ce 100644 --- a/docs/swarm/secrets.md +++ b/docs/swarm/secrets.md @@ -118,7 +118,7 @@ eval, naming the option it wants. That's deliberate: a queue that started without them would accept `CONNECT {"user":"auth"}` from anyone sharing the host's network namespace, and nothing would look wrong until somebody connected. -**All four or none** — the seed paths are required too, not just the public +**All four or none** — you must supply the seed paths too, not just the public keys. They're two halves of the same pair: the server verifies with the public half, the responder signs with the private one. Supplying only the public keys used to pass eval and leave the queue with an auth-callout nobody answers, which @@ -195,7 +195,7 @@ the client id it authenticates, because that's how a queue client reads them — the secret by path, the id by value. No local fallback exists, and none is possible, so absent files mean this hive's agents don't connect, which is what a swarm looks like before the publisher on the authelia host has run. The -reader runs before `hive-c0re.service` and is wanted (not required) by it, so +reader runs before `hive-c0re.service`, which wants it (doesn't require it), so an agent container never renders ahead of the credential; an unreachable store delays the daemon's start rather than failing it. @@ -231,9 +231,9 @@ exists so a host holds **one** out-of-band secret, its client certificate, and reads everything else with it. Two things follow, and `swarm-grafana.nix` asserts both rather than degrading: -running Grafana requires `swarm.authelia.url` (its local login form is disabled -unconditionally, so SSO isn't a feature of some topologies — it's the only way -in), and it requires this host's `deploy.bao.clientCertFile` / +running Grafana requires `swarm.authelia.url` (this module disables its local +login form unconditionally, so SSO isn't a feature of some topologies — it's the +only way in), and it requires this host's `deploy.bao.clientCertFile` / `clientKeyFile`. Each refusal names the option to set. Both used to be silent: a null URL dropped the OIDC block, a missing leaf produced a warning, and either one left a Grafana with no SSO and no password box — nothing failed, so diff --git a/docs/swarm/services.md b/docs/swarm/services.md index 96403566..b3e88c19 100644 --- a/docs/swarm/services.md +++ b/docs/swarm/services.md @@ -118,12 +118,16 @@ See `retentionPeriod` below before leaving it at its default. | `swarm.grafana.oidc.role` | Default `Admin` for everyone who logs in. Lower to `Viewer`/`Editor` if the swarm grows operators who shouldn't be able to reconfigure Grafana. | | `deploy.grafana.datasourceUrl` | Only if you front VictoriaMetrics with something else. It defaults to the store on this host, which is the only thing it can reach. | + + **Logging in.** Grafana is behind swarm SSO, so the accounts are the authelia ones — there is no separate Grafana password, and this module switches off the local login form whenever SSO is configured. If you enable Grafana on a host with no authelia, the form stays on and Grafana's default `admin`/`admin` applies; change it before exposing that host. + + **Where the data comes from.** The swarm's OTEL collector, below. Neither container is reachable except through the gateway: both bind diff --git a/docs/swarm/sso.md b/docs/swarm/sso.md index 991471ad..ca9033dc 100644 --- a/docs/swarm/sso.md +++ b/docs/swarm/sso.md @@ -121,6 +121,8 @@ read that same value, so the redirect URI authelia accepts and the one the service actually sends can't drift apart. A mismatch there is a rejected login with no error text worth reading. + + ⚠️ The delivery is a copy, not a `bindMounts` entry, and deliberately so: nixos-container refuses to start a container whose bind source is missing, and this secret doesn't exist until authelia's first boot has @@ -128,6 +130,8 @@ run. Binding it would make the service wait on a file that waits on a container that starts after it — on a fresh hive, a permanent stall presenting as "the forge is broken," many layers from its cause. + + ### 2. Swarm-managed services The controller side owns provisioning: `swarmctl` writes both halves, the diff --git a/docs/swarm/ui.md b/docs/swarm/ui.md index 8c151f6b..d054220d 100644 --- a/docs/swarm/ui.md +++ b/docs/swarm/ui.md @@ -38,6 +38,8 @@ fine and still gets bounced. swarmctl user add --group admins ``` + + `admins` deliberately, not a new word: [`../getting-started/setup.md`](../getting-started/setup.md) has told every operator to create exactly that group since the bootstrap step existed, so an account made by following the guide already passes. This @@ -45,6 +47,8 @@ is the first rule that _consumes_ a group name — inventing a second one would have meant those accounts silently failing a check they were supposed to pass. + + An account created without any group needs re-adding with the flag — `swarmctl` reads the existing entry out of `users.yml,` so the group is what changes. @@ -73,6 +77,8 @@ a container": | vhost + `gateway.localNames` | the service's own module (for example `nix/host-modules/swarm-ui.nix`) | | **certificate name** | `nix/host-modules/swarm.nix` (`serviceDomains`) | + + The DNS record and the local-dev `/etc/hosts` entry need no separate edit: both derive from `services.hyperhive.gateway.localNames`, which a service's own module already has to push its domain into to be @@ -82,6 +88,8 @@ the surface the hive's own domain serves (dashboard, per-agent routing, matrix discovery); a swarm service declares its own vhost next to its own options, the way `swarm-ui.nix` and `swarm-authelia.nix` do. + + ⚠️ The certificate one is the hardest to predict and the most visible when missed. `serviceDomains` is _both_ the services sub-CA's `nameConstraints` set and the leaf's SAN list, and the apex is a diff --git a/docs/tools/forge.md b/docs/tools/forge.md index 552aaee8..29ba434a 100644 --- a/docs/tools/forge.md +++ b/docs/tools/forge.md @@ -142,10 +142,12 @@ field; `pr status` when the only question is "can I merge it." ### Contributing to a read-only repo (`clone` + `pr create --agit`) + Agents are read-only collaborators on some repos (e.g. `internal/knowledge`) and so can't push branches. Forgejo's AGit flow lets a read-only user open a PR by pushing the current `HEAD` to the magic ref `refs/for//`. Two verbs cover the workflow: + ``` hive-forge -r internal/knowledge clone # clone, auth handled for you @@ -158,6 +160,7 @@ hive-forge -r internal/knowledge pr create --agit \ [--body "details"] # PR description (also accepts --body-file) ``` + `clone` derives the dest dir from the repo basename (override with a positional arg); it passes `--branch` / `--depth` through. The clone URL and the `origin` remote it leaves behind carry no credentials — @@ -166,6 +169,7 @@ URL and the `origin` remote it leaves behind carry no credentials — hand), which git calls fresh on every fetch/push. That's what lets `pr create --agit` (default remote `origin`) push without re-auth, without a durable token sitting in the checkout's `.git/config`. + `pr create --agit` prints the PR URL. Re-running with the same `--topic` force-updates the existing open PR (the AGit ref is @@ -244,6 +248,7 @@ to discover valid label names before triaging or to audit the label set. ## Notes + - **Read-before-comment guard:** `comment` refuses to post when forge still has an unread notification for the thread (that is, someone commented since you last read it). This prevents accidentally replying to old activity without @@ -341,3 +346,4 @@ to discover valid label names before triaging or to audit the label set. response's `X-Total-Count` (`… 50 of 187 shown … 137 more`), so trust the trailer, not the row count, when deciding whether you've seen everything. + diff --git a/docs/tools/hivectl.md b/docs/tools/hivectl.md index 51f8f1a8..280afe08 100644 --- a/docs/tools/hivectl.md +++ b/docs/tools/hivectl.md @@ -92,6 +92,8 @@ hivectl matrix invite @mara:server --room '#hive-chat:server' # ...or to a spec ## GitHub + + Write an operator-supplied GitHub personal access token (PAT) into an agent's token file so its `gh` wrapper + git credential helper can act as the bot account. Unlike forge/matrix there is no account creation — the PAT @@ -99,6 +101,8 @@ is for an existing GitHub account. A CLI alternative to the dashboard credentials tab; the [GitHub integration](../integrations/github.md) is on by default (`services.hyperhive.agent.github.enable`), so no per-agent config is needed. + + ```bash hivectl github set-token damocles --token-stdin # paste the PAT on stdin (preferred) hivectl github set-token damocles --token # inline (visible in shell history) @@ -242,8 +246,8 @@ session id — the flag name deliberately matches the claude flag it maps to. (choom never uses claude's `--continue`: that's a bare flag that takes no argument and resumes the cwd's _latest_ session, that is, the harness's; claude would consume a value after it as the first prompt, -silently poking the live harness session.) A value is required when you -pass the flag. Either way choom never collides with the harness's live +silently poking the live harness session.) Passing the flag requires a +value. Either way choom never collides with the harness's live session in the same project dir: the harness pins its own id via `--resume`, so a blank choom session is invisible to it. The container must be running. diff --git a/docs/tools/matrix.md b/docs/tools/matrix.md index f6d59350..cf5ea334 100644 --- a/docs/tools/matrix.md +++ b/docs/tools/matrix.md @@ -53,6 +53,7 @@ room you haven't read yet. ### Room membership + - `invite_user(room, user_id)` — invite `@user:server` into a room you're already in; you must have a high enough power level. The invitee sees a pending invite and resolves it via @@ -66,6 +67,7 @@ room you haven't read yet. invites (it can reject too). - `list_invites()` — rooms this agent has been invited to but not yet joined (`{ id, canonical_alias, name }` per room). + ### Receipts @@ -73,6 +75,7 @@ room you haven't read yet. ## Multiple accounts + `services.hyperhive.agent.matrixAccounts` (declared in `agent.nix`) is the agent's full set of matrix identities — for example an external-facing account alongside the internal one — **and, being @@ -89,6 +92,7 @@ here are the *further* accounts. hive-c0re pins its `tokenFile` to `/matrix-token` and provisions it there, and the dashboard's link-account route refuses to create an account by that name. + `main` is present exactly when that URL is non-null, which is the whole mechanism behind "accounts are the enable signal": an agent with no diff --git a/docs/tools/scheduling.md b/docs/tools/scheduling.md index 2794abc5..30641cb5 100644 --- a/docs/tools/scheduling.md +++ b/docs/tools/scheduling.md @@ -17,11 +17,15 @@ cancel. ### `request_schedule_prompt(targets, body, first_fire_at_unix, interval_seconds?, description?)` + + Queue an operator-approval for a scheduled prompt. On approve, hive-c0re fans `body` out to each agent in `targets` at `first_fire_at_unix` (Unix timestamp). Recurring when `interval_seconds` is set, one-shot otherwise. + + Catch-up clamp: if hive-c0re is down across multiple intervals, only ONE delayed fire happens on resume (per recurring schedule). The skipped-cycle count surfaces in the per-target `last_result` for @@ -41,10 +45,14 @@ rows (terminal state). ### `cancel_schedule(id, targets?)` + + Cancel a schedule. Omit `targets` / pass empty to cancel the whole schedule; pass a list to cancel just those recipients (the schedule autocancels once every target is gone). + + ### `fire_schedule_now(id)` Fire a scheduled prompt out of band immediately. Recurring schedules diff --git a/docs/tools/subagent.md b/docs/tools/subagent.md index a4024b3c..554458cd 100644 --- a/docs/tools/subagent.md +++ b/docs/tools/subagent.md @@ -144,12 +144,16 @@ no progress left to describe. ## A `continue` that finds no session + + `continue` doesn't check for the session before spawning. claude's own `--resume` is the authority, and it exits non-zero rather than quietly starting a fresh session, so the check could only duplicate the lookup the driver was about to do — while answering as though the session were gone. The usual truth is that the session exists somewhere else. + + `continue` waits for that answer instead. Where `start` returns the instant the process exists — it creates its session, so the spawn succeeding is the whole story — a resumed turn can fail a moment _after_ @@ -198,6 +202,8 @@ to report it, which is what `OOMPolicy=continue` on the unit is for. ## Compaction trade-off + + Built on `hive_claude::Claude::spawn` + `RunningClaude::wait` directly rather than `InfiniteSession::run`, since only the low-level driver exposes a cancel handle to stop a turn mid-flight — that's what makes @@ -208,6 +214,8 @@ Subagents are meant to be bounded, single-batch work, not sessions long-lived enough to need in-place compaction — a real follow-up if that assumption stops holding. + + ## Configuration `services.hyperhive.agent.mcp.subagentHttpPort` — the daemon's streamable-http listen diff --git a/docs/tools/swarm-logs-cli.md b/docs/tools/swarm-logs-cli.md index f6f1d2b1..999b9a58 100644 --- a/docs/tools/swarm-logs-cli.md +++ b/docs/tools/swarm-logs-cli.md @@ -51,7 +51,9 @@ Run a LogsQL query and print the matched log lines
+ This document was generated automatically by clap-markdown. + diff --git a/docs/trust-boundary/boundary.md b/docs/trust-boundary/boundary.md index bda50798..ce99a0b6 100644 --- a/docs/trust-boundary/boundary.md +++ b/docs/trust-boundary/boundary.md @@ -1,10 +1,14 @@ # The operator/agent boundary + + Design rationale for hyperhive's two-principal trust model. The _implementation_ work — container network isolation, the unifying gateway, core-daemon privsep — is tracked as `area:ops` issues on the forge. + + The operator/agent boundary is technically enforced, not just a convention: containers run in private netns (network isolation is always on), the gateway proxies all operator-facing traffic, and @@ -109,6 +113,8 @@ The last two land in "other," so the dir is **`0751`, owned by the agent's container uid/gid** — `o=--x` is traverse without listing, and both sockets are `0666`, which is all a dialer needs. + + **Ownership is declared, not repaired.** The tmpfiles.d entry written by `SyncAgentTmpfiles` names the uid/gid directly. Don't add a chown alongside it: `d` re-applies on every boot _and_ every agent @@ -116,6 +122,8 @@ spawn/destroy, and reverts any ownership set afterwards the next time any agent changes — which is exactly how this dir spent a long time at `0777 root root` while a privileged chown appeared to be fixing it. + + The mode is load-bearing, not cosmetic. Write permission on a _directory_ is what confers the right to unlink its entries, whoever owns them, and the sticky bit is the only thing that would restrain that (it diff --git a/docs/trust-boundary/security.md b/docs/trust-boundary/security.md index 907726c8..6e2d544c 100644 --- a/docs/trust-boundary/security.md +++ b/docs/trust-boundary/security.md @@ -10,6 +10,8 @@ agent capability X?." ### The trust boundary is the container, not credential storage + + An agent is **trusted code running inside its own nspawn container**. The boundary that matters is the container: a sub-agent can't see the host netns, another agent's container, or another agent's state dir. Within its @@ -22,10 +24,16 @@ below stops a build's nixbld user reading the agent's own forge token, and the state-file endpoint stops one agent proxying another's files. Those harden the boundary; they don't sandbox the agent from itself.) + + + + The corollary: **don't reason about security as "can the agent be stopped from touching its credentials." Reason about it as "what's the blast radius if this agent does the worst possible thing with everything it can reach."** + + ### Scoped tokens bound the blast radius Each agent gets its own scoped credentials, never shared: @@ -34,10 +42,14 @@ Each agent gets its own scoped credentials, never shared: collaborator grants; can't act as another agent or as `core`). - **matrix token** → that agent's matrix account only. + + _Its own_ account's scope bounds a compromised/confused agent's reach on the forge or matrix, not the swarm's. This is the main thing standing between "one agent does something dumb" and "the whole hive is affected." + + **Identity vs. secret (matrix).** The scoping is on the _secret_, not the _identity_: an agent's matrix **token** is private to its own account, but its matrix **identities** — the public handles (`name`, `user_id` `@user:server`, @@ -222,7 +234,7 @@ token policy bounds file reads; network isolation bounds network reach. The proper fix is to enable user namespaces inside nspawn containers (`--private-users=inherit` in `EXTRA_NSPAWN_FLAGS`) so nix can set up its real sandbox and `sandbox-fallback` becomes a true last resort. This requires verifying -bind-mount compatibility with user namespace UID mapping and is tracked as a TODO. +bind-mount compatibility with user namespace UID mapping first. ## hive-c0re privilege separation diff --git a/docs/turn-loop/claude-invocation.md b/docs/turn-loop/claude-invocation.md index 110bdf7a..bfb5f4e1 100644 --- a/docs/turn-loop/claude-invocation.md +++ b/docs/turn-loop/claude-invocation.md @@ -113,6 +113,8 @@ hyperhive owns compaction as policy: the `hive_claude::InfiniteSession` keeps the session alive across the context window with two triggers baked into its `run`: + + - **Reactive** — claude-code prints `Prompt is too long`. The session is _already_ past the window, so no turn can run on it — the session `/compact`s straight away and retries the same wake-up prompt once. No @@ -123,11 +125,12 @@ into its `run`: (see [Turn outcomes](README.md#turn-outcomes) — the wake prompt itself is small, so the overflow was the accumulated context the archive clears). - **Proactive** — a turn finishes cleanly but the last inference's context - size crossed the policy watermark. While the session is still healthy it - runs one synthetic _notes-checkpoint_ turn (`CHECKPOINT_PROMPT` — - "context is filling up, flush durable state into `/state` now") and - _then_ `/compact`s, so the agent can persist in-flight state before the - detail collapses into a summary. +size crossed the policy watermark. While the session is still healthy it +runs one synthetic _notes-checkpoint_ turn (`CHECKPOINT_PROMPT` — +"context is filling up, flush durable state into `/state` now") and +_then_ `/compact`s, so the agent can persist in-flight state before the +detail collapses into a summary. + **hive-agent checks both triggers above between its own turns** — `PercentPolicy::should_compact` reads the percent watermark from the @@ -236,8 +239,8 @@ needs to `chown` a bind mount), once at startup: - `claude-system-prompt.md` — rendered from `hive-agent/prompts/system.md` by `hive-agent`'s `prompt::render`: HTML-comment markers (`...`, - same for `role:manager`) gate the role-specific blocks; everything - else is shared. Five placeholders are then + same for `role:manager`) gate the role-specific blocks; both flavors + share everything else. Five placeholders are then substituted: `{label}` (short agent name), `{qualified_label}` (hive-qualified `name@domain` form), `{operator_pronouns}`, `{hive_identity}` (for example `` on hive `pr1ma` ``; empty when @@ -245,7 +248,7 @@ needs to `chown` a bind mount), once at startup: shape for the swarm). Pronouns come from `HIVE_OPERATOR_PRONOUNS` env (set by the meta flake from `services.hyperhive.c0re.operatorPronouns`, default `she/her`). - When `services.hyperhive.agent.docs.enable` is set, `HIVE_DOCS_DIR` is present + When you enable `services.hyperhive.agent.docs.enable`, `HIVE_DOCS_DIR` is present in the environment and `render()` appends a one-sentence pointer telling the agent where the docs live. Passed via `--system-prompt-file`. diff --git a/docs/turn-loop/config.md b/docs/turn-loop/config.md index 1d020a64..50549231 100644 --- a/docs/turn-loop/config.md +++ b/docs/turn-loop/config.md @@ -288,6 +288,8 @@ The file lives in the agent's bind-mounted **harness** dir, not `state/` (see `docs/agent-lifecycle/persistence.md`'s "Parent access to child state"), so an API key placed here is reachable by nothing but this agent and the host. + + ⚠️ Verified end-to-end against OpenRouter hasn't happened as of this writing — `ANTHROPIC_BASE_URL` support in the shipped Claude CLI is documented behavior, not something this hive has run a live turn @@ -295,6 +297,8 @@ against yet. Tool use, streaming, and MCP all need to keep working through a non-Anthropic base URL; treat the first real agent on this path as the actual verification, not this doc. + + Switching an already-provisioned OAuth agent to `useApiKey` leaves `~/.claude/credentials.json` in place but unused — harmless, not cleaned up automatically. Cost shape also changes: subscription pricing diff --git a/docs/web-ui/agent.md b/docs/web-ui/agent.md index cb90e0cf..e00ebf89 100644 --- a/docs/web-ui/agent.md +++ b/docs/web-ui/agent.md @@ -27,6 +27,7 @@ moment any row of badges/pills wrapped onto an extra line at some viewport width; measuring instead of guessing closes that bug class structurally rather than for one specific trigger. Two columns: + - **Agent icon** (``): fixed-size square identity anchor — `width: 5em; height: 5em` with explicit pixel sizing so the ``'s intrinsic (large) dimensions don't push @@ -100,6 +101,7 @@ structurally rather than for one specific trigger. Two columns: - No header cancel-turn button any more — `/cancel` (slash command, below) is the only path; the turn-loop state badge already shows `thinking` as the discoverability cue. + Values throughout come from `GET /api/state`'s cold-load snapshot, kept in sync afterwards by the SSE stream (see Live view below) — @@ -113,6 +115,7 @@ so two tabs from different hives are distinguishable; the header's own **Main content** (`
`): fills the viewport and scrolls behind the fixed header + footer. + - `#status` overlay: empty when online; shows the login form / OAuth URL when `status` is `needs_login_*`. The OAuth code input is `type="password"` with a `👁 reveal` toggle that flips it back to @@ -135,6 +138,7 @@ and scrolls behind the fixed header + footer. composites above the composer. Geometry is unchanged — `.agent-main` and `.terminal-wrap` both `inset: 0` fill the same area. + ## Footer / composer diff --git a/docs/web-ui/dashboard.md b/docs/web-ui/dashboard.md index 47ccbf1e..d07ba185 100644 --- a/docs/web-ui/dashboard.md +++ b/docs/web-ui/dashboard.md @@ -310,9 +310,11 @@ Three sub-tabs: ### MATRIX tab + Provision / log in a per-agent **external** matrix account and store its access token (this half is unchanged from the old `/matrix-accounts.html` page it replaces — only the URL and surrounding chrome moved). + An agent picker (populated from `state.containers`, the live roster) drives a list of that agent's accounts — name, homeserver, user id, and a status dot — @@ -447,6 +449,7 @@ boxes only stages the change in-browser; the browser writes nothing until the operator selects the page-level **save all** button (described below). Row values follow the `effective`/`assignments` rule described above. + **T00L GR0UPS** — per-agent tool-group permissions. Tool groups are named buckets of MCP tools; each agent starts with a role default (sub-agents: `messaging`, `meta`, `inbox`, `execution` — @@ -458,6 +461,7 @@ unchecking stages which groups are active for the agent; the page-level **save all** button (below) commits it. Columns come from `GET /api/tool-groups`. hive-c0re queues a rebuild so `HIVE_TOOL_GROUPS` takes effect. + The current tool groups are: `messaging`, `meta`, `inbox`, `lifecycle`, `approvals`, `scheduling`, `forge`, `execution`, @@ -746,6 +750,7 @@ falls back to the dimmed hyperhive mark (`/favicon.svg`). The card body sits to the right with three stacked lines (`assets/swarm.js::renderContainers`). + **Icon layout + load strategy:** the `` is absolutely positioned (`inset: 0`) inside the `.container-icon` wrapper — the wrapper is the flex child and sizes itself via `width: 5em` + @@ -762,7 +767,9 @@ the dashboard itself, always reachable) and adds the already knows the container is stopped (`ContainerView.running = false`) the fallback fires immediately, skipping the doomed `/icon` fetch entirely. + + **Line 1** — agent name (link → new tab), m1nd/ag3nt chip, an **icon-only nav strip** plus live agent-owned state, all populated async from a single `GET /api/dashboard-state` call to the agent's @@ -793,7 +800,9 @@ that's unset — never guessed from `:3000`. External links are already absolute. The same base URL drives the primary agent-name link + favicon fetch, so the whole row routes through the gateway as a unit. + + **When the container is stopped** (`ContainerView.running = false`), the dashboard skips the async `dashboard-state` fetch entirely (the agent web server is down), so a single badge replaces the badge chain, @@ -803,6 +812,7 @@ badges disappear. The agent icon goes straight to the dimmed container's URL. Static fields — `needs_update`, `deployed_sha`, `pending_reminders`, `parent`, `config` link — remain visible regardless of run state. + **Line 2** — status badges only (no per-card action buttons — actions moved to the **selection bar** or the **per-agent `⋮` menu**, see @@ -1010,6 +1020,7 @@ When the operator selects one or more agents (via the icon), a sticky frosted-mauve bar slides up from the bottom of the viewport (`#selection-bar`, `position: fixed; bottom: 0`). It shows: + - **Count + names** — "N agents selected · name1, name2, …" - **Bulk action buttons** — only enabled when ALL selected agents support the action; disabled with a tooltip naming the blockers @@ -1037,6 +1048,7 @@ frosted-mauve bar slides up from the bottom of the viewport - **multiple agents** → `POST /api/topology/set-parent-bulk` (JSON `[{ child, new_parent }]`; all moves land in a single `topology.json` commit instead of one per agent) + Both write `topology.json` and re-emit a container snapshot so the tree repaints without a page reload. @@ -1061,6 +1073,7 @@ renderApprovals`) with three stacked sections: | `schedule_prompt` | `⏱` | `schedule` | — | | `spawn` | `⊕` | `spawn` | — | + The chip ticks live every second via a `data-requested-at` attribute + client-side interval (no re-render). Turns amber once the request has been pending ≥ 1h so a stale approval stands out; @@ -1076,6 +1089,7 @@ renderApprovals`) with three stacked sections: - **decision actions** — `◆ APPR0VE` and `DENY`. Deny pops a `prompt()` for an optional reason carried to the submitting agent as `HelperEvent::ApprovalResolved.note`. + A `pending · N` / `history · N` tab pair switches the section between the live queue and the last 30 resolved approvals. @@ -1091,6 +1105,7 @@ The toggle controls live in the Y3R C4LL tab's ◆ PR3F3R3NC3S ◆ section; see that section above for the user-facing shape. Dispatch logic lives in `common.js::NOTIF`. + First `/api/state` after page load seeds "seen" sets without firing — only items that arrive while the page is open count. Per-event tags (`hyperhive:approval:`, @@ -1105,6 +1120,7 @@ permission. Requires a secure context (HTTPS or localhost); on other origins the controls hide themselves. Browsers typically suppress notifications while the originating tab is focused — that's a browser-level decision, not the dashboard's. + ## Dashboard endpoints @@ -1183,6 +1199,7 @@ below — some endpoints aren't in it yet. bodies at 1 MiB. Selection-time backing for the inline path-link preview. + The broker forwarder detects which tokens *are* path links **server-side at broker-message ingest**, not client-side: it calls `scan_validated_paths(body)` — @@ -1298,6 +1315,7 @@ below — some endpoints aren't in it yet. - `GET /api/dashboard/history` — last ~200 broker messages (wrapped as `{ seq, events }`) for the message-flow terminal's backfill on page load. + ## Dashboard event channel @@ -1378,6 +1396,7 @@ payload): `nix flake update` ripple starts or completes. BU1LDS M3T4 1NPUTS tab uses this to show/hide the "⏳ meta-update running" banner. + `/api/state` is **only fetched on cold-load and on the few forms that mutate non-event-derived state** (PURG3 + meta-update, since tombstones + meta_inputs aren't event- @@ -1386,6 +1405,7 @@ transients, containers, operator inbox, message flow — derives from `/api/dashboard/stream` after the initial snapshot, maintaining its own client-side store and applying events on top. The 5s periodic poll is gone. + Generalised form helpers: `form[data-confirm="…"]` pops `confirm()` before submit; `form[data-prompt="…"]` pops diff --git a/docs/web-ui/design-guide.md b/docs/web-ui/design-guide.md index 4a215c1f..04fbc047 100644 --- a/docs/web-ui/design-guide.md +++ b/docs/web-ui/design-guide.md @@ -45,6 +45,8 @@ home.js`, is the reference example — currently in the dashboard ## Motion + + **General rule, not case-by-case: every non-essential CSS animation gates on `prefers-reduced-motion` and pauses when its tab/section is hidden.** The dashboard's matrix-rain background (`packages/dashboard/ @@ -54,6 +56,8 @@ though it lives in the dashboard package rather than swarm-ui; every future swarm-ui animation follows the same pattern, not just whimsy pieces. + + Prefer CSS-driven animation over JS-driven where possible, and avoid jarring content swaps (layout shift, hard cuts) where a transition can smooth them instead. @@ -88,6 +92,8 @@ The governing question for anything that shows time-sensitive data: needs a refresh story; a value that's silently gone stale with no way to tell is worse than one that's visibly stale. + + - **Relative-time labels must actually tick.** A label like "fresh (5s ago)" derives from a stored timestamp and re-renders itself on an interval — never a value frozen at fetch time that quietly goes stale @@ -97,9 +103,10 @@ tell is worse than one that's visibly stale. 1m / …" control the operator sets per page, paused while the tab is backgrounded and resumed on foreground. - **A refresh must never clobber input the operator is mid-edit on.** - Any polling component's contract needs to make this the caller's - problem to opt out of correctly, not something the next adopter - discovers by shipping a bug. +Any polling component's contract needs to make this the caller's +problem to opt out of correctly, not something the next adopter +discovers by shipping a bug. + ## Errors diff --git a/docs/web-ui/shape.md b/docs/web-ui/shape.md index c16d8030..69cfd22f 100644 --- a/docs/web-ui/shape.md +++ b/docs/web-ui/shape.md @@ -110,6 +110,8 @@ shapes the renderers call: - `api.fromHistory` — `true` while backfill replay is running; renderers use it to suppress live-only side effects. + + **`create(opts)` options:** `logEl` (log container element), `streamUrl` (SSE endpoint), `historyUrl?` (optional replay endpoint — skipped if absent or if the fetch fails), `renderers` (kind→fn map; unknown kinds fall through @@ -126,6 +128,8 @@ than captured once — lets a page default otherwise-collapsed panels open per a live browser-local preference; renderers that force a row open regardless, for example message-bearing tool_use, are unaffected either way). + + **Sticky-bottom + snap animation.** `stickToBottom` is the operator's intent: true means "keep snapping to bottom on every mutation," false means "I scrolled up, leave me alone." The flag @@ -238,6 +242,8 @@ checkboxes use a lighter snapshot-then-restore pattern (snapshot before `replaceChildren`, restore after) since they're single values rather than per-row caches. + + **`
` open-state preservation:** any collapsible element tagged with `data-restore-key=""` survives the refresh. `snapshotOpenDetails()` walks managed sections before @@ -250,6 +256,8 @@ dashboard's own answered-questions history list was the only nothing to restore, kept in place for the next collapsible section that needs it rather than ripped out along with their one caller. + + **Side panel (dashboard):** long content opens in a drawer that swipes in from the right — a singleton `#side-panel` with a titled header, a close button, and a scrollable body. Closes on