feat(gateway,desktop): mcpmux_* self-management meta tools with native approval

Exposes a small built-in toolset (`mcpmux_*`) alongside every backend
tool so LLMs can introspect and, with explicit user approval, reshape
their own session's FeatureSet. Enabled by default.

Read tools (no approval — always advertised):
  * mcpmux_list_all_tools       — unfiltered view across connected servers
  * mcpmux_list_feature_sets    — space's FSes w/ is_active + is_pinned
  * mcpmux_describe_resolution  — current FS + why (pin | binding | active)
  * mcpmux_describe_workspace   — reported MCP roots + matching binding

Write tools (each gated by native desktop approval + diff preview):
  * mcpmux_pin_this_session        — caller-scope, sets pinned_feature_set_id
  * mcpmux_create_feature_set      — compose a custom FS from qualified names
  * mcpmux_bind_current_workspace  — persistent WorkspaceBinding (space-wide)
  * mcpmux_set_space_active        — flips space fallback (affects everyone)

Gateway plumbing (`crates/mcpmux-gateway/src/services/meta_tools/`):
  * MetaTool trait + MetaToolRegistry. Handler intercepts `mcpmux_*` before
    routing, so meta tools are always visible regardless of the caller's
    resolved FS.
  * ApprovalBroker: session-scoped rate limit (10/min/client), oneshot
    request/response with 60s default timeout, session-only "always allow"
    cache keyed by (client_id, tool_name) — deliberately NOT persisted so
    gateway restarts re-prompt.
  * ToolDiff: before/after qualified-name comparison (via FeatureService)
    so approval dialogs show "68 tools removed, 0 added" instead of
    abstract FeatureSet names.
  * Write path emits `FeatureSetMembersChanged` → MCPNotifier pushes
    `tools/list_changed` → caller re-fetches the trimmed toolset in the
    next turn.

Desktop (Tauri + React):
  * `commands/meta_tool_approval.rs` Tauri commands:
      - respond_to_meta_tool_approval(request_id, decision)
      - list_meta_tool_grants / revoke_meta_tool_grant
  * `start_gateway` attaches a publisher that emits
    `meta-tool-approval-request` events to the frontend.
  * `<MetaToolApprovalDialog>` — global React component (mounted once from
    `App.tsx`). Renders the summary + affect-other-clients warning +
    tool-list diff (+added / −removed, color-coded), with
    [Allow once] / [Always for this session] / [Deny] buttons. Queues
    concurrent requests.
  * GatewayAppState gains `approval_broker: Option<Arc<ApprovalBroker>>`,
    populated on gateway start.

Tests (20 new passing):
  * `services::meta_tools::approval::tests` — 6 unit tests covering
    always-allow short-circuit, publisher allow/deny/timeout, headless
    no-desktop, and always-scope persistence across calls.
  * `tests/integration/meta_tools.rs` — 14 end-to-end tests with real
    SQLite repos + auto-approving publisher:
      - list_all_tools / list_feature_sets / describe_resolution /
        describe_workspace return correct payloads
      - write w/o publisher → approval_required
      - pin_this_session allow → pin persists; deny → unchanged
      - always-allow decision bypasses subsequent publisher calls
      - create_feature_set persists members only after approval
      - bind_current_workspace fails without roots; normalizes on success
      - set_space_active updates Space fallback
      - invalid UUID arg rejected
      - registry advertises all 8 tools with destructive_hint annotations

Other:
  * `gateway_notifications::test_client_can_list_tools_after_notification`
    updated to filter `mcpmux_*` from its "empty toolset" assertion — meta
    tools are always present.
  * Total test count: 9 (mcpmux), 123 (core), 104 (gateway lib incl. the
    6 approval tests), 66 (integration incl. 14 meta-tool tests), plus
    all existing suites green.
Signed-off-by: Mohammod Al Amin Ashik <maa.ashik00@gmail.com>

Author: its-mash

apps/desktop/src-tauri/src/commands/gateway.rs

@@ -56,6 +56,8 @@ pub struct GatewayAppState {
     pub event_emitter: Option<Arc<mcpmux_gateway::EventEmitter>>,
     /// Grant service for centralized grant management with auto-notifications
     pub grant_service: Option<Arc<mcpmux_gateway::GrantService>>,
+    /// Approval broker for meta-tool writes (publisher attached on gateway start)
+    pub approval_broker: Option<Arc<mcpmux_gateway::services::ApprovalBroker>>,
 }
 
 /// Start domain event bridge from Gateway to Tauri
@@ -596,6 +598,34 @@ pub async fn start_gateway(
     let grant_service = server.grant_service();
     info!("[Gateway] Got grant_service: {:p}", &*grant_service);
 
+    // Meta-tool approval broker — attach a Tauri-event publisher so
+    // incoming approval requests reach the React dialog.
+    let approval_broker = server.approval_broker();
+    {
+        let app_handle_for_broker = app_handle.clone();
+        let publisher: mcpmux_gateway::services::meta_tools::ApprovalPublisher =
+            std::sync::Arc::new(move |req| {
+                let app_handle = app_handle_for_broker.clone();
+                Box::pin(async move {
+                    // Emit the request; the React layer owns rendering +
+                    // collecting the user's decision. Failure to emit means
+                    // no desktop frontend is listening — broker maps that to
+                    // "approval_required" to the calling tool.
+                    match app_handle.emit("meta-tool-approval-request", &req) {
+                        Ok(()) => true,
+                        Err(e) => {
+                            tracing::warn!(
+                                error = %e,
+                                "[meta-tool] failed to emit approval request"
+                            );
+                            false
+                        }
+                    }
+                })
+            });
+        approval_broker.set_publisher(publisher).await;
+    }
+
     // Start domain event bridge (clean architecture)
     start_domain_event_bridge(&app_handle, gw_state.clone());
 
@@ -615,6 +645,7 @@ pub async fn start_gateway(
         &*grant_service
     );
     state.grant_service = Some(grant_service);
+    state.approval_broker = Some(approval_broker);
     info!(
         "[Gateway] grant_service set! Checking: {}",
         state.grant_service.is_some()

apps/desktop/src-tauri/src/commands/meta_tool_approval.rs

@@ -0,0 +1,111 @@
+//! Tauri commands for meta-tool approval dialogs.
+//!
+//! Flow:
+//!   1. Gateway's [`ApprovalBroker`] emits `meta-tool-approval-request`
+//!      event (see gateway.rs `start_gateway`).
+//!   2. React dialog renders it, user picks once/always/deny.
+//!   3. Dialog calls [`respond_to_meta_tool_approval`], which resolves the
+//!      broker's oneshot channel and unblocks the calling tool.
+
+use std::sync::Arc;
+
+use mcpmux_gateway::services::ApprovalDecision;
+use serde::Serialize;
+use tauri::State;
+use tokio::sync::RwLock;
+use tracing::{info, warn};
+use uuid::Uuid;
+
+use crate::commands::gateway::GatewayAppState;
+
+#[derive(Debug, Serialize)]
+pub struct MetaToolGrantEntry {
+    pub client_id: String,
+    pub tool_name: String,
+}
+
+/// Resolve a pending approval dialog.
+///
+/// `decision` is one of `"allow_once" | "always_for_this_session_and_client" | "deny"`.
+/// Called from the React dialog. If the broker doesn't recognize the
+/// request_id (e.g. it already timed out), returns a no-op success so the
+/// UI can close its dialog cleanly.
+#[tauri::command]
+pub async fn respond_to_meta_tool_approval(
+    request_id: String,
+    client_id: String,
+    tool_name: String,
+    decision: String,
+    gateway_state: State<'_, Arc<RwLock<GatewayAppState>>>,
+) -> Result<bool, String> {
+    let decision = match decision.as_str() {
+        "allow_once" => ApprovalDecision::AllowOnce,
+        "always_for_this_session_and_client" => ApprovalDecision::AlwaysForThisSessionAndClient,
+        "deny" => ApprovalDecision::Deny,
+        other => return Err(format!("unknown decision: {other}")),
+    };
+    let client_uuid = Uuid::parse_str(&client_id).map_err(|e| format!("bad client_id: {e}"))?;
+
+    let broker = {
+        let state = gateway_state.read().await;
+        state.approval_broker.clone()
+    };
+    let Some(broker) = broker else {
+        warn!("[meta-tool] respond called but gateway is not running");
+        return Ok(false);
+    };
+
+    let resolved = broker.respond(&request_id, client_uuid, &tool_name, decision);
+    info!(
+        %request_id,
+        %client_id,
+        tool = %tool_name,
+        ?decision,
+        resolved,
+        "[meta-tool] approval decision recorded"
+    );
+    Ok(resolved)
+}
+
+/// List every active "always allow from this client for this tool" grant.
+///
+/// Entries are session-only (cleared on gateway restart by design). The
+/// Connections page uses this to show a revoke list.
+#[tauri::command]
+pub async fn list_meta_tool_grants(
+    gateway_state: State<'_, Arc<RwLock<GatewayAppState>>>,
+) -> Result<Vec<MetaToolGrantEntry>, String> {
+    let broker = {
+        let state = gateway_state.read().await;
+        state.approval_broker.clone()
+    };
+    let Some(broker) = broker else {
+        return Ok(vec![]);
+    };
+    Ok(broker
+        .list_always_allow()
+        .into_iter()
+        .map(|(client_id, tool_name)| MetaToolGrantEntry {
+            client_id: client_id.to_string(),
+            tool_name,
+        })
+        .collect())
+}
+
+/// Revoke an "always allow" entry.
+#[tauri::command]
+pub async fn revoke_meta_tool_grant(
+    client_id: String,
+    tool_name: String,
+    gateway_state: State<'_, Arc<RwLock<GatewayAppState>>>,
+) -> Result<bool, String> {
+    let client_uuid = Uuid::parse_str(&client_id).map_err(|e| format!("bad client_id: {e}"))?;
+    let broker = {
+        let state = gateway_state.read().await;
+        state.approval_broker.clone()
+    };
+    let Some(broker) = broker else {
+        return Ok(false);
+    };
+    Ok(broker.revoke_always_allow(client_uuid, &tool_name))
+}

apps/desktop/src-tauri/src/commands/mod.rs

@@ -12,6 +12,7 @@ pub mod feature_members;
 pub mod feature_set;
 pub mod gateway;
 pub mod logs;
+pub mod meta_tool_approval;
 pub mod oauth;
 pub mod server;
 pub mod server_discovery;
@@ -30,6 +31,7 @@ pub use feature_members::*;
 pub use feature_set::*;
 pub use gateway::*;
 pub use logs::*;
+pub use meta_tool_approval::*;
 pub use oauth::*;
 pub use server::*;
 pub use server_discovery::*;

apps/desktop/src-tauri/src/lib.rs

@@ -801,6 +801,10 @@ pub fn run() {
             commands::create_workspace_binding,
             commands::update_workspace_binding,
             commands::delete_workspace_binding,
+            // Meta-tool approval (self-management mcpmux_* tools)
+            commands::respond_to_meta_tool_approval,
+            commands::list_meta_tool_grants,
+            commands::revoke_meta_tool_grant,
             // Config export commands
             commands::preview_config_export,
             commands::export_config_to_file,

apps/desktop/src/App.tsx

@@ -42,6 +42,7 @@ import { ClientsPage } from '@/features/clients';
 import { ServersPage } from '@/features/servers';
 import { SpacesPage } from '@/features/spaces';
 import { SettingsPage } from '@/features/settings';
+import { MetaToolApprovalDialog } from '@/features/metaTools';
 import { useGatewayEvents, useServerStatusEvents } from '@/hooks/useDomainEvents';
 
 /** McpMux title-bar icon — miniature cat icon */
@@ -353,6 +354,8 @@ function App() {
       <OAuthConsentModal />
       {/* Server install modal - shown when install deep link is received */}
       <ServerInstallModal />
+      {/* Meta-tool approval dialog — gates every mcpmux_* write tool */}
+      <MetaToolApprovalDialog />
     </ThemeProvider>
   );
 }