docs(agents): drop nonexistent-thing mentions, state current behaviour
This commit is contained in:
atlas
mara
parent
578ee90096
commit
78aacf13ce
3 changed files with 39 additions and 45 deletions
|
|
@ -2,16 +2,15 @@
|
|||
|
||||
<!-- vale write-good.Passive = NO -->
|
||||
|
||||
Agents are a **flat set**, with no parent/child tree: the `parent` field
|
||||
`topology.json` used to carry is gone, along with every mechanism that
|
||||
read it. The capability store scopes which agents can manage which
|
||||
others; a tree position no longer scopes anything.
|
||||
Agents are a **flat set**, with no parent/child tree: `topology.json`
|
||||
carries no `parent` field, and the capability store — not tree
|
||||
position — scopes which agents can manage which others.
|
||||
|
||||
<!-- vale write-good.Passive = YES -->
|
||||
|
||||
This doc covers what the roster file is now, what the removal took with
|
||||
it, and where the manager still gets special-cased, as a tracked
|
||||
cleanup.
|
||||
This doc covers what the roster file holds today, the map-shaped
|
||||
alternative `topology::all_agents` still accepts, and where the manager
|
||||
still gets special-cased, as a tracked cleanup.
|
||||
|
||||
## Where the roster lives
|
||||
|
||||
|
|
@ -49,11 +48,11 @@ agent's `state` read-write and `config` read-only; never `harness`). An
|
|||
agent holding no capability sees its own dirs and nothing else. See
|
||||
[`persistence.md`](persistence.md)'s _Cross-agent access to state._
|
||||
|
||||
### Reading the legacy format
|
||||
### Reading the map-shaped format
|
||||
|
||||
`topology.json` used to be a map of `name → parent | null`. The reader
|
||||
still accepts that shape and keeps its keys, so a hive upgrading across
|
||||
the change reads the same roster rather than an empty one. An empty
|
||||
`topology.json` may also be a map of `name → parent | null`; the reader
|
||||
accepts that shape too and keeps its keys, so a hive with a file in that
|
||||
shape still reads the same roster rather than an empty one. An empty
|
||||
roster costs more than a cosmetic gap: every capability holder loses its
|
||||
mounts until the next reconcile pass writes the array form.
|
||||
|
||||
|
|
@ -79,7 +78,7 @@ from which agents exist, so the next pass overwrites a hand edit.
|
|||
See `hive-c0re/src/agent_config/topology.rs` and `hive-c0re/src/meta.rs`'s
|
||||
module docs for the exact call chain.
|
||||
|
||||
## What the parent field used to do
|
||||
## What replaced the parent field
|
||||
|
||||
Recorded so a reader who finds one of these in an old branch, an issue
|
||||
thread or a stale comment knows each one went away rather than moved:
|
||||
|
|
@ -98,10 +97,10 @@ thread or a stale comment knows each one went away rather than moved:
|
|||
|
||||
<!-- vale write-good.Passive = NO -->
|
||||
|
||||
The last row is the one with teeth: an agent that used to reach a child's
|
||||
state dir by virtue of being its parent no longer reaches it at all
|
||||
unless it holds `ManageRootAgent`. That narrowing is the intended
|
||||
consequence of removing the field, not a side effect of it.
|
||||
The last row is the one with teeth: reaching a child's state dir
|
||||
requires holding `ManageRootAgent`; parentage grants nothing. That
|
||||
narrowing is the intended consequence of removing the field, not a
|
||||
side effect of it.
|
||||
|
||||
<!-- vale write-good.Passive = YES -->
|
||||
|
||||
|
|
@ -141,12 +140,11 @@ everything below applies only when it doesn't:
|
|||
manage any agent's state dir — config isn't authored there, since a
|
||||
real config change is a PR from a clone), plus RO mounts for
|
||||
`/applied` (diff against what's deployed) and `/meta` (system-wide
|
||||
deploy log). That grant is the `ManageRootAgent` capability now, and
|
||||
ruth holds it; no name check remains. hive-c0re will
|
||||
deploy log). That grant is the `ManageRootAgent` capability, which
|
||||
ruth holds; nothing checks the agent's name. hive-c0re will
|
||||
gate RO `/meta` access on a "meta read" capability; no agent-facing
|
||||
path writes `flake.lock` any more — `request_update_meta_inputs` was
|
||||
removed, leaving the operator dashboard's `POST
|
||||
/api/meta-update` as the only entry point.
|
||||
path writes `flake.lock` — the operator dashboard's `POST
|
||||
/api/meta-update` is the only entry point.
|
||||
- **Prompt** — treated identically: `prompt::render` always filters for `agent`. `prompts/system.md`
|
||||
still carries `<!-- role:agent -->` / `<!-- role:manager -->` marker
|
||||
blocks, but `prompt::render` filters for `"agent"` unconditionally for
|
||||
|
|
|
|||
|
|
@ -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`).
|
||||
|
|
|
|||
|
|
@ -80,8 +80,7 @@ transitions the job-queue scheduler or crash watcher drive directly —
|
|||
stop/kill, destroy, a flake-rev login or logout state change — reach
|
||||
no individual agent: they publish onto a swarm-wide NATS
|
||||
JetStream stream (`swarm_notices::notify`,
|
||||
`hive-c0re/src/swarm_notices.rs`); every hive is swarm-controlled, so
|
||||
there is no manager-agent fallback to push an in-container todo to.
|
||||
`hive-c0re/src/swarm_notices.rs`); every hive is swarm-controlled.
|
||||
|
||||
**Inbox** (`inbox` group): `get_loose_ends()`,
|
||||
`cancel_loose_end(kind, id)`, `remind(message, delay_seconds? |
|
||||
|
|
@ -153,16 +152,13 @@ hive_name?, swarm_name?, matrix_accounts? }`. `matrix_accounts` is a
|
|||
default-on like bash execution (no tool group gates it yet). See
|
||||
[`docs/tools/subagent.md`](../tools/subagent.md).
|
||||
- **Lifecycle + config** (`lifecycle`, `approvals`) — neither group
|
||||
carries an MCP tool any more: `list_containers` and
|
||||
`request_update_meta_inputs` no longer exist, with no
|
||||
replacement. `approvals` survives as a server-side gate on
|
||||
carries an MCP tool. `approvals` survives as a server-side gate on
|
||||
`cancel_loose_end`'s approval-cancel arm; `lifecycle` gates nothing.
|
||||
Config changes go through a forge PR on `agent-configs/<name>` — see
|
||||
[`docs/agent-lifecycle/approvals.md`](../agent-lifecycle/approvals.md).
|
||||
- **Scheduling** (`scheduling`) — scheduled prompts. See
|
||||
[`docs/tools/scheduling.md`](../tools/scheduling.md).
|
||||
- **Forge repos** (`forge`) — carries no MCP tool: `create_repo` no
|
||||
longer exists, with no replacement; `forge` gates nothing.
|
||||
- **Forge repos** (`forge`) — carries no MCP tool; `forge` gates nothing.
|
||||
- **Web egress** (`web_tools`) — enables Claude's built-in `WebFetch`
|
||||
and `WebSearch` tools (not MCP tools; added directly to the
|
||||
`--allowedTools` list). Off by default; add the group in the
|
||||
|
|
|
|||
Loading…
Reference in a new issue