From d88a0cc52629052cd104a4d6905bce9b3c4890d4 Mon Sep 17 00:00:00 2001 From: damocles Date: Sun, 22 Nov 2026 19:01:51 +0100 Subject: [PATCH] hive-matrix-mcp: add a leave_room tool --- docs/4-implementation/agent-tools/matrix.md | 8 ++++--- hive-matrix-mcp/src/handlers.rs | 16 +++++++++++++ hive-matrix-mcp/src/handlers_mock_tests.rs | 18 +++++++++++++++ hive-matrix-mcp/src/mcp.rs | 25 +++++++++++++++++++++ hive-sh4re/src/stream_enrich.rs | 5 ++++- 5 files changed, 68 insertions(+), 4 deletions(-) diff --git a/docs/4-implementation/agent-tools/matrix.md b/docs/4-implementation/agent-tools/matrix.md index 6597c6e68..be36c2828 100644 --- a/docs/4-implementation/agent-tools/matrix.md +++ b/docs/4-implementation/agent-tools/matrix.md @@ -33,9 +33,11 @@ is what an agent reads at call time. They fall into four groups: `edited: true`. The edit event doesn't appear as a second message and doesn't count as unread. When the original is outside the window read, the edit stays as its own event, and its `replaces_event_id` names the message it replaces. -- **Room membership:** `invite_user`, `list_invites`, `resolve_invite` and - `join_room`. `resolve_invite` accepts or rejects a pending invite and is the - path for invites; `join_room` is for a public room the agent wasn't invited to. +- **Room membership:** `invite_user`, `list_invites`, `resolve_invite`, + `join_room` and `leave_room`. `resolve_invite` accepts or rejects a pending + invite and is the path for invites; `join_room` is for a public room the + agent wasn't invited to. `leave_room` leaves a joined room, which is how a + retired account stops receiving a room's messages once the agent moves on. `list_invites` gives the inviter and the topic, so an agent can judge an invite before it answers. On an account that lives on the swarm homeserver, the daemon joins an invite from a user of that same server by itself, diff --git a/hive-matrix-mcp/src/handlers.rs b/hive-matrix-mcp/src/handlers.rs index 09e25b365..01c37710c 100644 --- a/hive-matrix-mcp/src/handlers.rs +++ b/hive-matrix-mcp/src/handlers.rs @@ -900,6 +900,22 @@ pub async fn join_room(client: &Client, room_ref: &str) -> DaemonResponse { } } +/// Leave the joined room `room_ref` (id or alias), so a retired account stops +/// receiving its messages. +pub async fn leave_room(client: &Client, room_ref: &str) -> DaemonResponse { + let room = match resolve_room(client, room_ref).await { + Ok(r) => r, + Err(e) => return e, + }; + match room.leave().await { + Ok(()) => DaemonResponse::ok(&serde_json::json!({ + "left": true, + "room_id": room.room_id().to_string(), + })), + Err(e) => DaemonResponse::error(format!("leave room {room_ref}: {e}")), + } +} + /// Accept or reject a pending invite to `room_ref` (id or alias). /// /// `Accept` is exactly `join_room` (joining a room you were invited to diff --git a/hive-matrix-mcp/src/handlers_mock_tests.rs b/hive-matrix-mcp/src/handlers_mock_tests.rs index 15f903ab5..cbdf82863 100644 --- a/hive-matrix-mcp/src/handlers_mock_tests.rs +++ b/hive-matrix-mcp/src/handlers_mock_tests.rs @@ -247,6 +247,24 @@ async fn rejecting_an_invite_leaves_the_room() { assert_eq!(got["room_id"], "!invited:localhost"); } +#[tokio::test] +async fn leaving_a_joined_room_asks_the_server_and_an_unknown_room_is_refused() { + let (server, client) = caught_up_room().await; + server + .mock_room_leave() + .ok(room_id!("!room:localhost")) + .expect(1) + .mount() + .await; + + let got = ok(leave_room(&client, "!room:localhost").await); + + assert_eq!(got["left"], true); + assert_eq!(got["room_id"], "!room:localhost"); + let unknown = err(leave_room(&client, "!never:localhost").await); + assert!(unknown.contains("not joined"), "{unknown}"); +} + #[tokio::test] async fn reading_a_room_returns_its_events_newest_first_with_sender_and_body() { let (_server, client) = room_with(vec![ diff --git a/hive-matrix-mcp/src/mcp.rs b/hive-matrix-mcp/src/mcp.rs index 8c56f700c..b92a581a8 100644 --- a/hive-matrix-mcp/src/mcp.rs +++ b/hive-matrix-mcp/src/mcp.rs @@ -212,6 +212,17 @@ struct ListInvitesArgs { account: Option, } +#[derive(Debug, Deserialize, JsonSchema)] +struct LeaveRoomArgs { + /// Matrix room id (`!abc:server`) or canonical alias (`#name:server`) of a + /// room the account has joined. + room: String, + /// Matrix account to act as (a `name` from `services.hyperhive.agent.matrixAccounts`). + /// Omit to use the agent's primary account. + #[serde(default)] + account: Option, +} + #[derive(Debug, Deserialize, JsonSchema)] struct JoinRoomArgs { /// Matrix room id (`!abc:server`) or canonical alias (`#name:server`). @@ -414,6 +425,20 @@ impl MatrixMcp { render(handlers::join_room(&client, &args.room).await) } + #[tool( + description = "Leave a matrix room you have joined, by id (!abc:server) or \ + alias (#name:server). Use it to drop a room a retired account still sits \ + in, so it stops getting that room's messages. To decline a pending \ + invite use `resolve_invite`. The room leaves `list_rooms`." + )] + async fn leave_room(&self, Parameters(args): Parameters) -> String { + let client = match self.resolve(args.account.as_deref()) { + Ok(c) => c, + Err(e) => return format!("matrix error: {e}"), + }; + render(handlers::leave_room(&client, &args.room).await) + } + #[tool( description = "Accept or reject a pending matrix invite. `room` is a room id \ (!abc:server) or alias (#name:server) you were invited to; `action` is \ diff --git a/hive-sh4re/src/stream_enrich.rs b/hive-sh4re/src/stream_enrich.rs index afba07ee2..8ee46521f 100644 --- a/hive-sh4re/src/stream_enrich.rs +++ b/hive-sh4re/src/stream_enrich.rs @@ -777,7 +777,10 @@ fn fmt_matrix_tool(name: &str, short: &str, input: &Value) -> String { .unwrap_or_default(); format!("{short} {}{limit}", fmt_room(&sv(input, "room"))) } - "mcp__matrix__mark_read" | "mcp__matrix__join_room" | "mcp__matrix__download_file" => { + "mcp__matrix__mark_read" + | "mcp__matrix__join_room" + | "mcp__matrix__leave_room" + | "mcp__matrix__download_file" => { format!("{short} {}", fmt_room(&sv(input, "room"))) } "mcp__matrix__send_message" | "mcp__matrix__send_reply" => format!(