feat: add beta googlechat channel

README.md

@@ -17,7 +17,7 @@
 </p>
 
 **Clawdbot** is a *personal AI assistant* you run on your own devices.
-It answers you on the channels you already use (WhatsApp, Telegram, Slack, Discord, Signal, iMessage, Microsoft Teams, WebChat), plus extension channels like BlueBubbles, Matrix, Zalo, and Zalo Personal. It can speak and listen on macOS/iOS/Android, and can render a live Canvas you control. The Gateway is just the control plane — the product is the assistant.
+It answers you on the channels you already use (WhatsApp, Telegram, Slack, Discord, Google Chat, Signal, iMessage, Microsoft Teams, WebChat), plus extension channels like BlueBubbles, Matrix, Zalo, and Zalo Personal. It can speak and listen on macOS/iOS/Android, and can render a live Canvas you control. The Gateway is just the control plane — the product is the assistant.
 
 If you want a personal, single-user assistant that feels local, fast, and always-on, this is it.
 
@@ -65,7 +65,7 @@ clawdbot gateway --port 18789 --verbose
 # Send a message
 clawdbot message send --to +1234567890 --message "Hello from Clawdbot"
 
-# Talk to the assistant (optionally deliver back to any connected channel: WhatsApp/Telegram/Slack/Discord/Signal/iMessage/BlueBubbles/Microsoft Teams/Matrix/Zalo/Zalo Personal/WebChat)
+# Talk to the assistant (optionally deliver back to any connected channel: WhatsApp/Telegram/Slack/Discord/Google Chat/Signal/iMessage/BlueBubbles/Microsoft Teams/Matrix/Zalo/Zalo Personal/WebChat)
 clawdbot agent --message "Ship checklist" --thinking high
 ```
 
@@ -106,7 +106,7 @@ Clawdbot connects to real messaging surfaces. Treat inbound DMs as **untrusted i
 
 Full security guide: [Security](https://docs.clawd.bot/gateway/security)
 
-Default behavior on Telegram/WhatsApp/Signal/iMessage/Microsoft Teams/Discord/Slack:
+Default behavior on Telegram/WhatsApp/Signal/iMessage/Microsoft Teams/Discord/Google Chat/Slack:
 - **DM pairing** (`dmPolicy="pairing"` / `channels.discord.dm.policy="pairing"` / `channels.slack.dm.policy="pairing"`): unknown senders receive a short pairing code and the bot does not process their message.
 - Approve with: `clawdbot pairing approve <channel> <code>` (then the sender is added to a local allowlist store).
 - Public inbound DMs require an explicit opt-in: set `dmPolicy="open"` and include `"*"` in the channel allowlist (`allowFrom` / `channels.discord.dm.allowFrom` / `channels.slack.dm.allowFrom`).
@@ -116,7 +116,7 @@ Run `clawdbot doctor` to surface risky/misconfigured DM policies.
 ## Highlights
 
 - **[Local-first Gateway](https://docs.clawd.bot/gateway)** — single control plane for sessions, channels, tools, and events.
-- **[Multi-channel inbox](https://docs.clawd.bot/channels)** — WhatsApp, Telegram, Slack, Discord, Signal, iMessage, BlueBubbles, Microsoft Teams, Matrix, Zalo, Zalo Personal, WebChat, macOS, iOS/Android.
+- **[Multi-channel inbox](https://docs.clawd.bot/channels)** — WhatsApp, Telegram, Slack, Discord, Google Chat, Signal, iMessage, BlueBubbles, Microsoft Teams, Matrix, Zalo, Zalo Personal, WebChat, macOS, iOS/Android.
 - **[Multi-agent routing](https://docs.clawd.bot/gateway/configuration)** — route inbound channels/accounts/peers to isolated agents (workspaces + per-agent sessions).
 - **[Voice Wake](https://docs.clawd.bot/nodes/voicewake) + [Talk Mode](https://docs.clawd.bot/nodes/talk)** — always-on speech for macOS/iOS/Android with ElevenLabs.
 - **[Live Canvas](https://docs.clawd.bot/platforms/mac/canvas)** — agent-driven visual workspace with [A2UI](https://docs.clawd.bot/platforms/mac/canvas#canvas-a2ui).
@@ -138,7 +138,7 @@ Run `clawdbot doctor` to surface risky/misconfigured DM policies.
 - [Media pipeline](https://docs.clawd.bot/nodes/images): images/audio/video, transcription hooks, size caps, temp file lifecycle. Audio details: [Audio](https://docs.clawd.bot/nodes/audio).
 
 ### Channels
-- [Channels](https://docs.clawd.bot/channels): [WhatsApp](https://docs.clawd.bot/channels/whatsapp) (Baileys), [Telegram](https://docs.clawd.bot/channels/telegram) (grammY), [Slack](https://docs.clawd.bot/channels/slack) (Bolt), [Discord](https://docs.clawd.bot/channels/discord) (discord.js), [Signal](https://docs.clawd.bot/channels/signal) (signal-cli), [iMessage](https://docs.clawd.bot/channels/imessage) (imsg), [BlueBubbles](https://docs.clawd.bot/channels/bluebubbles) (extension), [Microsoft Teams](https://docs.clawd.bot/channels/msteams) (extension), [Matrix](https://docs.clawd.bot/channels/matrix) (extension), [Zalo](https://docs.clawd.bot/channels/zalo) (extension), [Zalo Personal](https://docs.clawd.bot/channels/zalouser) (extension), [WebChat](https://docs.clawd.bot/web/webchat).
+- [Channels](https://docs.clawd.bot/channels): [WhatsApp](https://docs.clawd.bot/channels/whatsapp) (Baileys), [Telegram](https://docs.clawd.bot/channels/telegram) (grammY), [Slack](https://docs.clawd.bot/channels/slack) (Bolt), [Discord](https://docs.clawd.bot/channels/discord) (discord.js), [Google Chat](https://docs.clawd.bot/channels/googlechat) (Chat API), [Signal](https://docs.clawd.bot/channels/signal) (signal-cli), [iMessage](https://docs.clawd.bot/channels/imessage) (imsg), [BlueBubbles](https://docs.clawd.bot/channels/bluebubbles) (extension), [Microsoft Teams](https://docs.clawd.bot/channels/msteams) (extension), [Matrix](https://docs.clawd.bot/channels/matrix) (extension), [Zalo](https://docs.clawd.bot/channels/zalo) (extension), [Zalo Personal](https://docs.clawd.bot/channels/zalouser) (extension), [WebChat](https://docs.clawd.bot/web/webchat).
 - [Group routing](https://docs.clawd.bot/concepts/group-messages): mention gating, reply tags, per-channel chunking and routing. Channel rules: [Channels](https://docs.clawd.bot/channels).
 
 ### Apps + nodes
@@ -169,7 +169,7 @@ Run `clawdbot doctor` to surface risky/misconfigured DM policies.
 ## How it works (short)
 
 ```
-WhatsApp / Telegram / Slack / Discord / Signal / iMessage / BlueBubbles / Microsoft Teams / Matrix / Zalo / Zalo Personal / WebChat
+WhatsApp / Telegram / Slack / Discord / Google Chat / Signal / iMessage / BlueBubbles / Microsoft Teams / Matrix / Zalo / Zalo Personal / WebChat
                │
                ▼
 ┌───────────────────────────────┐
@@ -252,7 +252,7 @@ ClawdHub is a minimal skill registry. With ClawdHub enabled, the agent can searc
 
 ## Chat commands
 
-Send these in WhatsApp/Telegram/Slack/Microsoft Teams/WebChat (group commands are owner-only):
+Send these in WhatsApp/Telegram/Slack/Google Chat/Microsoft Teams/WebChat (group commands are owner-only):
 
 - `/status` — compact session status (model + tokens, cost when available)
 - `/new` or `/reset` — reset the session

apps/macos/Sources/Clawdbot/ChannelsSettings+ChannelState.swift

@@ -40,6 +40,16 @@ extension ChannelsSettings {
         return .orange
     }
 
+    var googlechatTint: Color {
+        guard let status = self.channelStatus("googlechat", as: ChannelsStatusSnapshot.GoogleChatStatus.self)
+        else { return .secondary }
+        if !status.configured { return .secondary }
+        if status.lastError != nil { return .orange }
+        if status.probe?.ok == false { return .orange }
+        if status.running { return .green }
+        return .orange
+    }
+
     var signalTint: Color {
         guard let status = self.channelStatus("signal", as: ChannelsStatusSnapshot.SignalStatus.self)
         else { return .secondary }
@@ -85,6 +95,14 @@ extension ChannelsSettings {
         return "Configured"
     }
 
+    var googlechatSummary: String {
+        guard let status = self.channelStatus("googlechat", as: ChannelsStatusSnapshot.GoogleChatStatus.self)
+        else { return "Checking…" }
+        if !status.configured { return "Not configured" }
+        if status.running { return "Running" }
+        return "Configured"
+    }
+
     var signalSummary: String {
         guard let status = self.channelStatus("signal", as: ChannelsStatusSnapshot.SignalStatus.self)
         else { return "Checking…" }
@@ -193,6 +211,37 @@ extension ChannelsSettings {
         return lines.isEmpty ? nil : lines.joined(separator: " · ")
     }
 
+    var googlechatDetails: String? {
+        guard let status = self.channelStatus("googlechat", as: ChannelsStatusSnapshot.GoogleChatStatus.self)
+        else { return nil }
+        var lines: [String] = []
+        if let source = status.credentialSource {
+            lines.append("Credential: \(source)")
+        }
+        if let audienceType = status.audienceType {
+            let audience = status.audience ?? ""
+            let label = audience.isEmpty ? audienceType : "\(audienceType) \(audience)"
+            lines.append("Audience: \(label)")
+        }
+        if let probe = status.probe {
+            if probe.ok {
+                if let elapsed = probe.elapsedMs {
+                    lines.append("Probe \(Int(elapsed))ms")
+                }
+            } else {
+                let code = probe.status.map { String($0) } ?? "unknown"
+                lines.append("Probe failed (\(code))")
+            }
+        }
+        if let last = self.date(fromMs: status.lastProbeAt) {
+            lines.append("Last probe \(relativeAge(from: last))")
+        }
+        if let err = status.lastError, !err.isEmpty {
+            lines.append("Error: \(err)")
+        }
+        return lines.isEmpty ? nil : lines.joined(separator: " · ")
+    }
+
     var signalDetails: String? {
         guard let status = self.channelStatus("signal", as: ChannelsStatusSnapshot.SignalStatus.self)
         else { return nil }
@@ -244,7 +293,7 @@ extension ChannelsSettings {
     }
 
     var orderedChannels: [ChannelItem] {
-        let fallback = ["whatsapp", "telegram", "discord", "slack", "signal", "imessage"]
+        let fallback = ["whatsapp", "telegram", "discord", "googlechat", "slack", "signal", "imessage"]
         let order = self.store.snapshot?.channelOrder ?? fallback
         let channels = order.enumerated().map { index, id in
             ChannelItem(
@@ -307,6 +356,8 @@ extension ChannelsSettings {
             return self.telegramTint
         case "discord":
             return self.discordTint
+        case "googlechat":
+            return self.googlechatTint
         case "signal":
             return self.signalTint
         case "imessage":
@@ -326,6 +377,8 @@ extension ChannelsSettings {
             return self.telegramSummary
         case "discord":
             return self.discordSummary
+        case "googlechat":
+            return self.googlechatSummary
         case "signal":
             return self.signalSummary
         case "imessage":
@@ -345,6 +398,8 @@ extension ChannelsSettings {
             return self.telegramDetails
         case "discord":
             return self.discordDetails
+        case "googlechat":
+            return self.googlechatDetails
         case "signal":
             return self.signalDetails
         case "imessage":
@@ -377,6 +432,10 @@ extension ChannelsSettings {
             return self
                 .date(fromMs: self.channelStatus("discord", as: ChannelsStatusSnapshot.DiscordStatus.self)?
                     .lastProbeAt)
+        case "googlechat":
+            return self
+                .date(fromMs: self.channelStatus("googlechat", as: ChannelsStatusSnapshot.GoogleChatStatus.self)?
+                    .lastProbeAt)
         case "signal":
             return self
                 .date(fromMs: self.channelStatus("signal", as: ChannelsStatusSnapshot.SignalStatus.self)?.lastProbeAt)
@@ -411,6 +470,10 @@ extension ChannelsSettings {
             guard let status = self.channelStatus("discord", as: ChannelsStatusSnapshot.DiscordStatus.self)
             else { return false }
             return status.lastError?.isEmpty == false || status.probe?.ok == false
+        case "googlechat":
+            guard let status = self.channelStatus("googlechat", as: ChannelsStatusSnapshot.GoogleChatStatus.self)
+            else { return false }
+            return status.lastError?.isEmpty == false || status.probe?.ok == false
         case "signal":
             guard let status = self.channelStatus("signal", as: ChannelsStatusSnapshot.SignalStatus.self)
             else { return false }

apps/macos/Sources/Clawdbot/ChannelsStore.swift

@@ -85,6 +85,28 @@ struct ChannelsStatusSnapshot: Codable {
         let lastProbeAt: Double?
     }
 
+    struct GoogleChatProbe: Codable {
+        let ok: Bool
+        let status: Int?
+        let error: String?
+        let elapsedMs: Double?
+    }
+
+    struct GoogleChatStatus: Codable {
+        let configured: Bool
+        let credentialSource: String?
+        let audienceType: String?
+        let audience: String?
+        let webhookPath: String?
+        let webhookUrl: String?
+        let running: Bool
+        let lastStartAt: Double?
+        let lastStopAt: Double?
+        let lastError: String?
+        let probe: GoogleChatProbe?
+        let lastProbeAt: Double?
+    }
+
     struct SignalProbe: Codable {
         let ok: Bool
         let status: Int?

apps/macos/Sources/Clawdbot/GatewayConnection.swift

@@ -11,6 +11,7 @@ enum GatewayAgentChannel: String, Codable, CaseIterable, Sendable {
     case whatsapp
     case telegram
     case discord
+    case googlechat
     case slack
     case signal
     case imessage

apps/macos/Tests/ClawdbotIPCTests/GatewayAgentChannelTests.swift

@@ -11,6 +11,7 @@ import Testing
         #expect(GatewayAgentChannel.last.shouldDeliver(true) == true)
         #expect(GatewayAgentChannel.whatsapp.shouldDeliver(true) == true)
         #expect(GatewayAgentChannel.telegram.shouldDeliver(true) == true)
+        #expect(GatewayAgentChannel.googlechat.shouldDeliver(true) == true)
         #expect(GatewayAgentChannel.bluebubbles.shouldDeliver(true) == true)
         #expect(GatewayAgentChannel.last.shouldDeliver(false) == false)
     }
@@ -19,6 +20,7 @@ import Testing
         #expect(GatewayAgentChannel(raw: nil) == .last)
         #expect(GatewayAgentChannel(raw: "  ") == .last)
         #expect(GatewayAgentChannel(raw: "WEBCHAT") == .webchat)
+        #expect(GatewayAgentChannel(raw: "googlechat") == .googlechat)
         #expect(GatewayAgentChannel(raw: "BLUEBUBBLES") == .bluebubbles)
         #expect(GatewayAgentChannel(raw: "unknown") == .last)
     }

docs/channels/googlechat.md

@@ -0,0 +1,172 @@
+---
+summary: "Google Chat app support status, capabilities, and configuration"
+read_when:
+  - Working on Google Chat channel features
+---
+# Google Chat (Chat API)
+
+Status: ready for DMs + spaces via Google Chat API webhooks (HTTP only).
+
+## Quick setup (beginner)
+1) Create a Google Cloud project and enable the **Google Chat API**.
+   - Go to: [Google Chat API Credentials](https://console.cloud.google.com/apis/api/chat.googleapis.com/credentials)
+   - Enable the API if it is not already enabled.
+2) Create a **Service Account**:
+   - Press **Create Credentials** > **Service Account**.
+   - Name it whatever you want (e.g., `clawdbot-chat`).
+   - Leave permissions blank (press **Continue**).
+   - Leave principals with access blank (press **Done**).
+3) Create and download the **JSON Key**:
+   - In the list of service accounts, click on the one you just created.
+   - Go to the **Keys** tab.
+   - Click **Add Key** > **Create new key**.
+   - Select **JSON** and press **Create**.
+4) Store the downloaded JSON file on your gateway host (e.g., `~/.clawdbot/googlechat-service-account.json`).
+5) Create a Google Chat app in the [Google Cloud Console Chat Configuration](https://console.cloud.google.com/apis/api/chat.googleapis.com/hangouts-chat):
+   - Fill in the **Application info**:
+     - **App name**: (e.g. `Clawdbot`)
+     - **Avatar URL**: (e.g. `https://clawd.bot/logo.png`)
+     - **Description**: (e.g. `Personal AI Assistant`)
+   - Enable **Interactive features**.
+   - Under **Functionality**, check **Join spaces and group conversations**.
+   - Under **Connection settings**, select **HTTP endpoint URL**.
+   - Under **Triggers**, select **Use a common HTTP endpoint URL for all triggers** and set it to your gateway's public URL followed by `/googlechat`.
+     - *Tip: Run `clawdbot status` to find your gateway's public URL.*
+   - Under **Visibility**, check **Make this Chat app available to specific people and groups in <Your Domain>**.
+   - Enter your email address (e.g. `user@example.com`) in the text box.
+   - Click **Save** at the bottom.
+6) **Enable the app status**:
+   - After saving, **refresh the page**.
+   - Look for the **App status** section (usually near the top or bottom after saving).
+   - Change the status to **Live - available to users**.
+   - Click **Save** again.
+7) Configure Clawdbot with the service account path + webhook audience:
+   - Env: `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE=/path/to/service-account.json`
+   - Or config: `channels.googlechat.serviceAccountFile: "/path/to/service-account.json"`.
+8) Set the webhook audience type + value (matches your Chat app config).
+9) Start the gateway. Google Chat will POST to your webhook path.
+
+## Add to Google Chat
+Once the gateway is running and your email is added to the visibility list:
+1) Go to [Google Chat](https://chat.google.com/).
+2) Click the **+** (plus) icon next to **Direct Messages**.
+3) In the search bar (where you usually add people), type the **App name** you configured in the Google Cloud Console.
+   - **Note**: The bot will *not* appear in the "Marketplace" browse list because it is a private app. You must search for it by name.
+4) Select your bot from the results.
+5) Click **Add** or **Chat** to start a 1:1 conversation.
+6) Send "Hello" to trigger the assistant!
+
+## Public URL (Webhook-only)
+Google Chat webhooks require a public HTTPS endpoint. For security, **only expose the `/googlechat` path** to the internet. Keep the Clawdbot dashboard and other sensitive endpoints on your private network.
+
+### Option A: Tailscale Funnel (Recommended)
+If you use Tailscale, you can expose **only** the webhook path using Tailscale Funnel. This keeps your dashboard private while allowing Google Chat to reach your gateway.
+
+1. **Check what address your gateway is bound to:**
+   ```bash
+   ss -tlnp | grep 18789
+   ```
+   Note the IP address (e.g., `127.0.0.1`, `0.0.0.0`, or your Tailscale IP like `100.x.x.x`).
+
+2. **Configure the path mapping** (use the IP from step 1):
+   ```bash
+   # If bound to localhost (127.0.0.1 or 0.0.0.0):
+   tailscale funnel --bg --set-path /googlechat http://127.0.0.1:18789/googlechat
+
+   # If bound to Tailscale IP only (e.g., 100.106.161.80):
+   tailscale funnel --bg --set-path /googlechat http://100.106.161.80:18789/googlechat
+   ```
+
+3. **Authorize the node for Funnel access:**
+   If prompted, visit the authorization URL shown in the output to enable Funnel for this node in your tailnet policy.
+
+4. **Verify the configuration:**
+   ```bash
+   tailscale funnel status
+   ```
+
+Your public webhook URL will be:
+`https://<node-name>.<tailnet>.ts.net/googlechat`
+
+The rest of your gateway (like the dashboard at `/`) remains inaccessible from the public web unless you explicitly add it.
+
+> Note: This configuration persists across reboots. To remove it later, run `tailscale funnel reset`.
+
+### Option B: Reverse Proxy (Caddy)
+If you use a reverse proxy like Caddy, only proxy the specific path:
+```caddy
+your-domain.com {
+    reverse_proxy /googlechat* localhost:18789
+}
+```
+With this config, any request to `your-domain.com/` will be ignored or returned as 404, while `your-domain.com/googlechat` is safely routed to Clawdbot.
+
+### Option C: Cloudflare Tunnel
+Configure your tunnel's ingress rules to only route the webhook path:
+- **Path**: `/googlechat` -> `http://localhost:18789/googlechat`
+- **Default Rule**: HTTP 404 (Not Found)
+
+## How it works
+
+1. Google Chat sends webhook POSTs to the gateway. Each request includes an `Authorization: Bearer <token>` header.
+2. Clawdbot verifies the token against the configured `audienceType` + `audience`:
+   - `audienceType: "app-url"` → audience is your HTTPS webhook URL.
+   - `audienceType: "project-number"` → audience is the Cloud project number.
+3. Messages are routed by space:
+   - DMs use session key `agent:<agentId>:googlechat:dm:<spaceId>`.
+   - Spaces use session key `agent:<agentId>:googlechat:group:<spaceId>`.
+4. DM access is pairing by default. Unknown senders receive a pairing code; approve with:
+   - `clawdbot pairing approve googlechat <code>`
+5. Group spaces require @-mention by default. Use `botUser` if mention detection needs the app’s user name.
+
+## Targets
+Use these identifiers for delivery and allowlists:
+- Direct messages: `users/<userId>` (Clawdbot resolves to a DM space automatically).
+- Spaces: `spaces/<spaceId>`.
+
+## Config highlights
+```json5
+{
+  channels: {
+    "googlechat": {
+      enabled: true,
+      serviceAccountFile: "/path/to/service-account.json",
+      audienceType: "app-url",
+      audience: "https://gateway.example.com/googlechat",
+      webhookPath: "/googlechat",
+      botUser: "users/1234567890", // optional; helps mention detection
+      dm: {
+        policy: "pairing",
+        allowFrom: ["users/1234567890", "name@example.com"]
+      },
+      groupPolicy: "allowlist",
+      groups: {
+        "spaces/AAAA": {
+          allow: true,
+          requireMention: true,
+          users: ["users/1234567890"],
+          systemPrompt: "Short answers only."
+        }
+      },
+      actions: { reactions: true },
+      mediaMaxMb: 20
+    }
+  }
+}
+```
+
+Notes:
+- Service account credentials can also be passed inline with `serviceAccount` (JSON string).
+- Default webhook path is `/googlechat` if `webhookPath` isn’t set.
+- Reactions are available via the `reactions` tool and `channels action` when `actions.reactions` is enabled.
+- Attachments are downloaded through the Chat API and stored in the media pipeline (size capped by `mediaMaxMb`).
+
+## Troubleshooting
+- Check `clawdbot channels status --probe` for auth errors or missing audience config.
+- If no messages arrive, confirm the Chat app’s webhook URL + event subscriptions.
+- If mention gating blocks replies, set `botUser` to the app’s user resource name and verify `requireMention`.
+
+Related docs:
+- [Gateway configuration](/gateway/configuration)
+- [Security](/gateway/security)
+- [Reactions](/tools/reactions)

docs/channels/index.md

@@ -15,6 +15,7 @@ Text is supported everywhere; media and reactions vary by channel.
 - [Telegram](/channels/telegram) — Bot API via grammY; supports groups.
 - [Discord](/channels/discord) — Discord Bot API + Gateway; supports servers, channels, and DMs.
 - [Slack](/channels/slack) — Bolt SDK; workspace apps.
+- [Google Chat](/channels/googlechat) — Google Chat API app via HTTP webhook.
 - [Mattermost](/channels/mattermost) — Bot API + WebSocket; channels, groups, DMs (plugin, installed separately).
 - [Signal](/channels/signal) — signal-cli; privacy-focused.
 - [BlueBubbles](/channels/bluebubbles) — **Recommended for iMessage**; uses the BlueBubbles macOS server REST API with full feature support (edit, unsend, effects, reactions, group management — edit currently broken on macOS 26 Tahoe).

docs/cli/channels.md

@@ -1,7 +1,7 @@
 ---
 summary: "CLI reference for `clawdbot channels` (accounts, status, login/logout, logs)"
 read_when:
-  - You want to add/remove channel accounts (WhatsApp/Telegram/Discord/Slack/Mattermost (plugin)/Signal/iMessage)
+  - You want to add/remove channel accounts (WhatsApp/Telegram/Discord/Google Chat/Slack/Mattermost (plugin)/Signal/iMessage)
   - You want to check channel status or tail channel logs
 ---
 

docs/cli/index.md

@@ -355,7 +355,7 @@ Options:
 ## Channel helpers
 
 ### `channels`
-Manage chat channel accounts (WhatsApp/Telegram/Discord/Slack/Mattermost (plugin)/Signal/iMessage/MS Teams).
+Manage chat channel accounts (WhatsApp/Telegram/Discord/Google Chat/Slack/Mattermost (plugin)/Signal/iMessage/MS Teams).
 
 Subcommands:
 - `channels list`: show configured channels and auth profiles (Claude Code + Codex CLI OAuth sync included).
@@ -368,7 +368,7 @@ Subcommands:
 - `channels logout`: log out of a channel session (if supported).
 
 Common options:
-- `--channel <name>`: `whatsapp|telegram|discord|slack|mattermost|signal|imessage|msteams`
+- `--channel <name>`: `whatsapp|telegram|discord|googlechat|slack|mattermost|signal|imessage|msteams`
 - `--account <id>`: channel account id (default `default`)
 - `--name <label>`: display name for the account
 

docs/cli/message.md

@@ -8,7 +8,7 @@ read_when:
 # `clawdbot message`
 
 Single outbound command for sending messages and channel actions
-(Discord/Slack/Mattermost (plugin)/Telegram/WhatsApp/Signal/iMessage/MS Teams).
+(Discord/Google Chat/Slack/Mattermost (plugin)/Telegram/WhatsApp/Signal/iMessage/MS Teams).
 
 ## Usage
 
@@ -19,12 +19,13 @@ clawdbot message <subcommand> [flags]
 Channel selection:
 - `--channel` required if more than one channel is configured.
 - If exactly one channel is configured, it becomes the default.
-- Values: `whatsapp|telegram|discord|slack|mattermost|signal|imessage|msteams` (Mattermost requires plugin)
+- Values: `whatsapp|telegram|discord|googlechat|slack|mattermost|signal|imessage|msteams` (Mattermost requires plugin)
 
 Target formats (`--target`):
 - WhatsApp: E.164 or group JID
 - Telegram: chat id or `@username`
 - Discord: `channel:<id>` or `user:<id>` (or `<@id>` mention; raw numeric ids are treated as channels)
+- Google Chat: `spaces/<spaceId>` or `users/<userId>`
 - Slack: `channel:<id>` or `user:<id>` (raw channel id is accepted)
 - Mattermost (plugin): `channel:<id>`, `user:<id>`, or `@username` (bare ids are treated as channels)
 - Signal: `+E.164`, `group:<id>`, `signal:+E.164`, `signal:group:<id>`, or `username:<name>`/`u:<name>`
@@ -50,7 +51,7 @@ Name lookup:
 ### Core
 
 - `send`
-  - Channels: WhatsApp/Telegram/Discord/Slack/Mattermost (plugin)/Signal/iMessage/MS Teams
+  - Channels: WhatsApp/Telegram/Discord/Google Chat/Slack/Mattermost (plugin)/Signal/iMessage/MS Teams
   - Required: `--target`, plus `--message` or `--media`
   - Optional: `--media`, `--reply-to`, `--thread-id`, `--gif-playback`
   - Telegram only: `--buttons` (requires `channels.telegram.capabilities.inlineButtons` to allow it)
@@ -65,14 +66,14 @@ Name lookup:
   - Discord only: `--poll-duration-hours`, `--message`
 
 - `react`
-  - Channels: Discord/Slack/Telegram/WhatsApp
+  - Channels: Discord/Google Chat/Slack/Telegram/WhatsApp
   - Required: `--message-id`, `--target`
   - Optional: `--emoji`, `--remove`, `--participant`, `--from-me`
   - Note: `--remove` requires `--emoji` (omit `--emoji` to clear own reactions where supported; see /tools/reactions)
   - WhatsApp only: `--participant`, `--from-me`
 
 - `reactions`
-  - Channels: Discord/Slack
+  - Channels: Discord/Google Chat/Slack
   - Required: `--message-id`, `--target`
   - Optional: `--limit`
 

docs/cli/status.md

@@ -17,7 +17,7 @@ clawdbot status --usage
 ```
 
 Notes:
-- `--deep` runs live probes (WhatsApp Web + Telegram + Discord + Slack + Signal).
+- `--deep` runs live probes (WhatsApp Web + Telegram + Discord + Google Chat + Slack + Signal).
 - Output includes per-agent session stores when multiple agents are configured.
 - Overview includes Gateway + node host service install/runtime status when available.
 - Overview includes update channel + git SHA (for source checkouts).

docs/docs.json

@@ -149,6 +149,14 @@
       "source": "/providers/discord/",
       "destination": "/channels/discord"
     },
+    {
+      "source": "/providers/googlechat",
+      "destination": "/channels/googlechat"
+    },
+    {
+      "source": "/providers/googlechat/",
+      "destination": "/channels/googlechat"
+    },
     {
       "source": "/providers/grammy",
       "destination": "/channels/grammy"
@@ -943,6 +951,7 @@
           "channels/grammy",
           "channels/discord",
           "channels/slack",
+          "channels/googlechat",
           "channels/mattermost",
           "channels/signal",
           "channels/imessage",

docs/gateway/configuration.md

@@ -399,7 +399,7 @@ Optional per-agent identity used for defaults and UX. This is written by the mac
 
 If set, Clawdbot derives defaults (only when you haven’t set them explicitly):
 - `messages.ackReaction` from the **active agent**’s `identity.emoji` (falls back to 👀)
-- `agents.list[].groupChat.mentionPatterns` from the agent’s `identity.name`/`identity.emoji` (so “@Samantha” works in groups across Telegram/Slack/Discord/iMessage/WhatsApp)
+- `agents.list[].groupChat.mentionPatterns` from the agent’s `identity.name`/`identity.emoji` (so “@Samantha” works in groups across Telegram/Slack/Discord/Google Chat/iMessage/WhatsApp)
 - `identity.avatar` accepts a workspace-relative image path or a remote URL/data URL. Local files must live inside the agent workspace.
 
 `identity.avatar` accepts:
@@ -543,7 +543,7 @@ Notes:
 - Outbound commands default to account `default` if present; otherwise the first configured account id (sorted).
 - The legacy single-account Baileys auth dir is migrated by `clawdbot doctor` into `whatsapp/default`.
 
-### `channels.telegram.accounts` / `channels.discord.accounts` / `channels.slack.accounts` / `channels.mattermost.accounts` / `channels.signal.accounts` / `channels.imessage.accounts`
+### `channels.telegram.accounts` / `channels.discord.accounts` / `channels.googlechat.accounts` / `channels.slack.accounts` / `channels.mattermost.accounts` / `channels.signal.accounts` / `channels.imessage.accounts`
 
 Run multiple accounts per channel (each account has its own `accountId` and optional `name`):
 
@@ -574,7 +574,7 @@ Notes:
 
 ### Group chat mention gating (`agents.list[].groupChat` + `messages.groupChat`)
 
-Group messages default to **require mention** (either metadata mention or regex patterns). Applies to WhatsApp, Telegram, Discord, and iMessage group chats.
+Group messages default to **require mention** (either metadata mention or regex patterns). Applies to WhatsApp, Telegram, Discord, Google Chat, and iMessage group chats.
 
 **Mention types:**
 - **Metadata mentions**: Native platform @-mentions (e.g., WhatsApp tap-to-mention). Ignored in WhatsApp self-chat mode (see `channels.whatsapp.allowFrom`).
@@ -1120,6 +1120,43 @@ Reaction notification modes:
 Outbound text is chunked by `channels.discord.textChunkLimit` (default 2000). Discord clients can clip very tall messages, so `channels.discord.maxLinesPerMessage` (default 17) splits long multi-line replies even when under 2000 chars.
 Retry policy defaults and behavior are documented in [Retry policy](/concepts/retry).
 
+### `channels.googlechat` (Chat API webhook)
+
+Google Chat runs over HTTP webhooks with app-level auth (service account).
+Multi-account support lives under `channels.googlechat.accounts` (see the multi-account section above). Env vars only apply to the default account.
+
+```json5
+{
+  channels: {
+    "googlechat": {
+      enabled: true,
+      serviceAccountFile: "/path/to/service-account.json",
+      audienceType: "app-url",             // app-url | project-number
+      audience: "https://gateway.example.com/googlechat",
+      webhookPath: "/googlechat",
+      botUser: "users/1234567890",        // optional; improves mention detection
+      dm: {
+        enabled: true,
+        policy: "pairing",                // pairing | allowlist | open | disabled
+        allowFrom: ["users/1234567890"]   // optional; "open" requires ["*"]
+      },
+      groupPolicy: "allowlist",
+      groups: {
+        "spaces/AAAA": { allow: true, requireMention: true }
+      },
+      actions: { reactions: true },
+      mediaMaxMb: 20
+    }
+  }
+}
+```
+
+Notes:
+- Service account JSON can be inline (`serviceAccount`) or file-based (`serviceAccountFile`).
+- Env fallbacks for the default account: `GOOGLE_CHAT_SERVICE_ACCOUNT` or `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`.
+- `audienceType` + `audience` must match the Chat app’s webhook auth config.
+- Use `spaces/<spaceId>` or `users/<userId>` when setting delivery targets.
+
 ### `channels.slack` (socket mode)
 
 Slack runs in Socket Mode and requires both a bot token and app token:
@@ -1434,7 +1471,7 @@ WhatsApp inbound prefix is configured via `channels.whatsapp.messagePrefix` (dep
 agent has `identity.name` set.
 
 `ackReaction` sends a best-effort emoji reaction to acknowledge inbound messages
-on channels that support reactions (Slack/Discord/Telegram). Defaults to the
+on channels that support reactions (Slack/Discord/Telegram/Google Chat). Defaults to the
 active agent’s `identity.emoji` when set, otherwise `"👀"`. Set it to `""` to disable.
 
 `ackReactionScope` controls when reactions fire:
@@ -1444,7 +1481,7 @@ active agent’s `identity.emoji` when set, otherwise `"👀"`. Set it to `""` t
 - `all`: all messages
 
 `removeAckAfterReply` removes the bot’s ack reaction after a reply is sent
-(Slack/Discord/Telegram only). Default: `false`.
+(Slack/Discord/Telegram/Google Chat only). Default: `false`.
 
 #### `messages.tts`
 
@@ -1829,11 +1866,12 @@ Block streaming:
   ```
 - `agents.defaults.blockStreamingCoalesce`: merge streamed blocks before sending.
   Defaults to `{ idleMs: 1000 }` and inherits `minChars` from `blockStreamingChunk`
-  with `maxChars` capped to the channel text limit. Signal/Slack/Discord default
+  with `maxChars` capped to the channel text limit. Signal/Slack/Discord/Google Chat default
   to `minChars: 1500` unless overridden.
   Channel overrides: `channels.whatsapp.blockStreamingCoalesce`, `channels.telegram.blockStreamingCoalesce`,
   `channels.discord.blockStreamingCoalesce`, `channels.slack.blockStreamingCoalesce`, `channels.mattermost.blockStreamingCoalesce`,
-  `channels.signal.blockStreamingCoalesce`, `channels.imessage.blockStreamingCoalesce`, `channels.msteams.blockStreamingCoalesce`
+  `channels.signal.blockStreamingCoalesce`, `channels.imessage.blockStreamingCoalesce`, `channels.msteams.blockStreamingCoalesce`,
+  `channels.googlechat.blockStreamingCoalesce`
   (and per-account variants).
 - `agents.defaults.humanDelay`: randomized pause between **block replies** after the first.
   Modes: `off` (default), `natural` (800–2500ms), `custom` (use `minMs`/`maxMs`).
@@ -2980,7 +3018,7 @@ Mapping notes:
 - Templates like `{{messages[0].subject}}` read from the payload.
 - `transform` can point to a JS/TS module that returns a hook action.
 - `deliver: true` sends the final reply to a channel; `channel` defaults to `last` (falls back to WhatsApp).
-- If there is no prior delivery route, set `channel` + `to` explicitly (required for Telegram/Discord/Slack/Signal/iMessage/MS Teams).
+- If there is no prior delivery route, set `channel` + `to` explicitly (required for Telegram/Discord/Google Chat/Slack/Signal/iMessage/MS Teams).
 - `model` overrides the LLM for this hook run (`provider/model` or alias; must be allowed if `agents.defaults.models` is set).
 
 Gmail helper config (used by `clawdbot webhooks gmail setup` / `run`):
@@ -3156,7 +3194,7 @@ Template placeholders are expanded in `tools.media.*.models[].args` and `tools.m
 | `{{GroupMembers}}` | Group members preview (best effort) |
 | `{{SenderName}}` | Sender display name (best effort) |
 | `{{SenderE164}}` | Sender phone number (best effort) |
-| `{{Provider}}` | Provider hint (whatsapp|telegram|discord|slack|signal|imessage|msteams|webchat|…) |
+| `{{Provider}}` | Provider hint (whatsapp|telegram|discord|googlechat|slack|signal|imessage|msteams|webchat|…) |
 
 ## Cron (Gateway scheduler)
 

docs/gateway/heartbeat.md

@@ -144,7 +144,7 @@ Example: two agents, only the second agent runs heartbeats.
   - Session key formats: see [Sessions](/concepts/session) and [Groups](/concepts/groups).
 - `target`:
   - `last` (default): deliver to the last used external channel.
-  - explicit channel: `whatsapp` / `telegram` / `discord` / `slack` / `msteams` / `signal` / `imessage`.
+  - explicit channel: `whatsapp` / `telegram` / `discord` / `googlechat` / `slack` / `msteams` / `signal` / `imessage`.
   - `none`: run the heartbeat but **do not deliver** externally.
 - `to`: optional recipient override (channel-specific id, e.g. E.164 for WhatsApp or a Telegram chat id).
 - `prompt`: overrides the default prompt body (not merged).

docs/help/faq.md

@@ -207,7 +207,7 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS,
 
 ### What is Clawdbot, in one paragraph?
 
-Clawdbot is a personal AI assistant you run on your own devices. It replies on the messaging surfaces you already use (WhatsApp, Telegram, Slack, Mattermost (plugin), Discord, Signal, iMessage, WebChat) and can also do voice + a live Canvas on supported platforms. The **Gateway** is the always-on control plane; the assistant is the product.
+Clawdbot is a personal AI assistant you run on your own devices. It replies on the messaging surfaces you already use (WhatsApp, Telegram, Slack, Mattermost (plugin), Discord, Google Chat, Signal, iMessage, WebChat) and can also do voice + a live Canvas on supported platforms. The **Gateway** is the always-on control plane; the assistant is the product.
 
 ### What’s the value proposition?
 

docs/start/wizard.md

@@ -48,7 +48,7 @@ The wizard starts with **QuickStart** (defaults) vs **Advanced** (full control).
   - Model/auth (OpenAI Code (Codex) subscription OAuth, Anthropic API key (recommended) or setup-token (paste), plus MiniMax/GLM/Moonshot/AI Gateway options)
 - Workspace location + bootstrap files
 - Gateway settings (port/bind/auth/tailscale)
-- Providers (Telegram, WhatsApp, Discord, Mattermost (plugin), Signal)
+- Providers (Telegram, WhatsApp, Discord, Google Chat, Mattermost (plugin), Signal)
 - Daemon install (LaunchAgent / systemd user unit)
 - Health check
 - Skills (recommended)
@@ -114,10 +114,11 @@ Tip: `--json` does **not** imply non-interactive mode. Use `--non-interactive` (
    - Non‑loopback binds still require auth.
 
 5) **Channels**
-   - WhatsApp: optional QR login.
-   - Telegram: bot token.
-   - Discord: bot token.
-   - Mattermost (plugin): bot token + base URL.
+  - WhatsApp: optional QR login.
+  - Telegram: bot token.
+  - Discord: bot token.
+  - Google Chat: service account JSON + webhook audience.
+  - Mattermost (plugin): bot token + base URL.
    - Signal: optional `signal-cli` install + account config.
    - iMessage: local `imsg` CLI path + DB access.
   - DM security: default is pairing. First DM sends a code; approve via `clawdbot pairing approve <channel> <code>` or use allowlists.
@@ -313,5 +314,5 @@ will prompt to install it (npm or a local path) before it can be configured.
 
 - macOS app onboarding: [Onboarding](/start/onboarding)
 - Config reference: [Gateway configuration](/gateway/configuration)
-- Providers: [WhatsApp](/channels/whatsapp), [Telegram](/channels/telegram), [Discord](/channels/discord), [Signal](/channels/signal), [iMessage](/channels/imessage)
+- Providers: [WhatsApp](/channels/whatsapp), [Telegram](/channels/telegram), [Discord](/channels/discord), [Google Chat](/channels/googlechat), [Signal](/channels/signal), [iMessage](/channels/imessage)
 - Skills: [Skills](/tools/skills), [Skills config](/tools/skills-config)

docs/tools/agent-send.md

@@ -41,7 +41,7 @@ clawdbot agent --agent ops --message "Generate report" --deliver --reply-channel
 
 - `--local`: run locally (requires model provider API keys in your shell)
 - `--deliver`: send the reply to the chosen channel
-- `--channel`: delivery channel (`whatsapp|telegram|discord|slack|signal|imessage`, default: `whatsapp`)
+- `--channel`: delivery channel (`whatsapp|telegram|discord|googlechat|slack|signal|imessage`, default: `whatsapp`)
 - `--reply-to`: delivery target override
 - `--reply-channel`: delivery channel override
 - `--reply-account`: delivery account id override

docs/tools/index.md

@@ -325,7 +325,7 @@ Notes:
 - Uses the image model directly (independent of the main chat model).
 
 ### `message`
-Send messages and channel actions across Discord/Slack/Telegram/WhatsApp/Signal/iMessage/MS Teams.
+Send messages and channel actions across Discord/Google Chat/Slack/Telegram/WhatsApp/Signal/iMessage/MS Teams.
 
 Core actions:
 - `send` (text + optional media; MS Teams also supports `card` for Adaptive Cards)

docs/tools/reactions.md

@@ -14,6 +14,7 @@ Shared reaction semantics across channels:
 Channel notes:
 
 - **Discord/Slack**: empty `emoji` removes all of the bot's reactions on the message; `remove: true` removes just that emoji.
+- **Google Chat**: empty `emoji` removes the app's reactions on the message; `remove: true` removes just that emoji.
 - **Telegram**: empty `emoji` removes the bot's reactions; `remove: true` also removes reactions but still requires a non-empty `emoji` for tool validation.
 - **WhatsApp**: empty `emoji` removes the bot reaction; `remove: true` maps to empty emoji (still requires `emoji`).
 - **Signal**: inbound reaction notifications emit system events when `channels.signal.reactionNotifications` is enabled.

docs/tools/slash-commands.md

@@ -39,7 +39,7 @@ They run immediately, are stripped before the model sees the message, and the re
 ```
 
 - `commands.text` (default `true`) enables parsing `/...` in chat messages.
-  - On surfaces without native commands (WhatsApp/WebChat/Signal/iMessage/MS Teams), text commands still work even if you set this to `false`.
+  - On surfaces without native commands (WhatsApp/WebChat/Signal/iMessage/Google Chat/MS Teams), text commands still work even if you set this to `false`.
 - `commands.native` (default `"auto"`) registers native commands.
   - Auto: on for Discord/Telegram; off for Slack (until you add slash commands); ignored for providers without native support.
   - Set `channels.discord.commands.native`, `channels.telegram.commands.native`, or `channels.slack.commands.native` to override per provider (bool or `"auto"`).

extensions/googlechat/clawdbot.plugin.json

@@ -0,0 +1,11 @@
+{
+  "id": "googlechat",
+  "channels": [
+    "googlechat"
+  ],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

extensions/googlechat/index.ts

@@ -0,0 +1,20 @@
+import type { ClawdbotPluginApi } from "clawdbot/plugin-sdk";
+import { emptyPluginConfigSchema } from "clawdbot/plugin-sdk";
+
+import { googlechatDock, googlechatPlugin } from "./src/channel.js";
+import { handleGoogleChatWebhookRequest } from "./src/monitor.js";
+import { setGoogleChatRuntime } from "./src/runtime.js";
+
+const plugin = {
+  id: "googlechat",
+  name: "Google Chat",
+  description: "Clawdbot Google Chat channel plugin",
+  configSchema: emptyPluginConfigSchema(),
+  register(api: ClawdbotPluginApi) {
+    setGoogleChatRuntime(api.runtime);
+    api.registerChannel({ plugin: googlechatPlugin, dock: googlechatDock });
+    api.registerHttpHandler(handleGoogleChatWebhookRequest);
+  },
+};
+
+export default plugin;

extensions/googlechat/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@clawdbot/googlechat",
+  "version": "2026.1.22",
+  "type": "module",
+  "description": "Clawdbot Google Chat channel plugin",
+  "clawdbot": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "channel": {
+      "id": "googlechat",
+      "label": "Google Chat",
+      "selectionLabel": "Google Chat (Chat API)",
+      "detailLabel": "Google Chat",
+      "docsPath": "/channels/googlechat",
+      "docsLabel": "googlechat",
+      "blurb": "Google Workspace Chat app via HTTP webhooks.",
+      "aliases": [
+        "gchat",
+        "google-chat"
+      ],
+      "order": 55
+    },
+    "install": {
+      "npmSpec": "@clawdbot/googlechat",
+      "localPath": "extensions/googlechat",
+      "defaultChoice": "npm"
+    }
+  },
+  "dependencies": {
+    "clawdbot": "workspace:*",
+    "google-auth-library": "^10.5.0"
+  }
+}

extensions/googlechat/src/accounts.ts

@@ -0,0 +1,133 @@
+import type { ClawdbotConfig } from "clawdbot/plugin-sdk";
+import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "clawdbot/plugin-sdk";
+
+import type { GoogleChatAccountConfig, GoogleChatConfig } from "./types.config.js";
+
+export type GoogleChatCredentialSource = "file" | "inline" | "env" | "none";
+
+export type ResolvedGoogleChatAccount = {
+  accountId: string;
+  name?: string;
+  enabled: boolean;
+  config: GoogleChatAccountConfig;
+  credentialSource: GoogleChatCredentialSource;
+  credentials?: Record<string, unknown>;
+  credentialsFile?: string;
+};
+
+const ENV_SERVICE_ACCOUNT = "GOOGLE_CHAT_SERVICE_ACCOUNT";
+const ENV_SERVICE_ACCOUNT_FILE = "GOOGLE_CHAT_SERVICE_ACCOUNT_FILE";
+
+function listConfiguredAccountIds(cfg: ClawdbotConfig): string[] {
+  const accounts = (cfg.channels?.["googlechat"] as GoogleChatConfig | undefined)?.accounts;
+  if (!accounts || typeof accounts !== "object") return [];
+  return Object.keys(accounts).filter(Boolean);
+}
+
+export function listGoogleChatAccountIds(cfg: ClawdbotConfig): string[] {
+  const ids = listConfiguredAccountIds(cfg);
+  if (ids.length === 0) return [DEFAULT_ACCOUNT_ID];
+  return ids.sort((a, b) => a.localeCompare(b));
+}
+
+export function resolveDefaultGoogleChatAccountId(cfg: ClawdbotConfig): string {
+  const channel = cfg.channels?.["googlechat"] as GoogleChatConfig | undefined;
+  if (channel?.defaultAccount?.trim()) return channel.defaultAccount.trim();
+  const ids = listGoogleChatAccountIds(cfg);
+  if (ids.includes(DEFAULT_ACCOUNT_ID)) return DEFAULT_ACCOUNT_ID;
+  return ids[0] ?? DEFAULT_ACCOUNT_ID;
+}
+
+function resolveAccountConfig(
+  cfg: ClawdbotConfig,
+  accountId: string,
+): GoogleChatAccountConfig | undefined {
+  const accounts = (cfg.channels?.["googlechat"] as GoogleChatConfig | undefined)?.accounts;
+  if (!accounts || typeof accounts !== "object") return undefined;
+  return accounts[accountId] as GoogleChatAccountConfig | undefined;
+}
+
+function mergeGoogleChatAccountConfig(
+  cfg: ClawdbotConfig,
+  accountId: string,
+): GoogleChatAccountConfig {
+  const raw = (cfg.channels?.["googlechat"] ?? {}) as GoogleChatConfig;
+  const { accounts: _ignored, defaultAccount: _ignored2, ...base } = raw;
+  const account = resolveAccountConfig(cfg, accountId) ?? {};
+  return { ...base, ...account } as GoogleChatAccountConfig;
+}
+
+function parseServiceAccount(value: unknown): Record<string, unknown> | null {
+  if (value && typeof value === "object") return value as Record<string, unknown>;
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  if (!trimmed) return null;
+  try {
+    return JSON.parse(trimmed) as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+}
+
+function resolveCredentialsFromConfig(params: {
+  accountId: string;
+  account: GoogleChatAccountConfig;
+}): {
+  credentials?: Record<string, unknown>;
+  credentialsFile?: string;
+  source: GoogleChatCredentialSource;
+} {
+  const { account, accountId } = params;
+  const inline = parseServiceAccount(account.serviceAccount);
+  if (inline) {
+    return { credentials: inline, source: "inline" };
+  }
+
+  const file = account.serviceAccountFile?.trim();
+  if (file) {
+    return { credentialsFile: file, source: "file" };
+  }
+
+  if (accountId === DEFAULT_ACCOUNT_ID) {
+    const envJson = process.env[ENV_SERVICE_ACCOUNT];
+    const envInline = parseServiceAccount(envJson);
+    if (envInline) {
+      return { credentials: envInline, source: "env" };
+    }
+    const envFile = process.env[ENV_SERVICE_ACCOUNT_FILE]?.trim();
+    if (envFile) {
+      return { credentialsFile: envFile, source: "env" };
+    }
+  }
+
+  return { source: "none" };
+}
+
+export function resolveGoogleChatAccount(params: {
+  cfg: ClawdbotConfig;
+  accountId?: string | null;
+}): ResolvedGoogleChatAccount {
+  const accountId = normalizeAccountId(params.accountId);
+  const baseEnabled =
+    (params.cfg.channels?.["googlechat"] as GoogleChatConfig | undefined)?.enabled !== false;
+  const merged = mergeGoogleChatAccountConfig(params.cfg, accountId);
+  const accountEnabled = merged.enabled !== false;
+  const enabled = baseEnabled && accountEnabled;
+  const credentials = resolveCredentialsFromConfig({ accountId, account: merged });
+
+  return {
+    accountId,
+    name: merged.name?.trim() || undefined,
+    enabled,
+    config: merged,
+    credentialSource: credentials.source,
+    credentials: credentials.credentials,
+    credentialsFile: credentials.credentialsFile,
+  };
+}
+
+export function listEnabledGoogleChatAccounts(cfg: ClawdbotConfig): ResolvedGoogleChatAccount[] {
+  return listGoogleChatAccountIds(cfg)
+    .map((accountId) => resolveGoogleChatAccount({ cfg, accountId }))
+    .filter((account) => account.enabled);
+}

extensions/googlechat/src/actions.ts

@@ -0,0 +1,162 @@
+import type {
+  ChannelMessageActionAdapter,
+  ChannelMessageActionName,
+  ClawdbotConfig,
+} from "clawdbot/plugin-sdk";
+import {
+  createActionGate,
+  jsonResult,
+  readNumberParam,
+  readReactionParams,
+  readStringParam,
+} from "clawdbot/plugin-sdk";
+
+import { listEnabledGoogleChatAccounts, resolveGoogleChatAccount } from "./accounts.js";
+import {
+  createGoogleChatReaction,
+  deleteGoogleChatReaction,
+  listGoogleChatReactions,
+  sendGoogleChatMessage,
+  uploadGoogleChatAttachment,
+} from "./api.js";
+import { getGoogleChatRuntime } from "./runtime.js";
+import { resolveGoogleChatOutboundSpace } from "./targets.js";
+
+const providerId = "googlechat";
+
+function listEnabledAccounts(cfg: ClawdbotConfig) {
+  return listEnabledGoogleChatAccounts(cfg).filter(
+    (account) => account.enabled && account.credentialSource !== "none",
+  );
+}
+
+function isReactionsEnabled(accounts: ReturnType<typeof listEnabledAccounts>, cfg: ClawdbotConfig) {
+  for (const account of accounts) {
+    const gate = createActionGate(
+      (account.config.actions ?? (cfg.channels?.["googlechat"] as { actions?: unknown })?.actions) as Record<
+        string,
+        boolean | undefined
+      >,
+    );
+    if (gate("reactions")) return true;
+  }
+  return false;
+}
+
+function resolveAppUserNames(account: { config: { botUser?: string | null } }) {
+  return new Set(["users/app", account.config.botUser?.trim()].filter(Boolean) as string[]);
+}
+
+export const googlechatMessageActions: ChannelMessageActionAdapter = {
+  listActions: ({ cfg }) => {
+    const accounts = listEnabledAccounts(cfg as ClawdbotConfig);
+    if (accounts.length === 0) return [];
+    const actions = new Set<ChannelMessageActionName>([]);
+    actions.add("send");
+    if (isReactionsEnabled(accounts, cfg as ClawdbotConfig)) {
+      actions.add("react");
+      actions.add("reactions");
+    }
+    return Array.from(actions);
+  },
+  extractToolSend: ({ args }) => {
+    const action = typeof args.action === "string" ? args.action.trim() : "";
+    if (action !== "sendMessage") return null;
+    const to = typeof args.to === "string" ? args.to : undefined;
+    if (!to) return null;
+    const accountId = typeof args.accountId === "string" ? args.accountId.trim() : undefined;
+    return { to, accountId };
+  },
+  handleAction: async ({ action, params, cfg, accountId }) => {
+    const account = resolveGoogleChatAccount({
+      cfg: cfg as ClawdbotConfig,
+      accountId,
+    });
+    if (account.credentialSource === "none") {
+      throw new Error("Google Chat credentials are missing.");
+    }
+
+    if (action === "send") {
+      const to = readStringParam(params, "to", { required: true });
+      const content = readStringParam(params, "message", {
+        required: true,
+        allowEmpty: true,
+      });
+      const mediaUrl = readStringParam(params, "media", { trim: false });
+      const threadId = readStringParam(params, "threadId") ?? readStringParam(params, "replyTo");
+      const space = await resolveGoogleChatOutboundSpace({ account, target: to });
+
+      if (mediaUrl) {
+        const core = getGoogleChatRuntime();
+        const maxBytes = (account.config.mediaMaxMb ?? 20) * 1024 * 1024;
+        const loaded = await core.channel.media.fetchRemoteMedia(mediaUrl, { maxBytes });
+        const upload = await uploadGoogleChatAttachment({
+          account,
+          space,
+          filename: loaded.filename ?? "attachment",
+          buffer: loaded.buffer,
+          contentType: loaded.contentType,
+        });
+        await sendGoogleChatMessage({
+          account,
+          space,
+          text: content,
+          thread: threadId ?? undefined,
+          attachments: upload.attachmentUploadToken
+            ? [{ attachmentUploadToken: upload.attachmentUploadToken, contentName: loaded.filename }]
+            : undefined,
+        });
+        return jsonResult({ ok: true, to: space });
+      }
+
+      await sendGoogleChatMessage({
+        account,
+        space,
+        text: content,
+        thread: threadId ?? undefined,
+      });
+      return jsonResult({ ok: true, to: space });
+    }
+
+    if (action === "react") {
+      const messageName = readStringParam(params, "messageId", { required: true });
+      const { emoji, remove, isEmpty } = readReactionParams(params, {
+        removeErrorMessage: "Emoji is required to remove a Google Chat reaction.",
+      });
+      if (remove || isEmpty) {
+        const reactions = await listGoogleChatReactions({ account, messageName });
+        const appUsers = resolveAppUserNames(account);
+        const toRemove = reactions.filter((reaction) => {
+          const userName = reaction.user?.name?.trim();
+          if (appUsers.size > 0 && !appUsers.has(userName ?? "")) return false;
+          if (emoji) return reaction.emoji?.unicode === emoji;
+          return true;
+        });
+        for (const reaction of toRemove) {
+          if (!reaction.name) continue;
+          await deleteGoogleChatReaction({ account, reactionName: reaction.name });
+        }
+        return jsonResult({ ok: true, removed: toRemove.length });
+      }
+      const reaction = await createGoogleChatReaction({
+        account,
+        messageName,
+        emoji,
+      });
+      return jsonResult({ ok: true, reaction });
+    }
+
+    if (action === "reactions") {
+      const messageName = readStringParam(params, "messageId", { required: true });
+      const limit = readNumberParam(params, "limit", { integer: true });
+      const reactions = await listGoogleChatReactions({
+        account,
+        messageName,
+        limit: limit ?? undefined,
+      });
+      return jsonResult({ ok: true, reactions });
+    }
+
+    throw new Error(`Action ${action} is not supported for provider ${providerId}.`);
+  },
+};

extensions/googlechat/src/api.ts

@@ -0,0 +1,207 @@
+import crypto from "node:crypto";
+
+import type { ResolvedGoogleChatAccount } from "./accounts.js";
+import { getGoogleChatAccessToken } from "./auth.js";
+import type { GoogleChatReaction } from "./types.js";
+
+const CHAT_API_BASE = "https://chat.googleapis.com/v1";
+const CHAT_UPLOAD_BASE = "https://chat.googleapis.com/upload/v1";
+
+async function fetchJson<T>(
+  account: ResolvedGoogleChatAccount,
+  url: string,
+  init: RequestInit,
+): Promise<T> {
+  const token = await getGoogleChatAccessToken(account);
+  const res = await fetch(url, {
+    ...init,
+    headers: {
+      Authorization: `Bearer ${token}`,
+      "Content-Type": "application/json",
+      ...(init.headers ?? {}),
+    },
+  });
+  if (!res.ok) {
+    const text = await res.text().catch(() => "");
+    throw new Error(`Google Chat API ${res.status}: ${text || res.statusText}`);
+  }
+  return (await res.json()) as T;
+}
+
+async function fetchOk(
+  account: ResolvedGoogleChatAccount,
+  url: string,
+  init: RequestInit,
+): Promise<void> {
+  const token = await getGoogleChatAccessToken(account);
+  const res = await fetch(url, {
+    ...init,
+    headers: {
+      Authorization: `Bearer ${token}`,
+      ...(init.headers ?? {}),
+    },
+  });
+  if (!res.ok) {
+    const text = await res.text().catch(() => "");
+    throw new Error(`Google Chat API ${res.status}: ${text || res.statusText}`);
+  }
+}
+
+async function fetchBuffer(
+  account: ResolvedGoogleChatAccount,
+  url: string,
+  init?: RequestInit,
+): Promise<{ buffer: Buffer; contentType?: string }> {
+  const token = await getGoogleChatAccessToken(account);
+  const res = await fetch(url, {
+    ...init,
+    headers: {
+      Authorization: `Bearer ${token}`,
+      ...(init?.headers ?? {}),
+    },
+  });
+  if (!res.ok) {
+    const text = await res.text().catch(() => "");
+    throw new Error(`Google Chat API ${res.status}: ${text || res.statusText}`);
+  }
+  const buffer = Buffer.from(await res.arrayBuffer());
+  const contentType = res.headers.get("content-type") ?? undefined;
+  return { buffer, contentType };
+}
+
+export async function sendGoogleChatMessage(params: {
+  account: ResolvedGoogleChatAccount;
+  space: string;
+  text?: string;
+  thread?: string;
+  attachments?: Array<{ attachmentUploadToken: string; contentName?: string }>;
+}): Promise<{ messageName?: string } | null> {
+  const { account, space, text, thread, attachments } = params;
+  const body: Record<string, unknown> = {};
+  if (text) body.text = text;
+  if (thread) body.thread = { name: thread };
+  if (attachments && attachments.length > 0) {
+    body.attachment = attachments.map((item) => ({
+      attachmentDataRef: { attachmentUploadToken: item.attachmentUploadToken },
+      ...(item.contentName ? { contentName: item.contentName } : {}),
+    }));
+  }
+  const url = `${CHAT_API_BASE}/${space}/messages`;
+  const result = await fetchJson<{ name?: string }>(account, url, {
+    method: "POST",
+    body: JSON.stringify(body),
+  });
+  return result ? { messageName: result.name } : null;
+}
+
+export async function uploadGoogleChatAttachment(params: {
+  account: ResolvedGoogleChatAccount;
+  space: string;
+  filename: string;
+  buffer: Buffer;
+  contentType?: string;
+}): Promise<{ attachmentUploadToken?: string }> {
+  const { account, space, filename, buffer, contentType } = params;
+  const boundary = `clawdbot-${crypto.randomUUID()}`;
+  const metadata = JSON.stringify({ filename });
+  const header = `--${boundary}\r\nContent-Type: application/json; charset=UTF-8\r\n\r\n${metadata}\r\n`;
+  const mediaHeader = `--${boundary}\r\nContent-Type: ${contentType ?? "application/octet-stream"}\r\n\r\n`;
+  const footer = `\r\n--${boundary}--\r\n`;
+  const body = Buffer.concat([
+    Buffer.from(header, "utf8"),
+    Buffer.from(mediaHeader, "utf8"),
+    buffer,
+    Buffer.from(footer, "utf8"),
+  ]);
+
+  const token = await getGoogleChatAccessToken(account);
+  const url = `${CHAT_UPLOAD_BASE}/${space}/attachments:upload?uploadType=multipart`;
+  const res = await fetch(url, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${token}`,
+      "Content-Type": `multipart/related; boundary=${boundary}`,
+    },
+    body,
+  });
+  if (!res.ok) {
+    const text = await res.text().catch(() => "");
+    throw new Error(`Google Chat upload ${res.status}: ${text || res.statusText}`);
+  }
+  const payload = (await res.json()) as {
+    attachmentDataRef?: { attachmentUploadToken?: string };
+  };
+  return { attachmentUploadToken: payload.attachmentDataRef?.attachmentUploadToken };
+}
+
+export async function downloadGoogleChatMedia(params: {
+  account: ResolvedGoogleChatAccount;
+  resourceName: string;
+}): Promise<{ buffer: Buffer; contentType?: string }> {
+  const { account, resourceName } = params;
+  const url = `${CHAT_API_BASE}/media/${resourceName}?alt=media`;
+  return await fetchBuffer(account, url);
+}
+
+export async function createGoogleChatReaction(params: {
+  account: ResolvedGoogleChatAccount;
+  messageName: string;
+  emoji: string;
+}): Promise<GoogleChatReaction> {
+  const { account, messageName, emoji } = params;
+  const url = `${CHAT_API_BASE}/${messageName}/reactions`;
+  return await fetchJson<GoogleChatReaction>(account, url, {
+    method: "POST",
+    body: JSON.stringify({ emoji: { unicode: emoji } }),
+  });
+}
+
+export async function listGoogleChatReactions(params: {
+  account: ResolvedGoogleChatAccount;
+  messageName: string;
+  limit?: number;
+}): Promise<GoogleChatReaction[]> {
+  const { account, messageName, limit } = params;
+  const url = new URL(`${CHAT_API_BASE}/${messageName}/reactions`);
+  if (limit && limit > 0) url.searchParams.set("pageSize", String(limit));
+  const result = await fetchJson<{ reactions?: GoogleChatReaction[] }>(account, url.toString(), {
+    method: "GET",
+  });
+  return result.reactions ?? [];
+}
+
+export async function deleteGoogleChatReaction(params: {
+  account: ResolvedGoogleChatAccount;
+  reactionName: string;
+}): Promise<void> {
+  const { account, reactionName } = params;
+  const url = `${CHAT_API_BASE}/${reactionName}`;
+  await fetchOk(account, url, { method: "DELETE" });
+}
+
+export async function findGoogleChatDirectMessage(params: {
+  account: ResolvedGoogleChatAccount;
+  userName: string;
+}): Promise<{ name?: string; displayName?: string } | null> {
+  const { account, userName } = params;
+  const url = new URL(`${CHAT_API_BASE}/spaces:findDirectMessage`);
+  url.searchParams.set("name", userName);
+  return await fetchJson<{ name?: string; displayName?: string }>(account, url.toString(), {
+    method: "GET",
+  });
+}
+
+export async function probeGoogleChat(account: ResolvedGoogleChatAccount): Promise<{
+  ok: boolean;
+  status?: number;
+  error?: string;
+}> {
+  try {
+    const url = new URL(`${CHAT_API_BASE}/spaces`);
+    url.searchParams.set("pageSize", "1");
+    await fetchJson<Record<string, unknown>>(account, url.toString(), { method: "GET" });
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, error: err instanceof Error ? err.message : String(err) };
+  }
+}

extensions/googlechat/src/auth.ts

@@ -0,0 +1,110 @@
+import { GoogleAuth, OAuth2Client } from "google-auth-library";
+
+import type { ResolvedGoogleChatAccount } from "./accounts.js";
+
+const CHAT_SCOPE = "https://www.googleapis.com/auth/chat.bot";
+const CHAT_ISSUER = "chat@system.gserviceaccount.com";
+const CHAT_CERTS_URL =
+  "https://www.googleapis.com/service_accounts/v1/metadata/x509/chat@system.gserviceaccount.com";
+
+const authCache = new Map<string, { key: string; auth: GoogleAuth }>();
+const verifyClient = new OAuth2Client();
+
+let cachedCerts: { fetchedAt: number; certs: Record<string, string> } | null = null;
+
+function buildAuthKey(account: ResolvedGoogleChatAccount): string {
+  if (account.credentialsFile) return `file:${account.credentialsFile}`;
+  if (account.credentials) return `inline:${JSON.stringify(account.credentials)}`;
+  return "none";
+}
+
+function getAuthInstance(account: ResolvedGoogleChatAccount): GoogleAuth {
+  const key = buildAuthKey(account);
+  const cached = authCache.get(account.accountId);
+  if (cached && cached.key === key) return cached.auth;
+
+  if (account.credentialsFile) {
+    const auth = new GoogleAuth({ keyFile: account.credentialsFile, scopes: [CHAT_SCOPE] });
+    authCache.set(account.accountId, { key, auth });
+    return auth;
+  }
+
+  if (account.credentials) {
+    const auth = new GoogleAuth({ credentials: account.credentials, scopes: [CHAT_SCOPE] });
+    authCache.set(account.accountId, { key, auth });
+    return auth;
+  }
+
+  const auth = new GoogleAuth({ scopes: [CHAT_SCOPE] });
+  authCache.set(account.accountId, { key, auth });
+  return auth;
+}
+
+export async function getGoogleChatAccessToken(
+  account: ResolvedGoogleChatAccount,
+): Promise<string> {
+  const auth = getAuthInstance(account);
+  const client = await auth.getClient();
+  const access = await client.getAccessToken();
+  const token = typeof access === "string" ? access : access?.token;
+  if (!token) {
+    throw new Error("Missing Google Chat access token");
+  }
+  return token;
+}
+
+async function fetchChatCerts(): Promise<Record<string, string>> {
+  const now = Date.now();
+  if (cachedCerts && now - cachedCerts.fetchedAt < 10 * 60 * 1000) {
+    return cachedCerts.certs;
+  }
+  const res = await fetch(CHAT_CERTS_URL);
+  if (!res.ok) {
+    throw new Error(`Failed to fetch Chat certs (${res.status})`);
+  }
+  const certs = (await res.json()) as Record<string, string>;
+  cachedCerts = { fetchedAt: now, certs };
+  return certs;
+}
+
+export type GoogleChatAudienceType = "app-url" | "project-number";
+
+export async function verifyGoogleChatRequest(params: {
+  bearer?: string | null;
+  audienceType?: GoogleChatAudienceType | null;
+  audience?: string | null;
+}): Promise<{ ok: boolean; reason?: string }> {
+  const bearer = params.bearer?.trim();
+  if (!bearer) return { ok: false, reason: "missing token" };
+  const audience = params.audience?.trim();
+  if (!audience) return { ok: false, reason: "missing audience" };
+  const audienceType = params.audienceType ?? null;
+
+  if (audienceType === "app-url") {
+    try {
+      const ticket = await verifyClient.verifyIdToken({
+        idToken: bearer,
+        audience,
+      });
+      const payload = ticket.getPayload();
+      const ok = Boolean(payload?.email_verified) && payload?.email === CHAT_ISSUER;
+      return ok ? { ok: true } : { ok: false, reason: "invalid issuer" };
+    } catch (err) {
+      return { ok: false, reason: err instanceof Error ? err.message : "invalid token" };
+    }
+  }
+
+  if (audienceType === "project-number") {
+    try {
+      const certs = await fetchChatCerts();
+      await verifyClient.verifySignedJwtWithCertsAsync(bearer, certs, audience, [CHAT_ISSUER]);
+      return { ok: true };
+    } catch (err) {
+      return { ok: false, reason: err instanceof Error ? err.message : "invalid token" };
+    }
+  }
+
+  return { ok: false, reason: "unsupported audience type" };
+}
+
+export const GOOGLE_CHAT_SCOPE = CHAT_SCOPE;

extensions/googlechat/src/channel.ts

@@ -0,0 +1,578 @@
+import {
+  applyAccountNameToChannelSection,
+  buildChannelConfigSchema,
+  DEFAULT_ACCOUNT_ID,
+  deleteAccountFromConfigSection,
+  formatPairingApproveHint,
+  getChatChannelMeta,
+  migrateBaseNameToDefaultAccount,
+  missingTargetError,
+  normalizeAccountId,
+  PAIRING_APPROVED_MESSAGE,
+  resolveChannelMediaMaxBytes,
+  resolveGoogleChatGroupRequireMention,
+  setAccountEnabledInConfigSection,
+  type ChannelDock,
+  type ChannelMessageActionAdapter,
+  type ChannelPlugin,
+  type ClawdbotConfig,
+} from "clawdbot/plugin-sdk";
+import { GoogleChatConfigSchema } from "clawdbot/plugin-sdk";
+
+import {
+  listGoogleChatAccountIds,
+  resolveDefaultGoogleChatAccountId,
+  resolveGoogleChatAccount,
+  type ResolvedGoogleChatAccount,
+} from "./accounts.js";
+import { googlechatMessageActions } from "./actions.js";
+import { sendGoogleChatMessage, uploadGoogleChatAttachment, probeGoogleChat } from "./api.js";
+import { googlechatOnboardingAdapter } from "./onboarding.js";
+import { getGoogleChatRuntime } from "./runtime.js";
+import { resolveGoogleChatWebhookPath, startGoogleChatMonitor } from "./monitor.js";
+import {
+  isGoogleChatSpaceTarget,
+  isGoogleChatUserTarget,
+  normalizeGoogleChatTarget,
+  resolveGoogleChatOutboundSpace,
+} from "./targets.js";
+
+const meta = getChatChannelMeta("googlechat");
+
+const formatAllowFromEntry = (entry: string) =>
+  entry
+    .trim()
+    .replace(/^(googlechat|gchat):/i, "")
+    .replace(/^users\//i, "")
+    .toLowerCase();
+
+export const googlechatDock: ChannelDock = {
+  id: "googlechat",
+  capabilities: {
+    chatTypes: ["direct", "group", "thread"],
+    reactions: true,
+    media: true,
+    threads: true,
+    blockStreaming: true,
+  },
+  outbound: { textChunkLimit: 4000 },
+  config: {
+    resolveAllowFrom: ({ cfg, accountId }) =>
+      (resolveGoogleChatAccount({ cfg: cfg as ClawdbotConfig, accountId }).config.dm?.allowFrom ??
+        []
+      ).map((entry) => String(entry)),
+    formatAllowFrom: ({ allowFrom }) =>
+      allowFrom
+        .map((entry) => String(entry))
+        .filter(Boolean)
+        .map(formatAllowFromEntry),
+  },
+  groups: {
+    resolveRequireMention: resolveGoogleChatGroupRequireMention,
+  },
+  threading: {
+    resolveReplyToMode: ({ cfg }) => cfg.channels?.["googlechat"]?.replyToMode ?? "off",
+    buildToolContext: ({ context, hasRepliedRef }) => {
+      const threadId = context.MessageThreadId ?? context.ReplyToId;
+      return {
+        currentChannelId: context.To?.trim() || undefined,
+        currentThreadTs: threadId != null ? String(threadId) : undefined,
+        hasRepliedRef,
+      };
+    },
+  },
+};
+
+const googlechatActions: ChannelMessageActionAdapter = {
+  listActions: (ctx) => googlechatMessageActions.listActions?.(ctx) ?? [],
+  extractToolSend: (ctx) => googlechatMessageActions.extractToolSend?.(ctx) ?? null,
+  handleAction: async (ctx) => {
+    if (!googlechatMessageActions.handleAction) {
+      throw new Error("Google Chat actions are not available.");
+    }
+    return await googlechatMessageActions.handleAction(ctx);
+  },
+};
+
+export const googlechatPlugin: ChannelPlugin<ResolvedGoogleChatAccount> = {
+  id: "googlechat",
+  meta: { ...meta },
+  onboarding: googlechatOnboardingAdapter,
+  pairing: {
+    idLabel: "googlechatUserId",
+    normalizeAllowEntry: (entry) => formatAllowFromEntry(entry),
+    notifyApproval: async ({ cfg, id }) => {
+      const account = resolveGoogleChatAccount({ cfg: cfg as ClawdbotConfig });
+      if (account.credentialSource === "none") return;
+      const user = normalizeGoogleChatTarget(id) ?? id;
+      const target = isGoogleChatUserTarget(user) ? user : `users/${user}`;
+      const space = await resolveGoogleChatOutboundSpace({ account, target });
+      await sendGoogleChatMessage({
+        account,
+        space,
+        text: PAIRING_APPROVED_MESSAGE,
+      });
+    },
+  },
+  capabilities: {
+    chatTypes: ["direct", "group", "thread"],
+    reactions: true,
+    threads: true,
+    media: true,
+    nativeCommands: false,
+    blockStreaming: true,
+  },
+  streaming: {
+    blockStreamingCoalesceDefaults: { minChars: 1500, idleMs: 1000 },
+  },
+  reload: { configPrefixes: ["channels.googlechat"] },
+  configSchema: buildChannelConfigSchema(GoogleChatConfigSchema),
+  config: {
+    listAccountIds: (cfg) => listGoogleChatAccountIds(cfg as ClawdbotConfig),
+    resolveAccount: (cfg, accountId) =>
+      resolveGoogleChatAccount({ cfg: cfg as ClawdbotConfig, accountId }),
+    defaultAccountId: (cfg) => resolveDefaultGoogleChatAccountId(cfg as ClawdbotConfig),
+    setAccountEnabled: ({ cfg, accountId, enabled }) =>
+      setAccountEnabledInConfigSection({
+        cfg: cfg as ClawdbotConfig,
+        sectionKey: "googlechat",
+        accountId,
+        enabled,
+        allowTopLevel: true,
+      }),
+    deleteAccount: ({ cfg, accountId }) =>
+      deleteAccountFromConfigSection({
+        cfg: cfg as ClawdbotConfig,
+        sectionKey: "googlechat",
+        accountId,
+        clearBaseFields: [
+          "serviceAccount",
+          "serviceAccountFile",
+          "audienceType",
+          "audience",
+          "webhookPath",
+          "webhookUrl",
+          "botUser",
+          "name",
+        ],
+      }),
+    isConfigured: (account) => account.credentialSource !== "none",
+    describeAccount: (account) => ({
+      accountId: account.accountId,
+      name: account.name,
+      enabled: account.enabled,
+      configured: account.credentialSource !== "none",
+      credentialSource: account.credentialSource,
+    }),
+    resolveAllowFrom: ({ cfg, accountId }) =>
+      (resolveGoogleChatAccount({
+        cfg: cfg as ClawdbotConfig,
+        accountId,
+      }).config.dm?.allowFrom ?? []
+      ).map((entry) => String(entry)),
+    formatAllowFrom: ({ allowFrom }) =>
+      allowFrom
+        .map((entry) => String(entry))
+        .filter(Boolean)
+        .map(formatAllowFromEntry),
+  },
+  security: {
+    resolveDmPolicy: ({ cfg, accountId, account }) => {
+      const resolvedAccountId = accountId ?? account.accountId ?? DEFAULT_ACCOUNT_ID;
+      const useAccountPath = Boolean(
+        (cfg as ClawdbotConfig).channels?.["googlechat"]?.accounts?.[resolvedAccountId],
+      );
+      const allowFromPath = useAccountPath
+        ? `channels.googlechat.accounts.${resolvedAccountId}.dm.`
+        : "channels.googlechat.dm.";
+      return {
+        policy: account.config.dm?.policy ?? "pairing",
+        allowFrom: account.config.dm?.allowFrom ?? [],
+        allowFromPath,
+        approveHint: formatPairingApproveHint("googlechat"),
+        normalizeEntry: (raw) => formatAllowFromEntry(raw),
+      };
+    },
+    collectWarnings: ({ account, cfg }) => {
+      const warnings: string[] = [];
+      const defaultGroupPolicy = cfg.channels?.defaults?.groupPolicy;
+      const groupPolicy = account.config.groupPolicy ?? defaultGroupPolicy ?? "allowlist";
+      if (groupPolicy === "open") {
+        warnings.push(
+          `- Google Chat spaces: groupPolicy="open" allows any space to trigger (mention-gated). Set channels.googlechat.groupPolicy="allowlist" and configure channels.googlechat.groups.`,
+        );
+      }
+      if (account.config.dm?.policy === "open") {
+        warnings.push(
+          `- Google Chat DMs are open to anyone. Set channels.googlechat.dm.policy="pairing" or "allowlist".`,
+        );
+      }
+      return warnings;
+    },
+  },
+  groups: {
+    resolveRequireMention: resolveGoogleChatGroupRequireMention,
+  },
+  threading: {
+    resolveReplyToMode: ({ cfg }) => cfg.channels?.["googlechat"]?.replyToMode ?? "off",
+  },
+  messaging: {
+    normalizeTarget: normalizeGoogleChatTarget,
+    targetResolver: {
+      looksLikeId: (raw, normalized) => {
+        const value = normalized ?? raw.trim();
+        return isGoogleChatSpaceTarget(value) || isGoogleChatUserTarget(value);
+      },
+      hint: "<spaces/{space}|users/{user}>",
+    },
+  },
+  directory: {
+    self: async () => null,
+    listPeers: async ({ cfg, accountId, query, limit }) => {
+      const account = resolveGoogleChatAccount({
+        cfg: cfg as ClawdbotConfig,
+        accountId,
+      });
+      const q = query?.trim().toLowerCase() || "";
+      const allowFrom = account.config.dm?.allowFrom ?? [];
+      const peers = Array.from(
+        new Set(
+          allowFrom
+            .map((entry) => String(entry).trim())
+            .filter((entry) => Boolean(entry) && entry !== "*")
+            .map((entry) => normalizeGoogleChatTarget(entry) ?? entry),
+        ),
+      )
+        .filter((id) => (q ? id.toLowerCase().includes(q) : true))
+        .slice(0, limit && limit > 0 ? limit : undefined)
+        .map((id) => ({ kind: "user", id }) as const);
+      return peers;
+    },
+    listGroups: async ({ cfg, accountId, query, limit }) => {
+      const account = resolveGoogleChatAccount({
+        cfg: cfg as ClawdbotConfig,
+        accountId,
+      });
+      const groups = account.config.groups ?? {};
+      const q = query?.trim().toLowerCase() || "";
+      const entries = Object.keys(groups)
+        .filter((key) => key && key !== "*")
+        .filter((key) => (q ? key.toLowerCase().includes(q) : true))
+        .slice(0, limit && limit > 0 ? limit : undefined)
+        .map((id) => ({ kind: "group", id }) as const);
+      return entries;
+    },
+  },
+  resolver: {
+    resolveTargets: async ({ inputs, kind }) => {
+      const resolved = inputs.map((input) => {
+        const normalized = normalizeGoogleChatTarget(input);
+        if (!normalized) {
+          return { input, resolved: false, note: "empty target" };
+        }
+        if (kind === "user" && isGoogleChatUserTarget(normalized)) {
+          return { input, resolved: true, id: normalized };
+        }
+        if (kind === "group" && isGoogleChatSpaceTarget(normalized)) {
+          return { input, resolved: true, id: normalized };
+        }
+        return {
+          input,
+          resolved: false,
+          note: "use spaces/{space} or users/{user}",
+        };
+      });
+      return resolved;
+    },
+  },
+  actions: googlechatActions,
+  setup: {
+    resolveAccountId: ({ accountId }) => normalizeAccountId(accountId),
+    applyAccountName: ({ cfg, accountId, name }) =>
+      applyAccountNameToChannelSection({
+        cfg: cfg as ClawdbotConfig,
+        channelKey: "googlechat",
+        accountId,
+        name,
+      }),
+    validateInput: ({ accountId, input }) => {
+      if (input.useEnv && accountId !== DEFAULT_ACCOUNT_ID) {
+        return "GOOGLE_CHAT_SERVICE_ACCOUNT env vars can only be used for the default account.";
+      }
+      if (!input.useEnv && !input.token && !input.tokenFile) {
+        return "Google Chat requires --token (service account JSON) or --token-file.";
+      }
+      return null;
+    },
+    applyAccountConfig: ({ cfg, accountId, input }) => {
+      const namedConfig = applyAccountNameToChannelSection({
+        cfg: cfg as ClawdbotConfig,
+        channelKey: "googlechat",
+        accountId,
+        name: input.name,
+      });
+      const next =
+        accountId !== DEFAULT_ACCOUNT_ID
+          ? migrateBaseNameToDefaultAccount({
+              cfg: namedConfig as ClawdbotConfig,
+              channelKey: "googlechat",
+            })
+          : namedConfig;
+      const patch = input.useEnv
+        ? {}
+        : input.tokenFile
+          ? { serviceAccountFile: input.tokenFile }
+          : input.token
+            ? { serviceAccount: input.token }
+            : {};
+      const audienceType = input.audienceType?.trim();
+      const audience = input.audience?.trim();
+      const webhookPath = input.webhookPath?.trim();
+      const webhookUrl = input.webhookUrl?.trim();
+      const configPatch = {
+        ...patch,
+        ...(audienceType ? { audienceType } : {}),
+        ...(audience ? { audience } : {}),
+        ...(webhookPath ? { webhookPath } : {}),
+        ...(webhookUrl ? { webhookUrl } : {}),
+      };
+      if (accountId === DEFAULT_ACCOUNT_ID) {
+        return {
+          ...next,
+          channels: {
+            ...next.channels,
+            "googlechat": {
+              ...(next.channels?.["googlechat"] ?? {}),
+              enabled: true,
+              ...configPatch,
+            },
+          },
+        } as ClawdbotConfig;
+      }
+      return {
+        ...next,
+        channels: {
+          ...next.channels,
+          "googlechat": {
+            ...(next.channels?.["googlechat"] ?? {}),
+            enabled: true,
+            accounts: {
+              ...(next.channels?.["googlechat"]?.accounts ?? {}),
+              [accountId]: {
+                ...(next.channels?.["googlechat"]?.accounts?.[accountId] ?? {}),
+                enabled: true,
+                ...configPatch,
+              },
+            },
+          },
+        },
+      } as ClawdbotConfig;
+    },
+  },
+  outbound: {
+    deliveryMode: "direct",
+    chunker: (text, limit) =>
+      getGoogleChatRuntime().channel.text.chunkMarkdownText(text, limit),
+    textChunkLimit: 4000,
+    resolveTarget: ({ to, allowFrom, mode }) => {
+      const trimmed = to?.trim() ?? "";
+      const allowListRaw = (allowFrom ?? []).map((entry) => String(entry).trim()).filter(Boolean);
+      const allowList = allowListRaw
+        .filter((entry) => entry !== "*")
+        .map((entry) => normalizeGoogleChatTarget(entry))
+        .filter((entry): entry is string => Boolean(entry));
+
+      if (trimmed) {
+        const normalized = normalizeGoogleChatTarget(trimmed);
+        if (!normalized) {
+          if ((mode === "implicit" || mode === "heartbeat") && allowList.length > 0) {
+            return { ok: true, to: allowList[0] };
+          }
+          return {
+            ok: false,
+            error: missingTargetError(
+              "Google Chat",
+              "<spaces/{space}|users/{user}> or channels.googlechat.dm.allowFrom[0]",
+            ),
+          };
+        }
+        return { ok: true, to: normalized };
+      }
+
+      if (allowList.length > 0) {
+        return { ok: true, to: allowList[0] };
+      }
+      return {
+        ok: false,
+        error: missingTargetError(
+          "Google Chat",
+          "<spaces/{space}|users/{user}> or channels.googlechat.dm.allowFrom[0]",
+        ),
+      };
+    },
+    sendText: async ({ cfg, to, text, accountId, replyToId, threadId }) => {
+      const account = resolveGoogleChatAccount({
+        cfg: cfg as ClawdbotConfig,
+        accountId,
+      });
+      const space = await resolveGoogleChatOutboundSpace({ account, target: to });
+      const thread = (threadId ?? replyToId ?? undefined) as string | undefined;
+      const result = await sendGoogleChatMessage({
+        account,
+        space,
+        text,
+        thread,
+      });
+      return {
+        channel: "googlechat",
+        messageId: result?.messageName ?? "",
+        chatId: space,
+      };
+    },
+    sendMedia: async ({ cfg, to, text, mediaUrl, accountId, replyToId, threadId }) => {
+      if (!mediaUrl) {
+        throw new Error("Google Chat mediaUrl is required.");
+      }
+      const account = resolveGoogleChatAccount({
+        cfg: cfg as ClawdbotConfig,
+        accountId,
+      });
+      const space = await resolveGoogleChatOutboundSpace({ account, target: to });
+      const thread = (threadId ?? replyToId ?? undefined) as string | undefined;
+      const runtime = getGoogleChatRuntime();
+      const maxBytes = resolveChannelMediaMaxBytes({
+        cfg: cfg as ClawdbotConfig,
+        resolveChannelLimitMb: ({ cfg, accountId }) =>
+          (cfg.channels?.["googlechat"] as { accounts?: Record<string, { mediaMaxMb?: number }>; mediaMaxMb?: number } | undefined)
+            ?.accounts?.[accountId]?.mediaMaxMb ??
+          (cfg.channels?.["googlechat"] as { mediaMaxMb?: number } | undefined)?.mediaMaxMb,
+        accountId,
+      });
+      const loaded = await runtime.channel.media.fetchRemoteMedia(mediaUrl, {
+        maxBytes: maxBytes ?? (account.config.mediaMaxMb ?? 20) * 1024 * 1024,
+      });
+      const upload = await uploadGoogleChatAttachment({
+        account,
+        space,
+        filename: loaded.filename ?? "attachment",
+        buffer: loaded.buffer,
+        contentType: loaded.contentType,
+      });
+      const result = await sendGoogleChatMessage({
+        account,
+        space,
+        text,
+        thread,
+        attachments: upload.attachmentUploadToken
+          ? [{ attachmentUploadToken: upload.attachmentUploadToken, contentName: loaded.filename }]
+          : undefined,
+      });
+      return {
+        channel: "googlechat",
+        messageId: result?.messageName ?? "",
+        chatId: space,
+      };
+    },
+  },
+  status: {
+    defaultRuntime: {
+      accountId: DEFAULT_ACCOUNT_ID,
+      running: false,
+      lastStartAt: null,
+      lastStopAt: null,
+      lastError: null,
+    },
+    collectStatusIssues: (accounts) =>
+      accounts.flatMap((entry) => {
+        const accountId = String(entry.accountId ?? DEFAULT_ACCOUNT_ID);
+        const enabled = entry.enabled !== false;
+        const configured = entry.configured === true;
+        if (!enabled || !configured) return [];
+        const issues = [];
+        if (!entry.audience) {
+          issues.push({
+            channel: "googlechat",
+            accountId,
+            kind: "config",
+            message: "Google Chat audience is missing (set channels.googlechat.audience).",
+            fix: "Set channels.googlechat.audienceType and channels.googlechat.audience.",
+          });
+        }
+        if (!entry.audienceType) {
+          issues.push({
+            channel: "googlechat",
+            accountId,
+            kind: "config",
+            message: "Google Chat audienceType is missing (app-url or project-number).",
+            fix: "Set channels.googlechat.audienceType and channels.googlechat.audience.",
+          });
+        }
+        return issues;
+      }),
+    buildChannelSummary: ({ snapshot }) => ({
+      configured: snapshot.configured ?? false,
+      credentialSource: snapshot.credentialSource ?? "none",
+      audienceType: snapshot.audienceType ?? null,
+      audience: snapshot.audience ?? null,
+      webhookPath: snapshot.webhookPath ?? null,
+      webhookUrl: snapshot.webhookUrl ?? null,
+      running: snapshot.running ?? false,
+      lastStartAt: snapshot.lastStartAt ?? null,
+      lastStopAt: snapshot.lastStopAt ?? null,
+      lastError: snapshot.lastError ?? null,
+      probe: snapshot.probe,
+      lastProbeAt: snapshot.lastProbeAt ?? null,
+    }),
+    probeAccount: async ({ account }) => probeGoogleChat(account),
+    buildAccountSnapshot: ({ account, runtime, probe }) => ({
+      accountId: account.accountId,
+      name: account.name,
+      enabled: account.enabled,
+      configured: account.credentialSource !== "none",
+      credentialSource: account.credentialSource,
+      audienceType: account.config.audienceType,
+      audience: account.config.audience,
+      webhookPath: account.config.webhookPath,
+      webhookUrl: account.config.webhookUrl,
+      running: runtime?.running ?? false,
+      lastStartAt: runtime?.lastStartAt ?? null,
+      lastStopAt: runtime?.lastStopAt ?? null,
+      lastError: runtime?.lastError ?? null,
+      lastInboundAt: runtime?.lastInboundAt ?? null,
+      lastOutboundAt: runtime?.lastOutboundAt ?? null,
+      dmPolicy: account.config.dm?.policy ?? "pairing",
+      probe,
+    }),
+  },
+  gateway: {
+    startAccount: async (ctx) => {
+      const account = ctx.account;
+      ctx.log?.info(`[${account.accountId}] starting Google Chat webhook`);
+      ctx.setStatus({
+        accountId: account.accountId,
+        running: true,
+        lastStartAt: Date.now(),
+        webhookPath: resolveGoogleChatWebhookPath({ account }),
+        audienceType: account.config.audienceType,
+        audience: account.config.audience,
+      });
+      const unregister = await startGoogleChatMonitor({
+        account,
+        config: ctx.cfg as ClawdbotConfig,
+        runtime: ctx.runtime,
+        abortSignal: ctx.abortSignal,
+        webhookPath: account.config.webhookPath,
+        webhookUrl: account.config.webhookUrl,
+        statusSink: (patch) => ctx.setStatus({ accountId: account.accountId, ...patch }),
+      });
+      return () => {
+        unregister?.();
+        ctx.setStatus({
+          accountId: account.accountId,
+          running: false,
+          lastStopAt: Date.now(),
+        });
+      };
+    },
+  },
+};

extensions/googlechat/src/monitor.ts

@@ -0,0 +1,751 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+
+import type { ClawdbotConfig } from "clawdbot/plugin-sdk";
+import { resolveMentionGatingWithBypass } from "clawdbot/plugin-sdk";
+
+import {
+  type ResolvedGoogleChatAccount
+} from "./accounts.js";
+import {
+  downloadGoogleChatMedia,
+  sendGoogleChatMessage,
+} from "./api.js";
+import { verifyGoogleChatRequest, type GoogleChatAudienceType } from "./auth.js";
+import { getGoogleChatRuntime } from "./runtime.js";
+import type { GoogleChatAnnotation, GoogleChatAttachment, GoogleChatEvent } from "./types.js";
+
+export type GoogleChatRuntimeEnv = {
+  log?: (message: string) => void;
+  error?: (message: string) => void;
+};
+
+export type GoogleChatMonitorOptions = {
+  account: ResolvedGoogleChatAccount;
+  config: ClawdbotConfig;
+  runtime: GoogleChatRuntimeEnv;
+  abortSignal: AbortSignal;
+  webhookPath?: string;
+  webhookUrl?: string;
+  statusSink?: (patch: { lastInboundAt?: number; lastOutboundAt?: number }) => void;
+};
+
+type GoogleChatCoreRuntime = ReturnType<typeof getGoogleChatRuntime>;
+
+type WebhookTarget = {
+  account: ResolvedGoogleChatAccount;
+  config: ClawdbotConfig;
+  runtime: GoogleChatRuntimeEnv;
+  core: GoogleChatCoreRuntime;
+  path: string;
+  audienceType?: GoogleChatAudienceType;
+  audience?: string;
+  statusSink?: (patch: { lastInboundAt?: number; lastOutboundAt?: number }) => void;
+  mediaMaxMb: number;
+};
+
+const webhookTargets = new Map<string, WebhookTarget[]>();
+
+function logVerbose(core: GoogleChatCoreRuntime, runtime: GoogleChatRuntimeEnv, message: string) {
+  if (core.logging.shouldLogVerbose()) {
+    runtime.log?.(`[googlechat] ${message}`);
+  }
+}
+
+function normalizeWebhookPath(raw: string): string {
+  const trimmed = raw.trim();
+  if (!trimmed) return "/";
+  const withSlash = trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+  if (withSlash.length > 1 && withSlash.endsWith("/")) {
+    return withSlash.slice(0, -1);
+  }
+  return withSlash;
+}
+
+function resolveWebhookPath(webhookPath?: string, webhookUrl?: string): string | null {
+  const trimmedPath = webhookPath?.trim();
+  if (trimmedPath) return normalizeWebhookPath(trimmedPath);
+  if (webhookUrl?.trim()) {
+    try {
+      const parsed = new URL(webhookUrl);
+      return normalizeWebhookPath(parsed.pathname || "/");
+    } catch {
+      return null;
+    }
+  }
+  return "/googlechat";
+}
+
+async function readJsonBody(req: IncomingMessage, maxBytes: number) {
+  const chunks: Buffer[] = [];
+  let total = 0;
+  return await new Promise<{ ok: boolean; value?: unknown; error?: string }>((resolve) => {
+    let resolved = false;
+    const doResolve = (value: { ok: boolean; value?: unknown; error?: string }) => {
+      if (resolved) return;
+      resolved = true;
+      req.removeAllListeners();
+      resolve(value);
+    };
+    req.on("data", (chunk: Buffer) => {
+      total += chunk.length;
+      if (total > maxBytes) {
+        doResolve({ ok: false, error: "payload too large" });
+        req.destroy();
+        return;
+      }
+      chunks.push(chunk);
+    });
+    req.on("end", () => {
+      try {
+        const raw = Buffer.concat(chunks).toString("utf8");
+        if (!raw.trim()) {
+          doResolve({ ok: false, error: "empty payload" });
+          return;
+        }
+        doResolve({ ok: true, value: JSON.parse(raw) as unknown });
+      } catch (err) {
+        doResolve({ ok: false, error: err instanceof Error ? err.message : String(err) });
+      }
+    });
+    req.on("error", (err) => {
+      doResolve({ ok: false, error: err instanceof Error ? err.message : String(err) });
+    });
+  });
+}
+
+export function registerGoogleChatWebhookTarget(target: WebhookTarget): () => void {
+  const key = normalizeWebhookPath(target.path);
+  const normalizedTarget = { ...target, path: key };
+  const existing = webhookTargets.get(key) ?? [];
+  const next = [...existing, normalizedTarget];
+  webhookTargets.set(key, next);
+  return () => {
+    const updated = (webhookTargets.get(key) ?? []).filter((entry) => entry !== normalizedTarget);
+    if (updated.length > 0) {
+      webhookTargets.set(key, updated);
+    } else {
+      webhookTargets.delete(key);
+    }
+  };
+}
+
+function normalizeAudienceType(value?: string | null): GoogleChatAudienceType | undefined {
+  const normalized = value?.trim().toLowerCase();
+  if (normalized === "app-url" || normalized === "app_url" || normalized === "app") {
+    return "app-url";
+  }
+  if (normalized === "project-number" || normalized === "project_number" || normalized === "project") {
+    return "project-number";
+  }
+  return undefined;
+}
+
+export async function handleGoogleChatWebhookRequest(
+  req: IncomingMessage,
+  res: ServerResponse,
+): Promise<boolean> {
+  const url = new URL(req.url ?? "/", "http://localhost");
+  const path = normalizeWebhookPath(url.pathname);
+  const targets = webhookTargets.get(path);
+  if (!targets || targets.length === 0) return false;
+
+  if (req.method !== "POST") {
+    res.statusCode = 405;
+    res.setHeader("Allow", "POST");
+    res.end("Method Not Allowed");
+    return true;
+  }
+
+  const authHeader = String(req.headers.authorization ?? "");
+  const bearer = authHeader.toLowerCase().startsWith("bearer ")
+    ? authHeader.slice("bearer ".length)
+    : "";
+
+  const body = await readJsonBody(req, 1024 * 1024);
+  if (!body.ok) {
+    res.statusCode = body.error === "payload too large" ? 413 : 400;
+    res.end(body.error ?? "invalid payload");
+    return true;
+  }
+
+  const raw = body.value;
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    res.statusCode = 400;
+    res.end("invalid payload");
+    return true;
+  }
+
+  const eventType = (raw as { type?: string; eventType?: string }).type ??
+    (raw as { type?: string; eventType?: string }).eventType;
+  if (typeof eventType !== "string") {
+    res.statusCode = 400;
+    res.end("invalid payload");
+    return true;
+  }
+
+  const rawObj = raw as Record<string, unknown>;
+  if (!rawObj.space || typeof rawObj.space !== "object" || Array.isArray(rawObj.space)) {
+    res.statusCode = 400;
+    res.end("invalid payload");
+    return true;
+  }
+
+  if (eventType === "MESSAGE") {
+    if (!rawObj.message || typeof rawObj.message !== "object" || Array.isArray(rawObj.message)) {
+      res.statusCode = 400;
+      res.end("invalid payload");
+      return true;
+    }
+  }
+
+  const event = raw as GoogleChatEvent;
+
+  let selected: WebhookTarget | undefined;
+  for (const target of targets) {
+    const audienceType = target.audienceType;
+    const audience = target.audience;
+    const verification = await verifyGoogleChatRequest({
+      bearer,
+      audienceType,
+      audience,
+    });
+    if (verification.ok) {
+      selected = target;
+      break;
+    }
+  }
+
+  if (!selected) {
+    res.statusCode = 401;
+    res.end("unauthorized");
+    return true;
+  }
+
+  selected.statusSink?.({ lastInboundAt: Date.now() });
+  processGoogleChatEvent(event, selected).catch((err) => {
+    selected?.runtime.error?.(
+      `[${selected.account.accountId}] Google Chat webhook failed: ${String(err)}`,
+    );
+  });
+
+  res.statusCode = 200;
+  res.setHeader("Content-Type", "application/json");
+  res.end("{}");
+  return true;
+}
+
+async function processGoogleChatEvent(event: GoogleChatEvent, target: WebhookTarget) {
+  const eventType = event.type ?? (event as { eventType?: string }).eventType;
+  if (eventType !== "MESSAGE") return;
+  if (!event.message || !event.space) return;
+
+  await processMessageWithPipeline({
+    event,
+    account: target.account,
+    config: target.config,
+    runtime: target.runtime,
+    core: target.core,
+    statusSink: target.statusSink,
+    mediaMaxMb: target.mediaMaxMb,
+  });
+}
+
+function normalizeUserId(raw?: string | null): string {
+  const trimmed = raw?.trim() ?? "";
+  if (!trimmed) return "";
+  return trimmed.replace(/^users\//i, "").toLowerCase();
+}
+
+function isSenderAllowed(senderId: string, senderEmail: string | undefined, allowFrom: string[]) {
+  if (allowFrom.includes("*")) return true;
+  const normalizedSenderId = normalizeUserId(senderId);
+  const normalizedEmail = senderEmail?.trim().toLowerCase() ?? "";
+  return allowFrom.some((entry) => {
+    const normalized = String(entry).trim().toLowerCase();
+    if (!normalized) return false;
+    if (normalized === normalizedSenderId) return true;
+    if (normalizedEmail && normalized === normalizedEmail) return true;
+    if (normalized.replace(/^users\//i, "") === normalizedSenderId) return true;
+    if (normalized.replace(/^(googlechat|gchat):/i, "") === normalizedSenderId) return true;
+    return false;
+  });
+}
+
+function resolveGroupConfig(params: {
+  groupId: string;
+  groupName?: string | null;
+  groups?: Record<string, { requireMention?: boolean; allow?: boolean; enabled?: boolean; users?: Array<string | number>; systemPrompt?: string }>;
+}) {
+  const { groupId, groupName, groups } = params;
+  const entries = groups ?? {};
+  const keys = Object.keys(entries);
+  if (keys.length === 0) {
+    return { entry: undefined, allowlistConfigured: false };
+  }
+  const normalizedName = groupName?.trim().toLowerCase();
+  const candidates = [groupId, groupName ?? "", normalizedName ?? ""].filter(Boolean);
+  let entry = candidates.map((candidate) => entries[candidate]).find(Boolean);
+  if (!entry && normalizedName) {
+    entry = entries[normalizedName];
+  }
+  const fallback = entries["*"];
+  return { entry: entry ?? fallback, allowlistConfigured: true, fallback };
+}
+
+function extractMentionInfo(annotations: GoogleChatAnnotation[], botUser?: string | null) {
+  const mentionAnnotations = annotations.filter((entry) => entry.type === "USER_MENTION");
+  const hasAnyMention = mentionAnnotations.length > 0;
+  const botTargets = new Set(["users/app", botUser?.trim()].filter(Boolean) as string[]);
+  const wasMentioned = mentionAnnotations.some((entry) => {
+    const userName = entry.userMention?.user?.name;
+    if (!userName) return false;
+    if (botTargets.has(userName)) return true;
+    return normalizeUserId(userName) === "app";
+  });
+  return { hasAnyMention, wasMentioned };
+}
+
+async function processMessageWithPipeline(params: {
+  event: GoogleChatEvent;
+  account: ResolvedGoogleChatAccount;
+  config: ClawdbotConfig;
+  runtime: GoogleChatRuntimeEnv;
+  core: GoogleChatCoreRuntime;
+  statusSink?: (patch: { lastInboundAt?: number; lastOutboundAt?: number }) => void;
+  mediaMaxMb: number;
+}): Promise<void> {
+  const { event, account, config, runtime, core, statusSink, mediaMaxMb } = params;
+  const space = event.space;
+  const message = event.message;
+  if (!space || !message) return;
+
+  const spaceId = space.name ?? "";
+  if (!spaceId) return;
+  const spaceType = (space.type ?? "").toUpperCase();
+  const isGroup = spaceType !== "DM";
+  const sender = message.sender ?? event.user;
+  const senderId = sender?.name ?? "";
+  const senderName = sender?.displayName ?? "";
+  const senderEmail = sender?.email ?? undefined;
+
+  const allowBots = account.config.allowBots === true;
+  if (!allowBots) {
+    if (sender?.type?.toUpperCase() === "BOT") {
+      logVerbose(core, runtime, `skip bot-authored message (${senderId || "unknown"})`);
+      return;
+    }
+    if (senderId === "users/app") {
+      logVerbose(core, runtime, "skip app-authored message");
+      return;
+    }
+  }
+
+  const messageText = (message.argumentText ?? message.text ?? "").trim();
+  const attachments = message.attachment ?? [];
+  const hasMedia = attachments.length > 0;
+  const rawBody = messageText || (hasMedia ? "<media:attachment>" : "");
+  if (!rawBody) return;
+
+  const defaultGroupPolicy = config.channels?.defaults?.groupPolicy;
+  const groupPolicy = account.config.groupPolicy ?? defaultGroupPolicy ?? "allowlist";
+  const groupConfigResolved = resolveGroupConfig({
+    groupId: spaceId,
+    groupName: space.displayName ?? null,
+    groups: account.config.groups ?? undefined,
+  });
+  const groupEntry = groupConfigResolved.entry;
+  const groupUsers = groupEntry?.users ?? account.config.groupAllowFrom ?? [];
+  let effectiveWasMentioned: boolean | undefined;
+
+  if (isGroup) {
+    if (groupPolicy === "disabled") {
+      logVerbose(core, runtime, `drop group message (groupPolicy=disabled, space=${spaceId})`);
+      return;
+    }
+    const groupAllowlistConfigured = groupConfigResolved.allowlistConfigured;
+    const groupAllowed =
+      Boolean(groupEntry) || Boolean((account.config.groups ?? {})["*"]);
+    if (groupPolicy === "allowlist") {
+      if (!groupAllowlistConfigured) {
+        logVerbose(
+          core,
+          runtime,
+          `drop group message (groupPolicy=allowlist, no allowlist, space=${spaceId})`,
+        );
+        return;
+      }
+      if (!groupAllowed) {
+        logVerbose(core, runtime, `drop group message (not allowlisted, space=${spaceId})`);
+        return;
+      }
+    }
+    if (groupEntry?.enabled === false || groupEntry?.allow === false) {
+      logVerbose(core, runtime, `drop group message (space disabled, space=${spaceId})`);
+      return;
+    }
+
+    if (groupUsers.length > 0) {
+      const ok = isSenderAllowed(senderId, senderEmail, groupUsers.map((v) => String(v)));
+      if (!ok) {
+        logVerbose(core, runtime, `drop group message (sender not allowed, ${senderId})`);
+        return;
+      }
+    }
+  }
+
+  const dmPolicy = account.config.dm?.policy ?? "pairing";
+  const configAllowFrom = (account.config.dm?.allowFrom ?? []).map((v) => String(v));
+  const shouldComputeAuth = core.channel.commands.shouldComputeCommandAuthorized(rawBody, config);
+  const storeAllowFrom =
+    !isGroup && (dmPolicy !== "open" || shouldComputeAuth)
+      ? await core.channel.pairing.readAllowFromStore("googlechat").catch(() => [])
+      : [];
+  const effectiveAllowFrom = [...configAllowFrom, ...storeAllowFrom];
+  const commandAllowFrom = isGroup ? groupUsers.map((v) => String(v)) : effectiveAllowFrom;
+  const useAccessGroups = config.commands?.useAccessGroups !== false;
+  const senderAllowedForCommands = isSenderAllowed(senderId, senderEmail, commandAllowFrom);
+  const commandAuthorized = shouldComputeAuth
+    ? core.channel.commands.resolveCommandAuthorizedFromAuthorizers({
+        useAccessGroups,
+        authorizers: [
+          { configured: commandAllowFrom.length > 0, allowed: senderAllowedForCommands },
+        ],
+      })
+    : undefined;
+
+  if (isGroup) {
+    const requireMention = groupEntry?.requireMention ?? account.config.requireMention ?? true;
+    const annotations = message.annotations ?? [];
+    const mentionInfo = extractMentionInfo(annotations, account.config.botUser);
+    const allowTextCommands = core.channel.commands.shouldHandleTextCommands({
+      cfg: config,
+      surface: "googlechat",
+    });
+    const mentionGate = resolveMentionGatingWithBypass({
+      isGroup: true,
+      requireMention,
+      canDetectMention: true,
+      wasMentioned: mentionInfo.wasMentioned,
+      implicitMention: false,
+      hasAnyMention: mentionInfo.hasAnyMention,
+      allowTextCommands,
+      hasControlCommand: core.channel.text.hasControlCommand(rawBody, config),
+      commandAuthorized: commandAuthorized === true,
+    });
+    effectiveWasMentioned = mentionGate.effectiveWasMentioned;
+    if (mentionGate.shouldSkip) {
+      logVerbose(core, runtime, `drop group message (mention required, space=${spaceId})`);
+      return;
+    }
+  }
+
+  if (!isGroup) {
+    if (dmPolicy === "disabled" || account.config.dm?.enabled === false) {
+      logVerbose(core, runtime, `Blocked Google Chat DM from ${senderId} (dmPolicy=disabled)`);
+      return;
+    }
+
+    if (dmPolicy !== "open") {
+      const allowed = senderAllowedForCommands;
+      if (!allowed) {
+        if (dmPolicy === "pairing") {
+          const { code, created } = await core.channel.pairing.upsertPairingRequest({
+            channel: "googlechat",
+            id: senderId,
+            meta: { name: senderName || undefined, email: senderEmail },
+          });
+          if (created) {
+            logVerbose(core, runtime, `googlechat pairing request sender=${senderId}`);
+            try {
+              await sendGoogleChatMessage({
+                account,
+                space: spaceId,
+                text: core.channel.pairing.buildPairingReply({
+                  channel: "googlechat",
+                  idLine: `Your Google Chat user id: ${senderId}`,
+                  code,
+                }),
+              });
+              statusSink?.({ lastOutboundAt: Date.now() });
+            } catch (err) {
+              logVerbose(core, runtime, `pairing reply failed for ${senderId}: ${String(err)}`);
+            }
+          }
+        } else {
+          logVerbose(
+            core,
+            runtime,
+            `Blocked unauthorized Google Chat sender ${senderId} (dmPolicy=${dmPolicy})`,
+          );
+        }
+        return;
+      }
+    }
+  }
+
+  if (
+    isGroup &&
+    core.channel.commands.isControlCommandMessage(rawBody, config) &&
+    commandAuthorized !== true
+  ) {
+    logVerbose(core, runtime, `googlechat: drop control command from ${senderId}`);
+    return;
+  }
+
+  const route = core.channel.routing.resolveAgentRoute({
+    cfg: config,
+    channel: "googlechat",
+    accountId: account.accountId,
+    peer: {
+      kind: isGroup ? "group" : "dm",
+      id: spaceId,
+    },
+  });
+
+  let mediaPath: string | undefined;
+  let mediaType: string | undefined;
+  if (attachments.length > 0) {
+    const first = attachments[0];
+    const attachmentData = await downloadAttachment(first, account, mediaMaxMb, core);
+    if (attachmentData) {
+      mediaPath = attachmentData.path;
+      mediaType = attachmentData.contentType;
+    }
+  }
+
+  const fromLabel = isGroup
+    ? space.displayName || `space:${spaceId}`
+    : senderName || `user:${senderId}`;
+  const storePath = core.channel.session.resolveStorePath(config.session?.store, {
+    agentId: route.agentId,
+  });
+  const envelopeOptions = core.channel.reply.resolveEnvelopeFormatOptions(config);
+  const previousTimestamp = core.channel.session.readSessionUpdatedAt({
+    storePath,
+    sessionKey: route.sessionKey,
+  });
+  const body = core.channel.reply.formatAgentEnvelope({
+    channel: "Google Chat",
+    from: fromLabel,
+    timestamp: event.eventTime ? Date.parse(event.eventTime) : undefined,
+    previousTimestamp,
+    envelope: envelopeOptions,
+    body: rawBody,
+  });
+
+  const groupSystemPrompt = groupConfigResolved.entry?.systemPrompt?.trim() || undefined;
+
+  const ctxPayload = core.channel.reply.finalizeInboundContext({
+    Body: body,
+    RawBody: rawBody,
+    CommandBody: rawBody,
+    From: `googlechat:${senderId}`,
+    To: `googlechat:${spaceId}`,
+    SessionKey: route.sessionKey,
+    AccountId: route.accountId,
+    ChatType: isGroup ? "channel" : "direct",
+    ConversationLabel: fromLabel,
+    SenderName: senderName || undefined,
+    SenderId: senderId,
+    SenderUsername: senderEmail,
+    WasMentioned: isGroup ? effectiveWasMentioned : undefined,
+    CommandAuthorized: commandAuthorized,
+    Provider: "googlechat",
+    Surface: "googlechat",
+    MessageSid: message.name,
+    MessageSidFull: message.name,
+    ReplyToId: message.thread?.name,
+    ReplyToIdFull: message.thread?.name,
+    MediaPath: mediaPath,
+    MediaType: mediaType,
+    MediaUrl: mediaPath,
+    GroupSpace: isGroup ? space.displayName ?? undefined : undefined,
+    GroupSystemPrompt: isGroup ? groupSystemPrompt : undefined,
+    OriginatingChannel: "googlechat",
+    OriginatingTo: `googlechat:${spaceId}`,
+  });
+
+  void core.channel.session
+    .recordSessionMetaFromInbound({
+      storePath,
+      sessionKey: ctxPayload.SessionKey ?? route.sessionKey,
+      ctx: ctxPayload,
+    })
+    .catch((err) => {
+      runtime.error?.(`googlechat: failed updating session meta: ${String(err)}`);
+    });
+
+  await core.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
+    ctx: ctxPayload,
+    cfg: config,
+    dispatcherOptions: {
+      deliver: async (payload) => {
+        await deliverGoogleChatReply({
+          payload,
+          account,
+          spaceId,
+          runtime,
+          core,
+          statusSink,
+        });
+      },
+      onError: (err, info) => {
+        runtime.error?.(
+          `[${account.accountId}] Google Chat ${info.kind} reply failed: ${String(err)}`,
+        );
+      },
+    },
+  });
+}
+
+async function downloadAttachment(
+  attachment: GoogleChatAttachment,
+  account: ResolvedGoogleChatAccount,
+  mediaMaxMb: number,
+  core: GoogleChatCoreRuntime,
+): Promise<{ path: string; contentType?: string } | null> {
+  const resourceName = attachment.attachmentDataRef?.resourceName;
+  if (!resourceName) return null;
+  const maxBytes = Math.max(1, mediaMaxMb) * 1024 * 1024;
+  const downloaded = await downloadGoogleChatMedia({ account, resourceName });
+  const saved = await core.channel.media.saveMediaBuffer(
+    downloaded.buffer,
+    downloaded.contentType ?? attachment.contentType,
+    "inbound",
+    maxBytes,
+    attachment.contentName,
+  );
+  return { path: saved.path, contentType: saved.contentType };
+}
+
+async function deliverGoogleChatReply(params: {
+  payload: { text?: string; mediaUrls?: string[]; mediaUrl?: string; replyToId?: string };
+  account: ResolvedGoogleChatAccount;
+  spaceId: string;
+  runtime: GoogleChatRuntimeEnv;
+  core: GoogleChatCoreRuntime;
+  statusSink?: (patch: { lastInboundAt?: number; lastOutboundAt?: number }) => void;
+}): Promise<void> {
+  const { payload, account, spaceId, runtime, core, statusSink } = params;
+  const mediaList = payload.mediaUrls?.length
+    ? payload.mediaUrls
+    : payload.mediaUrl
+      ? [payload.mediaUrl]
+      : [];
+
+  if (mediaList.length > 0) {
+    let first = true;
+    for (const mediaUrl of mediaList) {
+      const caption = first ? payload.text : undefined;
+      first = false;
+      try {
+        const loaded = await core.channel.media.fetchRemoteMedia(mediaUrl, {
+          maxBytes: (account.config.mediaMaxMb ?? 20) * 1024 * 1024,
+        });
+        const upload = await uploadAttachmentForReply({
+          account,
+          spaceId,
+          buffer: loaded.buffer,
+          contentType: loaded.contentType,
+          filename: loaded.filename ?? "attachment",
+        });
+        if (!upload.attachmentUploadToken) {
+          throw new Error("missing attachment upload token");
+        }
+        await sendGoogleChatMessage({
+          account,
+          space: spaceId,
+          text: caption,
+          thread: payload.replyToId,
+          attachments: [
+            { attachmentUploadToken: upload.attachmentUploadToken, contentName: loaded.filename },
+          ],
+        });
+        statusSink?.({ lastOutboundAt: Date.now() });
+      } catch (err) {
+        runtime.error?.(`Google Chat attachment send failed: ${String(err)}`);
+      }
+    }
+    return;
+  }
+
+  if (payload.text) {
+    const chunkLimit = account.config.textChunkLimit ?? 4000;
+    const chunks = core.channel.text.chunkMarkdownText(payload.text, chunkLimit);
+    for (const chunk of chunks) {
+      try {
+        await sendGoogleChatMessage({
+          account,
+          space: spaceId,
+          text: chunk,
+          thread: payload.replyToId,
+        });
+        statusSink?.({ lastOutboundAt: Date.now() });
+      } catch (err) {
+        runtime.error?.(`Google Chat message send failed: ${String(err)}`);
+      }
+    }
+  }
+}
+
+async function uploadAttachmentForReply(params: {
+  account: ResolvedGoogleChatAccount;
+  spaceId: string;
+  buffer: Buffer;
+  contentType?: string;
+  filename: string;
+}) {
+  const { account, spaceId, buffer, contentType, filename } = params;
+  const { uploadGoogleChatAttachment } = await import("./api.js");
+  return await uploadGoogleChatAttachment({
+    account,
+    space: spaceId,
+    filename,
+    buffer,
+    contentType,
+  });
+}
+
+export function monitorGoogleChatProvider(options: GoogleChatMonitorOptions): () => void {
+  const core = getGoogleChatRuntime();
+  const webhookPath = resolveWebhookPath(options.webhookPath, options.webhookUrl);
+  if (!webhookPath) {
+    options.runtime.error?.(`[${options.account.accountId}] invalid webhook path`);
+    return () => {};
+  }
+
+  const audienceType = normalizeAudienceType(options.account.config.audienceType);
+  const audience = options.account.config.audience?.trim();
+  const mediaMaxMb = options.account.config.mediaMaxMb ?? 20;
+
+  const unregister = registerGoogleChatWebhookTarget({
+    account: options.account,
+    config: options.config,
+    runtime: options.runtime,
+    core,
+    path: webhookPath,
+    audienceType,
+    audience,
+    statusSink: options.statusSink,
+    mediaMaxMb,
+  });
+
+  return unregister;
+}
+
+export async function startGoogleChatMonitor(params: GoogleChatMonitorOptions): Promise<() => void> {
+  return monitorGoogleChatProvider(params);
+}
+
+export function resolveGoogleChatWebhookPath(params: {
+  account: ResolvedGoogleChatAccount;
+}): string {
+  return resolveWebhookPath(
+    params.account.config.webhookPath,
+    params.account.config.webhookUrl,
+  ) ?? "/googlechat";
+}
+
+export function computeGoogleChatMediaMaxMb(params: { account: ResolvedGoogleChatAccount }) {
+  return params.account.config.mediaMaxMb ?? 20;
+}

extensions/googlechat/src/onboarding.ts

@@ -0,0 +1,276 @@
+import type { ClawdbotConfig, DmPolicy } from "clawdbot/plugin-sdk";
+import {
+  addWildcardAllowFrom,
+  formatDocsLink,
+  promptAccountId,
+  type ChannelOnboardingAdapter,
+  type ChannelOnboardingDmPolicy,
+  type WizardPrompter,
+  DEFAULT_ACCOUNT_ID,
+  normalizeAccountId,
+  migrateBaseNameToDefaultAccount,
+} from "clawdbot/plugin-sdk";
+
+import {
+  listGoogleChatAccountIds,
+  resolveDefaultGoogleChatAccountId,
+  resolveGoogleChatAccount,
+} from "./accounts.js";
+
+const channel = "googlechat" as const;
+
+const ENV_SERVICE_ACCOUNT = "GOOGLE_CHAT_SERVICE_ACCOUNT";
+const ENV_SERVICE_ACCOUNT_FILE = "GOOGLE_CHAT_SERVICE_ACCOUNT_FILE";
+
+function setGoogleChatDmPolicy(cfg: ClawdbotConfig, policy: DmPolicy) {
+  const allowFrom =
+    policy === "open"
+      ? addWildcardAllowFrom(cfg.channels?.["googlechat"]?.dm?.allowFrom)
+      : undefined;
+  return {
+    ...cfg,
+    channels: {
+      ...cfg.channels,
+      "googlechat": {
+        ...(cfg.channels?.["googlechat"] ?? {}),
+        dm: {
+          ...(cfg.channels?.["googlechat"]?.dm ?? {}),
+          policy,
+          ...(allowFrom ? { allowFrom } : {}),
+        },
+      },
+    },
+  };
+}
+
+function parseAllowFromInput(raw: string): string[] {
+  return raw
+    .split(/[\n,;]+/g)
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+}
+
+async function promptAllowFrom(params: {
+  cfg: ClawdbotConfig;
+  prompter: WizardPrompter;
+}): Promise<ClawdbotConfig> {
+  const current = params.cfg.channels?.["googlechat"]?.dm?.allowFrom ?? [];
+  const entry = await params.prompter.text({
+    message: "Google Chat allowFrom (user id or email)",
+    placeholder: "users/123456789, name@example.com",
+    initialValue: current[0] ? String(current[0]) : undefined,
+    validate: (value) => (String(value ?? "").trim() ? undefined : "Required"),
+  });
+  const parts = parseAllowFromInput(String(entry));
+  const unique = [...new Set(parts)];
+  return {
+    ...params.cfg,
+    channels: {
+      ...params.cfg.channels,
+      "googlechat": {
+        ...(params.cfg.channels?.["googlechat"] ?? {}),
+        enabled: true,
+        dm: {
+          ...(params.cfg.channels?.["googlechat"]?.dm ?? {}),
+          policy: "allowlist",
+          allowFrom: unique,
+        },
+      },
+    },
+  };
+}
+
+const dmPolicy: ChannelOnboardingDmPolicy = {
+  label: "Google Chat",
+  channel,
+  policyKey: "channels.googlechat.dm.policy",
+  allowFromKey: "channels.googlechat.dm.allowFrom",
+  getCurrent: (cfg) => cfg.channels?.["googlechat"]?.dm?.policy ?? "pairing",
+  setPolicy: (cfg, policy) => setGoogleChatDmPolicy(cfg, policy),
+  promptAllowFrom,
+};
+
+function applyAccountConfig(params: {
+  cfg: ClawdbotConfig;
+  accountId: string;
+  patch: Record<string, unknown>;
+}): ClawdbotConfig {
+  const { cfg, accountId, patch } = params;
+  if (accountId === DEFAULT_ACCOUNT_ID) {
+    return {
+      ...cfg,
+      channels: {
+        ...cfg.channels,
+        "googlechat": {
+          ...(cfg.channels?.["googlechat"] ?? {}),
+          enabled: true,
+          ...patch,
+        },
+      },
+    };
+  }
+  return {
+    ...cfg,
+    channels: {
+      ...cfg.channels,
+      "googlechat": {
+        ...(cfg.channels?.["googlechat"] ?? {}),
+        enabled: true,
+        accounts: {
+          ...(cfg.channels?.["googlechat"]?.accounts ?? {}),
+          [accountId]: {
+            ...(cfg.channels?.["googlechat"]?.accounts?.[accountId] ?? {}),
+            enabled: true,
+            ...patch,
+          },
+        },
+      },
+    },
+  };
+}
+
+async function promptCredentials(params: {
+  cfg: ClawdbotConfig;
+  prompter: WizardPrompter;
+  accountId: string;
+}): Promise<ClawdbotConfig> {
+  const { cfg, prompter, accountId } = params;
+  const envReady =
+    Boolean(process.env[ENV_SERVICE_ACCOUNT]) || Boolean(process.env[ENV_SERVICE_ACCOUNT_FILE]);
+  if (envReady) {
+    const useEnv = await prompter.confirm({
+      message: "Use GOOGLE_CHAT_SERVICE_ACCOUNT env vars?",
+      initialValue: true,
+    });
+    if (useEnv) {
+      return applyAccountConfig({ cfg, accountId, patch: {} });
+    }
+  }
+
+  const method = await prompter.select({
+    message: "Google Chat auth method",
+    options: [
+      { value: "file", label: "Service account JSON file" },
+      { value: "inline", label: "Paste service account JSON" },
+    ],
+    initialValue: "file",
+  });
+
+  if (method === "file") {
+    const path = await prompter.text({
+      message: "Service account JSON path",
+      placeholder: "/path/to/service-account.json",
+      validate: (value) => (String(value ?? "").trim() ? undefined : "Required"),
+    });
+    return applyAccountConfig({
+      cfg,
+      accountId,
+      patch: { serviceAccountFile: String(path).trim() },
+    });
+  }
+
+  const json = await prompter.text({
+    message: "Service account JSON (single line)",
+    placeholder: "{\"type\":\"service_account\", ... }",
+    validate: (value) => (String(value ?? "").trim() ? undefined : "Required"),
+  });
+  return applyAccountConfig({
+    cfg,
+    accountId,
+    patch: { serviceAccount: String(json).trim() },
+  });
+}
+
+async function promptAudience(params: {
+  cfg: ClawdbotConfig;
+  prompter: WizardPrompter;
+  accountId: string;
+}): Promise<ClawdbotConfig> {
+  const account = resolveGoogleChatAccount({
+    cfg: params.cfg,
+    accountId: params.accountId,
+  });
+  const currentType = account.config.audienceType ?? "app-url";
+  const currentAudience = account.config.audience ?? "";
+  const audienceType = (await params.prompter.select({
+    message: "Webhook audience type",
+    options: [
+      { value: "app-url", label: "App URL (recommended)" },
+      { value: "project-number", label: "Project number" },
+    ],
+    initialValue: currentType === "project-number" ? "project-number" : "app-url",
+  })) as "app-url" | "project-number";
+  const audience = await params.prompter.text({
+    message: audienceType === "project-number" ? "Project number" : "App URL",
+    placeholder: audienceType === "project-number" ? "1234567890" : "https://your.host/googlechat",
+    initialValue: currentAudience || undefined,
+    validate: (value) => (String(value ?? "").trim() ? undefined : "Required"),
+  });
+  return applyAccountConfig({
+    cfg: params.cfg,
+    accountId: params.accountId,
+    patch: { audienceType, audience: String(audience).trim() },
+  });
+}
+
+async function noteGoogleChatSetup(prompter: WizardPrompter) {
+  await prompter.note(
+    [
+      "Google Chat apps use service-account auth and an HTTPS webhook.",
+      "Set the Chat API scopes in your service account and configure the Chat app URL.",
+      "Webhook verification requires audience type + audience value.",
+      `Docs: ${formatDocsLink("/channels/googlechat", "channels/googlechat")}`,
+    ].join("\n"),
+    "Google Chat setup",
+  );
+}
+
+export const googlechatOnboardingAdapter: ChannelOnboardingAdapter = {
+  channel,
+  dmPolicy,
+  getStatus: async ({ cfg }) => {
+    const configured = listGoogleChatAccountIds(cfg).some(
+      (accountId) => resolveGoogleChatAccount({ cfg, accountId }).credentialSource !== "none",
+    );
+    return {
+      channel,
+      configured,
+      statusLines: [
+        `Google Chat: ${configured ? "configured" : "needs service account"}`,
+      ],
+      selectionHint: configured ? "configured" : "needs auth",
+    };
+  },
+  configure: async ({
+    cfg,
+    prompter,
+    accountOverrides,
+    shouldPromptAccountIds,
+  }) => {
+    const override = accountOverrides["googlechat"]?.trim();
+    const defaultAccountId = resolveDefaultGoogleChatAccountId(cfg);
+    let accountId = override ? normalizeAccountId(override) : defaultAccountId;
+    if (shouldPromptAccountIds && !override) {
+      accountId = await promptAccountId({
+        cfg,
+        prompter,
+        label: "Google Chat",
+        currentId: accountId,
+        listAccountIds: listGoogleChatAccountIds,
+        defaultAccountId,
+      });
+    }
+
+    let next = cfg;
+    await noteGoogleChatSetup(prompter);
+    next = await promptCredentials({ cfg: next, prompter, accountId });
+    next = await promptAudience({ cfg: next, prompter, accountId });
+
+    const namedConfig = migrateBaseNameToDefaultAccount({
+      cfg: next,
+      channelKey: "googlechat",
+    });
+
+    return { cfg: namedConfig, accountId };
+  },
+};

extensions/googlechat/src/runtime.ts

@@ -0,0 +1,14 @@
+import type { PluginRuntime } from "clawdbot/plugin-sdk";
+
+let runtime: PluginRuntime | null = null;
+
+export function setGoogleChatRuntime(next: PluginRuntime) {
+  runtime = next;
+}
+
+export function getGoogleChatRuntime(): PluginRuntime {
+  if (!runtime) {
+    throw new Error("Google Chat runtime not initialized");
+  }
+  return runtime;
+}

extensions/googlechat/src/targets.ts

@@ -0,0 +1,49 @@
+import type { ResolvedGoogleChatAccount } from "./accounts.js";
+import { findGoogleChatDirectMessage } from "./api.js";
+
+export function normalizeGoogleChatTarget(raw?: string | null): string | undefined {
+  const trimmed = raw?.trim();
+  if (!trimmed) return undefined;
+  const withoutPrefix = trimmed.replace(/^(googlechat|gchat):/i, "");
+  const normalized = withoutPrefix
+    .replace(/^user:/i, "users/")
+    .replace(/^space:/i, "spaces/");
+  return normalized;
+}
+
+export function isGoogleChatUserTarget(value: string): boolean {
+  return value.toLowerCase().startsWith("users/");
+}
+
+export function isGoogleChatSpaceTarget(value: string): boolean {
+  return value.toLowerCase().startsWith("spaces/");
+}
+
+function stripMessageSuffix(target: string): string {
+  const index = target.indexOf("/messages/");
+  if (index === -1) return target;
+  return target.slice(0, index);
+}
+
+export async function resolveGoogleChatOutboundSpace(params: {
+  account: ResolvedGoogleChatAccount;
+  target: string;
+}): Promise<string> {
+  const normalized = normalizeGoogleChatTarget(params.target);
+  if (!normalized) {
+    throw new Error("Missing Google Chat target.");
+  }
+  const base = stripMessageSuffix(normalized);
+  if (isGoogleChatSpaceTarget(base)) return base;
+  if (isGoogleChatUserTarget(base)) {
+    const dm = await findGoogleChatDirectMessage({
+      account: params.account,
+      userName: base,
+    });
+    if (!dm?.name) {
+      throw new Error(`No Google Chat DM found for ${base}`);
+    }
+    return dm.name;
+  }
+  return base;
+}

extensions/googlechat/src/types.config.ts

@@ -0,0 +1,3 @@
+import type { GoogleChatAccountConfig, GoogleChatConfig } from "clawdbot/plugin-sdk";
+
+export type { GoogleChatAccountConfig, GoogleChatConfig };

extensions/googlechat/src/types.ts

@@ -0,0 +1,73 @@
+export type GoogleChatSpace = {
+  name?: string;
+  displayName?: string;
+  type?: string;
+};
+
+export type GoogleChatUser = {
+  name?: string;
+  displayName?: string;
+  email?: string;
+  type?: string;
+};
+
+export type GoogleChatThread = {
+  name?: string;
+  threadKey?: string;
+};
+
+export type GoogleChatAttachmentDataRef = {
+  resourceName?: string;
+  attachmentUploadToken?: string;
+};
+
+export type GoogleChatAttachment = {
+  name?: string;
+  contentName?: string;
+  contentType?: string;
+  thumbnailUri?: string;
+  downloadUri?: string;
+  source?: string;
+  attachmentDataRef?: GoogleChatAttachmentDataRef;
+  driveDataRef?: Record<string, unknown>;
+};
+
+export type GoogleChatUserMention = {
+  user?: GoogleChatUser;
+  type?: string;
+};
+
+export type GoogleChatAnnotation = {
+  type?: string;
+  startIndex?: number;
+  length?: number;
+  userMention?: GoogleChatUserMention;
+  slashCommand?: Record<string, unknown>;
+  richLinkMetadata?: Record<string, unknown>;
+  customEmojiMetadata?: Record<string, unknown>;
+};
+
+export type GoogleChatMessage = {
+  name?: string;
+  text?: string;
+  argumentText?: string;
+  sender?: GoogleChatUser;
+  thread?: GoogleChatThread;
+  attachment?: GoogleChatAttachment[];
+  annotations?: GoogleChatAnnotation[];
+};
+
+export type GoogleChatEvent = {
+  type?: string;
+  eventType?: string;
+  eventTime?: string;
+  space?: GoogleChatSpace;
+  user?: GoogleChatUser;
+  message?: GoogleChatMessage;
+};
+
+export type GoogleChatReaction = {
+  name?: string;
+  user?: GoogleChatUser;
+  emoji?: { unicode?: string };
+};

pnpm-lock.yaml

@@ -300,6 +300,15 @@ importers:
 
   extensions/google-antigravity-auth: {}
 
+  extensions/google-chat:
+    dependencies:
+      clawdbot:
+        specifier: workspace:*
+        version: link:../..
+      google-auth-library:
+        specifier: ^10.5.0
+        version: 10.5.0
+
   extensions/google-gemini-cli-auth: {}
 
   extensions/imessage: {}
@@ -387,6 +396,8 @@ importers:
 
   extensions/open-prose: {}
 
+  extensions/open-prose: {}
+
   extensions/signal: {}
 
   extensions/slack: {}

src/channels/dock.ts

@@ -5,6 +5,7 @@ import { resolveSignalAccount } from "../signal/accounts.js";
 import { resolveSlackAccount, resolveSlackReplyToMode } from "../slack/accounts.js";
 import { buildSlackThreadingToolContext } from "../slack/threading-tool-context.js";
 import { resolveTelegramAccount } from "../telegram/accounts.js";
+import { normalizeAccountId } from "../routing/session-key.js";
 import { normalizeE164 } from "../utils.js";
 import { resolveWhatsAppAccount } from "../web/accounts.js";
 import { normalizeWhatsAppTarget } from "../whatsapp/normalize.js";
@@ -12,6 +13,8 @@ import { requireActivePluginRegistry } from "../plugins/runtime.js";
 import {
   resolveDiscordGroupRequireMention,
   resolveDiscordGroupToolPolicy,
+  resolveGoogleChatGroupRequireMention,
+  resolveGoogleChatGroupToolPolicy,
   resolveIMessageGroupRequireMention,
   resolveIMessageGroupToolPolicy,
   resolveSlackGroupRequireMention,
@@ -210,6 +213,64 @@ const DOCKS: Record<ChatChannelId, ChannelDock> = {
       }),
     },
   },
+  googlechat: {
+    id: "googlechat",
+    capabilities: {
+      chatTypes: ["direct", "group", "thread"],
+      reactions: true,
+      media: true,
+      threads: true,
+      blockStreaming: true,
+    },
+    outbound: { textChunkLimit: 4000 },
+    config: {
+      resolveAllowFrom: ({ cfg, accountId }) => {
+        const channel = cfg.channels?.googlechat as
+          | {
+              accounts?: Record<string, { dm?: { allowFrom?: Array<string | number> } }>;
+              dm?: { allowFrom?: Array<string | number> };
+            }
+          | undefined;
+        const normalized = normalizeAccountId(accountId);
+        const account =
+          channel?.accounts?.[normalized] ??
+          channel?.accounts?.[
+            Object.keys(channel?.accounts ?? {}).find(
+              (key) => key.toLowerCase() === normalized.toLowerCase(),
+            ) ?? ""
+          ];
+        return (account?.dm?.allowFrom ?? channel?.dm?.allowFrom ?? []).map((entry) =>
+          String(entry),
+        );
+      },
+      formatAllowFrom: ({ allowFrom }) =>
+        allowFrom
+          .map((entry) => String(entry).trim())
+          .filter(Boolean)
+          .map((entry) =>
+            entry
+              .replace(/^(googlechat|google-chat|gchat):/i, "")
+              .replace(/^user:/i, "")
+              .replace(/^users\//i, "")
+              .toLowerCase(),
+          ),
+    },
+    groups: {
+      resolveRequireMention: resolveGoogleChatGroupRequireMention,
+      resolveToolPolicy: resolveGoogleChatGroupToolPolicy,
+    },
+    threading: {
+      resolveReplyToMode: ({ cfg }) => cfg.channels?.googlechat?.replyToMode ?? "off",
+      buildToolContext: ({ context, hasRepliedRef }) => {
+        const threadId = context.MessageThreadId ?? context.ReplyToId;
+        return {
+          currentChannelId: context.To?.trim() || undefined,
+          currentThreadTs: threadId != null ? String(threadId) : undefined,
+          hasRepliedRef,
+        };
+      },
+    },
+  },
   slack: {
     id: "slack",
     capabilities: {

src/channels/plugins/group-mentions.ts

@@ -155,6 +155,15 @@ export function resolveDiscordGroupRequireMention(params: GroupMentionParams): b
   return true;
 }
 
+export function resolveGoogleChatGroupRequireMention(params: GroupMentionParams): boolean {
+  return resolveChannelGroupRequireMention({
+    cfg: params.cfg,
+    channel: "googlechat",
+    groupId: params.groupId,
+    accountId: params.accountId,
+  });
+}
+
 export function resolveSlackGroupRequireMention(params: GroupMentionParams): boolean {
   const account = resolveSlackAccount({
     cfg: params.cfg,

src/channels/plugins/types.core.ts

@@ -32,6 +32,9 @@ export type ChannelSetupInput = {
   httpHost?: string;
   httpPort?: string;
   webhookPath?: string;
+  webhookUrl?: string;
+  audienceType?: string;
+  audience?: string;
   useEnv?: boolean;
   homeserver?: string;
   userId?: string;
@@ -121,6 +124,11 @@ export type ChannelAccountSnapshot = {
   tokenSource?: string;
   botTokenSource?: string;
   appTokenSource?: string;
+  credentialSource?: string;
+  audienceType?: string;
+  audience?: string;
+  webhookPath?: string;
+  webhookUrl?: string;
   baseUrl?: string;
   allowUnmentionedGroups?: boolean;
   cliPath?: string | null;

src/channels/registry.test.ts

@@ -9,6 +9,8 @@ import {
 describe("channel registry", () => {
   it("normalizes aliases", () => {
     expect(normalizeChatChannelId("imsg")).toBe("imessage");
+    expect(normalizeChatChannelId("gchat")).toBe("googlechat");
+    expect(normalizeChatChannelId("google-chat")).toBe("googlechat");
     expect(normalizeChatChannelId("web")).toBeNull();
   });
 

src/channels/registry.ts

@@ -8,6 +8,7 @@ export const CHAT_CHANNEL_ORDER = [
   "telegram",
   "whatsapp",
   "discord",
+  "googlechat",
   "slack",
   "signal",
   "imessage",
@@ -57,6 +58,16 @@ const CHAT_CHANNEL_META: Record<ChatChannelId, ChannelMeta> = {
     blurb: "very well supported right now.",
     systemImage: "bubble.left.and.bubble.right",
   },
+  googlechat: {
+    id: "googlechat",
+    label: "Google Chat",
+    selectionLabel: "Google Chat (Chat API)",
+    detailLabel: "Google Chat",
+    docsPath: "/channels/googlechat",
+    docsLabel: "googlechat",
+    blurb: "Google Workspace Chat app with HTTP webhook.",
+    systemImage: "message.badge",
+  },
   slack: {
     id: "slack",
     label: "Slack",
@@ -91,6 +102,8 @@ const CHAT_CHANNEL_META: Record<ChatChannelId, ChannelMeta> = {
 
 export const CHAT_CHANNEL_ALIASES: Record<string, ChatChannelId> = {
   imsg: "imessage",
+  "google-chat": "googlechat",
+  gchat: "googlechat",
 };
 
 const normalizeChannelKey = (raw?: string | null): string | undefined => {

src/cli/channels-cli.ts

@@ -35,6 +35,9 @@ const optionNamesAdd = [
   "httpHost",
   "httpPort",
   "webhookPath",
+  "webhookUrl",
+  "audienceType",
+  "audience",
   "useEnv",
   "homeserver",
   "userId",
@@ -168,7 +171,10 @@ export function registerChannelsCli(program: Command) {
     .option("--http-url <url>", "Signal HTTP daemon base URL")
     .option("--http-host <host>", "Signal HTTP host")
     .option("--http-port <port>", "Signal HTTP port")
-    .option("--webhook-path <path>", "BlueBubbles webhook path")
+    .option("--webhook-path <path>", "Webhook path (Google Chat/BlueBubbles)")
+    .option("--webhook-url <url>", "Google Chat webhook URL")
+    .option("--audience-type <type>", "Google Chat audience type (app-url|project-number)")
+    .option("--audience <value>", "Google Chat audience value (app URL or project number)")
     .option("--homeserver <url>", "Matrix homeserver URL")
     .option("--user-id <id>", "Matrix user ID")
     .option("--access-token <token>", "Matrix access token")

src/commands/channels/add-mutators.ts

@@ -36,6 +36,9 @@ export function applyChannelAccountConfig(params: {
   httpHost?: string;
   httpPort?: string;
   webhookPath?: string;
+  webhookUrl?: string;
+  audienceType?: string;
+  audience?: string;
   useEnv?: boolean;
   homeserver?: string;
   userId?: string;
@@ -70,6 +73,9 @@ export function applyChannelAccountConfig(params: {
     httpHost: params.httpHost,
     httpPort: params.httpPort,
     webhookPath: params.webhookPath,
+    webhookUrl: params.webhookUrl,
+    audienceType: params.audienceType,
+    audience: params.audience,
     useEnv: params.useEnv,
     homeserver: params.homeserver,
     userId: params.userId,

src/commands/channels/add.ts

@@ -33,6 +33,9 @@ export type ChannelsAddOptions = {
   httpHost?: string;
   httpPort?: string;
   webhookPath?: string;
+  webhookUrl?: string;
+  audienceType?: string;
+  audience?: string;
   useEnv?: boolean;
   homeserver?: string;
   userId?: string;
@@ -198,6 +201,9 @@ export async function channelsAddCommand(
       httpHost: opts.httpHost,
       httpPort: opts.httpPort,
       webhookPath: opts.webhookPath,
+      webhookUrl: opts.webhookUrl,
+      audienceType: opts.audienceType,
+      audience: opts.audience,
       homeserver: opts.homeserver,
       userId: opts.userId,
       accessToken: opts.accessToken,
@@ -238,6 +244,9 @@ export async function channelsAddCommand(
     httpHost: opts.httpHost,
     httpPort: opts.httpPort,
     webhookPath: opts.webhookPath,
+    webhookUrl: opts.webhookUrl,
+    audienceType: opts.audienceType,
+    audience: opts.audience,
     homeserver: opts.homeserver,
     userId: opts.userId,
     accessToken: opts.accessToken,

src/commands/channels/resolve.ts

@@ -35,7 +35,11 @@ function detectAutoKind(input: string): ChannelResolveKind {
   if (!trimmed) return "group";
   if (trimmed.startsWith("@")) return "user";
   if (/^<@!?/.test(trimmed)) return "user";
-  if (/^(user|discord|slack|matrix|msteams|teams|zalo|zalouser):/i.test(trimmed)) {
+  if (
+    /^(user|discord|slack|matrix|msteams|teams|zalo|zalouser|googlechat|google-chat|gchat):/i.test(
+      trimmed,
+    )
+  ) {
     return "user";
   }
   return "group";

src/config/types.channels.ts

@@ -1,4 +1,5 @@
 import type { DiscordConfig } from "./types.discord.js";
+import type { GoogleChatConfig } from "./types.googlechat.js";
 import type { IMessageConfig } from "./types.imessage.js";
 import type { MSTeamsConfig } from "./types.msteams.js";
 import type { SignalConfig } from "./types.signal.js";
@@ -27,6 +28,7 @@ export type ChannelsConfig = {
   whatsapp?: WhatsAppConfig;
   telegram?: TelegramConfig;
   discord?: DiscordConfig;
+  googlechat?: GoogleChatConfig;
   slack?: SlackConfig;
   signal?: SignalConfig;
   imessage?: IMessageConfig;

src/config/types.googlechat.ts

@@ -0,0 +1,97 @@
+import type {
+  BlockStreamingCoalesceConfig,
+  DmPolicy,
+  GroupPolicy,
+  ReplyToMode,
+} from "./types.base.js";
+import type { DmConfig } from "./types.messages.js";
+
+export type GoogleChatDmConfig = {
+  /** If false, ignore all incoming Google Chat DMs. Default: true. */
+  enabled?: boolean;
+  /** Direct message access policy (default: pairing). */
+  policy?: DmPolicy;
+  /** Allowlist for DM senders (user ids or emails). */
+  allowFrom?: Array<string | number>;
+};
+
+export type GoogleChatGroupConfig = {
+  /** If false, disable the bot in this space. (Alias for allow: false.) */
+  enabled?: boolean;
+  /** Legacy allow toggle; prefer enabled. */
+  allow?: boolean;
+  /** Require mentioning the bot to trigger replies. */
+  requireMention?: boolean;
+  /** Allowlist of users that can invoke the bot in this space. */
+  users?: Array<string | number>;
+  /** Optional system prompt for this space. */
+  systemPrompt?: string;
+};
+
+export type GoogleChatActionConfig = {
+  reactions?: boolean;
+};
+
+export type GoogleChatAccountConfig = {
+  /** Optional display name for this account (used in CLI/UI lists). */
+  name?: string;
+  /** Optional provider capability tags used for agent/runtime guidance. */
+  capabilities?: string[];
+  /** Allow channel-initiated config writes (default: true). */
+  configWrites?: boolean;
+  /** If false, do not start this Google Chat account. Default: true. */
+  enabled?: boolean;
+  /** Allow bot-authored messages to trigger replies (default: false). */
+  allowBots?: boolean;
+  /** Default mention requirement for space messages (default: true). */
+  requireMention?: boolean;
+  /**
+   * Controls how space messages are handled:
+   * - "open": spaces bypass allowlists; mention-gating applies
+   * - "disabled": block all space messages
+   * - "allowlist": only allow spaces present in channels.googlechat.groups
+   */
+  groupPolicy?: GroupPolicy;
+  /** Optional allowlist for space senders (user ids or emails). */
+  groupAllowFrom?: Array<string | number>;
+  /** Per-space configuration keyed by space id or name. */
+  groups?: Record<string, GoogleChatGroupConfig>;
+  /** Service account JSON (inline string or object). */
+  serviceAccount?: string | Record<string, unknown>;
+  /** Service account JSON file path. */
+  serviceAccountFile?: string;
+  /** Webhook audience type (app-url or project-number). */
+  audienceType?: "app-url" | "project-number";
+  /** Audience value (app URL or project number). */
+  audience?: string;
+  /** Google Chat webhook path (default: /googlechat). */
+  webhookPath?: string;
+  /** Google Chat webhook URL (used to derive the path). */
+  webhookUrl?: string;
+  /** Optional bot user resource name (users/...). */
+  botUser?: string;
+  /** Max space messages to keep as history context (0 disables). */
+  historyLimit?: number;
+  /** Max DM turns to keep as history context. */
+  dmHistoryLimit?: number;
+  /** Per-DM config overrides keyed by user id. */
+  dms?: Record<string, DmConfig>;
+  /** Outbound text chunk size (chars). Default: 4000. */
+  textChunkLimit?: number;
+  blockStreaming?: boolean;
+  /** Merge streamed block replies before sending. */
+  blockStreamingCoalesce?: BlockStreamingCoalesceConfig;
+  mediaMaxMb?: number;
+  /** Control reply threading when reply tags are present (off|first|all). */
+  replyToMode?: ReplyToMode;
+  /** Per-action tool gating (default: true for all). */
+  actions?: GoogleChatActionConfig;
+  dm?: GoogleChatDmConfig;
+};
+
+export type GoogleChatConfig = {
+  /** Optional per-account Google Chat configuration (multi-account). */
+  accounts?: Record<string, GoogleChatAccountConfig>;
+  /** Optional default account id when multiple accounts are configured. */
+  defaultAccount?: string;
+} & GoogleChatAccountConfig;

src/config/types.hooks.ts

@@ -23,6 +23,7 @@ export type HookMappingConfig = {
     | "whatsapp"
     | "telegram"
     | "discord"
+    | "googlechat"
     | "slack"
     | "signal"
     | "imessage"

src/config/types.queue.ts

@@ -12,6 +12,7 @@ export type QueueModeByProvider = {
   whatsapp?: QueueMode;
   telegram?: QueueMode;
   discord?: QueueMode;
+  googlechat?: QueueMode;
   slack?: QueueMode;
   signal?: QueueMode;
   imessage?: QueueMode;

src/config/types.ts

@@ -10,6 +10,7 @@ export * from "./types.channels.js";
 export * from "./types.clawdbot.js";
 export * from "./types.cron.js";
 export * from "./types.discord.js";
+export * from "./types.googlechat.js";
 export * from "./types.gateway.js";
 export * from "./types.hooks.js";
 export * from "./types.imessage.js";

src/config/zod-schema.providers-core.ts

@@ -260,6 +260,75 @@ export const DiscordConfigSchema = DiscordAccountSchema.extend({
   accounts: z.record(z.string(), DiscordAccountSchema.optional()).optional(),
 });
 
+export const GoogleChatDmSchema = z
+  .object({
+    enabled: z.boolean().optional(),
+    policy: DmPolicySchema.optional().default("pairing"),
+    allowFrom: z.array(z.union([z.string(), z.number()])).optional(),
+  })
+  .strict()
+  .superRefine((value, ctx) => {
+    requireOpenAllowFrom({
+      policy: value.policy,
+      allowFrom: value.allowFrom,
+      ctx,
+      path: ["allowFrom"],
+      message:
+        'channels.googlechat.dm.policy="open" requires channels.googlechat.dm.allowFrom to include "*"',
+    });
+  });
+
+export const GoogleChatGroupSchema = z
+  .object({
+    enabled: z.boolean().optional(),
+    allow: z.boolean().optional(),
+    requireMention: z.boolean().optional(),
+    users: z.array(z.union([z.string(), z.number()])).optional(),
+    systemPrompt: z.string().optional(),
+  })
+  .strict();
+
+export const GoogleChatAccountSchema = z
+  .object({
+    name: z.string().optional(),
+    capabilities: z.array(z.string()).optional(),
+    enabled: z.boolean().optional(),
+    configWrites: z.boolean().optional(),
+    allowBots: z.boolean().optional(),
+    requireMention: z.boolean().optional(),
+    groupPolicy: GroupPolicySchema.optional().default("allowlist"),
+    groupAllowFrom: z.array(z.union([z.string(), z.number()])).optional(),
+    groups: z.record(z.string(), GoogleChatGroupSchema.optional()).optional(),
+    serviceAccount: z.union([z.string(), z.record(z.string(), z.unknown())]).optional(),
+    serviceAccountFile: z.string().optional(),
+    audienceType: z.enum(["app-url", "project-number"]).optional(),
+    audience: z.string().optional(),
+    webhookPath: z.string().optional(),
+    webhookUrl: z.string().optional(),
+    botUser: z.string().optional(),
+    historyLimit: z.number().int().min(0).optional(),
+    dmHistoryLimit: z.number().int().min(0).optional(),
+    dms: z.record(z.string(), DmConfigSchema.optional()).optional(),
+    textChunkLimit: z.number().int().positive().optional(),
+    blockStreaming: z.boolean().optional(),
+    blockStreamingCoalesce: BlockStreamingCoalesceSchema.optional(),
+    mediaMaxMb: z.number().positive().optional(),
+    replyToMode: ReplyToModeSchema.optional(),
+    actions: z
+      .object({
+        reactions: z.boolean().optional(),
+      })
+      .strict()
+      .optional(),
+    dm: GoogleChatDmSchema.optional(),
+  })
+  .strict();
+
+export const GoogleChatConfigSchema = GoogleChatAccountSchema.extend({
+  accounts: z.record(z.string(), GoogleChatAccountSchema.optional()).optional(),
+  defaultAccount: z.string().optional(),
+});
+
 export const SlackDmSchema = z
   .object({
     enabled: z.boolean().optional(),

src/config/zod-schema.providers.ts

@@ -3,6 +3,7 @@ import { z } from "zod";
 import {
   BlueBubblesConfigSchema,
   DiscordConfigSchema,
+  GoogleChatConfigSchema,
   IMessageConfigSchema,
   MSTeamsConfigSchema,
   SignalConfigSchema,
@@ -29,6 +30,7 @@ export const ChannelsSchema = z
     whatsapp: WhatsAppConfigSchema.optional(),
     telegram: TelegramConfigSchema.optional(),
     discord: DiscordConfigSchema.optional(),
+    googlechat: GoogleChatConfigSchema.optional(),
     slack: SlackConfigSchema.optional(),
     signal: SignalConfigSchema.optional(),
     imessage: IMessageConfigSchema.optional(),

src/gateway/chat-sanitize.ts

@@ -6,6 +6,7 @@ const ENVELOPE_CHANNELS = [
   "Signal",
   "Slack",
   "Discord",
+  "Google Chat",
   "iMessage",
   "Teams",
   "Matrix",

src/plugin-sdk/index.ts

@@ -76,6 +76,11 @@ export type {
   GroupToolPolicyConfig,
   MarkdownConfig,
   MarkdownTableMode,
+  GoogleChatAccountConfig,
+  GoogleChatConfig,
+  GoogleChatDmConfig,
+  GoogleChatGroupConfig,
+  GoogleChatActionConfig,
   MSTeamsChannelConfig,
   MSTeamsConfig,
   MSTeamsReplyStyle,
@@ -83,6 +88,7 @@ export type {
 } from "../config/types.js";
 export {
   DiscordConfigSchema,
+  GoogleChatConfigSchema,
   IMessageConfigSchema,
   MSTeamsConfigSchema,
   SignalConfigSchema,
@@ -141,6 +147,7 @@ export { resolveControlCommandGate } from "../channels/command-gating.js";
 export {
   resolveBlueBubblesGroupRequireMention,
   resolveDiscordGroupRequireMention,
+  resolveGoogleChatGroupRequireMention,
   resolveIMessageGroupRequireMention,
   resolveSlackGroupRequireMention,
   resolveTelegramGroupRequireMention,

src/utils/message-channel.ts

@@ -22,6 +22,7 @@ const MARKDOWN_CAPABLE_CHANNELS = new Set<string>([
   "telegram",
   "signal",
   "discord",
+  "googlechat",
   "tui",
   INTERNAL_MESSAGE_CHANNEL,
 ]);

ui/src/ui/types.ts

@@ -41,6 +41,11 @@ export type ChannelAccountSnapshot = {
   tokenSource?: string | null;
   botTokenSource?: string | null;
   appTokenSource?: string | null;
+  credentialSource?: string | null;
+  audienceType?: string | null;
+  audience?: string | null;
+  webhookPath?: string | null;
+  webhookUrl?: string | null;
   baseUrl?: string | null;
   allowUnmentionedGroups?: boolean | null;
   cliPath?: string | null;
@@ -133,6 +138,28 @@ export type DiscordStatus = {
   lastProbeAt?: number | null;
 };
 
+export type GoogleChatProbe = {
+  ok: boolean;
+  status?: number | null;
+  error?: string | null;
+  elapsedMs?: number | null;
+};
+
+export type GoogleChatStatus = {
+  configured: boolean;
+  credentialSource?: string | null;
+  audienceType?: string | null;
+  audience?: string | null;
+  webhookPath?: string | null;
+  webhookUrl?: string | null;
+  running: boolean;
+  lastStartAt?: number | null;
+  lastStopAt?: number | null;
+  lastError?: string | null;
+  probe?: GoogleChatProbe | null;
+  lastProbeAt?: number | null;
+};
+
 export type SlackBot = {
   id?: string | null;
   name?: string | null;

ui/src/ui/views/channels.googlechat.ts

@@ -0,0 +1,74 @@
+import { html, nothing } from "lit";
+
+import { formatAgo } from "../format";
+import type { GoogleChatStatus } from "../types";
+import { renderChannelConfigSection } from "./channels.config";
+import type { ChannelsProps } from "./channels.types";
+
+export function renderGoogleChatCard(params: {
+  props: ChannelsProps;
+  googleChat?: GoogleChatStatus | null;
+  accountCountLabel: unknown;
+}) {
+  const { props, googleChat, accountCountLabel } = params;
+
+  return html`
+    <div class="card">
+      <div class="card-title">Google Chat</div>
+      <div class="card-sub">Chat API webhook status and channel configuration.</div>
+      ${accountCountLabel}
+
+      <div class="status-list" style="margin-top: 16px;">
+        <div>
+          <span class="label">Configured</span>
+          <span>${googleChat ? (googleChat.configured ? "Yes" : "No") : "n/a"}</span>
+        </div>
+        <div>
+          <span class="label">Running</span>
+          <span>${googleChat ? (googleChat.running ? "Yes" : "No") : "n/a"}</span>
+        </div>
+        <div>
+          <span class="label">Credential</span>
+          <span>${googleChat?.credentialSource ?? "n/a"}</span>
+        </div>
+        <div>
+          <span class="label">Audience</span>
+          <span>
+            ${googleChat?.audienceType
+              ? `${googleChat.audienceType}${googleChat.audience ? ` · ${googleChat.audience}` : ""}`
+              : "n/a"}
+          </span>
+        </div>
+        <div>
+          <span class="label">Last start</span>
+          <span>${googleChat?.lastStartAt ? formatAgo(googleChat.lastStartAt) : "n/a"}</span>
+        </div>
+        <div>
+          <span class="label">Last probe</span>
+          <span>${googleChat?.lastProbeAt ? formatAgo(googleChat.lastProbeAt) : "n/a"}</span>
+        </div>
+      </div>
+
+      ${googleChat?.lastError
+        ? html`<div class="callout danger" style="margin-top: 12px;">
+            ${googleChat.lastError}
+          </div>`
+        : nothing}
+
+      ${googleChat?.probe
+        ? html`<div class="callout" style="margin-top: 12px;">
+            Probe ${googleChat.probe.ok ? "ok" : "failed"} ·
+            ${googleChat.probe.status ?? ""} ${googleChat.probe.error ?? ""}
+          </div>`
+        : nothing}
+
+      ${renderChannelConfigSection({ channelId: "googlechat", props })}
+
+      <div class="row" style="margin-top: 12px;">
+        <button class="btn" @click=${() => props.onRefresh(true)}>
+          Probe
+        </button>
+      </div>
+    </div>
+  `;
+}

ui/src/ui/views/channels.ts

@@ -6,6 +6,7 @@ import type {
   ChannelUiMetaEntry,
   ChannelsStatusSnapshot,
   DiscordStatus,
+  GoogleChatStatus,
   IMessageStatus,
   NostrProfile,
   NostrStatus,
@@ -22,6 +23,7 @@ import type {
 import { channelEnabled, renderChannelAccountCount } from "./channels.shared";
 import { renderChannelConfigSection } from "./channels.config";
 import { renderDiscordCard } from "./channels.discord";
+import { renderGoogleChatCard } from "./channels.googlechat";
 import { renderIMessageCard } from "./channels.imessage";
 import { renderNostrCard } from "./channels.nostr";
 import { renderSignalCard } from "./channels.signal";
@@ -38,6 +40,7 @@ export function renderChannels(props: ChannelsProps) {
     | TelegramStatus
     | undefined;
   const discord = (channels?.discord ?? null) as DiscordStatus | null;
+  const googlechat = (channels?.googlechat ?? null) as GoogleChatStatus | null;
   const slack = (channels?.slack ?? null) as SlackStatus | null;
   const signal = (channels?.signal ?? null) as SignalStatus | null;
   const imessage = (channels?.imessage ?? null) as IMessageStatus | null;
@@ -61,6 +64,7 @@ export function renderChannels(props: ChannelsProps) {
           whatsapp,
           telegram,
           discord,
+          googlechat,
           slack,
           signal,
           imessage,
@@ -97,7 +101,16 @@ function resolveChannelOrder(snapshot: ChannelsStatusSnapshot | null): ChannelKe
   if (snapshot?.channelOrder?.length) {
     return snapshot.channelOrder;
   }
-  return ["whatsapp", "telegram", "discord", "slack", "signal", "imessage", "nostr"];
+  return [
+    "whatsapp",
+    "telegram",
+    "discord",
+    "googlechat",
+    "slack",
+    "signal",
+    "imessage",
+    "nostr",
+  ];
 }
 
 function renderChannel(
@@ -129,6 +142,12 @@ function renderChannel(
         discord: data.discord,
         accountCountLabel,
       });
+    case "googlechat":
+      return renderGoogleChatCard({
+        props,
+        googlechat: data.googlechat,
+        accountCountLabel,
+      });
     case "slack":
       return renderSlackCard({
         props,

ui/src/ui/views/channels.types.ts

@@ -1,15 +1,16 @@
 import type {
-  ChannelAccountSnapshot,
-  ChannelsStatusSnapshot,
-  ConfigUiHints,
-  DiscordStatus,
-  IMessageStatus,
-  NostrProfile,
-  NostrStatus,
-  SignalStatus,
-  SlackStatus,
-  TelegramStatus,
-  WhatsAppStatus,
+    ChannelAccountSnapshot,
+    ChannelsStatusSnapshot,
+    ConfigUiHints,
+    DiscordStatus,
+    GoogleChatStatus,
+    IMessageStatus,
+    NostrProfile,
+    NostrStatus,
+    SignalStatus,
+    SlackStatus,
+    TelegramStatus,
+    WhatsAppStatus,
 } from "../types";
 import type { NostrProfileFormState } from "./channels.nostr-profile-form";
 
@@ -52,6 +53,7 @@ export type ChannelsChannelData = {
   whatsapp?: WhatsAppStatus;
   telegram?: TelegramStatus;
   discord?: DiscordStatus | null;
+  googlechat?: GoogleChatStatus | null;
   slack?: SlackStatus | null;
   signal?: SignalStatus | null;
   imessage?: IMessageStatus | null;