@mercury-fw/channel-google-chat 0.6.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @mercury-fw/channel-google-chat
 
+## 0.8.0
+
+### Minor Changes
+
+- b2f8cfb: - A confirmation can offer several choices (for example "only this time" / "always for this host"): a plugin tool stages them with the new `stageChoices` of `SessionToolContext`, and gets one token per choice. The person takes one; the others die with it, and they all expire together.
+  - The paper-trail note of a group of choices is one, under its first token, and says which choice was taken.
+  - `detectPendingConfirmation` returns the `choices` a staging offers; a plain staging is one choice labelled `Conferma`.
+  - A confirmed action can hand its result back to the model (`resume` on a choice): instead of showing the person the raw result, the channel resumes the turn and the model answers on it, the result reaching it as the tool result of the call that staged it, never stored in the history.
+  - A resumed turn answers the person who confirmed even in a shared space, and the line standing for the confirmation isn't archived as something they said. A result nobody resumes within five minutes (the life of a confirmation token) is forgotten, and a restart loses it.
+  - `InboundTurn.resumeAfterConfirm` and `RESUME_AFTER_CONFIRM` (channel contract) carry the resumed turn; `ConfirmOutcome` has a `resume` status.
+  - Terminal: every choice is printed on its own line with its token; a confirmation that resumes runs the turn again.
+  - Google Chat: the confirmation card has one button per choice; a typed token or a clicked choice that resumes runs the turn again, in the session's queue. The channel now needs channel-types 0.51.0 or later.
+  - HTTP: the `pending` event carries `choices`; a token sent to `POST /turn` that resumes streams the model's answer on the same request; `POST /confirm` answers `resume: true`, and `POST /turn { resume: true, conversationId }` runs that turn. The channel now needs channel-types 0.51.0 or later.
+
+## 0.7.0
+
+### Minor Changes
+
+- 4184ea6: - `loginLinkText` words a login link the same way on every channel, and the contract states that a login link is shown only to the person it's for.
+  - Google Chat shows the login to a service a plugin acts on as the person (Jira, Bitbucket) as a button that opens it, visible only to them: in a shared space it's a private message to whoever asked.
+  - `@mercury-fw/channel-google-chat` needs `@mercury-fw/channel-types` 0.46.0 or later.
+
 ## 0.6.0
 
 ### Minor Changes

package/README.md

@@ -26,6 +26,8 @@ channels: [googleChatChannel],
 
 Each message reaches the core as `google-chat:users/<id>`, the sender's Chat user, with their email when Google vouches for it (a person's, never a bot's), which a user directory can join on: the ZITADEL directory of `@mercury-fw/plugin-zitadel` does.
 
+When a plugin that acts as the person (Jira, Bitbucket) needs them to log in, the channel sends a card with a button that opens the service's login, visible only to that person: in a direct message the space is already theirs, in a shared space the card is a private message to whoever asked, since anyone else opening it would log their own account in as them. The service sends the browser back to the HTTP channel's `/login/callback`, so the app needs [`@mercury-fw/channel-http`](https://www.npmjs.com/package/@mercury-fw/channel-http) with `HTTP_SURFACE_PUBLIC_URL` too; without it Mercury answers that nobody can log in on this instance.
+
 ## Table of contents
 
 - [Setting up the Chat app](#setting-up-the-chat-app)

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

@@ -55,10 +55,16 @@ export type ChatCard = {
     };
     sections: ChatCardSection[];
 };
-/** Posts `card` as a Cards v2 message to `space`. Returns the created message's `name`, same shape as `sendMessage`. */
+/**
+ * Posts `card` as a Cards v2 message to `space`. Returns the created message's
+ * `name`, same shape as `sendMessage`. With `privateViewer` (`users/<id>`) only
+ * that user and the app see it, in a space anyone else is in too.
+ */
 export declare function sendCard(space: string, card: ChatCard, deps: {
     tokenSource: TokenSource;
     fetchFn?: FetchFn;
+}, options?: {
+    privateViewer?: string;
 }): Promise<{
     name: string;
 }>;

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

@@ -58,10 +58,12 @@ export type ParsedCardClickEvent = {
     sender: string;
     senderEmail: string | undefined;
     parameters: Record<string, string>;
+    /** As on a message (see `ParsedMessageEvent.isDirectMessage`): for the turn a click resumes. */
+    isDirectMessage: boolean;
 };
 /** 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, senderEmail?: string) => Promise<void>;
+export type CardClickHandler = (params: Record<string, string>, space: string, sender: string, senderEmail?: string, isDirectMessage?: boolean) => Promise<void>;
 export type GoogleChatProviderDeps = {
     credentials: ServiceAccountCredentials;
     subscription: string;

package/google-chat-app-client.ts

@@ -171,17 +171,22 @@ export type ChatCardSection = {
 };
 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`. */
+/**
+ * Posts `card` as a Cards v2 message to `space`. Returns the created message's
+ * `name`, same shape as `sendMessage`. With `privateViewer` (`users/<id>`) only
+ * that user and the app see it, in a space anyone else is in too.
+ */
 export async function sendCard(
   space: string,
   card: ChatCard,
   deps: { tokenSource: TokenSource; fetchFn?: FetchFn },
+  options: { privateViewer?: string } = {},
 ): Promise<{ name: string }> {
-  const data = (await callChatApi(
-    `${space}/messages`,
-    { method: "POST", body: { cardsV2: [{ cardId: "card", card }] } },
-    deps,
-  )) as { name: string };
+  const body = {
+    cardsV2: [{ cardId: "card", card }],
+    ...(options.privateViewer === undefined ? {} : { privateMessageViewer: { name: options.privateViewer } }),
+  };
+  const data = (await callChatApi(`${space}/messages`, { method: "POST", body }, deps)) as { name: string };
   return { name: data.name };
 }
 

package/google-chat-provider.ts

@@ -32,9 +32,13 @@ import {
 import { openSubscription, type PubSubSubscription, type StreamMessage } from "./google-chat-pubsub-stream.ts";
 import { splitForSendLimit } from "./google-chat-message-buffer.ts";
 import {
+  detectLoginRequired,
   detectPendingConfirmation,
+  loginLinkText,
   PENDING_CONFIRMATION_NOTE,
+  RESUME_AFTER_CONFIRM,
   NO_REPLY,
+  type LoginRequest,
   type PendingConfirmation,
   type ToolOutcome,
   type Provider,
@@ -45,7 +49,8 @@ import {
 
 /**
  * Builds the confirmation card sent when a step stages an irreversible
- * command (see `pending-confirmation.ts`). The button's parameters carry
+ * command (see `pending-confirmation.ts`), one button per choice it offers
+ * (a single `Conferma` for a plain staging). Each 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.
@@ -59,12 +64,10 @@ function buildConfirmCard(pending: PendingConfirmation): ChatCard {
           { textParagraph: { text: `\`${pending.summary}\`` } },
           {
             buttonList: {
-              buttons: [
-                {
-                  text: "Conferma",
-                  onClick: { action: { function: "confirm", parameters: [{ key: "token", value: pending.token }] } },
-                },
-              ],
+              buttons: pending.choices.map((choice) => ({
+                text: choice.label,
+                onClick: { action: { function: "confirm", parameters: [{ key: "token", value: choice.token }] } },
+              })),
             },
           },
         ],
@@ -73,6 +76,13 @@ function buildConfirmCard(pending: PendingConfirmation): ChatCard {
   };
 }
 
+/** The card that shows a person the link to log in to a service a plugin acts on as them: one button that opens it. */
+function buildLoginCard(login: LoginRequest): ChatCard {
+  return {
+    sections: [{ widgets: [{ buttonList: { buttons: [{ text: loginLinkText(login), onClick: { openLink: { url: login.url } } }] } }] }],
+  };
+}
+
 const TOOL_STATUS_LINES: Record<"loading" | ToolOutcome, string> = {
   loading: "In corso…",
   success: "Fatto.",
@@ -186,7 +196,7 @@ type RawChatEvent = {
     sender?: RawChatSender;
   };
   action?: { actionMethodName?: string; parameters?: Array<{ key?: string; value?: string }> };
-  space?: { name?: string };
+  space?: { name?: string; type?: string };
   user?: RawChatSender;
 };
 
@@ -215,6 +225,8 @@ export type ParsedCardClickEvent = {
   sender: string;
   senderEmail: string | undefined;
   parameters: Record<string, string>;
+  /** As on a message (see `ParsedMessageEvent.isDirectMessage`): for the turn a click resumes. */
+  isDirectMessage: boolean;
 };
 
 /** The email Google vouches for on `sender`: a person's only (`HUMAN`), never a bot's or an unknown kind's. */
@@ -250,12 +262,25 @@ export function parseChatEvent(raw: unknown): ParsedMessageEvent | ParsedCardCli
         parameters[p.key] = p.value;
       }
     }
-    return { kind: "card-click", space: event.space.name, sender: event.user.name, senderEmail: emailOf(event.user), parameters };
+    return {
+      kind: "card-click",
+      space: event.space.name,
+      sender: event.user.name,
+      senderEmail: emailOf(event.user),
+      parameters,
+      isDirectMessage: event.space.type === "DM",
+    };
   }
   return null;
 }
 
-export type CardClickHandler = (params: Record<string, string>, space: string, sender: string, senderEmail?: string) => Promise<void>;
+export type CardClickHandler = (
+  params: Record<string, string>,
+  space: string,
+  sender: string,
+  senderEmail?: string,
+  isDirectMessage?: boolean,
+) => Promise<void>;
 
 export type GoogleChatProviderDeps = {
   credentials: ServiceAccountCredentials;
@@ -309,7 +334,50 @@ export function createGoogleChatProvider(deps: GoogleChatProviderDeps): GoogleCh
   // 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[]>();
+  const queuedTurns = new Map<string, Array<() => Promise<void>>>();
+  // The turn handler `start` was given, for a turn a card click resumes.
+  let activeHandleTurn: HandleTurn | undefined;
+
+  /** Runs `turn` for `sessionKey` now, or after the turns already queued for it. */
+  async function runInSession(sessionKey: string, turn: () => Promise<void>): Promise<void> {
+    if (busySessions.has(sessionKey)) {
+      const queue = queuedTurns.get(sessionKey) ?? [];
+      queue.push(turn);
+      queuedTurns.set(sessionKey, queue);
+      return;
+    }
+    busySessions.add(sessionKey);
+    try {
+      await turn();
+    } finally {
+      busySessions.delete(sessionKey);
+      const queue = queuedTurns.get(sessionKey);
+      const next = queue?.shift();
+      if (queue && queue.length === 0) queuedTurns.delete(sessionKey);
+      if (next) {
+        runInSession(sessionKey, next).catch((err) => log(`[chat] queued turn failed: ${String(err)}`));
+      }
+    }
+  }
+
+  /** Resumes the session's turn after a confirmation whose result went back to the model (`RESUME_AFTER_CONFIRM`). */
+  function resumeTurn(handleTurn: HandleTurn, space: string, principal: Principal, isDirectMessage: boolean): Promise<void> {
+    const sessionKey = deriveSessionKey(space, principal.id);
+    return runInSession(sessionKey, () =>
+      handleTurn(
+        {
+          channel: "google-chat",
+          multiUser: !isDirectMessage,
+          text: "",
+          sessionKey,
+          principal,
+          logPrefix: `[chat:${space}:${principal.id}] `,
+          resumeAfterConfirm: true,
+        },
+        createSink(space, { user: principal.id, isDirectMessage }),
+      ),
+    );
+  }
 
   /**
    * Default `onCardClick`: the confirm button's token routes through the exact
@@ -319,17 +387,22 @@ export function createGoogleChatProvider(deps: GoogleChatProviderDeps): GoogleCh
    */
   const onCardClick: CardClickHandler =
     deps.onCardClick ??
-    (async (params, space, sender, senderEmail) => {
+    (async (params, space, sender, senderEmail, isDirectMessage = false) => {
       const token = params.token;
       if (!token) {
         log(`[chat] card click with no token parameter`);
         return;
       }
-      const reply = await deps.confirm(token, deriveSessionKey(space, sender), {
+      const principal: Principal = {
         id: sender,
         provider: "google-chat",
         ...(senderEmail === undefined ? {} : { claims: { email: senderEmail } }),
-      });
+      };
+      const reply = await deps.confirm(token, deriveSessionKey(space, sender), principal);
+      if (reply === RESUME_AFTER_CONFIRM && activeHandleTurn) {
+        await resumeTurn(activeHandleTurn, space, principal, isDirectMessage);
+        return;
+      }
       if (reply !== null) {
         log(`[chat:${space}] [out] ${reply}`);
         const sent = await sendMessageFn(space, reply, clientDeps);
@@ -338,8 +411,12 @@ export function createGoogleChatProvider(deps: GoogleChatProviderDeps): GoogleCh
     });
   let activeSubscription: PubSubSubscription | undefined;
 
-  /** Per-turn output sink — same responsibilities as the retired `ChatStreamer`, rebuilt against the new client. */
-  function createSink(space: string): TurnSink {
+  /**
+   * Per-turn output sink — same responsibilities as the retired `ChatStreamer`,
+   * rebuilt against the new client. `viewer` is the person the turn is for;
+   * outside a direct message, what only they may see is sent to them alone.
+   */
+  function createSink(space: string, viewer: { user: string; isDirectMessage: boolean }): TurnSink {
     let chain: Promise<void> = Promise.resolve();
 
     function enqueue(fn: () => Promise<void>): void {
@@ -376,6 +453,9 @@ export function createGoogleChatProvider(deps: GoogleChatProviderDeps): GoogleCh
     // the same turn (e.g. after a tool call) always gets its own new card,
     // never reuses this one.
     let receivingCardName: string | undefined;
+
+    // A tool asking again in the same turn hands back the same pending login.
+    const shownLogins = new Set<string>();
     enqueue(async () => {
       log(`[chat:${space}] [out] receiving card`);
       const sent = await sendCardFn(space, buildReceivingCard(), clientDeps);
@@ -470,6 +550,16 @@ export function createGoogleChatProvider(deps: GoogleChatProviderDeps): GoogleCh
             sentMessageNames.add(sent.name);
           });
         }
+        const login = detectLoginRequired(step);
+        if (login && !shownLogins.has(login.url)) {
+          shownLogins.add(login.url);
+          enqueue(async () => {
+            log(`[chat:${space}] [out] login card: ${login.service}`);
+            const options = viewer.isDirectMessage ? undefined : { privateViewer: viewer.user };
+            const sent = await sendCardFn(space, buildLoginCard(login), clientDeps, options);
+            sentMessageNames.add(sent.name);
+          });
+        }
       },
       finalize: async (finalText: string) => {
         const trimmed = finalText.trim();
@@ -501,6 +591,10 @@ export function createGoogleChatProvider(deps: GoogleChatProviderDeps): GoogleCh
     };
 
     const confirmReply = await deps.confirm(event.text, sessionKey, principal);
+    if (confirmReply === RESUME_AFTER_CONFIRM) {
+      await resumeTurn(handleTurn, event.space, principal, event.isDirectMessage);
+      return;
+    }
     if (confirmReply !== null) {
       log(`[chat:${event.space}] [out] ${confirmReply}`);
       const sent = await sendMessageFn(event.space, confirmReply, clientDeps);
@@ -511,17 +605,8 @@ export function createGoogleChatProvider(deps: GoogleChatProviderDeps): GoogleCh
     // 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(
+    await runInSession(sessionKey, () =>
+      handleTurn(
         {
           channel: "google-chat",
           multiUser: !event.isDirectMessage,
@@ -530,17 +615,9 @@ export function createGoogleChatProvider(deps: GoogleChatProviderDeps): GoogleCh
           principal,
           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)}`));
-      }
-    }
+        createSink(event.space, { user: event.sender, isDirectMessage: event.isDirectMessage }),
+      ),
+    );
   }
 
   /**
@@ -571,7 +648,7 @@ export function createGoogleChatProvider(deps: GoogleChatProviderDeps): GoogleCh
       if (parsed.kind === "message") {
         await processMessageEvent(parsed, handleTurn);
       } else {
-        await onCardClick(parsed.parameters, parsed.space, parsed.sender, parsed.senderEmail);
+        await onCardClick(parsed.parameters, parsed.space, parsed.sender, parsed.senderEmail, parsed.isDirectMessage);
       }
     } catch (err) {
       log(`[chat] event handling failed: ${String(err)}`);
@@ -580,6 +657,7 @@ export function createGoogleChatProvider(deps: GoogleChatProviderDeps): GoogleCh
 
   return {
     async start(handleTurn: HandleTurn): Promise<void> {
+      activeHandleTurn = handleTurn;
       const sub = subscriptionFn(deps.credentials, deps.subscription);
       activeSubscription = sub;
       sub.on("message", (message) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mercury-fw/channel-google-chat",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -31,10 +31,10 @@
     "@google-cloud/pubsub": "^5.3.1"
   },
   "peerDependencies": {
-    "@mercury-fw/channel-types": ">=0.36.0 <1.0.0"
+    "@mercury-fw/channel-types": ">=0.51.0 <1.0.0"
   },
   "devDependencies": {
-    "@mercury-fw/channel-types": "0.44.1",
+    "@mercury-fw/channel-types": "0.51.0",
     "@mercury-fw/typescript-config": "*",
     "@types/bun": "^1.4.2",
     "typescript": "^6.0.3"