From c7f3706597a1906fdc3403b55b0d2890133ee55a Mon Sep 17 00:00:00 2001 From: damocles Date: Wed, 28 Oct 2026 20:39:15 +0100 Subject: [PATCH 1/4] stop provisioning the hive-chat room in the matrix sweep --- docs/getting-started/setup.md | 2 +- docs/integrations/matrix.md | 38 +-- docs/tools/hivectl-cli.md | 2 +- docs/tools/hivectl.md | 2 +- hive-c0re/src/job_queue/exec.rs | 3 +- hive-c0re/src/job_queue/resource.rs | 2 +- hive-c0re/src/main.rs | 2 +- hive-c0re/src/matrix.rs | 332 +-------------------- hive-c0re/src/paths.rs | 7 - hivectl/src/cli.rs | 4 +- nix/host-modules/hive-c0re/environment.nix | 2 +- nix/host-modules/hive-matrix-service.nix | 4 +- nix/host-modules/hive-matrix.nix | 4 +- swarm-matrix-client/README.md | 2 +- swarm-matrix-client/src/lib.rs | 2 +- 15 files changed, 37 insertions(+), 371 deletions(-) diff --git a/docs/getting-started/setup.md b/docs/getting-started/setup.md index 9ccdf24d3..c6339f526 100644 --- a/docs/getting-started/setup.md +++ b/docs/getting-started/setup.md @@ -116,7 +116,7 @@ optionally to rooms: ```bash hivectl matrix invite mara -hivectl matrix invite @mara:yourserver --room '#hive-chat:yourserver' +hivectl matrix invite @mara:yourserver --room '#some-room:yourserver' ``` ## 6 · Your first agent diff --git a/docs/integrations/matrix.md b/docs/integrations/matrix.md index 2f60f311d..d54e728d9 100644 --- a/docs/integrations/matrix.md +++ b/docs/integrations/matrix.md @@ -97,7 +97,7 @@ through the gateway; from outside the host that takes `gateway.openFirewall`. hive-c0re provisions matrix (its own sender login, the hive Space and -chat room, invites) through `swarm.matrix.apiUrl`, which defaults to +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 @@ -259,9 +259,8 @@ 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. 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 +Space and inviting agents into it are ordinary client calls that ride on +being the Space's 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. @@ -355,28 +354,19 @@ 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. - -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 the Space's room ID to +`/var/lib/hyperhive/matrix/space-room-id` (mode `0600`, owned by the +hive-c0re service user). The path is **outside** every agent state dir and +**isn't** deleted by `nixos-container destroy --purge`, so it survives full +agent purges, and hive-c0re reuses it on re-provision. -**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 +An earlier version also provisioned a `hive-chat` room and kept its id in +`chat-room-id`. The sweep no longer touches either; an existing room and +file are harmless leftovers that can be removed by hand. -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). +**Idempotent**: if the file exists and is non-empty, hive-c0re considers the +Space already created. Delete the file to force re-creation (for example +after a homeserver wipe). ## Configuration tuning diff --git a/docs/tools/hivectl-cli.md b/docs/tools/hivectl-cli.md index 85a7ec039..eda3044dc 100644 --- a/docs/tools/hivectl-cli.md +++ b/docs/tools/hivectl-cli.md @@ -116,7 +116,7 @@ Always prints the diff first. `--from forge` resets the local checkout to forge matrix-tuwunel invites. -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. +Manual invites into the hive Space and its rooms; c0re's periodic matrix sweep provisions the Space and the agents' invites on its own. **Usage:** `hivectl matrix ` diff --git a/docs/tools/hivectl.md b/docs/tools/hivectl.md index a31057ee0..491bd03ab 100644 --- a/docs/tools/hivectl.md +++ b/docs/tools/hivectl.md @@ -50,7 +50,7 @@ running (`services.hyperhive.deploy.matrix.enable = true`). ```bash 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 +hivectl matrix invite @mara:server --room '#some-room:server' # ...or to a specific room/alias ``` Human matrix accounts come from SSO, not `hivectl`; matrix homeserver diff --git a/hive-c0re/src/job_queue/exec.rs b/hive-c0re/src/job_queue/exec.rs index bb0c9228a..fe4ff0b15 100644 --- a/hive-c0re/src/job_queue/exec.rs +++ b/hive-c0re/src/job_queue/exec.rs @@ -412,8 +412,7 @@ fn matrix_sweep_warning(ctx: sweep_health::SweepFailure) -> String { ); format!( "matrix user/space sweep failing ({} consecutive, {age}) \ - — some agents may be missing matrix accounts, space membership, \ - or chat-room invites", + — some agents may be missing matrix accounts or space membership", ctx.consecutive ) } diff --git a/hive-c0re/src/job_queue/resource.rs b/hive-c0re/src/job_queue/resource.rs index 1c103e741..c2a6b5493 100644 --- a/hive-c0re/src/job_queue/resource.rs +++ b/hive-c0re/src/job_queue/resource.rs @@ -32,7 +32,7 @@ pub enum Resource { /// `.git/index.lock` and the remote-tracking ref lock. KnowledgeTree, /// The hive's matrix provisioning, held by every `MatrixSweep`. Two - /// overlapping passes on a hive with no persisted Space / chat-room id both + /// overlapping passes on a hive with no persisted Space 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/main.rs b/hive-c0re/src/main.rs index 13f037ae8..14c8909fa 100644 --- a/hive-c0re/src/main.rs +++ b/hive-c0re/src/main.rs @@ -308,7 +308,7 @@ async fn cmd_serve( } }); // 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 + // Space, and every agent container's invite to it. 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. diff --git a/hive-c0re/src/matrix.rs b/hive-c0re/src/matrix.rs index 70b95a96f..0e5cc385f 100644 --- a/hive-c0re/src/matrix.rs +++ b/hive-c0re/src/matrix.rs @@ -1,5 +1,5 @@ //! Optional matrix-tuwunel wiring: the hive's `@hive-:` sender token, -//! taken from the swarm secret store, and the hive Space, chat room and +//! taken from the swarm secret store, and the hive Space 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. @@ -60,8 +60,8 @@ fn matrix_base() -> Result<&'static str> { /// [`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. +/// provisions — the Space and the invites — it provisions as the +/// creator of the Space. /// /// # Errors /// When `HYPERHIVE_HIVE_NAME` is unset or empty. That is the same variable @@ -86,16 +86,6 @@ pub fn hive_localpart() -> Result { /// 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] @@ -110,13 +100,6 @@ 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 @@ -408,233 +391,6 @@ pub async fn ensure_hive_space(client: &reqwest::Client, sender_token: &str) -> 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( @@ -777,7 +533,7 @@ pub async fn invite_user( } /// Make sure the hive's own `@hive-:` account exists, then provision -/// the hive Space and chat room and invite every agent container to both. +/// the hive Space and invite every agent container to it. /// 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 @@ -804,9 +560,8 @@ pub async fn ensure_all() -> bool { } }; // 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. + // THROUGH it (the Space and every invite are sent with its token) — as + // an ordinary user that created the Space, not as a homeserver admin. if let Err(e) = ensure_hive_user().await { tracing::warn!(error = ?e, "matrix: ensure_hive_user failed"); ok = false; @@ -829,8 +584,8 @@ pub async fn ensure_all() -> bool { ok } -/// Provision the hive Space + default chat room and invite every agent -/// (+ the admin account) to both. Split out of [`ensure_all`] purely to +/// Provision the hive Space and invite every agent (+ the admin account) +/// to it. 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. @@ -878,40 +633,6 @@ async fn provision_space(client: &reqwest::Client, agent_names: &[String]) -> bo 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 } @@ -956,43 +677,6 @@ 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] diff --git a/hive-c0re/src/paths.rs b/hive-c0re/src/paths.rs index bcc5b1400..fdc7876d5 100644 --- a/hive-c0re/src/paths.rs +++ b/hive-c0re/src/paths.rs @@ -110,13 +110,6 @@ 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 { diff --git a/hivectl/src/cli.rs b/hivectl/src/cli.rs index c8b62c681..1c1c349f6 100644 --- a/hivectl/src/cli.rs +++ b/hivectl/src/cli.rs @@ -39,8 +39,8 @@ pub enum Cmd { /// matrix-tuwunel invites. /// /// 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 sweep provisions the Space and the agents' invites on + /// its own. Matrix { #[command(subcommand)] cmd: MatrixCmd, diff --git a/nix/host-modules/hive-c0re/environment.nix b/nix/host-modules/hive-c0re/environment.nix index 867245ef7..2f32ea48d 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, create the hive space + chat room, invite members). + # agent users, create the hive space, 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 a23408391..53292fc9a 100644 --- a/nix/host-modules/hive-matrix-service.nix +++ b/nix/host-modules/hive-matrix-service.nix @@ -59,8 +59,8 @@ in example = "https://matrix.example.com"; description = '' Client-server API base URL **hive-c0re itself** uses to - provision matrix (register agent users, create the hive space - and chat room, invite members). Distinct from the agent-facing + provision matrix (register agent users, create the hive space, + 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 c84ac209e..0848b4986 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 Space, the chat room, the - # invites) rides on being the rooms' creator, not on admin. + # credential; what it does (the Space and the invites) + # rides on being the Space's 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 cbb97454c..8636de9d4 100644 --- a/swarm-matrix-client/README.md +++ b/swarm-matrix-client/README.md @@ -15,7 +15,7 @@ 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` provisions the hive Space and chat room with the room calls +`hive-c0re` provisions the hive Space 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 diff --git a/swarm-matrix-client/src/lib.rs b/swarm-matrix-client/src/lib.rs index 5a573a0ed..8e1263308 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 Space and chat-room provisioning need (resolve an alias, list +//! `hive-c0re`'s Space 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. From c0dc4b07f4dec00367a0d6dab1d7e942ab5d2ea7 Mon Sep 17 00:00:00 2001 From: damocles Date: Wed, 28 Oct 2026 20:42:57 +0100 Subject: [PATCH 2/4] reword the leftover-room note in the matrix docs in active voice --- docs/integrations/matrix.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/integrations/matrix.md b/docs/integrations/matrix.md index d54e728d9..4c4881390 100644 --- a/docs/integrations/matrix.md +++ b/docs/integrations/matrix.md @@ -362,7 +362,7 @@ agent purges, and hive-c0re reuses it on re-provision. An earlier version also provisioned a `hive-chat` room and kept its id in `chat-room-id`. The sweep no longer touches either; an existing room and -file are harmless leftovers that can be removed by hand. +file are harmless leftovers, so delete them by hand if you like. **Idempotent**: if the file exists and is non-empty, hive-c0re considers the Space already created. Delete the file to force re-creation (for example From fd01848d4dacf1ddbf5afca4a9c4f0d96134467c Mon Sep 17 00:00:00 2001 From: damocles Date: Wed, 28 Oct 2026 20:57:41 +0100 Subject: [PATCH 3/4] also stop provisioning the hive space and make hivectl matrix invite take a room --- docs/getting-started/setup.md | 7 +- docs/integrations/matrix.md | 36 +-- docs/scheduler/coordinator.md | 2 +- docs/tools/hivectl-cli.md | 10 +- docs/tools/hivectl.md | 14 +- hive-c0re/src/job_queue/exec.rs | 8 +- hive-c0re/src/job_queue/model.rs | 2 +- hive-c0re/src/job_queue/resource.rs | 6 +- hive-c0re/src/job_queue/templates.rs | 2 +- hive-c0re/src/main.rs | 6 +- hive-c0re/src/matrix.rs | 372 ++------------------------- hive-c0re/src/paths.rs | 9 +- hive-c0re/src/server.rs | 6 +- hive-host-sock/src/lib.rs | 11 +- hivectl/README.md | 2 +- hivectl/src/cli.rs | 10 +- hivectl/src/matrix.rs | 6 +- nix/host-modules/hive-matrix.nix | 4 +- swarm-matrix-client/README.md | 5 +- swarm-matrix-client/src/lib.rs | 2 +- 20 files changed, 83 insertions(+), 437 deletions(-) diff --git a/docs/getting-started/setup.md b/docs/getting-started/setup.md index c6339f526..7622e027f 100644 --- a/docs/getting-started/setup.md +++ b/docs/getting-started/setup.md @@ -111,12 +111,11 @@ container keeps starting with the hive meanwhile. ## 5 · Matrix -Your matrix account comes from SSO. Invite it to the hive Space, and -optionally to rooms: +Your matrix account comes from SSO. Invite it to the rooms you want it in: ```bash -hivectl matrix invite mara -hivectl matrix invite @mara:yourserver --room '#some-room:yourserver' +hivectl matrix invite mara --room '#some-room:yourserver' +hivectl matrix invite @mara:yourserver --room '!abc:yourserver' ``` ## 6 · Your first agent diff --git a/docs/integrations/matrix.md b/docs/integrations/matrix.md index 4c4881390..99fd7da58 100644 --- a/docs/integrations/matrix.md +++ b/docs/integrations/matrix.md @@ -96,8 +96,7 @@ and federation peers all reach the homeserver at `chat.` through the gateway; from outside the host that takes `gateway.openFirewall`. -hive-c0re provisions matrix (its own sender login, the hive Space and -invites) through `swarm.matrix.apiUrl`, which defaults to +hive-c0re talks to matrix (its own sender login, 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 @@ -258,9 +257,8 @@ 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. Creating the hive -Space and inviting agents into it are ordinary client calls that ride on -being the Space's own creator at power level 100 — there is no homeserver +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 admin in any of it, and no Synapse admin API to reach for either, since tuwunel has none. @@ -346,27 +344,17 @@ 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 Matrix Space +## Hive sender token -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. +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). -**State**: hive-c0re persists the Space's room ID to -`/var/lib/hyperhive/matrix/space-room-id` (mode `0600`, owned by the -hive-c0re service user). The path is **outside** every agent state dir and -**isn't** deleted by `nixos-container destroy --purge`, so it survives full -agent purges, and hive-c0re reuses it on re-provision. - -An earlier version also provisioned a `hive-chat` room and kept its id in -`chat-room-id`. The sweep no longer touches either; an existing room and -file are harmless leftovers, so delete them by hand if you like. - -**Idempotent**: if the file exists and is non-empty, hive-c0re considers the -Space already created. Delete the file to force re-creation (for example -after a homeserver wipe). +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. ## Configuration tuning diff --git a/docs/scheduler/coordinator.md b/docs/scheduler/coordinator.md index 130334fa4..e5a8ee4cc 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 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 | +| `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 | | `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 eda3044dc..8655f703c 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 the hive Space and its rooms; c0re's periodic matrix sweep provisions the Space and the agents' invites on its own. +Manual invites into a room by id or alias. **Usage:** `hivectl matrix ` ###### **Subcommands:** -* `invite` — Invite a matrix user to the hive Space, or a specific room with `--room`. Idempotent +* `invite` — Invite a matrix user to a room. Idempotent ## `hivectl matrix invite` -Invite a matrix user to the hive Space, or a specific room with `--room`. Idempotent +Invite a matrix user to a room. Idempotent -**Usage:** `hivectl matrix invite [OPTIONS] ` +**Usage:** `hivectl matrix invite --room ` ###### **Arguments:** @@ -138,7 +138,7 @@ Invite a matrix user to the hive Space, or a specific room with `--room`. Idempo ###### **Options:** -* `--room ` — Target room id (`!abc:server`) or alias (`#name:server`). Omit to invite to the hive Space +* `--room ` — Target room id (`!abc:server`) or alias (`#name:server`) diff --git a/docs/tools/hivectl.md b/docs/tools/hivectl.md index 491bd03ab..43822c89b 100644 --- a/docs/tools/hivectl.md +++ b/docs/tools/hivectl.md @@ -44,13 +44,12 @@ hivectl forge reconcile-config iris --verbose # include the full diff, not ## Matrix -Manual entry to the same idempotent matrix provisioning flow -`hive-c0re` runs at boot. Requires the `hive-matrix` container to be +Manual invites into a room. Requires the `hive-matrix` container to be running (`services.hyperhive.deploy.matrix.enable = true`). ```bash -hivectl matrix invite mara # invite a user to the hive Space -hivectl matrix invite @mara:server --room '#some-room:server' # ...or to a specific room/alias +hivectl matrix invite mara --room '#some-room:server' # a room alias +hivectl matrix invite @mara:server --room '!abc:server' # ...or a room id ``` Human matrix accounts come from SSO, not `hivectl`; matrix homeserver @@ -58,10 +57,9 @@ 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 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). + 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. 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 fe4ff0b15..4c2ae7059 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 user/space pass; whether every agent synced. + /// One matrix sender-token pass; whether the token is in place. 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 user/space sweep as a DAG node — see [`NodeKind::MatrixSweep`]. +/// Matrix sender-token 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,8 @@ fn matrix_sweep_warning(ctx: sweep_health::SweepFailure) -> String { |d| format!("last ok {} ago", sweep_health::fmt_age(d)), ); format!( - "matrix user/space sweep failing ({} consecutive, {age}) \ - — some agents may be missing matrix accounts or space membership", + "matrix sender-token sweep failing ({} consecutive, {age}) \ + — `hivectl matrix invite` may not work", ctx.consecutive ) } diff --git a/hive-c0re/src/job_queue/model.rs b/hive-c0re/src/job_queue/model.rs index fa755a451..dd9e3b35e 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 user/space sweep (`matrix::ensure_all`): at boot and every 30 + /// Matrix sender-token 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 c2a6b5493..433b29924 100644 --- a/hive-c0re/src/job_queue/resource.rs +++ b/hive-c0re/src/job_queue/resource.rs @@ -31,10 +31,8 @@ pub enum Resource { /// overlapping `reset` / `clean` / `pull` passes there fail on /// `.git/index.lock` and the remote-tracking ref lock. KnowledgeTree, - /// The hive's matrix provisioning, held by every `MatrixSweep`. Two - /// overlapping passes on a hive with no persisted Space id both - /// miss the by-name lookup and both `createRoom`, leaving a duplicate room - /// with agents invited to both. + /// The hive's sender-token file, held by every `MatrixSweep`. Two + /// overlapping passes would race on writing it. MatrixSweep, } diff --git a/hive-c0re/src/job_queue/templates.rs b/hive-c0re/src/job_queue/templates.rs index 681b1422a..7afb42468 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 user/space sweep. Holding [`Resource::MatrixSweep`] is what keeps +/// One matrix sender-token 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 14c8909fa..d7c8c6275 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 account, the hive - // Space, and every agent container's invite to it. It - // creates no agent accounts or tokens — swarm-controller mints those. + // 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. // 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 0e5cc385f..0318d639e 100644 --- a/hive-c0re/src/matrix.rs +++ b/hive-c0re/src/matrix.rs @@ -1,8 +1,7 @@ //! Optional matrix-tuwunel wiring: the hive's `@hive-:` sender token, -//! taken from the swarm secret store, and the hive Space 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. +//! 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. //! //! This module creates no accounts: `swarm-controller` mints every hive's //! sender account and every agent's account with the swarm's appservice token. @@ -46,46 +45,6 @@ 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 and the invites — it provisions as the -/// creator of the Space. -/// -/// # 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"; - /// 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] @@ -93,13 +52,6 @@ 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() -} - /// Whether this hive has a homeserver to provision against. /// /// **A configured API URL, not a local container**: whether the homeserver @@ -274,136 +226,6 @@ 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) -} - -/// 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`, …). @@ -484,23 +306,21 @@ fn forbidden_invite(membership: Option<&str>, user_id: &str, room_id: &str) -> R ) } -/// 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`. +/// 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`. /// /// # Errors /// -/// 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. +/// 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. pub async fn invite_user( client: &reqwest::Client, sender_token: &str, user: &str, - room_override: Option<&str>, + room: &str, server_name: &str, ) -> Result { // Qualify a bare localpart to a full user id on the hive homeserver. @@ -509,39 +329,29 @@ pub async fn invite_user( } else { format!("@{user}:{server_name}") }; - // 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; \ + 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; \ 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-:` account exists, then provision -/// the hive Space and invite every agent container to it. -/// 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. +/// 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. /// -/// Returns `true` when every step of the sweep succeeded, `false` when at -/// least one step failed — the caller feeds this into a +/// Returns `true` when the token is in place, `false` when it could not be +/// fetched — 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). @@ -550,90 +360,11 @@ 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 and every invite are sent with its token) — as - // an ordinary user that created the Space, not as a homeserver admin. if let Err(e) = ensure_hive_user().await { tracing::warn!(error = ?e, "matrix: ensure_hive_user failed"); - ok = false; - } - 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 and invite every agent (+ the admin account) -/// to it. 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; - } - } - ok + true } #[cfg(test)] @@ -729,53 +460,4 @@ mod tests { assert!(!message.contains("free-form-marker"), "{message}"); } } - - /// 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("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) - } - - #[tokio::test] - 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 fdc7876d5..52bcd89a3 100644 --- a/hive-c0re/src/paths.rs +++ b/hive-c0re/src/paths.rs @@ -104,12 +104,6 @@ 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") -} - /// `run/` — runtime maps hive-c0re regenerates on every meta sync. #[must_use] pub fn run_dir() -> PathBuf { @@ -258,11 +252,10 @@ 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); 5] = [ + let moves: [(&str, PathBuf); 4] = [ ("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 db3065297..34cd6af72 100644 --- a/hive-c0re/src/server.rs +++ b/hive-c0re/src/server.rs @@ -203,9 +203,7 @@ 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.as_deref()).await? - } + HostRequest::MatrixInvite { user, room } => handle_matrix_invite(user, room).await?, HostRequest::ReconcileConfigStatus { agent, verbose } => { crate::forge::reconcile_config_status(agent.as_str(), *verbose).await? } @@ -500,7 +498,7 @@ async fn handle_push_snapshot( Ok(HostResponse::success()) } -async fn handle_matrix_invite(user: &str, room: Option<&str>) -> Result { +async fn handle_matrix_invite(user: &str, room: &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 4d5af3f3f..374c6caa0 100644 --- a/hive-host-sock/src/lib.rs +++ b/hive-host-sock/src/lib.rs @@ -223,14 +223,9 @@ pub enum HostRequest { #[serde(default)] scope: LifecycleScope, }, - /// 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, - }, + /// 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 }, /// 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 7fdec9f42..ef9c944ef 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 the hive Space or a room. +- **`matrix.rs`** — invite a matrix user to 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 1c1c349f6..cbb75fbcb 100644 --- a/hivectl/src/cli.rs +++ b/hivectl/src/cli.rs @@ -38,9 +38,7 @@ pub enum Cmd { }, /// matrix-tuwunel invites. /// - /// Manual invites into the hive Space and its rooms; c0re's periodic - /// matrix sweep provisions the Space and the agents' invites on - /// its own. + /// Manual invites into a room by id or alias. Matrix { #[command(subcommand)] cmd: MatrixCmd, @@ -250,16 +248,14 @@ impl From for hive_host_sock::ReconcileDirection { #[derive(Subcommand)] pub enum MatrixCmd { - /// Invite a matrix user to the hive Space, or a specific room with - /// `--room`. Idempotent. + /// Invite a matrix user to a 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: Option, + room: String, }, } diff --git a/hivectl/src/matrix.rs b/hivectl/src/matrix.rs index 4fd27a238..ee77f9e05 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.as_deref()).await, + MatrixCmd::Invite { user, room } => matrix_invite(socket, &user, &room).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: Option<&str>) -> Result<()> { +async fn matrix_invite(socket: &Path, user: &str, room: &str) -> Result<()> { matrix_request( socket, hive_host_sock::HostRequest::MatrixInvite { user: user.to_owned(), - room: room.map(str::to_owned), + room: room.to_owned(), }, ) .await diff --git a/nix/host-modules/hive-matrix.nix b/nix/host-modules/hive-matrix.nix index 0848b4986..d691cbbac 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 Space and the invites) - # rides on being the Space's creator, not on admin. + # credential; what it does (the invites) rides on its + # power in the room, 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 8636de9d4..28f919116 100644 --- a/swarm-matrix-client/README.md +++ b/swarm-matrix-client/README.md @@ -15,9 +15,8 @@ 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` provisions the hive Space 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 +`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 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 8e1263308..bbcc0b4f0 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 Space provisioning need (resolve an alias, list +//! `hive-c0re`'s invites 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. From ae9c3444bc45b5242e73596d2e90ed02d6a0842a Mon Sep 17 00:00:00 2001 From: damocles Date: Wed, 28 Oct 2026 21:07:32 +0100 Subject: [PATCH 4/4] test the invite room check and the no-homeserver sweep, drop the last space wording --- hive-c0re/src/matrix.rs | 23 ++++++++++++++++++++++ nix/host-modules/hive-c0re/environment.nix | 2 +- nix/host-modules/hive-matrix-service.nix | 3 +-- 3 files changed, 25 insertions(+), 3 deletions(-) diff --git a/hive-c0re/src/matrix.rs b/hive-c0re/src/matrix.rs index 0318d639e..d92a98aac 100644 --- a/hive-c0re/src/matrix.rs +++ b/hive-c0re/src/matrix.rs @@ -460,4 +460,27 @@ mod tests { assert!(!message.contains("free-form-marker"), "{message}"); } } + + /// 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") + .await + .expect_err("a bare name is not a room"); + assert!( + format!("{err:#}").contains("neither a room id nor an alias"), + "{err:#}" + ); + } + + /// 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); + } } diff --git a/nix/host-modules/hive-c0re/environment.nix b/nix/host-modules/hive-c0re/environment.nix index 2f32ea48d..e89d5c80a 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, create the hive space, invite members). + # agent users, 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 53292fc9a..5cfa49f16 100644 --- a/nix/host-modules/hive-matrix-service.nix +++ b/nix/host-modules/hive-matrix-service.nix @@ -59,8 +59,7 @@ in example = "https://matrix.example.com"; description = '' Client-server API base URL **hive-c0re itself** uses to - provision matrix (register agent users, create the hive space, - invite members). Distinct from the agent-facing + provision matrix (register agent users, 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`.