From b99ce2b572404b1c1ef7f739256eea8f09e059fa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?m=C3=BCde?= Date: Wed, 14 Oct 2026 19:34:34 +0200 Subject: [PATCH] CLAUDE.md: build commands, the 8 missing crates, leaner entries Adds a build & check section, maps every workspace member, links gotchas.md, and trims entries down to purpose + warnings (the rest lives in each crate's //! doc). Also drops the comment in turn.rs that repeated the module doc. --- CLAUDE.md | 381 ++++++++++++++++------------------------- hive-agent/src/turn.rs | 6 - 2 files changed, 144 insertions(+), 243 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 5b8917fc..5ff74582 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -16,6 +16,27 @@ when you need depth on a subsystem. This file is the index. - Agent trust model (trust boundary, prompt-injection threat model, capability = accepted risk), credential isolation + sandbox threat model: **[docs/trust-boundary/security.md](docs/trust-boundary/security.md)**. +- Odd-looking nspawn / container plumbing usually has a story: + **[docs/process/gotchas.md](docs/process/gotchas.md)**. + +## Build & check + +Always through the devshell — a bare `cargo` fails (`failed to find tool +"cc"`, `cannot find -lsqlite3`). Details: +[`docs/process/conventions.md`](docs/process/conventions.md#building--local-checks). + +```sh +nix develop -c cargo clippy --all-targets -- -D warnings +nix develop -c cargo test +nix fmt # treefmt is the CI gate, NOT bare cargo fmt +``` + +Changed a `hivectl` / `swarmctl` verb or flag? Regenerate its doc — only +CI's `nix flake check` catches the drift: +`nix develop -c cargo run --bin hivectl -- markdown-docs > docs/tools/hivectl-cli.md` +(same for `swarmctl` → `docs/tools/swarmctl-cli.md`). CI red but local +green → build the suspect check (e.g. `nix build +.#checks.x86_64-linux.hivectl-docs`) before blaming the builder. ## Repo map @@ -27,251 +48,140 @@ hand-maintained per-file tree drifts out of sync with the code. ### Rust workspace (`Cargo.toml` members) +Per-hive (host + in-container): + - **`hive-c0re/`** — host daemon (runs as the unprivileged `hive-core` - user). `src/main.rs` is the `hive-c0re` binary — **daemon-only** - (`serve` + the periodic vacuum/sweep loops); the operator CLI lives in - the separate `hivectl` crate, which talks to the daemon over the host - admin socket. Owns the sqlite broker, the reminder queue, the meta - flake, lifecycle (`nixos-container` shellouts), gateway / forge / - matrix wiring (agent forge and matrix accounts are - `swarm-controller`'s), per-container stats, and the axum operator - dashboard (`dashboard/`). Largest crate. -- **`hivectl/`** — standalone operator CLI (`hivectl` binary). Talks to - the `hive-c0re` daemon over the host admin socket (`hive-host-sock` - wire types) — does NOT link `hive-c0re`. Full, always-current verb - reference (CI-enforced against the clap tree, see `docs/process/conventions.md`): + user), **daemon-only** — the operator CLI is `hivectl`. Owns the sqlite + broker, reminder queue, meta flake, lifecycle (`nixos-container` + shellouts), gateway wiring, per-container stats and the axum operator + dashboard. Agent forge/matrix accounts are `swarm-controller`'s. Largest + crate. +- **`hivectl/`** — operator CLI; talks to `hive-c0re` over the host admin + socket, does NOT link it. Verb reference (CI-enforced): [`docs/tools/hivectl-cli.md`](docs/tools/hivectl-cli.md). -- **`hive-agent/`**, **`hive-agent-mcp/`** — - in-container harness, two sibling crates for every agent (not a - single `hive-ag3nt/` dir — that's the runtime/binary-family nickname, - not a directory). -- **`hive-agent/`** — the serve-loop binary: turn-loop *policy* layer - (`turn.rs`) over `hive-runtime`, per-agent web UI (`web_ui/` - module dir), event + turn-stats sqlite sinks, login flow, system-prompt - renderer, and the claude launch-config layer (`mcp_config.rs`: - tool-group/capability → `--allowedTools`, `--mcp-config` render). -- **`hive-agent-mcp/`** — the embedded MCP server (long-lived - streamable-http listener, `hive-mcp-http` systemd unit). -- **`hive-runtime/`** — the runtime an agent's turns run on: one - `Runtime` interface (`run`/`compact`/`archive`/`canceller`/`choices`) with a `claude` backend - (a pass-through to `hive-claude`) and an `acp` backend (any Agent Client - Protocol agent, spawned from the command/args/env nix hands it — no agent - is named in Rust). The ACP backend translates its stream into claude's - `stream-json` shape, so the harness's consumers read either unchanged. - Depends on no hyperhive binary crate, so the subagent daemon can use it - too. -- **`hive-jobq/`** — job-DAG scheduler, extracted from hive-c0re's - in-tree `job_queue` as a domain-agnostic library. **Runtime-only — - nothing writes the graph to disk**; hive-c0re starts empty each boot - and re-derives desired state via the reconcile sweep, so node ids and - timestamps are stable within a run, not across restarts. One - shared graph for the whole system (not a DAG per job); enqueuing - inserts a self-contained sub-DAG and returns the ids of the nodes the job - asked for, in the order it named them. Generic over - the node payload `N` and the resource name `R`; resource deps are named - counting semaphores acquired all-or-nothing at node start. `hive-c0re`'s - remaining `job_queue/` module is the c0re-specific layer *over* this - crate, and is being removed in favour of it — new scheduler-shaped code - belongs here, not there. -- **`hive-jobq-wire/`** — wire types for serving a `hive-jobq` graph to a - viewer, plus the `WireNode` / `WireResource` traits a host implements to - say how its `N` and `R` render. Deliberately *not* part of `hive-jobq`: - that crate is logic, this is presentation, and folded together they - remix. `GraphWire::wire_snapshot` is blanket-implemented for any - `Graph` whose parameters implement both — so a payload that has - never said how it displays cannot reach a viewer at all. -- **`hive-log/`** — the one log-sink chooser, called by `hive-c0re`, - `hive-agent` and `swarm-controller` and by nothing else. `init()` builds - the `EnvFilter` those binaries always built, then installs **exactly - one** sink: the native journald layer when an `fstat` of stdout matches - the device and inode numbers systemd exports in `$JOURNAL_STREAM`, the - `fmt` stdout layer otherwise. Under a unit stdout already **is** the - journal, so both layers together store every record twice. Deliberately - single-purpose — do not grow it into a utility crate. -- **`hive-screen-mcp/`** — stdio MCP bridge for GUI agents - (`services.hyperhive.agent.gui.enable`): `screenshot` via `grim`, `type_text` / - `key_press` via `wtype` (Wayland virtual-keyboard protocol), and - `mouse_move` / `mouse_click` as RFB pointer events to the local neatvnc - server. All userspace, no daemon of its own. -- **`hive-priv/`** — minimal root privileged-helper, socket-activated at - `/run/hive/priv.sock`; performs the few root operations (bind-mount - edits, nsenter) the unprivileged `hive-c0re` delegates to it. See - `docs/trust-boundary/boundary.md`. -- **`hive-forge/`** — `hive-forge` Forgejo CLI wrapper; one module per - verb under `src/verbs/`. -- **`hive-forge-notify/`** — per-agent notification poller daemons; turns - unread notification threads into todos on the harness's in-agent - socket. Two binaries from one crate: `hive-forge-notify` (the hive's - Forgejo) and `hive-github-notify` (github.com, installed by - `nix/agent-modules/github.nix`). Was a task inside the `hive-agent` - serve loop; own process since it needs nothing else from the harness. -- **`hive-matrix-mcp/`** — per-agent matrix-sdk daemon - (`hive-matrix-daemon`); serves its MCP tools (`send_message`, - `read_room`, …) directly over streamable-http (no stdio bridge), - same shape as `hive-bash-mcp`. -- **`hive-bash-mcp/`** — per-agent bash-task runner daemon - (`hive-bash-daemon`); serves its MCP tools (`run`/`status`/`kill`) - directly over streamable-http (no stdio bridge), writes task files - under `/harness/bash-tasks/`, and records the favorite-tools - `bash_commands` stat into turn-stats.sqlite. -- **`hive-subagent-mcp/`** — per-agent subagent runner daemon - (`hive-subagent-daemon`); spawns nested sessions on request, on the - parent agent's runtime via `hive-runtime` (claude or ACP), and - serves `start`/`continue`/`status`/`interrupt` directly over - streamable-http (no stdio bridge), plus a second subagent-facing route - carrying `goal_reached`/`need_help` — served per session under a minted - token, since neither tool takes a session name. Independent of `hive-bash-mcp` (a - subagent is a much heavier capability than a bash command). A `start` - with a `goal` is a multi-turn run: the daemon re-prompts the subagent - toward the goal each time a turn ends, up to a per-session turn cap. No - task files — the daemon's state is in-memory only, live only as long as - the process is; the actual claude session survives a daemon restart - independently (see `session.rs`'s module doc). -- **`hive-sh4re/`** — shared wire types (Agent / Manager request + - response, `Message`, `HelperEvent`) used across the unix - sockets. Host-admin-socket and hive-priv-socket wire types have been - split out into their own crates (below) so `hivectl` and `hive-priv` - don't need to pull in the rest of `hive-sh4re`. -- **`hive-host-sock/`** — wire types for the host admin socket - (`/run/hyperhive/host.sock`), the protocol `hivectl` speaks to - `hive-c0re`. Split out of `hive-sh4re` so a standalone `hivectl` only - depends on this protocol crate, not the whole daemon crate. -- **`hive-priv-sock/`** — wire types for the `hive-priv` privileged-helper - socket (`/run/hive/priv.sock`), shared by `hive-priv` (server) and - `hive-c0re` (client). Also split out of `hive-sh4re`. -- **`hive-core-agent-sock/`** — wire types for the *host*-served per-agent - + manager socket (`/run/hive/mcp.sock`), the protocol an agent's harness - speaks to `hive-c0re`. Same split rationale as the two above; the shared - payload types it references stay in `hive-sh4re`. -- **`hive-agent-sock/`** — what's common across the in-container "agent - plugins" (matrix/bash/subagent MCP daemons, `forge_notify`, any - user-configured MCP server). Wire types for the *in-agent* socket, served - by the harness to those producers — nothing restricts the `subsystem` set - on the todo ops, any producer can push its own. Carries the loose-ends-v2 - **todo** ops plus harness-local reminders. ⚠️ Distinct from - `hive-core-agent-sock` above: **this socket never leaves the container** - and `hive-c0re` is not in the path at all — no broker round-trip, no - long-poll, no marker files. Also carries `extra_mcp`: the - `services.hyperhive.agent.extraMcpServers` spec + parsing, shared by `hive-agent` and - `hive-subagent-mcp` — not a socket protocol, just the natural home since - both already depend on this crate. -- **`hive-types/`** — zero-dependency (bar serde) leaf crate holding the - foundational newtypes, chiefly `Ident` (1–63 chars of `[a-z0-9-]`, - constructed only via the validating parser). Lets every wire-type crate - and both binaries type their agent-name fields as a validated ident and - get serde-checked parsing at the socket boundary, without coupling to - `hive-sh4re`. -- **`hive-sock-client/`** — the shared JSON-line-over-unix-socket client - every daemon uses to talk to a hyperhive socket. Generic over the - request/response types, so the host-served control socket and the - harness's in-agent socket both use it with their own wire-type crates. - Retry is a policy value (`Retry::None` for callers already inside a poll - loop, `Retry::RideOutRestart` for callers with no natural retry), and - the response is either decoded (`request`) or drained (`notify`). - Deliberately separate from the `*-sock` crates — those stay - dependency-free wire types. -- **`hive-metric/`** — small CLI to push a single labeled metric to the - OTEL collector via the OpenTelemetry Rust SDK / OTLP HTTP exporter. -- **`swarm-controller/`** — swarm-level daemon, opt-in per host - (`services.hyperhive.deploy.swarm-controller.enable`). Where `hive-c0re` owns - the agents on **one** host, this owns what is true **across** hives; a - swarm runs one of them, so most hives leave it off. Serves HTTP over a - unix socket the gateway's nginx proxies to — ⚠️ **the socket's - directory is its access control**; the constraint that governs it is in - the crate's README, and a unit test pins the path. -- **`swarm-secret-client/`** — client for the swarm's secret store, over - `vaultrs`. Owns the *agreements* both ends of the store must share rather - than the HTTP: the path a credential lives at, the field its bytes are in, - and the translation from this deployment's environment into a logged-in - client. ⚠️ Reads the **`BAO_`** env spellings explicitly — `vaultrs`'s own - defaults look for `VAULT_ADDR`/`VAULT_CLIENT_CERT`/`VAULT_CLIENT_KEY`, which - no unit in this tree sets, so falling through to them yields a client with - **no identity** and a TLS handshake failure that names no cause. -- **`swarm-review-classifier/`** — the review classifier's try-out daemon, - in its own container where `deploy.review-classifier.enable` is set. Takes - a PR and classifications from `swarm-controller` over the queue, runs one - `claude --print` per classification (no tools, no session) and replies - with the rows and the overall verdict. Holds no forge credential. Design: - [`docs/swarm/review-classifier.md`](docs/swarm/review-classifier.md). -- **`swarm-agent-verify/`** — the check that a presented - `swarm-agent..` token holds the secret stored at - `swarm/agents//queue`, read under the verifier's own certificate. - Shared by `swarm-nats-auth` (the queue's auth callout) and - `swarm-logs-auth`. -- **`swarm-logs-auth/`** — the log store gateway's `auth_request` responder - for agents: nginx sends it `/select/logsql/` requests carrying an agent - token, it answers 200 or 401 via `swarm-agent-verify`. Runs on the log - store's host (`swarm-victorialogs.nix`). -- **`swarm-builder/`** — the swarm builder's build daemon, in its own - container where `deploy.builder.enable` is set. Takes an agent config PR's - head from `swarm-controller` over the queue, builds it on its host's agent - base through the host nix daemon (`nix/builder/check-flake`), and replies - with the store path or the error tail; the controller writes the commit - status. Holds a read-only forge token. Design: - [`docs/swarm/builder.md`](docs/swarm/builder.md). -- **`swarmctl/`** — swarm-level operator CLI, installed by the - swarm-controller module on the host that runs the daemon. Runs as - **root and acts directly** — it serves no socket, publishes no HTTP - route and has no priv helper; the crate's README records why the - rootless shape was examined and rejected. `agent create` is the one - verb that talks to a service rather than acting locally: it POSTs - `/api/agents` to swarm-controller over the daemon's unix socket and - prints the queued job id without waiting (the DAG settling would not - mean the agent is up). With `--swarm`, the controller verbs go - through the swarm domain's gateway instead, as the operator's own SSO - login (`swarmctl login`). Does not link `swarm-controller` — its wire - shapes are a local mirror kept in this crate, not a shared crate, so - the two binaries can be deployed independently. ⚠️ Its user store is - authelia's own **`users.yml`, read and - written in place** — one file, shared with `swarm-authelia-bridge`; see - that crate's README for what both writers must uphold. Full, always-current - verb reference (CI-enforced against the clap tree, same pattern as - `hivectl`'s — see `docs/process/conventions.md`): +- **`hive-priv/`** — minimal root helper, socket-activated at + `/run/hive/priv.sock`; the few root ops (bind-mount edits, nsenter) + `hive-c0re` delegates. See `docs/trust-boundary/boundary.md`. +- **`hive-agent/`** — the in-container serve loop: turn-loop *policy* + (`turn.rs`) over `hive-runtime`, per-agent web UI, event + turn-stats + sinks, system-prompt renderer, claude launch config (`mcp_config.rs`). + With `hive-agent-mcp` it's what "hive-ag3nt" refers to — there is no + such directory. +- **`hive-agent-mcp/`** — the embedded MCP server (`hive-mcp-http` unit). +- **`hive-runtime/`** — the `Runtime` interface an agent's turns run on: + a `claude` backend (over `hive-claude`) and an `acp` backend whose stream + is translated into claude's `stream-json` shape. Links no hyperhive + binary crate, so the subagent daemon uses it too. +- **`hive-bash-mcp/`**, **`hive-matrix-mcp/`**, **`hive-subagent-mcp/`** — + per-agent MCP daemons serving streamable-http directly (no stdio + bridge): background bash tasks, matrix-sdk tools, nested subagent + sessions (optionally goal-driven over several turns; daemon state is + in-memory, the claude session survives a restart). +- **`hive-screen-mcp/`** — stdio MCP bridge for GUI agents: screenshot, + keyboard, mouse. All userspace. +- **`hive-forge/`** — `hive-forge` Forgejo CLI; one module per verb. +- **`hive-forge-notify/`** — notification pollers → todos on the in-agent + socket. Two binaries: `hive-forge-notify`, `hive-github-notify`. +- **`hive-jobq/`** — the job-DAG scheduler library. **Runtime-only — + nothing writes the graph to disk**, so node ids are stable within a run, + not across restarts. `hive-c0re`'s `job_queue/` is being removed in its + favour — new scheduler-shaped code goes here. +- **`hive-jobq-wire/`** — presentation of a `hive-jobq` graph to viewers + (`WireNode` / `WireResource`); kept out of `hive-jobq` on purpose. +- **`hive-jobq-metrics/`** — OTEL export of a graph's state rollup on a + timer. +- **`hive-log/`** — the one log-sink chooser: journald *or* stdout, never + both (under a unit, stdout already is the journal). Do not grow it into a + utility crate. +- **`hive-metric/`** — one-shot CLI pushing a labeled metric over OTLP. + +Wire types + socket plumbing: + +- **`hive-types/`** — leaf newtypes, chiefly the validated `Ident`. +- **`hive-sh4re/`** — shared payload types (`Message`, `HelperEvent`, …). +- **`hive-host-sock/`** (hivectl ↔ c0re), **`hive-priv-sock/`** (c0re ↔ + priv), **`hive-core-agent-sock/`** (harness ↔ c0re, `/run/hive/mcp.sock`) + — per-socket wire types, split out so each client links only its protocol. +- **`hive-agent-sock/`** — the *in-agent* socket the harness serves to + in-container producers (todos, reminders); also holds the `extra_mcp` + spec. ⚠️ **This socket never leaves the container** — `hive-c0re` is not + in the path, unlike `hive-core-agent-sock`. +- **`hive-sock-client/`** — the shared JSON-line unix-socket client; retry + is a policy value (`Retry::None` / `Retry::RideOutRestart`). + +Swarm-level: + +- **`swarm-controller/`** — owns what is true **across** hives; opt-in, + one per swarm. Serves HTTP over a unix socket nginx proxies to — ⚠️ + **the socket's directory is its access control**; the crate README has + the constraint and a unit test pins the path. +- **`swarmctl/`** — swarm operator CLI; runs as **root and acts directly** + (README says why). Does not link `swarm-controller` — its wire shapes + are a local mirror. ⚠️ Edits authelia's **`users.yml` in place**, shared + with `swarm-authelia-bridge`; that crate's README says what both writers + must uphold. Verb reference (CI-enforced): [`docs/tools/swarmctl-cli.md`](docs/tools/swarmctl-cli.md). +- **`swarm-authelia-bridge/`** (+ **`swarm-authelia-bridge-sock/`** wire + types) — the other writer of authelia's users DB; runs inside + `swarm-authelia`. +- **`swarm-secret-client/`** — OpenBao client over `vaultrs`. ⚠️ Reads + the **`BAO_`** env spellings explicitly — `vaultrs`'s `VAULT_*` defaults + are set by no unit here, and falling through to them yields a client + with **no identity** and a TLS failure that names no cause. +- **`swarm-queue-client/`** — the one authenticated connect to the swarm + NATS queue. +- **`swarm-nats-auth/`** — NATS auth-callout responder; without it the + queue is fail-closed and admits nobody. +- **`swarm-agent-verify/`** — checks a `swarm-agent..` + token against the store; shared by `swarm-nats-auth` and + `swarm-logs-auth`. +- **`swarm-logs-auth/`** — nginx `auth_request` responder for agent access + to the log store. +- **`swarm-logs/`** — agent CLI: a LogsQL query in, log lines out. +- **`swarm-matrix-client/`** — appservice calls against the swarm + homeserver, shared by `swarm-controller` and `swarm-matrix-ctl`. +- **`swarm-matrix-ctl/`** — the one binary run inside + `containers.hive-matrix`; new in-container jobs are verbs here, not + crates. +- **`swarm-builder/`** — builds agent config PR heads for commit status. + Design: [`docs/swarm/builder.md`](docs/swarm/builder.md). +- **`swarm-review-classifier/`** — one `claude --print` per PR + classification, no tools, no forge credential. Design: + [`docs/swarm/review-classifier.md`](docs/swarm/review-classifier.md). ### External dependencies with no directory here -- **`hive-claude`** — reusable, app-agnostic driver for headless - `claude --print`: spawns the CLI, streams + classifies stream-json, - parses per-turn `Telemetry`, and drives a durable self-compacting - `InfiniteSession` (name + `SessionStore` + `CompactionPolicy`). Uses - `thiserror` (it's a library); the `hive-*` binaries consume it with - `anyhow`. ⚠️ **Its own repo, not a workspace member** — consumed as a - dependency in the root `Cargo.toml`, so there is no `hive-claude/` - directory to read and `grep` here will not find it. +- **`hive-claude`** — app-agnostic driver for headless `claude --print` + (stream-json, `Telemetry`, the self-compacting `InfiniteSession`). + ⚠️ **Its own repo, not a workspace member** — there is no + `hive-claude/` directory and `grep` here will not find it. ### Other top-level dirs -- **`frontend/`** — npm workspaces → static dashboard + per-agent UI - dist, built hermetically by `nix/packages/frontend.nix`. Packages: - `shared` (terminal pane + Catppuccin palette), `dashboard` (the - operator SPA), `agent` (the default per-container UI), `swarm-ui` - (swarm-level UI shell — Preact + wouter + TypeScript + JSX, project- - bootstrap scope; packaged separately by `nix/packages/swarm-ui.nix`, - not bundled into `packages.default`'s closure — see that file). -- **`nix/`** — `host-modules/` (the host stack: hyperhive core options, - `hive-{c0re,priv,forge,gateway,matrix,network,tls,ci}`, otel, swarm), - `agent-modules/` (the per-agent harness feature modules), - `container-modules/` (modules imported inside service containers — - guest side), `templates/{agent,ruth}.nix` (container entry points), - `packages/` (flake package outputs), `docs/` (the options-doc - derivation), plus `sources.nix` / `rust.nix` / `checks.nix` / - `devshell.nix` / `treefmt.nix` behind the thin `flake.nix`. +- **`frontend/`** — npm workspaces built hermetically by + `nix/packages/frontend.nix`: `shared`, `dashboard` (operator SPA), + `agent` (per-container UI), `swarm-ui` (Preact; packaged separately by + `nix/packages/swarm-ui.nix`, not in `packages.default`'s closure). +- **`nix/`** — `host-modules/` (the host stack), `agent-modules/` + (per-agent harness features), `container-modules/` (guest side of + service containers), `templates/{agent,ruth}.nix` (container entry + points), `packages/`, `docs/` (options doc), `module-eval/` (NixOS + module-eval tests), `builder/` (`check-flake`), `script-tests/`, plus + `sources.nix` / `rust.nix` / `checks.nix` / `devshell.nix` / + `treefmt.nix` behind the thin `flake.nix`. - **`docs/`** — subsystem reference docs (see *Reading paths* below). - **`branding/`**, **`scripts/`** — static assets + helper scripts. ## Reading paths -**[`docs/README.md`](docs/README.md) is the single index** — grouped by topic -(getting started, agent lifecycle, trust boundary, integrations, networking, -scheduler, process). Read it instead of a second copy here; this file used to -carry its own parallel "Reading paths" list, and the two drifted out of sync -with each other. +**[`docs/README.md`](docs/README.md) is the single index**, grouped by +topic. Don't add a second copy of it here — a parallel list used to live +in this file and drifted. ## Conventions & process - **Never add `#[allow(clippy::…)]`** — fix the lint instead (extract a - helper, add backticks, etc.). Details + worked examples: → + helper, add backticks, etc.). Worked examples: [`docs/process/conventions.md`](docs/process/conventions.md#building--local-checks). - **Pre-push lint hook** (catches tracker-tag and comment-block failures before CI does — install once per clone): @@ -279,15 +189,12 @@ with each other. - **Comment/PR-description length**: size it to how non-obvious the thing is, not to how much investigation it took to find it — a mechanical fix gets a one-line comment, a genuinely non-obvious - invariant or decision earns real prose. + invariant or decision earns real prose. Don't restate a module's `//!` + doc in a comment further down the same file. - **Operator-facing doc with real implementation detail mixed in**: wrap the implementation part in a `
…` block - (blank line after `` so the markdown inside still renders, - not a second file) rather than splitting into a sibling page — see - `docs/integrations/github.md`'s "Implementation" section. Zero nav - churn, works uniformly regardless of whether the doc already had a - clean boundary. Caveat: it only collapses in a rendered browser — - reading the file as raw text (`cat`, the Read tool) shows everything, - same as today. Also: the `` line itself isn't markdown- - processed — backticks render as literal characters, not styled code - — so keep summary text plain prose, no inline-code formatting. + (blank line after `` so the markdown inside renders) rather + than a sibling page — see `docs/integrations/github.md`'s + "Implementation" section. It only collapses in a rendered browser, and + the `` line isn't markdown-processed, so keep it plain prose + with no backticks. diff --git a/hive-agent/src/turn.rs b/hive-agent/src/turn.rs index cb38dfe5..61c8b0fe 100644 --- a/hive-agent/src/turn.rs +++ b/hive-agent/src/turn.rs @@ -26,12 +26,6 @@ use crate::mcp_config; // `docs/turn-loop/claude-invocation.md`. Unknown keys are silently ignored by // claude-code; if a key gets renamed we'll spot it because the corresponding // behavior will start firing mid-turn again. -// -// The runtime mechanics — spawning the agent, streaming its output, session -// lookup/archive — live in the generic `hive-runtime` crate. This module is -// the hyperhive *policy* layer on top: -// it builds the per-turn [`Config`] from the bus, forwards the stream to the -// event bus via [`BusSink`], and owns compaction / auto-reset / retry. /// Fixed, harness-owned claude session title. Every turn / compact / /// checkpoint resumes THIS title (`--resume `); the create path