Watch
0
0
Fork
You've already forked hyperhive
0

Compare commits

..
44 changed files with 1849 additions and 3146 deletions

View file

@ -295,10 +295,6 @@ docs/
boundary.md operator/agent trust model rationale
agent-hierarchy.md tree-shape topology design + manager-privilege audit (#361)
damocles-migration.md future migration plan for damocles → hyperhive
gateway.md nginx vhost map, matrix discovery flow, firewall posture,
HIVE_FORGE_URL loopback rationale (#764, #772, #793)
matrix.md matrix container shape, serverName/gatewayHost split,
firewall + federation, provisioning flow, fluffychat-web build
```
## Reading paths
@ -320,11 +316,6 @@ read them à la carte.
pattern."** → [`docs/conventions.md`](docs/conventions.md).
- **"Why does the nspawn flag look like that?"** →
[`docs/gotchas.md`](docs/gotchas.md).
- **"What nginx vhosts does the gateway serve? How does matrix
discovery work?"** → [`docs/gateway.md`](docs/gateway.md).
- **"How does the matrix-tuwunel container work? What about
fluffychat-web and per-agent matrix accounts?"** →
[`docs/matrix.md`](docs/matrix.md).
## Conventions & process

View file

@ -1,7 +1,7 @@
# Agent hierarchy & privileges
Design + audit doc for the agent-privileges + tree-shape milestone
(the [issue tree](http://localhost:3000/hyperhive/hyperhive/issues/361)).
Design + audit doc for milestone #6 (the
[issue](http://localhost:3000/hyperhive/hyperhive/issues/361) tree).
The implementation lands in pieces; this doc tracks what's done, what's
planned, and what currently special-cases the manager.
@ -20,7 +20,7 @@ Topology lives in the hive-c0re-owned **meta repo**, alongside
`null` = root-level agent. Today only the manager qualifies by default.
Other agents land under `"manager"` on first sync. Re-parenting is
operator-driven:
operator-driven (#486 / #487):
- CLI: `hive-c0re set-parent <child> --parent <new>` (or `--root` to
promote). Exactly one of `--parent` / `--root` is required.
@ -34,11 +34,11 @@ validation rules to a pure `apply_set_parent` helper. Refuses:
- self-parenting,
- cycles (32-hop ancestor walk, mirroring `is_descendant_of`).
The manager is reparentable like any other agent — there's no
"structurally root" carve-out; the manager's privileges live on its
MCP socket, not its tree position, and the cycle walk above catches
the only real safety concern (moving the manager under one of its
own descendants).
Post-#743 the manager is reparentable like any other agent — the
"structurally root" carve-out was historical paranoia; the manager's
privileges live on its MCP socket, not its tree position, and the
cycle walk above catches the only real safety concern (moving the
manager under one of its own descendants).
Idempotent no-op fast path skips the disk write when the parent is
already what's requested. After a successful write the surfaces call
@ -46,12 +46,13 @@ already what's requested. After a successful write the surfaces call
viewers see the tree repaint without polling
(`ContainerView.parent` is sourced from `topology.json`).
**Today's caveat:** the move is purely a JSON edit. Only the
top-level manager (`hm1nd`) gets `/var/lib/hyperhive/agents`
**Today's caveat (#361 follow-up):** the move is purely a JSON edit.
Only the top-level manager (`hm1nd`) gets `/var/lib/hyperhive/agents`
bind-mounted at `/agents` in its container, so sub-agents don't yet
see their would-be children's state. Once sub-manager bind mounts
land alongside cap enforcement, `set_parent` grows a companion
umount-old / mount-new / restart-cascade step.
land alongside #361 enforcement, `set_parent` grows a companion
umount-old / mount-new / restart-cascade step (tracked via the
cross-ref comment on #361).
### Why meta, not per-agent `agent.nix`
@ -77,7 +78,7 @@ where system-level facts live.
so the harness / claude prompts can see it.
4. **Surface**: `container_view::build_all` reads `topology.json` and
populates `ContainerView.parent: Option<String>` on every rescan.
The dashboard renders the field as a tree.
The dashboard renders the field as a tree (#363 follow-up).
## Target topology semantics
@ -149,7 +150,7 @@ Tree-shape version:
- `request_update_meta_inputs` is the only path that actually writes
`flake.lock`, gated by the cap; everyone else stays RO.
### D — drop legacy `/state` for manager ✓ done
### D — drop legacy `/state` for manager ✓ done (#604)
`lifecycle.rs` no longer binds `/state` for the manager.
`HYPERHIVE_STATE_DIR` is now injected uniformly via
@ -164,8 +165,8 @@ read.
- `prompts/system.md` with `<!-- role:agent -->` / `<!-- role:manager -->`
marker blocks, assembled by `hive_ag3nt::prompt::render` based on
flavor. **Per-agent cap list** of what the agent can do — already
a single parametrised prompt; once per-agent cap groups land the
flavor (closes #519). **Per-agent cap list** of what the agent can
do — already a single parametrised prompt; once #513 lands the
marker grammar grows `cap:<group>` blocks the renderer reads from
the per-agent ToolGroup set.
- `mcp.rs::Flavor::{Agent, Manager}` controls which MCP tools claude
@ -181,7 +182,8 @@ read.
descendants'.
- `operator_questions.rs` + `broker.rs`: "manager can cancel any
question" override on the owner check. **Topology** — agents can
moderate threads of their descendants.
moderate threads of their descendants. (per mara's
https://localhost:3000/hyperhive/hyperhive/issues/361#issuecomment-3344)
- `reminder_scheduler.rs`: same override pattern for reminder cancel.
**Topology** — descendants only.
- `actions.rs`: `destroy` refuses to act on `MANAGER_NAME` (no
@ -194,9 +196,9 @@ read.
### G — sub-agents inside the same container
Future work: when enabled for an agent, it can spawn temporary
"sub-agents" that run inside its own container. Lighter than a full
nspawn agent. Open questions, not yet wired:
Future work mentioned in #361: when enabled for an agent, it can spawn
temporary "sub-agents" that run inside its own container. Lighter than
a full nspawn agent. Open questions, not yet wired:
- Inherit caps from parent, or take an explicit narrower set?
- Survive container restart, or always ephemeral?
@ -204,102 +206,9 @@ nspawn agent. Open questions, not yet wired:
- Filesystem: share parent's `/state` RW, or a sub-dir?
- Identity: distinct broker recipient name, or address the parent?
## Harness systemd unit shape (per-role)
One harness binary (`hive`), one `harness-base.nix` template, two
systemd units depending on `hyperhive.role`:
- `agent-base.nix` (`role = "agent"`) → `systemd.services.hive-ag3nt`
- `manager.nix` (`role = "manager"`) → `systemd.services.hive-m1nd`
The unit names diverge but the binary is the same. `HIVE_ROLE` env
var picks the surface at startup (agent vs manager); naming the
units after the historical per-role binaries keeps dashboard log
queries, ExecStartPre paths, and ancestor PR diffs working without a
rename cascade.
### Manager-only defaults
`harness-base.nix` flips these when `hyperhive.role == "manager"`,
via `lib.mkDefault` so any agent can invert if needed:
- `hyperhive.forge.keepSubscriptions = false`
- `hyperhive.forge.skipNotifyReasons = [ "subscribed" "participating" ]`
Skips the subscription / participation firehose so the manager's
inbox only carries direct mentions, reviews, and assignments. Sub-
agents keep the noisier defaults so they see anything aimed at the
repos they're working on.
### Standalone-eval fallbacks
`nixosConfigurations.manager` must build standalone (without the
meta-flake's per-agent flake.nix wrapper). For the manager unit
that means hardcoded `HIVE_PORT` / `HIVE_LABEL` env values:
- `HIVE_PORT = "8875"` — FNV-1a(`"hm1nd"`) % 900 + 8100, matching
`lifecycle::agent_web_port`. Sub-agents have the same shape via
the meta-flake-generated `applied/<name>/flake.nix`.
- `HIVE_LABEL = "hm1nd"` — container name; matches what `meta.rs`
injects at deploy time.
Real deploys never read these — `meta::render_flake` overrides them
via the generated wrapper. They exist so the manager
`nixosConfigurations` evaluates cleanly even outside the meta-flake
boundary.
### Environment variables set on the unit
- `HOME = /home/<userName>` — systemd defaults `HOME` to `/` for
services without `User=` set; with the per-agent user (#658) the
harness needs the right home so claude finds its bind-mounted
`~/.claude/` session dir.
- `HIVE_STATIC_DIR = <mergedDist>` — `tower_http::ServeDir` root for
the per-agent web UI; merged dist = agent default + every
`hyperhive.frontend.extraFiles` overlay.
- `HIVE_ASSETS_DIR = pkgs.hyperhive-assets/share/hyperhive` — set
directly on the unit, **not** via `environment.variables`, because
the latter only populates `/etc/profile` which systemd services
don't inherit.
- `HIVE_ROLE = config.hyperhive.role` — picks the binary surface
(agent / manager) at startup.
### `PATH` setup (the wrapper-dir trick)
```nix
path = [ "/run/wrappers" "/run/current-system/sw" ];
```
`/run/wrappers` comes first so setuid wrappers (notably `sudo`)
resolve before bare nix-store binaries. NixOS's
`systemd.services.<unit>.path` appends `/bin` to every entry via
`lib.makeBinPath`; passing `/run/wrappers/bin` directly produces
`/run/wrappers/bin/bin` which doesn't exist (`docs/gotchas.md::
systemd.services.*.path appends /bin to every entry`). Post-#658
when the harness runs as the per-agent user this matters: without
the wrapper dir on PATH, `sudo` resolves to the un-setuid nix-store
binary and rejects with `must be owned by uid 0 and have the setuid
bit set` regardless of `hyperhive.user.passwordlessSudo`.
### `serviceConfig` highlights
- `ExecStart = pkgs.hyperhive/bin/hive serve` — single binary,
surface picked from `HIVE_ROLE`.
- `Restart = on-failure`, `RestartSec = 2` — keeps the harness
resilient across transient crashes without thundering retries.
- `RuntimeDirectory = "hive-config"` → `/run/hive-config/` owned by
`User=`, auto-cleared on stop. The harness writes regenerated
`claude-{mcp-config,settings,system-prompt}` files there
(`paths::config_dir`). Deliberately separate from `/run/hive`,
which the host bind-mounts in root-owned and which holds
hive-c0re's `mcp.sock` (#658 fixup).
- `User = Group = userName` — drops root inside the container; sudo
is the explicit escalation surface
(`hyperhive.user.passwordlessSudo`).
## Cross-references
- Milestone: ["Agent privileges and sub-agents"](http://localhost:3000/hyperhive/hyperhive/issues/361)
- Dashboard render: ["show agent topology in container list"](http://localhost:3000/hyperhive/hyperhive/issues/363)
- Audit table source: [milestone comment](http://localhost:3000/hyperhive/hyperhive/issues/361#issuecomment-3335)
- Milestone: [#361 "Agent privileges and sub-agents"](http://localhost:3000/hyperhive/hyperhive/issues/361)
- Dashboard render: [#363 "show agent topology in container list"](http://localhost:3000/hyperhive/hyperhive/issues/363)
- Audit table source: [comment 3335 on #361](http://localhost:3000/hyperhive/hyperhive/issues/361#issuecomment-3335)
- Operator/agent trust boundary (orthogonal axis): [`boundary.md`](boundary.md)

View file

@ -30,7 +30,7 @@ happens after a decision lands.
applied.
3a. **Flake validation (ApplyCommit only):** after the proposal tag
is planted, hive-c0re reads `proposal/<id>:flake.lock` and
runs two checks. If either check fails, no
runs two checks (closes #317). If either check fails, no
pending approval is created for the operator — the row is
marked failed and surfaces on the dashboard with the
validation message:
@ -66,7 +66,7 @@ happens after a decision lands.
### Withdrawing a pending approval
The manager can call `cancel_loose_end(kind: "approval", id)` to
withdraw an approval that hasn't been acted on yet.
withdraw an approval that hasn't been acted on yet (closes #250).
The row transitions to `ApprovalStatus::Cancelled` (distinct from
`Denied`/`Failed`), the dashboard pulls the card out of the
pending pane, and `ApprovalResolved { status: "cancelled" }` fires
@ -202,7 +202,7 @@ approval id to retry. Because tags are first-class git objects,
rejected and failed trees stay browsable forever — `git log
--tags` in the applied repo is the audit trail.
### Dispatch via `rebuild_queue`
### Dispatch via `rebuild_queue` (#441)
Long-running approval work — `ApplyCommit`, `UpdateMetaInputs`,
`Spawn` — no longer runs inline inside `actions::approve`. Instead
@ -344,7 +344,7 @@ Differences from sub-agents:
(vs `agent-base`).
- Container name is `hm1nd` (no `h-` prefix).
- Web UI port via `lifecycle::agent_web_port("hm1nd")` — same
FNV-1a hash as every other agent (8100..8999 range).
FNV-1a hash as every other agent (8100..8999 range) since #753.
- `set_nspawn_flags` adds two extra binds: `/var/lib/hyperhive/agents`
→ `/agents` (RW) so the manager can edit per-agent proposed repos,
and `/var/lib/hyperhive/applied` → `/applied` (RO) so the manager
@ -424,8 +424,8 @@ regular claude turn so the manager can react. Variants
such transient was cleared in the last 30s (`RECENT_TRANSIENT_GRACE`
tombstone, three `POLL_INTERVAL`s — closes the race where a
lifecycle op finishes between two crash-watch polls and the
container shows briefly as "stopped without transient" before
the next start). Manager can `start` it again or escalate.
container shows briefly as "stopped without transient" before the
next start, #425). Manager can `start` it again or escalate.
- `NeedsLogin { agent }` — sub-agent has no claude session yet.
Manager can't act directly (interactive OAuth); typically flags
the operator.

View file

@ -10,7 +10,7 @@ exist because something already went wrong without them.
- The manager is `hm1nd` (no `h-` prefix, fixed name).
- `MAX_AGENT_NAME` in `lifecycle.rs` enforces the cap.
- Per-agent web UI port = `WEB_PORT_BASE + FNV1a(name) % WEB_PORT_RANGE`
(8100..8999) for every agent including the manager; dashboard
(8100..8999) for every agent including the manager (#753); dashboard
`cfg.dashboardPort` (default 7000).
## Identity = socket
@ -32,12 +32,12 @@ angle-bracket and asterisk shapes below are structurally safe.
(`agent_server::handle_send` fans out via `Coordinator::broadcast_send`).
- `operator` — the human at the dashboard. Messages accumulate in the
inbox view; no agent ever `recv`'s them.
- `<parent>` — the sender's parent per `topology.json`. Rewritten at
send time by `topology::resolve_recipient`: looks up
- `<parent>` — the sender's parent per `topology.json` (`#692`).
Rewritten at send time by `topology::resolve_recipient`: looks up
`parent_of(sender)` and falls back to `operator` when the sender is
a root agent (or absent from topology entirely). Lets agents address
their parent without learning the label, so runtime reparenting
propagates with zero agent-side restart.
(`#486`) propagates with zero agent-side restart.
When the resolver rewrites `<parent>`, the broker stores the
*resolved* label as the message's recipient — the dashboard and
@ -54,43 +54,6 @@ each frame carries a `seq` field for the snapshot-dedupe dance
— change them in one place. The dashboard event vocabulary lives
in `hive-c0re::dashboard_events::DashboardEvent`.
### Broker delivery + ack cycle
`AgentRequest::Recv` is the only path that delivers messages to an
agent. Always returns a list (`Messages { messages }`) — empty when
nothing's pending, single-pop when `max = None` (default 1, the
single-message behaviour), batched up to `max` when caller asks for
more (server-side cap is 32; values above clamp silently).
`wait_seconds` long-polls for the first message; once one arrives —
or one is already pending — the call drains up to `max` in total
before returning, so a single `Recv` call coalesces a burst.
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
the last ack as fully handled. Claude doesn't see this surface; it's
strictly a harness↔broker pairing. On `TurnOutcome::Failed` the
harness intentionally skips the ack so the unacked rows stay
in-flight in the DB and get picked up by the next requeue sweep.
`AgentRequest::RequeueInflight` is the recovery pair: fired by the
harness exactly once at boot, before the serve loop starts. Catches
the crashed-mid-turn / OOM-killed / container-restarted cases where
a previous harness session popped messages but never drove them to
a clean turn-end. Resets `delivered_at` back to NULL on every
unacked row (so the next `Recv` pops them again), and remembers
each id in a per-recipient in-memory set so the next `Recv` can tag
the row with `redelivered: true`. Idempotent + cheap when there's
nothing in flight, so the at-boot fire is unconditional.
## Async forms
Dashboard + per-agent mutating forms carry `data-async`; a delegated

View file

@ -76,92 +76,3 @@ SSH for forge stays direct on `cfg.sshPort` — separate listener protocol, not
- #772 / #775 — fluffychat hops from `<hive>/matrix/` to `matrix.<hive>/`.
Next-up tracked separately: #14 (container netns isolation), TLS (#594).
## Firewall posture (host-level)
`hive-c0re.nix` opens the per-agent web-port range
`8100..8999` in the host firewall **only when
`services.hyperhive.gateway.enable = false`**. With the gateway on
(default), it's the sole external entry point and proxies to
`127.0.0.1:<port>` internally — leaving the per-agent ports
firewall-open would defeat the single-front-door story (closes
#621).
Manager hashes into the same range since #753 (no more
"manager pinned at 8000" special case), so one range opening covers
every container.
The dashboard port (`cfg.dashboardPort`, default 7000) is *not*
listed in either case — since #652 it binds `127.0.0.1` only, so a
firewall hole would be a no-op. Remote dashboard access flows
through the gateway. Operators who opt out of the gateway lose
external dashboard reach by design — the surface is privileged
(approve / deny / destroy) and must not be exposed without a real
reverse proxy in front.
## `HIVE_FORGE_URL`: loopback for in-cluster, sub-domain for the operator
Agents poll `HIVE_FORGE_URL` for Forgejo notifications + run all
`hive-forge` calls against it. `hive-c0re.nix` pins this to
`http://127.0.0.1:<forge.httpPort>` for the in-cluster path: every
agent container shares the host's network namespace, so loopback
reaches the forge container directly with no DNS lookup needed
(closes #761).
The post-#754 sub-domain default (`forge.<hive-domain>`) is for
**operator browsers + cross-host clients**, not in-cluster traffic.
Using the sub-domain URL inside agent containers would fail every
`hive-forge` invocation with "Name or service not known" — the
agent's nspawn doesn't have DNS for the external hostname.
## hive-forge container shape
Private Forgejo wrapped in a nixos-container (`hive-forge`, not
`h-*` — keeps c0re's lifecycle scanner out of the picture; the
operator manages it via the standard `nixos-container` CLI). The
container also keeps hive-forge from fighting any `services.forgejo`
the operator already runs on the host — separate systemd namespace,
separate state dir, separate port unless the operator deliberately
collides.
Container shares the host network namespace
(`privateNetwork = false`) so agents reach the forge at
`http://localhost:<httpPort>` without extra plumbing — nixos-container
is here for state + systemd-unit isolation, not network isolation.
State lives at `/var/lib/nixos-containers/hive-forge/var/lib/forgejo/`
and survives container restart / host reboot. To wipe, destroy the
container.
## Per-agent error pages
`/agent/<name>/` requests hit two failure modes; both get static
HTML pages instead of nginx's default error chrome (#755):
- **Agent not found** (`/agent/<unknown>/...`) — name isn't in
`agentPortsTable`. nginx's prefix match falls back to the bare
`/agent/` catch-all, which `return 404`s and `error_page 404` rewrites
to `/__hive_agent_not_found` → serves `not-found.html` with a link
back to the dashboard.
- **Agent unreachable** (`502 / 503 / 504` from `proxy_pass`) — the
per-agent harness isn't responding (container restarting, crash
recovery, etc.). `proxy_intercept_errors on` + `error_page 502 503
504 = /__hive_agent_unreachable` rewrites to `unreachable.html`.
Both pages are built at deploy time via `pkgs.runCommand` (one nix
derivation `hyperhive-agent-error-pages` with `not-found.html` +
`unreachable.html` inside) and served via two `internal` nginx
locations with `alias` to the exact file. `internal` keeps the
files from being directly request-able by operators — only nginx's
own error-handling can reach them.
Page styling: minimal inline CSS matching the dashboard's catppuccin
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 per mara on #755: "only for routes
already special cased in the nginx config". Other gateway routes
(forge / matrix / fluffychat) get nginx defaults — extending the
custom-error pattern there is a separate follow-up.

View file

@ -87,7 +87,8 @@ propagate in. Operators don't need to set anything on their side.
## Claude credentials are per-agent
`/var/lib/hyperhive/agents/<name>/claude/` bind-mounts to
`/home/<name>/.claude` (RW). Sharing one dir across agents is NOT viable —
`/home/<name>/.claude` (RW; was `/root/.claude` pre-#658 when every
harness ran as root). Sharing one dir across agents is NOT viable —
OAuth refresh tokens rotate, so any sibling refresh invalidates all
the others. Login flow runs from the per-agent web UI; creds persist
across `destroy`/recreate (`--purge` wipes them).
@ -95,8 +96,8 @@ across `destroy`/recreate (`--purge` wipes them).
## Persistent notes dir per agent
`/var/lib/hyperhive/agents/<name>/state/` bind-mounts to
`/agents/<name>/state` (RW; uniform for sub-agents + manager).
The harness exposes the same path
`/agents/<name>/state` (RW; uniform for sub-agents + manager
post-#604, was `/state` pre-#604). The harness exposes the same path
via `$HYPERHIVE_STATE_DIR`. System prompts tell agents to keep
durable knowledge here (`notes.md`, anything else). The harness also
writes its events log here (`hyperhive-events.sqlite`).
@ -111,8 +112,8 @@ unlucky. Operator resolves a collision by renaming the offending
agent (different hash → different port) and rebuilding. No state
file, no probing, no port-allocation drift — the value is
reproducible from just the name. Every agent — including the
manager — hashes into 8100..8999 via the same FNV-1a; dashboard
at `cfg.dashboardPort` (default 7000).
manager — hashes into 8100..8999 via the same FNV-1a since #753;
dashboard at `cfg.dashboardPort` (default 7000).
## Restart races on TCP bind
@ -145,12 +146,13 @@ files in subdirectories) fails with `EPERM`. Fix: pass
The naive nginx pattern for a path-prefix SPA (`try_files $uri $uri/
/matrix/index.html`) silently swallows asset 404s — a missing JS file
returns `index.html` with a 200, so the JS runtime never loads and the
page renders blank with no visible error. Extension allowlists (tried
as an alternative) have the same maintenance problem: any new file
extension the SPA ships breaks silently.
page renders blank with no visible error (#685; fixed in PR #684;
#686 filed the follow-up edge-case, addressed in PR #729).
Extension allowlists (tried in #686 → PR #729) have the same maintenance
problem: any new file extension the SPA ships breaks silently.
The pattern that works (`hive-gateway.nix`) keys the fallback on the
HTTP `Accept` header:
The correct pattern (landed in PR #729, `hive-gateway.nix`) keys the
fallback on the HTTP `Accept` header:
```nginx
# Outside the server block (appendHttpConfig):
@ -186,22 +188,22 @@ nix build /var/lib/hyperhive/meta#argus.config.system.build.toplevel
nix build /var/lib/hyperhive/meta#nixosConfigurations.argus.config.system.build.toplevel
```
`lifecycle::prebuild_toplevel` hit this once by constructing the attr
path as `{flake_ref}.config…` — which produced `meta#argus.config…`
instead of `meta#nixosConfigurations.argus.config…`. The fix:
`split_once('#')` to separate flake path from name, then template
`{path}#nixosConfigurations.{name}.config.system.build.toplevel`.
`lifecycle::prebuild_toplevel` hit this in #721 (fixed in #738) by
constructing the attr path as `{flake_ref}.config…` — which produced
`meta#argus.config…` instead of `meta#nixosConfigurations.argus.config…`.
The fix: `split_once('#')` to separate flake path from name, then
template `{path}#nixosConfigurations.{name}.config.system.build.toplevel`.
## `hive-forge`: prefer over raw curl pipelines
Every agent container has `hive-forge` in PATH (installed via
`harness-base.nix`; lives in `/hive-forge` as a proper Rust binary).
Use it instead of ad-hoc curl pipelines:
`harness-base.nix`; lives in `/hive-forge` as a proper Rust binary
since #280). Use it instead of ad-hoc curl pipelines:
```bash
hive-forge view 42 # title + body + comments
hive-forge comments 42 # list all comments (human-readable)
hive-forge --json comments 42 # same as above, JSON array (global flag)
hive-forge --json comments 42 # same as above, JSON array (global flag, closes #421)
hive-forge comment 42 --body "..." # post comment (inline body)
hive-forge comment 42 --body-file - <<EOF # ...or pipe a HEREDOC
multi-line body
@ -210,7 +212,7 @@ hive-forge assign 42 damocles
hive-forge close 42
hive-forge labels 42 add feature
hive-forge pr 42 # PR metadata as JSON
hive-forge pr-create --title "..." --head my-branch --push # also `git push forge my-branch`, suppressing the post-push "Create a pull request" hint
hive-forge pr-create --title "..." --head my-branch --push # also `git push forge my-branch`, suppressing the post-push "Create a pull request" hint (#222)
hive-forge diff 42 # unified diff (lockfile hunks collapsed by default)
hive-forge diff 42 --full # include unfiltered lockfile hunks
hive-forge branches deployed/ # filter branches by pattern
@ -225,114 +227,3 @@ hive-forge lint assignments # per-assignee open item count
Credentials come from `$HYPERHIVE_STATE_DIR/forge-token`; default
repo from `$HIVE_FORGE_REPO`, overridden per-invocation by the
global `-r/--repo` flag.
## Containerized nix-daemon needs `sandbox-fallback = true`
Agent containers bind-mount the host's nix-daemon socket. nspawn
containers don't get user-namespaces by default, so `nix build`
invocations *inside* the container can't set up the build sandbox
and fail outright if the host daemon's
`nix.settings.sandbox-fallback` is `false` (nixpkgs default).
`nix/templates/harness-base.nix` does `lib.mkForce true` so builds
fall back to unsandboxed local builds rather than failing. Security
implications: `docs/security.md`.
## Split asset derivations away from the rust workspace
`nix/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
rust build's `src` was the whole repo tree, any tweak to
`branding/agent-configs.svg` or `hive-ag3nt/prompts/system.md`
invalidated the cargo cache and forced a full rebuild. crane (and
naersk before it) couldn't see "these inputs are unused by rust" on
its own — the split breaks the coupling at the derivation boundary.
The agent-configs PNG is rendered from the SVG via `rsvg-convert` at
build time; librsvg dependency lives here, not in the rust
derivation's `nativeBuildInputs`.
## Weston VNC compositor (per-agent `hyperhive.gui.enable`)
`nix/templates/weston-vnc.nix` adds an optional Weston Wayland
compositor with the VNC backend, surfaced as
`hyperhive.gui.enable = true` per-agent. The harness's
`/screen/ws` WebSocket relay (`docs/web-ui.md::Per-agent endpoints`)
connects to the compositor at `127.0.0.1:<vnc_port>`.
- **Port allocation**: deterministic FNV-1a of the agent name
(read from `/etc/hostname`, leading `h-` stripped) mapped into
`[15900, 16799]`. Mirrors the agent web-UI port pattern from
`docs/gotchas.md::Web UI ports collide on hash` — same FNV-1a
constant, different range. The compositor's startup script writes
`/etc/hyperhive/gui.json = {"vnc_port":N,"auth":"none"}` so the
harness reads the port at runtime; no nix-side / harness-side hash
duplication.
- **VNC bind address**: weston's VNC backend has no CLI
bind-address flag (unlike the RDP backend's `--address`), so the
listener binds `0.0.0.0`. The harness relay only connects via
`127.0.0.1`; the host firewall blocks the per-agent VNC port range
from external access. A future weston.ini `[vnc] address=` will
let us restrict the bind directly once upstream supports it.
- **PAM service name**: literal `weston-remote-access` — that's the
string libweston passes to `pam_start()` in `libweston/auth.c`.
Using `weston` falls back to the system default PAM stack and
rejects auth. The service is configured to `pam_permit.so` for
all three module types (auth / account / session) so the
browser's empty Apple-DH credentials (type 30) always pass —
neatvnc ≥ 0.9 calls the PAM auth callback regardless of
`weston.ini` `auth-method=none`, so the permit fallback is what
actually lets the empty-cred client through.
- **`Type = "simple"` (not `notify`)**: `switch-to-configuration`
must never block on weston signalling readiness. A misconfigured
weston degrades to a `Restart=on-failure` loop visible in
`journalctl`, it does not abort the `nixos-container update`.
Same reasoning as the `tea-login` unit in `harness-base.nix`.
- **`[core] idle-time=0`**: disables weston's 300-second idle
timeout. Without it the VNC desktop fades to black and
desktop-shell shows its click-to-unlock screen — useless for an
agent desktop viewed over `/screen`. `idle-time=0` updates the
idle timer with a 0ms delay, which
`wl_event_source_timer_update` treats as "disarm", so the
compositor never goes idle and never locks.
## Nix options reference (`nix/docs/default.nix`)
`pkgs.nixosOptionsDoc` over two evaluated module trees:
`hostEval` (a stub NixOS system loading `self.nixosModules.default`
with every hyperhive subsystem `mkForce false` so heavy build
inputs stay out of the eval) and `agentEval` (reuses the already-evaluated
`agent-base` container config so the per-agent options tree is
identical to what a real agent container sees).
Three output trees consumed by `flake.nix`:
- `docs-host` — operator-facing host module options
(`services.hyperhive.*`)
- `docs-agent` — per-agent harness options (`hyperhive.*`
declared in `nix/templates/harness-base.nix`)
- `docs` — bundled static site (`index.html` + `host.html` +
`agent.html`, plus `.md` source-of-truth versions of each
options page)
Rendering pipeline:
- CommonMark from `nixosOptionsDoc.optionsCommonMark` — source of
truth, kept as `.md` in the bundle.
- HTML via `pkgs.cmark-gfm` over the CommonMark, wrapped in a
minimal inline-CSS template. `cmark-gfm` (not plain `cmark`) so
any future tables / autolinks Just Work without revisiting.
- Inline `<style>` from `nix/docs/style.css` so the bundle is
single-file-per-page and nginx's `/options/` mount needs no MIME
setup for separate `.css` files and no cache-busting.
- Asset paths inside rendered HTML are all relative
(`./host.html`, etc.) so the bundle can mount at any URL prefix
without rewriting.
- `transformOptions` strips the nix-store prefix from option
declaration paths and rewrites them as forge URLs, so the
rendered docs link back to the source.
Host options live entirely under `services.hyperhive.*`. The
`pickSubtrees` filter is rooted at `["services" "hyperhive"]` so the
options tree picks up everything under that root — picking against
stray roots produces an empty tree and renders the host page as
template chrome with no `<h2>` headers.

View file

@ -1,199 +0,0 @@
# hive-matrix
Private Matrix homeserver (matrix-tuwunel — the conduwuit
successor) wrapped in a nixos-container, plus optional fluffychat-web
client at `matrix.<hive>/`. Configured via
`services.hyperhive.matrix.*`; vhost routing lives in
[`gateway.md`](gateway.md).
## Container shape
Same shape as [`gateway.md::hive-forge container shape`](gateway.md):
- Container name `hive-matrix` (not `h-*`) so c0re's lifecycle
scanner ignores it; operator manages via the standard
`nixos-container` CLI.
- Keeps hive-matrix from fighting any `services.matrix-*` the
operator already runs on the host — separate systemd namespace,
separate state dir.
- Container shares the host network namespace
(`privateNetwork = false`) so agents reach tuwunel at
`http://localhost:<httpPort>` without extra plumbing — the
nixos-container is here for state + systemd-unit isolation, not
network isolation.
- Persistent state at
`/var/lib/nixos-containers/hive-matrix/var/lib/matrix-tuwunel/`
survives container restart / host reboot. To wipe, destroy the
container.
## Identity vs API listener: `serverName` vs `gatewayHost`
Two distinct hostnames:
- **`serverName`** — matrix-spec `server_name`, embedded
*irrevocably* in every `@user:<server_name>` and `!room:<server_name>`
identifier minted on this homeserver. Cannot be changed later
without abandoning every account and chat history. Defaults to the
bare `services.hyperhive.domain` per mara on #660; clients
auto-discover the actual API endpoint via the
`.well-known/matrix/{client,server}` routes the hive-gateway serves
at that domain.
- **`gatewayHost`** — the API listener hostname, where the gateway's
matrix vhost proxies `/_matrix/*` to tuwunel. Defaults to
`matrix.<services.hyperhive.domain>` (sub-domain shape per mara on
#749:9609). Set to `null` to skip the gateway vhost (tuwunel stays
direct on `httpPort`).
**Breaking change** (#660): `serverName` used to default to
`matrix.${services.hyperhive.domain}`. Existing homeservers must set
the option explicitly to preserve their pre-#660 user / room IDs
before rebuilding. The default flipped because the bare hive-domain
makes for cleaner matrix IDs and `.well-known` delegation hides the
sub-domain from the user-facing identifier.
## Default-closed firewall
`openFirewall` defaults to `false` (#651, secure-by-default): the
homeserver is reachable from the host + every agent container via
loopback either way (shared netns), so the firewall hole only
matters for access from *outside* the host. Flip to `true` when
announcing the homeserver to other hives or when an external matrix
client needs to reach the client-server API directly.
**Breaking change** (#651): used to default to `true`. Operators
relying on external reach must add
`services.hyperhive.matrix.openFirewall = true;` before rebuilding.
Federation port 8448 is intentionally not opened here — tuwunel
serves the federation API on the same `httpPort` as client-server
by default. Reaching it on 8448 needs either an explicit tuwunel
bind to that port OR a reverse-proxy + `.well-known/matrix/server`
delegation (the latter lives in `gateway.md::Discovery flow`).
## Provisioning flow (registration token)
Token-gated registration: hive-c0re holds the token, agents never
see it. The agent only receives the resulting `access_token`.
1. **System activation** writes a 32-byte random hex token (64
chars) to `cfg.registrationTokenFile`
(`/var/lib/hyperhive/matrix-register-token` by default), mode
`0600 root:root`, before any container start. Idempotent — only
writes when the file is missing or empty; always re-applies 0600
(normalises any 0640 / world-readable carry-over from
pre-LoadCredential deployments). This runs at activation time
(not first container start) to dodge the argus #565 race where
nspawn creates an empty file when the bind-mount target is
missing and tuwunel reads `registration_token_file=""` rejecting
every registration until next restart.
2. **Read-only bind-mount** maps the host file into the tuwunel
container at the same path.
3. **systemd `LoadCredential=`** inside the container copies the
bind-mounted file into
`/run/credentials/tuwunel.service/registration_token`, owned by
tuwunel's dynamic user with mode `0400`, at service start. The
host file stays `root:root 0600` — no `chown :tuwunel` /
`chmod 0640` / GID-pin gymnastics required (per iris on #644
8043, dropping the shape #649 originally shipped with). Keeps
`DynamicUser = true` + `PrivateUsers = true` intact.
4. tuwunel's `registration_token_file` points at the credentials
path, not the original bind-mount path.
5. **hive-c0re** uses the token to register each agent account via
the matrix-spec UIAA registration flow, persists the returned
`access_token` to `<agent-state>/matrix-token`. The agent's
matrix MCP client authenticates with that access_token and
never touches the shared registration token.
Initial rollout settings (#548):
- `allow_federation = true` at the protocol level so swarms can be
wired up later by extending `trustedServers` without a homeserver
restart. `trusted_servers = []` keeps it effectively closed
until peers are listed.
- `allow_registration = true` (required for the token flow to
engage). The absent
`yes_i_am_very_very_sure_…_open_registration_…` flag keeps the
server closed to anyone without the token.
- `allow_encryption = false` per operator call (#548). E2EE
re-enabling tracked at #551.
## Assertion rationale
Two `config.assertions` entries fail eval early rather than ship
surprising behaviour:
- **`hyperhiveDomain != null || cfg.serverName != null`** (mara on
#548) — `server_name` is embedded into every user / room ID
irrevocably; we refuse to spawn the homeserver with a bogus
server_name we can never change later.
- **`cfg.gatewayHost != ""`** (argus 🟡 on #764) — same footgun as
`forge.domain` (#754). Empty string renders `.<hive>`-shaped
garbage in both nginx `server_name` (treated as wildcard
catch-all, surprising) and `/etc/hosts` (invalid entry). `null`
is the right opt-out shape; empty string is rejected explicitly.
## fluffychat-web build fixes (#685)
`pkgs.fluffychat-web` ships from `flutter341.buildFlutterApplication`,
which has two upstream gaps for fluffychat's web target:
- The dart web-worker entry point (`web/native_executor.dart`) isn't
compiled — `buildFlutterApplication` only runs `flutter build web`
on the main entry.
- `native_imaging`'s C source isn't built — emscripten isn't a
flutter-builder native build input.
Both fixed in `nix/modules/hive-matrix.nix` via two derivations:
- **`fluffychat-web-imaging`** builds `Imaging.{js,wasm}` from the
`native_imaging` C source via `pkgs.emscripten`. Source comes
from `pkgs.fluffychat-web.passthru.pubspecLock.dependencySources.native_imaging`
— already in the build closure of the flutter app, so no parallel
hash pin and version auto-syncs with nixpkgs bumps. Build closure
is ~3.6 GiB (emscripten LLVM); runtime closure is just the two
output files. `dontConfigure = true` because cmake runs inside
`js/Makefile` via `emcmake cmake`, not at the package root. The
build script needs `HOME` + `EM_CACHE` writable for emscripten's
on-demand sysroot build (libc, libc++ → wasm).
- **`fluffychat-web-fixed`** is `pkgs.fluffychat-web` plus a
`postInstall` patch that (a) compiles `web/native_executor.dart`
via `dart compile js` (dart from the flutter341 closure, no
incremental cost) and (b) installs `fluffychat-web-imaging`'s
outputs into `$out`.
Two non-obvious fixes from review history:
- **`make -C js`** instead of `cd js; make` (argus 🟡 on #697 v2)
— keeps the build-phase pwd at the source root so `installPhase`
doesn't have to know about the cd. Robust against future
reorders / `dontBuild`.
- **`web/native_executor.dart`** as a build-CWD-relative path,
*not* `$src/web/...` (#685 / #733 fixup) — `dart`'s
`package_config.json` walk-up needs to hit
`buildFlutterApplication`'s pub-get output (`.dart_tool/` in the
build CWD). Walking up from a read-only `$src/` store path finds
no `.dart_tool/` and errors with "Couldn't resolve the package
'matrix'". Confused two PRs.
Drop both derivations when nixpkgs's flutter builder grows worker
+ emcc support upstream.
Mount point is `matrix.<hive>/` (#772); upstream `--base-href "/"`
is correct at sub-domain root, no override.
## Sequencing history
- #548 — initial rollout (federation enabled, registration enabled,
E2EE disabled)
- #565 — first-boot empty-token race fix → activation-time token
generation
- #644 / iris 8043 / #649 — registration token ownership shape
(dropped chown/GID-pin; LoadCredential delivers as 0400 dynamic-user)
- #651 — `openFirewall` default flipped to `false`
- #660 — `serverName` default flipped to bare hive-domain (was
`matrix.<hive>`)
- #685 / #697 / #733 — fluffychat-web build fixes (Imaging emscripten,
native_executor dart worker, build-CWD path)
- #736 — fluffychat config.json inline JSON at sub-domain root
- #749 / #764 — gateway sub-domain shape verdict
- #772 / #775 — fluffychat hops from `<hive>/matrix/` to `matrix.<hive>/`

View file

@ -32,8 +32,8 @@ header/targets split:
Q&A (`HelperEvent::QuestionAsked` pushed into target's inbox,
answered via `Answer` request). Migrated via `ALTER TABLE ADD
COLUMN` against `pragma_table_info`.
- `scheduled_prompts` — recurring + one-shot prompt queue.
`owner / body / interval_seconds (NULL = one-shot) /
- `scheduled_prompts` — recurring + one-shot prompt queue
(closes #444). `owner / body / interval_seconds (NULL = one-shot) /
next_fire_at_unix / created_at_unix / source ("operator" or
"approval:<id>") / cancelled_at_unix / description`. `owner`
drives cancel-permission checks (operator vs the submitting
@ -101,8 +101,9 @@ Bin-loop helpers `build_row` + `record` land each row at
`turn_end`; writes are best-effort, a sqlite hiccup logs + lets
the turn loop continue.
No host-side vacuum yet — tracked separately. Target retention
~90 days, age-only sweep like events_vacuum.
No host-side vacuum yet — tracked as forge issue
[#10](http://localhost:3000/hyperhive/hyperhive/issues/10)
(target retention ~90 days, age-only sweep like events_vacuum).
### `/state/hyperhive-rate-limited` (per agent)
@ -135,12 +136,13 @@ Under `/var/lib/hyperhive/agents/<name>/`:
precise changes from the manager; RW into the manager via the
`/agents` tree bind.
- `claude/` — claude OAuth credentials, bind-mounted RW to
`/home/<name>/.claude` inside the container.
`/home/<name>/.claude` inside the container (post-#658 — was
`/root/.claude` pre-#658 when every harness ran as root).
- `state/` — durable notes, the events.sqlite db, and the
turn-stats sqlite db. Bind-mounted to `/agents/<name>/state`
inside the container (uniform for sub-agents + manager).
The `$HYPERHIVE_STATE_DIR` env var exposes the same path to
in-container scripts.
inside the container (uniform for sub-agents + manager
post-#604). The `$HYPERHIVE_STATE_DIR` env var exposes the
same path to in-container scripts.
Under `/var/lib/hyperhive/applied/<name>/` — the hive-c0re-only
applied repo. Tracks `flake.nix` (module-only boilerplate; never
@ -196,66 +198,3 @@ On startup, `Coordinator::register_agent` drops any prior socket
task before rebinding — idempotent so a hive-c0re restart followed
by `rebuild alice` recreates the agent's socket without a clean
reinstall.
## First-boot agent-user migration
The harness runs as a per-agent unix user inside the container
(`hyperhive.user.name`, defaults to the agent's logical label so each
container has a uniquely-named user). Operators with legacy root-owned
state dirs need a one-time data shuffle so they don't lose their claude
session.
`system.activationScripts.hive-agent-user-migrate` (in
`nix/templates/harness-base.nix`) runs on every activation,
marker-guarded so the substantive moves only happen once per
container lifetime:
1. **`${homeDir}` exists with the right ownership** — covers the
very first boot before `useradd`'s `createHome` has had a
chance to chown. Also re-applies on every rebuild in case the
meta-flake's per-agent name evolves (rare).
2. **Migrate any leftover `/root/.claude` content into
`${homeDir}/.claude`** — legacy `claude` wrote to root's
empty home; the bind mount didn't exist yet. Marker
(`/var/lib/hive-agent-user-migrated`) guards single-shot.
`cp -an` (no-clobber) so any pre-existing files at the new
location win — never blow over data already there.
3. **Chown the bind-mounted state dir** (`/agents/*/state`)
recursively so the agent user can read/write it. Wildcard
matches the single agent that container sees; `-h` skips
symlinks the agent might have planted.
4. **Chown the `~/.claude/` bind-mount** recursively. Legacy
`claude` wrote `.credentials.json` 0600 root:root; the
current harness reads `~/.claude/` as the agent user to decide
Online vs NeedsLogin in `login::has_session`. Without the
chown the existing credentials get silently treated as "no
session" and the operator re-prompts every boot.
The activation script will eventually become unnecessary once no
operators have legacy root-owned state dirs left to migrate; drop
the body + marker check at that point.
## Matrix per-agent daemon + token-arrival trigger
`hive-matrix-daemon` is a long-running matrix-sdk Client + sync
process per agent. Holds the unix socket the stdio
`hive-matrix-mcp` bridge talks to, emits hyperhive wake signals
on incoming room events via `/run/hive/mcp.sock`. Conditional on
`hyperhive.matrix.enable` (which both the daemon AND the
auto-injected `extraMcpServers.matrix` entry read).
Socket path lives inside the systemd-managed runtime dir
(`RuntimeDirectory = "hive-matrix"` → `/run/hive-matrix/`, owned by
the agent user) so the daemon can bind without needing root over
`/run/` itself. Both daemon + bridge agree on the path via the
`HIVE_MATRIX_SOCKET` env var.
**First-boot ordering**: hive-c0re provisions the matrix token AFTER
agent containers come up. Without the path-trigger sibling
(`systemd.paths.hive-matrix-daemon`, `PathExistsGlob =
/agents/*/state/matrix-token`), the daemon would exit 0 quietly the
first time it ran and the MCP would have no backend until the next
restart. The `.path` unit makes the appearance of the token re-fire
the service so the daemon comes alive in the same boot cycle as
provisioning. `matrix-avatar-sync.path` uses the same pattern for
the icon-upload oneshot.

View file

@ -1,6 +1,6 @@
# Security model
## Nix builds and credential isolation
## Nix builds and credential isolation (issue #240)
### Background
@ -19,11 +19,12 @@ any file in the container that the nixbld user can read.
**What is NOT exposed**:
- `/home/<name>/.claude/` — mode `0700`, owned by the per-agent
user `<name>`. nixbld users cannot read it.
user `<name>` (post-#658 — was `/root/.claude` owned by root
pre-#658). nixbld users cannot read it.
- `$HYPERHIVE_STATE_DIR/forge-token` (= `/agents/<name>/state/forge-token`)
— written at mode `0600` by `hive-c0re/src/forge.rs` and chowned to the
per-agent uid:gid by `lifecycle::chown_to_agent`. nixbld users
cannot read it.
per-agent uid:gid by `lifecycle::chown_to_agent` (post-#673/#678).
nixbld users cannot read it.
**Policy**: all credential files written to agent state directories MUST be mode
`0600` or stricter. Do not create world-readable secret files in agent state dirs.

View file

@ -43,7 +43,7 @@ parent's negative pull.
| `.tool-use` (flat) | `→ Name args…` | cyan | tool_use w/o rich renderer | stream-json |
| `.tool-use` `<details>` | `Write/Edit <path> · +N` (no `→`) | cyan, body is +/- diff | `renderRichToolUse` Write/Edit | stream-json |
| `.tool-use` `<details open>` | `send → to · NL`, `ask → to`, `answer #id` | cyan, body is markdown | rich renderer for send / ask / answer | stream-json |
| `.tool-use .ask-answer-inline-slot` | (sub-block under `ask → operator`) | inherits row | inline answer form bound by `reconcileAskBinds` to the loose-end | rich renderer |
| `.tool-use .ask-answer-inline-slot` | (sub-block under `ask → operator`) | inherits row | inline answer form bound by `reconcileAskBinds` to the loose-end | #666 |
| `.tool-result` (flat) | `← <txt>` | muted | short `tool_result` (≤120c, non-recv) | stream-json |
| `.tool-result-block` `<details>` | `Nl · headline` | muted, body is text | long generic `tool_result` | stream-json |
| `.tool-result-block` `<details open>` | `recv ← <txt>` | muted, body is markdown | `tool_result` correlated to a prior `recv` tool_use via id | stream-json |
@ -105,7 +105,7 @@ isn't in the built-in `fmtToolUse` switch:
This keeps `mcp__matrix__send_message` and similar from
dumping raw JSON.
## Inline ask-operator answer
## Inline ask-operator answer (#666)
When an agent calls `mcp__hyperhive__ask` with `to == "operator"`
(default), the rich tool-use renderer mounts an empty

View file

@ -6,8 +6,8 @@ claude has access to in return.
## The loop
Each agent harness (`hive serve`, with role picked from `$HIVE_ROLE`
— `"agent"` for sub-agents, `"manager"` for the manager — one
binary, not two) runs:
— `"agent"` for sub-agents, `"manager"` for the manager; post-#598
this is one binary not two) runs:
1. Long-poll `Recv` on its socket. The host-side broker
(`broker.rs::recv_blocking_batch`) returns immediately if there's
@ -31,8 +31,8 @@ binary, not two) runs:
(`Bus::emit_status("rate_limited")`), sleeps
`HIVE_RATE_LIMIT_SLEEP_SECS` (default 300), then retries.
The dashboard and per-agent page show a `⊘ rate limited` badge
while the harness is parked. **Auth-failed detection**: both
stdout and stderr pumps also match
while the harness is parked. **Auth-failed detection** (closes
#419): both stdout and stderr pumps also match
`AUTH_FAIL_MARKERS` (`"authentication_failed"`, `401`, etc.).
On match the harness writes `{state_dir}/hyperhive-needs-login`,
emits `needs_login_idle` status, requeues the inflight message
@ -40,7 +40,7 @@ binary, not two) runs:
the same path used at boot. The operator re-authenticates via
the per-agent web UI login flow; on success the sentinel is
cleared and the queued message drives the next turn normally.
**Mtime-snapshot resumption**: `wait_for_login`
**Mtime-snapshot resumption** (closes #542): `wait_for_login`
snapshots the `~/.claude/` dir (newest file mtime + file count)
at entry and only resumes when that snapshot advances — not
just when credentials exist on disk. This prevents a silent
@ -176,8 +176,8 @@ socket at `/run/hive/` once at startup:
- `claude-system-prompt.md` — rendered from
`hive-ag3nt/prompts/system.md` by `hive_ag3nt::prompt::render`:
HTML-comment markers (`<!-- role:agent -->...<!-- /role:agent -->`,
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 (closes
#519); everything else is shared. Five placeholders are then
substituted: `{label}` (short agent name), `{qualified_label}`
(hive-qualified `name@domain` form), `{operator_pronouns}`,
`{hive_identity}` (e.g. `` on hive `pr1ma` ``; empty when
@ -350,9 +350,10 @@ meta's.
`agent.nix`, commits the changes, and calls `request_apply_commit`
with the commit sha — the first ApplyCommit on a freshly-init'd
config creates the container. Fails if a proposed repo for this
name already exists. (The operator can also direct-spawn an empty
agent from the dashboard's `◆ R3QU3ST SP4WN` button, which routes
via `HostRequest::RequestSpawn`.)
name already exists. (The pre-#442 path through a separate
manager-side `request_spawn` was removed; operator can still
direct-spawn an empty agent from the dashboard's `◆ R3QU3ST SP4WN`
button which routes via `HostRequest::RequestSpawn`.)
- `kill(name)` — graceful stop. No approval required.
- `start(name)` — start a stopped sub-agent. No approval.
- `restart(name)` — stop + start. No approval.
@ -397,7 +398,7 @@ meta's.
approval (use `remind` for unapproved self-wake). Long downtime
fires once per recurring row on resume (catch-up clamp).
- `edit_schedule(id, body?, description?, interval_seconds?, next_fire_at_unix?, targets_add?, targets_remove?)` —
partial-update a schedule. Pass only the fields to
partial-update a schedule (#474/#478). Pass only the fields to
change; absent fields are left alone. `targets_add` / `targets_remove`
mutate the recipient list in the same transaction; re-adding a
previously-cancelled target drops its tombstone + history (fresh

View file

@ -2,9 +2,9 @@
Two web surfaces share the same skeleton: the dashboard (port 7000)
and the per-agent UIs (every container — including the manager —
hashes into :8100-8999 via `lifecycle::agent_web_port`'s FNV-1a).
Both are SPAs — `GET /` returns a static shell, `/api/state`
returns JSON, JS renders. No full-page reloads.
hashes into :8100-8999 via `lifecycle::agent_web_port`'s FNV-1a,
since #753). Both are SPAs — `GET /` returns a static shell,
`/api/state` returns JSON, JS renders. No full-page reloads.
## Shape (shared by both)
@ -33,7 +33,7 @@ returns JSON, JS renders. No full-page reloads.
based, no `innerHTML` — XSS-safe); markdown bodies get the
same treatment via `marked`'s autolink (npm dep, replacing the
vendored UMD bundle), with the rendered `<a>`s rewritten to
`target="_blank"`.
`target="_blank"` (issue #233).
- `GET /api/state` → JSON snapshot the JS app renders into the
DOM. Includes a top-level `seq` (the dashboard event channel's
high-water mark at the moment the snapshot was assembled);
@ -50,7 +50,7 @@ returns JSON, JS renders. No full-page reloads.
~200 broker messages wrapped in `{ seq, events }`) on the
dashboard and `GET /events/history` (last 2000 `LiveEvent`s
also wrapped in `{ seq, events }`) on the agent.
**SSE multiplexing**: the dashboard uses a
**SSE multiplexing** (#448): the dashboard uses a
`SharedWorker` (`stream-worker.js`) to hold one upstream
`EventSource` per URL. All same-origin tabs share this worker
— a second dashboard tab joins the existing connection rather
@ -59,7 +59,7 @@ returns JSON, JS renders. No full-page reloads.
page re-subscribes (gets a synthetic `open` event immediately
if the upstream is already connected). Falls back gracefully
when `SharedWorker` is unavailable (e.g. some private-mode
browsers). **Worker-death self-heal**: Firefox kills
browsers). **Worker-death self-heal** (#515): Firefox kills
"idle" SharedWorkers under memory pressure with no client-side
signal — the port silently goes no-op. The worker now pings
every connected port every 30s; the client bumps a
@ -72,84 +72,6 @@ returns JSON, JS renders. No full-page reloads.
bfcache-restore uses). Recovery is per-tab; pings are
invisible on the healthy path.
### Shared terminal pane
Both surfaces' scrollable log streams (`#msgflow` on the dashboard,
`#live` on the per-agent page) are backed by the shared terminal
factory in `@hive/shared/terminal.js`. The factory wires up
sticky-bottom auto-scroll, a "↓ N new" pill, history backfill, and
SSE replay. Pages register a `kind → renderer` map; unknown kinds
fall through to a JSON-dump note row. The factory ships three row
shapes the renderers call:
- `api.row(cls, text)` — single-line row with an inline `linkify`
pass over the text.
- `api.details(cls, summary, body)` — collapsible `<details>` with
a `<pre>` body (used by long tool-results and stack traces).
- `api.detailsDiff(cls, summary, body)` — same shape, splits the
body on newlines and tags each line as `diff-add` / `diff-del` /
`diff-ctx` so the renderer's diff bodies get coloured without
emitting raw HTML.
**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
flips when a scroll event lands further than `NEAR_BOTTOM_PX = 48`
from the bottom. New rows then either snap to bottom (when sticky)
or bump the unseen-count and surface the "↓ N new" pill. The snap
is a brief 140ms ease-out (`SCROLL_ANIM_MS`) — the browser's
default `behavior: 'smooth'` ~500ms reads as "still smooth, but
visibly slow"; 140ms feels snap-y while still reading as motion
rather than a jump. Distances under `SCROLL_SNAP_PX = 24`
short-circuit to instant — animating a 12px nudge would just be
jitter. Each new snap cancels the previous `requestAnimationFrame`
so a burst of mutations coalesces into one ride to the latest
bottom; the per-frame step re-reads `scrollHeight - clientHeight`
so mutations landing mid-animation extend the destination smoothly
rather than land short.
**Mid-animation scroll-event guard.** The scroll handler's
`isNearBottom` check would flip `stickToBottom` false mid-snap as
the smooth animation eases through positions that are technically
"not near bottom yet", which would strand the operator partway. A
`smoothScrollingUntil` timestamp gates the scroll handler — set to
the animation end + ~80ms headroom, re-armed on each fresh snap.
Programmatic `scrollTop` writes (the animation's per-frame update)
fire scroll events that the gate swallows.
**Post-append `MutationObserver`.** Renderers commonly call
`api.row(cls, text)` to create the row shell then append more
children (badges, multi-line bodies, tool result panes) after the
factory returned. The initial sticky-snap fires off the row's
empty shape; the renderer's later appends grow the row past the
visible bottom. A `MutationObserver` on the log subtree fires once
per microtask after each batch of synchronous mutations and snaps
again when `stickToBottom` is true. Programmatic `scrollTop`
writes don't re-trigger the observer (scroll isn't a DOM
mutation), so no feedback loop. The pre-append
`nearBottomBeforeAppend` snapshot is still useful — it keeps the
initial visual lag to one frame instead of one microtask + frame.
**Backfill + SSE.** Cold load fetches `historyUrl` (replay), then
subscribes to `streamUrl` (live tail). Both endpoints return
`{ seq, events }` so the client can dedupe — events with
`seq <= snapshot.seq` from the SSE stream are dropped silently
(the snapshot already covers them). History rows render with a
`.no-anim` class so they don't stagger in like live events. The
optional `streamFactory(url)` callback lets the dashboard hand
the factory a `SharedWorker`-backed `EventSource` facade (so
multiple tabs share one upstream connection — see *SSE
multiplexing* above); when omitted, the factory falls back to a
plain `new EventSource(url)`.
**`linkify` (text-node based).** Bare `http(s)://` URLs in row
text get wrapped in `<a target="_blank" rel="noopener noreferrer">`
inside a fresh text node, so the autolinker never touches
`innerHTML` and untrusted row content can't smuggle markup. The
trailing-punctuation strip keeps `.,;:` outside the link surface.
Markdown bodies go through `marked` separately and get the same
target rewrite.
The JS app handles all `form[data-async]` submissions via a delegated
listener: read `data-confirm`, swap the button to a spinner, POST
`application/x-www-form-urlencoded`, re-enable the button on success
@ -194,7 +116,7 @@ titled header, a close button, and a scrollable body. Closes on
the button, a backdrop click, or `Escape`. `Panel.open(title,
node)` swaps the body; the JS builders for file previews,
approval diffs, and journald logs all render into it. **The
drawer width is drag-to-resize**: a thin 6px hit-strip on
drawer width is drag-to-resize** (#451): a thin 6px hit-strip on
the left edge captures pointer events, resizes the drawer in
real-time (pointer capture keeps dragging even if the cursor
outpaces the handle), and persists the chosen width to
@ -432,7 +354,7 @@ with `--base-href /matrix/`, swappable via
`services.hyperhive.matrix.gui.package`) served by the hive-gateway
nginx container at `/matrix/` when
`services.hyperhive.matrix.gui.enable` is on (defaults to
`matrix.enable`). c0re signals availability via the
`matrix.enable`, #635). c0re signals availability via the
`HIVE_MATRIX_GUI_ENABLED` env var → `state.matrix_gui_enabled` in
`/api/state`; the gateway does the actual static serving.
@ -442,7 +364,7 @@ in once with the in-host tuwunel homeserver URL
The unified nginx-front re-root to
`https://matrix.${hyperhive.domain}` + `.well-known/matrix/client`
auto-discovery lives in `docs/gateway.md` (atlas's lane).
auto-discovery is tracked in #609 (atlas's lane, post-#15).
### FL0W page (`/flow.html`)
@ -461,14 +383,7 @@ newest-first.
**MESS4GE FL0W** — live broker tail wrapped in a `.terminal-wrap`.
Cold load backfills the last ~200 messages from `/dashboard/history`;
live frames arrive on `/dashboard/stream`. Each row is one broker
event — `sent` or `delivered` — with `from → to: body`. The row is
a `flex-wrap: wrap` container holding ts / arrow / from / sep / to
chips inline; the **body wraps to its own full-width line below**
the chips (`flex: 1 1 100%`) so the body always gets the full row
width down to the content edge — long timestamps + agent names
used to push the body ~30ch in and force awkward narrow-column
wraps. `min-width: 0` keeps `word-break: break-word` effective so
the body doesn't force the row wider than its container. Sticky-
event — `sent` or `delivered` — with `from → to: body`. Sticky-
bottom auto-scroll + "↓ N new" pill. Below the stream sits a
terminal-style compose box: `@name` picks the recipient (sticky via
localStorage; auto-complete from the live container list, Tab/Enter
@ -567,7 +482,7 @@ fetch entirely.
`ContainerView.context_window_tokens`; the badge goes yellow
≥ 50% and red ≥ 75% of that window (the harness compaction
watermarks). When the window can't be resolved the badge falls
back to fixed 100k / 150k thresholds.
back to fixed 100k / 150k thresholds. (issue #66)
- Line 2: status badges only (no per-card action buttons — actions
moved to the **selection bar**, see below).
- Line 3: drill-in triggers —
@ -577,7 +492,7 @@ fetch entirely.
A unit dropdown (harness service / full machine journal) and
a refresh button live in the panel. The panel uses a column-flex
layout so the `<pre>` log surface fills the full remaining panel
height; scroll happens inside the `<pre>`, not the side
height (#541); scroll happens inside the `<pre>`, not the side
panel body.
- Plain navigation links (config repo, forge profile,
`dashboardLinks` extras) now live in the icon-only nav strip
@ -623,26 +538,6 @@ needed). The joint at the row's own depth column is `├` (more
siblings below) or `└` (last sibling at this depth — vertical
stops at the row's icon midline).
**Indent + lane geometry.** Each depth level shifts the row right
by `1.8em` (the lane width). The per-depth ladders are hardcoded
for six levels — enough for any plausible hive topology, and the
typed `attr()` function from CSS Values 5 that would collapse
this to one rule is still partial-support (Chromium-only as of
2026). The `.tree-prefix` span sits absolutely positioned with
`left: -<depth>*1.8em` so its right edge meets the row content
(the icon) and its leftmost lane lines up with top-level rows'
icons at `x = 0`. Each `.tree-lane` is `flex: 0 0 1.8em` so all
lanes have equal width. Continuation bars are drawn at lane
center (`left: 0.6em`, `border-left: 1px solid currentColor`,
`top: 0; bottom: 0`) and extend through `.containers { gap: 0.4em }`
into the next sibling's prefix (`bottom: -0.4em` on the prefix
span itself) so adjacent ancestor lines visually merge into one
unbroken vertical line. The horizontal stub at a row's own joint
lands at the icon midline so the L/T meets the icon edge cleanly.
When every container has `parent = null` (pre-topology state) the
`[data-depth]` attribute is absent on every row and these rules
are no-ops — the layout reads exactly like the legacy flat list.
### Selection bar
Per-card action buttons (`R3ST4RT` / `ST0P` / `ST4RT` / `R3BU1LD` /
@ -755,13 +650,13 @@ not ours.
the sentinel `[cancelled]`. Same code path as a real answer.
- `POST /request-spawn` — queue a Spawn approval.
- `POST /update-all` — rebuild every stale container.
- `POST /api/rebuild-queue/{id}/cancel` — drop a `Queued` entry.
Refuses `Running` / terminal-state entries (in-flight
- `POST /api/rebuild-queue/{id}/cancel` — drop a `Queued` entry
(#447). Refuses `Running` / terminal-state entries (in-flight
rebuilds can't be safely interrupted). Always 200; body is
`{"cancelled": true}` on a successful flip or
`{"cancelled": false}` when the entry was not in `Queued` state.
- `POST /api/agent/{name}/mark-all-read` — ack all pending broker
messages for `{name}`. Backfills `delivered_at` for rows
messages for `{name}` (#559). Backfills `delivered_at` for rows
not yet delivered and sets `acked_at = now`. Returns
`{ "marked": N }`. Agent name validated against
`[a-z0-9_-]`, 1-63 chars; 400 on bad input.
@ -810,7 +705,7 @@ not ours.
`{ targets, body, first_fire_at_unix, interval_seconds?, description? }`.
Agent-initiated schedules go through the approval queue instead
(manager MCP `request_schedule_prompt`).
- `PATCH /api/schedules/{id}` — partial edit. JSON body
- `PATCH /api/schedules/{id}` — partial edit (#474). JSON body
`{ body?, description?, interval_seconds?, next_fire_at_unix?,
targets_add?, targets_remove? }`.
Missing key = "leave alone"; explicit `null` on
@ -828,7 +723,7 @@ not ours.
`{ targets?: ["name", …] }` cancels just those recipients;
absent or empty body cancels the whole schedule.
- `POST /api/schedules/{id}/fire-now` — out-of-band manual
pulse. Fires the schedule body once immediately to
pulse (#467). Fires the schedule body once immediately to
every active target. Recurring schedules: `next_fire_at_unix`
is untouched; the regular cadence continues. One-shots: the
schedule is consumed (cancelled) after the manual fan-out.
@ -912,17 +807,13 @@ Three fixed-position layers frame a full-viewport terminal:
**Fixed-overlay header** (`<header class="agent-header">`): frosted
glass — `backdrop-filter: blur` lets scrolled terminal rows show
through. Three flex columns:
through. Three flex columns (#394 redesign):
- **Agent icon** (`<img class="agent-icon">`): fixed-size square
identity anchor — `width: 5em; height: 5em` with explicit pixel
sizing so the `<img>`'s intrinsic (large) dimensions don't push
the parent flex container open via `align-items: stretch`-driven
height feedback. 5em ≈ header content area (header `min-height: 6em`
minus `2 × 0.5em` padding). `align-self: flex-start` keeps the
icon stuck to the top so a state-row line-wrap doesn't drag it
down with it. Falls back to the dimmed hyperhive mark on load
error.
identity anchor (5em, `width: 5em; aspect-ratio: 1;
align-self: flex-start` — capped so a tall state-row doesn't
inflate the icon, #411). Falls back to the dimmed hyperhive mark
on load error.
- **Main column** (`.agent-header-main`): two rows.
- Row 1 (`.agent-header-title-row`): title (`<h2 id="title">`) +
meta-nav (`<nav id="meta-links">`). Meta-nav renders
@ -970,11 +861,8 @@ through. Three flex columns:
(POST confirm → `POST /api/logout`; SIGINTs any in-flight turn,
wipes OAuth credential files, flips the agent to `needs_login`
— session history preserved). All destructive actions require
one extra click to acknowledge — rare ops shouldn't live in the
primary state strip. The popover's display rules are scoped to
`:not([hidden])` so the `[hidden]` HTML attribute's UA `display:
none` isn't overridden by the author CSS's `display: flex` —
the popover stays hidden until JS removes the attribute.
one extra click to acknowledge (#394 — rare ops shouldn't live
in the primary state strip).
`/api/state` is fetched once on cold load (+ while
`status === 'needs_login_in_progress'`); all other updates arrive via
@ -983,7 +871,7 @@ tooltip, and `qualified_label` — the hive-qualified agent name
(`name@domain` form when `HYPERHIVE_HIVE_DOMAIN` is set, otherwise
just `name`). The frontend uses `qualified_label` to set the browser
tab title so two tabs from different hives are distinguishable; the
header `<h2 id="title">` stays short.
header `<h2 id="title">` stays short (#589 phase A).
**Main content** (`<main class="agent-main">`): fills the viewport
and scrolls behind the fixed header + footer.
@ -1160,26 +1048,14 @@ shaped).
`wait_for_login` entry.
- `GET /events/history` — replay buffer for the terminal.
- `GET /screen` — VNC viewer page (minimal RFB-over-WebSocket
renderer — deliberately thin, just enough to display the
desktop + forward pointer + keyboard. A production-grade viewer
would vendor noVNC; this file ships the minimal in-tree variant).
Only accessible when `hyperhive.gui.enable = true` in the agent's
`agent.nix`; the harness shows a 🖥 screen link in the state row
when `gui_vnc_port` is present. Toolbar: `⤢ fit` CSS-downscales
the canvas to the window via `relayoutCanvas()` setting explicit
pixel dimensions on the canvas — *not* CSS `max-width/max-height`,
because a flex item's automatic minimum size (`min-width: auto`
resolves to the canvas's intrinsic framebuffer resolution) silently
clamps `max-*` back up, making fit mode a no-op that just centred +
clipped the oversized canvas. The fit-mode rules pin the canvas
with `flex: none; min-width: 0; min-height: 0` so the JS-set size
sticks. `⤡ match size` sends an RFB `SetDesktopSize` request so the
server (weston) changes its real output resolution to the window
dimensions; enabled once the server advertises the
`ExtendedDesktopSize` pseudo-encoding (`-308` rect in the header).
Fit-mode state persists in `localStorage` (`screen-fit`); default
is on. Pointer coordinates are rescaled in `sendPointer` so clicks
land on the right pixel regardless of CSS scale.
renderer). Only accessible when `hyperhive.gui.enable = true`
in the agent's `agent.nix`; the harness shows a 🖥 screen link
in the state row when `gui_vnc_port` is present. Toolbar:
`⤢ fit` CSS-downscales the canvas to the window; `⤡ match size`
sends an RFB `SetDesktopSize` request so the server (weston)
changes its real output resolution to the window dimensions —
enabled once the server advertises the `ExtendedDesktopSize`
pseudo-encoding (issue #133).
- `GET /screen/ws` — raw RFB byte relay: proxies WebSocket
frames to the weston VNC server at `127.0.0.1:<vnc_port>`.
Transparent to any RFB variant. VNC port comes from

View file

@ -3,16 +3,18 @@
@import "@hive/shared/base.css";
@import "@hive/shared/terminal.css";
/* ─── full-screen layout overrides ─────────────────────────────────
The agent page mounts a full-viewport terminal under a fixed
frosted-glass header + composer pair. See docs/web-ui.md::Per-agent
page for the layer / pill / side-panel structure; rules below
override the in-page defaults from @hive/shared. */
/* ─── full-screen vibec0re overhaul (issue #360) ──────────────────
Layout shape: fixed-position frosted-glass header at top, fixed-
position composer at bottom, full-viewport terminal in between.
The terminal scrolls — its text passes BENEATH the floating
header/composer with backdrop-filter blur for the frosted look.
Inbox + loose-ends move into the side-panel flyout; header pills
surface their counts as the only chrome they get. */
:root {
/* 6em min-height accommodates the full-height agent icon (5em +
padding) alongside the two-row main column (title + nav-links
on top, state strip below). */
/* Bumped to 6em (#394) so the agent icon can be a full-height
square identity anchor without crowding the two-row main column
(title + nav-links on top, state strip below). */
--agent-header-h: 6em;
--agent-composer-h: 3.6em;
--agent-frost-bg: rgba(30, 30, 46, 0.72);
@ -84,7 +86,7 @@ body.agent-shell {
box-shadow: 0 6px 18px rgba(0, 0, 0, 0.35);
}
/* Main column: title row on top, state strip below. Centred
/* Main column: title row on top, state strip below (#394). Centred
vertically against the full-height icon on the left. */
.agent-header-main {
display: flex;
@ -138,10 +140,12 @@ h2, h3 {
text-shadow: 0 0 8px rgba(203, 166, 247, 0.4);
}
.agent-icon {
/* Square identity anchor — explicit 5em sizing + align-self.
See docs/web-ui.md::Per-agent page (Agent icon) for the
intrinsic-dim-pushes-parent-flex-open + sticks-to-top
rationale. */
/* Square identity anchor (#394 — mara's spec). Explicit em sizing
so the <img>'s intrinsic (large) dimensions don't push the
parent flex container open via `align-items: stretch`-driven
height feedback. Width = header content area (header min-h 6em
- 2 × 0.5em padding ≈ 5em). Sticks to the top so a state-row
wrap doesn't drag the icon down with it. (#411) */
width: 5em;
height: 5em;
flex-shrink: 0;
@ -152,9 +156,9 @@ h2, h3 {
}
/* Meta-nav links (stats / screen / forge / dashboard / extras) —
no underline; hover lights with cyan glow + subtle background
tint. Reads as a row of soft tabs rather than default-styled
inline anchors. */
no underline (#394 mara's spec); hover lights with cyan glow +
subtle background tint. Reads as a row of soft tabs rather than
default-styled inline anchors. */
.agent-nav-link {
color: var(--cyan);
text-decoration: none;
@ -172,7 +176,7 @@ h2, h3 {
}
/* Overflow menu trigger — `⋯` round button on the right of the
pills row. Quiet by default, lights on hover / open. */
pills row. Quiet by default, lights on hover / open (#394). */
.overflow-btn {
background: transparent;
border: 1px solid var(--purple-dim);
@ -196,11 +200,13 @@ h2, h3 {
box-shadow: 0 0 10px -2px var(--purple);
}
/* Overflow popover — rebuild + new-session + logout (and the
dashboard back-link, prepended in app.js setHeader). Positioned
in JS so the menu's top-right corner anchors under the trigger
button. See docs/web-ui.md::Per-agent page (Overflow button)
for the `:not([hidden])` scoping rationale. */
/* Overflow popover — rebuild + new-session (and the dashboard
back-link, prepended in app.js setHeader). Positioned in JS so
the menu's top-right corner anchors under the trigger button.
`:not([hidden])` scoping (#411): the `[hidden]` HTML attribute
sets `display: none` via the UA stylesheet, but author CSS's
`display: flex` would override that. Scope display rules so
they apply only when the menu is unhidden. */
.overflow-menu:not([hidden]) {
display: flex;
flex-direction: column;
@ -389,12 +395,14 @@ a:hover { color: var(--fg); text-shadow: 0 0 12px rgba(137, 220, 235, 0.9); }
}
.btn-login { color: var(--amber); border-color: var(--amber); }
.btn-cancel { color: var(--red); border-color: var(--red); font-size: 0.85em; padding: 0.15em 0.6em; }
/* Orphaned rules — left here as a tombstone so a search for the
class name finds them. Live consumers gone:
- `.btn-rebuild` was a per-agent header chip (covered now by
`.overflow-item-rebuild` in the overflow menu).
- `.btn-send` was a green send-button variant — the dashboard's
compose form that used it is retired. */
/* `.btn-rebuild` was the per-agent header chip — moved into the
overflow menu in #394 (`.overflow-item-rebuild` covers it now).
The dashboard has its own `.btn-rebuild` rule for the per-row
R3BU1LD form on the SW4RM tab; this one was specific to the
per-agent header.
`.btn-send` was a green send-button variant — orphaned since
the dashboard's compose form was retired; no live consumer left
in either the agent or dashboard tree. */
.sendform { display: flex; gap: 0.6em; margin-top: 0.5em; }
.sendform input {
font-family: inherit; font-size: 1em;
@ -416,10 +424,10 @@ a:hover { color: var(--fg); text-shadow: 0 0 12px rgba(137, 220, 235, 0.9); }
}
.loginform input:focus { outline: 1px solid var(--purple); }
/* Show / hide toggle for the masked OAuth-code input. Quiet by
default (muted border + transparent bg), lights amber on hover
/ when pressed (`aria-pressed="true"`) so the operator sees at
a glance whether the code is currently visible. */
/* #568: show / hide toggle for the masked OAuth-code input. Quiet
by default (muted border + transparent bg), lights amber on
hover / when pressed (aria-pressed="true") so the operator
sees at a glance whether the code is currently visible. */
.loginform-reveal {
font-family: inherit;
font-size: 1em;
@ -481,7 +489,7 @@ pre.diff {
/* Inbox / loose-ends rows: header (from / sep / ts) on one line,
body on its own line below — gives the body the full panel width
instead of squeezing it into a fourth grid column that wrapped
long messages over many narrow lines. */
long messages over many narrow lines (issue #376). */
.agent-inbox li {
padding: 0.4em 0;
display: block;
@ -544,16 +552,15 @@ pre.diff {
.agent-inbox .answer-form button:disabled { opacity: 0.5; cursor: default; }
.agent-inbox .answer-status { color: var(--muted); align-self: center; }
/* Inline answer slot mounted under each `ask → operator` row in
the live terminal stream. Mirrors the side-panel `.answer-form`
/* #666: inline answer slot mounted under each `ask → operator` row
in the live terminal stream. Mirrors the side-panel `.answer-form`
look-and-feel — same textarea, same send button — so the operator
doesn't have to context-switch between "answering in the panel"
and "answering inline". Empty slot collapses to nothing (no
margin) so pre-bind rows stay tidy; populated slot gets a thin
top divider to separate the question body from the form. A
`[resolved]` tag (neutral, covers answered / cancelled /
TTL-expired uniformly) replaces the form once the question
leaves the pending list. */
doesn't have to context-switch between "answering in the panel" and
"answering inline". Empty slot collapses to nothing (no margin) so
pre-bind rows stay tidy; populated slot gets a thin top divider to
separate the question body from the form. Resolved tag (the
struck-through `[answered ✓]`) replaces the form once the
question's been answered. */
.live .ask-answer-inline-slot:empty { display: none; }
.live .ask-answer-inline-slot {
margin-top: 0.5em;
@ -606,10 +613,10 @@ pre.diff {
text-decoration-color: var(--muted);
}
/* "mark all read" header row sits above the recent-messages list
in the inbox side-panel flyout. Same look as the answer-form
button (mauve hover, bg-elev background) so they read as part
of the same affordance family. */
/* #559: "mark all read" header row sits above the recent-messages
list in the inbox side-panel flyout. Same look as the answer-form
button (mauve hover, bg-elev background) so they read as part of
the same affordance family. */
.agent-inbox .inbox-mark-all-row {
display: flex;
gap: 0.6em;
@ -690,9 +697,8 @@ pre.diff {
text-shadow: 0 0 6px rgba(243, 139, 168, 0.55); }
.status-badge.status-needs-login { color: var(--amber); border-color: var(--amber); }
.status-badge.status-offline { color: var(--muted); border-color: var(--muted); }
/* Orphaned tombstone — `.btn-dashlink` chip that lived beside the
title was moved into the overflow menu (`.overflow-item-dashboard`
covers it now). */
/* Orphaned in #394 — `.btn-dashlink` chip beside the title moved
into the overflow menu (`.overflow-item-dashboard` covers it). */
.btn-cancel-turn {
font-family: inherit;
font-size: 0.8em;
@ -710,8 +716,8 @@ pre.diff {
background: rgba(243, 139, 168, 0.1);
box-shadow: 0 0 10px -2px currentColor;
}
/* Orphaned tombstone — `.btn-new-session` round-pill moved into
the overflow menu (`.overflow-item-new-session` covers it; the
/* Orphaned in #394 — `.btn-new-session` round-pill moved into the
overflow menu (`.overflow-item-new-session` covers it; the
`:disabled` opacity treatment lives on the shared
`.overflow-item:disabled` rule). */
.state-badge {
@ -787,10 +793,7 @@ pre.diff {
/* Tail pill (↓ N new): nudged up so it floats clear of the composer
rather than colliding with the frosted bar. z-index bumped above
the composer (z-30) so the pill sits on the top layer instead of
being clipped by the floating chrome. (Pill is anchored in
`.agent-main` rather than `.terminal-wrap` — see
docs/web-ui.md::Per-agent page Terminal-wrap paragraph for the
backdrop-filter stacking-context rationale.) */
being clipped by the floating chrome (issue #375). */
.agent-main .tail-pill {
bottom: calc(var(--agent-composer-h) + 0.6em);
z-index: 35;
@ -840,9 +843,10 @@ pre.diff {
/* Row + pill + details styling moved to hive-fr0nt::TERMINAL_CSS. */
/* ─── side panel (singleton drawer) ────────────────────────────────
Inbox + loose-ends details open here instead of expanding inline.
Copy of the dashboard's side-panel pattern — candidate for
extraction into @hive/shared once both surfaces stabilize. */
Inbox + loose-ends details open here instead of expanding inline
(issue #360). Copy of the dashboard's side-panel pattern —
candidate for extraction into @hive/shared once both surfaces
stabilize. */
.side-panel {
position: fixed;
inset: 0;

View file

@ -79,7 +79,8 @@ window.marked = marked;
// ─── side panel (singleton drawer for inbox + loose-ends flyouts) ──────
// Shared shape with the dashboard's panel. Candidate for extraction
// into @hive/shared once both surfaces stabilise.
// into @hive/shared in a follow-up — keeping the duplication for
// now to land #360 without simultaneously refactoring the dashboard.
const Panel = (() => {
const root = $('side-panel');
const titleEl = $('side-panel-title');
@ -140,12 +141,13 @@ window.marked = marked;
// ─── state rendering ────────────────────────────────────────────────────
function setHeader(label, qualifiedLabel, dashboardPort) {
const title = $('title');
// Title is just the glowing identity glyph — DASHB04RD, R3BU1LD,
// NEW SESSION live in the overflow `⋯` menu. Glow + uppercase
// styling from h2 / .agent-header-title-row. The glyphic title
// stays short (no @hive suffix) — the hive qualifier lives on
// the second row's `qualified` chip + the browser tab title so
// the cinematic header reads cleanly at a glance.
// Title is now just the glowing identity glyph — DASHB04RD,
// R3BU1LD, NEW SESSION all live in the overflow `⋯` menu now
// (#394). Glow + uppercase styling from h2 / .agent-header-title-row.
// The glyphic title stays short (no @hive suffix) — the hive
// qualifier lives on the second row's `qualified` chip + the
// browser tab title so the cinematic header reads cleanly at a
// glance (#589).
title.textContent = `◆ ${label} ◆`;
// Document title carries the qualified name so the browser's tab
// bar disambiguates between same-named agents on different hives
@ -158,17 +160,20 @@ window.marked = marked;
populateOverflowMenu(label, dashUrl);
}
// Overflow popover: dashboard back-link + rebuild + new-session +
// logout. Rare + destructive actions live here behind one extra
// click (the operator rebuilds from the host dashboard normally).
// See docs/web-ui.md::Per-agent page (Overflow button).
// Overflow popover: dashboard back-link + rebuild + new-session.
// Per #394 mara's spec — rebuild + new-session both moved off the
// header strip into the `⋯` menu (rare actions, both destructive
// enough to warrant one extra click; the operator rebuilds from
// the host dashboard normally). Dashboard link also slotted in so
// every "leave this page" action lives in one menu.
let overflowMenuPopulated = false;
function populateOverflowMenu(label, dashUrl) {
const menu = $('overflow-menu');
if (!menu) return;
menu.replaceChildren();
// ↑ dashboard — host dashboard back-link.
// ↑ dashboard — host dashboard back-link (was `.btn-dashlink`
// beside the title pre-#394).
menu.append(el('a', {
class: 'overflow-item overflow-item-dashboard',
href: dashUrl,
@ -222,14 +227,15 @@ window.marked = marked;
});
menu.append(newSessBtn);
// 🔓 logout — SIGINTs claude, wipes the credentials dir, flips
// the harness LoginState to NeedsLogin. The turn loop's next
// iteration parks in wait_for_login; a fresh `claude auth login`
// from the dashboard re-arms it. Operator has to re-paste OAuth
// creds on the login screen after, but the --continue session
// history is preserved (the backend wipe is narrowed to just
// .credentials.json + mcp-needs-auth-cache.json) — so the agent
// picks up where it left off on the next turn after re-login.
// 🔓 logout (#576) — SIGINTs claude, wipes the credentials dir,
// flips the harness LoginState to NeedsLogin. The turn loop's
// next iteration parks in wait_for_login; a fresh `claude auth
// login` from the dashboard re-arms it (#542 mtime resumption).
// Operator has to re-paste OAuth creds on the login screen after,
// but the --continue session history is preserved (#584 narrowed
// the backend wipe to just .credentials.json + mcp-needs-auth-
// cache.json) — so the agent picks up where it left off on the
// next turn after re-login.
const logoutBtn = el('button', {
type: 'button',
class: 'overflow-item overflow-item-logout',
@ -458,9 +464,8 @@ window.marked = marked;
if (termAPI) termAPI.row('turn-end-fail', '✗ ' + label + ' failed: ' + err);
}
}
// First arg is the URL path (relative to document base — see
// docs/web-ui.md::Per-agent relative paths); second is the
// slash-command label rendered in the local note.
// First arg is the URL path (relative to document base, #14);
// second is the slash-command label rendered in the local note.
const postCancelTurn = () => postSimple('api/cancel', '/cancel');
const postCompact = () => postSimple('api/compact', '/compact');
const postNewSession = () => postSimple('api/new-session', '/new-session');
@ -480,7 +485,7 @@ window.marked = marked;
return true;
case '/clear':
termAPI.clear();
// Detached `ask → operator` rows no longer have a live
// #666: detached `ask → operator` rows no longer have a live
// mount-point in the DOM — drop their slots so subsequent
// loose-ends reconciliation doesn't walk dead references.
pendingAskBinds.length = 0;
@ -832,11 +837,12 @@ window.marked = marked;
return wrap;
}
/** "mark all read" affordance for the agent's inbox flyout —
* see docs/web-ui.md::Per-agent page (Loose-ends flyout) for the
* cross-origin POST + count rendering. Returns a DOM row
* containing a button + an inline status pill; re-runs
* `onCleared` on success so the caller can refresh its own state. */
/** #559: "mark all read" affordance for the agent's inbox flyout.
* Returns a DOM row containing a button + an inline status pill.
* POSTs to the host dashboard's `/api/agent/{name}/mark-all-read`
* (damocles PR #566) and surfaces the `{ marked: N }` count back to
* the operator. Re-runs `onCleared` on success so the caller can
* refresh whatever state it owns. */
function buildInboxMarkAllRow(label, onCleared) {
const status = el('span', { class: 'inbox-mark-status' });
const btn = el('button', {
@ -890,12 +896,12 @@ window.marked = marked;
'inbox empty.'));
return wrap;
}
// "mark all read" header row drains the host broker's pending +
// delivered-unacked rows for this agent. Visible rows here are
// the most-recent-N regardless of ack state, so the list itself
// doesn't visually empty on click — the status pill confirms
// the drain count, and the next turn_start's "unread" badge
// will read zero.
// #559: "mark all read" header row drains the host broker's
// pending + delivered-unacked rows for this agent (damocles PR
// #566). Visible rows here are the most-recent-N regardless of
// ack state, so the list itself doesn't visually empty on click —
// the status pill confirms the drain count, and the next
// turn_start's "unread" badge will read zero.
wrap.append(buildInboxMarkAllRow(currentLabel, () => {
// Refresh state so any UI surface that DOES depend on
// delivery state (eg future per-status filters) picks up
@ -1023,6 +1029,10 @@ window.marked = marked;
});
})();
// (#394) — `↻ new session` button moved into the overflow `⋯`
// menu and wired by `populateOverflowMenu()` above. Previously
// wired here as a static `#new-session-btn` in index.html.
// Track banner activity by reference-counting in-flight turns. A turn
// can begin while the previous turn_end is still in the pipeline (rare
// but happens on tight wake cycles), so we count rather than toggle.
@ -1064,8 +1074,9 @@ window.marked = marked;
rel: 'noopener',
title: lnk.label || '',
});
// Layout gap comes from `.agent-nav { gap }`. The trailing
// `→` is the "leaves this page" affordance.
// Layout gap comes from `.agent-nav { gap }` (#394) — drop
// the legacy per-link inline `marginLeft`. The trailing `→`
// is the "leaves this page" affordance.
a.append(((lnk.icon || '') + ' ' + (lnk.label || '')).trim() + ' →');
metaLinks.append(a);
});
@ -1143,7 +1154,7 @@ window.marked = marked;
marked.setOptions({ breaks: true, gfm: true });
div.innerHTML = marked.parse(src);
// marked autolinks URLs but leaves them same-tab — open them
// externally so a click never unloads the terminal.
// externally so a click never unloads the terminal. (issue #233)
div.querySelectorAll('a[href]').forEach((a) => {
a.target = '_blank';
a.rel = 'noopener noreferrer';
@ -1295,10 +1306,15 @@ window.marked = marked;
const d = detailsOpenMd(api, 'tool-use',
'ask → ' + to + (lines > 1 ? ` · ${lines}L` : ''),
q);
// When the ask targets the operator, mount an inline answer
// slot in the live terminal — see docs/web-ui.md::Per-agent
// page (Ask → operator inline-answer binding) for the slot
// registry + reconciler + [resolved] semantics.
// #666: when the ask targets the operator, mount an inline
// answer slot in the live terminal so the operator doesn't
// need to open the loose-ends side panel (or jump to Y3R C4LL
// on the dashboard) to respond. The slot starts empty and
// gets populated by `reconcileAskBinds()` once the
// loose-ends fetch identifies a matching pending question
// (by asker == this agent + question text). Resolved
// questions render as a struck-through [answered ✓] tag
// instead of a form.
if (to === 'operator') {
const slot = el('div', { class: 'ask-answer-inline-slot' });
// Stash the question text on the slot so the reconciler
@ -1340,13 +1356,12 @@ window.marked = marked;
: (c.content || '');
const sourceName = c.tool_use_id ? toolNameById.get(c.tool_use_id) : null;
const isMessageBearing = sourceName === 'mcp__hyperhive__recv';
// When an ask's tool_result lands the broker has just
// persisted the question with its assigned id. Refresh
// loose-ends so reconcileAskBinds finds the new entry and
// mounts the inline answer form under the rendered ask row.
// Skipped during history replay (the question's likely
// long-resolved; turn_end refresh on cold-load covers
// reconciliation).
// #666: when an ask's tool_result lands the broker has just
// persisted the question with its assigned id. Refresh loose
// ends so `reconcileAskBinds` finds the new entry and mounts
// the inline answer form under the rendered ask row. Skipped
// during history replay (the question's likely long-resolved;
// turn_end refresh on cold-load already covers reconciliation).
if (sourceName === 'mcp__hyperhive__ask' && !api.fromHistory) {
refreshLooseEnds();
}

View file

@ -8,10 +8,16 @@
</head>
<body class="agent-shell">
<!-- Fixed-overlay header — see docs/web-ui.md::Per-agent page
for the three-column layout (icon · main · pills). All asset
/ API hrefs are relative — see docs/web-ui.md::Per-agent
relative paths for the document-baseURI resolution model. -->
<!-- Fixed-overlay header (#394 redesign): two-row layout in the
main column — row 1 carries the title + meta-nav, row 2 carries
the live state strip. The agent icon eats the full header
height on the left as the identity anchor; flyout pills + an
overflow menu trigger sit on the right. Frosted glass over the
terminal — backdrop-filter blur shows the scrolled terminal
text behind.
All asset / API hrefs are relative — see docs/web-ui.md::Per-agent
relative paths for why (#14). -->
<header class="agent-header" id="agent-header">
<img class="agent-icon" src="icon" alt="">
@ -38,9 +44,9 @@
<!-- Right cluster: flyout triggers + overflow menu. Pills stay
hidden until their list is non-empty; the overflow `⋯` is
always visible. Rebuild + new-session + logout live inside
it — see docs/web-ui.md::Per-agent page (Overflow button)
for the rare-destructive-extra-click rationale. -->
always visible (rebuild + new-session live inside it per
#394 — both rare, both destructive, both deserve one extra
click). -->
<div class="agent-header-pills">
<button type="button" id="inbox-pill" class="header-pill header-pill-inbox" hidden
title="open inbox flyout">

View file

@ -62,10 +62,13 @@ html, body { height: 100%; background: var(--base); color: var(--text);
fit the wrap) and clip any sub-pixel rounding overflow. */
#canvas-wrap.fit { align-items: center; overflow: hidden; }
canvas { display: block; cursor: default; }
/* Pin the canvas to exactly the size relayoutCanvas() sets. See
docs/web-ui.md::Per-agent endpoints (GET /screen) for the
flex-item min-width:auto clamp that made fit mode a silent
no-op before this pinning. */
/* In fit mode relayoutCanvas() sets the canvas display size explicitly.
The canvas is a flex item, and flex items default to
min-width/min-height: auto — which resolves to the canvas's intrinsic
framebuffer resolution and clamps the JS-set size straight back up,
defeating the downscale (the bug behind #133 round 1). Pin the canvas
to exactly the size relayoutCanvas() sets: min-* 0 lifts the clamp,
flex: none stops flex grow/shrink from fighting it. */
#canvas-wrap.fit canvas { flex: none; min-width: 0; min-height: 0; }
#msg {
position: fixed; bottom: 1rem; left: 50%; transform: translateX(-50%);
@ -90,11 +93,13 @@ canvas { display: block; cursor: default; }
<div id="debug-log"></div>
<script>
// Minimal RFB-over-WebSocket renderer. Connects to `screen/ws` on
// the same host; the harness relays raw RFB bytes to the VNC server
// running inside the container. See docs/web-ui.md::Per-agent
// endpoints (GET /screen) for the design rationale + canvas-sizing
// implementation notes.
// Minimal RFB-over-WebSocket renderer.
// Connects to /screen/ws on the same host; the harness relays raw
// RFB bytes to the VNC server running inside the container.
//
// This is a deliberately thin implementation — enough to display the
// desktop and forward pointer + keyboard events. For a production-grade
// viewer, replace with noVNC (issue #52 vendors the full bundle).
(function () {
'use strict';
@ -118,13 +123,18 @@ canvas { display: block; cursor: default; }
});
// --- Fit-to-window toggle ---
// See docs/web-ui.md::Per-agent endpoints (GET /screen) for the
// localStorage persistence + canvas-intrinsic-resolution +
// pointer-rescale model.
// Scales the canvas down so the whole desktop is visible without
// scrolling. The canvas's intrinsic resolution (width/height attrs)
// is untouched — only its CSS display size changes, set explicitly
// by relayoutCanvas(). Pointer coordinates are rescaled in
// sendPointer to stay accurate. Persisted in localStorage; default
// is fit-on.
let fitMode = localStorage.getItem('screen-fit') !== 'off';
// Scale down (never up) to the wrap, preserving aspect ratio.
// Explicit px sizing — see GET /screen docs for the flex-item
// min-width:auto clamp this avoids.
// Size the canvas. In fit mode, scale down (never up) to the wrap,
// preserving aspect ratio. Explicit px sizing rather than CSS
// max-width/max-height: on a flex item those are overridden by the
// automatic minimum size, so fit mode was a silent no-op — the
// oversized canvas just got centred and clipped (issue #133).
function relayoutCanvas() {
if (fitMode && canvas.width && canvas.height
&& canvasWrap.clientWidth && canvasWrap.clientHeight) {
@ -156,9 +166,9 @@ canvas { display: block; cursor: default; }
// --- Match-size: resize the remote desktop to this window ---
// Sends an RFB SetDesktopSize request so the VNC server (weston)
// changes its actual output resolution to match the browser
// viewport — sharper than fit-mode's CSS downscale. Gated on the
// server's ExtendedDesktopSize advert; see docs/web-ui.md::Per-agent
// endpoints (GET /screen).
// viewport — sharper than fit-mode's CSS downscale. The button is
// enabled only once the server has advertised the ExtendedDesktopSize
// pseudo-encoding (a -308 rect). (issue #133)
let extDesktopSupported = false;
let screenId = 1; // captured from the server's ExtendedDesktopSize advert
matchBtn.addEventListener('click', () => {
@ -196,10 +206,10 @@ canvas { display: block; cursor: default; }
}
// --- WebSocket connection ---
// Path-relative URL — `document.baseURI` resolves against the
// page's URL so the agent page mounted under a nginx prefix
// (e.g. /agent/<name>/screen) still hits the right upstream.
// Swap protocol on top gives ws(s)://host/<prefix>/screen/ws.
// Path-relative so the agent page mounted under a prefix
// (e.g. /agent/<name>/screen via nginx, #14) still hits the right
// upstream. `document.baseURI` resolves against the page's URL;
// swapping protocol on top gives ws(s)://host/<prefix>/screen/ws.
const proto = location.protocol === 'https:' ? 'wss' : 'ws';
const wsUrl = new URL('screen/ws', document.baseURI);
wsUrl.protocol = proto + ':';
@ -563,8 +573,8 @@ canvas { display: block; cursor: default; }
canvas.height = fbH;
relayoutCanvas();
setStatus('connected', 'connected');
// Advertise Raw + the ExtendedDesktopSize pseudo-encoding so
// the server reports (and accepts) desktop-size changes.
// Advertise Raw + the ExtendedDesktopSize pseudo-encoding so the
// server reports (and accepts) desktop-size changes. (issue #133)
sendSetEncodings([0, -308]);
// Request full framebuffer update
requestUpdate(0, 0, 0, fbW, fbH);
@ -608,7 +618,7 @@ canvas { display: block; cursor: default; }
} else if (enc === EXT_DESKTOP_SIZE_U32) {
// ExtendedDesktopSize: w,h carry the new desktop dimensions;
// the rect body is nScreens(1) + pad(3) + nScreens×16. The
// header's x = change reason, y = request status.
// header's x = change reason, y = request status. (issue #133)
const nScreens = peekByte();
if (nScreens < 0) { chunks.unshift(b); totalBytes += 12; return false; }
const body = drainTo(4 + nScreens * 16);
@ -683,7 +693,7 @@ canvas { display: block; cursor: default; }
}
// SetDesktopSize (msg type 251): ask the server to change the desktop
// resolution. One screen at the origin, sized to the request.
// resolution. One screen at the origin, sized to the request. (#133)
function sendSetDesktopSize(w, h) {
const b = new Uint8Array(24);
b[0] = 251; b[1] = 0; // message-type + padding

View file

@ -1,7 +1,13 @@
// Shared dashboard helpers used by both index.html (./tabs.js) and
// flow.html (./flow.js): pure DOM helpers, the side-panel singleton,
// the OS-notification module, and the path-link / file-preview
// infrastructure for the side panel.
// Shared dashboard helpers — extracted from the original monolithic
// dashboard JS as step 1 of the #406 split. These bits are used by
// both the tab dashboard (index.html) and the flow page (flow.html):
// pure DOM helpers, the side-panel singleton, the OS-notification
// module, and the path-link / file-preview infrastructure for the
// side panel.
//
// Each page now has its own entry point — `./tabs.js` for index.html,
// `./flow.js` for flow.html — and both import from here directly
// (#406 steps 2 + 3 complete; #406 closed).
import { linkify as termLinkify } from '@hive/shared/terminal.js';
@ -51,23 +57,31 @@ export const form = (action, btnClass, btnLabel, confirmMsg, extra = {}, opts =
// tied to its caller, so they don't generalise cleanly. We can lift
// them when a second consumer needs the same shape.
// ─── shared-worker SSE pipe ─────────────────────────────────────────────
// Returns an EventSource-shaped facade backed by a SharedWorker that
// holds one upstream `new EventSource(url)` and fans events out to
// every connected tab. See docs/web-ui.md (SSE multiplexing paragraph)
// for the design + Firefox throttling motivation; graceful fallback to
// direct EventSource on environments without SharedWorker.
// ─── shared-worker SSE pipe (#448) ──────────────────────────────────────
// Returns an EventSource-shaped object backed by a SharedWorker that
// holds ONE upstream `new EventSource(url)` and fans events out to
// every connected tab. Replaces direct `new EventSource(url)` at the
// dashboard's two consumer sites (tabs.js inline + flow.js via
// terminal.js's `streamFactory` option) so N hyperhive tabs share
// ONE backend connection — way under the browser's per-host
// connection cap, immune to per-tab throttling that drops the SSE
// when Firefox suspends background tabs.
//
// Consumer API: assign `onmessage` / `onopen` / `onerror`; `.close()`
// drops the subscription (the worker closes the upstream when the last
// subscriber leaves).
// Graceful fallback to direct EventSource on environments without
// SharedWorker (some embedded browsers, some Safari versions). The
// per-tab connection cost is the same as today — no regression.
//
// The page consumer uses the returned object like a regular
// EventSource: assign `onmessage` / `onopen` / `onerror`. `.close()`
// tells the worker to drop the subscription; the worker closes the
// upstream EventSource when the last subscriber leaves.
const SHARED_WORKER_PATH = '/static/stream-worker.js';
const SHARED_WORKER_NAME = 'hyperhive-stream';
// One SharedWorker port per page, reused by all openStream calls on
// that page. Invalidated on `pagehide` so a bfcache restore picks up
// a fresh port — the cached port may be dead if all other tabs
// closed while this page was frozen.
// a fresh port (the cached one may have been collected if all other
// tabs closed while this page was frozen — argus nit on #453).
let _sharedPort = null;
function makeSharedPort() {
if (typeof SharedWorker === 'undefined') return null;
@ -85,11 +99,30 @@ function getSharedPort() {
return _sharedPort;
}
// SharedWorker death detection: pings from the worker bump the
// activity clock; a visibility-gated watchdog polls and re-subscribes
// on a fresh port if the page has been silent past the threshold.
// See docs/web-ui.md (Worker-death self-heal paragraph) for the
// timing rationale + Firefox reclaim symptom.
// #515: detect when the SharedWorker has been killed. Firefox aggressively
// reclaims "idle" SharedWorkers under memory pressure (or just on tab
// lifecycle quirks we don't fully understand), and there's no native
// signal to the client when that happens — `postMessage` on a dead
// port silently no-ops, and the page just stops receiving events. The
// observable symptom is "dashboard never refreshes; F5 fixes it" (a
// fresh page creates a fresh worker), which is mara's report on #515.
//
// Pipeline:
// - The worker pings every connected port every WORKER_PING_INTERVAL_MS.
// - `route` (every message arrival, including pings) bumps
// `_lastWorkerActivityAt`.
// - `startWorkerWatchdog` polls every WORKER_WATCHDOG_INTERVAL_MS.
// If the page is visible AND we have active subs AND we haven't
// heard from the worker in > WORKER_DEAD_THRESHOLD_MS, we presume
// the worker is dead, log a warning, and re-subscribe on a fresh
// port.
//
// Numbers picked so a real Firefox tab-suspend / unsuspend cycle (which
// can pause the watchdog itself) doesn't false-positive: 90s without a
// 30s ping means at least three pings missed. Visibility-gated so a
// backgrounded tab — where Firefox throttles setInterval to 1Hz min and
// our healthcheck wouldn't trigger reliably anyway — doesn't try to
// reconnect uselessly.
const WORKER_DEAD_THRESHOLD_MS = 90_000;
const WORKER_WATCHDOG_INTERVAL_MS = 15_000;
let _lastWorkerActivityAt = 0;
@ -131,19 +164,25 @@ function rebindOnFreshPort() {
noteWorkerActivity();
}
// Registry of live subscriptions on this page. Keyed by url; entries
// cache the route function so bfcache-restore re-bind can re-attach
// it to the fresh port. Today's pages only call openStream once with
// one URL; the registry shape just keeps the bfcache path correct
// if that changes.
// Registry of live subscriptions on this page. Keyed by url so a
// second openStream call for the same URL (would only happen on a
// hypothetical multi-consumer page) attaches to the existing route
// rather than overlapping. Each entry caches the route function so
// bfcache-restore re-bind can re-attach it to the fresh port.
//
// Today's pages only call openStream once with one URL; the registry
// shape just keeps the bfcache-restore path correct if that changes
// (e.g. /index.html later subscribing to two streams).
const _activeSubs = new Map();
// One-shot wiring of page-wide lifecycle hooks. On bfcache freeze
// we unsubscribe so the worker can close the upstream when the last
// live subscriber leaves; on bfcache restore we invalidate the cached
// port (may be dead after the freeze) and re-attach every active
// subscription to a fresh port. Without this, the consumer's
// onmessage stays bound but no events flow after restore.
// One-shot wiring of the page-wide lifecycle hooks: on bfcache
// freeze (`pagehide { persisted: true }`) we unsubscribe so the
// worker can close the upstream when the last live subscriber
// leaves; on bfcache restore (`pageshow { persisted: true }`) we
// invalidate the cached port (it may be dead if all other tabs
// closed during the freeze) and re-attach every active subscription
// to a fresh port. argus nit on #453: without this, the consumer's
// onmessage stays bound but no events flow after a bfcache restore.
let _lifecycleBound = false;
function bindLifecycleOnce() {
if (_lifecycleBound) return;
@ -206,7 +245,7 @@ export function openStream(url) {
},
};
const route = (e) => {
// Any message from the worker is proof of life — note it
// #515: any message from the worker is proof of life — note it
// before the URL filter, since heartbeat pings carry no URL.
noteWorkerActivity();
const m = e.data;
@ -233,8 +272,8 @@ export function openStream(url) {
_activeSubs.set(url, { target, route });
port.addEventListener('message', route);
port.postMessage({ kind: 'subscribe', url });
// Seed the activity clock so the watchdog has a baseline (would
// otherwise compare against 0 and trigger immediately).
// #515: seed the activity clock so the watchdog has a baseline; it
// would otherwise compare against 0 (epoch) and trigger immediately.
noteWorkerActivity();
return target;
}
@ -291,10 +330,13 @@ export const Panel = (() => {
root.classList.remove('open');
root.setAttribute('aria-hidden', 'true');
}
// Drag-to-resize the drawer's width. See docs/web-ui.md::Side panel
// for the hit-strip + pointer-capture + localStorage persistence
// model; CSS clamps the stored value to min 320px / max 96vw and
// out-of-range stored values are dropped silently.
// #451: drag-to-resize the drawer's width. Listens on a thin
// hit-strip glued to the drawer's left edge; mousedown captures
// pointermove + pointerup on the document so the drag continues
// even if the cursor strays outside the 6px handle band. Width
// persists to localStorage so it survives page reload. The CSS
// clamps the value (min-width: 320px, max-width: 96vw) — drop
// unparseable / out-of-range stored values silently.
const WIDTH_KEY = 'hyperhive:side-panel-width';
const WIDTH_MIN = 320;
function clampWidth(w) {
@ -434,7 +476,7 @@ function mdNode(text) {
window.marked.setOptions({ breaks: true, gfm: true });
div.innerHTML = window.marked.parse(text);
// marked autolinks URLs but leaves them same-tab — open externally
// so a click never navigates away from the dashboard.
// so a click never navigates away from the dashboard. (issue #233)
div.querySelectorAll('a[href]').forEach((a) => {
a.target = '_blank';
a.rel = 'noopener noreferrer';

View file

@ -3,19 +3,19 @@
@import "@hive/shared/base.css";
@import "@hive/shared/terminal.css";
/* ─── tabbed dashboard chrome ──────────────────────────────────────
Top-of-page sticky header with banner + tab strip. SSE stays
alive across tab switches so count pills update live on inactive
tabs. See docs/web-ui.md::Chrome header + Tab strip for the
routing model. */
/* ─── tabbed dashboard chrome (#369) ────────────────────────────────
Top-of-page sticky header with banner + tab strip. Tab routing is
hash-based; tab panes are show/hide via the `.tab-pane-active`
class. SSE stays alive across tab switches so count pills update
live on inactive tabs without losing pulse on what's happening
elsewhere. */
body.dashboard-shell {
/* Full-width layout — no max-width cap so wide screens don't
waste real estate on empty side margins. `padding: 0 1.5em
1.5em` keeps a small gutter on the left/right so cards don't
kiss the viewport edge; `.dashboard-chrome { margin: 0 -1.5em
... }` still pulls the chrome bar edge-to-edge through that
gutter. */
/* Full-width layout (#416 — mara: drop the 90em cap so wide screens
don't waste real estate on empty side margins). `padding: 0 1.5em
1.5em` keeps a small gutter on the left/right so cards don't kiss
the viewport edge; `.dashboard-chrome { margin: 0 -1.5em ... }`
still pulls the chrome bar edge-to-edge through that gutter. */
margin: 0;
padding: 0 1.5em 1.5em;
}
@ -189,9 +189,16 @@ a:hover {
background: rgba(24, 24, 37, 0.55);
transition: opacity 200ms ease, border-color 200ms ease;
}
/* Topology indent ladder. See docs/web-ui.md::Topology tree (Indent
+ lane geometry paragraph) for the 1.8em-per-depth-level
rationale + CSS-attr()-not-yet-portable caveat. */
/* Topology indent (#363). Each depth level shifts the row right by one
step; the .tree-prefix span (drawn by tabs.js::treePrefix) carries
the ├─ / └─ glyph and any continuation lines that thread through
ancestor columns. When every container has parent=null (pre-#361
state) `[data-depth]` is absent on every row and these rules are
no-ops — the layout reads exactly like the legacy flat list.
Per-depth indent: hardcoded steps for 6 levels (sufficient for any
plausible hive topology) — the typed `attr()` function from CSS
Values 5 would collapse this to one rule, but browser support is
still partial (Chromium-only as of 2026). */
.container-row[data-depth] { position: relative; }
.container-row[data-depth="1"] { margin-left: 1.8em; }
.container-row[data-depth="2"] { margin-left: 3.6em; }
@ -199,9 +206,16 @@ a:hover {
.container-row[data-depth="4"] { margin-left: 7.2em; }
.container-row[data-depth="5"] { margin-left: 9em; }
.container-row[data-depth="6"] { margin-left: 10.8em; }
/* Tree prefix lanes — DOM-painted, not text-glyph-painted. See
docs/web-ui.md::Topology tree for the full-row-height vertical
bar rationale + icon-midline joint alignment. */
/* Tree prefix sits in the left margin and paints the connecting
├ / └ / │ lanes as CSS rules rather than text glyphs (#388). Each
ancestor depth gets its own `.tree-lane` so we can paint a
full-row-height vertical bar that extends through the
.containers row gap into the next sibling — text box-drawing
glyphs only fill one text line, which left visible breaks
between rows once cards grew taller than one line of text (5em
square icons + multi-line body). The horizontal stub at the row's
own joint lands at the icon midline so the L/T meets the icon
edge cleanly. */
.container-row .tree-prefix {
position: absolute;
/* Extend into the `.containers { gap: 0.4em }` below so vertical
@ -214,10 +228,12 @@ a:hover {
user-select: none;
color: var(--purple-dim);
}
/* Prefix-left-edge ladder. Each depth step is 1.8em (matches the
row indent ladder above) so the prefix's right edge meets the
icon and its leftmost lane lines up with top-level rows' icons
at x = 0. */
/* Each depth step is one 1.8em lane wide — same step as the row's
own margin-left ladder above, so the rightmost lane (the joint)
sits flush against the row content (the icon). The prefix's left
edge is depth*1.8em LEFT of the row's left edge, so its right
edge meets the icon, and the leftmost lane lines up with the
top-level rows' icons at x=0. */
.container-row[data-depth="1"] .tree-prefix { left: -1.8em; }
.container-row[data-depth="2"] .tree-prefix { left: -3.6em; }
.container-row[data-depth="3"] .tree-prefix { left: -5.4em; }
@ -261,12 +277,14 @@ a:hover {
width: 2em;
border-top: 1px solid currentColor;
}
/* Live cards get the icon-left / body-right split; tombstone rows
keep the plain stacked block layout. The icon's fixed 5em width
+ aspect-ratio-derived height avoid the align-self: stretch
feedback loop that used to make different-content cards show
different-sized icons. See docs/web-ui.md::Container row (Icon
layout + load strategy) for the load-state reflow rationale. */
/* Live cards get the icon-left / body-right split; tombstone rows keep
the plain stacked block layout. The icon is a background-image div
with no intrinsic size, so its load state can never reflow the row
(issue #177). It used to `align-self: stretch` to fill the body
height, but with state badges / rate-limit pills / etc. wrapping the
head row, the body grew taller and the square icon grew with it —
so two cards with different content showed different-sized icons
(issue #344). Fixed at 5em now; height follows from aspect-ratio. */
.container-row:not(.tombstone) {
display: flex;
align-items: flex-start;
@ -280,10 +298,9 @@ a:hover {
aspect-ratio: 1;
border-radius: 6px;
background-color: rgba(17, 17, 27, 0.6);
/* Icon doubles as the selection toggle — cursor + hover ring
make that affordable without a chrome change. The
:focus-visible ring covers keyboard activation (Enter / Space).
See docs/web-ui.md::Selection bar for the toggle semantics. */
/* #443 — icon is the selection toggle. Cursor + hover ring make
that affordable without a chrome change. The :focus-visible ring
covers keyboard activation (Enter / Space). */
cursor: pointer;
transition: box-shadow 120ms ease, transform 120ms ease;
}
@ -304,9 +321,9 @@ a:hover {
.container-row.selected > .container-icon {
box-shadow: 0 0 0 2px var(--purple), 0 0 12px -4px var(--purple);
}
/* Icon image — absolutely positioned, fills the square wrapper.
See docs/web-ui.md::Container row (Icon layout + load strategy)
for the load-state-can't-reflow-row rationale. */
/* The icon image fills the square wrapper and is taken out of flow
(absolute) so its load state — pending, loaded, broken — can never
contribute intrinsic size or reflow the row. (issue #177) */
.container-row:not(.tombstone) > .container-icon > .container-icon-img {
position: absolute;
inset: 0;
@ -314,9 +331,8 @@ a:hover {
height: 100%;
object-fit: contain;
}
/* When the <img> fails to load it falls back to the dimmed
hyperhive mark — see docs/web-ui.md::Container row for the
fire-and-forget load + favicon fallback chain. */
/* When the <img> fails to load it falls back to the dimmed hyperhive
mark, standing in for the unreachable agent icon (issues #195, #202). */
.container-row:not(.tombstone) > .container-icon.icon-unreachable {
filter: grayscale(1);
opacity: 0.4;
@ -325,29 +341,23 @@ a:hover {
flex: 1;
min-width: 0;
}
/* Pending state splits queued vs running — queued ops show only
the pending-state badge (no row tint), running ops keep the
amber row tint AND get a rotating amber ring on the icon. See
docs/web-ui.md::Container row (Pending-state derivation) for
the priority order. */
/* Pending state splits queued vs running (#769): queued ops show
only the pending-state badge — the row sits unhighlighted so a
long queue doesn't paint half the SW4RM tab amber. Running ops
keep the amber row tint AND get a rotating amber ring on the
agent icon so it's obvious which container is actually moving. */
.container-row.pending .actions { opacity: 0.4; pointer-events: none; }
.container-row.pending-running {
border-color: var(--amber);
background: rgba(250, 179, 135, 0.05);
}
/* The spinner is a faint amber ring with one brighter arc on top
that rotates around the icon — classic CSS spinner shape. The
previous version coloured two adjacent border sides amber, which
rendered as a rotating L-corner ("_|") rather than a smooth
orbiting arc (mara on #804). Faint-ring + bright-arc reads
unambiguously as a loading spinner.
Override the icon's overflow:hidden so the ring can sit just
outside the square; it composes naturally with the mauve
selected-ring (selected + running shows both). */
/* The spinner is a transparent border ring with two adjacent sides
coloured amber, rotated by a CSS animation — looks like an
orbiting arc around the icon. Override the icon's overflow:hidden
so the ring can sit just outside the square; it composes naturally
with the mauve selected-ring (selected + running shows both). */
@keyframes container-icon-spin {
from { transform: rotate(0deg); }
to { transform: rotate(360deg); }
to { transform: rotate(360deg); }
}
.container-row.pending-running > .container-icon {
overflow: visible;
@ -357,8 +367,9 @@ a:hover {
position: absolute;
inset: -4px;
border-radius: 10px;
border: 2px solid rgba(250, 179, 135, 0.2);
border: 2px solid transparent;
border-top-color: var(--amber);
border-right-color: var(--amber);
animation: container-icon-spin 1s linear infinite;
pointer-events: none;
}
@ -374,13 +385,11 @@ a:hover {
font-weight: bold;
}
.container-row .head .meta { margin-left: auto; }
/* Icon-only nav strip in the head row — backend-supplied per-
container link list. Inline-flex + gap so a longer list (e.g.
with `dashboardLinks` extras) doesn't cram. Each link gets a
comfortable hit target with a subtle hover so the icons read
as interactive rather than decorative. See
docs/web-ui.md::Container row Line 1 for the link-list source
of truth. */
/* Icon-only nav strip in the head row — the per-container backend-
supplied link list (issue #262). Inline-flex + gap so a longer list
(e.g. with `dashboardLinks` extras) doesn't cram (issue #333). Each
link gets a comfortable hit target with a subtle hover so the
icons read as interactive rather than decorative. */
.container-row .head .nav-strip {
display: inline-flex;
align-items: center;
@ -432,10 +441,11 @@ a:hover {
color: var(--cyan); border-color: var(--cyan);
text-shadow: 0 0 6px rgba(137, 220, 235, 0.4);
}
/* Context-window usage badges on dashboard container rows. See
docs/web-ui.md::Container row Line 1 for the per-container
threshold derivation (yellow ≥ 50% / red ≥ 75% of the model's
context window) and fallback values. */
/* Context-window usage badges on dashboard container rows. Thresholds
are derived per-container: yellow ≥ 50% and red ≥ 75% of the model's
context window (`ContainerView.context_window_tokens`), mirroring the
harness compaction watermarks. Falls back to fixed 100k / 150k when
the window is unknown. (issue #66) */
.badge-ctx-ok {
color: var(--green); border-color: var(--green);
opacity: 0.85;
@ -468,10 +478,10 @@ a:hover {
/* Per-container journald viewer + applied-config viewer. Both open
in the side panel and lazy-fetch on open; output is monospace
inside a bordered <pre>, controls (unit select + refresh) above.
The panel-body wrapper is a column flex container that fills the
side-panel-body so the <pre> can flex-grow into a single tall
scrollable surface instead of a short box at the top with the
rest of the panel empty. */
#541: the panel-body wrapper is a column flex container that fills
the side-panel-body so the <pre> can flex-grow into a single tall
scrollable surface instead of a short box at the top with the rest
of the panel empty. */
.journal-body {
display: flex;
flex-direction: column;
@ -499,9 +509,9 @@ a:hover {
color: var(--fg);
border: 1px solid var(--purple-dim);
padding: 0.5em 0.7em;
/* Take all leftover panel height + scroll inside the pre so long
log fetches don't push the controls off-screen. `min-height: 0`
is the canonical "let me actually flex-shrink for overflow"
/* #541: take all leftover panel height + scroll inside the pre so
long log fetches don't push the controls off-screen. `min-height:
0` is the canonical "let me actually flex-shrink for overflow"
escape hatch on flex children. */
flex: 1 1 0;
min-height: 0;
@ -595,8 +605,9 @@ code {
flex-wrap: wrap;
gap: 0.3em;
}
/* Approval requested-at chip — right-aligned, goes amber after
1h. See docs/web-ui.md::Approval card. */
/* When the approval was requested — right-aligned in the head row;
goes amber once it has been pending ≥ 1h so a stale request stands
out at a glance (issue #272). */
.approval-ts {
margin-left: auto;
color: var(--muted);
@ -649,8 +660,7 @@ code {
border-color: var(--purple);
background: rgba(203, 166, 247, 0.08);
}
/* Image / tabbed file preview — see docs/web-ui.md::Side panel
for the type-aware preview shapes. */
/* Image / tabbed file preview (issues #188, #192) */
.preview-host { margin-top: 0.5em; }
.img-preview {
display: block;
@ -724,7 +734,7 @@ code {
text-overflow: ellipsis;
white-space: nowrap;
}
/* Bulk select-all / -none control above the meta-inputs tree. */
/* Bulk select-all / -none control above the meta-inputs tree (#275). */
.meta-inputs-bulk {
margin: 0 0 0.5em;
font-size: 0.8em;
@ -744,7 +754,7 @@ code {
border-color: var(--cyan);
text-shadow: 0 0 6px currentColor;
}
/* Tree twig glyph prefixing a nested (sub-)input row. */
/* Tree twig glyph prefixing a nested (sub-)input row (#275). */
.meta-input-twig {
color: var(--purple-dim);
margin-right: 0.1em;
@ -770,7 +780,7 @@ code {
cursor: not-allowed;
}
/* In-progress banner for the META INPUTS panel: shown while a
dashboard-triggered meta-update runs in the background. */
dashboard-triggered meta-update runs in the background (issue #259). */
.meta-update-running {
margin: 0 0 0.7em;
padding: 0.4em 0.7em;
@ -826,10 +836,11 @@ code {
.rqe-source-approval { color: var(--green); border-color: var(--green); }
.rqe-when { color: var(--muted); font-size: 0.85em; }
.rqe-reason { color: var(--muted); font-size: 0.85em; flex: 1 1 auto; }
/* In-flight step indicator on running queue entries — cyan sub-
line below the main row, wraps to its own line via flex-basis:
100%. See docs/web-ui.md::R3BU1LD QU3U3 for the step-annotation
semantics. */
/* #437: in-flight step indicator on running queue entries — sub-line
below the main row, indented under the state glyph + kind. Cyan
keeps it visually grouped with the running spinner instead of
blending into the muted reason/timing chips. flex-basis: 100% so
it always wraps to its own line. */
.rqe-step {
flex-basis: 100%;
margin: 0.1em 0 0 1.8em;
@ -847,11 +858,12 @@ code {
white-space: pre-wrap;
}
/* Cancel-X for queued rebuild_queue entries — sits at far right
via margin-left: auto, lights red on hover. Mirrors the side-
panel-close glyph shape (✗) so it stays unobtrusive in a list
row. See docs/web-ui.md::R3BU1LD QU3U3 for the queued-only
gating. */
/* #575: cancel-X for queued rebuild_queue entries. Quiet by default
(sits at the far right via margin-left: auto), lights red on hover.
Renders only when `state === 'queued'` per renderQueueEntry's
guard — Running / terminal rows don't get the affordance. Mirrors
the side-panel-close glyph shape (✗) without the full B6N-style
`btn-deny` width so it stays unobtrusive in a list row. */
.rqe-cancel {
margin-left: auto;
}
@ -930,9 +942,10 @@ ul form.inline { display: inline-block; }
.btn-restart { color: var(--cyan); border-color: var(--cyan); font-size: 0.75em; padding: 0.15em 0.5em; margin-left: 0.6em; }
.btn-stop { color: var(--pink); border-color: var(--pink); font-size: 0.75em; padding: 0.15em 0.5em; margin-left: 0.6em; }
.btn-start { color: var(--green); border-color: var(--green); font-size: 0.75em; padding: 0.15em 0.5em; margin-left: 0.6em; }
/* M0V3 affordance (selection bar) — mauve reads as "structural
change" rather than the destructive red / amber chrome of
destroy / rebuild. See docs/web-ui.md::Selection bar. */
/* #486 — M0V3 affordance (selection bar). Mauve picks up the same
accent the question-override / mid-status surfaces use; reads as
"structural change" rather than the destructive red / amber chrome
of destroy / rebuild. */
.btn-move { color: var(--mauve); border-color: var(--mauve); font-size: 0.75em; padding: 0.15em 0.5em; margin-left: 0.6em; }
.btn-talk { color: var(--cyan); border-color: var(--cyan); }
.btn-spawn { color: var(--amber); border-color: var(--amber); }
@ -946,7 +959,7 @@ ul form.inline { display: inline-block; }
text-shadow: 0 0 6px currentColor;
box-shadow: 0 0 8px -2px currentColor;
}
/* Inline edit button on each schedule row. Yellow reads as a
/* #474: inline edit button on each schedule row. Yellow reads as a
parallel destructive-adjacent action (edit changes state, but
isn't deletion). */
.btn-edit-schedule { color: var(--yellow, #f9e2af); border-color: var(--yellow, #f9e2af); }
@ -1211,8 +1224,10 @@ summary:hover { color: var(--purple); }
background: var(--bg-elev);
border: 1px solid var(--border);
padding: 0.5em 0.8em;
/* No max-height cap — let the inbox grow to fill the
side-panel-body which already scrolls. */
/* #450: no max-height cap — let the inbox grow to fill the
side-panel-body which already scrolls (`overflow: auto`). The
pre-#450 24em cap clamped the list well short of the available
panel height even on tall viewports. */
}
.inbox li {
padding: 0.25em 0;
@ -1248,9 +1263,17 @@ summary:hover { color: var(--purple); }
text-indent: 0;
}
.live .msgrow .msg-body {
/* Body takes a full flex line of its own beneath the metadata
chips. See docs/web-ui.md::FL0W page (MESS4GE FL0W) for the
flex-basis: 100% + min-width: 0 rationale. */
/* #485: body takes a full flex line of its own beneath the
metadata chips (ts / arrow / from / sep / to). Previously the
body sat inline with `flex: 1 1 0`, eating whatever the chips
left — which on a long timestamp + agent names + arrows meant
the body started ~30ch in and wrapped awkwardly. Pushing
`flex-basis: 100%` forces the body to wrap to its own line in
the existing `flex-wrap: wrap` row, where it can use the full
width down to the row's content edge.
`min-width: 0` still applies so `word-break: break-word`
actually kicks in instead of forcing the row wider than its
container. */
flex: 1 1 100%;
min-width: 0;
}
@ -1349,9 +1372,9 @@ footer {
font-size: 0.9em;
}
footer a { color: var(--purple); }
/* Slug banner lives at the page footer — slim top margin so it
doesn't crash into the prior content, bottom margin separating
from the divider/link line. */
/* Slug banner now lives at the page footer (#389 follow-up) — give
it a slim top margin so it doesn't crash into the prior content,
and bottom margin separating from the divider/link line. */
footer .banner-thin {
margin-bottom: 0.8em;
}
@ -1397,11 +1420,13 @@ footer .banner-thin {
top: 0;
right: 0;
bottom: 0;
/* Width is a CSS variable so the drag handle can update it live
(JS sets `--side-panel-w` on the drawer) and localStorage-
persisted widths apply on first paint. Default min(760px, 94vw)
covers operators who never drag. See docs/web-ui.md::Side panel
for the drag-to-resize mechanism + localStorage key. */
/* #451: width is a CSS variable so the drag handle (added by
Panel.bind) can update it live, and so localStorage-persisted
widths apply on first paint. Default min(760px, 94vw) preserves
the pre-#451 behaviour for operators who never drag. JS sets
`--side-panel-w` via inline style on the drawer; persistence
lives in localStorage (key `hyperhive:side-panel-width`),
replayed onto the var by `Panel.applyStoredWidth` at bind. */
width: var(--side-panel-w, min(760px, 94vw));
/* Clamp so a stored width can never push the drawer off-screen
or shrink it past readability. min content width matches the
@ -1419,11 +1444,12 @@ footer .banner-thin {
.side-panel.open { pointer-events: auto; }
.side-panel.open .side-panel-backdrop { opacity: 1; }
.side-panel.open .side-panel-drawer { transform: translateX(0); }
/* Drag-to-resize handle on the drawer's left edge. Invisible until
hover/drag so it doesn't compete with the 2px mauve border-left
for the visual boundary. Pointer-cursor tells the operator the
edge is grabbable; the brighter glow during drag
(body.side-panel-resizing) is the affordance the eye tracks. */
/* #451: drag-to-resize handle on the drawer's left edge. The handle
itself is invisible until hover/drag so it doesn't compete with the
2px mauve `border-left` for the visual boundary. Pointer-cursor
tells the operator the edge is grabbable; the brighter glow during
drag (`body.side-panel-resizing`) is the affordance the eye
tracks. */
.side-panel-resize {
position: absolute;
top: 0;
@ -1521,17 +1547,22 @@ body.side-panel-resizing * { cursor: ew-resize !important; }
padding: 0.2em 0.5em;
}
/* ─── /flow.html — full-page chat ─────────────────────────────────
See docs/web-ui.md::FL0W page for the page-vs-pane rationale
and the inbox-flyout-as-pill ergonomics. Shape mirrors the
per-agent live page (frosted-glass header + composer, full-
viewport terminal). */
/* ─── /flow.html — full-page chat (#369) ───────────────────────────
The all-agents chat surface lives on its own page so it can claim
full-viewport vibec0re styling (operator @ #369#issuecomment-3437).
Same shape as the per-agent live page (#362): frosted-glass header
at top, frosted composer docked at bottom, terminal scrolls
behind both. Operator inbox lives behind a header pill that opens
the side-panel flyout — preserves the "inbox + chat in one view"
ergonomics without stealing terminal real estate. */
:root {
/* Approximate height of the flow chrome (tabbar + dashboard-chrome
padding). The slug banner lives at the page footer on /, omitted
on /flow.html since the full-viewport terminal has no normal-flow
footer position. */
padding). The banner-thin slug used to live in the chrome and
padded this up to 4.7em; with the slug moved out (#389 follow-up:
slug lives at the page footer on /, simply omitted on /flow.html
since there's no normal-flow footer position in the full-viewport
terminal), the chrome is just tabs now and shrinks accordingly. */
--flow-header-h: 3.6em;
--flow-composer-h: 3.6em;
--flow-frost-bg: rgba(30, 30, 46, 0.74);
@ -1553,8 +1584,8 @@ body.flow-shell {
var(--bg);
}
/* Flow chrome reuses the dashboard's `.dashboard-chrome` + tabbar
so the operator can switch tabs from the flow page without
/* Flow chrome (#383): reuses the dashboard's `.dashboard-chrome` +
tabbar so the operator can switch tabs from the flow page without
navigating back first. The chrome must be fixed-position (vs
sticky on the dashboard) since flow-shell has `overflow: hidden`
on body and the main area absolute-positions the terminal. */
@ -1582,13 +1613,15 @@ body.flow-shell .tabbar .tab.active.tab-link {
border-color: var(--purple-dim);
box-shadow: 0 -2px 12px -4px rgba(203, 166, 247, 0.4);
}
/* `.notif-row` styling lives under the shared `.tabbar #notif-row`
selector earlier in the file — the flow page reuses the dashboard
tab strip rather than carrying its own title/hint/back chrome. */
/* Legacy `.flow-title` / `.flow-hint` / `.flow-back` rules were
removed in #383 — the flow page now uses the shared chrome with
the dashboard tab strip, no need for FL0W-specific title/hint
elements. The `.notif-row` styling lives under the shared
`.tabbar #notif-row` selector earlier in the file. */
/* Inbox pill — operator inbox flyout trigger. Sits right under the
header so it stays in the operator's gaze without crowding the
chat. Same shape as the agent page's header pills. */
chat. Same shape as the agent page's pills (#362). */
.flow-pill {
position: fixed;
top: calc(var(--flow-header-h) + 0.8em);
@ -1657,10 +1690,11 @@ body.flow-shell .tabbar .tab.active.tab-link {
overflow: auto;
}
/* Tail pill (↓ N new): bottom offset clears the floating composer.
Pill is anchored on .flow-main (not .terminal-wrap) so the
backdrop-filter stacking context doesn't trap its z-index — see
docs/web-ui.md::Per-agent page (Terminal-wrap) for the same
gotcha on the agent page. */
z-index escapes the stacking context the .terminal-wrap's
backdrop-filter creates (issue #375) — tabs.js anchors the pill
on .flow-main now (not .terminal-wrap), so this z-index reaches
the root stacking context and properly floats above the
composer at z-index 30. */
.flow-main .tail-pill {
bottom: calc(var(--flow-composer-h) + 0.6em);
z-index: 35;
@ -1686,11 +1720,10 @@ body.flow-shell .tabbar .tab.active.tab-link {
surface the messages via the pill/flyout instead. */
.flow-inbox-headless { display: none !important; }
/* ─── scheduled prompts tab ────────────────────────────────────────
/* ─── scheduled prompts tab (#459) ─────────────────────────────────────
Creation form at the top, list of queued schedule cards below.
Cards show: id + source + due-in + cancel-all in the header,
the prompt body, then a targets table with per-row cancel. See
docs/web-ui.md::SCH3DUL3S tab. */
the prompt body, then a targets table with per-row cancel. */
.schedule-edit-form {
display: flex;
@ -1702,9 +1735,9 @@ body.flow-shell .tabbar .tab.active.tab-link {
padding: 0.8em 1em;
margin-bottom: 0.5em;
}
/* Inline edit form opens directly under the schedule row's
actions strip, indented slightly so it visually nests under
the row it edits. */
/* #474 — inline edit form opens directly under the schedule row's
actions strip, indented slightly so it visually nests under the
row it edits. */
.schedule-edit-form-wrapper {
margin-top: 0.5em;
padding-left: 0.5em;
@ -1767,7 +1800,7 @@ body.flow-shell .tabbar .tab.active.tab-link {
justify-content: flex-end;
}
/* Interval composer — preset chip row + d/h/m/s inputs + live
/* Interval composer (#466). Preset chip row + d/h/m/s inputs + live
preview, so the operator never has to multiply seconds by hand. */
.schedule-interval-presets {
display: flex;
@ -1811,9 +1844,10 @@ body.flow-shell .tabbar .tab.active.tab-link {
}
.schedule-interval-preview-oneshot { color: var(--muted); font-style: italic; }
/* Schedules-as-table — one row per schedule, attribute columns
/* #535 — schedules-as-table. One row per schedule, attribute columns
on the left, one ✓/✕ column per agent in the middle, actions
column on the right. See docs/web-ui.md::SCH3DUL3S tab. */
column on the right. Agent column headers tilt -45° so a stack of
short agent names fits in ~28px each. */
.schedules-table {
width: 100%;
border-collapse: collapse;
@ -1833,11 +1867,11 @@ body.flow-shell .tabbar .tab.active.tab-link {
.schedules-table-id { width: 3em; }
.schedules-table-body-th { min-width: 12em; }
.schedules-table-actions-th { width: 7em; }
/* Tilted agent column headers — narrow (~28px) and tall (~90px);
the inner <div> rotates -45° about its bottom-left corner, with
a translate to slide the text up alongside the cell border. The
inner <span> carries the actual baseline so the underline
(border-bottom on the cell) aligns with the rotated text. */
/* Tilted agent column headers (#535). Header cell is narrow (~28px)
and tall (~90px); the inner <div> rotates -45° about its bottom-left
corner, with a translate to slide the text up alongside the cell
border. The inner <span> carries the actual baseline so the
underline (border-bottom on the cell) aligns with the rotated text. */
.schedules-table-agent-th {
width: 28px;
min-width: 28px;
@ -1921,8 +1955,8 @@ body.flow-shell .tabbar .tab.active.tab-link {
padding: 0.1em 0.45em;
}
/* Inline create row at the bottom of the schedules table. Cells
host inputs directly so the operator can fill + click + to
/* #564 — inline create row at the bottom of the schedules table.
Cells host inputs directly so the operator can fill + click + to
queue a new schedule without leaving the table view. Slightly
different background tone so it reads as "this isn't a schedule
yet, it's the create form". */
@ -2024,11 +2058,11 @@ body.flow-shell .tabbar .tab.active.tab-link {
border-color: var(--border);
}
/* Selection bar — sticky-bottom strip that surfaces bulk actions
when ≥1 agent is selected (click the icon). Visually echoes the
flow composer's frosted-mauve treatment so the chrome reads as
part of the same vibecore family. Hidden when empty. See
docs/web-ui.md::Selection bar for the bulk-action semantics. */
/* Selection bar (#443). Sticky-bottom strip that surfaces bulk
actions when ≥1 agent is selected (click the icon). Visually
echoes the flow composer's frosted-mauve treatment so the chrome
reads as part of the same vibecore family. Hidden when empty —
leaves the page footer's normal-flow position untouched. */
.selection-bar {
position: fixed;
bottom: 0;
@ -2084,11 +2118,11 @@ body.flow-shell .tabbar .tab.active.tab-link {
selection set is non-empty). */
body.dashboard-shell.has-selection { padding-bottom: 4.5em; }
/* M0V3 → <pick> picker — inline `<select>` + button pair sitting
alongside the bulk action buttons in the selection bar. The
select inherits the terminal-y monospace look so it doesn't read
as system-chrome popping out of the swarm aesthetic. See
docs/web-ui.md::Selection bar for the picker semantics. */
/* #486 — M0V3 → <pick> picker. Inline `<select>` + button pair
sitting alongside the bulk action buttons in the selection bar.
The select inherits the terminal-y monospace look so it doesn't
read as system-chrome popping out of the swarm aesthetic. Only
surfaces when exactly one agent is selected. */
.move-picker {
display: inline-flex;
align-items: center;

View file

@ -8,11 +8,12 @@
</head>
<body class="flow-shell">
<!-- Fixed-overlay chrome — just the tab strip. The full-viewport
terminal has no normal-flow footer position so the dashboard's
slug doesn't appear here. The operator can still switch tabs
from the flow page without navigating back; FL0W is the current
page, SW4RM / Y3R C4LL / SYST3M / SCH3DUL3S cross-link to the
<!-- Fixed-overlay chrome — just the tab strip (#389 follow-up:
slug moved to the dashboard's page footer; the flow page is a
full-viewport terminal with no normal-flow footer position, so
the slug simply doesn't appear here). The operator can still
switch tabs from the flow page without navigating back; FL0W is
the current page, SW4RM / Y3R C4LL / SYST3M cross-link to the
dashboard with the matching hash. -->
<header class="dashboard-chrome flow-chrome" id="flow-header">
<nav class="tabbar" id="tabbar" role="tablist">
@ -54,7 +55,7 @@
<!-- Operator inbox flyout trigger — count + click → side panel
(singleton, declared below). Hidden until the inbox is non-
empty. Mirrors the agent page's header pill pattern. -->
empty. Mirrors the agent page's pill pattern (#362). -->
<button type="button" id="inbox-pill" class="flow-pill" hidden
title="open operator inbox">
<span class="flow-pill-icon" aria-hidden="true">📬</span>
@ -110,10 +111,10 @@
</aside>
</div>
<!-- Flow-specific bundle. Contains the broker terminal init, the
operator-inbox derived store, the inbox pill flyout, and the
@-mention composer. Tab renderers etc. live in
`/static/tabs.js` which /flow.html doesn't load. -->
<!-- Flow-specific bundle (#406 step 2). Contains the broker
terminal init, the operator-inbox derived store, the inbox
pill flyout, and the @-mention composer. Tab renderers etc.
live in `/static/tabs.js` which /flow.html doesn't load. -->
<script type="module" src="/static/flow.js" defer></script>
</body>
</html>

View file

@ -1,8 +1,11 @@
// /flow.html entry point. Owns the full-page broker terminal, the
// operator-inbox derived store (populated from the broker stream),
// the inbox pill flyout, and the @-mention compose box. Pulls shared
// infrastructure (DOM helpers, side panel, OS notifications, path
// linkification) from `./common.js`.
// /flow.html entry point (#406 step 2 — flow-specific split from the
// previous combined entry; #406 step 3 renamed that combined entry
// from `app.js` to `tabs.js`).
//
// Owns the full-page broker terminal, the operator-inbox derived store
// (populated from the broker stream), the inbox pill flyout, and the
// @-mention compose box. Pulls shared infrastructure (DOM helpers, side
// panel, OS notifications, path linkification) from `./common.js`.
//
// Does NOT contain the dashboard's tab renderers, mutation-event
// dispatchers, or refreshState — that's `./tabs.js`, loaded only by
@ -103,11 +106,11 @@ import {
if (!flow) return;
flow.innerHTML = '';
const tsFmt = (n) => new Date(n * 1000).toISOString().slice(11, 19);
// Pulse the page banner whenever a broker event lands. The
// `.banner` element lives in the dashboard's <footer> rather than
// in the flow chrome — `pulseBanner` no-ops on /flow.html since
// there's no element to find. Kept for parity if a future chrome
// change reintroduces a banner.
// Pulse the page banner whenever a broker event lands. (Note:
// post-#389 the `.banner` lives in the dashboard's <footer>, not
// in the flow page chrome — `pulseBanner` no-ops on /flow.html
// since there's no element to find. Kept for parity if a future
// chrome change reintroduces a banner.)
const banner = document.querySelector('.banner');
let bannerOffTimer = null;
function pulseBanner() {
@ -171,28 +174,33 @@ import {
// Register this row so future replies can reference it.
if (ev.id != null && ev.id > 0) msgRowMap.set(ev.id, row);
}
// Anchor the `↓ N new` pill in `.flow-main` rather than the
// default `.terminal-wrap` parent — see docs/web-ui.md::Per-agent
// page (Terminal-wrap) for the backdrop-filter stacking-context
// gotcha (same shape on the flow page).
// Anchor the `↓ N new` pill in `.flow-main` (NOT the default
// `log.parentElement` = `.terminal-wrap`). `.terminal-wrap`
// applies `backdrop-filter`, which creates a CSS stacking
// context — the pill's z-index would otherwise be trapped
// inside and clipped under the fixed composer (issue #375).
// `.flow-main` has no backdrop-filter / stacking-context
// creators, so the pill's z-index reaches the root and floats
// above the composer.
const flowMain = document.querySelector('.flow-main');
termCreate({
logEl: flow,
pillAnchor: flowMain,
historyUrl: '/dashboard/history',
// Server-side filter — only the kinds this page actually renders
// or routes (sent/delivered → broker terminal,
// #408: server-side filter — only the kinds this page actually
// renders or routes (sent/delivered → broker terminal,
// container_state_changed/_removed → local autocomplete cache).
// Backend pre-parses the allow-list at subscribe time so the
// per-frame hot path is one HashSet::contains and the
// Backend (#499) pre-parses the allow-list at subscribe time so
// the per-frame hot path is one HashSet::contains and the
// JSON-serialise is skipped entirely on irrelevant kinds. The
// dashboard tabs page (tabs.js) keeps the unfiltered subscribe
// since it routes every mutation kind into its derived stores.
streamUrl: '/dashboard/stream?kinds=sent,delivered,container_state_changed,container_removed',
// Route through the SharedWorker — see docs/web-ui.md (SSE
// multiplexing paragraph). Worker keys on the full URL incl.
// query string, so this filtered subscribe is its own upstream
// and won't accidentally share with tabs.js's wider subscribe.
// #448: route through the SharedWorker so this page's SSE shares
// a single backend connection with /index.html (and any other
// open hyperhive tab). Worker keys on the full URL (incl.
// query string), so the filtered subscribe is its own upstream
// — won't accidentally share with tabs.js's wider subscribe.
streamFactory: openStream,
renderers: {
sent: (ev, api) => renderMsg(ev, api, '→'),
@ -224,9 +232,10 @@ import {
// Re-sync the local containers cache on every SSE (re)connect.
// Live mutation events that fired during a disconnect window
// are never replayed, so without this the compose autocomplete
// could drift stale. We don't try to recover missed broker rows
// here — operator inbox briefly stales on reconnect; the
// history-replay covers the next page load.
// could drift stale (issue #163). We don't try to recover
// missed broker rows here — operator inbox briefly stales on
// reconnect; HiveTerminal's history-replay covers the next
// page load.
onStreamOpen: () => {
fetch('/api/state').then((r) => r.ok ? r.json() : null).then((s) => {
if (!s || !Array.isArray(s.containers)) return;

Some files were not shown because too many files have changed in this diff Show more