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

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @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

package/README.md

@@ -26,11 +26,11 @@ 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.
 
 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.
 

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,16 @@ export type ParsedCardClickEvent = {
     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, 
 /** 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

@@ -226,8 +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; `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 +249,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,6 +265,8 @@ export type ParsedCardClickEvent = {
   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. */
@@ -271,6 +275,12 @@ function localeOf(event: RawChatEvent | null | undefined): string | undefined {
   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;
@@ -280,6 +290,7 @@ function emailOf(sender: RawChatSender | undefined): string | undefined {
 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;
@@ -295,6 +306,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") {
@@ -315,6 +327,7 @@ export function parseChatEvent(raw: unknown): ParsedMessageEvent | ParsedCardCli
       parameters,
       isDirectMessage: event.space.type === "DM",
       ...(locale === undefined ? {} : { locale }),
+      ...(timeZone === undefined ? {} : { timeZone }),
     };
   }
   return null;
@@ -329,6 +342,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 = {
@@ -429,6 +444,7 @@ 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);
@@ -443,6 +459,7 @@ 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),
       ),
@@ -460,7 +477,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 +512,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) {
@@ -692,7 +709,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) {
@@ -716,6 +733,7 @@ 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),
       ),
@@ -750,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, 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mercury-fw/channel-google-chat",
-  "version": "0.9.0",
+  "version": "0.10.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.56.0",
     "@mercury-fw/typescript-config": "*",
     "@types/bun": "^1.4.2",
     "typescript": "^6.0.3"