vinzenz/hyperhive
vinzenz/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Activity

Compare commits

base: vinzenz:9fd5a7a6898295c9ed2976faec2e0af02674d7e9
Branches Tags
vinzenz:main
..
compare: vinzenz:df498a9abebd559f829b1de6583d677316f3f5e8
Branches Tags
vinzenz:main
5 changed files with 33 additions and 33 deletions
Download patch file Download diff file Expand all files Collapse all files

16
docs/agent-lifecycle/approvals.md
View file

@ -25,9 +25,9 @@ CLI) before it takes effect. What you'll see, and what to do with it:
the agent stays on its last-good config, no recovery action needed the agent stays on its last-good config, no recovery action needed
from you. from you.
- **New agent** (`Spawn`) — the one approval in creating a brand-new - **New agent** (`Spawn`) — the one approval in creating a brand-new
agent. The swarm controller's `InitAgentConfigRepo` job agent. Its config repo is scaffolded first, outside the approval
(`POST /api/agents`) scaffolds its config repo first, outside the queue, by the swarm controller's `InitAgentConfigRepo` job
approval queue; `Spawn` then creates the container from that (`POST /api/agents`); `Spawn` then creates the container from that
config. Tailoring what the template seeded isn't a separate config. Tailoring what the template seeded isn't a separate
mechanism — it's the config-change flow above, a PR you review like mechanism — it's the config-change flow above, a PR you review like
any other. Every later change goes through that flow — there's no any other. Every later change goes through that flow — there's no
@ -133,9 +133,9 @@ agent that lacks the `approvals` tool group: only an agent with that
group submits approvals (for its direct children), so an agent group submits approvals (for its direct children), so an agent
without it has nothing of its own to withdraw. without it has nothing of its own to withdraw.
The swarm controller's `InitAgentConfigRepo` job creates a brand-new A brand-new agent's config repo is created outside this queue, by the
agent's config repo outside this queue, seeding it with a default swarm controller's `InitAgentConfigRepo` job, which seeds it with a
`agent.nix` template. The operator then **spawns** the agent default `agent.nix` template. The operator then **spawns** the agent
(the `Spawn` approval / `◆ R3QU3ST SP4WN` button), which creates the (the `Spawn` approval / `◆ R3QU3ST SP4WN` button), which creates the
container from that config. container from that config.
@ -612,8 +612,8 @@ root agent. Variants (`hive_sh4re::manager::HelperEvent`):
approval transitions to its terminal state. approval transitions to its terminal state.
- `ContainerCrash { agent, note }` — `crash_watch`: a previously- - `ContainerCrash { agent, note }` — `crash_watch`: a previously-
running container went away with no operator-initiated transient running container went away with no operator-initiated transient
state (Stopping / Restarting / Destroying / Rebuilding) AND nothing state (Stopping / Restarting / Destroying / Rebuilding) AND no
cleared that transient in the last 30s (`RECENT_TRANSIENT_GRACE` such transient was cleared in the last 30s (`RECENT_TRANSIENT_GRACE`
tombstone, three `POLL_INTERVAL`s — closes the race where a tombstone, three `POLL_INTERVAL`s — closes the race where a
lifecycle op finishes between two crash-watch polls and the lifecycle op finishes between two crash-watch polls and the
container shows briefly as "stopped without transient" before container shows briefly as "stopped without transient" before

16
docs/swarm/services.md
View file

@ -17,7 +17,7 @@ visible difference rather than one more paragraph saying the same thing.
`singleHostSwarm` is the all-on-one-box switch above it: it defaults `singleHostSwarm` is the all-on-one-box switch above it: it defaults
both `deploy.allSwarmServices` and `swarm.ca.autoConfigure` (this host both `deploy.allSwarmServices` and `swarm.ca.autoConfigure` (this host
generates the swarm CA here). You can still set each derived toggle on its own, generates the swarm CA here). Each derived toggle can still be set on its own,
which wins, so "all local except X" needs no further option. which wins, so "all local except X" needs no further option.
**Both default to off**, and that's deliberate: a host can't tell **Both default to off**, and that's deliberate: a host can't tell
@ -46,7 +46,7 @@ the shapes worth naming are the ones they produce:
somewhere. somewhere.
**These are a set, not a ladder with a correct top, and hyperhive **These are a set, not a ladder with a correct top, and hyperhive
supports in-between shapes.** You can set each derived toggle on its own (see supports in-between shapes.** Each derived toggle can be set on its own (see
above), which is what makes "all local except X" a configuration rather above), which is what makes "all local except X" a configuration rather
than an unsupported edge case. Nothing in hyperhive prescribes a than an unsupported edge case. Nothing in hyperhive prescribes a
deployment model, so a doc that treats one shape as the real one and deployment model, so a doc that treats one shape as the real one and
@ -75,8 +75,8 @@ there is one IdP and one auth path.
joining someone else's swarm sets it explicitly. Null means "no SSO joining someone else's swarm sets it explicitly. Null means "no SSO
configured", and consumers say so rather than guessing an address. configured", and consumers say so rather than guessing an address.
swarm-controller writes the users database, not by hand: hive-c0re swarm-controller writes the users database, not by hand: agents
creates and destroys agents continuously, so the subject set is dynamic. are created and destroyed continuously, so the subject set is dynamic.
This module only guarantees the file exists and parses, so authelia This module only guarantees the file exists and parses, so authelia
starts with nobody in it rather than failing to start — a provider with starts with nobody in it rather than failing to start — a provider with
no subjects yet is the correct state before anything has provisioned no subjects yet is the correct state before anything has provisioned
@ -98,8 +98,8 @@ generates and reads each of its keys.
The swarm's telemetry lands in one VictoriaMetrics, and one Grafana The swarm's telemetry lands in one VictoriaMetrics, and one Grafana
reads it, in two containers at `metrics.<swarm-domain>` and reads it, in two containers at `metrics.<swarm-domain>` and
`grafana.<swarm-domain>`. Two containers rather than one so you can `grafana.<swarm-domain>`. Two containers rather than one so Grafana can
restart or break Grafana without taking the time-series database with it. be restarted or broken without taking the time-series database with it.
They derive together: a store with no UI is unreadable and a UI with no They derive together: a store with no UI is unreadable and a UI with no
store is empty. To run one without the other, set it directly: store is empty. To run one without the other, set it directly:
@ -144,8 +144,8 @@ no setting here changes that, so Explore is the log browser for this
swarm. swarm.
| Option | When you'd touch it | | Option | When you'd touch it |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `deploy.victorialogs.retentionPeriod` | Default `30d`, far shorter than the metrics store's — logs are bulkier per unit of value and are typically read within days of ingestion. Raise it if you need to answer questions about last quarter. | | `deploy.victorialogs.retentionPeriod` | Default `30d`, far shorter than the metrics store's — logs are bulkier per unit of value and are typically read within days of being written. Raise it if you need to answer questions about last quarter. |
| `swarm.victorialogs.domain` | Only to rename it. | | `swarm.victorialogs.domain` | Only to rename it. |
| `swarm.victorialogs.port` | Only if something else on the services host already claims `9428`. | | `swarm.victorialogs.port` | Only if something else on the services host already claims `9428`. |

18
docs/tools/bash.md
View file

@ -23,14 +23,14 @@ When the task completes (or times out, or the process errors), it
surfaces as a todo in the agent's loose-ends (via `get_loose_ends`), surfaces as a todo in the agent's loose-ends (via `get_loose_ends`),
carrying the exit code and a `Read(<path>)` pointer to the captured carrying the exit code and a `Read(<path>)` pointer to the captured
output. Handle it on a future turn — unless `wait_seconds` already output. Handle it on a future turn — unless `wait_seconds` already
delivered the terminal result inline, in which case the daemon creates delivered the terminal result inline, in which case no todo is created
no todo (see `status` below). (see `status` below).
- `timeout_secs` — kill the task after N seconds and mark it - `timeout_secs` — kill the task after N seconds and mark it
`timed_out`. Omit for no timeout (runs until natural exit). `timed_out`. Omit for no timeout (runs until natural exit).
- `wait_seconds` — inline poll before returning (capped at 30). - `wait_seconds` — inline poll before returning (capped at 30).
When the task finishes within the window the full status is When the task finishes within the window the full status is
returned immediately and the daemon creates no todo; when the window expires returned immediately and no todo is created; when the window expires
the task keeps running and the daemon returns the normal the task keeps running and the daemon returns the normal
`task started: id=<id>` response. **Defaults to 3** — pass `wait_seconds: 0` `task started: id=<id>` response. **Defaults to 3** — pass `wait_seconds: 0`
to disable inline waiting and always get the immediate response. to disable inline waiting and always get the immediate response.
@ -55,7 +55,7 @@ Poll the status of a task submitted with `run`. Returns:
`wait_seconds` — optional inline poll (capped at 30): when the task `wait_seconds` — optional inline poll (capped at 30): when the task
finishes within the window the call returns the full status immediately. finishes within the window the call returns the full status immediately.
Useful to avoid a separate round-trip when you expect the task to Useful to avoid a separate round-trip when the task is expected to
finish soon. finish soon.
Any `status` call (waited or not) that observes a terminal task clears Any `status` call (waited or not) that observes a terminal task clears
@ -124,14 +124,14 @@ loose-end follows.
## Relationship to the `execution` tool group ## Relationship to the `execution` tool group
`ToolGroup::Execution` (in `AGENT_DEFAULT`) is the real gate on bash: `ToolGroup::Execution` (in `AGENT_DEFAULT`) is the real gate on bash: it
`extra_server_required_group` (in `hive-agent/src/mcp_config.rs`) controls whether the `bash` MCP server is rendered into the agent's
controls whether the `bash` MCP server reaches the agent's claude claude config at all (`extra_server_required_group` in
config at all, suppressing every `mcp__bash__*` tool `hive-agent/src/mcp_config.rs`), suppressing every `mcp__bash__*` tool
when absent — not just leaving them unused. Its own `tools()` returns when absent — not just leaving them unused. Its own `tools()` returns
`&[]` and stays that way: `mcp__bash__run`/`status`/`kill` belong to a `&[]` and stays that way: `mcp__bash__run`/`status`/`kill` belong to a
different, out-of-process MCP server (`bash`, not `hyperhive`), so they different, out-of-process MCP server (`bash`, not `hyperhive`), so they
were never real entries in the `mcp__hyperhive__*` allowlist `tools()` were never real entries in the `mcp__hyperhive__*` allowlist `tools()`
builds — the two dead `["run", "status"]` strings it used to return builds — the two dead `["run", "status"]` strings it used to return
matched nothing, so they're gone now. Removing `execution` from an matched nothing and have been removed. Removing `execution` from an
agent's groups **does** remove bash availability. agent's groups **does** remove bash availability.

6
docs/tools/forge.md
View file

@ -17,8 +17,8 @@ markdown-docs > docs/tools/forge-cli.md`.
- Credentials: `$HYPERHIVE_STATE_DIR/forge-token` - Credentials: `$HYPERHIVE_STATE_DIR/forge-token`
- Active repo resolves, highest priority first: global `-r/--repo` flag - Active repo resolves, highest priority first: global `-r/--repo` flag
> the `origin` remote of the cwd's git checkout > `$HIVE_FORGE_REPO` > the `origin` remote of the cwd's git checkout > `$HIVE_FORGE_REPO`
(last-resort override, unset by default) > a hard error. (last-resort override, unset by default) > a hard error. No single
`client::Client::from_env` assumes no single repo by default. repo is assumed by default — see `client::Client::from_env`.
## Verbs ## Verbs
@ -128,7 +128,7 @@ distinct output shape — pick by what you need:
| ------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| The full human view of one item — title, body, **and** every comment in order | `view <n>` | prose dump; **marks the thread read** (clears the read-before-comment guard). Top-level `view` autodetects issue-or-PR by number; scoped `issue view <n>` / `pr view <n>` do the same when you already know the kind | | The full human view of one item — title, body, **and** every comment in order | `view <n>` | prose dump; **marks the thread read** (clears the read-before-comment guard). Top-level `view` autodetects issue-or-PR by number; scoped `issue view <n>` / `pr view <n>` do the same when you already know the kind |
| Just the structured metadata of one item (state, labels, assignees, head sha…) | `issue <n>` / `pr <n>` | JSON object | | Just the structured metadata of one item (state, labels, assignees, head sha…) | `issue <n>` / `pr <n>` | JSON object |
| Only the comments (skip the body), for example to catch up a long thread; for PRs, review bodies (approve/request-changes/comment summaries) come along too | `comments <n>` [`--tail N`] | comment + review-body list; **marks read** | | Only the comments (skip the body), for example to catch up a long thread; for PRs, review bodies (approve/request-changes/comment summaries) are merged in too | `comments <n>` [`--tail N`] | comment + review-body list; **marks read** |
| One specific comment by its id | `comment-show <id>` | single comment | | One specific comment by its id | `comment-show <id>` | single comment |
| The audit trail — closes, label/assignee changes, commit refs, merges (no comment bodies) | `timeline <n>` | event list | | The audit trail — closes, label/assignee changes, commit refs, merges (no comment bodies) | `timeline <n>` | event list |
| The code change | `pr diff <n>` | unified diff | | The code change | `pr diff <n>` | unified diff |

4
docs/web-ui/agent.md
View file

@ -173,7 +173,7 @@ The todos flyout is the only per-agent flyout — there is no separate
"loose-ends" or "tasks" list. There used to be a note here about the "loose-ends" or "tasks" list. There used to be a note here about the
`ask`/`answer` MCP tools having no inline answer form in this `ask`/`answer` MCP tools having no inline answer form in this
terminal — that whole mechanism (the tools, the dashboard's questions terminal — that whole mechanism (the tools, the dashboard's questions
pane, the wire protocol) no longer exists, so there's pane, the wire protocol) has since been removed entirely, so there's
nothing left to render a form for. nothing left to render a form for.
## Live view ## Live view
@ -270,7 +270,7 @@ Successful POSTs return 200 (no 303 redirects). Error responses
use semantic status codes: **400** for missing/invalid input use semantic status codes: **400** for missing/invalid input
(`body` required, unknown model name, invalid effort level), (`body` required, unknown model name, invalid effort level),
**409** for retryable state conflicts (turn in flight when **409** for retryable state conflicts (turn in flight when
`/compact` fires), **500** only for genuine server/transport `/compact` is called), **500** only for genuine server/transport
failures. The matching failures. The matching
mutations fire `LiveEvent` variants on the per-agent bus, so the mutations fire `LiveEvent` variants on the per-agent bus, so the
client doesn't refetch `/api/state` on submit — the SSE stream client doesn't refetch `/api/state` on submit — the SSE stream