@actagent/googlechat 2026.6.2

package/src/approval-native.test.ts

@@ -0,0 +1,399 @@
+import type { ChannelOutboundPayloadHint } from "actagent/plugin-sdk/channel-contract";
+import type { ACTAgentConfig } from "actagent/plugin-sdk/config-contracts";
+import type { ReplyPayload } from "actagent/plugin-sdk/reply-runtime";
+import { describe, expect, it } from "vitest";
+import {
+  googleChatApprovalCapability,
+  shouldHandleGoogleChatNativeApprovalRequest,
+  shouldSuppressLocalGoogleChatExecApprovalPrompt,
+} from "./approval-native.js";
+
+const GOOGLE_CHAT_APPROVAL_ACCOUNT = {
+  serviceAccount: {
+    type: "service_account" as const,
+    client_email: "bot@example.com",
+    private_key: "test-key",
+    token_uri: "https://oauth2.googleapis.com/token",
+  },
+  audienceType: "app-url" as const,
+  audience: "https://chat-app.example.test/googlechat",
+  appPrincipal: "123456789012345678901",
+  dm: { allowFrom: ["users/123"] },
+};
+
+const execApprovalPayload: ReplyPayload = {
+  text: "I need approval to run this command.",
+  channelData: {
+    execApproval: {
+      approvalId: "12345678-1234-1234-1234-123456789012",
+      approvalSlug: "12345678",
+      approvalKind: "exec",
+      agentId: "dev",
+      sessionKey: "agent:dev:main",
+    },
+  },
+};
+
+const activeExecApprovalHint: ChannelOutboundPayloadHint = {
+  kind: "approval-pending",
+  approvalKind: "exec",
+  nativeRouteActive: true,
+};
+
+describe("googleChatApprovalCapability", () => {
+  it("declares native exec and plugin approval runtime support", async () => {
+    const runtime = googleChatApprovalCapability.nativeRuntime;
+    expect(runtime?.eventKinds).toEqual(["exec", "plugin"]);
+    expect(
+      runtime?.availability.isConfigured({
+        cfg: {
+          approvals: { exec: { enabled: true } },
+          channels: {
+            googlechat: {
+              serviceAccount: {
+                type: "service_account",
+                client_email: "bot@example.com",
+                private_key: "test-key",
+                token_uri: "https://oauth2.googleapis.com/token",
+              },
+              audienceType: "app-url",
+              audience: "https://chat-app.example.test/googlechat",
+              appPrincipal: "123456789012345678901",
+              dm: { allowFrom: ["users/123"] },
+            },
+          },
+        },
+      }),
+    ).toBe(true);
+  });
+
+  it("does not enable native cards when webhook callback audience auth is incomplete", async () => {
+    const runtime = googleChatApprovalCapability.nativeRuntime;
+    expect(
+      runtime?.availability.isConfigured({
+        cfg: {
+          approvals: { exec: { enabled: true } },
+          channels: {
+            googlechat: {
+              serviceAccount: {
+                type: "service_account",
+                client_email: "bot@example.com",
+                private_key: "test-key",
+                token_uri: "https://oauth2.googleapis.com/token",
+              },
+              dm: { allowFrom: ["users/123"] },
+            },
+          },
+        },
+      }),
+    ).toBe(false);
+    expect(
+      runtime?.availability.isConfigured({
+        cfg: {
+          approvals: { exec: { enabled: true } },
+          channels: {
+            googlechat: {
+              serviceAccount: {
+                type: "service_account",
+                client_email: "bot@example.com",
+                private_key: "test-key",
+                token_uri: "https://oauth2.googleapis.com/token",
+              },
+              audienceType: "project-number",
+              dm: { allowFrom: ["users/123"] },
+            },
+          },
+        },
+      }),
+    ).toBe(false);
+  });
+
+  it("requires a top-level approval forwarding route before enabling native cards", async () => {
+    const runtime = googleChatApprovalCapability.nativeRuntime;
+    const googlechat = {
+      serviceAccount: {
+        type: "service_account" as const,
+        client_email: "bot@example.com",
+        private_key: "test-key",
+        token_uri: "https://oauth2.googleapis.com/token",
+      },
+      audienceType: "app-url" as const,
+      audience: "https://chat-app.example.test/googlechat",
+      dm: { allowFrom: ["users/123"] },
+    };
+
+    expect(
+      runtime?.availability.isConfigured({
+        cfg: { channels: { googlechat } },
+      }),
+    ).toBe(false);
+    expect(
+      runtime?.availability.isConfigured({
+        cfg: {
+          approvals: { exec: { enabled: false } },
+          channels: { googlechat },
+        },
+      }),
+    ).toBe(false);
+    expect(
+      runtime?.availability.isConfigured({
+        cfg: {
+          approvals: { exec: { enabled: true, mode: "targets" } },
+          channels: { googlechat },
+        },
+      }),
+    ).toBe(false);
+    expect(
+      runtime?.availability.isConfigured({
+        cfg: {
+          approvals: { plugin: { enabled: true } },
+          channels: { googlechat },
+        },
+      }),
+    ).toBe(true);
+  });
+
+  it("enables native cards for supported webhook audience modes", async () => {
+    const runtime = googleChatApprovalCapability.nativeRuntime;
+    expect(
+      runtime?.availability.isConfigured({
+        cfg: {
+          approvals: { exec: { enabled: true } },
+          channels: {
+            googlechat: {
+              serviceAccount: {
+                type: "service_account",
+                client_email: "bot@example.com",
+                private_key: "test-key",
+                token_uri: "https://oauth2.googleapis.com/token",
+              },
+              audienceType: "app-url",
+              audience: "https://chat-app.example.test/googlechat",
+              dm: { allowFrom: ["users/123"] },
+            },
+          },
+        },
+      }),
+    ).toBe(true);
+    expect(
+      runtime?.availability.isConfigured({
+        cfg: {
+          approvals: { exec: { enabled: true } },
+          channels: {
+            googlechat: {
+              serviceAccount: {
+                type: "service_account",
+                client_email: "bot@example.com",
+                private_key: "test-key",
+                token_uri: "https://oauth2.googleapis.com/token",
+              },
+              audienceType: "project-number",
+              audience: "1234567890",
+              dm: { allowFrom: ["users/123"] },
+            },
+          },
+        },
+      }),
+    ).toBe(true);
+  });
+
+  it("preserves Google Chat approval actor authorization", () => {
+    expect(
+      googleChatApprovalCapability.authorizeActorAction?.({
+        cfg: { channels: { googlechat: { dm: { allowFrom: ["users/123"] } } } },
+        senderId: "users/123",
+        action: "approve",
+        approvalKind: "plugin",
+      }),
+    ).toEqual({ authorized: true });
+
+    expect(
+      googleChatApprovalCapability.authorizeActorAction?.({
+        cfg: { channels: { googlechat: { dm: { allowFrom: ["users/123"] } } } },
+        senderId: "users/999",
+        action: "approve",
+        approvalKind: "plugin",
+      }),
+    ).toEqual({
+      authorized: false,
+      reason: "❌ You are not authorized to approve plugin requests on Google Chat.",
+    });
+  });
+
+  it("only handles approvals for the originating Google Chat account", () => {
+    const cfg: ACTAgentConfig = {
+      approvals: { exec: { enabled: true } },
+      channels: {
+        googlechat: {
+          accounts: {
+            alpha: {
+              enabled: true,
+              serviceAccount: {
+                type: "service_account",
+                client_email: "alpha@example.com",
+                private_key: "test-key",
+                token_uri: "https://oauth2.googleapis.com/token",
+              },
+              audienceType: "app-url",
+              audience: "https://alpha.example.com/googlechat",
+              appPrincipal: "123456789012345678901",
+              dm: { allowFrom: ["users/123"] },
+            },
+            beta: {
+              enabled: true,
+              serviceAccount: {
+                type: "service_account",
+                client_email: "beta@example.com",
+                private_key: "test-key",
+                token_uri: "https://oauth2.googleapis.com/token",
+              },
+              audienceType: "app-url",
+              audience: "https://beta.example.com/googlechat",
+              appPrincipal: "987654321098765432109",
+              dm: { allowFrom: ["users/456"] },
+            },
+          },
+        },
+      },
+    };
+    const request = {
+      id: "approval-1",
+      request: {
+        command: "echo hi",
+        turnSourceChannel: "googlechat",
+        turnSourceAccountId: "alpha",
+        turnSourceTo: "spaces/AAA",
+      },
+    } as never;
+
+    expect(
+      shouldHandleGoogleChatNativeApprovalRequest({
+        cfg,
+        accountId: "alpha",
+        request,
+      }),
+    ).toBe(true);
+    expect(
+      shouldHandleGoogleChatNativeApprovalRequest({
+        cfg,
+        accountId: "beta",
+        request,
+      }),
+    ).toBe(false);
+  });
+
+  it("does not handle exec approvals when only plugin approval forwarding is enabled", () => {
+    const cfg: ACTAgentConfig = {
+      approvals: { plugin: { enabled: true } },
+      channels: {
+        googlechat: {
+          serviceAccount: {
+            type: "service_account",
+            client_email: "bot@example.com",
+            private_key: "test-key",
+            token_uri: "https://oauth2.googleapis.com/token",
+          },
+          audienceType: "app-url",
+          audience: "https://chat-app.example.test/googlechat",
+          appPrincipal: "123456789012345678901",
+          dm: { allowFrom: ["users/123"] },
+        },
+      },
+    };
+    const request = {
+      id: "approval-1",
+      request: {
+        command: "echo hi",
+        turnSourceChannel: "googlechat",
+        turnSourceTo: "spaces/AAA",
+      },
+    } as never;
+
+    expect(
+      shouldHandleGoogleChatNativeApprovalRequest({
+        cfg,
+        request,
+      }),
+    ).toBe(false);
+  });
+
+  it("suppresses the local exec prompt when a Google Chat native route is active", () => {
+    expect(
+      shouldSuppressLocalGoogleChatExecApprovalPrompt({
+        cfg: {
+          approvals: { exec: { enabled: true } },
+          channels: { googlechat: GOOGLE_CHAT_APPROVAL_ACCOUNT },
+        },
+        payload: execApprovalPayload,
+        hint: activeExecApprovalHint,
+      }),
+    ).toBe(true);
+  });
+
+  it("keeps the local exec prompt when native Google Chat delivery cannot own it", () => {
+    expect(
+      shouldSuppressLocalGoogleChatExecApprovalPrompt({
+        cfg: {
+          approvals: { exec: { enabled: true } },
+          channels: { googlechat: GOOGLE_CHAT_APPROVAL_ACCOUNT },
+        },
+        payload: execApprovalPayload,
+        hint: {
+          kind: "approval-pending",
+          approvalKind: "exec",
+          nativeRouteActive: false,
+        },
+      }),
+    ).toBe(false);
+
+    expect(
+      shouldSuppressLocalGoogleChatExecApprovalPrompt({
+        cfg: {
+          approvals: { exec: { enabled: false } },
+          channels: { googlechat: GOOGLE_CHAT_APPROVAL_ACCOUNT },
+        },
+        payload: execApprovalPayload,
+        hint: activeExecApprovalHint,
+      }),
+    ).toBe(false);
+
+    expect(
+      shouldSuppressLocalGoogleChatExecApprovalPrompt({
+        cfg: {
+          approvals: { exec: { enabled: true } },
+          channels: {
+            googlechat: {
+              ...GOOGLE_CHAT_APPROVAL_ACCOUNT,
+              audience: undefined,
+            },
+          },
+        },
+        payload: execApprovalPayload,
+        hint: activeExecApprovalHint,
+      }),
+    ).toBe(false);
+
+    expect(
+      shouldSuppressLocalGoogleChatExecApprovalPrompt({
+        cfg: {
+          approvals: { exec: { enabled: true } },
+          channels: { googlechat: GOOGLE_CHAT_APPROVAL_ACCOUNT },
+        },
+        payload: {
+          channelData: {
+            execApproval: {
+              approvalId: "12345678-1234-1234-1234-123456789012",
+              approvalSlug: "12345678",
+              approvalKind: "plugin",
+            },
+          },
+        },
+        hint: {
+          kind: "approval-pending",
+          approvalKind: "plugin",
+          nativeRouteActive: true,
+        },
+      }),
+    ).toBe(false);
+  });
+});

package/src/approval-native.ts

@@ -0,0 +1,246 @@
+import {
+  createApproverRestrictedNativeApprovalCapability,
+  splitChannelApprovalCapability,
+} from "actagent/plugin-sdk/approval-delivery-runtime";
+import { createLazyChannelApprovalNativeRuntimeAdapter } from "actagent/plugin-sdk/approval-handler-adapter-runtime";
+import type { ChannelApprovalNativeRuntimeAdapter } from "actagent/plugin-sdk/approval-handler-runtime";
+import {
+  createChannelApproverDmTargetResolver,
+  createChannelNativeOriginTargetResolver,
+  createNativeApprovalChannelRouteGates,
+  shouldSuppressLocalNativeExecApprovalPrompt,
+} from "actagent/plugin-sdk/approval-native-runtime";
+import type {
+  ExecApprovalRequest,
+  PluginApprovalRequest,
+} from "actagent/plugin-sdk/approval-runtime";
+import type {
+  ChannelApprovalCapability,
+  ChannelOutboundPayloadHint,
+} from "actagent/plugin-sdk/channel-contract";
+import type { ACTAgentConfig } from "actagent/plugin-sdk/config-contracts";
+import type { ReplyPayload } from "actagent/plugin-sdk/reply-runtime";
+import {
+  normalizeLowercaseStringOrEmpty,
+  normalizeOptionalString,
+} from "actagent/plugin-sdk/string-coerce-runtime";
+import {
+  listGoogleChatAccountIds,
+  resolveDefaultGoogleChatAccountId,
+  resolveGoogleChatAccount,
+} from "./accounts.js";
+import {
+  getGoogleChatApprovalApprovers,
+  googleChatApprovalAuth,
+  normalizeGoogleChatApproverId,
+} from "./approval-auth.js";
+import { isGoogleChatSpaceTarget, normalizeGoogleChatTarget } from "./targets.js";
+
+type ApprovalRequest = ExecApprovalRequest | PluginApprovalRequest;
+type GoogleChatApprovalTarget = {
+  to: string;
+  accountId?: string | null;
+  threadId?: string | number | null;
+};
+type ChannelApprovalForwardTarget = Parameters<
+  NonNullable<
+    NonNullable<ChannelApprovalCapability["delivery"]>["shouldSuppressForwardingFallback"]
+  >
+>[0]["target"];
+
+const DEFAULT_APPROVAL_FORWARDING_MODE = "session";
+
+function isGoogleChatAccountConfigured(params: {
+  cfg: Parameters<typeof resolveGoogleChatAccount>[0]["cfg"];
+  accountId?: string | null;
+}): boolean {
+  const account = resolveGoogleChatAccount(params);
+  return account.enabled && account.credentialSource !== "none";
+}
+
+function hasGoogleChatWebhookApprovalAuthConfig(params: {
+  cfg: Parameters<typeof resolveGoogleChatAccount>[0]["cfg"];
+  accountId?: string | null;
+}): boolean {
+  const account = resolveGoogleChatAccount(params).config;
+  const audience = normalizeOptionalString(account.audience);
+  if (!audience) {
+    return false;
+  }
+  if (account.audienceType === "project-number") {
+    return true;
+  }
+  return account.audienceType === "app-url";
+}
+
+function isGoogleChatApprovalTransportEnabled(params: {
+  cfg: Parameters<typeof resolveGoogleChatAccount>[0]["cfg"];
+  accountId?: string | null;
+}): boolean {
+  return isGoogleChatAccountConfigured(params) && hasGoogleChatWebhookApprovalAuthConfig(params);
+}
+
+function normalizeGoogleChatForwardTarget(
+  target: Pick<ChannelApprovalForwardTarget, "channel" | "to" | "accountId" | "threadId">,
+): GoogleChatApprovalTarget | null {
+  if (normalizeLowercaseStringOrEmpty(target.channel) !== "googlechat") {
+    return null;
+  }
+  const to = normalizeGoogleChatTarget(target.to);
+  return to
+    ? {
+        to,
+        accountId: normalizeOptionalString(target.accountId),
+        threadId: target.threadId ?? null,
+      }
+    : null;
+}
+
+function resolveTurnSourceGoogleChatOriginTarget(
+  request: ApprovalRequest,
+): GoogleChatApprovalTarget | null {
+  const turnSourceChannel = normalizeLowercaseStringOrEmpty(request.request.turnSourceChannel);
+  if (turnSourceChannel !== "googlechat") {
+    return null;
+  }
+  const target = normalizeGoogleChatTarget(request.request.turnSourceTo ?? "");
+  if (!target || !isGoogleChatSpaceTarget(target)) {
+    return null;
+  }
+  return {
+    to: target,
+    accountId: normalizeOptionalString(request.request.turnSourceAccountId),
+    threadId: request.request.turnSourceThreadId ?? null,
+  };
+}
+
+const googleChatApprovalRouteGates = createNativeApprovalChannelRouteGates({
+  channel: "googlechat",
+  defaultForwardingMode: DEFAULT_APPROVAL_FORWARDING_MODE,
+  isTransportEnabled: isGoogleChatApprovalTransportEnabled,
+  listAccountIds: listGoogleChatAccountIds,
+  resolveDefaultAccountId: resolveDefaultGoogleChatAccountId,
+  normalizeForwardTarget: normalizeGoogleChatForwardTarget,
+  resolveTurnSourceTarget: resolveTurnSourceGoogleChatOriginTarget,
+});
+
+export function isGoogleChatNativeApprovalClientEnabled(params: {
+  cfg: Parameters<typeof resolveGoogleChatAccount>[0]["cfg"];
+  accountId?: string | null;
+}): boolean {
+  return (
+    googleChatApprovalRouteGates.canAnyApprovalPotentiallyRouteToChannel({
+      ...params,
+      nativeSessionOnly: true,
+    }) && getGoogleChatApprovalApprovers(params).length > 0
+  );
+}
+
+function resolveSessionGoogleChatOriginTarget(sessionTarget: {
+  to: string;
+  threadId?: string | number | null;
+}): GoogleChatApprovalTarget | null {
+  const target = normalizeGoogleChatTarget(sessionTarget.to);
+  return target && isGoogleChatSpaceTarget(target)
+    ? { to: target, threadId: sessionTarget.threadId ?? null }
+    : null;
+}
+
+export function shouldHandleGoogleChatNativeApprovalRequest(params: {
+  cfg: Parameters<typeof resolveGoogleChatAccount>[0]["cfg"];
+  accountId?: string | null;
+  request: ApprovalRequest;
+}): boolean {
+  return (
+    googleChatApprovalRouteGates.shouldHandleApprovalRequest(params) &&
+    getGoogleChatApprovalApprovers(params).length > 0 &&
+    Boolean(resolveTurnSourceGoogleChatOriginTarget(params.request))
+  );
+}
+
+export function shouldSuppressLocalGoogleChatExecApprovalPrompt(params: {
+  cfg: ACTAgentConfig;
+  accountId?: string | null;
+  payload: ReplyPayload;
+  hint?: ChannelOutboundPayloadHint;
+}): boolean {
+  return shouldSuppressLocalNativeExecApprovalPrompt({
+    ...params,
+    isNativeDeliveryEnabled: isGoogleChatNativeApprovalClientEnabled,
+  });
+}
+
+const resolveGoogleChatOriginTarget = createChannelNativeOriginTargetResolver({
+  channel: "googlechat",
+  shouldHandleRequest: shouldHandleGoogleChatNativeApprovalRequest,
+  resolveTurnSourceTarget: resolveTurnSourceGoogleChatOriginTarget,
+  resolveSessionTarget: resolveSessionGoogleChatOriginTarget,
+});
+
+const resolveGoogleChatApproverDmTargets = createChannelApproverDmTargetResolver({
+  shouldHandleRequest: shouldHandleGoogleChatNativeApprovalRequest,
+  resolveApprovers: getGoogleChatApprovalApprovers,
+  mapApprover: (approver, params) => {
+    const to = normalizeGoogleChatApproverId(approver);
+    return to
+      ? {
+          to,
+          accountId: normalizeOptionalString(params.accountId),
+        }
+      : null;
+  },
+});
+
+export const googleChatApprovalCapability: ChannelApprovalCapability =
+  createApproverRestrictedNativeApprovalCapability({
+    channel: "googlechat",
+    channelLabel: "Google Chat",
+    describeExecApprovalSetup: ({ accountId }) => {
+      const prefix =
+        accountId && accountId !== "default"
+          ? `channels.googlechat.accounts.${accountId}`
+          : "channels.googlechat";
+      return `Approve it from the Web UI or terminal UI for now. Google Chat supports native approvals for this account when the webhook and service account are configured. Configure \`${prefix}.dm.allowFrom\` or \`${prefix}.defaultTo\` with numeric \`users/{id}\` approvers.`;
+    },
+    listAccountIds: listGoogleChatAccountIds,
+    hasApprovers: ({ cfg, accountId }) =>
+      getGoogleChatApprovalApprovers({ cfg, accountId }).length > 0,
+    isExecAuthorizedSender: ({ cfg, accountId, senderId }) =>
+      googleChatApprovalAuth.authorizeActorAction?.({
+        cfg,
+        accountId,
+        senderId,
+        action: "approve",
+        approvalKind: "exec",
+      })?.authorized ?? false,
+    isPluginAuthorizedSender: ({ cfg, accountId, senderId }) =>
+      googleChatApprovalAuth.authorizeActorAction?.({
+        cfg,
+        accountId,
+        senderId,
+        action: "approve",
+        approvalKind: "plugin",
+      })?.authorized ?? false,
+    isNativeDeliveryEnabled: isGoogleChatNativeApprovalClientEnabled,
+    resolveNativeDeliveryMode: () => "channel",
+    requireMatchingTurnSourceChannel: true,
+    resolveSuppressionAccountId: ({ target, request }) =>
+      normalizeOptionalString(target.accountId) ??
+      normalizeOptionalString(request.request.turnSourceAccountId),
+    resolveOriginTarget: resolveGoogleChatOriginTarget,
+    resolveApproverDmTargets: resolveGoogleChatApproverDmTargets,
+    nativeRuntime: createLazyChannelApprovalNativeRuntimeAdapter({
+      eventKinds: ["exec", "plugin"],
+      isConfigured: ({ cfg, accountId }) =>
+        isGoogleChatNativeApprovalClientEnabled({ cfg, accountId }),
+      shouldHandle: ({ cfg, accountId, request }) =>
+        shouldHandleGoogleChatNativeApprovalRequest({ cfg, accountId, request }),
+      load: async () =>
+        (await import("./approval-handler.runtime.js"))
+          .googleChatApprovalNativeRuntime as unknown as ChannelApprovalNativeRuntimeAdapter,
+    }),
+  });
+
+export const googleChatNativeApprovalAdapter = splitChannelApprovalCapability(
+  googleChatApprovalCapability,
+);