From a9e05d3bb13d72d2e3f5a88d523cfc9195267db4 Mon Sep 17 00:00:00 2001 From: atlas Date: Sun, 2 Aug 2026 04:50:26 +0200 Subject: [PATCH] docs: repair the CLAUDE.md repo map This file auto-loads into every agent's context on every turn, so each error in it is paid continuously by everyone rather than once by whoever reads it. Four of them: Five workspace members were missing entirely: hive-jobq, hive-types, hive-agent-sock, hive-core-agent-sock, hive-screen-mcp. hive-jobq is the worst of those to omit -- it is the crate the c0re-side job_queue layer is being folded into, so the map that loads every turn did not mention the target crate exists. hive-claude was listed as a workspace member. It has no directory here and is consumed as a dependency, so anyone following the map went looking for source that is not in this repo. Moved to its own section that says so. The issue tracker was linked at a loopback address. Inside an agent container loopback is the agent, not the forge, so the link cannot resolve for its primary audience; point at the env var instead. The ops label was written with a colon. The real label uses a slash, and a colon does not fail loudly -- the filter matches nothing and returns unfiltered results, which reads like a backlog instead of like an error. --- CLAUDE.md | 60 +++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 50 insertions(+), 10 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 9d811e00..d853b55c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -5,11 +5,15 @@ Hey claude. This is your starting page. The detailed docs live in when you need depth on a subsystem. This file is the index. - High-level project intro: **[README.md](README.md)**. -- Open work + backlog: the **[forge issue - tracker](http://localhost:3000/hyperhive/hyperhive/issues)**. +- Open work + backlog: the forge issue tracker at + **`$HIVE_FORGE_URL/hyperhive/hyperhive/issues`**. Read the host out of + the env var — inside an agent container `localhost` is the *agent*, not + the forge, so a hardcoded loopback address fails to connect. - Operator/agent trust-boundary design: - **[docs/boundary.md](docs/boundary.md)** (`area:ops` issues - for the deployment/gateway/privsep work). + **[docs/boundary.md](docs/boundary.md)** (`area/ops` issues + for the deployment/gateway/privsep work — the separator is a **slash**; + `--label area:ops` matches nothing and silently returns *unfiltered* + results, which reads like a backlog rather than like an error). - Agent trust model (trust boundary, prompt-injection threat model, capability = accepted risk), credential isolation + sandbox threat model: **[docs/security.md](docs/security.md)**. @@ -50,12 +54,20 @@ hand-maintained per-file tree drifts out of sync with the code. streamable-http listener, `hive-mcp-http` systemd unit) + its claude launch-config layer (tool-group/capability → `--allowedTools`, `--mcp-config` render). -- **`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`. See `hive-claude/README.md`. +- **`hive-jobq/`** — persistent job-DAG scheduler, extracted from + hive-c0re's in-tree `job_queue` as a domain-agnostic library. One + persistent graph for the whole system (not a DAG per job); enqueuing + inserts a self-contained sub-DAG and returns its node ids. 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-screen-mcp/`** — stdio MCP bridge for GUI agents + (`hyperhive.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 @@ -89,6 +101,23 @@ hand-maintained per-file tree drifts out of sync with the code. - **`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/`** — wire types for the *in-agent* socket, served by + the harness to in-container producers (matrix / bash MCP daemons, + `forge_notify`). Carries the loose-ends-v2 **todo** ops plus + harness-local reminders + questions. ⚠️ 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. +- **`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 @@ -101,6 +130,17 @@ hand-maintained per-file tree drifts out of sync with the code. - **`hive-metric/`** — small CLI to push a single labeled metric to the OTEL collector via the OpenTelemetry Rust SDK / OTLP HTTP exporter. +### 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. + ### Other top-level dirs - **`frontend/`** — npm workspaces → static dashboard + per-agent UI