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.
This commit is contained in:
parent
1f8cfdabd9
commit
a9e05d3bb1
1 changed files with 50 additions and 10 deletions
60
CLAUDE.md
60
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
|
||||
|
|
|
|||
Loading…
Reference in a new issue