feat(gateway): add Google Chat adapter

[canyugs]

Summary

Adds Google Chat support to the Custom Gateway. Users can chat with OAB agents via Google Chat DMs and Spaces.

Google Chat ──POST──▶ ┌──────────────────┐
                      │  Custom Gateway  │ ◀──WebSocket── OAB Pod
                      │     :8080        │   (OAB connects out)
                      └──────────────────┘

Changes

File	Change	Description
gateway/src/adapters/googlechat.rs	NEW	Google Chat adapter: webhook handler, JWT verification (Google OIDC), SA key auth, token cache, message splitting, bot filtering, thread replies
gateway/src/adapters/mod.rs	MOD	Add pub mod googlechat
gateway/src/main.rs	MOD	AppState + reply router + GoogleChatAdapter initialization
gateway/README.md	MOD	Add Google Chat env vars and /webhook/googlechat endpoint
docs/google-chat.md	NEW	Operator guide: prerequisites, setup, config reference, security, troubleshooting
docs/config-reference.md	MOD	Add "googlechat" to gateway platform values
charts/openab/values.yaml	MOD	Add googleChat config block under gateway
charts/openab/templates/gateway.yaml	MOD	Inject Google Chat env vars (secrets via secretKeyRef)
charts/openab/templates/gateway-secret.yaml	MOD	Add google-chat-sa-key-json and google-chat-access-token to unified Secret
charts/openab/tests/gateway_test.yaml	NEW	Helm rendering tests for Google Chat gateway configuration
README.md	MOD	Add Google Chat to architecture diagram and platform list

Key Design Decisions

1. JWT verification via Google OIDC — Webhook requests are signed by https://accounts.google.com (not chat@system.gserviceaccount.com). Verification uses Google's public JWKS at googleapis.com/oauth2/v3/certs, validates issuer, audience (webhook URL), and email suffix (@gcp-sa-gsuiteaddons.iam.gserviceaccount.com).

2. Service Account key auth — Google Chat doesn't support client credentials flow (unlike Teams/Feishu). The adapter signs JWTs with the SA private key to obtain access tokens, with automatic refresh before expiry.

3. GoogleChatAdapter struct — Encapsulates token_cache, access_token, jwt_verifier, and client in a single struct, following the same pattern as Teams and Feishu adapters.

4. Audience-based JWT verification — GOOGLE_CHAT_AUDIENCE env var (full webhook URL) is used as the expected JWT aud claim. If unset, verification is skipped with a warning (for local dev only).

5. Message splitting — Replies exceeding 4096 chars are split at newline/space boundaries to comply with Google Chat API limits.

Testing

Verified end-to-end on k3s with Helm chart deployment:

Scenario	Result
DM text message send/receive	PASS
Space @mention → agent reply in thread	PASS
JWT verification (valid token)	PASS
JWT rejection (missing/invalid token)	PASS
Bot message filtering (no self-echo)	PASS
Message splitting (>4096 chars)	PASS
Token auto-refresh (SA key)	PASS
cargo test — 91 gateway tests passed	PASS

Configuration

# Helm values.yaml
agents:
  kiro:
    gateway:
      enabled: true
      deploy: true
      url: "ws://openab-kiro-gateway:8080/ws"
      googleChat:
        saKeyJson: '{"type":"service_account",...}'
        audience: "https://your-domain.com/webhook/googlechat"

Not Yet Supported

• Reactions — Google Chat API only supports reactions with user auth, not service accounts
• File/image/voice attachments — attachment download + processing not yet implemented
• Markdown rendering — replies sent as plain text (Google Chat uses its own card markup)

Test plan

• CI build + cargo test passes
• Helm template rendering tests pass (7 suites, 74 tests)
• Deploy to a test cluster and verify DM + Space messages work
• Verify JWT verification rejects unsigned requests

🤖 Generated with Claude Code

[github-actions]

⚠️ This PR is missing a Discord Discussion URL in the body.

All PRs must reference a prior Discord discussion to ensure community alignment before implementation.

Please edit the PR description to include a link like:

Discord Discussion URL: https://discord.com/channels/...

This PR will be automatically closed in 3 days if the link is not added.

[Copilot]

Pull request overview

Adds a new Google Chat adapter to the Custom Gateway so Google Chat DMs/Spaces can be bridged into OAB via the existing WebSocket event/reply flow.

Changes:

• Introduces GoogleChatAdapter with webhook ingestion, (optional) JWT verification, and reply sending (including token refresh + message splitting).
• Wires the adapter into the gateway runtime (state + reply routing + webhook route mounting) and documents configuration.
• Extends Helm chart values/templates/tests and repo docs to support deploying/configuring the Google Chat adapter.

Reviewed changes

Copilot reviewed 12 out of 13 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
gateway/src/adapters/googlechat.rs	New adapter implementation: webhook parsing, JWT verification, token refresh, reply posting + splitting, unit tests
gateway/src/adapters/mod.rs	Exposes the new googlechat adapter module
gateway/src/main.rs	Adds adapter initialization, webhook route registration, and reply routing for platform="googlechat"
gateway/README.md	Documents gateway env vars + endpoint for Google Chat
docs/google-chat.md	Adds operator setup guide for Google Chat
docs/config-reference.md	Adds googlechat to supported gateway platform values
config.toml.example	Updates example gateway platform values
charts/openab/values.yaml	Adds gateway.googleChat configuration block
charts/openab/templates/gateway.yaml	Injects Google Chat env vars into the gateway Deployment when configured
charts/openab/templates/gateway-secret.yaml	Adds Google Chat secrets (SA key JSON / access token) to the unified Secret
charts/openab/tests/gateway_test.yaml	Adds Helm rendering tests for Google Chat env vars + secret keys
README.md	Updates top-level docs/diagram to mention Google Chat support via Custom Gateway
Cargo.lock	Lockfile updates associated with dependency graph/version changes

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[shaun-agent]

OpenAB PR Screening

This is auto-generated by the OpenAB project-screening flow for context collection and reviewer handoff.
Click 👍 if you find this useful. Human review will be done within 24 hours. We appreciate your support and contribution 🙏

• Title: feat(gateway): add Google Chat adapter
• Source: feat(gateway): add Google Chat adapter #718
• Status: moved to PR-Screening
• Generated at: 2026-05-03T20:05:48.473Z
• Discord thread: https://discord.com/channels/1488041051187974246/1500588984676515993

Screening report

## Intent

PR #718 adds Google Chat as a supported Custom Gateway platform so OpenAB agents can receive and reply to messages from Google Chat DMs and Spaces.

The operator-visible problem is that OpenAB currently supports other chat surfaces but not Google Chat, leaving Google Workspace deployments without a native gateway adapter. The PR attempts to close that gap with webhook intake, outbound replies, authentication, Helm config, and operator docs.

Feat

Feature.

The change introduces a googlechat gateway adapter that handles Google Chat webhook events, verifies Google-issued JWTs, filters bot/self messages, routes user messages to OAB pods over the gateway, and sends agent replies back to Google Chat threads. It also adds Helm values, Kubernetes secret wiring, docs, and config reference updates.

Who It Serves

Primary beneficiaries:

• Deployers running OpenAB in Google Workspace environments
• Google Chat end users who want to interact with OAB agents in DMs or Spaces
• Agent runtime operators who need another first-party gateway surface
• Maintainers reviewing platform adapter consistency across Slack, Teams, Feishu, and Google Chat

Rewritten Prompt

Implement Google Chat support for the OpenAB Custom Gateway.

Add a googlechat adapter that accepts Google Chat webhook events at /webhook/googlechat, verifies Google OIDC JWTs when GOOGLE_CHAT_AUDIENCE is configured, extracts supported text messages from DMs and Spaces, filters bot/self events, forwards user messages into the existing gateway routing path, and posts agent replies back to Google Chat using service account authentication.

Include Helm configuration for enabling Google Chat, secret-backed service account key injection, docs for Google Chat setup and security expectations, and tests covering webhook parsing, JWT rejection behavior, message splitting, bot filtering, and Helm rendering.

Keep unsupported features explicit: attachments, reactions, and rich card rendering are out of scope for the first merge.

Merge Pitch

This is worth advancing because Google Chat is a major enterprise messaging surface and fits OpenAB’s gateway strategy: users should be able to reach agents from the collaboration tools they already use.

Risk profile is moderate to high. The feature touches gateway runtime routing, auth/security validation, Helm secret handling, and adds a large new adapter file. The main reviewer concern should be whether JWT verification, token handling, and reply routing are implemented consistently with existing gateway adapters and whether the adapter introduces hidden operational risk through skipped verification, secret exposure, or self-echo loops.

Best-Practice Comparison

Relevant OpenClaw principles:

• Explicit delivery routing is directly relevant. Google Chat DMs, Spaces, and thread replies need deterministic routing back to the originating conversation.
• Retry/backoff and run logs are relevant for outbound reply delivery and Google API failures. The PR summary mentions token refresh but not durable outbound retry behavior.
• Isolated executions are partially relevant because this is a gateway adapter, not an execution runtime, but adapter failures should not destabilize other platforms.
• Durable job persistence is less directly applicable unless outbound replies are queued or scheduled.
• Gateway-owned scheduling is not relevant unless future Google Chat features include scheduled messages or polling.

Relevant Hermes Agent principles:

• Atomic writes and file locking are not directly relevant unless the adapter persists local state, which this PR does not appear to do.
• Fresh session per scheduled run is not relevant.
• Self-contained prompts are not relevant to webhook delivery.
• Gateway daemon tick model is not relevant for webhook-first Google Chat intake.
• The broader Hermes concern about preventing overlap maps loosely to avoiding duplicate webhook handling and self-echo loops.

Best-practice gap to check during follow-up: the PR should make failure modes observable. Token refresh failures, JWT verification failures, unsupported event types, and outbound post failures should produce useful logs without leaking secrets.

Implementation Options

Option 1: Conservative adapter merge

Merge a minimal Google Chat adapter focused only on text DMs and Space thread replies. Require GOOGLE_CHAT_AUDIENCE outside local development, keep service account auth, add focused unit tests and Helm rendering tests, and leave attachments/cards/reactions explicitly unsupported.

Option 2: Balanced production adapter

Accept the core PR but harden it before merge: enforce JWT verification in production-like deployments, add structured logs for auth and delivery failures, add retry/backoff for transient Google API send failures, verify secret handling in Helm, and ensure adapter behavior matches Teams/Feishu patterns.

Option 3: Gateway platform abstraction cleanup first

Before merging Google Chat, extract common adapter concerns across Teams, Feishu, and Google Chat: token caching, outbound message splitting, request verification hooks, bot filtering, and reply routing. Then land Google Chat on top of the shared abstraction.

Option 4: Ambitious durable delivery model

Add Google Chat support with a durable outbound message queue, retry/backoff, delivery logs, and idempotency keys for webhook events. This would align more closely with OpenClaw-style durable gateway operations but is significantly larger than a platform adapter PR.

Comparison Table

Option	Speed to ship	Complexity	Reliability	Maintainability	User impact	Fit for OpenAB right now
1. Conservative adapter merge	High	Medium	Medium	Medium	High for Google Chat users	Good if scope is tightly reviewed
2. Balanced production adapter	Medium	Medium-High	High	High	High	Best fit
3. Abstraction cleanup first	Low-Medium	High	Medium-High	High long term	Delayed	Useful, but likely too broad for this PR
4. Durable delivery model	Low	Very High	Very High	Medium-High	High	Better as a later gateway reliability project

Recommendation

Advance with Option 2: balanced production adapter.

The PR’s intent is strong and the feature is valuable, but the next review should focus on production hardening rather than expanding scope. Masami or Pahud should verify JWT enforcement semantics, service account secret handling, outbound error behavior, self-message filtering, and consistency with existing gateway adapters.

Suggested sequencing:

1. Review and tighten security defaults first, especially behavior when GOOGLE_CHAT_AUDIENCE is unset.
2. Validate adapter tests and Helm tests against realistic Google Chat payloads.
3. Merge text-message support only after auth, routing, and observability are solid.
4. Split attachments, reactions, cards, durable retries, and shared adapter abstractions into follow-up issues.

[chaodu-agent]

🟢 Looks good — solid addition

Verdict: Clean, well-structured Google Chat adapter that follows existing patterns (Teams, Feishu, LINE). No new dependencies. Comprehensive docs, Helm tests, and unit tests. No blocking issues — all items below are NITs.

四問框架 Review

1. What problem does this solve?

Adds Google Chat as the 5th gateway adapter platform. Users can chat with OAB agents via Google Chat DMs and Spaces, using the same Custom Gateway architecture as Telegram/LINE/Teams/Feishu.

2. How does it solve it?

• New googlechat.rs adapter (879 lines): webhook handler, JWT verification (Google OIDC JWKS), SA key auth with token auto-refresh, message splitting, bot filtering, thread replies
• GoogleChatAdapter struct encapsulates all state — same pattern as TeamsAdapter and FeishuAdapter
• Helm chart: googleChat config block under gateway, secrets via secretKeyRef
• Full operator guide (docs/google-chat.md), config reference updates, README architecture diagram update
• 8 Helm rendering tests + 25 unit tests covering parsing, splitting, JWT, token cache, bot filtering

3. What alternatives were considered?

• JWT verification uses Google OIDC (accounts.google.com issuer) with email suffix check (@gcp-sa-gsuiteaddons.iam.gserviceaccount.com) — correctly identifies Google Chat vs other Google services
• Supports both SA key (recommended, auto-refresh) and static access token (fallback, 1h TTL)
• Audience-based JWT verification with opt-out for local dev (logs warning)
• Explicitly documents unsupported features (reactions, attachments, markdown)

4. Is this the best approach?

Yes — follows established patterns, no new crates, clean separation. A few NITs below.

Traffic Light

🟢 INFO — Done well

• No new dependencies — reuses existing jsonwebtoken, reqwest, serde_json from Cargo.toml
• JWKS key rotation handling — cache miss triggers re-fetch before failing (line 155-163)
• Email claim verification — prevents accepting arbitrary Google-issued tokens (not just issuer check)
• Comprehensive Helm tests — 8 test cases covering enable/disable, secrets, env vars, negative cases
• Good docs — docs/google-chat.md covers prerequisites, setup, config, security, troubleshooting
• Bot filtering — user_type: "BOT" check prevents self-echo loops
• argument_text preference — correctly strips @mention prefix in Space messages

🟡 NIT — Non-blocking suggestions

1. Cargo.lock version bump 0.8.1 → 0.8.3 — This appears unrelated to the Google Chat feature. Consider reverting or splitting into a separate commit to keep the diff focused.

2. split_text limit is byte-based, not char-based — The GOOGLE_CHAT_MESSAGE_LIMIT (4096) and split_text function operate on byte offsets. For CJK text (3 bytes per char in UTF-8), the effective character limit is ~1365 chars. The Google Chat API limit is 4096 characters, not bytes. The is_char_boundary guards prevent panics, but messages may be split earlier than necessary. The existing test split_text_chinese_utf8_safe validates safety but not optimality.

3. JWKS cache TTL is hardcoded at 1 hour — Google's JWKS endpoint returns Cache-Control: max-age=N headers. Respecting that would be more correct, though 1 hour is a reasonable default and matches what other adapters do.

4. send_message doesn't retry on transient failures — A 429 or 5xx from the Google Chat API will log an error but not retry. This is consistent with the Teams and Feishu adapters (they don't retry either), so not a regression — but worth noting for future improvement across all adapters.

5. Two reqwest::Client instances — GoogleChatAdapter creates its own client, and GoogleChatJwtVerifier creates another. Could share one, but this is minor.

🔴 SUGGESTED CHANGES

None — no blocking issues found.

[chaodu-agent]

📊 Prior Art Analysis — Google Chat in Open-Source AI Agent Frameworks

Surveyed the major open-source AI agent frameworks for Google Chat support:

Framework	Google Chat Support	Notes
OpenClaw	❌ Broken	SA key auth fails with client_email JSON parse error (openclaw/openclaw#9945). Receiving works, sending does not. Issue closed as not planned.
Hermes Agent	❌ Not supported	Gateway supports Telegram, Discord, Slack, WhatsApp, Signal — no Google Chat.
Armis Agent	❌ Not supported	No Google Chat adapter found.

This PR would make OpenAB the first open-source AI agent framework with a working Google Chat adapter.

Notably, the GoogleChatTokenCache implementation in this PR directly addresses the exact failure point that broke OpenClaw's Google Chat support — it validates client_email and private_key fields upfront with clear error messages, and has unit tests covering invalid/missing SA key JSON scenarios (token_cache_rejects_invalid_json, token_cache_rejects_missing_fields, token_cache_accepts_valid_sa_key).

[chaodu-agent]

Approved — clean, additive Google Chat adapter following established gateway patterns.

Review summary (3/4 monks concur, no blocking issues):

• Pure additive change — no core code modified
• Custom Gateway + Webhook architecture, consistent with Telegram/LINE/Teams/Feishu adapters
• JWT verification correctly implements Google Workspace Add-on OIDC flow (v2 envelope)
• SA key auth with token auto-refresh — addresses the exact failure point that broke OpenClaw's Google Chat support (openclaw/openclaw#9945)
• Comprehensive docs, Helm tests, and unit tests
• First working Google Chat adapter among open-source AI agent frameworks (OpenClaw broken, Hermes/Armis unsupported)

NITs for future improvement (non-blocking):

1. split_text byte-based limit vs Google Chat's character-based 4096 limit (CJK splits earlier than necessary)
2. No inter-chunk delay for send_message (per-space write quota: 1 req/sec)
3. Cargo.lock version bump 0.8.1→0.8.3 appears unrelated
4. Two separate reqwest::Client instances could be shared
5. JWKS cache TTL hardcoded at 1 hour (could respect Cache-Control headers)