@actagent/googlechat 2026.6.2

package/src/channel.adapters.ts

@@ -0,0 +1,363 @@
+// Googlechat plugin module implements channel.adapters behavior.
+import { adaptScopedAccountAccessor } from "actagent/plugin-sdk/channel-config-helpers";
+import type {
+  ChannelThreadingContext,
+  ChannelThreadingToolContext,
+} from "actagent/plugin-sdk/channel-contract";
+import {
+  createMessageReceiptFromOutboundResults,
+  defineChannelMessageAdapter,
+  type MessageReceiptPartKind,
+} from "actagent/plugin-sdk/channel-outbound";
+import { sanitizeForPlainText } from "actagent/plugin-sdk/channel-outbound";
+import {
+  composeAccountWarningCollectors,
+  createAllowlistProviderOpenWarningCollector,
+} from "actagent/plugin-sdk/channel-policy";
+import {
+  createChannelDirectoryAdapter,
+  listResolvedDirectoryGroupEntriesFromMapKeys,
+  listResolvedDirectoryUserEntriesFromAllowFrom,
+} from "actagent/plugin-sdk/directory-runtime";
+import { createLazyRuntimeNamedExport } from "actagent/plugin-sdk/lazy-runtime";
+import type { OutboundMediaLoadOptions } from "actagent/plugin-sdk/outbound-media";
+import type { ReplyPayload } from "actagent/plugin-sdk/reply-runtime";
+import { normalizeOptionalString } from "actagent/plugin-sdk/string-coerce-runtime";
+import { shouldSuppressGoogleChatManualExecApprovalFollowupPayload } from "./approval-card-actions.js";
+import { formatGoogleChatAllowFromEntry } from "./channel-base.js";
+import {
+  type ResolvedGoogleChatAccount,
+  chunkTextForOutbound,
+  readRemoteMediaBuffer,
+  isGoogleChatUserTarget,
+  loadOutboundMediaFromUrl,
+  missingTargetError,
+  normalizeGoogleChatTarget,
+  PAIRING_APPROVED_MESSAGE,
+  resolveChannelMediaMaxBytes,
+  resolveGoogleChatAccount,
+  resolveGoogleChatOutboundSpace,
+  type ACTAgentConfig,
+} from "./channel.deps.runtime.js";
+import { resolveGoogleChatGroupRequireMention } from "./group-policy.js";
+
+const loadGoogleChatChannelRuntime = createLazyRuntimeNamedExport(
+  () => import("./channel.runtime.js"),
+  "googleChatChannelRuntime",
+);
+
+function createGoogleChatSendReceipt(params: {
+  messageId?: string;
+  chatId: string;
+  kind: MessageReceiptPartKind;
+}) {
+  const messageId = params.messageId?.trim();
+  return createMessageReceiptFromOutboundResults({
+    results: messageId
+      ? [
+          {
+            channel: "googlechat",
+            messageId,
+            chatId: params.chatId,
+            conversationId: params.chatId,
+          },
+        ]
+      : [],
+    threadId: params.chatId,
+    kind: params.kind,
+  });
+}
+
+export const formatAllowFromEntry = formatGoogleChatAllowFromEntry;
+
+const collectGoogleChatGroupPolicyWarnings =
+  createAllowlistProviderOpenWarningCollector<ResolvedGoogleChatAccount>({
+    providerConfigPresent: (cfg) => cfg.channels?.googlechat !== undefined,
+    resolveGroupPolicy: (account) => account.config.groupPolicy,
+    buildOpenWarning: {
+      surface: "Google Chat spaces",
+      openBehavior: "allows any space to trigger (mention-gated)",
+      remediation:
+        'Set channels.googlechat.groupPolicy="allowlist" and configure channels.googlechat.groups',
+    },
+  });
+
+const collectGoogleChatSecurityWarnings = composeAccountWarningCollectors<
+  ResolvedGoogleChatAccount,
+  {
+    cfg: ACTAgentConfig;
+    account: ResolvedGoogleChatAccount;
+  }
+>(
+  collectGoogleChatGroupPolicyWarnings,
+  (account) =>
+    account.config.dm?.policy === "open" &&
+    '- Google Chat DMs are open to anyone. Set channels.googlechat.dm.policy="pairing" or "allowlist".',
+);
+
+export const googlechatGroupsAdapter = {
+  resolveRequireMention: resolveGoogleChatGroupRequireMention,
+};
+
+export const googlechatDirectoryAdapter = createChannelDirectoryAdapter({
+  listPeers: async (params) =>
+    listResolvedDirectoryUserEntriesFromAllowFrom<ResolvedGoogleChatAccount>({
+      ...params,
+      resolveAccount: adaptScopedAccountAccessor(resolveGoogleChatAccount),
+      resolveAllowFrom: (account) => account.config.dm?.allowFrom,
+      normalizeId: (entry) => normalizeGoogleChatTarget(entry) ?? entry,
+    }),
+  listGroups: async (params) =>
+    listResolvedDirectoryGroupEntriesFromMapKeys<ResolvedGoogleChatAccount>({
+      ...params,
+      resolveAccount: adaptScopedAccountAccessor(resolveGoogleChatAccount),
+      resolveGroups: (account) => account.config.groups,
+    }),
+});
+
+export const googlechatSecurityAdapter = {
+  dm: {
+    channelKey: "googlechat",
+    resolvePolicy: (account: ResolvedGoogleChatAccount) => account.config.dm?.policy,
+    resolveAllowFrom: (account: ResolvedGoogleChatAccount) => account.config.dm?.allowFrom,
+    allowFromPathSuffix: "dm.",
+    normalizeEntry: (raw: string) => formatAllowFromEntry(raw),
+  },
+  collectWarnings: collectGoogleChatSecurityWarnings,
+};
+
+export const googlechatThreadingAdapter = {
+  scopedAccountReplyToMode: {
+    resolveAccount: (cfg: ACTAgentConfig, accountId?: string | null) =>
+      resolveGoogleChatAccount({ cfg, accountId }),
+    resolveReplyToMode: (account: ResolvedGoogleChatAccount, _chatType?: string | null) =>
+      account.config.replyToMode,
+    fallback: "off" as const,
+  },
+  buildToolContext: ({
+    cfg,
+    accountId,
+    context,
+    hasRepliedRef,
+  }: {
+    cfg: ACTAgentConfig;
+    accountId?: string | null;
+    context: ChannelThreadingContext;
+    hasRepliedRef?: { value: boolean };
+  }): ChannelThreadingToolContext => {
+    const currentChannelId = normalizeGoogleChatTarget(context.To);
+    const replyToId =
+      normalizeOptionalString(context.ReplyToIdFull) ?? normalizeOptionalString(context.ReplyToId);
+
+    return {
+      currentChannelId,
+      currentMessageId: replyToId,
+      currentThreadTs: replyToId,
+      replyToMode: resolveGoogleChatAccount({ cfg, accountId }).config.replyToMode,
+      hasRepliedRef,
+    };
+  },
+};
+
+export const googlechatPairingTextAdapter = {
+  idLabel: "googlechatUserId",
+  message: PAIRING_APPROVED_MESSAGE,
+  normalizeAllowEntry: (entry: string) => formatAllowFromEntry(entry),
+  notify: async ({
+    cfg,
+    id,
+    message,
+    accountId,
+  }: {
+    cfg: ACTAgentConfig;
+    id: string;
+    message: string;
+    accountId?: string | null;
+  }) => {
+    const account = resolveGoogleChatAccount({ cfg, accountId });
+    if (account.credentialSource === "none") {
+      return;
+    }
+    const user = normalizeGoogleChatTarget(id) ?? id;
+    const target = isGoogleChatUserTarget(user) ? user : `users/${user}`;
+    const space = await resolveGoogleChatOutboundSpace({ account, target });
+    const { sendGoogleChatMessage } = await loadGoogleChatChannelRuntime();
+    await sendGoogleChatMessage({
+      account,
+      space,
+      text: message,
+    });
+  },
+};
+
+export const googlechatOutboundAdapter = {
+  base: {
+    deliveryMode: "direct" as const,
+    chunker: chunkTextForOutbound,
+    chunkerMode: "markdown" as const,
+    textChunkLimit: 4000,
+    sanitizeText: ({ text }: { text: string }) => sanitizeForPlainText(text),
+    normalizePayload: ({ payload }: { payload: ReplyPayload }) =>
+      shouldSuppressGoogleChatManualExecApprovalFollowupPayload(payload) ? null : payload,
+    resolveTarget: ({ to }: { to?: string }) => {
+      const trimmed = normalizeOptionalString(to) ?? "";
+
+      if (trimmed) {
+        const normalized = normalizeGoogleChatTarget(trimmed);
+        if (!normalized) {
+          return {
+            ok: false as const,
+            error: missingTargetError("Google Chat", "<spaces/{space}|users/{user}>"),
+          };
+        }
+        return { ok: true as const, to: normalized };
+      }
+
+      return {
+        ok: false as const,
+        error: missingTargetError("Google Chat", "<spaces/{space}|users/{user}>"),
+      };
+    },
+  },
+  attachedResults: {
+    channel: "googlechat" as const,
+    sendText: async ({
+      cfg,
+      to,
+      text,
+      accountId,
+      replyToId,
+      threadId,
+    }: {
+      cfg: ACTAgentConfig;
+      to: string;
+      text: string;
+      accountId?: string | null;
+      replyToId?: string | null;
+      threadId?: string | number | null;
+    }) => {
+      const account = resolveGoogleChatAccount({
+        cfg,
+        accountId,
+      });
+      const space = await resolveGoogleChatOutboundSpace({ account, target: to });
+      const thread =
+        typeof threadId === "number" ? String(threadId) : (threadId ?? replyToId ?? undefined);
+      const { sendGoogleChatMessage } = await loadGoogleChatChannelRuntime();
+      const result = await sendGoogleChatMessage({
+        account,
+        space,
+        text,
+        thread,
+      });
+      const messageId = result?.messageName ?? "";
+      return {
+        messageId,
+        chatId: space,
+        receipt: createGoogleChatSendReceipt({ messageId, chatId: space, kind: "text" }),
+      };
+    },
+    sendMedia: async ({
+      cfg,
+      to,
+      text,
+      mediaUrl,
+      mediaAccess,
+      mediaLocalRoots,
+      mediaReadFile,
+      accountId,
+      replyToId,
+      threadId,
+    }: {
+      cfg: ACTAgentConfig;
+      to: string;
+      text?: string;
+      mediaUrl?: string;
+      mediaAccess?: OutboundMediaLoadOptions["mediaAccess"];
+      mediaLocalRoots?: OutboundMediaLoadOptions["mediaLocalRoots"];
+      mediaReadFile?: OutboundMediaLoadOptions["mediaReadFile"];
+      accountId?: string | null;
+      replyToId?: string | null;
+      threadId?: string | number | null;
+    }) => {
+      if (!mediaUrl) {
+        throw new Error("Google Chat mediaUrl is required.");
+      }
+      const account = resolveGoogleChatAccount({
+        cfg,
+        accountId,
+      });
+      const space = await resolveGoogleChatOutboundSpace({ account, target: to });
+      const thread =
+        typeof threadId === "number" ? String(threadId) : (threadId ?? replyToId ?? undefined);
+      const maxBytes = resolveChannelMediaMaxBytes({
+        cfg,
+        resolveChannelLimitMb: ({ cfg: cfgLocal, accountId: accountIdLocal }) =>
+          (
+            cfgLocal.channels?.googlechat as
+              | { accounts?: Record<string, { mediaMaxMb?: number }>; mediaMaxMb?: number }
+              | undefined
+          )?.accounts?.[accountIdLocal]?.mediaMaxMb ??
+          (cfgLocal.channels?.googlechat as { mediaMaxMb?: number } | undefined)?.mediaMaxMb,
+        accountId,
+      });
+      const effectiveMaxBytes = maxBytes ?? (account.config.mediaMaxMb ?? 20) * 1024 * 1024;
+      const loaded = /^https?:\/\//i.test(mediaUrl)
+        ? await readRemoteMediaBuffer({
+            url: mediaUrl,
+            maxBytes: effectiveMaxBytes,
+          })
+        : await loadOutboundMediaFromUrl(mediaUrl, {
+            maxBytes: effectiveMaxBytes,
+            mediaAccess,
+            mediaLocalRoots,
+            mediaReadFile,
+          });
+      const { sendGoogleChatMessage, uploadGoogleChatAttachment } =
+        await loadGoogleChatChannelRuntime();
+      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,
+      });
+      const messageId = result?.messageName ?? "";
+      return {
+        messageId,
+        chatId: space,
+        receipt: createGoogleChatSendReceipt({ messageId, chatId: space, kind: "media" }),
+      };
+    },
+  },
+};
+
+export const googlechatMessageAdapter = defineChannelMessageAdapter({
+  id: "googlechat",
+  durableFinal: {
+    capabilities: {
+      text: true,
+      media: true,
+      thread: true,
+      messageSendingHooks: true,
+    },
+  },
+  send: {
+    text: googlechatOutboundAdapter.attachedResults.sendText,
+    media: googlechatOutboundAdapter.attachedResults.sendMedia,
+  },
+});

package/src/channel.deps.runtime.ts

@@ -0,0 +1,30 @@
+// Googlechat plugin module implements channeleps behavior.
+export {
+  buildChannelConfigSchema,
+  chunkTextForOutbound,
+  DEFAULT_ACCOUNT_ID,
+  readRemoteMediaBuffer,
+  GoogleChatConfigSchema,
+  loadOutboundMediaFromUrl,
+  missingTargetError,
+  PAIRING_APPROVED_MESSAGE,
+  resolveChannelMediaMaxBytes,
+  type ChannelMessageActionAdapter,
+  type ChannelMessageActionName,
+  type ChannelStatusIssue,
+  type ACTAgentConfig,
+} from "../runtime-api.js";
+export {
+  type GoogleChatConfigAccessorAccount,
+  listGoogleChatAccountIds,
+  resolveGoogleChatConfigAccessorAccount,
+  resolveDefaultGoogleChatAccountId,
+  resolveGoogleChatAccount,
+  type ResolvedGoogleChatAccount,
+} from "./accounts.js";
+export {
+  isGoogleChatSpaceTarget,
+  isGoogleChatUserTarget,
+  normalizeGoogleChatTarget,
+  resolveGoogleChatOutboundSpace,
+} from "./targets.js";

package/src/channel.runtime.ts

@@ -0,0 +1,18 @@
+// Googlechat plugin module implements channel behavior.
+import {
+  probeGoogleChat as probeGoogleChatImpl,
+  sendGoogleChatMessage as sendGoogleChatMessageImpl,
+  uploadGoogleChatAttachment as uploadGoogleChatAttachmentImpl,
+} from "./api.js";
+import {
+  resolveGoogleChatWebhookPath as resolveGoogleChatWebhookPathImpl,
+  startGoogleChatMonitor as startGoogleChatMonitorImpl,
+} from "./monitor.js";
+
+export const googleChatChannelRuntime = {
+  probeGoogleChat: probeGoogleChatImpl,
+  sendGoogleChatMessage: sendGoogleChatMessageImpl,
+  uploadGoogleChatAttachment: uploadGoogleChatAttachmentImpl,
+  resolveGoogleChatWebhookPath: resolveGoogleChatWebhookPathImpl,
+  startGoogleChatMonitor: startGoogleChatMonitorImpl,
+};

package/src/channel.setup.ts

@@ -0,0 +1,7 @@
+// Googlechat plugin module implements channel.setup behavior.
+import type { ChannelPlugin } from "actagent/plugin-sdk/channel-core";
+import type { ResolvedGoogleChatAccount } from "./accounts.js";
+import { createGoogleChatPluginBase } from "./channel-base.js";
+
+export const googlechatSetupPlugin: ChannelPlugin<ResolvedGoogleChatAccount> =
+  createGoogleChatPluginBase();