Watch
0
0
Fork
You've already forked hyperhive
0

docs(agents): drop nonexistent-thing mentions, state current behaviour

This commit is contained in:
atlas 2026-10-02 09:20:57 +02:00 • committed by mara
commit 78aacf13ce
3 changed files with 39 additions and 45 deletions

View file

@ -91,12 +91,11 @@ angle-bracket and asterisk shapes below are structurally safe.
- `operator` — the human at the dashboard. Messages accumulate in the
inbox view; no agent ever `recv`'s them.
`<parent>` and `<children>` were two more, resolved against a
`topology.json` parent field. That field and both sentinels no longer
exist: address `operator` where you would have said
`<parent>`, and name the recipients (or broadcast to `*`) where you
would have said `<children>`. Nothing rewrites a recipient at send time
any more — what an agent passes is what the broker stores.
`<parent>` and `<children>` aren't valid recipients: address
`operator` directly instead of `<parent>`, and name the recipients (or
broadcast to `*`) instead of `<children>`. Nothing rewrites a
recipient at send time — what an agent passes is what the broker
stores.
## Wire protocol
@ -225,8 +224,8 @@ the card out of the pending pane.
### Agent metadata
`AgentRequest::GetAgentMeta { name }` returns identity + status for
an agent. Self-introspection when `name = None` (replaces the older
`Whoami` request); target query when `name = Some`.
an agent. Self-introspection when `name = None`; target query when
`name = Some`.
Response is `AgentMeta { name, running, hyperhive_rev,
status_text, status_set_at, hive_name, swarm_name, matrix_accounts }`:
@ -238,9 +237,10 @@ status_text, status_set_at, hive_name, swarm_name, matrix_accounts }`:
`false`, the host clears `status_text` / `status_set_at` —
on-disk values from before the stop are stale snapshots, not
live status. Defaults to `true` on the
wire (older harnesses never serialised it, and the host only
knew how to ask about live containers — keeps backwards-compat
with pre-running-field payloads).
wire: the deserializer treats a payload lacking the field — from a
harness that never serialises it, or a host that only knows how to
ask about live containers — as running, keeping compatibility with
pre-running-field payloads.
- `status_text` / `status_set_at`: last value written via
`SetStatus`, plus its unix timestamp. Both `None` when the
target has never set a status, when the agent name is unknown,
@ -259,8 +259,8 @@ Timestamp fields that cross a JSON boundary (dashboard API + SSE,
the wire structs in hive-sh4re) serialize as **RFC 3339 UTC strings**
(`2026-07-02T18:30:00Z`) via `hive_sh4re::wire_time` — Rust keeps the
fields as `i64` unix seconds internally, only the JSON representation
changes, and deserialization leniently accepts both the string form
and the legacy bare integer (rolling-deploy skew, persisted blobs).
changes, and deserialization accepts both the string form and a bare
integer (rolling-deploy skew, persisted blobs).
**Input-direction** fields agents compute as epoch (`first_fire_at_unix`,
schedule-edit `next_fire_at_unix`, `Wakeup::At`) stay integers. The
`*_unix` field *names* stay for now — renaming is the wire-types
@ -302,10 +302,10 @@ binary flavor.
| `meta` | `get_agent_meta` (`set_status` is always-on, see below) |
| `inbox` | `get_loose_ends`, `cancel_loose_end`, `remind` |
| `execution` | vestigial — `mcp__bash__run` / `mcp__bash__status` are always available unconditionally via `extraMcpServers`; this group's entries expand to non-existent `mcp__hyperhive__run` / `mcp__hyperhive__status` and have no effect. See `docs/tools/bash.md`. |
| `lifecycle` | none — `list_containers` no longer exists, with no replacement; the variant survives only so existing grants parse. |
| `approvals` | none — `request_update_meta_inputs` no longer exists, with no replacement. Still a live server-side gate: `cancel_loose_end`'s approval-cancel arm requires it. |
| `lifecycle` | none — `list_containers` isn't a tool; the variant survives only so existing grants parse. |
| `approvals` | none — `request_update_meta_inputs` isn't a tool. Still a live server-side gate: `cancel_loose_end`'s approval-cancel arm requires it. |
| `scheduling` | `request_schedule_prompt`, `fire_schedule_now`, `cancel_schedule`, `edit_schedule`, `list_schedules` *(privileged)* |
| `forge` | none — `create_repo` no longer exists, with no replacement; the variant survives only so existing grants parse. |
| `forge` | none — `create_repo` isn't a tool; the variant survives only so existing grants parse. |
| `web_tools` | none (gates the Claude built-ins `WebFetch`/`WebSearch`, not an MCP tool) |
**Always-on tools** — `ToolGroup::ALWAYS_ON_TOOLS` exposes `set_status`,
@ -411,7 +411,7 @@ rewrite — `PRIVATE_NETWORK=1`, `HOST_ADDRESS` = the bridge gateway IP,
sets `EXTRA_NSPAWN_FLAGS` — plus the systemd resource-limits drop-in)
into the `Swap` node, then runs `nixos-container update` + stop +
start across the `StopForUpdate → Swap → RebuildBookkeeping`
brace and the tail `Reconcile` node. `flake.nix` itself is no longer
brace and the tail `Reconcile` node. `flake.nix` itself isn't
regenerated host-side on rebuild — it's tracked in the agent's
proposed/applied repos and rides along on every fetch (see
`docs/agent-lifecycle/approvals.md::Two repos per agent`).