feat: Add Google Chat channel integration

[longzhi]

Summary

Add Google Chat (Google Workspace) as a channel adapter, enabling agents to receive and respond to messages in Google Chat spaces.

Motivation

Google Chat is widely used in organizations running Google Workspace. Adding it as a channel extends Clawhive's reach into the enterprise messaging space alongside existing Feishu, DingTalk, and WeCom integrations.

Implementation Plan

1. Channel Adapter (crates/clawhive-channels/src/google_chat.rs)

Implement ChannelBot trait:

• channel_type() → "google_chat"
• connector_id() → from config
• run() → start message listener

Connection modes (implement in priority order):

1. HTTP endpoint mode (recommended first) — Register an HTTP endpoint that Google Chat calls via Google Chat API events. The endpoint receives MESSAGE, ADDED_TO_SPACE, REMOVED_FROM_SPACE events. This can be integrated into clawhive-server as a route (similar pattern to webhook channel).

2. Pub/Sub mode (optional, Phase 2) — Subscribe to a Google Cloud Pub/Sub topic for receiving events. Useful for environments where exposing HTTP endpoints is not feasible.

2. Authentication

Google Chat apps authenticate via Service Account with domain-wide delegation or OAuth 2.0:

• Service Account JSON key file (recommended for bots)
• Use google-cloud-auth or equivalent Rust crate for token management
• Scopes needed: https://www.googleapis.com/auth/chat.bot

3. Configuration (crates/clawhive-core/src/config.rs)

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct GoogleChatChannelConfig {
    #[serde(default)]
    pub enabled: bool,
    pub connectors: Vec<GoogleChatConnector>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct GoogleChatConnector {
    pub id: String,
    /// Path to service account JSON key file
    pub service_account_key: String,
    /// Google Chat space IDs to listen on (optional, listens to all if empty)
    #[serde(default)]
    pub space_ids: Vec<String>,
    /// Project ID for Pub/Sub mode (optional)
    pub project_id: Option<String>,
    /// Pub/Sub subscription name (optional, for Pub/Sub mode)
    pub subscription: Option<String>,
}

Add to ChannelsConfig:

pub google_chat: Option<GoogleChatChannelConfig>,

YAML config example:

channels:
  google_chat:
    enabled: true
    connectors:
      - id: workspace-bot
        service_account_key: "${GOOGLE_SERVICE_ACCOUNT_KEY}"

4. Feature Flag (crates/clawhive-channels/Cargo.toml)

google_chat = ["dep:reqwest"]  # reqwest already in workspace

Add to lib.rs:

#[cfg(feature = "google_chat")]
pub mod google_chat;

NOT added to default features initially — opt-in until stable.

5. Message Mapping

Google Chat Event	Clawhive Mapping
MESSAGE	InboundMessage with channel_type: "google_chat"
ADDED_TO_SPACE	Log info, optionally send welcome message
REMOVED_FROM_SPACE	Log info, cleanup
Card interactions	Map to InboundMessage with interaction metadata

Conversation scope derivation:

• DM: dm:{user_id}
• Space: space:{space_name}
• Thread in space: space:{space_name}:thread:{thread_id}

6. Response Handling

• Send text messages via spaces.messages.create REST API
• Support Google Chat's card format for rich responses (Phase 2)
• Handle message length limits (4096 chars per message, split if needed)

7. Registration in Gateway

Wire up in clawhive-cli startup flow — same pattern as existing channels:

• Read GoogleChatChannelConfig from main.yaml
• Create GoogleChatBot instances per connector
• Register with gateway for routing

Tasks Checklist

• Add GoogleChatChannelConfig and GoogleChatConnector to config.rs
• Add google_chat field to ChannelsConfig
• Create google_chat.rs in clawhive-channels with ChannelBot implementation
• Add feature flag to clawhive-channels/Cargo.toml
• Add module declaration to clawhive-channels/src/lib.rs
• Add HTTP endpoint handler in clawhive-server for receiving Google Chat events
• Implement Service Account authentication and token refresh
• Wire up in CLI startup flow (clawhive-cli)
• Add setup wizard support (clawhive setup)
• Add tests (unit + integration with mocked HTTP)
• Update README channel list and documentation

References

• Google Chat API Overview
• Google Chat App Authentication
• Chat API REST Reference
• Existing channel adapters for patterns: dingtalk.rs, wecom.rs, feishu.rs

Labels

enhancement, channel