@mercury-fw/channel-google-chat 0.8.2 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # @mercury-fw/channel-google-chat
 
+## 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
+
+- e00ff73: The channels' texts come out in the person's language too, and the language their client asks for counts. Channel contract version 6:
+
+  - The person's language is the one they saved, else the one their client asks for, else the app's default. The HTTP channel passes on the request's `Accept-Language` header (what browsers send), Google Chat the language of the person's Chat client when its event carries one (`InboundTurn.languageHint`). Someone the agent refuses gets it too.
+  - A channel declares its own texts in English in `messages`, under its name (`google-chat.`, `http.`), checked like a plugin's; it gets them through `ctx.i18n.forRequest(principal, hint)`.
+  - The replies to a confirmation are the core's, in the person's language: `ctx.confirm` returns `{ text, resume? }` and `ctx.resolveConfirmation` the outcome with its `text`. A confirmed action reads "Confirmed and done." instead of its raw result as JSON. `confirmReply`, `RESUME_AFTER_CONFIRM` and `PENDING_CONFIRMATION_NOTE` are gone from the contract, and `tryConfirm` from `@mercury-fw/confirm-engine` (`resolveConfirmation` reports the outcome; the core words it).
+  - The stand-in for an answer the model didn't write because the turn staged an action (`core.pending.note`, "Action pending, waiting for confirmation.") is no longer streamed as text: `finalize(text, { pendingNote })` says the text begins with it, and channels drop it through that, never by comparing text.
+  - A plain staging's single choice has an empty label: each channel words its own button ("Confirm" on Google Chat, in the person's language). `loginLinkText(login, t)` takes the person's texts.
+  - HTTP: `Accept-Language` on `/turn`, `/confirm` and `/login/callback`; `Content-Language` on the responses of `/turn` and `/confirm`; the `final` event carries `pendingNote`; the login page reads in the browser's language.
+  - Google Chat: the cards' titles, status lines and confirm button are `google-chat.*` texts; the client's `common.userLocale` is the hint when the event carries it.
+  - The terminal's replies to a confirmation read in the terminal person's language, like its other lines.
+
+  The texts that were in Italian (the cards, the replies to a confirmation, the pending note) are now English by default. An app that wants them in Italian adds their keys to `locales/it.json` (`core.pending.note`, `core.confirm.*`, `core.login.link*`, `google-chat.*`, `http.*`; the log lists the missing ones at startup). A UI on the HTTP channel can hide the pending note through `final`'s `pendingNote`, and words the button of a choice with an empty label itself. A channel written for contract 5 isn't loaded by this core, and the log says why: rebuild it against `CHANNEL_API_VERSION` 6.
+
+### Patch Changes
+
+- 6bb8291: Needs the framework at 0.54.0 or later, the version that brings the contract it's written for (plugin contract 5, channel contract 6): the peer range on `@mercury-fw/plugin-types` and `@mercury-fw/cli-engine` (the plugins) or `@mercury-fw/channel-types` (the channels) starts there.
+
 ## 0.8.2
 
 ### Patch Changes

package/README.md

@@ -26,9 +26,13 @@ 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. The client's time zone reaches the model from the framework at 0.56 on; an older core ignores it.
+
 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.
 
-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 `Conferma` for a plain staging (deleting a Jira issue, say), more when there's a choice to make (the web search plugin offers "Solo questa volta" and "Sempre per \<host\>" 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.
+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.
 
 ## Table of contents
 

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

@@ -21,7 +21,7 @@
  */
 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 ConfirmOutcome, type Provider, type Principal } from "@mercury-fw/channel-types";
+import { type ChannelI18n, type ChannelRuntimeContext, 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
@@ -51,6 +51,10 @@ export type ParsedMessageEvent = {
      * live against a real DM event this session.
      */
     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";
@@ -62,28 +66,39 @@ export type ParsedCardClickEvent = {
     parameters: Record<string, string>;
     /** As on a message (see `ParsedMessageEvent.isDirectMessage`): for the turn a click resumes. */
     isDirectMessage: boolean;
+    /** As on a message (see `ParsedMessageEvent.locale`). */
+    locale?: string;
+    /** As on a message (see `ParsedMessageEvent.timeZone`). */
+    timeZone?: 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, senderEmail?: string, isDirectMessage?: boolean, messageName?: string) => Promise<void>;
+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, 
+/** The clicking person's client time zone (`ParsedCardClickEvent.timeZone`). */
+timeZone?: 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. With
+     * the channel loader (`ChannelRuntimeContext.confirm`). Returns what to tell
+     * the person, in their language, or `null` when the input wasn't
+     * token-shaped. With
      * `resolveConfirmation` below, the channel's whole contact with confirmation:
      * the store, vault and note-writer stay in the core.
      */
-    confirm: (token: string, sessionKey: string, principal: Principal) => Promise<string | null>;
+    confirm: ChannelRuntimeContext["confirm"];
     /**
      * The structured sibling of `confirm` (`ChannelRuntimeContext.resolveConfirmation`).
      * When it's there, a click resolves through it, and an accepted choice
      * turns its card into the choice taken; without it, a click goes through
      * `confirm` and the card stays as it was.
      */
-    resolveConfirmation?: (token: string, sessionKey: string, principal: Principal) => Promise<ConfirmOutcome>;
+    resolveConfirmation?: ChannelRuntimeContext["resolveConfirmation"];
+    /** The texts the cards show, in each person's language (`ChannelRuntimeContext.i18n`); English when absent. */
+    i18n?: ChannelI18n;
     /**
      * Handles a `CARD_CLICKED` event's action parameters. Defaults to resolving
      * the confirm button's token through `deps.confirm` (the same path a bare

package/dist/messages.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The Google Chat channel's texts a person sees, in English: the base every
+ * instance's language files translate (`ChannelPlugin.messages`). The cards'
+ * titles and status lines, the confirm button of a plain staging; the replies
+ * and the tool labels are the core's and the plugins'.
+ */
+import type { Messages, Translate } from "@mercury-fw/channel-types";
+export declare const GOOGLE_CHAT_MESSAGES: Messages;
+/** These texts in English, for a provider built without the core's (`ChannelI18n`); any other key comes back as itself. */
+export declare const englishChat: Translate;

package/google-chat-provider.ts

@@ -35,11 +35,11 @@ import {
   detectLoginRequired,
   detectPendingConfirmation,
   loginLinkText,
-  PENDING_CONFIRMATION_NOTE,
-  RESUME_AFTER_CONFIRM,
-  confirmReply,
-  type ConfirmOutcome,
   NO_REPLY,
+  type ChannelI18n,
+  type ChannelRuntimeContext,
+  type ConfirmReply,
+  type Translate,
   type LoginRequest,
   type PendingConfirmation,
   type ToolOutcome,
@@ -48,20 +48,22 @@ import {
   type TurnSink,
   type Principal,
 } from "@mercury-fw/channel-types";
+import { englishChat } from "./messages.ts";
 
 /**
  * Builds the confirmation card sent when a step stages an irreversible
  * 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 single "Confirm" for a plain staging, in the person's language: `t`).
+ * Each button's parameters carry the token, so a click routes straight into
+ * the same confirmation 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 —
  * plus its label and the summary, so the click can turn the card into
  * `buildChosenCard` without the channel keeping any state.
  */
-function buildConfirmCard(pending: PendingConfirmation): ChatCard {
+function buildConfirmCard(pending: PendingConfirmation, t: Translate): ChatCard {
   return {
-    header: { title: "Conferma richiesta" },
+    header: { title: t("google-chat.confirm.title") },
     sections: [
       {
         widgets: [
@@ -69,13 +71,13 @@ function buildConfirmCard(pending: PendingConfirmation): ChatCard {
           {
             buttonList: {
               buttons: pending.choices.map((choice) => ({
-                text: choice.label,
+                text: choice.label || t("google-chat.confirm.button"),
                 onClick: {
                   action: {
                     function: "confirm",
                     parameters: [
                       { key: "token", value: choice.token },
-                      { key: "label", value: choice.label },
+                      { key: "label", value: choice.label || t("google-chat.confirm.button") },
                       { key: "summary", value: pending.summary },
                     ],
                   },
@@ -90,14 +92,14 @@ function buildConfirmCard(pending: PendingConfirmation): ChatCard {
 }
 
 /** The confirmation card once a choice is taken: the same request, the choice instead of the buttons. */
-function buildChosenCard(summary: string, label: string | undefined): ChatCard {
+function buildChosenCard(summary: string, label: string | undefined, t: Translate): ChatCard {
   return {
-    header: { title: "Conferma richiesta" },
+    header: { title: t("google-chat.confirm.title") },
     sections: [
       {
         widgets: [
           { textParagraph: { text: `\`${summary}\`` } },
-          { textParagraph: { text: label === undefined ? "Scelta registrata." : `Scelto: ${label}` } },
+          { textParagraph: { text: label === undefined ? t("google-chat.confirm.taken") : t("google-chat.confirm.chosen", { label }) } },
         ],
       },
     ],
@@ -105,18 +107,16 @@ function buildChosenCard(summary: string, label: string | undefined): 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 {
+function buildLoginCard(login: LoginRequest, t: Translate): ChatCard {
   return {
-    sections: [{ widgets: [{ buttonList: { buttons: [{ text: loginLinkText(login), onClick: { openLink: { url: login.url } } }] } }] }],
+    sections: [{ widgets: [{ buttonList: { buttons: [{ text: loginLinkText(login, t), onClick: { openLink: { url: login.url } } }] } }] }],
   };
 }
 
-const TOOL_STATUS_LINES: Record<"loading" | ToolOutcome, string> = {
-  loading: "In corso…",
-  success: "Fatto.",
-  failed: "Non riuscito.",
-  pending: "In attesa di conferma.",
-};
+/** A card's status line, in the person's language. */
+function statusLine(status: "loading" | ToolOutcome, t: Translate): string {
+  return t(`google-chat.status.${status}`);
+}
 
 /**
  * A tool-call/reasoning status card: `label` is a section `header`
@@ -129,10 +129,10 @@ const TOOL_STATUS_LINES: Record<"loading" | ToolOutcome, string> = {
  * 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).
+ * collapsed body: a title stuck reading "Reading Jira…" (present
+ * progressive) forever, even once the card's own body says "Done.", 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
@@ -146,14 +146,14 @@ const TOOL_STATUS_LINES: Record<"loading" | ToolOutcome, 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): ChatCard {
+function buildToolCallCard(label: string, detail: string, status: "loading" | ToolOutcome, t: Translate): ChatCard {
   return {
     sections: [
       {
-        header: status === "loading" ? label : `${label} ${TOOL_STATUS_LINES[status]}`,
+        header: status === "loading" ? label : `${label} ${statusLine(status, t)}`,
         collapsible: true,
         uncollapsibleWidgetsCount: 0,
-        widgets: [{ textParagraph: { text: detail } }, { textParagraph: { text: TOOL_STATUS_LINES[status] } }],
+        widgets: [{ textParagraph: { text: detail } }, { textParagraph: { text: statusLine(status, t) } }],
       },
     ],
   };
@@ -171,7 +171,7 @@ const REASONING_TAIL_CHARS = 4000;
  * 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
+ * Header is the generic "Status" (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.
  *
@@ -180,12 +180,12 @@ const REASONING_TAIL_CHARS = 4000;
  * (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…"
+ * `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.
  */
-function buildReceivingCard(): ChatCard {
-  return { sections: [{ header: "Stato", widgets: [{ textParagraph: { text: "Messaggio in ricezione…" } }] }] };
+function buildReceivingCard(t: Translate): ChatCard {
+  return { sections: [{ header: t("google-chat.receiving.title"), widgets: [{ textParagraph: { text: t("google-chat.receiving.text") } }] }] };
 }
 
 /**
@@ -226,6 +226,8 @@ type RawChatEvent = {
   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, 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 = {
@@ -245,6 +247,10 @@ export type ParsedMessageEvent = {
    * live against a real DM event this session.
    */
   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 = {
@@ -257,8 +263,24 @@ export type ParsedCardClickEvent = {
   parameters: Record<string, string>;
   /** As on a message (see `ParsedMessageEvent.isDirectMessage`): for the turn a click resumes. */
   isDirectMessage: boolean;
+  /** As on a message (see `ParsedMessageEvent.locale`). */
+  locale?: string;
+  /** As on a message (see `ParsedMessageEvent.timeZone`). */
+  timeZone?: string;
 };
 
+/** 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;
@@ -267,6 +289,8 @@ function emailOf(sender: RawChatSender | undefined): string | 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 {
   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;
@@ -281,6 +305,8 @@ export function parseChatEvent(raw: unknown): ParsedMessageEvent | ParsedCardCli
       senderDisplayName: m.sender.displayName,
       senderEmail: emailOf(m.sender),
       isDirectMessage: m.space.type === "DM",
+      ...(locale === undefined ? {} : { locale }),
+      ...(timeZone === undefined ? {} : { timeZone }),
     };
   }
   if (event?.type === "CARD_CLICKED") {
@@ -300,6 +326,8 @@ export function parseChatEvent(raw: unknown): ParsedMessageEvent | ParsedCardCli
       senderEmail: emailOf(event.user),
       parameters,
       isDirectMessage: event.space.type === "DM",
+      ...(locale === undefined ? {} : { locale }),
+      ...(timeZone === undefined ? {} : { timeZone }),
     };
   }
   return null;
@@ -312,6 +340,10 @@ export type CardClickHandler = (
   senderEmail?: string,
   isDirectMessage?: boolean,
   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 = {
@@ -319,19 +351,22 @@ export type GoogleChatProviderDeps = {
   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. With
+   * the channel loader (`ChannelRuntimeContext.confirm`). Returns what to tell
+   * the person, in their language, or `null` when the input wasn't
+   * token-shaped. With
    * `resolveConfirmation` below, the channel's whole contact with confirmation:
    * the store, vault and note-writer stay in the core.
    */
-  confirm: (token: string, sessionKey: string, principal: Principal) => Promise<string | null>;
+  confirm: ChannelRuntimeContext["confirm"];
   /**
    * The structured sibling of `confirm` (`ChannelRuntimeContext.resolveConfirmation`).
    * When it's there, a click resolves through it, and an accepted choice
    * turns its card into the choice taken; without it, a click goes through
    * `confirm` and the card stays as it was.
    */
-  resolveConfirmation?: (token: string, sessionKey: string, principal: Principal) => Promise<ConfirmOutcome>;
+  resolveConfirmation?: ChannelRuntimeContext["resolveConfirmation"];
+  /** The texts the cards show, in each person's language (`ChannelRuntimeContext.i18n`); English when absent. */
+  i18n?: ChannelI18n;
   /**
    * Handles a `CARD_CLICKED` event's action parameters. Defaults to resolving
    * the confirm button's token through `deps.confirm` (the same path a bare
@@ -366,6 +401,9 @@ export function createGoogleChatProvider(deps: GoogleChatProviderDeps): GoogleCh
   const subscriptionFn = deps.subscriptionFn ?? openSubscription;
   const clientDeps = { tokenSource };
   const sentMessageNames = new Set<string>();
+  /** The texts for `principal`, on the client language `hint`. */
+  const textsFor = async (principal: Principal, hint: string | undefined): Promise<Translate> =>
+    deps.i18n ? (await deps.i18n.forRequest(principal, hint)).t : englishChat;
   // 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
@@ -399,9 +437,17 @@ export function createGoogleChatProvider(deps: GoogleChatProviderDeps): GoogleCh
     }
   }
 
-  /** 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> {
+  /** Resumes the session's turn after a confirmation whose result went back to the model (`ConfirmReply.resume`). */
+  async function resumeTurn(
+    handleTurn: HandleTurn,
+    space: string,
+    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(
         {
@@ -412,8 +458,10 @@ export function createGoogleChatProvider(deps: GoogleChatProviderDeps): GoogleCh
           principal,
           logPrefix: `[chat:${space}:${principal.id}] `,
           resumeAfterConfirm: true,
+          ...(locale === undefined ? {} : { languageHint: locale }),
+          ...(timeZone === undefined ? {} : { timeZoneHint: timeZone }),
         },
-        createSink(space, { user: principal.id, isDirectMessage }),
+        createSink(space, { user: principal.id, isDirectMessage }, t),
       ),
     );
   }
@@ -429,7 +477,7 @@ export function createGoogleChatProvider(deps: GoogleChatProviderDeps): GoogleCh
    */
   const onCardClick: CardClickHandler =
     deps.onCardClick ??
-    (async (params, space, sender, senderEmail, isDirectMessage = false, messageName) => {
+    (async (params, space, sender, senderEmail, isDirectMessage = false, messageName, locale, timeZone) => {
       const token = params.token;
       if (!token) {
         log(`[chat] card click with no token parameter`);
@@ -441,13 +489,14 @@ export function createGoogleChatProvider(deps: GoogleChatProviderDeps): GoogleCh
         ...(senderEmail === undefined ? {} : { claims: { email: senderEmail } }),
       };
       const sessionKey = deriveSessionKey(space, sender);
-      let reply: string | null;
+      let reply: ConfirmReply | null;
       if (deps.resolveConfirmation) {
-        const outcome = await deps.resolveConfirmation(token, sessionKey, principal);
+        const outcome = await deps.resolveConfirmation(token, sessionKey, principal, locale);
         const accepted = outcome.status === "ok" || outcome.status === "failed" || outcome.status === "resume";
         if (accepted && messageName !== undefined && params.summary !== undefined) {
           try {
-            await updateCardFn(messageName, buildChosenCard(params.summary, params.label), clientDeps);
+            const t = await textsFor(principal, locale);
+            await updateCardFn(messageName, buildChosenCard(params.summary, params.label, t), clientDeps);
             log(`[chat:${space}] [out] confirm card ${messageName} patched to the choice taken`);
           } catch (err) {
             log(`[chat:${space}] confirm card patch failed: ${String(err)}`);
@@ -456,17 +505,19 @@ export function createGoogleChatProvider(deps: GoogleChatProviderDeps): GoogleCh
         // On not-found nothing was taken, so `confirm` gives the reply as it
         // always did: the core's own message for someone it won't talk to,
         // which the outcome doesn't carry.
-        reply = outcome.status === "not-found" ? await deps.confirm(token, sessionKey, principal) : confirmReply(outcome);
+        if (outcome.status === "not-found") reply = await deps.confirm(token, sessionKey, principal, locale);
+        else if (outcome.text === null) reply = null;
+        else reply = outcome.status === "resume" ? { text: outcome.text, resume: true } : { text: outcome.text };
       } else {
-        reply = await deps.confirm(token, sessionKey, principal);
+        reply = await deps.confirm(token, sessionKey, principal, locale);
       }
-      if (reply === RESUME_AFTER_CONFIRM && activeHandleTurn) {
-        await resumeTurn(activeHandleTurn, space, principal, isDirectMessage);
+      if (reply?.resume && activeHandleTurn) {
+        await resumeTurn(activeHandleTurn, space, principal, isDirectMessage, locale, timeZone);
         return;
       }
       if (reply !== null) {
-        log(`[chat:${space}] [out] ${reply}`);
-        const sent = await sendMessageFn(space, reply, clientDeps);
+        log(`[chat:${space}] [out] ${reply.text}`);
+        const sent = await sendMessageFn(space, reply.text, clientDeps);
         sentMessageNames.add(sent.name);
       }
     });
@@ -476,8 +527,9 @@ 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.
    */
-  function createSink(space: string, viewer: { user: string; isDirectMessage: boolean }): TurnSink {
+  function createSink(space: string, viewer: { user: string; isDirectMessage: boolean }, t: Translate): TurnSink {
     let chain: Promise<void> = Promise.resolve();
 
     function enqueue(fn: () => Promise<void>): void {
@@ -519,7 +571,7 @@ export function createGoogleChatProvider(deps: GoogleChatProviderDeps): GoogleCh
     const shownLogins = new Set<string>();
     enqueue(async () => {
       log(`[chat:${space}] [out] receiving card`);
-      const sent = await sendCardFn(space, buildReceivingCard(), clientDeps);
+      const sent = await sendCardFn(space, buildReceivingCard(t), clientDeps);
       sentMessageNames.add(sent.name);
       receivingCardName = sent.name;
     });
@@ -531,7 +583,7 @@ export function createGoogleChatProvider(deps: GoogleChatProviderDeps): GoogleCh
           return;
         }
         enqueue(async () => {
-          const card = buildToolCallCard(label, detail ?? "", "loading");
+          const card = buildToolCallCard(label, detail ?? "", "loading", t);
           log(`[chat:${space}] [out] tool card: ${label}`);
           const sent = await sendCardFn(space, card, clientDeps);
           sentMessageNames.add(sent.name);
@@ -545,7 +597,7 @@ export function createGoogleChatProvider(deps: GoogleChatProviderDeps): GoogleCh
             log(`[chat:${space}] onToolFinish for unknown toolCallId ${toolCallId}`);
             return;
           }
-          const card = buildToolCallCard(entry.label, entry.detail, outcome);
+          const card = buildToolCallCard(entry.label, entry.detail, outcome, t);
           log(`[chat:${space}] [out] patching ${entry.name} to "${outcome}"`);
           const patched = await updateCardFn(entry.name, card, clientDeps);
           log(`[chat:${space}] [out] patched ${patched.name}`);
@@ -562,9 +614,9 @@ export function createGoogleChatProvider(deps: GoogleChatProviderDeps): GoogleCh
           entry = { name: undefined, buffer: chunk };
           reasoningCards.set(id, entry);
           enqueue(async () => {
-            const card = buildToolCallCard("Sto pensando…", "", "loading");
+            const card = buildToolCallCard(t("google-chat.thinking"), "", "loading", t);
             if (receivingCardName !== undefined) {
-              // Replace the "Stato" placeholder in place instead of
+              // Replace the "Status" 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);
@@ -591,7 +643,7 @@ export function createGoogleChatProvider(deps: GoogleChatProviderDeps): GoogleCh
         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);
+          const card = buildToolCallCard(t("google-chat.thinking"), tailTruncate(entry.buffer, REASONING_TAIL_CHARS), status, t);
           log(`[chat:${space}] [out] reasoning patch (${id}): status=${status} bufferLen=${entry.buffer.length}`);
           await updateCardFn(entry.name, card, clientDeps);
           reasoningCards.delete(id);
@@ -607,7 +659,7 @@ export function createGoogleChatProvider(deps: GoogleChatProviderDeps): GoogleCh
         if (pending) {
           enqueue(async () => {
             log(`[chat:${space}] [out] confirm card: ${pending.summary}`);
-            const sent = await sendCardFn(space, buildConfirmCard(pending), clientDeps);
+            const sent = await sendCardFn(space, buildConfirmCard(pending, t), clientDeps);
             sentMessageNames.add(sent.name);
           });
         }
@@ -617,14 +669,18 @@ export function createGoogleChatProvider(deps: GoogleChatProviderDeps): GoogleCh
           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);
+            const sent = await sendCardFn(space, buildLoginCard(login, t), clientDeps, options);
             sentMessageNames.add(sent.name);
           });
         }
       },
-      finalize: async (finalText: string) => {
-        const trimmed = finalText.trim();
-        if (trimmed.length > 0 && trimmed !== NO_REPLY && trimmed !== PENDING_CONFIRMATION_NOTE) {
+      finalize: async (finalText, info) => {
+        // The core's stand-in for an answer the model didn't write: the
+        // confirmation card already says it; only a list after it is sent.
+        const note = info?.pendingNote;
+        const shown = note !== undefined && finalText.startsWith(note) ? finalText.slice(note.length) : finalText;
+        const trimmed = shown.trim();
+        if (trimmed.length > 0 && trimmed !== NO_REPLY) {
           for (const message of splitForSendLimit(trimmed)) {
             sendPlain(message);
           }
@@ -651,19 +707,20 @@ export function createGoogleChatProvider(deps: GoogleChatProviderDeps): GoogleCh
       ...(event.senderEmail === undefined ? {} : { claims: { email: event.senderEmail } }),
     };
 
-    const confirmReply = await deps.confirm(event.text, sessionKey, principal);
-    if (confirmReply === RESUME_AFTER_CONFIRM) {
-      await resumeTurn(handleTurn, event.space, principal, event.isDirectMessage);
+    const reply = await deps.confirm(event.text, sessionKey, principal, event.locale);
+    if (reply?.resume) {
+      await resumeTurn(handleTurn, event.space, principal, event.isDirectMessage, event.locale, event.timeZone);
       return;
     }
-    if (confirmReply !== null) {
-      log(`[chat:${event.space}] [out] ${confirmReply}`);
-      const sent = await sendMessageFn(event.space, confirmReply, clientDeps);
+    if (reply !== null) {
+      log(`[chat:${event.space}] [out] ${reply.text}`);
+      const sent = await sendMessageFn(event.space, reply.text, clientDeps);
       sentMessageNames.add(sent.name);
       return;
     }
 
-    // Only the actual model turn needs serializing — tryConfirm above
+    const t = await textsFor(principal, event.locale);
+    // 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, () =>
@@ -675,8 +732,10 @@ export function createGoogleChatProvider(deps: GoogleChatProviderDeps): GoogleCh
           sessionKey,
           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 }),
+        createSink(event.space, { user: event.sender, isDirectMessage: event.isDirectMessage }, t),
       ),
     );
   }
@@ -709,7 +768,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, parsed.isDirectMessage, parsed.messageName);
+        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/index.ts

@@ -9,6 +9,7 @@
  */
 import type { ChannelPlugin, ChannelRuntimeContext } from "@mercury-fw/channel-types";
 import { createGoogleChatProvider } from "./google-chat-provider.ts";
+import { GOOGLE_CHAT_MESSAGES } from "./messages.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 {
@@ -22,8 +23,9 @@ function require(env: ChannelRuntimeContext["env"], name: string): string {
 export const googleChatChannel: ChannelPlugin = {
   // The contract this channel is written for, as a literal: importing
   // CHANNEL_API_VERSION would report whichever contract is installed.
-  apiVersion: 5,
+  apiVersion: 6,
   name: "google-chat",
+  messages: GOOGLE_CHAT_MESSAGES,
   build: (ctx) => {
     // No subscription configured ⇒ this instance simply doesn't run Google Chat.
     const subscription = ctx.env.GOOGLE_CHAT_PUBSUB_SUBSCRIPTION;
@@ -40,6 +42,7 @@ export const googleChatChannel: ChannelPlugin = {
       subscription,
       confirm: ctx.confirm,
       ...(ctx.resolveConfirmation === undefined ? {} : { resolveConfirmation: ctx.resolveConfirmation }),
+      i18n: ctx.i18n,
       log: ctx.log,
     });
   },

package/messages.ts

@@ -0,0 +1,30 @@
+/**
+ * The Google Chat channel's texts a person sees, in English: the base every
+ * instance's language files translate (`ChannelPlugin.messages`). The cards'
+ * titles and status lines, the confirm button of a plain staging; the replies
+ * and the tool labels are the core's and the plugins'.
+ */
+import type { Messages, Translate } from "@mercury-fw/channel-types";
+
+export const GOOGLE_CHAT_MESSAGES: Messages = {
+  // The confirmation card (`buildConfirmCard`, `buildChosenCard`).
+  "google-chat.confirm.title": "Confirmation needed",
+  "google-chat.confirm.button": "Confirm",
+  "google-chat.confirm.chosen": "Chosen: {label}",
+  "google-chat.confirm.taken": "Choice recorded.",
+  // A tool call's or a reasoning burst's card (`buildToolCallCard`).
+  "google-chat.status.loading": "In progress…",
+  "google-chat.status.success": "Done.",
+  "google-chat.status.failed": "Failed.",
+  "google-chat.status.pending": "Waiting for confirmation.",
+  "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…",
+};
+
+/** These texts in English, for a provider built without the core's (`ChannelI18n`); any other key comes back as itself. */
+export const englishChat: Translate = (key, params) =>
+  (GOOGLE_CHAT_MESSAGES[key] ?? key).replace(/\{(\w+)\}/g, (whole, name: string) =>
+    params !== undefined && Object.hasOwn(params, name) ? String(params[name]) : whole,
+  );

package/package.json

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