feat: add beta googlechat channel

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 };
+};