diff --git a/docs/getting-started/setup.md b/docs/getting-started/setup.md index 7622e027f..9ccdf24d3 100644 --- a/docs/getting-started/setup.md +++ b/docs/getting-started/setup.md @@ -111,11 +111,12 @@ container keeps starting with the hive meanwhile. ## 5 · Matrix -Your matrix account comes from SSO. Invite it to the rooms you want it in: +Your matrix account comes from SSO. Invite it to the hive Space, and +optionally to rooms: ```bash -hivectl matrix invite mara --room '#some-room:yourserver' -hivectl matrix invite @mara:yourserver --room '!abc:yourserver' +hivectl matrix invite mara +hivectl matrix invite @mara:yourserver --room '#hive-chat:yourserver' ``` ## 6 · Your first agent diff --git a/docs/integrations/matrix.md b/docs/integrations/matrix.md index 99fd7da58..2f60f311d 100644 --- a/docs/integrations/matrix.md +++ b/docs/integrations/matrix.md @@ -96,7 +96,8 @@ and federation peers all reach the homeserver at `chat.` through the gateway; from outside the host that takes `gateway.openFirewall`. -hive-c0re talks to matrix (its own sender login, invites) through `swarm.matrix.apiUrl`, which defaults to +hive-c0re provisions matrix (its own sender login, the hive Space and +chat room, invites) through `swarm.matrix.apiUrl`, which defaults to `https://` on every hive. That login carries the hive's matrix access token, and on a hive that doesn't run the homeserver it crosses the network, so the default is TLS; hive-c0re @@ -257,8 +258,10 @@ token and gets a refusal on any other hive's. The name says what it authenticates as — an account the swarm's appservice creates — rather than any privilege level, because it carries none. -It needs no promotion for what the hive does with it. Inviting a user into a -room it has the power in is an ordinary client call — there is no homeserver +It needs no promotion for what the hive does with it. Creating the hive +Space and the chat room, writing their hierarchy and join rules, and +inviting agents into them are all ordinary client calls that ride on +being the rooms' own creator at power level 100 — there is no homeserver admin in any of it, and no Synapse admin API to reach for either, since tuwunel has none. @@ -344,17 +347,36 @@ Initial rollout settings: stored yet the account comes up without backup and picks it up on the next daemon start. A failure is a `WARN` and never stops the daemon. -## Hive sender token +## Hive Matrix Space -hive-c0re keeps the hive's `@hive-:` sender token on disk for -`hivectl matrix invite`, refreshed from the swarm secret store by the -matrix sweep (at boot, then every 30 minutes). +On first boot hive-c0re creates a private **Matrix Space** named `"hive"` using its own hive +account (`@hive-:`) and invites every provisioned agent +into it. This gives the operator a single Space in FluffyChat or any +Matrix client that groups all agent-to-agent + operator rooms in one +place. -Earlier versions also created a private "hive" Matrix Space and a -`hive-chat` room, invited every agent to both, and kept their ids in -`/var/lib/hyperhive/matrix/space-room-id` and `chat-room-id`. The sweep no -longer touches any of them. The rooms and files are harmless leftovers, so -delete them by hand if you like. + +The sweep also provisions a default **`hive-chat` room** as an +`m.space.child` of the Space. Joining a Space doesn't autojoin +child rooms — the explicit room entry ensures the operator and every +agent can find a common chat room without manual setup. Room join is +restricted (any Space member including the operator can join; agents +are explicitly invited). Room version pinned to 10 for the restricted +join floor. + + +**State**: hive-c0re persists both room IDs to `/var/lib/hyperhive/matrix/` +(mode `0600`, owned by the hive-c0re service user): +- `space-room-id` — the Space itself +- `chat-room-id` — the `hive-chat` room + +These paths are **outside** every agent state dir and **aren't** deleted by +`nixos-container destroy --purge` — both survive full agent purges, and +hive-c0re reuses them on re-provision. + +**Idempotent**: if the files exist and are non-empty, hive-c0re considers the Space and +room already created. Delete the files to force +re-creation (for example after a homeserver wipe). ## Configuration tuning diff --git a/docs/scheduler/coordinator.md b/docs/scheduler/coordinator.md index e5a8ee4cc..130334fa4 100644 --- a/docs/scheduler/coordinator.md +++ b/docs/scheduler/coordinator.md @@ -73,7 +73,7 @@ Cheap — no build slot: | `EmitRebuilt` | tail of a rebuild — emit the agent's `Rebuilt` manager event (ok/fail per outcome, nothing on cancel). One node per agent _and_ per outcome | | `WriteDropin` | `set_nspawn_flags` + `set_resource_limits` + daemon-reload | | `ForgeSweep` | one-shot boot-time publish of the hive's forge read token for nix (`forge::ensure_all`) as a first-class node, so it shows as real work on the dashboard instead of running invisibly in a bare `tokio::spawn`. Agentless | -| `MatrixSweep` | matrix sender-token sweep (`matrix::ensure_all`): the boot-time instance, plus one every 30 min from a loop in `main.rs`. Holds `Resource::MatrixSweep` (capacity 1), so two passes never overlap; each tick queues its own pass, which waits for the resource if one is already live. Agentless | +| `MatrixSweep` | matrix user/space sweep (`matrix::ensure_all`): the boot-time instance, plus one every 30 min from a loop in `main.rs`. Holds `Resource::MatrixSweep` (capacity 1), so two passes never overlap; each tick queues its own pass, which waits for the resource if one is already live. Agentless | | `KnowledgePull` | `/knowledge` pull (`knowledge::pull`): at boot (commits that landed while `hive-c0re` was down), on the swarm knowledge-changed event, and hourly as a fallback. Holds `Resource::KnowledgeTree` (capacity 1), so two pulls never overlap on the working tree; each trigger queues its own pass, which waits for the resource if one is already live. Agentless | | `WantedPull` | pull of the agent set the swarm controller declares for this hive (`wanted::pull`), converging the agents it names. Runs at boot, waiting up to a minute in total for the queue connection, and again after every attach of the wanted-state watch (which retries with a backoff when the attach fails or the stream ends); the deploy event (`swarm_status`) and the watch are the fast path, this repairs a missed one. A first deploy already queued or running for an agent isn't queued again. Agentless | diff --git a/docs/tools/hivectl-cli.md b/docs/tools/hivectl-cli.md index 8655f703c..85a7ec039 100644 --- a/docs/tools/hivectl-cli.md +++ b/docs/tools/hivectl-cli.md @@ -116,21 +116,21 @@ Always prints the diff first. `--from forge` resets the local checkout to forge matrix-tuwunel invites. -Manual invites into a room by id or alias. +Manual invites into the hive Space and its rooms; c0re's periodic matrix sweep provisions the Space, the chat room and the agents' invites on its own. **Usage:** `hivectl matrix ` ###### **Subcommands:** -* `invite` — Invite a matrix user to a room. Idempotent +* `invite` — Invite a matrix user to the hive Space, or a specific room with `--room`. Idempotent ## `hivectl matrix invite` -Invite a matrix user to a room. Idempotent +Invite a matrix user to the hive Space, or a specific room with `--room`. Idempotent -**Usage:** `hivectl matrix invite --room ` +**Usage:** `hivectl matrix invite [OPTIONS] ` ###### **Arguments:** @@ -138,7 +138,7 @@ Invite a matrix user to a room. Idempotent ###### **Options:** -* `--room ` — Target room id (`!abc:server`) or alias (`#name:server`) +* `--room ` — Target room id (`!abc:server`) or alias (`#name:server`). Omit to invite to the hive Space diff --git a/docs/tools/hivectl.md b/docs/tools/hivectl.md index 43822c89b..a31057ee0 100644 --- a/docs/tools/hivectl.md +++ b/docs/tools/hivectl.md @@ -44,12 +44,13 @@ hivectl forge reconcile-config iris --verbose # include the full diff, not ## Matrix -Manual invites into a room. Requires the `hive-matrix` container to be +Manual entry to the same idempotent matrix provisioning flow +`hive-c0re` runs at boot. Requires the `hive-matrix` container to be running (`services.hyperhive.deploy.matrix.enable = true`). ```bash -hivectl matrix invite mara --room '#some-room:server' # a room alias -hivectl matrix invite @mara:server --room '!abc:server' # ...or a room id +hivectl matrix invite mara # invite a user to the hive Space +hivectl matrix invite @mara:server --room '#hive-chat:server' # ...or to a specific room/alias ``` Human matrix accounts come from SSO, not `hivectl`; matrix homeserver @@ -57,9 +58,10 @@ admin should eventually come from membership in authelia's `admins` group; nobody has built that sync yet. - `invite`: invites a matrix user (full `@user:server` or a bare - localpart, qualified with the homeserver's `server_name`) to the - `--room` id / `#alias`. Uses the sender token; the account must be a - member of the target room with invite power. + localpart, qualified with the homeserver's `server_name`) to the hive + Space by default, or to a `--room` id / `#alias`. Uses the sender + token; the account must be a member of the target room with + invite power (it owns the hive Space, so that case always works). Idempotent — already-member / already-invited is a no-op. ## Agents diff --git a/hive-c0re/src/job_queue/exec.rs b/hive-c0re/src/job_queue/exec.rs index 4c2ae7059..bb0c9228a 100644 --- a/hive-c0re/src/job_queue/exec.rs +++ b/hive-c0re/src/job_queue/exec.rs @@ -106,7 +106,7 @@ pub(super) trait Host: Sync { fn purge_dirs(&self, name: &str) -> Vec; /// Publish the hive's forge credential for nix. async fn forge_ensure_all(&self); - /// One matrix sender-token pass; whether the token is in place. + /// One matrix user/space pass; whether every agent synced. async fn matrix_ensure_all(&self) -> bool; /// One `/knowledge` pull. async fn knowledge_pull(&self, coord: &Arc) -> Result<()>; @@ -367,7 +367,7 @@ async fn run_forge_sweep(host: &impl Host) -> Result<()> { Ok(()) } -/// Matrix sender-token sweep as a DAG node — see [`NodeKind::MatrixSweep`]. +/// Matrix user/space sweep as a DAG node — see [`NodeKind::MatrixSweep`]. /// Every pass reports here, whoever submitted it: as the node's own error on /// the dashboard, and into the debounced warning. async fn run_matrix_sweep(host: &impl Host, deadline: std::time::Duration) -> Result<()> { @@ -411,8 +411,9 @@ fn matrix_sweep_warning(ctx: sweep_health::SweepFailure) -> String { |d| format!("last ok {} ago", sweep_health::fmt_age(d)), ); format!( - "matrix sender-token sweep failing ({} consecutive, {age}) \ - — `hivectl matrix invite` may not work", + "matrix user/space sweep failing ({} consecutive, {age}) \ + — some agents may be missing matrix accounts, space membership, \ + or chat-room invites", ctx.consecutive ) } diff --git a/hive-c0re/src/job_queue/model.rs b/hive-c0re/src/job_queue/model.rs index dd9e3b35e..fa755a451 100644 --- a/hive-c0re/src/job_queue/model.rs +++ b/hive-c0re/src/job_queue/model.rs @@ -99,7 +99,7 @@ pub enum NodeKind { /// One-shot boot-time publish of the hive's forge read token for nix /// (`forge::ensure_all`). Agentless. ForgeSweep, - /// Matrix sender-token sweep (`matrix::ensure_all`): at boot and every 30 + /// Matrix user/space sweep (`matrix::ensure_all`): at boot and every 30 /// minutes. Agentless. MatrixSweep, /// `/knowledge` pull (`knowledge::pull`): at boot, on the swarm diff --git a/hive-c0re/src/job_queue/resource.rs b/hive-c0re/src/job_queue/resource.rs index 433b29924..1c103e741 100644 --- a/hive-c0re/src/job_queue/resource.rs +++ b/hive-c0re/src/job_queue/resource.rs @@ -31,8 +31,10 @@ pub enum Resource { /// overlapping `reset` / `clean` / `pull` passes there fail on /// `.git/index.lock` and the remote-tracking ref lock. KnowledgeTree, - /// The hive's sender-token file, held by every `MatrixSweep`. Two - /// overlapping passes would race on writing it. + /// The hive's matrix provisioning, held by every `MatrixSweep`. Two + /// overlapping passes on a hive with no persisted Space / chat-room id both + /// miss the by-name lookup and both `createRoom`, leaving a duplicate room + /// with agents invited to both. MatrixSweep, } diff --git a/hive-c0re/src/job_queue/templates.rs b/hive-c0re/src/job_queue/templates.rs index 7afb42468..681b1422a 100644 --- a/hive-c0re/src/job_queue/templates.rs +++ b/hive-c0re/src/job_queue/templates.rs @@ -370,7 +370,7 @@ pub fn destroy(builder: &JobBuilder, agent: &str, purge: bool) { // `Reconcile` root per drifted agent) — no anchor node and no per-agent child // DAGs. -/// One matrix sender-token sweep. Holding [`Resource::MatrixSweep`] is what keeps +/// One matrix user/space sweep. Holding [`Resource::MatrixSweep`] is what keeps /// two passes from overlapping, whichever caller submitted each. pub fn matrix_sweep(builder: &JobBuilder) -> Handle<'_> { builder diff --git a/hive-c0re/src/main.rs b/hive-c0re/src/main.rs index d7c8c6275..13f037ae8 100644 --- a/hive-c0re/src/main.rs +++ b/hive-c0re/src/main.rs @@ -307,9 +307,9 @@ async fn cmd_serve( } } }); - // Matrix sweep (`matrix::ensure_all`): the hive's own sender token, kept - // on disk for `hivectl matrix invite`. It - // creates no accounts or tokens — swarm-controller mints those. + // Matrix sweep (`matrix::ensure_all`): the hive's own account, the hive + // Space and chat room, and every agent container's invite to both. It + // creates no agent accounts or tokens — swarm-controller mints those. // No-op when the hive-matrix container isn't running. Re-submitted every // 30 minutes; the startup pass is the boot `MatrixSweep` node. let mut matrix_shutdown = coord.shutdown_rx(); diff --git a/hive-c0re/src/matrix.rs b/hive-c0re/src/matrix.rs index d92a98aac..70b95a96f 100644 --- a/hive-c0re/src/matrix.rs +++ b/hive-c0re/src/matrix.rs @@ -1,7 +1,8 @@ //! Optional matrix-tuwunel wiring: the hive's `@hive-:` sender token, -//! taken from the swarm secret store and kept on disk for `hivectl matrix -//! invite`. No-op when no homeserver is configured, so operators who haven't -//! flipped `services.hyperhive.deploy.matrix.enable = true` pay nothing. +//! taken from the swarm secret store, and the hive Space, chat room and +//! invites provisioned with it. No-op when no homeserver is configured, so +//! operators who haven't flipped `services.hyperhive.deploy.matrix.enable = +//! true` pay nothing. //! //! This module creates no accounts: `swarm-controller` mints every hive's //! sender account and every agent's account with the swarm's appservice token. @@ -45,6 +46,56 @@ fn matrix_base() -> Result<&'static str> { ) } +/// Matrix localpart this hive acts as. Not an agent; has no state dir. +/// +/// **Per hive, derived from the hive's name** — `hive-`, built by +/// `swarm_secret_client::matrix::hive_localpart`, which is the one place the +/// derivation lives. It used to be the bare constant `hive`, and a swarm runs +/// one homeserver: every hive on it logged in as the same `@hive:`, so the +/// homeserver could not attribute an action to a hive and revoking one hive's +/// standing revoked all of them. +/// +/// `swarm-controller` creates this account with the swarm's appservice token +/// (`matrix_account::hive_sender`) and stores its token where +/// [`stored_sender_token`] reads it; hive-c0re never creates it. +/// +/// An ordinary account, with no homeserver-admin standing: what it +/// provisions — the Space, the chat room, the invites — it provisions as +/// the creator of those rooms. +/// +/// # Errors +/// When `HYPERHIVE_HIVE_NAME` is unset or empty. That is the same variable +/// [`stored_sender_token`] logs in with and the swarm meta flake asserts +/// for every hive, so its absence is a broken deployment rather than a +/// supported one — and there is no safe default to fall back to: the only one +/// available is the shared account this replaced. +pub fn hive_localpart() -> Result { + let hive = std::env::var("HYPERHIVE_HIVE_NAME") + .ok() + .filter(|h| !h.is_empty()) + .context( + "matrix: HYPERHIVE_HIVE_NAME is unset, so this hive has no matrix account of its own \ + — the localpart is derived from the hive name and has no swarm-wide fallback", + )?; + Ok(swarm_secret_client::matrix::hive_localpart(&hive)) +} + +/// Display name of the hive Space. Plain text, no special characters, so +/// the Space stays rediscoverable by name (no room alias needed) even when +/// the persisted room-id file is lost — preventing duplicate spaces from +/// being created on the next sweep. +pub const HIVE_SPACE_NAME: &str = "hive"; + +/// Display name of the default "hive chat" room — the `m.space.child` of +/// the hive Space that every agent + the operator can join. Plain text so +/// it stays rediscoverable by name (mirrors [`HIVE_SPACE_NAME`]) when the +/// persisted room-id file is lost, preventing duplicate chat rooms. +pub const HIVE_CHAT_ROOM_NAME: &str = "hive-chat"; + +/// Topic for the default hive chat room. +const HIVE_CHAT_ROOM_TOPIC: &str = + "Hive-wide chat for all agents and the operator. Auto-provisioned by hive-c0re."; + /// Host path for the appservice sender account's matrix access token. Outside every /// purgeable path — not deleted by `destroy --purge` on any agent. #[must_use] @@ -52,6 +103,20 @@ pub fn sender_token_path() -> PathBuf { crate::paths::matrix_sender_token() } +/// Host path where the hive Matrix Space room ID is persisted. +/// Outside every purgeable path — not deleted by `destroy --purge`. +#[must_use] +pub fn hive_space_room_id_path() -> PathBuf { + crate::paths::matrix_space_room_id() +} + +/// Host path where the default hive chat room ID is persisted. Outside +/// every purgeable path — not deleted by `destroy --purge`. +#[must_use] +pub fn hive_chat_room_id_path() -> PathBuf { + crate::paths::matrix_chat_room_id() +} + /// Whether this hive has a homeserver to provision against. /// /// **A configured API URL, not a local container**: whether the homeserver @@ -226,6 +291,363 @@ pub fn read_sender_token() -> Result { }) } +/// Persist the hive Space room id to [`hive_space_room_id_path()`] (0600). +fn persist_space_room_id(room_id: &str) -> Result<()> { + let path = hive_space_room_id_path(); + crate::secret_file::write_secret_0600(&path, format!("{room_id}\n").as_bytes()) + .with_context(|| format!("matrix: write space room_id to {}", path.display())) +} + +/// Walk the admin account's joined rooms at `base` and return the first room +/// named `name` that is an `m.space` exactly when `want_space` is set (the +/// `m.room.create` `type`). `None` if the homeserver is unreachable or no +/// room matches. +async fn find_joined_room( + client: &reqwest::Client, + base: &str, + sender_token: &str, + want_space: bool, + name: &str, +) -> Option { + let rooms = swarm_matrix_client::joined_rooms(client, base, sender_token) + .await + .ok()?; + for room_id in rooms { + // m.room.create `type` says whether this is a Space. + let is_space = keyless_state(client, base, sender_token, &room_id, "m.room.create") + .await + .is_some_and(|c| c["type"].as_str() == Some("m.space")); + if is_space != want_space { + continue; + } + // …and named `name` (m.room.name `name`). + let name_matches = keyless_state(client, base, sender_token, &room_id, "m.room.name") + .await + .is_some_and(|n| n["name"].as_str() == Some(name)); + if name_matches { + return Some(room_id); + } + } + None +} + +/// The content of a state event with an empty state key, or `None` when the +/// room has none or the read failed. +async fn keyless_state( + client: &reqwest::Client, + base: &str, + sender_token: &str, + room_id: &str, + event_type: &str, +) -> Option { + swarm_matrix_client::room_state(client, base, sender_token, room_id, event_type, "") + .await + .ok() + .flatten() +} + +/// Scan the admin account's joined rooms for the canonical hive Space: the +/// `m.space` whose name is [`HIVE_SPACE_NAME`]. Returns the first match +/// (deterministic per the homeserver's joined-rooms order) so a lost +/// room-id file recovers the existing space instead of spawning a +/// duplicate. `None` if the homeserver is unreachable or no match exists. +/// +/// Name-based (not alias-based) rediscovery keeps the Space free of any +/// special-char room alias — the hardcoded plain name is the anchor. +async fn find_space_by_name(client: &reqwest::Client, sender_token: &str) -> Option { + find_joined_room(client, matrix_http()?, sender_token, true, HIVE_SPACE_NAME).await +} + +/// Create (or recover) the hive Matrix Space and persist its room ID to +/// [`hive_space_room_id_path()`]. The Space is a private `m.space` owned by +/// `@hive-:`, identified by its hardcoded name [`HIVE_SPACE_NAME`] (no alias). +/// +/// Dedup strategy (single canonical space): +/// 1. If the room-id file exists, reuse it. +/// 2. Otherwise, rediscover by scanning the admin's joined rooms for the +/// `m.space` named [`HIVE_SPACE_NAME`] and adopt it (re-persisting the +/// file). This recovers the existing space after a state wipe instead +/// of creating a duplicate. +/// 3. Only if neither yields a room do we `createRoom`. +/// +/// # Errors +/// +/// Returns an error if the homeserver is unreachable, `createRoom` fails, +/// or the room-ID file cannot be written. +pub async fn ensure_hive_space(client: &reqwest::Client, sender_token: &str) -> Result { + let base = matrix_base()?; + // 1. Stored room id wins (fast path). + if let Ok(existing) = std::fs::read_to_string(hive_space_room_id_path()) { + let trimmed = existing.trim().to_owned(); + if !trimmed.is_empty() { + tracing::debug!(room_id = %trimmed, "matrix: hive space already provisioned"); + return Ok(trimmed); + } + } + + // 2. No stored id — rediscover the existing space by its hardcoded name + // before creating a new one (prevents duplicate spaces after a wipe). + if let Some(room_id) = find_space_by_name(client, sender_token).await { + persist_space_room_id(&room_id)?; + tracing::info!(%room_id, "matrix: recovered hive space by name"); + return Ok(room_id); + } + + // 3. Create the space (plain hardcoded name, no alias). + let body = serde_json::json!({ + "name": HIVE_SPACE_NAME, + "creation_content": { "type": "m.space" }, + "preset": "private_chat", + "visibility": "private", + }); + let room_id = swarm_matrix_client::create_room(client, base, sender_token, &body) + .await + .context("matrix: create hive space")?; + persist_space_room_id(&room_id)?; + tracing::info!(%room_id, "matrix: created hive space"); + Ok(room_id) +} + +/// Persist the hive chat room id to [`hive_chat_room_id_path()`] (0600). +fn persist_chat_room_id(room_id: &str) -> Result<()> { + let path = hive_chat_room_id_path(); + crate::secret_file::write_secret_0600(&path, format!("{room_id}\n").as_bytes()) + .with_context(|| format!("matrix: write chat room_id to {}", path.display())) +} + +/// Scan the admin account's joined rooms for the canonical hive chat room: +/// a non-space room named [`HIVE_CHAT_ROOM_NAME`]. Mirrors +/// [`find_space_by_name`] so a lost room-id file recovers the existing chat +/// room instead of spawning a duplicate. `None` if the homeserver is +/// unreachable or no match exists. +async fn find_chat_room_by_name(client: &reqwest::Client, sender_token: &str) -> Option { + find_joined_room( + client, + matrix_http()?, + sender_token, + false, + HIVE_CHAT_ROOM_NAME, + ) + .await +} + +/// Whether the state event still has to be written. +/// +/// `current` is the room's existing content for this `(type, state_key)`, +/// or `None` when it could not be read. **Unreadable means write**: the +/// re-apply exists so a missing link gets repaired, and one redundant +/// event is cheaper than a hierarchy that never reconverges. +/// +/// Comparison is `serde_json::Value` equality, which compares objects as +/// maps — key order in the response does not matter. +fn state_needs_write(current: Option<&serde_json::Value>, desired: &serde_json::Value) -> bool { + current != Some(desired) +} + +/// Read the room's current content for one state event. `None` on any +/// failure — absent state, transport error, a refusal, or an unparseable body +/// are all "we don't know", and [`state_needs_write`] turns that into a write. +/// +/// A failure other than absent state is logged at `warn`: **a read that breaks +/// while the write still works** makes the guard degrade to writing every +/// time, and the sweep resumes waking the hive with nothing else to show for +/// it. An absent state event (404) is the expected first-setup case. +async fn current_room_state( + client: &reqwest::Client, + base: &str, + sender_token: &str, + room_id: &str, + event_type: &str, + state_key: &str, +) -> Option { + match swarm_matrix_client::room_state( + client, + base, + sender_token, + room_id, + event_type, + state_key, + ) + .await + { + Ok(content) => content, + Err(e) => { + tracing::warn!( + error = %format!("{e:#}"), + %room_id, + event_type, + "matrix: state read failed while writes still work — the \ + skip-if-unchanged guard is off and every sweep will re-emit" + ); + None + } + } +} + +/// PUT a state event into `room_id` using the sender token, **skipping the +/// write when the room already carries identical content**. +/// +/// The read is not an optimisation. A PUT of identical content is a no-op +/// on the room's *state*, and the homeserver still appends an event to the +/// *timeline* — so "idempotent" was true one level too high. Downstream, +/// an event is unread activity, which is a todo, which is a turn: a caller +/// re-applying a link on a periodic sweep wakes every agent in the room on +/// that sweep's cadence, forever. Measured at ~30 minutes per wake per +/// agent before this guard existed. +/// +/// The self-healing property the re-apply exists for is unaffected: a +/// missing or divergent link still gets written. +async fn set_room_state( + client: &reqwest::Client, + sender_token: &str, + room_id: &str, + event_type: &str, + state_key: &str, + content: &serde_json::Value, +) -> Result<()> { + let base = matrix_base()?; + let current = + current_room_state(client, base, sender_token, room_id, event_type, state_key).await; + if !state_needs_write(current.as_ref(), content) { + tracing::debug!( + %room_id, + event_type, + "matrix: state already current, skipping PUT (no timeline event)" + ); + return Ok(()); + } + swarm_matrix_client::put_state( + client, + base, + sender_token, + room_id, + event_type, + state_key, + content, + ) + .await + .context("matrix: set room state") +} + +/// Create (or recover) the default hive chat room and wire it as a child of +/// the hive Space, persisting its room id to [`hive_chat_room_id_path()`]. +/// +/// The room is a normal room (not an `m.space`) named [`HIVE_CHAT_ROOM_NAME`] +/// with a `restricted` join rule allowing any member of the hive Space to +/// join — so the operator (who is in the Space) and every agent can chat +/// without needing an explicit invite. It's linked bidirectionally to the +/// Space: `m.space.child` on the Space points at the room, `m.space.parent` +/// on the room points back. Joining a Space does NOT auto-join its children +/// (Matrix semantics), so this gives clients a concrete room to surface + +/// join instead of an empty Space. +/// +/// Dedup mirrors [`ensure_hive_space`]: persisted id wins, else rediscover +/// by name, else create. The space-child link is re-checked on every call +/// so a recovered room reconverges its hierarchy link — and written only +/// when it differs, see [`set_room_state`]. +/// +/// # Errors +/// +/// Returns an error if the homeserver is unreachable, `createRoom` fails, +/// or the room-ID file cannot be written. A failure wiring the space-child +/// link is logged but not fatal (the room still exists + is joinable). +pub async fn ensure_hive_chat_room( + client: &reqwest::Client, + sender_token: &str, + space_room_id: &str, + server_name: &str, +) -> Result { + let base = matrix_base()?; + // 1. Stored room id wins (fast path). 2. Rediscover by name before + // creating (prevents duplicates after a state wipe). 3. Create. + let room_id = if let Some(id) = std::fs::read_to_string(hive_chat_room_id_path()) + .ok() + .map(|s| s.trim().to_owned()) + .filter(|s| !s.is_empty()) + { + tracing::debug!(room_id = %id, "matrix: hive chat room already provisioned"); + id + } else if let Some(id) = find_chat_room_by_name(client, sender_token).await { + persist_chat_room_id(&id)?; + tracing::info!(room_id = %id, "matrix: recovered hive chat room by name"); + id + } else { + // `initial_state` is applied after the preset-derived state, so the + // restricted join rule overrides private_chat's invite-only default. + let body = serde_json::json!({ + "name": HIVE_CHAT_ROOM_NAME, + "topic": HIVE_CHAT_ROOM_TOPIC, + // Pin the room version explicitly: the `restricted` join rule + // below needs room version >= 8. tuwunel's default is currently + // higher, but pinning makes the dependency explicit so a future + // homeserver-default change can't silently invalidate the + // restricted rule (which would quietly fall back to invite-only + // and break the "operator joins from the Space" path). + "room_version": "10", + "preset": "private_chat", + "visibility": "private", + "initial_state": [ + { + "type": "m.room.join_rules", + "state_key": "", + "content": { + "join_rule": "restricted", + "allow": [ + { "type": "m.room_membership", "room_id": space_room_id } + ] + } + }, + { + "type": "m.space.parent", + "state_key": space_room_id, + "content": { "via": [server_name], "canonical": true } + } + ] + }); + let id = swarm_matrix_client::create_room(client, base, sender_token, &body) + .await + .context("matrix: create hive chat room")?; + persist_chat_room_id(&id)?; + tracing::info!(room_id = %id, "matrix: created hive chat room"); + id + }; + + // Wire the Space → room child link. Without an `m.space.child` carrying + // a `via`, the room won't surface in the Space hierarchy. `suggested` + // hints clients to surface it prominently. + let child_content = serde_json::json!({ + "via": [server_name], + "suggested": true, + }); + if let Err(e) = set_room_state( + client, + sender_token, + space_room_id, + "m.space.child", + &room_id, + &child_content, + ) + .await + { + tracing::warn!(error = ?e, "matrix: set m.space.child on hive space failed"); + } + + Ok(room_id) +} + +/// Invite `@{localpart}:{server_name}` to `room_id` using the admin +/// account. Idempotent — treats already-member responses as success. +async fn invite_to_room( + client: &reqwest::Client, + sender_token: &str, + room_id: &str, + localpart: &str, + server_name: &str, +) -> Result<()> { + let user_id = format!("@{localpart}:{server_name}"); + invite_user_id(client, sender_token, room_id, &user_id).await +} + /// Fetch a user's current membership in a room via the sender token, or /// `None` if there is no membership event (never invited) or the lookup /// fails. Returns the raw membership string (`invite`, `join`, `leave`, …). @@ -306,21 +728,23 @@ fn forbidden_invite(membership: Option<&str>, user_id: &str, room_id: &str) -> R ) } -/// Invite an arbitrary Matrix user to `room` (a room id or alias). `user` -/// may be a fully-qualified id (`@name:server`) or a bare localpart, which -/// is qualified with the homeserver's `server_name`. Returns the resolved -/// room id the invite targeted. Used by `hivectl matrix invite`. +/// Invite an arbitrary Matrix user to the hive Space (default) or an +/// explicit `room_id` / alias. `user` may be a fully-qualified id +/// (`@name:server`) or a bare localpart, which is qualified with the +/// homeserver's `server_name`. Returns the resolved room id the invite +/// targeted. Used by `hivectl matrix invite`. /// /// # Errors /// -/// Returns an error if `room` is neither a room id nor an alias, or the -/// invite POST fails for a reason other than the user already being a -/// member / invited. +/// Returns an error if the sender token or `server_name` can't be read, +/// the target room can't be resolved (no `--room` and no persisted hive +/// space), or the invite POST fails for a reason other than the user +/// already being a member / invited. pub async fn invite_user( client: &reqwest::Client, sender_token: &str, user: &str, - room: &str, + room_override: Option<&str>, server_name: &str, ) -> Result { // Qualify a bare localpart to a full user id on the hive homeserver. @@ -329,29 +753,39 @@ pub async fn invite_user( } else { format!("@{user}:{server_name}") }; - let room_id = if room.starts_with('#') { - swarm_matrix_client::resolve_alias(client, matrix_base()?, sender_token, room).await? - } else if room.starts_with('!') { - room.to_owned() - } else { - anyhow::bail!( - "matrix: --room {room:?} is neither a room id nor an alias; \ + // Resolve the room: explicit override (id or #alias) wins; otherwise + // the persisted hive Space. + let room_id = match room_override { + Some(r) if r.starts_with('#') => { + swarm_matrix_client::resolve_alias(client, matrix_base()?, sender_token, r).await? + } + Some(r) if r.starts_with('!') => r.to_owned(), + Some(r) => anyhow::bail!( + "matrix: --room {r:?} is neither a room id nor an alias; \ prefix with '!' for a room id (!abc:server) or '#' for an \ alias (#name:server)" - ) + ), + None => std::fs::read_to_string(hive_space_room_id_path()) + .map(|s| s.trim().to_owned()) + .context( + "matrix: no --room given and no persisted hive space \ + (run the hive-c0re matrix sweep first)", + )?, }; invite_user_id(client, sender_token, &room_id, &user_id).await?; Ok(room_id) } -/// Make sure the hive's own `@hive-:` sender token is on disk. -/// Accounts are not created here: `swarm-controller` mints them with the -/// swarm's appservice token. Runs only as a `MatrixSweep` job node (see -/// `job_queue::templates::matrix_sweep`). No-op when no homeserver is -/// configured. +/// Make sure the hive's own `@hive-:` account exists, then provision +/// the hive Space and chat room and invite every agent container to both. +/// Agents' own accounts are not created here: `swarm-controller` mints them +/// with the swarm's appservice token. Runs only as a `MatrixSweep` job node +/// (see `job_queue::templates::matrix_sweep`). No-op when the +/// hive-matrix container isn't running. Per-step failures are logged +/// but don't abort the sweep. /// -/// Returns `true` when the token is in place, `false` when it could not be -/// fetched — the caller feeds this into a +/// Returns `true` when every step of the sweep succeeded, `false` when at +/// least one step failed — the caller feeds this into a /// [`crate::stats::sweep_health::SweepHealth`] to raise a debounced /// hive warning on persistent failure (this sweep re-runs every 30 /// minutes, so a one-off blip self-heals without ever warning). @@ -360,11 +794,125 @@ pub async fn ensure_all() -> bool { tracing::debug!("matrix: hive-matrix container absent, skipping user sweep"); return true; } + let mut ok = true; + // One HTTP client for the whole sweep. + let client = match swarm_matrix_client::client() { + Ok(c) => c, + Err(e) => { + tracing::warn!(error = ?e, "matrix: build HTTP client failed; skipping sweep"); + return false; + } + }; + // The hive's `@hive-:` account first, because everything below provisions + // THROUGH it (the Space, the chat room and every invite are sent with + // its token) — as an ordinary user that created those rooms, not as a + // homeserver admin. if let Err(e) = ensure_hive_user().await { tracing::warn!(error = ?e, "matrix: ensure_hive_user failed"); - return false; + ok = false; } - true + let Ok(containers) = crate::lifecycle::list().await else { + tracing::warn!("matrix: nixos-container list failed; skipping user sweep"); + return false; + }; + let mut agent_names: Vec = Vec::new(); + for c in &containers { + let Some(name) = c.strip_prefix(crate::lifecycle::AGENT_PREFIX) else { + continue; + }; + agent_names.push(name.to_owned()); + } + + if !provision_space(&client, &agent_names).await { + ok = false; + } + ok +} + +/// Provision the hive Space + default chat room and invite every agent +/// (+ the admin account) to both. Split out of [`ensure_all`] purely to +/// keep that function under the `too_many_lines` threshold — this is the +/// tail half of the same sequential sweep and shares its aggregate-bool, +/// log-and-continue failure handling. +async fn provision_space(client: &reqwest::Client, agent_names: &[String]) -> bool { + let mut ok = true; + // server_name is needed to form full Matrix user IDs for invites. + let sender_token = match read_sender_token() { + Ok(t) => t, + Err(e) => { + tracing::warn!(error = ?e, "matrix: skipping hive space provisioning (no matrix sender token)"); + return false; + } + }; + // server_name first — the agent invites need it (fully-qualified user ids). + let server_name = match discover_server_name(client).await { + Ok(s) => s, + Err(e) => { + tracing::warn!(error = ?e, "matrix: discover_server_name failed; skipping space provisioning"); + return false; + } + }; + let room_id = match ensure_hive_space(client, &sender_token).await { + Ok(id) => id, + Err(e) => { + tracing::warn!(error = ?e, "matrix: ensure_hive_space failed"); + return false; + } + }; + // This hive's own account first, then all agents. + let localpart = match hive_localpart() { + Ok(l) => l, + Err(e) => { + tracing::warn!(error = ?e, "matrix: skipping hive space provisioning"); + return false; + } + }; + if let Err(e) = invite_to_room(client, &sender_token, &room_id, &localpart, &server_name).await + { + tracing::warn!(error = ?e, %localpart, "matrix: invite the hive account to the space failed"); + ok = false; + } + for name in agent_names { + if let Err(e) = invite_to_room(client, &sender_token, &room_id, name, &server_name).await { + tracing::warn!(%name, error = ?e, "matrix: invite agent to space failed"); + ok = false; + } + } + + // Provision the default hive chat room as an m.space.child of the Space + // and invite `@hive-:` + every agent. Joining a Space alone surfaces no + // rooms to chat in (Matrix semantics — children aren't auto-joined), so + // without this the Space is empty. The restricted join rule additionally + // lets the operator (a Space member) join from the Space hierarchy. + match ensure_hive_chat_room(client, &sender_token, &room_id, &server_name).await { + Ok(chat_room_id) => { + if let Err(e) = invite_to_room( + client, + &sender_token, + &chat_room_id, + &localpart, + &server_name, + ) + .await + { + tracing::warn!(error = ?e, %localpart, "matrix: invite the hive account to the chat room failed"); + ok = false; + } + for name in agent_names { + if let Err(e) = + invite_to_room(client, &sender_token, &chat_room_id, name, &server_name).await + { + tracing::warn!(%name, error = ?e, "matrix: invite agent to chat room failed"); + ok = false; + } + } + } + Err(e) => { + tracing::warn!(error = ?e, "matrix: ensure_hive_chat_room failed"); + ok = false; + } + } + ok } #[cfg(test)] @@ -408,6 +956,43 @@ mod tests { assert_eq!(sender_source(None, None), SenderSource::Unavailable); } + /// The steady state. This is the whole point of the guard: the sweep + /// runs forever, and every write it makes is a wake for every agent + /// in the room. + #[test] + fn state_matching_the_room_is_not_rewritten() { + let desired = serde_json::json!({ "via": ["example.org"], "suggested": true }); + let current = desired.clone(); + assert!(!state_needs_write(Some(¤t), &desired)); + } + + /// Key order in the homeserver's response must not force a write — + /// the guard leans on `serde_json::Value` comparing objects as maps, + /// and a byte- or order-sensitive comparison would silently degrade + /// to writing every time while still looking correct. + #[test] + fn state_matching_but_reordered_is_not_rewritten() { + let desired = serde_json::json!({ "via": ["example.org"], "suggested": true }); + let current = serde_json::json!({ "suggested": true, "via": ["example.org"] }); + assert!(!state_needs_write(Some(¤t), &desired)); + } + + #[test] + fn diverged_state_is_rewritten() { + let desired = serde_json::json!({ "via": ["example.org"], "suggested": true }); + let current = serde_json::json!({ "via": ["old.example.org"], "suggested": true }); + assert!(state_needs_write(Some(¤t), &desired)); + } + + /// Fail-open, and deliberately so: an unreadable current state must + /// write. The re-apply exists to repair a missing link, so "we don't + /// know" has to behave like "it's missing", not like "it's fine". + #[test] + fn unknown_state_is_written() { + let desired = serde_json::json!({ "via": ["example.org"], "suggested": true }); + assert!(state_needs_write(None, &desired)); + } + /// A banned target or a sender without power gets a 403; with no /// membership behind it, the invite did not happen. #[test] @@ -461,26 +1046,52 @@ mod tests { } } - /// A room that is neither an id nor an alias is refused before any - /// request is made; with no default Space left, there is nothing to fall - /// back to. - #[tokio::test] - async fn invite_user_refuses_a_room_that_is_neither_an_id_nor_an_alias() { - let client = swarm_matrix_client::client().expect("client"); - let err = invite_user(&client, "tok", "mara", "general", "example.org") + /// Serve a fake homeserver on loopback: `!space` is an `m.space` and + /// `!chat` a plain room, both named "shared"; `!decoy` is a plain room + /// named "other". Returns the base URL and the server task. + async fn fake_homeserver() -> (String, tokio::task::JoinHandle<()>) { + let app = axum::Router::new().fallback(|uri: axum::http::Uri| async move { + let path = uri.path(); + let body = if path.ends_with("/joined_rooms") { + serde_json::json!({"joined_rooms": ["!decoy", "!space", "!chat"]}) + } else if path.ends_with("/m.room.create/") { + if path.contains("space") { + serde_json::json!({"type": "m.space"}) + } else { + serde_json::json!({}) + } + } else if path.ends_with("/m.room.name/") { + let name = if path.contains("decoy") { + "other" + } else { + "shared" + }; + serde_json::json!({"name": name}) + } else { + serde_json::json!({}) + }; + axum::Json(body) + }); + let listener = tokio::net::TcpListener::bind("127.0.0.1:0") .await - .expect_err("a bare name is not a room"); - assert!( - format!("{err:#}").contains("neither a room id nor an alias"), - "{err:#}" - ); + .expect("bind"); + let base = format!("http://{}", listener.local_addr().expect("local addr")); + let server = tokio::spawn(async move { + axum::serve(listener, app).await.expect("serve"); + }); + (base, server) } - /// The sweep touches nothing, and reports success, on a hive with no - /// homeserver configured (the test environment has none). #[tokio::test] - async fn the_sweep_is_a_successful_no_op_without_a_homeserver() { - assert!(!is_present()); - assert!(ensure_all().await); + async fn find_joined_room_matches_a_space_only_when_a_space_is_wanted() { + let (base, server) = fake_homeserver().await; + let client = reqwest::Client::new(); + let want_space = find_joined_room(&client, &base, "tok", true, "shared").await; + let want_chat = find_joined_room(&client, &base, "tok", false, "shared").await; + let no_name = find_joined_room(&client, &base, "tok", true, "absent").await; + server.abort(); + assert_eq!(want_space.as_deref(), Some("!space")); + assert_eq!(want_chat.as_deref(), Some("!chat")); + assert_eq!(no_name, None); } } diff --git a/hive-c0re/src/paths.rs b/hive-c0re/src/paths.rs index 52bcd89a3..bcc5b1400 100644 --- a/hive-c0re/src/paths.rs +++ b/hive-c0re/src/paths.rs @@ -104,6 +104,19 @@ pub fn matrix_sender_token() -> PathBuf { matrix_dir().join("access-token") } +/// `matrix/space-room-id` — persisted hive Space room id. +#[must_use] +pub fn matrix_space_room_id() -> PathBuf { + matrix_dir().join("space-room-id") +} + +/// `matrix/chat-room-id` — persisted default "hive chat" room id (the +/// `m.space.child` of the hive Space every agent + the operator can join). +#[must_use] +pub fn matrix_chat_room_id() -> PathBuf { + matrix_dir().join("chat-room-id") +} + /// `run/` — runtime maps hive-c0re regenerates on every meta sync. #[must_use] pub fn run_dir() -> PathBuf { @@ -252,10 +265,11 @@ pub fn agent_runtime_dir(name: &str) -> PathBuf { /// within the same filesystem is atomic. pub fn relocate_legacy_state() { let root = state_root(); - let moves: [(&str, PathBuf); 4] = [ + let moves: [(&str, PathBuf); 5] = [ ("broker.sqlite", db_dir().join("broker.sqlite")), ("build_logs.sqlite", db_dir().join("build_logs.sqlite")), ("matrix-sender-token", matrix_sender_token()), + ("matrix-space-room-id", matrix_space_room_id()), ("agent-sockets.json", agent_sockets_file()), ]; for (old_rel, new) in &moves { diff --git a/hive-c0re/src/server.rs b/hive-c0re/src/server.rs index 34cd6af72..db3065297 100644 --- a/hive-c0re/src/server.rs +++ b/hive-c0re/src/server.rs @@ -203,7 +203,9 @@ async fn dispatch(req: &HostRequest, coord: Arc) -> HostResponse { // federation peer-config block) and open the web surfaces // (`hivectl open`). HostRequest::Urls => HostResponse::urls(hive_urls()), - HostRequest::MatrixInvite { user, room } => handle_matrix_invite(user, room).await?, + HostRequest::MatrixInvite { user, room } => { + handle_matrix_invite(user, room.as_deref()).await? + } HostRequest::ReconcileConfigStatus { agent, verbose } => { crate::forge::reconcile_config_status(agent.as_str(), *verbose).await? } @@ -498,7 +500,7 @@ async fn handle_push_snapshot( Ok(HostResponse::success()) } -async fn handle_matrix_invite(user: &str, room: &str) -> Result { +async fn handle_matrix_invite(user: &str, room: Option<&str>) -> Result { require_matrix_present()?; let sender_token = crate::matrix::read_sender_token()?; let client = matrix_http_client()?; diff --git a/hive-host-sock/src/lib.rs b/hive-host-sock/src/lib.rs index 374c6caa0..4d5af3f3f 100644 --- a/hive-host-sock/src/lib.rs +++ b/hive-host-sock/src/lib.rs @@ -223,9 +223,14 @@ pub enum HostRequest { #[serde(default)] scope: LifecycleScope, }, - /// Invite a matrix user to `room` (id or alias). Uses the daemon's - /// admin token; idempotent (already-member / already-invited is a no-op). - MatrixInvite { user: String, room: String }, + /// Invite a matrix user to the hive Space (default) or a specific + /// `room`. Uses the daemon's admin token; idempotent + /// (already-member / already-invited is a no-op). + MatrixInvite { + user: String, + #[serde(default)] + room: Option, + }, /// Report the divergence between agent `agent`'s local applied config /// checkout and its forge `agent-configs/` `main`. The daemon /// fetches forge `main` read-only and returns a human-readable report diff --git a/hivectl/README.md b/hivectl/README.md index ef9c944ef..7fdec9f42 100644 --- a/hivectl/README.md +++ b/hivectl/README.md @@ -27,7 +27,7 @@ dispatch: container. - **`forge.rs`** — reconciles an agent's config against its forge repo. -- **`matrix.rs`** — invite a matrix user to a room. +- **`matrix.rs`** — invite a matrix user to the hive Space or a room. - **`wg.rs`** — WireGuard mesh helpers. - **`subvol.rs`** — btrfs state-subvolume ops. - **`quota.rs`**, **`util.rs`**, **`completions.rs`**, **`open.rs`** — diff --git a/hivectl/src/cli.rs b/hivectl/src/cli.rs index cbb75fbcb..c8b62c681 100644 --- a/hivectl/src/cli.rs +++ b/hivectl/src/cli.rs @@ -38,7 +38,9 @@ pub enum Cmd { }, /// matrix-tuwunel invites. /// - /// Manual invites into a room by id or alias. + /// Manual invites into the hive Space and its rooms; c0re's periodic + /// matrix sweep provisions the Space, the chat room and the agents' + /// invites on its own. Matrix { #[command(subcommand)] cmd: MatrixCmd, @@ -248,14 +250,16 @@ impl From for hive_host_sock::ReconcileDirection { #[derive(Subcommand)] pub enum MatrixCmd { - /// Invite a matrix user to a room. Idempotent. + /// Invite a matrix user to the hive Space, or a specific room with + /// `--room`. Idempotent. Invite { /// User to invite: a full id (`@mara:server`) or a bare /// localpart (qualified with the homeserver's `server_name`). user: String, /// Target room id (`!abc:server`) or alias (`#name:server`). + /// Omit to invite to the hive Space. #[arg(long)] - room: String, + room: Option, }, } diff --git a/hivectl/src/matrix.rs b/hivectl/src/matrix.rs index ee77f9e05..4fd27a238 100644 --- a/hivectl/src/matrix.rs +++ b/hivectl/src/matrix.rs @@ -12,7 +12,7 @@ use crate::cli::MatrixCmd; /// dispatch match so the top-level router stays small. pub(crate) async fn run_matrix_cmd(socket: &Path, cmd: MatrixCmd) -> Result<()> { match cmd { - MatrixCmd::Invite { user, room } => matrix_invite(socket, &user, &room).await, + MatrixCmd::Invite { user, room } => matrix_invite(socket, &user, room.as_deref()).await, } } @@ -36,12 +36,12 @@ async fn matrix_request(socket: &Path, req: hive_host_sock::HostRequest) -> Resu Ok(()) } -async fn matrix_invite(socket: &Path, user: &str, room: &str) -> Result<()> { +async fn matrix_invite(socket: &Path, user: &str, room: Option<&str>) -> Result<()> { matrix_request( socket, hive_host_sock::HostRequest::MatrixInvite { user: user.to_owned(), - room: room.to_owned(), + room: room.map(str::to_owned), }, ) .await diff --git a/nix/host-modules/hive-c0re/environment.nix b/nix/host-modules/hive-c0re/environment.nix index e89d5c80a..867245ef7 100644 --- a/nix/host-modules/hive-c0re/environment.nix +++ b/nix/host-modules/hive-c0re/environment.nix @@ -170,7 +170,7 @@ in } // lib.optionalAttrs (config.services.hyperhive.swarm.matrix.apiUrl != null) { # Client-server API base hive-c0re uses to provision matrix (register - # agent users, invite members). + # agent users, create the hive space + chat room, invite members). # Supplied by `services.hyperhive.swarm.matrix.apiUrl`, which defaults to # the same gateway vhost as HIVE_MATRIX_URL above, over https because it # carries the hive's matrix token and may cross the network. Its own diff --git a/nix/host-modules/hive-matrix-service.nix b/nix/host-modules/hive-matrix-service.nix index 5cfa49f16..a23408391 100644 --- a/nix/host-modules/hive-matrix-service.nix +++ b/nix/host-modules/hive-matrix-service.nix @@ -59,7 +59,8 @@ in example = "https://matrix.example.com"; description = '' Client-server API base URL **hive-c0re itself** uses to - provision matrix (register agent users, invite members). Distinct from the agent-facing + provision matrix (register agent users, create the hive space + and chat room, invite members). Distinct from the agent-facing `services.hyperhive.agent.matrix.url`, which is the gateway vhost handed to each agent's `hive-matrix-daemon`. diff --git a/nix/host-modules/hive-matrix.nix b/nix/host-modules/hive-matrix.nix index d691cbbac..c84ac209e 100644 --- a/nix/host-modules/hive-matrix.nix +++ b/nix/host-modules/hive-matrix.nix @@ -913,8 +913,8 @@ in # the swarm appservice's sender. Its token is read by # matrix-ctl and swarm-controller only. Each `@hive-` # stays an ordinary user, because its hive reads its - # credential; what it does (the invites) rides on its - # power in the room, not on admin. + # credential; what it does (the Space, the chat room, the + # invites) rides on being the rooms' creator, not on admin. # # The registration load creates the sender inside # `Services::start()`, and `admin_execute` runs after that and diff --git a/swarm-matrix-client/README.md b/swarm-matrix-client/README.md index 28f919116..cbb97454c 100644 --- a/swarm-matrix-client/README.md +++ b/swarm-matrix-client/README.md @@ -15,8 +15,9 @@ device's token instead of adding a device. the operator names. Neither call is an appservice call, so neither carries the appservice token. -`hive-c0re` invites users into rooms with the room calls (`room_state`, -`invite`, `resolve_alias`), and `hive-matrix-mcp` recovers a session's user and device id +`hive-c0re` provisions the hive Space and chat room with the room calls +(`joined_rooms`, `room_state`, `put_state`, `create_room`, `invite`, +`resolve_alias`), and `hive-matrix-mcp` recovers a session's user and device id with `whoami_session`. Each takes the caller's `reqwest::Client`, so the caller sets its own timeout; `client()` is the 10 second default. diff --git a/swarm-matrix-client/src/lib.rs b/swarm-matrix-client/src/lib.rs index bbcc0b4f0..5a573a0ed 100644 --- a/swarm-matrix-client/src/lib.rs +++ b/swarm-matrix-client/src/lib.rs @@ -1,7 +1,7 @@ //! The calls against a Matrix homeserver's client-server API shared by the //! swarm and the hive: the appservice calls (register, log in, ask a token who //! it is), the room calls `swarm-controller`'s admin-room commands and -//! `hive-c0re`'s invites need (resolve an alias, list +//! `hive-c0re`'s Space and chat-room provisioning need (resolve an alias, list //! members and joined rooms, read and set room state, create a room, invite, send //! a message, check an account exists), and the password login and logout //! `swarm-controller` runs for an operator-linked account on any homeserver.