feat(channels): expose WhatsApp Web data to agent via structured RPC API (tinyhumansai#1308)

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: M3gA-Mind

app/src-tauri/src/whatsapp_scanner/mod.rs

@@ -49,6 +49,11 @@ impl RegisteredController {
 /// The global static registry of all controllers, initialized once on first access.
 static REGISTRY: OnceLock<Vec<RegisteredController>> = OnceLock::new();
 
+/// Internal-only controllers: registered for RPC dispatch but NOT in the agent-facing
+/// schema catalog.  These handlers are callable by trusted callers (e.g. the Tauri scanner)
+/// but should not be advertised to agents via tool listings or schema discovery.
+static INTERNAL_REGISTRY: OnceLock<Vec<RegisteredController>> = OnceLock::new();
+
 /// The global static registry of standalone CLI adapters.
 static CLI_ADAPTERS: OnceLock<Vec<RegisteredCliAdapter>> = OnceLock::new();
 
@@ -69,6 +74,16 @@ fn registry() -> &'static [RegisteredController] {
         .as_slice()
 }
 
+/// Returns a reference to the internal-only controller registry.
+///
+/// These controllers are callable over RPC but are NOT included in agent tool listings
+/// or schema discovery endpoints.
+fn internal_registry() -> &'static [RegisteredController] {
+    INTERNAL_REGISTRY
+        .get_or_init(build_internal_only_controllers)
+        .as_slice()
+}
+
 /// Returns a reference to the global CLI adapter registry.
 fn cli_adapters() -> &'static [RegisteredCliAdapter] {
     CLI_ADAPTERS.get_or_init(|| {
@@ -192,6 +207,21 @@ fn build_registered_controllers() -> Vec<RegisteredController> {
     );
     // Integration notification ingest, triage, and per-provider settings
     controllers.extend(crate::openhuman::notifications::all_notifications_registered_controllers());
+    // Structured WhatsApp Web data — agent-facing read-only controllers (list/search).
+    // The write-path ingest controller is registered separately in build_internal_only_controllers.
+    controllers.extend(crate::openhuman::whatsapp_data::all_whatsapp_data_registered_controllers());
+    controllers
+}
+
+/// Aggregates controllers that are registered for RPC routing but NOT exposed to agents.
+///
+/// These are write-path or internal-only handlers callable by trusted callers
+/// (e.g. the Tauri scanner ingest path) that should not appear in agent tool listings.
+fn build_internal_only_controllers() -> Vec<RegisteredController> {
+    let mut controllers = Vec::new();
+    // whatsapp_data ingest: scanner-side write path.  Callable over RPC by the
+    // Tauri scanner but excluded from agent-facing schema discovery.
+    controllers.extend(crate::openhuman::whatsapp_data::all_whatsapp_data_internal_controllers());
     controllers
 }
 
@@ -255,6 +285,8 @@ fn build_declared_controller_schemas() -> Vec<ControllerSchema> {
     );
     // Integration notification ingest, triage, and per-provider settings
     schemas.extend(crate::openhuman::notifications::all_notifications_controller_schemas());
+    // Structured WhatsApp Web data — local SQLite store, agent-queryable
+    schemas.extend(crate::openhuman::whatsapp_data::all_whatsapp_data_controller_schemas());
     schemas
 }
 
@@ -340,6 +372,9 @@ pub fn namespace_description(namespace: &str) -> Option<&'static str> {
             "Integration notification ingest, triage scoring, listing, read-state, \
              and per-provider routing settings.",
         ),
+        "whatsapp_data" => Some(
+            "Structured WhatsApp conversation and message store — list chats, read messages, and search across WhatsApp Web data.",
+        ),
         _ => None,
     }
 }
@@ -361,9 +396,13 @@ pub fn rpc_method_from_parts(namespace: &str, function: &str) -> Option<String>
 }
 
 /// Retrieves the schema for a specific RPC method.
+///
+/// Checks both the agent-facing registry and the internal registry so that
+/// parameter validation still applies to internal-only methods (e.g. ingest).
 pub fn schema_for_rpc_method(method: &str) -> Option<ControllerSchema> {
     registry()
         .iter()
+        .chain(internal_registry().iter())
         .find(|r| r.rpc_method_name() == method)
         .map(|r| r.schema.clone())
 }
@@ -400,7 +439,11 @@ pub fn validate_params(
 
 /// Attempts to invoke a registered RPC method by name.
 ///
-/// Returns `None` if the method is not found in the registry.
+/// Checks both the agent-facing controller registry and the internal-only registry,
+/// so scanner-side write paths (e.g. `openhuman.whatsapp_data_ingest`) are routable
+/// even though they are not included in agent tool listings.
+///
+/// Returns `None` if the method is not found in either registry.
 pub async fn try_invoke_registered_rpc(
     method: &str,
     params: Map<String, Value>,
@@ -410,6 +453,11 @@ pub async fn try_invoke_registered_rpc(
             return Some((controller.handler)(params).await);
         }
     }
+    for controller in internal_registry() {
+        if controller.rpc_method_name() == method {
+            return Some((controller.handler)(params).await);
+        }
+    }
     None
 }
 

src/core/all.rs

@@ -674,6 +674,15 @@ async fn run_server_inner(
             ),
             Err(e) => log::warn!("[boot] memory::global init failed: {e}"),
         }
+        // Initialize the WhatsApp data store so scanner ingest calls
+        // can write data without requiring a lazy-init fallback.
+        match crate::openhuman::whatsapp_data::global::init(cfg.workspace_dir.clone()) {
+            Ok(_) => log::info!(
+                "[boot] whatsapp_data::global initialized (workspace={})",
+                cfg.workspace_dir.display()
+            ),
+            Err(e) => log::warn!("[boot] whatsapp_data::global init failed: {e}"),
+        }
     }
 
     let (resolved_port, port_source) = match port {

src/core/jsonrpc.rs

@@ -686,6 +686,16 @@ const CAPABILITIES: &[Capability] = &[
         status: CapabilityStatus::Beta,
         privacy: None,
     },
+    Capability {
+        id: "channels.whatsapp_read_messages",
+        name: "Read WhatsApp Messages",
+        domain: "channels",
+        category: CapabilityCategory::Channels,
+        description: "Read and search WhatsApp Web conversations and messages after connecting WhatsApp in OpenHuman. Data is stored locally only and never transmitted.",
+        how_to: "Connect WhatsApp Web via Channels, then ask the agent to read or summarise your messages.",
+        status: CapabilityStatus::Beta,
+        privacy: LOCAL_RAW,
+    },
     Capability {
         id: "settings.configure_ai",
         name: "Configure AI",

src/openhuman/about_app/catalog.rs

@@ -70,4 +70,5 @@ pub mod webhooks;
 pub mod webview_accounts;
 pub mod webview_apis;
 pub mod webview_notifications;
+pub mod whatsapp_data;
 pub mod workspace;

src/openhuman/mod.rs

@@ -0,0 +1,57 @@
+//! Process-global WhatsApp data store singleton.
+//!
+//! One `WhatsAppDataStore` lives for the entire core process, shared by RPC
+//! handlers and any other subsystem that needs it.
+//!
+//! # Usage
+//!
+//! ```ignore
+//! // At startup:
+//! whatsapp_data::global::init(workspace_dir)?;
+//!
+//! // In RPC handlers:
+//! let store = whatsapp_data::global::store()?;
+//! ```
+
+use std::path::PathBuf;
+use std::sync::{Arc, OnceLock};
+
+use crate::openhuman::whatsapp_data::store::WhatsAppDataStore;
+
+/// Shared, thread-safe reference to the store.
+pub type WhatsAppDataStoreRef = Arc<WhatsAppDataStore>;
+
+static GLOBAL_STORE: OnceLock<WhatsAppDataStoreRef> = OnceLock::new();
+
+/// Initialise the global store from a workspace directory. Idempotent —
+/// only the first call has any effect; subsequent calls return the existing
+/// instance.
+pub fn init(workspace_dir: PathBuf) -> Result<WhatsAppDataStoreRef, String> {
+    if let Some(existing) = GLOBAL_STORE.get() {
+        log::debug!("[whatsapp_data:global] already initialised");
+        return Ok(Arc::clone(existing));
+    }
+    log::info!(
+        "[whatsapp_data:global] initialising store workspace={}",
+        workspace_dir.display()
+    );
+    let store = Arc::new(
+        WhatsAppDataStore::new(&workspace_dir)
+            .map_err(|e| format!("[whatsapp_data] store init failed: {e}"))?,
+    );
+    let _ = GLOBAL_STORE.set(Arc::clone(&store));
+    Ok(GLOBAL_STORE.get().cloned().unwrap_or(store))
+}
+
+/// Return the global store. Errors if [`init`] has not been called yet.
+pub fn store() -> Result<WhatsAppDataStoreRef, String> {
+    GLOBAL_STORE.get().cloned().ok_or_else(|| {
+        "whatsapp_data global store accessed before init — call init(workspace) at startup"
+            .to_string()
+    })
+}
+
+/// Return the global store if already initialised, without error.
+pub fn store_if_ready() -> Option<WhatsAppDataStoreRef> {
+    GLOBAL_STORE.get().cloned()
+}

src/openhuman/whatsapp_data/global.rs

@@ -0,0 +1,29 @@
+//! Structured WhatsApp Web data — local-only SQLite persistence and agent API.
+//!
+//! This domain stores WhatsApp chats and messages scraped by the Tauri
+//! `whatsapp_scanner` via CDP, making them queryable by the agent through
+//! the JSON-RPC controller surface.
+//!
+//! **Data locality**: all data remains on-device in `whatsapp_data.db`; it is
+//! never transmitted to any external service.
+//!
+//! ## Agent-facing RPC methods (read-only)
+//! - `openhuman.whatsapp_data_list_chats`
+//! - `openhuman.whatsapp_data_list_messages`
+//! - `openhuman.whatsapp_data_search_messages`
+//!
+//! ## Internal-only RPC method (write, scanner-side)
+//! - `openhuman.whatsapp_data_ingest` — NOT exposed via agent tool listings
+
+pub mod global;
+pub mod ops;
+pub mod rpc;
+mod schemas;
+pub mod store;
+pub mod types;
+
+pub use schemas::{
+    all_controller_schemas as all_whatsapp_data_controller_schemas,
+    all_internal_controllers as all_whatsapp_data_internal_controllers,
+    all_registered_controllers as all_whatsapp_data_registered_controllers,
+};