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