@kodelyth/googlechat 2026.5.39 → 2026.5.42

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kodelyth/googlechat",
-  "version": "2026.5.39",
+  "version": "2026.5.42",
   "description": "Klaw Google Chat channel plugin",
   "repository": {
     "type": "git",
@@ -14,7 +14,7 @@
   },
   "devDependencies": {
     "@kodelyth/plugin-sdk": "1.0.1",
-    "@kodelyth/klaw": "2026.5.41"
+    "@kodelyth/klaw": "2026.5.42"
   },
   "peerDependencies": {
     "@kodelyth/klaw": ">=2026.5.19"
@@ -26,9 +26,9 @@
   },
   "klaw": {
     "extensions": [
-      "./index.js"
+      "./index.ts"
     ],
-    "setupEntry": "./setup-entry.js",
+    "setupEntry": "./setup-entry.ts",
     "channel": {
       "id": "googlechat",
       "label": "Google Chat",

package/runtime-api.ts

@@ -0,0 +1,55 @@
+// Private runtime barrel for the bundled Google Chat extension.
+// Keep this barrel thin and avoid broad plugin-sdk surfaces during bootstrap.
+
+export { DEFAULT_ACCOUNT_ID } from "klaw/plugin-sdk/account-id";
+export {
+  createActionGate,
+  jsonResult,
+  readNumberParam,
+  readReactionParams,
+  readStringParam,
+} from "klaw/plugin-sdk/channel-actions";
+export { buildChannelConfigSchema } from "klaw/plugin-sdk/channel-config-primitives";
+export type {
+  ChannelMessageActionAdapter,
+  ChannelMessageActionName,
+  ChannelStatusIssue,
+} from "klaw/plugin-sdk/channel-contract";
+export { missingTargetError } from "klaw/plugin-sdk/channel-feedback";
+export {
+  createAccountStatusSink,
+  runPassiveAccountLifecycle,
+} from "klaw/plugin-sdk/channel-lifecycle";
+export { createChannelPairingController } from "klaw/plugin-sdk/channel-pairing";
+export { createChannelMessageReplyPipeline } from "klaw/plugin-sdk/channel-message";
+export { PAIRING_APPROVED_MESSAGE } from "klaw/plugin-sdk/channel-status";
+export { chunkTextForOutbound } from "klaw/plugin-sdk/text-chunking";
+export type { KlawConfig } from "klaw/plugin-sdk/config-contracts";
+export { GoogleChatConfigSchema } from "klaw/plugin-sdk/bundled-channel-config-schema";
+export {
+  GROUP_POLICY_BLOCKED_LABEL,
+  resolveAllowlistProviderRuntimeGroupPolicy,
+  resolveDefaultGroupPolicy,
+  warnMissingProviderGroupPolicyFallbackOnce,
+} from "klaw/plugin-sdk/runtime-group-policy";
+export { isDangerousNameMatchingEnabled } from "klaw/plugin-sdk/dangerous-name-runtime";
+export { readRemoteMediaBuffer, resolveChannelMediaMaxBytes } from "klaw/plugin-sdk/media-runtime";
+export { loadOutboundMediaFromUrl } from "klaw/plugin-sdk/outbound-media";
+export type { PluginRuntime } from "klaw/plugin-sdk/runtime-store";
+export { fetchWithSsrFGuard } from "klaw/plugin-sdk/ssrf-runtime";
+export type { GoogleChatAccountConfig, GoogleChatConfig } from "klaw/plugin-sdk/config-contracts";
+export { extractToolSend } from "klaw/plugin-sdk/tool-send";
+export { resolveInboundMentionDecision } from "klaw/plugin-sdk/channel-inbound";
+export { resolveInboundRouteEnvelopeBuilderWithRuntime } from "klaw/plugin-sdk/inbound-envelope";
+export { resolveWebhookPath } from "klaw/plugin-sdk/webhook-ingress";
+export {
+  registerWebhookTargetWithPluginRoute,
+  resolveWebhookTargetWithAuthOrReject,
+  withResolvedWebhookRequestPipeline,
+} from "klaw/plugin-sdk/webhook-targets";
+export {
+  createWebhookInFlightLimiter,
+  readJsonWebhookBodyOrReject,
+  type WebhookInFlightLimiter,
+} from "klaw/plugin-sdk/webhook-request-guards";
+export { setGoogleChatRuntime } from "./src/runtime.js";

package/secret-contract-api.ts

@@ -0,0 +1,5 @@
+export {
+  channelSecrets,
+  collectRuntimeConfigAssignments,
+  secretTargetRegistryEntries,
+} from "./src/secret-contract.js";

package/setup-entry.ts

@@ -0,0 +1,13 @@
+import { defineBundledChannelSetupEntry } from "klaw/plugin-sdk/channel-entry-contract";
+
+export default defineBundledChannelSetupEntry({
+  importMetaUrl: import.meta.url,
+  plugin: {
+    specifier: "./setup-plugin-api.js",
+    exportName: "googlechatSetupPlugin",
+  },
+  secrets: {
+    specifier: "./secret-contract-api.js",
+    exportName: "channelSecrets",
+  },
+});

package/setup-plugin-api.ts

@@ -0,0 +1,3 @@
+// Keep bundled setup entry imports narrow so setup loads do not pull the
+// broader Google Chat runtime plugin surface.
+export { googlechatSetupPlugin } from "./src/channel.setup.js";

package/src/accounts.ts

@@ -0,0 +1,181 @@
+import {
+  createAccountListHelpers,
+  DEFAULT_ACCOUNT_ID,
+  normalizeAccountId,
+  type KlawConfig,
+  resolveAccountEntry,
+  resolveMergedAccountConfig,
+} from "klaw/plugin-sdk/account-resolution";
+import { safeParseJsonWithSchema, safeParseWithSchema } from "klaw/plugin-sdk/extension-shared";
+import { mergePairLoopGuardConfig } from "klaw/plugin-sdk/pair-loop-guard-runtime";
+import { isSecretRef } from "klaw/plugin-sdk/secret-input";
+import { normalizeOptionalString } from "klaw/plugin-sdk/string-coerce-runtime";
+import { z } from "zod";
+import type { GoogleChatAccountConfig } from "./types.config.js";
+
+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;
+};
+
+export type GoogleChatConfigAccessorAccount = {
+  config: GoogleChatAccountConfig;
+};
+
+const ENV_SERVICE_ACCOUNT = "GOOGLE_CHAT_SERVICE_ACCOUNT";
+const ENV_SERVICE_ACCOUNT_FILE = "GOOGLE_CHAT_SERVICE_ACCOUNT_FILE";
+const JsonRecordSchema = z.record(z.string(), z.unknown());
+
+const {
+  listAccountIds: listGoogleChatAccountIds,
+  resolveDefaultAccountId: resolveDefaultGoogleChatAccountId,
+} = createAccountListHelpers("googlechat", {
+  implicitDefaultAccount: {
+    channelKeys: ["serviceAccount", "serviceAccountRef", "serviceAccountFile"],
+    envVars: [ENV_SERVICE_ACCOUNT, ENV_SERVICE_ACCOUNT_FILE],
+  },
+});
+export { listGoogleChatAccountIds, resolveDefaultGoogleChatAccountId };
+
+function mergeGoogleChatAccountConfig(cfg: KlawConfig, accountId: string): GoogleChatAccountConfig {
+  const raw = cfg.channels?.["googlechat"] ?? {};
+  const base = resolveMergedAccountConfig<GoogleChatAccountConfig>({
+    channelConfig: raw as GoogleChatAccountConfig,
+    accounts: raw.accounts as Record<string, Partial<GoogleChatAccountConfig>> | undefined,
+    accountId,
+    omitKeys: ["defaultAccount"],
+    nestedObjectKeys: ["botLoopProtection"],
+  });
+  const defaultAccountConfig = resolveAccountEntry(raw.accounts, DEFAULT_ACCOUNT_ID) ?? {};
+  if (accountId === DEFAULT_ACCOUNT_ID) {
+    return base;
+  }
+  const {
+    enabled: _ignoredEnabled,
+    dangerouslyAllowNameMatching: _ignoredDangerouslyAllowNameMatching,
+    serviceAccount: _ignoredServiceAccount,
+    serviceAccountRef: _ignoredServiceAccountRef,
+    serviceAccountFile: _ignoredServiceAccountFile,
+    ...defaultAccountShared
+  } = defaultAccountConfig;
+  // In multi-account setups, allow accounts.default to provide shared defaults
+  // (for example webhook/audience fields) while preserving top-level and account overrides.
+  const botLoopProtection = mergePairLoopGuardConfig(
+    defaultAccountShared.botLoopProtection,
+    base.botLoopProtection,
+  );
+  return {
+    ...defaultAccountShared,
+    ...base,
+    ...(botLoopProtection ? { botLoopProtection } : {}),
+  } as GoogleChatAccountConfig;
+}
+
+export function resolveGoogleChatConfigAccessorAccount(params: {
+  cfg: KlawConfig;
+  accountId?: string | null;
+}): GoogleChatConfigAccessorAccount {
+  const accountId = normalizeAccountId(
+    params.accountId ?? params.cfg.channels?.googlechat?.defaultAccount,
+  );
+  return { config: mergeGoogleChatAccountConfig(params.cfg, accountId) };
+}
+
+function parseServiceAccount(value: unknown): Record<string, unknown> | null {
+  if (isSecretRef(value)) {
+    return null;
+  }
+
+  if (typeof value === "string") {
+    const trimmed = value.trim();
+    if (!trimmed) {
+      return null;
+    }
+    return safeParseJsonWithSchema(JsonRecordSchema, trimmed);
+  }
+
+  return safeParseWithSchema(JsonRecordSchema, value);
+}
+
+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" };
+  }
+
+  if (isSecretRef(account.serviceAccount)) {
+    throw new Error(
+      `channels.googlechat.accounts.${accountId}.serviceAccount: unresolved SecretRef "${account.serviceAccount.source}:${account.serviceAccount.provider}:${account.serviceAccount.id}". Resolve this command against an active gateway runtime snapshot before reading it.`,
+    );
+  }
+
+  if (isSecretRef(account.serviceAccountRef)) {
+    throw new Error(
+      `channels.googlechat.accounts.${accountId}.serviceAccount: unresolved SecretRef "${account.serviceAccountRef.source}:${account.serviceAccountRef.provider}:${account.serviceAccountRef.id}". Resolve this command against an active gateway runtime snapshot before reading it.`,
+    );
+  }
+
+  const file = normalizeOptionalString(account.serviceAccountFile);
+  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 = normalizeOptionalString(process.env[ENV_SERVICE_ACCOUNT_FILE]);
+    if (envFile) {
+      return { credentialsFile: envFile, source: "env" };
+    }
+  }
+
+  return { source: "none" };
+}
+
+export function resolveGoogleChatAccount(params: {
+  cfg: KlawConfig;
+  accountId?: string | null;
+}): ResolvedGoogleChatAccount {
+  const accountId = normalizeAccountId(
+    params.accountId ?? params.cfg.channels?.["googlechat"]?.defaultAccount,
+  );
+  const baseEnabled = params.cfg.channels?.["googlechat"]?.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: normalizeOptionalString(merged.name),
+    enabled,
+    config: merged,
+    credentialSource: credentials.source,
+    credentials: credentials.credentials,
+    credentialsFile: credentials.credentialsFile,
+  };
+}
+
+export function listEnabledGoogleChatAccounts(cfg: KlawConfig): ResolvedGoogleChatAccount[] {
+  return listGoogleChatAccountIds(cfg)
+    .map((accountId) => resolveGoogleChatAccount({ cfg, accountId }))
+    .filter((account) => account.enabled);
+}

package/src/actions.test.ts

@@ -0,0 +1,289 @@
+import path from "node:path";
+import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+
+const listEnabledGoogleChatAccounts = vi.hoisted(() => vi.fn());
+const resolveGoogleChatAccount = vi.hoisted(() => vi.fn());
+const createGoogleChatReaction = vi.hoisted(() => vi.fn());
+const deleteGoogleChatReaction = vi.hoisted(() => vi.fn());
+const listGoogleChatReactions = vi.hoisted(() => vi.fn());
+const sendGoogleChatMessage = vi.hoisted(() => vi.fn());
+const uploadGoogleChatAttachment = vi.hoisted(() => vi.fn());
+const resolveGoogleChatOutboundSpace = vi.hoisted(() => vi.fn());
+const getGoogleChatRuntime = vi.hoisted(() => vi.fn());
+
+vi.mock("./accounts.js", () => ({
+  listEnabledGoogleChatAccounts,
+  resolveGoogleChatAccount,
+}));
+
+vi.mock("./api.js", () => ({
+  createGoogleChatReaction,
+  deleteGoogleChatReaction,
+  listGoogleChatReactions,
+  sendGoogleChatMessage,
+  uploadGoogleChatAttachment,
+}));
+
+vi.mock("./runtime.js", () => ({
+  getGoogleChatRuntime,
+}));
+
+vi.mock("./targets.js", () => ({
+  resolveGoogleChatOutboundSpace,
+}));
+
+let googlechatMessageActions: typeof import("./actions.js").googlechatMessageActions;
+
+describe("googlechat message actions", () => {
+  beforeAll(async () => {
+    ({ googlechatMessageActions } = await import("./actions.js"));
+  });
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  afterAll(() => {
+    vi.doUnmock("./accounts.js");
+    vi.doUnmock("./api.js");
+    vi.doUnmock("./runtime.js");
+    vi.doUnmock("./targets.js");
+    vi.resetModules();
+  });
+
+  function buildAccount(overrides: Record<string, unknown> = {}) {
+    return {
+      accountId: "default",
+      enabled: true,
+      credentialSource: "service-account",
+      config: {},
+      ...overrides,
+    };
+  }
+
+  function expectJsonResult(result: unknown, details: Record<string, unknown>) {
+    expect(result).toEqual({
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(details, null, 2),
+        },
+      ],
+      details,
+    });
+  }
+
+  it("describes send and reaction actions only when enabled accounts exist", () => {
+    listEnabledGoogleChatAccounts.mockReturnValueOnce([]);
+    expect(googlechatMessageActions.describeMessageTool?.({ cfg: {} as never })).toBeNull();
+
+    listEnabledGoogleChatAccounts.mockReturnValueOnce([
+      {
+        enabled: true,
+        credentialSource: "service-account",
+        config: { actions: { reactions: true } },
+      },
+    ]);
+
+    expect(googlechatMessageActions.describeMessageTool?.({ cfg: {} as never })).toEqual({
+      actions: ["send", "upload-file", "react", "reactions"],
+    });
+  });
+
+  it("honors account-scoped reaction gates during discovery", () => {
+    resolveGoogleChatAccount.mockImplementation(({ accountId }: { accountId?: string | null }) => ({
+      enabled: true,
+      credentialSource: "service-account",
+      config: {
+        actions: { reactions: accountId === "work" },
+      },
+    }));
+
+    expect(
+      googlechatMessageActions.describeMessageTool?.({ cfg: {} as never, accountId: "default" }),
+    ).toEqual({
+      actions: ["send", "upload-file"],
+    });
+    expect(
+      googlechatMessageActions.describeMessageTool?.({ cfg: {} as never, accountId: "work" }),
+    ).toEqual({
+      actions: ["send", "upload-file", "react", "reactions"],
+    });
+  });
+
+  it("sends messages with uploaded media through the resolved space", async () => {
+    const account = buildAccount({
+      config: { mediaMaxMb: 5 },
+    });
+    resolveGoogleChatAccount.mockReturnValue(account);
+    resolveGoogleChatOutboundSpace.mockResolvedValue("spaces/AAA");
+    const readRemoteMediaBuffer = vi.fn(async () => ({
+      buffer: Buffer.from("remote-bytes"),
+      fileName: "remote.png",
+      contentType: "image/png",
+    }));
+    getGoogleChatRuntime.mockReturnValue({
+      channel: {
+        media: {
+          readRemoteMediaBuffer,
+        },
+      },
+    });
+    uploadGoogleChatAttachment.mockResolvedValue({
+      attachmentUploadToken: "token-1",
+    });
+    sendGoogleChatMessage.mockResolvedValue({
+      messageName: "spaces/AAA/messages/msg-1",
+    });
+
+    if (!googlechatMessageActions.handleAction) {
+      throw new Error("Expected googlechatMessageActions.handleAction to be defined");
+    }
+    const result = await googlechatMessageActions.handleAction({
+      action: "send",
+      params: {
+        to: "spaces/AAA",
+        message: "caption",
+        media: "https://example.com/file.png",
+        threadId: "thread-1",
+      },
+      cfg: {},
+      accountId: "default",
+    } as never);
+
+    expect(resolveGoogleChatOutboundSpace).toHaveBeenCalledWith({
+      account,
+      target: "spaces/AAA",
+    });
+    expect(readRemoteMediaBuffer).toHaveBeenCalledWith({
+      url: "https://example.com/file.png",
+      maxBytes: 5 * 1024 * 1024,
+    });
+    expect(uploadGoogleChatAttachment).toHaveBeenCalledWith({
+      account,
+      space: "spaces/AAA",
+      filename: "remote.png",
+      buffer: Buffer.from("remote-bytes"),
+      contentType: "image/png",
+    });
+    expect(sendGoogleChatMessage).toHaveBeenCalledWith({
+      account,
+      space: "spaces/AAA",
+      text: "caption",
+      thread: "thread-1",
+      attachments: [{ attachmentUploadToken: "token-1", contentName: "remote.png" }],
+    });
+    expectJsonResult(result, { ok: true, to: "spaces/AAA" });
+  });
+
+  it("routes upload-file through the same attachment upload path with filename override", async () => {
+    const account = buildAccount({
+      config: { mediaMaxMb: 5 },
+    });
+    resolveGoogleChatAccount.mockReturnValue(account);
+    resolveGoogleChatOutboundSpace.mockResolvedValue("spaces/BBB");
+    const localRoot = "/tmp/googlechat-action-test";
+    const localPath = path.join(localRoot, "local.md");
+    const readFile = vi.fn(async () => Buffer.from("local-bytes"));
+    getGoogleChatRuntime.mockReturnValue({
+      channel: {
+        media: {
+          readRemoteMediaBuffer: vi.fn(),
+        },
+      },
+    });
+    uploadGoogleChatAttachment.mockResolvedValue({
+      attachmentUploadToken: "token-2",
+    });
+    sendGoogleChatMessage.mockResolvedValue({
+      messageName: "spaces/BBB/messages/msg-2",
+    });
+
+    if (!googlechatMessageActions.handleAction) {
+      throw new Error("Expected googlechatMessageActions.handleAction to be defined");
+    }
+    const result = await googlechatMessageActions.handleAction({
+      action: "upload-file",
+      params: {
+        to: "spaces/BBB",
+        path: localPath,
+        message: "notes",
+        filename: "renamed.txt",
+      },
+      cfg: {},
+      accountId: "default",
+      mediaLocalRoots: [localRoot],
+      mediaReadFile: readFile,
+    } as never);
+
+    expect(readFile).toHaveBeenCalledWith(localPath);
+    expect(uploadGoogleChatAttachment).toHaveBeenCalledWith({
+      account,
+      space: "spaces/BBB",
+      filename: "renamed.txt",
+      buffer: Buffer.from("local-bytes"),
+      contentType: "text/markdown",
+    });
+    expect(sendGoogleChatMessage).toHaveBeenCalledWith({
+      account,
+      space: "spaces/BBB",
+      text: "notes",
+      thread: undefined,
+      attachments: [{ attachmentUploadToken: "token-2", contentName: "renamed.txt" }],
+    });
+    expectJsonResult(result, { ok: true, to: "spaces/BBB" });
+  });
+
+  it("removes only matching app reactions on react remove", async () => {
+    const account = buildAccount({
+      config: { botUser: "users/app-bot" },
+    });
+    resolveGoogleChatAccount.mockReturnValue(account);
+    listGoogleChatReactions.mockResolvedValue([
+      {
+        name: "reactions/1",
+        emoji: { unicode: "👍" },
+        user: { name: "users/app" },
+      },
+      {
+        name: "reactions/2",
+        emoji: { unicode: "👍" },
+        user: { name: "users/app-bot" },
+      },
+      {
+        name: "reactions/3",
+        emoji: { unicode: "👍" },
+        user: { name: "users/other" },
+      },
+    ]);
+
+    if (!googlechatMessageActions.handleAction) {
+      throw new Error("Expected googlechatMessageActions.handleAction to be defined");
+    }
+    const result = await googlechatMessageActions.handleAction({
+      action: "react",
+      params: {
+        messageId: "spaces/AAA/messages/msg-1",
+        emoji: "👍",
+        remove: true,
+      },
+      cfg: {},
+      accountId: "default",
+    } as never);
+
+    expect(listGoogleChatReactions).toHaveBeenCalledWith({
+      account,
+      messageName: "spaces/AAA/messages/msg-1",
+    });
+    expect(deleteGoogleChatReaction).toHaveBeenCalledTimes(2);
+    expect(deleteGoogleChatReaction).toHaveBeenNthCalledWith(1, {
+      account,
+      reactionName: "reactions/1",
+    });
+    expect(deleteGoogleChatReaction).toHaveBeenNthCalledWith(2, {
+      account,
+      reactionName: "reactions/2",
+    });
+    expectJsonResult(result, { ok: true, removed: 2 });
+  });
+});