@mercury-fw/channel-google-chat 0.9.0 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # @mercury-fw/channel-google-chat
 
+## 0.11.0
+
+### Minor Changes
+
+- e3eb49d: Stop an answer from Google Chat.
+
+  - Every card still in progress (the receiving card, a reasoning card, a tool's card) has a Stop button, in a section of its own so it's visible without expanding the card; the card's final state has none.
+  - `/stop` does the same: the registered slash command, or a message reading exactly `/stop`. With nothing running, the reply says there's nothing to stop.
+  - A stop aborts the person's running turn and discards the messages they queued behind it. No partial answer is sent; the card in progress says "Stopped." (or a short message does, when no card was in progress). A command a tool already ran stays done.
+  - Only the person who started the answer can stop it: in a shared space, someone else's stop doesn't touch it.
+  - New texts: `google-chat.status.stopped`, `google-chat.stop.button`, `google-chat.stop.nothing`.
+
+  Needs the framework at 0.58 or later; an older core stops the model too, but sends the half answer it had. To have Chat suggest `/stop`, and to let it reach the app in a space without a mention, add it in the Chat app's configuration (Cloud Console, Google Chat API → Configuration → Commands): type Slash command, name `/stop`, any free command id.
+
+## 0.10.0
+
+### Minor Changes
+
+- 1126106: Every turn tells the model when and where the person wrote it.
+
+  - Each message reaches the model after a line with the weekday, date, time and time zone it was written in (`[Wednesday 2026-10-21 14:32 Europe/Rome]`), and the system prompt says what that line is. The conversation's archive and what a UI shows of it keep the message as written.
+  - A resumed conversation's messages come back stamped from the archive's timestamps.
+  - The Layer 1 summary keeps when things were said; the episodic summary quotes a date only from those lines, never guessing one. The semantic-fact extractor and the capture card's preview leave the line out.
+  - The time zone, always an IANA name (`Europe/Rome`), is the one the person saved, else the one their client is in when the channel passes it on, else the new `i18n.timeZone` in `mercury.config.ts`, else the machine's. A `timeZone` that isn't a zone's name stops the start.
+  - The person saves theirs by telling the assistant (the new `set_time_zone` tool), or from a channel's settings.
+  - Channel contract: `InboundTurn.timeZoneHint`, and `ctx.settings.setTimeZone` for a channel with a settings area; `reads.me` also returns the saved `timeZone`. Both are optional additions: the contract version stays 6.
+  - HTTP channel: the `X-Time-Zone` header on `POST /turn` (allowed by CORS), `timeZone` in `GET /me`, and `PATCH /me` with `{ timeZone }` to save it. Needs the framework at 0.56 or later; an older core ignores the header and offers no `PATCH /me`.
+  - Google Chat channel: the client's time zone (`common.timeZone`), when the event carries it, on messages and on the turn a click resumes.
+
+  To set a default for an app's people, add `timeZone: "Europe/Rome"` (their zone) to `i18n` in `mercury.config.ts`; without it the machine's zone is used, often UTC inside a container.
+
 ## 0.9.0
 
 ### Minor Changes

package/README.md

@@ -26,14 +26,16 @@ 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.
 
-This version is written for version 6 of the channel contract, the one that brings the channels' texts in the person's language, and needs the framework at 0.54 or later: a core with an older contract skips it, and the log says why.
+This version is written for version 6 of the channel contract, the one that brings the channels' texts in the person's language, and needs the framework at 0.54 or later: a core with an older contract skips it, and the log says why. The client's time zone reaches the model from the framework at 0.56 on; an older core ignores it. Stopping an answer needs the framework at 0.58 or later: an older core stops the model as well, but then sends the half answer it had.
 
 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.
 
-Every text the channel shows a person (the cards' titles and status lines, the confirm button, the replies to a confirmation) is in their language: the one they asked the assistant for, else the language of their Chat client when the event carries it, else the app's default. The cards' own texts are `google-chat.` keys an app translates in its language files.
+Every text the channel shows a person (the cards' titles and status lines, the confirm button, the replies to a confirmation) is in their language: the one they asked the assistant for, else the language of their Chat client when the event carries it, else the app's default. The cards' own texts are `google-chat.` keys an app translates in its language files. The time zone of their Chat client, when the event carries it (`common.timeZone`), goes to the core the same way: the model reads each message with the time there, unless the person saved a zone of their own.
 
 When a tool stages an action that needs confirming, the channel sends a card with the action and a button per choice the tool offers: one "Confirm" for a plain staging (deleting a Jira issue, say), more when there's a choice to make (the web search plugin offers "Only this time" and "Always for \<host\>", in the person's language, before reading a page on a host nobody allowed). Clicking a button confirms that choice and the others die with it, and the card shows the choice taken instead of the buttons; typing the token in the conversation does the same, leaving the card as it is. A click that confirms nothing (the request expired, or in a shared space it's someone else's) leaves the card for whoever has to choose. When the confirmed action's result goes back to the model (a page read after the person allowed it), the channel runs the conversation's turn again instead of sending the raw result, so the answer comes from the model, built on what came back.
 
+While it works, every card still in progress (the one that says the message arrived, a reasoning card, a tool's card) has a Stop button, and sending `/stop` does the same. A stop ends the answer the person was waiting for and throws away the messages they had queued behind it: nothing of the half answer is sent, the card in progress says it stopped (or a short message does, when no card was in progress), and the conversation keeps their message with a note that the answer was stopped, so whatever they write next still has its context. A command a tool already ran stays done, since the stop cuts the model, not the command. Only the person who started the answer can stop it: in a shared space someone else's Stop or `/stop` finds nothing of theirs running, and `/stop` with nothing running says so. The button works as soon as the channel is installed, while `/stop` typed as a message works too, the registered slash command (step 7, item 8) only adds it to the commands Chat suggests, and lets it reach the app in a space without mentioning it.
+
 ## Table of contents
 
 - [Setting up the Chat app](#setting-up-the-chat-app)
@@ -145,6 +147,7 @@ Open the Chat API's configuration page for the project, `https://console.develop
 5. **Connection settings**: pick **Cloud Pub/Sub** and paste the topic's full name, `projects/<PROJECT_ID>/topics/<TOPIC>`.
 6. **Visibility**: check **Make this Google Chat app available to specific people and groups in <your domain>** and enter who can use it (people or a group).
 7. **Logs**: check **Log errors to Logging**, so a delivery error from Chat shows up in the project's logs.
+8. **Commands**: add a command of type **Slash command**, named `/stop`, with any free **Command ID** (`1` on a new app) and a description such as "Stop the answer in progress". The channel recognises it by its name, so the id is up to you.
 
 Click **Save**. The field names here come from Google's own Pub/Sub quickstart; Console moves things around now and then, so trust the meaning over the exact position.
 

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

@@ -53,6 +53,8 @@ export type ParsedMessageEvent = {
     isDirectMessage: boolean;
     /** The language of the sender's Chat client (`common.userLocale`), when the event carries it: the turn's language hint. */
     locale?: string;
+    /** The time zone of the sender's Chat client (`common.timeZone.id`), when the event carries it: the turn's time zone hint. */
+    timeZone?: string;
 };
 export type ParsedCardClickEvent = {
     kind: "card-click";
@@ -66,12 +68,34 @@ export type ParsedCardClickEvent = {
     isDirectMessage: boolean;
     /** As on a message (see `ParsedMessageEvent.locale`). */
     locale?: string;
+    /** As on a message (see `ParsedMessageEvent.timeZone`). */
+    timeZone?: string;
+};
+/**
+ * The person asked to stop their running turn: `/stop` (`source: "command"`,
+ * the registered slash command or a message reading exactly that), or a click
+ * on a card's Stop button (`source: "button"`).
+ */
+export type ParsedStopEvent = {
+    kind: "stop";
+    source: "command" | "button";
+    space: string;
+    sender: string;
+    senderEmail: string | undefined;
+    /** As on a message (see `ParsedMessageEvent.isDirectMessage`). */
+    isDirectMessage: boolean;
+    /** As on a message (see `ParsedMessageEvent.locale`): for the reply when there's nothing to stop. */
+    locale?: string;
+    /** For a click, the turn whose card carried the button: only that turn is stopped. */
+    turn?: 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 declare function parseChatEvent(raw: unknown): ParsedMessageEvent | ParsedCardClickEvent | ParsedStopEvent | null;
 export type CardClickHandler = (params: Record<string, string>, space: string, sender: string, senderEmail?: string, isDirectMessage?: boolean, messageName?: string, 
 /** The clicking person's client language (`ParsedCardClickEvent.locale`). */
-locale?: string) => Promise<void>;
+locale?: string, 
+/** The clicking person's client time zone (`ParsedCardClickEvent.timeZone`). */
+timeZone?: string) => Promise<void>;
 export type GoogleChatProviderDeps = {
     credentials: ServiceAccountCredentials;
     subscription: string;

package/google-chat-provider.ts

@@ -28,6 +28,7 @@ import {
   type ServiceAccountCredentials,
   type TokenSource,
   type ChatCard,
+  type ChatCardSection,
 } 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";
@@ -113,11 +114,35 @@ function buildLoginCard(login: LoginRequest, t: Translate): ChatCard {
   };
 }
 
+/** Where a status card stands: in progress, ended as a tool ends, or stopped by the person. */
+type CardStatus = "loading" | ToolOutcome | "stopped";
+
 /** A card's status line, in the person's language. */
-function statusLine(status: "loading" | ToolOutcome, t: Translate): string {
+function statusLine(status: CardStatus, t: Translate): string {
   return t(`google-chat.status.${status}`);
 }
 
+/**
+ * The section that carries the Stop button on a card in progress: a section of
+ * its own, outside the collapsible one, so it's visible without expanding
+ * anything. A click comes back as `CARD_CLICKED` with the `stop` parameter
+ * set to `turn`, the id of the turn the card belongs to (`parseChatEvent`), so
+ * a button left on an older card never stops a newer turn. A card's final
+ * patch rebuilds it without this section, so the button goes away with the
+ * turn.
+ */
+function stopSection(t: Translate, turn: string): ChatCardSection {
+  return {
+    widgets: [
+      {
+        buttonList: {
+          buttons: [{ text: t("google-chat.stop.button"), onClick: { action: { function: "stop", parameters: [{ key: "stop", value: turn }] } } }],
+        },
+      },
+    ],
+  };
+}
+
 /**
  * A tool-call/reasoning status card: `label` is a section `header`
  * (Google Chat's native accordion title, always visible regardless of
@@ -146,7 +171,7 @@ function statusLine(status: "loading" | ToolOutcome, t: Translate): string {
  * 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, t: Translate): ChatCard {
+function buildToolCallCard(label: string, detail: string, status: CardStatus, t: Translate, turn: string): ChatCard {
   return {
     sections: [
       {
@@ -155,6 +180,7 @@ function buildToolCallCard(label: string, detail: string, status: "loading" | To
         uncollapsibleWidgetsCount: 0,
         widgets: [{ textParagraph: { text: detail } }, { textParagraph: { text: statusLine(status, t) } }],
       },
+      ...(status === "loading" ? [stopSection(t, turn)] : []),
     ],
   };
 }
@@ -182,10 +208,17 @@ const REASONING_TAIL_CHARS = 4000;
  * in this file. If the turn's first reasoning burst arrives,
  * `onReasoningChunk` patches this exact card into the "Thinking…"
  * card in place, rather than sending a second message; otherwise it's
- * simply left as the last status before the turn's real answer.
+ * left as the last status before the turn's real answer, patched only to
+ * take its Stop button away, or to say the person stopped the turn.
  */
-function buildReceivingCard(t: Translate): ChatCard {
-  return { sections: [{ header: t("google-chat.receiving.title"), widgets: [{ textParagraph: { text: t("google-chat.receiving.text") } }] }] };
+function buildReceivingCard(t: Translate, turn: string, state: "loading" | "answered" | "stopped" = "loading"): ChatCard {
+  const text = state === "stopped" ? statusLine("stopped", t) : t("google-chat.receiving.text");
+  return {
+    sections: [
+      { header: t("google-chat.receiving.title"), widgets: [{ textParagraph: { text } }] },
+      ...(state === "loading" ? [stopSection(t, turn)] : []),
+    ],
+  };
 }
 
 /**
@@ -220,14 +253,18 @@ type RawChatEvent = {
   message?: {
     name?: string;
     text?: string;
+    /** The text without the leading @mention of the app, in a space. */
+    argumentText?: string;
     space?: { name?: string; type?: string };
     sender?: RawChatSender;
+    /** A slash command the message invoked shows up here, with its name. */
+    annotations?: Array<{ type?: string; slashCommand?: { commandName?: string } }>;
   };
   action?: { actionMethodName?: string; parameters?: Array<{ key?: string; value?: string }> };
   space?: { name?: string; type?: string };
   user?: RawChatSender;
-  /** What the person's Chat client says about them; `userLocale` is their language (`en-US`), when the event carries it. */
-  common?: { userLocale?: string };
+  /** What the person's Chat client says about them, when the event carries it: `userLocale` is their language (`en-US`), `timeZone.id` the zone they're in (`Europe/Rome`). */
+  common?: { userLocale?: string; timeZone?: { id?: string; offset?: number } };
 };
 
 export type ParsedMessageEvent = {
@@ -249,6 +286,8 @@ export type ParsedMessageEvent = {
   isDirectMessage: boolean;
   /** The language of the sender's Chat client (`common.userLocale`), when the event carries it: the turn's language hint. */
   locale?: string;
+  /** The time zone of the sender's Chat client (`common.timeZone.id`), when the event carries it: the turn's time zone hint. */
+  timeZone?: string;
 };
 
 export type ParsedCardClickEvent = {
@@ -263,28 +302,77 @@ export type ParsedCardClickEvent = {
   isDirectMessage: boolean;
   /** As on a message (see `ParsedMessageEvent.locale`). */
   locale?: string;
+  /** As on a message (see `ParsedMessageEvent.timeZone`). */
+  timeZone?: string;
+};
+
+/**
+ * The person asked to stop their running turn: `/stop` (`source: "command"`,
+ * the registered slash command or a message reading exactly that), or a click
+ * on a card's Stop button (`source: "button"`).
+ */
+export type ParsedStopEvent = {
+  kind: "stop";
+  source: "command" | "button";
+  space: string;
+  sender: string;
+  senderEmail: string | undefined;
+  /** As on a message (see `ParsedMessageEvent.isDirectMessage`). */
+  isDirectMessage: boolean;
+  /** As on a message (see `ParsedMessageEvent.locale`): for the reply when there's nothing to stop. */
+  locale?: string;
+  /** For a click, the turn whose card carried the button: only that turn is stopped. */
+  turn?: string;
 };
 
+/** The command that stops the session's running turn. */
+const STOP_COMMAND = "/stop";
+
+/** Whether a message asks to stop: it invoked the `/stop` slash command, or its text (after any @mention) is exactly `/stop`. */
+function isStopMessage(m: NonNullable<RawChatEvent["message"]>): boolean {
+  if (m.annotations?.some((a) => a.type === "SLASH_COMMAND" && a.slashCommand?.commandName === STOP_COMMAND)) return true;
+  const text = typeof m.argumentText === "string" ? m.argumentText : m.text;
+  return text?.trim() === STOP_COMMAND;
+}
+
 /** The language the event says the person's client is in, when it says. */
 function localeOf(event: RawChatEvent | null | undefined): string | undefined {
   const locale = event?.common?.userLocale;
   return typeof locale === "string" && locale.trim() !== "" ? locale.trim() : undefined;
 }
 
+/** The time zone the event says the person's client is in, when it says. */
+function timeZoneOf(event: RawChatEvent | null | undefined): string | undefined {
+  const id = event?.common?.timeZone?.id;
+  return typeof id === "string" && id.trim() !== "" ? id.trim() : undefined;
+}
+
 /** The email Google vouches for on `sender`: a person's only (`HUMAN`), never a bot's or an unknown kind's. */
 function emailOf(sender: RawChatSender | undefined): string | undefined {
   return typeof sender?.email === "string" && sender.email !== "" && sender.type === "HUMAN" ? sender.email : undefined;
 }
 
 /** 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 {
+export function parseChatEvent(raw: unknown): ParsedMessageEvent | ParsedCardClickEvent | ParsedStopEvent | null {
   const event = raw as RawChatEvent;
   const locale = localeOf(event);
+  const timeZone = timeZoneOf(event);
   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;
+    if (isStopMessage(m)) {
+      return {
+        kind: "stop",
+        source: "command",
+        space: m.space.name,
+        sender: m.sender.name,
+        senderEmail: emailOf(m.sender),
+        isDirectMessage: m.space.type === "DM",
+        ...(locale === undefined ? {} : { locale }),
+      };
+    }
     return {
       kind: "message",
       text: m.text,
@@ -295,6 +383,7 @@ export function parseChatEvent(raw: unknown): ParsedMessageEvent | ParsedCardCli
       senderEmail: emailOf(m.sender),
       isDirectMessage: m.space.type === "DM",
       ...(locale === undefined ? {} : { locale }),
+      ...(timeZone === undefined ? {} : { timeZone }),
     };
   }
   if (event?.type === "CARD_CLICKED") {
@@ -306,6 +395,18 @@ export function parseChatEvent(raw: unknown): ParsedMessageEvent | ParsedCardCli
         parameters[p.key] = p.value;
       }
     }
+    if (parameters.stop !== undefined) {
+      return {
+        kind: "stop",
+        source: "button",
+        turn: parameters.stop,
+        space: event.space.name,
+        sender: event.user.name,
+        senderEmail: emailOf(event.user),
+        isDirectMessage: event.space.type === "DM",
+        ...(locale === undefined ? {} : { locale }),
+      };
+    }
     return {
       kind: "card-click",
       ...(typeof event.message?.name === "string" ? { messageName: event.message.name } : {}),
@@ -315,6 +416,7 @@ export function parseChatEvent(raw: unknown): ParsedMessageEvent | ParsedCardCli
       parameters,
       isDirectMessage: event.space.type === "DM",
       ...(locale === undefined ? {} : { locale }),
+      ...(timeZone === undefined ? {} : { timeZone }),
     };
   }
   return null;
@@ -329,6 +431,8 @@ export type CardClickHandler = (
   messageName?: string,
   /** The clicking person's client language (`ParsedCardClickEvent.locale`). */
   locale?: string,
+  /** The clicking person's client time zone (`ParsedCardClickEvent.timeZone`). */
+  timeZone?: string,
 ) => Promise<void>;
 
 export type GoogleChatProviderDeps = {
@@ -371,6 +475,15 @@ export type GoogleChatProviderDeps = {
   log?: (msg: string) => void;
 };
 
+/**
+ * A turn's sink, plus what the provider does once the turn has let go:
+ * after a stop, `settle` makes the cards say so (the receiving card, or a
+ * short message when no card in progress could); after a turn that `failed`
+ * (threw, so never reached `finalize`), it takes the receiving card's Stop
+ * button away; after an answer, it does nothing.
+ */
+type StopAwareSink = TurnSink & { settle(failed: boolean): Promise<void> };
+
 export type GoogleChatProvider = Provider & {
   stop(): Promise<void>;
 };
@@ -396,12 +509,14 @@ 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 queuedTurns = new Map<string, Array<() => Promise<void>>>();
+  const queuedTurns = new Map<string, Array<(signal: AbortSignal, turnId: string) => Promise<void>>>();
+  // The running turn, per session: its id (on its cards' Stop buttons) and the abort a stop fires.
+  const runningTurns = new Map<string, { id: string; controller: AbortController }>();
   // 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> {
+  /** Runs `turn` for `sessionKey` now, or after the turns already queued for it, with a signal `stopSession` aborts. */
+  async function runInSession(sessionKey: string, turn: (signal: AbortSignal, turnId: string) => Promise<void>): Promise<void> {
     if (busySessions.has(sessionKey)) {
       const queue = queuedTurns.get(sessionKey) ?? [];
       queue.push(turn);
@@ -409,9 +524,13 @@ export function createGoogleChatProvider(deps: GoogleChatProviderDeps): GoogleCh
       return;
     }
     busySessions.add(sessionKey);
+    const controller = new AbortController();
+    const id = crypto.randomUUID();
+    runningTurns.set(sessionKey, { id, controller });
     try {
-      await turn();
+      await turn(controller.signal, id);
     } finally {
+      runningTurns.delete(sessionKey);
       busySessions.delete(sessionKey);
       const queue = queuedTurns.get(sessionKey);
       const next = queue?.shift();
@@ -422,6 +541,40 @@ export function createGoogleChatProvider(deps: GoogleChatProviderDeps): GoogleCh
     }
   }
 
+  /**
+   * Stops `sessionKey`'s running turn and discards every turn queued behind
+   * it: they haven't sent anything yet, so they just never run. With `turnId`
+   * (a button's), only when that's the turn running: a click on an older
+   * card stops nothing. Returns whether there was a turn to stop.
+   */
+  function stopSession(sessionKey: string, turnId?: string): boolean {
+    const running = runningTurns.get(sessionKey);
+    if (running === undefined || running.controller.signal.aborted) return false;
+    if (turnId !== undefined && turnId !== running.id) return false;
+    queuedTurns.delete(sessionKey);
+    running.controller.abort();
+    return true;
+  }
+
+  /**
+   * Runs one turn on `handleTurn` with the session's stop signal, then
+   * settles its cards once it has let go (`StopAwareSink.settle`).
+   */
+  async function runTurn(
+    handleTurn: HandleTurn,
+    turn: Parameters<HandleTurn>[0],
+    sink: StopAwareSink,
+    signal: AbortSignal,
+  ): Promise<void> {
+    try {
+      await handleTurn({ ...turn, abortSignal: signal }, sink);
+    } catch (err) {
+      await sink.settle(true);
+      throw err;
+    }
+    await sink.settle(false);
+  }
+
   /** Resumes the session's turn after a confirmation whose result went back to the model (`ConfirmReply.resume`). */
   async function resumeTurn(
     handleTurn: HandleTurn,
@@ -429,11 +582,13 @@ export function createGoogleChatProvider(deps: GoogleChatProviderDeps): GoogleCh
     principal: Principal,
     isDirectMessage: boolean,
     locale: string | undefined,
+    timeZone: string | undefined,
   ): Promise<void> {
     const sessionKey = deriveSessionKey(space, principal.id);
     const t = await textsFor(principal, locale);
-    return runInSession(sessionKey, () =>
-      handleTurn(
+    return runInSession(sessionKey, (signal, turnId) =>
+      runTurn(
+        handleTurn,
         {
           channel: "google-chat",
           multiUser: !isDirectMessage,
@@ -443,8 +598,10 @@ export function createGoogleChatProvider(deps: GoogleChatProviderDeps): GoogleCh
           logPrefix: `[chat:${space}:${principal.id}] `,
           resumeAfterConfirm: true,
           ...(locale === undefined ? {} : { languageHint: locale }),
+          ...(timeZone === undefined ? {} : { timeZoneHint: timeZone }),
         },
-        createSink(space, { user: principal.id, isDirectMessage }, t),
+        createSink(space, { user: principal.id, isDirectMessage }, t, signal, turnId),
+        signal,
       ),
     );
   }
@@ -460,7 +617,7 @@ export function createGoogleChatProvider(deps: GoogleChatProviderDeps): GoogleCh
    */
   const onCardClick: CardClickHandler =
     deps.onCardClick ??
-    (async (params, space, sender, senderEmail, isDirectMessage = false, messageName, locale) => {
+    (async (params, space, sender, senderEmail, isDirectMessage = false, messageName, locale, timeZone) => {
       const token = params.token;
       if (!token) {
         log(`[chat] card click with no token parameter`);
@@ -495,7 +652,7 @@ export function createGoogleChatProvider(deps: GoogleChatProviderDeps): GoogleCh
         reply = await deps.confirm(token, sessionKey, principal, locale);
       }
       if (reply?.resume && activeHandleTurn) {
-        await resumeTurn(activeHandleTurn, space, principal, isDirectMessage, locale);
+        await resumeTurn(activeHandleTurn, space, principal, isDirectMessage, locale, timeZone);
         return;
       }
       if (reply !== null) {
@@ -510,9 +667,17 @@ export function createGoogleChatProvider(deps: GoogleChatProviderDeps): GoogleCh
    * 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.
-   * `t` gives the cards' texts in their language.
+   * `t` gives the cards' texts in their language. `signal` is the turn's
+   * stop: once it aborted, a reasoning block cut short ends as "Stopped"
+   * rather than "Failed". `turn` is the turn's id, on its Stop buttons.
    */
-  function createSink(space: string, viewer: { user: string; isDirectMessage: boolean }, t: Translate): TurnSink {
+  function createSink(
+    space: string,
+    viewer: { user: string; isDirectMessage: boolean },
+    t: Translate,
+    signal: AbortSignal,
+    turn: string,
+  ): StopAwareSink {
     let chain: Promise<void> = Promise.resolve();
 
     function enqueue(fn: () => Promise<void>): void {
@@ -552,9 +717,23 @@ export function createGoogleChatProvider(deps: GoogleChatProviderDeps): GoogleCh
 
     // A tool asking again in the same turn hands back the same pending login.
     const shownLogins = new Set<string>();
+    // Whether a card already says the person stopped the turn.
+    let stopShown = false;
+    // Set once the answer is on its way: a stop after it has nothing left to say.
+    let answered = false;
+
+    /** Patches the receiving card no reasoning claimed, to `state`: it has nothing else that would ever take its Stop button away. */
+    async function closeReceivingCard(state: "answered" | "stopped"): Promise<boolean> {
+      if (receivingCardName === undefined) return false;
+      const name = receivingCardName;
+      receivingCardName = undefined;
+      log(`[chat:${space}] [out] receiving card ${name}: ${state}`);
+      await updateCardFn(name, buildReceivingCard(t, turn, state), clientDeps);
+      return true;
+    }
     enqueue(async () => {
       log(`[chat:${space}] [out] receiving card`);
-      const sent = await sendCardFn(space, buildReceivingCard(t), clientDeps);
+      const sent = await sendCardFn(space, buildReceivingCard(t, turn), clientDeps);
       sentMessageNames.add(sent.name);
       receivingCardName = sent.name;
     });
@@ -566,7 +745,7 @@ export function createGoogleChatProvider(deps: GoogleChatProviderDeps): GoogleCh
           return;
         }
         enqueue(async () => {
-          const card = buildToolCallCard(label, detail ?? "", "loading", t);
+          const card = buildToolCallCard(label, detail ?? "", "loading", t, turn);
           log(`[chat:${space}] [out] tool card: ${label}`);
           const sent = await sendCardFn(space, card, clientDeps);
           sentMessageNames.add(sent.name);
@@ -580,7 +759,7 @@ export function createGoogleChatProvider(deps: GoogleChatProviderDeps): GoogleCh
             log(`[chat:${space}] onToolFinish for unknown toolCallId ${toolCallId}`);
             return;
           }
-          const card = buildToolCallCard(entry.label, entry.detail, outcome, t);
+          const card = buildToolCallCard(entry.label, entry.detail, outcome, t, turn);
           log(`[chat:${space}] [out] patching ${entry.name} to "${outcome}"`);
           const patched = await updateCardFn(entry.name, card, clientDeps);
           log(`[chat:${space}] [out] patched ${patched.name}`);
@@ -597,7 +776,7 @@ export function createGoogleChatProvider(deps: GoogleChatProviderDeps): GoogleCh
           entry = { name: undefined, buffer: chunk };
           reasoningCards.set(id, entry);
           enqueue(async () => {
-            const card = buildToolCallCard(t("google-chat.thinking"), "", "loading", t);
+            const card = buildToolCallCard(t("google-chat.thinking"), "", "loading", t, turn);
             if (receivingCardName !== undefined) {
               // Replace the "Status" placeholder in place instead of
               // sending a second message.
@@ -625,8 +804,9 @@ export function createGoogleChatProvider(deps: GoogleChatProviderDeps): GoogleCh
         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(t("google-chat.thinking"), tailTruncate(entry.buffer, REASONING_TAIL_CHARS), status, t);
+          const status = !failed ? "success" : signal.aborted ? "stopped" : "failed";
+          if (status === "stopped") stopShown = true;
+          const card = buildToolCallCard(t("google-chat.thinking"), tailTruncate(entry.buffer, REASONING_TAIL_CHARS), status, t, turn);
           log(`[chat:${space}] [out] reasoning patch (${id}): status=${status} bufferLen=${entry.buffer.length}`);
           await updateCardFn(entry.name, card, clientDeps);
           reasoningCards.delete(id);
@@ -663,6 +843,10 @@ export function createGoogleChatProvider(deps: GoogleChatProviderDeps): GoogleCh
         const note = info?.pendingNote;
         const shown = note !== undefined && finalText.startsWith(note) ? finalText.slice(note.length) : finalText;
         const trimmed = shown.trim();
+        answered = true;
+        enqueue(async () => {
+          await closeReceivingCard("answered");
+        });
         if (trimmed.length > 0 && trimmed !== NO_REPLY) {
           for (const message of splitForSendLimit(trimmed)) {
             sendPlain(message);
@@ -671,6 +855,27 @@ export function createGoogleChatProvider(deps: GoogleChatProviderDeps): GoogleCh
         await chain;
       },
       dispose: () => {},
+      settle: async (failed) => {
+        if (answered) return;
+        if (!signal.aborted) {
+          if (!failed) return;
+          enqueue(async () => {
+            await closeReceivingCard("answered");
+          });
+          await chain;
+          return;
+        }
+        enqueue(async () => {
+          if (await closeReceivingCard("stopped")) stopShown = true;
+          if (stopShown) return;
+          stopShown = true;
+          const text = statusLine("stopped", t);
+          log(`[chat:${space}] [out] ${text}`);
+          const sent = await sendMessageFn(space, text, clientDeps);
+          sentMessageNames.add(sent.name);
+        });
+        await chain;
+      },
     };
   }
 
@@ -692,7 +897,7 @@ export function createGoogleChatProvider(deps: GoogleChatProviderDeps): GoogleCh
 
     const reply = await deps.confirm(event.text, sessionKey, principal, event.locale);
     if (reply?.resume) {
-      await resumeTurn(handleTurn, event.space, principal, event.isDirectMessage, event.locale);
+      await resumeTurn(handleTurn, event.space, principal, event.isDirectMessage, event.locale, event.timeZone);
       return;
     }
     if (reply !== null) {
@@ -706,8 +911,9 @@ export function createGoogleChatProvider(deps: GoogleChatProviderDeps): GoogleCh
     // Only the actual model turn needs serializing — the confirmation above
     // never touches SessionHistory, so it's always safe to run right
     // away regardless of whether this session is mid-turn.
-    await runInSession(sessionKey, () =>
-      handleTurn(
+    await runInSession(sessionKey, (signal, turnId) =>
+      runTurn(
+        handleTurn,
         {
           channel: "google-chat",
           multiUser: !event.isDirectMessage,
@@ -716,12 +922,39 @@ export function createGoogleChatProvider(deps: GoogleChatProviderDeps): GoogleCh
           principal,
           logPrefix: `[chat:${event.space}:${event.sender}] `,
           ...(event.locale === undefined ? {} : { languageHint: event.locale }),
+          ...(event.timeZone === undefined ? {} : { timeZoneHint: event.timeZone }),
         },
-        createSink(event.space, { user: event.sender, isDirectMessage: event.isDirectMessage }, t),
+        createSink(event.space, { user: event.sender, isDirectMessage: event.isDirectMessage }, t, signal, turnId),
+        signal,
       ),
     );
   }
 
+  /**
+   * A stop from the person: aborts their running turn in this space and
+   * discards what's queued behind it (`stopSession`), ahead of the queue it
+   * would otherwise wait in. Only their own session: in a shared space,
+   * someone else's stop finds nothing of theirs running. `/stop` with nothing
+   * to stop says so; a click on a card whose turn is over does nothing.
+   */
+  async function processStopEvent(event: ParsedStopEvent): Promise<void> {
+    const sessionKey = deriveSessionKey(event.space, event.sender);
+    if (stopSession(sessionKey, event.turn)) {
+      log(`[chat:${event.space}:${event.sender}] [in] stop (${event.source})`);
+      return;
+    }
+    log(`[chat:${event.space}:${event.sender}] [in] stop (${event.source}), nothing running`);
+    if (event.source !== "command") return;
+    const principal: Principal = {
+      id: event.sender,
+      provider: "google-chat",
+      ...(event.senderEmail === undefined ? {} : { claims: { email: event.senderEmail } }),
+    };
+    const t = await textsFor(principal, event.locale);
+    const sent = await sendMessageFn(event.space, t("google-chat.stop.nothing"), clientDeps);
+    sentMessageNames.add(sent.name);
+  }
+
   /**
    * Acks each message immediately on arrival — before `handleTurn` (or
    * `onCardClick`) ever runs, not after it resolves. Same pattern the
@@ -738,7 +971,7 @@ export function createGoogleChatProvider(deps: GoogleChatProviderDeps): GoogleCh
    */
   async function handleMessage(message: StreamMessage, handleTurn: HandleTurn): Promise<void> {
     message.ack();
-    let parsed: ParsedMessageEvent | ParsedCardClickEvent | null;
+    let parsed: ParsedMessageEvent | ParsedCardClickEvent | ParsedStopEvent | null;
     try {
       parsed = parseChatEvent(JSON.parse(message.data.toString("utf-8")));
     } catch (err) {
@@ -749,8 +982,10 @@ export function createGoogleChatProvider(deps: GoogleChatProviderDeps): GoogleCh
     try {
       if (parsed.kind === "message") {
         await processMessageEvent(parsed, handleTurn);
+      } else if (parsed.kind === "stop") {
+        await processStopEvent(parsed);
       } else {
-        await onCardClick(parsed.parameters, parsed.space, parsed.sender, parsed.senderEmail, parsed.isDirectMessage, parsed.messageName, parsed.locale);
+        await onCardClick(parsed.parameters, parsed.space, parsed.sender, parsed.senderEmail, parsed.isDirectMessage, parsed.messageName, parsed.locale, parsed.timeZone);
       }
     } catch (err) {
       log(`[chat] event handling failed: ${String(err)}`);

package/messages.ts

@@ -17,10 +17,14 @@ export const GOOGLE_CHAT_MESSAGES: Messages = {
   "google-chat.status.success": "Done.",
   "google-chat.status.failed": "Failed.",
   "google-chat.status.pending": "Waiting for confirmation.",
+  "google-chat.status.stopped": "Stopped.",
   "google-chat.thinking": "Thinking…",
   // The card sent as soon as a message arrives (`buildReceivingCard`).
   "google-chat.receiving.title": "Status",
   "google-chat.receiving.text": "Message received…",
+  // The Stop button on a card in progress (`stopSection`), and `/stop` with nothing running.
+  "google-chat.stop.button": "Stop",
+  "google-chat.stop.nothing": "Nothing to stop.",
 };
 
 /** These texts in English, for a provider built without the core's (`ChannelI18n`); any other key comes back as itself. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mercury-fw/channel-google-chat",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -34,7 +34,7 @@
     "@mercury-fw/channel-types": ">=0.54.0 <1.0.0"
   },
   "devDependencies": {
-    "@mercury-fw/channel-types": "0.54.0",
+    "@mercury-fw/channel-types": "0.58.0",
     "@mercury-fw/typescript-config": "*",
     "@types/bun": "^1.4.2",
     "typescript": "^6.0.3"