@mercury-fw/channel-google-chat 0.1.0

package/README.md

@@ -0,0 +1,23 @@
+# @mercury-fw/channel-google-chat
+
+Puts a [Mercury](https://github.com/lucabro81/mercury-fw) agent on Google Chat as a registered Chat app: it receives messages through a Pub/Sub subscription and replies through the Chat API, with status cards while it works and a button for the actions that need confirmation.
+
+```bash
+bun add @mercury-fw/channel-google-chat
+```
+
+```ts
+import { googleChatChannel } from "@mercury-fw/channel-google-chat";
+
+channels: [googleChatChannel],
+```
+
+| Variable | |
+|---|---|
+| `GOOGLE_CHAT_PUBSUB_SUBSCRIPTION` | `projects/<project>/subscriptions/<subscription>` the Chat app's events arrive on. Empty leaves the channel inert. |
+| `GOOGLE_CHAT_APP_CLIENT_EMAIL` | The service account the app authenticates as. |
+| `GOOGLE_CHAT_APP_PRIVATE_KEY` | That service account's private key. |
+
+Each instance needs a Chat app of its own (its own Google Cloud project, topic, subscription and service account): two instances on one subscription either both answer or split a conversation between them. The [reference instance's README](https://github.com/lucabro81/mercury-fw/tree/main/apps/mercury#setting-up-the-chat-apps-google-cloud-project) has the `gcloud` commands, and the one step Cloud Console only does by hand.
+
+MIT

package/dist/google-chat-app-client.d.ts

@@ -0,0 +1,71 @@
+export type ServiceAccountCredentials = {
+    clientEmail: string;
+    privateKey: string;
+};
+/** Builds and signs the JWT assertion for the OAuth2 JWT-bearer grant. Pure function, no I/O — testable without a real key. */
+export declare function buildSignedAssertion(creds: ServiceAccountCredentials, scope: string, nowSeconds: number): string;
+export type FetchFn = typeof fetch;
+export type TokenSource = {
+    getToken(): Promise<string>;
+};
+/** A lazily-refreshing token source: mints once, reuses until close to expiry, re-mints after. */
+export declare function createTokenSource(creds: ServiceAccountCredentials, deps?: {
+    fetchFn?: FetchFn;
+    nowSeconds?: () => number;
+}): TokenSource;
+/**
+ * Finds or creates a DIRECT_MESSAGE space with `userId` (`users/<id>`).
+ * Checks `spaces.findDirectMessage` first and reuses an existing DM if one
+ * exists; falls back to `spaces.setup` (creates a space **and** adds the
+ * given member in one call — the closest single-call equivalent of the
+ * retired `gchat-cli`'s `spaces create --user`, which the CLI's own docs
+ * described as wrapping `spaces.setup`) when none is found.
+ */
+export declare function getOrCreateDmSpace(userId: string, deps: {
+    tokenSource: TokenSource;
+    fetchFn?: FetchFn;
+}): Promise<{
+    name: string;
+}>;
+/** Sends a plain-text message to `space`. Returns the created message's `name` (used for loop-prevention, same as the retired impersonation-era transport). */
+export declare function sendMessage(space: string, text: string, deps: {
+    tokenSource: TokenSource;
+    fetchFn?: FetchFn;
+}): Promise<{
+    name: string;
+}>;
+/**
+ * A single Cards v2 message — one call, `cardsV2` is an array because the
+ * API supports multiple cards per message, but every caller here sends
+ * exactly one. A section's `header` (distinct from the card-level
+ * `header.title`) plus `collapsible`/`uncollapsibleWidgetsCount` is Google
+ * Chat's own native accordion primitive: `header` stays visible regardless
+ * of collapse state, and widgets beyond `uncollapsibleWidgetsCount` fold
+ * behind a "Show more" toggle.
+ */
+export type ChatCardSection = {
+    widgets: unknown[];
+    header?: string;
+    collapsible?: boolean;
+    uncollapsibleWidgetsCount?: number;
+};
+export type ChatCard = {
+    header?: {
+        title: string;
+    };
+    sections: ChatCardSection[];
+};
+/** Posts `card` as a Cards v2 message to `space`. Returns the created message's `name`, same shape as `sendMessage`. */
+export declare function sendCard(space: string, card: ChatCard, deps: {
+    tokenSource: TokenSource;
+    fetchFn?: FetchFn;
+}): Promise<{
+    name: string;
+}>;
+/** Edits an already-sent card message's `cardsV2` in place (PATCH, `updateMask=cardsV2`) — used to patch a tool-call status card from loading to its final outcome without sending a new message. */
+export declare function updateCard(name: string, card: ChatCard, deps: {
+    tokenSource: TokenSource;
+    fetchFn?: FetchFn;
+}): Promise<{
+    name: string;
+}>;

package/dist/google-chat-message-buffer.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Splits a complete final answer into more than one Google Chat message
+ * only when it would exceed the API's own message-size limit — a purely
+ * technical safety net, not a readability choice (see
+ * `google-chat-streamer.ts`, the only caller). Google Chat rejects a
+ * message over 32,000 bytes ("the maximum message size... is 32,000
+ * bytes... your Chat app must send multiple messages instead" —
+ * https://developers.google.com/workspace/chat/create-messages). A local
+ * model's answer coming anywhere close to that is effectively never
+ * observed in practice, but the cut stays in place as a correctness net
+ * regardless. Caller: `google-chat-provider.ts`.
+ */
+export declare const MAX_CHAT_MESSAGE_CHARS = 30000;
+/**
+ * Splits `text` at the last whitespace at-or-before `MAX_CHAT_MESSAGE_CHARS`,
+ * repeated as needed — never splits a single word, even if that means one
+ * piece exceeds the cap (a single unbroken token longer than the cap is
+ * left intact, the one documented case where the cap can be exceeded).
+ * Returns `[]` for empty/whitespace-only input.
+ */
+export declare function splitForSendLimit(text: string): string[];

package/dist/google-chat-provider.d.ts

@@ -0,0 +1,95 @@
+/**
+ * The registered Chat app's `Provider` — replaces the retired
+ * impersonation-based channel (`google-chat-client.ts`/`google-chat-events.ts`/
+ * `google-chat-streamer.ts`/`google-chat-message-buffer.ts`, all deleted)
+ * wholesale, not as an adapter over it. Built directly against the
+ * chat-app model: `chat.bot`-scoped service-account auth
+ * (`google-chat-app-client.ts`), a single Pub/Sub subscription for the
+ * whole app (no more per-space Workspace Events subscriptions — a real
+ * simplification the old impersonation path needed and this one doesn't),
+ * and a real per-app bot identity.
+ *
+ * Session key is `space:sender` — same as the retired channel's own key
+ * (see `deriveSessionKey` for why a thread-keyed variant, tried initially,
+ * broke conversation continuity in DMs).
+ *
+ * The `[Da: X]` sender marker no longer needs a People-API round trip: a
+ * registered app's `MESSAGE` event already carries `sender.displayName`
+ * directly (confirmed live against a real captured event earlier this
+ * session) — `resolveSenderName`/`getUser`/the `resolved-name.md` wiki
+ * cache are not used by this provider at all.
+ */
+import { sendMessage, sendCard, updateCard, getOrCreateDmSpace, type ServiceAccountCredentials, type TokenSource } from "./google-chat-app-client.ts";
+import { type PubSubSubscription } from "./google-chat-pubsub-stream.ts";
+import { type Provider } from "@mercury-fw/channel-types";
+/**
+ * Composite session key: space + sender. Deliberately does NOT include
+ * `thread` — confirmed live (two consecutive messages in the same DM
+ * conversation produced two different `thread.name` values) that Google
+ * Chat assigns a fresh thread to every top-level message in a DM (the DM
+ * UI has no way to reply in-thread at all), so a thread-keyed session was
+ * a brand new, empty history on every single message. Matches the retired
+ * impersonation-based channel's own key exactly. Revisit only once Mercury
+ * actually participates in threaded group spaces with a demonstrated need
+ * for parallel per-thread conversations — not speculatively.
+ */
+export declare function deriveSessionKey(space: string, sender: string): string;
+export type ParsedMessageEvent = {
+    kind: "message";
+    text: string;
+    messageName: string;
+    space: string;
+    sender: string;
+    senderDisplayName: string | undefined;
+    /**
+     * True only when `space.type` is exactly `"DM"` (the Chat API's shape
+     * for a private 1:1 space) — anything else, including a missing field,
+     * stays `false` on purpose: a DM is unambiguously addressed to Mercury,
+     * everything else keeps the cautious multi-user default. Confirmed
+     * live against a real DM event this session.
+     */
+    isDirectMessage: boolean;
+};
+export type ParsedCardClickEvent = {
+    kind: "card-click";
+    space: string;
+    sender: string;
+    parameters: Record<string, string>;
+};
+/** Parses one decoded Pub/Sub event, or `null` if it isn't a kind this provider acts on. */
+export declare function parseChatEvent(raw: unknown): ParsedMessageEvent | ParsedCardClickEvent | null;
+export type CardClickHandler = (params: Record<string, string>, space: string, sender: string) => Promise<void>;
+export type GoogleChatProviderDeps = {
+    credentials: ServiceAccountCredentials;
+    subscription: string;
+    /**
+     * Resolves a confirmation token against the core's shared store, injected by
+     * the channel loader (`ChannelRuntimeContext.confirm`). Returns the reply to
+     * send, or `null` when the input wasn't token-shaped. This is the whole of
+     * the channel's contact with confirmation — the store, vault and note-writer
+     * stay in the core.
+     */
+    confirm: (token: string, sessionKey: string, userId: string) => Promise<string | null>;
+    /**
+     * Handles a `CARD_CLICKED` event's action parameters. Defaults to resolving
+     * the confirm button's token through `deps.confirm` (the same path a bare
+     * token typed on the terminal uses) — override only to handle a different
+     * card's click shape (e.g. a future `notify-user` disambiguation token), not
+     * to change how confirmation itself resolves.
+     */
+    onCardClick?: CardClickHandler;
+    /** Test seams — default to the real client functions bound with a token source built from `credentials`. */
+    tokenSourceFn?: (creds: ServiceAccountCredentials) => TokenSource;
+    sendMessageFn?: typeof sendMessage;
+    sendCardFn?: typeof sendCard;
+    updateCardFn?: typeof updateCard;
+    getOrCreateDmSpaceFn?: typeof getOrCreateDmSpace;
+    /** Test seam — defaults to `openSubscription` (real StreamingPull); tests inject a fake `PubSubSubscription`. */
+    subscriptionFn?: (creds: ServiceAccountCredentials, subscription: string) => PubSubSubscription;
+    log?: (msg: string) => void;
+};
+export type GoogleChatProvider = Provider & {
+    stop(): Promise<void>;
+};
+/** Builds the registered Google Chat app's `Provider`. */
+export declare function createGoogleChatProvider(deps: GoogleChatProviderDeps): GoogleChatProvider;

package/dist/google-chat-pubsub-stream.d.ts

@@ -0,0 +1,27 @@
+import type { ServiceAccountCredentials } from "./google-chat-app-client.ts";
+/** One incoming Pub/Sub message. `data` is already the raw message body — the SDK handles the wire-level base64 transport itself. */
+export type StreamMessage = {
+    data: Buffer;
+    ack: () => void;
+    nack: () => void;
+};
+/** The subset of `@google-cloud/pubsub`'s `Subscription` this app actually uses — narrowed so a fake can satisfy it in tests without depending on the real SDK's types. */
+export type PubSubSubscription = {
+    on(event: "message", listener: (message: StreamMessage) => void): void;
+    on(event: "error", listener: (err: Error) => void): void;
+    close(): Promise<void>;
+};
+/** Splits `"projects/<id>/subscriptions/<name>"` into its two parts — thrown separately so a malformed env var fails fast and clearly, not deep inside the SDK's own error handling. */
+export declare function parseSubscriptionName(resourceName: string): {
+    projectId: string;
+    subscriptionId: string;
+};
+/**
+ * Opens a StreamingPull subscription. Real gRPC — exercised by the Phase 0
+ * spike and live verification, not by unit tests (`google-chat-provider.ts`
+ * injects a fake `PubSubSubscription` via its own `subscriptionFn` seam for
+ * those). Credentials are passed directly (`client_email`/`private_key`),
+ * same service-account values already used for the Chat API's own
+ * JWT-bearer flow — no key file on disk, no second credential to manage.
+ */
+export declare function openSubscription(credentials: ServiceAccountCredentials, resourceName: string): PubSubSubscription;

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The Google Chat channel plugin: the `ChannelPlugin` the core's channel loader
+ * consumes. `build()` reads this channel's own config from `ctx.env` and
+ * constructs the provider; it returns `undefined` when no
+ * `GOOGLE_CHAT_PUBSUB_SUBSCRIPTION` is set (the instance isn't running Google
+ * Chat — present but inert). A subscription set with the app credentials
+ * missing is a misconfiguration: `build()` throws and the loader skips this
+ * channel fail-soft, leaving the rest of Mercury up.
+ */
+import { type ChannelPlugin } from "@mercury-fw/channel-types";
+export declare const googleChatChannel: ChannelPlugin;

package/google-chat-app-client.ts

@@ -0,0 +1,200 @@
+/**
+ * The registered Chat app's own transport — Chat REST API + Pub/Sub pull,
+ * called directly over HTTPS from this process. Channel transport
+ * (reading/sending the messages that carry a conversation) is never something
+ * the model drives, unlike a tool such as `notify-user.ts`, which it does invoke.
+ *
+ * Auth: a service-account JWT-bearer flow (RFC 7523), signed with Node's
+ * built-in `crypto` — no new OAuth/Google API client dependency needed for
+ * this. Scoped to `chat.bot` only — event delivery now goes through
+ * `google-chat-pubsub-stream.ts` (`@google-cloud/pubsub`'s StreamingPull),
+ * which mints its own token internally from the same credentials, not
+ * through this token source. Re-minted lazily once it's within a minute of
+ * expiring. Verified live against the real APIs earlier in this project's
+ * history (a throwaway service account, JWT-bearer flow, `chat.bot` scope,
+ * `spaces.messages.create` → HTTP 200, delivered as the app's own `BOT`
+ * identity) before this file was written — this is that same pattern,
+ * generalized and made persistent instead of a one-off script.
+ */
+import { createSign } from "node:crypto";
+
+export type ServiceAccountCredentials = { clientEmail: string; privateKey: string };
+
+const TOKEN_URL = "https://oauth2.googleapis.com/token";
+const CHAT_API_BASE = "https://chat.googleapis.com/v1";
+const SCOPES = "https://www.googleapis.com/auth/chat.bot";
+/** Re-mint this long before real expiry — a token that expires mid-request is worse than one wasted early. */
+const REFRESH_MARGIN_SECONDS = 60;
+
+function base64url(input: Buffer | string): string {
+  return Buffer.from(input).toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+/** Builds and signs the JWT assertion for the OAuth2 JWT-bearer grant. Pure function, no I/O — testable without a real key. */
+export function buildSignedAssertion(creds: ServiceAccountCredentials, scope: string, nowSeconds: number): string {
+  const header = base64url(JSON.stringify({ alg: "RS256", typ: "JWT" }));
+  const claims = base64url(
+    JSON.stringify({
+      iss: creds.clientEmail,
+      scope,
+      aud: TOKEN_URL,
+      exp: nowSeconds + 3600,
+      iat: nowSeconds,
+    }),
+  );
+  const unsigned = `${header}.${claims}`;
+  const signer = createSign("RSA-SHA256");
+  signer.update(unsigned);
+  signer.end();
+  const signature = base64url(signer.sign(creds.privateKey));
+  return `${unsigned}.${signature}`;
+}
+
+export type FetchFn = typeof fetch;
+
+/** Exchanges a signed JWT assertion for an access token. Throws with the response body on failure — no fallback identity to authenticate as instead. */
+async function exchangeAssertionForToken(
+  assertion: string,
+  fetchFn: FetchFn,
+): Promise<{ accessToken: string; expiresInSeconds: number }> {
+  const response = await fetchFn(TOKEN_URL, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer",
+      assertion,
+    }).toString(),
+  });
+  if (!response.ok) {
+    throw new Error(`token exchange failed: HTTP ${response.status} ${await response.text()}`);
+  }
+  const data = (await response.json()) as { access_token: string; expires_in: number };
+  return { accessToken: data.access_token, expiresInSeconds: data.expires_in };
+}
+
+export type TokenSource = { getToken(): Promise<string> };
+
+/** A lazily-refreshing token source: mints once, reuses until close to expiry, re-mints after. */
+export function createTokenSource(
+  creds: ServiceAccountCredentials,
+  deps: { fetchFn?: FetchFn; nowSeconds?: () => number } = {},
+): TokenSource {
+  const fetchFn = deps.fetchFn ?? fetch;
+  const nowSeconds = deps.nowSeconds ?? (() => Math.floor(Date.now() / 1000));
+  let cached: { accessToken: string; expiresAt: number } | null = null;
+
+  return {
+    async getToken(): Promise<string> {
+      const now = nowSeconds();
+      if (cached && cached.expiresAt - REFRESH_MARGIN_SECONDS > now) {
+        return cached.accessToken;
+      }
+      const assertion = buildSignedAssertion(creds, SCOPES, now);
+      const { accessToken, expiresInSeconds } = await exchangeAssertionForToken(assertion, fetchFn);
+      cached = { accessToken, expiresAt: now + expiresInSeconds };
+      return accessToken;
+    },
+  };
+}
+
+/** Throws with the response body on a non-2xx result — there's no fallback the caller can take instead of knowing the real call failed. */
+async function callChatApi(
+  path: string,
+  init: { method: string; body?: unknown },
+  deps: { tokenSource: TokenSource; fetchFn?: FetchFn },
+): Promise<unknown> {
+  const fetchFn = deps.fetchFn ?? fetch;
+  const token = await deps.tokenSource.getToken();
+  const response = await fetchFn(`${CHAT_API_BASE}/${path}`, {
+    method: init.method,
+    headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+    body: init.body !== undefined ? JSON.stringify(init.body) : undefined,
+  });
+  if (!response.ok) {
+    throw new Error(`Chat API ${init.method} ${path} failed: HTTP ${response.status} ${await response.text()}`);
+  }
+  return response.json();
+}
+
+/**
+ * Finds or creates a DIRECT_MESSAGE space with `userId` (`users/<id>`).
+ * Checks `spaces.findDirectMessage` first and reuses an existing DM if one
+ * exists; falls back to `spaces.setup` (creates a space **and** adds the
+ * given member in one call — the closest single-call equivalent of the
+ * retired `gchat-cli`'s `spaces create --user`, which the CLI's own docs
+ * described as wrapping `spaces.setup`) when none is found.
+ */
+export async function getOrCreateDmSpace(
+  userId: string,
+  deps: { tokenSource: TokenSource; fetchFn?: FetchFn },
+): Promise<{ name: string }> {
+  const found = (await callChatApi(
+    `spaces:findDirectMessage?name=${encodeURIComponent(userId)}`,
+    { method: "GET" },
+    deps,
+  ).catch(() => null)) as { name?: string } | null;
+  if (found?.name) {
+    return { name: found.name };
+  }
+  const created = (await callChatApi(
+    "spaces:setup",
+    { method: "POST", body: { space: { spaceType: "DIRECT_MESSAGE" }, memberships: [{ member: { name: userId, type: "HUMAN" } }] } },
+    deps,
+  )) as { name: string };
+  return { name: created.name };
+}
+
+/** Sends a plain-text message to `space`. Returns the created message's `name` (used for loop-prevention, same as the retired impersonation-era transport). */
+export async function sendMessage(
+  space: string,
+  text: string,
+  deps: { tokenSource: TokenSource; fetchFn?: FetchFn },
+): Promise<{ name: string }> {
+  const data = (await callChatApi(`${space}/messages`, { method: "POST", body: { text } }, deps)) as { name: string };
+  return { name: data.name };
+}
+
+/**
+ * A single Cards v2 message — one call, `cardsV2` is an array because the
+ * API supports multiple cards per message, but every caller here sends
+ * exactly one. A section's `header` (distinct from the card-level
+ * `header.title`) plus `collapsible`/`uncollapsibleWidgetsCount` is Google
+ * Chat's own native accordion primitive: `header` stays visible regardless
+ * of collapse state, and widgets beyond `uncollapsibleWidgetsCount` fold
+ * behind a "Show more" toggle.
+ */
+export type ChatCardSection = {
+  widgets: unknown[];
+  header?: string;
+  collapsible?: boolean;
+  uncollapsibleWidgetsCount?: number;
+};
+export type ChatCard = { header?: { title: string }; sections: ChatCardSection[] };
+
+/** Posts `card` as a Cards v2 message to `space`. Returns the created message's `name`, same shape as `sendMessage`. */
+export async function sendCard(
+  space: string,
+  card: ChatCard,
+  deps: { tokenSource: TokenSource; fetchFn?: FetchFn },
+): Promise<{ name: string }> {
+  const data = (await callChatApi(
+    `${space}/messages`,
+    { method: "POST", body: { cardsV2: [{ cardId: "card", card }] } },
+    deps,
+  )) as { name: string };
+  return { name: data.name };
+}
+
+/** Edits an already-sent card message's `cardsV2` in place (PATCH, `updateMask=cardsV2`) — used to patch a tool-call status card from loading to its final outcome without sending a new message. */
+export async function updateCard(
+  name: string,
+  card: ChatCard,
+  deps: { tokenSource: TokenSource; fetchFn?: FetchFn },
+): Promise<{ name: string }> {
+  const data = (await callChatApi(
+    `${name}?updateMask=cardsV2`,
+    { method: "PATCH", body: { cardsV2: [{ cardId: "card", card }] } },
+    deps,
+  )) as { name: string };
+  return { name: data.name };
+}

package/google-chat-message-buffer.ts

@@ -0,0 +1,50 @@
+/**
+ * Splits a complete final answer into more than one Google Chat message
+ * only when it would exceed the API's own message-size limit — a purely
+ * technical safety net, not a readability choice (see
+ * `google-chat-streamer.ts`, the only caller). Google Chat rejects a
+ * message over 32,000 bytes ("the maximum message size... is 32,000
+ * bytes... your Chat app must send multiple messages instead" —
+ * https://developers.google.com/workspace/chat/create-messages). A local
+ * model's answer coming anywhere close to that is effectively never
+ * observed in practice, but the cut stays in place as a correctness net
+ * regardless. Caller: `google-chat-provider.ts`.
+ */
+
+// Characters, not bytes — a wide margin under the real 32,000-byte limit.
+// Multi-byte UTF-8 characters (accents, emoji) mean chars != bytes, but the
+// margin is generous enough that only text many times longer than any real
+// answer would ever need the exact byte count instead of this estimate.
+export const MAX_CHAT_MESSAGE_CHARS = 30_000;
+
+function lastWhitespaceIndex(s: string): number {
+  for (let i = s.length - 1; i >= 0; i--) {
+    if (/\s/.test(s[i] as string)) return i;
+  }
+  return -1;
+}
+
+/**
+ * Splits `text` at the last whitespace at-or-before `MAX_CHAT_MESSAGE_CHARS`,
+ * repeated as needed — never splits a single word, even if that means one
+ * piece exceeds the cap (a single unbroken token longer than the cap is
+ * left intact, the one documented case where the cap can be exceeded).
+ * Returns `[]` for empty/whitespace-only input.
+ */
+export function splitForSendLimit(text: string): string[] {
+  const messages: string[] = [];
+  let remaining = text.trim();
+
+  while (remaining.length > MAX_CHAT_MESSAGE_CHARS) {
+    const window = remaining.slice(0, MAX_CHAT_MESSAGE_CHARS);
+    const cutAt = lastWhitespaceIndex(window);
+    if (cutAt <= 0) break; // no safe cut point without splitting a word
+    const piece = remaining.slice(0, cutAt).trim();
+    if (piece.length === 0) break;
+    messages.push(piece);
+    remaining = remaining.slice(cutAt).trim();
+  }
+
+  if (remaining.length > 0) messages.push(remaining);
+  return messages;
+}

package/google-chat-provider.ts

@@ -0,0 +1,591 @@
+/**
+ * The registered Chat app's `Provider` — replaces the retired
+ * impersonation-based channel (`google-chat-client.ts`/`google-chat-events.ts`/
+ * `google-chat-streamer.ts`/`google-chat-message-buffer.ts`, all deleted)
+ * wholesale, not as an adapter over it. Built directly against the
+ * chat-app model: `chat.bot`-scoped service-account auth
+ * (`google-chat-app-client.ts`), a single Pub/Sub subscription for the
+ * whole app (no more per-space Workspace Events subscriptions — a real
+ * simplification the old impersonation path needed and this one doesn't),
+ * and a real per-app bot identity.
+ *
+ * Session key is `space:sender` — same as the retired channel's own key
+ * (see `deriveSessionKey` for why a thread-keyed variant, tried initially,
+ * broke conversation continuity in DMs).
+ *
+ * The `[Da: X]` sender marker no longer needs a People-API round trip: a
+ * registered app's `MESSAGE` event already carries `sender.displayName`
+ * directly (confirmed live against a real captured event earlier this
+ * session) — `resolveSenderName`/`getUser`/the `resolved-name.md` wiki
+ * cache are not used by this provider at all.
+ */
+import {
+  createTokenSource,
+  sendMessage,
+  sendCard,
+  updateCard,
+  getOrCreateDmSpace,
+  type ServiceAccountCredentials,
+  type TokenSource,
+  type ChatCard,
+} from "./google-chat-app-client.ts";
+import { openSubscription, type PubSubSubscription, type StreamMessage } from "./google-chat-pubsub-stream.ts";
+import { splitForSendLimit } from "./google-chat-message-buffer.ts";
+import {
+  detectPendingConfirmation,
+  PENDING_CONFIRMATION_NOTE,
+  NO_REPLY,
+  type PendingConfirmation,
+  type ToolOutcome,
+  type Provider,
+  type HandleTurn,
+  type TurnSink,
+} from "@mercury-fw/channel-types";
+
+/**
+ * Builds the confirmation card sent when a step stages an irreversible
+ * command (see `pending-confirmation.ts`). The button's parameters carry
+ * the token, so a click routes straight into the same `tryConfirm` path
+ * a bare token typed on the terminal uses (see `onCardClick`'s `confirm`
+ * case, below) — the user never has to see or type the token themselves.
+ */
+function buildConfirmCard(pending: PendingConfirmation): ChatCard {
+  return {
+    header: { title: "Conferma richiesta" },
+    sections: [
+      {
+        widgets: [
+          { textParagraph: { text: `\`${pending.summary}\`` } },
+          {
+            buttonList: {
+              buttons: [
+                {
+                  text: "Conferma",
+                  onClick: { action: { function: "confirm", parameters: [{ key: "token", value: pending.token }] } },
+                },
+              ],
+            },
+          },
+        ],
+      },
+    ],
+  };
+}
+
+const TOOL_STATUS_LINES: Record<"loading" | ToolOutcome, string> = {
+  loading: "In corso…",
+  success: "Fatto.",
+  failed: "Non riuscito.",
+  pending: "In attesa di conferma.",
+};
+
+/**
+ * A tool-call/reasoning status card: `label` is a section `header`
+ * (Google Chat's native accordion title, always visible regardless of
+ * collapse state), `detail`/status are the two widgets folded behind it —
+ * `uncollapsibleWidgetsCount: 0` means both start collapsed. Sent once as
+ * "loading" (`createSink`'s `onToolStart`/first `onReasoningChunk`), then
+ * the very same message is patched in place to its final status
+ * (`onToolFinish`/`onReasoningEnd`) via `updateCardFn` — never a second
+ * message.
+ *
+ * The status is appended to the title too, not just left inside the
+ * collapsed body: a title stuck reading "Sto leggendo dati con jira…"
+ * (present progressive) forever, even once the card's own body says
+ * "Fatto.", looked like the card never updated at all — confirmed live
+ * (the body did patch, only the title didn't change).
+ *
+ * Native `collapsible` state is client-side only and resets to collapsed
+ * on every PATCH — confirmed live. Harmless for a card patched exactly
+ * twice (send, then one final patch): reasoning cards used to be patched
+ * every ~1s while streaming and forcibly kept open (`alwaysExpanded`) to
+ * work around it, which made the reset bug moot but leaked the
+ * in-progress reasoning text into a card the user might reopen mid-stream.
+ * Simpler fix, not just a workaround: `createSink`'s reasoning handling no
+ * longer patches this card at all while loading (see `onReasoningChunk`) —
+ * detail is only ever revealed in the single final patch, at which point
+ * nothing patches the message again, so the native toggle can never be
+ * reset out from under the user again either.
+ */
+function buildToolCallCard(label: string, detail: string, status: "loading" | ToolOutcome): ChatCard {
+  return {
+    sections: [
+      {
+        header: status === "loading" ? label : `${label} ${TOOL_STATUS_LINES[status]}`,
+        collapsible: true,
+        uncollapsibleWidgetsCount: 0,
+        widgets: [{ textParagraph: { text: detail } }, { textParagraph: { text: TOOL_STATUS_LINES[status] } }],
+      },
+    ],
+  };
+}
+
+const REASONING_TAIL_CHARS = 4000;
+
+/**
+ * Sent immediately when a turn starts, before the model has produced
+ * anything at all — covers the real gap (confirmed live, ~10s) between a
+ * message arriving and the first visible activity: Ollama's own
+ * prompt-prefill/model-load time, which happens before even the first
+ * reasoning token, so nothing else would appear on screen until then.
+ * Ollama's `/api/generate`/`/api/chat` streaming endpoints don't expose
+ * any intermediate loading/prefill event to distinguish finer-grained
+ * states here (checked against the API docs) — `load_duration`/
+ * `prompt_eval_duration` only appear in the final, non-streamed response.
+ * Header is the generic "Stato" (not a restatement of the body) so this
+ * has somewhere to grow if a genuinely different state ever becomes
+ * observable, rather than needing a redesign.
+ *
+ * Not expandable (no `collapsible`) — there's nothing to fold away. A
+ * section with zero widgets renders as a near-empty sliver in Google Chat
+ * (confirmed live — a thin grey line, no visible text at all), so this
+ * always carries at least one `textParagraph`, same as every other card
+ * in this file. If the turn's first reasoning burst arrives,
+ * `onReasoningChunk` patches this exact card into the "Sto pensando…"
+ * card in place, rather than sending a second message; otherwise it's
+ * simply left as the last status before the turn's real answer.
+ */
+function buildReceivingCard(): ChatCard {
+  return { sections: [{ header: "Stato", widgets: [{ textParagraph: { text: "Messaggio in ricezione…" } }] }] };
+}
+
+/**
+ * Bounds a live-growing reasoning buffer to its most recent
+ * `max` characters, prefixed with "…" when truncated — deliberately the
+ * opposite direction of `tool-start-hook.ts`'s `truncate()` (which keeps
+ * the head, right for a short command): a live stream should show its
+ * most recent content as it grows, not freeze on its first N characters.
+ */
+function tailTruncate(text: string, max: number): string {
+  return text.length <= max ? text : `…${text.slice(text.length - max)}`;
+}
+
+/**
+ * Composite session key: space + sender. Deliberately does NOT include
+ * `thread` — confirmed live (two consecutive messages in the same DM
+ * conversation produced two different `thread.name` values) that Google
+ * Chat assigns a fresh thread to every top-level message in a DM (the DM
+ * UI has no way to reply in-thread at all), so a thread-keyed session was
+ * a brand new, empty history on every single message. Matches the retired
+ * impersonation-based channel's own key exactly. Revisit only once Mercury
+ * actually participates in threaded group spaces with a demonstrated need
+ * for parallel per-thread conversations — not speculatively.
+ */
+export function deriveSessionKey(space: string, sender: string): string {
+  return `${space}:${sender}`;
+}
+
+type RawChatSender = { name?: string; displayName?: string; email?: string; type?: string };
+type RawChatEvent = {
+  type?: string;
+  message?: {
+    name?: string;
+    text?: string;
+    space?: { name?: string; type?: string };
+    sender?: RawChatSender;
+  };
+  action?: { actionMethodName?: string; parameters?: Array<{ key?: string; value?: string }> };
+  space?: { name?: string };
+  user?: RawChatSender;
+};
+
+export type ParsedMessageEvent = {
+  kind: "message";
+  text: string;
+  messageName: string;
+  space: string;
+  sender: string;
+  senderDisplayName: string | undefined;
+  /**
+   * True only when `space.type` is exactly `"DM"` (the Chat API's shape
+   * for a private 1:1 space) — anything else, including a missing field,
+   * stays `false` on purpose: a DM is unambiguously addressed to Mercury,
+   * everything else keeps the cautious multi-user default. Confirmed
+   * live against a real DM event this session.
+   */
+  isDirectMessage: boolean;
+};
+
+export type ParsedCardClickEvent = {
+  kind: "card-click";
+  space: string;
+  sender: string;
+  parameters: Record<string, string>;
+};
+
+/** Parses one decoded Pub/Sub event, or `null` if it isn't a kind this provider acts on. */
+export function parseChatEvent(raw: unknown): ParsedMessageEvent | ParsedCardClickEvent | null {
+  const event = raw as RawChatEvent;
+  if (event?.type === "MESSAGE") {
+    const m = event.message;
+    if (!m || typeof m.name !== "string" || typeof m.text !== "string") return null;
+    if (typeof m.space?.name !== "string") return null;
+    if (typeof m.sender?.name !== "string") return null;
+    return {
+      kind: "message",
+      text: m.text,
+      messageName: m.name,
+      space: m.space.name,
+      sender: m.sender.name,
+      senderDisplayName: m.sender.displayName,
+      isDirectMessage: m.space.type === "DM",
+    };
+  }
+  if (event?.type === "CARD_CLICKED") {
+    if (typeof event.space?.name !== "string") return null;
+    if (typeof event.user?.name !== "string") return null;
+    const parameters: Record<string, string> = {};
+    for (const p of event.action?.parameters ?? []) {
+      if (typeof p.key === "string" && typeof p.value === "string") {
+        parameters[p.key] = p.value;
+      }
+    }
+    return { kind: "card-click", space: event.space.name, sender: event.user.name, parameters };
+  }
+  return null;
+}
+
+export type CardClickHandler = (params: Record<string, string>, space: string, sender: string) => Promise<void>;
+
+export type GoogleChatProviderDeps = {
+  credentials: ServiceAccountCredentials;
+  subscription: string;
+  /**
+   * Resolves a confirmation token against the core's shared store, injected by
+   * the channel loader (`ChannelRuntimeContext.confirm`). Returns the reply to
+   * send, or `null` when the input wasn't token-shaped. This is the whole of
+   * the channel's contact with confirmation — the store, vault and note-writer
+   * stay in the core.
+   */
+  confirm: (token: string, sessionKey: string, userId: string) => Promise<string | null>;
+  /**
+   * Handles a `CARD_CLICKED` event's action parameters. Defaults to resolving
+   * the confirm button's token through `deps.confirm` (the same path a bare
+   * token typed on the terminal uses) — override only to handle a different
+   * card's click shape (e.g. a future `notify-user` disambiguation token), not
+   * to change how confirmation itself resolves.
+   */
+  onCardClick?: CardClickHandler;
+  /** Test seams — default to the real client functions bound with a token source built from `credentials`. */
+  tokenSourceFn?: (creds: ServiceAccountCredentials) => TokenSource;
+  sendMessageFn?: typeof sendMessage;
+  sendCardFn?: typeof sendCard;
+  updateCardFn?: typeof updateCard;
+  getOrCreateDmSpaceFn?: typeof getOrCreateDmSpace;
+  /** Test seam — defaults to `openSubscription` (real StreamingPull); tests inject a fake `PubSubSubscription`. */
+  subscriptionFn?: (creds: ServiceAccountCredentials, subscription: string) => PubSubSubscription;
+  log?: (msg: string) => void;
+};
+
+export type GoogleChatProvider = Provider & {
+  stop(): Promise<void>;
+};
+
+/** Builds the registered Google Chat app's `Provider`. */
+export function createGoogleChatProvider(deps: GoogleChatProviderDeps): GoogleChatProvider {
+  const log = deps.log ?? ((msg: string) => console.error(msg));
+  const tokenSource = (deps.tokenSourceFn ?? createTokenSource)(deps.credentials);
+  const sendMessageFn = deps.sendMessageFn ?? sendMessage;
+  const sendCardFn = deps.sendCardFn ?? sendCard;
+  const updateCardFn = deps.updateCardFn ?? updateCard;
+  const getOrCreateDmSpaceFn = deps.getOrCreateDmSpaceFn ?? getOrCreateDmSpace;
+  const subscriptionFn = deps.subscriptionFn ?? openSubscription;
+  const clientDeps = { tokenSource };
+  const sentMessageNames = new Set<string>();
+  // Per-session serialization: pollOnce's setInterval fires on a fixed
+  // clock regardless of whether the previous tick's turn finished, so two
+  // overlapping ticks could otherwise both call handleTurn for the SAME
+  // session at once — both reading/writing the same SessionHistory
+  // concurrently. Scoped by sessionKey only (not global), so a slow turn
+  // for one user/space never blocks a different one's.
+  const busySessions = new Set<string>();
+  const queuedEvents = new Map<string, ParsedMessageEvent[]>();
+
+  /**
+   * Default `onCardClick`: the confirm button's token routes through the exact
+   * same `deps.confirm` a bare token typed on the terminal uses — one execution
+   * path, one set of valid/expired/wrong-session-token behaviors, regardless of
+   * how the token got here.
+   */
+  const onCardClick: CardClickHandler =
+    deps.onCardClick ??
+    (async (params, space, sender) => {
+      const token = params.token;
+      if (!token) {
+        log(`[chat] card click with no token parameter`);
+        return;
+      }
+      const reply = await deps.confirm(token, deriveSessionKey(space, sender), sender);
+      if (reply !== null) {
+        log(`[chat:${space}] [out] ${reply}`);
+        const sent = await sendMessageFn(space, reply, clientDeps);
+        sentMessageNames.add(sent.name);
+      }
+    });
+  let activeSubscription: PubSubSubscription | undefined;
+
+  /** Per-turn output sink — same responsibilities as the retired `ChatStreamer`, rebuilt against the new client. */
+  function createSink(space: string): TurnSink {
+    let chain: Promise<void> = Promise.resolve();
+
+    function enqueue(fn: () => Promise<void>): void {
+      chain = chain.then(async () => {
+        try {
+          await fn();
+        } catch (err) {
+          log(`[chat:${space}] send failed: ${String(err)}`);
+        }
+      });
+    }
+    function sendPlain(text: string): void {
+      enqueue(async () => {
+        log(`[chat:${space}] [out] ${text}`);
+        const sent = await sendMessageFn(space, text, clientDeps);
+        sentMessageNames.add(sent.name);
+      });
+    }
+
+    // Keyed by toolCallId (or, for a capture-ping, the id its own caller
+    // generated — see index.ts's captureIncrement/processToolCorrections):
+    // lets onToolFinish patch the exact message onToolStart created for
+    // that same call, rather than guessing the most recent one.
+    const toolCards = new Map<string, { name: string; label: string; detail: string }>();
+
+    // Keyed by the SDK's own reasoning-block id, exactly like toolCards —
+    // a tool-calling turn can reason more than once (before a tool call,
+    // again after seeing its result), each burst a fully independent card,
+    // never a continuation of an earlier one.
+    const reasoningCards = new Map<string, { name: string | undefined; buffer: string }>();
+
+    // Claimed (patched into the turn's first reasoning card) by
+    // onReasoningChunk below, then cleared — a second reasoning burst in
+    // the same turn (e.g. after a tool call) always gets its own new card,
+    // never reuses this one.
+    let receivingCardName: string | undefined;
+    enqueue(async () => {
+      log(`[chat:${space}] [out] receiving card`);
+      const sent = await sendCardFn(space, buildReceivingCard(), clientDeps);
+      sentMessageNames.add(sent.name);
+      receivingCardName = sent.name;
+    });
+
+    return {
+      onToolStart: (label: string, detail?: string, toolCallId?: string) => {
+        if (toolCallId === undefined) {
+          sendPlain(`_${label}_`);
+          return;
+        }
+        enqueue(async () => {
+          const card = buildToolCallCard(label, detail ?? "", "loading");
+          log(`[chat:${space}] [out] tool card: ${label}`);
+          const sent = await sendCardFn(space, card, clientDeps);
+          sentMessageNames.add(sent.name);
+          toolCards.set(toolCallId, { name: sent.name, label, detail: detail ?? "" });
+        });
+      },
+      onToolFinish: (toolCallId: string, outcome: ToolOutcome) => {
+        enqueue(async () => {
+          const entry = toolCards.get(toolCallId);
+          if (!entry) {
+            log(`[chat:${space}] onToolFinish for unknown toolCallId ${toolCallId}`);
+            return;
+          }
+          const card = buildToolCallCard(entry.label, entry.detail, outcome);
+          log(`[chat:${space}] [out] patching ${entry.name} to "${outcome}"`);
+          const patched = await updateCardFn(entry.name, card, clientDeps);
+          log(`[chat:${space}] [out] patched ${patched.name}`);
+          toolCards.delete(toolCallId);
+        });
+      },
+      // Only ever fires for a model that actually supports Ollama's
+      // extended thinking (see src/index.ts's OLLAMA_THINK) — a
+      // non-reasoning model means this is simply never called, so no card
+      // is ever created for that turn.
+      onReasoningChunk: (chunk: string, id: string) => {
+        let entry = reasoningCards.get(id);
+        if (!entry) {
+          entry = { name: undefined, buffer: chunk };
+          reasoningCards.set(id, entry);
+          enqueue(async () => {
+            const card = buildToolCallCard("Sto pensando…", "", "loading");
+            if (receivingCardName !== undefined) {
+              // Replace the "Stato" placeholder in place instead of
+              // sending a second message.
+              log(`[chat:${space}] [out] reasoning card (${id}) — replacing receiving card`);
+              const patched = await updateCardFn(receivingCardName, card, clientDeps);
+              entry!.name = patched.name;
+              receivingCardName = undefined;
+            } else {
+              log(`[chat:${space}] [out] reasoning card (${id})`);
+              const sent = await sendCardFn(space, card, clientDeps);
+              sentMessageNames.add(sent.name);
+              entry!.name = sent.name;
+            }
+          });
+          return;
+        }
+        // Accumulated only, never patched here: no live peek at the
+        // reasoning text while it's still streaming — see buildToolCallCard's
+        // doc comment for why. Revealed once, in full, by onReasoningEnd.
+        entry.buffer += chunk;
+      },
+      onReasoningEnd: (id: string, failed: boolean) => {
+        log(`[chat:${space}] onReasoningEnd(${id}, failed=${failed})`);
+        const entry = reasoningCards.get(id);
+        if (!entry) return; // no reasoning happened for this id — no card to close
+        enqueue(async () => {
+          if (entry.name === undefined) return; // shouldn't happen given enqueue's own FIFO ordering, but stays defensive
+          const status = failed ? "failed" : "success";
+          const card = buildToolCallCard("Sto pensando…", tailTruncate(entry.buffer, REASONING_TAIL_CHARS), status);
+          log(`[chat:${space}] [out] reasoning patch (${id}): status=${status} bufferLen=${entry.buffer.length}`);
+          await updateCardFn(entry.name, card, clientDeps);
+          reasoningCards.delete(id);
+        });
+      },
+      // Deliberately absent: Google Chat only shows a message once fully
+      // sent, so incremental delivery never actually reaches a human
+      // faster — this MUST stay undefined, it's what keeps runTurn on its
+      // non-streaming path (see src/router/provider.ts's TurnSink).
+      onUsage: (inputTokens) => log(`[chat:${space}] [usage] inputTokens=${inputTokens ?? "?"}`),
+      onStep: (step) => {
+        const pending = detectPendingConfirmation(step);
+        if (pending) {
+          enqueue(async () => {
+            log(`[chat:${space}] [out] confirm card: ${pending.summary}`);
+            const sent = await sendCardFn(space, buildConfirmCard(pending), clientDeps);
+            sentMessageNames.add(sent.name);
+          });
+        }
+      },
+      finalize: async (finalText: string) => {
+        const trimmed = finalText.trim();
+        if (trimmed.length > 0 && trimmed !== NO_REPLY && trimmed !== PENDING_CONFIRMATION_NOTE) {
+          for (const message of splitForSendLimit(trimmed)) {
+            sendPlain(message);
+          }
+        }
+        await chain;
+      },
+      dispose: () => {},
+    };
+  }
+
+  async function processMessageEvent(event: ParsedMessageEvent, handleTurn: HandleTurn): Promise<void> {
+    if (sentMessageNames.has(event.messageName)) return;
+
+    log(`[chat:${event.space}:${event.sender}] [in] ${event.text}`);
+
+    const sessionKey = deriveSessionKey(event.space, event.sender);
+    const markedInput = event.senderDisplayName ? `[Da: ${event.senderDisplayName}]\n${event.text}` : event.text;
+
+    const confirmReply = await deps.confirm(event.text, sessionKey, event.sender);
+    if (confirmReply !== null) {
+      log(`[chat:${event.space}] [out] ${confirmReply}`);
+      const sent = await sendMessageFn(event.space, confirmReply, clientDeps);
+      sentMessageNames.add(sent.name);
+      return;
+    }
+
+    // Only the actual model turn needs serializing — tryConfirm above
+    // never touches SessionHistory, so it's always safe to run right
+    // away regardless of whether this session is mid-turn.
+    if (busySessions.has(sessionKey)) {
+      const queue = queuedEvents.get(sessionKey) ?? [];
+      queue.push(event);
+      queuedEvents.set(sessionKey, queue);
+      return;
+    }
+
+    busySessions.add(sessionKey);
+    try {
+      const sink = createSink(event.space);
+      await handleTurn(
+        {
+          channel: "google-chat",
+          multiUser: !event.isDirectMessage,
+          text: markedInput,
+          sessionKey,
+          userId: event.sender,
+          wikiUserId: encodeURIComponent(event.sender),
+          logPrefix: `[chat:${event.space}:${event.sender}] `,
+        },
+        sink,
+      );
+    } finally {
+      busySessions.delete(sessionKey);
+      const queue = queuedEvents.get(sessionKey);
+      const next = queue?.shift();
+      if (queue && queue.length === 0) queuedEvents.delete(sessionKey);
+      if (next) {
+        processMessageEvent(next, handleTurn).catch((err) => log(`[chat] queued event handling failed: ${String(err)}`));
+      }
+    }
+  }
+
+  /**
+   * Acks each message immediately on arrival — before `handleTurn` (or
+   * `onCardClick`) ever runs, not after it resolves. Same pattern the
+   * open-source Hermes agent's Google Chat adapter uses (ack in the Pub/Sub
+   * callback, agent processing dispatched separately): a real multi-step
+   * turn routinely takes longer than the subscription's ack deadline
+   * (Google's default is 10s), so acking only once processing completes
+   * would leave a message open to being redelivered — and reprocessed a
+   * second time, concurrently — while still being worked on. Acking first
+   * decouples "message confirmed" from "turn finished" entirely, so no
+   * turn duration can trigger a redelivery. Accepted tradeoff, same one
+   * Hermes makes: a hard crash mid-turn loses that one message rather than
+   * risking an endless redelivery loop.
+   */
+  async function handleMessage(message: StreamMessage, handleTurn: HandleTurn): Promise<void> {
+    message.ack();
+    let parsed: ParsedMessageEvent | ParsedCardClickEvent | null;
+    try {
+      parsed = parseChatEvent(JSON.parse(message.data.toString("utf-8")));
+    } catch (err) {
+      log(`[chat] failed to parse Pub/Sub message: ${String(err)}`);
+      return;
+    }
+    if (!parsed) return;
+    try {
+      if (parsed.kind === "message") {
+        await processMessageEvent(parsed, handleTurn);
+      } else {
+        await onCardClick(parsed.parameters, parsed.space, parsed.sender);
+      }
+    } catch (err) {
+      log(`[chat] event handling failed: ${String(err)}`);
+    }
+  }
+
+  return {
+    async start(handleTurn: HandleTurn): Promise<void> {
+      const sub = subscriptionFn(deps.credentials, deps.subscription);
+      activeSubscription = sub;
+      sub.on("message", (message) => {
+        handleMessage(message, handleTurn).catch((err) => log(`[chat] event handling failed: ${String(err)}`));
+      });
+      // The SDK retries transient stream errors internally — this only
+      // fires for something it gave up on. Logged, not thrown: one bad
+      // stream event must never take down the rest of Mercury (same
+      // convention every other channel/poller loop in this project
+      // follows).
+      sub.on("error", (err) => log(`[chat] pubsub stream error: ${String(err)}`));
+    },
+
+    async stop(): Promise<void> {
+      await activeSubscription?.close();
+    },
+
+    async notify(userId: string, text: string): Promise<{ sessionKey: string }> {
+      // sessionKey is the DM space's name, not the sent message's — matches
+      // the retired channel's exact behavior (preserved, not fixed, per
+      // this plan's "known pre-existing inconsistency" note: a real
+      // conversation in that DM is keyed space:sender, not space.name
+      // alone; reconciling that is a separate decision).
+      const space = await getOrCreateDmSpaceFn(userId, clientDeps);
+      const sent = await sendMessageFn(space.name, text, clientDeps);
+      sentMessageNames.add(sent.name); // loop prevention applies here too — a proactive notification is still our own message if it comes back as an event
+      return { sessionKey: space.name };
+    },
+  };
+}

package/google-chat-pubsub-stream.ts

@@ -0,0 +1,54 @@
+/**
+ * Wraps `@google-cloud/pubsub` for the one thing this app needs: a
+ * long-lived StreamingPull subscription that emits decoded events as they
+ * arrive, replacing the retired REST `pull`-in-a-`setInterval` loop
+ * (`pullEvents`/`acknowledge` in `google-chat-app-client.ts`) — synchronous
+ * Pull has no real long-polling (confirmed against Google's own docs: an
+ * empty response doesn't mean the server waited for a message), so a fixed
+ * poll interval was the only lever available with that API. StreamingPull
+ * is a bidirectional gRPC stream; hand-rolling that with `fetch` the way
+ * the REST pull/ack calls were isn't practical, hence the one real
+ * dependency this project takes on Google's own client library.
+ *
+ * Isolated in its own file so `google-chat-provider.ts` never imports the
+ * SDK directly — its own tests inject a fake via the `subscriptionFn` seam
+ * instead of touching real gRPC. Verified live (`docs/DECISIONS.md`) that
+ * this SDK's StreamingPull works cleanly under Bun in this project's real
+ * Docker image before this file was written.
+ */
+import { PubSub } from "@google-cloud/pubsub";
+import type { ServiceAccountCredentials } from "./google-chat-app-client.ts";
+
+/** One incoming Pub/Sub message. `data` is already the raw message body — the SDK handles the wire-level base64 transport itself. */
+export type StreamMessage = { data: Buffer; ack: () => void; nack: () => void };
+
+/** The subset of `@google-cloud/pubsub`'s `Subscription` this app actually uses — narrowed so a fake can satisfy it in tests without depending on the real SDK's types. */
+export type PubSubSubscription = {
+  on(event: "message", listener: (message: StreamMessage) => void): void;
+  on(event: "error", listener: (err: Error) => void): void;
+  close(): Promise<void>;
+};
+
+/** Splits `"projects/<id>/subscriptions/<name>"` into its two parts — thrown separately so a malformed env var fails fast and clearly, not deep inside the SDK's own error handling. */
+export function parseSubscriptionName(resourceName: string): { projectId: string; subscriptionId: string } {
+  const match = resourceName.match(/^projects\/([^/]+)\/subscriptions\/([^/]+)$/);
+  if (!match) throw new Error(`unexpected Pub/Sub subscription resource name: ${resourceName}`);
+  return { projectId: match[1]!, subscriptionId: match[2]! };
+}
+
+/**
+ * Opens a StreamingPull subscription. Real gRPC — exercised by the Phase 0
+ * spike and live verification, not by unit tests (`google-chat-provider.ts`
+ * injects a fake `PubSubSubscription` via its own `subscriptionFn` seam for
+ * those). Credentials are passed directly (`client_email`/`private_key`),
+ * same service-account values already used for the Chat API's own
+ * JWT-bearer flow — no key file on disk, no second credential to manage.
+ */
+export function openSubscription(credentials: ServiceAccountCredentials, resourceName: string): PubSubSubscription {
+  const { projectId, subscriptionId } = parseSubscriptionName(resourceName);
+  const pubsub = new PubSub({
+    projectId,
+    credentials: { client_email: credentials.clientEmail, private_key: credentials.privateKey },
+  });
+  return pubsub.subscription(subscriptionId) as unknown as PubSubSubscription;
+}

package/index.ts

@@ -0,0 +1,43 @@
+/**
+ * The Google Chat channel plugin: the `ChannelPlugin` the core's channel loader
+ * consumes. `build()` reads this channel's own config from `ctx.env` and
+ * constructs the provider; it returns `undefined` when no
+ * `GOOGLE_CHAT_PUBSUB_SUBSCRIPTION` is set (the instance isn't running Google
+ * Chat — present but inert). A subscription set with the app credentials
+ * missing is a misconfiguration: `build()` throws and the loader skips this
+ * channel fail-soft, leaving the rest of Mercury up.
+ */
+import { CHANNEL_API_VERSION, type ChannelPlugin, type ChannelRuntimeContext } from "@mercury-fw/channel-types";
+import { createGoogleChatProvider } from "./google-chat-provider.ts";
+
+/** Reads a required env var, failing loudly (caught by the channel loader) instead of silently degrading. */
+function require(env: ChannelRuntimeContext["env"], name: string): string {
+  const value = env[name];
+  if (!value) {
+    throw new Error(`${name} is not set`);
+  }
+  return value;
+}
+
+export const googleChatChannel: ChannelPlugin = {
+  apiVersion: CHANNEL_API_VERSION,
+  name: "google-chat",
+  build: (ctx) => {
+    // No subscription configured ⇒ this instance simply doesn't run Google Chat.
+    const subscription = ctx.env.GOOGLE_CHAT_PUBSUB_SUBSCRIPTION;
+    if (!subscription) {
+      return undefined;
+    }
+    return createGoogleChatProvider({
+      credentials: {
+        clientEmail: require(ctx.env, "GOOGLE_CHAT_APP_CLIENT_EMAIL"),
+        // A PEM key is multi-line; stored in a single-line env var with literal
+        // "\n" escapes — unescape before Node's crypto, which needs real newlines.
+        privateKey: require(ctx.env, "GOOGLE_CHAT_APP_PRIVATE_KEY").replace(/\\n/g, "\n"),
+      },
+      subscription,
+      confirm: ctx.confirm,
+      log: ctx.log,
+    });
+  },
+};

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@mercury-fw/channel-google-chat",
+  "version": "0.1.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lucabro81/mercury-fw.git",
+    "directory": "packages/channels/channel-google-chat"
+  },
+  "files": [
+    "*.ts",
+    "dist",
+    "CHANGELOG.md",
+    "!**/*.test.ts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "mercury-fw-source": "./index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./index.ts"
+    }
+  },
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@google-cloud/pubsub": "^5.3.1"
+  },
+  "peerDependencies": {
+    "@mercury-fw/channel-types": ">=0.24.0 <1.0.0"
+  },
+  "devDependencies": {
+    "@mercury-fw/channel-types": "0.25.0",
+    "@mercury-fw/typescript-config": "*",
+    "@types/bun": "^1.4.0",
+    "typescript": "^6.0.3"
+  }
+}