@mercury-fw/channel-http 0.11.0 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @mercury-fw/channel-http
 
+## 0.12.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.11.0
 
 ### Minor Changes

package/README.md

@@ -2,7 +2,7 @@
 
 Gives a [Mercury](https://github.com/lucabro81/mercury-fw) agent an HTTP surface to build a custom UI on: one conversational turn per request, streamed back as Server-Sent Events, plus confirmation and read-only routes over what the agent holds (conversations, the wiki, memory, its plugins).
 
-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. `X-Time-Zone` and `PATCH /me` need the framework at 0.56 or later: an older core ignores the header and offers no `PATCH /me`.
 
 ```bash
 bun add @mercury-fw/channel-http
@@ -56,6 +56,8 @@ Runs one conversational turn; the reply streams back as Server-Sent Events.
 
 **Languages.** Every text a person reads that isn't the model's (a refusal, a tool's status line, a choice's label, a confirmation's reply, the login page) is in their language: the one they asked the assistant for, else the one the request's `Accept-Language` header asks for (what browsers send on their own), else the app's default. The responses of `POST /turn` and `POST /confirm`, a refusal and the login page say which with `Content-Language` (as it stood when the response started: a language picked during a turn counts from the next one).
 
+**Time zone.** The model reads each message with the time the person wrote it, in their time zone: the one they saved, else the one the request's `X-Time-Zone` header names (an IANA name such as `Europe/Rome`, what `Intl.DateTimeFormat().resolvedOptions().timeZone` gives in a browser), else the app's. A UI saves the person's with `PATCH /me`.
+
 Reasoning and answer text arrive as **incremental deltas** — never one finished block — so a UI renders them live; treat the `final` event as the authoritative text. **To cancel** a turn (e.g. a generation that's diverging), close the connection: Mercury aborts the in-flight generation.
 
 **SSE events** — each is `event: <name>` followed by `data: <json>`:
@@ -89,6 +91,10 @@ Whoever opens the link and accepts decides which account gets linked: a link bel
 
 A code for linking another of the caller's accounts to them, for the UI to show: `{ ok: true, code, expiresAt }`, or `400` with the reason when there's none. The person sends the code from the other account, on any channel, twice: the first time Mercury says whom the account would be linked to, the second time it links it, and from then on both accounts are one person (one private area, the same roles). The code lasts ten minutes, works once, and only the caller sees it; the model never does. It belongs to the first account that sends it, so it should be sent in a one-to-one conversation, never in a shared space where someone else could send it first. Over HTTP only an account the instance already admits can send it (anyone else is refused before the turn), so an account a closed instance doesn't know links from a chat.
 
+## `PATCH /me`
+
+Saves the caller's time zone, for a UI's settings: body `{ timeZone }`, an IANA name such as `Europe/Rome`; returns `{ ok: true, timeZone }` as saved (`europe/rome` is saved as `Europe/Rome`), or `400` with the reason for what isn't a zone's name (a fixed offset such as `+02:00` isn't one) and for a body without it. From then on the caller's turns are stamped with the time there, whatever `X-Time-Zone` says. Not there on a core without settings.
+
 ## `POST /confirm`
 
 Explicit alternative to re-sending a token as `/turn` `text`. Body `{ token, conversationId }`; returns `{ ok: true, resolved: true, text }` when the token was a pending confirmation (`text`: the core's reply in the caller's language, "Confirmed and done." or the failure, never the action's raw result), `{ ok: true, resolved: false }` otherwise. When the confirmed action hands its result back to the model, it returns `{ ok: true, resolved: true, resume: true }` instead: open `POST /turn { resume: true, conversationId }` to hear the model's answer. `400` if `token` or `conversationId` is missing, or the id has other characters than `/turn` accepts. Never invokes the model.
@@ -103,7 +109,7 @@ All `GET`, all JSON, all reporting state already held in-process. They need an a
 | `GET /conversations?limit=<n>` | `{ conversations: [{ conversationId, lastTimestamp, preview }] }` — your conversations, most-recently-active first |
 | `GET /manifest` | `{ manifest: { coreApiVersion, plugins: [{ name, apiVersion, active, skills, hasBuild, customStatus }], activeClis, skills } }` |
 | `GET /confirmations` | `{ pending: [{ sessionKey, summary, expiresAt }] }` — your pending confirmations; tokens are deliberately never included |
-| `GET /me` | `{ name, language }` — how you asked the assistant to call you and the language you asked it to use, `null` when you never said; `language` is missing on a core that doesn't know languages, and the route isn't there on a core older than this channel |
+| `GET /me` | `{ name, language, timeZone }` — how you asked the assistant to call you, the language you asked it to use and the time zone you saved, `null` when you never said; `language` and `timeZone` are missing on a core that doesn't know them, and the route isn't there on a core older than this channel |
 | `GET /tool-log` | `{ entries: [...] }` — the tool calls of your recent turns |
 | `GET /health` | `{ uptimeSeconds, memory, qdrantReachable, ollamaReachable }` |
 | `GET /wiki/list` | `{ files: [...] }` — `curated/...` and `personal/...` paths |

package/dist/http-provider.d.ts

@@ -11,7 +11,7 @@
  * injected (`confirm`/`resolveConfirmation`), so this package never imports the app.
  */
 import { type AdmitFn, type CompleteLoginFn, type ConfirmFn, type ResolveConfirmationFn } from "./http-server.ts";
-import type { Authenticate, Provider, ChannelHostReads, ChannelI18n, ChannelLinking } from "@mercury-fw/channel-types";
+import type { Authenticate, Provider, ChannelHostReads, ChannelI18n, ChannelLinking, ChannelSettings } from "@mercury-fw/channel-types";
 export type HttpProviderDeps = {
     port: number;
     /** Bare-token interception before the model. */
@@ -34,6 +34,8 @@ export type HttpProviderDeps = {
     };
     /** Linking another account to the caller (`POST /link`). */
     linking?: ChannelLinking;
+    /** The person's own settings (`PATCH /me`). */
+    settings?: ChannelSettings;
     /** The surface's budget for a reopened conversation (`HTTP_SURFACE_RESUME_MAX_CHARS`). */
     resumeMaxChars?: number;
     /** What the pages people read call the assistant. */

package/dist/http-server.d.ts

@@ -22,7 +22,7 @@
  * Confirm resolution is injected too (`confirm`/`resolveConfirmation`), so this
  * package never imports the app.
  */
-import { type HandleTurn, type Authenticate, type ChannelHostReads, type ChannelI18n, type ChannelRuntimeContext, type LoginOutcome, type Principal, type Admission, type ChannelLinking } from "@mercury-fw/channel-types";
+import { type HandleTurn, type Authenticate, type ChannelHostReads, type ChannelI18n, type ChannelRuntimeContext, type LoginOutcome, type Principal, type Admission, type ChannelLinking, type ChannelSettings } from "@mercury-fw/channel-types";
 /** Resolves a bare confirmation token to what to tell the person, or `null` if the input isn't a token. Injected by the core (`ctx.confirm`). */
 export type ConfirmFn = ChannelRuntimeContext["confirm"];
 /** The structured sibling of {@link ConfirmFn}, for the `/confirm` `resolved` flag. Injected by the core (`ctx.resolveConfirmation`). */
@@ -124,9 +124,11 @@ export declare function handleLoginCallback(req: Request, deps: {
     assistantName?: string;
     i18n?: ChannelI18n;
 }): Promise<Response>;
-/** A single read route: its `GET` handler plus the shared `OPTIONS` preflight. */
+/** A single read route: its `GET` handler plus the shared `OPTIONS` preflight, and on `/me` the `PATCH` saving a setting. */
 type ReadRoute = {
     GET: (req: Request) => Response | Promise<Response>;
+    /** Only on `/me`, when the core offers the person's settings (`PATCH /me`). */
+    PATCH?: (req: Request) => Promise<Response>;
     OPTIONS: () => Response;
 };
 /**
@@ -138,9 +140,10 @@ type ReadRoute = {
  * their data only; a conversation is named by its conversationId, as on
  * `/turn`, and its session key is built from the caller.
  * `json` JSON-encodes with the CORS headers merged in; `badRequest` does the
- * same for a 400.
+ * same for a 400. With `settings`, `/me` also takes a `PATCH` saving the
+ * caller's time zone (a UI's settings area), asking `authenticate` first too.
  */
-export declare function readRoutes(reads: ChannelHostReads, authenticate: Authenticate, corsOrigin?: string, admit?: AdmitFn): Record<string, ReadRoute>;
+export declare function readRoutes(reads: ChannelHostReads, authenticate: Authenticate, corsOrigin?: string, admit?: AdmitFn, settings?: ChannelSettings): Record<string, ReadRoute>;
 export type HttpServerDeps = TurnRequestDeps & {
     port: number;
     reads?: ChannelHostReads;
@@ -150,6 +153,8 @@ export type HttpServerDeps = TurnRequestDeps & {
     completeLogin?: CompleteLoginFn;
     /** Linking another account to the caller; `/link` is mounted only with it. */
     linking?: ChannelLinking;
+    /** The person's own settings; `PATCH /me` is mounted only with it. */
+    settings?: ChannelSettings;
     /** What the pages people read call the assistant. */
     assistantName?: string;
 };

package/http-provider.ts

@@ -11,7 +11,7 @@
  * injected (`confirm`/`resolveConfirmation`), so this package never imports the app.
  */
 import { startHttpServer, type AdmitFn, type CompleteLoginFn, type ConfirmFn, type ResolveConfirmationFn } from "./http-server.ts";
-import type { Authenticate, Provider, HandleTurn, ChannelHostReads, ChannelI18n, ChannelLinking } from "@mercury-fw/channel-types";
+import type { Authenticate, Provider, HandleTurn, ChannelHostReads, ChannelI18n, ChannelLinking, ChannelSettings } from "@mercury-fw/channel-types";
 
 export type HttpProviderDeps = {
   port: number;
@@ -31,6 +31,8 @@ export type HttpProviderDeps = {
   logins?: { callbackUrl: string; accept: (callbackUrl: string) => void; complete: CompleteLoginFn };
   /** Linking another account to the caller (`POST /link`). */
   linking?: ChannelLinking;
+  /** The person's own settings (`PATCH /me`). */
+  settings?: ChannelSettings;
   /** The surface's budget for a reopened conversation (`HTTP_SURFACE_RESUME_MAX_CHARS`). */
   resumeMaxChars?: number;
   /** What the pages people read call the assistant. */
@@ -54,6 +56,7 @@ export function createHttpProvider(deps: HttpProviderDeps): Provider & { stop():
         corsOrigin: deps.corsOrigin,
         completeLogin: deps.logins?.complete,
         ...(deps.linking === undefined ? {} : { linking: deps.linking }),
+        ...(deps.settings === undefined ? {} : { settings: deps.settings }),
         ...(deps.resumeMaxChars === undefined ? {} : { resumeMaxChars: deps.resumeMaxChars }),
         ...(deps.assistantName === undefined ? {} : { assistantName: deps.assistantName }),
         ...(deps.i18n === undefined ? {} : { i18n: deps.i18n }),

package/http-server.ts

@@ -35,6 +35,7 @@ import {
   type Principal,
   type Admission,
   type ChannelLinking,
+  type ChannelSettings,
 } from "@mercury-fw/channel-types";
 import { englishHttp } from "./messages.ts";
 
@@ -65,6 +66,12 @@ function languageHint(req: Request): string | undefined {
   return value ? value : undefined;
 }
 
+/** The time zone the caller's client says it's in (`X-Time-Zone`, an IANA name), when it says; the core ignores a name that isn't a zone. */
+function timeZoneHint(req: Request): string | undefined {
+  const value = req.headers.get("x-time-zone")?.trim();
+  return value ? value : undefined;
+}
+
 /** `Content-Language` for a response to `principal` asking for `hint`, when the core says which language its texts are in. */
 async function contentLanguage(i18n: ChannelI18n | undefined, principal: Principal | null, hint: string | undefined): Promise<Record<string, string>> {
   return i18n ? { "content-language": (await i18n.forRequest(principal, hint)).locale } : {};
@@ -104,8 +111,8 @@ const SSE_HEADERS = {
 function corsHeaders(origin: string): Record<string, string> {
   return {
     "access-control-allow-origin": origin,
-    "access-control-allow-methods": "GET, POST, OPTIONS",
-    "access-control-allow-headers": "content-type, authorization, accept-language",
+    "access-control-allow-methods": "GET, POST, PATCH, OPTIONS",
+    "access-control-allow-headers": "content-type, authorization, accept-language, x-time-zone",
   };
 }
 
@@ -207,6 +214,7 @@ export async function handleTurnRequest(req: Request, deps: TurnRequestDeps): Pr
   }
   const sessionKey = `${principal.id}:${conversationId}`;
   const hint = languageHint(req);
+  const zone = timeZoneHint(req);
   const language = await contentLanguage(deps.i18n, principal, hint);
 
   // Aborted when the client disconnects (see the stream's `cancel` below) so
@@ -280,6 +288,7 @@ export async function handleTurnRequest(req: Request, deps: TurnRequestDeps): Pr
             ...(opening ? { opening: true as const } : {}),
             ...(resuming ? { resumeAfterConfirm: true as const } : {}),
             ...(hint === undefined ? {} : { languageHint: hint }),
+            ...(zone === undefined ? {} : { timeZoneHint: zone }),
           },
           sink,
         );
@@ -449,9 +458,11 @@ function loginRoutes(
   };
 }
 
-/** A single read route: its `GET` handler plus the shared `OPTIONS` preflight. */
+/** A single read route: its `GET` handler plus the shared `OPTIONS` preflight, and on `/me` the `PATCH` saving a setting. */
 type ReadRoute = {
   GET: (req: Request) => Response | Promise<Response>;
+  /** Only on `/me`, when the core offers the person's settings (`PATCH /me`). */
+  PATCH?: (req: Request) => Promise<Response>;
   OPTIONS: () => Response;
 };
 
@@ -464,13 +475,15 @@ type ReadRoute = {
  * their data only; a conversation is named by its conversationId, as on
  * `/turn`, and its session key is built from the caller.
  * `json` JSON-encodes with the CORS headers merged in; `badRequest` does the
- * same for a 400.
+ * same for a 400. With `settings`, `/me` also takes a `PATCH` saving the
+ * caller's time zone (a UI's settings area), asking `authenticate` first too.
  */
 export function readRoutes(
   reads: ChannelHostReads,
   authenticate: Authenticate,
   corsOrigin = "*",
   admit?: AdmitFn,
+  settings?: ChannelSettings,
 ): Record<string, ReadRoute> {
   const cors = corsHeaders(corsOrigin);
   const json = (payload: object, status = 200): Response =>
@@ -515,12 +528,31 @@ export function readRoutes(
     ...(reads.me === undefined
       ? {}
       : {
-          "/me": route(async (_req, principal) => {
-            // Null when the core no longer admits the caller: still a name, null.
-            const me = (await reads.me!(principal)) as { name: string | null; language?: string | null } | null;
-            // An older core says no language: the reply then has none either.
-            return json({ ok: true, name: me?.name ?? null, ...(me?.language === undefined ? {} : { language: me.language }) });
-          }),
+          "/me": {
+            ...route(async (_req, principal) => {
+              // Null when the core no longer admits the caller: still a name, null.
+              const me = (await reads.me!(principal)) as { name: string | null; language?: string | null; timeZone?: string | null } | null;
+              // An older core says no language or time zone: the reply then has none either.
+              return json({
+                ok: true,
+                name: me?.name ?? null,
+                ...(me?.language === undefined ? {} : { language: me.language }),
+                ...(me?.timeZone === undefined ? {} : { timeZone: me.timeZone }),
+              });
+            }),
+            ...(settings === undefined
+              ? {}
+              : {
+                  PATCH: async (req: Request) => {
+                    const principal = await caller(req, { authenticate, ...(admit === undefined ? {} : { admit }) }, corsOrigin);
+                    if (principal instanceof Response) return principal;
+                    const body = (await req.json().catch(() => null)) as { timeZone?: unknown } | null;
+                    if (typeof body?.timeZone !== "string") return badRequest('the body must be {"timeZone": "<IANA name>"}');
+                    const saved = await settings.setTimeZone(principal, body.timeZone);
+                    return saved.ok ? json({ ok: true, timeZone: saved.value }) : badRequest(saved.error);
+                  },
+                }),
+          },
         }),
     "/health": route(async () => json({ ok: true, ...(await reads.health() as object) })),
     "/wiki/list": route(async (_req, principal) => json({ ok: true, files: await reads.wikiList(principal) })),
@@ -556,6 +588,8 @@ export type HttpServerDeps = TurnRequestDeps & {
   completeLogin?: CompleteLoginFn;
   /** Linking another account to the caller; `/link` is mounted only with it. */
   linking?: ChannelLinking;
+  /** The person's own settings; `PATCH /me` is mounted only with it. */
+  settings?: ChannelSettings;
   /** What the pages people read call the assistant. */
   assistantName?: string;
 };
@@ -589,7 +623,7 @@ export function startHttpServer(deps: HttpServerDeps): ReturnType<typeof Bun.ser
         OPTIONS: () => preflight(origin),
       },
       "/openapi.yaml": { GET: () => openApiResponse(origin), OPTIONS: () => preflight(origin) },
-      ...(deps.reads ? readRoutes(deps.reads, deps.authenticate, origin, deps.admit) : {}),
+      ...(deps.reads ? readRoutes(deps.reads, deps.authenticate, origin, deps.admit, deps.settings) : {}),
       ...(deps.completeLogin ? loginRoutes(deps.completeLogin, deps.assistantName, deps.i18n) : {}),
       ...(deps.linking ? linkRoutes({ ...deps, start: deps.linking.start, corsOrigin: origin }) : {}),
     },

package/index.ts

@@ -48,6 +48,7 @@ export const httpChannel: ChannelPlugin = {
       admit: ctx.admit,
       i18n: ctx.i18n,
       ...(ctx.linking === undefined ? {} : { linking: ctx.linking }),
+      ...(ctx.settings === undefined ? {} : { settings: ctx.settings }),
       ...(resumeMaxChars === undefined ? {} : { resumeMaxChars }),
       ...(ctx.assistantName === undefined ? {} : { assistantName: ctx.assistantName }),
       ...(logins ? { logins: { callbackUrl: `${publicUrl}/login/callback`, accept: logins.accept, complete: logins.complete } } : {}),

package/openapi.yaml

@@ -104,9 +104,12 @@ paths:
         an empty text. Every text the person reads that isn't the model's (a
         refusal, a status line, a confirmation's reply) is in their language:
         the one they saved, else the one `Accept-Language` asks for, else the
-        instance's default.
+        instance's default. The model reads the person's message after when
+        and where they wrote it: in the time zone they saved, else the one
+        `X-Time-Zone` says, else the instance's.
       parameters:
         - $ref: "#/components/parameters/AcceptLanguage"
+        - $ref: "#/components/parameters/TimeZone"
       requestBody:
         required: true
         content:
@@ -344,9 +347,9 @@ paths:
       description: >
         How the caller asked to be called, `null` when they never said: a UI
         asks for an opening turn after a sign-in only then. Also the language
-        they asked the assistant to use, `null` when they never said (missing
-        when the core doesn't know languages). Not there on an older core,
-        which can't say.
+        they asked the assistant to use and the time zone they saved, `null`
+        when they never said (missing on a core that doesn't know them). Not
+        there on an older core, which can't say.
       responses:
         "401":
           $ref: "#/components/responses/Unauthorized"
@@ -355,7 +358,7 @@ paths:
         "503":
           $ref: "#/components/responses/NotAdmitted"
         "200":
-          description: The caller's name and language, or null.
+          description: The caller's name, language and time zone, or null.
           content:
             application/json:
               schema:
@@ -369,6 +372,52 @@ paths:
                   language:
                     type: [string, "null"]
                     description: A language tag such as `it` or `pt-br`, one the instance ships.
+                  timeZone:
+                    type: [string, "null"]
+                    description: The time zone's IANA name, such as `Europe/Rome`.
+    patch:
+      summary: Saves the caller's time zone
+      description: >
+        The time zone the caller is in, by its IANA name, for a UI's settings:
+        from then on their turns are stamped with the time there, whatever
+        `X-Time-Zone` says. Saved as the IANA list writes it (`europe/rome` is
+        `Europe/Rome`). Not there on a core without settings.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [timeZone]
+              properties:
+                timeZone:
+                  type: string
+                  description: An IANA name such as `Europe/Rome`; a fixed offset (`+02:00`) isn't one.
+      responses:
+        "400":
+          description: The body has no `timeZone`, or it isn't a zone's name.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/NotAdmitted"
+        "503":
+          $ref: "#/components/responses/NotAdmitted"
+        "200":
+          description: The time zone as saved.
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [ok, timeZone]
+                properties:
+                  ok:
+                    type: boolean
+                  timeZone:
+                    type: string
   /tool-log:
     get:
       summary: The tool calls made in the caller's recent turns
@@ -564,6 +613,17 @@ components:
         ship is passed over.
       schema:
         type: string
+    TimeZone:
+      name: X-Time-Zone
+      in: header
+      required: false
+      description: >
+        The time zone the client is in, by its IANA name, as a browser gives
+        it (`Intl.DateTimeFormat().resolvedOptions().timeZone`). Used for the
+        turn's time when the person saved no time zone of their own; a name
+        that isn't a zone is passed over.
+      schema:
+        type: string
   headers:
     ContentLanguage:
       description: >

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mercury-fw/channel-http",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -21,8 +21,8 @@
     "@mercury-fw/channel-types": ">=0.54.0 <1.0.0"
   },
   "devDependencies": {
-    "@mercury-fw/channel-types": "0.54.0",
-    "@mercury-fw/plugin-types": "0.54.0",
+    "@mercury-fw/channel-types": "0.56.0",
+    "@mercury-fw/plugin-types": "0.56.0",
     "@mercury-fw/typescript-config": "*",
     "@types/bun": "^1.4.2",
     "typescript": "^6.0.3"